FE-1745: Let Brunch draft Ledger-derived experiments

[kostandinang]

🌟 What is the purpose of this PR?

Mission 8 (FE-1745) makes experiment drafting part of normal Brunch modelling. Using the settled Ledger and current Petrinaut model—not keywords such as “experiment” or “optimize”—Brunch detects when an operational decision is testable, drafts an experiment, and displays it as Drafted — not run. The experiment starts only when the user presses Run, then follows Petrinaut’s existing runExperiment path, including records, progress, the “N active” indicator, and Simulate → Experiments.

When complete, this PR establishes:

• a proactive, Ledger-derived proposal;
• Petrinaut-owned validation against the live model without execution; and
• one user-started run through the existing execution path.

It does not claim constraint enforcement, proposal persistence, experiment credibility, or consumer handoff (Mission 11). The first demo is intentionally constraint-free and says so.

The branch authority is libs/@hashintel/brunch-agent/MISSION.md. Lu’s Mission 8 draft is the planning record from which this cut was taken and remains the home for deferred work.

Proactive trigger behaviour

Readiness requires both Ledger meaning and model executability.

The Ledger must state the decision, objective and direction, tunable quantity with a user-provided range and unit, operating regime, and horizon. The model must contain the corresponding saved scenario, an integer- or real-typed scenario parameter, and a saved objective metric.

Model structure alone never triggers a proposal or supplies its objective. Brunch never invents bounds, units, or thresholds. It proposes once when readiness is first reached or the meaningful configuration changes; declined or completed proposals are not repeated unchanged.

When prerequisites are missing, Brunch constructs supported scenarios and metrics through new mutate_petrinaut_net operations or asks the smallest focused question. Restrictions that the current request cannot carry are recorded under unsupported and disclosed before Run is offered; optional observed metrics are labelled reported, not enforced. A load-bearing hard restriction blocks Run rather than being silently dropped.

Demo flow (support-desk staffing)

1. User: “Help me model our support operation. We need to decide how many agents to schedule while keeping waiting times low at peak.”
2. Brunch elicits and settles the Ledger: 2–8 agents, average waiting time as the objective, peak demand as the regime, and a two-hour horizon.
3. Brunch constructs the net, a saved Peak demand scenario with an integer activeAgents parameter, and a saved average-waiting-time metric.
4. Brunch drafts an experiment that varies agents from 2–8 and minimizes average waiting time. The card shows Drafted — not run · not saved with the document, with Run and Dismiss actions, while Brunch’s turn continues.
5. The user presses Run. The top bar shows “1 active,” Simulate → Experiments updates live, and the indicator clears when the completed result remains available.

Ownership and dependencies

