diff --git a/03-DESIGN/01-to-be/34-milestones/every-event.md b/03-DESIGN/01-to-be/34-milestones/every-event.md index deae12ad..490bd251 100644 --- a/03-DESIGN/01-to-be/34-milestones/every-event.md +++ b/03-DESIGN/01-to-be/34-milestones/every-event.md @@ -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, mesh-catalog modules/nats] +code: [mesh-sdk, mesh-delivery, mesh-tools, mesh-catalog modules/claude-code] decisions: - "ADR 0670" - "ADR 0671" @@ -140,7 +140,8 @@ that holds its mark reach the machines together. 14. **A misspelt name is refused, not waited on for ever.** Before it subscribes, `waitAnswer` refuses a name whose emitter is neither a seat nor a module of the catalog half the tool runner holds from G (its first view by `mesh-catalog.revision`, followed on `catalog-revision`; design 47 G §196), naming that source and its revision. - A name whose emitter is known but whose event no seat definition and no manifest's `emits` declares is waited on, + A name whose emitter is known but whose event no seat definition and no module's entry in the catalog half + declares (its `emits` and its streams' events, design 46 7-approval-mark §5) is waited on, and its timed-out answer says that no declaration names that event. While the catalog half is not yet read (the first views' state, `mesh_first_views`), names are not checked, and the answer says `unchecked` with why; a marked wait is then held as §34 says. @@ -194,18 +195,19 @@ that holds its mark reach the machines together. ## Events carry no secret 21. **The prepare lists every event.** The milestone file's prepare (playbook 07, step 0) gains a section *Events and - their fields*: every event each module's manifest `emits` and each seat's definition declares, read from the - manifests and the seat definitions at the group's heads, not only from what the live bus holds, so the events G - and design 46's milestone 7 add are listed (the finding streams of design 47 G §383 among them), each a holder's - event with its subject form; and every event mesh-sdk publishes on a module's behalf (the - announcement's `states` on `mesh.mod..event.states`, found by the callers of its subject builders); each - with the fields of its body as the emitting code builds it, by file and line (ADR 0670 §4). + their fields*: every event each module declares (its `emits` and its streams' events) and each seat's definition + declares, read from the module catalog: the catalog revision of the change's branch (`mesh-catalog.revision`), + which carries the seat definitions too, and nothing else, no manifest and no bus read, so the events G and design + 46's milestone 7 add are listed (the finding streams of design 47 G §383 among them), each a holder's event with + its subject form; and every event mesh-sdk publishes on a module's behalf (the announcement's `states` on + `mesh.mod..event.states`, found by the callers of its subject builders); each with the fields of its body + as the emitting code builds it, by file and line (ADR 0670 §4). *Why:* the operator, 2026-11-11: "only the indexer + uses the manifest to build the module catalog". 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: 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 + such a token (ADR 0259 §3, §5). The list is the module catalog's (§21); the review reads no bus. 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.** §21's list also names every event kept in a module's own stream (`mesh.stream..event.`, ADR 0363 §2), the seat holders' events published there among them, and @@ -266,17 +268,12 @@ that holds its mark reach the machines together. 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 +## Nothing built 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. +31. **No tool is built ahead of the group.** The extension of the nats module's `nats_streams` this line held, for + §22's bus read, is not built: the secrets review reads the module catalog alone (§21, §22). *Why:* the operator, + 2026-11-11: "only the indexer uses the manifest to build the module catalog". *How it is checked:* the milestone's + prepare names no member outside the group. ## A marked event waits for the operator's warrant @@ -307,9 +304,9 @@ approves, for a marked event or a restricted stream. events, following the running version as that line says. A mark added while a wait waits applies from the next call, which that call's answer says. *Why:* ADR 0286 §5 had the mark issued in a membership; no controller issues one now, a membership names no event (ADR - 0670 §2), and the judged manifest on the bus keeps the mark out of any bundle as §5 required (the operator, - 2026-11-11: the mark read from the manifests on the bus); from G the catalog half is where the tool runner reads - which modules exist (design 47 G §196). + 0670 §2), and the catalog half, which the indexer alone builds from the manifests, keeps the mark out of any bundle + as §5 required; from G the catalog half is where the tool runner reads which modules exist (design 47 G §196), and + no part but the indexer reads a manifest (the operator, 2026-11-11). 34. **Which wait is marked.** A wait is marked when any subject it subscribes (§13, §26, after `from`) overlaps a marked subject of §33, that is, some subject matches both, a wildcard on either side. mesh-sdk's `events.go` (§1) gains `Overlaps(a, b)` for it. Before the catalog half is read (`mesh_first_views`), a wait with any subject diff --git a/03-DESIGN/01-to-be/46-milestones/7-approval-mark.md b/03-DESIGN/01-to-be/46-milestones/7-approval-mark.md index 9fd4e856..396ad4d8 100644 --- a/03-DESIGN/01-to-be/46-milestones/7-approval-mark.md +++ b/03-DESIGN/01-to-be/46-milestones/7-approval-mark.md @@ -95,7 +95,9 @@ file; a node where the file is readable beyond the operator's account is a findi ## Where the marks are read, and where they are withheld 5. **From the catalog half on the bus, never from a bundle.** The indexer's catalog graph entry of a module (design 47 - G §174) gains its `needs-approval` and, for each stream it declares, whether the stream carries a `grant`; the seat + G §174) gains its `needs-approval`, its `emits`, and for each stream it declares its events and whether it carries a + `grant`; no part but the indexer reads a manifest (the operator, 2026-11-11: "only the indexer uses the manifest to + build the module catalog"); the seat definitions of the catalog half carry the verb marks (§2). The tool runner, which from G takes its first view of the catalog half by `mesh-catalog.revision` and follows `catalog-revision` (design 47 G §196), derives from it, for each module it serves, its marked tools and verbs, in a package of its own, `node-tools/internal/approval`, again on @@ -113,7 +115,8 @@ file; a node where the file is readable beyond the operator's account is a findi (design 47 G §194). The grants part, composing a runtime's account, reads that runtime's node's readings: where the tool runner does not state `approval-mark/1`, where the node has no readings, or where its readings are older than the tool runner's version on that node (failing closed as §19), it composes a subscribe deny of every marked - subject of every module the runtime carries: `mesh.mod..tool.` and the same followed by `.*`; the + subject of every module the runtime carries, the marks read from the catalog half as §5 has them: + `mesh.mod..tool.` and the same followed by `.*`; the caller-named subject mesh-sdk's `process.Call` sends on first, `mesh.mod..call..>`; and for a marked verb `mesh.seat..tool.`, the same followed by `.`, and `mesh.seat..call...>`. The bus's deny outranks its allow of `mesh.mod..tool.>` for each. The tool runner's version on a node is read from the @@ -247,7 +250,7 @@ file; a node where the file is readable beyond the operator's account is a findi 18. **The tools read and steer what was asked.** The mesh MCP server on each machine gains the tool `mesh_approvals`: with no argument, the calls asked on that machine in the last day, newest first, each with its state and fingerprint, read from §13's state, and the marks it applies, each module's marked tools and verbs with their - source (its manifest or its seat's definition) and the catalog revision read; given an ask's id, its whole + source (its module's entry in the catalog half or its seat's definition) and the catalog revision read; given an ask's id, its whole arguments and the act's digest; given `cancel` and an ask's id, it takes that open ask back (`Client.Cancel`), recorded first in the hand-act log through `mesh-hand-acts.hand-act` with who and why, and refused when the record cannot be written. `mesh_describe` answers, for a marked tool or verb, `needs-approval` with its source. *Why:*