[lunelson]

🌟 What is the purpose of this PR?

Brunch and its users can now ask why a net element is modelled the way it is and get an answer from the Ledger. Select something on the canvas and the Ledger tab shows the reflections that name it, the claims they rest on and the user messages behind those claims, and highlights those records in the Ledger. The query_basis tool gives Brunch the same answer. The Ledger tab is now a document whose records carry anchors, which is the ground the next step, comments on the Ledger (FE-1851), builds on.

The branch also gives each type shared by the Brunch server and website one owner, mostly in @hashintel/brunch-agent, and trims that library's exports to what its consumers import.

🔗 Related links

• FE-1850 (internal): answer why a net element was modelled as it was
• FE-1336 (internal): Petri net provenance
• FE-1851 (internal): comments on the Ledger, on a branch stacked on this one
• Follow-ons: FE-2020 (internal) makes Brunch name the elements each reflection explains; FE-2022 (internal) makes cited records clickable; FE-1332 (internal) would let a "why" question use the canvas selection
• FE-1776 (internal): moving the assistant panel's contents out of Petrinaut, where the remaining Brunch couplings are tracked
• FE-1991 (internal): let assistant hosts decline Petrinaut's injected diagnostics
• Middle of a stack. It sits on FE-1943: Show where each Brunch exchange's time goes in persona runs #10066 (FE-1943); review that first. FE-1943: Shorten Brunch's turns by cutting model calls and Ledger text #10070 (FE-1943) sits on it.

🚫 Blocked by

• FE-1943: Show where each Brunch exchange's time goes in persona runs #10066, which this branch is based on.

🔍 What does this change?

• One backward trace. traceLedger follows a net element to the reflections that name it, then to their claims, entities and discharged obligations, and each record to the user turn it came from. It never walks forward: an entity does not pull in every claim about it.

• query_basis answers from that trace alone. Its dispositions are basis-declared, basis-absent, not-found and stale-read. It no longer treats records committed in the same turn as an element's basis, so an element no reflection names reads as having no recorded basis. Turn excerpts (240 characters) are filled in. Brunch is told to quote the turns it cites, and to offer no rationale of its own when no basis was recorded.

• Ledger tab as a document. The tab renders the Ledger projection as React instead of Markdown. Every record occurrence carries data-ledger-address, and record IDs stay hidden.

• Canvas selection. A panel explains the selection, or says Brunch recorded no reasoning for it. The records behind it are ringed and the rest fade; the first scrolls into view.

• Reflections. Show Brunch's reflections, off by default, lists each reflection under the entities it concerns. Show in net selects the elements it names. The tab reads and sets the selection through Brunch's editor plugin, so the host passes nothing.

• Badge. The Ledger tab's badge counts commits only; net changes add nothing to read there.

• Markdown only for the model. The user skin of renderLedgerMarkdown had no callers left and is removed. The model's Markdown is unchanged, byte for byte.

• User turns. Petrinaut's injected diagnostics are dropped from Brunch's user turns, and the petrinaut-contextual-user-message envelope is removed. Making that injection optional per host is FE-1991.

• Shared ID matching. namesId moves into @hashintel/brunch-agent, with netElementSelectionItem and namesSelectionItem, so the website matches the IDs Brunch wrote as query_basis does.

• react-markdown and remark-gfm leave the website.

• Type ownership. The library's README states which code belongs there: what the server and browser must agree on. The library now owns, and both sides import:

  • the browser-tool result envelope;
  • the browser-call protocol;
  • the set of tools the browser runs;
  • the net read-back type (NetStructure);
  • Ledger record types derived from their schemas.

  The server takes thinking levels, JSON and chronology types from Flue. The website takes its voice, approval and replay types from their owners. The library exports only what its consumers import.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

• Changes only @hashintel/brunch-agent, which is private, and the unpublished docs/ of @hashintel/petrinaut. No changeset.

📜 Does this require a change to the docs?

• libs/@hashintel/petrinaut/docs/ai-assistant.md describes the selection panel, the reflections switch and the badge. apps/brunch-agent/docs/petrinaut/ARCHITECTURE.md describes query_basis and the tab.

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

• Does not affect the execution graph.

⚠️ Known issues

• The canvas link and query_basis assume reflections name the net elements they explain. Nothing enforces that yet (FE-2020). In a live session, reflections named every top-level place and transition but no parameters, arcs or elements inside a subnet.
• Brunch doesn't see the canvas selection, so a "why" question has to name the element (FE-1332).
• Show in net selects an element inside a subnet the user isn't viewing but doesn't move the canvas there.
• A confirmed claim with no entity appears in neither ledger_compile nor the Ledger tab (from FE-1764: Keep elicited knowledge in an efficient append-only Ledger #9865).
• src/server/provider-admission.test.ts fails intermittently, also when run alone. It predates this branch.

🛡 What tests cover this?

• traceLedger, the projection's per-entity reflections, ID matching and query_basis dispositions have unit tests.
• Pane tests cover the document, the selection panel, the reflections switch and the badge. An in-editor test runs Show in net through the real editor and plugin and checks the selection comes back explained.
• Checked live in a persona-built conversation. Asked why a place is modelled as it is, Brunch called query_basis and answered from the reflections and claims behind it. Asked about a parameter no reflection names, it said no basis was recorded.
• Lint, type, unit, build and integration checks pass for @hashintel/brunch-agent, @apps/brunch-agent, @apps/petrinaut-website and @tests/petrinaut-brunch-integration.

[vercel]

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

Project	Deployment	Actions	Updated
petrinaut	Ready	Preview	Oct 20, 2026 4:17pm UTC
petrinaut-docs	Ready	Preview	Oct 20, 2026 4:17pm UTC

2 Skipped Deployments

Project	Deployment	Actions	Updated
hash	Ignored	Preview	Oct 20, 2026 4:17pm UTC
hashdotdesign-tokens	Ignored	Preview	Oct 20, 2026 4:17pm UTC

[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 0e9955d. Configure here.}