FE-711: Add Metrics to Experiments

[kube]

🌟 What is the purpose of this PR?

Adds Monte Carlo experiment metrics to Petrinaut, so experiments can define metric outputs, run them in a worker, and inspect scalar/distribution timelines.

🔗 Related links

• FE-711

🚫 Blocked by

None.

🔍 What does this change?

• Adds Monte Carlo metric specs, accumulators, and worker/runtime plumbing in @hashintel/petrinaut-core.
• Updates experiment creation in @hashintel/petrinaut to require explicit metrics, validate metric LSP diagnostics, and default to model scenarios when present.
• Adds experiment metric timeline visualizations for scalar and distribution outputs, including per-frame distribution popovers.
• Adds Simulate stories for running SIR and Satellites Launcher experiments.

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 internal and do not require a docs change

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

The changes in this PR:

• do not affect the execution graph

⚠️ Known issues

• Metric frame storage/downsampling may need follow-up optimization for long experiments.

🐾 Next steps

• Follow up on streaming/downsampling distribution data from the worker to the visualization layer.

🛡 What tests cover this?

• @hashintel/petrinaut-core Monte Carlo simulator, runtime, and accumulator tests.
• @hashintel/petrinaut experiment provider and metric LSP validation tests.
• Package lint and TypeScript checks were run during development.

❓ How to test this?

1. Open the Simulate Storybook stories for SIR or Satellites Launcher.
2. Create an experiment with at least one metric.
3. Confirm experiment progress updates and metric timelines render, including distribution popovers on timeline click/drag.

📹 Demo

Not included.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview, Comment	Jun 1, 2026 10:57am
hashdotdesign-tokens	Ready	Preview, Comment	Jun 1, 2026 10:57am
petrinaut	Ready	Preview, Comment	Jun 1, 2026 10:57am

[cursor]

PR Summary

Medium Risk
Large change to Monte Carlo experiment and worker messaging plus user-supplied expression compilation, but covered by tests and scoped to simulation/metrics—not security-critical paths.

Overview
Replaces the old place token count distribution experiment output with a configurable Monte Carlo metrics pipeline: declarative metric specs (expression, place mean, transition firing), mergeable numeric/histogram accumulators, and per-frame scalar or distribution frames streamed from the simulator, local experiment loop, and worker (metricSpecs on init, metricFrames on the wire).

@hashintel/petrinaut now requires at least one metric when creating an experiment, validates duplicate metric ids and expression LSP diagnostics, and surfaces metricFrames / latestMetricFramesById instead of distribution frames. The create-experiment drawer adds a metrics section (built-in kinds, model metrics, custom code with LSP). Simulation settings default to the first scenario when the model has scenarios; the editor defaults to the experiments simulate view.

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

[augmentcode]

🤖 Augment PR Summary

Summary: This PR introduces first-class Monte Carlo “experiment metrics” for Petrinaut experiments, including runtime/user-defined metric evaluation and UI controls to configure and view metric outputs.

Changes:

• Exports new Monte Carlo metric APIs and types from @hashintel/petrinaut-core (metric specs, user-defined metrics, accumulators).
• Adds a SimulationFrameReader-based per-run frame reader so metrics can safely inspect place/transition state.
• Implements numeric and histogram accumulator utilities plus tests for merge/monoid behavior.
• Adds metric spec compilation (including expression metrics via compileMetric) into user-defined metric configs.
• Extends createMonteCarloExperiment() with a local execution path when metric callbacks/specs are provided (worker cannot receive executable code).
• Updates experiments React state/provider to store metric specs, metric frames, and latest-by-id.
• Adds UI for defining metrics when creating an experiment (including LSP diagnostics for expression metrics).
• Updates experiment viewing UI to optionally show token-count timeline and a new metrics summary section.
• Adds architecture/proposal/usage docs for Monte Carlo metrics direction.

Technical Notes: Worker-backed experiments remain distribution-only; experiments with expression/aggregated metrics run locally to avoid posting JS code across the worker boundary.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 3 suggestions posted.

Comment augment review to trigger a new review at any time.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 079dd75. Configure here.}