FE-1480: Project and realize a CPS model as a Petrinaut SDCPN

[lunelson]

🌟 What is the purpose of this PR?

A cyber-physical system (CPS) model can say what stochastic and dynamic Petrinaut net code must express, but it cannot choose a TypeScript implementation. This pull request records that split as an accepted decision: pure projection stops at a deterministic scaffold and typed code obligations; executable TypeScript is realized later through Petrinaut's client tools. It also records which design issues to settle next from existing baseline evidence, before runtime implementation resumes. Projection and realization code remain later work.

🔗 Related links

• FE-1480: Project and realize a CPS model as a Petrinaut SDCPN (internal)
• Parent in this stack: FE-1495 / #9312
• Decision: libs/@hashintel/brunch-agent/docs/adr/0005-model-assisted-sdcpn-realization.md
• Current strategy: libs/@hashintel/brunch-agent/docs/control/STEERING.md

🚫 Blocked by

• FE-1495: Prevent Brunch TypeScript contracts from drifting

FE-1438 blocks a later production proof of executable realization, not this decision record.

🔍 What does this change?

ADR-0005 amends the three-register claim in ADR-0003 and extends ADR-0004's artifact contract without changing application/library topology. The plugin's pure project step must emit a versioned stochastic dynamically colored Petri net (SDCPN) scaffold, a sidecar of field-addressed code obligations, and a typed loss report. Generated TypeScript is derived artifact state at the application meeting point; it is not a capture, a fourth register, or a plugin operation. Steering and the specification suite are reconciled to that boundary, and the selected next work is a design-convergence queue that can run from existing transcripts and literature.

🏗️ Agent notes

Stacked as ln/fe-1494-strategic-controls → ln/fe-1495-typescript-contracts → this branch.

Commits

• db3bf21054 Define SDCPN artifact realization boundary
• d3feeaa596 Reconcile the projection obligation ledger
• e070ee89f9 Select the Brunch design convergence queue
• 44a5e1df95 Encode the design convergence prerequisites

ADR-0005 outputs of project(elicitedModel)

1. Versioned SDCPN scaffold: deterministic structure plus readable comments in code fields that still need implementation.
2. Typed code obligations keyed by element and field: semantic intent, available places/token fields/parameters, supporting capture ids, acceptance checks.
3. Typed per-capture loss report.

Comments are readable context only. Realization must consume the sidecar. FE-1438 remains the hard blocker for the executable production proof because client tools must return field-addressed compiler diagnostics. Scaffold and obligation design do not require that round trip.

Selected design-convergence order

Recorded in docs/control/STEERING.md and STRATEGY-LOG.md. Linear owns the three hard prerequisite joins: FE-1407 blocks FE-1404, FE-1404 blocks FE-1406, and FE-1406 blocks FE-1431. Remaining arrows are strategic order, not additional Linear blockers.

design resolution
FE-1407 failure catalogue -> FE-1402 completion/stopping contract
-> FE-1403 CPS guidance -> FE-1404 condition-3 run
-> FE-1406 strategy quiver -> FE-1431 plugin-authoring/absence-locator closure

reviewer-path implementation
FE-1420 retry/abandonment safety -> FE-1438 client-tool return -> FE-1439 durable session

semantic implementation
FE-1393 exercised plugin SDK -> FE-1482 CPS plugin -> FE-1478 provenance read
-> FE-1480 scaffold/realization -> FE-1479 targeted correction join

Resolving the authority boundary does not select FE-1480 implementation as the next build. During design convergence, do not implement SDK, client tools, projection, provider routing, or deployment.

Spec and glossary

CONTEXT.md adds artifact boundary, code obligation, and artifact realization. Specs under docs/specs/ and SPEC-LEDGER.md distinguish deterministic scaffold/obligation output from pending projection and realization work.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• does not modify any publishable blocks or libraries, or modifications do not need publishing

Documentation and glossary only.

📜 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

ADR-0005, steering, specs, ledger, index, and glossary. No Petrinaut user-guide pages.

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

The changes in this PR:

• do not affect the execution graph

⚠️ Known issues

