Design 34 every-event: the review reads a stream's subjects with nats_streams

No tool answered which subjects a stream holds, so the secret review could not find an
event the list missed; a module's tools read everything it holds, so the nats module's
tool gains that read, built first as a small fix.

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
This commit is contained in:
2026-11-11 02:41:11 +01:00
parent c232b1fb81
commit d758964ca9
@@ -3,7 +3,7 @@ layer: to-be
design: 34
milestone: every-event
updated: 2026-11-11
code: [mesh-sdk, mesh-delivery, mesh-tools, mesh-catalog modules/claude-code]
code: [mesh-sdk, mesh-delivery, mesh-tools, mesh-catalog modules/claude-code, mesh-catalog modules/nats]
decisions:
- "ADR 0670"
- "ADR 0367"
@@ -194,8 +194,8 @@ line depends on them.
22. **The code review confirms none carries a secret, before the grant is delivered.** The milestone's code review
(playbook 07, step 2) reads that list again at the group's heads, and confirms that no event's body carries a
credential, a token that grants an act, code, or a message marked secret; an intake `choice`'s one-use token is not
such a token (ADR 0259 §3, §5). A subject the bus holds that the list does not name is a finding of that review; how the subjects a stream holds
are read is open with the operator (no tool answers them today).
such a token (ADR 0259 §3, §5). A subject the bus holds that the list does not name is a finding of that review: the review reads the subjects
the EVENTS stream (and, under §23, each module stream) holds with `nats.nats_streams` as §31 extends it.
An event found carrying a secret holds the milestone's delivery and goes to the operator as a design question
(ADR 0670 §4).
23. **The stream events are read too.** *Pending the operator's answer (stream events).* §21's list also names every
@@ -243,6 +243,18 @@ line depends on them.
sets aside the old tool runner's manifest carrying `waits` (§10); until the revert reaches a node, `mesh_wait`
there answers as §29 says.
## Built first, ahead of the group
31. **`nats.nats_streams` reads the subjects a stream holds.** The nats module's tool `nats_streams` (mesh-catalog
`modules/nats`) takes, with `stream`, an optional `subjects`: a subject filter (`>` for all), read through
JetStream's stream information with that subject filter, answering each subject the stream holds with its message
count, sorted by subject; and an optional `bound` in bytes, 16,384 when absent and 262,144 at most, past which the
answer is cut and says so with `cut` and how many subjects it does not show. Without `subjects` it answers as
today. A module's tools read everything it holds (the operator's instruction that tools are how a module is spoken
to, 2026-10-25). It is built first, ahead of this group, as a small fix in mesh-catalog (playbook 08) under issue
595, with one table row in the module's existing tool test for the filter and one for the cut; §22's review reads
the bus with it.
## Acceptance
- **A watcher wakes on an event no manifest names** (the operator's acceptance; live, read by tool call): at the first