• Lu — owns the Mission 8 draft and Ledger-to-experiment correspondence on FE-1573: Protect long Brunch interviews from abrupt Ledger loss and stalled responses #9761; authorized this second live mission, its issue, and merge posture.
• Chris — owns the execution host (FE-1666/1667/1668) and creation UX (FE-1718, FE-1718: Polish experiment creation, results, and optimizer controls #9725). The only required upstream decision is how to expose canonical preparation without execution: a named prepareExperiment export from @hashintel/petrinaut/react or a PetrinautExperimentHost method. This branch provisionally uses the named export with a patch changeset and will switch if Chris prefers the host method. The existing experiment card, drawer, indicator, and results UI remain unchanged.
• Kostandin — owns the Brunch changes and website-owned widget.

🔗 Related links

• Linear: FE-1745
• Base branch PR: FE-1573: Protect long Brunch interviews from abrupt Ledger loss and stalled responses #9761 (Mission 7e, Lu)
• Related: FE-1484, FE-1718 / FE-1718: Polish experiment creation, results, and optimizer controls #9725, FE-1735 (Chris); FE-1573 (parent branch mission)
• Demo feedback thread (internal): https://hashintel.slack.com/archives/C0AJT2P2F52/p1789563418113119

🚫 Blocked by

• Merge order: this PR is based on ln/fe-1573-mission-7e-express until FE-1573: Protect long Brunch interviews from abrupt Ledger loss and stalled responses #9761 merges; Lu owns the resulting MISSION.md lifecycle decision.
• Chris’s preferred preparation boundary: named export or host method. The branch provisionally uses the named export.
• Lu’s separate authorization for a paid persona observation of the support-desk case.

🔍 What does this change?

• Cuts Mission 8 into this branch’s live MISSION.md, including Status, Imperative, Throughline, Proof, Constraints, Fog-line, Stop, and Deferred.
• Exports prepareExperiment from @hashintel/petrinaut/react with a patch changeset.

🏗️ Agent notes

Delivery proceeds in work packages, each with an oracle defined in MISSION.md:

• WP-A — scenario and metric operations: add/update/remove scenarios and metrics across mutate-petrinet.ts, mutation-record.ts, and the website executor, with per-operation tests and a loopback case.
• WP-B — guidance: add experiment-readiness guidance to the SDCPN modelling skill, prompt, and workpiece template, covered by the packaging test.
• WP-C — drafting tool: add draft_petrinaut_experiment with { experiment, declarations, basis, unsupported }, wire it through the Brunch and website catalogues, and cover it with schema fixtures and yarn test:native-schema.
• WP-D — widget: prepare without execution; auto-submit status, summary, and diagnostics; supersede earlier proposals; re-prepare and diff before Run; then call experimentHost.runExperiment. Oracles cover no execution, replacement, user-started execution, and stale proposals.
• WP-E — demo: add the support-desk case under evaluations/cases/support-desk-staffing/ and record one agent-browser run.

At the branch point, prepareExperiment was private to run-experiment.ts. None of Chris’s open PRs (#9664, #9723, #9724, #9725, #9728, #9729) touched that file, the required react/index.ts export, Petrinaut’s experiment schemas, or the relevant Brunch integration files.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• modifies an npm-publishable library and I have added a changeset file(s)

📜 Does this require a change to the docs?

The changes in this PR:

• are in a state where docs changes are not yet required but will be
  • tracked in FE-1745: update Petrinaut’s ai-assistant.md if WP-D makes the Brunch panel behaviour user-facing

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

⚠️ Known issues

• PetrinautExperimentRequest does not carry constraints or a constraint policy; prepareExperiment currently supplies constraints: [] and constraintPolicy: null. This PR does not change that. Restrictions are reported as unsupported, never as enforced.
• Proposals are session-only and do not survive reload; the widget states this explicitly.

🐾 Next steps

• Deliver WP-A through WP-E incrementally on this PR.
• Leave constraint carriage, the Inventory avoid-state example, design E, and drawer prefill in the Mission 8 draft for a later cut.

🛡 What tests cover this?

• Current: @hashintel/petrinaut typecheck with the new export (turbo run lint:tsc --filter @hashintel/petrinaut; 8/8 tasks successful).
• Planned: the per-work-package oracles listed under MISSION.md → Proof obligations.

❓ How to test this?

1. Check out the branch and run yarn install.
2. Run npx turbo run lint:tsc --filter @hashintel/petrinaut.
3. Confirm that import { prepareExperiment } from "@hashintel/petrinaut/react" resolves.
4. Read libs/@hashintel/brunch-agent/MISSION.md for the live contract.

📹 Demo

Loom

[vercel]

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

Project	Deployment	Actions	Updated
hash	Ready	Preview	Sep 16, 2026 11:47pm UTC

3 Skipped Deployments

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Sep 16, 2026 11:47pm UTC
petrinaut	Skipped		Sep 16, 2026 11:47pm UTC
petrinaut-docs	Skipped		Sep 16, 2026 11:47pm UTC

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ kostandinang
❌ ampagent
_{You have signed the CLA already but the status is still pending? Let us recheck it.}