FE-1219: Define and enforce a Scenario HIR for server-side Petrinaut optimization

[kube]

Closes FE-1219 (part of FE-1217).

Stacked on #9058 (base cf/fe-1220-...).

What

Server-side Petrinaut scenario materialization now goes through the existing restricted HIR pipeline instead of executing manifest-authored strings via sandboxed new Function. This closes the last unrestricted raw-code execution path on the optimizer's server path. The in-editor sandbox path is unchanged.

petrinaut-core

• Two new HIR surface kinds — scenarioExpression (a single expression over (parameters, scenario) → scalar) and scenarioInit (a statement body → record of place-name → count | token records) — lowered through the generalized wrapped-module machinery, typechecked, and instantiated over compiler-emitted source only (instantiateHirScenarioEvaluator).
• Scenario orchestration (evaluation order, validation, coercion, rounding, error shapes, and the documented code-mode quirks) extracted to compile-scenario-core.ts, shared by the unchanged sandboxed compileScenario (editor) and the new Node-only compileScenarioProgram (compile once per study, evaluate per trial).
• Exported only via the Node-only ./compiled-model subpath, so the main entry gains no TypeScript-compiler dependency.
• Math.random() is a compile error on scenario surfaces (determinism); scenario expressions/init compile at CLI bootstrap, so out-of-subset code fails study startup with the offending manifest path — validation happens before any trial runs.

petrinaut-cli

• createOptimizationProtocol compiles the scenario program once at bootstrap; per-trial optimization.evaluate runs the pre-instantiated evaluators. The run-with-scenario path compiles once per request. No compileScenario (sandbox) references remain in CLI source.

Security property

Only compiler-emitted source ever reaches new Function; user strings are JSON-quoted by the emitter, and lowering/typecheck reject dynamic import, tagged/template literals, regex, Function, prototype/constructor access, global assignment, and loops. Verified adversarially — no raw-execution path survives.

Review fixes included

• Reject a const/callback parameter that shadows the scenario/parameters inputs on scenario surfaces (hir:redeclared-parameter), matching the sandbox's SyntaxError so the server no longer accepts what the editor rejects.
• Documented that server-compiled scenario equality is strict (==→===) and can differ from the editor sandbox for mixed-type comparisons (scenarios.md, hir/README.md).

Tests

• petrinaut-core: 866 vitest
• petrinaut-cli: 36 vitest
• petrinaut editor: 150 vitest

Includes a parity suite (HIR program vs sandbox for representative scenarios incl. code-mode colored tokens and the unknown-place-skip quirk), a rejection matrix, and a security test proving zero dynamic evaluation per trial.

Docs

User guide (scenarios.md), OPTIMIZATION_INTEGRATION.md, hir/README.md, the threat model (raw scenario path removed), and a changeset are updated.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview, Comment	Jul 19, 2026 4:10am
petrinaut	Ready	Preview, Comment	Jul 19, 2026 4:10am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored		Jul 19, 2026 4:10am

[cursor]

PR Summary

Medium Risk
Touches the security-critical server path for user-authored optimization manifests; risk is reduced by eliminating raw new Function on manifest text, but correctness now depends on the HIR compiler/emitters and parity with the editor sandbox for edge cases like strict equality.

Overview
Server-side scenario materialization (optimization trials and CLI scenario runs) no longer evaluates manifest strings via sandboxed new Function. Parameter overrides, per-place initial-state expressions, and code-mode initial state are lowered through new HIR surfaces (scenarioExpression, scenarioInit), typechecked, emitted, and compiled once; only compiler-emitted source is instantiated. Per trial/request, the pre-built program runs shared orchestration in compile-scenario-core.ts.

The CLI calls compileScenarioProgram at optimization study bootstrap and once per scenario run request, failing startup with manifest paths when code is outside the supported subset. The in-editor path still uses compileScenario + the existing sandbox.

HIR lowering adds scenario-specific rules (e.g. no Math.random(), no redeclaring scenario/parameters, strict equality). Docs and the optimizer threat model are updated to reflect removal of the raw server execution path.

^{Reviewed by Cursor Bugbot for commit 718ddcd. Bugbot is set up for automated code reviews on this repo. Configure here.}