Author SHA1 Message Date
jschoubben 006a6d7eb7 Carry the findings bridge to the indexer: #12's merged message was lost while G's forge bridge crash-looped
mesh/delivery ready: it is merged on the Approve
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 16:43:18 +01:00
jschoubben 20b06dbcd3 Merge pull request 'Bridge for G's builds: an empty meshconditionsclient/findings package' (#12) from fix/47-G-bridge-findings into main
Reviewed-on: #12
2026-11-13 14:48:02 +00:00
jschoubben 8e722a68c9 Bridge for G's builds: an empty meshconditionsclient/findings package
mesh/delivery merged: source.main moved to novox/mesh-contracts@20b06dbcd32e
The modules whose last build before G imported meshconditionsclient/findings (the assigner, builder, checker, indexer,
teller, view, watchman) get a fingerprint on the version line while that package is unpublished, so their build asks
name no mesh-sdk commit and fetch pre-G mesh-sdk; they fail and never record new imports (2026-11-13, indexer journal
'no published package holds .../meshconditionsclient/findings'). An empty package is published again; it goes once
those modules have built under G.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 15:38:36 +01:00
mesh-tools b3a6d17c08 Merge pull request 'Milestone 47 G: mesh-contracts's part of the one release' (#11) from feat/47-G-join12 into main 2026-11-13 13:08:48 +00:00
jschoubben ef1fe33a9d T5: the enrolment client test names a role, laptop-login, not a node
mesh/delivery merged: source.main moved to novox/mesh-contracts@b3a6d17c0800
mesh/delivery-group group feat/47-G-join12 merged: every member is merged
mesh/check failed (2): mesh-delivery-checker: no published of the tagged version of go-meshconditions of me…; and 1 more | ef1fe33a9da5 on 20b06dbcd32e
Builds: design 47 G (review round 2 finding T5)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 23:27:49 +01:00
jschoubben 5e95cbed59 A-316: the assigner's candidate gains added, the version and parts the want it would write carries
The state candidates' value (CandidatesByProposalNodeValue) gains `added`, by module name, each an AddedModule
with `version` and `parts` in the want's own forms. It is a copy of the two properties of the seat mesh-wants'
state wants, because the seat-definition format cannot reuse another repository's seat's forms (includes take only
parts/ of the same repository, and a part holds no state value); a fixture holds both to the want's wire.
Regenerated with seatgen. The node names the first round-2 pass left in fixtures lines equal to base lines are
role names now, the generated tests with them.

Builds: design 47 G A-316 (corrected, hq #594), §626
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 22:48:01 +01:00
jschoubben 821d611530 Round 2 T1, T2, T5: the contracts end G with no more tests than at their merge base; fixtures name roles
The test that read every fixture for the operator's account and a node goes (T1); the tests G added
fold into existing ones as subtests, so each module counts its merge base (design 47 G §626, A-306);
node names in the lines G adds are role names (T5).

Builds: design 47 G §626, A-306; review round 2 findings T1, T2, T5
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 22:18:04 +01:00
jschoubben 5cb77ce69f Merge origin/main into the join: node-files list says a place a secret is kept
Brings mesh-contracts #9 (issue 1409): the node-files list verb's text. No conflict.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 17:01:44 +01:00
mesh-tools e6e90f1bd0 Merge pull request 'node-files: list lists a place a secret is kept, its entries never their content (issue 1409)' (#9) from fix/1409-list-secret-place into main 2026-11-12 15:28:25 +00:00
jschoubben 31e84ba67c mesh-contracts: node-files list text says a place a secret is kept is listed, marked secret-place
mesh/delivery merged: source.main moved to novox/mesh-contracts@e6e90f1bd049
mesh/delivery-group group fix/1409-list-secret-place merged: every member is merged
mesh/check checking 31e84ba67cac on e6e90f1bd049 | novox/mesh-contracts#9 in group fix/1409-list-secret-place
Issue 1409. One line of text; no verb or field changes.

Builds: design 39 parts D3 (§15), bullet 4
2026-11-12 15:45:02 +01:00
jschoubben 181dd3263d G A-230: the seat mesh-recovery's restore point says names, the bus names it took
Point gains names, one per bus object as Aside's (required, at least one), regenerated with seatgen; the kept-points
fixture names its point's bus name, so the fixture test fails without the field.

Builds: design 47 G A-230, §554, §565

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 11:35:10 +01:00
jschoubben 622adcc26c Join 11: merge main (mesh-contracts #8, the engine reads' heard event) 2026-11-12 11:29:23 +01:00
mesh-tools 0e12819cc7 Merge pull request 'enginereads: a reads statement older than a heard reads-changed does not stand (issue 1975)' (#8) from fix/engine-reads-and-compositions into main 2026-11-12 10:23:26 +00:00
jschoubben 04c6a1eead enginereads: the event heard is kept in the node's statement (issue 1975 note 6)
mesh/delivery merged: source.main moved to novox/mesh-contracts@0e12819cc727
mesh/delivery-group group fix/engine-reads-and-compositions merged: every member is merged
mesh/check checking 04c6a1eead98 on 0e12819cc727 | novox/mesh-contracts#8 in group fix/engine-reads-and-compositions
Builds: issue 1975 note 6 (the lead's review round 1; no design line). The engine 'not yet' half is dropped there.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 11:00:33 +01:00
jschoubben e575659187 enginereads: a statement older than an event heard does not stand (issue 1975)
Builds: issue 1975 note 4 (the lead's handover; no design line)
2026-11-12 10:46:28 +01:00
jschoubben 76d716e021 Merge remote-tracking branch 'origin/main' into feat/47-G-join11 2026-11-12 10:25:48 +01:00
jschoubben 8aa6de9776 Merge branch 'feat/47-G-fix11-a3h' into feat/47-G-join11 2026-11-12 10:25:41 +01:00
jschoubben 62e31e2451 Merge branch 'feat/47-G-fix11-b4b' into feat/47-G-join11 2026-11-12 10:25:41 +01:00
jschoubben bd4d38556c Merge branch 'feat/47-G-fix11-a7' into feat/47-G-join11 2026-11-12 10:25:41 +01:00
jschoubben 886be5cca7 A3h item 2b: NewGateChannel is the gate's operator channel over a process connection
It asks and cancels as accepted kinds of the seat operator-channel through the connection's Accept, and reads the router's
record by a get in the seat holder's state asks, never through a bucket named in code.

Builds: design 47 G §677, §700; lead answers A-272, A-273

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 10:23:22 +01:00
mesh-tools 6a914b1d17 Merge pull request 'node-service-manager: the verb kernel-log reads a node's kernel log, this boot or an earlier one (issue 1975)' (#7) from fix/1975-kernel-log into main 2026-11-12 08:40:39 +00:00
jschoubben dbb197b0c7 AM-H1 contract: the node-engine's composition answer names the withheld subjects
A session reads in one composition why a marked tool is not served on a node,
or that the grants part did not answer.

Builds: design 46 7 §6 (the node-engine's composition of the module names the withheld subjects; "withheld unknown: the grants part does not answer"), lead answer A-239 (withheld, withheld-unknown)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 06:26:10 +01:00
jschoubben 1d3f24250c A3e item 1: operatorchannelclient implements the gate's channel and re-exports its Kept
Builds: design 47 G §677, §700, lead answers A-219, A-224, A-228

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 06:25:56 +01:00
jschoubben 33d9b28869 A3d item 1: operatorchannelclient re-exports mesh-sdk's act and its digest, one form
Builds: design 47 G §677, lead answers A-198, A-219

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 06:09:18 +01:00
jschoubben ff63be3028 AM-D3/AM-H1 path: the node's record carries the runner's reading; mesh-grants gains withheld
The grants part must tell a reading of the running tool runner from an older
one, and the node-engine's composition reads the withheld subjects through a
verb of the seat, never the grants part's state.

Builds: design 46 7 §6 (the node's record takes the runner's capabilities and fingerprint; the seat mesh-grants' verb withheld, class read, callers the node-engine, persons and the operator, input node, with a fixture), lead answer A-203 (runner-capabilities, runner-fingerprint; withheld's input and answer)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 06:04:56 +01:00
jschoubben 49e26f5d27 Kept: the operator-channel client keeps an asked call's act, arguments and recorded mark
An asker that asks for a call (the tool runner's approval gate) keeps beside the ask the
act its options bind, the call's whole arguments, and whether its run is in the hand-act
log; Take keeps all three as it marks the ask.

Builds: design 46 7-approval-mark §13

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 05:00:12 +01:00
jschoubben 6be23459ab A7: the contracts' fixtures and the tests generated from them name no operator account and no workstation (role names)
Builds: the lead's handover item A7 (fixtures name no operator account or node); no design line names it
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 04:59:34 +01:00
jschoubben 74c157284f Merge branch 'feat/47-G-fix9-recovery' into feat/47-G-join10 2026-11-12 02:39:12 +01:00
jschoubben c4adc618c8 node-service-manager: kernel-log is built on the issue's prepare record (issue 1975)
mesh/delivery merged: source.main moved to novox/mesh-contracts@6a914b1d1747
mesh/delivery-group group fix/1975-kernel-log merged: every member is merged
mesh/check being carried to c4adc618c874 on 6a914b1d1747 | from 29ec1c3df312, mesh-catalog d9f2b7bcfa07
No file change: this commit only names what the first commit builds, as the review asked.

Builds: issue 1975 note 2: lead answers L1-L3 (the verb kernel-log, its boot argument, no scope and no unit), acceptance 1975/AC1-AC5

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 02:24:44 +01:00
jschoubben cdb80ca4d3 node-service-manager: the kernel-log verb beside journal (issue 1975)
The kernel's messages of this boot or an earlier one (boot 0, -1, ...), in a window, narrowed to a
priority and a text, at most 2000 lines, the journal's argument forms; replaces journalctl -k,
journalctl -k -b -1 and dmesg. seatgen -check is clean.

Builds: issue 1975, the operator's request of 2026-11-12 (the lead's handover; no design line names the verb)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 02:17:28 +01:00
jschoubben 5503882d55 Merge origin/main (licence-put, issue 1409) into feat/47-G-join9
The vault's seat definition keeps retire's class act (G) beside main's licence-put; the
TypeScript contract is regenerated with join 9's seatgen (seatgen -check clean).

Builds: design 47 G §610

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 01:46:17 +01:00
jschoubben 630de8babc G A-129: the seat mesh-recovery's kept-points answers unrestored
The asides whose record ended at removed with no running act holding them, which the recovery
module's health check fails on, are listed in the answer the tool and the check read.

Builds: design 47 G A-129, §554, §657

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 01:29:07 +01:00
jschoubben e3520750d5 G A-124: the seat mesh-recovery's aside says names, a list of the bus names it was live under
Builds: design 47 G A-124, §516, §560

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 01:17:22 +01:00
mesh-tools 29ec1c3df3 Merge pull request 'The vault's seat gains licence-put, so the licence manager keeps its grants in the vault (issue 1409)' (#6) from feat/39-licence-switch into main 2026-11-12 00:13:01 +00:00
jschoubben b58c4e6b14 G A-117: the seat mesh-recovery's ended and restored events gain why, the hand act's words for a cancel
Builds: design 47 G A-117, §560
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 01:06:05 +01:00
jschoubben 30389b2ed9 Merge branch 'feat/47-G-recover-host-contracts' into feat/47-G-join8 2026-11-12 00:11:50 +01:00
jschoubben ed8914974f Merge branch 'feat/47-G-recover-runner' into feat/47-G-join8 2026-11-12 00:11:50 +01:00
jschoubben 97b5f9684e Merge branch 'feat/47-G-placement6' into feat/47-G-join8 2026-11-12 00:11:50 +01:00
jschoubben 8f70f1c5ee Merge branch 'feat/47-G-cond6' into feat/47-G-join8 2026-11-12 00:11:50 +01:00
jschoubben 2ae0c67930 G A-92: the node-engine's seat definition gains the state bounds, key <what>.<id>, in its old section
Builds: design 47 G §560, §557, §627, A-77, A-92

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:44:36 +01:00
jschoubben e5b3a89430 A-91: the operator-channel contract's asks value carries the ask's warrant
Builds: design 47 G §700, A-91; the router's record carries its warrant

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:27:37 +01:00
jschoubben 3eba6b8299 V-1/B1: the vault's seat definition gains licence-put
mesh/delivery merged: source.main moved to novox/mesh-contracts@29ec1c3df312
mesh/delivery-group group feat/39-licence-switch merged: every member is merged
mesh/check checking 3eba6b8299e0 on 29ec1c3df312 | novox/mesh-contracts#6 in group feat/39-licence-switch
The licence manager hands the vault a licence's grant and access token through a verb of
the seat mesh-vault; the manifest validator refuses a seat verb the definition does not
serve, so the definition carries it, and the generated Go and TypeScript follow.

Builds: design 39 bus-and-switch §15, B1, B4, B5

Claude-Session: https://claude.ai/code/session_01NcbgfHb9d4T9nq5Q6WqdiJ
2026-11-11 23:07:44 +01:00
jschoubben b0be30c267 Contract: the seat mesh-module-assigner gains the read verb placement
Builds: design 47 G A-62 (§704, §402)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 22:58:13 +01:00
jschoubben c5cf0126f9 K27 (owner change): the seat mesh-conditions' condition-changed gains the change value owner
Builds: design 47 G §540, §685, A-58 (findings-stated's kinds, §580, and attempt-changed, §541/§665, were built by K13 and K12; seatgen -check clean)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 22:46:44 +01:00
jschoubben cf5590c759 bus5 K27 (§681): mesh-broker's snapshot-get, snapshot-restore, snapshot-restore-cancel, snapshot-remove and snapshot-restored; the format's verb word chunks
Builds: design 47 G §681, §691, A-44
2026-11-11 22:37:57 +01:00
jschoubben 3658ceb1b6 K26 (D-34): the definition format takes a state's view field, and the assigner's assignments and seat-holders carry it
Builds: design 47 G §699 (§616; ADR 0571 §6)

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 21:36:41 +01:00
jschoubben 78e61c9437 K25 (D-33): the node-engine's first-views answers entries and wants, and the seat gains entry-again
Builds: design 47 G §698 (§683, §422)

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 21:36:34 +01:00
jschoubben b76e52d30a K24 (mesh-recovery's hand verbs): take, restore, retry, aside, discard-aside and expire-points, asker and why on every hand verb, one answer form with cancel
Builds: design 47 G §682, §691 (§516, §554, §566, §656, §681)

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 20:45:56 +01:00
jschoubben 0ccac1d42a K11 (no named callers): no seat definition names a callers, and the verbs that had one keep their class
Every verb takes its class's default (read: invokers, persons, sessions; act and warrant: operator, sessions, invokers); resync and
retire, which named a caller beside the operator or a seat, are of class act.

Builds: design 47 G §610 (§391, §392, §394, §405, §555, §554, §659, §681, §393, §422, §579)

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 20:45:23 +01:00
jschoubben bd038b15a3 K23 (owner and waiting-on of a condition): the seat mesh-conditions' condition and its events carry them
Builds: design 47 G §685 (§451, §540, §678)

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 20:44:03 +01:00
jschoubben b2cc72b4a3 K22 (finding helpers gone): meshconditionsclient keeps what concerns conditions, and heard builds the seat's generated finding
The helpers CheckFinding, FindingFor, FindingWriter, FindingState, FindingVersion, Observation, EncodeFinding, DecodeFinding, Says,
FindingBucket, FindingsBucket, Raise, Clear and CallUnanswered go; mesh-sdk's writer is the one writer and checks. Importers
outside this repository move in G's change (named in the line).

Builds: design 47 G §689 (§461, §503, §640, §660)

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 20:43:22 +01:00
jschoubben 74b6162807 K21a (regenerate, in between): the generated Go and TypeScript follow the definitions so far
The conditions developer reads kinds, attempt-changed, wait-held and wait-ended from it. K21 regenerates last. The client
meshconditionsclient does not build against the findings state's new layout until the question on it is answered.

Builds: design 47 G §341, §523, §580, §541, §499

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 20:31:55 +01:00
jschoubben 9243f8c44f K7, K8, K9 (the seat mesh-recovery): its verbs, its events and its place in the module
The seat is defined whole in scope mesh: snapshot-kept, restore-kept, kept-points, restore-aside and cancel (the verbs
of the four forms §516 gives and §566 names; take, restore, retry, aside, discard-aside and expire-points wait for D-19),
events ended, restore-started, restored, set-aside, aside-discarded, point-removed (<module>.<kept>) and expiry-ended,
each kept 90 days and last per subject but expiry-ended, which has no parts and so no last-per-subject. The four acts
that a process answers say by-caller; no verb names callers. The artifacts go-meshrecovery and ts-meshrecovery are in
module.json, the seat in seats/index.json. Generated code waits for K21; the generator reads a verb's by-caller only
once mesh-sdk's reader release (§621) knows it.

Builds: design 47 G §516, §517, §523, §551, §554, §560, §563, §566, §567, §656, §659

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 20:31:03 +01:00
jschoubben 9cefd47223 K18 (asker hears refused): Take answers Refused with the router's words for a refused ask
The ask is closed as any ended ask is, then the asker's request ends with why.

Builds: design 47 G §570, §638

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 20:31:03 +01:00
jschoubben 6beae382b3 K17 (refused said): the asks record says when an ask ended
decided already names ask, outcome refused, words and at; the record gains at beside state refused and answer.
Generated code waits for K21.

Builds: design 47 G §570, §638

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 20:31:03 +01:00
jschoubben a16cf80bd6 K19 (caps in list): mesh-broker's list answers the sum of the caps and the limits
Builds: design 47 G §661, §547

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 20:31:03 +01:00
jschoubben 86a5dcc93a K20 (adapter goes): meshconditionsclient/findings is deleted
mesh-sdk's writer is the one place a finding is written; seatgen -check is clean for health-and-repair but for the
generated code K21 writes.

Builds: design 47 G §461, §503

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 20:31:03 +01:00
jschoubben 68b0c97079 K15 (findings state): the state findings is keyed <scope>.<id>.<kind> and holds the Finding body
Builds: design 47 G §660, §461, §437, §439

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 20:31:03 +01:00
jschoubben 22911c3644 K12 (healers attempts): mesh-healers says attempt-changed, keyed by condition and attempt
attempt-changed.<condition>.<attempt>, kept last per subject, 7 days and 16 MiB, its body the attempt's value whole with
until, or removed. Generated code waits for K21.

Builds: design 47 G §541, §665

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 20:31:03 +01:00
jschoubben a5cf2c5df1 K4, K5 (node-engine waits): the seat says wait-held and wait-ended, and the have carries its wait
defs.Wait has the fields of a wait (owner, step compose or kept-build, node, on, bound, since, clock-from, words, reason)
and, in the have, ask-at and act; wait-held.<node>.<module> and wait-ended.<node>.<module> are kept last per subject on
the stream running is kept on; the have's value gains wait, waits stays. Generated code waits for K21.

Builds: design 47 G §498, §499, §541, §556, §560, §629

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 20:31:03 +01:00
jschoubben 7d730a4a75 K6 (one capabilities event): the node-engine seat says manifest-reads-changed alone
capabilities-changed and its body go, the one event of a node's stated capabilities is manifest-reads-changed, which
already carries why. Generated code waits for K21.

Builds: design 47 G §590

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 20:26:26 +01:00
jschoubben c65628de23 K1b (format): a verb may say by-caller
Builds: design 47 G §554, §621, §656

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 20:25:41 +01:00
jschoubben f4d0d58619 K14 (owner forms): a finding's owner and waiting-on are one of three forms
owner and waiting-on carry the pattern of the three forms (session who@node, a seat's name, forge:<account>) in the layout
and the state value, and the fixtures read two forms. mesh-sdk's writer is what refuses another. Generated code waits for K21.

Builds: design 47 G §678, §540, §451

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 20:24:46 +01:00
jschoubben a090a447d3 K16 (notify every channel): notify may ask a message sent on every channel
operator-channel's notify takes every-channel, which the router sends on every channel's send, as a break-glass
act is announced; the teller tells widens, recovery-merged and forge-made through it. A fixture reads the input.
Generated code waits for K21.

Builds: design 47 G §514

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 15:56:39 +01:00
jschoubben b3526b762c K13 (stated kinds): a findings statement names the kinds it states
FindingsStated gains kinds, the finding kinds the stating bundle owns; a statement deletes only keys of those kinds
and one with none covers every kind, as before. A body of bodies yields its type alone, so no fixture reads it here:
mesh-sdk's writer is what reads and tests it. Generated code waits for K21.

Builds: design 47 G §580

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 15:55:58 +01:00
jschoubben 24d58f0786 K10 (backup items): node-backup says when each item starts and ends
The seat gains item-started and item-ended on <event>.<node>.<module>.<item>, kept last per subject for 7 days,
each with at, and item-ended with outcome (done, failed or put-off), the restore's act it gave way to and an
error, so the recovery module and the backup holder each read the other's start and never overlap. The seat is
of the seat-list grain: nothing is generated and its fixtures are not read, so mesh-sdk's definition reader and
its bootstrapped copy of this file are what read it.

Builds: design 47 G §554, §555, §563, §523

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 15:54:17 +01:00
jschoubben 5e8dce621b K3 (running healthy): running says the health of the build that runs
The node-engine seat's Running gains healthy, a nullable boolean so that a false survives the wire and a running
said by a node-engine of before G, with none, is told apart and reads as healthy; stopped is said only when the
have no longer holds the module. Two fixtures read healthy true and false; the one without it still decodes.
Generated code waits for K21.

Builds: design 47 G §520

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 15:51:53 +01:00
jschoubben 3ccc3cc3cb K2 (node-engine verbs): the seat is claimed as one module, and its first views are seat verbs
The definition drops held-by-the-engine, so one module's claim of the seat is read as any other. It gains
first-views (read; any person and the healers) and first-view-again (act; the operator and the healers), not
optional, their inputs and answers those of the view's two tools mesh-sdk's runtime serves; a fixture reads
first-view-again's input. Generated code waits for K21.

Builds: design 47 G §508, §422, §204, §400

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 15:50:06 +01:00
jschoubben 37a906ed4e K1 (format): an accepted kind names its stream, and a verb naming no class is a read
The format's accepted kind gains stream (check or delivery), so the build seats' step on both streams and run on
check validate against it; the class description says a verb that names no class takes read, on main or added in
G, and that nothing refuses it.

Builds: design 47 G §455, §456

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 15:47:44 +01:00
jschoubben 2f680c661e Take out C7: node-backup's aside, discard-aside, ended and restored, and the kept, form and fingerprint arguments
G section 555: the seat node-backup gains nothing for kept data on the bus; its now and restore keep the class act (§405).

Builds: design 47 G §555, §405

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 14:40:11 +01:00
jschoubben a7ab33028f Merge origin/main (#5): mesh-broker's Binding is the wire form; restore-kept and snapshot-kept taken out, the binding names its objects
The conflicts in mesh-broker's seat.json and fixtures took origin/main's Binding (list, show and orphans answer each
binding) and the objects field of C8; C8's snapshot-kept, restore-kept, KeptPoint and Aside are not carried over as G
section 555 moves them to the seat mesh-recovery, which mesh-broker does not gain. The generated Go and TypeScript of
mesh-broker are written again by seatgen.

Builds: design 47 G §399, §513, §555

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 14:40:11 +01:00
jschoubben 9068aac406 C14 (regenerate): mesh-conditions' finding body types, no hand-kept tsconfig.json, the watchdogs client's artifact
Regenerated by seatgen at mesh-catalog b5aebbbe (bodies types, design 47 G section 452, 454); the eight hand-kept
tsconfig.json files are deleted (the generator writes none, section 341); health-and-repair/module.json names the
artifact go-meshwatchdogsclient its client check asks for.

Builds: design 47 G §439, §452, §454, §341
2026-11-11 11:33:06 +01:00
mesh-tools 5fd0bf86f1 Merge pull request 'Registry recovery: mesh-broker's list, show and orphans answer each binding (issue 1966)' (#5) from fix/1966-bindings-first-view into main 2026-11-11 10:32:31 +00:00
jschoubben 0167b24b95 mesh-broker's fixtures take a keeper ledger plan's binding with a type and an index, so types survive the round trip
mesh/delivery-group group fix/1966-bindings-first-view merged: every member is merged
mesh/delivery merged: source.main moved to novox/mesh-contracts@5fd0bf86f120
mesh/check checking 0167b24b9564 on 5fd0bf86f120 | novox/mesh-contracts#5 in group fix/1966-bindings-first-view
Builds: design 25 bindings-first-view §2

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:54:37 +01:00
jschoubben 5f7610f521 C5 (answer): the node-engine's verbs name their class
hand-over and access-act are warrants, compose an act, the other six without callers reads.

Builds: design 47 G §391, §393, §447

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:45:58 +01:00
jschoubben e529c372d0 C14: the generated Go and TypeScript of every seat follow the definitions
Written by seatgen at c62650e4 (GEN3) with mesh-sdk b19fc7fa (reader release): the seat mesh-grants new,
every TypeScript contract as index.js with index.d.ts, events with subject and stream. mesh-watchdogs gains
its family, which a definition with events needs. Written with the reader as it is: the field needs-approval
(node-login-shell) and the section bodies (mesh-conditions) are unknown to it, so they were laid aside for
the run; nothing generated carries either.

Builds: design 47 G §339, §341, §261, §389

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:45:30 +01:00
jschoubben 44492ce555 C3 (repair): mesh-vault retire names seat:mesh-config again
The checkout of C9 had laid back the earlier text.

Builds: design 47 G §336, §392

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:44:40 +01:00
jschoubben 77e583be44 C3, C5, C11 (answers): mesh-broker's write verbs name module:nats, node-engine's seat-list verbs the callers its code names, mesh-conditions declares findings-views
create and apply are of class act; recreate and drop of class warrant; all four called by module:nats.
seat-list and seat-list-again name persons, sessions and healers as SeatListCallers does.

Builds: design 47 G §336, §388, §391, §392, §393

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:44:34 +01:00
jschoubben 26ef347d27 C13: every contracts manifest says version 0.1 and no artifact says series
Builds: design 47 G §368, §411

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:43:17 +01:00
jschoubben 70b91f7a79 C12: mesh-watchdogs says machine-away and machine-back
Subject parts name the machine, not the publisher; kept 90 days and 16 MiB.

Builds: design 47 G §389, §436

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:43:02 +01:00
jschoubben 41690f7c3f C11: mesh-conditions says findings-asked, resyncs one observer, and defines the finding bodies
The event findings-asked (ask, at, by, module; 7 days, 16 MiB), resync with an optional module and callers
operator, healers and sessions, and the section bodies: the finding with its layout whole, finding-written,
finding-cleared and findings-stated. The state findings is its owner's alone. Whether findings-views is a
state of this definition waits on a question.

Builds: design 47 G §383, §384, §390, §434, §437, §439

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:42:51 +01:00
jschoubben e84b1e3712 C10: operator-channel lists a held-back ask with since when and serves ask-again
asks gains the state held-back and the field held-since (no behind); the seat gains the verb ask-again,
of class act, the operator's and the healers'.

Builds: design 47 G §40, §83, §394, §403; design 46 §6

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:42:06 +01:00
jschoubben 5cd44f0ebe C9: the seat mesh-grants is defined whole: rule grant, the events wait-held, wait-ended, filling and room, and the read grants-for
Rewritten from the earlier branch to the final lines: the earlier verbs waits and release go (the part's
tools stay its own), grants-for is added, wait events carry clock-from, filling and room carry a store's fill
as mesh-wants' do. The generated Go and TypeScript wait on the generator.

Builds: design 47 Where it goes (grants part), G §264, §266, §331, §401, §441

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:41:42 +01:00
jschoubben bcb37afb48 C8: mesh-broker takes and restores a module's kept data (snapshot-kept, restore-kept) and a binding names its objects
Both verbs are of class act, not optional, and called by holder:node-backup@same-node alone; restore-kept
takes aside-only and discard-aside; the Binding gains objects. The verbs' sibling mesh-broker callers text
(create, apply, recreate, drop) is left as it is: a question is open.

Builds: design 47 G §58, §59, §337, §399, §400, §405, §406

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:40:49 +01:00
jschoubben d86a46e5d8 C7: node-backup backs up and restores a module's kept data on the bus: aside, discard-aside, ended and restored
now, restore and aside are of class act; discard-aside is the operator's alone; ended and restored carry the
node, module and kept data in their subject and the module, kept data, form, fingerprint and outcome.

Builds: design 47 G §296, §297, §302, §405

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:40:23 +01:00
jschoubben a904102a07 C6: a placed module and a place change name the watched branch and the build's fingerprint
Builds: design 47 G §14, §78, §114, §402

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:39:46 +01:00
jschoubben 91818305e7 C5: the node-engine seat says composed, running (kept last per subject, no age limit, or stopped) and capabilities-changed, acts in compose, and serves process-builds
Rewritten from the earlier branch to the final lines: keep as an object, stopped on running, process-builds a
read for persons, sessions and healers and not optional, the compose rule with the step's default bound.
The eleven verbs' callers (§393) wait on a question; the generated Go and TypeScript wait on the generator.

Builds: design 47 G §177, §199, §203, §260, §261, §266, §396, §404, §440

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:39:23 +01:00
jschoubben f33c1d4b78 C3: the callers of mesh-broker's four reads, mesh-config's renames, mesh-vault's retire and node-engine's seat-list verbs are lists
mesh-broker list, show, check, orphans and mesh-config renames name invokers; mesh-vault retire names
seat:mesh-config; node-engine seat-list names persons and healers, seat-list-again the operator and the
healers. mesh-broker create, apply, recreate and drop keep their text: the design names no form for them.

Builds: design 47 G §336, §392, §204

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:38:50 +01:00
jschoubben 8d8a28934c AM-C2: the login shell's verb execute is marked needs-approval
Builds: design 46 milestone 7 §21, §2

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:37:48 +01:00
jschoubben a711302323 C1, C2 (format): the schema names a verb's class and callers list, an accepted kind's callers, a kept event, acts and bodies
A verb gains class (read, act, warrant), callers as a list of the forms of §336/§392 and needs-approval; an
accepted kind gains callers; an event gains subject and keep as an object (max-age-days, max-mib,
last-per-subject), a dot only without keep; the seat gains acts (steps incl. pipeline, on every|language|
kind:image, bound) and bodies.

Builds: design 47 G §68, §203, §336, §338, §391, §392, §396, §397, §439; design 46 milestone 7 §2

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:37:48 +01:00
jschoubben ada45be38b AM-C1: the operator-channel client puts a key prefix before every key of its own state
Client.KeyPrefix is put before the keys the client writes and reads in its own State; empty for every
asker today, so today's keys stay; Where still reads the router's record under <module>.<id>.

Builds: design 46 milestone 7 §10, §22 (design 47 G, approval mark)

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:35:35 +01:00
jschoubben ed12ffb387 mesh-broker's Binding is the wire form and Held carries it, so list, show and orphans answer the binding
The seat's Binding takes the fields the events carry and the membership holds
(local, storage, template, stream, subject, bucket, object-store, history,
state, indexes, snapshot, types): one form in the events, in list, show and
orphans. Held gains binding, present on an entry the bus holds. Definition,
fixture and generated Go and TypeScript contract.

Builds: design 25 bindings-first-view §2, §7 (hq d0760629, PR 543)

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 10:14:55 +01:00
mesh-tools f5d76e84ca Merge pull request 'The node-engine seat's client asks a node once more when an event came while an ask ran, never dropping it (issue 1966 note 170; group with mesh-delivery)' (#4) from fix/1966-engine-reads-asked-again into main 2026-11-10 10:45:49 +00:00
jschoubben c9ffed7042 S1-S3: the node-engine seat's client asks a node once more when an ask came while one ran, and shows when the event was heard (issue 1966 note 170)
mesh/delivery merged: source.main moved to novox/mesh-contracts@f5d76e84ca71
mesh/delivery-group group fix/1966-engine-reads-asked-again merged: every member is merged
mesh/check checking c9ffed70421a on f5d76e84ca71 | novox/mesh-contracts#4 in group fix/1966-engine-reads-asked-again
An event of manifest-reads-changed heard while an ask of the same node ran was dropped
without a line, so a restated engine could stay read at its first statement (ace,
2026-11-10 07:36). Every reader goes through Keeper.AskNode, so the assigner, the
builder and the indexer are fixed at once (ADR 0668 §4: the caller hears it and calls
again; ADR 0634 §1: the seat's client).

- AskNode: an ask while one runs is asked once more after it, one follow-up however
  many came, said in one line (1966/AC170-1, AC170-3). The asks of one node so run one
  after another, and take keeps the last answer, as before (no rule on the engine's
  clock: review round 1).
- Statement.EventAt (event-at): when the node's event was last heard, read by the
  parts' engine-reads tools; forgotten with the node's key.

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-10 11:42:05 +01:00
mesh-tools 7fbfd77a76 Merge pull request 'Engine reads keep the last answer and say an unanswered node; operator-channel asks and watchdogs presence declared (ADR 0668; issue 1966; group fix/1966-call-made-once)' (#3) from fix/1966-call-made-once into main 2026-11-10 07:20:28 +00:00
jschoubben bb16f99e2d C7: the node-engine seat's client keeps the wait of every caller's kept manifest-reads calls, ReadsCalls beside Keeper.Unanswered, its bound's end asking once whether the machine is heard (issue 1966, ADR 0668 §3, ADR 0634 §1, ADR 0596 §2; review round 3, findings 1 and 2)
mesh/delivery merged: source.main moved to novox/mesh-contracts@7fbfd77a76cb
mesh/delivery-group group fix/1966-call-made-once merged: every member is merged
mesh/check checking bb16f99e2d5e on 7fbfd77a76cb | novox/mesh-contracts#3 in group fix/1966-call-made-once
The assigner, the builder and the indexer share it instead of two copies; it names no other seat's client (the client check), so each caller writes its finding in mesh-conditions' layout through Raise, stamped with ReadsCalls' clock.

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-10 04:54:06 +01:00
jschoubben 11a36eb88c C6: the watchdogs seat declares presence's answer: with machine, that machine's online and since; without, the keys of the state presence (issue 1966, ADR 0596 §2, ADR 0668 §3; review round 3, finding 1)
The builder and the indexer ask whether a node's machine is heard through this verb instead of reading the watchman's state; regenerated with seatgen, whose -check names nothing new.

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-10 04:52:53 +01:00
jschoubben 0ae7cb7a76 C5: the operator-channel seat declares its verb asks' input (key, state, since, bound) and answer (asks with key and state, cut, matched), as the router serves it (issue 1966, ADR 0668 §4; review round 1, finding 5)
The assigner's read at its consumer's bind calls the verb with them; regenerated with seatgen, whose -check passes.

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-10 04:20:04 +01:00
jschoubben c6689bfdb3 C4: a statement keeps since when its engine is unanswered, and the keeper names each node unanswered past a bound while heard (issue 1966, ADR 0668 §3; review round 1, finding 4)
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-10 04:15:01 +01:00
jschoubben c584f4570b C3: the engine-reads keeper keeps the fallback or the last statement at the first fault while the kept call asks on (issue 1966, ADR 0668 §3; review round 1, finding 1)
A part whose node answers nothing waited out busretry.Bound (30 s) before it acted on the node's record: Once asks the verb once, and its fault is taken at once.

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-10 04:11:07 +01:00
jschoubben e1303f1542 C2: the finding kind call-unanswered of the seat mesh-conditions (issue 1966, ADR 0668 §3)
A kept call still unanswered past five minutes is said in the caller's findings, keyed call.<id>.call-unanswered.

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-10 02:54:44 +01:00
jschoubben 5c29bea0b3 C1: the engine-reads keeper calls every node again at its part's consumer bind (issue 1966, ADR 0668)
A manifest-reads-changed said before the part's consumer existed was never heard (note 155), and the
statement taken while an engine restarted stood. AtBind is registered on the hub's OnBound.

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-10 02:54:44 +01:00
mesh-tools 66e0c611bf Merge pull request 'Record a merge through the merge gate (issue 1966, bootstrap)' (#2) from fix/1966-gate-record into main 2026-11-07 20:19:51 +00:00
jschoubben 1aa5dee992 Record a merge through the merge gate so the new indexer reads this repository's seat definitions on its merge (issue 1966, the operator's bootstrap)
mesh/delivery merged: source.main moved to novox/mesh-contracts@66e0c611bf83
mesh/delivery-group group fix/1966-gate-record merged: every member is merged
mesh/check pass 1aa5dee99226 on 66e0c611bf83 | carried from 08580d25d2dc, mesh-networking 5af7189cad82 | unit 14 run, 270 kept | integration 0 run, 27…
2026-11-07 21:13:54 +01:00
mesh-tools 08580d25d2 Merge pull request 'Registry milestone: mesh-contracts (issue 1966)' (#1) from feat/registry-milestone into main 2026-11-07 14:19:16 +00:00
154 changed files with 11501 additions and 2303 deletions
+146 -10
View File
@@ -1,8 +1,8 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://git.novox.be/novox/mesh-contracts/format/seat-definition.schema.json",
"title": "A seat's definition (novox/hq ADR 0608 \u00a71, design 26), format 1",
"description": "One file per seat, seats/<seat>/seat.json. A whole definition (grain whole) gives every verb's input and answer, every message's body and where its events are kept; one at the seat list's grain (seat-list) holds what mesh-sdk's compiled seat list held (ADR 0613 \u00a72). At most 256 KiB. Read strictly: a field not named here is refused.",
"title": "A seat's definition (novox/hq ADR 0608 §1, design 26), format 1",
"description": "One file per seat, seats/<seat>/seat.json. A whole definition (grain whole) gives every verb's input and answer, every message's body and where its events are kept; one at the seat list's grain (seat-list) holds what mesh-sdk's compiled seat list held (ADR 0613 §2). At most 256 KiB. Read strictly: a field not named here is refused.",
"type": "object",
"additionalProperties": false,
"required": [
@@ -34,7 +34,7 @@
]
},
"domain": {
"description": "the glossary domain the seat belongs to, by its heading (ADR 0636 \u00a75)",
"description": "the glossary domain the seat belongs to, by its heading (ADR 0636 §5)",
"enum": [
"Module",
"Config",
@@ -97,9 +97,9 @@
"events": {
"type": "array",
"items": {
"$ref": "#/$defs/message"
"$ref": "#/$defs/event"
},
"description": "published on mesh.seat.<seat>.event.<name>"
"description": "published on mesh.seat.<seat>.event.<name>, or on its subject when it carries parts"
},
"family": {
"type": "object",
@@ -144,11 +144,11 @@
}
}
},
"description": "the holder's own events listed beside the seat, keeping the holder's subjects (ADR 0620 \u00a72)"
"description": "the holder's own events listed beside the seat, keeping the holder's subjects (ADR 0620 §2)"
},
"states": {
"type": "array",
"description": "the layouts of the state the holder keeps on the bus for the seat (ADR 0608 \u00a71, ADR 0634 \u00a76); a whole definition's. No holder module is named: each reader takes the holder from its own manifest's reads",
"description": "the layouts of the state the holder keeps on the bus for the seat (ADR 0608 §1, ADR 0634 §6); a whole definition's. No holder module is named: each reader takes the holder from its own manifest's reads",
"items": {
"$ref": "#/$defs/state"
}
@@ -261,6 +261,50 @@
"type": "object",
"description": "a JSON Schema"
}
},
"acts": {
"type": "array",
"description": "the seat's acting rules (design 47 G 203): each step of a delivery the seat's holder acts in, on which modules, and how long an entry waits there for the holder's new version",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"step"
],
"properties": {
"step": {
"type": "string",
"enum": [
"take-in",
"validate",
"check",
"pipeline",
"build",
"compose",
"grant",
"place"
]
},
"on": {
"type": "string",
"pattern": "^(every|kind:image|[a-z][a-z0-9-]*)$",
"description": "every (the default), a language, or kind:image (design 47 G 397)"
},
"bound": {
"type": "string",
"pattern": "^([0-9]+(\\.[0-9]+)?(h|m|s|ms))+$",
"description": "how long an entry waits in the step for the holder's new version, such as 30m (design 47 G 397); none is the step's default"
}
}
}
},
"bodies": {
"type": "object",
"additionalProperties": {
"type": "object",
"description": "a JSON Schema"
},
"description": "the bodies other modules say on their own streams, from which the grants part makes no seat event or stream (design 47 G 439)"
}
},
"$defs": {
@@ -295,8 +339,25 @@
"type": "object",
"description": "a JSON Schema"
},
"callers": {
"type": "string"
"class": {
"enum": [
"read",
"act",
"warrant"
],
"description": "read: invokers, persons and sessions; act and warrant: operator, sessions and invokers (design 47 G 610); no verb names its callers, and a definition naming a `callers` is refused. A verb that names no class is a read, whether it is on main or design 47 G adds it, and nothing refuses a verb for naming none (design 47 G 456)"
},
"needs-approval": {
"type": "boolean",
"description": "the verb runs only on the operator's Approve of the call, for every holder (design 46 milestone 7, 2)"
},
"by-caller": {
"type": "boolean",
"description": "the holder's process answers the verb itself and tells callers apart by the account the bus proved (ADR 0259 3; design 47 G 554, 621, 656)"
},
"chunks": {
"type": "boolean",
"description": "the holder's process sends the answer's file in chunks on mesh.seat.<seat>.chunk.<verb>.<call>.<n>, each acknowledged by the caller on mesh.seat.<seat>.ack.<verb>.<call>.<n>; only with by-caller (design 47 G 681)"
}
}
},
@@ -311,6 +372,13 @@
"type": "string",
"pattern": "^[a-z][a-z0-9-]*$"
},
"stream": {
"enum": [
"check",
"delivery"
],
"description": "the stream an accepted kind rides: its subject is <stream>.<kind>, and one kind name may ride both streams, as the build seats accept step on check and on delivery (design 47 G 455)"
},
"body": {
"type": "object",
"description": "a JSON Schema"
@@ -433,7 +501,7 @@
"objects",
"ledger"
],
"description": "ADR 0595 \u00a72"
"description": "ADR 0595 §2"
},
"writer": {
"enum": [
@@ -461,6 +529,11 @@
},
"description": {
"type": "string"
},
"view": {
"type": "boolean",
"const": true,
"description": "true when the seat offers the state as a view for a module to follow by `consumes` (design 47 G 699; ADR 0571 §6); the manifest validator refuses a seat-named view of a state without it"
}
}
},
@@ -485,6 +558,69 @@
"type": "string"
}
}
},
"event": {
"type": "object",
"additionalProperties": false,
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)*$",
"description": "lower-case words; a dot only in an event that names no keep, which stays on its seat's family (design 47 G 396)"
},
"body": {
"type": "object",
"description": "a JSON Schema"
},
"by-caller": {
"type": "boolean"
},
"subject": {
"type": "string",
"pattern": "^([a-z][a-z0-9-]*|<[a-z][a-z0-9-]*>)(\\.([a-z][a-z0-9-]*|<[a-z][a-z0-9-]*>))*$",
"description": "the words after mesh.seat.<seat>.event. with <part> tokens, <node> written out (design 47 G 397); a part <node> is the publishing node's. Not with by-caller"
},
"keep": {
"type": "object",
"additionalProperties": false,
"description": "the event is kept on the stream SEAT_<seat>_<event> (design 47 G 396); without it the event stays on the seat's family",
"properties": {
"max-age-days": {
"type": "integer",
"minimum": 0,
"description": "days a message is kept; 0 is no age limit; 90 when not named"
},
"max-mib": {
"type": "integer",
"minimum": 1,
"description": "the stream's cap in MiB; 16 when not named"
},
"last-per-subject": {
"type": "boolean",
"description": "keep the last message of each subject; no when not named"
}
}
}
},
"allOf": [
{
"if": {
"required": [
"keep"
]
},
"then": {
"properties": {
"name": {
"pattern": "^[a-z][a-z0-9-]*$"
}
}
}
}
]
}
}
}
@@ -0,0 +1,225 @@
package enginereads
import (
"context"
"maps"
"slices"
"strings"
"sync"
"time"
)
// CallID is the id of a part's finding about node's manifest-reads: the node the kept call waits on.
func CallID(node string) string { return "manifest-reads." + node }
// BoundPrefix starts the key of a node's bound in a part's state of bounds, a key that expires at its end.
const BoundPrefix = "reads-call."
// BoundOf is the node a bound key is of.
func BoundOf(key string) (string, bool) { return strings.CutPrefix(key, BoundPrefix) }
// UnansweredCall is a node's manifest-reads left unanswered past the bound while its machine is heard: what the part's
// finding call-unanswered says (novox/hq ADR 0668 §3), and At, the part's clock when it is written.
type UnansweredCall struct {
Node string
Since time.Time
Words string
At time.Time
}
// ReadsCalls is the wait of a part's kept manifest-reads calls through a Keeper, shared by every caller of the verb (the
// assigner, the builder, the indexer): a node whose engine has not answered for Bound while its machine is heard is
// Raised in the part's own findings, and Cleared once it answers (novox/hq ADR 0668 §3). Every step is an event; nothing
// waits on a timer.
//
// With Arm set, a node unanswered is weighed when its bound ends (Expired, on the expiry of the key Arm keeps in the
// part's state of bounds): Heard is asked then, once, and a node not heard has no finding; it is asked again when it
// returns, on manifest-reads-changed (ADR 0668 §4). With no Arm, Heard is the part's own knowledge, asked at each Step.
type ReadsCalls struct {
Keeper *Keeper
// Nodes are the counted nodes.
Nodes func() []string
// Heard says whether node's machine is heard (with Arm, the seat mesh-watchdogs' verb presence); an error is said and
// reads as not heard.
Heard func(ctx context.Context, node string) (bool, error)
// Bound is how long a node may stay unanswered before it is the finding.
Bound time.Duration
// Raise writes the finding of u in the part's findings; Clear removes the finding of node, none being nothing to clear.
Raise func(ctx context.Context, u UnansweredCall) error
Clear func(ctx context.Context, node string) error
// Held are the nodes whose finding the part's findings hold, written by this process or another; nil clears every
// counted node not raised.
Held func(ctx context.Context) ([]string, error)
// Arm keeps a bound for node ending at ends, whose expiry is Expired; nil weighs Heard at each Step.
Arm func(ctx context.Context, node string, ends time.Time) error
Now func() time.Time
Logf func(string, ...any)
mu sync.Mutex
said map[string]time.Time // node -> the since its finding was written for
}
func (c *ReadsCalls) now() time.Time {
if c.Now != nil {
return c.Now()
}
return time.Now()
}
func (c *ReadsCalls) logf(f string, a ...any) {
if c.Logf != nil {
c.Logf(f, a...)
}
}
func (c *ReadsCalls) ready() bool {
return c != nil && c.Keeper != nil && c.Nodes != nil && c.Heard != nil && c.Raise != nil && c.Clear != nil
}
// unanswered is node's since while its statement is unanswered.
func unanswered(statements map[string]Statement, node string) (time.Time, bool) {
s, ok := statements[node]
if !ok || s.Answered || s.UnansweredSince.IsZero() {
return time.Time{}, false
}
return s.UnansweredSince, true
}
func (c *ReadsCalls) heard(ctx context.Context, node string) bool {
ok, err := c.Heard(ctx, node)
if err != nil {
c.logf("whether %s's machine is heard cannot be read, so its unanswered %s is no finding: %v", node, Verb, err)
return false
}
return ok
}
func (c *ReadsCalls) isSaid(node string, since time.Time) bool {
c.mu.Lock()
defer c.mu.Unlock()
was, ok := c.said[node]
return ok && was.Equal(since)
}
// raise writes node's finding, unless written for this since already, and asks the node again once its last ask ended.
func (c *ReadsCalls) raise(ctx context.Context, node string, since time.Time, words string) bool {
if !c.Keeper.Asking(node) {
c.Keeper.AskNode(node, "unanswered since "+since.UTC().Format(time.RFC3339)+", its machine heard")
}
if c.isSaid(node, since) {
return true
}
if err := c.Raise(ctx, UnansweredCall{Node: node, Since: since, Words: words, At: c.now().UTC()}); err != nil {
c.logf("the finding call-unanswered of %s's %s is not written: %v", node, Verb, err)
return false
}
c.logf("%s on %s is unanswered since %s and its machine is heard: the finding call-unanswered", Verb, node, since.UTC().Format(time.RFC3339))
c.mu.Lock()
if c.said == nil {
c.said = map[string]time.Time{}
}
c.said[node] = since
c.mu.Unlock()
return true
}
// Step weighs every counted node after a statement changed or the counted nodes changed: with no Arm a node unanswered
// and heard is asked again, and past Bound it is the finding; with Arm, a node unanswered and not yet said has its bound
// kept. Every finding no longer raised is cleared.
func (c *ReadsCalls) Step(ctx context.Context) {
if !c.ready() {
return
}
nodes := c.Nodes()
statements := c.Keeper.Statements()
now := c.now()
raised := map[string]bool{}
for _, node := range nodes {
since, ok := unanswered(statements, node)
if !ok {
continue
}
if c.Arm != nil {
if c.isSaid(node, since) {
raised[node] = true
continue
}
if err := c.Arm(ctx, node, since.Add(c.Bound)); err != nil {
c.logf("the bound of %s's %s is not kept: %v", node, Verb, err)
}
continue
}
if !c.heard(ctx, node) {
continue
}
if now.Sub(since) < c.Bound {
if !c.Keeper.Asking(node) {
c.Keeper.AskNode(node, "unanswered since "+since.UTC().Format(time.RFC3339)+", its machine heard")
}
continue
}
raised[node] = c.raise(ctx, node, since, statements[node].Words)
}
c.clear(ctx, nodes, raised)
}
// Expired weighs node when its bound ended: unanswered past Bound and its machine heard, it is the finding and is asked
// again; not yet past Bound, its bound is kept again; not heard, it has none.
func (c *ReadsCalls) Expired(ctx context.Context, node string) {
if !c.ready() || !slices.Contains(c.Nodes(), node) {
return
}
statements := c.Keeper.Statements()
since, ok := unanswered(statements, node)
if !ok || c.isSaid(node, since) {
return
}
if c.now().Sub(since) < c.Bound {
if c.Arm != nil {
if err := c.Arm(ctx, node, since.Add(c.Bound)); err != nil {
c.logf("the bound of %s's %s is not kept: %v", node, Verb, err)
}
}
return
}
if !c.heard(ctx, node) {
c.logf("%s on %s is unanswered since %s and its machine is not heard: no finding; it is asked again when it returns", Verb, node, since.UTC().Format(time.RFC3339))
return
}
c.raise(ctx, node, since, statements[node].Words)
}
// clear removes the finding of every node held or said and not raised: with Held those it names, else every counted node.
func (c *ReadsCalls) clear(ctx context.Context, nodes []string, raised map[string]bool) {
candidates := map[string]bool{}
if c.Held != nil {
held, err := c.Held(ctx)
if err != nil {
c.logf("the findings of %s held cannot be listed: %v", Verb, err)
}
for _, node := range held {
candidates[node] = true
}
} else {
for _, node := range nodes {
candidates[node] = true
}
}
c.mu.Lock()
for node := range c.said {
candidates[node] = true
}
c.mu.Unlock()
for _, node := range slices.Sorted(maps.Keys(candidates)) {
if raised[node] {
continue
}
if err := c.Clear(ctx, node); err != nil {
c.logf("the finding call-unanswered of %s's %s is not cleared: %v", node, Verb, err)
continue
}
c.mu.Lock()
delete(c.said, node)
c.mu.Unlock()
}
}
@@ -137,6 +137,21 @@ type Statement struct {
Answered bool `json:"answered"`
Words string `json:"words,omitempty"`
AskAgain *Again `json:"ask-again,omitempty"`
// UnansweredSince is when the engine first did not answer, of the asks since its last answer; zero once answered
// (ADR 0668 §3: a kept call unanswered past five minutes is a finding of its caller).
UnansweredSince time.Time `json:"unanswered-since,omitzero"`
// EventAt is when the part last heard the seat's event manifest-reads-changed for the node, beside when it asked and
// what the engine stated then (issue 1966 note 170: was the event heard, and was it asked again after it).
EventAt time.Time `json:"event-at,omitzero"`
// Heard is the newest event heard of the node with what it says the engine states, kept so the state shows what the
// rules read while the statement is behind it (issue 1975 note 6), and so a part that starts again holds it.
Heard *HeardEvent `json:"heard,omitempty"`
}
// HeardEvent is an event manifest-reads-changed as the part kept it: when the engine said it and what it said.
type HeardEvent struct {
At time.Time `json:"at"`
ManifestReads []string `json:"manifest-reads,omitempty"`
}
// Again is a person's ask again of one node, written by the tool and answered by the part that keeps the state.
@@ -170,7 +185,8 @@ func Decode(raw []byte) (Statement, error) {
return s, nil
}
// Caller calls a seat's verb on one node: process.Conn.CallOn.
// Caller calls a seat's verb on one node: process.Conn.CallKeptOn, a kept call asked again through a transport fault
// within the bus's retry bound (novox/hq ADR 0668 §1; the verb is a read, safe to call again).
type Caller func(node, key string, body any) (json.RawMessage, error)
// Ask asks node's engine the verb once and says what it answered. An engine that answered the call with an error is
@@ -220,6 +236,10 @@ func NodeOf(subject string, data []byte) (string, bool, error) {
type Keeper struct {
// Call asks the verb; nil asks nothing (every node then reads as the fallback or the baseline).
Call Caller
// Once asks the verb once (process.Conn.CallOn). When set, its fault keeps the fallback or the last statement at once,
// marked as not answering, while Call, the kept call, asks on until answered (novox/hq ADR 0668 §3): a part does not
// wait out busretry.Bound for a node whose engine answers nothing before it acts on what it last knew.
Once Caller
// Fallback reads a node's record `<node>.node` once where its engine did not answer the verb; nil reads none.
Fallback func(node string) ([]string, bool)
// Put writes a node's key of the part's state, Delete removes it; nil keeps the statements in memory only.
@@ -235,8 +255,22 @@ type Keeper struct {
mu sync.Mutex
by map[string]Statement
asking map[string]bool
// again is, per node an ask of which runs, the newest why of an ask that came meanwhile: it is asked once more when
// the running ask ends, never dropped (issue 1966 note 170).
again map[string]string
// eventAt is, per node, when its event manifest-reads-changed was last heard (Statement.EventAt).
eventAt map[string]time.Time
// said is, per node, the newest event heard with what it says the engine states: a statement older than it is behind
// (issue 1975's kind: an answer taken while the engine still stated its bootstrapped seats stood after the full list).
said map[string]nodeengine.ManifestReadsChangedEvent
// catching counts, per node, the asks made since the last event only to catch a statement up to it.
catching map[string]int
}
// MaxCatchUp is how many asks one event may cause beyond its own while the engine's answer stays behind it: an engine
// that answers older than its own event is said loudly, never asked in a loop.
const MaxCatchUp = 3
func (k *Keeper) logf(f string, a ...any) {
if k.Logf != nil {
k.Logf(f, a...)
@@ -250,14 +284,25 @@ func (k *Keeper) now() time.Time {
return time.Now()
}
// AskNode asks node's engine, unless an ask of it runs already; why is said in the log.
// AskNode asks node's engine; why is said in the log. When an ask of it runs already, the node is asked once more after
// that ask ends, one follow-up however many asks came meanwhile, so an event heard while an ask runs is never lost (issue
// 1966 note 170; ADR 0668 §4: the caller hears it and calls again). A why that starts with Event is the seat's event,
// whose time the node's statement shows as event-at.
func (k *Keeper) AskNode(node, why string) {
k.mu.Lock()
if k.asking == nil {
k.asking = map[string]bool{}
k.asking, k.again, k.eventAt = map[string]bool{}, map[string]string{}, map[string]time.Time{}
}
if strings.HasPrefix(why, Event) {
k.eventAt[node] = k.now().UTC()
}
if k.asking[node] {
_, waits := k.again[node]
k.again[node] = why
k.mu.Unlock()
if !waits {
k.logf("%s on %s: an ask runs, so it is asked once more after it (%s)", Verb, node, why)
}
return
}
k.asking[node] = true
@@ -269,16 +314,122 @@ func (k *Keeper) AskNode(node, why string) {
go k.ask(node, why)
}
// HeardChanged keeps the newest event heard of a node: until the node's statement is at least as new, the node reads
// as the event says (the engine's own word), and the node is asked again until its statement is (see ask). Call it before
// AskNode for the same event.
func (k *Keeper) HeardChanged(e nodeengine.ManifestReadsChangedEvent) {
at, err := time.Parse(time.RFC3339Nano, e.At)
if err != nil {
return
}
k.mu.Lock()
defer k.mu.Unlock()
if k.said == nil {
k.said, k.catching = map[string]nodeengine.ManifestReadsChangedEvent{}, map[string]int{}
}
if old, ok := k.said[e.Node]; ok {
if oat, err := time.Parse(time.RFC3339Nano, old.At); err == nil && !at.After(oat) {
return
}
}
e.ManifestReads = slices.Clone(e.ManifestReads)
k.said[e.Node] = e
k.catching[e.Node] = 0
}
// behindLocked says node's statement is older than the newest event heard of it: the engine said its reads changed
// after the time the statement was made, and to something else. k.mu is held.
func (k *Keeper) behindLocked(node string) bool {
e, ok := k.said[node]
if !ok {
return false
}
at, err := time.Parse(time.RFC3339Nano, e.At)
if err != nil {
return false
}
s := k.by[node]
return s.StatedAt.Before(at) && !slices.Equal(sortedCopy(s.ManifestReads), sortedCopy(e.ManifestReads))
}
func sortedCopy(in []string) []string {
out := slices.Clone(in)
slices.Sort(out)
return out
}
// readsLocked is what node reads: its statement, or the newest event's reads while the statement is behind it.
func (k *Keeper) readsLocked(node string) []string {
if k.behindLocked(node) {
return slices.Clone(k.said[node].ManifestReads)
}
return slices.Clone(k.by[node].ManifestReads)
}
// AskAll asks every node of nodes once, each as AskNode does.
func (k *Keeper) AskAll(nodes []string, why string) {
for _, n := range nodes {
k.AskNode(n, why)
}
}
// AtBind is what a part registers with its event hub's OnBound (process.EventHub.OnBound): at each bind of its consumer
// every node nodes names is asked once, so a manifest-reads-changed said before the consumer existed, and a statement
// taken while an engine restarted, end at the bind and not at the next event (novox/hq ADR 0668 §4; issue 1966 note 155).
func (k *Keeper) AtBind(nodes func() []string) func(created time.Time) {
return func(created time.Time) {
k.AskAll(nodes(), "the part's consumer was bound, made "+created.UTC().Format(time.RFC3339))
}
}
// ask asks node, and once more for as long as an ask came while it ran (AskNode); only then is the node no longer asking.
func (k *Keeper) ask(node, why string) {
defer func() {
for {
k.askOnce(node, why)
k.mu.Lock()
delete(k.asking, node)
next, again := k.again[node]
delete(k.again, node)
if !again && k.behindLocked(node) {
// The answer taken is older than an event heard: ask until the statement is at least as new.
if k.catching[node] < MaxCatchUp {
k.catching[node]++
next, again = "its statement is older than the event heard", true
} else {
defer k.logf("%s on %s: the engine answers older than its own event said (%d asks); the node reads as the event says",
Verb, node, MaxCatchUp)
}
}
if !again {
delete(k.asking, node)
}
k.mu.Unlock()
}()
if !again {
return
}
why = "asked again: " + next
}
}
func (k *Keeper) askOnce(node, why string) {
if k.Call != nil && k.Once != nil {
first := Ask(k.Once, node, k.now())
if first.Answered {
k.take(first)
return
}
k.settle(first, why)
why += "; the kept call asks on after: " + first.Words
}
s := Statement{Node: node, AskedAt: k.now().UTC(), From: FromNone, Words: "nothing asks the verb"}
if k.Call != nil {
s = Ask(k.Call, node, k.now())
}
k.settle(s, why)
}
// settle takes s, read from the node's record in its place where the engine did not answer.
func (k *Keeper) settle(s Statement, why string) {
node := s.Node
if s.From != FromVerb && k.Fallback != nil {
if reads, ok := k.Fallback(node); ok {
s.ManifestReads, s.From = slices.Clone(reads), FromRecord
@@ -292,15 +443,59 @@ func (k *Keeper) ask(node, why string) {
k.take(s)
}
// Unanswered is, of nodes, each whose engine the kept call has not answered for bound or longer by now while heard says
// its machine is heard, with since when (novox/hq ADR 0668 §3); a node whose machine is away is none. With no Call, none.
func (k *Keeper) Unanswered(nodes []string, heard func(node string) bool, bound time.Duration, now time.Time) map[string]time.Time {
out := map[string]time.Time{}
if k.Call == nil {
return out
}
k.mu.Lock()
defer k.mu.Unlock()
for _, node := range nodes {
s, ok := k.by[node]
if ok && !s.Answered && !s.UnansweredSince.IsZero() && now.Sub(s.UnansweredSince) >= bound && heard(node) {
out[node] = s.UnansweredSince
}
}
return out
}
// Asking says an ask of node runs now.
func (k *Keeper) Asking(node string) bool {
k.mu.Lock()
defer k.mu.Unlock()
return k.asking[node]
}
// take keeps s, unless the node did not answer and an earlier statement stands: an away node keeps its last one (ADR 0624
// §1), marked as not answering.
// §1), marked as not answering. The asks of one node run one after another (AskNode), so the last answer is the newest.
// The statement shows when the node's event was last heard.
func (k *Keeper) take(s Statement) {
k.mu.Lock()
if k.by == nil {
k.by = map[string]Statement{}
}
if old, ok := k.by[s.Node]; ok && old.EventAt.After(s.EventAt) {
s.EventAt = old.EventAt
}
if at := k.eventAt[s.Node]; at.After(s.EventAt) {
s.EventAt = at
}
if e, ok := k.said[s.Node]; ok {
if at, err := time.Parse(time.RFC3339Nano, e.At); err == nil {
s.Heard = &HeardEvent{At: at.UTC(), ManifestReads: slices.Clone(e.ManifestReads)}
}
}
if !s.Answered {
s.UnansweredSince = s.AskedAt
if old, ok := k.by[s.Node]; ok && !old.Answered && !old.UnansweredSince.IsZero() {
s.UnansweredSince = old.UnansweredSince
}
}
if old, ok := k.by[s.Node]; ok && !s.Answered && old.From != FromNone {
old.Answered, old.AskedAt, old.Words, old.AskAgain = false, s.AskedAt, s.Words, nil
old.Answered, old.AskedAt, old.Words, old.AskAgain, old.UnansweredSince = false, s.AskedAt, s.Words, nil, s.UnansweredSince
old.Heard = s.Heard
s = old
}
k.by[s.Node] = s
@@ -326,6 +521,7 @@ func (k *Keeper) Heard(node string, raw []byte, deleted bool) {
k.mu.Lock()
_, had := k.by[node]
delete(k.by, node)
delete(k.eventAt, node)
k.mu.Unlock()
if had && k.Changed != nil {
k.Changed()
@@ -348,6 +544,15 @@ func (k *Keeper) Heard(node string, raw []byte, deleted bool) {
_, had := k.by[node]
if !had {
k.by[node] = s
if h := s.Heard; h != nil && !h.At.IsZero() {
if k.said == nil {
k.said, k.catching = map[string]nodeengine.ManifestReadsChangedEvent{}, map[string]int{}
}
if _, ok := k.said[node]; !ok {
k.said[node] = nodeengine.ManifestReadsChangedEvent{V: ContractVersion, Node: node, Why: ReadsStarted,
At: h.At.UTC().Format(time.RFC3339Nano), ManifestReads: slices.Clone(h.ManifestReads)}
}
}
}
k.mu.Unlock()
if !had && k.Changed != nil {
@@ -360,6 +565,8 @@ func (k *Keeper) Forget(node string) {
k.mu.Lock()
_, had := k.by[node]
delete(k.by, node)
delete(k.eventAt, node)
delete(k.said, node)
k.mu.Unlock()
if had && k.Delete != nil {
if err := k.Delete(node); err != nil {
@@ -393,7 +600,7 @@ func (k *Keeper) Reads(nodes []string) map[string][]string {
defer k.mu.Unlock()
out := make(map[string][]string, len(nodes))
for _, n := range nodes {
out[n] = slices.Clone(k.by[n].ManifestReads)
out[n] = k.readsLocked(n)
}
return out
}
@@ -405,7 +612,7 @@ func (k *Keeper) Present(nodes []string) map[string][]string {
out := map[string][]string{}
for _, n := range nodes {
if s, ok := k.by[n]; ok && s.Answered {
out[n] = slices.Clone(s.ManifestReads)
out[n] = k.readsLocked(n)
}
}
return out
@@ -1,8 +1,15 @@
package enginereads
import (
"context"
"encoding/json"
"errors"
"fmt"
"strings"
"testing"
"time"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
)
// The answer and the event are judged as the contract lays them out and its reader checks: the layout's version, a node
@@ -34,7 +41,251 @@ func TestTheAnswerAndTheEventAreJudged(t *testing.T) {
t.Errorf("event %s: %v, want %q", name, err, c.bad)
}
}
// Issue 1966 note 155, ADR 0668 §4: a part whose first call of a node timed out, and whose consumer was bound after
// the node's event was said, calls every node once at the bind, and the node is then held as it answered.
calls := map[string]int{}
k := &Keeper{Sync: true, Call: func(node, _ string, _ any) (json.RawMessage, error) {
calls[node]++
if node == "ace" && calls[node] == 1 {
return nil, context.DeadlineExceeded
}
return json.RawMessage(`{"v":1,"node":"` + node + `","manifest-reads":["a.b"],"stated-at":"` + at + `"}`), nil
}}
k.AskNode("ace", "the first view")
if k.Statements()["ace"].Answered {
t.Errorf("a call that timed out reads as answered")
}
k.AtBind(func() []string { return []string{"ace", "g14"} })(time.Unix(0, 0))
if p := k.Present([]string{"ace", "g14"}); len(p["ace"]) != 1 || len(p["g14"]) != 1 || calls["ace"] != 2 || calls["g14"] != 1 {
t.Errorf("after the bind: present %v, calls %v", p, calls)
}
// Review round 1 (ADR 0668 §3): a node whose engine answers nothing reads as its record at the first fault of the call
// made once, while the kept call asks on; what the kept call answers then stands.
var during Statement
f := &Keeper{Sync: true, Fallback: func(string) ([]string, bool) { return []string{"r.s"}, true },
Once: func(string, string, any) (json.RawMessage, error) {
return nil, errors.New("nats: no responders available for request")
}}
f.Call = func(node, _ string, _ any) (json.RawMessage, error) {
during = f.Statements()[node]
return json.RawMessage(`{"v":1,"node":"` + node + `","manifest-reads":["a.b"],"stated-at":"` + at + `"}`), nil
}
f.AskNode("g14", "the first view")
if during.From != FromRecord || during.Answered || f.Statements()["g14"].From != FromVerb {
t.Errorf("while the kept call asked g14 read %+v; after it %+v", during, f.Statements()["g14"])
}
// ADR 0668 §3: a node unanswered keeps when it first was not, across asks; past the bound it is unanswered while its
// machine is heard, none while away, and none once it answers.
clock := time.Date(2026, 11, 10, 3, 0, 0, 0, time.UTC)
answers := false
u := &Keeper{Sync: true, Now: func() time.Time { return clock }, Call: func(node, _ string, _ any) (json.RawMessage, error) {
if answers {
return json.RawMessage(`{"v":1,"node":"` + node + `","manifest-reads":["a.b"],"stated-at":"` + at + `"}`), nil
}
return nil, context.DeadlineExceeded
}}
first := clock
u.AskNode("ace", "the first view")
clock = clock.Add(6 * time.Minute)
u.AskNode("ace", "asked on")
heard := func(string) bool { return true }
if got := u.Unanswered([]string{"ace"}, heard, 5*time.Minute, clock); !got["ace"].Equal(first) ||
len(u.Unanswered([]string{"ace"}, func(string) bool { return false }, 5*time.Minute, clock)) != 0 {
t.Errorf("unanswered past the bound: %v", got)
}
answers = true
u.AskNode("ace", "answered")
if got := u.Unanswered([]string{"ace"}, heard, 5*time.Minute, clock); len(got) != 0 || !u.Statements()["ace"].UnansweredSince.IsZero() {
t.Errorf("an answered node is unanswered: %v", got)
}
// Issue 1966 note 170, 1966/AC170-1 and AC170-3: an event of a node heard while an ask of it runs is not dropped: the
// node is asked once more after that ask ends (one follow-up however many came), said in one line, and the newer
// statement is kept; the event's time is shown beside the statement (event-at).
const stated26, restated = "2026-11-10T07:36:26Z", "2026-11-10T07:36:30Z"
var lines []string
eclock := time.Date(2026, 11, 10, 7, 36, 26, 0, time.UTC)
asks := 0
var e *Keeper
e = &Keeper{Sync: true, Now: func() time.Time { return eclock },
Logf: func(f string, a ...any) { lines = append(lines, fmt.Sprintf(f, a...)) },
Put: func(_ string, raw []byte) error { _, err := Decode(raw); return err },
Call: func(node, _ string, _ any) (json.RawMessage, error) {
asks++
stated := restated
if asks == 1 {
eclock = eclock.Add(4 * time.Second)
e.AskNode(node, Event)
e.AskNode(node, Event)
stated = stated26
} else if got := e.Statements()[node].StatedAt.Format(time.RFC3339); got != stated26 {
t.Errorf("the second ask began before the first was taken in: held %s", got)
}
return json.RawMessage(`{"v":1,"node":"` + node + `","manifest-reads":["a.b"],"stated-at":"` + stated + `"}`), nil
}}
e.AskNode("ace", Event)
held := e.Statements()["ace"]
if asks != 2 || held.StatedAt.Format(time.RFC3339) != restated || e.Asking("ace") {
t.Errorf("an event during an ask: asked %d times, held stated at %s, asking %v", asks, held.StatedAt, e.Asking("ace"))
}
if again := strings.Count(strings.Join(lines, "\n"), "asked once more"); again != 1 {
t.Errorf("the ask kept for later is said in %d lines, not one: %q", again, lines)
}
if !held.EventAt.Equal(eclock) || !strings.Contains(string(must(Encode(held))), `"event-at":"2026-11-10T07:36:30Z"`) {
t.Errorf("the event's time is not shown: %+v", held)
}
if Verb != "manifest-reads" || Event != "manifest-reads-changed" || Consumes != "node-engine.manifest-reads-changed" || Invoke != "seat:node-engine.manifest-reads" {
t.Errorf("the names are %s %s %s %s", Verb, Event, Consumes, Invoke)
}
}
// ADR 0668 §3, ADR 0596 §2 (review round 3): the wait of a part's kept manifest-reads calls. With Arm, a node unanswered
// has its bound kept, and only its expiry asks whether its machine is heard, once: heard, the finding is written at the
// part's clock and the node asked again; away, none; answered, it is cleared. With no Arm, heard is weighed at each step.
func TestReadsCallsSayAnUnansweredNodeHeard(t *testing.T) {
clock := time.Date(2026, 11, 10, 3, 0, 0, 0, time.UTC)
answers, calls := false, 0
k := &Keeper{Sync: true, Now: func() time.Time { return clock }, Call: func(node, _ string, _ any) (json.RawMessage, error) {
calls++
if answers {
return json.RawMessage(`{"v":1,"node":"` + node + `","manifest-reads":["a.b"],"stated-at":"2026-11-10T03:00:00Z"}`), nil
}
return nil, context.DeadlineExceeded
}}
for name, armed := range map[string]bool{"armed": true, "by its own knowledge": false} {
answers, calls = false, 0
k.Forget("ace")
first := clock
k.AskNode("ace", "the first view")
heard, asked := true, 0
raised, cleared := map[string]UnansweredCall{}, map[string]int{}
bounds := map[string]time.Time{}
c := &ReadsCalls{Keeper: k, Nodes: func() []string { return []string{"ace", "g14"} }, Bound: 5 * time.Minute,
Now: func() time.Time { return clock.Add(time.Second) },
Heard: func(context.Context, string) (bool, error) { asked++; return heard, nil },
Raise: func(_ context.Context, u UnansweredCall) error { raised[u.Node] = u; return nil },
Clear: func(_ context.Context, node string) error { cleared[node]++; delete(raised, node); return nil }}
if armed {
c.Arm = func(_ context.Context, node string, ends time.Time) error { bounds[node] = ends; return nil }
}
c.Step(context.Background())
if armed && (asked != 0 || !bounds["ace"].Equal(first.Add(5*time.Minute)) || len(raised) != 0) {
t.Errorf("%s: a step before the bound asked heard %d times, bounds %v, raised %v", name, asked, bounds, raised)
}
clock = clock.Add(6 * time.Minute)
heard, asked = false, 0
if armed {
c.Expired(context.Background(), "ace")
} else {
c.Step(context.Background())
}
if len(raised) != 0 || asked != 1 {
t.Errorf("%s: away, raised %v, heard asked %d times", name, raised, asked)
}
heard, asked, calls = true, 0, 0
if armed {
c.Expired(context.Background(), "ace")
} else {
c.Step(context.Background())
}
if u, ok := raised["ace"]; !ok || !u.Since.Equal(first) || !u.At.Equal(clock.Add(time.Second)) || asked != 1 || calls != 1 {
t.Errorf("%s: heard past the bound, raised %+v, heard asked %d, called %d", name, raised, asked, calls)
}
answers = true
k.AskNode("ace", "answered")
c.Step(context.Background())
if _, ok := raised["ace"]; ok || cleared["ace"] == 0 {
t.Errorf("%s: answered, raised %v, cleared %v", name, raised, cleared)
}
clock = clock.Add(time.Hour)
}
if CallID("ace") != "manifest-reads.ace" {
t.Errorf("the call's id is %s", CallID("ace"))
}
if n, ok := BoundOf(BoundPrefix + "ace"); !ok || n != "ace" {
t.Errorf("the bound's node is %q %v", n, ok)
}
}
func must(b []byte, err error) []byte {
if err != nil {
panic(err)
}
return b
}
// Issue 1975: an engine states its bootstrapped seats, then, a moment later, the full list, and says so with an event.
// An answer taken before the full statement must not stand: the node reads as the event says at once, and is asked until
// its statement is at least as new; an engine that keeps answering older than its own event is asked a bounded number of
// times and not looped on.
func TestAStatementOlderThanAHeardEventDoesNotStand(t *testing.T) {
const early, late = "2026-11-12T01:14:36.498Z", "2026-11-12T01:14:39.001Z"
event := nodeengine.ManifestReadsChangedEvent{V: 1, Node: "ace", Why: ReadsStarted, At: late, ManifestReads: []string{"seat:a", "seat:b"}}
answer := func(reads, at string) json.RawMessage {
return json.RawMessage(`{"v":1,"node":"ace","manifest-reads":[` + reads + `],"stated-at":"` + at + `"}`)
}
// The engine's first answer is the bootstrapped one, taken while the event is heard (the event says the full list).
calls := 0
k := &Keeper{Sync: true, Call: func(string, string, any) (json.RawMessage, error) {
calls++
if calls == 1 {
return answer(`"seat:a"`, early), nil
}
return answer(`"seat:a","seat:b"`, late), nil
}}
k.AskNode("ace", "the assigner started")
k.HeardChanged(event)
if got := k.Reads([]string{"ace"})["ace"]; len(got) != 2 {
t.Fatalf("a statement older than the event heard stands: reads %v", got)
}
if got := k.Present([]string{"ace"})["ace"]; len(got) != 2 {
t.Errorf("present reads %v, want the event's", got)
}
k.AskNode("ace", nodeengine.EventManifestReadsChanged)
if s := k.Statements()["ace"]; len(s.ManifestReads) != 2 || calls != 2 {
t.Errorf("after the event's ask: %v, %d calls", s.ManifestReads, calls)
}
// The event heard is in the node's statement as the part keeps it, and a part that starts again holds it.
var kept []byte
keeper := &Keeper{Sync: true, Put: func(_ string, v []byte) error { kept = v; return nil }, Call: func(string, string, any) (json.RawMessage, error) {
return answer(`"seat:a"`, early), nil
}}
keeper.HeardChanged(event)
keeper.AskNode("ace", "x")
if st, err := Decode(kept); err != nil || st.Heard == nil || len(st.Heard.ManifestReads) != 2 {
t.Errorf("the kept statement shows the event heard as %+v, %v", st.Heard, err)
}
restarted := &Keeper{Sync: true}
restarted.Heard("ace", kept, false)
if got := restarted.Reads([]string{"ace"})["ace"]; len(got) != 2 {
t.Errorf("a part started again reads %v, want the event's", got)
}
// An engine that answers the old statement to every ask: the event's reads stand, the asks are bounded.
calls = 0
stuck := &Keeper{Sync: true, Call: func(string, string, any) (json.RawMessage, error) {
calls++
return answer(`"seat:a"`, early), nil
}}
stuck.HeardChanged(event)
stuck.AskNode("ace", nodeengine.EventManifestReadsChanged)
if calls != 1+MaxCatchUp {
t.Errorf("asked %d times, want %d", calls, 1+MaxCatchUp)
}
if got := stuck.Reads([]string{"ace"})["ace"]; len(got) != 2 {
t.Errorf("reads %v, want the event's", got)
}
// The statement the event describes does not count as behind it: no ask beyond the one.
calls = 0
even := &Keeper{Sync: true, Call: func(string, string, any) (json.RawMessage, error) {
calls++
return answer(`"seat:a","seat:b"`, early), nil
}}
even.HeardChanged(event)
even.AskNode("ace", "x")
if calls != 1 {
t.Errorf("a statement that says what the event says was asked %d times", calls)
}
}
+15 -16
View File
@@ -58,22 +58,21 @@ func TestHaveCodec(t *testing.T) {
if _, err := DecodeHave([]byte(`{"v":1,"phase":"running","health":"ok","extra":1}`)); err == nil {
t.Fatal("an unknown field is read")
}
}
func TestSameHaveComparesTimesAsInstants(t *testing.T) {
at := time.Date(2026, 11, 5, 12, 0, 0, 0, time.UTC)
zone := time.FixedZone("x", 3600)
mk := func(tm time.Time) seat.HaveByNodeModuleValue {
return seat.HaveByNodeModuleValue{Phase: PhaseFailed, Health: HealthFailed,
PullWait: &seat.PullWait{Image: "i", Holder: "h", Began: tm},
UserList: &seat.UserListWritten{Source: "s", At: tm}}
}
if !SameHave(mk(at), mk(at.In(zone))) {
t.Fatal("the same instant in another zone differs")
}
if SameHave(mk(at), mk(at.Add(time.Second))) {
t.Fatal("another instant is the same")
}
t.Run("SameHaveComparesTimesAsInstants", func(t *testing.T) {
at := time.Date(2026, 11, 5, 12, 0, 0, 0, time.UTC)
zone := time.FixedZone("x", 3600)
mk := func(tm time.Time) seat.HaveByNodeModuleValue {
return seat.HaveByNodeModuleValue{Phase: PhaseFailed, Health: HealthFailed,
PullWait: &seat.PullWait{Image: "i", Holder: "h", Began: tm},
UserList: &seat.UserListWritten{Source: "s", At: tm}}
}
if !SameHave(mk(at), mk(at.In(zone))) {
t.Fatal("the same instant in another zone differs")
}
if SameHave(mk(at), mk(at.Add(time.Second))) {
t.Fatal("another instant is the same")
}
})
}
func TestHaveNodeCodec(t *testing.T) {
+173 -26
View File
@@ -3,40 +3,47 @@
// Package meshbroker is the contract of the seat "mesh-broker", defined whole (seats/mesh-broker/seat.json): The mesh's bus, and the bus state modules ask of it in requires (design 25 § 12). create, apply, recreate and drop are granted to the bus module's own credential alone.
package meshbroker
import "time"
// Seat is the seat's name.
const Seat = "mesh-broker"
const (
VerbList = "list"
VerbShow = "show"
VerbCheck = "check"
VerbOrphans = "orphans"
VerbCreate = "create"
VerbApply = "apply"
VerbRecreate = "recreate"
VerbDrop = "drop"
VerbList = "list"
VerbShow = "show"
VerbCheck = "check"
VerbOrphans = "orphans"
VerbCreate = "create"
VerbApply = "apply"
VerbRecreate = "recreate"
VerbDrop = "drop"
VerbSnapshotGet = "snapshot-get"
VerbSnapshotRestore = "snapshot-restore"
VerbSnapshotRestoreCancel = "snapshot-restore-cancel"
VerbSnapshotRemove = "snapshot-remove"
)
const (
EventCreated = "created"
EventRefused = "refused"
EventDrifted = "drifted"
EventDriftCleared = "drift-cleared"
EventFull = "full"
EventFullCleared = "full-cleared"
EventOrphaned = "orphaned"
EventRecreated = "recreated"
EventDropped = "dropped"
EventCreated = "created"
EventRefused = "refused"
EventDrifted = "drifted"
EventDriftCleared = "drift-cleared"
EventFull = "full"
EventFullCleared = "full-cleared"
EventOrphaned = "orphaned"
EventRecreated = "recreated"
EventDropped = "dropped"
EventSnapshotRestored = "snapshot-restored"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbList, VerbShow, VerbCheck, VerbOrphans, VerbCreate, VerbApply, VerbRecreate, VerbDrop}
return []string{VerbList, VerbShow, VerbCheck, VerbOrphans, VerbCreate, VerbApply, VerbRecreate, VerbDrop, VerbSnapshotGet, VerbSnapshotRestore, VerbSnapshotRestoreCancel, VerbSnapshotRemove}
}
// Events is every event published on the seat's subject: a new copy each call.
func Events() []string {
return []string{EventCreated, EventRefused, EventDrifted, EventDriftCleared, EventFull, EventFullCleared, EventOrphaned, EventRecreated, EventDropped}
return []string{EventCreated, EventRefused, EventDrifted, EventDriftCleared, EventFull, EventFullCleared, EventOrphaned, EventRecreated, EventDropped, EventSnapshotRestored}
}
// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects.
@@ -72,16 +79,45 @@ const SubjectRecreated = "mesh.seat.mesh-broker.event.recreated"
// SubjectDropped is where dropped is published.
const SubjectDropped = "mesh.seat.mesh-broker.event.dropped"
// Binding is the binding a module receives in its membership for one entry (ADR 0595 §1, §7).
// StreamSnapshotRestored is the stream snapshot-restored is kept in.
const StreamSnapshotRestored = "SEAT_mesh-broker_snapshot-restored"
// SubjectSnapshotRestored is where snapshot-restored is published, on mesh.seat.mesh-broker.event.snapshot-restored.<request>.<act>.
func SubjectSnapshotRestored(request, act string) string {
return "mesh.seat.mesh-broker.event.snapshot-restored." + request + "." + act
}
// SubjectSnapshotRestoredAll hears every snapshot-restored.
const SubjectSnapshotRestoredAll = "mesh.seat.mesh-broker.event.snapshot-restored.*.*"
// Binding is the binding a module receives in its membership for one entry (ADR 0595 §1, §7): the names on the bus of the entry's objects, one form in the events, in list, show and orphans, and in the membership.
type Binding struct {
// the entry's name on the bus
BusName string `json:"bus-name"`
// how the bus keeps it
StorageType string `json:"storage-type"`
// its subjects, for a stream
Subjects []string `json:"subjects,omitempty"`
// a key-value bucket's name
Bucket string `json:"bucket,omitempty"`
// a ledger's history stream
History string `json:"history,omitempty"`
// a ledger's index buckets, by index name
Indexes map[string]string `json:"indexes,omitempty"`
// the entry's local name in the module's manifest
Local string `json:"local"`
// an object store's name
ObjectStore string `json:"object-store,omitempty"`
// the bus name of the state's <state>-objects, where its large values go (design 47 G 58, 399)
Objects string `json:"objects,omitempty"`
// the subject of a ledger's instances' snapshots
Snapshot string `json:"snapshot,omitempty"`
// a ledger's state bucket
State string `json:"state,omitempty"`
// how the bus keeps it: the entry's storage type
Storage string `json:"storage"`
// a stream's name on the bus
Stream string `json:"stream,omitempty"`
// the subject a stream's messages are on; also a ledger's history's
Subject string `json:"subject,omitempty"`
// its template
Template string `json:"template,omitempty"`
// a ledger's types, as its manifest declares them
Types []map[string]any `json:"types,omitempty"`
}
// Entry is one piece of bus state as a manifest asks it.
@@ -131,6 +167,8 @@ type Fill struct {
// Held is one entry as the bus holds it.
type Held struct {
// the binding a module receives for the entry, as created and recreated carry it; present on an entry whose objects the bus holds, absent on one it does not (design 25 bindings-first-view §2)
Binding *Binding `json:"binding,omitempty"`
// its name on the bus, <module>_<local name>
BusName string `json:"bus-name"`
// its own configuration, where no template fits
@@ -258,8 +296,17 @@ type ListInput struct {
Module string `json:"module,omitempty"`
}
// ListAnswerCaps is the sum of the bus's caps against its limits, in MiB; an absent limit is unlimited (design 47 G 547, 661).
type ListAnswerCaps struct {
AccountLimitMiB int64 `json:"account-limit-mib,omitempty"`
ServerLimitMiB int64 `json:"server-limit-mib,omitempty"`
SumMiB int64 `json:"sum-mib"`
}
// ListAnswer is what list answers.
type ListAnswer struct {
// the sum of the bus's caps against its limits, in MiB; an absent limit is unlimited (design 47 G 547, 661)
Caps *ListAnswerCaps `json:"caps,omitempty"`
// every entry
Entries []Held `json:"entries"`
}
@@ -335,6 +382,91 @@ type DropAnswer struct {
Snapshot string `json:"snapshot,omitempty"`
}
// SnapshotGetInput is what snapshot-get takes.
type SnapshotGetInput struct {
// 128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements
Call string `json:"call"`
// the snapshot's request: the id of the request the keeper took it for, in its state requests
Request string `json:"request"`
}
// SnapshotGetAnswer is what snapshot-get answers.
type SnapshotGetAnswer struct {
// when the snapshot was taken, RFC 3339
At *time.Time `json:"at,omitempty"`
// how many chunks are sent; 0 when the caller is granted no chunk subjects
Chunks int64 `json:"chunks,omitempty"`
// sha256: of the file's bytes
Digest string `json:"digest,omitempty"`
// why not: snapshot damaged, snapshot missing, snapshot protected or snapshot taken before milestone G; set alone
Error string `json:"error,omitempty"`
// the entry's local name
Local string `json:"local,omitempty"`
Module string `json:"module,omitempty"`
Request string `json:"request,omitempty"`
Size int64 `json:"size,omitempty"`
// the stream's name on the bus
Stream string `json:"stream,omitempty"`
}
// SnapshotRestoreInput is what snapshot-restore takes.
type SnapshotRestoreInput struct {
// the snapshot's request: the id of the request the keeper took it for, in its state requests
Request string `json:"request"`
// check the file against its digest and restore nothing
Verify bool `json:"verify,omitempty"`
// why, which the hand-act log keeps
Why string `json:"why"`
}
// SnapshotRestoreAnswer is what snapshot-restore answers.
type SnapshotRestoreAnswer struct {
// accepted: the act's id
Accepted string `json:"accepted,omitempty"`
// busy: the id of the act that runs; it keeps no queue
Busy string `json:"busy,omitempty"`
// why not; set alone
Error string `json:"error,omitempty"`
}
// SnapshotRestoreCancelInput is what snapshot-restore-cancel takes.
type SnapshotRestoreCancelInput struct {
// the restore's act id
Act string `json:"act"`
// why, which the hand-act log keeps
Why string `json:"why"`
}
// SnapshotRestoreCancelAnswer is what snapshot-restore-cancel answers.
type SnapshotRestoreCancelAnswer struct {
// accepted: the act's id
Accepted string `json:"accepted,omitempty"`
// busy: the id of the act that runs; it keeps no queue
Busy string `json:"busy,omitempty"`
// why not; set alone
Error string `json:"error,omitempty"`
}
// SnapshotRemoveInput is what snapshot-remove takes.
type SnapshotRemoveInput struct {
// true: every snapshot past snapshot-keep-days
Expired bool `json:"expired,omitempty"`
// the snapshot's request; or expired true, not both
Request string `json:"request,omitempty"`
// why, which the hand-act log keeps
Why string `json:"why"`
}
// SnapshotRemoveAnswer is what snapshot-remove answers.
type SnapshotRemoveAnswer struct {
// accepted: the act's id
Accepted string `json:"accepted,omitempty"`
// busy: the id of the act that runs; it keeps no queue
Busy string `json:"busy,omitempty"`
// why not; set alone
Error string `json:"error,omitempty"`
}
// CreatedEvent is the body of the event created.
type CreatedEvent = Said
@@ -362,5 +494,20 @@ type RecreatedEvent = Said
// DroppedEvent is the body of the event dropped.
type DroppedEvent = Said
// SnapshotRestoredEvent is the body of the event snapshot-restored.
type SnapshotRestoredEvent struct {
Act string `json:"act"`
// when failed
Error string `json:"error,omitempty"`
Outcome string `json:"outcome"`
Request string `json:"request"`
}
// The values of SnapshotRestoredEvent's outcome.
const (
SnapshotRestoredEventOutcomeDone = "done"
SnapshotRestoredEventOutcomeFailed = "failed"
)
// BusStateForm is the form of the provision bus-state.
type BusStateForm = Binding
+42
View File
@@ -19,6 +19,8 @@ func TestFixtures(t *testing.T) {
}{
{name: "created on the seat's subject", subject: "mesh.seat.mesh-broker.event.created", given: "{\"asked\":{\"max-mib\":64},\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"held\":{\"max-mib\":64},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"storage-type\":\"ledger\",\"template\":\"ledger\"}", wire: "{\"asked\":{\"max-mib\":64},\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"held\":{\"max-mib\":64},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"storage-type\":\"ledger\",\"template\":\"ledger\"}",
decode: func(b []byte) (any, error) { var v CreatedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-broker\\.event\\.created$")},
{name: "created with a ledger's binding as the bus module writes it", subject: "mesh.seat.mesh-broker.event.created", given: "{\"binding\":{\"history\":\"mesh-knowledge_ledger\",\"indexes\":{\"by-kind\":\"mesh-knowledge_ledger_index-by-kind\"},\"local\":\"ledger\",\"snapshot\":\"mesh.ledger.mesh-knowledge.ledger.snapshot\",\"state\":\"mesh-knowledge_ledger_state\",\"storage\":\"ledger\",\"subject\":\"mesh.ledger.mesh-knowledge.ledger.history\",\"template\":\"ledger\",\"types\":[{\"indexes\":[{\"name\":\"by-kind\",\"on\":[\"kind\"]}],\"name\":\"decision\",\"operations\":[{\"effect\":\"set-fields\",\"fields\":[\"title\",\"kind\"],\"name\":\"set\"}],\"schema\":{\"kind\":{\"type\":\"string\"},\"title\":{\"type\":\"string\"}}}]},\"bus-name\":\"mesh-knowledge_ledger\",\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"revision\":7,\"storage-type\":\"ledger\",\"template\":\"ledger\"}", wire: "{\"binding\":{\"history\":\"mesh-knowledge_ledger\",\"indexes\":{\"by-kind\":\"mesh-knowledge_ledger_index-by-kind\"},\"local\":\"ledger\",\"snapshot\":\"mesh.ledger.mesh-knowledge.ledger.snapshot\",\"state\":\"mesh-knowledge_ledger_state\",\"storage\":\"ledger\",\"subject\":\"mesh.ledger.mesh-knowledge.ledger.history\",\"template\":\"ledger\",\"types\":[{\"indexes\":[{\"name\":\"by-kind\",\"on\":[\"kind\"]}],\"name\":\"decision\",\"operations\":[{\"effect\":\"set-fields\",\"fields\":[\"title\",\"kind\"],\"name\":\"set\"}],\"schema\":{\"kind\":{\"type\":\"string\"},\"title\":{\"type\":\"string\"}}}]},\"bus-name\":\"mesh-knowledge_ledger\",\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"revision\":7,\"storage-type\":\"ledger\",\"template\":\"ledger\"}",
decode: func(b []byte) (any, error) { var v CreatedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-broker\\.event\\.created$")},
{name: "refused on the seat's subject", subject: "mesh.seat.mesh-broker.event.refused", given: "{\"asked\":{\"max-mib\":64},\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"held\":{\"max-mib\":64},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"storage-type\":\"ledger\",\"template\":\"ledger\",\"why\":\"the bus refused it\"}", wire: "{\"asked\":{\"max-mib\":64},\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"held\":{\"max-mib\":64},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"storage-type\":\"ledger\",\"template\":\"ledger\",\"why\":\"the bus refused it\"}",
decode: func(b []byte) (any, error) { var v RefusedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-broker\\.event\\.refused$")},
{name: "drifted on the seat's subject", subject: "mesh.seat.mesh-broker.event.drifted", given: "{\"asked\":{\"max-mib\":64},\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"held\":{\"max-mib\":64},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"storage-type\":\"ledger\",\"template\":\"ledger\",\"why\":\"the bus refused it\"}", wire: "{\"asked\":{\"max-mib\":64},\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"held\":{\"max-mib\":64},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"storage-type\":\"ledger\",\"template\":\"ledger\",\"why\":\"the bus refused it\"}",
@@ -35,12 +37,52 @@ func TestFixtures(t *testing.T) {
decode: func(b []byte) (any, error) { var v RecreatedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-broker\\.event\\.recreated$")},
{name: "dropped on the seat's subject", subject: "mesh.seat.mesh-broker.event.dropped", given: "{\"asked\":{\"max-mib\":64},\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"held\":{\"max-mib\":64},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"storage-type\":\"ledger\",\"template\":\"ledger\",\"why\":\"the bus refused it\"}", wire: "{\"asked\":{\"max-mib\":64},\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"held\":{\"max-mib\":64},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"storage-type\":\"ledger\",\"template\":\"ledger\",\"why\":\"the bus refused it\"}",
decode: func(b []byte) (any, error) { var v DroppedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-broker\\.event\\.dropped$")},
{name: "snapshot-restored is said under its request and act", subject: "mesh.seat.mesh-broker.event.snapshot-restored.r-1.a-20261111t100000", given: "{\"act\":\"a-20261111t100000\",\"error\":\"names live\",\"outcome\":\"failed\",\"request\":\"r-1\"}", wire: "{\"act\":\"a-20261111t100000\",\"error\":\"names live\",\"outcome\":\"failed\",\"request\":\"r-1\"}",
decode: func(b []byte) (any, error) { var v SnapshotRestoredEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-broker\\.event\\.snapshot-restored\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "create one entry", subject: "", given: "{\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"options\":{\"max-mib\":64},\"storage-type\":\"ledger\",\"template\":\"ledger\"}", wire: "{\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"options\":{\"max-mib\":64},\"storage-type\":\"ledger\",\"template\":\"ledger\"}",
decode: func(b []byte) (any, error) { var v CreateInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "drop on the operator's warrant", subject: "", given: "{\"local-name\":\"old\",\"module\":\"mesh-knowledge\",\"warrant\":\"w-1\",\"why\":\"the operator approved the drop\"}", wire: "{\"local-name\":\"old\",\"module\":\"mesh-knowledge\",\"warrant\":\"w-1\",\"why\":\"the operator approved the drop\"}",
decode: func(b []byte) (any, error) { var v DropInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "list answers every entry", subject: "", given: "{\"entries\":[{\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"options\":{\"max-mib\":64},\"settings\":{\"max-mib\":64},\"storage-type\":\"ledger\",\"template\":\"ledger\"}]}", wire: "{\"entries\":[{\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"options\":{\"max-mib\":64},\"settings\":{\"max-mib\":64},\"storage-type\":\"ledger\",\"template\":\"ledger\"}]}",
decode: func(b []byte) (any, error) { var v ListAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "list answers the binding of an entry the bus holds", subject: "", given: "{\"entries\":[{\"binding\":{\"history\":\"mesh-knowledge_ledger\",\"indexes\":{\"by-kind\":\"mesh-knowledge_ledger_index-by-kind\"},\"local\":\"ledger\",\"objects\":\"mesh-knowledge_ledger_state-objects\",\"snapshot\":\"mesh.ledger.mesh-knowledge.ledger.snapshot\",\"state\":\"mesh-knowledge_ledger_state\",\"storage\":\"ledger\",\"subject\":\"mesh.ledger.mesh-knowledge.ledger.history\",\"template\":\"ledger\",\"types\":[{\"indexes\":[{\"name\":\"by-kind\",\"on\":[\"kind\"]}],\"name\":\"decision\",\"operations\":[{\"effect\":\"set-fields\",\"fields\":[\"title\",\"kind\"],\"name\":\"set\"}],\"schema\":{\"kind\":{\"type\":\"string\"},\"title\":{\"type\":\"string\"}}}]},\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"settings\":{\"max-mib\":64},\"storage-type\":\"ledger\",\"template\":\"ledger\"}]}", wire: "{\"entries\":[{\"binding\":{\"history\":\"mesh-knowledge_ledger\",\"indexes\":{\"by-kind\":\"mesh-knowledge_ledger_index-by-kind\"},\"local\":\"ledger\",\"objects\":\"mesh-knowledge_ledger_state-objects\",\"snapshot\":\"mesh.ledger.mesh-knowledge.ledger.snapshot\",\"state\":\"mesh-knowledge_ledger_state\",\"storage\":\"ledger\",\"subject\":\"mesh.ledger.mesh-knowledge.ledger.history\",\"template\":\"ledger\",\"types\":[{\"indexes\":[{\"name\":\"by-kind\",\"on\":[\"kind\"]}],\"name\":\"decision\",\"operations\":[{\"effect\":\"set-fields\",\"fields\":[\"title\",\"kind\"],\"name\":\"set\"}],\"schema\":{\"kind\":{\"type\":\"string\"},\"title\":{\"type\":\"string\"}}}]},\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"settings\":{\"max-mib\":64},\"storage-type\":\"ledger\",\"template\":\"ledger\"}]}",
decode: func(b []byte) (any, error) { var v ListAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "list answers the sum of the caps and both limits (design 47 G 661)", subject: "", given: "{\"caps\":{\"account-limit-mib\":1024,\"server-limit-mib\":2048,\"sum-mib\":512},\"entries\":[]}", wire: "{\"caps\":{\"account-limit-mib\":1024,\"server-limit-mib\":2048,\"sum-mib\":512},\"entries\":[]}",
decode: func(b []byte) (any, error) { var v ListAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "list answers a sum with no limit, which is unlimited", subject: "", given: "{\"caps\":{\"sum-mib\":64},\"entries\":[]}", wire: "{\"caps\":{\"sum-mib\":64},\"entries\":[]}",
decode: func(b []byte) (any, error) { var v ListAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "snapshot-get asks a snapshot by its request", subject: "", given: "{\"call\":\"0123456789abcdef0123456789abcdef\",\"request\":\"r-1\"}", wire: "{\"call\":\"0123456789abcdef0123456789abcdef\",\"request\":\"r-1\"}",
decode: func(b []byte) (any, error) { var v SnapshotGetInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "snapshot-get answers the fields and the chunks", subject: "", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"chunks\":2,\"digest\":\"sha256:00\",\"local\":\"ledger\",\"module\":\"mesh-knowledge\",\"request\":\"r-1\",\"size\":1048576,\"stream\":\"mesh-knowledge_ledger\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"chunks\":2,\"digest\":\"sha256:00\",\"local\":\"ledger\",\"module\":\"mesh-knowledge\",\"request\":\"r-1\",\"size\":1048576,\"stream\":\"mesh-knowledge_ledger\"}",
decode: func(b []byte) (any, error) { var v SnapshotGetAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "snapshot-get answers a protected snapshot refused", subject: "", given: "{\"error\":\"snapshot protected\"}", wire: "{\"error\":\"snapshot protected\"}",
decode: func(b []byte) (any, error) { var v SnapshotGetAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "snapshot-restore asks a verify", subject: "", given: "{\"request\":\"r-1\",\"verify\":true,\"why\":\"the file is read before the live data is set aside\"}", wire: "{\"request\":\"r-1\",\"verify\":true,\"why\":\"the file is read before the live data is set aside\"}",
decode: func(b []byte) (any, error) { var v SnapshotRestoreInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "snapshot-restore answers accepted with the act", subject: "", given: "{\"accepted\":\"a-20261111t100000\"}", wire: "{\"accepted\":\"a-20261111t100000\"}",
decode: func(b []byte) (any, error) { var v SnapshotRestoreAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "snapshot-restore answers busy with the act that runs", subject: "", given: "{\"busy\":\"a-20261111t095900\"}", wire: "{\"busy\":\"a-20261111t095900\"}",
decode: func(b []byte) (any, error) { var v SnapshotRestoreAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "snapshot-restore answers names live", subject: "", given: "{\"error\":\"names live\"}", wire: "{\"error\":\"names live\"}",
decode: func(b []byte) (any, error) { var v SnapshotRestoreAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "snapshot-restore-cancel names the act", subject: "", given: "{\"act\":\"a-20261111t100000\",\"why\":\"the restore passed its bound\"}", wire: "{\"act\":\"a-20261111t100000\",\"why\":\"the restore passed its bound\"}",
decode: func(b []byte) (any, error) {
var v SnapshotRestoreCancelInput
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "snapshot-restore-cancel answers accepted", subject: "", given: "{\"accepted\":\"a-20261111t100000\"}", wire: "{\"accepted\":\"a-20261111t100000\"}",
decode: func(b []byte) (any, error) {
var v SnapshotRestoreCancelAnswer
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "snapshot-remove names one snapshot", subject: "", given: "{\"request\":\"r-1\",\"why\":\"the data is restored\"}", wire: "{\"request\":\"r-1\",\"why\":\"the data is restored\"}",
decode: func(b []byte) (any, error) { var v SnapshotRemoveInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "snapshot-remove names every expired one", subject: "", given: "{\"expired\":true,\"why\":\"the days are past\"}", wire: "{\"expired\":true,\"why\":\"the days are past\"}",
decode: func(b []byte) (any, error) { var v SnapshotRemoveInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "snapshot-remove answers accepted", subject: "", given: "{\"accepted\":\"a-20261111t100000\"}", wire: "{\"accepted\":\"a-20261111t100000\"}",
decode: func(b []byte) (any, error) { var v SnapshotRemoveAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
+44 -7
View File
@@ -20,6 +20,7 @@ const (
VerbPropose = "propose"
VerbWithdraw = "withdraw"
VerbAgain = "again"
VerbPlacement = "placement"
)
const (
@@ -31,7 +32,7 @@ const (
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbAssignments, VerbProposals, VerbPropose, VerbWithdraw, VerbAgain}
return []string{VerbAssignments, VerbProposals, VerbPropose, VerbWithdraw, VerbAgain, VerbPlacement}
}
// Events is every event published on the seat's subject: a new copy each call.
@@ -343,6 +344,14 @@ func DecodeSeatHoldersBySeatNodeValue(raw []byte) (SeatHoldersBySeatNodeValue, e
return v, nil
}
// AddedModule is what the want a candidate would write for a module carries of its build, in the want's own forms (the seat mesh-wants' state wants: `version` and `parts`; copied here because a seat definition cannot reuse another repository's seat's forms, design 47 G A-316).
type AddedModule struct {
// the digest of each of the module's parts, by `<module>:<artifact>` (design 47 G section 379)
Parts map[string]string `json:"parts,omitempty"`
// the module's released version, for people; none for a build of another watched branch (design 47 G section 379)
Version string `json:"version,omitempty"`
}
// Assignments is one node's assignments assembled.
type Assignments struct {
Decided NodeDecided `json:"decided"`
@@ -401,6 +410,12 @@ type Holding struct {
Site string `json:"site,omitempty"`
}
// ModulePlacement is the nodes that run a module from one watched branch.
type ModulePlacement struct {
Branch string `json:"branch"`
Nodes []string `json:"nodes"`
}
// NodeDecided is what a person decides of a node; no secret and no key material.
type NodeDecided struct {
Account string `json:"account,omitempty"`
@@ -423,9 +438,13 @@ type NodeDecided struct {
// PlacedModule is one module placed on a node.
type PlacedModule struct {
// by provision, the provider each requirement that keeps data is bound to
Bindings map[string]Provider `json:"bindings,omitempty"`
HasLayer bool `json:"has-layer,omitempty"`
HasMeshWide bool `json:"has-mesh-wide,omitempty"`
Bindings map[string]Provider `json:"bindings,omitempty"`
// the watched branch this node runs the module from; absent, the first watched branch of the module's registration (design 47 G 14)
Branch string `json:"branch,omitempty"`
// the fingerprint of the build the node runs; absent, the newest delivered of the branch (design 47 G 78, 402)
Build string `json:"build,omitempty"`
HasLayer bool `json:"has-layer,omitempty"`
HasMeshWide bool `json:"has-mesh-wide,omitempty"`
// this node's settings layer of the module's assignments
Layer map[string]any `json:"layer,omitempty"`
// the whole mesh's settings layer of the module's assignments
@@ -475,9 +494,13 @@ type ProposalChangeKeys struct {
// ProposalChange is one change of a proposal.
type ProposalChange struct {
Bindings map[string]Provider `json:"bindings,omitempty"`
Claim string `json:"claim,omitempty"`
Decided *NodeDecided `json:"decided,omitempty"`
Field string `json:"field,omitempty"`
// for place, the watched branch the node runs the module from; absent, the first watched branch of the module's registration (design 47 G 14)
Branch string `json:"branch,omitempty"`
// for place, the build of that branch the node runs, a return to an earlier build being this one value; absent, the newest delivered of the branch (ADR 0666 section 24)
Build string `json:"build,omitempty"`
Claim string `json:"claim,omitempty"`
Decided *NodeDecided `json:"decided,omitempty"`
Field string `json:"field,omitempty"`
// the public halves of a joining node's keys
Keys *ProposalChangeKeys `json:"keys,omitempty"`
Kind string `json:"kind,omitempty"`
@@ -616,6 +639,18 @@ type AgainInput struct {
// AgainAnswer is what again answers.
type AgainAnswer = map[string]any
// PlacementInput is what placement takes.
type PlacementInput struct {
// the module
Module string `json:"module"`
}
// PlacementAnswer is what placement answers.
type PlacementAnswer struct {
// one per branch, the nodes that run the module from it
Placements []ModulePlacement `json:"placements"`
}
// AssignmentsProposedEvent is the body of the event assignments-proposed.
type AssignmentsProposedEvent = AssignmentsEvent
@@ -660,6 +695,8 @@ type ProposalsByProposalValue = Proposal
// CandidatesByProposalNodeValue is one value of the state candidates under the key <proposal>.<node>.
type CandidatesByProposalNodeValue struct {
// by module name, each module the candidate adds to this node without a want there: the `version` and `parts` the want it would write carries (design 47 G A-316); the node-engine builds such a module from this entry
Added map[string]AddedModule `json:"added,omitempty"`
// the node's assignments with the proposal laid over it; absent when the proposal takes its key away
Assignments *Assignments `json:"assignments,omitempty"`
Proposal string `json:"proposal"`
+13 -1
View File
@@ -41,13 +41,25 @@ func TestFixtures(t *testing.T) {
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a module's key on a watched branch and a build", subject: "", given: "{\"node\":\"home-server\",\"placed\":{\"branch\":\"beta\",\"build\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"plex\"},\"v\":1}", wire: "{\"node\":\"home-server\",\"placed\":{\"branch\":\"beta\",\"build\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"plex\"},\"v\":1}",
decode: func(b []byte) (any, error) {
var v AssignmentsByNodeModuleValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "an open proposal", subject: "", given: "{\"at\":\"2026-11-05T12:00:00Z\",\"base\":{\"ace\":3},\"by\":\"operator\",\"changes\":[{\"module\":\"plex\",\"node\":\"ace\",\"op\":\"place\",\"ports\":{\"32400\":32400}}],\"id\":\"p-20261105t120000-aabbccdd\",\"state\":\"answering\",\"why\":\"move plex\"}", wire: "{\"at\":\"2026-11-05T12:00:00Z\",\"base\":{\"ace\":3},\"by\":\"operator\",\"changes\":[{\"module\":\"plex\",\"node\":\"ace\",\"op\":\"place\",\"ports\":{\"32400\":32400}}],\"id\":\"p-20261105t120000-aabbccdd\",\"state\":\"answering\",\"why\":\"move plex\"}",
decode: func(b []byte) (any, error) {
var v ProposalsByProposalValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a candidate", subject: "", given: "{\"proposal\":\"p-20261105t120000-aabbccdd\",\"v\":1}", wire: "{\"proposal\":\"p-20261105t120000-aabbccdd\",\"v\":1}",
{name: "a proposal placing a module on a watched branch at an earlier build", subject: "", given: "{\"at\":\"2026-11-10T12:00:00Z\",\"base\":{\"home-server\":3},\"by\":\"operator\",\"changes\":[{\"branch\":\"beta\",\"build\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"nats\",\"node\":\"home-server\",\"op\":\"place\"}],\"id\":\"p-20261110t120000-aabbccdd\",\"state\":\"answering\",\"why\":\"run nats from beta, back one build\"}", wire: "{\"at\":\"2026-11-10T12:00:00Z\",\"base\":{\"home-server\":3},\"by\":\"operator\",\"changes\":[{\"branch\":\"beta\",\"build\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"nats\",\"node\":\"home-server\",\"op\":\"place\"}],\"id\":\"p-20261110t120000-aabbccdd\",\"state\":\"answering\",\"why\":\"run nats from beta, back one build\"}",
decode: func(b []byte) (any, error) {
var v ProposalsByProposalValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a candidate, with the modules it adds and what their wants would carry", subject: "", given: "{\"added\":{\"mesh-build-go\":{\"parts\":{\"mesh-build-go:go-binary\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"},\"version\":\"1.4.0\"}},\"proposal\":\"p-20261105t120000-aabbccdd\",\"v\":1}", wire: "{\"added\":{\"mesh-build-go\":{\"parts\":{\"mesh-build-go:go-binary\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"},\"version\":\"1.4.0\"}},\"proposal\":\"p-20261105t120000-aabbccdd\",\"v\":1}",
decode: func(b []byte) (any, error) {
var v CandidatesByProposalNodeValue
err := json.Unmarshal(b, &v)
+551
View File
@@ -0,0 +1,551 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// Package meshrecovery is the contract of the seat "mesh-recovery", defined whole (seats/mesh-recovery/seat.json): Takes, sets aside and restores a module's kept data on the live bus, each act in the hand-act log (design 47 G 554). Its verbs answer at once and the result is the event.
package meshrecovery
import "time"
// Seat is the seat's name.
const Seat = "mesh-recovery"
const (
VerbSnapshotKept = "snapshot-kept"
VerbRestoreKept = "restore-kept"
VerbKeptPoints = "kept-points"
VerbRestoreAside = "restore-aside"
VerbCancel = "cancel"
VerbTake = "take"
VerbRestore = "restore"
VerbRetry = "retry"
VerbAside = "aside"
VerbDiscardAside = "discard-aside"
VerbExpirePoints = "expire-points"
)
const (
EventEnded = "ended"
EventRestoreStarted = "restore-started"
EventRestored = "restored"
EventSetAside = "set-aside"
EventAsideDiscarded = "aside-discarded"
EventPointRemoved = "point-removed"
EventExpiryEnded = "expiry-ended"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbSnapshotKept, VerbRestoreKept, VerbKeptPoints, VerbRestoreAside, VerbCancel, VerbTake, VerbRestore, VerbRetry, VerbAside, VerbDiscardAside, VerbExpirePoints}
}
// Events is every event published on the seat's subject: a new copy each call.
func Events() []string {
return []string{EventEnded, EventRestoreStarted, EventRestored, EventSetAside, EventAsideDiscarded, EventPointRemoved, EventExpiryEnded}
}
// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects.
const (
Family = "mesh-recovery.events"
FamilyMaxAgeDays = 7
)
// StreamEnded is the stream ended is kept in.
const StreamEnded = "SEAT_mesh-recovery_ended"
// SubjectEnded is where ended is published, on mesh.seat.mesh-recovery.event.ended.<module>.<kept>.
func SubjectEnded(module, kept string) string {
return "mesh.seat.mesh-recovery.event.ended." + module + "." + kept
}
// SubjectEndedAll hears every ended.
const SubjectEndedAll = "mesh.seat.mesh-recovery.event.ended.*.*"
// StreamRestoreStarted is the stream restore-started is kept in.
const StreamRestoreStarted = "SEAT_mesh-recovery_restore-started"
// SubjectRestoreStarted is where restore-started is published, on mesh.seat.mesh-recovery.event.restore-started.<module>.<kept>.
func SubjectRestoreStarted(module, kept string) string {
return "mesh.seat.mesh-recovery.event.restore-started." + module + "." + kept
}
// SubjectRestoreStartedAll hears every restore-started.
const SubjectRestoreStartedAll = "mesh.seat.mesh-recovery.event.restore-started.*.*"
// StreamRestored is the stream restored is kept in.
const StreamRestored = "SEAT_mesh-recovery_restored"
// SubjectRestored is where restored is published, on mesh.seat.mesh-recovery.event.restored.<module>.<kept>.
func SubjectRestored(module, kept string) string {
return "mesh.seat.mesh-recovery.event.restored." + module + "." + kept
}
// SubjectRestoredAll hears every restored.
const SubjectRestoredAll = "mesh.seat.mesh-recovery.event.restored.*.*"
// StreamSetAside is the stream set-aside is kept in.
const StreamSetAside = "SEAT_mesh-recovery_set-aside"
// SubjectSetAside is where set-aside is published, on mesh.seat.mesh-recovery.event.set-aside.<module>.<kept>.
func SubjectSetAside(module, kept string) string {
return "mesh.seat.mesh-recovery.event.set-aside." + module + "." + kept
}
// SubjectSetAsideAll hears every set-aside.
const SubjectSetAsideAll = "mesh.seat.mesh-recovery.event.set-aside.*.*"
// StreamAsideDiscarded is the stream aside-discarded is kept in.
const StreamAsideDiscarded = "SEAT_mesh-recovery_aside-discarded"
// SubjectAsideDiscarded is where aside-discarded is published, on mesh.seat.mesh-recovery.event.aside-discarded.<module>.<kept>.
func SubjectAsideDiscarded(module, kept string) string {
return "mesh.seat.mesh-recovery.event.aside-discarded." + module + "." + kept
}
// SubjectAsideDiscardedAll hears every aside-discarded.
const SubjectAsideDiscardedAll = "mesh.seat.mesh-recovery.event.aside-discarded.*.*"
// StreamPointRemoved is the stream point-removed is kept in.
const StreamPointRemoved = "SEAT_mesh-recovery_point-removed"
// SubjectPointRemoved is where point-removed is published, on mesh.seat.mesh-recovery.event.point-removed.<module>.<kept>.
func SubjectPointRemoved(module, kept string) string {
return "mesh.seat.mesh-recovery.event.point-removed." + module + "." + kept
}
// SubjectPointRemovedAll hears every point-removed.
const SubjectPointRemovedAll = "mesh.seat.mesh-recovery.event.point-removed.*.*"
// StreamExpiryEnded is the stream expiry-ended is kept in.
const StreamExpiryEnded = "SEAT_mesh-recovery_expiry-ended"
// SubjectExpiryEnded is where expiry-ended is published.
const SubjectExpiryEnded = "mesh.seat.mesh-recovery.event.expiry-ended"
// Aside is the live data set aside before a restore: a directory under aside/ in the recovery module's directory, nothing of it on the bus (design 47 G 516).
type Aside struct {
// the directory's name
ID string `json:"id"`
// the bus names it was live under, one per bus object
Names []string `json:"names"`
// its bytes on disk
Size int64 `json:"size"`
}
// CatchUp is the catch-up of the newer manifest: a tool and its arguments, never text (design 47 G 451, 516, 631).
type CatchUp struct {
Arguments map[string]any `json:"arguments,omitempty"`
Tool string `json:"tool"`
}
// Consumer is one durable consumer of the kept data and the sequence it had acknowledged.
type Consumer struct {
Name string `json:"name"`
Sequence int64 `json:"sequence"`
Stream string `json:"stream"`
}
// Digest is the digest of one object of a point's bytes.
type Digest struct {
Digest string `json:"digest"`
Name string `json:"name"`
}
// Point is a restore point: the kept data whole and its consumers' positions, in the recovery module's points directory (design 47 G 516, 560).
type Point struct {
// when it was taken, RFC 3339
At time.Time `json:"at"`
CatchUp *CatchUp `json:"catch-up,omitempty"`
Consumers []Consumer `json:"consumers,omitempty"`
// the digest of each object's bytes, checked before a restore (design 47 G 567)
Digests []Digest `json:"digests,omitempty"`
// the fingerprint it was taken before
Fingerprint string `json:"fingerprint"`
// its form, the number the holder raises when it changes how it writes it (0 when undeclared)
Form int64 `json:"form"`
// the kept data, its local name in the module's manifest
Kept string `json:"kept"`
// the module
Module string `json:"module"`
// the bus names it took, one per bus object (design 47 G A-230)
Names []string `json:"names"`
// its bytes
Size int64 `json:"size"`
// the point's name, also its directory's
Snapshot string `json:"snapshot"`
}
// Running is the act that runs, since when and what it waits on (design 47 G 517, 554).
type Running struct {
Act string `json:"act"`
Since time.Time `json:"since"`
Step string `json:"step,omitempty"`
// what it waits on, when it waits
WaitsOn string `json:"waits-on,omitempty"`
}
// SnapshotKeptInput is what snapshot-kept takes.
type SnapshotKeptInput struct {
CatchUp *CatchUp `json:"catch-up,omitempty"`
// the fingerprint the restore point is taken before, or reverted from
Fingerprint string `json:"fingerprint"`
// its form, the number the holder raises when it changes how it writes it (0 when undeclared)
Form int64 `json:"form"`
// the kept data, its local name in the module's manifest
Kept string `json:"kept"`
// the module
Module string `json:"module"`
// why, which the hand-act log keeps
Why string `json:"why"`
}
// SnapshotKeptAnswer is what snapshot-kept answers.
type SnapshotKeptAnswer struct {
// accepted: the act's id, which the ending event carries
Accepted string `json:"accepted,omitempty"`
// busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event
Busy string `json:"busy,omitempty"`
// why it was not taken; set alone
Error string `json:"error,omitempty"`
}
// RestoreKeptInput is what restore-kept takes.
type RestoreKeptInput struct {
// the fingerprint the restore point is taken before, or reverted from
Fingerprint string `json:"fingerprint"`
// its form, the number the holder raises when it changes how it writes it (0 when undeclared)
Form int64 `json:"form"`
// ask the backup holder for the points directory when the point is missing there (design 47 G 516)
FromBackup bool `json:"from-backup,omitempty"`
// the kept data, its local name in the module's manifest
Kept string `json:"kept"`
// the module
Module string `json:"module"`
// the restore point's name
Snapshot string `json:"snapshot,omitempty"`
// why, which the hand-act log keeps
Why string `json:"why"`
}
// RestoreKeptAnswer is what restore-kept answers.
type RestoreKeptAnswer struct {
// accepted: the act's id, which the ending event carries
Accepted string `json:"accepted,omitempty"`
// busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event
Busy string `json:"busy,omitempty"`
// why it was not taken; set alone
Error string `json:"error,omitempty"`
}
// KeptPointsInput is what kept-points takes.
type KeptPointsInput struct {
// one kept data (optional)
Kept string `json:"kept,omitempty"`
// one module (optional)
Module string `json:"module,omitempty"`
}
// KeptPointsAnswer is what kept-points answers.
type KeptPointsAnswer struct {
Asides []Aside `json:"asides"`
Points []Point `json:"points"`
Running *Running `json:"running,omitempty"`
// the asides whose record ended at removed that no running act holds: the live data of those names is gone and only the aside holds it; the module's health check fails while one is listed (design 47 G 554, 657, A-129)
Unrestored []Aside `json:"unrestored"`
}
// RestoreAsideInput is what restore-aside takes.
type RestoreAsideInput struct {
// who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)
Asker string `json:"asker,omitempty"`
// the aside's id
ID string `json:"id"`
// the kept data, its local name in the module's manifest
Kept string `json:"kept"`
// the module
Module string `json:"module"`
// why, which the hand-act log keeps
Why string `json:"why"`
}
// RestoreAsideAnswer is what restore-aside answers.
type RestoreAsideAnswer struct {
// accepted: the act's id, which the ending event carries
Accepted string `json:"accepted,omitempty"`
// busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event
Busy string `json:"busy,omitempty"`
// why it was not taken; set alone
Error string `json:"error,omitempty"`
}
// CancelInput is what cancel takes.
type CancelInput struct {
// the act's id
Act string `json:"act"`
// who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)
Asker string `json:"asker,omitempty"`
// why, which the hand-act log keeps
Why string `json:"why"`
}
// CancelAnswer is what cancel answers.
type CancelAnswer struct {
// accepted: the id of the act it cancelled, whose ending event follows under that id
Accepted string `json:"accepted,omitempty"`
// busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event
Busy string `json:"busy,omitempty"`
// why not, naming the step an act has begun; set alone
Error string `json:"error,omitempty"`
}
// TakeInput is what take takes.
type TakeInput struct {
// who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)
Asker string `json:"asker,omitempty"`
// the fingerprint whose form the point is taken at
Fingerprint string `json:"fingerprint"`
// the kept data, its local name in the module's manifest
Kept string `json:"kept"`
// the module
Module string `json:"module"`
// why, which the hand-act log keeps
Why string `json:"why"`
}
// TakeAnswer is what take answers.
type TakeAnswer struct {
// accepted: the act's id, which the ending event carries
Accepted string `json:"accepted,omitempty"`
// busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event
Busy string `json:"busy,omitempty"`
// why it was not taken; set alone
Error string `json:"error,omitempty"`
}
// RestoreInput is what restore takes.
type RestoreInput struct {
// who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)
Asker string `json:"asker,omitempty"`
// ask the backup holder for the points directory when the point is missing there; only with snapshot
FromBackup bool `json:"from-backup,omitempty"`
// the kept data, its local name in the module's manifest
Kept string `json:"kept"`
// the module
Module string `json:"module"`
// a keeper's snapshot by its request (design 47 G 681)
Request string `json:"request,omitempty"`
// a restore point's name
Snapshot string `json:"snapshot,omitempty"`
// why, which the hand-act log keeps
Why string `json:"why"`
}
// RestoreAnswer is what restore answers.
type RestoreAnswer struct {
// accepted: the act's id, which the ending event carries
Accepted string `json:"accepted,omitempty"`
// busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event
Busy string `json:"busy,omitempty"`
// why it was not taken; set alone
Error string `json:"error,omitempty"`
}
// RetryInput is what retry takes.
type RetryInput struct {
// who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)
Asker string `json:"asker,omitempty"`
// the kept data, its local name in the module's manifest
Kept string `json:"kept"`
// the module
Module string `json:"module"`
// why, which the hand-act log keeps
Why string `json:"why"`
}
// RetryAnswer is what retry answers.
type RetryAnswer struct {
// accepted: the act's id, which the ending event carries
Accepted string `json:"accepted,omitempty"`
// busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event
Busy string `json:"busy,omitempty"`
// why it was not taken; set alone
Error string `json:"error,omitempty"`
}
// AsideInput is what aside takes.
type AsideInput struct {
// who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)
Asker string `json:"asker,omitempty"`
// the kept data, its local name in the module's manifest
Kept string `json:"kept"`
// the module
Module string `json:"module"`
// why, which the hand-act log keeps
Why string `json:"why"`
}
// AsideAnswer is what aside answers.
type AsideAnswer struct {
// accepted: the act's id, which the ending event carries
Accepted string `json:"accepted,omitempty"`
// busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event
Busy string `json:"busy,omitempty"`
// why it was not taken; set alone
Error string `json:"error,omitempty"`
}
// DiscardAsideInput is what discard-aside takes.
type DiscardAsideInput struct {
// who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)
Asker string `json:"asker,omitempty"`
// the aside's id
ID string `json:"id"`
// the kept data, its local name in the module's manifest
Kept string `json:"kept"`
// the module
Module string `json:"module"`
// why, which the hand-act log keeps
Why string `json:"why"`
}
// DiscardAsideAnswer is what discard-aside answers.
type DiscardAsideAnswer struct {
// accepted: the act's id, which the ending event carries
Accepted string `json:"accepted,omitempty"`
// busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event
Busy string `json:"busy,omitempty"`
// why it was not taken; set alone
Error string `json:"error,omitempty"`
}
// ExpirePointsInput is what expire-points takes.
type ExpirePointsInput struct {
// who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)
Asker string `json:"asker,omitempty"`
// why, which the hand-act log keeps
Why string `json:"why"`
}
// ExpirePointsAnswer is what expire-points answers.
type ExpirePointsAnswer struct {
// accepted: the act's id, which the ending event carries
Accepted string `json:"accepted,omitempty"`
// busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event
Busy string `json:"busy,omitempty"`
// why it was not taken; set alone
Error string `json:"error,omitempty"`
}
// EndedEvent is the body of the event ended.
type EndedEvent struct {
// the id the act was answered accepted with, or a hand act's own id (design 47 G 560)
Act string `json:"act"`
// when it was said, RFC 3339
At time.Time `json:"at"`
CatchUp *CatchUp `json:"catch-up,omitempty"`
Consumers []Consumer `json:"consumers,omitempty"`
Digests []Digest `json:"digests,omitempty"`
// when failed
Error string `json:"error,omitempty"`
Fingerprint string `json:"fingerprint,omitempty"`
Form int64 `json:"form,omitempty"`
Kept string `json:"kept"`
Module string `json:"module"`
// how the act ended
Outcome string `json:"outcome"`
Size int64 `json:"size,omitempty"`
Snapshot string `json:"snapshot,omitempty"`
// the words of the hand act that ended it, for a cancel (design 47 G A-117, 560)
Why string `json:"why,omitempty"`
}
// The values of EndedEvent's outcome.
const (
EndedEventOutcomeDone = "done"
EndedEventOutcomeFailed = "failed"
)
// RestoreStartedEvent is the body of the event restore-started.
type RestoreStartedEvent struct {
// the id the act was answered accepted with, or a hand act's own id (design 47 G 560)
Act string `json:"act"`
// when it was said, RFC 3339
At time.Time `json:"at"`
Fingerprint string `json:"fingerprint,omitempty"`
Form int64 `json:"form,omitempty"`
Kept string `json:"kept"`
Module string `json:"module"`
Snapshot string `json:"snapshot,omitempty"`
}
// RestoredEvent is the body of the event restored.
type RestoredEvent struct {
// the id the act was answered accepted with, or a hand act's own id (design 47 G 560)
Act string `json:"act"`
Aside *Aside `json:"aside,omitempty"`
// when it was said, RFC 3339
At time.Time `json:"at"`
Error string `json:"error,omitempty"`
Fingerprint string `json:"fingerprint,omitempty"`
Form int64 `json:"form,omitempty"`
Kept string `json:"kept"`
// the point is not in the recovery module's directory
Missing bool `json:"missing,omitempty"`
Module string `json:"module"`
// how the act ended
Outcome string `json:"outcome"`
Snapshot string `json:"snapshot,omitempty"`
// the words of the hand act that ended it, for a cancel (design 47 G A-117, 560)
Why string `json:"why,omitempty"`
}
// The values of RestoredEvent's outcome.
const (
RestoredEventOutcomeDone = "done"
RestoredEventOutcomeFailed = "failed"
)
// SetAsideEvent is the body of the event set-aside.
type SetAsideEvent struct {
// the id the act was answered accepted with, or a hand act's own id (design 47 G 560)
Act string `json:"act"`
// when it was said, RFC 3339
At time.Time `json:"at"`
ID string `json:"id"`
// the bus names it was live under, one per bus object
Names []string `json:"names"`
Size int64 `json:"size"`
}
// AsideDiscardedEvent is the body of the event aside-discarded.
type AsideDiscardedEvent struct {
// the id the act was answered accepted with, or a hand act's own id (design 47 G 560)
Act string `json:"act"`
// when it was said, RFC 3339
At time.Time `json:"at"`
ID string `json:"id"`
// the bus names it was live under, one per bus object
Names []string `json:"names"`
Size int64 `json:"size"`
}
// PointRemovedEvent is the body of the event point-removed.
type PointRemovedEvent struct {
// the id the act was answered accepted with, or a hand act's own id (design 47 G 560)
Act string `json:"act"`
// when it was said, RFC 3339
At time.Time `json:"at"`
Fingerprint string `json:"fingerprint,omitempty"`
Form int64 `json:"form,omitempty"`
Kept string `json:"kept"`
Module string `json:"module"`
Snapshot string `json:"snapshot,omitempty"`
}
// ExpiryEndedEvent is the body of the event expiry-ended.
type ExpiryEndedEvent struct {
// the id the act was answered accepted with, or a hand act's own id (design 47 G 560)
Act string `json:"act"`
// when it was said, RFC 3339
At time.Time `json:"at"`
// the number of points the run removed, 0 included
Removed int64 `json:"removed"`
}
+112
View File
@@ -0,0 +1,112 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
package meshrecovery
import (
"encoding/json"
"reflect"
"regexp"
"testing"
)
// TestFixtures reads every fixture of seats/mesh-recovery/fixtures: each decodes into its type, a field the type does not
// know is dropped (ADR 0608 §6), and it reads back as its wire says; each subject named is the contract's.
func TestFixtures(t *testing.T) {
cases := []struct {
name, subject, given, wire string
decode func([]byte) (any, error)
subjectIs *regexp.Regexp
}{
{name: "ended is said", subject: "mesh.seat.mesh-recovery.event.ended.mesh-knowledge.ledger", given: "{\"act\":\"a-1\",\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"outcome\":\"done\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}", wire: "{\"act\":\"a-1\",\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"outcome\":\"done\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}",
decode: func(b []byte) (any, error) { var v EndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.ended\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "ended is said", subject: "mesh.seat.mesh-recovery.event.ended.mesh-knowledge.ledger", given: "{\"act\":\"a-2\",\"at\":\"2026-11-11T10:00:00Z\",\"error\":\"stopped\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"outcome\":\"failed\"}", wire: "{\"act\":\"a-2\",\"at\":\"2026-11-11T10:00:00Z\",\"error\":\"stopped\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"outcome\":\"failed\"}",
decode: func(b []byte) (any, error) { var v EndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.ended\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "restore-started is said", subject: "mesh.seat.mesh-recovery.event.restore-started.mesh-knowledge.ledger", given: "{\"act\":\"a-3\",\"at\":\"2026-11-11T10:00:00Z\",\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"2-0123456789ab\"}", wire: "{\"act\":\"a-3\",\"at\":\"2026-11-11T10:00:00Z\",\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"2-0123456789ab\"}",
decode: func(b []byte) (any, error) { var v RestoreStartedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.restore-started\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "restored is said", subject: "mesh.seat.mesh-recovery.event.restored.mesh-knowledge.ledger", given: "{\"act\":\"a-3\",\"at\":\"2026-11-11T10:00:00Z\",\"error\":\"restore point missing\",\"kept\":\"ledger\",\"missing\":true,\"module\":\"mesh-knowledge\",\"outcome\":\"failed\"}", wire: "{\"act\":\"a-3\",\"at\":\"2026-11-11T10:00:00Z\",\"error\":\"restore point missing\",\"kept\":\"ledger\",\"missing\":true,\"module\":\"mesh-knowledge\",\"outcome\":\"failed\"}",
decode: func(b []byte) (any, error) { var v RestoredEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.restored\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "a cancelled act says the hand act's why", subject: "mesh.seat.mesh-recovery.event.restored.mesh-knowledge.ledger", given: "{\"act\":\"a-4\",\"at\":\"2026-11-11T10:00:00Z\",\"error\":\"cancelled\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"outcome\":\"failed\",\"why\":\"the operator stopped it to look at the disk\"}", wire: "{\"act\":\"a-4\",\"at\":\"2026-11-11T10:00:00Z\",\"error\":\"cancelled\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"outcome\":\"failed\",\"why\":\"the operator stopped it to look at the disk\"}",
decode: func(b []byte) (any, error) { var v RestoredEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.restored\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "set-aside is said", subject: "mesh.seat.mesh-recovery.event.set-aside.mesh-knowledge.ledger", given: "{\"act\":\"a-4\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}", wire: "{\"act\":\"a-4\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}",
decode: func(b []byte) (any, error) { var v SetAsideEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.set-aside\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "aside-discarded is said", subject: "mesh.seat.mesh-recovery.event.aside-discarded.mesh-knowledge.ledger", given: "{\"act\":\"a-5\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}", wire: "{\"act\":\"a-5\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}",
decode: func(b []byte) (any, error) { var v AsideDiscardedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.aside-discarded\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "point-removed is said", subject: "mesh.seat.mesh-recovery.event.point-removed.mesh-knowledge.ledger", given: "{\"act\":\"a-6\",\"at\":\"2026-11-11T10:00:00Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"1-aaaaaaaaaaaa\"}", wire: "{\"act\":\"a-6\",\"at\":\"2026-11-11T10:00:00Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"1-aaaaaaaaaaaa\"}",
decode: func(b []byte) (any, error) { var v PointRemovedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.point-removed\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "expiry-ended says 0 when it removed nothing", subject: "mesh.seat.mesh-recovery.event.expiry-ended", given: "{\"act\":\"a-7\",\"at\":\"2026-11-11T10:00:00Z\",\"removed\":0}", wire: "{\"act\":\"a-7\",\"at\":\"2026-11-11T10:00:00Z\",\"removed\":0}",
decode: func(b []byte) (any, error) { var v ExpiryEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.expiry-ended$")},
{name: "snapshot-kept takes the point of a kept data before its form changes", subject: "", given: "{\"catch-up\":{\"arguments\":{\"since\":\"0\"},\"tool\":\"knowledge_catch_up\"},\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"form change of mesh-knowledge's ledger to 0123456789ab\"}", wire: "{\"catch-up\":{\"arguments\":{\"since\":\"0\"},\"tool\":\"knowledge_catch_up\"},\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"form change of mesh-knowledge's ledger to 0123456789ab\"}",
decode: func(b []byte) (any, error) { var v SnapshotKeptInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "snapshot-kept answers accepted with the act", subject: "", given: "{\"accepted\":\"a-20261111t100000\"}", wire: "{\"accepted\":\"a-20261111t100000\"}",
decode: func(b []byte) (any, error) { var v SnapshotKeptAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "restore-kept answers busy with the act that runs", subject: "", given: "{\"busy\":\"a-20261111t100000\"}", wire: "{\"busy\":\"a-20261111t100000\"}",
decode: func(b []byte) (any, error) { var v RestoreKeptAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "restore-kept takes a point and asks the backup for its directory", subject: "", given: "{\"fingerprint\":\"0123456789ab\",\"form\":2,\"from-backup\":true,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"2-0123456789ab\",\"why\":\"revert of mesh-knowledge's ledger from 0123456789ab\"}", wire: "{\"fingerprint\":\"0123456789ab\",\"form\":2,\"from-backup\":true,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"2-0123456789ab\",\"why\":\"revert of mesh-knowledge's ledger from 0123456789ab\"}",
decode: func(b []byte) (any, error) { var v RestoreKeptInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "restore-kept answers an error naming why", subject: "", given: "{\"error\":\"aside-only is the operator's hand tool alone\"}", wire: "{\"error\":\"aside-only is the operator's hand tool alone\"}",
decode: func(b []byte) (any, error) { var v RestoreKeptAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "kept-points lists a point, an aside and the act that runs", subject: "", given: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"},\"unrestored\":[{\"id\":\"20261110T080000Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":1024}]}", wire: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"},\"unrestored\":[{\"id\":\"20261110T080000Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":1024}]}",
decode: func(b []byte) (any, error) { var v KeptPointsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "restore-aside names the aside", subject: "", given: "{\"asker\":\"operator@workstation\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"an aside left at removed\"}", wire: "{\"asker\":\"operator@workstation\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"an aside left at removed\"}",
decode: func(b []byte) (any, error) { var v RestoreAsideInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "cancel names the act", subject: "", given: "{\"act\":\"a-1\",\"asker\":\"operator@workstation\",\"why\":\"the dump waits too long\"}", wire: "{\"act\":\"a-1\",\"asker\":\"operator@workstation\",\"why\":\"the dump waits too long\"}",
decode: func(b []byte) (any, error) { var v CancelInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "take names the fingerprint whose form the point is taken at", subject: "", given: "{\"asker\":\"operator@workstation\",\"fingerprint\":\"0123456789ab\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"operator@workstation\",\"fingerprint\":\"0123456789ab\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}",
decode: func(b []byte) (any, error) { var v TakeInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "take answers accepted with the act", subject: "", given: "{\"accepted\":\"a-20261111t100000\"}", wire: "{\"accepted\":\"a-20261111t100000\"}",
decode: func(b []byte) (any, error) { var v TakeAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "restore takes a point by its name", subject: "", given: "{\"asker\":\"operator@workstation\",\"from-backup\":true,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"2-0123456789ab\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"operator@workstation\",\"from-backup\":true,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"2-0123456789ab\",\"why\":\"the operator's hand act\"}",
decode: func(b []byte) (any, error) { var v RestoreInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "restore takes a keeper's snapshot by its request", subject: "", given: "{\"asker\":\"operator@workstation\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"request\":\"r-20261111t100000\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"operator@workstation\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"request\":\"r-20261111t100000\",\"why\":\"the operator's hand act\"}",
decode: func(b []byte) (any, error) { var v RestoreInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "restore answers busy with the act that runs", subject: "", given: "{\"busy\":\"a-20261111t100000\"}", wire: "{\"busy\":\"a-20261111t100000\"}",
decode: func(b []byte) (any, error) { var v RestoreAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "retry names the module and its kept data", subject: "", given: "{\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"a failed take\"}", wire: "{\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"a failed take\"}",
decode: func(b []byte) (any, error) { var v RetryInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "retry answers an error when nothing failed", subject: "", given: "{\"error\":\"nothing to retry\"}", wire: "{\"error\":\"nothing to retry\"}",
decode: func(b []byte) (any, error) { var v RetryAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "aside sets the live kept data aside", subject: "", given: "{\"asker\":\"operator@workstation\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"operator@workstation\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}",
decode: func(b []byte) (any, error) { var v AsideInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "aside answers accepted with the act", subject: "", given: "{\"accepted\":\"a-20261111t100000\"}", wire: "{\"accepted\":\"a-20261111t100000\"}",
decode: func(b []byte) (any, error) { var v AsideAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "discard-aside names the aside", subject: "", given: "{\"asker\":\"operator@workstation\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"operator@workstation\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}",
decode: func(b []byte) (any, error) { var v DiscardAsideInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "discard-aside answers an error", subject: "", given: "{\"error\":\"no such aside\"}", wire: "{\"error\":\"no such aside\"}",
decode: func(b []byte) (any, error) { var v DiscardAsideAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "expire-points has no field of its own", subject: "", given: "{\"asker\":\"operator\",\"why\":\"the points past 90 days\"}", wire: "{\"asker\":\"operator\",\"why\":\"the points past 90 days\"}",
decode: func(b []byte) (any, error) { var v ExpirePointsInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "expire-points answers accepted with the act", subject: "", given: "{\"accepted\":\"a-20261111t100000\"}", wire: "{\"accepted\":\"a-20261111t100000\"}",
decode: func(b []byte) (any, error) { var v ExpirePointsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "cancel answers accepted with the act it cancelled", subject: "", given: "{\"accepted\":\"a-1\"}", wire: "{\"accepted\":\"a-1\"}",
decode: func(b []byte) (any, error) { var v CancelAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "cancel answers an error naming the step an act has begun", subject: "", given: "{\"error\":\"the act has begun: step restoring\"}", wire: "{\"error\":\"the act has begun: step restoring\"}",
decode: func(b []byte) (any, error) { var v CancelAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "cancel answers busy with the act that runs", subject: "", given: "{\"busy\":\"a-20261111t100000\"}", wire: "{\"busy\":\"a-20261111t100000\"}",
decode: func(b []byte) (any, error) { var v CancelAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
if err != nil {
t.Errorf("%s: does not decode: %v", c.name, err)
continue
}
back, err := json.Marshal(v)
if err != nil {
t.Errorf("%s: does not encode: %v", c.name, err)
continue
}
var got, want any
if err := json.Unmarshal(back, &got); err != nil {
t.Fatal(err)
}
if err := json.Unmarshal([]byte(c.wire), &want); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(got, want) {
t.Errorf("%s: reads back as %s, want %s", c.name, back, c.wire)
}
if c.subjectIs != nil && !c.subjectIs.MatchString(c.subject) {
t.Errorf("%s: subject %q is not the contract's %s", c.name, c.subject, c.subjectIs)
}
}
}
+3
View File
@@ -0,0 +1,3 @@
module git.novox.be/novox/mesh-contracts/go/seats/meshrecovery
go 1.26.0
+341 -8
View File
@@ -1,6 +1,6 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// Package nodeengine is the contract of the seat "node-engine", defined whole (seats/node-engine/seat.json): The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 §3, §4): its hand acts on the operator's warrant, its read-only judgements, its compositions and what it reads of a manifest. Each verb is answered on this node's subject, mesh.seat.node-engine.tool.<verb>.<node>, and each event is published on mesh.seat.node-engine.event.<event>.<node>, the node's name its last token.
// Package nodeengine is the contract of the seat "node-engine", defined whole (seats/node-engine/seat.json): The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 §3, §4): its hand acts on the operator's warrant, its read-only judgements, its compositions and what it reads of a manifest. Each verb is answered on this node's subject, mesh.seat.node-engine.tool.<verb>.<node>, and each event is published on mesh.seat.node-engine.event.<event>.<node>, the node's name its last token, or, for an event whose subject names <node>, there (composed.<node>, running.<node>.<module>): the grants part grants a node's account only its own node's subjects (ADR 0363 §2).
package nodeengine
import (
@@ -28,6 +28,10 @@ const (
VerbManifestReads = "manifest-reads"
VerbSeatList = "seat-list"
VerbSeatListAgain = "seat-list-again"
VerbFirstViews = "first-views"
VerbFirstViewAgain = "first-view-again"
VerbEntryAgain = "entry-again"
VerbProcessBuilds = "process-builds"
)
const (
@@ -35,16 +39,20 @@ const (
EventDone = "done"
EventRefused = "refused"
EventManifestReadsChanged = "manifest-reads-changed"
EventComposed = "composed"
EventRunning = "running"
EventWaitHeld = "wait-held"
EventWaitEnded = "wait-ended"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbHandOver, VerbAccessAct, VerbJudgeDirectories, VerbSetuidSearch, VerbRootFree, VerbActs, VerbPackages, VerbComposition, VerbCompose, VerbComposeCandidate, VerbManifestReads, VerbSeatList, VerbSeatListAgain}
return []string{VerbHandOver, VerbAccessAct, VerbJudgeDirectories, VerbSetuidSearch, VerbRootFree, VerbActs, VerbPackages, VerbComposition, VerbCompose, VerbComposeCandidate, VerbManifestReads, VerbSeatList, VerbSeatListAgain, VerbFirstViews, VerbFirstViewAgain, VerbEntryAgain, VerbProcessBuilds}
}
// Events is every event published on the seat's subject: a new copy each call.
func Events() []string {
return []string{EventAsked, EventDone, EventRefused, EventManifestReadsChanged}
return []string{EventAsked, EventDone, EventRefused, EventManifestReadsChanged, EventComposed, EventRunning, EventWaitHeld, EventWaitEnded}
}
// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects.
@@ -67,6 +75,45 @@ func SubjectManifestReadsChanged(caller string) string {
return "mesh.seat.node-engine.event.manifest-reads-changed." + caller
}
// SubjectComposed is where composed is published, on mesh.seat.node-engine.event.composed.<node>.
func SubjectComposed(node string) string { return "mesh.seat.node-engine.event.composed." + node }
// SubjectComposedAll hears every composed.
const SubjectComposedAll = "mesh.seat.node-engine.event.composed.*"
// StreamRunning is the stream running is kept in.
const StreamRunning = "SEAT_node-engine_running"
// SubjectRunning is where running is published, on mesh.seat.node-engine.event.running.<node>.<module>.
func SubjectRunning(node, module string) string {
return "mesh.seat.node-engine.event.running." + node + "." + module
}
// SubjectRunningAll hears every running.
const SubjectRunningAll = "mesh.seat.node-engine.event.running.*.*"
// StreamWaitHeld is the stream wait-held is kept in.
const StreamWaitHeld = "SEAT_node-engine_wait-held"
// SubjectWaitHeld is where wait-held is published, on mesh.seat.node-engine.event.wait-held.<node>.<module>.
func SubjectWaitHeld(node, module string) string {
return "mesh.seat.node-engine.event.wait-held." + node + "." + module
}
// SubjectWaitHeldAll hears every wait-held.
const SubjectWaitHeldAll = "mesh.seat.node-engine.event.wait-held.*.*"
// StreamWaitEnded is the stream wait-ended is kept in.
const StreamWaitEnded = "SEAT_node-engine_wait-ended"
// SubjectWaitEnded is where wait-ended is published, on mesh.seat.node-engine.event.wait-ended.<node>.<module>.
func SubjectWaitEnded(node, module string) string {
return "mesh.seat.node-engine.event.wait-ended." + node + "." + module
}
// SubjectWaitEndedAll hears every wait-ended.
const SubjectWaitEndedAll = "mesh.seat.node-engine.event.wait-ended.*.*"
const (
StateHave = "have"
StateComposed = "composed"
@@ -74,6 +121,7 @@ const (
StatePackages = "packages"
StateHealth = "health"
StateFindings = "findings"
StateBounds = "bounds"
)
// HaveByNodeModuleKey is the key of one value of the state have under the form "<node>.<module>".
@@ -346,6 +394,42 @@ func DecodeFindingsByKeyValue(raw []byte) (FindingsByKeyValue, error) {
return v, nil
}
// BoundsByWhatIDKey is the key of one value of the state bounds under the form "<what>.<id>".
func BoundsByWhatIDKey(what, id string) string { return what + "." + id }
// ParseBoundsByWhatIDKey reads the parts of a key of the form "<what>.<id>", in the order of the form; the last result is false for a key of another form.
func ParseBoundsByWhatIDKey(key string) (string, string, bool) {
rest := key
v0, after0, found0 := strings.Cut(rest, ".")
if !found0 || v0 == "" {
return "", "", false
}
rest = after0
if rest == "" {
return "", "", false
}
v2 := rest
rest = ""
if rest != "" {
return "", "", false
}
return v0, v2, true
}
// DecodeBoundsByWhatIDValue reads one value of the state bounds under the form "<what>.<id>", refusing a field BoundsByWhatIDValue does not know and any text after the value.
func DecodeBoundsByWhatIDValue(raw []byte) (BoundsByWhatIDValue, error) {
var v BoundsByWhatIDValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// AccountsHanded is the hashes of the users of the list, sealed to the vault.
type AccountsHanded struct {
// when
@@ -523,6 +607,22 @@ type CandidateRefusal struct {
Why string `json:"why"`
}
// Composed is an entry composed on a node (design 47 *What each step says*).
type Composed struct {
// when, RFC 3339
At time.Time `json:"at"`
// the digest of the composition (design 47 G 404)
Digest string `json:"digest"`
// the fingerprint of the want composed
Fingerprint string `json:"fingerprint"`
// the module
Module string `json:"module"`
// the node
Node string `json:"node"`
// the layout's version
V int64 `json:"v"`
}
// DeclaredGroup is a group.
type DeclaredGroup struct {
Gid int64 `json:"gid"`
@@ -713,11 +813,15 @@ type NodeRecord struct {
NetworksSaid bool `json:"networks-said,omitempty"`
Node string `json:"node"`
OutwardLinks []string `json:"outward-links,omitempty"`
SealingKey string `json:"sealing-key,omitempty"`
ServingKey string `json:"serving-key,omitempty"`
Trusts []string `json:"trusts,omitempty"`
TunnelKey string `json:"tunnel-key,omitempty"`
V int64 `json:"v"`
// the capabilities this node's tool runner states of the calls it answers, as its announcement carries them (design 46 approval mark 6)
RunnerCapabilities []string `json:"runner-capabilities,omitempty"`
// the fingerprint of the tool runner that stated runner-capabilities, as its announcement carries it; empty when it stated none
RunnerFingerprint string `json:"runner-fingerprint,omitempty"`
SealingKey string `json:"sealing-key,omitempty"`
ServingKey string `json:"serving-key,omitempty"`
Trusts []string `json:"trusts,omitempty"`
TunnelKey string `json:"tunnel-key,omitempty"`
V int64 `json:"v"`
}
// PeerSeen is a tunnel peer and whether it is seen.
@@ -742,6 +846,38 @@ type PlacedDataItem struct {
Protection string `json:"protection,omitempty"`
}
// ProcessBuild is the build one process of a module was started with.
type ProcessBuild struct {
// the fingerprint handed to it in MESH_FINGERPRINT; empty when it was started without one
Fingerprint string `json:"fingerprint,omitempty"`
// service or container
Kind string `json:"kind"`
// the module
Module string `json:"module"`
// the service's unit or the container's name
Process string `json:"process"`
// when it was started, RFC 3339
Started *time.Time `json:"started,omitempty"`
// why its build is unknown: started before the node-engine handed MESH_FINGERPRINT, or the value could not be read
Unknown string `json:"unknown,omitempty"`
}
// The values of ProcessBuild's kind.
const (
ProcessBuildKindService = "service"
ProcessBuildKindContainer = "container"
)
// ProcessBuilds is what process-builds answers.
type ProcessBuilds struct {
// why they could not be read
Error string `json:"error,omitempty"`
// the node
Node string `json:"node"`
// every process the node-engine started, by module
Processes []ProcessBuild `json:"processes"`
}
// PullWait is the pull from a store a failed apply waits on.
type PullWait struct {
// when the pull began
@@ -796,6 +932,26 @@ type RootVerdict struct {
Why string `json:"why"`
}
// Running is a module's build running on a node, and its health: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), and the assigner reads a provider's and a canary's health and a put's end from (design 47 G 520); said again on the same subject each time healthy changes and for every module the have holds at the engine's start, kept last per subject with no age limit.
type Running struct {
// when it was said, RFC 3339
At time.Time `json:"at"`
// the fingerprint of the build it runs; none with stopped
Fingerprint string `json:"fingerprint,omitempty"`
// the health of the build that runs, as the node-engine's have holds it from the module's declared check (ADR 0240); a running with none, said by a node-engine of before design 47 G, reads as healthy (design 47 G 520). SeatsToPassOn reads none of it: an unhealthy holder still holds its seat
Healthy *bool `json:"healthy,omitempty"`
// the digest of that build's manifest, the indexer's manifest of it, read by digest from the catalog half
Manifest string `json:"manifest,omitempty"`
// the module
Module string `json:"module"`
// the node
Node string `json:"node"`
// true when the have no longer holds the module on the node, never for an unhealthy build: no fingerprint or manifest then (design 47 G 365, 404, 520); mesh-sdk's SeatsToPassOn counts such a module as not running there
Stopped bool `json:"stopped,omitempty"`
// the layout's version
V int64 `json:"v"`
}
// Said is the answer of a read-only judgement.
type Said struct {
// the node
@@ -880,6 +1036,37 @@ type UserListWritten struct {
Wanted string `json:"wanted"`
}
// Wait is a hold or wait a node-engine says, the fields of the seat mesh-wants' wait (design 47 G 498, 512, 629); in the have it also carries ask-at and act (design 47 G 560).
type Wait struct {
// in the have: the act the recovery module answered accepted with (design 47 G 560)
Act string `json:"act,omitempty"`
// in the have: the time of the first ask of the recovery module for this wait (design 47 G 560)
AskAt *time.Time `json:"ask-at,omitempty"`
// a duration such as 30m
Bound string `json:"bound,omitempty"`
// the time the bound counts from (design 47 G 266, 269, 498)
ClockFrom *time.Time `json:"clock-from,omitempty"`
// the node waited on: the build node for a kept build; the subject's <node> is the node that says it
Node string `json:"node,omitempty"`
// what it waits on
On string `json:"on,omitempty"`
// the seat holding the wait: node-engine
Owner string `json:"owner,omitempty"`
// why it holds, such as restore point missing, entry-missing, parts-differ, node away or build no longer kept (design 47 G 541, 499)
Reason string `json:"reason,omitempty"`
Since time.Time `json:"since"`
// compose: a hold of the composition (a restore point missing, an entry missing, parts that differ, a recovery that waits); kept-build: waiting for a kept build (design 47 G 499, 541)
Step string `json:"step"`
// the wait said in words
Words string `json:"words,omitempty"`
}
// The values of Wait's step.
const (
WaitStepCompose = "compose"
WaitStepKeptBuild = "kept-build"
)
// HandOverInput is what hand-over takes.
type HandOverInput struct {
// the directory's absolute path, as the engine states it
@@ -1093,6 +1280,12 @@ type CompositionAnswerWant struct {
Yes string `json:"yes,omitempty"`
}
// CompositionAnswerWithheldItem is a type of the contract.
type CompositionAnswerWithheldItem struct {
Subject string `json:"subject"`
Why string `json:"why"`
}
// CompositionAnswer is what composition answers.
type CompositionAnswer struct {
// the module's last apply that did not end running; absent when none
@@ -1118,6 +1311,10 @@ type CompositionAnswer struct {
Started bool `json:"started"`
// the module's want as the agent holds it; absent when it holds none
Want *CompositionAnswerWant `json:"want,omitempty"`
// the module's marked subjects the grants part withholds from this node's runtime, each with why, read through mesh-grants' verb withheld (design 46 approval mark 6)
Withheld []CompositionAnswerWithheldItem `json:"withheld,omitempty"`
// withheld unknown: the grants part does not answer, when its verb withheld did not answer
WithheldUnknown string `json:"withheld-unknown,omitempty"`
}
// ComposeInput is what compose takes.
@@ -1217,6 +1414,120 @@ type SeatListAgainInput struct {
// SeatListAgainAnswer is what seat-list-again answers.
type SeatListAgainAnswer = SeatList
// FirstViewsInput is what first-views takes.
type FirstViewsInput struct {
}
// FirstViewsAnswerEntriesItem is a type of the contract.
type FirstViewsAnswerEntriesItem struct {
// the build's fingerprint
Fingerprint string `json:"fingerprint"`
// since when it stands in that state, RFC 3339
Since time.Time `json:"since"`
// asked of the indexer, answered, or not found by it
State string `json:"state"`
}
// The values of FirstViewsAnswerEntriesItem's state.
const (
FirstViewsAnswerEntriesItemStateAsked = "asked"
FirstViewsAnswerEntriesItemStateAnswered = "answered"
FirstViewsAnswerEntriesItemStateNotFound = "not-found"
)
// FirstViewsAnswerWantsItem is a type of the contract.
type FirstViewsAnswerWantsItem struct {
// the fingerprint wanted
Fingerprint string `json:"fingerprint"`
// since when the want is kept, RFC 3339
KeptSince time.Time `json:"kept-since"`
// the module the want is of
Module string `json:"module"`
}
// FirstViewsAnswer is what first-views answers.
type FirstViewsAnswer struct {
// one row per entry the node-engine keeps of a module's build by its fingerprint: when it asked the indexer's entry and where that stands (design 47 G 698)
Entries []FirstViewsAnswerEntriesItem `json:"entries"`
// one status per owner and state followed, as mesh-sdk's views runtime keeps it
FirstViews []map[string]any `json:"first-views"`
// the wants the node-engine keeps (design 47 G 683, 698)
Wants []FirstViewsAnswerWantsItem `json:"wants"`
}
// FirstViewAgainInput is what first-view-again takes.
type FirstViewAgainInput struct {
// the owner module, as first-views names it
Owner string `json:"owner"`
// the owner's state, as first-views names it
State string `json:"state"`
// why it is asked again, in plain words
Why string `json:"why"`
}
// FirstViewAgainAnswerAsked is the hand ask written.
type FirstViewAgainAnswerAsked struct {
// when it was asked, RFC 3339
At time.Time `json:"at"`
// the caller the runtime proved
By string `json:"by"`
// the owner module
Owner string `json:"owner"`
// the owner's state
State string `json:"state"`
// the layout's version
V int64 `json:"v"`
// why it was asked again
Why string `json:"why"`
}
// FirstViewAgainAnswer is what first-view-again answers.
type FirstViewAgainAnswer struct {
// the hand ask written
Asked FirstViewAgainAnswerAsked `json:"asked"`
// the verb that reads the status, first-views
Read string `json:"read"`
}
// EntryAgainInput is what entry-again takes.
type EntryAgainInput struct {
// the build's fingerprint, as first-views' entries name it
Fingerprint string `json:"fingerprint"`
// why it is asked again, in plain words
Why string `json:"why"`
}
// EntryAgainAnswerAsked is the hand ask written.
type EntryAgainAnswerAsked struct {
// when it was asked, RFC 3339
At time.Time `json:"at"`
// the caller the runtime proved
By string `json:"by"`
// the build's fingerprint
Fingerprint string `json:"fingerprint"`
// the layout's version
V int64 `json:"v"`
// why it was asked again
Why string `json:"why"`
}
// EntryAgainAnswer is what entry-again answers.
type EntryAgainAnswer struct {
// the hand ask written
Asked EntryAgainAnswerAsked `json:"asked"`
// the verb that reads the status, first-views
Read string `json:"read"`
}
// ProcessBuildsInput is what process-builds takes.
type ProcessBuildsInput struct {
// only this module's processes
Module string `json:"module,omitempty"`
}
// ProcessBuildsAnswer is what process-builds answers.
type ProcessBuildsAnswer = ProcessBuilds
// AskedEvent is the body of the event asked.
type AskedEvent = ActSaid
@@ -1229,6 +1540,18 @@ type RefusedEvent = ActSaid
// ManifestReadsChangedEvent is the body of the event manifest-reads-changed.
type ManifestReadsChangedEvent = ManifestReadsChanged
// ComposedEvent is the body of the event composed.
type ComposedEvent = Composed
// RunningEvent is the body of the event running.
type RunningEvent = Running
// WaitHeldEvent is the body of the event wait-held.
type WaitHeldEvent = Wait
// WaitEndedEvent is the body of the event wait-ended.
type WaitEndedEvent = Wait
// HaveByNodeModuleValue is one value of the state have under the key <node>.<module>.
type HaveByNodeModuleValue struct {
Build string `json:"build,omitempty"`
@@ -1255,6 +1578,7 @@ type HaveByNodeModuleValue struct {
SealedAt map[string]string `json:"sealed-at,omitempty"`
UserList *UserListWritten `json:"user-list,omitempty"`
V int64 `json:"v"`
Wait *Wait `json:"wait,omitempty"`
// in phase waiting-yes, the digest of the composition that waits
Waits string `json:"waits,omitempty"`
}
@@ -1411,3 +1735,12 @@ const (
FindingsByKeyValueSeverityUrgent = "urgent"
FindingsByKeyValueSeverityWarning = "warning"
)
// BoundsByWhatIDValue is one value of the state bounds under the key <what>.<id>.
type BoundsByWhatIDValue struct {
Module string `json:"module,omitempty"`
// when the wait began, RFC 3339
Since string `json:"since"`
// layout version, 1
V int64 `json:"v"`
}
+37 -1
View File
@@ -35,6 +35,20 @@ func TestFixtures(t *testing.T) {
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.manifest-reads-changed\\.[A-Za-z0-9_-]+$")},
{name: "composed is said", subject: "mesh.seat.node-engine.event.composed.home-server", given: "{\"at\":\"2026-11-09T20:00:00Z\",\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"nats\",\"node\":\"home-server\",\"v\":1}", wire: "{\"at\":\"2026-11-09T20:00:00Z\",\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"nats\",\"node\":\"home-server\",\"v\":1}",
decode: func(b []byte) (any, error) { var v ComposedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.composed\\.[^.*> ]+$")},
{name: "running is said, its node and module in its subject", subject: "mesh.seat.node-engine.event.running.home-server.nats", given: "{\"at\":\"2026-11-09T20:01:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"home-server\",\"v\":1}", wire: "{\"at\":\"2026-11-09T20:01:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"home-server\",\"v\":1}",
decode: func(b []byte) (any, error) { var v RunningEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.running\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "running says the build that runs is healthy", subject: "mesh.seat.node-engine.event.running.home-server.nats", given: "{\"at\":\"2026-11-11T09:00:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"healthy\":true,\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"home-server\",\"v\":1}", wire: "{\"at\":\"2026-11-11T09:00:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"healthy\":true,\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"home-server\",\"v\":1}",
decode: func(b []byte) (any, error) { var v RunningEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.running\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "running says the build that runs turned unhealthy, still running", subject: "mesh.seat.node-engine.event.running.home-server.nats", given: "{\"at\":\"2026-11-11T09:05:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"healthy\":false,\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"home-server\",\"v\":1}", wire: "{\"at\":\"2026-11-11T09:05:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"healthy\":false,\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"home-server\",\"v\":1}",
decode: func(b []byte) (any, error) { var v RunningEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.running\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "running says a module stopped on the node, with no fingerprint", subject: "mesh.seat.node-engine.event.running.home-server.nats", given: "{\"at\":\"2026-11-11T09:00:00Z\",\"module\":\"nats\",\"node\":\"home-server\",\"stopped\":true,\"v\":1}", wire: "{\"at\":\"2026-11-11T09:00:00Z\",\"module\":\"nats\",\"node\":\"home-server\",\"stopped\":true,\"v\":1}",
decode: func(b []byte) (any, error) { var v RunningEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.running\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "a kept build's wait is held", subject: "mesh.seat.node-engine.event.wait-held.home-server.postgres", given: "{\"bound\":\"60m\",\"clock-from\":\"2026-11-11T10:00:00Z\",\"node\":\"home-server\",\"on\":\"the kept build of postgres\",\"owner\":\"node-engine\",\"reason\":\"node away\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"kept-build\",\"words\":\"waiting for the kept build of postgres on home-server\"}", wire: "{\"bound\":\"60m\",\"clock-from\":\"2026-11-11T10:00:00Z\",\"node\":\"home-server\",\"on\":\"the kept build of postgres\",\"owner\":\"node-engine\",\"reason\":\"node away\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"kept-build\",\"words\":\"waiting for the kept build of postgres on home-server\"}",
decode: func(b []byte) (any, error) { var v WaitHeldEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.wait-held\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "a hold of the composition ends", subject: "mesh.seat.node-engine.event.wait-ended.home-server.postgres", given: "{\"owner\":\"node-engine\",\"reason\":\"restore point missing\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"compose\"}", wire: "{\"owner\":\"node-engine\",\"reason\":\"restore point missing\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"compose\"}",
decode: func(b []byte) (any, error) { var v WaitEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.wait-ended\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "the finding of a seat list unread, as the engine writes it", subject: "", given: "{\"at\":\"2026-11-05T14:00:00Z\",\"key\":\"machine.ace.seat-list-unread\",\"kind\":\"seat-list-unread\",\"observer\":\"mesh-host\",\"severity\":\"warning\",\"source\":\"node-engine.seat-list\",\"subject\":{\"id\":\"ace\",\"machine\":\"ace\",\"scope\":\"machine\"},\"summary\":\"the seat list has not been read for five minutes\",\"v\":1}", wire: "{\"at\":\"2026-11-05T14:00:00Z\",\"key\":\"machine.ace.seat-list-unread\",\"kind\":\"seat-list-unread\",\"observer\":\"mesh-host\",\"severity\":\"warning\",\"source\":\"node-engine.seat-list\",\"subject\":{\"id\":\"ace\",\"machine\":\"ace\",\"scope\":\"machine\"},\"summary\":\"the seat list has not been read for five minutes\",\"v\":1}",
decode: func(b []byte) (any, error) { var v FindingsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a node's packages, present and absent (captured from ace, shortened)", subject: "", given: "{\"node\":\"ace\",\"packages\":[{\"absent\":false,\"modules\":[\"avahi\"],\"package\":\"avahi\"},{\"absent\":false,\"modules\":[\"mesh-build-go\",\"mesh-build-node\"],\"package\":\"bubblewrap\"},{\"absent\":true,\"modules\":[\"time-sync\"],\"package\":\"ntp\"}]}", wire: "{\"node\":\"ace\",\"packages\":[{\"absent\":false,\"modules\":[\"avahi\"],\"package\":\"avahi\"},{\"absent\":false,\"modules\":[\"mesh-build-go\",\"mesh-build-node\"],\"package\":\"bubblewrap\"},{\"absent\":true,\"modules\":[\"time-sync\"],\"package\":\"ntp\"}]}",
@@ -71,12 +85,16 @@ func TestFixtures(t *testing.T) {
decode: func(b []byte) (any, error) { var v HaveByNodeModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "the bus module's have carries the user list written (typed from the engine's values)", subject: "", given: "{\"health\":\"ok\",\"phase\":\"running\",\"user-list\":{\"at\":\"2026-11-05T12:00:00Z\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"follows\":\"grants\",\"handed\":{\"at\":\"2026-11-05T12:00:00Z\",\"box\":{\"ct\":\"c\",\"eph\":\"e\",\"iv\":\"i\",\"tag\":\"t\",\"v\":1},\"from\":\"ace\",\"to\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"users\":3},\"key\":\"-----BEGIN PUBLIC KEY-----\",\"revision\":7,\"source\":\"user-list\",\"users\":3,\"wanted\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"},\"v\":1}", wire: "{\"health\":\"ok\",\"phase\":\"running\",\"user-list\":{\"at\":\"2026-11-05T12:00:00Z\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"follows\":\"grants\",\"handed\":{\"at\":\"2026-11-05T12:00:00Z\",\"box\":{\"ct\":\"c\",\"eph\":\"e\",\"iv\":\"i\",\"tag\":\"t\",\"v\":1},\"from\":\"ace\",\"to\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"users\":3},\"key\":\"-----BEGIN PUBLIC KEY-----\",\"revision\":7,\"source\":\"user-list\",\"users\":3,\"wanted\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"},\"v\":1}",
decode: func(b []byte) (any, error) { var v HaveByNodeModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a node's own facts with its record and an answer to a candidate (typed from the engine's values)", subject: "", given: "{\"candidates\":{\"p1\":{\"added\":[{\"module\":\"db\",\"unissued\":[\"db.secret\"]}],\"differs\":[{\"bodies\":[{\"id\":\"api.cfg\",\"paths\":[\"/etc/api.conf\"],\"why\":\"content\"}],\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"api\",\"running\":\"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"why\":\"a file differs\"}],\"proposal\":\"p1\",\"refusals\":[{\"module\":\"mail\",\"today\":\"runs\",\"why\":\"a value is missing\"}],\"removed\":[\"old\"],\"revision\":4,\"same\":[\"web\"],\"verdict\":\"differs\"}},\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"composes\":\"own\",\"record\":{\"capabilities\":[\"docker\"],\"contract\":3,\"networks\":[{\"link\":\"eth0\",\"network\":\"192.0.2.0/24\"}],\"networks-said\":true,\"node\":\"ace\",\"tunnel-key\":\"k\",\"v\":1},\"v\":1}", wire: "{\"candidates\":{\"p1\":{\"added\":[{\"module\":\"db\",\"unissued\":[\"db.secret\"]}],\"differs\":[{\"bodies\":[{\"id\":\"api.cfg\",\"paths\":[\"/etc/api.conf\"],\"why\":\"content\"}],\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"api\",\"running\":\"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"why\":\"a file differs\"}],\"proposal\":\"p1\",\"refusals\":[{\"module\":\"mail\",\"today\":\"runs\",\"why\":\"a value is missing\"}],\"removed\":[\"old\"],\"revision\":4,\"same\":[\"web\"],\"verdict\":\"differs\"}},\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"composes\":\"own\",\"record\":{\"capabilities\":[\"docker\"],\"contract\":3,\"networks\":[{\"link\":\"eth0\",\"network\":\"192.0.2.0/24\"}],\"networks-said\":true,\"node\":\"ace\",\"tunnel-key\":\"k\",\"v\":1},\"v\":1}",
{name: "a node's own facts with its record and an answer to a candidate (typed from the engine's values)", subject: "", given: "{\"candidates\":{\"p1\":{\"added\":[{\"module\":\"db\",\"unissued\":[\"db.secret\"]}],\"differs\":[{\"bodies\":[{\"id\":\"api.cfg\",\"paths\":[\"/etc/api.conf\"],\"why\":\"content\"}],\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"api\",\"running\":\"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"why\":\"a file differs\"}],\"proposal\":\"p1\",\"refusals\":[{\"module\":\"mail\",\"today\":\"runs\",\"why\":\"a value is missing\"}],\"removed\":[\"old\"],\"revision\":4,\"same\":[\"web\"],\"verdict\":\"differs\"}},\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"composes\":\"own\",\"record\":{\"capabilities\":[\"approval-mark/1\",\"docker\"],\"contract\":3,\"networks\":[{\"link\":\"eth0\",\"network\":\"192.0.2.0/24\"}],\"networks-said\":true,\"node\":\"ace\",\"runner-capabilities\":[\"approval-mark/1\"],\"runner-fingerprint\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"tunnel-key\":\"k\",\"v\":1},\"v\":1}", wire: "{\"candidates\":{\"p1\":{\"added\":[{\"module\":\"db\",\"unissued\":[\"db.secret\"]}],\"differs\":[{\"bodies\":[{\"id\":\"api.cfg\",\"paths\":[\"/etc/api.conf\"],\"why\":\"content\"}],\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"api\",\"running\":\"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"why\":\"a file differs\"}],\"proposal\":\"p1\",\"refusals\":[{\"module\":\"mail\",\"today\":\"runs\",\"why\":\"a value is missing\"}],\"removed\":[\"old\"],\"revision\":4,\"same\":[\"web\"],\"verdict\":\"differs\"}},\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"composes\":\"own\",\"record\":{\"capabilities\":[\"approval-mark/1\",\"docker\"],\"contract\":3,\"networks\":[{\"link\":\"eth0\",\"network\":\"192.0.2.0/24\"}],\"networks-said\":true,\"node\":\"ace\",\"runner-capabilities\":[\"approval-mark/1\"],\"runner-fingerprint\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"tunnel-key\":\"k\",\"v\":1},\"v\":1}",
decode: func(b []byte) (any, error) { var v HaveByNodeNodeValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a module's data items on a node (typed from the engine's values)", subject: "", given: "{\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"items\":[{\"class\":\"database\",\"covered_by\":\"/var/lib/postgres\",\"item\":\"cluster\",\"measure\":\"dataset\",\"module\":\"postgres\",\"path\":\"/var/lib/postgres\",\"protection\":\"backup\"}],\"module\":\"postgres\",\"node\":\"ace\",\"v\":1}", wire: "{\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"items\":[{\"class\":\"database\",\"covered_by\":\"/var/lib/postgres\",\"item\":\"cluster\",\"measure\":\"dataset\",\"module\":\"postgres\",\"path\":\"/var/lib/postgres\",\"protection\":\"backup\"}],\"module\":\"postgres\",\"node\":\"ace\",\"v\":1}",
decode: func(b []byte) (any, error) { var v DataByNodeModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a node's health (typed from the engine's values)", subject: "", given: "{\"at\":\"2026-11-05T12:00:00Z\",\"contract\":3,\"network\":{\"parts\":[{\"part\":\"resolver\",\"since\":\"2026-11-05T10:00:00Z\",\"state\":\"running\"}],\"since\":\"2026-11-05T10:00:00Z\",\"state\":\"running\"},\"node\":\"ace\",\"peers\":[{\"addresses\":[\"198.51.100.1\"],\"key\":\"k\",\"seen\":true}],\"relogin\":[{\"account\":\"web\",\"reason\":\"password changed\",\"since\":\"2026-11-05T11:00:00Z\"}],\"units\":{\"failed\":[{\"result\":\"exit-code\",\"scope\":\"system\",\"since\":\"2026-11-05T11:00:00Z\",\"unit\":\"x.service\"}],\"state\":\"degraded\"},\"v\":1}", wire: "{\"at\":\"2026-11-05T12:00:00Z\",\"contract\":3,\"network\":{\"parts\":[{\"part\":\"resolver\",\"since\":\"2026-11-05T10:00:00Z\",\"state\":\"running\"}],\"since\":\"2026-11-05T10:00:00Z\",\"state\":\"running\"},\"node\":\"ace\",\"peers\":[{\"addresses\":[\"198.51.100.1\"],\"key\":\"k\",\"seen\":true}],\"relogin\":[{\"account\":\"web\",\"reason\":\"password changed\",\"since\":\"2026-11-05T11:00:00Z\"}],\"units\":{\"failed\":[{\"result\":\"exit-code\",\"scope\":\"system\",\"since\":\"2026-11-05T11:00:00Z\",\"unit\":\"x.service\"}],\"state\":\"degraded\"},\"v\":1}",
decode: func(b []byte) (any, error) { var v HealthByNodeValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a have that waits for the recovery module, with its wait, ask-at and act (design 47 G 560, 629)", subject: "", given: "{\"detail\":\"waiting for a restore point\",\"fp\":\"0123456789ab\",\"health\":\"waits\",\"phase\":\"held\",\"v\":1,\"wait\":{\"act\":\"a-20261111t100000\",\"ask-at\":\"2026-11-11T10:00:00Z\",\"bound\":\"90m\",\"clock-from\":\"2026-11-11T10:00:00Z\",\"on\":\"the recovery module's ended\",\"owner\":\"node-engine\",\"reason\":\"recovery wait\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"compose\",\"words\":\"waiting for the point of postgres's data\"}}", wire: "{\"detail\":\"waiting for a restore point\",\"fp\":\"0123456789ab\",\"health\":\"waits\",\"phase\":\"held\",\"v\":1,\"wait\":{\"act\":\"a-20261111t100000\",\"ask-at\":\"2026-11-11T10:00:00Z\",\"bound\":\"90m\",\"clock-from\":\"2026-11-11T10:00:00Z\",\"on\":\"the recovery module's ended\",\"owner\":\"node-engine\",\"reason\":\"recovery wait\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"compose\",\"words\":\"waiting for the point of postgres's data\"}}",
decode: func(b []byte) (any, error) { var v HaveByNodeModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a bound of a wait on the recovery module's restore point", subject: "", given: "{\"module\":\"mesh-delivery-assigner\",\"since\":\"2026-11-11T14:00:00Z\",\"v\":1}", wire: "{\"module\":\"mesh-delivery-assigner\",\"since\":\"2026-11-11T14:00:00Z\",\"v\":1}",
decode: func(b []byte) (any, error) { var v BoundsByWhatIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "manifest-reads answers what the engine reads and when it stated it", subject: "", given: "{\"manifest-reads\":[\"form:seat-reference\",\"word:series\"],\"node\":\"ace\",\"stated-at\":\"2026-11-04T10:00:00Z\",\"v\":1}", wire: "{\"manifest-reads\":[\"form:seat-reference\",\"word:series\"],\"node\":\"ace\",\"stated-at\":\"2026-11-04T10:00:00Z\",\"v\":1}",
decode: func(b []byte) (any, error) { var v ManifestReadsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "manifest-reads of an engine built before it said them is the baseline", subject: "", given: "{\"node\":\"g14\",\"stated-at\":\"2026-11-04T10:05:00Z\",\"v\":1}", wire: "{\"node\":\"g14\",\"stated-at\":\"2026-11-04T10:05:00Z\",\"v\":1}",
@@ -91,6 +109,24 @@ func TestFixtures(t *testing.T) {
decode: func(b []byte) (any, error) { var v SeatListAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "seat-list-again answers the error when the read failed", subject: "", given: "{\"error\":\"seatlist: no answer\",\"health\":\"the seat list is held from the bootstrap\",\"status\":{\"heard\":false,\"held\":[{\"seat\":\"node-engine\",\"source\":\"bootstrap\"}],\"waiting\":[\"node-engine\"]}}", wire: "{\"error\":\"seatlist: no answer\",\"health\":\"the seat list is held from the bootstrap\",\"status\":{\"heard\":false,\"held\":[{\"seat\":\"node-engine\",\"source\":\"bootstrap\"}],\"waiting\":[\"node-engine\"]}}",
decode: func(b []byte) (any, error) { var v SeatListAgainAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "process-builds asks one module", subject: "", given: "{\"module\":\"nats\"}", wire: "{\"module\":\"nats\"}",
decode: func(b []byte) (any, error) { var v ProcessBuildsInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "process-builds answers each process's build", subject: "", given: "{\"node\":\"home-server\",\"processes\":[{\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"kind\":\"service\",\"module\":\"nats\",\"process\":\"nats.service\",\"started\":\"2026-11-09T19:00:00Z\"},{\"kind\":\"container\",\"module\":\"route-proxy\",\"process\":\"route-proxy\",\"started\":\"2026-11-01T08:00:00Z\",\"unknown\":\"started before the node-engine handed MESH_FINGERPRINT\"}]}", wire: "{\"node\":\"home-server\",\"processes\":[{\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"kind\":\"service\",\"module\":\"nats\",\"process\":\"nats.service\",\"started\":\"2026-11-09T19:00:00Z\"},{\"kind\":\"container\",\"module\":\"route-proxy\",\"process\":\"route-proxy\",\"started\":\"2026-11-01T08:00:00Z\",\"unknown\":\"started before the node-engine handed MESH_FINGERPRINT\"}]}",
decode: func(b []byte) (any, error) { var v ProcessBuildsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "process-builds answers an error", subject: "", given: "{\"error\":\"the service manager did not answer\",\"node\":\"home-server\",\"processes\":[]}", wire: "{\"error\":\"the service manager did not answer\",\"node\":\"home-server\",\"processes\":[]}",
decode: func(b []byte) (any, error) { var v ProcessBuildsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "first-view-again names the owner, its state and why", subject: "", given: "{\"owner\":\"mesh-delivery-indexer\",\"state\":\"manifests\",\"why\":\"the picture lags the indexer by hand\"}", wire: "{\"owner\":\"mesh-delivery-indexer\",\"state\":\"manifests\",\"why\":\"the picture lags the indexer by hand\"}",
decode: func(b []byte) (any, error) { var v FirstViewAgainInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "first-views answers its entries and its kept wants", subject: "", given: "{\"entries\":[{\"fingerprint\":\"b3f1c9\",\"since\":\"2026-11-11T08:00:00Z\",\"state\":\"asked\"},{\"fingerprint\":\"a77d02\",\"since\":\"2026-11-11T08:01:00Z\",\"state\":\"answered\"},{\"fingerprint\":\"0c1e55\",\"since\":\"2026-11-11T08:02:00Z\",\"state\":\"not-found\"}],\"first-views\":[],\"wants\":[{\"fingerprint\":\"b3f1c9\",\"kept-since\":\"2026-11-11T07:00:00Z\",\"module\":\"mesh-delivery-indexer\"}]}", wire: "{\"entries\":[{\"fingerprint\":\"b3f1c9\",\"since\":\"2026-11-11T08:00:00Z\",\"state\":\"asked\"},{\"fingerprint\":\"a77d02\",\"since\":\"2026-11-11T08:01:00Z\",\"state\":\"answered\"},{\"fingerprint\":\"0c1e55\",\"since\":\"2026-11-11T08:02:00Z\",\"state\":\"not-found\"}],\"first-views\":[],\"wants\":[{\"fingerprint\":\"b3f1c9\",\"kept-since\":\"2026-11-11T07:00:00Z\",\"module\":\"mesh-delivery-indexer\"}]}",
decode: func(b []byte) (any, error) { var v FirstViewsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "entry-again names the fingerprint and why", subject: "", given: "{\"fingerprint\":\"b3f1c9\",\"why\":\"the entry could not be read\"}", wire: "{\"fingerprint\":\"b3f1c9\",\"why\":\"the entry could not be read\"}",
decode: func(b []byte) (any, error) { var v EntryAgainInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "entry-again answers what was asked and where it is read", subject: "", given: "{\"asked\":{\"at\":\"2026-11-11T08:00:00Z\",\"by\":\"operator@workstation\",\"fingerprint\":\"b3f1c9\",\"v\":1,\"why\":\"the entry could not be read\"},\"read\":\"first-views\"}", wire: "{\"asked\":{\"at\":\"2026-11-11T08:00:00Z\",\"by\":\"operator@workstation\",\"fingerprint\":\"b3f1c9\",\"v\":1,\"why\":\"the entry could not be read\"},\"read\":\"first-views\"}",
decode: func(b []byte) (any, error) { var v EntryAgainAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "composition names what the grants part withholds of the module", subject: "", given: "{\"composition\":{\"key\":\"\"},\"judged\":{\"judgement\":\"\",\"waits_for_yes\":false,\"words\":\"\"},\"module\":\"zsh\",\"node\":\"workstation\",\"started\":false,\"withheld\":[{\"subject\":\"mesh.mod.zsh.tool.execute\",\"why\":\"its tool runner does not state approval-mark/1\"}]}", wire: "{\"composition\":{\"key\":\"\"},\"judged\":{\"judgement\":\"\",\"waits_for_yes\":false,\"words\":\"\"},\"module\":\"zsh\",\"node\":\"workstation\",\"started\":false,\"withheld\":[{\"subject\":\"mesh.mod.zsh.tool.execute\",\"why\":\"its tool runner does not state approval-mark/1\"}]}",
decode: func(b []byte) (any, error) { var v CompositionAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "composition says withheld unknown when the grants part does not answer", subject: "", given: "{\"composition\":{\"key\":\"\"},\"judged\":{\"judgement\":\"\",\"waits_for_yes\":false,\"words\":\"\"},\"module\":\"zsh\",\"node\":\"workstation\",\"started\":false,\"withheld-unknown\":\"withheld unknown: the grants part does not answer\"}", wire: "{\"composition\":{\"key\":\"\"},\"judged\":{\"judgement\":\"\",\"waits_for_yes\":false,\"words\":\"\"},\"module\":\"zsh\",\"node\":\"workstation\",\"started\":false,\"withheld-unknown\":\"withheld unknown: the grants part does not answer\"}",
decode: func(b []byte) (any, error) { var v CompositionAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
@@ -0,0 +1,11 @@
package meshconditionsclient
import "time"
// KindCallUnanswered is the kind of a kept call still unanswered past CallUnansweredAfter (novox/hq ADR 0668 §3, issue
// 1966): a call whose answer the caller keeps, asked again through every transport fault, that no answer has ended. The
// caller writes it into its own findings, keeps the wait, and clears it when the call is answered.
const KindCallUnanswered = "call-unanswered"
// CallUnansweredAfter is how long a kept call stays unanswered before it is a finding (ADR 0668 §3; ADR 0564 §2's bound).
const CallUnansweredAfter = 5 * time.Minute
@@ -1,17 +1,15 @@
// Package meshconditionsclient is the logic every observer, healer and reader of conditions shares over the seat
// mesh-conditions (novox/hq ADR 0564, ADR 0634 §4): how a finding's key is made and checked, the scopes and the bounds,
// mesh-conditions (novox/hq ADR 0564, ADR 0634 §4): how a finding's key is made, the scopes and the bounds,
// the order a person reads conditions in, and the answers a notification offers. The layouts are the seat's contract's.
package meshconditionsclient
import (
"fmt"
"regexp"
"sort"
"strings"
"time"
seat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
"git.novox.be/novox/mesh-sdk/go/views"
)
// The two severities, how soon the operator is needed.
@@ -74,6 +72,7 @@ const (
ChangeUnsilenced = "silence-ended"
ChangeCleared = "cleared"
ChangeWords = "words"
ChangeOwner = "owner"
)
var unsafeKey = regexp.MustCompile(`[^A-Za-z0-9_=/-]`)
@@ -111,39 +110,6 @@ func SilenceAction(key string) seat.Action {
Arguments: map[string]string{"key": key, "for": "7d", "why": "", "cause": CauseOperatorAnswer}}
}
// CheckFinding refuses a finding the keeper could not make a condition of, naming why.
func CheckFinding(f seat.FindingsByKeyValue) error {
known := false
for _, s := range Scopes {
known = known || s == f.Subject.Scope
}
token := f.Ref
if token == "" {
token = f.Kind
}
switch {
case !known:
return fmt.Errorf("health: a finding's scope is one of %s, not %q", strings.Join(Scopes, ", "), f.Subject.Scope)
case strings.TrimSpace(f.Subject.ID) == "":
return fmt.Errorf("health: a %s finding names what it is about", f.Subject.Scope)
case strings.TrimSpace(f.Kind) == "":
return fmt.Errorf("health: the finding %s has no kind", f.Key)
case f.Key != Key(f.Subject.Scope, f.Subject.ID, token):
return fmt.Errorf("health: the finding's key %q is not %q, its scope, id and kind", f.Key, Key(f.Subject.Scope, f.Subject.ID, token))
case f.Severity != Urgent && f.Severity != Warning:
return fmt.Errorf("health: the finding %s is urgent or a warning, not %q", f.Key, f.Severity)
case strings.TrimSpace(f.Summary) == "":
return fmt.Errorf("health: the finding %s says nothing", f.Key)
case strings.TrimSpace(f.Source) == "":
return fmt.Errorf("health: the finding %s does not say what saw it", f.Key)
case strings.TrimSpace(f.Observer) == "":
return fmt.Errorf("health: the finding %s does not name its observer", f.Key)
case len(f.Evidence) > KeptEvidence:
return fmt.Errorf("health: the finding %s keeps %d observations, at most %d", f.Key, len(f.Evidence), KeptEvidence)
}
return nil
}
// Order sorts conditions as a person reads them: urgent first, then oldest raised, then by key.
func Order(list []seat.ConditionsByKeyValue) {
raised := func(c seat.ConditionsByKeyValue) time.Time { return c.Raised }
@@ -171,44 +137,3 @@ func SilencedAt(c seat.ConditionsByKeyValue, now time.Time) bool {
func Escalated(c seat.ConditionsByKeyValue) bool {
return c.Resolver == ResolverOperator && len(c.Tried) > 0
}
// FindingVersion is the layout version of a finding's value.
const FindingVersion = 1
// FindingState is a part's own state `findings`, where the condition keeper reads what a part saw: the runtime's kept
// state (mesh-sdk's KeptState) satisfies it.
type FindingState interface {
Put(key string, value any) (uint64, error)
Delete(key string) error
}
// FindingWriter writes and clears a part's findings of a module in its own state `findings`, in this seat's layout; it
// is mesh-sdk's views.FindingWriter. A finding is a warning about the module its ID names, and is checked
// (CheckFinding) before it is written.
type FindingWriter struct{ State FindingState }
var _ views.FindingWriter = FindingWriter{}
// FindingFor is the value and key of the seat's finding for f.
func FindingFor(f views.Finding) seat.FindingsByKeyValue {
at := f.At.UTC()
return seat.FindingsByKeyValue{V: FindingVersion, Key: Key(ScopeModule, f.ID, f.Kind), Kind: f.Kind,
Subject: seat.Subject{Scope: ScopeModule, ID: f.ID}, Severity: Warning, Summary: f.Summary, Headline: f.Headline,
Explanation: f.Explanation, Evidence: []seat.Evidence{{At: at, Said: f.Summary}}, Source: f.Observer + "." + f.Kind,
Observer: f.Observer, At: at}
}
// Put writes the finding.
func (w FindingWriter) Put(f views.Finding) error {
v := FindingFor(f)
if err := CheckFinding(v); err != nil {
return err
}
_, err := w.State.Put(v.Key, v)
return err
}
// Delete clears the finding.
func (w FindingWriter) Delete(f views.Finding) error {
return w.State.Delete(Key(ScopeModule, f.ID, f.Kind))
}
@@ -1,14 +1,10 @@
package meshconditionsclient
import (
"os"
"reflect"
"strings"
"testing"
"time"
seat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
"git.novox.be/novox/mesh-sdk/go/views"
)
// ADR 0564 clause 3: the key rule, the checks of a finding, the order and the silence a person reads conditions by.
@@ -19,28 +15,8 @@ func TestAFindingsKeyAndTheOrderOfConditions(t *testing.T) {
if k := Key("call", "a b", ""); k != "call.a_b._" {
t.Errorf("an unsafe part and an empty token: %s", k)
}
good := seat.FindingsByKeyValue{Key: "machine.g14.silent", Kind: "silent", Severity: Warning, Summary: "x", Source: "S1",
Observer: "mesh-delivery-watchman", Subject: seat.Subject{Scope: ScopeMachine, ID: "g14"}}
for _, c := range []struct {
name string
change func(*seat.FindingsByKeyValue)
refuse string
}{
{"a good finding", func(*seat.FindingsByKeyValue) {}, ""},
{"an unknown scope", func(f *seat.FindingsByKeyValue) { f.Subject.Scope = "moon" }, "scope is one of"},
{"a key that is not its subject's", func(f *seat.FindingsByKeyValue) { f.Key = "machine.g14.other" }, "is not"},
{"a reference as the key's last part", func(f *seat.FindingsByKeyValue) { f.Ref = "gone"; f.Key = "machine.g14.gone" }, ""},
{"no summary", func(f *seat.FindingsByKeyValue) { f.Summary = " " }, "says nothing"},
{"no observer", func(f *seat.FindingsByKeyValue) { f.Observer = "" }, "observer"},
{"a severity of neither kind", func(f *seat.FindingsByKeyValue) { f.Severity = "info" }, "urgent or a warning"},
{"too much evidence", func(f *seat.FindingsByKeyValue) { f.Evidence = make([]seat.Evidence, KeptEvidence+1) }, "keeps 11"},
} {
f := good
c.change(&f)
err := CheckFinding(f)
if (c.refuse == "") != (err == nil) || (err != nil && !strings.Contains(err.Error(), c.refuse)) {
t.Errorf("%s: %v", c.name, err)
}
if KindCallUnanswered != "call-unanswered" || CallUnansweredAfter != 5*time.Minute {
t.Error("the kept call's finding kind and bound")
}
list := []seat.ConditionsByKeyValue{
{Key: "b", Severity: Warning, Raised: when("2026-11-01T10:00:00Z")},
@@ -56,7 +32,8 @@ func TestAFindingsKeyAndTheOrderOfConditions(t *testing.T) {
t.Error("silence is until its end")
}
if EventFor(ChangeReopened) != seat.EventConditionRaised || EventFor(ChangeSilenced) != seat.EventConditionChanged ||
EventFor(ChangeCleared) != seat.EventConditionCleared {
EventFor(ChangeCleared) != seat.EventConditionCleared || EventFor(ChangeOwner) != seat.EventConditionChanged ||
ChangeOwner != seat.ConditionEventChangeOwner {
t.Error("a change is said as its event")
}
if a := SilenceAction("k"); a.Verb != "mesh-conditions.silence" || ShowKeeper("k") != "mesh-conditions.conditions key=k" {
@@ -64,44 +41,6 @@ func TestAFindingsKeyAndTheOrderOfConditions(t *testing.T) {
}
}
type fakeFindings struct {
put map[string]any
deleted []string
}
func (f *fakeFindings) Put(key string, value any) (uint64, error) {
if f.put == nil {
f.put = map[string]any{}
}
f.put[key] = value
return 1, nil
}
func (f *fakeFindings) Delete(key string) error { f.deleted = append(f.deleted, key); return nil }
func TestTheFindingWriterWritesAndClearsAModulesFindingInTheSeatsLayout(t *testing.T) {
state := &fakeFindings{}
var w views.FindingWriter = FindingWriter{State: state}
f := views.Finding{Observer: "mesh-config", Kind: "unanswered", ID: "mesh-config.mesh-vault.secrets", Summary: "no first view",
Headline: "waits", Explanation: "look", At: time.Date(2026, 11, 5, 12, 0, 0, 0, time.UTC)}
if err := w.Put(f); err != nil {
t.Fatal(err)
}
key := "module.mesh-config.mesh-vault.secrets.unanswered"
v, ok := state.put[key].(seat.FindingsByKeyValue)
if !ok || v.Key != key || v.Severity != Warning || v.Source != "mesh-config.unanswered" || v.Subject.Scope != ScopeModule || len(v.Evidence) != 1 {
t.Fatalf("written %#v", state.put)
}
if err := CheckFinding(v); err != nil {
t.Error(err)
}
if err := w.Delete(f); err != nil || len(state.deleted) != 1 || state.deleted[0] != key {
t.Errorf("deleted %v: %v", state.deleted, err)
}
if err := w.Put(views.Finding{Observer: "x", Kind: "k", ID: "i"}); err == nil {
t.Error("a finding that says nothing was written")
}
}
func when(s string) time.Time {
t, err := time.Parse(time.RFC3339Nano, s)
if err != nil {
@@ -111,85 +50,3 @@ func when(s string) time.Time {
}
func ptr(t time.Time) *time.Time { return &t }
type fakeBucket struct {
kept map[string][]byte
puts, dels int
}
func (b *fakeBucket) Get(key string) ([]byte, bool, error) { v, ok := b.kept[key]; return v, ok, nil }
func (b *fakeBucket) Put(key string, v []byte) error {
if b.kept == nil {
b.kept = map[string][]byte{}
}
b.kept[key] = v
b.puts++
return nil
}
func (b *fakeBucket) Delete(key string) error { delete(b.kept, key); b.dels++; return nil }
// The goldens are what mesh-sdk's go/health EncodeFinding wrote for the same findings: the helpers write the same
// values, read by the seat's strict decoder.
func TestAnObservationIsWrittenAsMeshSDKsHealthWroteItsFinding(t *testing.T) {
at := time.Date(2026, 11, 5, 12, 0, 0, 0, time.UTC)
for _, c := range []struct {
golden string
o Observation
run string
}{
{"finding_full.json", Observation{Scope: ScopeMachine, ID: "g14", Kind: "silent-kind", Ref: "silent", Machine: "g14", Also: []string{"ace"},
Severity: Urgent, Summary: "g14 is silent", Said: "no pulse", Headline: "g14 is silent", Explanation: "It said nothing.",
Resolved: "It speaks.", Needs: "look", Source: "S1", Resolver: "operator"}, "r1"},
{"finding_minimal.json", Observation{Scope: ScopeModule, ID: "nats.g14", Kind: "build-failed", Summary: "failed",
Source: "builder.build-failed"}, ""},
} {
raw, err := os.ReadFile("testdata/" + c.golden)
if err != nil {
t.Fatal(err)
}
want, err := seat.DecodeFindingsByKeyValue(raw)
if err != nil {
t.Fatalf("%s: %v", c.golden, err)
}
observer := want.Observer
got, err := EncodeFinding(c.o.Finding(observer, c.run, at))
if err != nil {
t.Fatalf("%s: %v", c.golden, err)
}
have, err := seat.DecodeFindingsByKeyValue(got)
if err != nil || !reflect.DeepEqual(have, want) {
t.Errorf("%s: wrote %s, want %s (%v)", c.golden, got, raw, err)
}
if back, err := DecodeFinding(raw); err != nil || !reflect.DeepEqual(back, want) {
t.Errorf("%s: read back %v", c.golden, err)
}
}
}
func TestRaiseWritesWhenTheWordsChangeAndClearDeletesWhatIsThere(t *testing.T) {
b := &fakeBucket{}
o := Observation{Scope: ScopeModule, ID: "m", Kind: "k", Summary: "one", Source: "x.k"}
at := when("2026-11-05T12:00:00Z")
if w, err := Raise(b, "obs", "", o, at); err != nil || !w {
t.Fatalf("first: %v %v", w, err)
}
if w, err := Raise(b, "obs", "r2", o, at.Add(time.Hour)); err != nil || w || b.puts != 1 {
t.Fatalf("the same words later: wrote %v, %d puts, %v", w, b.puts, err)
}
o.Summary = "two"
if w, err := Raise(b, "obs", "", o, at); err != nil || !w || b.puts != 2 {
t.Fatalf("changed: %v %d %v", w, b.puts, err)
}
if _, err := Raise(b, "obs", "", Observation{Scope: "moon", ID: "m", Kind: "k"}, at); err == nil || b.puts != 2 {
t.Errorf("a finding the keeper cannot use was written: %v", err)
}
if c, err := Clear(b, ScopeModule, "m", "k"); err != nil || !c || b.dels != 1 {
t.Fatalf("clear: %v %v %d", c, err, b.dels)
}
if c, err := Clear(b, ScopeModule, "m", "k"); err != nil || c || b.dels != 1 {
t.Errorf("clearing what is not there: %v %v %d", c, err, b.dels)
}
if FindingsBucket("obs") != "obs_findings" {
t.Error(FindingsBucket("obs"))
}
}
@@ -0,0 +1,4 @@
// Package findings is kept empty as a bridge: the modules whose last build before G imported it get a fingerprint
// naming their packages' commits only while it is published. It goes once those modules have built under G
// (mesh-contracts #12; this second commit only carries #12's merge to the indexer, whose message was lost).
package findings
@@ -1,88 +0,0 @@
// Package findings is a part's own bucket `findings` as the state the seat mesh-conditions' client writes into
// (meshconditionsclient.FindingState), so a part gives mesh-sdk's views the FindingWriter of the seat's layout without
// each writing the same adapter over its bucket (novox/hq ADR 0564 §2, ADR 0635 §4).
package findings
import (
"context"
"encoding/json"
"errors"
"github.com/nats-io/nats.go/jetstream"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshconditionsclient"
"git.novox.be/novox/mesh-sdk/go/views"
)
// ErrUnbound says the bucket is not on the bus yet, so the finding is not written (the part says it in its log).
var ErrUnbound = errors.New("the findings state is not bound yet")
// State is the bucket the part's state `findings` is, given when it is bound (process.AwaitedBucket.KV): nil is not bound yet.
type State struct {
Ctx context.Context
KV func() jetstream.KeyValue
}
var _ meshconditionsclient.FindingState = State{}
// Put writes one value under its key as JSON.
func (s State) Put(key string, value any) (uint64, error) {
kv := s.KV()
if kv == nil {
return 0, ErrUnbound
}
data, err := json.Marshal(value)
if err != nil {
return 0, err
}
return kv.Put(s.Ctx, key, data)
}
// Delete clears one key.
func (s State) Delete(key string) error {
kv := s.KV()
if kv == nil {
return ErrUnbound
}
return kv.Delete(s.Ctx, key)
}
// Writer is the part's views.FindingWriter over its bucket; the function is what views.ProcessReader.Findings and the
// emitter's Findings take.
func Writer(ctx context.Context, kv func() jetstream.KeyValue) views.FindingWriter {
return meshconditionsclient.FindingWriter{State: State{Ctx: ctx, KV: kv}}
}
// Funcs is a findings state held as the two functions a part keeps over it (the assigner's findings, which also say
// its conditions): a value is put as JSON.
type Funcs struct {
PutBytes func(key string, value []byte) error
DeleteKey func(key string) error
}
var _ meshconditionsclient.FindingState = Funcs{}
// Put writes one value under its key as JSON; the state not bound (no function) is ErrUnbound.
func (f Funcs) Put(key string, value any) (uint64, error) {
if f.PutBytes == nil {
return 0, ErrUnbound
}
data, err := json.Marshal(value)
if err != nil {
return 0, err
}
return 0, f.PutBytes(key, data)
}
// Delete clears one key.
func (f Funcs) Delete(key string) error {
if f.DeleteKey == nil {
return ErrUnbound
}
return f.DeleteKey(key)
}
// WriterOver is the part's views.FindingWriter over its two functions.
func WriterOver(put func(string, []byte) error, del func(string) error) views.FindingWriter {
return meshconditionsclient.FindingWriter{State: Funcs{PutBytes: put, DeleteKey: del}}
}
@@ -1,71 +0,0 @@
package findings
import (
"context"
"encoding/json"
"errors"
"testing"
"time"
"github.com/nats-io/nats.go/jetstream"
"git.novox.be/novox/mesh-sdk/go/views"
)
// fakeKV is the two calls a findings state makes of its bucket.
type fakeKV struct {
jetstream.KeyValue
held map[string][]byte
}
func (f *fakeKV) Put(_ context.Context, key string, value []byte) (uint64, error) {
f.held[key] = value
return uint64(len(f.held)), nil
}
func (f *fakeKV) Delete(_ context.Context, key string, _ ...jetstream.KVDeleteOpt) error {
delete(f.held, key)
return nil
}
// A part's finding is written in the seat mesh-conditions' layout under the key the condition keeper reads, cleared by the
// same finding, and refused while the bucket is not bound (the part says that in its log).
func TestAFindingIsWrittenInTheSeatsLayoutAndClearedAndRefusedUnbound(t *testing.T) {
kv := &fakeKV{held: map[string][]byte{}}
var bound jetstream.KeyValue
w := Writer(context.Background(), func() jetstream.KeyValue { return bound })
f := views.Finding{Observer: "mesh-delivery-teller", Kind: views.UnansweredKind, ID: "mesh-delivery-teller.asks", Summary: "s", Headline: "h",
Explanation: "e", At: time.Date(2026, 11, 5, 15, 0, 0, 0, time.UTC)}
if err := w.Put(f); !errors.Is(err, ErrUnbound) {
t.Fatalf("an unbound bucket took the finding: %v", err)
}
bound = kv
if err := w.Put(f); err != nil {
t.Fatal(err)
}
var got struct{ Key, Kind, Observer, Source string }
for key, value := range kv.held {
if err := json.Unmarshal(value, &got); err != nil || got.Key != key || got.Kind != views.UnansweredKind ||
got.Observer != f.Observer || got.Source != f.Observer+"."+f.Kind {
t.Fatalf("%s holds %s (%v)", key, value, err)
}
}
if len(kv.held) != 1 {
t.Fatalf("the bucket holds %d findings, want 1", len(kv.held))
}
if err := w.Delete(f); err != nil || len(kv.held) != 0 {
t.Fatalf("the finding is not cleared: %v, %d left", err, len(kv.held))
}
// The same finding over two functions (a part whose findings also say its conditions).
held := map[string][]byte{}
o := WriterOver(func(k string, v []byte) error { held[k] = v; return nil }, func(k string) error { delete(held, k); return nil })
if err := o.Put(f); err != nil || len(held) != 1 {
t.Fatalf("over functions: %v, %d held", err, len(held))
}
if err := o.Delete(f); err != nil || len(held) != 0 {
t.Fatalf("over functions not cleared: %v, %d left", err, len(held))
}
if err := WriterOver(nil, nil).Put(f); !errors.Is(err, ErrUnbound) {
t.Fatalf("no functions took the finding: %v", err)
}
}
@@ -13,7 +13,7 @@ import (
"time"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshconditionsclient"
"git.novox.be/novox/mesh-sdk/go/views"
seat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
)
// Kind is the finding's kind.
@@ -43,16 +43,18 @@ func Words(observer, family, consequence string, why error) (summary, headline,
return summary, headline, explanation
}
// Finding is observer's finding that it does not hear family, in the layout of the seat mesh-conditions' state findings.
// Finding is observer's finding that it does not hear family, as the seat mesh-conditions' generated type
// (design 47 G 689): its key and its value. The check of its rules is mesh-sdk's writer's, which refuses a finding
// breaking them before it writes.
func Finding(observer, family, consequence string, why error, at time.Time) (string, []byte, error) {
summary, headline, explanation := Words(observer, family, consequence, why)
v := meshconditionsclient.FindingFor(views.Finding{Observer: observer, Kind: Kind, ID: ID(observer, family), Summary: summary,
Headline: headline, Explanation: explanation, At: at})
if err := meshconditionsclient.CheckFinding(v); err != nil {
return v.Key, nil, err
}
at = at.UTC()
v := seat.Finding{Scope: meshconditionsclient.ScopeModule, ID: ID(observer, family), Kind: Kind,
Subject: seat.Subject{Scope: meshconditionsclient.ScopeModule, ID: ID(observer, family)},
Severity: meshconditionsclient.Warning, Summary: summary, Headline: headline, Explanation: explanation,
Evidence: []seat.Evidence{{At: at, Said: summary}}, Source: observer + "." + Kind, Observer: observer, At: at, Since: at}
value, err := json.Marshal(v)
return v.Key, value, err
return Key(observer, family), value, err
}
// Writer writes and deletes the finding in the observer's findings state. Put or Delete nil writes nothing, said in the
@@ -5,6 +5,8 @@ import (
"strings"
"testing"
"time"
seat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
)
// A consumer that does not bind writes the finding, with why, under the observer's findings key; the one that binds
@@ -22,6 +24,11 @@ func TestBindWritesTheFindingUntilTheConsumerBinds(t *testing.T) {
if err := w.Bind("placement", "the first view is the only picture", func() error { return errors.New("no consumer") }); err == nil {
t.Fatal("a failed bind was not answered")
}
// Design 47 G 689: the value is the seat's generated finding, read by its strict decoder, key and subject by the rule.
if f, err := seat.DecodeFindingsByScopeIDKindValue(puts[key]); err != nil || f.Observer != "mesh-x" || f.Kind != Kind ||
f.Scope != "module" || f.ID != "mesh-x.placement" || f.Subject.ID != f.ID || f.Severity != "warning" || f.Source == "" {
t.Errorf("the finding is not the seat's generated one: %+v (%v)", f, err)
}
if v := string(puts[key]); !strings.Contains(v, "no consumer") || !strings.Contains(v, "mesh-x does not hear placement") {
t.Errorf("the finding is %q", v)
}
@@ -1,147 +0,0 @@
package meshconditionsclient
import (
"encoding/json"
"fmt"
"time"
seat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
)
// What an observer says it sees wrong, raised and cleared as a finding in its own state `findings` (novox/hq ADR 0564
// clause 2, ADR 0634 §4): one write shared by every observer (the self-check, the healers, the watchman, the builder,
// the indexer, the node-engine), in this seat's layout. The condition keeper raises and clears the conditions from them.
// FindingsState is the name of an observer's state of findings.
const FindingsState = "findings"
// FindingsBucket is the bucket of an observer's findings, `<module>_findings`.
func FindingsBucket(observer string) string { return observer + "_" + FindingsState }
// Observation is one thing an observer sees wrong now: what it is about (Scope, ID, Machine, Also), which kind of fault
// (Kind; Ref when the key's last part is not the kind), and its words.
type Observation struct {
Scope, ID, Kind, Ref, Machine string
Also []string
// Severity is Urgent or Warning; Warning when empty.
Severity string
// Summary is one line; Said the one observation kept as evidence (the summary when empty).
Summary, Said string
Headline, Explanation, Resolved, Needs string
// Source is the row, probe or event that saw it.
Source string
// Resolver is who resolves it, self when empty.
Resolver string
Actions []seat.Action
// Since is when the finding is stamped; the zero value leaves it to the caller's moment.
Since time.Time
}
// Key is the finding's key: `<scope>.<id>.<token>`, the token Ref or else Kind.
func (o Observation) Key() string {
token := o.Ref
if token == "" {
token = o.Kind
}
return Key(o.Scope, o.ID, token)
}
// Finding is the observation as the seat's finding written by observer in run, at the moment at.
func (o Observation) Finding(observer, run string, at time.Time) seat.FindingsByKeyValue {
at = at.UTC()
said := o.Said
if said == "" {
said = o.Summary
}
sev := o.Severity
if sev == "" {
sev = Warning
}
f := seat.FindingsByKeyValue{V: FindingVersion, Key: o.Key(), Kind: o.Kind,
Subject: seat.Subject{Scope: o.Scope, ID: o.ID, Machine: o.Machine, Also: o.Also},
Severity: sev, Summary: o.Summary, Headline: o.Headline, Explanation: o.Explanation, Resolved: o.Resolved,
Needs: o.Needs, Actions: o.Actions, Evidence: []seat.Evidence{{At: at, Said: said}}, Source: o.Source,
Resolver: o.Resolver, Observer: observer, Run: run, At: at}
if o.Ref != "" && o.Ref != o.Kind {
f.Ref = o.Ref
}
return f
}
// EncodeFinding is f as JSON at FindingVersion; it refuses what CheckFinding refuses.
func EncodeFinding(f seat.FindingsByKeyValue) ([]byte, error) {
f.V = FindingVersion
if f.Evidence == nil {
f.Evidence = []seat.Evidence{}
}
if err := CheckFinding(f); err != nil {
return nil, err
}
return json.Marshal(f)
}
// DecodeFinding reads a finding's value; it refuses another version and what CheckFinding refuses. A finding written
// before the field was named `ref` (novox/hq issue 1952) is read by its old name, `token`.
func DecodeFinding(data []byte) (seat.FindingsByKeyValue, error) {
f, err := seat.DecodeFindingsByKeyValue(data)
if err != nil {
return seat.FindingsByKeyValue{}, fmt.Errorf("health: a finding is not readable: %w", err)
}
if f.V != FindingVersion {
return seat.FindingsByKeyValue{}, fmt.Errorf("health: a finding of version %d, and this reads %d", f.V, FindingVersion)
}
if err := CheckFinding(f); err != nil {
return seat.FindingsByKeyValue{}, err
}
return f, nil
}
// Says is what a finding says, the moments and the run that wrote it aside: two findings that say the same are one
// write (novox/hq ADR 0289 §1), so the condition moves only when the words do.
func Says(f seat.FindingsByKeyValue) string {
f.At, f.Run, f.V = time.Time{}, "", 0
ev := make([]seat.Evidence, len(f.Evidence))
for i, e := range f.Evidence {
ev[i] = seat.Evidence{Said: e.Said}
}
f.Evidence = ev
raw, _ := json.Marshal(f)
return string(raw)
}
// FindingBucket is the part of an observer's state `findings` that Raise and Clear use.
type FindingBucket interface {
// Get answers the value at key; found is false when there is none.
Get(key string) (value []byte, found bool, err error)
Put(key string, value []byte) error
Delete(key string) error
}
// Raise writes the observation as observer's finding in run at at, only when what it says differs from the finding kept
// (so the keeper's condition moves only then); wrote says whether it wrote. A finding the keeper could not make a
// condition of is refused, nothing written.
func Raise(b FindingBucket, observer, run string, o Observation, at time.Time) (wrote bool, err error) {
f := o.Finding(observer, run, at)
value, err := EncodeFinding(f)
if err != nil {
return false, err
}
if kept, found, err := b.Get(f.Key); err != nil {
return false, err
} else if found {
if old, err := DecodeFinding(kept); err == nil && Says(old) == Says(f) {
return false, nil
}
}
return true, b.Put(f.Key, value)
}
// Clear deletes the finding about scope and id of kind (its token); one not there is nothing to clear, and cleared says
// whether one was.
func Clear(b FindingBucket, scope, id, token string) (cleared bool, err error) {
key := Key(scope, id, token)
if _, found, err := b.Get(key); err != nil || !found {
return false, err
}
return true, b.Delete(key)
}
@@ -1 +0,0 @@
{"v":1,"key":"machine.g14.silent","kind":"silent-kind","ref":"silent","subject":{"scope":"machine","id":"g14","machine":"g14","also":["ace"]},"severity":"urgent","summary":"g14 is silent","headline":"g14 is silent","explanation":"It said nothing.","resolved":"It speaks.","needs":"look","evidence":[{"at":"2026-11-05T12:00:00Z","said":"no pulse"}],"source":"S1","resolver":"operator","observer":"mesh-delivery-watchman","run":"r1","at":"2026-11-05T12:00:00Z"}
@@ -1 +0,0 @@
{"v":1,"key":"module.nats.g14.build-failed","kind":"build-failed","subject":{"scope":"module","id":"nats.g14"},"severity":"warning","summary":"failed","headline":"","explanation":"","resolved":"","evidence":[{"at":"2026-11-05T12:00:00Z","said":"failed"}],"source":"builder.build-failed","observer":"mesh-delivery-builder","at":"2026-11-05T12:00:00Z"}
@@ -16,7 +16,7 @@ import (
// recorder records through the seat alone, the controller's verbs being gone, and says loudly when nothing was recorded.
func TestAnActIsRecordedInTheLogThatAnswers(t *testing.T) {
// The shape of mesh-controller internal/link HandAct, as its bucket keeps an entry (handacts.go at 0fbb5ef3).
raw := `{"id":"act-1","at":"2026-10-28T09:00:00Z","by":"person.jochen","verb":"hand-act record","why":"a stuck consumer",` +
raw := `{"id":"act-1","at":"2026-10-28T09:00:00Z","by":"person.operator","verb":"hand-act record","why":"a stuck consumer",` +
`"cause":"consumer-lost","condition":"bus.EVENTS.x.consumer-lost","via":"telegram","ask":"a-1","proofs":["P1"],` +
`"requested-by":"bus.EVENTS.x.consumer-lost","outcome":"done"}`
var a seat.Act
@@ -7,6 +7,7 @@ import (
"bytes"
"encoding/json"
"errors"
"strings"
"time"
)
@@ -23,6 +24,7 @@ const (
EventConditionRaised = "condition-raised"
EventConditionChanged = "condition-changed"
EventConditionCleared = "condition-cleared"
EventFindingsAsked = "findings-asked"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
@@ -32,7 +34,7 @@ func Verbs() []string {
// Events is every event published on the seat's subject: a new copy each call.
func Events() []string {
return []string{EventConditionRaised, EventConditionChanged, EventConditionCleared}
return []string{EventConditionRaised, EventConditionChanged, EventConditionCleared, EventFindingsAsked}
}
// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects.
@@ -50,9 +52,16 @@ const SubjectConditionChanged = "mesh.seat.mesh-conditions.event.condition-chang
// SubjectConditionCleared is where condition-cleared is published.
const SubjectConditionCleared = "mesh.seat.mesh-conditions.event.condition-cleared"
// StreamFindingsAsked is the stream findings-asked is kept in.
const StreamFindingsAsked = "SEAT_mesh-conditions_findings-asked"
// SubjectFindingsAsked is where findings-asked is published.
const SubjectFindingsAsked = "mesh.seat.mesh-conditions.event.findings-asked"
const (
StateConditions = "conditions"
StateFindings = "findings"
StateConditions = "conditions"
StateFindings = "findings"
StateFindingsViews = "findings-views"
)
// ConditionsByKeyKey is the key of one value of the state conditions under the form "<key>".
@@ -86,26 +95,72 @@ func DecodeConditionsByKeyValue(raw []byte) (ConditionsByKeyValue, error) {
return v, nil
}
// FindingsByKeyKey is the key of one value of the state findings under the form "<key>".
func FindingsByKeyKey(key string) string { return key }
// FindingsByScopeIDKindKey is the key of one value of the state findings under the form "<scope>.<id>.<kind>".
func FindingsByScopeIDKindKey(scope, id, kind string) string { return scope + "." + id + "." + kind }
// ParseFindingsByKeyKey reads the parts of a key of the form "<key>", in the order of the form; the last result is false for a key of another form.
func ParseFindingsByKeyKey(key string) (string, bool) {
// ParseFindingsByScopeIDKindKey reads the parts of a key of the form "<scope>.<id>.<kind>", in the order of the form; the last result is false for a key of another form.
func ParseFindingsByScopeIDKindKey(key string) (string, string, string, bool) {
rest := key
if rest == "" {
return "", false
v0, after0, found0 := strings.Cut(rest, ".")
if !found0 || v0 == "" {
return "", "", "", false
}
v0 := rest
rest = after0
v2, after2, found2 := strings.Cut(rest, ".")
if !found2 || v2 == "" {
return "", "", "", false
}
rest = after2
if rest == "" {
return "", "", "", false
}
v4 := rest
rest = ""
if rest != "" {
return "", false
return "", "", "", false
}
return v0, true
return v0, v2, v4, true
}
// DecodeFindingsByKeyValue reads one value of the state findings under the form "<key>", refusing a field FindingsByKeyValue does not know and any text after the value.
func DecodeFindingsByKeyValue(raw []byte) (FindingsByKeyValue, error) {
var v FindingsByKeyValue
// DecodeFindingsByScopeIDKindValue reads one value of the state findings under the form "<scope>.<id>.<kind>", refusing a field FindingsByScopeIDKindValue does not know and any text after the value.
func DecodeFindingsByScopeIDKindValue(raw []byte) (FindingsByScopeIDKindValue, error) {
var v FindingsByScopeIDKindValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// FindingsViewsByObserverNodeKey is the key of one value of the state findings-views under the form "<observer>.<node>".
func FindingsViewsByObserverNodeKey(observer, node string) string { return observer + "." + node }
// ParseFindingsViewsByObserverNodeKey reads the parts of a key of the form "<observer>.<node>", in the order of the form; the last result is false for a key of another form.
func ParseFindingsViewsByObserverNodeKey(key string) (string, string, bool) {
rest := key
v0, after0, found0 := strings.Cut(rest, ".")
if !found0 || v0 == "" {
return "", "", false
}
rest = after0
if rest == "" {
return "", "", false
}
v2 := rest
rest = ""
if rest != "" {
return "", "", false
}
return v0, v2, true
}
// DecodeFindingsViewsByObserverNodeValue reads one value of the state findings-views under the form "<observer>.<node>", refusing a field FindingsViewsByObserverNodeValue does not know and any text after the value.
func DecodeFindingsViewsByObserverNodeValue(raw []byte) (FindingsViewsByObserverNodeValue, error) {
var v FindingsViewsByObserverNodeValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
@@ -177,8 +232,10 @@ type ConditionEvent struct {
LooksUnread string `json:"looks-unread,omitempty"`
Needs string `json:"needs,omitempty"`
Observations int64 `json:"observations,omitempty"`
Raised *time.Time `json:"raised,omitempty"`
Resolved string `json:"resolved,omitempty"`
// who the condition is about, taken from the finding or handed to operator-channel by the keeper: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge:<account> (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)
Owner string `json:"owner,omitempty"`
Raised *time.Time `json:"raised,omitempty"`
Resolved string `json:"resolved,omitempty"`
// self, operator, agent or healer:<name>
Resolver string `json:"resolver,omitempty"`
Severity string `json:"severity,omitempty"`
@@ -191,8 +248,10 @@ type ConditionEvent struct {
// one line
Summary string `json:"summary,omitempty"`
Tried []ConditionEventTriedItem `json:"tried,omitempty"`
Was string `json:"was,omitempty"`
Why string `json:"why,omitempty"`
// what it waits on, from the finding: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge:<account> (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)
WaitingOn string `json:"waiting-on,omitempty"`
Was string `json:"was,omitempty"`
Why string `json:"why,omitempty"`
}
// The values of ConditionEvent's change.
@@ -205,6 +264,7 @@ const (
ConditionEventChangeSilenceEnded = "silence-ended"
ConditionEventChangeCleared = "cleared"
ConditionEventChangeWords = "words"
ConditionEventChangeOwner = "owner"
)
// The values of ConditionEvent's severity.
@@ -231,6 +291,80 @@ type Subject struct {
Scope string `json:"scope"`
}
// Finding is one finding as an observer says it: the layout whole, plus scope, id and since (design 47 G 437, 439).
type Finding struct {
Actions []Action `json:"actions,omitempty"`
At time.Time `json:"at"`
// newest first, at most 10
Evidence []Evidence `json:"evidence,omitempty"`
Explanation string `json:"explanation,omitempty"`
Headline string `json:"headline,omitempty"`
// the key's second part
ID string `json:"id"`
Kind string `json:"kind"`
Needs string `json:"needs,omitempty"`
// the module that wrote it
Observer string `json:"observer"`
// who the finding is about, when not the observer: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge:<account> (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)
Owner string `json:"owner,omitempty"`
// the key's last part when it is not the kind
Ref string `json:"ref,omitempty"`
// self, operator, agent or healer:<name>
Resolver string `json:"resolver,omitempty"`
// what of its own saw it last
Run string `json:"run,omitempty"`
// the key's first part: <scope>.<id>.<kind> (ADR 0564)
Scope string `json:"scope"`
Severity string `json:"severity"`
// since when the finding stands
Since time.Time `json:"since"`
// the row, probe or event that saw it
Source string `json:"source"`
Subject Subject `json:"subject"`
// one line
Summary string `json:"summary"`
// what it waits on: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge:<account> (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)
WaitingOn string `json:"waiting-on,omitempty"`
}
// The values of Finding's severity.
const (
FindingSeverityUrgent = "urgent"
FindingSeverityWarning = "warning"
)
// FindingCleared is an observer no longer observes a finding.
type FindingCleared struct {
At time.Time `json:"at"`
ID string `json:"id"`
Kind string `json:"kind"`
Scope string `json:"scope"`
Why string `json:"why"`
}
// FindingWritten is a type of the contract.
type FindingWritten = Finding
// FindingsStatedPendingItem is a type of the contract.
type FindingsStatedPendingItem struct {
// a duration such as 5m
Bound string `json:"bound"`
Key string `json:"key"`
Since time.Time `json:"since"`
}
// FindingsStated is every finding an observer observes now, at its start and when asked (design 47 G 384, 439).
type FindingsStated struct {
// the ask it answers; none at a start
Asked string `json:"asked,omitempty"`
At time.Time `json:"at"`
Findings []Finding `json:"findings"`
// the finding kinds the stating bundle owns and states, the only kinds whose keys the statement deletes and whose conditions the keeper clears when it names none of them; none covers every kind, as a part with one bundle states (design 47 G 580)
Kinds []string `json:"kinds,omitempty"`
// the keys the observer cannot judge yet since its start, with their since and bound
Pending []FindingsStatedPendingItem `json:"pending"`
}
// ConditionsInput is what conditions takes.
type ConditionsInput struct {
// with history: how many days back (default 7, at most 90)
@@ -273,6 +407,8 @@ type SilenceAnswer = map[string]any
// ResyncInput is what resync takes.
type ResyncInput struct {
// ask this observer alone; none asks all
Module string `json:"module,omitempty"`
}
// ResyncAnswer is what resync answers.
@@ -287,6 +423,17 @@ type ConditionChangedEvent = ConditionEvent
// ConditionClearedEvent is the body of the event condition-cleared.
type ConditionClearedEvent = ConditionEvent
// FindingsAskedEvent is the body of the event findings-asked.
type FindingsAskedEvent struct {
// the ask's id
Ask string `json:"ask"`
At time.Time `json:"at"`
// who asked: the keeper, or the person or session that called resync
By string `json:"by"`
// to ask one observer; none asks all
Module string `json:"module,omitempty"`
}
// ConditionsByKeyValueGapsItem is a type of the contract.
type ConditionsByKeyValueGapsItem struct {
Cleared *time.Time `json:"cleared,omitempty"`
@@ -327,8 +474,10 @@ type ConditionsByKeyValue struct {
LooksUnread string `json:"looks-unread,omitempty"`
Needs string `json:"needs,omitempty"`
Observations int64 `json:"observations,omitempty"`
Raised time.Time `json:"raised"`
Resolved string `json:"resolved,omitempty"`
// who the condition is about, taken from the finding or handed to operator-channel by the keeper: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge:<account> (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)
Owner string `json:"owner,omitempty"`
Raised time.Time `json:"raised"`
Resolved string `json:"resolved,omitempty"`
// self, operator, agent or healer:<name>
Resolver string `json:"resolver,omitempty"`
Severity string `json:"severity"`
@@ -339,6 +488,8 @@ type ConditionsByKeyValue struct {
// one line
Summary string `json:"summary,omitempty"`
Tried []ConditionsByKeyValueTriedItem `json:"tried,omitempty"`
// what it waits on, from the finding: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge:<account> (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)
WaitingOn string `json:"waiting-on,omitempty"`
}
// The values of ConditionsByKeyValue's severity.
@@ -347,39 +498,24 @@ const (
ConditionsByKeyValueSeverityWarning = "warning"
)
// FindingsByKeyValue is one value of the state findings under the key <key>.
type FindingsByKeyValue struct {
Actions []Action `json:"actions,omitempty"`
At time.Time `json:"at"`
// newest first, at most 10
Evidence []Evidence `json:"evidence,omitempty"`
Explanation string `json:"explanation,omitempty"`
Headline string `json:"headline,omitempty"`
// scope.id.token
Key string `json:"key"`
Kind string `json:"kind"`
Needs string `json:"needs,omitempty"`
// the module that wrote it
Observer string `json:"observer"`
// the key's last part when it is not the kind
Ref string `json:"ref,omitempty"`
Resolved string `json:"resolved,omitempty"`
// self, operator, agent or healer:<name>
Resolver string `json:"resolver,omitempty"`
// what of its own saw it last
Run string `json:"run,omitempty"`
Severity string `json:"severity"`
// the row, probe or event that saw it
Source string `json:"source"`
Subject Subject `json:"subject"`
// one line
Summary string `json:"summary"`
// layout version, 1
V int64 `json:"v"`
// FindingsByScopeIDKindValue is one value of the state findings under the key <scope>.<id>.<kind>.
type FindingsByScopeIDKindValue = Finding
// FindingsViewsByObserverNodeValueStated is the last findings-stated set.
type FindingsViewsByObserverNodeValueStated struct {
At *time.Time `json:"at,omitempty"`
Findings []Finding `json:"findings,omitempty"`
}
// The values of FindingsByKeyValue's severity.
const (
FindingsByKeyValueSeverityUrgent = "urgent"
FindingsByKeyValueSeverityWarning = "warning"
)
// FindingsViewsByObserverNodeValue is one value of the state findings-views under the key <observer>.<node>.
type FindingsViewsByObserverNodeValue struct {
// the open asks
Asks []string `json:"asks,omitempty"`
Node string `json:"node"`
Observer string `json:"observer"`
// the keys it cannot judge yet
Pending []string `json:"pending,omitempty"`
// the last findings-stated set
Stated *FindingsViewsByObserverNodeValueStated `json:"stated,omitempty"`
V int64 `json:"v"`
}
@@ -17,14 +17,46 @@ func TestFixtures(t *testing.T) {
decode func([]byte) (any, error)
subjectIs *regexp.Regexp
}{
{name: "a condition raised from a finding, as the keeper holds it (captured; empty fields left out)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}",
{name: "the keeper asks one observer to state its findings", subject: "mesh.seat.mesh-conditions.event.findings-asked", given: "{\"ask\":\"a-20261111t100000\",\"at\":\"2026-11-11T10:00:00Z\",\"by\":\"operator\",\"module\":\"mesh-host\"}", wire: "{\"ask\":\"a-20261111t100000\",\"at\":\"2026-11-11T10:00:00Z\",\"by\":\"operator\",\"module\":\"mesh-host\"}",
decode: func(b []byte) (any, error) { var v FindingsAskedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.findings-asked$")},
{name: "the keeper asks every observer", subject: "mesh.seat.mesh-conditions.event.findings-asked", given: "{\"ask\":\"a-20261111t100100\",\"at\":\"2026-11-11T10:01:00Z\",\"by\":\"mesh-conditions\"}", wire: "{\"ask\":\"a-20261111t100100\",\"at\":\"2026-11-11T10:01:00Z\",\"by\":\"mesh-conditions\"}",
decode: func(b []byte) (any, error) { var v FindingsAskedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.findings-asked$")},
{name: "a condition raised with its owner and what it waits on (design 47 G 685)", subject: "mesh.seat.mesh-conditions.event.condition-raised", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"change\":\"raised\",\"event\":\"condition-raised\",\"key\":\"module.mesh-host.home-server.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"owner\":\"forge:operator\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"change\":\"raised\",\"event\":\"condition-raised\",\"key\":\"module.mesh-host.home-server.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"owner\":\"forge:operator\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}",
decode: func(b []byte) (any, error) { var v ConditionRaisedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.condition-raised$")},
{name: "a condition's owner handed to the operator after two hours (design 47 G 540, A-58)", subject: "mesh.seat.mesh-conditions.event.condition-changed", given: "{\"at\":\"2026-11-11T12:00:00Z\",\"change\":\"owner\",\"event\":\"condition-changed\",\"key\":\"module.mesh-delivery.home-server.pipeline-failed\",\"kind\":\"pipeline-failed\",\"owner\":\"operator-channel\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"runner\",\"subject\":{\"id\":\"mesh-delivery.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"a head failed its pipeline\",\"waiting-on\":\"operator-channel\",\"was\":\"forge:operator\"}", wire: "{\"at\":\"2026-11-11T12:00:00Z\",\"change\":\"owner\",\"event\":\"condition-changed\",\"key\":\"module.mesh-delivery.home-server.pipeline-failed\",\"kind\":\"pipeline-failed\",\"owner\":\"operator-channel\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"runner\",\"subject\":{\"id\":\"mesh-delivery.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"a head failed its pipeline\",\"waiting-on\":\"operator-channel\",\"was\":\"forge:operator\"}",
decode: func(b []byte) (any, error) { var v ConditionChangedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.condition-changed$")},
{name: "a condition raised from a finding, as the keeper holds it (captured; empty fields left out)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}",
decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a condition with an empty evidence trail of headline (captured; empty fields left out)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-30T13:03:46.432309782Z\",\"said\":\"The backup of postgres failed on ace\"}],\"explanation\":\"Needs you: answer whether to back up again or go on without a backup. The backup before applying postgres at 978b5db8cb4e on ace failed: node-backup.now could not be asked: not asked: nothing on this machine answers mesh.seat.node-backup.tool.now.ace.\",\"headline\":\"The backup of postgres failed on ace\",\"key\":\"module.ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f.backup\",\"kind\":\"backup\",\"last-observed\":\"2026-10-30T13:03:46.432309782Z\",\"needs\":\"answer whether to back up again or go on without a backup\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.069818178Z\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"assigner.backup\",\"subject\":{\"id\":\"ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"The backup of postgres failed on ace\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-30T13:03:46.432309782Z\",\"said\":\"The backup of postgres failed on ace\"}],\"explanation\":\"Needs you: answer whether to back up again or go on without a backup. The backup before applying postgres at 978b5db8cb4e on ace failed: node-backup.now could not be asked: not asked: nothing on this machine answers mesh.seat.node-backup.tool.now.ace.\",\"headline\":\"The backup of postgres failed on ace\",\"key\":\"module.ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f.backup\",\"kind\":\"backup\",\"last-observed\":\"2026-10-30T13:03:46.432309782Z\",\"needs\":\"answer whether to back up again or go on without a backup\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.069818178Z\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"assigner.backup\",\"subject\":{\"id\":\"ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"The backup of postgres failed on ace\"}",
decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a finding of the bus scope with its zero time (captured from the watchman; empty fields left out)", subject: "", given: "{\"at\":\"0001-01-01T00:00:00Z\",\"evidence\":[{\"at\":\"0001-01-01T00:00:00Z\",\"said\":\"1 held for EVENTS.controller (counted again every 5m0s while any is held, so one delivered again or dropped ends this within it)\"}],\"key\":\"bus.EVENTS.controller.max-deliveries\",\"kind\":\"max-deliveries\",\"needs\":\"deliver them again or drop them, from the mesh MCP server.\",\"observer\":\"mesh-delivery-watchman\",\"severity\":\"warning\",\"source\":\"S9\",\"subject\":{\"id\":\"EVENTS.controller\",\"scope\":\"bus\"},\"summary\":\"the controller's consumer on EVENTS gave up on a message; it is kept in DEAD_LETTERS until delivered again or dropped, with why\",\"v\":1}", wire: "{\"at\":\"0001-01-01T00:00:00Z\",\"evidence\":[{\"at\":\"0001-01-01T00:00:00Z\",\"said\":\"1 held for EVENTS.controller (counted again every 5m0s while any is held, so one delivered again or dropped ends this within it)\"}],\"key\":\"bus.EVENTS.controller.max-deliveries\",\"kind\":\"max-deliveries\",\"needs\":\"deliver them again or drop them, from the mesh MCP server.\",\"observer\":\"mesh-delivery-watchman\",\"severity\":\"warning\",\"source\":\"S9\",\"subject\":{\"id\":\"EVENTS.controller\",\"scope\":\"bus\"},\"summary\":\"the controller's consumer on EVENTS gave up on a message; it is kept in DEAD_LETTERS until delivered again or dropped, with why\",\"v\":1}",
decode: func(b []byte) (any, error) { var v FindingsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a finding of the module scope with its machine (captured from the watchman; empty fields left out)", subject: "", given: "{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: owned by 10005:10005, mode 700, as found\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observer\":\"mesh-delivery-watchman\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found\",\"v\":1}", wire: "{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: owned by 10005:10005, mode 700, as found\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observer\":\"mesh-delivery-watchman\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found\",\"v\":1}",
decode: func(b []byte) (any, error) { var v FindingsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a condition carrying its finding's owner, a session, and what it waits on, a seat (design 47 G 685)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on home-server, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on home-server\",\"key\":\"module.mesh-build-node.home-server.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator@workstation\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on home-server is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"node-engine\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on home-server, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on home-server\",\"key\":\"module.mesh-build-node.home-server.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator@workstation\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on home-server is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"node-engine\"}",
decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a condition owned by a commit's author, handed to operator-channel when the keeper hands it over (design 47 G 685, 540)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on home-server, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on home-server\",\"key\":\"module.mesh-build-node.home-server.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator-channel\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on home-server is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"forge:operator\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on home-server, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on home-server\",\"key\":\"module.mesh-build-node.home-server.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator-channel\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on home-server is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"forge:operator\"}",
decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a finding of the bus scope with its zero time (in the finding layout (design 47 G 660))", subject: "", given: "{\"at\":\"0001-01-01T00:00:00Z\",\"evidence\":[{\"at\":\"0001-01-01T00:00:00Z\",\"said\":\"1 held for EVENTS.controller (counted again every 5m0s while any is held, so one delivered again or dropped ends this within it)\"}],\"id\":\"EVENTS.controller\",\"kind\":\"max-deliveries\",\"needs\":\"deliver them again or drop them, from the mesh MCP server.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"bus\",\"severity\":\"warning\",\"since\":\"0001-01-01T00:00:00Z\",\"source\":\"S9\",\"subject\":{\"id\":\"EVENTS.controller\",\"scope\":\"bus\"},\"summary\":\"the controller's consumer on EVENTS gave up on a message; it is kept in DEAD_LETTERS until delivered again or dropped, with why\"}", wire: "{\"at\":\"0001-01-01T00:00:00Z\",\"evidence\":[{\"at\":\"0001-01-01T00:00:00Z\",\"said\":\"1 held for EVENTS.controller (counted again every 5m0s while any is held, so one delivered again or dropped ends this within it)\"}],\"id\":\"EVENTS.controller\",\"kind\":\"max-deliveries\",\"needs\":\"deliver them again or drop them, from the mesh MCP server.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"bus\",\"severity\":\"warning\",\"since\":\"0001-01-01T00:00:00Z\",\"source\":\"S9\",\"subject\":{\"id\":\"EVENTS.controller\",\"scope\":\"bus\"},\"summary\":\"the controller's consumer on EVENTS gave up on a message; it is kept in DEAD_LETTERS until delivered again or dropped, with why\"}",
decode: func(b []byte) (any, error) {
var v FindingsByScopeIDKindValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a finding of the module scope with its machine (in the finding layout (design 47 G 660))", subject: "", given: "{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: owned by 10005:10005, mode 700, as found\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"id\":\"mesh-build-node.home-server\",\"kind\":\"directory-used-as-found\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-10-26T20:19:41.474823121Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found\"}", wire: "{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: owned by 10005:10005, mode 700, as found\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"id\":\"mesh-build-node.home-server\",\"kind\":\"directory-used-as-found\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-10-26T20:19:41.474823121Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found\"}",
decode: func(b []byte) (any, error) {
var v FindingsByScopeIDKindValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a finding owned by a session and waiting on a seat (design 47 G 678)", subject: "", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.home-server\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"operator@workstation\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.home-server\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"operator@workstation\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}",
decode: func(b []byte) (any, error) {
var v FindingsByScopeIDKindValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a finding owned by a seat and waiting on a commit's author (design 47 G 678, 540)", subject: "", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.home-server\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"node-engine\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"forge:operator\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.home-server\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"node-engine\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"forge:operator\"}",
decode: func(b []byte) (any, error) {
var v FindingsByScopeIDKindValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
@@ -20,7 +20,8 @@ const (
)
const (
EventHealerActed = "healer-acted"
EventHealerActed = "healer-acted"
EventAttemptChanged = "attempt-changed"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
@@ -30,7 +31,7 @@ func Verbs() []string {
// Events is every event published on the seat's subject: a new copy each call.
func Events() []string {
return []string{EventHealerActed}
return []string{EventHealerActed, EventAttemptChanged}
}
// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects.
@@ -42,6 +43,17 @@ const (
// SubjectHealerActed is where healer-acted is published.
const SubjectHealerActed = "mesh.seat.mesh-healers.event.healer-acted"
// StreamAttemptChanged is the stream attempt-changed is kept in.
const StreamAttemptChanged = "SEAT_mesh-healers_attempt-changed"
// SubjectAttemptChanged is where attempt-changed is published, on mesh.seat.mesh-healers.event.attempt-changed.<condition>.<attempt>.
func SubjectAttemptChanged(condition, attempt string) string {
return "mesh.seat.mesh-healers.event.attempt-changed." + condition + "." + attempt
}
// SubjectAttemptChangedAll hears every attempt-changed.
const SubjectAttemptChangedAll = "mesh.seat.mesh-healers.event.attempt-changed.*.*"
const (
StateAttempts = "attempts"
StateWould = "would"
@@ -165,6 +177,32 @@ const (
HealerActedEventOutcomeEscalated = "escalated"
)
// AttemptChangedEvent is the body of the event attempt-changed.
type AttemptChangedEvent struct {
Act string `json:"act,omitempty"`
Begun *time.Time `json:"begun,omitempty"`
// what the budget counts by: the condition's key unless the healer says another
BudgetKey string `json:"budget-key,omitempty"`
Condition string `json:"condition,omitempty"`
Finished *time.Time `json:"finished,omitempty"`
Healer string `json:"healer,omitempty"`
Kind string `json:"kind,omitempty"`
Outcome string `json:"outcome,omitempty"`
// true when the healer ends the attempt
Removed bool `json:"removed,omitempty"`
Said string `json:"said,omitempty"`
// the end of that key's lifetime, which the keeper drops the attempt at on its own clock
Until *time.Time `json:"until,omitempty"`
}
// The values of AttemptChangedEvent's outcome.
const (
AttemptChangedEventOutcomeActing = "acting"
AttemptChangedEventOutcomeActed = "acted"
AttemptChangedEventOutcomeFailed = "failed"
AttemptChangedEventOutcomeEscalated = "escalated"
)
// AttemptsByAttemptValue is one value of the state attempts under the key <attempt>.
type AttemptsByAttemptValue struct {
Act string `json:"act"`
@@ -17,6 +17,10 @@ func TestFixtures(t *testing.T) {
decode func([]byte) (any, error)
subjectIs *regexp.Regexp
}{
{name: "an attempt begun, said with its end (design 47 G 665)", subject: "mesh.seat.mesh-healers.event.attempt-changed.c-1.a-1", given: "{\"act\":\"hand-over\",\"begun\":\"2026-11-11T10:00:00Z\",\"budget-key\":\"module.mesh-host.home-server.directory-used-as-found\",\"condition\":\"module.mesh-host.home-server.directory-used-as-found\",\"healer\":\"directory\",\"kind\":\"directory-used-as-found\",\"outcome\":\"acting\",\"until\":\"2026-11-11T12:00:00Z\"}", wire: "{\"act\":\"hand-over\",\"begun\":\"2026-11-11T10:00:00Z\",\"budget-key\":\"module.mesh-host.home-server.directory-used-as-found\",\"condition\":\"module.mesh-host.home-server.directory-used-as-found\",\"healer\":\"directory\",\"kind\":\"directory-used-as-found\",\"outcome\":\"acting\",\"until\":\"2026-11-11T12:00:00Z\"}",
decode: func(b []byte) (any, error) { var v AttemptChangedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-healers\\.event\\.attempt-changed\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "an attempt ended by its healer", subject: "mesh.seat.mesh-healers.event.attempt-changed.c-1.a-1", given: "{\"condition\":\"module.mesh-host.home-server.directory-used-as-found\",\"removed\":true}", wire: "{\"condition\":\"module.mesh-host.home-server.directory-used-as-found\",\"removed\":true}",
decode: func(b []byte) (any, error) { var v AttemptChangedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-healers\\.event\\.attempt-changed\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "an act a healer would have made, kept from the controller's time (captured)", subject: "", given: "{\"act\":\"assert the module's buckets, logs and streams again through the grants part (grants_assert)\",\"at\":\"2026-11-02T08:15:56.49507336Z\",\"condition\":\"bus.EVENTS.4fs9xzyDY7CD2Cf1wVFYDK_1.consumer-lost\",\"healer\":\"H3\",\"kind\":\"consumer-lost\",\"why\":\"the controller's lease names a controller (or none is written, so one may take it): every act is written as would\"}", wire: "{\"act\":\"assert the module's buckets, logs and streams again through the grants part (grants_assert)\",\"at\":\"2026-11-02T08:15:56.49507336Z\",\"condition\":\"bus.EVENTS.4fs9xzyDY7CD2Cf1wVFYDK_1.consumer-lost\",\"healer\":\"H3\",\"kind\":\"consumer-lost\",\"why\":\"the controller's lease names a controller (or none is written, so one may take it): every act is written as would\"}",
decode: func(b []byte) (any, error) { var v WouldByWouldValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
@@ -22,11 +22,49 @@ const (
VerbResync = "resync"
)
const (
EventMachineAway = "machine-away"
EventMachineBack = "machine-back"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbSignals, VerbStuck, VerbPresence, VerbDeadLetters, VerbResync}
}
// Events is every event published on the seat's subject: a new copy each call.
func Events() []string {
return []string{EventMachineAway, EventMachineBack}
}
// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects.
const (
Family = "mesh-watchdogs.events"
FamilyMaxAgeDays = 7
)
// StreamMachineAway is the stream machine-away is kept in.
const StreamMachineAway = "SEAT_mesh-watchdogs_machine-away"
// SubjectMachineAway is where machine-away is published, on mesh.seat.mesh-watchdogs.event.machine-away.<machine>.
func SubjectMachineAway(machine string) string {
return "mesh.seat.mesh-watchdogs.event.machine-away." + machine
}
// SubjectMachineAwayAll hears every machine-away.
const SubjectMachineAwayAll = "mesh.seat.mesh-watchdogs.event.machine-away.*"
// StreamMachineBack is the stream machine-back is kept in.
const StreamMachineBack = "SEAT_mesh-watchdogs_machine-back"
// SubjectMachineBack is where machine-back is published, on mesh.seat.mesh-watchdogs.event.machine-back.<machine>.
func SubjectMachineBack(machine string) string {
return "mesh.seat.mesh-watchdogs.event.machine-back." + machine
}
// SubjectMachineBackAll hears every machine-back.
const SubjectMachineBackAll = "mesh.seat.mesh-watchdogs.event.machine-back.*"
const (
StatePresence = "presence"
StatePulse = "pulse"
@@ -202,8 +240,31 @@ type PresenceInput struct {
Machine string `json:"machine,omitempty"`
}
// PresenceAnswerKeysItem is a type of the contract.
type PresenceAnswerKeysItem struct {
// <node> or part.<part>.<instance>
Key string `json:"key"`
// the key's revision
Revision int64 `json:"revision,omitempty"`
// the key's value, online and its layout's version
Value map[string]any `json:"value"`
}
// PresenceAnswer is what presence answers.
type PresenceAnswer = map[string]any
type PresenceAnswer struct {
// without machine: how many keys the state holds
Holds int64 `json:"holds,omitempty"`
// without machine: each key of the state presence, <node> or part.<part>.<instance>, with its value
Keys []PresenceAnswerKeysItem `json:"keys,omitempty"`
// the machine asked, with machine
Machine string `json:"machine,omitempty"`
// with machine: whether the watchman hears the machine now; false for a machine it holds no word of
Online bool `json:"online,omitempty"`
// with machine: when its presence last changed, RFC 3339; empty for a machine the watchman holds no word of
Since string `json:"since,omitempty"`
// without machine: the state read, presence
State string `json:"state,omitempty"`
}
// DeadLettersInput is what dead-letters takes.
type DeadLettersInput struct {
@@ -233,6 +294,28 @@ type ResyncInput struct {
// ResyncAnswer is what resync answers.
type ResyncAnswer = map[string]any
// MachineAwayEvent is the body of the event machine-away.
type MachineAwayEvent struct {
At time.Time `json:"at"`
// when the machine was last heard
LastHeard time.Time `json:"last-heard"`
// the machine whose presence changed
Machine string `json:"machine"`
// the layout's version
V int64 `json:"v"`
}
// MachineBackEvent is the body of the event machine-back.
type MachineBackEvent struct {
At time.Time `json:"at"`
// when the machine was last heard
LastHeard time.Time `json:"last-heard"`
// the machine whose presence changed
Machine string `json:"machine"`
// the layout's version
V int64 `json:"v"`
}
// PresenceByNodeValue is one value of the state presence under the key <node>.
type PresenceByNodeValue struct {
Online bool `json:"online"`
@@ -17,6 +17,10 @@ func TestFixtures(t *testing.T) {
decode func([]byte) (any, error)
subjectIs *regexp.Regexp
}{
{name: "a machine's presence expired", subject: "mesh.seat.mesh-watchdogs.event.machine-away.laptop", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"last-heard\":\"2026-11-11T09:58:00Z\",\"machine\":\"laptop\",\"v\":1}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"last-heard\":\"2026-11-11T09:58:00Z\",\"machine\":\"laptop\",\"v\":1}",
decode: func(b []byte) (any, error) { var v MachineAwayEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-watchdogs\\.event\\.machine-away\\.[^.*> ]+$")},
{name: "a machine heard again", subject: "mesh.seat.mesh-watchdogs.event.machine-back.laptop", given: "{\"at\":\"2026-11-11T10:30:00Z\",\"last-heard\":\"2026-11-11T10:30:00Z\",\"machine\":\"laptop\",\"v\":1}", wire: "{\"at\":\"2026-11-11T10:30:00Z\",\"last-heard\":\"2026-11-11T10:30:00Z\",\"machine\":\"laptop\",\"v\":1}",
decode: func(b []byte) (any, error) { var v MachineBackEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-watchdogs\\.event\\.machine-back\\.[^.*> ]+$")},
{name: "a node's agent online (captured)", subject: "", given: "{\"online\":true,\"v\":1}", wire: "{\"online\":true,\"v\":1}",
decode: func(b []byte) (any, error) { var v PresenceByNodeValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a delivery part's instance online (captured)", subject: "", given: "{\"online\":true,\"v\":1}", wire: "{\"online\":true,\"v\":1}",
+11 -15
View File
@@ -1,6 +1,6 @@
{
"module": "mesh-health-and-repair-contracts",
"version": "1",
"version": "0.1",
"build": {
"artifacts": [
{
@@ -10,7 +10,6 @@
"paths": [
"go/seats/meshconditions"
],
"series": "0.1",
"generated-from": "."
},
{
@@ -20,7 +19,6 @@
"paths": [
"go/seats/meshselfcheck"
],
"series": "0.1",
"generated-from": "."
},
{
@@ -30,7 +28,6 @@
"paths": [
"go/seats/meshhealers"
],
"series": "0.1",
"generated-from": "."
},
{
@@ -40,7 +37,6 @@
"paths": [
"go/seats/meshwatchdogs"
],
"series": "0.1",
"generated-from": "."
},
{
@@ -50,7 +46,6 @@
"paths": [
"go/seats/meshhandacts"
],
"series": "0.1",
"generated-from": "."
},
{
@@ -59,8 +54,15 @@
"language": "go",
"paths": [
"go/clients/meshhandactsclient"
],
"series": "0.1"
]
},
{
"name": "go-meshwatchdogsclient",
"kind": "package",
"language": "go",
"paths": [
"go/clients/meshwatchdogsclient"
]
},
{
"name": "go-meshconditionsclient",
@@ -68,8 +70,7 @@
"language": "go",
"paths": [
"go/clients/meshconditionsclient"
],
"series": "0.1"
]
},
{
"name": "ts-meshconditions",
@@ -78,7 +79,6 @@
"paths": [
"ts/seats/meshconditions"
],
"series": "0.1",
"generated-from": "."
},
{
@@ -88,7 +88,6 @@
"paths": [
"ts/seats/meshselfcheck"
],
"series": "0.1",
"generated-from": "."
},
{
@@ -98,7 +97,6 @@
"paths": [
"ts/seats/meshhealers"
],
"series": "0.1",
"generated-from": "."
},
{
@@ -108,7 +106,6 @@
"paths": [
"ts/seats/meshwatchdogs"
],
"series": "0.1",
"generated-from": "."
},
{
@@ -118,7 +115,6 @@
"paths": [
"ts/seats/meshhandacts"
],
"series": "0.1",
"generated-from": "."
}
]
@@ -0,0 +1,70 @@
[
{
"name": "the keeper asks one observer to state its findings",
"of": "event:findings-asked",
"subject": "mesh.seat.mesh-conditions.event.findings-asked",
"given": {
"ask": "a-20261111t100000",
"at": "2026-11-11T10:00:00Z",
"by": "operator",
"module": "mesh-host"
}
},
{
"name": "the keeper asks every observer",
"of": "event:findings-asked",
"subject": "mesh.seat.mesh-conditions.event.findings-asked",
"given": {
"ask": "a-20261111t100100",
"at": "2026-11-11T10:01:00Z",
"by": "mesh-conditions"
}
},
{
"name": "a condition raised with its owner and what it waits on (design 47 G 685)",
"of": "event:condition-raised",
"subject": "mesh.seat.mesh-conditions.event.condition-raised",
"given": {
"key": "module.mesh-host.home-server.directory-used-as-found",
"kind": "directory-used-as-found",
"subject": {
"scope": "module",
"id": "mesh-host.home-server",
"machine": "home-server"
},
"severity": "warning",
"summary": "a directory waits for a hand",
"source": "health-report",
"resolver": "self",
"owner": "forge:operator",
"waiting-on": "node-engine",
"event": "condition-raised",
"at": "2026-11-11T10:00:00Z",
"change": "raised"
}
},
{
"name": "a condition's owner handed to the operator after two hours (design 47 G 540, A-58)",
"of": "event:condition-changed",
"subject": "mesh.seat.mesh-conditions.event.condition-changed",
"given": {
"key": "module.mesh-delivery.home-server.pipeline-failed",
"kind": "pipeline-failed",
"subject": {
"scope": "module",
"id": "mesh-delivery.home-server",
"machine": "home-server"
},
"severity": "warning",
"summary": "a head failed its pipeline",
"source": "runner",
"resolver": "self",
"owner": "operator-channel",
"waiting-on": "operator-channel",
"event": "condition-changed",
"at": "2026-11-11T12:00:00Z",
"change": "owner",
"was": "forge:operator"
}
}
]
@@ -7,7 +7,7 @@
"evidence": [
{
"at": "2026-10-26T20:19:41.474823121Z",
"said": "mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it \u2014 `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh"
"said": "mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh"
}
],
"explanation": "Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.",
@@ -27,7 +27,7 @@
"machine": "ace",
"scope": "module"
},
"summary": "mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it \u2014 `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh"
"summary": "mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh"
}
},
{
@@ -61,11 +61,75 @@
}
},
{
"name": "a finding of the bus scope with its zero time (captured from the watchman; empty fields left out)",
"of": "state:findings/<key>",
"name": "a condition carrying its finding's owner, a session, and what it waits on, a seat (design 47 G 685)",
"of": "state:conditions/<key>",
"given": {
"count": 1,
"evidence": [
{
"at": "2026-10-26T20:19:41.474823121Z",
"said": "mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh"
}
],
"explanation": "Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on home-server, with another owner or mode than mesh-build-node declares.",
"headline": "mesh-build-node waits for a directory on home-server",
"key": "module.mesh-build-node.home-server.directory-used-as-found",
"kind": "directory-used-as-found",
"last-observed": "2026-10-26T20:19:41.474823121Z",
"needs": "hand the directory over from the control-node, as the operator; the details name it and the line to type.",
"observations": 1,
"raised": "2026-10-31T08:19:57.076843727Z",
"resolved": "mesh-build-node's directory on home-server is the mesh's",
"resolver": "self",
"severity": "warning",
"source": "health-report",
"subject": {
"id": "mesh-build-node.home-server",
"machine": "home-server",
"scope": "module"
},
"summary": "mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh",
"owner": "operator@workstation",
"waiting-on": "node-engine"
}
},
{
"name": "a condition owned by a commit's author, handed to operator-channel when the keeper hands it over (design 47 G 685, 540)",
"of": "state:conditions/<key>",
"given": {
"count": 1,
"evidence": [
{
"at": "2026-10-26T20:19:41.474823121Z",
"said": "mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh"
}
],
"explanation": "Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on home-server, with another owner or mode than mesh-build-node declares.",
"headline": "mesh-build-node waits for a directory on home-server",
"key": "module.mesh-build-node.home-server.directory-used-as-found",
"kind": "directory-used-as-found",
"last-observed": "2026-10-26T20:19:41.474823121Z",
"needs": "hand the directory over from the control-node, as the operator; the details name it and the line to type.",
"observations": 1,
"raised": "2026-10-31T08:19:57.076843727Z",
"resolved": "mesh-build-node's directory on home-server is the mesh's",
"resolver": "self",
"severity": "warning",
"source": "health-report",
"subject": {
"id": "mesh-build-node.home-server",
"machine": "home-server",
"scope": "module"
},
"summary": "mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh",
"owner": "operator-channel",
"waiting-on": "forge:operator"
}
},
{
"name": "a finding of the bus scope with its zero time (in the finding layout (design 47 G 660))",
"of": "state:findings/<scope>.<id>.<kind>",
"given": {
"v": 1,
"key": "bus.EVENTS.controller.max-deliveries",
"kind": "max-deliveries",
"subject": {
"id": "EVENTS.controller",
@@ -82,15 +146,16 @@
"said": "1 held for EVENTS.controller (counted again every 5m0s while any is held, so one delivered again or dropped ends this within it)"
}
],
"at": "0001-01-01T00:00:00Z"
"at": "0001-01-01T00:00:00Z",
"scope": "bus",
"id": "EVENTS.controller",
"since": "0001-01-01T00:00:00Z"
}
},
{
"name": "a finding of the module scope with its machine (captured from the watchman; empty fields left out)",
"of": "state:findings/<key>",
"name": "a finding of the module scope with its machine (in the finding layout (design 47 G 660))",
"of": "state:findings/<scope>.<id>.<kind>",
"given": {
"v": 1,
"key": "module.mesh-build-node.ace.directory-used-as-found",
"kind": "directory-used-as-found",
"subject": {
"id": "mesh-build-node.ace",
@@ -102,7 +167,6 @@
"explanation": "Needs you: hand the directory over from the control-node, as the operator.",
"headline": "mesh-build-node waits for a directory on ace",
"needs": "hand the directory over from the control-node, as the operator; the details name it and the line to type.",
"resolved": "mesh-build-node's directory on ace is the mesh's",
"observer": "mesh-delivery-watchman",
"source": "health-report",
"evidence": [
@@ -111,7 +175,54 @@
"said": "mesh-build-node on ace uses mesh-build-node.cache as found: owned by 10005:10005, mode 700, as found"
}
],
"at": "2026-10-26T20:19:41.474823121Z"
"at": "2026-10-26T20:19:41.474823121Z",
"scope": "module",
"id": "mesh-build-node.home-server",
"since": "2026-10-26T20:19:41.474823121Z"
}
},
{
"name": "a finding owned by a session and waiting on a seat (design 47 G 678)",
"of": "state:findings/<scope>.<id>.<kind>",
"given": {
"kind": "directory-used-as-found",
"subject": {
"scope": "module",
"id": "mesh-host.home-server",
"machine": "home-server"
},
"severity": "warning",
"summary": "a directory waits for a hand",
"source": "health-report",
"observer": "mesh-delivery-watchman",
"at": "2026-11-11T10:00:00Z",
"owner": "operator@workstation",
"waiting-on": "node-engine",
"scope": "module",
"id": "mesh-host.home-server",
"since": "2026-11-11T10:00:00Z"
}
},
{
"name": "a finding owned by a seat and waiting on a commit's author (design 47 G 678, 540)",
"of": "state:findings/<scope>.<id>.<kind>",
"given": {
"kind": "directory-used-as-found",
"subject": {
"scope": "module",
"id": "mesh-host.home-server",
"machine": "home-server"
},
"severity": "warning",
"summary": "a directory waits for a hand",
"source": "health-report",
"observer": "mesh-delivery-watchman",
"at": "2026-11-11T10:00:00Z",
"owner": "node-engine",
"waiting-on": "forge:operator",
"scope": "module",
"id": "mesh-host.home-server",
"since": "2026-11-11T10:00:00Z"
}
}
]
+315 -86
View File
@@ -84,15 +84,22 @@
},
{
"name": "resync",
"description": "Read every observer's findings again and raise and clear what differs from the open conditions: the recovery of a keeper that missed a change.",
"description": "Ask the observers to state their findings again, every one or the one named, and raise and clear what differs from the open conditions: the recovery of a keeper that missed a change. Each call is written in the hand-act log of the seat mesh-hand-acts (design 47 G 390).",
"input": {
"properties": {},
"type": "object"
"type": "object",
"properties": {
"module": {
"type": "string",
"description": "ask this observer alone; none asks all"
}
},
"additionalProperties": false
},
"answer": {
"type": "object",
"description": "what was raised and cleared again"
}
},
"class": "act"
}
],
"events": [
@@ -113,6 +120,40 @@
"body": {
"$ref": "#/defs/ConditionEvent"
}
},
{
"name": "findings-asked",
"keep": {
"max-age-days": 7,
"max-mib": 16
},
"body": {
"type": "object",
"description": "the keeper asks every observer, or one, to state its findings (design 47 G 384, 390)",
"properties": {
"ask": {
"type": "string",
"description": "the ask's id"
},
"at": {
"type": "string",
"format": "date-time"
},
"by": {
"type": "string",
"description": "who asked: the keeper, or the person or session that called resync"
},
"module": {
"type": "string",
"description": "to ask one observer; none asks all"
}
},
"required": [
"ask",
"at",
"by"
]
}
}
],
"family": {
@@ -184,6 +225,16 @@
"type": "string",
"description": "self, operator, agent or healer:<name>"
},
"owner": {
"type": "string",
"pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$",
"description": "who the condition is about, taken from the finding or handed to operator-channel by the keeper: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge:<account> (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)"
},
"waiting-on": {
"type": "string",
"pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$",
"description": "what it waits on, from the finding: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge:<account> (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)"
},
"raised": {
"type": "string",
"format": "date-time"
@@ -285,102 +336,74 @@
"writer": "caller",
"key-forms": [
{
"key": "<key>",
"key": "<scope>.<id>.<kind>",
"value": {
"$ref": "#/bodies/Finding"
},
"description": "one finding of the observer that wrote it, its layout the body Finding (design 47 G 439, 461, 660)"
}
],
"description": "every observer's findings, one key per finding, kept in the observer's own state and read only by its owner's read tool; the keeper hears each change as the observer's events finding-written, finding-cleared and findings-stated (design 47 G 383, 434)"
},
{
"name": "findings-views",
"template": "state",
"description": "the keeper's sources: one key per observer and node, its last stated set with its at, its pending keys and the open asks; deleted when the module leaves the catalog or the node (design 47 G 388)",
"key-forms": [
{
"key": "<observer>.<node>",
"description": "one observer on one node",
"value": {
"type": "object",
"description": "one thing an observer sees wrong now",
"properties": {
"v": {
"type": "integer",
"description": "layout version, 1"
},
"key": {
"type": "string",
"description": "scope.id.token"
},
"kind": {
"type": "string"
},
"subject": {
"$ref": "#/defs/Subject"
},
"severity": {
"type": "string",
"enum": [
"urgent",
"warning"
]
},
"summary": {
"type": "string",
"description": "one line"
},
"headline": {
"type": "string"
},
"explanation": {
"type": "string"
},
"resolved": {
"type": "string"
},
"needs": {
"type": "string"
},
"actions": {
"type": "array",
"items": {
"$ref": "#/defs/Action"
}
},
"evidence": {
"type": "array",
"description": "newest first, at most 10",
"items": {
"$ref": "#/defs/Evidence"
}
},
"source": {
"type": "string",
"description": "the row, probe or event that saw it"
},
"resolver": {
"type": "string",
"description": "self, operator, agent or healer:<name>"
},
"ref": {
"type": "string",
"description": "the key's last part when it is not the kind"
"type": "integer"
},
"observer": {
"type": "string",
"description": "the module that wrote it"
"type": "string"
},
"run": {
"type": "string",
"description": "what of its own saw it last"
"node": {
"type": "string"
},
"at": {
"type": "string",
"format": "date-time"
"stated": {
"type": "object",
"description": "the last findings-stated set",
"properties": {
"at": {
"type": "string",
"format": "date-time"
},
"findings": {
"type": "array",
"items": {
"$ref": "#/bodies/Finding"
}
}
}
},
"pending": {
"type": "array",
"items": {
"type": "string"
},
"description": "the keys it cannot judge yet"
},
"asks": {
"type": "array",
"items": {
"type": "string"
},
"description": "the open asks"
}
},
"required": [
"v",
"key",
"kind",
"subject",
"severity",
"summary",
"source",
"observer",
"at"
"node"
]
},
"description": "one finding of the observer that wrote it"
}
}
],
"description": "every observer's findings, one key per finding; a key written raises or changes the condition of the same key, a key deleted clears it"
]
}
],
"defs": {
@@ -521,6 +544,16 @@
"type": "string",
"description": "self, operator, agent or healer:<name>"
},
"owner": {
"type": "string",
"pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$",
"description": "who the condition is about, taken from the finding or handed to operator-channel by the keeper: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge:<account> (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)"
},
"waiting-on": {
"type": "string",
"pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$",
"description": "what it waits on, from the finding: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge:<account> (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)"
},
"raised": {
"type": "string",
"format": "date-time"
@@ -618,7 +651,8 @@
"silenced",
"silence-ended",
"cleared",
"words"
"words",
"owner"
]
},
"was": {
@@ -643,5 +677,200 @@
"change"
]
}
},
"bodies": {
"Finding": {
"type": "object",
"description": "one finding as an observer says it: the layout whole, plus scope, id and since (design 47 G 437, 439)",
"properties": {
"kind": {
"type": "string"
},
"scope": {
"type": "string",
"description": "the key's first part: <scope>.<id>.<kind> (ADR 0564)"
},
"id": {
"type": "string",
"description": "the key's second part"
},
"at": {
"type": "string",
"format": "date-time"
},
"since": {
"type": "string",
"format": "date-time",
"description": "since when the finding stands"
},
"severity": {
"type": "string",
"enum": [
"urgent",
"warning"
]
},
"summary": {
"type": "string",
"description": "one line"
},
"headline": {
"type": "string"
},
"explanation": {
"type": "string"
},
"subject": {
"$ref": "#/defs/Subject"
},
"evidence": {
"type": "array",
"description": "newest first, at most 10",
"items": {
"$ref": "#/defs/Evidence"
}
},
"source": {
"type": "string",
"description": "the row, probe or event that saw it"
},
"observer": {
"type": "string",
"description": "the module that wrote it"
},
"owner": {
"type": "string",
"pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$",
"description": "who the finding is about, when not the observer: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge:<account> (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)"
},
"waiting-on": {
"type": "string",
"pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$",
"description": "what it waits on: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge:<account> (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)"
},
"actions": {
"type": "array",
"items": {
"$ref": "#/defs/Action"
}
},
"needs": {
"type": "string"
},
"resolver": {
"type": "string",
"description": "self, operator, agent or healer:<name>"
},
"ref": {
"type": "string",
"description": "the key's last part when it is not the kind"
},
"run": {
"type": "string",
"description": "what of its own saw it last"
}
},
"required": [
"kind",
"scope",
"id",
"at",
"since",
"severity",
"summary",
"subject",
"source",
"observer"
]
},
"FindingWritten": {
"$ref": "#/bodies/Finding"
},
"FindingCleared": {
"type": "object",
"description": "an observer no longer observes a finding",
"properties": {
"kind": {
"type": "string"
},
"scope": {
"type": "string"
},
"id": {
"type": "string"
},
"at": {
"type": "string",
"format": "date-time"
},
"why": {
"type": "string"
}
},
"required": [
"kind",
"scope",
"id",
"at",
"why"
]
},
"FindingsStated": {
"type": "object",
"description": "every finding an observer observes now, at its start and when asked (design 47 G 384, 439)",
"properties": {
"at": {
"type": "string",
"format": "date-time"
},
"asked": {
"type": "string",
"description": "the ask it answers; none at a start"
},
"kinds": {
"type": "array",
"items": {
"type": "string"
},
"description": "the finding kinds the stating bundle owns and states, the only kinds whose keys the statement deletes and whose conditions the keeper clears when it names none of them; none covers every kind, as a part with one bundle states (design 47 G 580)"
},
"findings": {
"type": "array",
"items": {
"$ref": "#/bodies/Finding"
}
},
"pending": {
"type": "array",
"description": "the keys the observer cannot judge yet since its start, with their since and bound",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"since": {
"type": "string",
"format": "date-time"
},
"bound": {
"type": "string",
"description": "a duration such as 5m"
}
},
"required": [
"key",
"since",
"bound"
]
}
}
},
"required": [
"at",
"findings",
"pending"
]
}
}
}
@@ -0,0 +1,26 @@
[
{
"name": "an attempt begun, said with its end (design 47 G 665)",
"of": "event:attempt-changed",
"subject": "mesh.seat.mesh-healers.event.attempt-changed.c-1.a-1",
"given": {
"healer": "directory",
"condition": "module.mesh-host.home-server.directory-used-as-found",
"kind": "directory-used-as-found",
"budget-key": "module.mesh-host.home-server.directory-used-as-found",
"act": "hand-over",
"outcome": "acting",
"begun": "2026-11-11T10:00:00Z",
"until": "2026-11-11T12:00:00Z"
}
},
{
"name": "an attempt ended by its healer",
"of": "event:attempt-changed",
"subject": "mesh.seat.mesh-healers.event.attempt-changed.c-1.a-1",
"given": {
"condition": "module.mesh-host.home-server.directory-used-as-found",
"removed": true
}
}
]
@@ -135,6 +135,66 @@
"outcome"
]
}
},
{
"name": "attempt-changed",
"subject": "attempt-changed.<condition>.<attempt>",
"keep": {
"max-age-days": 7,
"max-mib": 16,
"last-per-subject": true
},
"body": {
"type": "object",
"description": "an attempt as the attempts state holds it, whole, with until, or removed: true when the healer ends it; said again for every open attempt at the healers' start (design 47 G 541, 665)",
"properties": {
"healer": {
"type": "string"
},
"condition": {
"type": "string"
},
"kind": {
"type": "string"
},
"budget-key": {
"type": "string",
"description": "what the budget counts by: the condition's key unless the healer says another"
},
"act": {
"type": "string"
},
"outcome": {
"type": "string",
"enum": [
"acting",
"acted",
"failed",
"escalated"
]
},
"said": {
"type": "string"
},
"begun": {
"type": "string",
"format": "date-time"
},
"finished": {
"type": "string",
"format": "date-time"
},
"until": {
"type": "string",
"format": "date-time",
"description": "the end of that key's lifetime, which the keeper drops the attempt at on its own clock"
},
"removed": {
"type": "boolean",
"description": "true when the healer ends the attempt"
}
}
}
}
],
"family": {
@@ -0,0 +1,24 @@
[
{
"name": "a machine's presence expired",
"of": "event:machine-away",
"subject": "mesh.seat.mesh-watchdogs.event.machine-away.laptop",
"given": {
"v": 1,
"machine": "laptop",
"at": "2026-11-11T10:00:00Z",
"last-heard": "2026-11-11T09:58:00Z"
}
},
{
"name": "a machine heard again",
"of": "event:machine-back",
"subject": "mesh.seat.mesh-watchdogs.event.machine-back.laptop",
"given": {
"v": 1,
"machine": "laptop",
"at": "2026-11-11T10:30:00Z",
"last-heard": "2026-11-11T10:30:00Z"
}
}
]
@@ -43,7 +43,7 @@
},
{
"name": "presence",
"description": "Every machine and tool runner the watchman sees connected, with its last word, and those it says silent; a machine that said it sleeps is shown as sleeping, not silent.",
"description": "Every machine and tool runner the watchman sees connected, with its last word, and those it says silent; a machine that said it sleeps is shown as sleeping, not silent. With machine, that machine's presence alone: whether the watchman hears it and since when.",
"input": {
"properties": {
"machine": {
@@ -55,7 +55,54 @@
},
"answer": {
"type": "object",
"description": "who is connected and who is silent"
"description": "with machine, that machine: online and since; without, every key of the state presence",
"properties": {
"machine": {
"type": "string",
"description": "the machine asked, with machine"
},
"online": {
"type": "boolean",
"description": "with machine: whether the watchman hears the machine now; false for a machine it holds no word of"
},
"since": {
"type": "string",
"description": "with machine: when its presence last changed, RFC 3339; empty for a machine the watchman holds no word of"
},
"state": {
"type": "string",
"description": "without machine: the state read, presence"
},
"holds": {
"type": "integer",
"description": "without machine: how many keys the state holds"
},
"keys": {
"type": "array",
"description": "without machine: each key of the state presence, <node> or part.<part>.<instance>, with its value",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "<node> or part.<part>.<instance>"
},
"value": {
"type": "object",
"description": "the key's value, online and its layout's version"
},
"revision": {
"type": "integer",
"description": "the key's revision"
}
},
"required": [
"key",
"value"
]
}
}
}
}
},
{
@@ -112,6 +159,86 @@
}
}
],
"events": [
{
"name": "machine-away",
"subject": "machine-away.<machine>",
"keep": {
"max-age-days": 90,
"max-mib": 16
},
"body": {
"type": "object",
"description": "the watchman's presence key of a machine expired (ADR 0564 4); published by the holder of this seat alone for another machine (design 47 G 436)",
"properties": {
"v": {
"type": "integer",
"description": "the layout's version"
},
"machine": {
"type": "string",
"description": "the machine whose presence changed"
},
"at": {
"type": "string",
"format": "date-time"
},
"last-heard": {
"type": "string",
"format": "date-time",
"description": "when the machine was last heard"
}
},
"required": [
"v",
"machine",
"at",
"last-heard"
]
}
},
{
"name": "machine-back",
"subject": "machine-back.<machine>",
"keep": {
"max-age-days": 90,
"max-mib": 16
},
"body": {
"type": "object",
"description": "a machine is heard again after it was away",
"properties": {
"v": {
"type": "integer",
"description": "the layout's version"
},
"machine": {
"type": "string",
"description": "the machine whose presence changed"
},
"at": {
"type": "string",
"format": "date-time"
},
"last-heard": {
"type": "string",
"format": "date-time",
"description": "when the machine was last heard"
}
},
"required": [
"v",
"machine",
"at",
"last-heard"
]
}
}
],
"family": {
"name": "mesh-watchdogs.events",
"max-age-days": 7
},
"states": [
{
"name": "presence",
+352
View File
@@ -0,0 +1,352 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// The contract of the seat "mesh-conditions", defined whole (seats/mesh-conditions/seat.json): What is wrong with the mesh now (ADR 0564): the open conditions raised from the observers' findings and cleared when a finding goes.
export declare const seat: "mesh-conditions";
export declare const verbs: {
readonly conditions: "conditions";
readonly silence: "silence";
readonly resync: "resync";
};
export declare const events: {
readonly conditionRaised: "condition-raised";
readonly conditionChanged: "condition-changed";
readonly conditionCleared: "condition-cleared";
readonly findingsAsked: "findings-asked";
};
export declare const family: { readonly name: "mesh-conditions.events"; readonly maxAgeDays: 7 };
export declare const conditionRaisedSubject: "mesh.seat.mesh-conditions.event.condition-raised";
export declare const conditionChangedSubject: "mesh.seat.mesh-conditions.event.condition-changed";
export declare const conditionClearedSubject: "mesh.seat.mesh-conditions.event.condition-cleared";
export declare const findingsAskedStream: "SEAT_mesh-conditions_findings-asked";
export declare const findingsAskedSubject: "mesh.seat.mesh-conditions.event.findings-asked";
export declare const states: {
readonly conditions: "conditions";
readonly findings: "findings";
readonly findingsViews: "findings-views";
};
/** The key of one value of the state conditions under the form "<key>". */
export declare function conditionsByKeyKey(key: string): string;
/** The parts of a key of the form "<key>", or undefined for a key of another form. */
export declare function parseConditionsByKeyKey(_key: string): { key: string } | undefined;
/** The key of one value of the state findings under the form "<scope>.<id>.<kind>". */
export declare function findingsByScopeIDKindKey(scope: string, id: string, kind: string): string;
/** The parts of a key of the form "<scope>.<id>.<kind>", or undefined for a key of another form. */
export declare function parseFindingsByScopeIDKindKey(_key: string): { scope: string; id: string; kind: string } | undefined;
/** The key of one value of the state findings-views under the form "<observer>.<node>". */
export declare function findingsViewsByObserverNodeKey(observer: string, node: string): string;
/** The parts of a key of the form "<observer>.<node>", or undefined for a key of another form. */
export declare function parseFindingsViewsByObserverNodeKey(_key: string): { observer: string; node: string } | undefined;
/** one answer the operator may give from a notification */
export interface Action {
"arguments"?: Record<string, string>;
"label": string;
"level"?: "acknowledge" | "approve";
"machine"?: string;
/** the seat verb the operator channel calls */
"verb": string;
}
export interface ConditionEventGapsItem {
"cleared"?: string;
"reopened"?: string;
}
export interface ConditionEventSilenced {
"by"?: string;
"since"?: string;
"until"?: string;
"why"?: string;
}
export interface ConditionEventTriedItem {
"at"?: string;
"by"?: string;
"outcome"?: string;
"what"?: string;
}
/** a condition and what changed */
export interface ConditionEvent {
"actions"?: Action[];
"at": string;
"change": "raised" | "reopened" | "severity" | "resolver" | "silenced" | "silence-ended" | "cleared" | "words" | "owner";
"cleared"?: string;
"count"?: number;
"epoch"?: number;
"event": string;
/** newest first, at most 10 */
"evidence"?: Evidence[];
"explanation"?: string;
"first"?: string;
"gaps"?: ConditionEventGapsItem[];
"headline"?: string;
/** scope.id.token */
"key": string;
"kind"?: string;
"last-observed"?: string;
"looks-unread"?: string;
"needs"?: string;
"observations"?: number;
/** who the condition is about, taken from the finding or handed to operator-channel by the keeper: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge:<account> (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678) */
"owner"?: string;
"raised"?: string;
"resolved"?: string;
/** self, operator, agent or healer:<name> */
"resolver"?: string;
"severity"?: "urgent" | "warning";
/** the tool call that shows it */
"show"?: string;
"silenced"?: ConditionEventSilenced;
/** the row, probe or event that saw it */
"source"?: string;
"subject"?: Subject;
/** one line */
"summary"?: string;
"tried"?: ConditionEventTriedItem[];
/** what it waits on, from the finding: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge:<account> (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678) */
"waiting-on"?: string;
"was"?: string;
"why"?: string;
}
/** one observation, as it was said */
export interface Evidence {
"at": string;
"said": string;
}
/** what the condition is about */
export interface Subject {
/** the other machines it concerns */
"also"?: string[];
/** its id within the scope */
"id": string;
/** the machine it concerns, when there is one */
"machine"?: string;
/** machine, plan, call, build, merge, provider, seat, bus, core, probe, mesh, delivery or module */
"scope": string;
}
/** one finding as an observer says it: the layout whole, plus scope, id and since (design 47 G 437, 439) */
export interface Finding {
"actions"?: Action[];
"at": string;
/** newest first, at most 10 */
"evidence"?: Evidence[];
"explanation"?: string;
"headline"?: string;
/** the key's second part */
"id": string;
"kind": string;
"needs"?: string;
/** the module that wrote it */
"observer": string;
/** who the finding is about, when not the observer: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge:<account> (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678) */
"owner"?: string;
/** the key's last part when it is not the kind */
"ref"?: string;
/** self, operator, agent or healer:<name> */
"resolver"?: string;
/** what of its own saw it last */
"run"?: string;
/** the key's first part: <scope>.<id>.<kind> (ADR 0564) */
"scope": string;
"severity": "urgent" | "warning";
/** since when the finding stands */
"since": string;
/** the row, probe or event that saw it */
"source": string;
"subject": Subject;
/** one line */
"summary": string;
/** what it waits on: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge:<account> (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678) */
"waiting-on"?: string;
}
/** an observer no longer observes a finding */
export interface FindingCleared {
"at": string;
"id": string;
"kind": string;
"scope": string;
"why": string;
}
export type FindingWritten = Finding;
export interface FindingsStatedPendingItem {
/** a duration such as 5m */
"bound": string;
"key": string;
"since": string;
}
/** every finding an observer observes now, at its start and when asked (design 47 G 384, 439) */
export interface FindingsStated {
/** the ask it answers; none at a start */
"asked"?: string;
"at": string;
"findings": Finding[];
/** the finding kinds the stating bundle owns and states, the only kinds whose keys the statement deletes and whose conditions the keeper clears when it names none of them; none covers every kind, as a part with one bundle states (design 47 G 580) */
"kinds"?: string[];
/** the keys the observer cannot judge yet since its start, with their since and bound */
"pending": FindingsStatedPendingItem[];
}
/** is what conditions takes. */
export interface ConditionsInput {
/** with history: how many days back (default 7, at most 90) */
"days"?: string;
/** "true": every raising, change, silence and clearing lately, oldest first */
"history"?: "true" | "false";
/** a condition's key: that one whole; with history, only its transitions */
"key"?: string;
/** only those about this machine */
"machine"?: string;
/** only this scope: machine, plan, call, build, merge, provider, seat, bus, core, probe, mesh, delivery or module */
"scope"?: string;
/** only urgent, or only warning */
"severity"?: string;
}
/** is what conditions answers. */
export type ConditionsAnswer = Record<string, unknown>;
/** is what silence takes. */
export interface SilenceInput {
/** the cause in a word (the condition's kind when absent) */
"cause"?: string;
/** how long: 30m, 4h, 2d; at most 7d */
"for": string;
/** the condition's key */
"key": string;
/** why, required and recorded */
"why": string;
}
/** is what silence answers. */
export type SilenceAnswer = Record<string, unknown>;
/** is what resync takes. */
export interface ResyncInput {
/** ask this observer alone; none asks all */
"module"?: string;
}
/** is what resync answers. */
export type ResyncAnswer = Record<string, unknown>;
/** is the body of the event condition-raised. */
export type ConditionRaisedEvent = ConditionEvent;
/** is the body of the event condition-changed. */
export type ConditionChangedEvent = ConditionEvent;
/** is the body of the event condition-cleared. */
export type ConditionClearedEvent = ConditionEvent;
/** is the body of the event findings-asked. */
export interface FindingsAskedEvent {
/** the ask's id */
"ask": string;
"at": string;
/** who asked: the keeper, or the person or session that called resync */
"by": string;
/** to ask one observer; none asks all */
"module"?: string;
}
export interface ConditionsByKeyValueGapsItem {
"cleared"?: string;
"reopened"?: string;
}
export interface ConditionsByKeyValueSilenced {
"by"?: string;
"since"?: string;
"until"?: string;
"why"?: string;
}
export interface ConditionsByKeyValueTriedItem {
"at"?: string;
"by"?: string;
"outcome"?: string;
"what"?: string;
}
/** is one value of the state conditions under the key <key>. */
export interface ConditionsByKeyValue {
"actions"?: Action[];
"count"?: number;
"epoch"?: number;
/** newest first, at most 10 */
"evidence"?: Evidence[];
"explanation"?: string;
"first"?: string;
"gaps"?: ConditionsByKeyValueGapsItem[];
"headline"?: string;
/** scope.id.token */
"key": string;
"kind": string;
"last-observed": string;
"looks-unread"?: string;
"needs"?: string;
"observations"?: number;
/** who the condition is about, taken from the finding or handed to operator-channel by the keeper: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge:<account> (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678) */
"owner"?: string;
"raised": string;
"resolved"?: string;
/** self, operator, agent or healer:<name> */
"resolver"?: string;
"severity": "urgent" | "warning";
"silenced"?: ConditionsByKeyValueSilenced;
/** the row, probe or event that saw it */
"source"?: string;
"subject": Subject;
/** one line */
"summary"?: string;
"tried"?: ConditionsByKeyValueTriedItem[];
/** what it waits on, from the finding: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge:<account> (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678) */
"waiting-on"?: string;
}
/** is one value of the state findings under the key <scope>.<id>.<kind>. */
export type FindingsByScopeIDKindValue = Finding;
/** the last findings-stated set */
export interface FindingsViewsByObserverNodeValueStated {
"at"?: string;
"findings"?: Finding[];
}
/** is one value of the state findings-views under the key <observer>.<node>. */
export interface FindingsViewsByObserverNodeValue {
/** the open asks */
"asks"?: string[];
"node": string;
"observer": string;
/** the keys it cannot judge yet */
"pending"?: string[];
/** the last findings-stated set */
"stated"?: FindingsViewsByObserverNodeValueStated;
"v": number;
}
@@ -0,0 +1,94 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// The contract of the seat "mesh-conditions", defined whole (seats/mesh-conditions/seat.json): What is wrong with the mesh now (ADR 0564): the open conditions raised from the observers' findings and cleared when a finding goes.
export const seat = "mesh-conditions";
export const verbs = {
conditions: "conditions",
silence: "silence",
resync: "resync",
};
export const events = {
conditionRaised: "condition-raised",
conditionChanged: "condition-changed",
conditionCleared: "condition-cleared",
findingsAsked: "findings-asked",
};
export const family = { name: "mesh-conditions.events", maxAgeDays: 7 };
export const conditionRaisedSubject = "mesh.seat.mesh-conditions.event.condition-raised";
export const conditionChangedSubject = "mesh.seat.mesh-conditions.event.condition-changed";
export const conditionClearedSubject = "mesh.seat.mesh-conditions.event.condition-cleared";
export const findingsAskedStream = "SEAT_mesh-conditions_findings-asked";
export const findingsAskedSubject = "mesh.seat.mesh-conditions.event.findings-asked";
export const states = {
conditions: "conditions",
findings: "findings",
findingsViews: "findings-views",
};
/** The key of one value of the state conditions under the form "<key>". */
export function conditionsByKeyKey(key) {
return key;
}
/** The parts of a key of the form "<key>", or undefined for a key of another form. */
export function parseConditionsByKeyKey(_key) {
let _rest = _key;
if (_rest === "") return undefined;
const key = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { key };
}
/** The key of one value of the state findings under the form "<scope>.<id>.<kind>". */
export function findingsByScopeIDKindKey(scope, id, kind) {
return scope + "." + id + "." + kind;
}
/** The parts of a key of the form "<scope>.<id>.<kind>", or undefined for a key of another form. */
export function parseFindingsByScopeIDKindKey(_key) {
let _rest = _key;
const _at0 = _rest.indexOf(".");
if (_at0 <= 0) return undefined;
const scope = _rest.slice(0, _at0);
_rest = _rest.slice(_at0 + 1);
const _at2 = _rest.indexOf(".");
if (_at2 <= 0) return undefined;
const id = _rest.slice(0, _at2);
_rest = _rest.slice(_at2 + 1);
if (_rest === "") return undefined;
const kind = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { scope, id, kind };
}
/** The key of one value of the state findings-views under the form "<observer>.<node>". */
export function findingsViewsByObserverNodeKey(observer, node) {
return observer + "." + node;
}
/** The parts of a key of the form "<observer>.<node>", or undefined for a key of another form. */
export function parseFindingsViewsByObserverNodeKey(_key) {
let _rest = _key;
const _at0 = _rest.indexOf(".");
if (_at0 <= 0) return undefined;
const observer = _rest.slice(0, _at0);
_rest = _rest.slice(_at0 + 1);
if (_rest === "") return undefined;
const node = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { observer, node };
}
+2 -2
View File
@@ -1,9 +1,9 @@
{
"lockfileVersion": 3,
"name": "@novox/mesh-health-and-repair-contracts-mesh-conditions",
"name": "@novox/mesh-contracts-health-and-repair-mesh-conditions",
"packages": {
"": {
"name": "@novox/mesh-health-and-repair-contracts-mesh-conditions",
"name": "@novox/mesh-contracts-health-and-repair-mesh-conditions",
"version": "0.1.0"
}
},
@@ -1,13 +1,18 @@
{
"description": "The contract of the seat mesh-conditions, generated from its definition.",
"exports": {
".": "./src/index.ts"
".": {
"default": "./index.js",
"types": "./index.d.ts"
}
},
"files": [
"src"
"index.js",
"index.d.ts",
"parts"
],
"name": "@novox/mesh-health-and-repair-contracts-mesh-conditions",
"name": "@novox/mesh-contracts-health-and-repair-mesh-conditions",
"type": "module",
"types": "./src/index.ts",
"types": "./index.d.ts",
"version": "0.1.0"
}
@@ -1,280 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// The contract of the seat "mesh-conditions", defined whole (seats/mesh-conditions/seat.json): What is wrong with the mesh now (ADR 0564): the open conditions raised from the observers' findings and cleared when a finding goes.
export const seat = "mesh-conditions";
export const verbs = {
conditions: "conditions",
silence: "silence",
resync: "resync",
} as const;
export const events = {
conditionRaised: "condition-raised",
conditionChanged: "condition-changed",
conditionCleared: "condition-cleared",
} as const;
export const family = { name: "mesh-conditions.events", maxAgeDays: 7 } as const;
export const conditionRaisedSubject = "mesh.seat.mesh-conditions.event.condition-raised";
export const conditionChangedSubject = "mesh.seat.mesh-conditions.event.condition-changed";
export const conditionClearedSubject = "mesh.seat.mesh-conditions.event.condition-cleared";
export const states = {
conditions: "conditions",
findings: "findings",
} as const;
/** The key of one value of the state conditions under the form "<key>". */
export function conditionsByKeyKey(key: string): string {
return key;
}
/** The parts of a key of the form "<key>", or undefined for a key of another form. */
export function parseConditionsByKeyKey(_key: string): { key: string } | undefined {
let _rest = _key;
if (_rest === "") return undefined;
const key = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { key };
}
/** The key of one value of the state findings under the form "<key>". */
export function findingsByKeyKey(key: string): string {
return key;
}
/** The parts of a key of the form "<key>", or undefined for a key of another form. */
export function parseFindingsByKeyKey(_key: string): { key: string } | undefined {
let _rest = _key;
if (_rest === "") return undefined;
const key = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { key };
}
/** one answer the operator may give from a notification */
export interface Action {
"arguments"?: Record<string, string>;
"label": string;
"level"?: "acknowledge" | "approve";
"machine"?: string;
/** the seat verb the operator channel calls */
"verb": string;
}
export interface ConditionEventGapsItem {
"cleared"?: string;
"reopened"?: string;
}
export interface ConditionEventSilenced {
"by"?: string;
"since"?: string;
"until"?: string;
"why"?: string;
}
export interface ConditionEventTriedItem {
"at"?: string;
"by"?: string;
"outcome"?: string;
"what"?: string;
}
/** a condition and what changed */
export interface ConditionEvent {
"actions"?: Action[];
"at": string;
"change": "raised" | "reopened" | "severity" | "resolver" | "silenced" | "silence-ended" | "cleared" | "words";
"cleared"?: string;
"count"?: number;
"epoch"?: number;
"event": string;
/** newest first, at most 10 */
"evidence"?: Evidence[];
"explanation"?: string;
"first"?: string;
"gaps"?: ConditionEventGapsItem[];
"headline"?: string;
/** scope.id.token */
"key": string;
"kind"?: string;
"last-observed"?: string;
"looks-unread"?: string;
"needs"?: string;
"observations"?: number;
"raised"?: string;
"resolved"?: string;
/** self, operator, agent or healer:<name> */
"resolver"?: string;
"severity"?: "urgent" | "warning";
/** the tool call that shows it */
"show"?: string;
"silenced"?: ConditionEventSilenced;
/** the row, probe or event that saw it */
"source"?: string;
"subject"?: Subject;
/** one line */
"summary"?: string;
"tried"?: ConditionEventTriedItem[];
"was"?: string;
"why"?: string;
}
/** one observation, as it was said */
export interface Evidence {
"at": string;
"said": string;
}
/** what the condition is about */
export interface Subject {
/** the other machines it concerns */
"also"?: string[];
/** its id within the scope */
"id": string;
/** the machine it concerns, when there is one */
"machine"?: string;
/** machine, plan, call, build, merge, provider, seat, bus, core, probe, mesh, delivery or module */
"scope": string;
}
/** is what conditions takes. */
export interface ConditionsInput {
/** with history: how many days back (default 7, at most 90) */
"days"?: string;
/** "true": every raising, change, silence and clearing lately, oldest first */
"history"?: "true" | "false";
/** a condition's key: that one whole; with history, only its transitions */
"key"?: string;
/** only those about this machine */
"machine"?: string;
/** only this scope: machine, plan, call, build, merge, provider, seat, bus, core, probe, mesh, delivery or module */
"scope"?: string;
/** only urgent, or only warning */
"severity"?: string;
}
/** is what conditions answers. */
export type ConditionsAnswer = Record<string, unknown>;
/** is what silence takes. */
export interface SilenceInput {
/** the cause in a word (the condition's kind when absent) */
"cause"?: string;
/** how long: 30m, 4h, 2d; at most 7d */
"for": string;
/** the condition's key */
"key": string;
/** why, required and recorded */
"why": string;
}
/** is what silence answers. */
export type SilenceAnswer = Record<string, unknown>;
/** is what resync takes. */
export interface ResyncInput {
}
/** is what resync answers. */
export type ResyncAnswer = Record<string, unknown>;
/** is the body of the event condition-raised. */
export type ConditionRaisedEvent = ConditionEvent;
/** is the body of the event condition-changed. */
export type ConditionChangedEvent = ConditionEvent;
/** is the body of the event condition-cleared. */
export type ConditionClearedEvent = ConditionEvent;
export interface ConditionsByKeyValueGapsItem {
"cleared"?: string;
"reopened"?: string;
}
export interface ConditionsByKeyValueSilenced {
"by"?: string;
"since"?: string;
"until"?: string;
"why"?: string;
}
export interface ConditionsByKeyValueTriedItem {
"at"?: string;
"by"?: string;
"outcome"?: string;
"what"?: string;
}
/** is one value of the state conditions under the key <key>. */
export interface ConditionsByKeyValue {
"actions"?: Action[];
"count"?: number;
"epoch"?: number;
/** newest first, at most 10 */
"evidence"?: Evidence[];
"explanation"?: string;
"first"?: string;
"gaps"?: ConditionsByKeyValueGapsItem[];
"headline"?: string;
/** scope.id.token */
"key": string;
"kind": string;
"last-observed": string;
"looks-unread"?: string;
"needs"?: string;
"observations"?: number;
"raised": string;
"resolved"?: string;
/** self, operator, agent or healer:<name> */
"resolver"?: string;
"severity": "urgent" | "warning";
"silenced"?: ConditionsByKeyValueSilenced;
/** the row, probe or event that saw it */
"source"?: string;
"subject": Subject;
/** one line */
"summary"?: string;
"tried"?: ConditionsByKeyValueTriedItem[];
}
/** is one value of the state findings under the key <key>. */
export interface FindingsByKeyValue {
"actions"?: Action[];
"at": string;
/** newest first, at most 10 */
"evidence"?: Evidence[];
"explanation"?: string;
"headline"?: string;
/** scope.id.token */
"key": string;
"kind": string;
"needs"?: string;
/** the module that wrote it */
"observer": string;
/** the key's last part when it is not the kind */
"ref"?: string;
"resolved"?: string;
/** self, operator, agent or healer:<name> */
"resolver"?: string;
/** what of its own saw it last */
"run"?: string;
"severity": "urgent" | "warning";
/** the row, probe or event that saw it */
"source": string;
"subject": Subject;
/** one line */
"summary": string;
/** layout version, 1 */
"v": number;
}
@@ -1,12 +0,0 @@
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"noEmit": true,
"strict": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*.ts"]
}
@@ -2,60 +2,38 @@
// The contract of the seat "mesh-hand-acts", defined whole (seats/mesh-hand-acts/seat.json): Acts done by hand, recorded with who, why and cause (ADR 0565): the log every module records through.
export const seat = "mesh-hand-acts";
export declare const seat: "mesh-hand-acts";
export const verbs = {
handAct: "hand-act",
handActs: "hand-acts",
warranted: "warranted",
} as const;
export declare const verbs: {
readonly handAct: "hand-act";
readonly handActs: "hand-acts";
readonly warranted: "warranted";
};
export const events = {
actRecorded: "act-recorded",
} as const;
export declare const events: {
readonly actRecorded: "act-recorded";
};
export const family = { name: "mesh-hand-acts.events", maxAgeDays: 7 } as const;
export declare const family: { readonly name: "mesh-hand-acts.events"; readonly maxAgeDays: 7 };
export const actRecordedSubject = "mesh.seat.mesh-hand-acts.event.act-recorded";
export declare const actRecordedSubject: "mesh.seat.mesh-hand-acts.event.act-recorded";
export const states = {
acts: "acts",
warrants: "warrants",
} as const;
export declare const states: {
readonly acts: "acts";
readonly warrants: "warrants";
};
/** The key of one value of the state acts under the form "<id>". */
export function actsByIDKey(id: string): string {
return id;
}
export declare function actsByIDKey(id: string): string;
/** The parts of a key of the form "<id>", or undefined for a key of another form. */
export function parseActsByIDKey(_key: string): { id: string } | undefined {
let _rest = _key;
if (_rest === "") return undefined;
const id = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { id };
}
export declare function parseActsByIDKey(_key: string): { id: string } | undefined;
/** The key of one value of the state warrants under the form "<asker>.<ask>". */
export function warrantsByAskerAskKey(asker: string, ask: string): string {
return asker + "." + ask;
}
export declare function warrantsByAskerAskKey(asker: string, ask: string): string;
/** The parts of a key of the form "<asker>.<ask>", or undefined for a key of another form. */
export function parseWarrantsByAskerAskKey(_key: string): { asker: string; ask: string } | undefined {
let _rest = _key;
const _at0 = _rest.indexOf(".");
if (_at0 <= 0) return undefined;
const asker = _rest.slice(0, _at0);
_rest = _rest.slice(_at0 + 1);
if (_rest === "") return undefined;
const ask = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { asker, ask };
}
export declare function parseWarrantsByAskerAskKey(_key: string): { asker: string; ask: string } | undefined;
/** one act done by hand */
export interface Act {
@@ -0,0 +1,59 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// The contract of the seat "mesh-hand-acts", defined whole (seats/mesh-hand-acts/seat.json): Acts done by hand, recorded with who, why and cause (ADR 0565): the log every module records through.
export const seat = "mesh-hand-acts";
export const verbs = {
handAct: "hand-act",
handActs: "hand-acts",
warranted: "warranted",
};
export const events = {
actRecorded: "act-recorded",
};
export const family = { name: "mesh-hand-acts.events", maxAgeDays: 7 };
export const actRecordedSubject = "mesh.seat.mesh-hand-acts.event.act-recorded";
export const states = {
acts: "acts",
warrants: "warrants",
};
/** The key of one value of the state acts under the form "<id>". */
export function actsByIDKey(id) {
return id;
}
/** The parts of a key of the form "<id>", or undefined for a key of another form. */
export function parseActsByIDKey(_key) {
let _rest = _key;
if (_rest === "") return undefined;
const id = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { id };
}
/** The key of one value of the state warrants under the form "<asker>.<ask>". */
export function warrantsByAskerAskKey(asker, ask) {
return asker + "." + ask;
}
/** The parts of a key of the form "<asker>.<ask>", or undefined for a key of another form. */
export function parseWarrantsByAskerAskKey(_key) {
let _rest = _key;
const _at0 = _rest.indexOf(".");
if (_at0 <= 0) return undefined;
const asker = _rest.slice(0, _at0);
_rest = _rest.slice(_at0 + 1);
if (_rest === "") return undefined;
const ask = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { asker, ask };
}
+2 -2
View File
@@ -1,9 +1,9 @@
{
"lockfileVersion": 3,
"name": "@novox/mesh-health-and-repair-contracts-mesh-hand-acts",
"name": "@novox/mesh-contracts-health-and-repair-mesh-hand-acts",
"packages": {
"": {
"name": "@novox/mesh-health-and-repair-contracts-mesh-hand-acts",
"name": "@novox/mesh-contracts-health-and-repair-mesh-hand-acts",
"version": "0.1.0"
}
},
@@ -1,13 +1,18 @@
{
"description": "The contract of the seat mesh-hand-acts, generated from its definition.",
"exports": {
".": "./src/index.ts"
".": {
"default": "./index.js",
"types": "./index.d.ts"
}
},
"files": [
"src"
"index.js",
"index.d.ts",
"parts"
],
"name": "@novox/mesh-health-and-repair-contracts-mesh-hand-acts",
"name": "@novox/mesh-contracts-health-and-repair-mesh-hand-acts",
"type": "module",
"types": "./src/index.ts",
"types": "./index.d.ts",
"version": "0.1.0"
}
@@ -1,12 +0,0 @@
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"noEmit": true,
"strict": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*.ts"]
}
@@ -2,56 +2,45 @@
// The contract of the seat "mesh-healers", defined whole (seats/mesh-healers/seat.json): The healers (ADR 0564): each a registered response to one kind of condition, within a budget and the mesh-wide brake.
export const seat = "mesh-healers";
export declare const seat: "mesh-healers";
export const verbs = {
healers: "healers",
heal: "heal",
drill: "drill",
} as const;
export declare const verbs: {
readonly healers: "healers";
readonly heal: "heal";
readonly drill: "drill";
};
export const events = {
healerActed: "healer-acted",
} as const;
export declare const events: {
readonly healerActed: "healer-acted";
readonly attemptChanged: "attempt-changed";
};
export const family = { name: "mesh-healers.events", maxAgeDays: 7 } as const;
export declare const family: { readonly name: "mesh-healers.events"; readonly maxAgeDays: 7 };
export const healerActedSubject = "mesh.seat.mesh-healers.event.healer-acted";
export declare const healerActedSubject: "mesh.seat.mesh-healers.event.healer-acted";
export const states = {
attempts: "attempts",
would: "would",
} as const;
export declare const attemptChangedStream: "SEAT_mesh-healers_attempt-changed";
export declare function attemptChangedSubject(condition: string, attempt: string): string;
export declare const attemptChangedSubjectAll: "mesh.seat.mesh-healers.event.attempt-changed.*.*";
export declare const states: {
readonly attempts: "attempts";
readonly would: "would";
};
/** The key of one value of the state attempts under the form "<attempt>". */
export function attemptsByAttemptKey(attempt: string): string {
return attempt;
}
export declare function attemptsByAttemptKey(attempt: string): string;
/** The parts of a key of the form "<attempt>", or undefined for a key of another form. */
export function parseAttemptsByAttemptKey(_key: string): { attempt: string } | undefined {
let _rest = _key;
if (_rest === "") return undefined;
const attempt = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { attempt };
}
export declare function parseAttemptsByAttemptKey(_key: string): { attempt: string } | undefined;
/** The key of one value of the state would under the form "<would>". */
export function wouldByWouldKey(would: string): string {
return would;
}
export declare function wouldByWouldKey(would: string): string;
/** The parts of a key of the form "<would>", or undefined for a key of another form. */
export function parseWouldByWouldKey(_key: string): { would: string } | undefined {
let _rest = _key;
if (_rest === "") return undefined;
const would = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { would };
}
export declare function parseWouldByWouldKey(_key: string): { would: string } | undefined;
/** is what healers takes. */
export interface HealersInput {
@@ -101,6 +90,24 @@ export interface HealerActedEvent {
"show"?: string;
}
/** is the body of the event attempt-changed. */
export interface AttemptChangedEvent {
"act"?: string;
"begun"?: string;
/** what the budget counts by: the condition's key unless the healer says another */
"budget-key"?: string;
"condition"?: string;
"finished"?: string;
"healer"?: string;
"kind"?: string;
"outcome"?: "acting" | "acted" | "failed" | "escalated";
/** true when the healer ends the attempt */
"removed"?: boolean;
"said"?: string;
/** the end of that key's lifetime, which the keeper drops the attempt at on its own clock */
"until"?: string;
}
/** is one value of the state attempts under the key <attempt>. */
export interface AttemptsByAttemptValue {
"act": string;
@@ -0,0 +1,64 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// The contract of the seat "mesh-healers", defined whole (seats/mesh-healers/seat.json): The healers (ADR 0564): each a registered response to one kind of condition, within a budget and the mesh-wide brake.
export const seat = "mesh-healers";
export const verbs = {
healers: "healers",
heal: "heal",
drill: "drill",
};
export const events = {
healerActed: "healer-acted",
attemptChanged: "attempt-changed",
};
export const family = { name: "mesh-healers.events", maxAgeDays: 7 };
export const healerActedSubject = "mesh.seat.mesh-healers.event.healer-acted";
export const attemptChangedStream = "SEAT_mesh-healers_attempt-changed";
export function attemptChangedSubject(condition, attempt) {
return "mesh.seat.mesh-healers.event.attempt-changed." + condition + "." + attempt;
}
export const attemptChangedSubjectAll = "mesh.seat.mesh-healers.event.attempt-changed.*.*";
export const states = {
attempts: "attempts",
would: "would",
};
/** The key of one value of the state attempts under the form "<attempt>". */
export function attemptsByAttemptKey(attempt) {
return attempt;
}
/** The parts of a key of the form "<attempt>", or undefined for a key of another form. */
export function parseAttemptsByAttemptKey(_key) {
let _rest = _key;
if (_rest === "") return undefined;
const attempt = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { attempt };
}
/** The key of one value of the state would under the form "<would>". */
export function wouldByWouldKey(would) {
return would;
}
/** The parts of a key of the form "<would>", or undefined for a key of another form. */
export function parseWouldByWouldKey(_key) {
let _rest = _key;
if (_rest === "") return undefined;
const would = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { would };
}
+2 -2
View File
@@ -1,9 +1,9 @@
{
"lockfileVersion": 3,
"name": "@novox/mesh-health-and-repair-contracts-mesh-healers",
"name": "@novox/mesh-contracts-health-and-repair-mesh-healers",
"packages": {
"": {
"name": "@novox/mesh-health-and-repair-contracts-mesh-healers",
"name": "@novox/mesh-contracts-health-and-repair-mesh-healers",
"version": "0.1.0"
}
},
@@ -1,13 +1,18 @@
{
"description": "The contract of the seat mesh-healers, generated from its definition.",
"exports": {
".": "./src/index.ts"
".": {
"default": "./index.js",
"types": "./index.d.ts"
}
},
"files": [
"src"
"index.js",
"index.d.ts",
"parts"
],
"name": "@novox/mesh-health-and-repair-contracts-mesh-healers",
"name": "@novox/mesh-contracts-health-and-repair-mesh-healers",
"type": "module",
"types": "./src/index.ts",
"types": "./index.d.ts",
"version": "0.1.0"
}
@@ -1,12 +0,0 @@
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"noEmit": true,
"strict": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*.ts"]
}
@@ -2,20 +2,20 @@
// The contract of the seat "mesh-self-check", defined whole (seats/mesh-self-check/seat.json): The mesh checking itself (ADR 0564): probes run every five minutes, each failure a finding the seat's conditions raise.
export const seat = "mesh-self-check";
export declare const seat: "mesh-self-check";
export const verbs = {
doctor: "doctor",
probes: "probes",
} as const;
export declare const verbs: {
readonly doctor: "doctor";
readonly probes: "probes";
};
export const events = {
checked: "checked",
} as const;
export declare const events: {
readonly checked: "checked";
};
export const family = { name: "mesh-self-check.events", maxAgeDays: 7 } as const;
export declare const family: { readonly name: "mesh-self-check.events"; readonly maxAgeDays: 7 };
export const checkedSubject = "mesh.seat.mesh-self-check.event.checked";
export declare const checkedSubject: "mesh.seat.mesh-self-check.event.checked";
/** one probe's verdict */
export interface ProbeVerdict {
@@ -0,0 +1,19 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// The contract of the seat "mesh-self-check", defined whole (seats/mesh-self-check/seat.json): The mesh checking itself (ADR 0564): probes run every five minutes, each failure a finding the seat's conditions raise.
export const seat = "mesh-self-check";
export const verbs = {
doctor: "doctor",
probes: "probes",
};
export const events = {
checked: "checked",
};
export const family = { name: "mesh-self-check.events", maxAgeDays: 7 };
export const checkedSubject = "mesh.seat.mesh-self-check.event.checked";
+2 -2
View File
@@ -1,9 +1,9 @@
{
"lockfileVersion": 3,
"name": "@novox/mesh-health-and-repair-contracts-mesh-self-check",
"name": "@novox/mesh-contracts-health-and-repair-mesh-self-check",
"packages": {
"": {
"name": "@novox/mesh-health-and-repair-contracts-mesh-self-check",
"name": "@novox/mesh-contracts-health-and-repair-mesh-self-check",
"version": "0.1.0"
}
},
@@ -1,13 +1,18 @@
{
"description": "The contract of the seat mesh-self-check, generated from its definition.",
"exports": {
".": "./src/index.ts"
".": {
"default": "./index.js",
"types": "./index.d.ts"
}
},
"files": [
"src"
"index.js",
"index.d.ts",
"parts"
],
"name": "@novox/mesh-health-and-repair-contracts-mesh-self-check",
"name": "@novox/mesh-contracts-health-and-repair-mesh-self-check",
"type": "module",
"types": "./src/index.ts",
"types": "./index.d.ts",
"version": "0.1.0"
}
@@ -1,12 +0,0 @@
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"noEmit": true,
"strict": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*.ts"]
}
@@ -2,95 +2,64 @@
// The contract of the seat "mesh-watchdogs", defined whole (seats/mesh-watchdogs/seat.json): The watchman's seat (ADR 0564, ADR 0433): signals that expire unless renewed, what stopped moving, who is present, the dead letters.
export const seat = "mesh-watchdogs";
export declare const seat: "mesh-watchdogs";
export const verbs = {
signals: "signals",
stuck: "stuck",
presence: "presence",
deadLetters: "dead-letters",
resync: "resync",
} as const;
export declare const verbs: {
readonly signals: "signals";
readonly stuck: "stuck";
readonly presence: "presence";
readonly deadLetters: "dead-letters";
readonly resync: "resync";
};
export const states = {
presence: "presence",
pulse: "pulse",
stuck: "stuck",
} as const;
export declare const events: {
readonly machineAway: "machine-away";
readonly machineBack: "machine-back";
};
export declare const family: { readonly name: "mesh-watchdogs.events"; readonly maxAgeDays: 7 };
export declare const machineAwayStream: "SEAT_mesh-watchdogs_machine-away";
export declare function machineAwaySubject(machine: string): string;
export declare const machineAwaySubjectAll: "mesh.seat.mesh-watchdogs.event.machine-away.*";
export declare const machineBackStream: "SEAT_mesh-watchdogs_machine-back";
export declare function machineBackSubject(machine: string): string;
export declare const machineBackSubjectAll: "mesh.seat.mesh-watchdogs.event.machine-back.*";
export declare const states: {
readonly presence: "presence";
readonly pulse: "pulse";
readonly stuck: "stuck";
};
/** The key of one value of the state presence under the form "<node>". */
export function presenceByNodeKey(node: string): string {
return node;
}
export declare function presenceByNodeKey(node: string): string;
/** The parts of a key of the form "<node>", or undefined for a key of another form. */
export function parsePresenceByNodeKey(_key: string): { node: string } | undefined {
let _rest = _key;
if (_rest === "") return undefined;
const node = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { node };
}
export declare function parsePresenceByNodeKey(_key: string): { node: string } | undefined;
/** The key of one value of the state presence under the form "part.<part>.<instance>". */
export function presenceByPartPartInstanceKey(part: string, instance: string): string {
return "part." + part + "." + instance;
}
export declare function presenceByPartPartInstanceKey(part: string, instance: string): string;
/** The parts of a key of the form "part.<part>.<instance>", or undefined for a key of another form. */
export function parsePresenceByPartPartInstanceKey(_key: string): { part: string; instance: string } | undefined {
let _rest = _key;
if (!_rest.startsWith("part.")) return undefined;
_rest = _rest.slice(5);
const _at1 = _rest.indexOf(".");
if (_at1 <= 0) return undefined;
const part = _rest.slice(0, _at1);
_rest = _rest.slice(_at1 + 1);
if (_rest === "") return undefined;
const instance = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { part, instance };
}
export declare function parsePresenceByPartPartInstanceKey(_key: string): { part: string; instance: string } | undefined;
/** The key of one value of the state pulse under the form "<bucket>.<key>". */
export function pulseByBucketKeyKey(bucket: string, key: string): string {
return bucket + "." + key;
}
export declare function pulseByBucketKeyKey(bucket: string, key: string): string;
/** The parts of a key of the form "<bucket>.<key>", or undefined for a key of another form. */
export function parsePulseByBucketKeyKey(_key: string): { bucket: string; key: string } | undefined {
let _rest = _key;
const _at0 = _rest.indexOf(".");
if (_at0 <= 0) return undefined;
const bucket = _rest.slice(0, _at0);
_rest = _rest.slice(_at0 + 1);
if (_rest === "") return undefined;
const key = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { bucket, key };
}
export declare function parsePulseByBucketKeyKey(_key: string): { bucket: string; key: string } | undefined;
/** The key of one value of the state stuck under the form "<bucket>.<key>". */
export function stuckByBucketKeyKey(bucket: string, key: string): string {
return bucket + "." + key;
}
export declare function stuckByBucketKeyKey(bucket: string, key: string): string;
/** The parts of a key of the form "<bucket>.<key>", or undefined for a key of another form. */
export function parseStuckByBucketKeyKey(_key: string): { bucket: string; key: string } | undefined {
let _rest = _key;
const _at0 = _rest.indexOf(".");
if (_at0 <= 0) return undefined;
const bucket = _rest.slice(0, _at0);
_rest = _rest.slice(_at0 + 1);
if (_rest === "") return undefined;
const key = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { bucket, key };
}
export declare function parseStuckByBucketKeyKey(_key: string): { bucket: string; key: string } | undefined;
/** is what signals takes. */
export interface SignalsInput {
@@ -116,8 +85,30 @@ export interface PresenceInput {
"machine"?: string;
}
export interface PresenceAnswerKeysItem {
/** <node> or part.<part>.<instance> */
"key": string;
/** the key's revision */
"revision"?: number;
/** the key's value, online and its layout's version */
"value": Record<string, unknown>;
}
/** is what presence answers. */
export type PresenceAnswer = Record<string, unknown>;
export interface PresenceAnswer {
/** without machine: how many keys the state holds */
"holds"?: number;
/** without machine: each key of the state presence, <node> or part.<part>.<instance>, with its value */
"keys"?: PresenceAnswerKeysItem[];
/** the machine asked, with machine */
"machine"?: string;
/** with machine: whether the watchman hears the machine now; false for a machine it holds no word of */
"online"?: boolean;
/** with machine: when its presence last changed, RFC 3339; empty for a machine the watchman holds no word of */
"since"?: string;
/** without machine: the state read, presence */
"state"?: string;
}
/** is what dead-letters takes. */
export interface DeadLettersInput {
@@ -147,6 +138,28 @@ export interface ResyncInput {
/** is what resync answers. */
export type ResyncAnswer = Record<string, unknown>;
/** is the body of the event machine-away. */
export interface MachineAwayEvent {
"at": string;
/** when the machine was last heard */
"last-heard": string;
/** the machine whose presence changed */
"machine": string;
/** the layout's version */
"v": number;
}
/** is the body of the event machine-back. */
export interface MachineBackEvent {
"at": string;
/** when the machine was last heard */
"last-heard": string;
/** the machine whose presence changed */
"machine": string;
/** the layout's version */
"v": number;
}
/** is one value of the state presence under the key <node>. */
export interface PresenceByNodeValue {
"online": boolean;
@@ -0,0 +1,117 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// The contract of the seat "mesh-watchdogs", defined whole (seats/mesh-watchdogs/seat.json): The watchman's seat (ADR 0564, ADR 0433): signals that expire unless renewed, what stopped moving, who is present, the dead letters.
export const seat = "mesh-watchdogs";
export const verbs = {
signals: "signals",
stuck: "stuck",
presence: "presence",
deadLetters: "dead-letters",
resync: "resync",
};
export const events = {
machineAway: "machine-away",
machineBack: "machine-back",
};
export const family = { name: "mesh-watchdogs.events", maxAgeDays: 7 };
export const machineAwayStream = "SEAT_mesh-watchdogs_machine-away";
export function machineAwaySubject(machine) {
return "mesh.seat.mesh-watchdogs.event.machine-away." + machine;
}
export const machineAwaySubjectAll = "mesh.seat.mesh-watchdogs.event.machine-away.*";
export const machineBackStream = "SEAT_mesh-watchdogs_machine-back";
export function machineBackSubject(machine) {
return "mesh.seat.mesh-watchdogs.event.machine-back." + machine;
}
export const machineBackSubjectAll = "mesh.seat.mesh-watchdogs.event.machine-back.*";
export const states = {
presence: "presence",
pulse: "pulse",
stuck: "stuck",
};
/** The key of one value of the state presence under the form "<node>". */
export function presenceByNodeKey(node) {
return node;
}
/** The parts of a key of the form "<node>", or undefined for a key of another form. */
export function parsePresenceByNodeKey(_key) {
let _rest = _key;
if (_rest === "") return undefined;
const node = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { node };
}
/** The key of one value of the state presence under the form "part.<part>.<instance>". */
export function presenceByPartPartInstanceKey(part, instance) {
return "part." + part + "." + instance;
}
/** The parts of a key of the form "part.<part>.<instance>", or undefined for a key of another form. */
export function parsePresenceByPartPartInstanceKey(_key) {
let _rest = _key;
if (!_rest.startsWith("part.")) return undefined;
_rest = _rest.slice(5);
const _at1 = _rest.indexOf(".");
if (_at1 <= 0) return undefined;
const part = _rest.slice(0, _at1);
_rest = _rest.slice(_at1 + 1);
if (_rest === "") return undefined;
const instance = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { part, instance };
}
/** The key of one value of the state pulse under the form "<bucket>.<key>". */
export function pulseByBucketKeyKey(bucket, key) {
return bucket + "." + key;
}
/** The parts of a key of the form "<bucket>.<key>", or undefined for a key of another form. */
export function parsePulseByBucketKeyKey(_key) {
let _rest = _key;
const _at0 = _rest.indexOf(".");
if (_at0 <= 0) return undefined;
const bucket = _rest.slice(0, _at0);
_rest = _rest.slice(_at0 + 1);
if (_rest === "") return undefined;
const key = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { bucket, key };
}
/** The key of one value of the state stuck under the form "<bucket>.<key>". */
export function stuckByBucketKeyKey(bucket, key) {
return bucket + "." + key;
}
/** The parts of a key of the form "<bucket>.<key>", or undefined for a key of another form. */
export function parseStuckByBucketKeyKey(_key) {
let _rest = _key;
const _at0 = _rest.indexOf(".");
if (_at0 <= 0) return undefined;
const bucket = _rest.slice(0, _at0);
_rest = _rest.slice(_at0 + 1);
if (_rest === "") return undefined;
const key = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { bucket, key };
}
+2 -2
View File
@@ -1,9 +1,9 @@
{
"lockfileVersion": 3,
"name": "@novox/mesh-health-and-repair-contracts-mesh-watchdogs",
"name": "@novox/mesh-contracts-health-and-repair-mesh-watchdogs",
"packages": {
"": {
"name": "@novox/mesh-health-and-repair-contracts-mesh-watchdogs",
"name": "@novox/mesh-contracts-health-and-repair-mesh-watchdogs",
"version": "0.1.0"
}
},
@@ -1,13 +1,18 @@
{
"description": "The contract of the seat mesh-watchdogs, generated from its definition.",
"exports": {
".": "./src/index.ts"
".": {
"default": "./index.js",
"types": "./index.d.ts"
}
},
"files": [
"src"
"index.js",
"index.d.ts",
"parts"
],
"name": "@novox/mesh-health-and-repair-contracts-mesh-watchdogs",
"name": "@novox/mesh-contracts-health-and-repair-mesh-watchdogs",
"type": "module",
"types": "./src/index.ts",
"types": "./index.d.ts",
"version": "0.1.0"
}
@@ -1,12 +0,0 @@
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"noEmit": true,
"strict": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*.ts"]
}
@@ -32,27 +32,26 @@ func TestATokenLifeAndTheRedeemProofAreAsTheHolderMakesThem(t *testing.T) {
if got := (RedeemAnswer{Node: "g14", Signature: "x"}).SignedBytes(); string(got) == "" || string(got) == "x" {
t.Errorf("SignedBytes = %s", got)
}
}
// TestTheRedeemAnswerIsTheContractsWire: the client's answer reads into the contract's type with no field dropped, and
// the contract's reads back as the client's wire.
func TestTheRedeemAnswerIsTheContractsWire(t *testing.T) {
mine := RedeemAnswer{Node: "g14", Login: "g14-login", Account: "YQ==", Certificate: "pem", Signer: "dg==", Signature: "cw=="}
wire, _ := json.Marshal(mine)
var theirs seat.RedeemAnswer
d := json.NewDecoder(bytes.NewReader(wire))
d.DisallowUnknownFields()
if err := d.Decode(&theirs); err != nil {
t.Fatal(err)
}
if theirs.Node != "g14" || theirs.Signer != "dg==" || theirs.Signature != "cw==" {
t.Errorf("the contract reads %+v", theirs)
}
back, _ := json.Marshal(theirs)
var a, b map[string]string
_ = json.Unmarshal(wire, &a)
_ = json.Unmarshal(back, &b)
if len(a) != 6 || !reflect.DeepEqual(a, b) {
t.Errorf("the contract reads %s back as %s", wire, back)
}
// TestTheRedeemAnswerIsTheContractsWire: the client's answer reads into the contract's type with no field dropped, and
// the contract's reads back as the client's wire.
t.Run("TheRedeemAnswerIsTheContractsWire", func(t *testing.T) {
mine := RedeemAnswer{Node: "laptop", Login: "laptop-login", Account: "YQ==", Certificate: "pem", Signer: "dg==", Signature: "cw=="}
wire, _ := json.Marshal(mine)
var theirs seat.RedeemAnswer
d := json.NewDecoder(bytes.NewReader(wire))
d.DisallowUnknownFields()
if err := d.Decode(&theirs); err != nil {
t.Fatal(err)
}
if theirs.Node != "laptop" || theirs.Signer != "dg==" || theirs.Signature != "cw==" {
t.Errorf("the contract reads %+v", theirs)
}
back, _ := json.Marshal(theirs)
var a, b map[string]string
_ = json.Unmarshal(wire, &a)
_ = json.Unmarshal(back, &b)
if len(a) != 6 || !reflect.DeepEqual(a, b) {
t.Errorf("the contract reads %s back as %s", wire, back)
}
})
}
@@ -0,0 +1,167 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// Package meshgrants is the contract of the seat "mesh-grants", defined whole (seats/mesh-grants/seat.json): Who may say what on the bus: the grants part composes each module's membership, its buckets, logs and streams, the bus's user list and grants (design 47 'The grants part'). An acting part of the step grant (ADR 0656 1): an entry whose grant waits for its new version is held on its running build within the bound, said by wait-held and wait-ended; a store passing 80 % of its cap is said by filling, and back below 70 % by room; grants-for answers the grants a candidate would compose (design 47 G 331, 441).
package meshgrants
import "time"
// Seat is the seat's name.
const Seat = "mesh-grants"
const (
VerbGrantsFor = "grants-for"
VerbWithheld = "withheld"
)
const (
EventWaitHeld = "wait-held"
EventWaitEnded = "wait-ended"
EventFilling = "filling"
EventRoom = "room"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbGrantsFor, VerbWithheld}
}
// Events is every event published on the seat's subject: a new copy each call.
func Events() []string {
return []string{EventWaitHeld, EventWaitEnded, EventFilling, EventRoom}
}
// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects.
const (
Family = "mesh-grants.events"
FamilyMaxAgeDays = 7
)
// SubjectWaitHeld is where wait-held is published.
const SubjectWaitHeld = "mesh.seat.mesh-grants.event.wait-held"
// SubjectWaitEnded is where wait-ended is published.
const SubjectWaitEnded = "mesh.seat.mesh-grants.event.wait-ended"
// SubjectFilling is where filling is published.
const SubjectFilling = "mesh.seat.mesh-grants.event.filling"
// SubjectRoom is where room is published.
const SubjectRoom = "mesh.seat.mesh-grants.event.room"
// Fill is a store's fill against its cap.
type Fill struct {
At *time.Time `json:"at,omitempty"`
Bytes int64 `json:"bytes"`
// bytes
Cap int64 `json:"cap"`
// the store
Store string `json:"store"`
}
// Grant is a type of the contract.
type Grant struct {
// the bus subject
Subject string `json:"subject"`
// the verb or event the grant is for
Verb string `json:"verb"`
}
// GrantsForModulesItem is a type of the contract.
type GrantsForModulesItem struct {
Added []Grant `json:"added"`
Module string `json:"module"`
Removed []Grant `json:"removed"`
}
// GrantsFor is the grants a candidate would compose, per module, added and removed against the branch's newest.
type GrantsFor struct {
// why it could not be answered: the catalog half of the candidate is not held
Error string `json:"error,omitempty"`
Modules []GrantsForModulesItem `json:"modules,omitempty"`
}
// Wait is a granting wait the grants part holds: an entry whose grant waits until the grants part's new version runs (design 47 *Each step's wait is its own part's*).
type Wait struct {
// a duration such as 10m
Bound string `json:"bound"`
// on a release, who released it and why
By string `json:"by,omitempty"`
// when the new version's build was done, as the builder's build.ended says; the bound's clock starts there (design 47 G 266)
ClockFrom time.Time `json:"clock-from"`
// the entry's fingerprint, whose grant waits
Fp string `json:"fp,omitempty"`
// on wait-ended: ran or released
How string `json:"how,omitempty"`
// the entry that waits
Module string `json:"module"`
// the acting part waited for
Part string `json:"part"`
Since time.Time `json:"since"`
// the step, grant
Step string `json:"step"`
// its new version's fingerprint
Version string `json:"version"`
}
// The values of Wait's how.
const (
WaitHowRan = "ran"
WaitHowReleased = "released"
)
// The values of Wait's step.
const (
WaitStepGrant = "grant"
)
// WithheldModulesItem is a type of the contract.
type WithheldModulesItem struct {
Module string `json:"module"`
Subjects []WithheldSubject `json:"subjects"`
}
// Withheld is a node's withheld subjects, by module.
type Withheld struct {
Modules []WithheldModulesItem `json:"modules"`
Node string `json:"node"`
}
// WithheldSubject is one subject withheld, and why.
type WithheldSubject struct {
Subject string `json:"subject"`
Why string `json:"why"`
}
// GrantsForInput is what grants-for takes.
type GrantsForInput struct {
// its watched branch
Branch string `json:"branch"`
// or the id of a run
Run string `json:"run,omitempty"`
// the candidate's source revision
Source string `json:"source,omitempty"`
}
// GrantsForAnswer is what grants-for answers.
type GrantsForAnswer = GrantsFor
// WithheldInput is what withheld takes.
type WithheldInput struct {
// the node whose runtime's withheld subjects are asked
Node string `json:"node"`
}
// WithheldAnswer is what withheld answers.
type WithheldAnswer = Withheld
// WaitHeldEvent is the body of the event wait-held.
type WaitHeldEvent = Wait
// WaitEndedEvent is the body of the event wait-ended.
type WaitEndedEvent = Wait
// FillingEvent is the body of the event filling.
type FillingEvent = Fill
// RoomEvent is the body of the event room.
type RoomEvent = Fill
@@ -0,0 +1,62 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
package meshgrants
import (
"encoding/json"
"reflect"
"regexp"
"testing"
)
// TestFixtures reads every fixture of seats/mesh-grants/fixtures: each decodes into its type, a field the type does not
// know is dropped (ADR 0608 §6), and it reads back as its wire says; each subject named is the contract's.
func TestFixtures(t *testing.T) {
cases := []struct {
name, subject, given, wire string
decode func([]byte) (any, error)
subjectIs *regexp.Regexp
}{
{name: "a granting wait held", subject: "mesh.seat.mesh-grants.event.wait-held", given: "{\"bound\":\"10m\",\"clock-from\":\"2026-11-09T20:55:00Z\",\"fp\":\"src2:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"module\":\"mesh-tools\",\"part\":\"mesh-grants\",\"since\":\"2026-11-09T21:00:00Z\",\"step\":\"grant\",\"version\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}", wire: "{\"bound\":\"10m\",\"clock-from\":\"2026-11-09T20:55:00Z\",\"fp\":\"src2:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"module\":\"mesh-tools\",\"part\":\"mesh-grants\",\"since\":\"2026-11-09T21:00:00Z\",\"step\":\"grant\",\"version\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}",
decode: func(b []byte) (any, error) { var v WaitHeldEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-grants\\.event\\.wait-held$")},
{name: "a granting wait released", subject: "mesh.seat.mesh-grants.event.wait-ended", given: "{\"bound\":\"10m\",\"by\":\"operator: the new grants part is stuck\",\"clock-from\":\"2026-11-09T20:55:00Z\",\"fp\":\"src2:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"how\":\"released\",\"module\":\"mesh-tools\",\"part\":\"mesh-grants\",\"since\":\"2026-11-09T21:00:00Z\",\"step\":\"grant\",\"version\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}", wire: "{\"bound\":\"10m\",\"by\":\"operator: the new grants part is stuck\",\"clock-from\":\"2026-11-09T20:55:00Z\",\"fp\":\"src2:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"how\":\"released\",\"module\":\"mesh-tools\",\"part\":\"mesh-grants\",\"since\":\"2026-11-09T21:00:00Z\",\"step\":\"grant\",\"version\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}",
decode: func(b []byte) (any, error) { var v WaitEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-grants\\.event\\.wait-ended$")},
{name: "filling is said past 80 %", subject: "mesh.seat.mesh-grants.event.filling", given: "{\"at\":\"2026-11-11T09:00:00Z\",\"bytes\":161061273,\"cap\":201326592,\"store\":\"SEAT_mesh-pipeline-runner_pipeline-ended\"}", wire: "{\"at\":\"2026-11-11T09:00:00Z\",\"bytes\":161061273,\"cap\":201326592,\"store\":\"SEAT_mesh-pipeline-runner_pipeline-ended\"}",
decode: func(b []byte) (any, error) { var v FillingEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-grants\\.event\\.filling$")},
{name: "room is said below 70 %", subject: "mesh.seat.mesh-grants.event.room", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"bytes\":100663296,\"cap\":201326592,\"store\":\"SEAT_mesh-pipeline-runner_pipeline-ended\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"bytes\":100663296,\"cap\":201326592,\"store\":\"SEAT_mesh-pipeline-runner_pipeline-ended\"}",
decode: func(b []byte) (any, error) { var v RoomEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-grants\\.event\\.room$")},
{name: "grants-for answers the grants a candidate adds", subject: "", given: "{\"modules\":[{\"added\":[{\"subject\":\"mesh.seat.node-engine.verb.manifest-reads\",\"verb\":\"manifest-reads\"}],\"module\":\"mesh-tools\",\"removed\":[]}]}", wire: "{\"modules\":[{\"added\":[{\"subject\":\"mesh.seat.node-engine.verb.manifest-reads\",\"verb\":\"manifest-reads\"}],\"module\":\"mesh-tools\",\"removed\":[]}]}",
decode: func(b []byte) (any, error) { var v GrantsForAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "grants-for asks a source revision on a branch", subject: "", given: "{\"branch\":\"main\",\"source\":\"a1b2c3d4\"}", wire: "{\"branch\":\"main\",\"source\":\"a1b2c3d4\"}",
decode: func(b []byte) (any, error) { var v GrantsForInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "withheld answers a node's withheld subjects by module", subject: "", given: "{\"modules\":[{\"module\":\"zsh\",\"subjects\":[{\"subject\":\"mesh.mod.zsh.tool.execute\",\"why\":\"its tool runner does not state approval-mark/1\"},{\"subject\":\"mesh.mod.zsh.tool.execute.*\",\"why\":\"its tool runner does not state approval-mark/1\"},{\"subject\":\"mesh.mod.zsh.call.execute.\\u003e\",\"why\":\"its tool runner does not state approval-mark/1\"}]}],\"node\":\"workstation\"}", wire: "{\"modules\":[{\"module\":\"zsh\",\"subjects\":[{\"subject\":\"mesh.mod.zsh.tool.execute\",\"why\":\"its tool runner does not state approval-mark/1\"},{\"subject\":\"mesh.mod.zsh.tool.execute.*\",\"why\":\"its tool runner does not state approval-mark/1\"},{\"subject\":\"mesh.mod.zsh.call.execute.\\u003e\",\"why\":\"its tool runner does not state approval-mark/1\"}]}],\"node\":\"workstation\"}",
decode: func(b []byte) (any, error) { var v WithheldAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "withheld asks a node", subject: "", given: "{\"node\":\"workstation\"}", wire: "{\"node\":\"workstation\"}",
decode: func(b []byte) (any, error) { var v WithheldInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
if err != nil {
t.Errorf("%s: does not decode: %v", c.name, err)
continue
}
back, err := json.Marshal(v)
if err != nil {
t.Errorf("%s: does not encode: %v", c.name, err)
continue
}
var got, want any
if err := json.Unmarshal(back, &got); err != nil {
t.Fatal(err)
}
if err := json.Unmarshal([]byte(c.wire), &want); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(got, want) {
t.Errorf("%s: reads back as %s, want %s", c.name, back, c.wire)
}
if c.subjectIs != nil && !c.subjectIs.MatchString(c.subject) {
t.Errorf("%s: subject %q is not the contract's %s", c.name, c.subject, c.subjectIs)
}
}
}
@@ -0,0 +1,3 @@
module git.novox.be/novox/mesh-contracts/identity-and-access/go/seats/meshgrants
go 1.26.0
@@ -30,11 +30,12 @@ const (
VerbNodeAccountConfirm = "node-account-confirm"
VerbAbandon = "abandon"
VerbRetire = "retire"
VerbLicencePut = "licence-put"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbGet, VerbSecretAsk, VerbIssued, VerbRotate, VerbMoveIn, VerbNodeKey, VerbOwn, VerbIssueAccount, VerbSign, VerbEnrolmentToken, VerbNodeAccount, VerbRotateNode, VerbNodeAccountConfirm, VerbAbandon, VerbRetire}
return []string{VerbGet, VerbSecretAsk, VerbIssued, VerbRotate, VerbMoveIn, VerbNodeKey, VerbOwn, VerbIssueAccount, VerbSign, VerbEnrolmentToken, VerbNodeAccount, VerbRotateNode, VerbNodeAccountConfirm, VerbAbandon, VerbRetire, VerbLicencePut}
}
// The holder's own events, listed beside the seat and published under the holder's subjects (ADR 0620 §2).
@@ -506,6 +507,23 @@ type RetireAnswer struct {
Retired bool `json:"retired"`
}
// LicencePutInput is what licence-put takes.
type LicencePutInput struct {
// the second step: the call the first step answered
Call string `json:"call,omitempty"`
// the first step: the licence's generation
Generation float64 `json:"generation,omitempty"`
// the first step: the licence's key
Licence string `json:"licence,omitempty"`
// the first step: grant or access
Part string `json:"part,omitempty"`
// the second step: the value sealed to the call's key — never the value
Sealed string `json:"sealed,omitempty"`
}
// LicencePutAnswer is what licence-put answers.
type LicencePutAnswer = map[string]any
// SignedHolderEvent is the body of the holder's event signed.
type SignedHolderEvent struct {
// when it was signed, RFC 3339
+21 -9
View File
@@ -1,6 +1,6 @@
{
"module": "mesh-identity-and-access-contracts",
"version": "1",
"version": "0.1",
"build": {
"artifacts": [
{
@@ -10,7 +10,6 @@
"paths": [
"go/seats/meshvault"
],
"series": "0.1",
"generated-from": "."
},
{
@@ -20,7 +19,15 @@
"paths": [
"go/seats/meshnodeenroller"
],
"series": "0.1",
"generated-from": "."
},
{
"name": "go-meshgrants",
"kind": "package",
"language": "go",
"paths": [
"go/seats/meshgrants"
],
"generated-from": "."
},
{
@@ -29,8 +36,7 @@
"language": "go",
"paths": [
"go/clients/meshvaultclient"
],
"series": "0.1"
]
},
{
"name": "go-meshnodeenrollerclient",
@@ -38,8 +44,7 @@
"language": "go",
"paths": [
"go/clients/meshnodeenrollerclient"
],
"series": "0.1"
]
},
{
"name": "ts-meshvault",
@@ -48,7 +53,6 @@
"paths": [
"ts/seats/meshvault"
],
"series": "0.1",
"generated-from": "."
},
{
@@ -58,7 +62,15 @@
"paths": [
"ts/seats/meshnodeenroller"
],
"series": "0.1",
"generated-from": "."
},
{
"name": "ts-meshgrants",
"kind": "package",
"language": "typescript",
"paths": [
"ts/seats/meshgrants"
],
"generated-from": "."
}
]
+1
View File
@@ -1,6 +1,7 @@
{
"format": 1,
"seats": [
"mesh-grants",
"mesh-node-enroller",
"mesh-vault",
"node-secret-service"
@@ -0,0 +1,56 @@
[
{
"name": "a granting wait held",
"of": "event:wait-held",
"subject": "mesh.seat.mesh-grants.event.wait-held",
"given": {
"step": "grant",
"part": "mesh-grants",
"version": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"module": "mesh-tools",
"fp": "src2:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"since": "2026-11-09T21:00:00Z",
"bound": "10m",
"clock-from": "2026-11-09T20:55:00Z"
}
},
{
"name": "a granting wait released",
"of": "event:wait-ended",
"subject": "mesh.seat.mesh-grants.event.wait-ended",
"given": {
"step": "grant",
"part": "mesh-grants",
"version": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"module": "mesh-tools",
"fp": "src2:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"since": "2026-11-09T21:00:00Z",
"bound": "10m",
"how": "released",
"by": "operator: the new grants part is stuck",
"clock-from": "2026-11-09T20:55:00Z"
}
},
{
"name": "filling is said past 80 %",
"of": "event:filling",
"subject": "mesh.seat.mesh-grants.event.filling",
"given": {
"store": "SEAT_mesh-pipeline-runner_pipeline-ended",
"bytes": 161061273,
"cap": 201326592,
"at": "2026-11-11T09:00:00Z"
}
},
{
"name": "room is said below 70 %",
"of": "event:room",
"subject": "mesh.seat.mesh-grants.event.room",
"given": {
"store": "SEAT_mesh-pipeline-runner_pipeline-ended",
"bytes": 100663296,
"cap": 201326592,
"at": "2026-11-11T10:00:00Z"
}
}
]
@@ -0,0 +1,61 @@
[
{
"name": "grants-for answers the grants a candidate adds",
"of": "verb:grants-for.answer",
"given": {
"modules": [
{
"module": "mesh-tools",
"added": [
{
"subject": "mesh.seat.node-engine.verb.manifest-reads",
"verb": "manifest-reads"
}
],
"removed": []
}
]
}
},
{
"name": "grants-for asks a source revision on a branch",
"of": "verb:grants-for.input",
"given": {
"source": "a1b2c3d4",
"branch": "main"
}
},
{
"name": "withheld answers a node's withheld subjects by module",
"of": "verb:withheld.answer",
"given": {
"node": "workstation",
"modules": [
{
"module": "zsh",
"subjects": [
{
"subject": "mesh.mod.zsh.tool.execute",
"why": "its tool runner does not state approval-mark/1"
},
{
"subject": "mesh.mod.zsh.tool.execute.*",
"why": "its tool runner does not state approval-mark/1"
},
{
"subject": "mesh.mod.zsh.call.execute.>",
"why": "its tool runner does not state approval-mark/1"
}
]
}
]
}
},
{
"name": "withheld asks a node",
"of": "verb:withheld.input",
"given": {
"node": "workstation"
}
}
]
@@ -0,0 +1,298 @@
{
"format": 1,
"seat": "mesh-grants",
"scope": "mesh",
"grain": "whole",
"domain": "Identity and access",
"decision": "novox/hq ADR 0656, ADR 0547, ADR 0636",
"description": "Who may say what on the bus: the grants part composes each module's membership, its buckets, logs and streams, the bus's user list and grants (design 47 'The grants part'). An acting part of the step grant (ADR 0656 1): an entry whose grant waits for its new version is held on its running build within the bound, said by wait-held and wait-ended; a store passing 80 % of its cap is said by filling, and back below 70 % by room; grants-for answers the grants a candidate would compose (design 47 G 331, 441).",
"acts": [
{
"step": "grant",
"on": "every"
}
],
"verbs": [
{
"name": "grants-for",
"description": "The grants a candidate would compose, per module: the grants it would add and remove against the branch's newest, each named by its subject and verb. The candidate's catalog half is taken by mesh-catalog's revision (design 47 G 441).",
"class": "read",
"input": {
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "the candidate's source revision"
},
"run": {
"type": "string",
"description": "or the id of a run"
},
"branch": {
"type": "string",
"description": "its watched branch"
}
},
"required": [
"branch"
],
"additionalProperties": false
},
"answer": {
"$ref": "#/defs/GrantsFor"
}
},
{
"name": "withheld",
"description": "The marked subjects withheld from each module a node's runtime carries, and why: where its tool runner does not state approval-mark/1, or its reading is not the running runner's (design 46 approval mark 6).",
"class": "read",
"callers": [
"seat:node-engine",
"persons",
"operator"
],
"input": {
"type": "object",
"properties": {
"node": {
"type": "string",
"description": "the node whose runtime's withheld subjects are asked"
}
},
"required": [
"node"
],
"additionalProperties": false
},
"answer": {
"$ref": "#/defs/Withheld"
}
}
],
"events": [
{
"name": "wait-held",
"body": {
"$ref": "#/defs/Wait"
}
},
{
"name": "wait-ended",
"body": {
"$ref": "#/defs/Wait"
}
},
{
"name": "filling",
"body": {
"$ref": "#/defs/Fill"
}
},
{
"name": "room",
"body": {
"$ref": "#/defs/Fill"
}
}
],
"family": {
"name": "mesh-grants.events",
"max-age-days": 7
},
"defs": {
"Wait": {
"type": "object",
"description": "a granting wait the grants part holds: an entry whose grant waits until the grants part's new version runs (design 47 *Each step's wait is its own part's*)",
"properties": {
"step": {
"type": "string",
"description": "the step, grant",
"enum": [
"grant"
]
},
"part": {
"type": "string",
"description": "the acting part waited for"
},
"version": {
"type": "string",
"description": "its new version's fingerprint"
},
"module": {
"type": "string",
"description": "the entry that waits"
},
"fp": {
"type": "string",
"description": "the entry's fingerprint, whose grant waits"
},
"since": {
"type": "string",
"format": "date-time"
},
"bound": {
"type": "string",
"description": "a duration such as 10m"
},
"how": {
"type": "string",
"description": "on wait-ended: ran or released",
"enum": [
"ran",
"released"
]
},
"by": {
"type": "string",
"description": "on a release, who released it and why"
},
"clock-from": {
"type": "string",
"format": "date-time",
"description": "when the new version's build was done, as the builder's build.ended says; the bound's clock starts there (design 47 G 266)"
}
},
"required": [
"step",
"part",
"version",
"module",
"since",
"bound",
"clock-from"
]
},
"Fill": {
"type": "object",
"description": "a store's fill against its cap",
"properties": {
"store": {
"type": "string",
"description": "the store"
},
"bytes": {
"type": "integer"
},
"cap": {
"type": "integer",
"description": "bytes"
},
"at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"store",
"bytes",
"cap"
]
},
"Grant": {
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "the bus subject"
},
"verb": {
"type": "string",
"description": "the verb or event the grant is for"
}
},
"required": [
"subject",
"verb"
]
},
"GrantsFor": {
"type": "object",
"description": "the grants a candidate would compose, per module, added and removed against the branch's newest",
"properties": {
"modules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"module": {
"type": "string"
},
"added": {
"type": "array",
"items": {
"$ref": "#/defs/Grant"
}
},
"removed": {
"type": "array",
"items": {
"$ref": "#/defs/Grant"
}
}
},
"required": [
"module",
"added",
"removed"
]
}
},
"error": {
"type": "string",
"description": "why it could not be answered: the catalog half of the candidate is not held"
}
}
},
"Withheld": {
"type": "object",
"description": "a node's withheld subjects, by module",
"properties": {
"node": {
"type": "string"
},
"modules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"module": {
"type": "string"
},
"subjects": {
"type": "array",
"items": {
"$ref": "#/defs/WithheldSubject"
}
}
},
"required": [
"module",
"subjects"
]
}
}
},
"required": [
"node",
"modules"
]
},
"WithheldSubject": {
"type": "object",
"description": "one subject withheld, and why",
"properties": {
"subject": {
"type": "string"
},
"why": {
"type": "string"
}
},
"required": [
"subject",
"why"
]
}
}
}
+35 -1
View File
@@ -597,7 +597,6 @@
"name": "retire",
"optional": true,
"description": "Retire one module's own secret, by node, module and name, on the operator's warrant bound to exactly those three (design 32 *A value no longer read*). Emits own-retired.",
"callers": "the holder of the seat mesh-config alone",
"input": {
"type": "object",
"properties": {
@@ -641,6 +640,41 @@
"required": [
"retired"
]
},
"class": "act"
},
{
"name": "licence-put",
"description": "Hand the vault one of a licence's two secrets, its grant or its access token, from the licence manager, in two steps: name the licence by its key, the part and its generation and get a call and a key made for it; then send the call and the value sealed to that key. Keeps the newest generation and refuses an older one; says secret-changed with the secret's name and generation, never the value (novox/hq design 39 bus-and-switch §15).",
"optional": true,
"input": {
"properties": {
"call": {
"description": "the second step: the call the first step answered",
"type": "string"
},
"generation": {
"description": "the first step: the licence's generation",
"type": "number"
},
"licence": {
"description": "the first step: the licence's key",
"type": "string"
},
"part": {
"description": "the first step: grant or access",
"type": "string"
},
"sealed": {
"description": "the second step: the value sealed to the call's key — never the value",
"type": "string"
}
},
"type": "object"
},
"answer": {
"type": "object",
"description": "the holder's answer"
}
}
],
+132
View File
@@ -0,0 +1,132 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// The contract of the seat "mesh-grants", defined whole (seats/mesh-grants/seat.json): Who may say what on the bus: the grants part composes each module's membership, its buckets, logs and streams, the bus's user list and grants (design 47 'The grants part'). An acting part of the step grant (ADR 0656 1): an entry whose grant waits for its new version is held on its running build within the bound, said by wait-held and wait-ended; a store passing 80 % of its cap is said by filling, and back below 70 % by room; grants-for answers the grants a candidate would compose (design 47 G 331, 441).
export declare const seat: "mesh-grants";
export declare const verbs: {
readonly grantsFor: "grants-for";
readonly withheld: "withheld";
};
export declare const events: {
readonly waitHeld: "wait-held";
readonly waitEnded: "wait-ended";
readonly filling: "filling";
readonly room: "room";
};
export declare const family: { readonly name: "mesh-grants.events"; readonly maxAgeDays: 7 };
export declare const waitHeldSubject: "mesh.seat.mesh-grants.event.wait-held";
export declare const waitEndedSubject: "mesh.seat.mesh-grants.event.wait-ended";
export declare const fillingSubject: "mesh.seat.mesh-grants.event.filling";
export declare const roomSubject: "mesh.seat.mesh-grants.event.room";
/** a store's fill against its cap */
export interface Fill {
"at"?: string;
"bytes": number;
/** bytes */
"cap": number;
/** the store */
"store": string;
}
export interface Grant {
/** the bus subject */
"subject": string;
/** the verb or event the grant is for */
"verb": string;
}
export interface GrantsForModulesItem {
"added": Grant[];
"module": string;
"removed": Grant[];
}
/** the grants a candidate would compose, per module, added and removed against the branch's newest */
export interface GrantsFor {
/** why it could not be answered: the catalog half of the candidate is not held */
"error"?: string;
"modules"?: GrantsForModulesItem[];
}
/** a granting wait the grants part holds: an entry whose grant waits until the grants part's new version runs (design 47 *Each step's wait is its own part's*) */
export interface Wait {
/** a duration such as 10m */
"bound": string;
/** on a release, who released it and why */
"by"?: string;
/** when the new version's build was done, as the builder's build.ended says; the bound's clock starts there (design 47 G 266) */
"clock-from": string;
/** the entry's fingerprint, whose grant waits */
"fp"?: string;
/** on wait-ended: ran or released */
"how"?: "ran" | "released";
/** the entry that waits */
"module": string;
/** the acting part waited for */
"part": string;
"since": string;
/** the step, grant */
"step": "grant";
/** its new version's fingerprint */
"version": string;
}
export interface WithheldModulesItem {
"module": string;
"subjects": WithheldSubject[];
}
/** a node's withheld subjects, by module */
export interface Withheld {
"modules": WithheldModulesItem[];
"node": string;
}
/** one subject withheld, and why */
export interface WithheldSubject {
"subject": string;
"why": string;
}
/** is what grants-for takes. */
export interface GrantsForInput {
/** its watched branch */
"branch": string;
/** or the id of a run */
"run"?: string;
/** the candidate's source revision */
"source"?: string;
}
/** is what grants-for answers. */
export type GrantsForAnswer = GrantsFor;
/** is what withheld takes. */
export interface WithheldInput {
/** the node whose runtime's withheld subjects are asked */
"node": string;
}
/** is what withheld answers. */
export type WithheldAnswer = Withheld;
/** is the body of the event wait-held. */
export type WaitHeldEvent = Wait;
/** is the body of the event wait-ended. */
export type WaitEndedEvent = Wait;
/** is the body of the event filling. */
export type FillingEvent = Fill;
/** is the body of the event room. */
export type RoomEvent = Fill;
@@ -0,0 +1,28 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// The contract of the seat "mesh-grants", defined whole (seats/mesh-grants/seat.json): Who may say what on the bus: the grants part composes each module's membership, its buckets, logs and streams, the bus's user list and grants (design 47 'The grants part'). An acting part of the step grant (ADR 0656 1): an entry whose grant waits for its new version is held on its running build within the bound, said by wait-held and wait-ended; a store passing 80 % of its cap is said by filling, and back below 70 % by room; grants-for answers the grants a candidate would compose (design 47 G 331, 441).
export const seat = "mesh-grants";
export const verbs = {
grantsFor: "grants-for",
withheld: "withheld",
};
export const events = {
waitHeld: "wait-held",
waitEnded: "wait-ended",
filling: "filling",
room: "room",
};
export const family = { name: "mesh-grants.events", maxAgeDays: 7 };
export const waitHeldSubject = "mesh.seat.mesh-grants.event.wait-held";
export const waitEndedSubject = "mesh.seat.mesh-grants.event.wait-ended";
export const fillingSubject = "mesh.seat.mesh-grants.event.filling";
export const roomSubject = "mesh.seat.mesh-grants.event.room";
@@ -0,0 +1,12 @@
{
"lockfileVersion": 3,
"name": "@novox/mesh-contracts-identity-and-access-mesh-grants",
"packages": {
"": {
"name": "@novox/mesh-contracts-identity-and-access-mesh-grants",
"version": "0.1.0"
}
},
"requires": true,
"version": "0.1.0"
}
@@ -0,0 +1,18 @@
{
"description": "The contract of the seat mesh-grants, generated from its definition.",
"exports": {
".": {
"default": "./index.js",
"types": "./index.d.ts"
}
},
"files": [
"index.js",
"index.d.ts",
"parts"
],
"name": "@novox/mesh-contracts-identity-and-access-mesh-grants",
"type": "module",
"types": "./index.d.ts",
"version": "0.1.0"
}
@@ -2,74 +2,52 @@
// The contract of the seat "mesh-node-enroller", defined whole (seats/mesh-node-enroller/seat.json): The seat that enrols a new machine on the operator's Approve and a one-time token (ADR 0587). Renamed from mesh-enrolment (ADR 0634 §9).
export const seat = "mesh-node-enroller";
export declare const seat: "mesh-node-enroller";
export const verbs = {
issue: "issue",
redeem: "redeem",
confirm: "confirm",
revoke: "revoke",
tokens: "tokens",
again: "again",
} as const;
export declare const verbs: {
readonly issue: "issue";
readonly redeem: "redeem";
readonly confirm: "confirm";
readonly revoke: "revoke";
readonly tokens: "tokens";
readonly again: "again";
};
export const events = {
enrolmentIssued: "enrolment-issued",
nodeEnrolled: "node-enrolled",
enrolmentRefused: "enrolment-refused",
enrolmentRevoked: "enrolment-revoked",
enrolmentExpired: "enrolment-expired",
} as const;
export declare const events: {
readonly enrolmentIssued: "enrolment-issued";
readonly nodeEnrolled: "node-enrolled";
readonly enrolmentRefused: "enrolment-refused";
readonly enrolmentRevoked: "enrolment-revoked";
readonly enrolmentExpired: "enrolment-expired";
};
export const family = { name: "mesh-node-enroller.events", maxAgeDays: 7 } as const;
export declare const family: { readonly name: "mesh-node-enroller.events"; readonly maxAgeDays: 7 };
export const enrolmentIssuedSubject = "mesh.seat.mesh-node-enroller.event.enrolment-issued";
export declare const enrolmentIssuedSubject: "mesh.seat.mesh-node-enroller.event.enrolment-issued";
export const nodeEnrolledSubject = "mesh.seat.mesh-node-enroller.event.node-enrolled";
export declare const nodeEnrolledSubject: "mesh.seat.mesh-node-enroller.event.node-enrolled";
export const enrolmentRefusedSubject = "mesh.seat.mesh-node-enroller.event.enrolment-refused";
export declare const enrolmentRefusedSubject: "mesh.seat.mesh-node-enroller.event.enrolment-refused";
export const enrolmentRevokedSubject = "mesh.seat.mesh-node-enroller.event.enrolment-revoked";
export declare const enrolmentRevokedSubject: "mesh.seat.mesh-node-enroller.event.enrolment-revoked";
export const enrolmentExpiredSubject = "mesh.seat.mesh-node-enroller.event.enrolment-expired";
export declare const enrolmentExpiredSubject: "mesh.seat.mesh-node-enroller.event.enrolment-expired";
export const states = {
enrolments: "enrolments",
} as const;
export declare const states: {
readonly enrolments: "enrolments";
};
/** The key of one value of the state enrolments under the form "node.<node>". */
export function enrolmentsByNodeNodeKey(node: string): string {
return "node." + node;
}
export declare function enrolmentsByNodeNodeKey(node: string): string;
/** The parts of a key of the form "node.<node>", or undefined for a key of another form. */
export function parseEnrolmentsByNodeNodeKey(_key: string): { node: string } | undefined {
let _rest = _key;
if (!_rest.startsWith("node.")) return undefined;
_rest = _rest.slice(5);
if (_rest === "") return undefined;
const node = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { node };
}
export declare function parseEnrolmentsByNodeNodeKey(_key: string): { node: string } | undefined;
/** The key of one value of the state enrolments under the form "address.<address>". */
export function enrolmentsByAddressAddressKey(address: string): string {
return "address." + address;
}
export declare function enrolmentsByAddressAddressKey(address: string): string;
/** The parts of a key of the form "address.<address>", or undefined for a key of another form. */
export function parseEnrolmentsByAddressAddressKey(_key: string): { address: string } | undefined {
let _rest = _key;
if (!_rest.startsWith("address.")) return undefined;
_rest = _rest.slice(8);
if (_rest === "") return undefined;
const address = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { address };
}
export declare function parseEnrolmentsByAddressAddressKey(_key: string): { address: string } | undefined;
/** one open enrolment */
export interface Enrolment {
@@ -0,0 +1,73 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// The contract of the seat "mesh-node-enroller", defined whole (seats/mesh-node-enroller/seat.json): The seat that enrols a new machine on the operator's Approve and a one-time token (ADR 0587). Renamed from mesh-enrolment (ADR 0634 §9).
export const seat = "mesh-node-enroller";
export const verbs = {
issue: "issue",
redeem: "redeem",
confirm: "confirm",
revoke: "revoke",
tokens: "tokens",
again: "again",
};
export const events = {
enrolmentIssued: "enrolment-issued",
nodeEnrolled: "node-enrolled",
enrolmentRefused: "enrolment-refused",
enrolmentRevoked: "enrolment-revoked",
enrolmentExpired: "enrolment-expired",
};
export const family = { name: "mesh-node-enroller.events", maxAgeDays: 7 };
export const enrolmentIssuedSubject = "mesh.seat.mesh-node-enroller.event.enrolment-issued";
export const nodeEnrolledSubject = "mesh.seat.mesh-node-enroller.event.node-enrolled";
export const enrolmentRefusedSubject = "mesh.seat.mesh-node-enroller.event.enrolment-refused";
export const enrolmentRevokedSubject = "mesh.seat.mesh-node-enroller.event.enrolment-revoked";
export const enrolmentExpiredSubject = "mesh.seat.mesh-node-enroller.event.enrolment-expired";
export const states = {
enrolments: "enrolments",
};
/** The key of one value of the state enrolments under the form "node.<node>". */
export function enrolmentsByNodeNodeKey(node) {
return "node." + node;
}
/** The parts of a key of the form "node.<node>", or undefined for a key of another form. */
export function parseEnrolmentsByNodeNodeKey(_key) {
let _rest = _key;
if (!_rest.startsWith("node.")) return undefined;
_rest = _rest.slice(5);
if (_rest === "") return undefined;
const node = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { node };
}
/** The key of one value of the state enrolments under the form "address.<address>". */
export function enrolmentsByAddressAddressKey(address) {
return "address." + address;
}
/** The parts of a key of the form "address.<address>", or undefined for a key of another form. */
export function parseEnrolmentsByAddressAddressKey(_key) {
let _rest = _key;
if (!_rest.startsWith("address.")) return undefined;
_rest = _rest.slice(8);
if (_rest === "") return undefined;
const address = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { address };
}
@@ -1,9 +1,9 @@
{
"lockfileVersion": 3,
"name": "@novox/mesh-identity-and-access-contracts-mesh-node-enroller",
"name": "@novox/mesh-contracts-identity-and-access-mesh-node-enroller",
"packages": {
"": {
"name": "@novox/mesh-identity-and-access-contracts-mesh-node-enroller",
"name": "@novox/mesh-contracts-identity-and-access-mesh-node-enroller",
"version": "0.1.0"
}
},
@@ -1,13 +1,18 @@
{
"description": "The contract of the seat mesh-node-enroller, generated from its definition.",
"exports": {
".": "./src/index.ts"
".": {
"default": "./index.js",
"types": "./index.d.ts"
}
},
"files": [
"src"
"index.js",
"index.d.ts",
"parts"
],
"name": "@novox/mesh-identity-and-access-contracts-mesh-node-enroller",
"name": "@novox/mesh-contracts-identity-and-access-mesh-node-enroller",
"type": "module",
"types": "./src/index.ts",
"types": "./index.d.ts",
"version": "0.1.0"
}
@@ -1,12 +0,0 @@
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"noEmit": true,
"strict": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*.ts"]
}
@@ -2,131 +2,85 @@
// The contract of the seat "mesh-vault", defined whole (seats/mesh-vault/seat.json): The mesh's secrets. accept and move-asks, which no holder served and nothing called, are left out (ADR 0620 §3). The vault's own events stay under its own subjects (ADR 0620 §2).
export const seat = "mesh-vault";
export declare const seat: "mesh-vault";
export const verbs = {
get: "get",
secretAsk: "secret-ask",
issued: "issued",
rotate: "rotate",
moveIn: "move-in",
nodeKey: "node-key",
own: "own",
issueAccount: "issue-account",
sign: "sign",
enrolmentToken: "enrolment-token",
nodeAccount: "node-account",
rotateNode: "rotate-node",
nodeAccountConfirm: "node-account-confirm",
abandon: "abandon",
retire: "retire",
} as const;
export declare const verbs: {
readonly get: "get";
readonly secretAsk: "secret-ask";
readonly issued: "issued";
readonly rotate: "rotate";
readonly moveIn: "move-in";
readonly nodeKey: "node-key";
readonly own: "own";
readonly issueAccount: "issue-account";
readonly sign: "sign";
readonly enrolmentToken: "enrolment-token";
readonly nodeAccount: "node-account";
readonly rotateNode: "rotate-node";
readonly nodeAccountConfirm: "node-account-confirm";
readonly abandon: "abandon";
readonly retire: "retire";
readonly licencePut: "licence-put";
};
export const holderEvents = {
provisioned: "provisioned",
rotated: "rotated",
secretChanged: "secret-changed",
accountHashed: "account-hashed",
ownReplaced: "own-replaced",
accountIssued: "account-issued",
signed: "signed",
rotationBegun: "rotation-begun",
nodeAccountReady: "node-account-ready",
rotationDone: "rotation-done",
ownRetired: "own-retired",
} as const;
export declare const holderEvents: {
readonly provisioned: "provisioned";
readonly rotated: "rotated";
readonly secretChanged: "secret-changed";
readonly accountHashed: "account-hashed";
readonly ownReplaced: "own-replaced";
readonly accountIssued: "account-issued";
readonly signed: "signed";
readonly rotationBegun: "rotation-begun";
readonly nodeAccountReady: "node-account-ready";
readonly rotationDone: "rotation-done";
readonly ownRetired: "own-retired";
};
export function provisionedHolderSubject(holder: string): string {
return "mesh.mod." + holder + ".event.provisioned";
}
export declare function provisionedHolderSubject(holder: string): string;
export function rotatedHolderSubject(holder: string): string {
return "mesh.mod." + holder + ".event.rotated";
}
export declare function rotatedHolderSubject(holder: string): string;
export function secretChangedHolderSubject(holder: string): string {
return "mesh.mod." + holder + ".event.secret-changed";
}
export declare function secretChangedHolderSubject(holder: string): string;
export function accountHashedHolderSubject(holder: string): string {
return "mesh.mod." + holder + ".event.account-hashed";
}
export declare function accountHashedHolderSubject(holder: string): string;
export function ownReplacedHolderSubject(holder: string): string {
return "mesh.mod." + holder + ".event.own-replaced";
}
export declare function ownReplacedHolderSubject(holder: string): string;
export function accountIssuedHolderSubject(holder: string): string {
return "mesh.mod." + holder + ".event.account-issued";
}
export declare function accountIssuedHolderSubject(holder: string): string;
export function signedHolderSubject(holder: string): string {
return "mesh.mod." + holder + ".event.signed";
}
export declare function signedHolderSubject(holder: string): string;
export function rotationBegunHolderSubject(holder: string): string {
return "mesh.mod." + holder + ".event.rotation-begun";
}
export declare function rotationBegunHolderSubject(holder: string): string;
export function nodeAccountReadyHolderSubject(holder: string): string {
return "mesh.mod." + holder + ".event.node-account-ready";
}
export declare function nodeAccountReadyHolderSubject(holder: string): string;
export function rotationDoneHolderSubject(holder: string): string {
return "mesh.mod." + holder + ".event.rotation-done";
}
export declare function rotationDoneHolderSubject(holder: string): string;
export function ownRetiredHolderSubject(holder: string): string {
return "mesh.mod." + holder + ".event.own-retired";
}
export declare function ownRetiredHolderSubject(holder: string): string;
export const states = {
signers: "signers",
nodeLogins: "node-logins",
} as const;
export declare const states: {
readonly signers: "signers";
readonly nodeLogins: "node-logins";
};
/** The key of one value of the state signers under the form "key". */
export function signersByKeyKey(): string {
return "key";
}
export declare function signersByKeyKey(): string;
/** The parts of a key of the form "key", or undefined for a key of another form. */
export function parseSignersByKeyKey(_key: string): { } | undefined {
let _rest = _key;
if (!_rest.startsWith("key")) return undefined;
_rest = _rest.slice(3);
if (_rest !== "") return undefined;
return { };
}
export declare function parseSignersByKeyKey(_key: string): { } | undefined;
/** The key of one value of the state signers under the form "authority". */
export function signersByAuthorityKey(): string {
return "authority";
}
export declare function signersByAuthorityKey(): string;
/** The parts of a key of the form "authority", or undefined for a key of another form. */
export function parseSignersByAuthorityKey(_key: string): { } | undefined {
let _rest = _key;
if (!_rest.startsWith("authority")) return undefined;
_rest = _rest.slice(9);
if (_rest !== "") return undefined;
return { };
}
export declare function parseSignersByAuthorityKey(_key: string): { } | undefined;
/** The key of one value of the state node-logins under the form "<node>". */
export function nodeLoginsByNodeKey(node: string): string {
return node;
}
export declare function nodeLoginsByNodeKey(node: string): string;
/** The parts of a key of the form "<node>", or undefined for a key of another form. */
export function parseNodeLoginsByNodeKey(_key: string): { node: string } | undefined {
let _rest = _key;
if (_rest === "") return undefined;
const node = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { node };
}
export declare function parseNodeLoginsByNodeKey(_key: string): { node: string } | undefined;
/** is what get takes. */
export interface GetInput {
@@ -416,6 +370,23 @@ export interface RetireAnswer {
"retired": boolean;
}
/** is what licence-put takes. */
export interface LicencePutInput {
/** the second step: the call the first step answered */
"call"?: string;
/** the first step: the licence's generation */
"generation"?: number;
/** the first step: the licence's key */
"licence"?: string;
/** the first step: grant or access */
"part"?: string;
/** the second step: the value sealed to the call's key — never the value */
"sealed"?: string;
}
/** is what licence-put answers. */
export type LicencePutAnswer = Record<string, unknown>;
/** is the body of the holder's event signed. */
export interface SignedHolderEvent {
/** when it was signed, RFC 3339 */
@@ -0,0 +1,131 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// The contract of the seat "mesh-vault", defined whole (seats/mesh-vault/seat.json): The mesh's secrets. accept and move-asks, which no holder served and nothing called, are left out (ADR 0620 §3). The vault's own events stay under its own subjects (ADR 0620 §2).
export const seat = "mesh-vault";
export const verbs = {
get: "get",
secretAsk: "secret-ask",
issued: "issued",
rotate: "rotate",
moveIn: "move-in",
nodeKey: "node-key",
own: "own",
issueAccount: "issue-account",
sign: "sign",
enrolmentToken: "enrolment-token",
nodeAccount: "node-account",
rotateNode: "rotate-node",
nodeAccountConfirm: "node-account-confirm",
abandon: "abandon",
retire: "retire",
licencePut: "licence-put",
};
export const holderEvents = {
provisioned: "provisioned",
rotated: "rotated",
secretChanged: "secret-changed",
accountHashed: "account-hashed",
ownReplaced: "own-replaced",
accountIssued: "account-issued",
signed: "signed",
rotationBegun: "rotation-begun",
nodeAccountReady: "node-account-ready",
rotationDone: "rotation-done",
ownRetired: "own-retired",
};
export function provisionedHolderSubject(holder) {
return "mesh.mod." + holder + ".event.provisioned";
}
export function rotatedHolderSubject(holder) {
return "mesh.mod." + holder + ".event.rotated";
}
export function secretChangedHolderSubject(holder) {
return "mesh.mod." + holder + ".event.secret-changed";
}
export function accountHashedHolderSubject(holder) {
return "mesh.mod." + holder + ".event.account-hashed";
}
export function ownReplacedHolderSubject(holder) {
return "mesh.mod." + holder + ".event.own-replaced";
}
export function accountIssuedHolderSubject(holder) {
return "mesh.mod." + holder + ".event.account-issued";
}
export function signedHolderSubject(holder) {
return "mesh.mod." + holder + ".event.signed";
}
export function rotationBegunHolderSubject(holder) {
return "mesh.mod." + holder + ".event.rotation-begun";
}
export function nodeAccountReadyHolderSubject(holder) {
return "mesh.mod." + holder + ".event.node-account-ready";
}
export function rotationDoneHolderSubject(holder) {
return "mesh.mod." + holder + ".event.rotation-done";
}
export function ownRetiredHolderSubject(holder) {
return "mesh.mod." + holder + ".event.own-retired";
}
export const states = {
signers: "signers",
nodeLogins: "node-logins",
};
/** The key of one value of the state signers under the form "key". */
export function signersByKeyKey() {
return "key";
}
/** The parts of a key of the form "key", or undefined for a key of another form. */
export function parseSignersByKeyKey(_key) {
let _rest = _key;
if (!_rest.startsWith("key")) return undefined;
_rest = _rest.slice(3);
if (_rest !== "") return undefined;
return { };
}
/** The key of one value of the state signers under the form "authority". */
export function signersByAuthorityKey() {
return "authority";
}
/** The parts of a key of the form "authority", or undefined for a key of another form. */
export function parseSignersByAuthorityKey(_key) {
let _rest = _key;
if (!_rest.startsWith("authority")) return undefined;
_rest = _rest.slice(9);
if (_rest !== "") return undefined;
return { };
}
/** The key of one value of the state node-logins under the form "<node>". */
export function nodeLoginsByNodeKey(node) {
return node;
}
/** The parts of a key of the form "<node>", or undefined for a key of another form. */
export function parseNodeLoginsByNodeKey(_key) {
let _rest = _key;
if (_rest === "") return undefined;
const node = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { node };
}
+2 -2
View File
@@ -1,9 +1,9 @@
{
"lockfileVersion": 3,
"name": "@novox/mesh-identity-and-access-contracts-mesh-vault",
"name": "@novox/mesh-contracts-identity-and-access-mesh-vault",
"packages": {
"": {
"name": "@novox/mesh-identity-and-access-contracts-mesh-vault",
"name": "@novox/mesh-contracts-identity-and-access-mesh-vault",
"version": "0.1.0"
}
},
@@ -1,13 +1,18 @@
{
"description": "The contract of the seat mesh-vault, generated from its definition.",
"exports": {
".": "./src/index.ts"
".": {
"default": "./index.js",
"types": "./index.d.ts"
}
},
"files": [
"src"
"index.js",
"index.d.ts",
"parts"
],
"name": "@novox/mesh-identity-and-access-contracts-mesh-vault",
"name": "@novox/mesh-contracts-identity-and-access-mesh-vault",
"type": "module",
"types": "./src/index.ts",
"types": "./index.d.ts",
"version": "0.1.0"
}
@@ -1,12 +0,0 @@
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"noEmit": true,
"strict": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*.ts"]
}
+22 -15
View File
@@ -1,6 +1,6 @@
{
"module": "mesh-contracts",
"version": "1",
"version": "0.1",
"slug": "contracts",
"build": {
"artifacts": [
@@ -10,8 +10,7 @@
"language": "go",
"paths": [
"go/clients/meshconfigclient"
],
"series": "0.1"
]
},
{
"name": "go-nodeengineclient",
@@ -19,8 +18,7 @@
"language": "go",
"paths": [
"go/clients/nodeengineclient"
],
"series": "0.1"
]
},
{
"name": "go-meshbroker",
@@ -29,7 +27,15 @@
"paths": [
"go/seats/meshbroker"
],
"series": "0.1",
"generated-from": "."
},
{
"name": "go-meshrecovery",
"kind": "package",
"language": "go",
"paths": [
"go/seats/meshrecovery"
],
"generated-from": "."
},
{
@@ -39,7 +45,6 @@
"paths": [
"go/seats/meshconfig"
],
"series": "0.1",
"generated-from": "."
},
{
@@ -49,7 +54,6 @@
"paths": [
"go/seats/nodeengine"
],
"series": "0.1",
"generated-from": "."
},
{
@@ -59,7 +63,15 @@
"paths": [
"ts/seats/meshbroker"
],
"series": "0.1",
"generated-from": "."
},
{
"name": "ts-meshrecovery",
"kind": "package",
"language": "typescript",
"paths": [
"ts/seats/meshrecovery"
],
"generated-from": "."
},
{
@@ -69,7 +81,6 @@
"paths": [
"ts/seats/meshconfig"
],
"series": "0.1",
"generated-from": "."
},
{
@@ -79,7 +90,6 @@
"paths": [
"ts/seats/nodeengine"
],
"series": "0.1",
"generated-from": "."
},
{
@@ -89,7 +99,6 @@
"paths": [
"go/seats/meshmoduleassigner"
],
"series": "0.1",
"generated-from": "."
},
{
@@ -98,8 +107,7 @@
"language": "go",
"paths": [
"go/clients/meshmoduleassignerclient"
],
"series": "0.1"
]
},
{
"name": "ts-meshmoduleassigner",
@@ -108,7 +116,6 @@
"paths": [
"ts/seats/meshmoduleassigner"
],
"series": "0.1",
"generated-from": "."
}
]
@@ -13,12 +13,13 @@ import (
"errors"
"fmt"
"regexp"
"sort"
"strconv"
"strings"
"time"
seat "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
"git.novox.be/novox/mesh-sdk/go/approval"
"git.novox.be/novox/mesh-sdk/go/operatorask"
)
// The levels an option is answered at: how much proof its answer needs (novox/hq ADR 0234 §8, the glossary's
@@ -57,35 +58,11 @@ const (
OutcomeRefused = "refused" // it was never shown: Words says why
)
// An Act is what an option binds: named fields, each a string — the verb, the machine, the level, and each
// argument under a name of its own ("arg.delivery"). Flat on purpose: its digest is over these names and
// values alone, never over how a language happens to encode a struct.
type Act map[string]string
// An Act is what an option binds: mesh-sdk's operatorask.Act, re-exported (design 47 G lead answers A-198, A-219).
type Act = operatorask.Act
// ActDigest is the digest an asker puts in an option's Binds: SHA-256 over the act's canonical encoding
// (canonical), written "sha256:<hex>". The same names and values give the same digest in any language, whatever
// order they were set in; a field renamed, added or emptied gives another.
func ActDigest(act Act) (string, error) {
if len(act) == 0 {
return "", fmt.Errorf("the act cannot be digested: it names nothing")
}
keys := make([]string, 0, len(act))
for k := range act {
if k == "" {
return "", fmt.Errorf("the act cannot be digested: a field has no name")
}
keys = append(keys, k)
}
sort.Strings(keys)
var b strings.Builder
b.WriteString("novox.act.v1\n")
for _, k := range keys {
canonical(&b, k)
canonical(&b, act[k])
}
sum := sha256.Sum256([]byte(b.String()))
return "sha256:" + hex.EncodeToString(sum[:]), nil
}
// ActDigest is the digest an asker puts in an option's Binds: mesh-sdk's operatorask.ActDigest, re-exported.
func ActDigest(act Act) (string, error) { return operatorask.ActDigest(act) }
// canonical writes one value as its length in bytes, a colon, the bytes and a newline: no value can be read
// as another's end or start, so two different sequences of values never encode the same.
@@ -202,7 +179,7 @@ const (
MostOpen = 3
ApproveLasts = 24 * time.Hour
DestroyLasts = 10 * time.Minute
HeadlineLength = 60
HeadlineLength = approval.HeadlineLength
LabelLength = 24
)
@@ -10,6 +10,7 @@ import (
"time"
seat "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
"git.novox.be/novox/mesh-sdk/go/operatorask"
)
var now = time.Date(2026, 10, 8, 14, 0, 0, 0, time.UTC)
@@ -189,6 +190,11 @@ func TestDigestsAreCanonicalOverNamedFields(t *testing.T) {
Digest(gold) != "sha256:997af29a80663c5eb7d9dd38fc029c4a15fd726220b25e3c7cdc54d5a60bbbae" {
t.Errorf("the digests changed with the move: %s, %s", Digest(held()), Digest(gold))
}
// The act is mesh-sdk's, re-exported (A-198, A-219): one form, so the seat server's gate digests as an asker does.
var shared operatorask.Act = Act{"verb": "release", "arg.delivery": "hq"}
if d, _ := operatorask.ActDigest(shared); d == "" {
t.Error("mesh-sdk's digest of the act is empty")
}
a1, _ := ActDigest(Act{"verb": "release", "arg.delivery": "hq"})
b := Act{}
b["arg.delivery"] = "hq"
@@ -19,6 +19,7 @@ import (
seat "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/approval"
)
// Client asks as one module.
@@ -27,6 +28,9 @@ type Client struct {
Module string
// State is the module's own state the asks are kept in.
State Store
// KeyPrefix is put before every key of State the client writes and reads; empty for every asker today, so
// today's keys stay (design 46 milestone 7 §10). The router's record Where reads is never prefixed.
KeyPrefix string
// Now is the clock; nil is time.Now.
Now func() time.Time
// Publish, Record and Subscribe reach the bus; nil is the stdio SDK's, through the module's runtime.
@@ -54,16 +58,12 @@ func (c *Client) now() time.Time {
return time.Now()
}
// Kept is one ask as the module keeps it.
type Kept struct {
Ask seat.Ask `json:"ask"`
Asked time.Time `json:"asked"`
Acted bool `json:"acted,omitempty"`
Ended string `json:"ended,omitempty"`
Answer *seat.Warrant `json:"answer,omitempty"`
}
// Kept is one ask as the module keeps it: mesh-sdk's go/approval's form (design 47 G lead answer A-228) over the generated
// contract's ask and warrant. An asker that asks for a call keeps beside it the act the ask binds, the call's whole
// arguments, and whether the act's run was recorded in the hand-act log (design 46 7-approval-mark §13).
type Kept = approval.Kept[seat.Ask, seat.Warrant]
func key(id string) string { return "ask." + id }
func (c *Client) key(id string) string { return c.KeyPrefix + "ask." + id }
// Ask checks an ask, keeps it, and publishes it under the module's own name. An ask with an id already kept
// is refused: a new question is a new id.
@@ -71,7 +71,7 @@ func (c *Client) Ask(a seat.Ask) error {
if err := Check(a, c.now()); err != nil {
return err
}
if _, err := c.State.Create(key(a.ID), Kept{Ask: a, Asked: c.now()}); err != nil {
if _, err := c.State.Create(c.key(a.ID), Kept{Ask: a, Asked: c.now()}); err != nil {
if errors.Is(err, stdio.ErrChanged) {
return fmt.Errorf("an ask %s was already made: a new question is a new id", a.ID)
}
@@ -103,10 +103,7 @@ func (c *Client) Where(id string) (state string, w *seat.Warrant, err error) {
if err != nil || e == nil {
return "", nil, err
}
var rec struct {
State string `json:"state"`
Warrant *seat.Warrant `json:"warrant"`
}
var rec seat.AsksByAskerIDValue
if err := json.Unmarshal(e.Value, &rec); err != nil {
return "", nil, fmt.Errorf("the router's record of %s cannot be read: %w", id, err)
}
@@ -130,7 +127,7 @@ func (c *Client) Take(w seat.Warrant, act func(seat.Option, seat.Warrant) error)
if w.Asker != c.Module {
return Refused, fmt.Errorf("a warrant for %s reached %s", w.Asker, c.Module)
}
e, err := c.State.Get(key(w.Ask))
e, err := c.State.Get(c.key(w.Ask))
if err != nil {
return "", err
}
@@ -147,9 +144,13 @@ func (c *Client) Take(w seat.Warrant, act func(seat.Option, seat.Warrant) error)
if w.Outcome != OutcomeChosen {
k.Ended = w.Outcome
k.Answer = &w
if _, err := c.State.Update(key(w.Ask), k, e.Revision); err != nil && !errors.Is(err, stdio.ErrChanged) {
if _, err := c.State.Update(c.key(w.Ask), k, e.Revision); err != nil && !errors.Is(err, stdio.ErrChanged) {
return "", err
}
if w.Outcome == OutcomeRefused {
// The router never took the ask (design 47 G 570): its asker's request ends with the router's words.
return Refused, fmt.Errorf("the ask %s was refused: %s", w.Ask, w.Words)
}
return Recorded, nil
}
o, err := For(w, c.Module, k.Ask)
@@ -158,7 +159,7 @@ func (c *Client) Take(w seat.Warrant, act func(seat.Option, seat.Warrant) error)
}
// Marked before acting: of two deliveries, or two instances, only the one whose write stands acts.
k.Acted, k.Ended, k.Answer = true, OutcomeChosen, &w
if _, err := c.State.Update(key(w.Ask), k, e.Revision); err != nil {
if _, err := c.State.Update(c.key(w.Ask), k, e.Revision); err != nil {
if errors.Is(err, stdio.ErrChanged) {
return Done, nil
}
@@ -2,12 +2,14 @@ package operatorchannelclient
import (
"encoding/json"
"errors"
"strings"
"testing"
"time"
seat "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/approval"
"git.novox.be/novox/mesh-sdk/go/process"
)
@@ -87,6 +89,51 @@ func TestAnAskIsKeptThenPublishedUnderTheModulesOwnName(t *testing.T) {
if err := c.Ask(bad); err == nil {
t.Error("an ask the contract refuses was published")
}
t.Run("AKeyPrefixIsPutBeforeEveryKeyOfTheClientsOwnStateAndNotBeforeWhere", func(t *testing.T) {
for _, tc := range []struct{ prefix, key string }{{"n1.", "n1.ask.d-1"}, {"", "ask.d-1"}} {
c, _ := client()
store := c.State.(*mem)
c.KeyPrefix = tc.prefix
var asked string
c.Record = func(k string) (*stdio.StateEntry, error) { asked = k; return nil, nil }
if err := c.Ask(askedHeld()); err != nil {
t.Fatal(err)
}
if _, ok := store.vals[tc.key]; len(store.vals) != 1 || !ok {
t.Fatalf("prefix %q: keys written %v, want %s", tc.prefix, store.vals, tc.key)
}
// Design 46 7-approval-mark §13: the act and the call's arguments kept beside the ask stay as Take marks it.
e, _ := store.Get(tc.key)
var k Kept
_ = json.Unmarshal(e.Value, &k)
k.Act, k.Arguments = releaseHQ, json.RawMessage(`{"delivery":"hq"}`)
if _, err := store.Update(tc.key, k, e.Revision); err != nil {
t.Fatal(err)
}
if h, err := c.Take(askedWarrant(), func(seat.Option, seat.Warrant) error { return nil }); h != Acted || err != nil {
t.Fatalf("prefix %q: the warrant was not read from %s: %s %v", tc.prefix, tc.key, h, err)
}
raw := string(store.vals[tc.key])
if !strings.Contains(raw, `"act":{"delivery":"hq","verb":"release"}`) || !strings.Contains(raw, `"arguments":{"delivery":"hq"}`) || strings.Contains(raw, `"recorded"`) {
t.Errorf("prefix %q: the kept ask after Take is %s", tc.prefix, raw)
}
if _, _, err := c.Where("an-asker.d-1"); err != nil || asked != "an-asker.d-1" {
t.Errorf("prefix %q: Where read %q", tc.prefix, asked)
}
}
})
// Design 47 G §700, A-91: Where reads the router's record as the contract's typed value, its warrant included.
t.Run("WhereReadsTheRecordsWarrantTyped", func(t *testing.T) {
c, _ := client()
rec := seat.AsksByAskerIDValue{Key: "an-asker.d-1", Asker: "an-asker", State: "chosen",
Warrant: &seat.Warrant{Ask: "d-1", Asker: "an-asker", Outcome: seat.WarrantOutcomeChosen, Option: "ok"}}
raw, _ := json.Marshal(rec)
c.Record = func(string) (*stdio.StateEntry, error) { return &stdio.StateEntry{Value: raw}, nil }
state, w, err := c.Where("d-1")
if err != nil || state != "chosen" || w == nil || w.Option != "ok" {
t.Fatalf("Where = %q, %+v, %v; want chosen and the record's warrant", state, w, err)
}
})
}
func TestAWarrantIsActedOnOnceAndOnlyForItsOwnAsk(t *testing.T) {
@@ -125,6 +172,109 @@ func TestAWarrantIsActedOnOnceAndOnlyForItsOwnAsk(t *testing.T) {
if acted != 1 {
t.Errorf("acted %d times", acted)
}
// The gate's channel (design 47 G lead answers A-219, A-228): the gate's ask raised to the operator at the level approve,
// the router's record read in the gate's form with its warrant whole, and a warrant claimed once, only for the act its
// option binds.
t.Run("TheGateChannelTranslatesTheGatesForms", func(t *testing.T) {
st := &mem{vals: map[string]json.RawMessage{}, revs: map[string]uint64{}}
records := map[string]seat.AsksByAskerIDValue{}
g := &GateChannel{State: st, KeyPrefix: "n1.", Now: func() time.Time { return now },
Publish: func(module, subject string, body any, id string) error {
if subject != seat.AcceptSubjectAsk(module) {
t.Fatalf("published on %s", subject)
}
return nil
},
ReadRecord: func(module, id string) (*stdio.StateEntry, error) {
rec, ok := records[module+"."+id]
if !ok {
return nil, nil
}
raw, _ := json.Marshal(rec)
return &stdio.StateEntry{Value: raw}, nil
}}
digest, _ := ActDigest(releaseHQ)
a := approval.Ask{ID: "a1", About: digest, Headline: "Run wipe?", Explanation: "Wipes.", Expires: FormatTime(now.Add(time.Hour)),
OnExpiry: "nothing runs", Options: []approval.Option{{ID: "approve", Label: "Approve", Does: "runs", Binds: digest}}}
if err := g.Ask("shell", a); err != nil {
t.Fatal(err)
}
var k Kept
if e, _ := st.Get("n1.ask.a1"); e == nil || json.Unmarshal(e.Value, &k) != nil || k.Ask.Who != Operator || k.Ask.Options[0].Level != Approve {
t.Fatalf("kept %+v", k)
}
if rec, err := g.Record("shell", "a1"); rec != nil || err != nil {
t.Fatalf("a record not yet there: %+v %v", rec, err)
}
w := seat.Warrant{Ask: "a1", Asker: "shell", Outcome: OutcomeChosen, Option: "approve", Level: Approve, At: FormatTime(now),
AskDigest: Digest(k.Ask), Channel: "telegram", By: &seat.Person{Who: Operator, Kind: "telegram"}}
records["shell.a1"] = seat.AsksByAskerIDValue{Asker: "shell", State: "chosen", Opened: FormatTime(now), Warrant: &w}
rec, err := g.Record("shell", "a1")
if err != nil || rec == nil || rec.State != "chosen" || rec.Warrant == nil || rec.Warrant.Channel != "telegram" || rec.Warrant.Option != "approve" {
t.Fatalf("record %+v %v", rec, err)
}
if h, err := g.Claim("shell", *rec.Warrant, map[string]string{"verb": "other"}, func() { t.Fatal("ran another act") }); h != approval.Claimed || err == nil {
t.Fatalf("another act: %s %v", h, err)
}
delete(st.vals, "n1.ask.a1")
_ = g.Ask("shell", a)
runs := 0
for i := 0; i < 2; i++ {
h, err := g.Claim("shell", *rec.Warrant, releaseHQ, func() { runs++ })
if want := []approval.Claim{approval.Claimed, approval.ClaimDone}[i]; h != want || err != nil {
t.Fatalf("claim %d: %s %v", i, h, err)
}
}
if runs != 1 || g.Decided("shell") != seat.SubjectDecided("shell") {
t.Fatalf("runs %d", runs)
}
})
// The gate's channel over a process connection (design 47 G lead answers A-272, A-273): an ask and its cancel go out as
// accepted kinds of the seat operator-channel with the ask's id as the message id, the router's record is the get of
// `<module>.<id>` in the state asks of the seat's holder, and nothing else is reached: another subject, or a seat with no
// holder, is refused.
t.Run("TheGateChannelOverAConnectionAsksAndReadsOnlyThroughTheSeat", func(t *testing.T) {
type sent struct{ seat, kind, id string }
var out []sent
accept := func(s, kind string, _ any, opts ...stdio.EmitOptions) error {
out = append(out, sent{s, kind, opts[0].MessageID})
return nil
}
raw, _ := json.Marshal(seat.AsksByAskerIDValue{Asker: "shell", State: "open", Opened: FormatTime(now)})
vals := map[string]json.RawMessage{"messenger_holder.asks|shell.a1": raw, "other.asks|shell.a1": json.RawMessage(`{"state":"wrong"}`)}
read := func(r string) asksRead { return readOf{state: r, vals: vals} }
holder := func() (string, error) { return "messenger_holder", nil }
st := &mem{vals: map[string]json.RawMessage{}, revs: map[string]uint64{}}
g := gateChannelOver(accept, read, st, "n1.", holder)
g.Now = func() time.Time { return now }
digest, _ := ActDigest(releaseHQ)
a := approval.Ask{ID: "a1", About: digest, Headline: "Run wipe?", Explanation: "Wipes.", Expires: FormatTime(now.Add(time.Hour)),
OnExpiry: "nothing runs", Options: []approval.Option{{ID: "approve", Label: "Approve", Does: "runs", Binds: digest}}}
if err := g.Ask("shell", a); err != nil {
t.Fatal(err)
}
if err := g.Cancel("shell", "a1"); err != nil {
t.Fatal(err)
}
if len(out) != 2 || out[0] != (sent{seat.Seat, seat.AcceptAsk, "a1"}) || out[1] != (sent{seat.Seat, seat.AcceptCancel, "cancel.a1"}) {
t.Fatalf("sent %+v, want the ask and its cancel on the seat's accepts", out)
}
if rec, err := g.Record("shell", "a1"); err != nil || rec == nil || rec.State != "open" {
t.Fatalf("record %+v %v, want the one in the holder's state asks", rec, err)
}
if rec, err := g.Record("shell", "zz"); err != nil || rec != nil {
t.Fatalf("a record not there: %+v %v", rec, err)
}
if err := g.Publish("shell", "mesh.seat.operator-channel.accept.ask.other", nil, "x"); err == nil {
t.Fatal("an accept subject naming another caller was sent")
}
for _, c := range []func() (string, error){func() (string, error) { return "", nil }, func() (string, error) { return "", errors.New("unread") }} {
if _, err := gateChannelOver(accept, read, st, "n1.", c).Record("shell", "a1"); err == nil {
t.Fatal("a record was read with no holder of the seat")
}
}
})
}
func TestAnAskEndedWithoutAChoiceIsRecordedAndNothingDone(t *testing.T) {
@@ -138,4 +288,17 @@ func TestAnAskEndedWithoutAChoiceIsRecordedAndNothingDone(t *testing.T) {
if h, _ := c.Take(askedWarrant(), func(seat.Option, seat.Warrant) error { t.Fatal("acted after it ended"); return nil }); h != Done {
t.Errorf("%s", h)
}
t.Run("AnAskTheRouterRefusedEndsTheRequestWithItsWords", func(t *testing.T) {
c, _ := client()
_ = c.Ask(askedHeld())
w := askedWarrant()
w.Outcome, w.Option, w.By, w.Words = OutcomeRefused, "", nil, "its expiry passes the bound of its level"
h, err := c.Take(w, func(seat.Option, seat.Warrant) error { t.Fatal("acted"); return nil })
if h != Refused || err == nil || !strings.Contains(err.Error(), w.Words) {
t.Fatalf("%s %v, want refused with the router's words", h, err)
}
if h, _ := c.Take(askedWarrant(), func(seat.Option, seat.Warrant) error { t.Fatal("acted after it ended"); return nil }); h != Done {
t.Errorf("the refused ask was not closed: %s", h)
}
})
}
@@ -0,0 +1,90 @@
package operatorchannelclient
import (
"encoding/json"
"fmt"
"time"
seat "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/approval"
"git.novox.be/novox/mesh-sdk/go/operatorask"
)
// GateChannel is the operator channel as mesh-sdk's approval gate reaches it (design 47 G lead answers A-219, A-228): it
// translates the gate's own forms to and from the generated contract's, asking under the marked module's name through a
// Client whose asks are kept in the gate's state under KeyPrefix.
type GateChannel struct {
// State is the gate's state approvals; KeyPrefix is put before every key the client keeps there.
State Store
KeyPrefix string
Now func() time.Time
// Publish says an accept on the seat under module's name; ReadRecord reads the router's record `<module>.<id>` of the
// seat's state asks, both on the gate's holder's own account (design 47 G §700).
Publish func(module, subject string, body any, id string) error
ReadRecord func(module, id string) (*stdio.StateEntry, error)
}
var _ approval.Channel = (*GateChannel)(nil)
func (g *GateChannel) client(module string) *Client {
return &Client{Module: module, State: g.State, KeyPrefix: g.KeyPrefix, Now: g.Now,
Publish: func(subject string, body any, id string) error { return g.Publish(module, subject, body, id) },
Record: func(id string) (*stdio.StateEntry, error) { return g.ReadRecord(module, id) }}
}
// Ask raises the gate's ask to the operator, every option at the level approve.
func (g *GateChannel) Ask(module string, a approval.Ask) error {
ask := seat.Ask{ID: a.ID, About: a.About, Who: Operator, Headline: a.Headline, Explanation: a.Explanation,
Expires: a.Expires, OnExpiry: a.OnExpiry}
for _, o := range a.Options {
ask.Options = append(ask.Options, seat.Option{ID: o.ID, Label: o.Label, Does: o.Does, Level: Approve, Binds: o.Binds})
}
return g.client(module).Ask(ask)
}
// Record is the router's record of module's ask in the gate's form, nil while there is none.
func (g *GateChannel) Record(module, id string) (*approval.Record, error) {
e, err := g.ReadRecord(module, id)
if err != nil || e == nil {
return nil, err
}
var rec seat.AsksByAskerIDValue
if err := json.Unmarshal(e.Value, &rec); err != nil {
return nil, fmt.Errorf("the router's record of %s cannot be read: %w", id, err)
}
out := &approval.Record{State: rec.State, Answer: rec.Answer, Opened: rec.Opened, Expires: rec.Expires, OfferedOn: rec.OfferedOn}
if w := rec.Warrant; w != nil {
whole, err := json.Marshal(w)
if err != nil {
return nil, err
}
out.Warrant = &approval.Warrant{Ask: w.Ask, Asker: w.Asker, Option: w.Option, Channel: w.Channel, At: w.At, Whole: whole}
}
return out, nil
}
// Claim takes the warrant once with Take, holding the chosen option to act before run.
func (g *GateChannel) Claim(module string, w approval.Warrant, act operatorask.Act, run func()) (approval.Claim, error) {
var sw seat.Warrant
if err := json.Unmarshal(w.Whole, &sw); err != nil {
return approval.ClaimRefused, fmt.Errorf("the warrant for the ask %s cannot be read: %w", w.Ask, err)
}
h, err := g.client(module).Take(sw, func(o seat.Option, _ seat.Warrant) error {
if err := Performs(o, act); err != nil {
return err
}
run()
return nil
})
return approval.Claim(h), err
}
// Cancel takes module's ask back.
func (g *GateChannel) Cancel(module, id string) error { return g.client(module).Cancel(id) }
// Decided is the subject of the router's `decided` for module.
func (g *GateChannel) Decided(module string) string { return seat.SubjectDecided(module) }
// Seat is the seat the gate's asks are raised on.
func (g *GateChannel) Seat() string { return seat.Seat }
@@ -0,0 +1,51 @@
package operatorchannelclient
import (
"fmt"
seat "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/process"
)
// asksRead is a state of another module read by key: process.State is one.
type asksRead interface {
Get(key string) (*stdio.StateEntry, error)
}
// NewGateChannel is the operator channel as a process holder's gate reaches it over its own connection (design 47 G §677,
// §700; lead answers A-272, A-273): an ask and its cancel are sent on the seat operator-channel's accept subjects through
// conn's Accept, and the router's record is read by a get of the key `<module>.<id>` in the seat's state asks, whose bucket
// is formed from holder (the module the seat list names for the seat operator-channel) and the contract's StateAsks, on the
// process's own account. state keeps the asks, under keyPrefix (the gate's state approvals and its node).
func NewGateChannel(conn *process.Conn, state Store, keyPrefix string, holder func() (string, error)) *GateChannel {
return gateChannelOver(conn.Accept, func(read string) asksRead { return conn.Read(read) }, state, keyPrefix, holder)
}
// gateChannelOver is NewGateChannel over the two things it reaches a connection through.
func gateChannelOver(accept func(seat, kind string, body any, opts ...stdio.EmitOptions) error, read func(read string) asksRead,
state Store, keyPrefix string, holder func() (string, error)) *GateChannel {
return &GateChannel{State: state, KeyPrefix: keyPrefix,
Publish: func(module, subject string, body any, id string) error {
var kind string
switch subject {
case seat.AcceptSubjectAsk(module):
kind = seat.AcceptAsk
case seat.AcceptSubjectCancel(module):
kind = seat.AcceptCancel
default:
return fmt.Errorf("%s is no accept subject of the seat %s that %s may use", subject, seat.Seat, module)
}
return accept(seat.Seat, kind, body, stdio.EmitOptions{MessageID: id})
},
ReadRecord: func(module, id string) (*stdio.StateEntry, error) {
held, err := holder()
if err != nil {
return nil, fmt.Errorf("the router's record of %s cannot be read: %w", id, err)
}
if held == "" {
return nil, fmt.Errorf("the router's record of %s cannot be read: the seat list names no holder of the seat %s", id, seat.Seat)
}
return read(held + "." + seat.StateAsks).Get(seat.AsksByAskerIDKey(module, id))
}}
}
@@ -0,0 +1,19 @@
package operatorchannelclient
import (
"encoding/json"
stdio "git.novox.be/novox/mesh-sdk/go"
)
type readOf struct {
state string
vals map[string]json.RawMessage
}
func (r readOf) Get(key string) (*stdio.StateEntry, error) {
if v, ok := r.vals[r.state+"|"+key]; ok {
return &stdio.StateEntry{Key: key, Value: v}, nil
}
return nil, nil
}
@@ -15,11 +15,12 @@ import (
const Seat = "operator-channel"
const (
VerbOpen = "open"
VerbHistory = "history"
VerbNotify = "notify"
VerbTell = "tell"
VerbAsks = "asks"
VerbOpen = "open"
VerbHistory = "history"
VerbNotify = "notify"
VerbTell = "tell"
VerbAsks = "asks"
VerbAskAgain = "ask-again"
)
const (
@@ -34,7 +35,7 @@ const (
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbOpen, VerbHistory, VerbNotify, VerbTell, VerbAsks}
return []string{VerbOpen, VerbHistory, VerbNotify, VerbTell, VerbAsks, VerbAskAgain}
}
// Events is every event published on the seat's subject: a new copy each call.
@@ -388,6 +389,8 @@ type HistoryAnswer = map[string]any
type NotifyInput struct {
// it is over
Clear bool `json:"clear,omitempty"`
// send it on every channel's send, as a break-glass act is announced, not on the operator's chosen channel alone (design 47 G 514)
EveryChannel bool `json:"every-channel,omitempty"`
// one or two plain sentences
Explanation string `json:"explanation,omitempty"`
// plain words
@@ -427,10 +430,48 @@ type TellAnswer = map[string]any
// AsksInput is what asks takes.
type AsksInput struct {
// the most bytes of the asks in the answer; said when it cuts the answer short
Bound int64 `json:"bound,omitempty"`
// one ask, by its key (<asker>.<id>); none for the open asks
Key string `json:"key,omitempty"`
// only the asks opened at or after this time, RFC 3339
Since string `json:"since,omitempty"`
// open (open, held and held-back), ended or all; none is open when no key or since is given, else all
State string `json:"state,omitempty"`
}
// AsksAnswerAsksItem is a type of the contract.
type AsksAnswerAsksItem struct {
// when the ask was held back, RFC 3339; present while its state is held-back
HeldSince string `json:"held-since,omitempty"`
// <asker>.<id>
Key string `json:"key"`
// how the ask stands: open, held (no ready channel), held-back (kept open behind the asker's newer asks, ADR 0666 §12), or how it ended (answered, expired, cancelled)
State string `json:"state"`
}
// AsksAnswer is what asks answers.
type AsksAnswer = map[string]any
type AsksAnswer struct {
// each ask the router holds, as its state asks holds it
Asks []AsksAnswerAsksItem `json:"asks"`
// what the bound cut, and how to ask for more; empty when nothing was cut
Cut string `json:"cut,omitempty"`
// how many asks the arguments matched
Matched int64 `json:"matched,omitempty"`
}
// AskAgainInput is what ask-again takes.
type AskAgainInput struct {
// <asker>.<id> of the held-back ask
Key string `json:"key"`
}
// AskAgainAnswer is what ask-again answers.
type AskAgainAnswer struct {
// why it was not offered; set alone
Error string `json:"error,omitempty"`
State string `json:"state,omitempty"`
}
// AskAccept is the body of ask.
type AskAccept = Ask
@@ -485,16 +526,21 @@ type AsksByAskerIDValue struct {
Asker string `json:"asker"`
// its asker has been told how it ended
AskerTold bool `json:"asker_told,omitempty"`
// when it ended, RFC 3339; present once it ended, a refused ask's refusal time (design 47 G 570, 638)
At string `json:"at,omitempty"`
// when it ends unanswered, RFC 3339
Expires string `json:"expires"`
// its headline
Headline string `json:"headline"`
// when the ask was held back, RFC 3339; present while its state is held-back
HeldSince string `json:"held-since,omitempty"`
// <asker>.<id>
Key string `json:"key"`
// the channels it was offered on
OfferedOn []string `json:"offered_on,omitempty"`
// when it was opened, RFC 3339
Opened string `json:"opened"`
// how it stands: open, chosen, expired, cancelled, replaced or refused
State string `json:"state"`
// how it stands: open, held-back (kept open behind the asker's newer asks, ADR 0666 §12), chosen, expired, cancelled, replaced or refused
State string `json:"state"`
Warrant *Warrant `json:"warrant,omitempty"`
}

Some files were not shown because too many files have changed in this diff Show More