docs(events): annotations are runtime-written; the agent path is not built (#90) - #492
Open
bricef wants to merge 1 commit into
Open
docs(events): annotations are runtime-written; the agent path is not built (#90)#492bricef wants to merge 1 commit into
bricef wants to merge 1 commit into
Conversation
…built (#90) The committed schema advertised annotations as "commentary from the producing agent". No agent can write one — there is no built-in, tool or reducer intent for it, and nothing in an agent's prompt or tool surface mentions the channel. The 2026-07-09 review called it "a small honesty trap", and the trap works on agents reading the docs, which is how it was found in the first place. Trimmed rather than wired, and deliberately without discarding the design. ## What is now said `docs/design/committed/event-schema.md` describes the layer as it is: runtime-written, with the reserved vocabulary marked per key. Four of the five well-known keys have no writer at all; `flags` has one and it is the host's context-pressure warning. The `dead_letter_*` keys the dispatcher and advisory watch write are named as runtime bookkeeping so the reserved list is not mistaken for the whole story. That folder's own rule is the licence for this edit: a committed doc "describes the system as built... If a committed doc contradicts the code, one of them is wrong — fix whichever it is." Here the doc was. ## What is preserved The intent, in the two places built for it. The aspirational design (`inter-node-contracts-and-event-layers.md`) is untouched — it is explicitly design-ahead and is where the annotation registry and learning loop live. ADR-0016 is untouched too, because ADRs are point-in-time records that "aren't rewritten as the system evolves"; its index row in `docs/adrs/README.md` gains the current-state note instead, which is how ADR-0011's and ADR-0027's rows already work. The schema doc gains a "When the agent write path arrives" section recording the decision: **consumer-driven — it lands when something reads it.** Building the producer first would give agents somewhere to write that nothing consumes, and the barrier means no agent ever reads annotations back. It also records that `reasoning` needs a retention answer before any write path opens: it is chain-of-thought, annotations ride every event, and the log is kept. ## Also recorded, not resolved The `flags` writer emits an object where the schema specifies an array of strings. `Annotations` is `Map<string, JsonValue>` so nothing catches it. Which shape is right is a decision, so it is written down in both the doc and the rustdoc and left on #90. No behaviour change. Doc comments only; `events.rs` stays inside its size budget (tightened prose rather than raising it). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Qc4GGVQbQ7nT2aqYtjP4Mh
Module couplingModule coupling changed in this PR — see below. What changedfq-runtime
Full coupling tablefq-cli — 32 modules
fq-dashboard — 4 modules
fq-edge — 8 modules
fq-lint — 4 modules
fq-ops — 5 modules, 1 cycle group(s)
fq-runtime — 26 modules, 1 cycle group(s)
fq-store — 18 modules
fq-tools — 4 modules
Advisory — this gates nothing. Measured at Edges are |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #90 by trimming, per the decision recorded there.
The committed schema advertised the annotations layer as "commentary from the producing agent". No agent can write one — no built-in, tool or reducer intent, and nothing in an agent's prompt or tool surface mentions the channel. The 2026-07-09 review called it "a small honesty trap"; it works on agents reading the docs, which is how it was found.
The layer isn't empty — it's host-owned
That reframes the fix.
Event::annotateis load-bearing; every writer is runtime code:control_plane/dispatcher.rs,control_plane/advisory_watch.rsdead_letter_*worker/reducer/runner/llm.rsflags(context-pressure warning, #76)Four of the five well-known keys —
notes,confidence,reasoning,sources_considered— have no writer at all. So this isn't deleting a capability; it's describing the one that exists.What changed
docs/design/committed/event-schema.md— the layer table's "Written by" column now says runtime, not producing agent. The Annotations section leads with the fact that agents have no write path. The well-known-keys table gains a Status column so shipped and reserved are distinguishable at a glance.docs/adrs/README.md— ADR-0016's index row notes that the annotation operations it names aren't built.events.rs— theannotation_keysrustdoc made the same claim; it now says reserved-not-available and points at the schema doc.The licence for editing a committed doc is that folder's own rule: "If a committed doc contradicts the code, one of them is wrong — fix whichever it is." Here the doc was.
What is deliberately preserved
The intent, in the two places built to hold it:
docs/design/aspirational/inter-node-contracts-and-event-layers.mdis untouched. It is explicitly design-ahead, and it is where the annotation registry and learning loop live.docs/adrs/README.mdstates ADRs "aren't rewritten as the system evolves (later ADRs supersede earlier ones; guides track the current state)". The current-state note goes on its index row instead — the same treatment ADR-0011's and ADR-0027's rows already carry.The schema doc gains a "When the agent write path arrives" section recording the decision: it is consumer-driven — the write path lands when something reads it. Building the producer first gives agents somewhere to write that nothing consumes, and the consumer barrier means no agent ever reads annotations back. ADR-0016 still governs the shape it must take (typed operations, never
annotations.set(key, value)).It also records that
reasoningneeds an answer before any write path opens: it is chain-of-thought, annotations ride every event, and the log is retained — a retention decision, not plumbing.Recorded, not resolved
The
flagswriter emits an object ({"context_pressure": "…"}) where the schema specifies an array of strings.AnnotationsisMap<string, JsonValue>, so nothing catches it. Which shape is right is a decision, so it's written down in the doc and the rustdoc and left on #90 rather than silently picked here.Verification
just quality,just lint-docs,RUSTDOCFLAGS="-D warnings" cargo doc, and 652fq-runtimelib tests — all green. Doc comments only, no behaviour change.events.rsis on a file-size budget and the additions tripped it; the prose was tightened to fit rather than raising the budget.Note for reviewers:
just check-linksreports0 relative links checkedwhen run from a.claude/worktrees/*worktree — the script skips any path containing.claude, so the gate is vacuously green in the layout this repo uses. The 41 relative links in the changed files were verified separately. Fixed under its own PR.🤖 Generated with Claude Code
https://claude.ai/code/session_01Qc4GGVQbQ7nT2aqYtjP4Mh