FE-1851: Comment on the Ledger and have Brunch resolve the comments

[lunelson]

🌟 What is the purpose of this PR?

Users can comment on Ledger records. Brunch reads the comments on its next turn, corrects the Ledger or asks about them, and the comments are resolved once a commit addresses them.

🔗 Related links

• FE-1851 (internal): comments on the Ledger
• Top of a stack. It sits on FE-1943: Shorten Brunch's turns by cutting model calls and Ledger text #10070 (FE-1943), which sits on FE-1850, FE-1336: Explain a net element from the Ledger, on the canvas and to Brunch #10067 (FE-1850, FE-1336) and FE-1943: Show where each Brunch exchange's time goes in persona runs #10066 (FE-1943); review those first.

🚫 Blocked by

• FE-1943: Shorten Brunch's turns by cutting model calls and Ledger text #10070, which this branch is based on.

🔍 What does this change?

• Comment signal. A batch of comments is a turn of its own: a Flue signal of type brunch.ledger-comments, rendered to the model as an XML block. Each comment names the records it is on by address, keeps the selected text for display, and has an ID such as n1.
• Fold. foldCommits holds comments in LedgerState.comments and treats a comment signal as a turn: later commits are anchored to it, and exchanges counts it.
• Resolution. Entity, claim, reflection and obligation entries take resolves: [commentId]; an unknown ID is refused. Receipts and ledger_compile list the comments still open, and the system prompt asks Brunch to address every comment.
• Transport. @local/flue-aisdk-transport can deliver a host-derived signal instead of a user message, and a reopened transcript shows host-named signals as user turns.
• Ledger tab. Select text, choose Comment, and the comment waits under its records. A composer bar visible from both tabs (N comments on the Ledger · Send · Discard) sends them as one turn. Chat shows the turn as Comments on the Ledger. Records with an open comment carry a badge that shows the comment on hover, until it is resolved.

Pending comments are kept in memory per editor, so a reload drops unsent ones.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

• Changes only private packages (@hashintel/brunch-agent, @local/flue-aisdk-transport). No changeset.

📜 Does this require a change to the docs?

• libs/@hashintel/petrinaut/docs/ai-assistant.md ("Ledger in Brunch") needs a paragraph on commenting. This stack doesn't touch the Petrinaut packages, so it follows separately.

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

• Does not affect the execution graph.

🛡 What tests cover this?

• Library unit tests for the fold, resolves, refusal of unknown comments, open comments on receipts and in the Markdown map.
• Transport tests for signal delivery and transcript projection.
• Website tests for selection-to-address resolution, the comment form, pending notes, open badges, the pending-comments store, the composer bar and the chat projection.
• ledger-history.integration.ts sends a comment through the real Flue runtime and checks that the model receives it, the commit is anchored to it, and resolves clears it.

❓ How to test this?

1. yarn dev:brunch, open a Brunch construction conversation and let Brunch record something.
2. In the Ledger tab, select text on a record, choose Comment, write a correction and add it.
3. Choose Send in the composer bar; check that Brunch corrects the record and the badge clears.

[vercel]

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

Project	Deployment	Actions	Updated
hash	Ready	Preview	Oct 19, 2026 9:47pm UTC
petrinaut	Ready	Preview	Oct 19, 2026 9:47pm UTC
petrinaut-docs	Ready	Preview	Oct 19, 2026 9:47pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Oct 19, 2026 9:47pm UTC