FE-1523: Import and export Petrinaut files as YAML

[kube]

🌟 What is the purpose of this PR?

Petrinaut saves and loads nets as JSON, where multi-line code fields (transition kernels, lambdas, metrics) serialize as single lines with \n escapes. Exports now default to YAML, and every import path — the editor, the CLI's --model and --optimization files, and the Python bindings that forward paths to the CLI — accepts YAML and JSON interchangeably, detected from the content. Existing JSON files load unchanged, and JSON export stays available in the Export menu.

The same field of the SIR example, before and after:

"lambdaCode": "// Mass-action infection: fires at the configured infection rate whenever a\n// Susceptible and an Infected are both present (the two standard input arcs).\nexport default Lambda((tokens, parameters) => parameters.infection_rate)"

lambdaCode: |-
  // Mass-action infection: fires at the configured infection rate whenever a
  // Susceptible and an Infected are both present (the two standard input arcs).
  export default Lambda((tokens, parameters) => parameters.infection_rate)

The document opens with format metadata, then the sections in dependency order (the Probabilistic Satellite Launcher example):

version: 1
meta:
  generator: Petrinaut
title: Probabilistic Satellite Launcher
parameters: ...
types: ...
differentialEquations: ...
places: ...
transitions: ...
metrics: ...
scenarios: ...

An optimization manifest (the CLI's --optimization input) reads the same way — the checked-in supply-chain fixture, with most of the embedded model and all but one binding elided. scenario.id and objective.metricId refer to the scenario and metric inside model.definition:

kind: petrinaut-optimization
version: 1
name: Supply Chain Profit model optimization
model:
  title: Supply Chain Profit model
  definition:
    places: ...
    transitions: ...
    parameters: ...
    scenarios:
      - id: scenario_baseline_supply_chain_with_stock
        name: Baseline with enough stock
        scenarioParameters: ...
    metrics:
      - id: metric_profit
        name: Profit
        code: |-
          const soldOrders = state.places.SoldOrders.count;
          ...
scenario:
  id: scenario_baseline_supply_chain_with_stock
  parameterBindings:
    production_rate:
      kind: optimize
      domain:
        kind: continuous
        minimum: 20
        maximum: 250
        scale: linear
    ...
objective:
  metricId: metric_profit
  direction: maximize
execution:
  seed: 1234
  dt: 0.1
  maxTime: 36.5
study:
  trials: 1000
  sampler: tpe

🔗 Related links

• FE-1523

🔍 What does this change?

• @hashintel/petrinaut-core gains file-format/document-text.ts. parseDocumentText tries JSON.parse first, so JSON documents keep their exact semantics, and falls back to js-yaml with CORE_SCHEMA, so on/yes stay strings and timestamps stay strings. serializeDocument encodes either format; its YAML output writes multi-line strings as literal block scalars, never folds long lines, and writes repeated objects in full instead of anchor/alias references.
• parseSDCPNDocument(text) is the text-level counterpart to parseSDCPNFile(data), and serializeSDCPN takes a format option that defaults to "yaml". A consumer that re-parses serializeSDCPN output with JSON.parse must now pass format: "json".
• The editor's Export menu offers YAML, YAML without visual info, JSON, JSON without visual info, and TikZ. Import accepts .yaml, .yml, and .json. Actual mode's Export Net follows the YAML default.
• Both formats write their keys in the fixed order shown above, where each section references only sections above it by id; subnets and componentInstances, absent from that example, come after differentialEquations and places respectively. Subnet keys are ordered the same way, a compile-time check fails when SDCPN gains a field without an export position, and import accepts any key order.
• Import accepts a versioned file without meta, so a hand-written file can declare version: 1 without generator boilerplate. Exports keep writing meta.generator: older importers require it on versioned files, so removing it would make new exports unreadable there.
• The CLI's JSON-lines protocol and its stdin sources still read one JSON line; only file loading gained YAML. Actual-mode stream recordings and clipboard payloads stay JSON.
• The user guide, the CLI README, the arch-docs usage manual, and the Python bindings' docstrings and README describe the new formats.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

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

Patch changesets for @hashintel/petrinaut-core and @hashintel/petrinaut.

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR

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

The changes in this PR:

• do not affect the execution graph

🛡 What tests cover this?

• document-text.test.ts covers format detection, JSON-first parsing, error selection, core-schema scalars, block scalars, and the throw on values YAML cannot represent.
• serialize-sdcpn.test.ts round-trips serialize → parse in both formats, with and without visual info.
• The CLI tests load a hand-written YAML model file and a YAML optimization manifest.

❓ How to test this?

1. Run yarn workspace @hashintel/petrinaut dev and load an example net.
2. Open the hamburger menu → Export → YAML; the downloaded file's code fields are block scalars.
3. Menu → Import with that file, then with an older .json export; both load.
4. For the CLI: node libs/@hashintel/petrinaut-cli/dist/cli.js serve --model <file>.yaml --stdio answers {"id":1,"method":"metadata"}.

🤖 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	Aug 28, 2026 9:31am
hashdotdesign-tokens	Ready	Preview	Aug 28, 2026 9:31am
petrinaut	Ready	Preview	Aug 28, 2026 9:31am
petrinaut-docs	Ready	Preview	Aug 28, 2026 9:31am

[cursor]

PR Summary

Medium Risk
Default export format and new parsing path affect all file I/O for models/manifests; JSON-first vs YAML fallback semantics must stay stable for existing JSON workflows.

Overview
Adds content-detected YAML and JSON for Petrinaut net files and optimization manifests across core, editor, and CLI. Exports default to YAML (block scalars for multi-line code); JSON remains available from the Export menu.

@hashintel/petrinaut-core introduces parseDocumentText / serializeDocument (js-yaml, JSON-first parse) and parseSDCPNDocument for raw file text. serializeSDCPN gains format (default "yaml") and writes version, meta, title, then net sections in dependency order; import still accepts any key order. Versioned imports may omit meta.

The editor Export menu lists YAML/JSON (with/without visual info); import accepts .yaml, .yml, .json. CLI --model and --optimization file paths use the same parsing; stdio JSON-lines protocol is unchanged.

Docs and Python binding docstrings describe YAML as the editor default.

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 60.66%. Comparing base (3b2d8e3) to head (b4b620d).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9379      +/-   ##
==========================================
- Coverage   60.74%   60.66%   -0.09%     
==========================================
  Files        1440     1439       -1     
  Lines      143458   143120     -338     
  Branches     6662     6654       -8     
==========================================
- Hits        87141    86817     -324     
+ Misses      55225    55212      -13     
+ Partials     1092     1091       -1     

Flag	Coverage Δ
apps.hash-api	14.68% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.