This branch does not implement project, obligation fulfillment, or Petrinaut compilation. FE-1438 still blocks an executable production proof of realization. Implementation priority versus the under-built elicitor remains a steering choice, not a consequence of landing this decision.

🐾 Next steps

• Run the design-convergence queue recorded in STEERING.md (FE-1407 → FE-1402 / FE-1403 → FE-1404 → FE-1406 → FE-1431).
• After that queue, prefer the reviewer path (FE-1420, FE-1438, FE-1439) before FE-1480 realization work.
• FE-1482 / FE-1478 remain prerequisites on the semantic path once implementation resumes.

🛡 What tests cover this?

No new executable tests. Existing architecture documentation-index coverage should still pass after the INDEX.md and ADR additions. Review is the check for ADR-0005, steering, and spec consistency.

❓ How to test this?

1. Read libs/@hashintel/brunch-agent/docs/adr/0005-model-assisted-sdcpn-realization.md and confirm it matches the FE-1480 issue's accepted boundary.

2. Read libs/@hashintel/brunch-agent/docs/control/STEERING.md and confirm design convergence is the selected next work, with FE-1480 realization later.

3. Run:

   turbo run test:unit --filter @hashintel/brunch-agent

📹 Demo

Not applicable — decision and steering records only.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 26, 2026 10:50am
petrinaut	Ready	Preview	Aug 26, 2026 10:50am
petrinaut-docs	Ready	Preview	Aug 26, 2026 10:50am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 26, 2026 10:50am

[lunelson]

• FE-1507: Move the repertoire into core behind a guarded prompts subpath #9349 : 2 dependent PRs (#9355 , #9381 )
• FE-1431: Build the plugin authoring surface (cycle two) #9348
• FE-1505: Time each interviewer turn by purpose #9347
• FE-1506: Show captures and completion while a panel elicitation runs #9346
• FE-1504: Run the process-model elicitor from the Petrinaut panel on one owned document #9345
• FE-1431: Build the plugin authoring surface #9337
• FE-1406: Audit the harness-teaching lineage and propose the fixed-key plugin contract (ADR-0007) #9327
• FE-1497: Build the controller read path and the SDCPN plugin package #9325
• FE-1404: Run condition 3 as the walking skeleton #9322
• FE-1403: Assemble and test the CPS interview guidance #9321
• FE-1402: Define and rehearse the elicitation completion contract #9320
• FE-1407: Catalogue elicitor failures that published measures miss #9319
• FE-1480: Project and realize a CPS model as a Petrinaut SDCPN #9313 👈 (View in Graphite)
• FE-1495: Prevent Brunch TypeScript contracts from drifting #9312
• FE-1494: Keep Brunch strategy and control records coherent #9311
• FE-1437: Move brunch-agent into hashintel/hash with its history #9274
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

PR Summary

Low Risk
No runtime or library code changes—only architecture, steering, and spec text. Risk is limited to teams building against outdated assumptions about deterministic full-net projection.

Overview
Documentation-only decision record for FE-1480: pure project stops at a deterministic SDCPN scaffold, a typed code-obligation sidecar, and the loss report; runnable TypeScript is artifact realization at the application layer (Petrinaut client tools, compile/sim gates), not a capture, fourth IR register, or plugin operation.

ADR-0005 is added and wired through ADR-0003 / ADR-0004, the elicitation-kernel and IR/plugin specs, SPEC-LEDGER, CONTEXT.md glossary, and INDEX.md. STEERING and STRATEGY-LOG (S-004–S-006) pivot the active frontier to a design-convergence queue (FE-1407 → FE-1402/1403 → FE-1404 → FE-1406 → FE-1431) from existing baseline evidence, with reviewer-path work (FE-1420/1438/1439) before semantic FE-1480 implementation; FE-1438 remains the gate for an executable realization proof. Agent legibility and steering protocols gain review-before-commit rules for ordered proof frontiers.

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

[lunelson]

Status note (2026-08-25): the design-convergence queue and the three hard prerequisite joins described in the agent notes here (FE-1407 → FE-1404 → FE-1406 → FE-1431) were superseded by strategy entry S-007 and ADR-0006 in #9322, further up this stack. The blockers were removed in Linear; the record above is kept as authored.

The base branch was changed.