node-tools: serve mesh/state.history (ADR 0307, issue 502) #29

Merged
mesh-admin merged 1 commits from adr-0307-state-history into main 2026-10-12 08:24:20 +00:00
Contributor

Implements the runtime part of novox/hq ADR 0307 (the runtime serves a key's kept values, oldest first, to whoever may read the bucket). The issue tracker needs it to carry its bucket's kept values into its log, for issue 502 (the audit trail lasts only 7 days).

What changes

  • bus.Conn.StateHistory sits next to StateGet in internal/bus/state.go. It reads the bucket with jetstream.KeyValue.History, which is the same ordered watch StateWatch already uses, so the runtime needs no new bus grant. The access check is the same as for get, through issuedState: the owner and every reader are served, and a module not issued the state is refused with the reason.
  • The answer is a JSON array, oldest first, of {key, value, revision, op, at}. op is put or delete, and a purge also reads delete. value is omitted for a delete. at is RFC 3339. A key the bucket holds nothing for answers [].
  • It is routed as mesh/state.history in runtime.moduleBus.State and in launch. The other mesh/state.* verbs are unchanged.
  • meshtest.Mesh.BucketKeeping creates a bucket that keeps more than one value per key, for tests.

How it is checked

internal/runtime/state_history_test.go runs against a bus of its own, as ADR 0307 says:

  • three puts and a delete on one key of a bucket keeping 8 values: the owner and a reader each read all four, oldest first, with revision, op and RFC 3339 time
  • an unknown key answers [] on the wire
  • reading writes nothing: the key stays deleted and its history is unchanged
  • a module not issued the state is refused with the reason

Both tests are added to merge-check.sh's runtimeless list, so they run where node is absent. sh merge-check.sh passes locally.

Implements the runtime part of novox/hq ADR 0307 (the runtime serves a key's kept values, oldest first, to whoever may read the bucket). The issue tracker needs it to carry its bucket's kept values into its log, for issue 502 (the audit trail lasts only 7 days). ## What changes - `bus.Conn.StateHistory` sits next to `StateGet` in `internal/bus/state.go`. It reads the bucket with `jetstream.KeyValue.History`, which is the same ordered watch `StateWatch` already uses, so the runtime needs no new bus grant. The access check is the same as for `get`, through `issuedState`: the owner and every reader are served, and a module not issued the state is refused with the reason. - The answer is a JSON array, oldest first, of `{key, value, revision, op, at}`. `op` is `put` or `delete`, and a purge also reads `delete`. `value` is omitted for a delete. `at` is RFC 3339. A key the bucket holds nothing for answers `[]`. - It is routed as `mesh/state.history` in `runtime.moduleBus.State` and in `launch`. The other `mesh/state.*` verbs are unchanged. - `meshtest.Mesh.BucketKeeping` creates a bucket that keeps more than one value per key, for tests. ## How it is checked `internal/runtime/state_history_test.go` runs against a bus of its own, as ADR 0307 says: - three puts and a delete on one key of a bucket keeping 8 values: the owner and a reader each read all four, oldest first, with revision, op and RFC 3339 time - an unknown key answers `[]` on the wire - reading writes nothing: the key stays deleted and its history is unchanged - a module not issued the state is refused with the reason Both tests are added to merge-check.sh's runtimeless list, so they run where node is absent. `sh merge-check.sh` passes locally.
mesh-admin added 1 commit 2026-10-12 08:18:44 +00:00
Serve a key's kept values so the issue tracker can carry them into its log (ADR 0307, issue 502)
mesh/delivery delivered
mesh/merge-gate pass: builds mesh-tools, node-tools → ace, g14, novox, shanks; no bus step; every machine composes with the change as it did without (4 of …
mesh/repo-check pass: THE CHANGE ALTERS ITS OWN CHECK (merge-check.sh): main's version judged it; the change's judges the pull requests after it merges; it…
mesh/delivery-group group adr-0307-state-history merged: every member is merged
3f0c1a6cec
mesh/state.history answers every value a bucket still keeps for a key,
oldest first, to whoever may get it, by the same watch the runtime already
uses, so no new grant is needed.
Author
Contributor

Delivery novox/mesh-tools@3f0c1a6cec18 — delivered since 2026-10-12T08:29:47Z

Delivery plan — builds mesh-tools, node-tools → ace, g14, novox, shanks; no bus step

  • tier 0: mesh-tools, node-tools
  • ace: receives node-tools
  • g14: receives node-tools
  • novox: receives node-tools
  • shanks: receives node-tools
  • node-tools provides mcp-endpoint: its consumers are sent again after it
  • grants step: if this changes what the bus's user list says (a new tool, subject or user), novox is sent that list alone, every build there kept, before node-tools is judged on its first machine

Group adr-0307-state-history, in order: novox/mesh-sdk@d41d255f28 → novox/mesh-tools@3f0c1a6cec

Machines

  • mesh-tools on every machine running it: sent
  • node-tools on ace: passed — healthy 3 times over 2m23s
  • node-tools on the rest running it: sent

Transitions

  • 2026-10-12 08:19 (new) → proposed (announced): novox/mesh-tools#29's head announced
  • 2026-10-12 08:21 proposed → checked (checked): the verdict names this commit
  • 2026-10-12 08:21 checked → ready (accepted): the gate passed or warned, and the repository's own check did not fail
  • 2026-10-12 08:26 ready → published (merged): on the trunk its modules follow: merged there, and its walk opened — or nothing for a walk to move
  • 2026-10-12 08:26 published → delivering (go): its walk started: let go by this owner in its group's order, by a person, or on the controller's own path — not a failed walk that carried a later commit for it, after which it waits for a walk of its own commit
  • 2026-10-12 08:29 delivering → delivered (done): its walk is done, carrying its own commit: every machine of its deploy plan passed, or was left as its policy says

The commit's note under refs/notes/mesh-plan keeps every transition: git log --notes=mesh-plan.

<!-- mesh-delivery:view --> **Delivery** `novox/mesh-tools@3f0c1a6cec18` — **delivered** since 2026-10-12T08:29:47Z **Delivery plan** — builds mesh-tools, node-tools → ace, g14, novox, shanks; no bus step - tier 0: mesh-tools, node-tools - ace: receives node-tools - g14: receives node-tools - novox: receives node-tools - shanks: receives node-tools - node-tools provides mcp-endpoint: its consumers are sent again after it - grants step: if this changes what the bus's user list says (a new tool, subject or user), novox is sent that list alone, every build there kept, before node-tools is judged on its first machine **Group** `adr-0307-state-history`, in order: novox/mesh-sdk@d41d255f28ad → novox/mesh-tools@3f0c1a6cec18 **Machines** - mesh-tools on every machine running it: sent - node-tools on ace: passed — healthy 3 times over 2m23s - node-tools on the rest running it: sent **Transitions** - 2026-10-12 08:19 (new) → proposed (announced): novox/mesh-tools#29's head announced - 2026-10-12 08:21 proposed → checked (checked): the verdict names this commit - 2026-10-12 08:21 checked → ready (accepted): the gate passed or warned, and the repository's own check did not fail - 2026-10-12 08:26 ready → published (merged): on the trunk its modules follow: merged there, and its walk opened — or nothing for a walk to move - 2026-10-12 08:26 published → delivering (go): its walk started: let go by this owner in its group's order, by a person, or on the controller's own path — not a failed walk that carried a later commit for it, after which it waits for a walk of its own commit - 2026-10-12 08:29 delivering → delivered (done): its walk is done, carrying its own commit: every machine of its deploy plan passed, or was left as its policy says The commit's note under `refs/notes/mesh-plan` keeps every transition: `git log --notes=mesh-plan`.
Author
Contributor

Review (independent): APPROVE of the code at 3f0c1a6cec, checked against ADR 0307. (The forge refuses an APPROVED review from a tool under ADR 0266, so this is a comment.) The required checks were not green when I read them, so this approval is not a merge clearance until they are: mesh/merge-gate pending 'building on ace since 10:19', mesh/repo-check missing (no status yet).

  1. Wire: pass. StateHistory (bus/state.go) answers an array, oldest first, of {key, value, revision, op, at}. op is 'put' only for KeyValuePut; delete and purge both read 'delete'. A delete's value is omitted (omitempty on a nil RawMessage). An unknown key answers [] on the wire, because ErrKeyNotFound maps to an empty slice (asserted at state_history_test.go:130).
  2. Access is exactly as get: pass. StateHistory runs the same issuedState and checkKey as StateGet and does not use writable, so the owner and readers are served it and anyone else is refused with the same reason. Tested for the owner, for a reader under 'issues.issues', and for a module issued nothing (state_history_test.go:92-121, 136-151).
  3. Writes nothing: pass. kv.History is a watch with IncludeHistory and no write. The test shows get is still null and the history unchanged after reading it (state_history_test.go:122-128).
  4. Grants: pass, by reading the code. In nats.go v1.54.0, jetstream kv.History (kv.go:1499) calls kv.Watch, the same ordered-consumer path StateWatch and StateKeys (ListKeys) already use. mesh-controller internal/broker/state.go stateGrants gives owner and reader alike STREAM.INFO, CONSUMER.CREATE..> (or the one-key filter form for per-machine state), CONSUMER.DELETE and $JS.FC. No new grant is needed.
  5. Other verbs unchanged: pass. The bus/state.go diff only adds lines; launch.go only adds the method to the existing state case; runtime.go only adds a history case and rewrites a comment.
  6. I ran merge-check.sh locally and it passed (all packages ok, race-checked). Both history tests passed when run verbosely.

Non-blocking findings:
(a) The runtime tests connect without the restricted runtime credential, so item 4 is shown by reading code, not by a test. A test under stateGrants permissions would prove it.
(b) The comment on moduleBus.State in runtime.go now runs past the line width.

Review (independent): APPROVE of the code at 3f0c1a6cec18523cfc601a42729ece7b7b3a8d97, checked against ADR 0307. (The forge refuses an APPROVED review from a tool under ADR 0266, so this is a comment.) The required checks were not green when I read them, so this approval is not a merge clearance until they are: mesh/merge-gate pending 'building on ace since 10:19', mesh/repo-check missing (no status yet). 1. Wire: pass. StateHistory (bus/state.go) answers an array, oldest first, of {key, value, revision, op, at}. op is 'put' only for KeyValuePut; delete and purge both read 'delete'. A delete's value is omitted (omitempty on a nil RawMessage). An unknown key answers [] on the wire, because ErrKeyNotFound maps to an empty slice (asserted at state_history_test.go:130). 2. Access is exactly as get: pass. StateHistory runs the same issuedState and checkKey as StateGet and does not use writable, so the owner and readers are served it and anyone else is refused with the same reason. Tested for the owner, for a reader under 'issues.issues', and for a module issued nothing (state_history_test.go:92-121, 136-151). 3. Writes nothing: pass. kv.History is a watch with IncludeHistory and no write. The test shows get is still null and the history unchanged after reading it (state_history_test.go:122-128). 4. Grants: pass, by reading the code. In nats.go v1.54.0, jetstream kv.History (kv.go:1499) calls kv.Watch, the same ordered-consumer path StateWatch and StateKeys (ListKeys) already use. mesh-controller internal/broker/state.go stateGrants gives owner and reader alike STREAM.INFO, CONSUMER.CREATE.<stream>.> (or the one-key filter form for per-machine state), CONSUMER.DELETE and $JS.FC. No new grant is needed. 5. Other verbs unchanged: pass. The bus/state.go diff only adds lines; launch.go only adds the method to the existing state case; runtime.go only adds a history case and rewrites a comment. 6. I ran merge-check.sh locally and it passed (all packages ok, race-checked). Both history tests passed when run verbosely. Non-blocking findings: (a) The runtime tests connect without the restricted runtime credential, so item 4 is shown by reading code, not by a test. A test under stateGrants permissions would prove it. (b) The comment on moduleBus.State in runtime.go now runs past the line width.
Author
Contributor

Merge check at 3f0c1a6c

  • mesh/merge-gate: PASS — every machine composes with the change as it did without (4 of 4 compose) (modules: mesh-tools, node-tools)
  • mesh/repo-check: PASS — THE CHANGE ALTERS ITS OWN CHECK (merge-check.sh): main's version judged it; the change's judges the pull requests after it merges; its merge-check.sh passed

Delivery plan — builds mesh-tools, node-tools → ace, g14, novox, shanks; no bus step

  • tier 0: mesh-tools, node-tools
  • ace: receives node-tools
  • g14: receives node-tools
  • novox: receives node-tools
  • shanks: receives node-tools
  • node-tools provides mcp-endpoint: its consumers are sent again after it
  • grants step: if this changes what the bus's user list says (a new tool, subject or user), novox is sent that list alone, every build there kept, before node-tools is judged on its first machine

Run by the build seat on ace as build-1791793154801694444 (builds --log build-1791793154801694444).

--- the gate: mesh-tools, node-tools
mesh-tools: ok
node-tools: ok, invokes every tool
long-running resources without health: 0
files asking for a setting without saying whether it is trusted: 0
2 manifest(s) checked. Judged against the seats this binary carries; a claim on one of the mesh's own seats is judged fully at registration, and a seat declared by a module not given here reads as unknown. Identities judged on a 6-character machine name, against the bounds of the providers given here
judging 0 module(s) changed against 4 machine(s), as the snapshot of 2026-10-12T00:55:24Z says they run
composing every machine as the mesh is
the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued
the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued
composing every machine with the change
the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued
the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued
merge gate: PASS — every machine composes with the change as it did without (4 of 4 compose)
judged by controller development build against the facts of 2026-10-12T00:55:24Z

machines:
  - a machine (f35): composes
  - holds mesh-dns-resolver (idt): composes
  - holds git, holds mesh-artifact-store, holds mesh-broker, holds mesh-catalog, holds mesh-delivery, holds mesh-dns-resolver, holds mesh-store, holds mesh-vault, holds npm-package-registry, the control node, the hub (ygcyr): composes
  - a machine (yvbpsm): composes

a merge would rebuild 2 module(s) in 1 tier(s): mesh-tools, node-tools
--- THE CHANGE ALTERS ITS OWN CHECK (merge-check.sh): main's version judged it; the change's judges the pull requests after it merges
--- its merge-check.sh (go toolchain)
NOT TESTED HERE: internal/runtime and internal/console launch bundles that need node and @novox/mesh-sdk
?   	github.com/novox/mesh-tools/node-tools/cmd/node-tools	[no test files]
ok  	github.com/novox/mesh-tools/node-tools/internal/alive	1.195s
ok  	github.com/novox/mesh-tools/node-tools/internal/announce	4.380s
ok  	github.com/novox/mesh-tools/node-tools/internal/bus	12.542s
ok  	github.com/novox/mesh-tools/node-tools/internal/launch	1.106s
ok  	github.com/novox/mesh-tools/node-tools/internal/meshtest	1.146s
?   	github.com/novox/mesh-tools/node-tools/internal/wire	[no test files]
ok  	github.com/novox/mesh-tools/node-tools/internal/console	0.006s
ok  	github.com/novox/mesh-tools/node-tools/internal/runtime	3.013s
NOT TESTED HERE: node-tools/src (TypeScript) needs @novox/mesh-sdk from the package registry
**Merge check** at `3f0c1a6c` - `mesh/merge-gate`: **PASS** — every machine composes with the change as it did without (4 of 4 compose) (modules: mesh-tools, node-tools) - `mesh/repo-check`: **PASS** — THE CHANGE ALTERS ITS OWN CHECK (merge-check.sh): main's version judged it; the change's judges the pull requests after it merges; its merge-check.sh passed **Delivery plan** — builds mesh-tools, node-tools → ace, g14, novox, shanks; no bus step - tier 0: mesh-tools, node-tools - ace: receives node-tools - g14: receives node-tools - novox: receives node-tools - shanks: receives node-tools - node-tools provides mcp-endpoint: its consumers are sent again after it - grants step: if this changes what the bus's user list says (a new tool, subject or user), novox is sent that list alone, every build there kept, before node-tools is judged on its first machine Run by the build seat on ace as `build-1791793154801694444` (`builds --log build-1791793154801694444`). ``` --- the gate: mesh-tools, node-tools mesh-tools: ok node-tools: ok, invokes every tool long-running resources without health: 0 files asking for a setting without saying whether it is trusted: 0 2 manifest(s) checked. Judged against the seats this binary carries; a claim on one of the mesh's own seats is judged fully at registration, and a seat declared by a module not given here reads as unknown. Identities judged on a 6-character machine name, against the bounds of the providers given here judging 0 module(s) changed against 4 machine(s), as the snapshot of 2026-10-12T00:55:24Z says they run composing every machine as the mesh is the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued composing every machine with the change the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued merge gate: PASS — every machine composes with the change as it did without (4 of 4 compose) judged by controller development build against the facts of 2026-10-12T00:55:24Z machines: - a machine (f35): composes - holds mesh-dns-resolver (idt): composes - holds git, holds mesh-artifact-store, holds mesh-broker, holds mesh-catalog, holds mesh-delivery, holds mesh-dns-resolver, holds mesh-store, holds mesh-vault, holds npm-package-registry, the control node, the hub (ygcyr): composes - a machine (yvbpsm): composes a merge would rebuild 2 module(s) in 1 tier(s): mesh-tools, node-tools --- THE CHANGE ALTERS ITS OWN CHECK (merge-check.sh): main's version judged it; the change's judges the pull requests after it merges --- its merge-check.sh (go toolchain) NOT TESTED HERE: internal/runtime and internal/console launch bundles that need node and @novox/mesh-sdk ? github.com/novox/mesh-tools/node-tools/cmd/node-tools [no test files] ok github.com/novox/mesh-tools/node-tools/internal/alive 1.195s ok github.com/novox/mesh-tools/node-tools/internal/announce 4.380s ok github.com/novox/mesh-tools/node-tools/internal/bus 12.542s ok github.com/novox/mesh-tools/node-tools/internal/launch 1.106s ok github.com/novox/mesh-tools/node-tools/internal/meshtest 1.146s ? github.com/novox/mesh-tools/node-tools/internal/wire [no test files] ok github.com/novox/mesh-tools/node-tools/internal/console 0.006s ok github.com/novox/mesh-tools/node-tools/internal/runtime 3.013s NOT TESTED HERE: node-tools/src (TypeScript) needs @novox/mesh-sdk from the package registry ```
mesh-admin merged commit 172b5af589 into main 2026-10-12 08:24:20 +00:00
mesh-admin deleted branch adr-0307-state-history 2026-10-12 08:24:20 +00:00
Sign in to join this conversation.
No Reviewers
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: novox/mesh-tools#29