Compare commits

...
Author SHA1 Message Date
jschoubben 61f7a12f58 Playbook 07: rehearse the delivery system, a bus-shape sheet in the prepare, no stand-in tests, review against the live mesh (design 47 H2's delivery, 2026-11-22) 2026-11-22 13:58:04 +01:00
mesh-tools dfaabb6c77 Merge pull request 'Design 47 H: lead answer H-A-128 (nats_consumer_remove judges a module's durable by prefix)' (#795) from design/47-H1-answers-57 into main 2026-11-20 05:22:09 +00:00
jschoubben 00d6446fea Design 47 H: H-A-128, nats_consumer_remove judges a module's durable by prefix
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 06:21:49 +01:00
mesh-tools 1540d297b4 Merge pull request 'Design 47 H: lead answer H-A-127 (nats_consumer_remove refuses by durable name; why is the warrant)' (#794) from design/47-H1-answers-56 into main 2026-11-20 05:15:28 +00:00
jschoubben f3d57662c6 Design 47 H: H-A-127, nats_consumer_remove refuses by durable name; why is the warrant
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 06:15:13 +01:00
mesh-tools f1164f49ff Merge pull request 'Design 47 H: lead answer H-A-126 (the bus module's drop tools exist; H-A-121 (1) withdrawn)' (#793) from design/47-H1-answers-55 into main 2026-11-20 05:13:00 +00:00
jschoubben f0559b3a71 Design 47 H: H-A-126, the bus module's drop tools exist; H-A-121 (1) withdrawn
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 06:12:46 +01:00
mesh-tools d42bbc6138 Merge pull request 'Design 47 H: lead answer H-A-125 (the knowledge base's delivery block goes whole)' (#792) from design/47-H1-answers-54 into main 2026-11-20 04:54:45 +00:00
jschoubben 7c21fef8e8 Design 47 H: H-A-125, the knowledge base's delivery block goes whole
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:54:30 +01:00
mesh-tools 9b16d3fa07 Merge pull request 'Design 47 H: lead answer H-A-124 (the all form of indexer_pin_drop drops every pin)' (#791) from design/47-H1-answers-53 into main 2026-11-20 04:53:38 +00:00
jschoubben 53f72a6740 Design 47 H: H-A-124, the all form of indexer_pin_drop drops every pin
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:53:26 +01:00
mesh-tools ffcf21d5bb Merge pull request 'Design 47 H: lead answer H-A-123 (the all form of assigner_want_drop drops every want)' (#790) from design/47-H1-answers-52 into main 2026-11-20 04:53:06 +00:00
jschoubben a653f39e2e Design 47 H: H-A-123, the all form of assigner_want_drop drops every want
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:52:52 +01:00
mesh-tools 6d7217619f Merge pull request 'Design 47 H: lead answers H-A-121 (the clean state's drop tools) and H-A-122 (the mail reader's callers list goes)' (#789) from design/47-H1-answers-51 into main 2026-11-20 04:49:20 +00:00
jschoubben fbff9aa306 Design 47 H: H-A-121 corrected (module tools, not a seat verb); H-A-122 the mail reader's callers list goes
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:48:44 +01:00
jschoubben 198d44382a Design 47 H: H-A-121, the clean state's drop tools (mesh-broker.drop, consumer delete, all forms)
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:45:49 +01:00
mesh-tools 4bebb4c1ed Merge pull request 'Design 47 H: lead answer H-A-120 (the build seats' kinds take turns, A-440; H-A-8 corrected)' (#788) from design/47-H1-answers-50 into main 2026-11-20 04:29:59 +00:00
jschoubben 1fe45361c1 Design 47 H: H-A-120, the build seats' kinds take turns (A-440); H-A-8 corrected
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:29:33 +01:00
mesh-tools 3af51ed4a1 Merge pull request 'Design 47 H: lead answer H-A-119 (pipeline-ended's mover entry gains commit and widens; the teller)' (#787) from design/47-H1-answers-49 into main 2026-11-20 04:12:00 +00:00
jschoubben ef446d6d8b Design 47 H: H-A-119, pipeline-ended's mover entry gains commit and widens; the teller hears no record-opened
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:11:32 +01:00
mesh-tools 3176501000 Merge pull request 'Design 47 H: lead answer H-A-118 (the held take-in's value carries the event; later ones wait in order)' (#786) from design/47-H1-answers-48 into main 2026-11-20 04:06:38 +00:00
jschoubben 6ea3bcd416 Design 47 H: H-A-118, the held take-in's value carries the event; later ones wait behind in order
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:06:14 +01:00
mesh-tools 0afc44ea6f Merge pull request 'Design 47 H: lead answer H-A-117 (the check and recheck kinds stay in H1; the runs' input is mesh-wants')' (#785) from design/47-H1-answers-47 into main 2026-11-20 03:57:41 +00:00
jschoubben c06d4dd03a Design 47 H: H-A-117, the check and recheck kinds stay in H1; the runs' input is mesh-wants'
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:57:10 +01:00
mesh-tools 162c721f08 Merge pull request 'Design 47 H: lead answer H-A-116 (the builder's floor wakes on take-in.taken in H1)' (#784) from design/47-H1-answers-46 into main 2026-11-20 03:44:05 +00:00
jschoubben 508faf0cf6 Design 47 H: H-A-116, the builder's floor wakes on take-in.taken in H1
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:43:38 +01:00
mesh-tools 853b3ae819 Merge pull request 'Design 47 H: lead answers H-A-114 and H-A-115 (a held take-in is acknowledged and kept; code dependents by go.sum)' (#783) from design/47-H1-answers-45 into main 2026-11-20 03:42:21 +00:00
jschoubben b93bf48739 Design 47 H: H-A-114 a held take-in is acknowledged and kept in state held; H-A-115 code dependents by go.sum in H1
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:41:28 +01:00
mesh-tools 0cf71a5515 Merge pull request 'Design 47 H: lead answer H-A-113 (grants_why_refused stays; every account gets every seat's verbs)' (#782) from design/47-H1-answers-44 into main 2026-11-20 03:22:27 +00:00
jschoubben f599b76165 Design 47 H: H-A-113, grants_why_refused stays; every account gets every seat's verbs
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:22:01 +01:00
mesh-tools 3c2cd089e8 Merge pull request 'Design 47 H: lead answer H-A-112 (the composer drops its verdict branch and Case.Verdicts)' (#781) from design/47-H1-answers-43 into main 2026-11-20 03:17:42 +00:00
jschoubben 49f08c9e83 Design 47 H: H-A-112, the composer drops its verdict branch and Case.Verdicts
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:17:16 +01:00
mesh-tools 8c94adf744 Merge pull request 'Design 47 H: lead answer H-A-111 (the node-engine reads a taken module without a verdict)' (#780) from design/47-H1-answers-42 into main 2026-11-20 03:16:17 +00:00
jschoubben 307168a778 Design 47 H: H-A-111, the node-engine reads a taken module without a verdict
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:15:42 +01:00
mesh-tools 7319cc5e1b Merge pull request 'Design 47 H: lead answer H-A-110 (the node-engine asks entries again on catalog-revision)' (#779) from design/47-H1-answers-41 into main 2026-11-20 03:15:06 +00:00
jschoubben 6fde0ff09d Design 47 H: H-A-110, the node-engine asks entries again on catalog-revision
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:14:55 +01:00
mesh-tools 13be7087dc Merge pull request 'Design 47 H: lead answer H-A-109 (the view says a held take-in without naming modules)' (#778) from design/47-H1-answers-40 into main 2026-11-20 03:14:11 +00:00
jschoubben 3433db0efb Design 47 H: H-A-109, the view says a held take-in without naming modules
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:12:57 +01:00
mesh-tools 996cd3c391 Merge pull request 'Design 47 H: lead answer H-A-108 (the validate step's run, input, baseline and verdict)' (#777) from design/47-H1-answers-39 into main 2026-11-20 03:11:30 +00:00
jschoubben 38fdb88994 Design 47 H: H-A-108 in the glossary's word
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:10:58 +01:00
jschoubben 9c7fa01851 Design 47 H: H-A-108, the validate step's run, input, baseline and verdict
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:10:33 +01:00
mesh-tools 0f8c0812d9 Merge pull request 'Design 47 H: lead answer H-A-107 (the pipeline keeps the movers superseded out of it)' (#776) from design/47-H1-answers-38 into main 2026-11-20 03:08:57 +00:00
jschoubben fabb927f26 Design 47 H: H-A-107, the pipeline keeps the movers superseded out of it
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:08:33 +01:00
mesh-tools eea237e45b Merge pull request 'Design 47 H: lead answer H-A-106 (the queue's over-cap start, the approved pipeline, the findings' form)' (#775) from design/47-H1-answers-37 into main 2026-11-20 03:07:36 +00:00
jschoubben e428f47913 Design 47 H: H-A-106, the queue's over-cap start, the approved pipeline and the findings' form
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:06:46 +01:00
mesh-tools 2cc1da4357 Merge pull request 'Design 47 H: lead answer H-A-105 (indexer_take_in goes; the run candidate's check stays)' (#774) from design/47-H1-answers-36 into main 2026-11-20 03:00:30 +00:00
jschoubben a000df7dbe Design 47 H: H-A-105, indexer_take_in goes; the run candidate's check stays
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:59:44 +01:00
mesh-tools 91266f3007 Merge pull request 'Design 47 H: lead answer H-A-104 (the assigner's state engine-reads; RefusedCycle into the sdk)' (#773) from design/47-H1-answers-35 into main 2026-11-20 02:59:06 +00:00
jschoubben 0d18ad2daf Design 47 H: H-A-104, the assigner's state engine-reads; RefusedCycle into the sdk on the contracts branch
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:58:36 +01:00
mesh-tools 0cef3fc826 Merge pull request 'Design 47 H: lead answer H-A-103 (the indexer's derived state between take-ins)' (#772) from design/47-H1-answers-34 into main 2026-11-20 02:56:53 +00:00
jschoubben 50e6d16381 Design 47 H: H-A-103, the indexer's derived state between take-ins
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:56:12 +01:00
mesh-tools 4b4802df52 Merge pull request 'Design 47 H: lead answer H-A-102 (indexer_pending's answer form)' (#771) from design/47-H1-answers-33 into main 2026-11-20 02:53:33 +00:00
jschoubben c836029155 Design 47 H: H-A-102, indexer_pending's answer form
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:52:35 +01:00
mesh-tools 960cc77a7c Merge pull request 'Design 47 H: lead answer H-A-101 (the runner's hand verbs name the module; a not-asked step says its end)' (#770) from design/47-H1-answers-32 into main 2026-11-20 02:52:10 +00:00
jschoubben 69a8854835 Design 47 H: H-A-101, the runner's hand verbs name the module; a not-asked step says its end
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:51:31 +01:00
mesh-tools b59a5893dd Merge pull request 'Design 47 H: lead answers H-A-98 to H-A-100' (#769) from design/47-H1-answers-31 into main 2026-11-20 02:50:49 +00:00
jschoubben 62d60bf43d Design 47 H: H-A-99 the placement's build is the want's target; H-A-100 the forge module's merge-check removal
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:50:17 +01:00
jschoubben 922f7017b8 Design 47 H: H-A-98, an old-form event is refused by each handler's strict decode
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:49:56 +01:00
mesh-tools 0bebde8bfe Merge pull request 'Design 47 H: lead answer H-A-97 (a held take-in is kept in the indexer's state held)' (#768) from design/47-H1-answers-30 into main 2026-11-20 02:48:58 +00:00
jschoubben 55da6d1af7 Design 47 H: H-A-97, a held take-in is kept in the indexer's state held
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:48:31 +01:00
mesh-tools f6b2837e0a Merge pull request 'Design 47 H: lead answer H-A-96 (the queue's running keys)' (#767) from design/47-H1-answers-29 into main 2026-11-20 02:47:59 +00:00
jschoubben c55ea604d1 Design 47 H: H-A-96, the queue's running keys
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:47:33 +01:00
mesh-tools d17fa4efa7 Merge pull request 'Design 47 H: lead answer H-A-95 (a held want is not timed; Owed's ask and group go)' (#766) from design/47-H1-answers-28 into main 2026-11-20 02:46:19 +00:00
jschoubben 77b05c2381 Design 47 H: H-A-95, a held want is not timed; Owed's ask and group go
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:45:35 +01:00
mesh-tools 0cef71532a Merge pull request 'Design 47 H: lead answer H-A-93 (step-unread is one finding per unread step)' (#765) from design/47-H1-answers-27 into main 2026-11-20 02:42:34 +00:00
jschoubben 33208b3cd9 Design 47 H: H-A-94, the watchman's bus-state and take-in readers
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:42:26 +01:00
jschoubben d33b17351c Design 47 H: H-A-93, step-unread is one finding per unread step
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:41:50 +01:00
mesh-tools 8c0b04e33c Merge pull request 'Design 47 H: lead answer H-A-92 (a catalog revision carries its movers)' (#764) from design/47-H1-answers-26 into main 2026-11-20 02:38:42 +00:00
jschoubben c8fc134444 Design 47 H: H-A-92, a catalog revision carries its movers
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:38:20 +01:00
mesh-tools f3e205fa72 Merge pull request 'Design 47 H: lead answer H-A-91 (an adopted branch says start; delivery-waits goes; the owed act merge leaves)' (#763) from design/47-H1-answers-25 into main 2026-11-20 02:36:11 +00:00
jschoubben 7425b11b34 Design 47 H: H-A-91, an adopted branch says start; delivery-waits goes; the owed act merge leaves the contract
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:35:28 +01:00
mesh-tools 6cacd527e3 Merge pull request 'Design 47 H: lead answer H-A-90 (a named event consumer in mesh-sdk; bound on registration-changed)' (#762) from design/47-H1-answers-24 into main 2026-11-20 02:31:08 +00:00
jschoubben e95cc598a0 Design 47 H: H-A-90, NamedEventConsumer in mesh-sdk; a consumer bound on registration-changed
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:30:41 +01:00
mesh-tools 81e1964d0c Merge pull request 'Design 47 H: lead answer H-A-89 (the record's pipeline families)' (#761) from design/47-H1-answers-23 into main 2026-11-20 02:29:00 +00:00
jschoubben 287871724b Design 47 H: H-A-89, the record's pipeline families
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:28:34 +01:00
mesh-tools 2c6c7c03d3 Merge pull request 'Design 47 H: lead answer H-A-88 (StepRun gains asker)' (#760) from design/47-H1-answers-22 into main 2026-11-20 02:26:46 +00:00
jschoubben 1a25538c0a Design 47 H: H-A-88, StepRun gains asker
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:26:19 +01:00
mesh-tools 76cc85de24 Merge pull request 'Design 47 H: lead answer H-A-87 (the forge module's whole test is Go; the source key's escaping)' (#759) from design/47-H1-answers-21 into main 2026-11-20 02:25:33 +00:00
jschoubben 4dabb3015a Design 47 H: H-A-87, the forge module's whole test is Go; the source key's escaping
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:24:48 +01:00
mesh-tools e19d61a4b0 Merge pull request 'Design 47 H: lead answers H-A-85 and H-A-86 (bridge_heads, a run's source; the assigner's pins go)' (#758) from design/47-H1-answers-20 into main 2026-11-20 02:22:57 +00:00
jschoubben 1bea97bed2 Design 47 H: H-A-86, the assigner's revision pins go whole
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:22:25 +01:00
jschoubben df47ba6a22 Design 47 H: H-A-85, bridge_heads; a run's pipeline source
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:22:08 +01:00
mesh-tools a6b6c6aab9 Merge pull request 'Design 47 H: lead answer H-A-84 (a mover keeps the publishes it heard)' (#757) from design/47-H1-answers-19 into main 2026-11-20 02:20:10 +00:00
jschoubben 1d8f7f06a2 Design 47 H: H-A-84, a mover keeps the publishes it heard
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:19:47 +01:00
mesh-tools dd3d82905c Merge pull request 'Design 47 H: lead answer H-A-83 (a run on request is one pipeline; kind-3 edges wait on the build step)' (#756) from design/47-H1-answers-18 into main 2026-11-20 02:19:13 +00:00
jschoubben ae7fc40ad4 Design 47 H: H-A-83, a run on request is one pipeline; kind-3 edges wait on the build step's end
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:18:48 +01:00
mesh-tools 0631f43f25 Merge pull request 'Design 47 H: lead answer H-A-82 (the indexer reads nothing in place of version-delivered)' (#755) from design/47-H1-answers-17 into main 2026-11-20 02:17:12 +00:00
jschoubben 0cbff22c6e Design 47 H: H-A-82, the indexer reads nothing in place of version-delivered
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:16:21 +01:00
mesh-tools 43aac6b785 Merge pull request 'Design 47 H: lead answer H-A-81 (severities of head-untaken and merge-partial)' (#754) from design/47-H1-answers-16 into main 2026-11-20 02:16:10 +00:00
jschoubben 92592c9375 Design 47 H: H-A-81, the severities and resolvers of head-untaken and merge-partial
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:15:28 +01:00
mesh-tools 9d0d941190 Merge pull request 'Design 47 H: lead answer H-A-80 (indexer_consumer goes; stopped work is committed in progress)' (#753) from design/47-H1-answers-15 into main 2026-11-20 02:14:59 +00:00
jschoubben 94fe792721 Design 47 H: H-A-80, indexer_consumer goes; stopped work is committed in progress
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:13:53 +01:00
mesh-tools c2b897e28c Merge pull request 'Design 47 H: lead answer H-A-79 (the verdicts state and its readers go; oldsections stays)' (#752) from design/47-H1-answers-14 into main 2026-11-20 02:13:38 +00:00
jschoubben cc20946308 Design 47 H: H-A-79, the verdicts state and its readers go; oldsections stays
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:12:58 +01:00
mesh-tools 1c9a24a06d Merge pull request 'Design 47 H: lead answer H-A-78 (applied compares the fingerprint; the readers' writer)' (#751) from design/47-H1-answers-13 into main 2026-11-20 02:11:19 +00:00
jschoubben 372123e744 Design 47 H: H-A-78, applied compares the fingerprint; the view, watchman and grants readers' writer
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:10:47 +01:00
mesh-tools 6179eb5a7d Merge pull request 'Design 47 H: lead answer H-A-77 (artifacts from the store; the kept-artifact fetch retires)' (#750) from design/47-H1-answers-12 into main 2026-11-20 02:10:16 +00:00
jschoubben 0bf11925c4 Design 47 H: H-A-77, artifacts come from the store; the kept-artifact fetch retires
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:09:54 +01:00
mesh-tools 2a0222bdbb Merge pull request 'Design 47 H: lead answer H-A-76 (the source say-again's body; the seed after the drop)' (#749) from design/47-H1-answers-11 into main 2026-11-20 02:06:22 +00:00
jschoubben 2f1512bd1d Design 47 H: H-A-76, the source say-again's body; the seed after the drop, refusing old keys
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:05:25 +01:00
mesh-tools ba1265100c Merge pull request 'Design 47 H: lead answer H-A-75 (pipeline-wanted's outcome and body; the node's own want unchanged)' (#748) from design/47-H1-answers-10 into main 2026-11-20 02:03:32 +00:00
jschoubben b4563e5256 Design 47 H: H-A-75, pipeline-wanted's outcome and body; the node's own want unchanged
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:03:10 +01:00
mesh-tools 49c216e299 Merge pull request 'Design 47 H: lead answer H-A-74 (nothing of the builder changes in H1)' (#747) from design/47-H1-answers-9 into main 2026-11-20 02:00:50 +00:00
jschoubben 18feae5df3 Design 47 H: H-A-74, nothing of the builder changes in H1; the toolchain wait stays
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:00:23 +01:00
mesh-tools a0cb55cfd3 Merge pull request 'Design 47 H: lead answer H-A-73 (the hand-placement hold is the want's hold field)' (#746) from design/47-H1-answers-8 into main 2026-11-20 01:53:33 +00:00
jschoubben ce96602bd9 Design 47 H: H-A-73, the hand-placement hold is the want's hold field
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:53:10 +01:00
mesh-tools bdecac13d6 Merge pull request 'Design 47 H: lead answer H-A-72 (the runner's and mesh-wants' seat forms)' (#745) from design/47-H1-answers-7 into main 2026-11-20 01:52:59 +00:00
jschoubben 67f21a7b7e Design 47 H: H-A-72, the runner's and mesh-wants' seat forms
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:52:09 +01:00
mesh-tools d7a45777a4 Merge pull request 'Design 47 H: lead answer H-A-71 (owed stays; the kept member gains branch; steprun's asker judgement)' (#744) from design/47-H1-answers-6 into main 2026-11-20 01:50:53 +00:00
jschoubben b4dcdbc93d Design 47 H: H-A-71, owed stays, the kept member gains branch, steprun's asker judgement is mesh-delivery's
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:50:11 +01:00
mesh-tools 96bb5261f3 Merge pull request 'Design 47 H: lead answer H-A-70 (acts stays as the kind-5 declaration; the bound and the holds go)' (#743) from design/47-H1-answers-5 into main 2026-11-20 01:40:09 +00:00
jschoubben bd6c89af74 Design 47 H: H-A-70, acts stays as the kind-5 declaration; the bound and the holds go
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:39:34 +01:00
mesh-tools daa666d40a Merge pull request 'Design 47 H: lead answer H-A-69 (the gate knows a first-view tool by its name form)' (#742) from design/47-H1-answers-4 into main 2026-11-20 01:37:30 +00:00
jschoubben d6318938af Design 47 H: H-A-69, the gate knows a first-view tool by its name form
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:36:56 +01:00
mesh-tools 5ecc060ff1 Merge pull request 'Design 47 H: lead answers H-A-65 to H-A-68 to H1's developers' (#741) from design/47-H1-answers-3 into main 2026-11-20 01:35:31 +00:00
jschoubben b24a4dc6f6 Design 47 H: H-A-67 placing step, H-A-68 a revert is a placement's build without pipeline and rank
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:35:04 +01:00
jschoubben 56b4225bcc Design 47 H: H-A-66, the whole callers set goes from mesh-sdk in H1
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:34:41 +01:00
jschoubben 3ce936a16a Design 47 H: H-A-65, the tool runner's call-timeout setting waits for H4; 30 s constant in H1
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:34:15 +01:00
mesh-tools 386079389e Merge pull request 'Design 47 H: lead answers H-A-63 and H-A-64 to H1's developers' (#740) from design/47-H1-answers-2 into main 2026-11-20 01:30:44 +00:00
jschoubben b123fb5a28 Design 47 H: H-A-64, want:version is a generated constant; seatgen splits on ':'
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:30:23 +01:00
jschoubben 4d7921a087 Design 47 H: H-A-63, apply-order's waits is a list of module names
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:29:56 +01:00
mesh-tools 34ac44de75 Merge pull request 'Design 47 H: the lead's answers H-A-21 to H-A-62 to milestone H1's prepare' (#739) from design/47-H1-lead-answers into main 2026-11-20 01:26:33 +00:00
jschoubben 6a4fbb7892 Plan H: repository names in code spans
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:26:18 +01:00
jschoubben 66a8a7bc02 Plan H: section 9, H1's develop assignments and their reasons
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:25:54 +01:00
jschoubben 0732501b22 Design 47 H: the lead's answers H-A-21 to H-A-62 to H1's prepare; §760 and §762 say what H1 carries
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:24:51 +01:00
mesh-tools 4f3268f6bb Merge pull request 'Design 47, milestone H: the design lines of the one model (§734 to §774), reviewed by architectural domain' (#738) from design/47-H-lines into main 2026-11-20 00:59:30 +00:00
jschoubben 76ddab3ea7 Cite ADR 0682 by its final clauses in milestone H, with no branch protection read and every ask offered
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 01:58:40 +01:00
jschoubben 551da194b7 Settle milestone H's last small points: the placement read, a verb's timeout, the enrolment event, the counts
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 01:54:01 +01:00
jschoubben 166ad75748 Design 47 H: H-A-10's bound ends the record failed, the pipeline's outcome stays
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 01:53:34 +01:00
jschoubben f9d3ecf2c7 Write the review's findings and the lead's answers into milestone H's lines
The four reviewers by architectural domain asked changes on the first
version of design 47 H; the lead answered them in H-A-1 to H-A-20. The
lines now carry the merge call's kept key, its partial refusal and its
tools, the clean state's seed and drop order, one consumer per branch
for the take-in, the runner's queue and per-revision events, wants
written tier by tier with a rank the node-engine applies, the producer's
publish limit, the four owners' change events, the tests split per
module with their counts against the budget, and ADR 0682 cited by its
version 5 clause numbers.

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 01:50:25 +01:00
jschoubben 5f49bfd818 Design 47 H: H-A-10 is the order inside the one pipeline, tier by tier on running
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 01:43:20 +01:00
jschoubben dae41a142f Design 47 H: the lead's answers H-A-9 to H-A-20 to the review by architectural domain
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 01:42:51 +01:00
jschoubben 689ab797a1 Design 47 H: the lead's answers H-A-1 to H-A-8 to the design writer's questions
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 01:38:18 +01:00
jschoubben 4baf34c7c3 Write milestone H's design lines so the one model is decided before code
Design 47 carried the commit-on-a-watched-branch model and the earlier
per-pull-request model side by side; the operator's answers of
2026-11-17 and 2026-11-20 (ADR 0682) lived only in lead answers. The
part H-1 to H-3 (design 47 H §734 to §765) states the merge call as the
start and group, the gate's watchdog, the take-in and validate step, one
pipeline per take-in with none in parallel, the want rule, the builder's
missing lines, reads made events, the missing read tools and what
retires; G's contradicting lines are corrected in place, the main file
gains the wake-up rule, tests 110 to 113 and the H row, and the
glossary gains merge call, untaken head, take-in and mover.

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 01:37:02 +01:00
mesh-tools e6a73d8f59 Merge pull request 'Design 47, milestone H: the plan to deliver the build-and-delivery system properly' (#737) from plan/47-deliver-properly into main 2026-11-20 00:21:01 +00:00
jschoubben ee0b4a271f Plan H: the operator chose the merge through the mesh as the delivery's start (shape A, 01:20)
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 01:20:13 +01:00
jschoubben 6b07fe2041 Plan H: the operator's answers of 01:10 (stale data goes, one take-in one pipeline and none in parallel, hand placement yes; groups still open)
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 01:12:20 +01:00
jschoubben 44975de2e1 Plan H: every node's modules, the module graph, the hand placement in the graph's order, no pull request checked today
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 00:57:06 +01:00
jschoubben cb6cabdf5e Plan H: fold the checker's findings in (counts, guesses said as guesses, the medium gaps left out, H4b)
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 00:35:54 +01:00
jschoubben bfa93e5f48 Plan design 47's milestone H: deliver the build-and-delivery system properly
The system cannot deliver itself: wants held, records never ended, two
models side by side. The plan decides one model, fix in place with the
indexer's take-in written again, one clean state by hand, milestones
H0 to H5 and the guards. Two agent definitions (spec-reader,
gap-surveyor) carried the readings it is written from.

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 00:31:29 +01:00
mesh-tools 50c9123d9e Merge pull request 'Design 47 G: the lead's answer A-490m (a runner rereads its seat list for a defined seat's unnamed verb)' (#736) from design/47-G-lead-answers-144 into main 2026-11-19 22:05:48 +00:00
jschoubben f081c9a23b Answer A-490m: a runner rereads its seat list once for a defined seat's unnamed verb; undefined seats and module tools ask as before
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 23:05:32 +01:00
mesh-tools 1c75f01a1c Merge pull request 'Design 47 G: the lead's answer A-490l (mesh-config's wake-ups and its one timer)' (#735) from design/47-G-lead-answers-143 into main 2026-11-19 22:04:44 +00:00
jschoubben a09270d6b8 Answer A-490l: mesh-config wakes on its inputs alone; one timer for its real deadlines; a proposal naming a pull request is refused
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 23:04:25 +01:00
mesh-tools bbeb890399 Merge pull request 'Design 47 G: the lead's answer A-490k (the catch-up says take-in.taken; a runner behind asks again)' (#734) from design/47-G-lead-answers-142 into main 2026-11-19 22:03:56 +00:00
jschoubben ccacffdc90 Answer A-490k: the indexer's catch-up says take-in.taken with its entries; a runner behind on its view asks again on the next event
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 23:03:39 +01:00
mesh-tools 0928ed52be Merge pull request 'mesh-watcher: read the working program's journal each round; a stuck read is a finding' (#733) from fix/watcher-reads-the-journal into main 2026-11-19 20:33:09 +00:00
jschoubben a6f811fce0 mesh-watcher: read the working program's journal each round; a stuck read is a finding; never guess the time
A watcher reported no change for ten minutes while the sdk's build had failed at its start (2026-11-19 21:19): it read only states that do not show a failed build, and read around a verb that timed out on every call.

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 21:32:59 +01:00
mesh-tools 39f7ecce8d Merge pull request 'Design 47 G: the lead's answer A-490j (a holder takes a publish while its build runs)' (#732) from design/47-G-lead-answers-141 into main 2026-11-19 20:32:37 +00:00
jschoubben 0b3974d773 Answer A-490j: a holder takes a publish while its build runs when the reservation names no digest yet
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 21:32:27 +01:00
mesh-tools 9c39e6be55 Merge pull request 'Design 47 G: the lead's answer A-490i (a floor read is a kept call; no timer in the indexer)' (#731) from design/47-G-lead-answers-140 into main 2026-11-19 16:34:03 +00:00
jschoubben bbc65d5e7a Answer A-490i: a floor read is a kept call of mesh-sdk's form, no timer in the indexer (corrects A-490h)
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 17:33:51 +01:00
mesh-tools 43dc902a0c Merge pull request 'Design 47 G: the lead's answers A-490g and A-490h (the floor reads every package's holder; an unanswered floor read is asked again)' (#730) from design/47-G-lead-answers-139 into main 2026-11-19 16:18:08 +00:00
jschoubben adbf113aa8 Answer A-490g and A-490h: the floor reads every package's holder too; an unanswered floor read is asked again and said
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 17:17:57 +01:00
mesh-tools 514eeb2a2e Merge pull request 'Design 47 G: the lead's answer A-490f (the tag floor at start and every revision meets A-490d)' (#729) from design/47-G-lead-answers-138 into main 2026-11-19 16:11:49 +00:00
jschoubben bdd86986de Answer A-490f: the tag floor filled at start and at every revision meets A-490d
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 17:11:38 +01:00
mesh-tools cff74e8419 Merge pull request 'Design 47 G: the lead's answers A-490c..A-490e (the catalog's tag floor)' (#728) from design/47-G-lead-answers-137 into main 2026-11-19 16:05:50 +00:00
jschoubben 4ac1cfb0b1 Answer A-490c..A-490e: the catalog's tag floor reads every tag of a module's form, per module with no version, in its own repository
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 17:05:38 +01:00
mesh-tools 9ae68e0dc0 Merge pull request 'Design 47 G: the lead's answers A-490a and A-490b (where the package holders' publish cases live; a rebuild reserves afresh)' (#727) from design/47-G-lead-answers-136 into main 2026-11-19 16:03:14 +00:00
jschoubben 1dd4daf184 Answer A-490a and A-490b: where the package holders' publish cases live; a rebuild reserves its version afresh
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 17:02:43 +01:00
mesh-tools 9bde22296e Merge pull request 'Design 47 G: the lead's answer A-490 (a package holder takes the no-parts publish as tag-or-refuse)' (#726) from design/47-G-lead-answers-135 into main 2026-11-19 15:44:47 +00:00
jschoubben 325bf58483 Answer A-490: a package holder takes the no-parts publish as tag-or-refuse and never reads the artifact store
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 16:44:24 +01:00
mesh-tools 9ad9511791 Merge pull request 'Design 47 G: the lead's answer A-489c (the build modules' kit also holds that a puller counts the runs that started)' (#725) from design/47-G-lead-answers-134 into main 2026-11-19 14:45:19 +00:00
jschoubben ef87d14e27 Answer A-489c: the build modules' kit also holds that a puller counts the runs that started
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 15:45:04 +01:00
mesh-tools d28cabd28e Merge pull request 'Design 47 G: the lead's answers A-489a and A-489b (every end of an ask is written, said, acknowledged; a build module that cannot say a step's end fails its own test)' (#724) from design/47-G-lead-answers-133 into main 2026-11-19 14:36:41 +00:00
jschoubben 7d2c80b9c0 Answer A-489a and A-489b: every end of an ask is written, said and acknowledged; a build module that cannot say a step's end fails its own test
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 15:36:25 +01:00
mesh-tools eb0e67753f Merge pull request 'Design 47 G: the lead's answer A-489 (an ask a build module ends itself is acknowledged once its end is written)' (#723) from design/47-G-lead-answers-132 into main 2026-11-19 14:22:08 +00:00
jschoubben 1e309472da Answer A-489: an ask a build module ends itself is acknowledged once its end is written, never terminated
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 15:21:32 +01:00
mesh-tools 420f2fd9c1 Merge pull request 'Design 47 G: the lead's answer A-488b (toolchain keyed by the artifact's language; every build module declares its seat-list reader's needs)' (#722) from design/47-G-lead-answers-131 into main 2026-11-19 12:47:56 +00:00
jschoubben 57c1404701 Answer A-488b: the toolchain stays keyed by the artifact's language; every build module declares what its seat-list reader uses
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 13:47:33 +01:00
mesh-tools 686bff9021 Merge pull request 'Design 47 G: the lead's answers A-488 and A-488a (a step ask names its seat's language; a seat-list follower consumes its events)' (#721) from design/47-G-lead-answers-130 into main 2026-11-19 12:40:26 +00:00
jschoubben 25df48ad70 Answer A-488 and A-488a: a step ask names its build seat's language; a module following the seat list consumes its events
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 13:40:10 +01:00
mesh-tools 96be83fcfc Merge pull request 'Design 47 G: the lead's answer A-487d (a read of the newest revision names the newest again while it moved on)' (#720) from design/47-G-lead-answers-129 into main 2026-11-19 11:16:58 +00:00
jschoubben 61bf1215e7 Answer A-487d: a read of the newest revision names the newest again while it moved on, bounded by progress
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 12:16:48 +01:00
mesh-tools 6938f6053d Merge pull request 'Design 47 G: the lead's answer A-487c (which catalog verbs answer from the view; the subject of catalog-revision)' (#719) from design/47-G-lead-answers-128 into main 2026-11-19 00:17:36 +00:00
jschoubben c1bd8d113f Answer A-487c: which catalog verbs answer from the view, and the subject a reader of catalog-revision subscribes to 2026-11-19 01:17:25 +01:00
mesh-tools 2378f3f6c8 Merge pull request 'Design 47 G: the lead's answer A-487b (the catalog half reads its newest revision from its own objects)' (#718) from design/47-G-lead-answers-127 into main 2026-11-19 00:03:35 +00:00
jschoubben 51e3c7b4d8 Answer A-487b: the catalog half reads its newest revision from its own objects, never by asking its own seat 2026-11-19 01:03:21 +01:00
mesh-tools b37b330221 Merge pull request 'Design 47 G: the lead's answers A-487 and A-487a (the catalog answers from memory; a node-engine asks a missing trunk build again on a backoff)' (#717) from design/47-G-lead-answers-126 into main 2026-11-18 23:54:00 +00:00
jschoubben 532aa1a379 Answer A-487: the catalog answers from its newest revision in memory; a node-engine asks a missing trunk build again on a backoff 2026-11-19 00:53:04 +01:00
mesh-tools 80d44d8547 Merge pull request 'Design 47 G: the lead's answer A-486 (a tool for every pipeline-runner verb no tool reaches)' (#716) from design/47-G-lead-answers-125 into main 2026-11-18 01:22:20 +00:00
jschoubben 3868280be2 Answer A-486: a tool for every pipeline-runner verb no tool reaches 2026-11-18 02:21:59 +01:00
mesh-tools 8f9954bc5d Merge pull request 'Design 47 G: the lead's answer A-485 (container module, a process naming no user, for ADR 0680 §3)' (#715) from design/47-G-lead-answers-124 into main 2026-11-18 00:21:45 +00:00
jschoubben ca8e13a306 Answer A-485: what a container module is and how a process naming no user runs, for ADR 0680 §3 2026-11-18 01:21:30 +01:00
mesh-tools 5d9961a789 Merge pull request 'Design 20: follow ADR 0680 (a process's own secrets belong to the account it runs as)' (#714) from design/20-adr-0680 into main 2026-11-18 00:09:45 +00:00
jschoubben 180a096a3e Follow ADR 0680 in design 20: a process's own secrets belong to the account it runs as
ADR 0436 §1's ban on root and the operator account for a bus process ended,
so design 20 now says whose own secrets are, the validator's two rules in
their place and how each is checked; zfs-owns-zfs A-37 notes its premise ended.
2026-11-18 01:09:07 +01:00
mesh-tools 9581cd5e26 Merge pull request 'Design 47 G: the lead's answer A-484a (the running statement's manifest is the second source)' (#713) from design/47-G-lead-answers-123 into main 2026-11-17 23:47:40 +00:00
jschoubben e69b81b8ea Answer A-484a: the running statement's manifest is the second source; a composition answers only kept data 2026-11-18 00:47:21 +01:00
mesh-tools 2c95a12b8f Merge pull request 'Design 47 G: the lead's answer A-484 (one place answers the manifest of the build a module runs)' (#712) from design/47-G-lead-answers-122 into main 2026-11-17 23:33:09 +00:00
jschoubben 4b8ef634ba Answer A-484: one place answers the manifest of the build a module runs 2026-11-18 00:32:49 +01:00
mesh-tools b5d19f3972 Merge pull request 'Design 47 G: the lead's answer A-483 (a running build with no entry keeps what its running composition keeps)' (#711) from design/47-G-lead-answers-121 into main 2026-11-17 23:22:51 +00:00
jschoubben 7225f752c6 Answer A-483: a running build with no entry keeps what its running composition keeps 2026-11-18 00:22:36 +01:00
mesh-tools 4eabfba370 Merge pull request 'Design 47 G: the lead's answer A-482 (a running build is one the node's own record says runs)' (#710) from design/47-G-lead-answers-120 into main 2026-11-17 22:42:54 +00:00
jschoubben bb04c5b089 Answer A-482: a running build is one the node's own record says runs 2026-11-17 23:42:44 +01:00
mesh-tools a3bb692725 Merge pull request 'Design 47 G: the lead's answer A-481a (the composition names its templates archives in a field of its own)' (#709) from design/47-G-lead-answers-119 into main 2026-11-17 22:40:08 +00:00
jschoubben 56b3cd6bc3 Answer A-481a: the composition names its templates archives in a field of its own 2026-11-17 23:39:54 +01:00
mesh-tools 7de86e7af9 Merge pull request 'Design 47 G: the lead's answer A-481 (a templates archive the composer read counts as a fetched part)' (#708) from design/47-G-lead-answers-118 into main 2026-11-17 22:38:06 +00:00
jschoubben 2359aea5e0 Answer A-481: a templates archive the composer read counts as a fetched part 2026-11-17 23:37:29 +01:00
mesh-tools 91d0ba10a2 Merge pull request 'Design 47 G: the lead's answer A-480a (a held module with no readable running manifest provides what its trunk manifest provides)' (#707) from design/47-G-lead-answers-117 into main 2026-11-17 22:06:42 +00:00
jschoubben 5502609780 Answer A-480a: a held module whose running manifest cannot be read provides what its trunk manifest provides 2026-11-17 23:06:28 +01:00
mesh-tools 89865f27d8 Merge pull request 'Design 47 G: the lead's answer A-480 (a held module still provides what its running build provides)' (#706) from design/47-G-lead-answers-116 into main 2026-11-17 21:53:43 +00:00
jschoubben ff43506156 Answer A-480: a held module still provides what its running build provides 2026-11-17 22:53:29 +01:00
mesh-tools a74591dc71 Merge pull request 'Design 47 G: the lead's answer A-478b (the order waits of one machine's apply stay)' (#705) from design/47-G-lead-answers-115 into main 2026-11-17 21:15:46 +00:00
jschoubben 1942c23c4a Answer A-478b: the order waits of one machine's apply stay beside the want rule 2026-11-17 22:15:30 +01:00
mesh-tools 580678e948 Merge pull request 'Design 47 G: the lead's answer A-478 (the assigner wants the newest released version that passed)' (#704) from design/47-G-lead-answers-114 into main 2026-11-17 21:05:09 +00:00
jschoubben b6b4e0232c Answer A-478: the assigner wants the newest released version that passed, on every placed machine
The operator's step 5 of the delivery walkthrough, 2026-11-17: the acting-part and
delivery-dependency holds held feh 0.1.8, a module nothing depends on.
2026-11-17 22:04:29 +01:00
mesh-tools dd89b437d2 Merge pull request 'Design 47 G: the lead's answer A-477a (the guard compares the recipe only when named)' (#703) from design/47-G-lead-answers-113 into main 2026-11-17 19:59:00 +00:00
jschoubben b27004f74d Answer A-477a: the build node's guard compares the recipe only when the ask names one 2026-11-17 20:58:49 +01:00
mesh-tools d757200010 Merge pull request 'Design 47 G: the lead's answer A-477 (a runner's step ask names the toolchain's recipe)' (#702) from design/47-G-lead-answers-112 into main 2026-11-17 19:57:58 +00:00
jschoubben b463a1518e Answer A-477: a runner's step ask names the agreed toolchain with its recipe 2026-11-17 20:57:42 +01:00
mesh-tools 21004f50e2 Merge pull request 'Design 47 G: the lead's answer A-476a (code dependents still move)' (#701) from design/47-G-lead-answers-111 into main 2026-11-17 19:21:40 +00:00
jschoubben 0ca76cf54f Answer A-476a: a commit still moves its moved modules' code dependents in any repository 2026-11-17 20:21:30 +01:00
mesh-tools 75857d9eb7 Merge pull request 'Design 47 G: the lead's answer A-476 (the take-in validates nothing, holds for no indexer build, moves only its repository's modules)' (#700) from design/47-G-lead-answers-110 into main 2026-11-17 19:13:31 +00:00
jschoubben d433411fcd Answer A-476: the take-in validates nothing, holds for no indexer build, and moves only its repository's modules 2026-11-17 20:13:20 +01:00
mesh-tools 8f08ef178f Merge pull request 'Design 47 G: the lead's answer A-475a' (#699) from design/47-G-lead-answers-109 into main 2026-11-17 15:17:50 +00:00
jschoubben 2eb4059897 Answer A-475a: the stale count, the catch-up's wait and validate-tries' bounds 2026-11-17 16:17:38 +01:00
mesh-tools fd3d7371bc Merge pull request 'Design 47 G: the lead's answer A-461e (no store address holds only the store's fetchers)' (#698) from design/47-G-lead-answers-108 into main 2026-11-17 15:11:23 +00:00
jschoubben 3982c57e98 Answer A-461e: no store address of any readable kind holds only the store's fetchers 2026-11-17 16:11:12 +01:00
mesh-tools 513920b66b Merge pull request 'Design 47 G: the lead's answer A-461d (a placed module not heard running is laid from its placement)' (#697) from design/47-G-lead-answers-107 into main 2026-11-17 15:03:50 +00:00
jschoubben 945a74b6f2 Answer A-461d: a placed module not heard running is laid from its placement or trunk build 2026-11-17 16:03:36 +01:00
mesh-tools ecf2a05179 Merge pull request 'Design 47 G: the lead's answer A-475 (a validation ask whose request moved is asked again)' (#696) from design/47-G-lead-answers-106 into main 2026-11-17 15:00:26 +00:00
jschoubben f906b7c8b3 Answer A-475: a validation ask whose request moved is asked again, not left could-not-validate 2026-11-17 16:00:12 +01:00
mesh-tools 0347a77bcb Merge pull request 'Design 47 G: the lead's answer A-474 (a module's tests read nothing outside their module)' (#695) from design/47-G-lead-answers-105 into main 2026-11-17 14:11:05 +00:00
jschoubben 16316da868 Answer A-474: a module's tests read nothing outside their module 2026-11-17 15:10:52 +01:00
mesh-tools 284c32062e Merge pull request 'Design 47 G: the lead's answer A-473 (the builder asks the tagged publish when its build ends)' (#694) from design/47-G-lead-answers-104 into main 2026-11-17 13:58:33 +00:00
jschoubben 96dadc6fde Answer A-473: the builder asks the tagged publish of a reserved version when its build ends 2026-11-17 14:58:19 +01:00
mesh-tools cc1c5cd5e1 Merge pull request 'Design 47 G: the lead's answer A-472a' (#693) from design/47-G-lead-answers-103 into main 2026-11-17 13:58:03 +00:00
jschoubben a622019bd5 Answer A-472a: the cancel's note stays; the read bound and revisions kept are settings 2026-11-17 14:57:52 +01:00
mesh-tools fa97929f21 Merge pull request 'Design 47 G: the lead's answer A-472 (a pipeline's end is said without waiting on another part)' (#692) from design/47-G-lead-answers-102 into main 2026-11-17 13:49:42 +00:00
jschoubben 76c92e4c1e Answer A-472: a pipeline's end is said without waiting on another part 2026-11-17 14:49:36 +01:00
mesh-tools bdb4efc160 Merge pull request 'Design 47 G: the lead's answer A-471 (a toolchain is agreed by its language version)' (#691) from design/47-G-lead-answers-101 into main 2026-11-17 13:48:18 +00:00
jschoubben 68148d886b Answer A-471: a toolchain is agreed by its language version, the patch not counted 2026-11-17 14:47:57 +01:00
mesh-tools 304ae5a5fb Merge pull request 'Design 47 G: the lead's answer A-470u (a reader that leaves has its wait ended)' (#690) from design/47-G-lead-answers-100 into main 2026-11-17 12:08:34 +00:00
jschoubben aa52fa5345 Answer A-470v: the search blames every refused module, not only the first 2026-11-17 13:08:28 +01:00
jschoubben e671d865d3 Answer A-470u: a reader that leaves or is replaced has its wait ended 2026-11-17 13:08:08 +01:00
mesh-tools 62b03ab4cd Merge pull request 'Design 47 G: the lead's answer A-470t (the runner's ends carry no message id)' (#689) from design/47-G-lead-answers-99 into main 2026-11-17 12:06:11 +00:00
jschoubben 5edbcdac6c Answer A-470t: the runner's ends carry no message id, so A-470q holds as built 2026-11-17 13:06:02 +01:00
mesh-tools 19e7da66d8 Merge pull request 'Design 47 G: the lead's answer A-470s (only build seats are judged for a holder)' (#688) from design/47-G-lead-answers-98 into main 2026-11-17 12:04:03 +00:00
jschoubben c1c7353191 Answer A-470s: only the build seats are judged for a holder at placing 2026-11-17 13:03:55 +01:00
mesh-tools 59cf3c25fd Merge pull request 'Design 47 G: the lead's answers A-470q, A-470r (an end said again has its own message id; a drop ends only owed ends)' (#687) from design/47-G-lead-answers-97 into main 2026-11-17 12:03:41 +00:00
jschoubben cd3428755a Answer A-470q and A-470r: an end said again has its own message id, and a drop ends only the ends owed 2026-11-17 13:03:28 +01:00
mesh-tools 7f846906ee Merge pull request 'Design 47 G: the lead's answer A-470p (a run's end before every other act)' (#686) from design/47-G-lead-answers-96 into main 2026-11-17 11:33:04 +00:00
jschoubben 42e9484261 Answer A-470p: a run's end comes before every other act of its step-ended 2026-11-17 12:32:55 +01:00
mesh-tools 83fab59cac Merge pull request 'Design 47 G: the lead's answer A-470o (an expiry judged by the key's absence)' (#685) from design/47-G-lead-answers-95 into main 2026-11-17 11:25:28 +00:00
jschoubben 384ceb714d Answer A-470o: an expiry is judged by the key's absence, and a run's end is never held behind a finding 2026-11-17 12:25:15 +01:00
mesh-tools 9ea4b009ed Merge pull request 'Design 47 G: the lead's answer A-470n (a run's bound names its ask)' (#684) from design/47-G-lead-answers-94 into main 2026-11-17 11:24:14 +00:00
jschoubben 72bc73df27 Answer A-470n: a run's bound names its ask, so a replaced run's late signal ends nothing 2026-11-17 12:24:05 +01:00
mesh-tools 60e23053c3 Merge pull request 'Design 47 G: the lead's answer A-470m (a reader's end is kept in the key)' (#683) from design/47-G-lead-answers-93 into main 2026-11-17 11:16:54 +00:00
jschoubben d71cbe8b49 Answer A-470m: a reader's end is kept in the key, so a take-up tells a passed reader from a late one 2026-11-17 12:16:40 +01:00
mesh-tools c79c69bfff Merge pull request 'Design 47 G: the lead's answer A-470l (a take-up says no end again for a reader that passed)' (#682) from design/47-G-lead-answers-92 into main 2026-11-17 11:14:54 +00:00
jschoubben 93a3e46923 Answer A-470l: a take-up says no end again for a reader that passed 2026-11-17 12:14:43 +01:00
mesh-tools b269b5f3fa Merge pull request 'Design 47 G-23: causes found on 2026-11-17' (#681) from design/47-G-after-delivery-notes-1117b into main 2026-11-17 11:12:14 +00:00
jschoubben c6943ee76f G-23: the causes found on 2026-11-17 for the assigner's long line, the toolchain disagreement and an untaken merge 2026-11-17 12:12:05 +01:00
mesh-tools 6e43789deb Merge pull request 'Design 47 G: the lead's answer A-470k (the case carries the revision's none)' (#680) from design/47-G-lead-answers-91 into main 2026-11-17 10:59:29 +00:00
jschoubben ff60461f5b Answer A-470k: the case carries the revision's none, so the composer can tell a build that can never be made 2026-11-17 11:58:59 +01:00
mesh-tools 3608c10b5c Merge pull request 'Design 47 G: the lead's answer A-470j (a module that can never be built is blamed)' (#679) from design/47-G-lead-answers-90 into main 2026-11-17 10:56:51 +00:00
jschoubben 10d6d75902 Answer A-470j: a module that can never be built is blamed, not a reason to judge no machine 2026-11-17 11:56:06 +01:00
mesh-tools 16c2f1339c Merge pull request 'Design 47 G: the lead's answer A-470i (a fill names the cap that refuses)' (#678) from design/47-G-lead-answers-89 into main 2026-11-17 10:55:33 +00:00
jschoubben e2e464a046 Answer A-470i: a fill names the cap that refuses, answered by the process that holds it 2026-11-17 11:55:24 +01:00
mesh-tools 8a45d966bd Merge pull request 'Design 47 G: the lead's answer A-470h (a holderless seat's pipeline asks none of its steps)' (#677) from design/47-G-lead-answers-88 into main 2026-11-17 10:54:25 +00:00
jschoubben 8231fd0acb Answer A-470h: a pipeline failed for a holderless seat asks none of its steps 2026-11-17 11:54:15 +01:00
mesh-tools 14a0c6c44f Merge pull request 'Design 47 G: the lead's answer A-470g (no holder fails at once; fill against the cap that refuses)' (#676) from design/47-G-lead-answers-87 into main 2026-11-17 10:51:01 +00:00
jschoubben bb99034295 Answer A-470g: no holder fails at once, and a fill is said against the cap that refuses 2026-11-17 11:50:50 +01:00
mesh-tools fd8c4aaeb7 Merge pull request 'Design 47 G: the lead's answer A-470f (the run drops refuse no caller)' (#675) from design/47-G-lead-answers-86 into main 2026-11-17 10:48:32 +00:00
jschoubben 12a3ef6960 Answer A-470f: the run drops refuse no caller, as every seat verb admits every caller 2026-11-17 11:48:23 +01:00
mesh-tools 79181abfa7 Merge pull request 'Design 47 G: the lead's answers A-470d, A-470e (a rerun carries every reader; a newer run is told by its ask)' (#674) from design/47-G-lead-answers-85 into main 2026-11-17 10:39:29 +00:00
jschoubben 520e95a10c Answer A-470d and A-470e: a rerun carries every reader with its mark, and a newer run is told by its ask 2026-11-17 11:39:20 +01:00
mesh-tools 12b7e246e4 Merge pull request 'Design 47 G: the lead's answers A-470a..A-470c (aging test runs; an untried module never fails; the composer's readings)' (#673) from design/47-G-lead-answers-84 into main 2026-11-17 10:24:26 +00:00
jschoubben 328e17112e Answer A-470a..A-470c: aging test runs, an untried module never fails, the composer's four readings 2026-11-17 11:24:13 +01:00
mesh-tools 36b66c0b54 Merge pull request 'Design 47 G: the lead's answers A-469w..A-470 (caps, settings, waits, bound keys)' (#672) from design/47-G-lead-answers-83 into main 2026-11-17 10:22:16 +00:00
jschoubben f62a73d757 Answer A-469w..A-470: the assigner developer's five questions on caps, settings, waits and bound keys 2026-11-17 11:22:06 +01:00
mesh-tools ff464265b9 Merge pull request 'Design 47 G-23: the faults met on 2026-11-17' (#671) from design/47-G-after-delivery-notes-1117 into main 2026-11-17 10:17:35 +00:00
jschoubben 8884fc9ee7 G-23: the faults met on 2026-11-17, so none is lost before G is delivered 2026-11-17 11:17:23 +01:00
mesh-tools c94cbff169 Merge pull request 'Design 47 G: the lead's answer A-469v (a drop's answer; named run definitions)' (#670) from design/47-G-lead-answers-82 into main 2026-11-17 10:11:37 +00:00
jschoubben 2ed3c5d368 Answer A-469v: a drop's answer names the run and the readers it ended apart, so C1 can go on 2026-11-17 11:11:27 +01:00
mesh-tools 5880f85e5b Merge pull request 'Design 47 G: the lead's answers A-469t, A-469u (one shared form; the four run verbs)' (#669) from design/47-G-lead-answers-81 into main 2026-11-17 10:10:14 +00:00
jschoubben 9bfb8b0211 Answer A-469t and A-469u: one shared form, and the four run verbs' names and answers, so C1 can go on 2026-11-17 11:10:03 +01:00
mesh-tools 9c23309b38 Merge pull request 'Design 47 G: the lead's answers A-468..A-469s (G-24's prepare: 14 design questions, 20 design-meets-code)' (#668) from design/47-G-lead-answers-80 into main 2026-11-17 10:04:16 +00:00
jschoubben e88cce45dd Answer A-468..A-469s: G-24's 14 design questions and 20 design-meets-code entries, so its develop can start 2026-11-17 11:04:04 +01:00
mesh-tools be550d1790 Merge pull request 'Design 47 G: the lead's answer A-467a (a composition step with no machine judged never passes)' (#667) from design/47-G-lead-answers-79 into main 2026-11-17 09:48:03 +00:00
jschoubben 92f967f542 Answer A-467a: a composition step with no machine judged never passes 2026-11-17 10:47:50 +01:00
mesh-tools c2aae05b59 Merge pull request 'Design 47 G: one composition run per candidate and machine, one test run per module's packages (G-24)' (#666) from design/47-G-shared-runs into main 2026-11-17 09:41:41 +00:00
jschoubben cbf12d3380 Merge main (A-467) into the shared-runs design 2026-11-17 10:41:23 +01:00
jschoubben 849a4012d6 Design 47 G: read "no holder" from the seat-holders view, not the seat list
The seat list answers definitions alone (§527); the holders are the seat mesh-module-assigner's
view seat-holders, which the runner now consumes (A-466z).
2026-11-17 10:39:47 +01:00
jschoubben 32302e0bd1 Design 47 G: test 109's line in G-24 names the queued run A-466y keeps 2026-11-17 10:38:51 +01:00
jschoubben 017e20504a Design 47 G: read "no holder" from the seat list, never from five minutes in the queue
A test run queued behind the build capacity with its holder present was ended failed for no
holder after five minutes, which is not true; the queue is §86's finding's and the untaken
bound's to time (A-466y).
2026-11-17 10:38:35 +01:00
jschoubben d7321df3e5 Design 47 G: write in round 2 of the review of the composition runs and test runs
A run's bound times owed progress from the ask's taking, a run never taken ends at a bound of
its own, blame-tries travels in the request, the hand order goes, a test run's output lives
with its key, stands names what a reader waits on, and G-24 reads in number order
(A-466p to A-466x).
2026-11-17 10:37:41 +01:00
mesh-tools e82887d67c Merge pull request 'Design 47 G: the lead's answer A-467 (no composition passes on a machine it did not judge)' (#665) from design/47-G-lead-answers-78 into main 2026-11-17 09:35:27 +00:00
jschoubben 605e0878a5 Answer A-467: a composition step never passes on a machine it did not judge; seats from the trunk while the revision names none 2026-11-17 10:35:05 +01:00
jschoubben cebac2e791 Design 47 G: count both run bounds from the ask's taking, 30 minutes
A bound counted from the asking would end a run that only waited in the queue as could not
run, which is not true; the queue is the build-capacity finding's to time (A-466n).
2026-11-17 10:33:58 +01:00
jschoubben 661fb8a742 Design 47 G: name the runs' asks where they are known, bound the runs, time every reader
The lead's answers A-466m to A-466o: the assigner names the composition runs' asks in its
step-progress, each run's bound is a setting, and since the watchman on main times only a
build seat's running ask, it now times every pipeline step that reads a run, so a reader no
part ends is said as pipeline-stands.
2026-11-17 10:33:22 +01:00
jschoubben 6b7adc5ec2 Design 47 G: write in the review of the composition runs and test runs
The four reviewers by architectural domain found results crossing candidates, a read of a
build seat's state, fixed durations and caps, unstated seat contract fields and a rerun rule
that differed between the two kinds; the lead's answers A-466 to A-466l settle each. The
lines move to a file of their own, G-24, so G-2 stays under its bound. The split of the main
file and G-22 waits until after G, as the operator decided at 10:31 CET.
2026-11-17 10:31:28 +01:00
jschoubben 77318ca60e Design 47 G: a test run asked again moves every step that reads it; two items after G
The coordinator's answers of 2026-11-17: a step left reading a failed result would say what
is no longer true, so a rerun of a test run moves all its readers; the node-engine's
differing input bytes and the split of design 47's main file wait until after G.
2026-11-17 10:25:15 +01:00
jschoubben 31cd62aeec Design 47 G: one composition run per candidate and machine, one test run per tested packages
G's live delivery of 2026-11-17 composed each machine once per pipeline (96 runs for one
revision, 80 more on rerun, the assigner's inputs state at its cap twice) and ran the same
tests once per artifact. Pipelines of one candidate now read one composition run per
machine, kept by the assigner, whose verdict names the modules it blames so one module's
fault fails only its own pipelines; test steps naming the same packages read one test run,
kept by the runner. The operator, 2026-11-17 about 10:20 CET: "In G, now".
2026-11-17 10:24:28 +01:00
mesh-tools 2407183c70 Merge pull request 'Design 47 G: the lead's answer A-465b (the inputs key form is the assigner's own)' (#664) from design/47-G-lead-answers-77 into main 2026-11-17 08:46:28 +00:00
jschoubben 399ac934f6 Answer A-465b: the inputs key form is the assigner's own; an ask's key holds its time; old keys age out 2026-11-17 09:46:15 +01:00
mesh-tools a550fb9256 Merge pull request 'Design 47 G: the lead's answer A-461c (the golden node grant checked against invokes); after G item 14' (#663) from design/47-G-lead-answers-76 into main 2026-11-17 08:40:06 +00:00
jschoubben ec6aae9997 Answer A-461c: the node-engine's golden grant is checked against its invokes; after G: no pass waits on a call 2026-11-17 09:39:53 +01:00
mesh-tools 1ac43e4ddf Merge pull request 'Design 47 G: the lead's answer A-465a (a composition input kept once per content)' (#662) from design/47-G-lead-answers-75 into main 2026-11-17 08:38:18 +00:00
jschoubben cb1ce7291f Answer A-465a: a composition input is kept once per content, shared by the asks that use it 2026-11-17 09:38:02 +01:00
mesh-tools 8fd85c6768 Merge pull request 'Design 47 G: after G, a full delivery cycle by hand (the operator, 2026-11-17)' (#661) from design/47-G-after-hand-cycle into main 2026-11-17 08:23:07 +00:00
jschoubben 0fc357c96b After G: say catalog, the glossary's word 2026-11-17 09:22:54 +01:00
jschoubben d84b7cbb57 After G: a full delivery cycle by hand, as the operator asked on 2026-11-17 2026-11-17 09:22:37 +01:00
mesh-tools 36d5b50d5b Merge pull request 'Design 47 G: the lead's answer A-465 (the assigner's inputs end with their objects)' (#660) from design/47-G-lead-answers-74 into main 2026-11-17 08:00:16 +00:00
jschoubben 64ff3fd4e9 Answer A-465: the assigner's composition inputs end with their objects, and a drop tool for those left 2026-11-17 09:00:02 +01:00
mesh-tools 2b59494c30 Merge pull request 'Design 47 G: the lead's answer A-464e (the gate's start comparison ends only when every head was compared)' (#659) from design/47-G-lead-answers-73 into main 2026-11-17 07:56:55 +00:00
jschoubben 782f90c003 Answer A-464e: the gate's start comparison ends only when every head was compared 2026-11-17 08:56:43 +01:00
mesh-tools f0a940463b Merge pull request 'Design 47 G: the lead's answers A-463a and A-464d (from the review)' (#658) from design/47-G-lead-answers-72 into main 2026-11-17 01:08:47 +00:00
jschoubben 5385c798c0 Answer A-463a and A-464d: a pending merge is not behind, and every source move is forward 2026-11-17 02:08:39 +01:00
mesh-tools cf08f6e69b Merge pull request 'Design 47 G: the lead's answer A-464c (the gate's source moves a head only forward)' (#657) from design/47-G-lead-answers-71 into main 2026-11-17 01:01:11 +00:00
jschoubben 163fe51f96 Answer A-464c: the gate's source moves a head only forward, and only when it changes 2026-11-17 02:00:59 +01:00
mesh-tools c81a186a3d Merge pull request 'Design 47 G: the lead's answer A-464b (a merge the gate did not make)' (#656) from design/47-G-lead-answers-70 into main 2026-11-17 00:57:23 +00:00
jschoubben acd7f1f588 Answer A-464b: what makes a merge one the gate did not make, and where that is said 2026-11-17 01:57:14 +01:00
mesh-tools 6664193aac Merge pull request 'Design 47 G: the lead's answer A-464a (a read tool for the indexer's takeins state)' (#655) from design/47-G-lead-answers-69 into main 2026-11-17 00:50:39 +00:00
jschoubben d47f617ad5 Answer A-464a: a read tool for the indexer's takeins state, so a hand take-in is seen 2026-11-17 01:50:25 +01:00
mesh-tools 84ef09d4b4 Merge pull request 'Design 47 G: the lead's answer A-464 (the gate's source follows every merge)' (#654) from design/47-G-lead-answers-68 into main 2026-11-17 00:43:10 +00:00
jschoubben 709ad9de59 A-464: name mesh-host in a code span, as the words test asks 2026-11-17 01:42:59 +01:00
jschoubben a4d7d44cd0 Answer A-464: the gate's source follows every merge into a watched branch 2026-11-17 01:42:43 +01:00
mesh-tools 47332934b8 Merge pull request 'Design 47 G: the lead's answer A-463 (the indexer takes in a merge it never took in)' (#653) from design/47-G-lead-answers-67 into main 2026-11-17 00:40:25 +00:00
jschoubben b6c99f171d Answer A-463: the indexer takes in a merge it never took in, and says so 2026-11-17 01:40:16 +01:00
mesh-tools e34c74c2f8 Merge pull request 'Design 47 G: A-459b withdraws A-459 and A-459a; A-462b' (#652) from design/47-G-lead-answers-66 into main 2026-11-17 00:32:53 +00:00
jschoubben f44b0fc90b Answer A-459b (withdraw A-459, A-459a: rule 7 reads the node's own composition) and A-462b 2026-11-17 01:32:44 +01:00
mesh-tools c91aafb6dd Merge pull request 'Design 47 G: the lead's answer A-457b (republish-max-versions goes)' (#651) from design/47-G-lead-answers-65 into main 2026-11-17 00:30:28 +00:00
jschoubben 1209008aba Answer A-457b: the builder's republish-max-versions setting goes with the path it bounded 2026-11-17 01:30:16 +01:00
mesh-tools 25449d1d4f Merge pull request 'Design 47 G: the lead's answer A-456b (the release record is bounded; a publish item ends with its release)' (#650) from design/47-G-lead-answers-64 into main 2026-11-17 00:24:02 +00:00
jschoubben dcaad0c6a4 Answer A-456b: the release record is bounded per module; a publish item ends with its release or its reservation 2026-11-17 01:23:38 +01:00
mesh-tools 66b3d0c7f6 Merge pull request 'Design 47 G: correct A-459a (composed is followed through the declared read)' (#649) from design/47-G-lead-answers-63 into main 2026-11-17 00:22:12 +00:00
jschoubben 92929d55ef Correct A-459a: rule 7 follows composed through the read the assigner's manifest declares 2026-11-17 01:22:00 +01:00
mesh-tools 0bb30e6bc9 Merge pull request 'Design 47 G: the lead's answer A-461b (an absent placed build is the trunk build)' (#648) from design/47-G-lead-answers-62 into main 2026-11-17 00:18:06 +00:00
jschoubben e69d2693de Answer A-461b: an absent placed build is the trunk build from mesh-catalog's module verb 2026-11-17 01:17:57 +01:00
mesh-tools b90489afc7 Merge pull request 'Design 47 G: the lead's answer A-460a (ace's refusal was a hand act; no retry added)' (#647) from design/47-G-lead-answers-61 into main 2026-11-17 00:11:52 +00:00
jschoubben bca45ea0df Answer A-460a: ace's refusal was a hand act; a failed install is tried again when its want changes 2026-11-17 01:11:39 +01:00
mesh-tools f48d5f5091 Merge pull request 'Design 47 G: the lead's answers A-456a, A-457a, A-461a' (#646) from design/47-G-lead-answers-60 into main 2026-11-17 00:11:21 +00:00
jschoubben 2ff96d1b7e Answer A-461a: another node's module is laid from the assignment's placed build 2026-11-17 01:11:09 +01:00
jschoubben e68d3a892e Answer A-456a and A-457a: a released build counts as reserved; the publish retries on the builder's own re-ask state 2026-11-17 01:10:59 +01:00
mesh-tools de9d3378af Merge pull request 'Design 47 G: the lead's answer A-462a (no entry in the followed catalog; the assigner asks the indexer nothing)' (#645) from design/47-G-lead-answers-59 into main 2026-11-17 00:10:20 +00:00
jschoubben 547006dd59 Answer A-462a: no entry means none in the followed catalog; the assigner asks the indexer nothing 2026-11-17 01:10:07 +01:00
mesh-tools 2945e57a4a Merge pull request 'Design 47 G: the lead's answer A-459a (rule 7 hears composed per module and fingerprint)' (#644) from design/47-G-lead-answers-58 into main 2026-11-17 00:09:49 +00:00
jschoubben fc5ec32b90 Answer A-459a: rule 7 hears composed per module and fingerprint from the node-engine's events 2026-11-17 01:09:38 +01:00
mesh-tools 242bae0d0c Merge pull request 'Design 47 G: the lead's answers A-454a, A-456..A-462 (the delivery path after a passed pipeline)' (#643) from design/47-G-lead-answers-57 into main 2026-11-17 00:05:31 +00:00
jschoubben 928aa7e5ba Answer A-454a, A-456..A-462: close the delivery path's six gaps after a passed pipeline 2026-11-17 01:05:14 +01:00
mesh-tools 4d4815c83d Merge pull request 'Design 47 G: the lead's answer A-455 (a stale reservation is taken over; builder_reserve_done)' (#642) from design/47-G-lead-answers-56 into main 2026-11-16 23:50:58 +00:00
jschoubben 975f83f045 Answer A-455: a newer trunk build takes over a stale reservation; builder_reserve_done for a done build 2026-11-17 00:50:50 +01:00
mesh-tools acc54c16b9 Merge pull request 'Design 47 G: correct A-453a (a held have has not moved past its hold)' (#641) from design/47-G-lead-answers-55 into main 2026-11-16 23:49:01 +00:00
jschoubben 77cf51b4c7 Correct A-453a: 'at another fingerprint' applies only to a have that is not held 2026-11-17 00:48:47 +01:00
mesh-tools 5f90d599c6 Merge pull request 'Design 47 G: the lead's answer A-454 (an upstream image is no part of the want)' (#640) from design/47-G-lead-answers-54 into main 2026-11-16 23:47:36 +00:00
jschoubben 987283dd30 Answer A-454: an upstream image a manifest pins is no part of the want 2026-11-17 00:47:28 +01:00
mesh-tools 0da67d6323 Merge pull request 'Design 47 G: the lead's answer A-453a (a have mid-move is not 'no longer held')' (#639) from design/47-G-lead-answers-53 into main 2026-11-16 23:46:13 +00:00
jschoubben 2ecb831355 Answer A-453a: a have mid-move is not 'no longer held' 2026-11-17 00:46:04 +01:00
mesh-tools 59d9f397e2 Merge pull request 'Design 47 G: the lead's answer A-453 (a backup ask only for a failed backup)' (#638) from design/47-G-lead-answers-52 into main 2026-11-16 23:37:41 +00:00
jschoubben 7b1607d933 Answer A-453: the operator is asked about a backup only when a backup failed 2026-11-17 00:37:32 +01:00
mesh-tools bfc7272b3c Merge pull request 'Design 47 G after delivery: retire held/kept for a module left on its build; hollow composition pass' (#637) from design/47-G-after-words into main 2026-11-16 23:17:48 +00:00
jschoubben 37fdc292f7 After G: retire held and kept for a module left on its build; a composition that judged nothing is no pass 2026-11-17 00:17:38 +01:00
mesh-tools 21ab7b1bdf Merge pull request 'Design 47 G: the lead's answer A-452 (an unanswered requirement costs its consumer, not the machine)' (#636) from design/47-G-lead-answers-51 into main 2026-11-16 23:15:03 +00:00
jschoubben e17cffa59e Answer A-452: an unanswered requirement costs its consumer, not the machine 2026-11-17 00:14:46 +01:00
mesh-tools dcdfbc12a6 Merge pull request 'Design 47 G: the lead's answer A-451 (composition with a node-engine not heard running)' (#635) from design/47-G-lead-answers-50 into main 2026-11-16 13:53:44 +00:00
jschoubben 7dd6563ab5 Answer A-451: a machine whose node-engine is not heard running composes with the revision's node-engine entry 2026-11-16 14:53:14 +01:00
mesh-tools eb5cc23a86 Merge pull request 'Design 47 G: the lead's answer A-237c (inline input stays for the checker until G)' (#634) from design/47-G-lead-answers-49 into main 2026-11-16 13:47:23 +00:00
jschoubben d07de2840d Answer A-237c: the token-less inline input stays for the checker until G removes it 2026-11-16 14:47:11 +01:00
mesh-tools 2ab0507440 Merge pull request 'Design 47 G: the lead's answer A-237b (compose-candidate sends its input in chunks)' (#633) from design/47-G-lead-answers-48 into main 2026-11-16 13:35:32 +00:00
jschoubben c47f9ea48e Answer A-237b: compose-candidate sends its input in chunks 2026-11-16 14:35:22 +01:00
mesh-tools dd462aa1ff Merge pull request 'Design 47 G: the lead's answer A-450 (the node-engine's account in the catalog's caller check)' (#632) from design/47-G-lead-answers-47 into main 2026-11-16 13:12:41 +00:00
jschoubben c0736710e8 Answer A-450: the node-engine's account counts as the module holding node-engine for the catalog's caller check 2026-11-16 14:12:28 +01:00
mesh-tools bedc92e251 Merge pull request 'Design 47 G: the lead's answer A-226c (a run's key reads candidates.run-<id>)' (#631) from design/47-G-lead-answers-46 into main 2026-11-16 12:59:58 +00:00
jschoubben d93dddf5b3 Answer A-226c: a run's key reads candidates.run-<id> 2026-11-16 13:59:47 +01:00
mesh-tools 2a52d91cc6 Merge pull request 'Design 47 G: the lead's answer A-226b (compose-candidate reads a revision key and a run key)' (#630) from design/47-G-lead-answers-45 into main 2026-11-16 12:55:03 +00:00
jschoubben ecaf070846 Answer A-226b: compose-candidate reads a branch revision key and a run key too 2026-11-16 13:54:52 +01:00
mesh-tools 2631a11447 Merge pull request 'Principles 11 and 12, and the reviewers ask them' (#629) from principles/configurable-and-own-files into main 2026-11-16 12:53:40 +00:00
jschoubben 39f7ae7203 Reviewers: a hard-coded value and a file written for another module are findings (principles 11 and 12) 2026-11-16 13:53:30 +01:00
jschoubben 6517bbebf0 Principles 11 and 12: configurable, never hard-coded; a module writes only its own 2026-11-16 13:51:28 +01:00
mesh-tools 4de493a784 Merge pull request 'Design 47 G: the lead's answer A-449a (the indexer pins a take-in's revision for its pipelines)' (#628) from design/47-G-lead-answers-44 into main 2026-11-16 12:44:33 +00:00
jschoubben 79214618f3 Answer A-449a: the indexer pins a take-in's revision for its pipelines when it keeps it 2026-11-16 13:44:23 +01:00
mesh-tools 8fa037074c Merge pull request 'Design 47 G: the lead's answers A-448 and A-449 (a take-in names its revision; a pipeline pins it)' (#627) from design/47-G-lead-answers-43 into main 2026-11-16 12:33:23 +00:00
jschoubben f07c337c22 Answer A-448 and A-449: a take-in names its revision; a pipeline pins it 2026-11-16 13:33:12 +01:00
mesh-tools d595d08042 Merge pull request 'After G: tests against the composed bus, kept events heard or loud, one way of asking work' (#626) from design/47-G-after-list-2 into main 2026-11-16 12:01:14 +00:00
jschoubben eaa6de7faf After G: tests against the composed bus, kept events heard or loud, one way of asking work 2026-11-16 13:01:03 +01:00
mesh-tools 2d4b34c51c Merge pull request 'Design 47 G: the lead's answer A-447e (the checker is removed at G, not rebuilt per module)' (#625) from design/47-G-lead-answers-42 into main 2026-11-16 10:39:32 +00:00
jschoubben d4c31d4ff0 Answer A-447e: the checker is removed at G, not rebuilt per module; the no-dir refusal lands with its removal 2026-11-16 11:39:23 +01:00
mesh-tools 71cb172953 Merge pull request 'Design 47 G: the lead's answer A-447d (the checker fetches per changed module)' (#624) from design/47-G-lead-answers-41 into main 2026-11-16 10:38:20 +00:00
jschoubben fa74c6d594 Answer A-447d: the checker fetches per changed module 2026-11-16 11:38:10 +01:00
mesh-tools 97c8c81e82 Merge pull request 'Principle 10: the module is the unit, never the repository' (#623) from principles/module-is-the-unit into main 2026-11-16 10:35:37 +00:00
jschoubben b5e5a35460 Principle 10: a merge moves only the modules it changes 2026-11-16 11:35:33 +01:00
jschoubben 3c0389f74e Principle 10: the module is the unit, never the repository 2026-11-16 11:32:32 +01:00
mesh-tools 99e2966bb7 Merge pull request 'Design 47 G: the lead's answer A-447c (nothing is ever repository-based)' (#622) from design/47-G-lead-answers-40 into main 2026-11-16 10:31:45 +00:00
jschoubben 42054c599c Answer A-447c: nothing in building, checking or delivering works on a repository 2026-11-16 11:31:35 +01:00
mesh-tools f887e777b2 Merge pull request 'Design 47 G: the lead's answer A-447b (a build is always for one module)' (#621) from design/47-G-lead-answers-39 into main 2026-11-16 10:30:14 +00:00
jschoubben bc9ba62959 Answer A-447b: a build, a step and a check are always for one module; a fetch with no dir is refused 2026-11-16 11:30:04 +01:00
mesh-tools 4353e7c018 Merge pull request 'Design 47 G: the lead's answer A-447a (a module whose directory holds no go.mod; an empty choice fails)' (#620) from design/47-G-lead-answers-38 into main 2026-11-16 10:15:43 +00:00
jschoubben ca8cda69d9 Answer A-447a: a module whose directory holds no go.mod takes the go.mod files under it; an empty choice fails 2026-11-16 11:15:34 +01:00
mesh-tools a7b72d49d2 Merge pull request 'Design 47 G: the lead's answer A-447 (a Go fetch asked with a module's directory resolves that module alone)' (#619) from design/47-G-lead-answers-37 into main 2026-11-16 10:00:19 +00:00
jschoubben 2c399ac708 Answer A-447: a Go fetch asked with a module's directory resolves that module and its local replaces alone 2026-11-16 11:00:04 +01:00
mesh-tools 8c307e0e7a Merge pull request 'Design 47 G: A-446a, what goes with the runner's set-aside' (#618) from design/47-G-lead-answers-36 into main 2026-11-16 09:35:06 +00:00
jschoubben 2d6da3f34d Answer A-446a: a placed pipeline says pipeline-started; what only the set-aside used goes 2026-11-16 10:34:59 +01:00
mesh-tools 45b43ce81c Merge pull request 'Design 47 G: A-446, the pipeline runner holds no pipeline for its own new version' (#617) from design/47-G-lead-answers-35 into main 2026-11-16 09:25:12 +00:00
jschoubben 13ad18268f Answer A-446: the pipeline runner holds no pipeline for its own new version (the operator) 2026-11-16 10:25:02 +01:00
mesh-tools 5be43e0193 Merge pull request 'Principles: no part without a need (7); depend on the contract, at the level it is interchangeable (9)' (#616) from principles/contract-and-no-part-without-need into main 2026-11-16 09:06:33 +00:00
jschoubben 4e0f340916 Principles: 7 becomes 'no part without a need', 9 'depend on the contract, at the level it is interchangeable' (the operator, 2026-11-16) 2026-11-16 10:06:25 +01:00
mesh-tools 12c0f66fab Merge pull request 'After G: the module graph's edges are dependencies, never verbs' (#615) from design/47-G-after-delivery-2 into main 2026-11-16 08:57:25 +00:00
jschoubben 6ccd7c3edf After G: the module graph's edges are dependencies on a seat or a module, never verbs or bus subjects (the operator) 2026-11-16 09:57:18 +01:00
mesh-tools ea02e537a3 Merge pull request 'Design 47 G: the lead's answer A-445 (the bus keeper's start path)' (#614) from design/47-G-lead-answers-34 into main 2026-11-16 08:52:04 +00:00
jschoubben 60872e67e9 Answer A-445: the bus keeper's A-376 path and its four manifest lines go 2026-11-16 09:51:57 +01:00
mesh-tools 9cf4d63c9c Merge pull request 'Design 47 G: what is owed once G is delivered' (#613) from design/47-G-after-delivery into main 2026-11-16 08:46:19 +00:00
jschoubben 1a2d31b82f Keep what is owed once G is delivered in hq, not in a session's memory 2026-11-16 09:46:13 +01:00
mesh-tools 267f1ef0de Merge pull request 'Design 47 G: the lead's answer A-443a (a given-up publish step)' (#612) from design/47-G-lead-answers-33 into main 2026-11-16 08:42:19 +00:00
jschoubben 23cba849e3 Answer A-443a: a given-up publish step's call ends at the SDK's own bound and is said 2026-11-16 09:42:12 +01:00
mesh-tools 3723b2ea41 Merge pull request 'Design 47 G: the lead's answers A-394 and A-434 to A-444 (the start fixes' review)' (#611) from design/47-G-lead-answers-32 into main 2026-11-16 08:38:26 +00:00
jschoubben 62e3715af4 Answer A-394 and A-434 to A-444: the start fixes' review questions, each against a principle or the operator's word 2026-11-16 09:38:16 +01:00
mesh-tools 18ce04f6e8 Merge pull request 'Design 47 G: the lead's answers A-363 to A-372 (G starts)' (#609) from design/47-G-lead-answers-31 into main 2026-11-16 08:24:38 +00:00
jschoubben 91f60c7075 Use the glossary's words in lead answers 31, so the words test passes 2026-11-16 09:24:19 +01:00
jschoubben 4169ded5cd Answer A-433: before the catalog half is read, a module account's call runs unmarked, seat verbs too 2026-11-16 02:34:22 +01:00
jschoubben d9dd5dab67 Answer A-432: a runtime of its own runs the tool runner's program, which §524's check of the module's parts leaves out 2026-11-16 01:00:35 +01:00
jschoubben 2829a47ea0 Answer A-431: a take-in names the source revision it makes, one above the newest seen or said 2026-11-15 17:51:01 +01:00
jschoubben 09cf7d609d Answer A-430b: a branch build is named by the version the builder reserved; build.ended carries it and the registry tags it unreleased 2026-11-15 16:48:29 +01:00
jschoubben 547eec3373 Answer A-430a: every wanted build has a version; the node-engine resolves artifacts by version through the registry's versions verb 2026-11-15 16:44:17 +01:00
jschoubben d2094f657e Answer A-430: a want names the module version; the node-engine fetches the artifacts by that version (the operator) 2026-11-15 16:43:23 +01:00
jschoubben ee80b4d84b Answer A-426a: every rule waiting on a serving part counts any healthy running build that serves it 2026-11-15 16:17:01 +01:00
jschoubben 14c3e90332 Answer A-429: a released build is done for rule 1 2026-11-15 16:13:29 +01:00
jschoubben cac334e749 Narrow A-428: only the pipeline runner's own want skips the passed-pipeline gate while no runner runs 2026-11-15 16:04:05 +01:00
jschoubben aad8f7c921 Answer A-428: with no pipeline runner running, wants do not wait for a passed pipeline 2026-11-15 16:03:56 +01:00
jschoubben b20b382cd9 Answer A-426 (an acting wait ends on any running build that serves the edge) and A-427 (a put may hold the running build) 2026-11-15 15:56:51 +01:00
jschoubben 8abbb539fd Answer A-425a: which proposals are asked is the assigner's config key ask-operator-for 2026-11-15 15:55:34 +01:00
jschoubben f988c23d1e Answer A-425: a passing placement proposal is applied without the operator's ask (the operator, 2026-11-15) 2026-11-15 15:54:46 +01:00
jschoubben fd45f01929 Answer A-424: the operator channel keeps no limit of open asks per asker (the operator, 2026-11-15) 2026-11-15 15:49:03 +01:00
jschoubben f0b9c73a9f Answer A-423: one reader per durable through the hub; a consumed kept event with no route is said 2026-11-15 03:52:41 +01:00
jschoubben 17ab2d028e Answer A-422: the SDK's event hub binds the kept seat streams in its own start 2026-11-15 03:48:47 +01:00
jschoubben 9a60a312a0 Answer A-421: a trunk entry with no fp-src is matched to its release by the digests its build made 2026-11-15 03:17:45 +01:00
jschoubben 1de67e76ed Answer A-419 (release matched by the fingerprint's source) and A-420 (a message given up is said) 2026-11-15 03:14:06 +01:00
jschoubben 1088d86e5c Answer A-418: a bundle's or archive's name for reserved is <module>/<artifact> from its entry's artifact reference 2026-11-15 02:59:19 +01:00
jschoubben 2ce9268504 Answer A-417: a registry holder tags a version on the artifact it holds by digest, else takes it from the artifact store 2026-11-15 02:37:16 +01:00
jschoubben 39ab7efb6b Answer A-416a: the builder reads a registry seat's holder from the catalog's seat holders, not FollowSeat 2026-11-15 02:17:33 +01:00
jschoubben 6c5f8aabb0 Answer A-416: the builder knows a registry seat's holder through FollowSeat, not from running events since its start 2026-11-15 02:16:18 +01:00
jschoubben 3d56f25942 Answer A-415: a published heard before the build's digests is kept on its reservation and marks it when the digests land 2026-11-15 02:05:05 +01:00
jschoubben 9da181e12d Answer A-414: the grants part composes a module whose running build has no entry from its newest entry, as A-407 does for the node 2026-11-15 00:23:25 +01:00
jschoubben 8b9b450855 Answer A-413: named asks are unused only while no account the part composes may publish one 2026-11-15 00:03:35 +01:00
jschoubben 16f4fd8696 Answer A-412a: the entry's digest readings live in the mesh-catalog contract 2026-11-14 23:44:50 +01:00
jschoubben ee543b8601 Answer A-412: the builder takes the entry's manifest digest bare, and a look that writes nothing says why 2026-11-14 23:44:11 +01:00
jschoubben 7981d72d9b Answer A-411: the builder reads the last versions-filled from the seat event's kept stream, not EVENTS 2026-11-14 23:37:07 +01:00
jschoubben 842071859a Answer A-410: a running module the node cannot fingerprint is held, never counted as removed 2026-11-14 23:14:41 +01:00
jschoubben 11054da240 Answer A-409: a consumed seat event matches by name and filters on the seat's subject; the revision's id names its branch 2026-11-14 22:51:41 +01:00
jschoubben 46b6b74148 Answer A-408: the builder reads the kept versions-filled at its start 2026-11-14 22:47:32 +01:00
jschoubben 706e76b566 Answer A-407: a running build with no entry is described for resolving by the entry of the build its want says is being built 2026-11-14 22:46:19 +01:00
jschoubben 4b2eb0bcf4 Answer A-405 and A-406: a node composes around a running build with no entry; the pipeline's manifest passes the judge and is built once by hand 2026-11-14 22:42:00 +01:00
jschoubben 634b4ea49e Answer A-404: a source the gate started from the forge names no group in its source-moved 2026-11-14 22:16:04 +01:00
jschoubben b6380d0958 Answer A-403: the gate adds a registered repository a held source key lacks, and changes no head it holds 2026-11-14 22:08:40 +01:00
jschoubben dbe9d711ea Answer A-402: a head is read whole on any failure to read its merged message 2026-11-14 22:08:11 +01:00
jschoubben de9f6d3353 Answer A-401: a newly watched branch starts from the forge at its head, as a clone does 2026-11-14 22:05:17 +01:00
jschoubben d5e7d42d17 Answer A-400: seat-holders names the assigned claimant of a seat no assignments holds 2026-11-14 20:21:29 +01:00
jschoubben 232454cf76 A-397: the rule is the developer's judgement (share a durable only for shared work), not an operator ruling 2026-11-14 18:51:53 +01:00
jschoubben f55a6e7927 Answer A-399: a seat pulled by kind's holder says the seat's own events 2026-11-14 18:39:47 +01:00
jschoubben f6f82721d5 Answer A-398: a seat-form read resolves to the assigned claimant when no holder is on record 2026-11-14 18:17:34 +01:00
jschoubben 98e8bc395b A-397: the operator's decision time read from the clock 2026-11-14 18:03:19 +01:00
jschoubben ed95207361 Answer A-397: every process that hears events has a durable consumer of its own, named constantly; a shared one split the first registrations between the assigner's program and its tool runner 2026-11-14 18:02:11 +01:00
jschoubben 525a9590cd Answer A-396: every module is composed as invoking the tool runner's own reads
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 12:09:52 +01:00
jschoubben 6bc258db0d Answer A-395: every trunk part and the tool runner may read the catalog half
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 12:00:53 +01:00
jschoubben 5f04a5e3af Answer A-393: a node seat's verb asked with no machine is answered by any one holder
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 11:31:09 +01:00
jschoubben 087e17c799 Answer A-392: a seed asks a silent build seat once, and says so
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 11:24:49 +01:00
jschoubben 19f5ad86d2 Answer A-391: the indexer's start replay writes the view once, and says its length
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 04:03:00 +01:00
jschoubben 5d7a96fe66 Answer A-390: the verb revision's callers count an invokes of a single *, as grants reads it
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 03:19:13 +01:00
jschoubben 5aa4510f0f Answer A-389: before the catalog half is read, a module's call of another module's tool runs unmarked, logged
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 02:36:55 +01:00
jschoubben c1a647e9bb Answer A-388: the start path takes only an explicit read class; the broker's four reads are classed
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 02:22:16 +01:00
jschoubben 8dffde7f33 Answer A-387: before the catalog half is read, a read verb of a held definition runs; git is bootstrapped
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 02:20:39 +01:00
jschoubben 240f6401ce Answer A-386: a runner kept as it runs still gains the runner grants of what it carries
mesh/delivery ready: it is merged on the Approve
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 01:32:07 +01:00
jschoubben 77a6a9aa68 Answer A-385: a kept account is the union of the list in force and this pass's composition
mesh/delivery closed: a newer head of the same pull request
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 01:06:35 +01:00
jschoubben 9e619006c7 Answer A-384: a runner may make the ordered consumers its bundles hear new events on
mesh/delivery closed: a newer head of the same pull request
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 00:43:18 +01:00
jschoubben 8af69b2082 Answer A-383: a right every account carries reaches a kept account too
mesh/delivery closed: a newer head of the same pull request
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 00:22:48 +01:00
jschoubben 2c67b2e53b Answer A-382: every account may list stream names, which hearing an event starts with
mesh/delivery closed: a newer head of the same pull request
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 00:06:50 +01:00
jschoubben be264026b5 Answer A-381: grants' own account may list stream names, which its stream assertion starts with
mesh/delivery closed: a newer head of the same pull request
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 23:59:02 +01:00
jschoubben a95c0d6d98 Answer A-380: the runner's old-objects fallback uses the name grants creates
mesh/delivery closed: a newer head of the same pull request
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 23:18:26 +01:00
jschoubben c1065d9868 Answer A-379: the runner reaches a module's old objects by the name its membership gives, beside bindings
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 23:15:17 +01:00
jschoubben 0e9b6e5286 Answer A-377 and A-378: first-view tools pass the start path; the keeper may read the indexer's views
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 23:12:47 +01:00
jschoubben 64b9ffe8c1 Answer A-376: the keeper makes the catalog holder's own bus state before its catalog half is in
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 23:01:04 +01:00
jschoubben c5adb7fe48 Answer A-375: the gate's start path also lets the bindings' first view through
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 22:46:43 +01:00
jschoubben 61149124f8 Answer A-374: the seat verb withheld reads a small key beside the list
mesh/delivery closed: a newer head of the same pull request
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 22:10:26 +01:00
jschoubben 591297f02e Answer A-373: grants keeps its user list and pass in an object store, since they outgrow one bucket value
mesh/delivery closed: a newer head of the same pull request
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 22:00:46 +01:00
jschoubben e9a2aaf253 Answer A-371 and A-372: grants counts a seat stream it creates itself as empty, and the assigner asks Ready
mesh/delivery closed: a newer head of the same pull request
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 20:54:05 +01:00
jschoubben 904f5bfac5 Answer A-370: the indexer answers the catalog's first views at once, never behind a running take-in
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 20:53:47 +01:00
jschoubben da161cdbf1 Answer A-369: grants' catalog wait asks the client's Ready, as every part does
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 20:45:09 +01:00
jschoubben 916be3a63c Answer A-363 to A-368: G's first start composes rights from the trunk, builds unpublished packages at the source commit, and waits for nothing only G answers
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 20:34:47 +01:00
jschoubben f67c788c82 Merge pull request 'Design 47 G: the lead's answers A-353 to A-362 (G's start)' (#608) from design/47-G-lead-answers-30 into main
Reviewed-on: #608
2026-11-13 19:08:20 +00:00
jschoubben 4fd3612c56 Answer A-361 and A-362: call words obey the cycle rule; the start seat list holds mesh-delivery
mesh/delivery merged: source.main moved to novox/hq@f67c788c8242
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 17:44:13 +01:00
jschoubben 8531306165 Answer A-360: the indexer says each change of modules on its views family
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 17:31:03 +01:00
jschoubben b0d52a1119 Answer A-359: the gate's start path passes the four seat verbs alone
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 17:27:52 +01:00
jschoubben 14acd2b593 Answer A-353 to A-358: G's start breaks the runner's own wait, grants keeps its modules read, the SDK declares the verbs it calls
Found after G's merge: a G tool runner waits on itself, grants freezes once
G's indexer runs, the watchman does not build, gitea needs G's build runtime,
and the graph ordered the tool runner first because the SDK's calls were undeclared.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 17:25:39 +01:00
mesh-tools 2b39e39385 Merge pull request 'Playbook 07: hold a delivery-system release's push on a dry run with no item open' (#607) from playbook/07-dry-run-delivery into main 2026-11-13 13:49:14 +00:00
jschoubben 010a93d6bc Hold a delivery-system release's push on a dry run with no item open
mesh/delivery merged: source.main moved to novox/hq@2b39e39385b6
mesh/check checking 010a93d6bc69 on 2b39e39385b6
Milestone G was pushed with its dry run's take-in item still open; once
merged, the running indexer refused G's own indexer with the live seat
list, and its trunk builds waited on renamed packages only the take-in
publishes. Playbook 07 gains step 2b: the live take-in run whole, every
build against the published packages, the gate's merge path read for the
group, and a dry run with an open item is not a pass. The glossary gains
"dry run"; the playbooks page lists the step.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 14:26:22 +01:00
mesh-tools 0bbcf98baa Merge pull request 'Design 47 G: A-352, a bus module's running build counts while its newer build waits for the operator's yes' (#606) from design/47-G-lead-answers-29 into main 2026-11-13 12:10:51 +00:00
jschoubben 328ca1b320 Answer A-352: a bus module's running build counts while its newer build waits for the operator's yes
mesh/delivery merged: source.main moved to novox/hq@0bbcf98baa96
mesh/check checking 328ca1b32047 on 0bbcf98baa96
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 13:09:39 +01:00
mesh-tools 67960e12ba Merge pull request 'Design 47 G: A-350, the catalog's fill starts above every number the builder gave' (#605) from design/47-G-lead-answers-29 into main 2026-11-13 12:09:15 +00:00
jschoubben 258de07806 Answer A-351: the filled edges count the builder's numbers too; no digest where the builder kept none
mesh/delivery merged: source.main moved to novox/hq@67960e12ba4f
mesh/check being carried to 258de078064c on 67960e12ba4f | from aed903059436
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 13:05:30 +01:00
jschoubben 5dee91703f Answer A-350: the catalog's fill starts above every number the builder gave, published or not
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 5dee91703f2e on aed903059436
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 13:02:51 +01:00
mesh-tools aed9030594 Merge pull request 'Design 47 G: A-349, the pipeline runner's old forms accepted before G' (#604) from design/47-G-lead-answers-28 into main 2026-11-13 11:03:20 +00:00
jschoubben ca86c2d8e7 Answer A-349: the pipeline runner's old forms are accepted before G, as §529 names it
mesh/delivery merged: source.main moved to novox/hq@aed903059436
mesh/check being carried to ca86c2d8e7b7 on aed903059436 | from afdb26b05706
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 11:46:29 +01:00
mesh-tools afdb26b057 Merge pull request 'Design 47 G: A-343 to A-348, the third reader release before G' (#603) from design/47-G-lead-answers-28 into main 2026-11-13 10:45:27 +00:00
jschoubben 96307d5f56 Answer A-343 to A-348: the third reader release before G, its scope and its checks
mesh/delivery merged: source.main moved to novox/hq@afdb26b05706
mesh/check being carried to 96307d5f56fe on afdb26b05706 | from dc76022e04b8
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 11:34:39 +01:00
mesh-tools dc76022e04 Merge pull request 'Design 47 G: the lead's answers A-339 to A-342, met merging the zfs group into G' (#602) from design/47-G-lead-answers-27 into main 2026-11-13 08:54:30 +00:00
jschoubben 14b5b324a2 Answer A-342: the node-engine sets MESH_NODE for every process it runs
mesh/delivery merged: source.main moved to novox/hq@dc76022e04b8
mesh/check pass 14b5b324a258 on a7004d5e2ad8 | unit 43 run, 0 kept, 1 skipped | integration 43 run, 0 kept, 1 skipped | composition passed in 61s on 2…
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 09:17:36 +01:00
jschoubben 253c18c693 Answer A-341: a zfs device's finding in the writer's key form
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 09:16:08 +01:00
jschoubben 20a04f0226 Answer A-340: a process's bus may name what its module consumes; the writer's three events
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 09:10:36 +01:00
jschoubben 325bf80f19 Answer A-339: zfs's findings take G's writer over its keeper
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 09:08:48 +01:00
mesh-tools a7004d5e2a Merge pull request 'Design 47 G: the lead's answers A-323 to A-334, from the dry run of G on itself' (#601) from design/47-G-lead-answers-26 into main 2026-11-13 08:00:18 +00:00
jschoubben ed8b3bbd98 Answer A-338: f1-circuits' cache and Link2Pay's logs are class cache
mesh/delivery merged: source.main moved to novox/hq@a7004d5e2ad8
mesh/check pass ed8b3bbd98e7 on bba961f9fd86 | unit 43 run, 0 kept, 1 skipped | integration 43 run, 0 kept, 1 skipped | composition passed in 68s on 4…
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 08:52:09 +01:00
jschoubben 50c4980a49 A-337: the glossary's word, the manifest validator
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 02:47:38 +01:00
jschoubben b216d914f7 Answer A-337: the judge counts and finds declarers over the whole trunk case
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 02:47:09 +01:00
jschoubben e7e3691799 A-336 holds for every start of a pipeline, not only a take-in
mesh/delivery closed: a newer head of the same pull request
mesh/check pass e7e369179944 on bba961f9fd86 | unit 43 run, 0 kept, 1 skipped | integration 43 run, 0 kept, 1 skipped | composition passed in 66s on 4…
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 02:42:06 +01:00
jschoubben cbd32e3fa4 Answer A-336: a take-in heard before its branch's half starts with no steps
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 02:35:19 +01:00
jschoubben 712eca24ad Answer A-335: the ten repositories still on version 1 join G's form (the operator's yes)
mesh/delivery closed: a newer head of the same pull request
mesh/check pass 712eca24ad12 on bba961f9fd86 | unit 43 run, 0 kept, 1 skipped | integration 43 run, 0 kept, 1 skipped | composition passed in 69s on 4…
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 02:27:56 +01:00
mesh-tools bba961f9fd Merge pull request 'Design 42 zfs-owns-zfs: the lead's answers A-30 to A-45 met in develop and review (issue 1979)' (#600) from design/42-zfs-answers-2 into main 2026-11-13 01:27:30 +00:00
jschoubben 4a466efcac A-329, A-333: the glossary's word catalog
mesh/delivery closed: a newer head of the same pull request
mesh/check being carried to 4a466efcac84 on bba961f9fd86 | from a5eae7aa0a68
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 02:18:35 +01:00
jschoubben 5df4fb0ff6 Answer A-334: in a group take-in the changed runner is wanted on its own pass, first
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 02:12:58 +01:00
jschoubben e4145affa2 Answer A-333: package-only cycles and delivery edges into packages are not refused
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 02:06:52 +01:00
jschoubben 7c13ee5682 Answer A-332: a kind-4 edge keeps its first-process-resource source
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 02:02:20 +01:00
jschoubben 8bd11f7532 Design 42 zfs-owns-zfs: A-45, every long-running unit declares its health
mesh/delivery merged: source.main moved to novox/hq@bba961f9fd86
mesh/check being carried to 8bd11f7532e2 on bba961f9fd86 | from a5eae7aa0a68
2026-11-13 02:00:15 +01:00
jschoubben f9f78f8f36 Answer A-331: a cycle across steps is a cycle; amends 272 as A-323 built it
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 01:58:42 +01:00
jschoubben 9fa132e393 Answer A-330: the acting-cycle finding; the node-engine's want is held by no acting edge, other rules stand
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 01:53:08 +01:00
jschoubben a7831db516 Design 42 zfs-owns-zfs: A-43 no wait in a hand act, A-44 the stream-publish capability 2026-11-13 01:51:17 +01:00
jschoubben 04e259524f Answer A-329: the seed's left-out module raises seed-left-out until a seat builds it
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 01:49:50 +01:00
jschoubben a60e04ed47 Answer A-326 to A-328: the build-input cycle is allowed, a late registration places its pipelines, the runner's own pipeline is never held
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 01:49:27 +01:00
jschoubben 6f417f30e7 Correct A-324 as A-325: a bypassed step is still placed and said
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 01:49:07 +01:00
jschoubben 75149fb5f3 Answer A-324: an archive or upstream artifact has its steps bypassed; a module no seat builds is left out of the seed by name
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 01:48:25 +01:00
jschoubben ca142d4b98 Design 42 zfs-owns-zfs: A-42, a tools bundle publishes onto its own events stream by name 2026-11-13 01:46:09 +01:00
jschoubben 87fdd04e81 Answer A-323: the assigner and the node-engine are one step, the node-engine's want first
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 01:44:49 +01:00
jschoubben 230dc73bc1 Design 42 zfs-owns-zfs: A-41, the keeper publishes on its events stream's subject 2026-11-13 01:29:19 +01:00
jschoubben f7d066fb32 Design 42 zfs-owns-zfs: A-39 and A-40, met in develop 2026-11-13 01:10:19 +01:00
jschoubben 0f9ab08e2d Design 42 zfs-owns-zfs: A-38, a process's bus names what its module asks for in requires 2026-11-13 01:01:16 +01:00
jschoubben 53c407350f Design 42 zfs-owns-zfs: A-36 corrects A-30's remove, A-37 the root processes reach the bus through a keeper 2026-11-13 01:00:37 +01:00
jschoubben 4001fd3515 Design 42 zfs-owns-zfs: A-33 to A-35, met in develop 2026-11-13 00:53:58 +01:00
jschoubben be36341681 Design 42 zfs-owns-zfs: A-32 corrects A-10, findings in today's state form 2026-11-13 00:53:58 +01:00
jschoubben fec5bc42dc Design 42 zfs-owns-zfs: A-31, the run reads the ledger through its module's tool 2026-11-13 00:53:58 +01:00
jschoubben 27fd5ff860 Design 42 zfs-owns-zfs: A-30, the snapshots ledger in the ledger's own forms 2026-11-13 00:53:58 +01:00
mesh-tools a5eae7aa0a Merge pull request 'Design 42 zfs-owns-zfs: /etc/hostid by the apply, and the lead's answers A-1 to A-26 (issue 1979)' (#599) from design/42-zfs-hostid into main 2026-11-12 23:53:39 +00:00
jschoubben 4cb9efadae Design 42 zfs-owns-zfs: A-27 to A-29, met in develop
mesh/delivery merged: source.main moved to novox/hq@a5eae7aa0a68
mesh/check being carried to 4cb9efadae24 on a5eae7aa0a68 | from 283363d5cf3a
2026-11-13 00:28:08 +01:00
jschoubben 2c129789ff Design 42 zfs-owns-zfs: A-26, a module declares what another resource needs before it
mesh/delivery closed: a newer head of the same pull request
mesh/check pass 2c129789ffe1 on 283363d5cf3a | unit 43 run, 0 kept, 1 skipped | integration 43 run, 0 kept, 1 skipped | composition passed in 46s on 4…
2026-11-13 00:19:30 +01:00
jschoubben 8c98c27a5e Design 42 zfs-owns-zfs: A-25, the form search finds ${config-json} 2026-11-13 00:09:44 +01:00
mesh-tools 283363d5cf Merge pull request 'Design 47 G: lead answers A-321 and A-322, the watchman follows wants by seat' (#598) from design/47-G-lead-answers-25 into main 2026-11-12 23:07:47 +00:00
jschoubben 435fe73a0f Design 42 zfs-owns-zfs: the lead's answers to the prepare's 24 questions, each against the principles 2026-11-13 00:04:41 +01:00
jschoubben 04de5c3b30 Design 42 zfs-owns-zfs: the apply writes /etc/hostid and reads it back, as ADR 0679 version 17 says
No template writes the four binary bytes of /etc/hostid, so it is no resource
and the composer cannot see a second writer: the apply guards it by the pool's
label, reads it back, is unhealthy on a mismatch, and keeps the file on leave.
2026-11-12 23:59:15 +01:00
jschoubben 78fedf86aa Answer A-322: the watchman takes seat events per seat, the branches follower takes registration-changed
mesh/delivery merged: source.main moved to novox/hq@283363d5cf3a
mesh/check being carried to 78fedf86aa81 on 283363d5cf3a | from e97647cd1805
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 23:46:10 +01:00
jschoubben cc4da43b3c Answer A-321: the watchman awaits a followed state by its seat and keeps seeded keys until the holder is read
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 23:41:03 +01:00
mesh-tools e97647cd18 Merge pull request 'Design 47 G: A-319 and A-320, the check runs unit and integration tests only' (#597) from design/47-G-lead-answers-24 into main 2026-11-12 22:37:17 +00:00
mesh-tools b9cd0bc492 Merge pull request 'Design 42: the zfs module owns a node's ZFS and changes nothing that is not set (ADR 0679, issue 1979)' (#596) from design/42-zfs-owns-zfs into main 2026-11-12 22:34:20 +00:00
jschoubben 06fd6f26b1 Test 36's end-to-end proof belongs to the test lab, not to a live node
mesh/delivery merged: source.main moved to novox/hq@e97647cd1805
mesh/check being carried to 06fd6f26b1bf on e97647cd1805 | from b9cd0bc492ac
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 23:21:35 +01:00
jschoubben dec17874ab Test 36 is proven by each module's integration test and one rehearsal; no check starts real builds
The operator, 2026-11-12: an integration test mocks every external dependency and tests the internal wiring.
Withdraws section 637 and A-315 (A-320).

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 23:21:12 +01:00
jschoubben 224348ff4d Design 42 zfs-owns-zfs: answer review round 1 against ADR 0679 version 11
mesh/delivery merged: source.main moved to novox/hq@b9cd0bc492ac
mesh/check being carried to 224348ff4d69 on b9cd0bc492ac | from 9ebf6e58f0d7
Cites the record's final clauses, drops the catalog check and every
write of the package's files, and writes the lead's answers as design
lines: a run that never waits on a scrub, waits ended by events,
ZFS snapshots kept in the ledger before any removal, hand acts as unit
instances, subjects per kind, the follower's findings, the readers of
the new manifest words and one node-engine integration test.
2026-11-12 23:20:51 +01:00
jschoubben 4d7fc66110 Answer A-319: entry-again also asks the shadow's entries again
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 23:13:12 +01:00
mesh-tools 9ebf6e58f0 Merge pull request 'Design 47 G: lead answer A-318, what keeps its module form in G' (#595) from design/47-G-lead-answers-23 into main 2026-11-12 22:12:37 +00:00
jschoubben 071192e586 Answer A-318: what keeps its module form in G, listed
mesh/delivery merged: source.main moved to novox/hq@9ebf6e58f0d7
mesh/check checking 071192e586b1 on 9ebf6e58f0d7
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 23:08:51 +01:00
jschoubben f26c8afc20 Design 42 zfs-owns-zfs: schedule the run in list form, so nothing waits on the calendar fix
Today's node-engine writes a cron step as an invalid calendar but a
minute list as a valid one, so the scheduled run declares
0,15,30,45 and the milestone no longer waits on another session's fix.
2026-11-12 23:02:13 +01:00
jschoubben 0ea81e0e96 Design 42 zfs-owns-zfs: answer the open question in the node-engine, name issue 1979
The lead answered that a resource following a set value and one line
per list entry are built in the node-engine in this milestone, so the
module's files, units and handlers are placed only once their value is
set, as ADR 0679 holds. The cron-to-calendar fix leaves the milestone
and stays an ordering edge the scheduled run waits on.
2026-11-12 22:57:56 +01:00
mesh-tools 1de7bc38c8 Merge pull request 'Design 47 G: lead answer A-316, a candidate carries the parts of the modules it adds' (#594) from design/47-G-lead-answers-22 into main 2026-11-12 21:55:25 +00:00
jschoubben 5c766b7c8c Answer A-317: the assigner's main process alone writes a proposal's candidates
mesh/delivery merged: source.main moved to novox/hq@1de7bc38c8d9
mesh/check checking 5c766b7c8ce2 on 1de7bc38c8d9
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 22:54:24 +01:00
jschoubben 294a30b82b A-316: the assigner's seat defines the two properties itself, held to the want's by a fixture
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 294a30b82b7a on aef65c2f1e7a
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 22:46:38 +01:00
jschoubben f6cb279eea Answer A-316: a candidate carries the parts of the modules it adds
mesh/delivery closed: a newer head of the same pull request
mesh/check checking f6cb279eeaec on aef65c2f1e7a
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 22:45:27 +01:00
mesh-tools aef65c2f1e Merge pull request 'Design 47 G: lead answer A-313, over-bound step answers in the steps state's own objects store' (#593) from design/47-G-lead-answers-21 into main 2026-11-12 21:41:15 +00:00
jschoubben 6772904668 Design 42: the zfs module owns a machine's ZFS and changes nothing unset (ADR 0679)
Adds row 12 and a section to the main file, and the milestone part
zfs-owns-zfs with numbered lines and its three prerequisites, so a
builder takes ownership of ZFS's packages, files, units and one pool's
devices, properties and scheduled ZFS snapshots without a choice of
its own. Leaves one design question open (a resource that follows a
value only once it is set). Adds ZFS snapshot to the glossary beside
the two snapshots it already names.
2026-11-12 22:32:54 +01:00
jschoubben fdac1264ac Answer A-315: test 36 takes the builds of before G from the mesh and starts them as every module starts
mesh/delivery merged: source.main moved to novox/hq@aef65c2f1e7a
mesh/check checking fdac1264acd0 on aef65c2f1e7a
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 22:29:02 +01:00
jschoubben 3acb50433a Answer A-314: the build modules' steps state moves into requires
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 3acb50433aaf on 0bf9465cbab6
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 22:28:07 +01:00
jschoubben a6d455f59c Answer A-313: over-bound step answers live in the steps state's own objects store
mesh/delivery closed: a newer head of the same pull request
mesh/check checking a6d455f59cfb on 0bf9465cbab6
A-309 named an age option the objects template does not have.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 22:26:49 +01:00
mesh-tools 0bf9465cba Merge pull request 'Design 47 G: lead answers A-306 to A-309 from review round 2' (#592) from design/47-G-lead-answers-20 into main 2026-11-12 21:25:58 +00:00
jschoubben aad0eafa79 Use the glossary's words in A-311
mesh/delivery merged: source.main moved to novox/hq@0bf9465cbab6
mesh/check checking aad0eafa793e on 0bf9465cbab6
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 22:20:55 +01:00
jschoubben 5744cc0472 Answer A-311 and A-312, and give A-310's shape
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 5744cc047254 on 4eba1f451be9
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 22:20:34 +01:00
jschoubben 47bb7409be Answer A-310: a compose request's manifest names its fingerprint beside its digest
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 47bb7409be46 on 4eba1f451be9
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 22:19:36 +01:00
jschoubben 383f21ed49 Answer A-309: a build module's outputs objects live as long as their step keys
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 383f21ed4906 on 4eba1f451be9
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 22:03:26 +01:00
jschoubben 1b9c63e947 Answer A-307 and A-308: the node-engine gains no uses, and its watch of the indexer's modules goes
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 22:02:57 +01:00
jschoubben edb7030102 Answer A-306: a module G creates is held by the test budget, not by section 626
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 22:00:16 +01:00
mesh-tools 4eba1f451b Merge pull request 'Design 47 G: lead answer A-304, the checker puts a phase's asks at once' (#591) from design/47-G-lead-answers-19 into main 2026-11-12 20:51:13 +00:00
jschoubben dce214b7f5 Answer A-305: the pipeline runner's health is its unit, like its siblings'
mesh/delivery merged: source.main moved to novox/hq@4eba1f451be9
mesh/check checking dce214b7f566 on 4eba1f451be9
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 21:47:56 +01:00
jschoubben a0147f94af Answer A-304: the checker puts a phase's asks at once and holds no step
mesh/delivery closed: a newer head of the same pull request
mesh/check checking a0147f94af01 on a70316b51236
Try 4 and 5 ran their steps one at a time because the checker waited on each ask before putting the next.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 21:35:48 +01:00
mesh-tools a70316b512 Merge pull request 'Design 47 G: correct lead answer A-303; playbook 07: the lead reads what an answer names first' (#590) from design/47-G-lead-answers-18 into main 2026-11-12 19:36:39 +00:00
jschoubben 26faa9981f Playbook 07: the lead reads what an answer names before it answers
mesh/delivery merged: source.main moved to novox/hq@a70316b51236
mesh/check being carried to 26faa9981fab on a70316b51236 | from ea3b790f1dc2
Three lead answers in one day named a structure from memory and needed a correction once a developer read the code.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 20:32:42 +01:00
jschoubben a4f9d43037 Correct A-303: the reach's watches use the seat form, only the stuck key takes the real bucket
mesh/delivery closed: a newer head of the same pull request
mesh/check checking a4f9d43037e0 on ea3b790f1dc2
The view's kept reach holds no bucket name, so no kept entry depends on the holder's real bucket.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 20:31:31 +01:00
mesh-tools ea3b790f1d Merge pull request 'Design 47 G: the lead's answers A-298 to A-303' (#589) from design/47-G-lead-answers-17 into main 2026-11-12 19:07:45 +00:00
jschoubben 9a14624b69 Answer A-303: seat-form pictures; the stuck key and reach history name the holder's real bucket at run time
mesh/delivery merged: source.main moved to novox/hq@ea3b790f1dc2
mesh/check being carried to 9a14624b6926 on ea3b790f1dc2 | from 023a355cdb2c
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 20:00:56 +01:00
jschoubben d02f00bce7 Answer A-302: the indexer follows assignments through FollowSeat too; the holder loop goes
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 20:00:56 +01:00
jschoubben 480a857635 Answer A-301: the view's answers tool is the SDK's first-view tool with its callers list
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 20:00:56 +01:00
jschoubben 4fa5891697 Correct A-300: the view's tools keep assigner_read_wants, since a first view does not read by key or history
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 20:00:56 +01:00
jschoubben f522c2114d Answer A-300: the view's tools read the wants through the holder's first-view tool
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 20:00:56 +01:00
jschoubben 5c98c86d70 Answer A-299: the view's answers take one key form per asks kind; the kinds are seven
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 20:00:56 +01:00
jschoubben b75c04f038 Answer A-298: one shared follower of the seat-holders view in the catalog seat's client
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 20:00:56 +01:00
mesh-tools 023a355cdb Merge pull request 'Design 47 G: §717 (the views are named by their seats) and the lead's answers A-294 to A-297' (#588) from design/47-G-lead-answers-16 into main 2026-11-12 17:59:25 +00:00
jschoubben b03f5193b8 Design 47 G §717: a follower hears its seat's holder from the seat-holders view
mesh/delivery merged: source.main moved to novox/hq@023a355cdb2c
mesh/check being carried to b03f5193b8c4 on 023a355cdb2c | from 7247b92fd6b1
A seat's view is said on its holder's module subject, so a follower must know
the holder; asking for it every 5 seconds was polling and kept a holder that
moved. It now follows the seat-holders view as A-295's holder function does,
reached from the catalog half's claim, and re-follows when the holder changes.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 18:54:41 +01:00
jschoubben 80863372dc Design 47 G §717: the status view's and the assigner's views are named by their seats
Developer J27 met, building A-210, a status view that claims no seat and an
assigner holding two seats, both followed by the teller by module name. ADR
0540 §1 already names the seat mesh-delivery-view; G defines it with its one
view, puts the assigner's asks and wants on mesh-wants, and has a follower find
the holder in the background so no start stops for it.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 18:54:41 +01:00
jschoubben 01fdde3701 Answer A-297: the runner's step ask id takes the usual form, repeatable per placement
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 18:54:41 +01:00
jschoubben ef76908e0d Answer A-296: seat forms in the manifests, own buckets from the credential's module
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 18:54:41 +01:00
jschoubben eed5be9244 Answer A-295: a callers list names a seat, resolved from the seat-holders view the SDK follows
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 18:54:41 +01:00
jschoubben 12c9c1efcf Answer A-294: mesh-wants' step keeps no token; step-progress names the caller its definition lists
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 18:54:41 +01:00
mesh-tools 7247b92fd6 Merge pull request 'Design 50: the own resolver's file waits longer than its pass over a silent mesh resolver (ADR 0678, issue 1748)' (#587) from design/50-resolver-wait into main 2026-11-12 17:51:40 +00:00
jschoubben ce0287dd2d Keep design 50 to what ADR 0678 asks, and hold the wait at 3 s per try
mesh/delivery merged: source.main moved to novox/hq@7247b92fd6b1
mesh/check being carried to ce0287dd2d87 on 7247b92fd6b1 | from 0d04a16560e4
A restart of resolved and a timed ask at the own resolver answered in 44-46 ms
with the first mesh resolver silent, so no read catches the pass today: the
value stays ADR 0678's until a read of resolved's server switches exists, and
the proof is the Go build steps at the next silence. The phases table and the
as-built notes go back to main: a to-be design states no live state.
2026-11-12 18:06:41 +01:00
jschoubben 067de23181 Give the own resolver's file a wait longer than its pass over a silent mesh resolver
ADR 0678: on a machine holding node-resolver the file names the own resolver
alone, so a program gave up after about 2 s while resolved still waited on a
silent first mesh resolver (issue 1748). Design 50 section 2 now gives the
file timeout:3 attempts:2 and how the value follows the measured pass; the
new milestone part resolver-wait holds the lines that build it, putting the
design in the shape of a main file and milestone parts.
2026-11-12 18:05:05 +01:00
mesh-tools 0d04a16560 Merge pull request 'Design 47 G: the lead's answer A-293' (#586) from design/47-G-lead-answers-15 into main 2026-11-12 16:24:57 +00:00
jschoubben 7c533965bf Amend A-293: a later done end deletes the refused key a failed end wrote
mesh/delivery merged: source.main moved to novox/hq@0d04a16560e4
mesh/check checking 7c533965bfa6 on 0d04a16560e4
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 17:11:35 +01:00
jschoubben f99c0c9e29 Amend A-293: the newest build is the last trunk build-ended event heard for the module
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 17:09:10 +01:00
jschoubben 66d37b8f30 Answer A-293: in by-entries mode a failed newest build is said as a refused key on the builder's build-ended event
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 17:05:37 +01:00
mesh-tools 852a0d1163 Merge pull request 'Design 47 G: the lead's answers A-291 and A-292' (#585) from design/47-G-lead-answers-14 into main 2026-11-12 16:00:57 +00:00
jschoubben cbbf170718 Answer A-292: a node-engine's failed say is said again within the link, loudly
mesh/delivery merged: source.main moved to novox/hq@852a0d1163d3
mesh/check checking cbbf17071862 on 852a0d1163d3
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 16:53:42 +01:00
jschoubben 3c357ee1f1 Answer A-291: a process receives a chunked seat answer through one SDK helper
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 16:46:26 +01:00
mesh-tools 43612bf1be Merge pull request 'Design 47 G: the lead's answers A-287 and A-288' (#582) from design/47-G-lead-answers-13 into main 2026-11-12 15:34:11 +00:00
mesh-tools 5f35cd2e32 Merge pull request 'Design 47: the lead's answers for a placed module whose build failed (a small fix on main, issue 1966)' (#584) from design/47-unpublished-placed-module into main 2026-11-12 15:28:10 +00:00
jschoubben 048545b266 Answer A-290: a step answer over the steps state's bound is kept as an object the key names
mesh/delivery merged: source.main moved to novox/hq@43612bf1be0a
mesh/check checking 048545b266bb on 43612bf1be0a
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 16:27:32 +01:00
mesh-tools 7792e96670 Merge pull request 'Design 39 parts: the lead's answers D3 (a list of a place a secret is kept, for §15) and D4 (the database §13 and §14 read)' (#583) from design/39-list-secret-place into main 2026-11-12 15:27:07 +00:00
jschoubben 34660dd256 Correct A-289: the unpublished count holds no package, since no reachable case leaves a reserving build's package unpublished
mesh/delivery closed: a newer head of the same pull request
mesh/check being carried to 34660dd2565f on 7792e9667042 | from 63ccbe512bc0
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 16:17:06 +01:00
jschoubben 84faadbe38 Answer A-289: a build that reserves no version leaves its package done; a package is published by its own language's seat
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 84faadbe382e on 63ccbe512bc0
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 16:12:45 +01:00
jschoubben 11d257516a Design 47 fix: U8, the refused key is written on the failed build's event
mesh/delivery merged: source.main moved to novox/hq@5f35cd2e324a
mesh/check checking 11d257516a51 on 5f35cd2e324a
2026-11-12 15:56:00 +01:00
jschoubben 99d01964ef Design 47: the lead's answers for a placed module whose build failed, a small fix on main 2026-11-12 15:49:05 +01:00
jschoubben da6c3ab163 Answer A-287 and A-288: a kept announcement names every declared state; a refusal's test holds its meaning
mesh/delivery closed: a newer head of the same pull request
mesh/check pass da6c3ab16305 on 63ccbe512bc0 | unit 43 run, 0 kept, 1 skipped | integration 43 run, 0 kept, 1 skipped | composition passed in 52s on 4…
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 15:47:09 +01:00
jschoubben 1995bd1247 Design 39 parts: the lead's answer D4, the database §13 and §14 read is the one postgres made
mesh/delivery merged: source.main moved to novox/hq@7792e9667042
mesh/check being carried to 1995bd1247be on 7792e9667042 | from 63ccbe512bc0
2026-11-12 15:45:59 +01:00
mesh-tools 63ccbe512b Merge pull request 'Design 39 bus-and-switch: the lead's answer C5, how a carried switch is read' (#581) from design/39-carried-switches into main 2026-11-12 14:42:06 +00:00
jschoubben 1a6a72dc02 Design 39 parts: the lead's answer D3, a list of a place a secret is kept, for §15's check 2026-11-12 15:41:47 +01:00
jschoubben 45ee24759b C5 cites the principles that settle it: failure is loud, the simplest thing
mesh/delivery merged: source.main moved to novox/hq@63ccbe512bc0
mesh/check checking 45ee24759b07 on 63ccbe512bc0
2026-11-12 15:37:49 +01:00
jschoubben 8326a3b57d Design 39 bus-and-switch: the lead's answer C5, how a carried switch is read 2026-11-12 15:37:25 +01:00
mesh-tools e81a8d62a5 Merge pull request 'Design 47 G: the lead's answers A-284 to A-286' (#580) from design/47-G-lead-answers-12 into main 2026-11-12 14:17:58 +00:00
jschoubben 41dd30fe43 Amend A-286: a check step that errors after its fetch merged still answers its fetch
mesh/delivery merged: source.main moved to novox/hq@e81a8d62a591
mesh/check checking 41dd30fe436e on e81a8d62a591
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 15:16:53 +01:00
jschoubben c7850092fa Correct A-285: the group's packages are group-packages, since packages already holds the Go versions
mesh/delivery closed: a newer head of the same pull request
mesh/check checking c7850092fa08 on e1a9a0f2d238
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 15:16:30 +01:00
jschoubben 9dfde6fca1 Answer A-285 and A-286: a fetch carries the group's packages as a list; a failed test never hides the validator
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 9dfde6fca119 on e1a9a0f2d238
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 15:15:44 +01:00
jschoubben a8da15caff Answer A-284: a group's check builds a TypeScript member against the group's own packages
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 15:08:26 +01:00
mesh-tools e1a9a0f2d2 Merge pull request 'Design 47 G: the lead's answers A-281 to A-283' (#579) from design/47-G-lead-answers-11 into main 2026-11-12 14:04:49 +00:00
jschoubben de676868c6 Correct A-282: the step bound moves with the step by a revision-checked update, never a delete
mesh/delivery merged: source.main moved to novox/hq@e1a9a0f2d238
mesh/check being carried to de676868c65a on e1a9a0f2d238 | from a412c0760ba4
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 14:36:17 +01:00
jschoubben da9b672747 Answer A-282 and A-283: a step bound is created once; a template state's max-mib reaches its bucket
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 14:36:17 +01:00
jschoubben 14f908926e Answer A-281: the switch runs once and marks it, so §716's deliveries never become records at a start
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 14:36:17 +01:00
mesh-tools a412c0760b Merge pull request 'Design 25 bus-state: the lead's answer L1, a merged candidate's manifest is newly accepted' (#578) from design/25-merged-verdict into main 2026-11-12 12:28:30 +00:00
jschoubben ff30ac166e Design 25 bus-state: the lead's answer L1, a merged candidate's manifest is newly accepted
mesh/delivery merged: source.main moved to novox/hq@a412c0760ba4
mesh/check being carried to ff30ac166ecc on a412c0760ba4 | from a45b31fdaf2e
2026-11-12 13:20:17 +01:00
mesh-tools a45b31fdaf Merge pull request 'Design 39 parts: the licence manager is built of its parts, and the finished carry-over and its database leave' (#576) from design/39-parts into main 2026-11-12 12:08:26 +00:00
mesh-tools 5235c00630 Merge pull request 'Design 47 G: §716 (a group's members and bases before the take-in) and the lead's answers A-274 to A-280' (#577) from design/47-G-lead-answers-10 into main 2026-11-12 12:05:39 +00:00
jschoubben 6141d7b5d1 Design 39 parts: the lead's answers D1 (the vault reading) and D2 (§17's wording)
mesh/delivery merged: source.main moved to novox/hq@a45b31fdaf2e
mesh/check checking 6141d7b5d177 on a45b31fdaf2e
2026-11-12 12:21:10 +01:00
jschoubben 2132bb711d Merge §716 (group members before take-in) into the lead answers; A-279 in its form after §716
mesh/delivery merged: source.main moved to novox/hq@5235c0063024
mesh/check being carried to 2132bb711d4e on 5235c0063024 | from f9bdd3b1d1ce
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 11:55:00 +01:00
jschoubben f74f9b19be Design 47 G §716: the gate keeps a group's members and their bases from the announcement
Before any take-in the gate held no group: its records open at the take-in, and from G it writes
`merges` no more, so the forge bridge's §715 read of each member's base through `groups` had
nothing to answer from. ADR 0666 §13 has the gate form the group; §716 keeps it in the states
`deliveries` and `groups` the gate already holds (§613), heard on the seat git's pull-updated,
pull-merged and pull-closed, and says who deletes each key and how `groups` answers.
A-236 now points to it, and A-279 is carried over from the answers branch in the form §716 makes
it, its Approve-entry form dropped.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 11:54:16 +01:00
jschoubben ac294e7b86 Design 39 parts: build the licence manager as four parts of one manifest and let the finished carry-over leave
mesh/delivery closed: a newer head of the same pull request
mesh/check pass ac294e7b8628 on f9bdd3b1d1ce | unit 43 run, 0 kept, 1 skipped | integration 43 run, 0 kept, 1 skipped | composition passed in 91s on 4…
The operator asked for the manager built as clean as possible, one manifest of several parts. The seat's verbs stay
on the runtime of its own, since a process account answers none; the tools that only read get a bundle of their own
so they answer while the manager fails; the carry-over ran live, so its code and the store database's and grant-key's
requirements leave now and retire on the operator's Approve. The glossary names the two senses of part.
2026-11-12 11:49:19 +01:00
jschoubben 3c40a6e6c8 A-280: the code name in a code span
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 11:47:35 +01:00
jschoubben 77379f62ce Answer A-280: a bundle's findings follow its membership's finding-events stream
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 11:47:17 +01:00
jschoubben 15d73fe09c A-279's form that stands: the base is kept on the merges entry the Approve makes, copied at take-in
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 11:42:50 +01:00
jschoubben b9f7ff6054 Correct A-279 again: the base comes from the git seat's pull-updated, kept on the pull's record entry
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 11:40:20 +01:00
jschoubben 3d4691c544 Correct A-279: a member's base is read from its delivery, which the gate already keeps
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 11:38:26 +01:00
mesh-tools f9bdd3b1d1 Merge pull request 'Design 20 and playbook 06 say what the manifest validator accepts, and how a module is built of parts' (#575) from design/20-manifest-as-judged into main 2026-11-12 10:38:25 +00:00
jschoubben 6fc3ccda4b Answer A-279: a member's base is its pull request's base from the forge message
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 11:37:27 +01:00
jschoubben 658d33892c Write design 20 and playbook 06 from what the manifest validator accepts
mesh/delivery merged: source.main moved to novox/hq@f9bdd3b1d1ce
mesh/check checking 658d33892c5e on f9bdd3b1d1ce
The module-development documents described a manifest the mesh no longer
reads: four languages where the builder builds two, a Go bundle with no
system, a scheduled process the guide never said how to write, the old
kept-data sections as the norm, and the controller as the one refusing.
They now name each part of a module and its manifest form as the
manifest validator, the builder and the node-engine read it, and the
playbook lists where those parts still disagree, so an author writes
the form every part takes.
2026-11-12 11:36:48 +01:00
jschoubben efcc065f8f Answer A-278: the seat-definition function lives once in mesh-sdk
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 11:28:25 +01:00
jschoubben f9aa43bf09 Answer A-277 in the glossary's word: the manifest validator
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 11:26:13 +01:00
jschoubben 5266949a59 Answer A-277: the approvals state's 64 MiB is a declared max-mib the judge bounds
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 11:25:55 +01:00
jschoubben 3631a151a3 Answer A-276: a pipeline-waits finding names its awaited fingerprint in its evidence
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 11:19:18 +01:00
mesh-tools 216bc8ad8b Merge pull request 'Design 39 bus-and-switch: C4, room and the switch read the weekly window alone' (#574) from design/39-licence-weekly-only into main 2026-11-12 10:18:42 +00:00
jschoubben e98e675673 Answer A-275: the node-engine reads invokes with the SDK's one reader
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 11:06:14 +01:00
jschoubben c94a65f2d8 Answer A-274: the finding writer takes its subjects from the part's own binding
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 11:00:39 +01:00
jschoubben 6738de67e3 Design 39 bus-and-switch: C4, room and the switch read the weekly window alone
mesh/delivery merged: source.main moved to novox/hq@216bc8ad8b26
mesh/check checking 6738de67e30b on 216bc8ad8b26
2026-11-12 10:50:52 +01:00
mesh-tools 01ecd2426a Merge pull request 'Design 47 G: §708 to §715, a requirement's provider, the revert ask, the validation before take-in and non-trunk branches' (#573) from design/47-G-AS14-AS17 into main 2026-11-12 09:48:23 +00:00
jschoubben 7540c9aa6b Shorten §710's live option to the router's 24-character bound
mesh/delivery merged: source.main moved to novox/hq@01ecd2426aa8
mesh/check checking 7540c9aa6b30 on 01ecd2426aa8
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 10:34:52 +01:00
jschoubben 9fc2bd73fb Answer IX5 to IX7 in design 47 G: the validation's run, its pending wait, and every branch's merges and groups
A-213 sent the validation before take-in and the per-branch take-in to design lines: the indexer needs
the run's job and verdict, what holds a revision while the run is out, and how a branch other than
the trunk gets its merges and its groups, none of which a line said.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 10:34:52 +01:00
jschoubben 09c9dc49f7 Answer IX8 in design 47 G: an acting rule gives kind 5 from its holder to the entries it acts on
The indexer writes every edge of the catalog graph, and kind 5 had no line saying which steps give it,
between which artifacts, or what fills a catalog entry's acts, which the runner and the builder read.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 10:34:52 +01:00
jschoubben 29b498c59d Answer AS14 and AS17 in design 47 G, so the assigner resolves providers and asks a held revert without choosing
§708 says the named seat is found by its definition's delivers and its holder from the placements' holds, so no
entry field is added for it; §709 carries the manifest's contributes into the catalog entry and gives the edge kind
contribution its contract meaning; §710 writes the held revert's ask in the backup ask's shape, with one message to
the operator.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 10:34:33 +01:00
mesh-tools 1f368771f6 Merge pull request 'Design 47 G: the lead's answers A-148 to A-273' (#572) from design/47-G-lead-answers-9 into main 2026-11-12 09:28:54 +00:00
mesh-tools 9d82c2dee8 Merge pull request 'Design 39 bus-and-switch: C1, the licence manager runs as its own account, service and tools in its own runtime' (#571) from design/39-licence-own-process into main 2026-11-12 09:28:00 +00:00
jschoubben 162f0520a3 Answer A-273 (corrects A-272): the gate channel reads the router's record by §700's one path
mesh/delivery merged: source.main moved to novox/hq@1f368771f698
mesh/check checking 162f0520a3d1 on 1f368771f698
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 10:18:46 +01:00
jschoubben 3b383de72e Design 39 bus-and-switch: C3, the manager's logs in the logs section main issues
mesh/delivery merged: source.main moved to novox/hq@9d82c2dee8d7
mesh/check being carried to 3b383de72e5b on 9d82c2dee8d7 | from 2d8ff36d03ab
2026-11-12 10:18:38 +01:00
jschoubben c8c6f4344d Answer A-270 to A-272: the approvals state's key lifetime, the runner's approvals answer, the gate channel's path
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:56:12 +01:00
jschoubben 220d2fbe69 Answer A-268 (corrects A-263) and A-269: the Go module is read where it is built; a push's head is its merge
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:55:02 +01:00
jschoubben e58be12323 Answer A-267: the composition step's progress names the runner as its asker
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:53:17 +01:00
jschoubben 5f6d71da21 Answer A-266: no holder names the gate's approvals verb
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:51:28 +01:00
jschoubben fa839454f6 Answer A-265: the tool runner answers a bundle's marked seat verb as AnswerSeat does
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:50:04 +01:00
jschoubben da260f0835 Answer A-264: a marked verb's additions are made where every definition is resolved
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:44:44 +01:00
jschoubben 9de6b0fb15 Answer A-261 to A-263: a request's seats by digest, the step's beat, a Go bundle's package
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:44:29 +01:00
jschoubben 5b39ffcfd0 Answer A-260: the trunk's head for §298's third edge is the highest held source revision
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:42:07 +01:00
jschoubben 1ce07690a4 Answer A-258 and A-259: §298's order edges name seats and are acting waits
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 1b37bb8d29 Answer A-257: the tool runner sends a bundle's chunked answer
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 57b261840b Correct A-251: the finding id is an escaped key name
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 70bfb72c78 Answer A-255: the process gate's bound key, header and act
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben ff669cc720 Answer A-254: a run's step-ended carries its answer
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 491e606472 Answer A-253: a chunked answer reaches a bundle as file
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben a7e339d7df Answer A-252: the composition step's machines, cases and asks
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben d40854a073 Answer A-251: the branch-unprotected finding's scope and id
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 637df7d374 Answer A-250: delivered-again is an ask the assigner's process judges
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 7e9bb2dab4 Answer A-249: the tool runner takes a chunked answer whole for a bundle
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 20e3e1a3cd Answer A-248: the run asker names its asker
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 41b2345ba4 Answer A-247: a validation says it was accepted; its answer comes in step-ended
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben c80b5eedd2 Answer A-246: delivery waits kept in their own state
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 52dc32cb07 Answer A-245: order edges under rule 7; state forms bump the version
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 2904b60c1e Answer A-244: wait held is a header; the held answer a field of its own
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 3b309fa61e Answer A-243: one composition request per machine; every run input any size
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 534fd88be4 Answer A-242: tiers from the assigner's difference; the view keeps waits
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 92358ddfd7 Answer A-241: the validation always judges against the whole seat list
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 0363e6f5f1 Answer A-240: the assigner hears its run's step-ended
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben a50c26ecea Answer A-239: the composition says the withheld subjects
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 88c44c095e Answer A-238: a run ask may name no head
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 04955c3112 Answer A-237: a run's input is any size, served in chunks
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben eba38e5ed9 Answer A-236: pushed's head and before; groups member gains base
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben b69d526139 Answer A-235: a run's end is said by the runner as a group-ended
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 653d2a84d9 Answer A-234: a catalog revision names its definitions
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 777bf7d281 Answer A-233: an age-kept stream is read whole at every start
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben f8986a5541 Answer A-232: the validation run rides the check queue with the usual id
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 1c29c4bc56 Answer A-231: an asker names its queue in invokes
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 24a0fc7272 Answer A-230: a restore point names the bus names it took
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 931c0878c1 Answer A-229: an entry's requires names the optional ones too
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 0dbff50da4 Answer A-228: the gate reads everything through interfaces in its own terms
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben e8a2134d94 Answer A-227: merged gains base, as §714 says; A-221 and A-223 withdrawn
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 96404d8acf Answer A-225 and A-226; code-span a module name in A-224
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 091551e053 Answer A-224: one approval gate in mesh-sdk for both gates
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 3f0f6483c8 Answer A-223: the pull request's own branch is head-branch
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 4fff5cdfab Answer A-222: a failed adopted event is asked again; runs taken up at start
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben ae6407fb71 Answer A-221: branch is the watched branch on every forge message
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben d4a14a7765 Answer A-220: the serving parts widens compares
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 1fa531268b Answer A-219: the gate takes the operator channel as an interface; only Act moves
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben beac2c0170 Answer A-218: pipeline-waits clears when the new runner runs healthy
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben ba7e8a2dfb Answer A-217: what a revert is, and where the running manifest comes from
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben b85f659f1a Answer A-216: build.ended keeps its last end per fingerprint with no age bound
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben fffad9f578 Answer A-214 and A-215: fill through state.info; what widens
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 5f761c16cd Answer A-213: the indexer asks the validation run; the rest to design lines
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 69fdbc7cb3 Answer A-212: kind 2 is a needs reference; kind 5 to a design line
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben fbb60b952c Answer A-211: the assigner's put waits in a state of their own
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben a56c9b6262 Answer A-210: other modules found as seat holders when called; callers by seat
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben ab03e427f4 Answer A-209: a digest in a key is escaped; test states refuse what the bus refuses
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben af25c1424f Answer A-208: the indexer writes the edges; every branch takes in as the trunk does
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 456a1eae45 Answer A-207: the runner's recoveries state; widens from revision and grants-for
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 18ecf1c47f Answer A-206: the runner's release verb, its wait finding and clock
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben d60302b2bd Answer A-205: grants-for reads its candidate through revision
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 6e65fe2246 Answer A-204: the assigner keeps its said put waits on the bus
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben fc7e52c404 Answer A-203: the forms of the withheld path
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 98d7be07fd Answer A-202: a pipeline says the publish that started it
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 7843f56522 Answer A-201: the assigner keeps a run's candidate graph until the run ends
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 8e767e10fb Answer A-200: a record joins its take-in by its milestone
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben e0f23683b0 Answer A-198 and A-199: the act's form in mesh-sdk; AdoptEvent for the candidates hook
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 9adfad1108 Answer A-197: the node-engine raises its own findings, the watchman reads none of its state
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 24df2be69a Answer A-196: an empty status never asks the operator for approval
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 2188dfaffe Answer A-195: the runner's pipeline wait
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 19a1d9342e Answer A-194: the indexer's runs get a read and a drop tool
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 18a5617fa4 Answer A-193: how a run is kept, placed and said
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 39b4149687 Answer A-192: the watchman hears waits and running, reads no other state
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 88e0ca6f2d Answer A-191: a failed pipeline with no known author has no owner
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben d01e1121f8 Answer A-190: the indexer's kept calls are open while what they serve stands
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 0d153c98e0 Answer A-189: version-delivered and version-released read whole at start
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 92709ec311 Answer A-188: a take-in writes its entries into the gate's record
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 2f5268d97a Answer A-187: the consumer ledger keeps a message's first delivery time
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 0a10272f3d Answer A-186: the seat server takes the definition from its caller's seat list
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben ae6d3ddecc Answer A-185: the catalog client hands a candidate's revision to a hook
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 8834af8bd0 Answer A-184: main's subject keeps the checker's asks until it goes
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 1bfbeda9ec Answer A-183: an unenforced mark is refused by both validators
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 23be8beda9 Answer A-182 in a new part: a superseded step's drop is asked where it stands
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben c518e59b9b Answer A-181: build.ended kept last per fingerprint, read whole at start
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 7f7eefdb44 Answer A-180: a run is placed on its candidate's catalog revision
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben f053779abe Answer A-179: the seat server refuses the unproven; the grants hold the rest
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 07aa46a02d Answer A-178: the view and the teller say their answers with a read tool and marks
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 9c6a6d2f00 Answer A-177: a compiled verb carries its approval mark
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 0afac8d52e Answer A-176: one mesh-sdk helper writes a process's consumer facts
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 65dcc83bf1 Answer A-175: the teller and the view follow each other's answers by views families
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 4c7b86af2c Answer A-174: the indexer keeps its runs; an unwatched branch takes the trunk's view
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben db726d734e Answer A-172 and A-173: the teller's merge path goes; the view per branch
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben d8dade2563 Answer A-171: a pinned catalog revision names its branch
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 17f8ec2fbb Answer A-170: an ask's kind is in its body, the subject names queue and asker
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben a2f2e5b98d Answer A-169: one key form for every holder of pins
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 19f969b2db Answer A-168: marked waits take the union of every branch's newest entry
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben b13dc2bfc4 Answer A-167: the assigner's composition step, held entries, reverts
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 7ebdfb3278 Answer A-166: the runner keeps when, the health works out the age
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben d71bd5d0fa Answer A-165: seat servers apply the class defaults
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 28c38dc2b9 Answer A-164: runner_health reads the consumer ages its process writes
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 01d8328758 Answer A-163: an ask's asker is its seat's name, checked against the definition's callers
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben ea4cb84ce1 Answer A-162: build.ended for every end, the assigner reads no builder bucket
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 7098d550f3 Answer A-161: the teller's events carry the fields it says
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben e89d0ce830 Answer A-160: a run's candidate from the branch take-in of its members
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 644a9484ab Answer A-159: resolved names the commit and the digest of what was laid
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben a6ffb0a7a1 Answer A-158: a marked call answers {answer, approval}
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 4020ff8b70 Answer A-157: warranted asked again on the holder heard; call-unanswered on a bound key
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben b054da9141 Answer A-156: distribution's build modules are the build seats' claimers
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 95e47c2776 Answer A-155: restic's put-off wait is a bound key on the bus
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 79d8ec7a52 Answer A-154: the approval mark's findings scope and id
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 9a90bec951 Answer A-153: a subscription's key resolves through mesh-sdk's EventSubjects
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben 82c483fccc Answer A-152: the toolchain digest is the sha256 of the program run
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:28 +01:00
jschoubben df569ad63a Answer A-151: the build modules read the artifact store through its provision
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:27 +01:00
jschoubben 9e737e7c4c Answer A-150: restic's night process gets its own bus
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:27 +01:00
jschoubben 855149b25b Answer A-149: the node-engine's own name from its applied store at start
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:27 +01:00
jschoubben 2b13097956 Answer A-148: a trunk fault that fails a release's check rides that release
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 09:41:27 +01:00
mesh-tools 2d8ff36d03 Merge pull request 'Design 47 G: the lead's answers A-112 to A-147' (#570) from design/47-G-lead-answers-8 into main 2026-11-12 08:40:47 +00:00
jschoubben 00c436dd15 Design 39 bus-and-switch: C2, the manager replaces a key pair it cannot read
mesh/delivery closed: a newer head of the same pull request
mesh/check pass 00c436dd1580 on 2d8ff36d03ab | carried from 044b913a9e50 | unit 43 run, 0 kept, 1 skipped | integration 43 run, 0 kept, 1 skipped | co…
Claude-Session: https://claude.ai/code/session_01NcbgfHb9d4T9nq5Q6WqdiJ
2026-11-12 09:36:39 +01:00
jschoubben 12a98c2183 Design 39 bus-and-switch: C1, the licence manager runs as its own account, its service and its tools in its own runtime
mesh/delivery closed: a newer head of the same pull request
mesh/check pass 12a98c21832e on 044b913a9e50 | unit 43 run, 0 kept, 1 skipped | integration 43 run, 0 kept, 1 skipped | composition passed in 62s on 4…
Claude-Session: https://claude.ai/code/session_01NcbgfHb9d4T9nq5Q6WqdiJ
2026-11-12 09:16:05 +01:00
jschoubben d16d23e2a2 Answer A-147: a recovery act during a move is refused, naming both fingerprints
mesh/delivery merged: source.main moved to novox/hq@2d8ff36d03ab
mesh/check being carried to d16d23e2a27a on 2d8ff36d03ab | from 044b913a9e50
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:16 +01:00
jschoubben 0d19a01ea7 Answer A-146: the reader release carries the foundation part's exception
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:16 +01:00
jschoubben 294df2d72e Answer A-145: the second reader release carries only §621's words
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:16 +01:00
jschoubben be5ab83015 Answer A-144: a client imports its own seat only; the key codec and source follower move to the domain SDK
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:16 +01:00
jschoubben 47583173db Answer A-143: the recovery module's waits are bound keys
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:16 +01:00
jschoubben f9bb4a6d78 Answer A-142: a missed step-ended reaches the watchman by its durable consumer
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:16 +01:00
jschoubben 61b2a273f2 Answer A-141: the recovery module acts on its own stop
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:16 +01:00
jschoubben 54f6d4bb5d Answer A-140: the wait after a restore's cancel, a busy keeper
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:16 +01:00
jschoubben 4e121e37cd Answer A-137 to A-139: what a keeper's restore sets aside, the recovery bounds, chunks from mesh-sdk
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:16 +01:00
jschoubben 8392ec5c2d Answer A-136: the watchman's steps read goes by §483
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:16 +01:00
jschoubben 7b03a6831b Answer A-135: the digests state takes the template's fixed cap
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:16 +01:00
jschoubben 1869e6b0a2 Answer A-134: binding.changed carries its consumer; the vault adopts it
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:16 +01:00
jschoubben 5b1d068de3 Answer A-133: the recovery module's manifest follows the validator
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:16 +01:00
jschoubben 8d5fcb8236 Answer A-132: the running fingerprint from the node-engine's running event
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:15 +01:00
jschoubben c764f46577 Answer A-131: the first view of a seat's view is the holder's first-view tool
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:15 +01:00
jschoubben 53f119fb48 Answer A-129 and A-130: kept-points says the unrestored asides; the recovery settings' names
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:15 +01:00
jschoubben 29692693fa Answer A-128: a read in seat form is its own kind in mesh-sdk; reword to the validator
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:15 +01:00
jschoubben 401f5dcb8b Answer A-126 and A-127: one seat-holder helper; serves beside the bus only
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:15 +01:00
jschoubben a1faef315f Answer A-123 to A-125: aside's names, a list, the restore in mesh-sdk
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:15 +01:00
jschoubben aef9bf8453 Answer A-122: the image build act's bound is the other build seats'
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:15 +01:00
jschoubben b42864542a Answer A-121: an old section's bus names are the bus composer's
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:15 +01:00
jschoubben fe138a638c Answer A-120: the early pass takes the node's record from the engine's own statement
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:15 +01:00
jschoubben 17c9525ebd Answer A-119: the builder's floor from the catalog half, the assignments view in seat form
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:15 +01:00
jschoubben cb0efaf9a6 Answer A-118: bound keys in the builder, the outgoing checker as it is
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:15 +01:00
jschoubben 6af2aecb73 Answer A-117: the node-engine's early pass, its entry-not-found, why on recovery endings
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:15 +01:00
jschoubben 363da8fbab Answer A-116: a read of a seat holder's state names the seat
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:15 +01:00
jschoubben c4ad757265 Answer A-115: serves belongs to the process, tools stay the bundle's
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:15 +01:00
jschoubben 168e41fd69 Answer A-114: wanted keeps each want's last word with no age limit
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:15 +01:00
jschoubben 1ff3066bab Answer A-113: a failed restore restarts the newer build; no move without its restore point
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:15 +01:00
jschoubben 69771a4d8e Answer A-112: a process reads its settings from a declared file
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 03:28:15 +01:00
mesh-tools 044b913a9e Merge pull request 'Design 39 bus-and-switch: the lead's answer B44, the carry-over carries live leases' (#569) from design/39-licence-answers-8 into main 2026-11-12 00:06:34 +00:00
jschoubben 28cd959de4 Design 39 bus-and-switch: the lead's answer B44, the carry-over carries live leases
mesh/delivery merged: source.main moved to novox/hq@044b913a9e50
mesh/check checking 28cd959de439 on 044b913a9e50
Claude-Session: https://claude.ai/code/session_01NcbgfHb9d4T9nq5Q6WqdiJ
2026-11-12 01:05:36 +01:00
mesh-tools 93f8ef4a2f Merge pull request 'Design 39 bus-and-switch: the lead's answer B43, a first view keeps a binding an event wrote after it was asked' (#568) from design/39-licence-answers-7 into main 2026-11-12 00:02:16 +00:00
jschoubben 87f86772f6 Design 39 bus-and-switch: the lead's answer B43, a first view keeps a binding an event wrote after it was asked
mesh/delivery merged: source.main moved to novox/hq@93f8ef4a2f7c
mesh/check being carried to 87f86772f60f on 93f8ef4a2f7c | from 7092d2afa9a7
Claude-Session: https://claude.ai/code/session_01NcbgfHb9d4T9nq5Q6WqdiJ
2026-11-12 00:57:58 +01:00
mesh-tools 7092d2afa9 Merge pull request 'Design 39 bus-and-switch: the lead's answer B42, the vault asks one first view again by name' (#567) from design/39-licence-answers-6 into main 2026-11-11 23:39:30 +00:00
jschoubben 4e2bf72219 Design 39 bus-and-switch: the lead's answer B42, the vault asks one first view again by name
mesh/delivery merged: source.main moved to novox/hq@7092d2afa9a7
mesh/check checking 4e2bf72219b5 on 7092d2afa9a7
Claude-Session: https://claude.ai/code/session_01NcbgfHb9d4T9nq5Q6WqdiJ
2026-11-12 00:38:33 +01:00
mesh-tools 627ef84453 Merge pull request 'Design 39 bus-and-switch: the lead's answer B40, a licence's target says where consumers go next' (#566) from design/39-licence-answers-5 into main 2026-11-11 23:32:37 +00:00
jschoubben 34f5ee62d2 Design 39 bus-and-switch: the lead's answer B41, the whole test reads the condition through the seat's contract
mesh/delivery merged: source.main moved to novox/hq@627ef8445326
mesh/check being carried to 34f5ee62d2a2 on 627ef8445326 | from 84e9f8a1929d
Claude-Session: https://claude.ai/code/session_01NcbgfHb9d4T9nq5Q6WqdiJ
2026-11-12 00:27:38 +01:00
jschoubben 4f19bdf6fb Design 39 bus-and-switch: the lead's answer B40, a licence's target says where consumers go next
mesh/delivery closed: a newer head of the same pull request
mesh/check pass 4f19bdf6fb2b on 84e9f8a1929d | unit 43 run, 0 kept, 1 skipped | integration 43 run, 0 kept, 1 skipped | composition passed in 80s on 3…
Claude-Session: https://claude.ai/code/session_01NcbgfHb9d4T9nq5Q6WqdiJ
2026-11-12 00:14:51 +01:00
mesh-tools 84e9f8a192 Merge pull request 'Design 47 G: the lead's answers A-101 to A-111' (#565) from design/47-G-lead-answers-7 into main 2026-11-11 23:12:59 +00:00
mesh-tools d65ed10931 Merge pull request 'Design 39 bus-and-switch: the lead's answers B38 and B39 met in develop' (#564) from design/39-licence-answers-4 into main 2026-11-11 23:09:28 +00:00
jschoubben e65c0ea27f Design 39 bus-and-switch: the lead's answers B38 and B39 met in develop
mesh/delivery merged: source.main moved to novox/hq@d65ed10931c1
mesh/check checking e65c0ea27f24 on d65ed10931c1
Claude-Session: https://claude.ai/code/session_01NcbgfHb9d4T9nq5Q6WqdiJ
2026-11-12 00:08:17 +01:00
mesh-tools 044cd2dfdd Merge pull request 'Design 39 bus-and-switch: the lead's answers B26-B37 met in develop' (#563) from design/39-licence-answers-3 into main 2026-11-11 23:07:17 +00:00
jschoubben c75f1072ea Design 39 bus-and-switch: the lead's answers B26-B37 met in develop
mesh/delivery merged: source.main moved to novox/hq@044cd2dfddbe
mesh/check checking c75f1072eaf4 on 044cd2dfddbe
Claude-Session: https://claude.ai/code/session_01NcbgfHb9d4T9nq5Q6WqdiJ
2026-11-12 00:05:53 +01:00
jschoubben 369c875358 Answer A-111: the runner's write verbs as built
mesh/delivery merged: source.main moved to novox/hq@84e9f8a1929d
mesh/check checking 369c875358ce on 84e9f8a1929d
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:57:54 +01:00
jschoubben 3ffb0f8d8e Answer A-110: a process's serves in the form of invokes
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 3ffb0f8d8e27 on d65ed10931c1
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:57:37 +01:00
jschoubben 9ff6368e82 Answer A-109: a process's serves, their grants, chunks on the core bus
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:56:42 +01:00
mesh-tools 87f2901f55 Merge pull request 'Playbook 07: the prepare reads the code; the lead answers design questions against the principles' (#562) from meta/prepare-reads-code into main 2026-11-11 22:54:31 +00:00
jschoubben a2da2a3e74 Let the lead answer every design question against the principles
mesh/delivery merged: source.main moved to novox/hq@87f2901f556b
mesh/check checking a2da2a3e7451 on 87f2901f556b
The operator replaced the instruction on implementing a design on
2026-11-11 about 21:48 CET: the lead answers each question met while
building in one line against the principles, and only one no principle
settles goes on, to the operator when it changes what they see or how
they work, removes data or needs their terminal, otherwise to the design
writer as a design line. Playbooks 02, 07 and 08, the glossary's design
question, AGENTS.md, the code reviewer and the drawn overview still said
only the operator or the design writer answers; they now say the rule.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:53:03 +01:00
jschoubben ccfac82fd1 Answer A-108: the node agent runs the catch-up after the restore
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:51:15 +01:00
jschoubben b6ea3a740c Have the prepare read the code and list where design and code disagree
In milestone 47/G's develop the lead answered over 100 questions, most of
them a design line meeting the code: a form the code cannot take, or a part
assumed built that was not. The prepare had read the design alone. The
operator, 2026-11-11 about 23:45 CET: the prepare reads the code each design
line lands in as well, and lists every such place before any developer
starts; the lead answers each in one line against the principles.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:50:17 +01:00
jschoubben f29a8f0ebe Answer A-107: a process answers its seat's verbs, the operator's yes
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:48:03 +01:00
jschoubben 362c8074d1 Answer A-106: the runner's steps as built, its write verbs waiting on the operator
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:44:17 +01:00
jschoubben ab39ee3290 Answer A-105: the runner's toolchains state
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:42:40 +01:00
jschoubben 9efa510ad5 Answer A-104: the runner's write verbs, kept results, toolchain and unanswered asks
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:40:16 +01:00
jschoubben f426b4e5fa Answer A-103: the registration's first branch wins; the follower's helpers built once
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:40:16 +01:00
jschoubben 1c9488c2ae Answer A-102: accepted kinds named in invokes
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:40:16 +01:00
jschoubben f871c9f968 Answer A-101: > in TopicMatches, one operator-channel asker in mesh-sdk
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:40:16 +01:00
mesh-tools e1609f5dbb Merge pull request 'Design 47 G: the lead's answers A-71 to A-92' (#560) from design/47-G-lead-answers-6 into main 2026-11-11 22:39:59 +00:00
jschoubben e8fce4ca46 Answer A-100: build.ended as built
mesh/delivery merged: source.main moved to novox/hq@e1609f5dbb9d
mesh/check being carried to e8fce4ca46b3 on e1609f5dbb9d | from 95d2c2247131
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:33:25 +01:00
jschoubben ed9a41147a Answer A-99: build is every pipeline's first step, for its own entry
mesh/delivery closed: a newer head of the same pull request
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:33:11 +01:00
mesh-tools 95d2c22471 Merge pull request 'Design 39 bus-and-switch: the lead's answers B23 and B24 met in develop' (#561) from design/39-licence-answers-2 into main 2026-11-11 22:32:54 +00:00
jschoubben fa8c046682 Answer A-98: a stop act that removes nothing, for a revert
mesh/delivery closed: a newer head of the same pull request
mesh/check checking fa8c046682f8 on 95d2c2247131
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:32:21 +01:00
jschoubben fe3b86d65f Design 39 bus-and-switch: the lead's answer B25, the bindings verb answers the licence's key
mesh/delivery merged: source.main moved to novox/hq@95d2c2247131
mesh/check checking fe3b86d65f86 on 95d2c2247131
Claude-Session: https://claude.ai/code/session_01NcbgfHb9d4T9nq5Q6WqdiJ
2026-11-11 23:31:45 +01:00
jschoubben 720cff7271 Answer A-97: a candidate's build is a pipeline step the runner asks of mesh-builds
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 720cff7271cb on 01b6441a48d2
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:31:38 +01:00
jschoubben 128236e7a0 Design 39 bus-and-switch: the lead's answers B23 and B24 met in develop
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 128236e7a047 on 01b6441a48d2
Claude-Session: https://claude.ai/code/session_01NcbgfHb9d4T9nq5Q6WqdiJ
2026-11-11 23:30:54 +01:00
jschoubben 2eb897699f Answer A-96: the builder says build.ended on its own stream
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 2eb897699fed on 01b6441a48d2
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:28:59 +01:00
jschoubben 4ffcadf4e9 Name the node-engine by its word in A-95
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 4ffcadf4e97c on 01b6441a48d2
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:28:21 +01:00
jschoubben 04f4d715bd Answer A-95: the node-engine's kept entries as built, and what is still owed
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 04f4d715bd1f on 01b6441a48d2
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:28:03 +01:00
jschoubben fb10a9359b Answer A-94: the assigner hears build.ended and maps a want to its release by source
mesh/delivery closed: a newer head of the same pull request
mesh/check checking fb10a9359bfb on 01b6441a48d2
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:27:35 +01:00
jschoubben d0beb962d8 Answer A-93: a branch's take-in computes its revision directly; the trunk stays main
mesh/delivery closed: a newer head of the same pull request
mesh/check checking d0beb962d890 on 01b6441a48d2
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:27:11 +01:00
jschoubben d0c7373d38 Answer A-92: the node-engine's bound keys
mesh/delivery closed: a newer head of the same pull request
mesh/check checking d0c7373d386e on 01b6441a48d2
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:26:25 +01:00
jschoubben 03813cce78 Answer A-91: the warrant in the router's record, unnamed steps, the runner's asking half
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:26:00 +01:00
jschoubben c96d5d6c6d Answer A-90: every watched branch is taken in by the trunk's take-in
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:25:22 +01:00
jschoubben f103680251 Answer A-89: every asker reads its warrant from the router's record
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:24:00 +01:00
jschoubben c096c4af1c Answer A-88: no callers named in mesh-networking's seats
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:21:30 +01:00
jschoubben 63153faa94 Answer A-87: the builder's fault words and builder_build's newest
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:20:52 +01:00
jschoubben 82e0d85700 Answer A-86: who keeps an input, and a kind-3 edge's language
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:20:01 +01:00
jschoubben 834370bf67 Answer A-85: a catalog revision per watched branch
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:18:38 +01:00
jschoubben 5b4cbc035c Answer A-84: the builder learns a candidate from the run's build step
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:17:35 +01:00
jschoubben 1963baefb3 Answer A-83: a branch build's edges and its newest build
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:15:40 +01:00
jschoubben 2f8e07d923 Answer A-82: build modules found through their seats
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:13:31 +01:00
jschoubben acdef3a98d Answer A-81: the builder's publish again, as built
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:13:02 +01:00
jschoubben 9d406b6f02 Answer A-80: what the indexer keeps as heard has a state of its own
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:08:26 +01:00
jschoubben 6cf7372ad4 Answer A-79: the grants part's catalog half, as built, and its last indexer reads go
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:06:17 +01:00
jschoubben e67326b6c7 Answer A-78: what outdated keeps and reads
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:05:20 +01:00
jschoubben 6ec5ac27a7 Answer A-77: a wait's bound is a key with its own time to live
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:05:00 +01:00
jschoubben e9c927d448 Answer A-76: the reservation's fingerprint, the registry seat, the fault's class
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:04:18 +01:00
jschoubben 8e87bdc148 Answer A-75: mesh-issues' pipeline rows in its delivery line
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:03:39 +01:00
jschoubben 0fe2118105 Answer A-73 and A-74: publish again by digest, the router's asks through its seat
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 23:02:28 +01:00
mesh-tools 01b6441a48 Merge pull request 'Design 47 G: the lead's answers A-44 to A-70' (#559) from design/47-G-lead-answers-5 into main 2026-11-11 22:01:50 +00:00
mesh-tools 173d6d2cd4 Merge pull request 'Design 39 bus-and-switch: the lead's answers to the prepare's 22 questions' (#558) from design/39-licence-answers into main 2026-11-11 22:00:34 +00:00
jschoubben 2bf174b57c Design 39 bus-and-switch: the lead's answers to the prepare's 22 questions, each by the principles
mesh/delivery merged: source.main moved to novox/hq@173d6d2cd45d
mesh/check being carried to 2bf174b57c57 on 173d6d2cd45d | from 18639c73921a
Claude-Session: https://claude.ai/code/session_01NcbgfHb9d4T9nq5Q6WqdiJ
2026-11-11 22:50:43 +01:00
mesh-tools 18639c7392 Merge pull request 'Design 39 bus-and-switch: the licence manager keeps its data on the bus and switches on its own usage' (#557) from design/39-licence-switch into main 2026-11-11 21:36:26 +00:00
jschoubben 8d772ad40c Answer design 39 bus-and-switch's questions by the principles, so it can ship on main as it is
mesh/delivery merged: source.main moved to novox/hq@18639c73921a
mesh/check being carried to 8d772ad40c95 on 18639c73921a | from e1819e0a0d08
The lead answered the four open questions against hq's principles on
2026-11-11: the vault serves licence secrets to the tool runner's account
(principle 6), the operator's word replaces ADR 0183 §21 and ADR 0206 §16, §18
with no record, the store database stays one milestone as the carry-over's
read-only source (principle 7, the delivery gap named), and the milestone no
longer waits for design 47's G: its conditions are said on the operator
channel as any module does today.

Claude-Session: https://claude.ai/code/session_01NcbgfHb9d4T9nq5Q6WqdiJ
2026-11-11 22:30:44 +01:00
jschoubben 84bb85d037 Design 39 bus-and-switch: the licence manager keeps its data on the bus and switches on its own usage
The operator, 2026-11-11: the licence manager itself moves every consumer off a
licence at 99 % of its session or weekly window to the licence with the most
room, configurable, with its Postgres database replaced by bus state and tools
for all it keeps and does. That night a session meant to switch missed the
readings, so no session does it any more. The new milestone part writes every
line it builds (kept data, the one carry-over of today's rows, the vault move
of ADR 0550 §3, bindings and holdings as events, the switch, its warning and
condition, the tools, adding a licence), and names the three questions no
record settles; the main file is put in the shape a builder reads whole.

Claude-Session: https://claude.ai/code/session_01NcbgfHb9d4T9nq5Q6WqdiJ
2026-11-11 22:30:44 +01:00
45 changed files with 7754 additions and 343 deletions
+54
View File
@@ -0,0 +1,54 @@
---
name: gap-surveyor
description: Holds the code on main of the Novox mesh against one part's specification (a spec-reader's file) and writes that part's gap table (hq playbook 07, before a prepare, when a design's parts are to be delivered again) - per design line what is built, built otherwise, contradicted or missing, where in code, how big the gap is, the leftovers of an earlier model, and which build runs live on each machine against main. Read-only on the mesh and every working copy; writes only the one file the caller names.
tools: Read, Grep, Glob, Bash, Write, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search
model: opus
---
You hold the code of the Novox mesh against the specification of one part of a design and write the gap table
the lead plans from. The caller names the part, its specification file, the repositories and modules that hold
it, the facts about what runs live on the machines that the caller already knows, and the file to write.
Read first: hq's glossary (`00-META/glossary.md`) and principles (`00-META/principles.md`), then the
specification file whole. Then the code.
How you read:
- **Code on main only, never a working copy's checkout.** Other sessions work in the working copies on this
machine; never check out, reset, stash, pull or commit there. Run `git fetch origin` in the repository and
read with `git show origin/main:<path>`, `git grep <words> origin/main`, `git ls-tree -r origin/main` and
`git log origin/main`. A branch the caller names (a held pull request) is read the same way as
`origin/<branch>`, and every fact from it is said to be from that branch.
- **Each fact with its source:** the repository, the short commit of `origin/main` you read, the module and the
function or type; never a line number.
- **What runs live** you read through the mesh MCP server with read tools only: `mesh_machine` for a machine's
modules, a module's own read tools and the seat verbs that read its state (find them with `mesh_search`).
Call no verb that writes, starts, cancels or restarts anything.
- **The tests count:** per module, how many unit tests and how many integration tests (`//go:build
integration`) main holds, and whether one integration test starts the module whole against a bus and a store.
Write the file the caller names, in this shape:
1. **The gap table**, one row per design line of the specification, in its order: the citation; its status, one
of *built* (the code does what the line says, by its contract), *built otherwise* (the outcome is there but by
another path: a poll, a timer, a direct call, a shared file, a read of another part's state, a comparison in
place of an event), *contradicts* (the code does something the line forbids or that a replaced line said),
*missing*, or *not judged* (say why); where it lives (repository, module, function or type); what the code
does instead, in one sentence, when it is not *built*; and the size of the gap, S (one function, under an
hour), M (one module's part, a day), L (the part's shape, more than a day).
2. **The leftovers**: every mechanism in these modules that no line of the specification asks for, or that a
replaced line asked for: what it is, where, what it does, and which line it contradicts or none. A sweep, a
poll, a retry loop, a stand-in, a hand-act path, a per-merge path count.
3. **Live against main**, a table per module of the part: the machine, the build that runs (its version or
fingerprint as the machine's tools say it), whether that build is main's or a hand-placed one, and what main
has that it lacks.
4. **The tests**: per module, the counts, whether an integration test starts the module whole, and what the
tests would not catch of the gaps above.
5. **Fix in place or write again**, one paragraph per module: your judgement from the table, with the reason:
the share of lines *built*, how many gaps are L, whether the module's shape is the specification's (its
events, verbs, kept data) or an earlier model's. A recommendation, not a decision.
6. **What you could not read**, and every fact you guessed, said as a guess with how to check it.
Report to the caller in under 400 words: the file's path, the counts per status, the three gaps that matter most,
your fix-or-rewrite recommendation per module in one line each, and what you could not read. Plain words in the
glossary's words.
+28 -5
View File
@@ -1,6 +1,6 @@
---
name: mesh-code-reviewer
description: Reviews one change of the Novox mesh before it is pushed (hq playbook 07, the review; at most three rounds): each commit against the design lines it cites, code no design line asks for, the build maps' What exists today, and whether its tests prove it. Read-only; reports findings, never fixes, and never re-judges the design.
description: Reviews one change of the Novox mesh before it is pushed (hq playbook 07, the review; at most three rounds): each commit against the design lines it cites, code no design line asks for, the build maps' What exists today, whether its tests prove it without standing in for another part of the mesh, and each changed module against the live mesh with the order of delivery it needs. Read-only; reports findings, never fixes, and never re-judges the design.
tools: Read, Grep, Glob, Bash, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search
model: opus
---
@@ -20,16 +20,28 @@ questions are.
- a commit that does not do what the design lines it cites say, or does only part of it; a design line in a build
map with no commit; a commit that cites no design line, or an answer no hq commit holds;
- code no design line asks for: a new exported type, field, constant, package, module, state, verb, event, bound,
caller or tool, or a fate for what exists, that the milestone part does not give; and a piece of code placed where
caller or tool, or a fate for what exists, that neither the milestone part nor the milestone's lead-answers file gives; and a piece of code placed where
the design line (or the design section *Where a seat's code goes* it cites) does not put it. The fix is to take it
out, or to hold it as a design question for the lead until the operator's answer is in the design;
out, or to hold it as a design question for the lead until its answer is in an hq commit (playbook 07, step 0b);
- an interaction the design does not place that is not a mesh path: one module naming another, reading another's
internals or being special-cased in another part; a module's name in shared code; state only in memory; a poll or
a timer where an event exists;
- a value written into the code that can differ between machines, modules or over time (a port, a path, a bound, a
cap, a name, a time) and is not a setting with a default (principle 11); name the setting it should be, eagerly;
- a module that writes another module's file or state, or anything in another module's place, instead of giving it
through a provision or a contribution that module declares (principle 12);
- an effect or a reader of the build map's `What exists today` whose fate the diff does not carry out (run its
searches again on the reviewed tree), or one the search finds and the answer omits;
- a test that does not fail without its change (check it by taking the change out in a copy), an acceptance
criterion with no test, a new test function where the repository is over budget, real sleeping;
- **a test that stands in for another part of the mesh, by rule** (playbook 07 step 2, item 11): one that creates a
stream, a consumer or a process taking a work queue's asks where the bus module, the grants part or the
node-engine should, or fakes a seat's holder in a whole test. The fix is composing what it needs with the parts' own
composers from the module's bus-shape sheet (step 0, item 11); a composer it cannot import is a gap of the build and
delivery system, named for the lead. List every new or changed test that creates bus state or fakes a seat's
holder, each with the composer that should make it;
- a changed module whose bus shape differs from its bus-shape sheet (its manifest sections, accounts, streams and
subjects, work queues and who takes their asks, who creates each);
- vet or tests that fail: run `go vet ./...`, `go vet -tags integration ./...` and `go test ./...` in every
touched module, with the siblings placed as the build map's one placement says;
- a change to any `module.json` reported without the manifest validator's verdicts (every manifest whose verdict
@@ -40,6 +52,16 @@ questions are.
principle you know of, name the line and why in a note; the lead brings it to the operator. The code follows the
line until the design changes.
**Read each changed module against the live mesh, and name the order of delivery** (playbook 07 step 2, item 12;
the operator, 2026-11-22). Through the mesh MCP server's tools, read what runs on the nodes now: each node's haves of
every module the change touches or relies on, and which parts still carry the form the change replaces (the tool
runner, the build modules, the node-engine, the indexer and its manifest validator, the grants part). For each, ask
whether its running version can take in, judge, build, compose or page the new form. Write a section `Live mesh`:
each such part with the build read on each node and the time read, then the order of delivery the change needs (the
parts that judge, build, compose or page first, then the modules that use them), each step an ordering edge the
delivery plan derives, or a gap of the build and delivery system for the lead. A part on the old form that no step of
the order brings over is a finding.
**Prove it against the live mesh, never a re-creation.** When the change answers a fault seen on the machines,
check what it claims against the state the mesh itself uses, read through its tools (the manifest validator's own verdicts in the indexer,
the packages state, the store, a node's haves), never against a copy you rebuilt: a manifest validator run without the seat list,
@@ -49,5 +71,6 @@ such in the report.
Anything else (hardening, a further case, a nicer form) is a note, never a round. Read only: no edits, no git
write, no verb that writes, never ssh. Use a temporary directory under `/var/tmp`.
Answer playbook 07 step 2 item 10's two questions, one line each. Answer **APPROVED at** the full commit ids, or numbered findings each with file:line, the design line it concerns,
what is wrong, and the fix; design questions and notes apart. Under 25 lines, glossary words only.
Answer playbook 07 step 2 item 10's two questions, one line each; then the list of tests of item 11 and the section
`Live mesh` of item 12 (a report without them is not an approval). Answer **APPROVED at** the full commit ids, or numbered findings each with file:line, the design line it concerns,
what is wrong, and the fix; design questions and notes apart. Under 40 lines, glossary words only.
+5 -1
View File
@@ -35,7 +35,11 @@ A fact the build map got wrong (a file moved, a function renamed) you say to the
**How you work.** Worktrees from `origin/main` on the branch the handover names, subtasks in the build map's order:
one that uses a contract, type, verb or package another subtask adds starts from that subtask's commit. Commit per
subtask, its label in the subject and a line `Builds: design NN M §n, …` in the body, locally only: never push, never open a pull request, never call a verb that writes on the mesh (reads are fine). Never
ssh, never a shell helper for the mesh. Tests: every change carries a test that fails without it (check it);
ssh, never a shell helper for the mesh. Tests: every change carries a test that fails without it (check it), and no test stands in for another part of the
mesh (playbook 07 step 2, item 11): none creates a stream, a consumer or a process taking a work queue's asks that the
bus module, the grants part or the node-engine should, and none fakes a seat's holder in a whole test; compose what a
test needs with the parts' own composers from the module's bus-shape sheet, and a composer you cannot import is a
question for the lead;
rows or subtests in existing tests where the repository is over the test budget the instructions set; no real
sleeping. Run `go vet ./...`, `go vet -tags integration ./...` and `go test ./...` in every touched module as
the running checker places siblings (playbook 07). Once per head you report, not per commit, also run the integration tests of
+30 -6
View File
@@ -1,20 +1,22 @@
---
name: mesh-preparer
description: Prepares one milestone or small fix of the Novox mesh before any code is written (hq playbook 07, the prepare step; playbook 08), from the milestone's part of its design alone - one build map per repository (where each design line lands in code, what exists there today and what relies on it, the subtasks and their order) and the list of design questions the design does not answer. Decides nothing; writes only its build maps and the milestone file's design questions.
description: Prepares one milestone or small fix of the Novox mesh before any code is written (hq playbook 07, the prepare step; playbook 08), from the milestone's part of its design and the design's main file, read whole, then the code each design line lands in - one build map per repository (where each design line lands in code, what exists there today and what relies on it, the subtasks and their order), the list of design questions the design does not answer, and the list of places where a design line and the code disagree. Decides nothing; writes only its build maps, the milestone file's two lists and a bus-shape sheet per module.
tools: Read, Grep, Glob, Bash, Write, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search, SendMessage
model: opus
---
You prepare one change of the Novox mesh for the lead who started you. The caller's handover names the issue, the
design and its milestone part at an hq commit, and where your files go (playbook 07, step 0). You write the build
maps and the milestone file's section `Design questions`, nothing else; you call no verb that writes and make no git
maps, the milestone file's sections `Design questions` and `Design meets code`, and a bus-shape sheet per module with
the test that composes it, in your own worktree, nothing else; you call no verb that writes and make no git
write.
**The design is your only input.** Read the milestone part and the design's main file whole, at the commit the
**The design is your only input for what is built.** Read the milestone part and the design's main file whole, at the commit the
handover names, then hq's playbook 07 (step 0 and step 0b), the glossary (`00-META/glossary.md`) and the mesh's
instructions (`/etc/claude-code/CLAUDE.md`). Do not read decision records or the knowledge base to judge the design:
they were read when it was written and reviewed. Read the issues the handover names (`issue-tracker.get`) for their
done-when. Code shows what exists, never what is to be built.
done-when. Code shows what exists, never what is to be built; but it says whether a line can be built as written, so
you read it too (next paragraph).
**Then map each design line onto code**, as playbook 07 step 0 says: per repository, every design line it builds
("design NN M §n") with the files and functions it changes, its subtask (about thirty minutes, one change, its
@@ -28,14 +30,36 @@ callers and kinds, as on main) with the design lines that name that seat, field
design question. Code: read the repositories at `origin/main` (`git fetch`, `git show`, `git grep`),
never a working tree; the live mesh through its tools.
**Then read the code each design line lands in, and list where they disagree** (playbook 07 step 0, items 3 and 10;
the operator, 2026-11-11). For each design line, read at `origin/main` the files and functions it changes, the
contracts, types and packages it uses and the rules the code holds there (a guard, a check, a test that refuses), and
ask: can the code take the form the line names; is every part the line assumes built (a verb, a field, a package, an
event, a module) there on main; does the line break a rule the code holds. Each no is an entry under `Design meets
code`: the design line, the code (file:line at the commit read, each repository's commit named once at the top),
which of the three it is, and your recommendation, said as one. The lead answers these against the principles before
develop starts, as it does the design questions; you answer none.
**End with a bus-shape sheet per module, composed in a test** (playbook 07 step 0, item 11; the operator,
2026-11-22). For each module the milestone adds or changes, write `.work/<slug>/<module>.bus.md`: its manifest
sections (each process, its `bus`, `serves` and `requires`), its bus accounts, its streams and their subjects, its
work queues and the process that takes each queue's asks, its durable consumers, and who creates each (the bus module
from `requires`, the grants part, the module's own process), every row citing its design line. Then judge it in a
test in a worktree of your own under `/var/tmp`: the manifest validator with the live seat list, and the grants part's
composer and the node-engine's composer (the composition of `mesh-delivery-sdk`) composing the manifests the sheet
describes. A refusal is an entry under `Design meets code`; a row no design line gives is a design question; a composer
the test cannot import you report to the lead as a gap of the build and delivery system. Name the test and its result
at the top of the sheet.
**Everything the design does not say is a design question, never your answer.** A reader or an effect with no fate,
a field's form, a key and who deletes it, a bound, a caller, an owner, a tool for a new state, an interaction whose
seat, verb, event or provision the design does not name, code or a live state that contradicts a design line: list
seat, verb, event or provision the design does not name, a live state that contradicts a design line: list
each under `Design questions` with the design line (or the missing one), what it leaves to its builder, where you met
it (file:line or the tool's answer) and your recommendation, said as one. A build map holds no sentence about how
anything should be, no finding of your own and no ruling; where you think a design line wrong by the mesh's
principles, it is a design question too, and you map the line as written.
Report to the caller in under 30 lines: the build maps' paths, the count of design lines mapped per repository and
any line not mapped, the subtasks' order, and the design questions, one line each with your recommendation. Glossary
any line not mapped, the subtasks' order, the bus-shape sheets' paths and their tests' results, the design questions and the entries of
`Design meets code`, one line each with your recommendation, and their count: more than ten together send the
milestone back to its design (step 0b, item 5). Glossary
words only; a guess is said as one.
+6
View File
@@ -23,6 +23,12 @@ without that read on each machine the module is wanted on.
Loop: wait with `mesh_wait` on the event family (its answer only wakes you), then read the state from the verb
the handover names; never report a state you did not read in that round.
**A state that does not change is not "nothing happened".** A reservation, a queue or a key can stay as it was while
the work behind it already failed. Each round, also read the journal of the program that does the work
(`<node>/node-service-manager.journal` with its unit, the last lines since your previous read) and report any failure
line word for word. A verb that times out or refuses twice is a finding of its own: report it at once, never read
around it. You have no clock: take times from the tools' answers, never guess them.
**A report along the way does not end you.** Your final message ends you, and then nothing watches. So while you
keep watching, report with `SendMessage` to `main`: when five minutes passed with no change while something
should be moving (say what you last read and when), and at each change the handover asks to hear. Then go on
+3
View File
@@ -25,6 +25,9 @@ write.
What you judge:
- Seams: where each piece of state lives on the bus (key-value bucket, stream, object store) and which module owns it; which seat, verb or event joins two parts; any link that is not NATS-native (a poll, a timer, HTTP between modules, a shared file, state only in memory); whether a form the manifest lacks is named with its cost (a mesh-sdk change rebuilds every module).
- Settings and ownership: every value that can differ between machines, modules or over time is a setting with a
default, never hard-coded (principle 11), and the design names it; no module writes another module's file or state:
what one module needs from another goes through a provision or a contribution that module declares (principle 12).
- Tools: for every new piece of state a tool that reads it, and for every new behaviour a tool that steers it (do by hand, ask again, drop, repair, re-check), as the instruction tools-are-how-a-module-is-spoken-to says.
Judge only whether the settled direction or design is complete and sound in your two architectural domains,
+43
View File
@@ -0,0 +1,43 @@
---
name: spec-reader
description: Reads one part of a to-be design of the Novox mesh with the records that decide it, and writes that part's specification as a list of its design lines with their checks (hq playbook 07, before a prepare, when a design's parts are to be delivered again) - what the part does, the seats, verbs, events and kept data it names, which later answers amend each line, and what the design leaves open. Reads no code; writes only the one file the caller names.
tools: Read, Grep, Glob, Bash, Write, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search
model: opus
---
You read one part of a to-be design of the Novox mesh and write its specification: everything the design and
its records say that part does, as a list a builder and a surveyor can hold code against. The caller names the
part, the design's files and sections to read, the records to read in the knowledge base, the other parts (so you
know where your part ends), and the file to write.
Read first: hq's glossary (`00-META/glossary.md`) and principles (`00-META/principles.md`), then the design's
main file sections the caller names, then the milestone part's files whole where the caller says whole, and the
answer files (the later design lines and the lead's answers) where they name your part: find them with `grep`
for the part's words (its seat, its module, its verbs, its events) and read each matching answer whole. Then the
records: `knowledge-base.get` with `reasoning: true` and `bound: 65536` for each record the caller names, and
`knowledge-base.ask` for the part's words to find records the caller did not name.
Never read code, a working copy or a repository's history: the specification says what should be, and the code
is the surveyor's job. Through the mesh MCP server only reads of the knowledge base.
Write the file the caller names, in this shape:
1. **What the part does**, in ten lines or fewer, in the glossary's words: its seat, the module that holds it,
its verbs, the events it publishes and consumes, the kept data it owns on the bus (state, streams, objects),
and the parts it talks to.
2. **The design lines**, a table, one row per line: the line's citation (`design 47 §n`, `design 47 G §n`,
`A-n`), one sentence of what it says, the record that decides it (`ADR nnnn §k`), how it is checked (the
acceptance test, the tool that reads it, the event that says it), and the later line or answer that amends or
replaces it, when one does. A line a later line replaced is kept in the table, marked replaced, so the
surveyor can tell a leftover from a build.
3. **The interactions**, one row per edge with another part: the event or verb, who publishes or serves, who
consumes or calls, and the line that decides it. A direct call, a shared file or a read of another part's state
is marked as such: it is a finding for the review, never a solution.
4. **What retires** at this part's delivery, with its line.
5. **What the design leaves open** for this part: a question no line answers, each in one sentence, with the
principle you think settles it or "no principle settles it". Decide nothing.
6. **What you could not read**: a record the knowledge base cut, a file you did not reach.
Report to the caller in under 400 words: the file's path, the counts (lines, interactions, open questions), the
three findings that matter most for delivering this part again, and what you could not read. Separate fact from
guess. Plain words in the glossary's words.
+123 -13
View File
@@ -89,8 +89,8 @@ is listed under [Homonyms](#homonyms), with the qualified form each domain uses.
**Purpose.** To say what one module is, in the one document every other domain reads.
**Recorded in** the catalog, one manifest per module. **Upstream of** every other domain; its words
are a published vocabulary, fixed by the manifest's schema. **Decided by** ADR 0040, 0126, 0174, 0188,
0207, 0236, 0262, 0634, 0635.
are a published vocabulary, fixed by the manifest's schema and judged by the manifest validator. **Decided by** ADR
0040, 0126, 0174, 0188, 0207, 0236, 0262, 0578, 0595, 0634, 0635.
**Uses:** module, seat, config value (Config), provision (Provisioning), data class (Data), health (Health
and repair).
@@ -100,9 +100,32 @@ and repair).
and never a pipeline step's status, which is the registration's policy (ADR 0666 §7, §14). Say
manifest in prose, not the file's name.
*Not:* ~~module definition~~ (hq)
- **resource** — one thing a manifest declares a node must have: a file, a directory, a service, a
container, a package, a bundle, an archive. A module **declares** resources; the verb *declares* is
- **resource** — one thing a manifest declares a node must have, by its `type`: a `directory`, a `file`, a
`service`, a `package`, a `container`, a `user`, an `archive`, a `network`, an `access`, a `process` or an
`opening`; never an `action` (ADR 0005). Its fields are the node-engine's vocabulary (mesh-sdk's declaration
package), which refuses a field its type does not use. A module **declares** resources; the verb *declares* is
this domain's and means what a manifest states.
- **process resource** — a resource of type `process`: a bundle of the module's own, named by `artifact`, fetched by
digest and run by the node-engine as a unit with the command `run`, in one of three modes: one that stays up, a
**run-once step** or a **scheduled run**. The way a module runs its own code without an image (ADR 0052, ADR 0053).
*Not:* ~~daemon resource~~ (hq)
- **run-once step** — a `process` or `container` resource with `run-once` true, run to completion by the node-engine
before every resource after it, which it gates; with `restart-on` it runs again when what it names changes (ADR
0052, ADR 0099). Not a migration of the module's own state, which is `prepares` (ADR 0135).
*Not:* ~~init step~~ (hq)
- **scheduled run** — a `process` or `container` resource with `schedule`, a five-field cron, run again on each fire
and never left running; a scheduled container may hold its own module's containers still while it runs
(`while-stopped`, ADR 0053, ADR 0189).
*Not:* ~~cron job~~ (hq)
- **runtime of its own** — the runtime that serves the tools bundle of a module saying `runs-as`, as that module's
account and on a bus account of its own, never the machine's runtime the tool runner runs as the operator's
account; its readiness is the manifest's `runtime-health` (ADR 0259 §8, ADR 0366).
*Not:* ~~private runtime~~ (hq)
- **old section** — a manifest's `state`, `logs`, `streams` or `objects`: kept data in the form before templates.
The parts the bus module needs before it can answer keep them for good; any other module's use of one is refused
once no accepted module outside those parts uses it any more (ADR 0595 §11, ADR 0619 §1). New kept data is asked
for in `requires` by template.
*Not:* ~~legacy section~~ (hq)
- **claim** — a module taking a spot on a seat: `claims: [{name, scope}]` in a manifest. A mesh-scoped
exclusive claim is how the mesh says "there is one of me". A foundation seat is named after the role
it guards: the `mesh-controller`, `postgres` and `nats` modules claim the `mesh-controller`,
@@ -112,7 +135,7 @@ and repair).
lines survive every send and are given back when the module goes (ADR 0174). The other way a node
varies a module, besides a config value; a **managed** file's marked block is one (Provisioning).
- **bundle** — the artifact a module's own code is built into — its tools, a seat's implementation, a
daemon — in any language the mesh has a toolchain for; never an image. A **tools bundle** speaks MCP to
daemon — in any language the mesh has a build module for (Go and TypeScript); never an image. A **tools bundle** speaks MCP to
the tool runner. One module may declare several
(ADR 0188).
- **tool** — one capability a module serves through the tool runner, addressed `<module>.<tool>`. A
@@ -535,6 +558,11 @@ and the operator act. **Recorded by** the controller's `identity` and `licences`
coding agent on a node (ADR 0183).
Taking a consumer off a licence is **unbinding** it; the licence manager's verb for it is still
`release`, an identifier to rename.
- **room** of a licence — how much of its vendor's usage windows is still unused: 100 less the higher of its
session window's (five hours) and weekly window's percentage in its latest reading, known only for a subscription
read recently and healthy. The licence manager moves every consumer off a licence at its threshold to the one with
the most room (design 39 bus-and-switch §25, §26).
*Not:* ~~headroom~~
- **proof** — what an authorising answer carries: a verified sender, a one-time code, a security key's
touch (ADR 0234). How much proof a kind of ask needs is its **assurance level**.
- **controller's terminal** — a command line the controller runs as typed by its operator, not asked through a
@@ -572,7 +600,46 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
registering and changing one are trusted acts (ADR 0666 §2). The mesh knows modules, and a repository only as a
module's git origin.
- **watched branch** — a branch a module's registration names, whose commits start that module's pipeline and which a
placement may choose for a node; registering one the forge does not protect is refused (ADR 0666 §3, §6).
placement may choose for a node; from milestone H's delivery it need not be protected, and nothing reads its
protection (ADR 0682 §13, which ends ADR 0666 §3's refusal and §11's judgement).
- **merge call** — one call of the seat `git`'s verb `merge-pull` naming one or more pull requests, each at the head
its caller names: from the delivery of design 47's milestone H the start of their delivery and, with two or more,
their group; the forge module judges every member before it merges any and says the call as its event
`merge-called`, from which the gate names the merged heads one source revision (ADR 0682). Not a merge made in the
forge's own screen, which delivers nothing and leaves an **untaken head**.
*Not:* ~~kick-off~~ (hq)
- **untaken head** — a watched branch's head that the forge bridge said moved (`head-moved`) and that no source revision
names within the gate's setting `untaken-bound`: a head moved outside the mesh, raised as the gate's finding
`head-untaken` and delivered by nothing but a later merge call or the gate's hand take (ADR 0682; design 47 H §740).
Not a pending revision, which is a source revision not yet taken in.
*Not:* ~~merge-untaken~~ (hq)
- **`merge-called`** — the seat `git`'s event saying one merge call: its members that landed, each at its merge
commit, and those refused; the gate's one input that names a source revision (ADR 0682 §1; design 47 H §736).
*Not:* ~~merge notice~~ (hq)
- **`head-moved`** — the forge bridge's one message for a move of a watched branch's head, however it moved, heard by
the gate's watchdog alone (ADR 0682 §3; design 47 H §739). It replaces the messages `merged` and `pushed`.
*Not:* ~~pushed message~~ (hq)
- **`head-untaken`** — the gate's finding for an **untaken head**, raised when `untaken-bound` passes (ADR 0682 §3).
*Not:* ~~untaken merge~~ (hq)
- **`untaken-bound`** — the gate's setting, default 10 minutes, after which a head moved and not named by a source
revision is `head-untaken` (ADR 0682 §3).
*Not:* ~~take-in bound~~ (hq)
- **`pipelines-at-once`** — the runner's setting, 1 to 8, default 1: how many pipelines have their steps asked at
once; the rest wait in order (ADR 0682 §7; design 47 H §748).
*Not:* ~~concurrent pipelines~~ (hq)
- **`tier-late`** — the assigner's finding when one tier of a pipeline's movers does not run on its present machines
within `tier-bound`: no later tier is written and the delivery record ends `failed` (ADR 0682 §8, §9; design 47 H
§751).
*Not:* ~~late tier~~ (hq)
- **take-in** — the indexer's act on one source revision of a watched branch: the commits it names, the
build-input fingerprints of the modules registered for those repositories, and one catalog revision of that branch,
said as `take-in.taken` naming the **movers**; it validates no manifest (that is the pipeline step `validate`) and
holds nothing for a named indexer (ADR 0682; A-476). Not a merge: what is taken in is a source revision the gate named.
*Not:* ~~merge take-in~~ (hq)
- **mover** — a module whose build-input fingerprint changed in a take-in, or a code dependent of one (a module, in any
repository, that imports a package of one): the modules a take-in's one pipeline runs and delivers (A-476a; ADR
0573 §3; ADR 0682). Not every module of the revision.
*Not:* ~~moving module~~ (hq)
- **run on request** — a pipeline run for a named commit or group that delivers nothing, asked by the runner's verb
`run`; the indexer builds its candidate from the runner's `run-started` (ADR 0666 §18).
- **artifact reference** — an artifact written `<module>:<artifact>`, such as `mesh-grants:program`: the end of a
@@ -581,12 +648,26 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
registrations, asks each pipeline step of the seat that serves it, says each step's start and end and each pipeline's
end as its events, keeps each pipeline's state and step log on the bus, and serves the run on request (ADR 0666 §7,
§11). An acting part of the step `pipeline` (design 47). Of this domain: its contract is in `mesh-delivery-contracts`.
- **mesh-delivery-view** — the seat, held once for the mesh, of the status view's role (ADR 0540 §1): it serves no
verb and declares one state, `answers`, the person's answers in the web view to the asks of `mesh-wants` that need
no proof of who answered, offered as a view, so the teller follows it by the seat (design 47 G §717). The four
events of ADR 0540 §1 are its holder's own. Of this domain: its contract is in `mesh-delivery-contracts`.
*Not:* ~~status seat~~ (hq)
- **mesh-builds** — the seat, held once for the mesh, whose holder numbers a package's version when it is published and
says the publication as its event `package-published`, on which every artifact built against the package is rebuilt
and its pipeline started (ADR 0666 §15; design 51). Of this domain: its contract is in `mesh-delivery-contracts`.
- **composition step** — the pipeline step that composes each machine's declaration with a change, by the composer built
from its heads in the sandbox, refusing a change in which two modules own one path; served by the seat `mesh-wants`
(ADR 0666 §17). From milestone G's delivery it replaces the **composition check**.
- **composition run** — the one run of the composer for one candidate on one machine, started by the first
composition step of that candidate that needs the machine and kept by the assigner in its state `composition-runs`;
every composition step of the candidate whose module is placed on the machine reads its verdict (design 47 G §718).
Not a **composition**, one module's resources composed for one node; nor the **composition step**, the pipeline
step that reads one composition run per machine.
- **test run** — the one run of a lint, unit test or integration test pipeline step for one candidate, one level and
one set of tested packages at their digests, kept by the runner in its state `test-runs`; every artifact's pipeline step of that candidate
naming the same packages reads its result (design 47 G §724). Not a **pipeline step**, each artifact's own, nor a **run
on request**, a whole pipeline that delivers nothing.
- **merge check** — what a pull request carries before it may merge, judging the merge of its head into a
named **trunk commit**, made in a clone of its own on a build node and never pushed (ADR 0323). One status,
`mesh/check`, written by the checker: the change's tests, run by the language's build module, and the
@@ -663,6 +744,18 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
It keeps the verdicts of the packages it passed for the check to take (ADR 0637). Asked only when the operator
asks for one (ADR 0637 §6). Goes at milestone G's delivery, the **run on request** in its place (ADR 0666 §18); the
word goes to that entry's *Not:* line with the as-is update after that delivery.
- **dry run** — a session's run, before a release is pushed, of the parts that will take it in, build it and merge it,
as they run live, on the revision as the merge will make it: in process on the session's machine, reading the mesh
and writing nothing there. It holds five items: the live take-in run whole with the seat list it will read, every
build against the packages as published, the gate's merge path read for the group, the reviewed heads delivered once
in the lab of one machine from take-in to `delivered`, and no item left open (hq playbook 07, step 2b). A change
of a delivery module, the node-engine, the tool runner, the bus module or the SDK's bus packages never skips it. Not a **try** nor a **run on request**, which the mesh runs and which deliver a verdict; a dry
run owes the forge nothing and is not a check.
- **bus-shape sheet** — the prepare's list, per module a milestone adds or changes, of what the module will be on the
bus: its manifest sections, bus accounts, streams and their subjects, work queues and the process that takes each
queue's asks, durable consumers, and which part creates each; judged by the manifest validator and composed by the
grants part's composer and the node-engine's composer in a test before any code (hq playbook 07, step 0, item 11).
Not a **build map**, which says where each design line lands in code.
- **trunk commit** — the commit of the trunk a merge check's verdict was judged against: the trunk's head when
the build module cloned it. The verdict holds for that commit only, goes out of date when the trunk moves, and
is then carried to the new commit (ADR 0323, ADR 0548). Goes at milestone G's delivery with the merge check: a pipeline
@@ -768,7 +861,8 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
level: a group holds deliveries, never groups. Its state is derived from its members, never set. From milestone G's
delivery: a shared branch name carrying its issue number, complete when each member's commit has landed on its
modules' watched branch, taken in as one source revision of that branch and run as one pipeline per watched branch
(ADR 0666 §13).
(ADR 0666 §13). From milestone H's delivery: the pull requests named in one **merge call**; no branch name and no
pull request read after the call forms one (ADR 0682).
- **hotfix** — one pull request in one repository, delivered at its merge (ADR 0401).
- **feature** — one branch name across its repositories: in two or more, its pull requests are one delivery group,
merged together and delivered member by member in the group's order; in one, a single pull request delivered as a
@@ -842,7 +936,9 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
- **pending revision** — a source revision the running indexer has not taken in, because it names another build of
the indexer or follows one that does: only the named indexer's own keys are written, the rest kept in the
indexer's state `pending` until that indexer starts and takes it in (ADR 0633 §1 to §3). A group's members wait
there too until the group's end, as members still gathered (§4).
there too until the group's end, as members still gathered (§4). Ends at milestone H's delivery: a take-in holds
nothing for a named indexer, and one that cannot be written waits as its unacknowledged `source-moved` (ADR 0682;
design 47 H §744).
- **canary** — the first node of a module's nodes, ordered by ring then name: a new fingerprint reaches it
first and the module's other nodes only once it runs healthy there (ADR 0429 §6). Replaces sending to every
machine at once from release 6 (§15); a fingerprint that fails there is held and the canary set back, or for
@@ -987,10 +1083,20 @@ becomes a message). **Decided by** ADR 0227, 0231, 0240, 0252, 0283, 0564, 0668.
`recreate` of a protected stream, in place (design 47 G §681), and the backup holder only stores copies (design 47 G §554).
**aside** — live kept data a restore set aside, removed only by the hand tool `recovery_discard_aside`, which the operator and sessions call.
*Not:* ~~restorer~~, ~~restore account~~
- **ZFS snapshot** — a read-only point in time of one ZFS dataset on a machine, kept inside that dataset's pool, so
it guards against a mistake and never against the pool's loss; taken by a person with `zfs_snapshot`, or by the zfs
module's scheduled run, which names its own `mesh-<kind>-<time>`, marks them and removes only those past their keep
count (ADR 0679 §8; design 42 zfs-owns-zfs §21, §22). Never bare, beside a ledger's snapshot and the stream snapshot
(see [Homonyms](#homonyms)); not a backup or a restore point, which are kept elsewhere.
*Not:* ~~pool snapshot~~, ~~dataset snapshot~~
- **disk readings** — the size of each data item a node's modules declare, measured by its `measure` and kept
with its largest size in seven days by disk-load on that node, in its own state, one key
`<node>.<module>.<item>` written only when it changes; the holder of `node-backup`, mounts, nfs-server and the
self-check read them there, never the controller (ADR 0571 §5).
- **carry-over** — a module's one copy of the data it kept in its old form into its bus state, at its first start
on the new form and before it does anything else, recorded in a key of its own so it is never copied again
(ADR 0437 §7; design 39 bus-and-switch §11 to §13). Not a take-over, which moves a job between parts.
*Not:* ~~data take-over~~
- **sticky binding** — a consumer's tie to the data a provider keeps for it, which moves only by a
person (ADR 0232).
- **bus state** — what a module keeps on the bus, asked for in `requires` as a provision of the bus module, by a
@@ -1349,11 +1455,11 @@ Not a domain of the mesh but of the way it is built, listed because its words me
should be, and lives only while the milestone is built (playbook 07, step 0).
*Not:* ~~context file~~ (hq)
- **design question** — what a milestone's builder would have to choose because its milestone part does not say it:
a field, a key, a bound, an owner, a caller, an event, a fate for what exists. It is asked of the operator, and its
answer is written into the design before any code builds it (playbook 02); nobody else answers it, save one of
internal form only (changing nothing the operator sees, no permission and no data kept or removed: a wire form, a
function's input, a contract field's shape, a package's place), which the design writer answers as a design line
read by the reviewers by architectural domain (playbook 07, step 0). A milestone's
a field, a key, a bound, an owner, a caller, an event, a fate for what exists, or a place where a design line and
the code disagree. The lead answers it in one line against the principles, naming the principle that settles it;
only one no principle settles goes to the operator (when its answer changes what the operator sees or how they work,
removes data or needs their terminal) or else to the design writer, as a design line read by the reviewers by
architectural domain. Every answer is in an hq commit before any code builds it (playbook 07, step 0b). A milestone's
design is **complete** when no design question of it is open (playbook 07, *Design complete*).
*Not:* ~~open point~~ (hq)
- **issue** — a question about the mesh that someone must answer, numbered and tracked by the issue tracker, which
@@ -1415,6 +1521,7 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical.
| | anything a module reads that someone may change | **config value** | Config |
| snapshot | the latest state of one ledger instance, from which a rebuild starts | **snapshot** of a ledger's state | Data |
| | the bus's own backup of each stream | **stream snapshot** | Data |
| | a read-only point in time of one ZFS dataset, inside its pool | **ZFS snapshot** | Data |
| template | a storage type with a configuration, asked for in `requires` | **template** of bus state | Data |
| | a file with placeholders a provisioner fills | **template file** | Config |
| option | a setting of a template a module may change | **option** of a template | Data |
@@ -1437,6 +1544,7 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical.
| step | an action run on a module's commit before it is delivered | **pipeline step**, always whole | Delivery |
| | the step an acting part acts in (`take-in`, `build`, `compose`, …) | an acting rule's **step** | Delivery |
| | a step a person starts, like the bus's | **planned step** | Core |
| | a resource the node-engine runs to completion before what follows it (`run-once`) | **run-once step** | Module |
| | a step of a rollout | **tier** | Delivery |
| tier | a level of the mesh | **layer** | Core |
| | a step of a rollout | **tier** | Delivery |
@@ -1494,6 +1602,8 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical.
| | the notice that mail matters | **mail signal** | Mail |
| conversation | the domain *Operator and conversation* | the domain's name | Operator and conversation |
| | the mail questions and answers on the mail page | **mail conversation** | Mail |
| part | one independent process of the delivery domain with its own bus credential (ADR 0429 §1) | the part by its name (the **indexer**, the **gate part**, the **grants part**) | Delivery |
| | one of the pieces a module is built of: a bundle, or a resource that places or runs one, in one manifest (ADR 0040; design 20 *What a module is built of*) | **a module's part** (its manager bundle, its tools bundle, its settings file) | Module |
## How this page is kept
+12 -3
View File
@@ -1,6 +1,6 @@
---
status: canonical
updated: 2026-11-11
updated: 2026-11-16
---
# The principles
@@ -22,9 +22,18 @@ add, sharpen or drop a principle in a pull request to this file.
6. **Nothing is exposed publicly.** No data leaves the mesh unasked: no secret in a record, a log or a public
repository, no service reachable from outside unless it is meant to be. Inside the mesh, every agent and module
is trusted; who may do what is not a question to ask.
7. **The simplest thing that works.** Prefer what already exists. No new mechanism unless it is needed, and fewer
parts over more.
7. **No part without a need.** Every mechanism, field, seat and step exists because something needs it; prefer what
exists over a new one, and remove what no longer serves. Never a shortcut instead of the right shape.
8. **One word per thing**, from the [glossary](glossary.md).
9. **Depend on the contract, at the level it is interchangeable.** A module depends on a seat where the mesh means
more than one module to be able to fill the need, and on a module where only that module does; never on another
module's internals.
10. **The module is the unit.** Everything is done per module, never per repository. A repository is only where a
module's files are kept; a merge moves only the modules it changes.
11. **Configurable, never hard-coded.** A value that can differ between machines, modules or over time (a port, a
path, a bound, a cap, a name, a time) is a setting with a default, never written into the code.
12. **A module writes only its own.** A module writes its own files and state alone; what another module needs from it
goes through a provision or a contribution that module declares, never a file written in its place.
How it is checked: the one code review of a milestone checks the code against these principles and the design's
shape; an answer to a develop question names the principle that settles it.
+13 -12
View File
@@ -191,14 +191,15 @@ be built (the cycle test reads only a design's main file today).
## Answering a design question
A design question (playbook [07](07-feature-branches.md), step 0) is answered by the operator and by nobody else:
not by the lead, the preparer, a developer or a reviewer, however technical it is. The one exception is a question
of internal form only (playbook 07, step 0, *Who answers a design question*; the operator, 2026-11-11): changing
nothing the operator sees, nobody's permissions and no data kept or removed, it is answered by `hq-design-writer` as
a design line of the milestone part with its reason, under the record it follows from, read in item 3's round, and
told to the operator in one line. The lead asks it as the
instruction on asking says, one question per ask, with what the milestone part says, what it leaves open, where it
was met (file:line) and a recommendation. Then:
A design question (playbook [07](07-feature-branches.md), step 0) is first answered by the lead, in one line in the
milestone's lead-answers file, tested against the principles (`00-META/principles.md`) and naming the principle
that settles it, with no design batch and no review round (playbook 07, step 0, *Who answers a design question*; the
operator, 2026-11-11). The preparer, a developer and a reviewer answer none. Only a question no principle settles
comes to this section: the operator answers it when its answer changes what the operator sees or how they work,
removes data or needs the operator's terminal; every other one `hq-design-writer` answers as a design line of the
milestone part with its reason, under the record it follows from, read in item 3's round, and told to the operator in
one line. The lead asks the operator's as the instruction on asking says, one question per ask, with what the
milestone part says, what it leaves open, where it was met (file:line) and a recommendation. Then:
1. **Within a record's question** (a field, a bound, an owner, an order of steps, inside what a record decides), the
answer is the design's own choice: `hq-design-writer` writes it as a design line of the milestone part, citing
@@ -213,10 +214,10 @@ was met (file:line) and a recommendation. Then:
(`feat/<slug>`), so its pull request joins the milestone's delivery group, and the builders read the milestone
part at that branch's head.
How it is checked: every design question in the milestone file names the hq commit that answers it; a design line
added during a milestone with no operator's answer or record behind it, other than an answer of internal form only
that touches nothing the operator sees, no permission and no data, is a finding of the review by architectural
domain.
How it is checked: every design question in the milestone file names the hq commit that answers it; a lead's answer
that names no principle, or a design line added during a milestone with no operator's answer or record behind it,
other than the writer's answer to one that changes nothing the operator sees or how they work, removes no data and
needs no terminal, is a finding of the review by architectural domain.
## Amending an existing design
+41 -11
View File
@@ -33,11 +33,22 @@ Three questions, answered from the machine:
`package-manager`, `seat`. A capability is detected and refused against; it is not something a
module can install.
3. **Write the resources in the order they must happen.** They are applied in the order written
3. **Choose each part's form, from the table in [design 20](../../03-DESIGN/01-to-be/20-writing-a-module.md) *What a
module is built of*.** Tools are a `bundle` the tool runner loads (`loads`, and every tool in `tools`); a service of
the module's own code is a `process` resource; a scheduled job says `schedule`, a one-time step `run-once`, a
migration of the module's own state `prepares`; a seat's implementation is a claim and the verbs it serves; an image
is an `image` or `upstream` artifact run by a `container`; a program of the operating system is a `package` and its
`service` resources. A bundle or a package is in Go or TypeScript, the languages the builder has build modules for.
4. **Ask for kept data in `requires`, by template** (`state`, `events`, `work-queue`, `log`, `objects`, `ledger`), each
entry with its `name`, `storage`, `template` and `options`. The old sections `state`, `logs`, `streams` and
`objects` are for the parts the bus module needs before it can answer, and for no new entry anywhere else.
5. **Write the resources in the order they must happen.** They are applied in the order written
and orphans are removed in reverse, so a `network` is written before the containers that join
it and removed after them.
4. **Put every secret in a file, never in `env`.** A declaration travels over the broker in plain
6. **Put every secret in a file, never in `env`.** A declaration travels over the broker in plain
text: a password in `env` is a password the broker sees. **The mesh delivers parts; a module
that needs them combined combines them.**
@@ -67,21 +78,39 @@ Three questions, answered from the machine:
Add `restart-on` naming the env file, or the container keeps the credential it started with
through every rotation.
5. **Pin every image by digest.** A tag moves. The manifest in a repository names artifacts; the
manifest the mesh holds names digests, and they are not the same document.
7. **Pin every image by digest.** A tag moves. An `upstream` artifact's `from`, and a container's `image` written
directly, name `@sha256:`: the builder refuses an upstream reference with a tag alone. The manifest in a repository
names artifacts; the manifest the mesh holds names digests, and they are not the same document.
6. **Decide generate or accept.** A new module's credential is generated. **An adopted one keeps
8. **Decide generate or accept.** A new module's credential is generated. **An adopted one keeps
the credential it already has** — `secret accept` — because minting a new password for a
database that already exists locks the application out of its own data.
7. **Add a provisioner only if the software cannot read a file.** A proxy that watches a
9. **Add a provisioner only if the software cannot read a file.** A proxy that watches a
directory needs nothing. PostgreSQL needs `CREATE ROLE`, an object store needs a bucket and a
policy, an identity provider needs a realm and a client — those need a small program beside
them. It reads what the mesh granted and reconciles; it does not decide anything.
8. **Prove it in the lab, against the real software.** Not that a container started — that the
thing works: the credential authenticates, a wrong one is refused, the containers reach each
other, the data survives a restart.
10. **Prove it in the lab, against the real software.** Not that a container started — that the
thing works: the credential authenticates, a wrong one is refused, the containers reach each
other, the data survives a restart.
## Where the parts of the mesh read a manifest differently
*Written 2026-11-12 from reading the manifest validator, the builder, the node-engine's vocabulary and the tool runner
on their main branches.* The manifest validator accepting a manifest does not yet mean every other part takes it.
Until each of these is closed in the part named, write the form in the right column:
| the manifest validator accepts | but | so write |
|---|---|---|
| a `bundle` or a `package` in any language word | the builder builds only Go and TypeScript bundles and TypeScript packages, and refuses the rest by name at the build | a bundle in Go or TypeScript |
| an `upstream` artifact whose `from` names a tag alone | the builder refuses an upstream reference with no `@sha256:` | the reference with its digest |
| a `log` asked for in `requires` by template | the tool runner's log calls reach only a log of the old `logs` section; a template log is reached only by its stream's read and fill calls, so a module cannot append to it through the runtime | a template log only where the module's own bus account publishes it; a log its tools append to through the runtime waits for the tool runner's fix |
| any `type` and any field on a resource | the node-engine refuses an unknown type and a field the type does not use, when the module is composed for a machine: in the change's composition step only for the machines the change touches, and for a module assigned nowhere never | each resource's fields as the node-engine's vocabulary has them (mesh-sdk's declaration package) |
| `schedule` and `run-once` on a `process` unjudged | the node-engine refuses a process with both, or a scheduled one with `restart-on`, `replaces` or `witness`, or an invalid cron | a process in one mode |
How it is checked: each row is closed by a change in the part it names, which deletes the row in the same pull
request; a reviewer of a manifest reads these rows.
## A module that calls or holds a seat, or shares code
@@ -124,8 +153,9 @@ time and the scaffolding was not.**
## Rules
- **Read the node-engine's log before theorising.** A declaration that was sent and not applied says so
there and nowhere else.
- **Read the check's verdict, then the node-engine's log, before theorising.** The change's check names every
problem the manifest validator and the composition step found; a declaration that was sent and not applied says
so in the node-engine's journal (`<node>/node-service-manager.journal`) and nowhere else.
- **A failing test is kept, not skipped.** It is the reproduction.
- **Never rotate during an adoption.** Rotation is a separate act, afterwards, deliberately.
- **A data directory is never removed by the mesh** (ADR 0030),
+230 -49
View File
@@ -54,23 +54,47 @@ A small fix (one repository, one issue, about an hour of work) follows
and the code; a developer refused an event the design names; and an audit found seven rulings against the records
or the design (among them a store kept twice and a copy of another part's data) and 29 questions the design never
answered, all found in develop. The design is now the only input to the prepare and to develop, the prepare's only
output is where each design line lands and what the design does not answer, the operator answers that (or, for a
question of internal form only, the design writer, step 0), and develop starts only when it is all answered (step 0b, *Design complete*).
output is where each design line lands and what the design does not answer, and develop starts only when it is all
answered (step 0b, *Design complete*). Since 2026-11-11 the lead answers each such question in one line against the
principles, and only one no principle settles goes further (step 0, *Who answers a design question*).
- **A design that met the code only in develop.** On 2026-11-11, in the develop step of milestone 47/G, the lead
answered over 100 questions, most of them a design line meeting the code: a line naming a form the code cannot
take, or assuming a part already built that was not. The prepare had read the design alone. It now reads the code
each design line lands in as well, and lists every place where the two disagree before any developer starts
(step 0, items 3 and 10; the operator, 2026-11-11).
- **A dry run with an open item, taken as a pass.** On 2026-11-13 milestone G of design 47 was pushed with its dry
run's item "the take-in's seat path is not run" still open; once merged, the running indexer refused the milestone's
own indexer and five more modules with the live seat list, and its trunk builds waited on renamed packages only the
take-in would publish. The dry run (step 2b) now runs the live take-in, the builds against what is published and the
gate's merge path, and holds the push while any item is open.
- **A change of the delivery system proven only on the live mesh.** On 2026-11-21 and 2026-11-22 milestone H2 of
design 47 was delivered after a review that approved it, and about 25 faults showed only on the machines: the
node-engine's composer stripped one manifest section of a process and kept another, so the declaration read refused
the milestone's own manifests; a stream's subject was not widened, so an approved registration was never written; a
work queue had no process taking its asks; and a durable consumer left behind for each old form set off the grants
part's alarm. The tests had passed because they created the streams, consumers and takers of asks the broker should
have, or a stand-in for a seat's holder, and the review read the code against the design, not against what the nodes
ran: the tool runner, the build modules and the node-engine still carried the old form, and the parts that judge,
build and compose had to reach the machines first. The prepare now ends with a bus-shape sheet composed in a test
(step 0, item 11), a test that stands in for a part of the mesh is a finding (step 2, item 11), the review reads the
live mesh and names the order of delivery (step 2, item 12), and the dry run delivers the reviewed heads once in the
lab before any pull request opens (step 2b, item 4; the operator, 2026-11-22).
- **A module proven only after it reached the machines.** The mail modules were delivered with unit tests
only, then failed live three times (issues 859, 865, 868) and took five more hours of fixes.
## The shape
One feature is **one branch name**, **one worktree per repository**, **one pull request per repository**,
opened **once**, after the review, and **one check** (ADR 0548). It runs in five steps, with the design completed between the first two (step 0b), and its time is bounded. A milestone has no phases
opened **once**, after the review, and **one check** (ADR 0548). It runs in five steps, with the design completed between the first two (step 0b) and, for a change of what judges, builds, composes or delivers it, a dry run between the review and the check (step 2b), and its time is bounded. A milestone has no phases
(the operator, 2026-10-17): these are its steps, and a report names the step it is in:
| Step | What happens | Bound |
|---|---|---|
| 0. Prepare | from the milestone part alone: where each design line lands in code, what exists there today and what relies on it, as one build map per repository; and every design question, the design's silences, listed | 15 minutes, longer when what exists is large: code never starts on an incomplete answer |
| 0b. Design complete | every design question is answered, by the operator or, for one of internal form only, by `hq-design-writer` (step 0); each answer is written into the milestone part (playbook 02) and its build map rows added | until the list is empty: develop never starts before |
| 0. Prepare | from the milestone part and the design's main file, read whole, then the code each design line lands in: where each line lands, what exists there today and what relies on it, as one build map per repository; every design question, the design's silences, listed; every place where a design line and the code disagree, listed; and a bus-shape sheet per module, composed in a test | 15 minutes, longer when what exists is large: code never starts on an incomplete answer |
| 0b. Design complete | every design question and every place where design and code disagree is answered: by the lead in one line against the principles, or, where no principle settles it, by the operator or `hq-design-writer` (step 0); each answer is written down (the lead's in the milestone's lead-answers file, the others into the milestone part, playbook 02) and its build map rows added; more than ten questions send the milestone back to its design | until the list is empty: develop never starts before |
| 1. Develop | one fixing agent per repository builds every design line of its build map locally, each commit citing the lines it builds, the whole unit suite before every commit, the integration tests compiled, and once per head it reports those of the packages it touched and their importers run against an embedded bus (below); nothing is pushed | the milestone's issues, 30 minutes each |
| 2. Review | one reviewer reads all of it, the local commits, judging the integration tests by reading them against the code; reports go both ways; at most 3 rounds | 15 minutes |
| 2. Review | one reviewer reads all of it, the local commits, judging the integration tests by reading them against the code, a test that stands in for a part of the mesh a finding, each changed module read against the live mesh and the order of delivery named; reports go both ways; at most 3 rounds | 15 minutes |
| 2b. Dry run | for a release that changes a part judging a change, or a module path, a package or a manifest form the take-in reads, and always for one that changes a delivery module, the node-engine, the tool runner, the bus module or the SDK's bus packages: the live take-in run whole with the seat list it will read, every build against the packages as published, the gate's merge path read for the group, the reviewed heads delivered once in the lab from take-in to `delivered`, and no item left open | until no item is open: nothing is pushed before |
| 3. Check | push the reviewed heads once and open the pull requests together; the checker's one check runs the integration tests; no further review unless the check fails | one check run |
| 4. Deliver | merge; the source revision moves, each module is built once and wanted on its nodes, its canary first | until the view says the source revision `delivered` |
@@ -116,7 +140,7 @@ issue whether it is being fixed in between, after the delivery, or waits, and on
`mesh-watcher` for every wait, and the four reviewers by architectural domain and `research-reader` of playbook 01.
The lead writes only the handover: what the agent works on (issue, the design and its milestone part at an hq commit,
branch, worktrees, commits) and where it reports; a handover carries no choice about what is built, and one that
does is the lead answering a design question. A subagent runs in the session that started it, from hq: its way of working comes from its definition and hq's playbooks; what it builds comes from the milestone part and nothing else; one given a coding task works in a worktree under hq's `.work/` and also reads the conventions of the repository it changes, and where those contradict hq, hq wins and the agent says so. How it works, what it reads first and what it judges come from its definition, and so does its model: a
does is the lead answering a design question outside its lead-answers file (step 0b). A subagent runs in the session that started it, from hq: its way of working comes from its definition and hq's playbooks; what it builds comes from the milestone part and the milestone's lead-answers file and nothing else; one given a coding task works in a worktree under hq's `.work/` and also reads the conventions of the repository it changes, and where those contradict hq, hq wins and the agent says so. How it works, what it reads first and what it judges come from its definition, and so does its model: a
`mesh-developer` runs on the smaller model, and the lead starts one on the larger model only for work whose parts meet
at an interface several of the milestone's subtasks build at once (the design names it whole; nothing is designed in
develop), written with its reason in the milestone file; a lesson about how an agent
@@ -129,32 +153,35 @@ follows the decided design and makes no decisions, least of all architectural on
design (playbook [02](02-graduation.md), *The shape of a design*) and the design's main file are what the preparer,
the developers and the code reviewer read whole, and build or judge against. Decision records, the mesh's principles
and the knowledge base were read when that design was written and reviewed by architectural domain; they are not read
again to judge the design while it is built, because a builder who re-judges it builds a second design. Where each
again to judge the design while it is built, because a builder who re-judges it builds a second design. The
principles answer only what the design leaves open (step 0b), never a line it states. Where each
interaction travels (the seat, verb, event, provision, state on the bus, manifest field) is a design line; one the
design does not name is a design question, never the preparer's finding with its own alternative. The mesh paths
are held where they are decided: the reviewers by architectural domain judge the milestone part before it is built
(playbook [02](02-graduation.md), *Answering a design question*).
- **The prepare's only output** is one build map per repository (item 4) and the list of design questions
(item 10). It writes no findings of its own, no recommendations into the build map and no rulings, and no file of
- **The prepare's only output** is one build map per repository (item 4), the list of design questions and the list
of places where a design line and the code disagree (item 10). It writes no findings of its own, no recommendations into the build map and no rulings, and no file of
the milestone holds a statement of how something should be.
- **Who answers a design question** (the operator, 2026-11-11). A question that changes nothing the operator sees,
nobody's permissions (who may call, publish or read what) and no data kept or removed (an internal wire form, a
function's input, a helper's API, a contract field's name or shape, a package's place) is a question of internal
form only: `hq-design-writer` answers it as a design line from the design and its records, with its reason, the four
reviewers by architectural domain read it in one round, and the lead tells the operator each such answer in one
line. Every other design question is the operator's, however technical: not the lead's, the preparer's, a
developer's or a reviewer's, nor a lead's of another session; one that seems internal but touches who may call,
what the operator sees or data is the operator's. The lead's part is the process: who works on what, on which
model, the waits and the reports, and asking the operator.
- **Who answers a design question, and where design and code disagree** (the operator, 2026-11-11, about 21:48
CET). The lead tests each design question and each entry of `Design meets code` (item 10) against the principles
(`00-META/principles.md`) and answers it in one line in the milestone's lead-answers file, naming the principle that
settles it, without a design batch or a review round. Only a question no principle settles goes further: to the
operator when its answer changes what the operator sees or how they work, removes data or needs the operator's
terminal; otherwise to `hq-design-writer`, who answers it as a design line from the design and its records, with
its reason, read by the four reviewers by architectural domain in one round, and the lead tells the operator each
such answer in one line. When unsure whether a question changes what the operator sees or how they work, it goes to
the operator. The preparer, a developer and a reviewer answer none, nor does a lead of another session.
- **One milestone has one lead.** A session that held part of the work hands its branches and heads to the lead and
stops; between sessions travel heads, commits, design questions and the hq commits that answer them, never an
instruction on how to build.
How it is checked: every subtask in a build map and every commit of the milestone cites the design lines it builds
("design NN M §n"), and the review finds code that cites none (step 2, item 2a); the milestone's files hold no
rulings (`grep -n -i 'ruling' .work/<slug>/*.md` finds none); a question answered by anyone but the operator, other than one of
internal form only answered by `hq-design-writer` in a design line the reviewers by architectural domain read, is a
breach the lead names at the next report.
rulings (`grep -n -i 'ruling' .work/<slug>/*.md` finds none); an answer of the lead's that names no principle, a
question answered other than as *Who answers a design question* says, or one sent on that no principle left open, is
a breach the lead names at the next report; the milestone file's `Design meets code` names, for each repository a design line lands in, the `origin/main`
commit the prepare read, and a developer's question that is a design line meeting code the prepare read is a miss
of the prepare the lead names at the next report.
1. **Name the feature once:** `feat/<slug>`, the same branch name in every repository it touches (but see the
exception for a new manifest word in phase 3: a release that must merge first has a name of its own). The
@@ -166,11 +193,17 @@ breach the lead names at the next report.
`main` (`git worktree add --detach .work/<slug>/mesh-tools main`), never symlinks. **A repository's own
clone stays on `main`** (the operator, 2026-10-17): no work is done in it and no branch is checked out
there, so a session that opens in it reads what holds now; fetch and fast-forward it before reading.
3. **Read the milestone part and the design's main file whole**, before any code; the preparer reads nothing else
to know what is to be built. Every question the code or the live mesh raises that the milestone part does not
answer goes onto the list of design questions (item 10), never into an answer of the preparer's or the lead's. A
fixing agent that meets a design question stops that part, and its run is spent again: the prepare is where the
questions are found.
3. **Read the milestone part and the design's main file whole, then the code each design line lands in**, before any
code is written (the operator, 2026-11-11: the prepare reads the code as well as the design). The design is the
only thing the preparer reads to know what is to be built; the code, read at `origin/main` in each repository a
line lands in, says whether the line can be built as written. For each design line the preparer reads the files
and functions it changes, the contracts, types and packages it uses, and the rules the code holds there (a guard,
a check, a test that refuses), and asks three things: can the code take the form the line names; is every part the
line assumes built (a verb, a field, a package, an event, a module) there on main; does the line break a rule the
code holds. Each no goes onto the list `Design meets code` (item 10). Every question the code or the live mesh
raises that the milestone part does not answer goes onto the list of design questions (item 10). Neither is ever
answered by the preparer. A fixing agent that meets either stops that part, and its run is spent again: the
prepare is where both are found.
3a. **Read what exists today, and write it down before any code** (the operator, 2026-11-02: "if i ask to implement
feature A, you'd better first check what exists today with regards to feature A"). Research, decisions, the survey
and the review each check the layer before them; this is the step that checks the running code. Each repository's
@@ -192,7 +225,8 @@ breach the lead names at the next report.
The fate is the milestone part's: the answer cites the design line that gives it, and an effect or a reader no
design line gives a fate is a design question. For every new exported type, field, constant, package or module,
the answer names the design line that places it (the milestone part's, or the design section *Where a seat's
code goes*): where new code goes is always the design's, never the lead's own choice.
code goes*): where new code goes is always the design's, or a lead's answer naming its principle (step 0b), never
a choice nobody wrote down.
**A seat's contract is a design line's form too.** For each seat contract the milestone adds or changes, the
answer compares what the contract on main says (its fields, subjects, callers and kinds) with the design lines
that name that seat, field by field; every difference is a design question (item 10), answered before develop
@@ -288,39 +322,71 @@ breach the lead names at the next report.
concerns (or the section where a line is missing), what the line leaves to its builder, where the prepare met it
(file:line or the tool's answer), and the preparer's recommendation, said as a recommendation. A design that
contradicts a decision in force, a reader or an effect with no fate, a lifetime, a caller, a bound, a field's
form, a tool for a new state: each is a question. The list is the prepare's last output and step 0b's input.
form, a tool for a new state: each is a question.
Then, under `Design meets code`, every place item 3 found where a design line and the code disagree, each with
the design line, the code (file:line at the `origin/main` commit read), which of the three it is (a form the code
cannot take, a part the line assumes built that is not, a rule in code the line would break), and the preparer's
recommendation, said as a recommendation. The two lists and the bus-shape sheets (item 11) are the prepare's last
output and step 0b's input.
11. **Write a bus-shape sheet per module, and compose it in a test, before any code** (the operator, 2026-11-22). For
each module the milestone adds or changes, `.work/<slug>/<module>.bus.md` lists what the module will be on the bus
once the change runs: its manifest sections (each process, its `bus`, `serves` and `requires`), its bus accounts,
its streams with their subjects, its work queues with the process that takes each queue's asks, its durable
consumers, and for each of these who creates it (the bus module from the module's `requires`, the grants part, the
module's own process at its start). Each row cites the design line that gives it; a row no design line gives is a
design question (item 10). The sheet is judged as the mesh will judge it, in a test in the preparer's worktree: the
manifest validator judges the manifests the sheet describes, with the live seat list, and the grants part's
composer and the node-engine's composer (the composition of `mesh-delivery-sdk`) compose them; each must take the
sheet as written. A refusal is an entry under `Design meets code`. A composer a test cannot import is a gap of the
build and delivery system, said to the lead and built there before develop (the grants part's composer belongs in
the SDK, beside the composition of `mesh-delivery-sdk`); never a sheet left unjudged. The sheet is what the
developers' tests and the reviewer's reading of the live mesh (step 2, items 11 and 12) hold the change to.
How it is checked: every module a build map changes has its sheet, with the test that composed it and its result
(`ls .work/<slug>/*.bus.md`); a fault of the bus's shape met after the push that the sheet omits is a miss of the
prepare, named at the next report.
## Step 0b — Design complete
Develop starts only when the milestone's design questions are all answered, each in the design (the operator,
2026-11-10: a question the design does not answer stops that part, goes to the operator, and its answer goes into
the design before the code).
Develop starts only when the milestone's design questions and the entries of `Design meets code` are all answered,
each in an hq commit (the operator, 2026-11-10: a question the design does not answer stops that part, and its
answer is written down before the code; 2026-11-11: the lead answers it against the principles).
1. **The lead sorts each question and asks the operator's.** A question of internal form only (step 0, *Who answers
a design question*) goes to `hq-design-writer` in its handover; every other one the lead asks the operator, one per
ask, as playbook [02](02-graduation.md), *Answering a design question*, says, and adds each ask to its wait list.
The lead answers none and passes on no answer of its own; a question the writer finds is not of internal form only
it hands back for the operator.
2. **Each answer is written into the milestone part** by `hq-design-writer` on hq's branch of the milestone, as a
design line (the operator's citing the operator and the date, the writer's own giving its reason) (or, outside every record's question, after its decision record), and the four reviewers by
architectural domain read the amended part in one round.
1. **The lead answers each question against the principles**, in one line in the milestone's lead-answers file
(beside the milestone part, cited as "design NN M A-n"), naming the principle that settles it (step 0, *Who answers
a design question*). **Before an answer names a field, a key, a bucket, a subject or a function, the lead reads it
where it lives** (the code at the join head, or the seat definition) and checks the answer against what is there,
not against the question's words (2026-11-12: three answers that day named a structure from memory and needed a
correction once a developer read the code). One no principle settles the lead sends on: to the operator, one per ask, as playbook
[02](02-graduation.md), *Answering a design question*, says, each ask added to its wait list, when its answer
changes what the operator sees or how they work, removes data or needs the operator's terminal; every other one to
`hq-design-writer` in its handover. A question the writer finds is the operator's it hands back.
2. **An answer the lead does not give is written into the milestone part** by `hq-design-writer` on hq's branch of
the milestone, as a design line (the operator's citing the operator and the date, the writer's own giving its
reason) (or, outside every record's question, after its decision record), and the four reviewers by architectural
domain read the amended part in one round.
3. **The preparer adds the new lines to the build maps** (item 4) and the question's entry names the hq commit that
answers it.
4. **The design is complete** when every entry names its answering commit. Then step 1 starts, from the milestone
4. **The design is complete** when every entry of both lists names its answering commit. Then step 1 starts, from the milestone
part at that commit.
5. **More than ten design questions send the milestone back to its design** (the operator, 2026-11-22). When the
prepare leaves more than ten entries in `Design questions` and `Design meets code` together, the milestone part is
not ready to be built: the lead answers none of them one by one, hands them all to `hq-design-writer` as one
amendment of the milestone part (playbook [02](02-graduation.md)), read by the four reviewers by architectural
domain, and the prepare runs again on the amended part. Develop starts only from a prepare that left ten or fewer.
How it is checked: the milestone file's two lists, counted at the prepare's end (`grep -c`), and the hq commit of
the amendment when they held more than ten.
**A question met later stops only its part.** A developer or the reviewer who meets a question the milestone part
does not answer stops the subtasks that need the answer, says the question to the lead with the design line and
file:line, and goes on with the subtasks that do not; the lead adds it to the list and asks it as above, and the
stopped subtasks resume from the hq commit that answers it; one of internal form only goes to `hq-design-writer` as
item 1 says. Nobody builds around it, guesses it or builds both ways.
file:line, and goes on with the subtasks that do not; the lead adds it to the list and answers it, or sends it on,
as item 1 says, and the stopped subtasks resume from the hq commit that answers it. Nobody builds around it, guesses it or builds both ways.
**A decision accepted while the milestone is built** that changes its part stops the subtasks of the lines it changes
until the part is amended (playbook [02](02-graduation.md)) and their build map rows are redone; code written before
the design was complete joins the milestone only where each of its commits builds a design line of the complete part,
and the review reads it as new code.
How it is checked: the milestone file's `Design questions` all name an answering hq commit older than the first
commit of step 1 (`git log` of each repository's branch against hq's); a commit with no design line, or one built on
How it is checked: the milestone file's `Design questions` and `Design meets code` all name an answering hq commit
older than the first commit of step 1 (`git log` of each repository's branch against hq's); a commit with no design line, or one built on
an answer no hq commit holds, is a finding of the review (step 2, item 2a).
## Step 1 — Develop (one fixing agent per repository, smaller model)
@@ -341,7 +407,10 @@ an answer no hq commit holds, is a finding of the review (step 2, item 2a).
the test calls what the change adds, the agent takes out the change's effect (the line that does it, not the new
function), sees the test fail, and puts it back (2026-10-19: a check request's new field was proven by a test of
its helper alone, and dropping the field from the request passed every test); `gofmt`, `go vet` and the whole unit suite stay green. **The tests are written from the issue's
acceptance criteria**: one test or more per criterion at the level it names, each test's comment citing
acceptance criteria**, and **a test never stands in for another part of the mesh** (step 2, item 11): it creates no
stream, consumer or taker of a work queue's asks that the bus module or the grants part should create, and fakes no
seat's holder in a whole test; it composes what it needs with the parts' own composers, from the bus-shape sheet
(step 0, item 11). One test or more per criterion at the level it names, each test's comment citing
the criterion it proves by its label (`// 1118/AC2`), and no criterion left without its test; an integration criterion is a test
that compiles and is run by the pull request's one check. The integration tests (those that start a store, a bus
or a process) are compiled with `go vet -tags integration ./...` while developing and run by that check. **Once per head it
@@ -480,11 +549,113 @@ an answer no hq commit holds, is a finding of the review (step 2, item 2a).
the record behind it, the lead brings it to the operator as a design question, and the code waits for the answer
in the design. How it is checked: the review report has a line for each question with its answer, and the lead reads both before the
push; a report without them is not an approval.
11. **A test that stands in for another part of the mesh is a finding, by rule** (the operator, 2026-11-22). A test
that creates a stream, a consumer or a process taking a work queue's asks where the bus module, the grants part
or the node-engine should, or that fakes a seat's holder in a whole test, proves what the test made, not what the
mesh will make: on 2026-11-21 milestone H2's tests passed on streams and takers they created themselves, and the
live broker made neither. The fix is the test composing what it needs with the parts' own composers (the grants
part's and the composition of `mesh-delivery-sdk`), from the module's bus-shape sheet (step 0, item 11); a
composer it cannot import is a gap of the build and delivery system, built there in the milestone, never a stand-in
kept. A unit test's fake of a function's own collaborator is not this; a stand-in for a part another module
holds is. How it is checked: the review report lists every new or changed test that creates bus state or fakes a
seat's holder, each with the composer that should make it, and a report without that list is not an approval.
12. **Each changed module is read against the live mesh, not only the design** (the operator, 2026-11-22). The
reviewer reads, through the mesh MCP server's tools, what runs on the nodes today: each node's haves of every
module the change touches or relies on, and which parts still carry the form the change replaces (the tool runner,
the build modules, the node-engine, the indexer and its manifest validator, the grants part). For each, it asks
whether the running version can take in, judge, build, compose or page the change's new form. Then it names, in
its report, **the order of delivery the change needs**: the parts that judge, build, compose or page the new form
first, then the modules that use it, each step an ordering edge of the module graph the delivery plan derives
(instruction design-it-as-it-should-be), or, where no edge carries it, a gap of the build and delivery system for
the lead to bring to the operator. A part still on the old form that no step of the order brings over makes the
change wrong. How it is checked: the review report holds a section `Live mesh` naming each node's build read for
each such part, with its time, and the order of delivery; the lead copies the order into the milestone file and
the dry run (step 2b, item 4) delivers in it. A fault met after the merge from a part on the old form is named at
the next report.
## Step 2b — Dry run (a change of the delivery system, or of what the take-in reads)
**When it runs.** After the review approves the heads and before the push of step 3, for every release that changes a
part judging a change (step 3, item 3: the indexer and its manifest validator, the gate, the builder, a build module,
the checker or the pipeline runner, the node-engine, a seat definition), and for every release that adds or renames a
module path or a package other modules take, or changes the form of manifests the take-in reads. **A release that
changes a delivery module, the node-engine, the tool runner, the bus module or the SDK's bus packages never skips it**,
and no rule is weighed against that (the operator, 2026-11-22: milestone H2's faults would each have shown in one
delivery off the machines). The prepare step's milestone file says per release whether it runs and why (`Dry run: yes`
or `no`, with the reason); the review refuses a group that lists a judging part with no such line, and a `no` for a
release that changes one of the parts just named. The operator, 2026-11-13: "remember the mistake and make sure our
pipeline catches this".
**What it is.** A dry run runs the parts that will take the change in, build it and merge it, as they run live, on the
revision as the merge will make it: in process on the session's machine, reading the mesh and writing nothing there,
asking no try and no check. An agent of hq's definitions runs it, read-only on the mesh and on every working copy; the
lead writes only the handover. Everything live it uses (the builds the nodes run, the seat list, the published
versions, the trunks) is read in the same hour as the push, and read again, with the dry run run again, when a head,
a main or a live build moves before the push. Five items, each held before any push:
1. **The live take-in, run whole.** The indexer that will take the revision in (the running one, read from the view's
reach of its module; for a revision that names another build of the indexer, the running one, which keeps it
pending, and the named one, from its start) runs on the revision: every member's head merged onto its base's main as
it is now, the other trunks' manifests as the indexer's state holds them, and **the seat list as the take-in will
read it**, which is the seat list the seat `mesh-catalog`'s verb `seat-definitions` answers at that moment, not the
group's own definitions laid over it (step 1's brief lays them over for the developer's case; the take-in does not).
It runs through to the keys the take-in would write (each fingerprint, a pending revision, a group's members
gathered), never the manifest validator alone. A manifest refused, a module set aside, or a revision left pending
with no indexer that can take it in is a fault of the release: it is fixed in the release, or what the running parts
cannot take in is delivered first (step 3, item 3), before the push.
2. **Every build against the packages as published.** Every build the revision starts (each module whose fingerprint it
moves, as the indexer's run of item 1 lists them) is built with `GOWORK=off` and no `replace` toward a local tree,
each mesh package resolved from the registry seat of its language as that seat serves it at that moment (its verb
`versions`), never from the group's heads. A new or renamed module path, or a package that only the revision's own
take-in or build would publish, shows here as a package with no published version: a circle in which the build
waits on a take-in that waits on the build. It is a gap of the build and delivery system, built there before the
push (in the same milestone or before it) and said to the operator, never pushed into.
3. **The gate's merge path, read for the group.** Before the push, and again before the operator's Approve is asked:
each member's base, read with `mesh-delivery.show` (the gate never hands a member whose base is not the branch it
merges into, and every member after it in the gate's order waits behind it); the group itself, read with
`mesh-delivery.show` on the group's id, open and holding every member (a pull request reopened into a group the gate
holds closed joins it as a lone delivery); and every member present before the first ask. The gate merges a group's
members one at a time and undoes none, so one member it cannot merge leaves the group half merged. A member on
another base is moved to the gate's branch or left out of the group, a group the gate holds closed is pushed under a
new branch name, and an Approve ask that names fewer members than the group is ended and said to the operator,
never answered.
4. **The reviewed heads delivered once in the lab, from take-in to delivery** (the operator, 2026-11-22). The lab of
one machine raises the mesh's four node roles on the session's machine (the control-node's parts, a build node's,
the bus module and a node-engine with its tool runner), with an embedded bus and store, from the builds the nodes
run now (item 1's reading). The reviewed heads are merged there and run the whole way once: the take-in, the
pipeline and its steps, the builds, the grants part's memberships, the compositions, the wants, the node-engine's
apply and the tool runner's start, in the order of delivery the review named (step 2, item 12), until the lab's
view says the source revision `delivered` and every changed module runs healthy and answers its tools. A step that
refuses, holds or stands still is a fault of the release, fixed and reviewed before the push. Where the lab cannot
yet raise a part (no bed for it), that is a gap of the build and delivery system, built in the lab in the same
milestone or before it and said to the operator; the item is never closed as "not run". The pull requests open
only after this item passed.
5. **No item open.** The dry run's report says of each item what ran, at which heads and on which live builds, and its
counts ("ran: 193 manifests, 0 refused, seat list read at 13:05"). An item said "not run", "not known" or "read, not
run" is closed, by running it or by showing why it does not apply, or the push is held: **a dry run with an open
item is not a pass**, and no rule is weighed against it. Before the push the lead says to the operator, in one line
per item, what each showed.
The faults it answers, 2026-11-13: milestone G of design 47 was pushed after two dry runs, the second of which said
"with the live seat list 26 refused; the take-in's seat path is not run", and the lead pushed with that item open.
Once merged, the running indexer took the revision in with the live seat list and refused the milestone's own indexer
and five more modules. The milestone renamed module paths, and the trunk builds waited for packages that only the
take-in publishes; no dry run had built a trunk module against the published packages alone. The same day the gate
merged a group one member at a time with no undo, stopped at a member whose base was not main, and asked an Approve
while a group was still forming and per member of a closed group.
**How it is checked.** The milestone file holds a section `Dry run` with each of the five items' result, the lab
run's source revision and its `delivered` time among them, the reviewed heads it ran
on and its time (`grep -n -A6 '^## Dry run' .work/<slug>/milestone.md`), older than the push (the forge branch's
first push of the heads) and with no item open; the pull requests' description names it in one line. A push of a
release whose milestone file lists a judging part with no such section, or with an item open, is this step skipped;
a fault met after the merge that an item would have shown is named at the next report and written here as a lesson.
## Step 3 — Check (no review)
1. **Push the reviewed heads once, then open one pull request per repository, together** (ADR 0548; the operator,
2026-10-26: "every release should only run 1 check or 1 try"). **No pull request, draft or not, exists before the
2026-10-26: "every release should only run 1 check or 1 try"), after the dry run where step 2b asks one, with no
item open. **No pull request, draft or not, exists before the
review approves the heads**, and no fix round is pushed to an open pull request: every push to an open pull request
asks a new check, of every member for a group, and the mesh's build capacity is spent on it ("we don't have more
processing power"). The integration tests run once, in the checker's merge check on the merge with the trunk's head, at the unit
@@ -582,7 +753,8 @@ an answer no hq commit holds, is a finding of the review (step 2, item 2a).
4. **The milestone's acceptance is proven by its check.** A milestone that adds or changes a module
carries an integration test that starts the module whole, its process against the real bus and store, and
shows the milestone's acceptance sentence; the forge's checks run it (ADR 0391 §1, §6). Unit tests alone are not
that proof; the mesh has no end-to-end tests yet, and the lab is not used (the operator, 2026-10-16).
that proof; the mesh has no end-to-end tests yet, and the lab is used only for the dry run's delivery (step 2b,
item 4; the operator, 2026-10-16 and 2026-11-22).
**A new manifest word's test goes through the first composition that meets it, not only the verb that fills it.**
On 2026-10-19 release 1 of feature mail-sender tested a process's own bus account through `module issue`
alone; the first push after mesh-mail declared the process composed a random 40-character stand-in for the
@@ -849,6 +1021,15 @@ issues in `fixing` that nobody works on reads to the operator as stuck work.
item 6b). A fixing agent started on a file without the section, or an effect of a removed or moved part met only
after the delivery, is the prepare step skipped, named in the next detailed report and written into the playbook's
lessons here.
- A release whose milestone file lists a part judging a change, or that changes a delivery module, the node-engine,
the tool runner, the bus module or the SDK's bus packages, holds a `Dry run` section with all five items closed, the
lab's delivery among them, older than its push (step 2b); one pushed without it, or with an item open, is that step
skipped.
- Every module a build map changes has its bus-shape sheet with the test that composed it (step 0, item 11); a
milestone developed from a prepare that left more than ten design questions, with no amendment of its part between,
is step 0b item 5 skipped.
- Every review report holds the list of tests that create bus state or fake a seat's holder (step 2, item 11) and the
section `Live mesh` with the order of delivery (step 2, item 12); a report without either is not an approval.
- No issue of a running milestone is sized over an hour in its prepare note; an issue whose fixing agent passes
twice its bound was not split.
- Every issue of a running milestone has a note from the prepare step naming its files and tests (file:line), how
+7 -6
View File
@@ -45,12 +45,13 @@ processing power"). Everything before the push is local and fast, and no try is
seat's code goes*. The note names, for everything the fix adds or changes (an exported type, field, constant,
package or module, a state, a verb, an event, a bound, a caller), the design line that gives it. A fix that only
makes the code do what its issue and its design already say needs nothing more. Anything no design line gives is
a **design question**: the session asks the operator, one question with its recommendation, and the answer is
written into the design (playbook [02](02-graduation.md), *Answering a design question*) before any code builds
it; neither the session nor the lead answers it. A question of internal form only (playbook
[07](07-feature-branches.md), step 0, *Who answers a design question*) is answered instead by `hq-design-writer`
as a design line, read by the four reviewers by architectural domain in one round, and told to the operator in
one line. A handover to the developer quotes the design lines and never
a **design question**, answered as playbook [07](07-feature-branches.md), step 0, *Who answers a design question*,
says, before any code builds it: the session's lead answers it in one line against the principles
(`00-META/principles.md`), written in the issue's note, naming the principle that settles it; one no principle
settles goes to the operator, one question with its recommendation, when its answer changes what the operator sees
or how they work, removes data or needs their terminal, and otherwise to `hq-design-writer` as a design line
(playbook [02](02-graduation.md), *Answering a design question*), read by the four reviewers by architectural
domain in one round and told to the operator in one line. A handover to the developer quotes the design lines and never
decides a placement itself (2026-11-04: a class placed in mesh-sdk by a lead's handover, against that section,
passed review and its check). A fix that turns out to need a second repository, or more than about an hour,
stops here and becomes a feature; one that needs a design question answered stays a small fix. **The session's own model (the larger) then writes the issue's acceptance
+8 -7
View File
@@ -282,7 +282,8 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
<h3>Step 0 · what the lead writes before any agent starts</h3>
<ul style="margin:6px 0;padding-left:20px;font-size:14px">
<li><span class="tag new">new</span>The milestone part of the design is the only input: the prepare maps each design line onto code (a build map per repository, each row citing its line) and lists every design question, what the design does not answer. It writes no findings or rulings of its own.</li>
<li><span class="tag new">new</span>Design complete: the operator answers each question, or the design writer one of internal form only (no change to what the operator sees, no permission, no data kept or removed), read by the reviewers by architectural domain; the answer is written into the milestone part, and only then does develop start. Nobody else answers one.</li>
<li><span class="tag new">new</span>The prepare reads the design whole, then the code each design line lands in, and lists under Design meets code every place where they disagree: a form the code cannot take, a part the line assumes built that is not, a rule in code the line would break. The lead answers each in one line against the principles before develop starts.</li>
<li><span class="tag new">new</span>Design complete: the lead answers each question in one line against the principles, naming the principle; only one no principle settles goes to the operator (when it changes what they see or how they work, removes data or needs their terminal) or else to the design writer as a design line, read by the reviewers by architectural domain. Develop starts only when every answer is in an hq commit.</li>
<li><span class="tag new">new</span>What exists today, read from the code and the live mesh, never from memory: every effect of a part removed or moved (bus writes, files, credentials, plans, processes, calls answered), every reader relying on each, what happens to each after the change and its test. It opens each build map; no code before it is complete, and the review refuses work without it.</li>
<li><span class="tag new">new</span>Subtasks ordered so a user starts from the commit that adds its contract; one writer per file; one placement of the siblings for every agent.</li>
<li>Into each issue: every file and test it touches (file:line), how it is checked and delivered, a group's merge order.</li>
@@ -467,7 +468,7 @@ const P = [
{n:"06",name:"Writing a module",kind:"side",c:"--side",
trig:"Something that runs today must run on the mesh.",
who:"Whoever ports or writes it.",
steps:["Read what runs: compose file, environment, where data sits.","Name what it provides and requires.","Declare capabilities for machine facts.","Write resources in the order they must happen.","Every secret in a file, never in env.","Pin every image by digest.","New: generate the credential; adopted: accept it.","Prove it against the real software: auth, refusal, restart."],
steps:["Read what runs: compose file, environment, where data sits.","Name what it provides and requires.","Declare capabilities for machine facts.","Choose each part's form (design 20).","Kept data in requires, by template.","Write resources in the order they must happen.","Every secret in a file, never in env.","Pin every image by digest, upstream too.","New: generate the credential; adopted: accept it.","Prove it against the real software: auth, refusal, restart."],
prod:"A module declaration, optionally a provisioner, and its proof.",
next:"07",bounds:"no time bound",
prev:["A service running with no password","A new password locking out adopted data","A test that cannot fail"],
@@ -475,15 +476,15 @@ const P = [
{n:"07",name:"Features",kind:"build",c:"--build",
trig:"Work that changes code across issues or repositories, too large for a small fix.",
who:"A lead (larger model), one fixing agent per repository (smaller), one reviewer (larger).",
steps:["Prepare: name the branch, make the worktrees, read the milestone part and the design's main file whole. (new)","Every agent is one of hq's definitions (mesh-preparer, mesh-developer, mesh-code-reviewer, mesh-watcher); the lead writes only the handover. (new)","The prepare's only output: a build map per repository, each row a design line and where it lands, and the design questions. No rulings. (new)","Design complete: the operator answers every question (the design writer one of internal form only), each written into the milestone part; then develop. (new)","Read what exists today from the code and the live mesh: every effect of what is removed or moved, every reader of each, what happens to each and its test. No code before it is complete; the review refuses work without it. (new)","The build map opens with what exists today; subtasks ordered contract first, one writer per file.","Write the findings and acceptance criteria into each issue.","Survey every other reader and writer of each changed value. (new)","Answer three questions in the milestone file: who deletes each new key and stream, how the switch-over is tried on one node first, what the one check does not cover. The review checks them. (new)","List every part the change reaches; copy fixtures from the real writer.","Develop: one agent per repository, one commit per subtask, each citing its design lines; a question stops only its subtask. (new)","A test fails first on behaviour, not on compiling. (new)","Bring each branch up to the trunk; nothing is pushed, no try runs. (new)","Review all of it against the design lines, code no line asks for a finding, reading the integration tests against the code; at most 3 rounds; the report answers the state-and-seams and mesh-agnostic questions. (new)","A group pins the group's own mesh-sdk head in every member. (new)","Push the reviewed heads once and read each forge head against the reviewed commit; no draft pull request, no fix round on an open one. (new)","Open one pull request per repository, together, with Reviewed-by and Pushed-by; the one check runs. A failed check is read, fixed, reviewed, pushed once more. (new)","The operator's Approve on Telegram; the group merges in one pass.","Follow the delivery in the status view (moving, settled, stuck, delivered) to done; resolve the issues; clean up. (new)","When the builder cannot deliver its own fix: revert, a build by a session's call, a registration at the terminal, copies kept outside the store; a broken controller is put back by a want the operator writes, a hand build by mesh-hand-compose and a want. (new)"],
steps:["Prepare: name the branch, make the worktrees, read the milestone part and the design's main file whole, then the code each design line lands in. (new)","List every place where a design line and the code disagree, beside the design questions. (new)","Every agent is one of hq's definitions (mesh-preparer, mesh-developer, mesh-code-reviewer, mesh-watcher); the lead writes only the handover. (new)","The prepare's only output: a build map per repository, each row a design line and where it lands, and the design questions. No rulings. (new)","Design complete: the lead answers every question against the principles; one no principle settles goes to the operator or the design writer; then develop. (new)","Read what exists today from the code and the live mesh: every effect of what is removed or moved, every reader of each, what happens to each and its test. No code before it is complete; the review refuses work without it. (new)","The build map opens with what exists today; subtasks ordered contract first, one writer per file.","Write the findings and acceptance criteria into each issue.","Survey every other reader and writer of each changed value. (new)","Answer three questions in the milestone file: who deletes each new key and stream, how the switch-over is tried on one node first, what the one check does not cover. The review checks them. (new)","List every part the change reaches; copy fixtures from the real writer.","End the prepare with a bus-shape sheet per module (manifest sections, accounts, streams and subjects, work queues and who takes their asks, who creates each), judged by the manifest validator and composed by the grants part's and the node-engine's composers in a test; more than ten design questions send the milestone back to its design. (new)","Develop: one agent per repository, one commit per subtask, each citing its design lines; a question stops only its subtask. (new)","A test fails first on behaviour, not on compiling. (new)","Bring each branch up to the trunk; nothing is pushed, no try runs. (new)","Review all of it against the design lines, code no line asks for a finding, reading the integration tests against the code; at most 3 rounds; the report answers the state-and-seams and mesh-agnostic questions. (new)","A test that stands in for another part of the mesh (a stream, consumer or taker of asks it creates, a faked seat's holder) is a finding; the review reads each changed module against the live mesh and names the order of delivery: the parts that judge, build, compose or page first. (new)","Dry run, for a change of what judges, builds or merges it: the live take-in run whole with the seat list it will read, every build against the packages as published, the gate's merge path read for the group, the reviewed heads delivered once in the lab of one machine from take-in to delivered; an item left open holds the push, and a change of a delivery module, the node-engine, the tool runner, the bus module or the SDK's bus packages never skips it. (new)","A group pins the group's own mesh-sdk head in every member. (new)","Push the reviewed heads once and read each forge head against the reviewed commit; no draft pull request, no fix round on an open one. (new)","Open one pull request per repository, together, with Reviewed-by and Pushed-by; the one check runs. A failed check is read, fixed, reviewed, pushed once more. (new)","The operator's Approve on Telegram; the group merges in one pass.","Follow the delivery in the status view (moving, settled, stuck, delivered) to done; resolve the issues; clean up. (new)","When the builder cannot deliver its own fix: revert, a build by a session's call, a registration at the terminal, copies kept outside the store; a broken controller is put back by a want the operator writes, a hand build by mesh-hand-compose and a want. (new)"],
prod:"One pull request per repository, one source revision delivered, resolved issues, no branch or worktree left.",
next:"02 (when it ships)",bounds:"Prepare 15 min · 30 min per issue · review 15 min, ≤ 3 rounds · one check, pushed once",
prev:["Pull requests as scratchpads","Context bought again and again","A change built on what was remembered, not on what runs","Review rounds spent on what a run would show","A node agent's bus reads, proven only by review"],
check:"The checker's one status, mesh/check; the review record; the tracker's move."},
next:"02 (when it ships)",bounds:"Prepare 15 min, at most ten design questions · 30 min per issue · review 15 min, ≤ 3 rounds · one check, pushed once",
prev:["Pull requests as scratchpads","Context bought again and again","A change built on what was remembered, not on what runs","Review rounds spent on what a run would show","A node agent's bus reads, proven only by review","A dry run with an open item, taken as a pass","A change of the delivery system proven only on the live mesh"],
check:"The checker's one status, mesh/check; the review record; the dry run's section in the milestone file, the lab's delivery among its items; the bus-shape sheets; the review's Live mesh section; the tracker's move."},
{n:"08",name:"Small fixes",kind:"build",c:"--build",
trig:"One issue in one repository, about an hour of work.",
who:"The session, with one reviewer on the larger model.",
steps:["Read the issue, the design lines it builds and the code; a design question goes to the operator (one of internal form only to the design writer) and into the design before code. (new)","Read what exists in the fix's area today, briefly: every reader of what the fix changes. (new)","Write the acceptance criteria.","Move the issue to fixing.","Build on fix/<issue>-<slug> in its own worktree.","A test that fails today first, on behaviour. (new)","Nothing is pushed and no try runs before the review. (new)","One review of the local commit.","Push the reviewed head once; only then open the pull request. (new)","The operator's Approve; the merge; the delivery, followed in the status view. (new)","Prove the fix live and resolve the same hour.","During a milestone: ride in its delivery group, unless broken for the operator now. (new)"],
steps:["Read the issue, the design lines it builds and the code; a design question is answered by the lead against the principles (one no principle settles by the operator or the design writer) before code. (new)","Read what exists in the fix's area today, briefly: every reader of what the fix changes. (new)","Write the acceptance criteria.","Move the issue to fixing.","Build on fix/<issue>-<slug> in its own worktree.","A test that fails today first, on behaviour. (new)","Nothing is pushed and no try runs before the review. (new)","One review of the local commit.","Push the reviewed head once; only then open the pull request. (new)","The operator's Approve; the merge; the delivery, followed in the status view. (new)","Prove the fix live and resolve the same hour.","During a milestone: ride in its delivery group, unless broken for the operator now. (new)"],
prod:"One pull request, one delivery, a resolved issue.",
next:"—",bounds:"About an hour · one review, one push, one check",
prev:["A fix reviewed after its pull request opened","A long part run twice","A fix waiting on someone else's delivery","Ten SDK merges and eight controller merges in a day, one per fix"],
+216 -134
View File
@@ -3,36 +3,65 @@ layer: to-be
status: proposed
code:
- mesh-catalog modules/showcase
- mesh-controller internal/builder
- mesh-sdk src
- mesh-delivery modules/mesh-delivery-indexer/judge (the manifest validator)
- mesh-delivery modules/mesh-delivery-builder
- mesh-sdk go/catalogue (the manifest's shapes)
- mesh-sdk go/declaration (the node-engine's resource vocabulary)
- mesh-contracts
updated: 2026-11-05
updated: 2026-11-18
decisions:
- "ADR 0680"
- "ADR 0578"
- "ADR 0595"
- "ADR 0619"
- "ADR 0634"
- "ADR 0635"
- "ADR 0625"
- "ADR 0627"
- "ADR 0573"
- "ADR 0605"
- "ADR 0606"
- "ADR 0607"
- "ADR 0609"
- "ADR 0593"
- "ADR 0150"
- "ADR 0099"
- "ADR 0053"
- "ADR 0499"
- "ADR 0498"
- "ADR 0478"
- "ADR 0436"
- "ADR 0366"
- "ADR 0316"
- "ADR 0267"
- "ADR 0259"
- "ADR 0262"
- "ADR 0348"
- "ADR 0564"
- "ADR 0596"
- "ADR 0201"
- "ADR 0193"
- "ADR 0192"
- "ADR 0189"
- "ADR 0175"
- "ADR 0152"
- "ADR 0150"
- "ADR 0142"
- "ADR 0135"
- "ADR 0099"
- "ADR 0074"
- "ADR 0053"
- "ADR 0052"
- "ADR 0040"
- "ADR 0039"
- "ADR 0053"
- "ADR 0005"
---
# Writing a module
A worked guide. One module, four capabilities, four languages, and the packages it publishes.
A worked guide: what a module is built of, the manifest form of each part, and the packages it publishes.
The reference for *what can be said* is [`18-building-a-module`](18-building-a-module.md); the
reference for *what the code and the mesh say to each other* is
[`19-the-module-protocol`](19-the-module-protocol.md). This is how you actually write one.
The reference for *what a manifest may say* is the manifest validator, the rules of the seat `mesh-catalog`'s holder
that judge every manifest (ADR 0578 §1), with [design 32](32-what-a-module-declares.md) for what the bus makes of it;
the reference for *how a build is modelled* is [design 18](18-building-a-module.md); the reference for *what the code
and the mesh say to each other* is [design 19](19-the-module-protocol.md). This is how you actually write one.
## First: what is in the SDK, exactly
@@ -93,136 +122,177 @@ the build modules' regenerate-and-compare step, the catalog check of a client an
contracts module that claims a seat; the home of each new exported name, a domain SDK's importers included, and a role
made a seat or a seat left as one module's tools, by the review of the pull request that adds it (ADR 0634 §10).
## A module with four capabilities, in four languages
## Who reads a manifest, and what each one judges
A module is **one piece of software** (ADR 0040) and
may still be written in several languages — each artifact names its own, compiles alone and is
packed alone.
*Rewritten 2026-11-12 from the manifest validator's code on mesh-delivery's main (the operator, 2026-11-12: "first
look into the indexer's code that reads the manifest and update our module-development documentation accordingly").*
```
showcase/
module.json
events/ ← TypeScript: reacts to what the mesh does
tools/ ← Go: answers questions
provisioner/ ← Rust: grants instances of what it provides
ingest/ ← Python: a scheduled job
```
A manifest is read by four parts, and each judges only what is its own:
### The manifest
| part | reads | judges | where a refusal is said |
|---|---|---|---|
| the **manifest validator**, the rules of the seat `mesh-catalog`'s holder (the indexer) | every manifest it takes in, and every manifest a change touches, at the change's head | the manifest strictly: every field known, at every depth; every rule a manifest is held to alone (a name's form, an artifact's words, a claim on a seat of the seat list, kept data, events, secrets, health, a container's `run-once`, `schedule` and `while-stopped`) and every rule between the manifests of one catalog | the change's check, naming each problem; and the indexer's verdict, which every other part takes (ADR 0578 §1, §2) |
| the **builder** and its build modules | `build` | which build module builds each artifact (`kind` and `language`) and whether an upstream reference is pinned by digest (ADR 0478, ADR 0498) | the build's refusal, naming the artifact |
| the **node-engine**, through its composer in the change's composition step and on each node | the resources of each module composed for one node | each resource's `type` and fields strictly, by the node-engine's vocabulary (mesh-sdk's declaration package): a field a type does not use is refused, never ignored, and an `action` is refused (ADR 0005) | the composition step of the change, for each machine the change touches; the node's verdict at apply |
| every other part (the assigner, the grants part, the tool runner, the provisioner) | the manifest, decoded leniently | nothing: it takes the indexer's verdict (ADR 0578 §3) | — |
```json
{
"module": "showcase",
"build": { "artifacts": [
{ "name": "events", "kind": "bundle", "language": "typescript",
"entrypoints": ["index.js"] },
{ "name": "tools", "kind": "bundle", "language": "go",
"entrypoints": ["tools"] },
{ "name": "provisioner", "kind": "bundle", "language": "rust",
"entrypoints": ["provisioner"] },
{ "name": "ingest", "kind": "bundle", "language": "python",
"entrypoints": ["ingest.py"] }
]},
"resources": [
{ "id": "events", "type": "process", "name": "showcase-events",
"artifact": "events", "run": ["node", "index.js"] },
{ "id": "tools", "type": "process", "name": "showcase-tools",
"artifact": "tools", "run": ["./tools"] },
{ "id": "grants", "type": "process", "name": "showcase-grants",
"artifact": "provisioner", "run": ["./provisioner"] },
{ "id": "ingest", "type": "process", "name": "showcase-ingest",
"artifact": "ingest", "run": ["python", "ingest.py"],
"schedule": "0 3 * * *" }
]
}
```
**A field the running manifest validator does not know** makes the indexer set the manifest aside to wait for a newer
validator; the change's check, which runs the validator built from the change's head, refuses it (ADR 0578 §1, as
changed). So a field is added to the validator in the same change that first writes it.
**Four artifacts, four toolchains, four processes, one module.** Nothing here says how any of them
is hosted — that is the mesh's, and it is why these are `process` rather than four containers.
The manifest validator does not judge a resource's own fields: those are the node-engine's vocabulary, judged where a
module is composed for a machine. A module assigned to no machine is therefore judged by the validator alone.
### Step 1 — say what it is, in each language's own terms
## What a module is built of
Each part is an ordinary project in its language, depending on the mesh SDK for that language the
way it would depend on anything:
A module is **one piece of software** (ADR 0040), and may be built of several parts. Each part is an artifact in
`build.artifacts`, named locally, and most are run by a resource in `resources` that names the artifact by its
`artifact` field: the resolved manifest names the artifact's digest where the repository's manifest names the
artifact (a `source` and a `digest` for a bundle or an archive, an `image` for an image).
```
events/package.json "@novox/mesh-sdk": "^1.2.0"
tools/go.mod require novox.example/mesh-sdk v1.2.0
provisioner/Cargo.toml mesh-sdk = "1.2"
ingest/pyproject.toml dependencies = ["mesh-sdk~=1.2"]
```
**The artifact kinds** the manifest validator accepts are five, and a builder builds each with one build module:
**Resolved from the mesh's own package registries**, which are the ordinary registries for each
ecosystem, hosted by the mesh. An author does nothing unusual: `npm install`, `go mod tidy`,
`cargo build`, `pip install` all work, and a developer's laptop resolves exactly what a build does.
| kind | its words | built by |
|---|---|---|
| `bundle` — the module's own code | `language`; for Go also `system` (one of the systems the mesh builds for), `from` (the package it compiles, relative to the module) and `binary`; for TypeScript `entrypoints` and, where it keeps imports, `external`; `loads`, `env` and `bus` for a tools bundle (below); `paths` for a language other than Go | the Go or the Node build module: a bundle in Go or TypeScript (ADR 0478); a bundle in another language is a build module of its own first |
| `package` — code other modules compile against | `language` (Go or TypeScript), `series`, `paths` (the files it is built from, ADR 0499), `generated-from` for a contracts module's | its language's build module, which asks the registry seat of its language to publish it (ADR 0605 §3, ADR 0606) |
| `image` — a container image built from a recipe | `from` (a Dockerfile), `target`, `compiles` (the Go package a recipe compiles, ADR 0267), `context` (a second repository its build reaches into) | the image build module |
| `upstream` — somebody else's image, copied | `from`, a reference pinned by its digest (`@sha256:`) | the image build module (ADR 0498 §4) |
| `archive` — files packed as they stand | `from` (a directory of the module), or an upstream release by `url`, `sha256` and `version`, with `file` or `within` (ADR 0316) | the Go build module |
### Step 2 — write each part against its capability
Every artifact may also say `needs` (an edge no other line says), and every kind but `upstream` its `series`. A `bundle` reached by nothing (no
`loads`, no `tools`, no resource naming it) is refused by name (issue 216); a resource naming a `package` is refused,
since a package is a build input and runs nowhere.
Each uses only the part of the protocol it needs. The event consumer never learns what a grant is.
**The parts, and the manifest form of each:**
```
events/index.ts on("module.builder.built", …) → the events capability
tools/main.go tool("showcase_state", …) → the tools capability
provisioner/main.rs grant → credential → the provisioning capability
ingest/ingest.py emit("module.showcase.ingested", …) → events, emitting only
```
| part | the manifest form | what runs it |
|---|---|---|
| **tools** | a `bundle` with `loads` naming what the runtime loads (for a Go bundle its `binary`), and the module's `tools` listing every tool it serves; `replaces` for the shell commands a tool replaces | the node's tool runner (ADR 0175); with `runs-as`, a **runtime of its own** under the module's account (below) |
| **a long-running service of its own code** | a `process` resource: `artifact` (a bundle), `name` (what the unit is called), `run` (the command, relative to the unpacked bundle), `user`, `env` and `env-file`, `restart-on`, `health`, `yields`, `replaces` (the ids it takes over from) | the node-engine, as a unit that stays up |
| **its own bus account for a process** | the process's `bus`: the `emits`, `state`, `queues`, `invokes` and `asks` it is granted, a subset of what the manifest declares; an own secret holding the account, owned by the account the process runs as, whatever that account (ADR 0680 §1; *Whose a process's own secrets are*, below) | the grants part composes the account from it |
| **a scheduled job** | a `process` or `container` resource with `schedule`, a five-field cron; never with `run-once`; a process with no `restart-on`, `replaces` or `witness`; a scheduled container may name `while-stopped` (below) | the node-engine, again on each fire (ADR 0053) |
| **a one-time step** (a seed, a first-start step, a validator of a file) | a `process` or `container` resource with `run-once` true: a **run-once step**, which gates every resource after it; `restart-on` makes it run again when what it names changes (ADR 0052, ADR 0099) | the node-engine, to completion |
| **a migration of its own state before a new version runs** | `prepares` true, and a `container` or `process` that stays up running an artifact the module built: the mesh runs that program in its preparation mode (ADR 0135); never a run-once step written by hand for it | the node-engine, before the new version starts |
| **a seat's implementation** | `claims`, each `{name, scope, serves}` for a seat on the seat list (the verbs it serves; a kinded seat's `kind`); a seat the module defines for itself in `seats`; the verbs answered by its tools bundle or a process | as its tools or its process |
| **an image** | an `image` or `upstream` artifact, and a `container` resource naming it by `artifact`; or a container naming an image pinned by digest in `image` directly, for an image the module does not copy; a container stays up unless it says `run-once` or `schedule` | the node-engine, on the container runtime the module's `capabilities` name |
| **a host program from the operating system** | a `package` resource (`package`, `absent`) and a `service` resource per unit it ships (`unit`, `state`, `boot`, `scope`, `restart-on`, `reload-on`, `health`); never an `action` | the node's package manager and service manager |
| **files** | `file` and `directory` resources (a directory by `place` or `path`), an `archive` resource unpacking an `archive` artifact, template files in the module's `templates` directory | the node-engine and the provisioner client |
### Step 3 — the mesh does the rest
**Whose a process's own secrets are** (ADR 0680). *Amended 2026-11-18.* Every own secret a process reads, its bus
credential first, is owned by the account that process runs as, whatever that account is: an account the module
makes (a `user` resource of that name), the operator account (`${machine:account}`), or root (ADR 0680 §1). The
manifest names it, as the secret's `owner` or the module's `secrets-owner`, and the process runs as it (its `user`)
or as root, as the second rule below holds; the node-engine writes the secret owned by it at mode 0600 (ADR 0680 §1). An account the module makes stays
the usual case, not a rule; a process that declares `bus` still names the account it runs as. ADR 0436 §1's "never
root and never the operator account" no longer holds for a process that declares `bus`, and the manifest validator's
two rules that refused them (as an own secret's owner and as a `bus` process's account) are gone (ADR 0680 §2). The
manifest validator holds two rules instead:
You do not write a Dockerfile, a unit file, or a port number. The builder picks the toolchain from
the language, compiles each artifact alone, and publishes it. The controller assigns the machine
and the ports; the node-engine writes the units.
- **Every account named is one the mesh knows.** An own secret's `owner`, a `secrets-owner` and the account of a
process that declares `bus` are each the operator account, root or an account the module makes; any other is
refused, and so is a `bus` process naming no account (ADR 0680 §2).
- **A process can read every own secret it names.** A process resource that names an own secret (its path in the
process's `run` or `env`) and runs as neither that secret's resolved owner (its `owner`, else `secrets-owner`) nor
root is refused (ADR 0680 §3). A container module is excepted, since a container reads its secrets as its own
account, and a process account's secret needs no such rule, since it is delivered owned by the process's account
(ADR 0436 §2).
### What it costs you to use four languages
A secret owned by the operator account is as private as what runs as that account on its node: the node's tool
runner, and through it every agent session there (ADR 0436 §9). That exposure is accepted (ADR 0680 §1); what bounds
a process account's credential is its grants, which answer no tool and no seat's verb (ADR 0436 §3). A module's
`runs-as` is unchanged: it names an account the module makes (ADR 0259 §8, below).
**Honestly: four sets of dependencies to keep current, and four SDKs that must agree.** The mesh
makes it possible, not free. A module in one language is simpler, and the reason to use four is
that one of them genuinely suits a part better — not that you can.
*How it is checked:* the node-engine's tests write an own secret owned by the account its manifest names, at mode
0600, for an account the module makes, for the operator account and for root; the manifest validator's tests, run on
every change of the validator and over every manifest a change of mesh-catalog touches, accept an own secret owned by
`${machine:account}` or root, a `bus` process running as either, a process running as the resolved owner of the own
secret it names (also through `secrets-owner`), a process running as root, and a container module naming another
account's own secret, and refuse a `bus` process naming no account or one the module does not make, and a process
naming another account's own secret; the controller's grant test still finds no process account able to answer a
call (ADR 0680 §4).
**A runtime of its own.** A module that says `runs-as` names an account it makes (a `user` resource of that name,
never root nor the operator's); its tools bundle is then served by a runtime of its own, as that account, on a bus
account of its own (ADR 0259 §8), whose readiness is the manifest's `runtime-health` (ADR 0366). Its secrets belong to
that account (`secrets-owner`), and its bus account's secret is the own secret `broker`. A tools bundle that holds an
account of its own instead says `bus` on its artifact, a Go bundle only, with the own secret `broker-<binary>` in a
directory the runtime's account may pass (ADR 0564).
**What it keeps on the bus.** Kept data is asked for in `requires`, each entry in its long form: `name` (a local name,
lower-case letters, digits and hyphens), `storage` (`key-value`, `stream`, `object-store` or `ledger`), `template`
(`state`, `events`, `work-queue`, `log`, `objects`, `ledger`) and its `options`, or a bare stream's `configuration`
(ADR 0595 §1 to §3). The manifest validator holds each option to its bound. The **old sections** `state`, `logs`,
`streams` and `objects` are kept by the parts the bus module needs before it can answer, and by no new entry
anywhere else: those parts ask nothing by template, and any other module's use of an old section is refused once no
accepted module outside them uses that section any more (ADR 0619 §1, ADR 0595 §11). One local name is in one form.
A module reads another module's data by asking its tools or seat verbs, never by its bus state (ADR 0201, as changed
by ADR 0596).
**What it says and hears.** `emits` names its events locally; `consumes` names `<emitter>.<event>`, with `*` for one
name and `**` for the rest; `invokes` names each tool `<module>.<tool>` or verb `seat:<seat>.<verb>` it calls, or `*`,
and an entry's long form `{verb, fields}` names the fields of the answer it relies on (ADR 0152); `uses` names the
seats it sends to; `needs-approval` marks a tool, verb or event that waits for the operator's approval.
**What someone may change.** Each config value a module reads is declared once under `config` (or its alias
`settings`, never both), with its type, its default where it is a preference, and whether it is trusted; a file takes
it by `takes-config` or a template file's `${config:<key>}` (ADR 0262, ADR 0348).
*How it is checked:* the manifest validator's tests (mesh-delivery modules/mesh-delivery-indexer/judge) refuse each
form above that a manifest gets wrong, by name; the builder's plan test refuses a kind or language no build module
builds; the node-engine's declaration tests refuse a field a resource type does not use; and the showcase module in
mesh-catalog declares one part of each kind its language allows and composes on a node.
## The showcase, worked
The catalog's `showcase` module is the worked example: **one TypeScript bundle, several entrypoints, every mode**.
| part | artifact | resource | its words |
|---|---|---|---|
| the module's code | `code`, a `bundle` in TypeScript, `entrypoints` for the tools, the provisioner, the service, the run-once step and the report | — | — |
| a run-once step | `code` | `migrate`, a `process` | `run` the step's entrypoint, `run-once` true, `env-file` |
| the service | `code` | `server`, a `process` | `run` the service's entrypoint, `user` the module's account, `env-file`, `restart-on` its settings file |
| a scheduled report | `code` | `reporting`, a `process` | `run` the report's entrypoint, `schedule` a five-field cron |
| a container from somebody else's image | `helper`, an `upstream` pinned by digest | `tools`, a `container` | `network`, `volumes` mounting its broker secret, `args` |
| packed files | `files`, an `archive` from a directory | `packed`, an `archive` | `path`, `unknown` |
| its settings file | `templates`, the module's templates directory | `settings`, a `file` | `path`, `mode`, `template` |
| a seat it defines for itself | — | — | `seats`, and `claims` of it |
Nothing in it says how any part is hosted beyond its resource type — that is the mesh's: the builder picks the
toolchain from the language, compiles each artifact alone and publishes it, the assigner places the module, and the
node-engine writes the units. **A module in several languages is several bundles**, each naming its own language and
compiled alone; each language is one more build module the mesh must have, and one more set of dependencies to keep
current. The reason to use two is that one genuinely suits a part better, not that you can.
### Its code, in each language's own terms
Each part is an ordinary project in its language, depending on the mesh's packages the way it would depend on
anything, resolved from the mesh's own package registries, which are the ordinary registries for each ecosystem
hosted by the mesh (the registry seats, ADR 0605): `npm install` and `go mod tidy` work, and a developer's laptop
resolves what a build does. **A Go module requires a mesh package at the zero version only**: the builder builds
against the newest version of the package series the manifest's `packages` accepts (ADR 0573 §2, §4, ADR 0606), so no
member of a change names another's version.
Each part uses only the part of the protocol it needs: the event consumer never learns what a grant is, and a run-once
step emits only.
## Publishing a package is a capability
A module may publish libraries as well as run code. **The SDK is not special; it is simply the first
module that did this**, and its own consumers are the mesh's modules.
```json
{
"module": "plex",
"build": { "artifacts": [
{ "name": "server", "kind": "upstream", "from": "plexinc/pms-docker@sha256:…" },
{ "name": "client-ts", "kind": "package", "language": "typescript", "from": "clients/typescript" },
{ "name": "client-rust", "kind": "package", "language": "rust", "from": "clients/rust" },
{ "name": "client-py", "kind": "package", "language": "python", "from": "clients/python" }
]}
}
```
A `package` artifact is built and **published to the mesh's registry for that ecosystem**, under the
version its own project file declares. Another module then depends on it the ordinary way:
```
"@novox/plex-client": "^2.0.0"
```
A `package` artifact, in Go or TypeScript, is built from the trunk and **published to the mesh's registry seat for its
language** under its next version, `<series>.<n>`, which the builder counts (ADR 0606 §1 to §3); a branch's build is a
tagged version, taken only by a build that asks its tag (ADR 0607). Another module then depends on it the ordinary
way, accepting a package series by its manifest's `packages`.
**Why this belongs to modules rather than being a separate thing.** A client for a piece of software
changes when that software changes, and the module that owns the software is the only thing that
knows. Putting the Plex client anywhere else is the shared-library disease with extra steps.
### What this leaves open
- **Which private registry.** That there *is* one is settled —
ADR 0014 says each module consumes its dependencies
from the private registry, the mesh's own shared library included. Which software serves it is
not: the catalog holds `verdaccio`, and a git host usually serves package registries too.
- **And the bootstrap does not have one.** ADR 0014 assumes a registry exists; on a fresh mesh
nothing has installed one when the first SDK is built. That is the same pivot as everything else
and it has not been designed.
- **Who may publish.** A builder pushing a package needs an account on that registry, which is a
credential in the bootstrap path and does not exist yet.
- **Versions and ranges.** Everything else the mesh delivers is pinned by digest, and a range is
resolved at build time from whatever the registry holds. A lock file records what was chosen, and
the builder records that as the build edge — but *a mesh that can rebuild a commit and get a
different library* is a real change from how everything else here works, and it should be a
decision rather than a consequence.
What design 20 once left open here is decided: the registries are the registry seats (ADR 0605), who publishes is the
build module of the package's language, and a build resolves a series, never a range, recorded as its build edge
(ADR 0606, ADR 0573).
## A file and the thing that reads it are guarded by a gate
@@ -230,47 +300,59 @@ knows. Putting the Plex client anywhere else is the shared-library disease with
The apply is not a transaction: every resource is attempted, every failure reported, and only a
failed gate stops what follows it (ADR 0053).
So a push can half-happen, and the pairing that matters is a configuration file beside the
So a send can half-happen, and the pairing that matters is a configuration file beside the
service that reads it. A module keeps that pair correct by declaring them in this order: the file;
a `run-once` container that validates it; the service, with `restart-on` naming the file. A file
the validator refuses reaches the disk and nothing else — the gate fails, the service after it is
left as it was, and the machine reports the push failed. The service never serves what the
validator refused. That is the grouping, made from what the manifest already has; no primitive
a run-once step (a `run-once` container or process) that validates it; the service, with `restart-on` naming the
file. A file the validating step refuses reaches the disk and nothing else — the gate fails, the service after it is
left as it was, and the machine reports the send failed. The service never serves what the
step refused. That is the grouping, made from what the manifest already has; no primitive
withholds a file from the disk, and a service that reads its file live rather than at start is the
one shape this does not protect, and should not be written.
*How it is checked:* the lab's coupled-pair spike declares exactly this pair, pushes a refused
*How it is checked:* the lab's coupled-pair spike declares exactly this pair, sends a refused
file, and asserts the file on disk is the new one, the service serves the old one, and the machine
reports the push failed.
reports the send failed.
A `run-once` step may itself name what it reads under `restart-on`; for a step the word means
A run-once step may itself name what it reads under `restart-on`; for a run-once step the word means
*run again* — a step that fetches a fact from a provider names the binding it reads, and runs
again when the provider moved. The service that consumes what the step made names the step, so it
is recreated with the new fact
(ADR 0099). *How it is
checked:* the node-engine's unit tests run a step again when its named file changed and not otherwise,
and recreate a container naming a step after the step ran.
checked:* the node-engine's unit tests run a run-once step again when its named file changed and not otherwise,
and recreate a container naming a run-once step after it ran.
## A recurring step may hold its own module's containers still
## A scheduled run may hold its own module's containers still
*Written 2026-10-02, from ADR 0189
and [issue 108](../../04-ISSUES/108-the-registry-has-no-garbage-collection-once-it-has-two-doors/00-report.md).*
Some work cannot be done underneath a running service: an artifact store's collector rollouts the
storage and requires every writer stopped. A `run-once` step runs *beside* containers and a
scheduled one is the same container again, so until this a module had no way to say it — and the
storage and requires every writer stopped. A run-once step runs *beside* containers and a
scheduled run is the same container again, so until this a module had no way to say it — and the
mesh inherited a store that has never collected anything, because the predecessor said it with a
shell script and a script beside a module is not a resource in it.
A scheduled step may name `while-stopped`: resource ids of **its own module's** containers, which
the node-engine stops before the run and starts again after it, in the reverse order, **whatever the step
A scheduled container may name `while-stopped`: resource ids of **its own module's** containers, which
the node-engine stops before the run and starts again after it, in the reverse order, **whatever the run
did**. Three boundaries, each refused where it can be seen earliest — its own module's containers
only, because a module that could quiesce a neighbour could stop the mesh; scheduled steps only,
because at apply the declaration is applied in order and a step already gates what follows, so a
only, because a module that could quiesce a neighbour could stop the mesh; scheduled runs only,
because at apply the declaration is applied in order and a run-once step already gates what follows, so a
one-time offline job says *before* rather than *instead of*; and restoring that is not conditional
on anything, because the only real risk of the field is a window that never closes.
*How it is checked:* the node-engine's unit tests assert stop–run–start in that order, the restart after a
step that **failed**, the reverse order for several containers, and a service left down said
loudly. The controller refuses, from the definition alone, a window with no schedule, one on a
run-once step, one naming a container the module does not declare, and one naming itself.
run that **failed**, the reverse order for several containers, and a service left down said
loudly. The manifest validator refuses, from the manifest alone, a window with no schedule, one on a
run-once container, one naming a container the module does not declare, and one naming itself.
## Acceptance
- A manifest written by this design's tables is accepted by the manifest validator, built by the builder and composed
by the node-engine for a machine, with no form one of them refuses: checked by the showcase module's check on every
change to it.
- Every refusal names the module, the part and the field, where its author reads it: the change's check.
## Milestones
None of its own. This design is the guide every module's change follows; a change to what a manifest may say is a
decision and a change of the manifest validator, the builder or the node-engine first, and this design follows it.
@@ -397,3 +397,10 @@ clause of the record that statement cites, as it was before the move; "§ 12.n"
23 readers of ADR 0615 §1 and move in the next milestone, queued on issue 1966. The manifest validator still refuses a moved module's subscription to an event
its owner does not declare. Every other reader moves when its module is next touched. These moves are tracked by
issue 1966.
## The lead's answers
- **L1** (issue 1966, met three times on 2026-11-12: a merged module's new build waited for its part grant): a candidate's
manifest that a merge makes a module's trunk manifest is newly accepted in §1, so the indexer's merge pass says
`manifest-accepted` from the verdict it holds even when that verdict was written for the candidate before the merge
and is unchanged; a reader that receives it below the revision it holds treats it as a gap (§12.2) (P3, P1).
@@ -0,0 +1,559 @@
---
layer: to-be
design: 39
milestone: bus-and-switch
updated: 2026-11-11
code: [mesh-catalog modules/claude-licence-manager, mesh-catalog modules/claude-code, mesh-catalog modules/mesh-vault]
decisions:
- "ADR 0183"
- "ADR 0206"
- "ADR 0209"
- "ADR 0054"
- "ADR 0550"
- "ADR 0595"
- "ADR 0596"
- "ADR 0437"
- "ADR 0564"
- "ADR 0570"
- "ADR 0230"
- "ADR 0380"
- "ADR 0253"
- "ADR 0289"
- "ADR 0349"
---
# Design 39, milestone bus-and-switch — the licence manager on the bus, switching on its own usage
**What it builds.** The seat `anthropic-licence-manager` keeps everything it holds in the bus's own storage, by the
kept-data templates, and its store database goes; every grant and token moves into the vault, as ADR 0550 §3 has it;
and the manager itself moves every consumer off a licence whose session or weekly usage reaches a threshold, to the
licence with the most room, says each switch as an event and to the operator, and raises a condition when no licence
has room. Its tools read all it keeps and start by hand all it does. The whole shape is in the design's main file
([39](../39-the-anthropic-licence-manager.md)); this part holds every line the milestone builds, cited as "design 39
bus-and-switch §n".
**Why now.** The operator, 2026-11-11 22:10 to 22:20 CET: "build it in the licence manager, but make it configurable
of course, also remove the postgres database in favor of a bus store, implement useful tools, as much relevant state
as possible"; earlier that evening: "when the current licence usage is at 99%, switch to a licence that still has
room" (first said at 98, then 99), "on all nodes". That night every node was bound to one licence that reached 99 % of
its weekly window, and a session meant to switch them missed the readings: so the manager switches on its own
readings, and never a session. Issue 1409 (no warning before a licence's limit) is fixed in the same change (§30).
**Where.** One repository, mesh-catalog, and three of its modules: `claude-licence-manager` (the seat's holder),
`claude-code` (the agent module on every node, the consumer) and `mesh-vault` (the seat `mesh-vault`), with hq for this
part, the main file and the glossary. The order between them is the module graph's, each an edge the delivery plan
derives (§50).
**The lead's answers, by the principles.** Four questions no accepted record settled were answered on 2026-11-11 by
the lead of issue 1409, against hq's principles, as the operator's way of working since 21:15 that evening has it (the
lead answers develop and design questions against the principles; no decision record is written for a detail). Each
line they reach names its answer:
- **A1, the vault's own-account rule** (§15 to §17). ADR 0550 §3 waits until the licence manager and each agent
module run under a bus account of their own (ADR 0349 §11, issue 569); both run in their machine's tool runner,
under its account. Settled by principle 6 (inside the mesh every agent and module is trusted; who may do what is not
a question) and the operator's instruction that who may do what is not the operator's question (approved
2026-11-11 21:15 CET): the vault serves licence secrets to the tool runner's account. Its check that the asking
machine is the node the binding names stays, as a guard against mistakes, not as a permission.
- **A2, the switch without a record** (§24 to §33). ADR 0183 §21 (moving a consumer is a person's act), ADR 0206 §16
(no `licence.switched` event) and ADR 0206 §18 (every later change is a person's act) are in force. The operator
decided, 2026-11-11 about 21:10 to 22:20 CET: switch automatically at 99 %, on all nodes, configurable; and said that
night not to write records for what they decided. So the operator's answer of 2026-11-11 replaces those three
clauses for this module, and no record is written.
- **A3, how the first start reads today's rows** (§1, §11, §14). A build whose manifest no longer requires
`postgres-database` is composed with no credential for it, and `mesh-store.query` refuses the grant column. Settled
by principle 7 (the simplest thing that works): this milestone keeps `requires postgres-database`, and the `secret`
`grant-key` that opens the grants at rest, as the carry-over's read-only source; dropping both, and the database's
retirement on the operator's Approve, is the module's next change once `licences_carried` (§44) shows the
carry-over done. The delivery gap this names: no path hands a build the credential of a provision its manifest
dropped, so a module cannot read its retiring database at the first start of its new form.
- **A4, no wait for design 47's milestone G** (§9, §50). Settled by principle 7: this milestone ships soon, built only
on what main holds today (mesh-sdk, the vault, the operator channel, and today's way a module says a condition,
ADR 0437 §9), so it uses neither G's writer nor its stream.
## The kept data on the bus
1. **The manifest asks for its kept data by template, and keeps its database only as the carry-over's source.**
It gains one `bus-state` entry per piece of kept data, each in the typed long form (ADR 0595 §1): the local name,
the storage type, the template and its options, as §2 to §9 list them. The old section `state` (today
`bindings`) and the `reads` entry `claude-code.holdings` go: the module moves to the new form whole (ADR 0595 §11),
keeping the local name `bindings` so its data stays. `requires` keeps `postgres-database` and the `secret`
`grant-key`, with their `contributes`, `binds`, `secrets` and the resource `database-url`, read only by §11 and
never written (A3); the run-once step `prepare`, which makes the tables, goes, since nothing writes them again.
`uses` gains `operator-channel` (§9, §28). Why: the operator, 2026-11-11, and principle 1; the templates are
ADR 0595 §2; A3. How it is checked: the manifest validator accepts the manifest at the merge check; a catalog test
finds no `reads`, old `state` or `prepare` in it; a unit test finds no write to the database in the code.
2. **State `licences`: one key per licence, no secret in it.** Template `state`, option `history` 1. The key is the
licence's key form (§10). The value: `name`, `kind` (`subscription` or `api-key`), `account` (the account id),
`address`, `organisation`, `refreshFingerprint`, `accessExpiresAt`, `refreshExpiresAt`, `failures` (refreshes
failed in a row), `notifiedAt`, `adoptedAt`, `adoptedFrom` (the node), `rotatedAt`, `generation` (the vault
secret's, §15), and `usage`, the latest reading of §24 (`sessionPct`, `sessionResetsAt`, `weeklyPct`,
`weeklyResetsAt`, `sonnetPct`, `sonnetResetsAt`, `readAt`, `readError`). Written by the manager alone, at each
adoption, rotation, failure and reading; deleted by no act of the milestone (a licence is never removed today, and
none is added here). It replaces the table `licence`, less its column `sealed`, which goes to the vault (§12).
Why: ADR 0550 §3 keeps the licence records without a secret in the manager; principle 4 keeps the latest reading
beside its licence so `licences` answers from one key. How it is checked: unit, a rotation and a reading each write
the key and no field holds a token; the after-move scan of §20.
3. **State `bindings`: one key per consumer.** Template `state`, option `history` 8, so the last moves of a consumer
are read with the state's `history` call. The key is the consumer's: the node's name for a node's agent, `<node>.<worker>`
for a worker (ADR 0183 §19). The value: `licence` (its name), `kind`, `generation` (one more at every rotation and
every switch of that consumer, ADR 0206 §13), `since`, `why` and `by` (who or what moved it last: a person's
name, `login` for ADR 0209's move, `usage` for §26). Written by the manager alone; deleted by `release`. It replaces
the table `binding` and today's old-section state of the same name. Why: ADR 0206 §13; the eight past values are
the design's choice, for `licences_switches` to show a consumer's last moves. How it is checked: unit, `bind`,
`switch`, `release` and §26 each write or delete the key with its `why` and `by`.
4. **State `leases`: one key per lease, ended by its holder or its lifetime.** Template `state`, option `history` 1,
with a lifetime per key of 2 minutes (the time one exchange with the vendor is given today). The key is
`licence.<licence key>` or `account.<account id>`; the value names the holder (the process) and `until`. A lease
is taken by creating the key, which fails while another holds it, before the licence is read (ADR 0183 §6); the
holder deletes it at the end; a holder that dies leaves it to its lifetime. It replaces the table `lease`. Why:
ADR 0183 §6 keeps one rotation source; a create that fails is the bus's own compare-and-set. How it is checked:
unit, two refreshes started together rotate once and the second answers "another run holds its lease"
(the main file's first acceptance test).
5. **State `offered`: one key per grant a node offered.** Template `state`, option `history` 1, a lifetime per key
of 90 days. The key is the refresh token's fingerprint; the value: `node`, `account`, `outcome` (`adopted`,
`dead`, `refused`), `why`, `at`. Written at each candidate's outcome (ADR 0206 §9, §10); deleted by its lifetime,
after which a fingerprint offered again is tried once more and recorded again. It replaces the table `offered`.
Why: the manager never exchanges a dead candidate twice within its lifetime; 90 days is longer than a refresh
token lives. How it is checked: unit, a dead candidate is not exchanged at its second report.
6. **Log `usage`: every reading, kept 35 days.** Template `log`, options `max-age-days` 35 and `max-mib` 256, one
subject per licence key. Each entry: `at`, the flattened reading of §24 and `raw`, the vendor's answer whole
(ADR 0054). Written at every reading, never rewritten. It replaces the table `usage`. Why: ADR 0054 keeps the raw
reading beside the normalised one; 35 days hold five weekly windows, and at five minutes for four licences
the log stays under a quarter of its cap. How it is checked: unit, a reading appends one entry under its licence's
subject; the bus module's fill condition (ADR 0595 §6) warns before the log is full.
7. **Log `audit`: every act, kept for good.** Template `log`, option `max-mib` 64, no age, one subject per kind:
`adopted`, `refused`, `failed`, `rotated`, `bound`, `switched`, `released`, `drift`, `carried`, `settings`. Each
entry: `at`, `by`, `why` and the act's own fields (for `switched`: §27's). Written after each act, never rewritten.
It replaces the table `audit`. Why: ADR 0183 §5 keeps the audit of every switch; a log keeps it in order and for
good. How it is checked: unit, each act appends one entry under its kind.
8. **State `carried`: the carry-over's record.** Template `state`, option `history` 1, one key `postgres`: `at`, and
for each table of today's database the rows read and the entries written. Written once, at the end of §11; never
deleted, since its presence is what keeps a second start from carrying over again. Why: ADR 0437 §7's way of
carrying a module's state over once. How it is checked: §13.
9. **Its conditions are said on the operator channel, and kept in its own state `conditions`.** The manager says
each condition of §11, §29 to §31 and §33 as any module does on main today (ADR 0437 §9): published on
`mesh.seat.operator-channel.accept.condition.claude-licence-manager` (the subject the operator channel's contract
names, through its client in mesh-contracts), carrying the condition's `key`, `severity` (`urgent` or `warning`),
`scope` and `id`, `raised` or `cleared`, its `summary` and ADR 0253's words (`headline`, `needs`, `explanation`
opened by its verdict, `resolved` and `actions`); the router alone decides whether and where the operator is told.
It keeps each condition it said raised in its state `conditions` (template `state`, option `history` 1, one key per
condition key, its body and `since`), written before it is said and deleted when it is said cleared. At its start
it judges each kind anew from its own state and readings, says raised again each it still holds and cleared each
key of `conditions` it no longer holds. A raise or clear is said again only when what it says changes (ADR 0289
§1). Why: A4 (today's way a module raises a condition, without G's writer); the state lets a restart clear what
it said. How it is checked: unit, a condition is written in `conditions` and published once with these fields;
a start with a key it no longer holds says it cleared; whole (manager and the router on a test bus), a raised
condition reaches the desk channel and its clearing clears it.
10. **A licence's key form.** A licence's name is its account's address, or its id where it has none, or the name
given at `adopt` for an API key (today's `NameFor`); a name holds characters a key may not. Its key is the name
with each `@` written as `_at_` and every other character outside letters, digits, `-` and `.` written as `_`. An
adoption whose key another licence already has is refused, said in the audit and as `licence.refused`. Every
verb and tool still takes and answers the name; the key is the store's alone. Why: a key of the bus takes only
those characters; the form is the design's choice, readable in `licences_kept`. How it is checked: unit, a table
of names and their keys, and the refused clash.
## Carrying over today's rows
11. **At its first start the manager carries over every row before it does anything else.** When the state
`carried` has no key `postgres`, the manager, before it hears an event, reads a holding report, refreshes or reads
usage, reads every row of the six tables of its database `claude_licences` and writes them as §12 says, then the
key `carried.postgres`. Until that key exists it serves its read verbs and tools only, answering every other
with "the carry-over has not ended", and says the condition `carry-over-failed` (§9; urgent; "Needs you: the licence
manager could not carry over its licences; no consumer is moved and no token is refreshed until it does", naming
the table and the error) when a read or a write fails, cleared when the key is written. Why: a manager that ran on
an empty state would take every holding report for a candidate (ADR 0206 §5) and exchange refresh tokens it
already holds; failure is loud (principle 3). Its source is the database read with the module's own credential, which this milestone keeps for it alone (A3). How it is checked: whole (manager, a store database filled from a copy of today's rows), every row
is carried and the key written; with the database unreachable the condition is raised and no vendor call is made. A table that does not
exist (a fresh install) is read as no rows.
12. **What each table becomes.**
- `licence` → a key of `licences` (§2) per row; each row's `sealed` grant is opened with today's `grant.key` and
handed to the vault as §15 says, its generation 1; the row's other columns become the key's fields.
- `binding` → a key of `bindings` (§3) per row, its `generation` kept, `why` "carried over", `by` the manager.
- `lease` → nothing: a lease lives two minutes, and none taken before the start still holds.
- `offered` → a key of `offered` (§5) per row, its lifetime counted from the row's `at`.
- `usage` → one entry of the log `usage` (§6) per row of the last 35 days, oldest first, its `at` kept.
- `audit` → one entry of the log `audit` (§7) per row, oldest first, its `at` kept, under the subject its `what`
names (`drift` for any other).
Why: no licence, binding, grant or history is lost (the operator, 2026-11-11); usage older than the log's age
would be dropped by the log at once. How it is checked: whole, the counts in `carried.postgres` equal the rows read
for every table but `lease`, and `mesh-vault.get` of each licence's grant (§16) answers it.
13. **A second start carries over nothing.** With `carried.postgres` present the manager never reads the database,
and a carry-over that failed halfway is started again from the beginning, every write of §12 being idempotent
(a key put again with the same value, a log entry not appended twice: before appending, the manager reads its
log's last entry for that subject and skips rows at or before its `at`). Why: ADR 0437 §7. How it is checked:
whole, a second start writes nothing; a start stopped after `bindings` and started again leaves every count equal
to the rows read.
14. **The database's fate, and that this delivery moves data.** In this milestone the database `claude_licences`
stays, read once by §11 and never written. Once `licences_carried` (§44) shows the carry-over done and §20's scan
finds no grant left outside the vault, the module's next change drops `requires postgres-database` and
`grant-key`; the provision is then retiring, its account removed only on the operator's Approve (ADR 0570 §5),
and the database is renamed aside by the postgres module's `postgres_retire_database` and deleted only by a
person (ADR 0230 §14). The delivery of this milestone moves data, so it is said to the operator before it starts
(which module, its machine, that its licences, bindings and grants move to the bus and the vault), and the
manager's machine is backed up before the module moves, as for every module that holds data. Why: A3,
ADR 0570 §5, ADR 0230; the operator's instruction that a delivery moving data is said first. How it is checked:
the delivery's plan names the backup; after the delivery `mesh-store.databases` still lists `claude_licences`.
## Grants and tokens in the vault
*Lines §15 to §20 build ADR 0550 §3, on the tool runner's account (A1).*
15. **The vault holds two secrets per licence, handed to it by the manager alone.** `licence.<licence key>.grant`
holds, for a subscription, the refresh token, the access token and both expiries, and for an API key the key;
`licence.<licence key>.access` holds a subscription's access token and its expiry, or the API key. The vault
serves a new verb on its seat, `licence-put`: `licence`, `part` (`grant` or `access`), `generation` and the value
sealed to the vault's key; answered for a call from the machine that holds the seat `anthropic-licence-manager`
(as the seat's placement names it), and refused from any other machine naming the rule, a guard against a
mistaken caller rather than a permission (A1); it keeps the newest generation and refuses an older one; and it says its event
`secret-changed` with the secret's name and generation, never the value. The manager calls it after every
adoption, rotation and carry-over (§12), the `grant` first. Why: ADR 0550 §3 (the manager hands what it gets back
to the vault, keeping nothing at rest); the names, the verb and its fields are the design's choice. How it is
checked: unit (vault), `licence-put` from another machine is refused and an older generation is refused; unit
(manager), a rotation calls it twice and keeps no token after the call returns.
16. **The manager reads a grant from the vault when it needs one, and keeps it only for that act.** To refresh,
adopt again or read usage, the manager calls `mesh-vault.get` for `licence.<licence key>.grant`, sealed to its own
public key, under the licence's lease (§4), and drops the value when the act ends. Why: ADR 0550 §3, ADR 0183 §6.
How it is checked: unit, the manager's state and log hold no token after a rotation.
17. **A consumer's agent module gets its token from the vault, which serves only the licence a binding names.** The
vault answers `mesh-vault.get` for `licence.<licence key>.access` to the tool runner's account of a machine,
and only when that machine is the node the asking consumer's binding names and the licence is the one that
binding names: a guard against a node applying another's licence by mistake, not a permission (A1). Its rule that a
value goes only to a module under a bus account of its own (ADR 0349 §11) does not apply to the licence
secrets. It learns the bindings from the
manager's `binding.changed` (§21), which it consumes, and at its start from `anthropic-licence-manager.bindings`,
its first view, keeping them in its own state `licence-bindings` (template `state`, one key per consumer, the
licence and generation, deleted on a release). The agent module never receives a refresh token (ADR 0206 §11).
Why: ADR 0550 §3; A1; ADR 0596 §2 (the vault asks the manager, never reads its state); the state is the
design's choice. How it is checked: unit (vault), a token is refused to a machine no binding names and for a licence its
binding does not name (the main file's acceptance test), and given after a `binding.changed` naming it.
18. **`current` answers which licence and its health, never the token.** The seat verb `current` takes `consumer`
and answers `licence`, `kind`, `generation`, `health` (`ok`, `failing`, `expiring`) and `accessExpiresAt`; its
argument `public_key` goes. Why: ADR 0550 §3. How it is checked: unit, no answer of `current` holds a token.
19. **The agent module applies a new token when the vault says it changed or its binding moved.** The agent module
on a node asks `mesh-vault.get` for its licence's `access` sealed to its own key, when it hears a
`binding.changed` for its consumer with a newer generation than it applied, when it hears the vault's
`secret-changed` for the licence it holds, and at its start; it then writes the credentials file or the key-helper
as design 36 §5 has it, unchanged. Why: ADR 0550 §3, ADR 0206 §14 as ADR 0596 §2 changes it (an event and a first
view in place of a watched key). How it is checked: whole, `switch` changes a workstation's token end to end (the
main file's acceptance test).
20. **What ends with the move.** The manager's `grant.key`, its `secret` requirement and the code that seals a grant
at rest go; the `public-key` verb and the manager's keypair stay, since a login offered by a node is sealed to it
(ADR 0183 §23, ADR 0550 §3). After the delivery the vault's `secret_holders` lists both secrets of every licence
and the manager's own secret `grant-key` is retired with `mesh-vault.retire` on the operator's word. Why:
ADR 0550 §3 (a scan after the move that the manager holds no grant). How it is checked: `licences_kept` (§41)
shows no field holding a token in any entry, and `secret_holders` the two secrets per licence.
## Bindings and holdings said as events
21. **Every change of a binding is said as `binding.changed`.** The manager declares in `emits` the event
`binding.changed`, said after the key of `bindings` is written or deleted: `consumer`, `licence` (empty on a
release), `kind`, `generation`, `from` (the licence before), `why`, `by` and `at`; never a token. Why: ADR 0596 §2,
§3 (the owner gains the event its readers need before they move); the name and fields are the design's choice.
How it is checked: unit, `bind`, `switch`, `release`, a login's move and §26 each say one event per consumer
moved.
22. **The agent module follows its binding by that event, and asks once at its start.** `claude-code` gains
`consumes` `claude-licence-manager.binding.changed`, acting only on the event naming its node's consumer, and at
its start asks `anthropic-licence-manager.bindings` with `consumer` its node for its first view; its `reads`
entry `claude-licence-manager.bindings` goes. A node that was away asks once when it is back (ADR 0206 §15), by its
start or its reconnect. Why: ADR 0596 §2, §4. How it is checked: unit (claude-code), an event for another
consumer is ignored; whole, a node started after a switch applies the new licence from its first view.
23. **A node's holdings are said as events, and asked for by the manager.** `claude-code` declares in `emits`
`holdings-changed`, said at its start and whenever its holdings change (ADR 0206 §2), carrying its holdings
report whole as ADR 0206 §1 lists it, never a token, and gains `consumes`
`claude-licence-manager.holdings.asked`, on which it says `holdings-changed` again. The manager declares
`holdings.asked` (`at`, `by`) and says it after its carry-over (§11) and on `licences_resync` (§42), and consumes
`claude-code.holdings-changed` in place of today's `reads`. Its state `holdings` stays `claude-code`'s own. Why:
ADR 0596 §2, §3; a first view by events, since the holdings are one key per node; the names are the design's
choice. How it is checked: whole (manager and a fixture agent module), a `holdings.asked` is answered by one
`holdings-changed` per node, and a report carrying an unknown refresh token's fingerprint makes a candidate
(ADR 0206 §4).
## Switching on usage
*Lines §24 to §33 are the operator's answer of 2026-11-11, which replaces ADR 0183 §21 and ADR 0206 §16 and §18 for
this module (A2): the manager moves consumers by itself on its own readings, and says every switch as an event.*
24. **The manager reads each subscription's usage on a cadence, and keeps the reset times.** Every
`usage_minutes` (§33), for each licence of kind `subscription`, the manager reads the vendor's usage with the
licence's access token (§16) and flattens it: `sessionPct` and `sessionResetsAt` (the five-hour window),
`weeklyPct` and `weeklyResetsAt` (the seven-day window), `sonnetPct` and `sonnetResetsAt`. It writes the entry of
§6, the key's `usage` of §2, and says `usage.read` with those fields, never a token. A failed reading writes
`readError` (the vendor's status and reason) and keeps the last percentages. This is the manager's one timer: the
vendor says nothing as usage grows. Why: ADR 0054; the operator's "reset times"; the reset times of the weekly and
sonnet windows are read beside the session's, which alone is read today. How it is checked: unit, a vendor
answer is flattened with its three reset times; a failed answer keeps the percentages and writes the reason.
25. **A licence's room, and when it is known.** A licence's room is 100 less the higher of its `sessionPct` and
`weeklyPct` in its latest reading. It is known only for a licence of kind `subscription`, read successfully within
`usage_stale_minutes`, whose refresh has not failed `failures_to_notify` times in a row and whose refresh token is
not expired. A licence whose room is not known is never a target of §26: an API key has no window to read and is
billed per use, so it is never one. Why: the operator's "a licence that still has room"; a licence's room is known
only from a reading; the sonnet window is shown and does not count, since the operator named the session and
weekly windows. How it is checked: unit, a table of readings, ages and healths and the room each gives.
26. **On each reading, a licence at its threshold moves every consumer bound to it.** After writing a reading of
licence L, when `switch_auto` is on, L has one or more consumers bound to it, and L's `sessionPct` or `weeklyPct`
is at or above `switch_at_pct`, the manager chooses the target: among the other licences whose room is known and
whose `sessionPct` and `weeklyPct` are both below `room_below_pct`, the one with the most room, the first by name
on a tie. It then moves every consumer bound to L to the target, each as the `switch` verb does (its binding's
generation one more, `why` naming L, the window, its percentage and its reset, `by` `usage`), says
`binding.changed` per consumer (§21) and one `licence.switched` (§27), and tells the operator (§28). A consumer
that inherits its node's licence (ADR 0183 §20) follows its node. A licence below its threshold, or with no
consumer, moves nothing; a consumer is never moved back by the rule, only off a licence at its threshold, so no
consumer flaps between two licences. Why: the operator, 2026-11-11 ("switch to a licence that still has room",
"on all nodes"; the manager itself, never a session); the order of choice and the tie are the design's choice.
How it is checked: unit, a table of licences, readings and bindings and the moves each gives; whole (manager, a
fixture vendor), a reading of 99 % moves four bound consumers to the licence with the most room in one act.
27. **Every switch is said as `licence.switched`.** The manager declares `licence.switched` in `emits` again and
says it once per act that moves consumers, by `switch` or by §26: `from`, `to`, `consumers` (the list), `by` (a
person's name or `usage`), `why`, and for §26 `window` (`session` or `weekly`), `pct`, `resetsAt` and the target's
`room`. The same fields are the log entry `switched` (§7). Why: the operator, 2026-11-11 ("each switch said as an
event"); this replaces ADR 0206 §16 for this module (A2). How it is checked: unit, one event per act with the consumers moved.
28. **Every switch the manager makes is told to the operator.** After an act of §26 the manager calls
`operator-channel.tell` (ADR 0380): `subject` the seat `anthropic-licence-manager`, `headline` "<consumers> moved
to <target>", and one line "<L> reached <pct> % of its <window> window, which resets at <time>; <target> has
<room> % room". A switch by the `switch` verb is not told, since the person who asked knows it. Why: the operator,
2026-11-11 ("told to the operator"); a notice that needs no answer is `tell` (ADR 0380). How it is checked: unit,
§26 calls `tell` once per act, and `switch` never.
29. **No licence with room is a condition, cleared when one has room.** When §26 finds no target for L, the manager says the condition `licence.<L key>.no-room` (§9), severity `urgent`: headline "No licence has room for
<consumers>"; "Needs you: add a licence, or wait for <L>'s <window> window to reset at <time>"; explanation
naming L's percentage and every other licence's room or why it is not known; resolved line "<consumers> have a
licence with room again". The manager clears it when a later reading of L falls below `switch_at_pct`, when its
consumers have moved (a target was found at a later reading of L), or when L has no consumer left. Why: the
operator, 2026-11-11 ("a condition when no licence has room, cleared when one has"); its words are ADR 0253's. How
it is checked: unit, with every licence at its threshold the condition is said once and cleared by a reading with
room; whole, the router takes its raise and its clearing.
30. **A licence near its limit is warned about once per crossing.** When a licence with one or more consumers has
`sessionPct` or `weeklyPct` at or above `warn_at_pct`, the manager says the condition `licence.<L key>.near-limit` (§9),
severity `warning`: headline "<L> at <pct> % of its <window> window"; "Nothing for you to do: <consumers> move to
<target> at <switch_at_pct> %" while §26 would find a target, "Needs you: no other licence has room" when it would
not; explanation naming the reset time. It is written again only when what it says changes (ADR 0289 §1), and
cleared when both windows read below `warn_at_pct`. Why: issue 1409 (a warning before the limit, cleared when the
reading falls back); ADR 0183 §21 (warned once per crossing of a declared threshold). How it is checked: unit, a
rising series of readings says the condition once at the crossing and again only when its words change; a reading
after the reset clears it.
31. **A licence whose usage cannot be read is a condition.** When a subscription's latest successful reading is
older than `usage_stale_minutes`, the manager says the condition `licence.<L key>.usage-unread` (§9), severity
`warning`, naming the vendor's reason from `readError`; "Needs you" only when consumers are bound to it ("<consumers>
are not moved off it while its usage is unknown"); cleared at its next successful reading. Why: principle 3 (a
switch that cannot see must say so). How it is checked: unit, three failed readings in a row write it, one
success clears it.
32. **The rule is started by hand too.** `licences_switch_now` (§39) runs §26 for one licence or all at once, from
their latest readings, and `licences_read_usage` (§38) reads first; with `dry` true either answers what §26 would
do and does nothing. Why: principle 4 (everything it does by itself can be started by hand). How it is checked:
unit, `dry` moves nothing and answers the same moves as the act.
33. **The settings, with their defaults, set through mesh-config.** The manifest's `config` gains, each `trusted`
and read from the settings file at every reading so a change takes effect at the next one: `switch_auto`
(boolean, default true: whether §26 moves consumers; off, §29 and §30 still raise), `switch_at_pct` (number 1 to
100, default 99), `room_below_pct` (number 1 to 100, default 90: what a target's windows must both be below),
`warn_at_pct` (number 1 to 100, default 90), `usage_minutes` (number 1 to 60, default 5) and
`usage_stale_minutes` (number 5 to 180, default 15). The settings file's template and its `takes-config` list
them beside today's five. A person sets one with `mesh-config.config`, at mesh or node level. When
`room_below_pct` is above `switch_at_pct` or `warn_at_pct` is above `switch_at_pct`, the manager says the condition `settings.<setting>.invalid` (§9) (warning, naming both values) and moves no consumer until it is fixed. Each change of
a value it reads is written in the audit under `settings`. Why: the operator, 2026-11-11 ("make it configurable";
99 by default); 90 as the room and the warning is the value the session used that night, so a licence warned
about is never a target; the bounds are the design's choice. How it is checked: unit, each setting's default and
bound, and the invalid pair moving nothing.
## The tools
*Each answers through the mesh MCP server; any person and agent sessions may call them. "Reads" and "acts" are each
tool's effect (the manifest's mark).*
34. **`licences` shows every licence with its latest usage and room.** The seat verb answers, per licence, today's
fields (`name`, `kind`, `identity`, expiries, `failures`, the consumers bound to it) and gains `usage` (§2's
latest reading with its reset times and `readAt`), `room` (§25, or why it is not known), `target` (whether §26
would choose it now), `adoptedAt`, `adoptedFrom` and the open conditions about it. Reads. Why: principle 4; the
operator's "read every licence with its latest usage and reset times". How it is checked: unit, an answer per
licence carries each field and no token.
35. **`usage` answers the history.** The seat verb takes `licence` (absent for all), `since` (a time) and `limit`
(default 20, at most 2000) and answers entries of the log `usage`, newest first, the flattened reading and, with
`raw` true, the vendor's answer. Reads. How it is checked: unit, `since` and `limit` bound the answer.
36. **`switch`, `bind` and `release` keep their arguments.** Each also says §21's and §27's events and writes the
audit with the caller as `by`. Acts. How it is checked: unit, as §21 and §27.
37. **`licences_switches`: every switch and why.** A module tool reading the log `audit` under `switched`: `licence`,
`consumer`, `since` and `limit` (default 20), newest first, each with `at`, `from`, `to`, `consumers`, `by`,
`why` and, for §26, the reading that moved them. Reads. How it is checked: unit, a switch by `usage` and one by a
person are answered with their causes.
38. **`licences_read_usage`: read usage now.** Takes `licence` (absent for every subscription) and `dry`; reads as
§24 does at once and then applies §26 unless `dry` is true; answers each reading and what §26 did or would do.
Acts. How it is checked: unit, as §24 and §32.
39. **`licences_switch_now`: apply the rule now.** Takes `licence` (absent for all) and `dry`; applies §26 from the
latest readings, even when `switch_auto` is off, since a person asked; answers the moves. Acts. How it is checked:
as §32.
40. **`licences_settings`: the settings in force.** Answers each setting of §33 and today's five: its value, its
default, where it was set (mesh, node or the default, as mesh-config answers it) and whether §33 finds it invalid.
Reads. How it is checked: unit, a value set at node level is answered with its level.
41. **`licences_kept`: every entry it keeps.** Takes `entry` (one of §2 to §9's local names; absent for all) and
`key`; answers each entry's keys (or the subjects of a log with their last entry), one key's value, and its fill
against its cap. Reads. Why: principle 4 and ADR 0564 §12 (a read of every bucket and stream a part keeps). How it
is checked: a unit test lists every bus-state entry of the manifest and fails on one this tool does not read.
42. **`licences_resync`: recover.** Says `binding.changed` again for every binding, `holdings.asked`, says again each condition it holds (§9) and calls `licence-put` again for each licence's `access` (§15); answers
what it said. Acts. Why: principle 4 (everything that goes wrong is recovered through its tools): a consumer, the
vault or the keeper that missed an event converges on one call. How it is checked: unit, each is said once per
binding, licence and condition.
43. **`licences_conditions`: the conditions it said.** Answers each key of `conditions` (§9) with its body and
`since`. Reads. Why: principle 4 (everything it holds can be read). How it is checked: unit.
44. **`licences_carried`: the carry-over's record, and its recovery.** Answers `carried.postgres` (§8), or, when it
is absent, the failure `carry-over-failed` names; with `run` true and the key absent, starts §11 again; refused
with the key present. Acts with `run`, reads without. How it is checked: unit, `run` is refused once carried.
45. **`refresh` and `adopt` stay.** `refresh` (one licence or every due one, under its lease) and `adopt` (an API key
from a file on the manager's node or sealed to its `public-key`) are unchanged but for reading and writing the
grant in the vault (§15, §16). Acts.
## A further licence
46. **A subscription licence is added by logging in on any node.** A person logs in to the new account (a team seat
among them) with the agent's own login on any node running `claude-code`. That node's `holdings-changed` (§23)
carries a refresh token whose fingerprint the manager does not hold, so it is a candidate; the manager asks that
node's `claude_code_grant` for it sealed to its key, refreshes it under the account's lease, and on success it is
a new licence, named by its account's address (ADR 0206 §4, §7, §8; §10), its grant handed to the vault (§15). The
node it came from is bound to it (ADR 0209); a person who wants that node back on its licence calls `switch`.
From the next reading (§24) it has a room and is a target of §26. Nothing is configured and no tool beside the
login is needed. Why: ADR 0206, ADR 0209. How it is checked: whole (manager, a fixture vendor), a report with a new
fingerprint is adopted, listed by `licences` with its organisation, and chosen as a target at its first reading
with room.
47. **A team seat's licence is shown as any subscription.** `licences` answers its `organisation` beside its address;
`kind` stays `subscription`. Whether the vendor's usage answer for a team seat carries the same windows is not
known (a guess that it does); if it does not, §31's `usage-unread` says so and it is never a target. Why: the
operator's new team-seat licence. How it is checked: live, after the login, `licences` lists it with a reading.
48. **An API key is added with `adopt`**, from a node through `claude_code_add_api_key` or from a file on the
manager's node (ADR 0209), and is never a target of §26 (§25). Why: ADR 0206 §6, ADR 0209.
## Delivery
49. **One pull request in mesh-catalog, with hq.** The three modules change in one mesh-catalog pull request; hq's
pull request carries this part, the main file and the glossary. Why: one milestone, one release (the operator's
instruction on designing a change as it should be).
50. **The order is the module graph's.** The edges the delivery plan derives: the bus module creates the manager's
bus-state entries before its want moves (the provision `bus-state`, ADR 0570 §4); `mesh-vault`'s `licence-put`
and its consumption of `binding.changed` are served before the manager calls them (a served verb); and `claude-code`
declares `holdings-changed` before the manager consumes it (ADR 0595 §11's judge refuses the reverse). It waits for
no other milestone: the operator channel's condition subject, the vault and mesh-sdk are used as main holds them
(A4). A node's agent keeps its last token, which lives hours, while the manager moves.
51. **Tonight's interim rule ends with the delivery.** Until the delivery, a session follows the readings and calls
`switch` (issue 1409's note of 2026-11-11 20:11); once §26 runs live, that session stops, said on issue 1409.
## Acceptance
52. **The tests of the milestone**, each run in its module's suite or live after the delivery:
- every row of today's database is carried over, counted in `carried.postgres`, and a second start carries
nothing (§11 to §13);
- after the delivery `licences_kept` and the vault's `secret_holders` show no token outside the vault (§20);
- a reading at `switch_at_pct` moves every consumer bound to that licence to the licence with the most room,
says one `licence.switched` and one `binding.changed` per consumer, and tells the operator once (§26 to §28);
- with every licence at its threshold, `no-room` is raised once and cleared by a reading with room (§29);
- a licence crossing `warn_at_pct` is warned about once (§30), and one that cannot be read is said (§31);
- each setting of §33 changes the rule at the next reading;
- every entry the manager keeps is read by `licences_kept`, and every act it takes by itself is started by a tool
(§37 to §45);
- live: a login to a new account on a node is adopted and listed with its usage (§46).
## The lead's answers to the prepare's questions
The prepare's design questions (2026-11-11), each answered by the lead in one line against
[the principles](../../../00-META/principles.md), as the operator's way of working says. A developer builds these as
written; they are cited as "design 39 bus-and-switch B*n*".
- **B1** (`licence-put` is not in the vault's seat definition): the vault's seat definition in mesh-contracts gains the
verb, and mesh-contracts joins this milestone as a second member of its delivery group (P5).
- **B2** (the validator refuses bus state by template from mesh-vault): `licence-bindings` stays in the vault's old
`state` section (P7).
- **B3** (who may read a licence's grant): no machine guard on `licence-put` or `get`; the generation guard stays.
Inside the mesh every module is trusted, and who may do what is not a question (P6; the operator's instruction
who-may-is-not-the-operators-question).
- **B4** (the manager has no vault key to seal to): two steps with a key made for the call, as `move-in` does (P7).
- **B5** (the vault numbers generations itself): the caller's generation is the record's generation (P8).
- **B6** (the vault takes only lower-case names): §10's key form is lower-case (P7).
- **B7** (claude-code needs the licence's key and the account's identity): `binding.changed` and `current` carry `key`,
and `current` keeps `identity` (P1, P3).
- **B8** (`get` names no consumer): the access token goes to machine M when any binding of a consumer on M names that
licence (P7).
- **B9** (no line names the `invokes` entries or claude-code's `consumes mesh-vault.secret-changed`): each is declared
in its module's manifest (P1).
- **B10** (`bindings` takes no `consumer`): an optional `consumer` argument; the §3 fields answered unpaged; the vault
reads it once at start (P7).
- **B11** (one generation counter for every consumer): a counter per consumer, from the higher of its own and its
node's last reported generation; `GenerationsAbove` goes (P7).
- **B12** (holdings unknown after a restart): the manager says `holdings.asked` at every start (P1).
- **B13** (`offered` key holds a colon; two outcomes §5 does not list): the key goes through §10's key form, and all
five outcomes are kept (P7).
- **B14** (`since` and `adoptedFrom` have no column; the live database's name): `since` is the carry-over's time,
`adoptedFrom` comes from the audit, and §14 checks the database the module's binding names (P7).
- **B15** (§20 retires `grant-key`, §1 and A3 keep it): only the sealing at rest goes now; `grant-key` is retired in
the module's next change, with the store database (P7).
- **B16** (`licence.bound`, `licence.released`, `licence.rotated`): dropped; `binding.changed` and the audit log
cover them (P8).
- **B17** (the conditions' scope and id): scope `module`, id `claude-licence-manager` (P7).
- **B18** (no mesh or node level for a module's own setting in mesh-config): the settings are the module's own values
on the manager's node, set and read through mesh-config as any module's own setting (P7).
- **B19** (`current`'s health thresholds and §34's field names): failing at `failures_to_notify`, expiring within
`refresh_warn_days`; today's field names are kept (P7).
- **B20** (the audit log is full): the act fails loudly and says so (P3).
- **B21** (no tool reads the vault's `licence-bindings`): `vault_first_views` and `vault_first_view_again` cover it (P4).
- **B22** (three internal forms): `bindings` stays at form 0; each reader decodes the event bodies with fixtures
copied from the writer; nothing to build for an inheriting consumer (P7).
- **B23** (what `licence-put` names a licence by): its `licence` argument is the licence's key of §10; the manager forms
keys, the vault does not (P8).
- **B24** (an equal generation in `licence-put`): with the same value it is unchanged; with a different value it is
refused loudly as not newer (P3).
- **B25** (the vault matching a token's secret name to a binding it learned at start): the `bindings` verb answers
`key` beside the §3 fields, as `binding.changed` does (B7); the vault's `licence-bindings` keeps `licence`, `key` and
`generation`, and compares the secret's key with the binding's key. One form travels; the vault never computes §10's
key form (P1, P7).
- **B26** (the form of `carried.postgres`): `{at, tables: {<table>: {read, written}}}` (P7).
- **B27** (the carry-over in the audit log): it appends one `carried` entry, the kind §7 lists (P7).
- **B28** (an `offered` row older than 90 days): counted as read, not written (P7).
- **B29** (`adoptedFrom` at the carry-over): the newest `adopted` audit row's `node`, else its `from` (P7).
- **B30** (when bind and switch say `licence.switched`): only when the consumer moves from another licence (P8).
- **B31** (an access token asked before the vault's first view of the bindings is answered): refused, saying why (P3).
- **B32** (a first view of the bindings racing an event heard just before it): a first view never removes or replaces a
binding whose generation is newer than the view's; the newer by generation stays (P3).
- **B33** (what §19's "applied" means): the home holds the token; a home with no token is fetched again at the same
generation (P3, ADR 0266).
- **B34** (a failed usage reading): no `usage` entry is appended; it is said by `readError` and `usage-unread` (P3).
- **B35** (a reading with no weekly window): its room is unknown, and it is never a target (P3).
- **B36** (both windows at the threshold): the act names the higher, the session window on a tie (P7).
- **B37** (a setting outside its bound): it keeps its default and raises `settings.<setting>.invalid`, cleared when the
setting is fixed (P3).
- **B38** (a subscription never read successfully since its adoption): `usage-unread` is raised once no reading has
succeeded for `usage_stale_minutes` counted from its adoption (P3).
- **B39** (a condition's headline longer than the operator channel's 60 characters): the headline names counts and
short names only ("No licence has room for 4 machines", "<account> at 99% weekly"); the full list, the licence and
the reset time go in the condition's detail. A cut at 60 characters with "…" stays as the last guard so a condition is
never refused unsaid (P3).
- **B40** (§34's `target`): true for the licence §26 would move a full licence's consumers to once it reaches its
threshold: the best licence with room now, whether or not any licence is at its threshold; so the tools say where
consumers go next (P4).
- **B41** (§9 and §29's whole test and the router): the manager runs whole on the test bus, and its condition is
taken off its subject and decoded by the operator channel's client, the contract the router reads; the router, another
module, is not run in this module's test, and the report says so (P1).
- **B42** (which first view `vault_first_view_again` asks again): a new argument `of` names the view by its owner's
state (`mesh-delivery-assigner.assignments` or `claude-licence-manager.bindings`); absent, both are asked again, as
the tool did before for its one view (P4).
- **B43** (B32 for a consumer absent from the first view): a `licence-bindings` key written by an event after the first
view was asked is kept; only a key written before it was asked, and absent from the view, is removed (P3).
- **B44** (§12's leases, review round 1): the carry-over carries each lease still live at its run, as a `leases` key with
its remaining lifetime, so the new manager never refreshes a licence the old one holds a refresh lease on, whatever the
order in which the delivery stops one and starts the other; an expired lease is counted read and not written (P3, P7).
- **C1** (the operator, 2026-11-12: "the licence manager module should have a service part and a tools part"; met live
when the manager, run inside the machine's tool runner, was issued none of its own logs): the module declares
`runs-as claude-licence-manager` with an account of its own, as the vault and the mail reader do. Its own runtime runs
the service part (the carry-over at start, the usage timer, the switch rule, the conditions) and serves the tools part
beside it, so every kept entry, log and secret of §1 to §20 is issued to its own account, never to the tool runner's.
The tools act only through the running service: no tool keeps a second copy of what the service does (P1, P7).
- **C2** (review of C1: the key-pair file the manager wrote in its state directory under the tool runner's account,
which the node-engine does not hand to the new owner): when the manager cannot read the key pair it finds, it makes a
new one in its place and says so in its journal; every use passes the public key per ask, so nothing depends on the
old pair (P3, P7). The node-engine handing a program-written directory's contents to a new owner (every module that
moves to `runs-as`) is noted on its issue, not built here.
- **C3** (met live after C1: the manager, now in its own runtime, was still issued none of its logs): the two logs
`usage` and `audit` are declared in the manifest's `logs` section, the form the runtime on main issues today; the
states stay templates. The move of logs to templates is design 47 milestone G's (P7).
- **C4** (the operator, 2026-11-12: "the session limit has been deprecated by anthropic"; met live: both licences read
`sessionPct` empty, so neither had room and the switch could choose no target): a licence's room is 100 less its
weekly percentage alone; the session window takes no part in room, the switch threshold, the warning or the
conditions, wherever §24 to §33 name it. A reading with no weekly percentage still has unknown room (B35).
- **C5** (met live 2026-11-12: `licences_switches` answered every switch carried from the old database with no `to` and
no `consumers`): a carried entry keeps the old manager's fields as §12 copies them, a switch written as its
`consumer`, its `licence` and `from`; §37's reader answers such an entry with `to` its `licence` and `consumers` the
one `consumer`, and its filters by licence and consumer read it the same way. The log is not rewritten (P3, P7).
+244
View File
@@ -0,0 +1,244 @@
---
layer: to-be
design: 39
milestone: parts
updated: 2026-11-12
code: [mesh-catalog modules/claude-licence-manager]
decisions:
- "ADR 0183"
- "ADR 0050"
- "ADR 0054"
- "ADR 0040"
- "ADR 0192"
- "ADR 0198"
- "ADR 0259"
- "ADR 0349"
- "ADR 0436"
- "ADR 0570"
- "ADR 0230"
- "ADR 0595"
- "ADR 0672"
- "ADR 0675"
---
# Design 39, milestone parts — the licence manager built of its parts
**What it builds.** The module holding the seat `anthropic-licence-manager` is one manifest built of four parts,
each in a form the manifest validator accepts and the builder, the node-engine and the tool runner honour today
([design 20](../20-writing-a-module.md) *Who reads a manifest* and *What a module is built of*; playbook
[06](../../../00-META/process/06-writing-a-module.md) *Where the parts of the mesh read a manifest differently*): the
manager bundle, which runs long and answers the seat's verbs and every act; the tools bundle, which answers the
module's reading tools; the settings file; and the module's account with its directory. The carry-over from the store
database, done live, leaves the module whole in this milestone, with its requirement of the database and of the secret
`grant-key`, and both provisions then retire on the operator's Approve. The whole shape is in the design's main file
([39](../39-the-anthropic-licence-manager.md)); this part holds every line the milestone builds, cited as "design 39
parts §n".
**Why now.** The operator, 2026-11-12: "build the anthropic-licence-manager as clean as possible"; a module is one
manifest with several parts; the seat stays named for the vendor (ADR 0183 §4, ADR 0050, ADR 0054), and a second
vendor is a module of its own. That morning the operator had said "the licence manager module should have a service
part and a tools part" (design 39 bus-and-switch C1). Today, after milestone bus-and-switch, one Go bundle `code` does
everything in one program: it runs long, answers the seat's ten verbs and the module's eight tools, and keeps the
carry-over's code, which ran once, live, at 2026-11-12 09:44:59Z, carrying every row of every table (issue 1409's note
of that morning); for that code alone the module still requires `postgres-database` and the secret `grant-key`
(bus-and-switch A3, B15).
**Where.** One repository, mesh-catalog, and one of its modules, `claude-licence-manager`; hq carries this part, the
main file and the glossary. No other module changes: every verb, event and provision the manager uses is served today
(§17).
**The shape at a glance.**
| a module's part | its artifact | how it runs | its account | what it keeps or reads |
|---|---|---|---|---|
| the manager | `manager`, a Go bundle, binary `claude-licence-manager` | loaded by the module's runtime of its own; runs long and answers the seat's ten verbs and the three acting tools | the module's account `claude-licence-manager`, on the runtime's bus account | writes all its kept data (bus-and-switch §1 to §9) and its two logs; reads its key pair and settings file |
| the tools | `tools`, a Go bundle, binary `claude-licence-manager-tools` | loaded by the same runtime; answers the four reading tools | the same | reads the kept data and the logs, writes nothing |
| the settings | `files`, an archive of the templates directory | the `settings` file resource, written by the node-engine | owned by the module's account | holds the eleven settings mesh-config sets |
| the account and its directory | none | the `user` resource `account` and the `directory` resource `state` | `claude-licence-manager` | the key pair, the settings file, the runtime's `broker` secret |
## The module's parts
1. **The module is four parts in one manifest, and runs no process resource, container or run-once step of its
own.** `build.artifacts` names exactly `manager`, `tools` and `files`; `resources` names exactly `account`,
`state` and `settings`, in that order; the module's runtime of its own is the process the node-engine composes for
`runs-as` (design 20 *A runtime of its own*), never one the manifest writes. Why: the operator, 2026-11-12; a module
is one piece of software built of parts (ADR 0040); principle 7 (fewer parts). How it is checked: the manifest
validator accepts the manifest at the change's check, and the composition step composes it for the manager's
machine; a catalog test of the module reads its manifest and fails on any other artifact or resource, a `process`
or `container` resource, or a `run-once` field.
2. **The manager bundle runs long and answers the seat's verbs.** The artifact `manager` (today's `code`, renamed):
kind `bundle`, `language` go, `system` arch, `from` `cmd/manager`, `binary` `claude-licence-manager`, `loads`
that binary, and `env` with exactly two words, `MESH_LICENCE_STATE` (`${dir:state}`) and `MESH_LICENCE_SETTINGS`
(`${dir:state}/settings.json`). It is loaded by the module's runtime of its own and runs long (ADR 0198 §1, §2: a
bundle may serve tools, run long, or both): its usage timer, its refresh cadence, the switch rule on each reading,
its consumption of `claude-code.holdings-changed`, the conditions it judges at its start, and every event of
bus-and-switch §21 to §27. It registers the seat's ten verbs (`licences`, `bindings`, `bind`, `switch`,
`release`, `refresh`, `usage`, `adopt`, `current`, `public-key`) under the seat and the three acting tools of §4
under the module. It is the only part that writes the module's kept data and logs, emits, calls the vendor, calls
the vault, tells the operator and reads the key pair. Why: one rotation source (ADR 0183 §6); the binary keeps its
name so the runtime's journal and the loaded entrypoint stay as they are. How it is checked: unit tests as
bus-and-switch has them, moved with the code; the catalog test of §1 reads the artifact's fields.
3. **The tools bundle answers the module's reading tools, and writes nothing.** The artifact `tools`: kind `bundle`,
`language` go, `system` arch, `from` `cmd/tools`, `binary` `claude-licence-manager-tools`, `loads` that binary, and
no `env`: the runtime hands a module's words to all its bundles (ADR 0192), so it reads `MESH_LICENCE_SETTINGS`
from the manager bundle's words, and a word two bundles gave different values would be refused at composition. It
registers under the module the four reading tools, `licences_switches`, `licences_settings`, `licences_kept` and
`licences_conditions`, with the arguments and answers of bus-and-switch §37, §40, §41 and §43. It reads the
module's kept data with the runtime's bus-state calls and the logs `usage` and `audit` with the runtime's log
calls, each answered as the module whose bundle asks; it calls `seat:mesh-config.config` for `licences_settings`
(bus-and-switch B18). It writes no key, appends to no log, emits nothing, subscribes to no event, asks no
heartbeat, calls neither the vendor nor the vault and opens neither the key pair nor a secret. Why: principle 4
(everything a module holds can be read): the runtime serves the tools of every bundle of a module that loaded, so
these four still answer while the manager bundle fails to load or stops; C1 (the tools act only through the running
manager) holds, since these do not act; principle 1 governs reading between modules, and both bundles are the one
module reading its own data. How it is checked: a unit test of the tools bundle runs each tool against a fixture
of the runtime's calls and fails on any write, append, emit or subscribe; whole, with the manager bundle refusing to
start, `licences_kept` answers every entry.
4. **Every act is the manager's.** The three tools that act, `licences_read_usage`, `licences_switch_now` and
`licences_resync` (bus-and-switch §38, §39, §42), are registered by the manager bundle beside the seat's verbs, and
no act is answered by the tools bundle. A person's act on a consumer or a licence stays a seat verb (`bind`,
`switch`, `release`, `refresh`, `adopt`). Why: C1 (no tool keeps a second copy of what the manager does);
ADR 0183 §6; principle 7 (no call between the two bundles, so no path the mesh lacks). How it is checked: the
catalog test of §1 finds the module's `tools` to be exactly the four of §3 and the three of this line; a unit test of each
bundle lists what it registers.
5. **The code both bundles share is one package of the module.** The package `internal/licences`, in the module's
one Go module, holds the layouts of the kept data and of the log entries (bus-and-switch §2 to §9), the key form
(§10), the names of the entries, and the settings with their defaults, bounds and validity (§33, B37); `cmd/manager`
and `cmd/tools` each import it, and neither holds a copy of what it holds. Why: a layout in one place, so the reading
tools never read a form the manager no longer writes; it is code the module owns alone (design 20 *Where a seat's
code goes*: a module's own package). How it is checked: the review reads that no type of a kept entry is declared
in either command package; `go vet ./...` at the module's root builds both.
6. **The settings file stays, without the database's template.** The resource `settings` (a `file` at
`${dir:state}/settings.json`, mode 0600, owner `claude-licence-manager`, `template` `files/settings.json`,
`merge` json, `takes-config` the eleven settings of bus-and-switch §33 and today's five) and the archive `files`
(`from` `files`, the one archive the templates are read from, ADR 0349 §2) stay as they are. The template
`files/database.url` is deleted. Why: the manager reads its settings at every reading (bus-and-switch §33); the
database's address has no reader once §9 holds. How it is checked: the composition step writes the file; the catalog
test of §1 finds no file under `files` but `settings.json`.
7. **The account, its directory and the runtime's secret stay.** `runs-as` `claude-licence-manager`, `secrets-owner`
the same, the own secret `broker` at `${dir:state}/broker`, the `user` resource `account` and the `directory`
resource `state` (mode 0700, owner the account, `place` `.`, `unknown` `program`) stay as they are; the key pair
`manager-key.json` stays in that directory, read and made only by the manager bundle (C2). No `runtime-health` is
added: the node-engine's judgement that the runtime is alive stands as its health. Why: design 20 *A runtime of its
own*; principle 7. How it is checked: the catalog test of §1.
8. **The seat's verbs are answered on the bus account of the runtime of its own, never by a process account.** The
manager bundle answers the verbs through the runtime that `runs-as` gives the module (ADR 0259 §8; ADR 0436 §5:
`runs-as` is unchanged and still gets a runtime of its own), as the router answers the operator channel's. The
manager is not a `process` resource with `bus`: a process account is granted no subject on which a tool or a seat's
verb is answered and holds no seat (ADR 0436 §3), which only ADR 0672 §7 lifts, for the recovery module, and
ADR 0675 §1 and §2, for the bus module's keeper; and a process account's grant names events, work queues, states,
asks and calls (ADR 0436 §1), never the old-section logs `usage` and `audit` the manager appends to (C3). Why: these
records. How it is checked: the catalog test of §1 finds no `process` resource and no `bus` key in the manifest;
whole, after the delivery, `anthropic-licence-manager.licences` answers through the mesh MCP server.
## The carry-over leaves
9. **The carry-over is done, and its code leaves the module now.** The carry-over (bus-and-switch §11 to §13) ran on
2026-11-12 at 09:44:59Z, every table's count equal and no lease live (issue 1409's note of 10:4x CET). In this
milestone the code that reads the store database, the carry-over itself, the opening of grants at rest with
`grant.key`, the gate that answers "the carry-over has not ended", the condition `carry-over-failed` and its
recovery go, with the postgres driver in the module's `go.mod`. No run-once step is built for it: no row is left to
carry, a fresh install has no database (bus-and-switch §11: read as no rows), and a run-once process with a bus
account could not append to the logs (§8). Why: bus-and-switch A3, B15 and §14 named this change as the module's
next; principle 7. How it is checked: the module's `go.mod` requires no postgres driver; a unit test fails on the
words `DATABASE_URL_FILE` or `MESH_LICENCE_KEY_FILE` anywhere in the module's code.
10. **What leaves the manifest, and what stays of the carry-over.** `requires` loses `postgres-database` and `secret`;
`contributes`, `binds` and the whole `secrets` section go; `env` loses `DATABASE_URL_FILE` and
`MESH_LICENCE_KEY_FILE`; the resource `database-url` goes; the tool `licences_carried` goes. The kept-data entry
`carried` stays, with its one key `postgres` as the record of the carry-over, read by `licences_kept`; nothing
writes it again. Why: removing the entry would drop kept data, which needs a warrant and a snapshot (ADR 0595 §5),
for nothing gained; principle 7. How it is checked: the catalog test of §1; after the delivery `licences_kept`
with `entry` `carried` answers the record of 09:44:59Z.
11. **The manager starts without waiting for a carry-over.** At its start the manager bundle judges each kind of
condition anew from its own state and says cleared each key of `conditions` it no longer holds (bus-and-switch
§9), `carry-over-failed` among them when present; then it says `holdings.asked` (B12) and starts its timers. It
reads `carried` never. Why: bus-and-switch §9, B12. How it is checked: unit, a start with a `carry-over-failed` key
in `conditions` says it cleared once and deletes the key.
12. **The pull request waits on two readings.** Before the push, the lead reads `licences_carried` of the running
build answering `carried.postgres` with every table's read equal to its written, and `mesh-vault.secret_holders`
listing `licence.<key>.grant` and `licence.<key>.access` for every licence `licences` answers, and writes both
readings in the milestone file. Why: bus-and-switch §14 and §20 (the database's requirement goes only once the
carry-over is done and no grant is left outside the vault); principle 3. How it is checked: the code review finds
both readings in the milestone file.
## The store database retires
13. **Both provisions retire, each on the operator's Approve, asked by the provisioner.** Once the new build's want
moves, no want needs this module's `postgres-database` nor its secret `grant-key`, so the holder of
`mesh-provisioner` marks both keys `retiring` and raises one ask each on the operator channel, saying what is
removed from which provider on which node (ADR 0570 §5). On the warrant postgres retires the consumer's account of
the database `claude_licences` and the vault removes `grant-key`; on a decline both stay retiring. The module asks
nothing. Before the delivery starts, the lead tells the operator that these two asks will come and what each
removes. Why: ADR 0570 §5; this replaces bus-and-switch §20's `mesh-vault.retire` of `grant-key`. How it is
checked: after the delivery `operator-channel.asks` holds both asks; after each warrant the provision's key is gone.
14. **The database's data is removed only by the operator.** Retiring keeps the database `claude_licences` and its
data (ADR 0570 §5). Its removal is a person's act, the postgres module's tool `provisioner_delete` called through
the mesh (ADR 0230 §5, §34): after both warrants the lead asks the operator for it, saying it removes the store's
copy of the licences, bindings, grants sealed with `grant-key`, usage and audit, whose every row is on the bus or
in the vault (§12). Why: ADR 0570 §5, ADR 0230; data removed is the operator's. How it is checked:
`mesh-store.databases` lists `claude_licences` until the operator's call and not after it.
15. **The files the database's requirement wrote leave the state directory with it.** `database.url` is the
resource `database-url`, which the node-engine removes as it removes every resource that leaves a declaration
(playbook 06, step 5); `database.json`, `database.secret` and `grant.key` are the files it wrote for the
requirements of §10, and whether it removes such a file when its requirement leaves is not known (a guess that it
does). A file left behind is a fault of the node-engine, noted on its issue and never removed by hand. Why:
principle 2. How it is checked: after the delivery, `node-reads.list` of the module's state directory on the
manager's machine lists none of the four.
## Delivery
16. **One pull request in mesh-catalog, with hq.** The module's change is one mesh-catalog pull request; hq's pull
request carries this part, the main file and the glossary. Why: one milestone, one release (the operator's
instruction on designing a change as it should be).
17. **No order between modules; within the module, the node-engine's.** The change adds no served verb, provision
or event and drops none another module uses: the manager still calls `seat:mesh-vault.licence-put` and
`seat:mesh-vault.get`, `seat:operator-channel.tell`, `seat:mesh-config.config` and `claude-code.claude_code_grant`,
and consumes `claude-code.holdings-changed`, each served or said today, so the delivery plan derives no edge. On
the manager's machine the node-engine writes the state directory and the settings file, unpacks both bundles, and
restarts the module's runtime once, since its `restart-on` names every bundle's archive; the runtime then loads
both. The kept data keeps its names and form, so no restore point is taken (ADR 0672 §1 is for a form change), and
the delivery itself moves no data; a node's agent keeps its last token, which lives hours, while the runtime
restarts. Why: the module graph orders deliveries; ADR 0595 §11. How it is checked: the delivery plan names one
module and no edge.
## Acceptance
18. **The tests of the milestone**, each run in the module's suite or live after the delivery:
- the manifest is accepted by the manifest validator, built by the builder and composed by the node-engine for
the manager's machine, with the artifacts and resources of §1 and nothing else (§1 to §8);
- after the delivery the runtime serves the seat's ten verbs and the module's seven tools, the four reading tools
from the tools bundle (§2 to §4);
- with the manager bundle refusing to start, the four reading tools still answer (§3);
- the module's code names no database and no `grant.key` (§9), and `licences_kept` answers the carry-over's record
(§10);
- after the delivery the provisioner holds both retiring asks, and after the operator's call the database is gone
(§13, §14);
- the state directory holds none of the database's files (§15).
## The lead's answers
- **D1** (§12's vault reading, review round 1: no vault tool lists licence secrets, so `secret_holders` cannot show
`licence.<key>.grant` and `.access`): the reading that proves bus-and-switch §20's condition is, for every licence
`licences` answers, a rotation after the carry-over with no failure (`rotatedAt` later than `carried.postgres.at`,
`failures` 0), since a rotation reads the grant from the vault and puts both secrets back; and the vault's journal
handing `licence.<key>.access` to a bound node. Both go in the milestone file before the push (P3, P7).
- **D2** (§17's wording): the manager calls `seat:mesh-config.config` no more; the tools bundle does (§3). `invokes`
is the module's, so the manifest is unchanged (P8).
- **D3** (§15's check, met after the delivery: `node-reads.list` and `node-files.list` refuse the module's state
directory as a place a secret is kept, so no tool can say its database files are gone; prepare in the fix's map):
- §15 is read with `node-files.list`, not the retired `node-reads` (P7, P8).
- `node-files.list` of a place a secret is kept, at any depth beneath it, answers each entry's name, type, owner,
group, mode, size and a link's target held to the content rule, never content, and marks the place
`secret-place` as `stat` does; this holds for the mesh's places and a machine's credential places, and a process's
`/proc/<pid>/` entries stay refused (P4, P6, P7).
- `node-files.stat` of a path that does not exist answers that it does not exist, not that file modes refuse it, so
§15's "gone" can be read (P3).
- The seat contract's `list` text in mesh-contracts says so in the same delivery group; playbook 08's one-repository
rule is bent for one line of text, said in the pull request (P5).
- The lines the fix touches cite ADR 0394 §7, the record that refuses a secret place (P8).
- The fix runs under issue 1409, whose part this check is, with a note on issue 1844; its own pull requests, since
the part's pull request has merged (P7).
- **D4** (met live: the store held the module's database as `mesh_novox_licmgr`, the name postgres gave it, not the
`claude_licences` the manifest asked for): §13 and §14 read the database as the one postgres made for the module,
named in `mesh-store.databases`; it was deleted on the operator's yes on 2026-11-12, set aside first by postgres's
own tool, because the provisioner never retired it (P3).
@@ -1,10 +1,20 @@
---
layer: to-be
status: in-progress
code: [mesh-catalog modules/claude-licence-manager, mesh-vault]
updated: 2026-10-26
code: [mesh-catalog modules/claude-licence-manager, mesh-catalog modules/claude-code, mesh-catalog modules/mesh-vault]
updated: 2026-11-12
decisions:
- "ADR 0550"
- "ADR 0595"
- "ADR 0596"
- "ADR 0437"
- "ADR 0564"
- "ADR 0570"
- "ADR 0230"
- "ADR 0380"
- "ADR 0253"
- "ADR 0289"
- "ADR 0349"
- "ADR 0209"
- "ADR 0206"
- "ADR 0183"
@@ -15,6 +25,13 @@ decisions:
- "ADR 0126"
- "ADR 0132"
- "ADR 0159"
- "ADR 0040"
- "ADR 0192"
- "ADR 0198"
- "ADR 0259"
- "ADR 0436"
- "ADR 0672"
- "ADR 0675"
---
# 39 — The Anthropic licence manager
@@ -29,45 +46,62 @@ which is the consumer on every node.
## Every grant in the vault
*Decided 2026-10-26 (ADR 0550 §3), on the operator's answer that every secret lives in the vault; built in
ADR 0547's second milestone (issue 1126). Until it is delivered, the sections below hold as first written.*
*Decided 2026-10-26 (ADR 0550 §3), on the operator's answer that every secret lives in the vault; built in milestone
bus-and-switch (§15 to §20 of its part, [39-milestones/bus-and-switch.md](39-milestones/bus-and-switch.md)), the vault
serving the licence secrets to the tool runner's account (principle 6; its answer A1). Until it is delivered, the
sections below hold as first written.*
- **The vault keeps every licence's secrets**: the refresh tokens, the API key and the access tokens are vault
secrets ([24](24-the-secrets-vault.md)). The manager keeps its bindings, its licence records without a secret
(account, kind, health, usage, audit), and nothing at rest that is secret.
- **The manager stays the one rotation source.** It alone calls the vendor's token endpoint: to refresh or adopt,
it asks the vault for the grant sealed to itself and hands what it gets back to the vault. A grant offered at
login, sealed to the manager's key (its `public-key` verb is kept), is handed on to the vault the same way.
- **A holder's token comes from the vault.** The agent module on a node registers its public half with the vault,
not the seat, and asks the vault for its token sealed to it. The vault serves only the licence the manager's
binding names for that holder, and says `secret-changed`, never a value. The seat's `current` verb answers which
licence a consumer holds and its health, never the token.
- **It waits for accounts of their own.** The vault hands a value only to a module running under a bus account of
its own (issue 569), so the move waits until the manager and each agent module run under one.
*How it is checked:* a unit test that the vault refuses a token to a holder no binding names or to one without an
account of its own, and a scan after the move that the manager's tables hold no grant.
- **The vault keeps every licence's secrets**, two per licence: its grant, and the access token a consumer is handed
([24](24-the-secrets-vault.md)). The manager keeps its bindings and its licence records without a secret.
- **The manager stays the one rotation source**: it reads a grant from the vault for one act and hands what the
vendor answers back to it, keeping nothing at rest.
- **A consumer's token comes from the vault**, which serves only the licence the manager's binding names for that
consumer, learned from the manager's `binding.changed`; the seat's `current` answers which licence and its health,
never the token.
## 1. What it is
A module, `claude-licence-manager`, holding the mesh-scoped seat **`anthropic-licence-manager`**. One
holder, on the node the operator assigns it to — the control node is the natural one, and nothing in the
definition says so. It requires a database for its own store and the bus; it claims the seat; it serves
the seat's verbs. It has no port, no route, no file under anyone's home.
definition says so. It claims the seat and serves the seat's verbs. It has no port, no route, no file under anyone's
home.
Its store holds four things:
**It is one manifest built of four parts** (ADR 0040; milestone parts, its part
[39-milestones/parts.md](39-milestones/parts.md)), each in a form the manifest validator accepts and the builder, the
node-engine and the tool runner honour today ([20](20-writing-a-module.md)):
| table | holds |
|---|---|
| **licences** | name, kind (`subscription` or `api-key`), the account's identity (id, address, organisation) once adopted, the grant encrypted at rest, when the access token expires, when the refresh token expires, consecutive failures, the refresh lease, when a person was last notified |
| **bindings** | one row per consumer: kind (`node-agent`, `node-session`, `worker`), its key (the node, or the node and the worker), the licence, or *inherit* |
| **usage** | the vendor's readings per licence per period, raw beside normalised (ADR 0054) |
| **audit** | every switch, adoption, refusal and drift, with who asked |
| a module's part | its artifact | how it runs |
|---|---|---|
| the manager | a Go bundle | loaded by the module's runtime of its own (`runs-as`), under the module's account: it runs long (the usage timer, refreshes, the switch rule, the conditions), answers the seat's verbs and every tool that acts, and alone writes what the module keeps (ADR 0198 §1, §2) |
| the tools | a Go bundle | loaded by the same runtime: the tools that only read the module's kept data and logs, served while the manager fails |
| the settings | the templates' archive | the settings file the node-engine writes from the template and mesh-config's values |
| the account and its directory | none | a `user` and a `directory` resource |
**The grants are encrypted with a key the vault made for the manager** — its one `secret` requirement.
The vault keeps that key; the manager keeps the grants. That is ADR 0050's carve-out, one module, one
node, the long-lived grants only. ADR 0550 §3 ends the carve-out: the grants move into the vault, and the
`licences` table keeps no grant (*Every grant in the vault*, above).
The seat's verbs are answered on the bus account of the runtime of its own (ADR 0259 §8, ADR 0436 §5), never by a
process account, which answers no seat's verb (ADR 0436 §3, lifted only for the recovery module, ADR 0672 §7, and the
bus module's keeper, ADR 0675 §1, §2).
**It keeps all its data in the bus's own storage, by the kept-data templates, and requires no database**
(ADR 0595, ADR 0596; the operator, 2026-11-11). Built in milestone bus-and-switch (§1 to §14 of its part), which carries
today's store database over at the manager's first start, reading it and never writing it (done live on
2026-11-12); milestone parts drops the carry-over's code and the database's requirement, which then retires on the
operator's Approve (ADR 0570 §5), its data removed only by the operator (principle 7; its answer A3):
| entry | template | holds |
|---|---|---|
| `licences` | state | one key per licence: kind, the account's identity, expiries, failures, its latest usage reading with its reset times; never a secret |
| `bindings` | state | one key per consumer: its licence, kind, generation, and who or what moved it last |
| `leases` | state | one key per lease, ended by its holder or its two-minute lifetime |
| `offered` | state | one key per grant a node offered, with its outcome |
| `usage` | log | every reading, raw beside normalised (ADR 0054), 35 days |
| `audit` | log | every adoption, refusal, rotation, binding, switch and setting, kept for good |
| `carried` | state | the record of the one carry-over from the store database, kept and never written again (milestone parts §10) |
| `conditions` | state | each condition it said on the operator channel, so a restart can clear what it said |
Every grant and token is the vault's (*Every grant in the vault*, above). Until milestone parts is delivered, the
module still requires its store database, its tables `licence` (with the grant encrypted at rest with a key the vault
made for the manager, ADR 0050's carve-out), `binding`, `lease`, `offered`, `usage` and `audit`, read by the
carry-over's code alone and written by nothing.
## 2. The licences it manages today
@@ -135,12 +169,15 @@ own, with its own agent directory and credentials file, which the agent module o
it as it writes the operator's — the predecessor ran its agents exactly so.
**Binding is a person's act through the seat's verbs**, listed by the mesh MCP server: `bind`, `switch`,
`release`. **Exhaustion is observed, not acted on**: usage is read every few minutes, a crossing of a
declared threshold in the five-hour window is notified once per crossing, and moving a consumer is the
operator's call. Switching remains a reaction, not a declaration
(ADR 0024), and an automated policy — move to the
least-used licence, stay off a dying one — is designed later if wanted, on the readings this module
already keeps.
`release`. **A licence at its threshold is left by the manager itself** (the operator, 2026-11-11: "when the current
licence usage is at 99%, switch to a licence that still has room", "on all nodes"; built in milestone
bus-and-switch, §24 to §33; the operator's answer replaces ADR 0183 §21 and ADR 0206 §16, §18 for this module, with
no record, its answer A2): on each of its own usage readings, a licence whose session or weekly usage reaches the threshold (99 % by
default) has every consumer bound to it moved to the licence with the most room; each switch is said as
`licence.switched` and told to the operator; a licence near its limit is warned about once per crossing, and no
licence with room is a condition until one has room. The threshold, the room a target needs and the switch itself
are settings. Switching stays a reaction to a reading, never a declaration (ADR 0024). Until the milestone is
delivered, exhaustion is observed and moving a consumer is the operator's call.
## 6. Adopting a grant
@@ -180,9 +217,14 @@ report, and adopted by refreshing it.
**Events**, no secret in any: `licence.adopted`, `licence.failing`, `licence.refused`, `usage.read` —
the audit logger records them all. *2026-10-04 (ADR 0206):* `licence.rotated` and `licence.switched` are
gone; a rotation or a switch is a new generation in the `bindings` state.
gone; a rotation or a switch is a new generation in the `bindings` state. *Milestone bus-and-switch:*
`binding.changed` says every change of a binding, `licence.switched` comes back for every switch, `holdings.asked`
asks every node's agent module for its holdings, and its conditions are said on the operator channel (§9, §21, §23,
§27 of its part).
**State**: `bindings`, which it keeps; the agent module's `holdings`, which it reads.
**State**: `bindings`, which it keeps; the agent module's `holdings`, which it reads. *Milestone bus-and-switch:*
the kept data of §1, and no other module's state read: the agent module's holdings are heard as its
`holdings-changed`, and the agent module follows its binding by `binding.changed` (ADR 0596).
**The seat's verbs**, the contract every future holder must serve: `licences` (each with kind,
identity, expiry, failures, who is bound), `bindings`, `bind`, `switch`, `release`, `refresh` (now, one
@@ -191,10 +233,17 @@ or all), `usage` (current and history), `adopt` (a file on the manager's node, o
consumer sends — ADR 0206; from ADR 0550 §3, which licence a consumer holds and its health, never the
token, which the vault hands). The manager asks a node for a candidate grant by the agent module's own tool.
The module's own tools beside the verbs (milestone bus-and-switch, §37 to §44): every switch and why, the settings
in force, usage read now, the switch rule applied now, every entry it keeps with its fill, the conditions it
said, the carry-over's record, and one recovery that says every binding, condition and access token again.
## 8. Settings
The refresh cadence; the usage threshold; the notification cooldown. Each declared with a default, so
one definition serves and one mesh may differ.
one definition serves and one mesh may differ. *Milestone bus-and-switch* (§33 of its part) adds whether the manager
switches by itself, the threshold that moves consumers (99), the room a target needs (both windows below 90), the
warning's threshold (90), the reading's cadence (5 minutes) and when a reading is too old (15 minutes), each set
through mesh-config.
## How it is checked
@@ -208,10 +257,24 @@ one definition serves and one mesh may differ.
| the mesh MCP server lists the seat's verbs and `switch` changes a workstation's token end to end | ADR 0132, the exit of the build |
| the vault refuses a token to a holder no binding names, or to one without a bus account of its own | ADR 0550 §3 |
| after the move, the manager's tables hold no grant | ADR 0550 §3 |
| every row of the store database is carried over once, and a second start carries nothing | bus-and-switch §11 to §13 |
| a reading at the threshold moves every consumer of that licence to the one with the most room, said as an event and to the operator | bus-and-switch §26 to §28 |
| no licence with room raises one condition, cleared by a reading with room; a licence near its limit is warned about once | bus-and-switch §29, §30 |
| every entry the manager keeps is read by a tool, and every act it takes by itself is started by one | bus-and-switch §37 to §45 |
| the manifest names the manager bundle, the tools bundle, the settings and the account, and no process, container or run-once step; the validator accepts it, the builder builds it and the node-engine composes it | parts §1 to §8 |
| with the manager bundle refusing to start, the tools that read still answer | parts §3 |
| the module names no store database and no `grant.key`; both provisions retire on the operator's Approve, and the database goes only by the operator's call | parts §9 to §15 |
## Milestones
| Milestone | What it builds | State |
|---|---|---|
| the manager and its consumer | §1 to §8 as first written: the module, its seat, its store database, adoption and the sealed hand-over (ADR 0183, ADR 0206, ADR 0209) | delivered; built as design [40](40-building-the-operators-agent-and-its-licence-manager.md) describes |
| bus-and-switch | its kept data on the bus and its store database carried over and retired; every grant and token in the vault (ADR 0550 §3); bindings and holdings as events; the switch on its own usage, its warning and its condition; its tools. mesh-catalog's `claude-licence-manager`, `claude-code` and `mesh-vault` in one pull request, on what main holds today | delivered 2026-11-12; its part is [`39-milestones/bus-and-switch.md`](39-milestones/bus-and-switch.md), its four questions answered by the principles (A1 to A4) |
| parts | the module as four parts in one manifest: the manager bundle (running long, the seat's verbs, every act), the tools bundle (every tool that reads), the settings, the account; the carry-over's code and the requirements of the store database and `grant-key` leave, both retiring on the operator's Approve and the database removed by the operator. mesh-catalog's `claude-licence-manager` alone | designed; its part is [`39-milestones/parts.md`](39-milestones/parts.md) |
## What this does not settle
- An automated switch on exhaustion (§5).
- Whether an OAuth refresh token is single-use; the lab measures it, and §3 holds either way.
- How the mesh's own session and a worker read their token on a node once those exist
([to-be 15](15-the-agent-session.md), ADR 0003):
@@ -0,0 +1,184 @@
---
layer: to-be
status: in-progress
design: 42
milestone: zfs-owns-zfs
updated: 2026-11-18
decisions:
- "ADR 0679"
- "ADR 0680"
---
# 42, milestone zfs-owns-zfs — the lead's answers to the prepare's questions
The lead's answers to the prepare's design questions (Q-n) and to the places where a design line and the code
disagree (C-n), for the milestone part [zfs-owns-zfs](zfs-owns-zfs.md): each one line, naming the principle that
settles it (`00-META/principles.md`), cited as "design 42 zfs-owns-zfs A-n". The code read is the prepare's, at the
`origin/main` commits its milestone file names.
- **A-1** (Q-1, §8; principles 2 and 7) The pool's name is not held by mesh-config: it is the zfs module's
`values` in the home server's assignment (seat `mesh-module-assigner`), a layer mesh-config's rename does not move.
So the module keeps `renamed-from: scrub-pool` for the values mesh-config holds, and at the delivery the lead moves
the assignment's value: `pool` set to that name through mesh-config for the home server, and the assignment
proposed without `scrub-pool` through `mesh-module-assigner.propose`, both before the new version is placed.
- **A-2** (Q-2, §14; principle 7) The module's ZED folder also holds the package's `zed-functions.sh`, from the
module's files archive, root's, mode 0644, under `if-config: [zed=on]` beside `zed.rc`; the handlers find it where
ZED points them, and nothing else changes.
- **A-3** (Q-3, §13; principles 2 and 7) `trim-schedule: none` is a set value meaning "no trim by the mesh": the
distribution's trim timers are held stopped for `none`, `weekly` and `monthly` alike; only an unset value leaves
them as found.
- **A-4** (Q-4, §3; principle 3) The validator refuses a `:` in a `config-lines` prefix, beside `}`, `$` and a
newline, naming the key.
- **A-5** (Q-5, §3; principle 3) The validator refuses `mib-bytes` on a value whose type is not a number, and a
`config-lines` key the module does not declare, as it refuses `${config:<key>}` of an undeclared key today.
- **A-6** (Q-6, §18, §24; principles 1 and 6) The follower's process bus declares
`invokes: ["seat:node-service-manager.start"]`, and the module's `invokes` carries the same for its tools bundle.
- **A-7** (Q-7, §14, §18; principle 7) `/etc/zfs/mesh-zed.d` is a directory resource under `if-config: [zed=on]`
with `unknown: module`; `/run/zfs-tools` is a directory resource with `unknown: program`, as `/run/zfs-events` is.
- **A-8** (Q-8, §18; principle 3) `zfs-tools apply` exits 0 on a refusal and on a wait, which it says by event and
in its state `applied` and which make the module unhealthy by §29; it exits non-zero only when a command it ran
failed, so the node-engine gates the module on a real failure.
- **A-9** (Q-9, §30; principle 7) When the module leaves a node, its kept data (the states `applied`, `schedule` and
`findings`, the ledger `snapshots`, the events stream) is kept as every module's kept data is on leaving; a return
finds its scheduled ZFS snapshots' records.
- **A-10** (Q-10, §27; principle 7; corrected by A-32) The findings stream is the one design 47 G §383 defines for every observer:
`zfs-findings`, its events `finding-written.*`, `finding-cleared.*` and `findings-stated.*`, kept 7 days and
16 MiB, said by the writer generated from the seat `mesh-conditions`' definition; the module declares it as §383
says and builds nothing of its own for it.
- **A-11** (Q-11, acceptance test 8; principles 5 and 7) Test 8 runs in the test lab, on a pool built on a
file-backed device, never on the home server's pool.
- **A-12** (Q-12, §24; principles 3 and 4) A hand act's tool waits at most 30 seconds for the act's event; past it,
it answers "started", naming the act and that `zfs_module_events` reads its outcome, and never answers "done"
for what it did not see end.
- **A-13** (C-1, §4; principle 7) The node-engine states the new reading as `word:resources.if-config` and
`form:config-lines` (and `form:config-json`, A-15), computed by `ManifestReads` and marked by `ManifestNeeds`;
stopping at the first failure is stated by no capability, since the node-engine build that reads those words is
the build that stops.
- **A-14** (C-2, §11; ADR 0679 §3; principle 7) The validator accepts a config value with neither a default nor
`required` as "not managed until set"; built in the validator's subtasks of this milestone.
- **A-15** (C-3, §9; principles 2 and 7) The config file's content is one new node-engine placeholder
`${config-json}`: the module's set config values as one JSON object, an unset value absent, lists and objects as
JSON; no unset value refuses the module. It is built with §2 and §3 in the node-engine, the validator and
mesh-sdk's form list, and stated as `form:config-json`; no existing form writes an unset value as absent.
- **A-16** (C-4, §18; principle 7) The follower, which runs from boot, starts the apply unit once at its own start
and on the events §27 names; the apply's own wait for an unimported pool (§18) stands for the order after
`zfs-import.target`. No new process field.
- **A-17** (C-5, §24; principle 7) A hand act writes its act into the state `schedule` under its own key and starts
`zfs-mesh-run.service`; the run reads the key, acts under the same lock and guards, and deletes it. No instance
units.
- **A-18** (C-6, §24; principle 7) `node-service-manager.start` is called with `{scope, unit}`; the tool keeps
`why` in its own event. The seat is not changed.
- **A-19** (C-7, §26; principle 7) The ledger `snapshots` declares a fixed `max-mib` sized from the bound of 168 per
kind (§11); a full ledger takes §21's "ledger full" path.
- **A-20** (C-8, §21, §22, §26; principles 1 and 7) A process cannot write a ledger: the ledger is served to a tools
bundle alone, through the tool runner (mesh-sdk `buscalls`, `ProcessBus` has no ledger). The scheduled run records
`taken` and `removed` by calling its own module's tool `zfs_snapshots_record` (declared in the run's process bus
`invokes`), whose bundle applies the operation to the ledger; the tool refuses a snapshot not named `mesh-`. No new
field in mesh-sdk.
- **A-21** (C-9, §13; principle 2) When one record of a unit goes while another still declares it, the found state
passes to the record that stays, as a file is handed to the resource still declaring its path (ADR 0223); built in
the node-engine's §2 subtask.
- **A-22** (C-10, the test budget; the test-budget instruction) The node-engine's repository is over its budget (about 1,742 unit tests
against 500): each new table test merges or replaces at least as many tests in the file it touches, named in the
build map, so the count does not rise.
- **A-23** (C-11, §9, §11; principle 6) The config file carries `"trusted": false`; each value's own `trusted` (§11)
decides who sets it.
- **A-24** (C-12, §2, §3; principle 3) `config-lines` and `config-json` are added to the validator's and the
composer's placeholder tables, and the validator counts `if-config`, `config-lines` and `config-json` as placing
their keys.
- **A-25** (A-15, S2; principle 3) `${config-json}` holds no colon, so the form search that finds `${<form>:` does not
find it: the manifest's reading also finds the exact token `${config-json}`, and a manifest that holds it needs
`form:config-json`, so no node-engine that cannot write it is given the module.
- **A-26** (§1, met in develop; principles 3 and 7) §1 stands: a module declares a resource another of its resources
needs before that one, since the apply now stops at the first failure. The pacman module declares its package
before its config file, and its package fails while the config file is missing, so the stop would keep a node
from restoring its package manager: in this milestone the pacman module's config file moves before its package,
and the node-engine's probe test of that restore keeps the pacman module's own resource names, in that order.
- **A-27** (§11, met in develop; principle 7) `snapshots` is an object, so its `none` is the object holding only the
key `none` set to true; keep counts are its other form, and the text `none` is refused as the type refuses it.
- **A-28** (§11, met in develop; principle 3) One refused value refuses the whole config: nothing is converged until
every value is valid, and each refused value is its own `config.refused`.
- **A-29** (§11, §18, met in develop; principle 3) The node's memory is read by the apply and given to the parse; a
memory that cannot be read refuses `arc-max` and `arc-min`, never guesses them.
- **A-30** (§21, §22, §26, A-19, A-20, met in develop; principles 1 and 7) The ledger `snapshots` uses the ledger's
own forms (ADR 0597) and nothing new: one type `snapshot`, its fields `dataset`, `name`, `kind` and `at`, all text;
an instance `snapshot/<kind>-<UTC stamp>-<dataset>`, the dataset's `/` written `~` (a character no ZFS name holds);
the operation `taken` with the effect `set-fields` on those four fields, and `removed` with the effect `remove`
naming no map, so the instance's state goes while its history keeps both operations; one index `by-dataset-kind` on
`dataset` and `kind`, read through `mesh/ledger.query`, the newest `at` among a kind's entries being its last.
- **A-31** (§21, §22, §28, A-20, met in develop; principles 1 and 7) The scheduled run reads the ledger as it writes
it, through its own module's tools: its process bus also invokes `zfs.zfs_snapshots_schedule`, whose answer holds
the ledger's entries (§28), and the run takes a kind's last entry and the entries to prune from that answer.
- **A-32** (corrects A-10, §27, met in develop; principles 2 and 7) The writer A-10 names is not on mesh-sdk's main: it
is built only on design 47 G's branch, a milestone not yet delivered. The follower says its findings in its own
state `findings`, keyed and written as every observer on main writes its findings today, and declares no
`zfs-findings` stream; G's change of §387 writes that stream into every module that declares a state `findings` on
main when it lands, the zfs module among them. Read before A-10 was given: nothing; the lead now reads what an
answer names first (playbook 07, step 0b).
- **A-33** (§20, met in develop; principle 3) A trim schedule set without its `trim-day` or `trim-time` runs no trim and
is said: the parse refuses it as one refused value (A-28), naming the missing value.
- **A-34** (§24, A-18, met in develop; principle 7) A hand act's `why` and `by` are kept in its key of the state
`schedule`, which the run deletes once it acted, and its outcome is the event the act itself emits (§25); no new
event kind.
- **A-35** (§21, §22, met in develop; principle 3 and the operator's "we may absolutely not lose any data") A kind's
keep count of 0 is that kind's `none`: none is taken, its existing scheduled ZFS snapshots are kept and a warning
names them; only a count above 0 prunes past it.
- **A-36** (corrects A-30, §26, met in develop; ADR 0597; principle 7) The ledger's `remove` effect names a map and a
key (the validator refuses one without), so the instance is one per dataset and kind:
`snapshot/<kind>-<dataset>` (the dataset's `/` written `~`), its state a map `taken` keyed by the ZFS snapshot's
name; `taken` is the effect `set-entry` into `taken` under the field `name`, with `dataset`, `name`, `kind` and `at`;
`removed` is the effect `remove` from `taken` under `name`. A kind's live ZFS snapshots are the instance's map, its
last the newest `at` there, so no index is declared.
- **A-37** (§18, §20, §26, §27, A-6, A-20, met in develop; ADR 0436 §1, §2; principle 7) A process's bus account is a
user the module makes, never root, so the three root processes (the apply, the run, the follower) declare no `bus`.
The module makes a user `zfs-keeper` and one process `zfs-keeper` running as it, which holds the module's one process
bus account (its events, its states `applied`, `schedule` and `findings`, and its invokes of
`zfs.zfs_snapshots_record`, `zfs.zfs_snapshots_schedule` and `seat:node-service-manager.start`). It serves a unix
socket in the module's state directory that only root may open (the peer's uid checked), with a closed list of
calls: emit an event, put or delete a key of those states, and invoke one of those three. The root processes say
everything they say on the bus through it; with the keeper not answering they act as with the bus down (A-8), and
warn. The module's tools keep their own account as today.
*Amended 2026-11-18:* ADR 0680 §1 ends ADR 0436 §1's "never root" for a process that declares `bus`, so this
answer's premise no longer holds; the keeper stands as the milestone builds it, a choice the records no longer force.
- **A-38** (A-37, §25, §26, met in develop; ADR 0436 §1, ADR 0595 §1, §2; the operator's "a case the delivery cannot
handle is a gap in the build and delivery system") A process's `bus` today is judged and granted only against the
module-level `emits` and `state`, which ADR 0595 replaced by what a module asks for in `requires`. In this
milestone a process's `bus.emits` may name an event of the events stream its module asks for by template in
`requires`, and its `bus.state` a state its module asks for there: the validator accepts them (in the indexer's
process-bus rule), and the grants (mesh-grants) give the process's account publish on that stream's subjects of
its own node and the reads and writes of those states, as they give a module's tools account today. A name its
module does not ask for is refused as today.
- **A-39** (A-37, A-17, met in develop; principle 7) The keeper's closed list of calls also reads: `get` one key and
`keys` of the same three states, since the run reads a hand act's key and the apply its state `applied`.
- **A-40** (A-36, met in develop; principle 3) A ledger instance not yet written is the tool runner's answer to
`mesh/ledger.get` with a state `null` and sequence 0 (the tool runner's `internal/ledger/read.go` `Get`, in mesh-tools), never
an error: the module reads it so, and recognises no error by its text.
- **A-41** (§25, A-37, A-38, review round 1; principles 1 and 7; shared code belongs in mesh-sdk) The events stream a
module asks for by template `events` captures `mesh.bus.<module>.<local>.>` (the bus module's keeper, `PlanOf`), and
that is what the grants of A-38 give. The keeper publishes each event there, as a JetStream publish the bus
acknowledges, on `mesh.bus.<module>.<local>.<event>`, the subject named by a new mesh-sdk helper
`process.Account.BusSubject(local, event)` beside `EventSubject` and `StreamSubject`; never `process.Conn.Emit`,
which publishes on the module's old event subjects.
- **A-42** (§25, A-12, A-41, review round 2; principles 1, 3 and 7; the operator's "a case the delivery cannot handle
is a gap in the build and delivery system") A tools bundle has no way onto the events stream its module asks for by
template: the tool runner's `mesh/publish` publishes on the module's old event subjects and reads no binding (the
tool runner's `PublishAs`, `eventSubject`), and its `mesh/subscribe` hears only the old streams. This milestone
builds the one path it lacks, by name, beside the bus-state calls a bundle already makes: a call
`mesh/stream.publish` {stream (the local name), event, body, id} in mesh-sdk's `buscalls`, which the tool runner
answers for the bundle's own bound stream alone by an acknowledged JetStream publish on the binding's subject plus
`.<event>`, the id as the message id, under the grant the tool runner's account already holds (`boundOf`). The zfs
tools say every event of §25 with it, never `stdio.Emit`. A hand act's tool hears its act's event by reading its own
events stream with the calls it has (`mesh/stream.fill` for the last sequence before it starts the act, then
`mesh/stream.read` from the next one with the act's subject), for at most the 30 seconds of A-12. The other modules
whose bundles emit onto a template events stream (messenger) move to the call in a change of their own.
- **A-43** (corrects A-12 and A-42's wait, met in develop; principles 1 and 7: nothing polls) A hand act's tool does not
wait: once its act's key is written and the run's unit started, it answers "started" at once, naming the act and that
`zfs_module_events` reads its outcome, as §24 says ("the tool answers from the state and events afterwards"). The
bundle has no watch on its events stream, and a repeated read for 30 seconds is a poll.
- **A-44** (A-42, met in develop; principle 3; the module graph orders the delivery) `mesh/stream.publish` is a family
of its own, the capability `stream-publish`, which the new tool runner states; the zfs module's `capabilities` ask
for it (and for `bus-state-calls` and `ledger-calls`, the calls it already makes), so the delivery plan places the
zfs module's new version only on a machine whose tool runner answers the call, and never one where its events would
fail.
- **A-45** (§13, review round 3; ADR 0240; principle 3) Each long-running unit the module declares (the services
`import-cache`, `mount`, `target` and `zed-on`) declares its health of kind `unit`, as the catalog's other
long-running resources do, so no running part of the module goes unwatched.
@@ -0,0 +1,337 @@
---
layer: to-be
design: 42
milestone: zfs-owns-zfs
updated: 2026-11-12
code: [mesh-sdk, mesh-delivery, mesh-host internal/apply, mesh-catalog modules/zfs]
decisions:
- "ADR 0679"
- "ADR 0051"
- "ADR 0117"
- "ADR 0269"
- "ADR 0303"
- "ADR 0348"
- "ADR 0508"
- "ADR 0564"
- "ADR 0593"
- "ADR 0595"
- "ADR 0609"
- "ADR 0614"
---
# Design 42, milestone zfs-owns-zfs — the zfs module owns a node's ZFS, and changes nothing that is not set
**What it builds.** On a node that holds a ZFS pool (today the home server), the zfs module owns ZFS's packages, its
kernel module's options file, its host id, its own folder for ZFS's event daemon (ZED), its units and, for one pool,
its cache and log devices, its properties, its datasets' properties and a schedule of ZFS snapshots; each is changed
only once its config value is set and not empty (ADR 0679). The purpose and the whole shape are the main file's,
[*The zfs module*](../42-the-machines-modules-in-order.md#the-zfs-module). This part holds every line the milestone
builds, cited as "design 42 zfs-owns-zfs §n".
**Where.** Built under issue 1979. Four repositories, one delivery group with one check: mesh-sdk, mesh-delivery
(the manifest validator) and `mesh-host` (the node-engine) for §1 to §5, issue 1979's three node-engine subtasks
and the readers of their words; mesh-catalog's `modules/zfs` for §6 to §31. **Ordering edges** (ADR 0679 §16): the
readers in §4's order, then the zfs module's new version only on a node whose node-engine states the three
capabilities of §4 (a reader's capability the delivery plan derives, ADR 0614 §4).
## The prerequisites (ADR 0679 §16)
1. **The node-engine's apply of a module stops at its first failed resource** (ADR 0679 §16 (a)). When one resource
of a module fails, the node-engine applies none of that module's later resources in the declared order; its apply
report names the failed resource with its error and each one left unapplied, and the module's phase is `failed`.
Resources already applied stay as applied; other modules on the node go on as today. Today the apply goes on, and
stopped the distribution's scrub timer after the module's own timer failed. Checked by a unit test (a module of
three resources whose second fails leaves the third untouched and reports it as left) and by §5.
2. **A resource is declared only while a config value holds** (ADR 0679 §16 (b), §3). A resource of any type may
carry the manifest field `if-config`: a list of conditions, each `<key>` (the module's config value is set and is
neither `false`, `off`, `none` nor an empty list) or `<key>=<value>` (the value equals it; for a list value, the
list holds that entry). The resource is declared while any condition holds, and not at all while none does. A
resource that leaves the declaration this way is removed as any resource that leaves it: a file the node-engine
wrote whole is deleted, a unit gets its found state back (ADR 0269 §2). The manifest validator refuses an
`if-config` key the module does not declare under `config`. Checked by the node-engine's table test (a value unset,
empty, `off`, set; a list with and without the entry; a value going from set to unset removes the resource) and
the validator's own test.
3. **A template writes one line per entry** (ADR 0679 §16 (c), §4). A template file may hold
`${config-lines:<key>:<prefix>}`: for a list value one line per entry, `<prefix><entry>`, in the list's order;
for a set scalar value one line `<prefix><value>`; nothing for an unset value or an empty list. With a fourth part,
`${config-lines:<key>:<prefix>:mib-bytes}`, a number given in MiB is written in bytes. The prefix is literal text
with no `}`, `$` or newline, refused by the manifest validator; an entry holding a newline is refused before the
file is written, and the file is left as it was. Checked by the node-engine's table test (a list of two, an empty
list, an unset and a set scalar, `mib-bytes`, a newline in an entry) and the validator's own test.
4. **Every reader of the new words, in order** (design-it-as-it-should-be; ADR 0614 §4). mesh-sdk first: the
manifest types gain `if-config` on every resource and the template form `config-lines`, and the capability names
`if-config`, `config-lines` and `apply-stops-at-failure`. Then the manifest validator in mesh-delivery's indexer:
it reads both words and refuses them as §2 and §3 say. Then the node-engine: it builds §1 to §3 and states the
three capabilities. A manifest using `if-config` or `config-lines` reaches a node only through a node-engine that
states both; the delivery plan derives the edge from the stated capability, never from a fingerprint. Checked by
each repository's unit tests and by the delivery plan naming the edge.
5. **One integration test of the node-engine** (how-work-is-done: a change to how modules run carries one). It
starts the node-engine whole against the real bus with a module of a resource under `if-config`, a template with
`config-lines`, and a resource that fails: the conditioned resource appears when its value is set and goes when it
is unset, the template's lines follow the list, and the failing resource stops the module's apply with the later
resource left. It is the only integration test this milestone adds.
6. **The order on the node** (ADR 0679 §16, §9). The zfs module declares its scheduled run's resource (§20) before
the resources that stop the distribution's scrub timers, so by §1 those are stopped only once the run's timer is
active. The run's `schedule` is the list form `0,15,30,45 * * * *`, which today's node-engine writes as
`OnCalendar=*-*-* *:0,15,30,45:00`, so nothing waits on another fix. Checked by the module's manifest test (the
resource order and the schedule string) and by acceptance test 3 of the main file.
## What the module owns
7. **The packages** (ADR 0679 §1; ADR 0303 §2). The manifest declares `zfs-utils` and `zfs-dkms` present: the
node-engine installs a missing one, upgrades none, removes none. `zfs-utils-debug` is not declared and is left as
found. Fate: the README's "It installs nothing" goes; it says the two packages and why the debug package is not the
module's. Read by `pacman_packages` as declared by `zfs`. Checked by the manifest test.
8. **One pool, renamed `pool`** (ADR 0679 §1; ADR 0609 §4). The config value `scrub-pool` becomes `pool` with
`renamed-from: scrub-pool`: type string, trusted, required. mesh-config moves the value under the new name and
answers both names during the rename window (design 32, *A config value renamed*); every template and the module's
code read `pool`. **Rollback:** a rolled-back version leaves pool and dataset properties and devices as the last
apply set them (ADR 0679 §15); once the rename window has closed, going back to the version with `scrub-pool` and
`zfs-mesh-scrub` is a new delivery of that version, with its own rename back, never a rollback. Checked by the
manifest test (no `scrub-pool` but in `renamed-from`) and `zfs_config` showing `pool` on the home server.
9. **The module's config file** (ADR 0679 §9; ADR 0348 §5). `/etc/zfs-tools/config.json`, root's, mode 0644, written
by the node-engine from a template holding every config value of the module, lists and objects rendered as ADR 0348
§5 says; it replaces `/etc/zfs-tools/scrub.conf`, which the node-engine removes as a resource that left. The apply
unit (§18) has `restart-on` this file: its change is the path by which mesh-config's `config-changed` for the
module's values reaches the apply. The scheduled run (§20) reads it at each run. `/var/lib/zfs-scrub` stays and is
read by the run as today. Checked by the manifest test.
10. **What it never writes** (ADR 0679 §1, §2). The package's own `/etc/default/zfs` and `/etc/zfs/zed.d`, with its
`zed.rc` and its links, are left as the package ships them, and nothing of them is given back on leaving; ZFS's own
`/etc/zfs/zpool.cache` and `/etc/zfs/zfs-list.cache` are read only. `zfs_config` shows each, and a `.pacnew`
beside `/etc/default/zfs` or the package's `zed.rc` is a warning (§29). A dataset's `sharenfs` is the seat
`node-nfs-server`'s, `sharesmb` the SMB module's (issue 613): neither is on a list of §16, a value naming either
is refused (§11), and `zfs_config` never reports either as differing. The pool's files are the operator's (ADR
0051). Checked by the call-site test (§19) and §31.
## The config values and their forms
11. **Not managed until set and not empty; each of a fixed form** (ADR 0679 §3, §4). No new value has a default in
the manifest. An absent value and an empty list both mean not managed: the module writes nothing, converges
nothing and reports no difference for it, so nothing is ever removed by a blank value. A value of another form is
refused by the module's own parse before any file is written or command run, emitting `config.refused` (§25).
Trusted values (every list and object below, `log-mirror` and `hostid`) are set only on the operator's Approve (ADR
0348 §4, §8). The module never reads a value from the node into config.
- `arc-max`, `arc-min` (number): whole MiB, `arc-min` ≤ `arc-max`, `arc-max` at least 64 and below the node's
memory read from `/proc/meminfo`. ZFS's read cache in memory (the ARC) is bounded by them.
- `module-options` (list, trusted): entries `name=digits`, the name from the module's fixed list `l2arc_write_max`,
`l2arc_write_boost`, `l2arc_headroom`, `l2arc_noprefetch`, `l2arc_rebuild_enabled`, `zfs_txg_timeout`,
`zfs_dirty_data_max`, `zfs_scan_vdev_limit`, `zfs_scrub_min_time_ms`, `zfs_resilver_min_time_ms`,
`zfs_arc_sys_free`; `zfs_arc_max` and `zfs_arc_min` are refused here, as `arc-max` and `arc-min` hold them. Reason:
the ARC, L2ARC, transaction group and scrub parameters ADR 0679 §4 names, and nothing else.
- `hostid` (string, trusted): eight hexadecimal digits, not all zero (§15).
- `zed` (string): `on` or `off`. `zed-handlers` (list, trusted): from `all-syslog` (the journal handler) and
`resilver_finish-start-scrub` (scrub after resilver), the two ADR 0679 §12 names; no notify handler.
- `trim-schedule` (string): `none`, `weekly` or `monthly`; `trim-day` and `trim-time` with `scrub-day`'s and
`scrub-time`'s forms.
- `cache-devices`, `log-devices` (lists, trusted): names under `/dev/disk/by-id`, letters, digits, `-`, `_`, `.`
and `:` only. `log-mirror` (boolean, trusted): when true, `log-devices` holds exactly two names, added as one
mirror; otherwise each is a log device of its own. Reason: the log's form today is a mirror.
- `pool-properties` (object, trusted): `autotrim`, `autoexpand`, `autoreplace` (`on`, `off`, `default`) and
`failmode` (`wait`, `continue`, `panic`, `default`).
- `dataset-properties` (object, trusted): a dataset of the pool (the pool's name or one beginning `<pool>/`) to
properties of §16's list with their forms.
- `snapshots` (object, trusted): `none`, or keep counts `hourly`, `daily`, `weekly` and `monthly`, each a whole
number from 0 to 168, a kind with 0 not taken; for every filesystem of the pool. The bound 168 (a week of hours)
is the design's, so the ledger's cap (§26) stays bounded.
Checked by §31's refused-forms tests, one table per value, the empty list among them.
## Files, units and the event daemon
12. **The options file** (ADR 0679 §1, §4). `/etc/modprobe.d/zfs.conf`, root's, 0644, carries `if-config: [arc-max,
arc-min, module-options]` (§2) and holds a header comment, then by §3 `options zfs zfs_arc_max=` and `options zfs
zfs_arc_min=` with the values in bytes (`mib-bytes`), then `options zfs ` with each `module-options` entry. With
none of the three set it is not placed. Checked by the manifest test and §31's template test.
13. **The units** (ADR 0679 §1, §15; ADR 0117). Declared running and enabled at boot: `zfs-import-cache.service`,
`zfs-mount.service` and `zfs.target`, as they run on the home server today, so declaring them changes nothing.
Declared with no state, owned and left as found: `zfs-import-scan.service`, `zfs-share.service`,
`zfs-volume-wait.service` and `zfs-import.target` (reason: ADR 0679 §15 keeps only the first three running when the
module leaves, so no other ZFS unit is one the mesh would stop then). `zfs-zed.service`: running and enabled with
`if-config: [zed=on]`, stopped and disabled with `if-config: [zed=off]`, left as found while `zed` is not managed.
The distribution's `zfs-trim-weekly@<pool>.timer` and `zfs-trim-monthly@<pool>.timer` are stopped and disabled
with `if-config: [trim-schedule]` (the run trims, §20); its scrub timers are stopped and disabled after the run's
timer (§6). Read by `<node>/node-service-manager.status`. Checked by the manifest test (each unit, its state and
its condition).
14. **ZED runs from the module's own folder, without links** (ADR 0679 §13, §12). The folder `/etc/zfs/mesh-zed.d`
(root's, 0755), its `zed.rc` and a drop-in for `zfs-zed.service` whose `ExecStart` adds `-d /etc/zfs/mesh-zed.d`
carry `if-config: [zed=on]`. The module's `zed.rc` holds the package's variables but every `ZED_NOTIFY_*` and mail
line, and `ZED_SCRUB_AFTER_RESILVER=1`, which only the scrub-after-resilver handler reads. Each handler is a file
of its own in the folder, a copy of the package's script by its content kept in the module's files archive, mode
0755, with `if-config: [zed-handlers=<its name>]`, so only the handlers set are placed. The package's
`/etc/zfs/zed.d` is not read while the drop-in holds. The mesh creates no symlinks. The node-engine restarts
`zfs-zed.service` on a change of the drop-in, a handler or `zed.rc` (`restart-on`). Checked by the manifest test (no
link resource, each handler's condition).
15. **The node's ZFS id** (ADR 0679 §1, §3, §4, §17). `/etc/hostid` holds four bytes, binary, which no template writes,
so it is no resource of the manifest and the apply (§18) writes it with ZFS's own writer, `zgenhostid -f <value>`,
only while `hostid` is set, and only when the pool's label (`zdb -C <pool>`, its `hostid`) is 0 or equals the value:
then the next boot imports without `zpool import -f`. When the label shows another value, or cannot be read, it
writes nothing and emits `config.refused` naming why ("the pool's import would need -f", "the pool's label cannot be
read"). Before the Approve, the value's description and `zfs_config` say the change needs a check of the pool's
import at the next boot; the module never reboots. After the reboot, `zfs_pools` shows the pool imported. Emits
`config.applied` with target `file`. The apply reads `/etc/hostid` back at every start and after every write: while
`hostid` is set, a value there other than the set one emits `config.refused` naming it, because the node-engine's
composer cannot see a second writer of a file that is no resource. Each refusal of this line makes `zfs_health`
unhealthy (§29), naming the key and why, until an apply finds the label and the file agreeing with `hostid`, or
`hostid` is unset. No resource or template of the manifest writes `/etc/hostid`. Checked by §31 (unset: no
`zgenhostid`; a label of another id, or one that cannot be read: refused; 0 or equal: one run; a file holding
another value: refused; unhealthy, then healthy again; no manifest resource for the file).
## The pool
16. **Pool and dataset properties** (ADR 0679 §6). For each set pool property the apply runs `zpool set
<property>=<value> <pool>`, and for `default` `zpool set <property>=<ZFS's default> <pool>`. For each set dataset
property it runs `zfs set <property>=<value> <dataset>`, and for `default` `zfs inherit <property> <dataset>`, so
its source stays default. The dataset list is `compression` (`off`, `lz4`, `zstd`, `zstd-1` to `zstd-19`,
`gzip-1` to `gzip-9`, `zle`), `atime` and `relatime` (`on`, `off`), `recordsize` (a power of two from `512` to
`16M`, with `K` or `M`), `primarycache` and `secondarycache` (`all`, `metadata`, `none`), `sync` (`standard`,
`always`, `disabled`), `logbias` (`latency`, `throughput`), `quota` and `reservation` (`none` or digits with `K`,
`M`, `G` or `T`). A property already at its value runs nothing. Each change is read back with `zpool get -Hp` or
`zfs get -Hp` and emitted (§25). Checked by §31's convergence tests.
17. **Cache and log devices** (ADR 0679 §5). From `zpool status -P -L <pool>` the apply knows each device's kernel
path, and from the link under `/dev/disk/by-id` each declared name's. Then, in this order:
- an entry of the pool whose kernel path is a declared device's, but named by its kernel name, is removed
(`zpool remove <pool> <entry>`) and added again by its stable name;
- a declared device not in the pool is added with `zpool add <pool> cache|log [mirror] <names>`, never `-f`, and
only after its checks: a device with a partition table or a file-system signature (`wipefs --no-act <device>`)
is refused, but for a `zfs_member` signature, which is judged by its label (`zdb -l <device>`): this pool's
label is allowed, another pool's refused; a device that is a member of any imported pool is refused;
- only while `cache-devices` is set and not empty, a cache entry it does not name is removed;
- only while `log-devices` is set and not empty, a log device it does not name, one to rename, or the log when
`log-mirror` changes (a removal and a re-add, said as such) is removed only while the pool is ONLINE with no
read, write or checksum errors and no scrub or resilver runs; otherwise it is a wait, `config.waiting` {key,
waits-on, since}.
A declared device that is not present is a wait. Each change is read back from `zpool status -P` and emitted.
Checked by §31's convergence tests (the empty list among them) and acceptance test 2.
18. **The apply: who, when, and what wakes a wait** (ADR 0679 §9, §17). A `process` resource `zfs-config-apply`, `run:
./zfs-tools apply`, as root, oneshot, ordered after `zfs-import.target`, enabled at boot, with `restart-on` the
config file (§9); it converges §15 to §17 and writes the ARC values live. It holds an exclusive lock on
`/run/zfs-tools/apply.lock`; a second start waits for it. It converges nothing while a scrub or resilver runs on
the pool or before the pool is imported: it emits `config.waiting` with what it waits on and since when, and ends.
It never runs on a timer. **A wait is ended by an event:** when the event follower (§27) hears a scrub or a
resilver finish (ZFS's `scrub_finish` and `resilver_finish` events) or a declared device appear (a udev `add` of a
block device whose link under `/dev/disk/by-id` is declared, read with `udevadm monitor --udev
--subsystem-match=block`), it starts the apply unit through `<node>/node-service-manager.start`. While the bus or
the control-node is down, the apply converges from the config file it last got. It writes `arc-max` and `arc-min`
to `/sys/module/zfs/parameters/zfs_arc_max` and `zfs_arc_min` as well as to §12's file, and reads both back; each
`module-options` entry whose live value differs is a warning naming it, "takes effect at the next load of the
kernel module", never success and never unhealthy.
19. **The call-site test** (ADR 0679 §7, §17). Every command the bundle runs is built by one of its argument functions, and
the test (`TestTheBundleRunsOnlyReadingVerbsSnapshotAndScrub`, renamed `TestTheBundleRunsOnlyTheFormsOfADR0679`)
allows only: `zpool add <pool> cache|log`, `zpool remove` of a cache or log device, `zpool set`, `zfs set` and `zfs
inherit` of a listed property, `zfs snapshot`, `zfs set mesh:schedule=<kind>` on a ZFS snapshot named `mesh-`,
`zfs destroy -- <dataset>@<snapshot>`, `zpool scrub`, `zpool scrub -p` and `zpool scrub -s` of the pool, `zpool trim`
of the pool; and the reads `zpool status`, `zpool list`, `zpool get`, `zpool iostat`, `zpool events`, `zfs list`,
`zfs get` and `zfs holds`. It refuses every other `zpool` or `zfs` form and every `-f`, `-r`, `-R` and `-d`, so
data vdevs, spares, special and dedup devices, `upgrade`, a dataset's destroy, `rollback`, `rename` and `clear` are
never run (each an act of its own, asked of the operator). The same test pins the module's other root forms:
`wipefs --no-act <device>`, `zdb -l <device>`, `zdb -C <pool>`, `zgenhostid -f <value>`, `udevadm monitor --udev
--subsystem-match=block` and `systemctl show`, and refuses every other `zgenhostid` or `zdb` form: `zgenhostid`
only as `-f` with the value §11 validated, `zdb` only as these two reads. Fate: the README's list of allowed forms
is replaced by this one.
## The scheduled run and ZFS snapshots
20. **The scheduled run** (ADR 0679 §9). The `process` resource `zfs-mesh-scrub` (`./zfs-tools scrub-run`) becomes
`zfs-mesh-run` (`./zfs-tools run`), root as today, with §6's schedule. Each run takes the apply's lock; when the lock
is held it does nothing and emits `run.skipped` {reason: `lock-held`}. It does nothing while a scrub or resilver
runs or before the pool is imported, emitting `run.skipped` with that reason. Otherwise, in order: it starts the
scrub when due and returns at once, never waiting on it (today's wait with `zpool wait -t scrub` goes; the scrub's
end is heard by the event follower, §27); starts a trim when `trim-schedule` is due (`zpool trim <pool>`, by
`trim-day` and `trim-time` in the node's time zone, as the scrub reads its own); and takes and removes the ZFS
snapshots (§21, §22) when `snapshots` is set. Checked by §31 (lock held: nothing run; scrub due: started and the
run ends).
21. **Taking scheduled ZFS snapshots** (ADR 0679 §8). Each kind whose keep count is above 0 is due at the first run of
the hour (hourly), the first run after midnight (daily), the first run on Monday (weekly) and the first run on the
first of the month (monthly), each read in the node's time zone against the ledger's last entry of that kind (§26).
For every filesystem of the pool it runs `zfs snapshot -- <dataset>@mesh-<kind>-<YYYYMMDDTHHMMZ>`, the time in UTC,
never recursive, then `zfs set mesh:schedule=<kind>` on it, and records the ledger's `taken` operation. The run
takes no ZFS snapshot it cannot record in the same run: with the bus down or the ledger full it takes none and
emits `snapshot.skipped.schedule` {pool, capacity, reason}. No ZFS snapshot is taken while the pool is more than 80
% full (`zpool list -Hp -o capacity`): a warning says so, and `snapshot.skipped.schedule` is emitted with reason
`full`.
22. **Removing them, only by their own record** (ADR 0679 §8; the operator, 2026-11-12: "we may absolutely not lose any
data"). After taking, the run reads the ledger in the same run (no read, no removal) and, per dataset and kind,
removes the oldest past its keep count, all of them in that run. Before any destroy it checks the name against
`<a dataset of the pool>@mesh-<kind>-<YYYYMMDDTHHMMZ>`, that it carries `mesh:schedule=<kind>`, is in the ledger,
has no hold (`zfs holds`) and no clone (`clones` empty); anything else is refused, emitted and left. Then `zfs
destroy -- <dataset>@<snapshot>`, the ledger's `removed` operation, and `snapshot.removed.schedule` {snapshot, kind,
space freed in bytes}. When `snapshots` goes back to `none`, the existing scheduled ZFS snapshots are kept, and a
warning names them; that change removes nothing. A ZFS snapshot taken by hand is never removed.
23. **A person's ZFS snapshot stays apart** (ADR 0679 §8, §10). `zfs_snapshot` refuses a name beginning `mesh-` and
emits `snapshot.taken.person`; the run emits `snapshot.taken.schedule`. A waiter on a person's ZFS snapshot waits
on `snapshot.taken.person`, which no scheduled one is said on. Fate: the README's "No tool of the mesh destroys a
snapshot" becomes §22's rule.
24. **Hand acts run as the run does** (ADR 0679 §14). `zfs_snapshots_run_now`, `zfs_snapshots_prune_now` and
`zfs_config_apply` each start a oneshot instance of the unit `zfs-mesh-run@<act>.service`, the act from the fixed
set `snapshots`, `prune` and `apply`, through `<node>/node-service-manager.start`, with `why`; the instance runs
under the same lock and guards as §18 and §20, and the tool answers from the state and events afterwards. Their
events carry `.person` (`snapshot.taken.person`, `snapshot.removed.person`, `snapshot.skipped.person`).
`zfs_snapshots_pause` writes the key `paused` {by, why, at} in the state `schedule`, which the run reads and then
takes and removes nothing; `zfs_snapshots_resume` deletes it.
## What it says, keeps and shows
25. **Events, each kind on a subject of its own** (ADR 0679 §10). `config.applied` {target (`pool`, `dataset`,
`file` or `unit`), key, before, after, read-back}, `config.refused` {key, value, reason}, `config.waiting` {key,
waits-on, since}, `snapshot.taken.person` and `.schedule` {snapshot, by}, `snapshot.removed.person` and
`.schedule` {snapshot, kind, space freed in bytes}, `snapshot.skipped.person` and `.schedule` {pool, capacity,
reason}, `run.skipped` {reason}, and today's `scrub.requested`. They go on an events stream asked for by template
in `requires` alone and created by the bus module (ADR 0595 §1, §2, §4), kept 30 days; today's module-level `emits`
move to it. No module consumes `snapshot.taken` or `scrub.requested` today (read in mesh-catalog's manifests on
main); a session waiting through `mesh_wait` on `snapshot.taken` hears `snapshot.taken.person` after.
26. **Kept data, by template in `requires`** (ADR 0679 §10; ADR 0595 §1). A state `applied`, one key per config value,
`{before, after, at, outcome}`, written by the apply and deleted by it when that value goes back to not managed,
after its last `config.applied`. A state `schedule`, the key `paused` alone (§24). A ledger `snapshots`, one
instance per ZFS snapshot the run took, operations `taken` and `removed`, the run removing the instance of one it
destroyed; its cap is the keep counts' sum times two instances per dataset. A state `findings` (§27). The apply,
the run and the event follower declare the bus account that writes them; the tools read them.
27. **The event follower's findings** (ADR 0679 §12; ADR 0564 §2; design 47 G §383 to §388). The event follower
(`zfs-events`, root) is an observer: in its state `findings` it keeps one key `pool.<pool>.<device>` per device
of the pool (and `pool.<pool>.pool` for the pool) not ONLINE, its value the state, deleted when the device is
ONLINE again or leaves the pool; it says each change on its findings stream as design 47 G §383 says, and at its
start it reads `zpool status -P` against its keys and states them (§384). The condition keeper raises and clears
the condition from those events, so a pool fault reaches the operator once and never from a ZED handler. It also
starts the apply on the events of §18. Its process declares the bus account; today it writes the journal only.
28. **Tools** (ADR 0679 §14). `zfs_config`: every owned value with its config value, what runs on the node, its state
(`not managed`, `as set`, `waiting` with on what and since, `refused` with why, `takes effect at the next load of
the kernel module`), and the files of §10. `zfs_config_apply` (§24). `zfs_snapshots_schedule`: the schedule, its
next run, what it would remove next and the ledger. `zfs_snapshots_run_now`, `zfs_snapshots_prune_now`,
`zfs_snapshots_pause` and `zfs_snapshots_resume` (§24). `zfs_module_events`: the module's stream, the last N events
by kind (named so because `zfs_events` already reads ZFS's own events). `zfs_snapshots_check`: compares the ledger
with what ZFS holds and names each entry whose ZFS snapshot is gone and each `mesh-` snapshot not in the ledger,
changing nothing. `zfs_findings`: the follower's findings. The existing read tools stay. Each is in `replaces`
where it replaces a command.
29. **Health** (ADR 0679 §11). `zfs_health` is unhealthy for a `refused` or a failed command in the state `applied`,
naming the key and why. Warnings: a wait, naming on what and since when; a `.pacnew` beside `/etc/default/zfs` or
the package's `zed.rc`; the last scheduled ZFS snapshot older than its cadence; a failed run; `autoreplace` on or a
spare in the pool while `zed` is not `on`; the pool above 80 % with `snapshots` set; scheduled ZFS snapshots kept
after `snapshots` went to `none`; a parameter awaiting a load of the kernel module; `paused` set.
30. **When the module leaves** (ADR 0679 §15; ADR 0303 §2; ADR 0269 §2). The packages stay. `zfs-import-cache`,
`zfs-mount` and `zfs.target` are never stopped or disabled, and the module says so before it leaves (ADR 0679 §15
changes ADR 0269 §10 for them). Nothing of the package's files is given back, since the module never wrote them.
`zfs.conf`, `/etc/zfs/mesh-zed.d` and the drop-in are removed, and before leaving `zfs_config` says that the next
load of the kernel module uses ZFS's defaults. The distribution's scrub and trim timers are put back as the
module's declaration found them, started and enabled again where it stopped or disabled them. Pool and dataset
properties and devices stay as the last apply set them, also on a rollback (§8). `/etc/hostid` stays, and the
module says so before it leaves (`zfs_config`): it is no resource the node-engine removes, and removing it would
change the node's hostid, so that the pool's next import could need `zpool import -f` (ADR 0679 §15).
## How it is checked
31. **Unit tests**, table-driven, one test per area, within the module's 500: no values gives no `zpool` or `zfs` write
but the due scrub; each convergence plan from parsed `zpool status` and `zfs get` output (an add, a kernel name to
its stable name, a removal, an empty list removing nothing, a log removal refused while not healthy, a `log-mirror`
change, a wait during a scrub); every refused form (a newline, quote, `$`, backtick or semicolon in each field; a
parameter or property not on its list; a `sharenfs` value; `-f`; a device with a signature or another pool's label;
a hostid of the wrong form, a label of another id or one that cannot be read, and a hostid file holding another
value than the set one, each unhealthy and healthy again once the label and the file agree or `hostid` is unset);
the call-site test of §19, refusing any other `zgenhostid` or `zdb` form and a `zgenhostid` value not validated; the
lock (a second apply waits, a run with the lock held does nothing); the apply started only by `config-changed`,
never a timer; one scheduled resource; both ARC writes read back; applying from the last config file with the bus
down; the three templates (config file, options file, `zed.rc`); pruning never removes a ZFS snapshot whose name,
property or ledger entry does not fit, nor one with a hold or clone, and removes every surplus in one run; no ZFS
snapshot taken without a ledger record; `snapshots` back to `none` removes nothing; `zfs_snapshot` refuses a `mesh-`
name; a scheduled `snapshot.taken.schedule` does not wake a person's waiter; a parameter awaiting a load is a
warning; the `.pacnew` warning; each change emits its event with before and after; one test per tool; no resource or
template of the manifest for `/etc/hostid`; the hostid converged at the apply's start after `zfs-import.target`; the
leave keeps `/etc/hostid` and says so. The module adds no integration test; §5 is the milestone's, and the main
file's live tests stand for the module whole, said in the pull request.
@@ -2,7 +2,7 @@
layer: to-be
status: in-progress
code: [mesh-catalog, mesh-controller, mesh-host]
updated: 2026-10-22
updated: 2026-11-12
decisions:
- "ADR 0369"
- "ADR 0303"
@@ -29,6 +29,12 @@ decisions:
- "ADR 0507"
- "ADR 0508"
- "ADR 0510"
- "ADR 0679"
- "ADR 0051"
- "ADR 0269"
- "ADR 0348"
- "ADR 0595"
- "ADR 0593"
---
# 42. The machines' modules, in order
@@ -80,6 +86,7 @@ In order:
| 9 | `ssh-client` | everything under `~/.ssh` (research 027/03) | a predecessor's entries winning over the mesh's; stale keys |
| 10 | scripts | the operator's own scripts, shared and per role (research 027/03) | under no version control, copied by hand |
| 11 | `kernel` | kernel, microcode, boot entries, the fallback kernel and its boot entry, and the kernel's run-time settings per machine (transparent huge pages first) | two machines without microcode; huge pages left at the distribution's `always` on a machine whose slow disks they flood (issue 746); only one machine with a fallback kernel |
| 12 | `zfs` | on a machine that holds a ZFS pool (today the home server): ZFS's packages, its kernel module's options, its event daemon's handlers, its import, mount, share and trim units, and, for the one pool its config names, that pool's properties, its cache and log devices, its datasets' properties and a schedule of ZFS snapshots, each changed only once its config value is set (ADR 0679) | ZFS installed by hand and declared by no module; no bound on its read cache on a machine that also runs its apps; cache devices named by kernel names that swap between boots; no scheduled ZFS snapshots; the pool left with no scrub schedule by a failed timer |
`systemd`, `pacman` and `docker` hold the three seats that apply resources
(ADR 0207):
@@ -131,6 +138,10 @@ before it passed; the boot-entry script in stand-in trees of both loaders), an i
keepers of two made-up nodes on a real bus, and, after the delivery, the view answering every node and every
boot menu listing the fallback kernel.
`zfs` comes after `kernel` because its kernel module is built by DKMS against the kernels `kernel` and `pacman` put
on the machine; it is placed only on a machine that holds a pool. Its section is below,
[*The zfs module*](#the-zfs-module).
**Added 2026-10-04.** Two more modules for every machine:
- `power` holds `node-power` (ADR 0211). Other modules contribute code for
its moments (after boot, before sleep, after waking, before shutdown, on mains, on battery), and it
@@ -140,6 +151,100 @@ boot menu listing the fallback kernel.
waits for a reboot. A live restart in the middle of a full upgrade took down a workstation's
logins on the day this was written.
## The zfs module
*Added 2026-11-12, ADR 0679; the operator, 2026-11-12: "you could configure the disk by id and make sure the module
handles the rest"; "the zfs module should/must own all zfs-configuration files and options"; "we may absolutely not
lose any data".*
**What it is for.** On a node that holds a ZFS pool, the zfs module owns ZFS: what was installed and set by hand and
seen by nothing becomes the module's, and the operator's choices about it are config values (ADR 0679 §1). It holds
no seat; a seat for it is a later record's. It keeps reading and acting by hand as today: the pools, the datasets, a
named ZFS snapshot, a scrub's start, pause and stop.
**The whole shape.**
- **What it owns** (ADR 0679 §1): the packages `zfs-utils` and `zfs-dkms`; `/etc/modprobe.d/zfs.conf`, placed only
while an ARC or module option is set; `/etc/hostid`; its own folder for ZFS's event daemon (ZED),
`/etc/zfs/mesh-zed.d`, with its `zed.rc` and handlers, and a drop-in for `zfs-zed`, placed only while ZED is on;
the states of ZFS's import, mount, share, volume and target units and of the distribution's scrub and trim timers;
and, for the one pool its config value `pool` names, that pool's cache and log devices, its properties and its
datasets' properties from fixed lists. The node-engine's composer refuses a second module owning one of its paths
(ADR 0593 §7, ADR 0051 §9), all but `/etc/hostid`, which is no resource: the module's apply reads it back instead
(ADR 0679 §1, §17).
- **What it never writes** (ADR 0679 §1, §2): the package's own `/etc/default/zfs` and `/etc/zfs/zed.d` with its
`zed.rc`, and what ZFS writes itself; it reads and shows them. A dataset's `sharenfs` is the seat
`node-nfs-server`'s, `sharesmb` the SMB module's; the pool's files are the operator's (ADR 0051); the weekly
upgrade and a kernel held for DKMS are the package manager's (ADR 0508).
- **An unset or empty value changes nothing** (ADR 0679 §3): every new config value is "not managed" until the
operator sets it through mesh-config, on the Approve for a trusted value (ADR 0348 §4, §8). Placing the new version
on a node runs no `zpool` or `zfs` write but the scrub its schedule already runs, and places none of its new files.
- **Who applies** (ADR 0679 §9, §17): the node-engine places the packages, files and units as the module's resources,
some only while a value holds, all but `/etc/hostid`; the module's root process `zfs-tools apply` converges the pool's
devices and properties at its start and on `config-changed`, never on a timer, and writes `/etc/hostid` with ZFS's own
writer only while `hostid` is set and the pool's label agrees; the module's one scheduled run, under the same lock,
starts the scrub and the trim when due and takes and removes the scheduled ZFS snapshots (ADR 0679 §8).
- **What it says** (ADR 0679 §10, §11, §12): every change, refusal and wait is an event, each kind on a subject of
its own, on an events stream asked for by template; the last change per value, the schedule's pause and every
scheduled ZFS snapshot are kept on the bus in its own states and ledger (ADR 0595). Its health names a refusal or a
failed command as unhealthy and a wait as a warning. Pool faults reach the operator once, from the module's event
follower's findings through the condition keeper.
- **What it never does** (ADR 0679 §7): it converges no data device, spare, special or dedup device, upgrades no
pool, destroys no dataset, rolls back, renames and clears nothing; each is an act of its own, decided separately.
- **When it leaves** (ADR 0679 §15): ZFS keeps running (the import, mount and ZFS target are never stopped), the
packages stay, its own files are removed but `/etc/hostid`, which stays and is said, and the distribution's timers
are put back as found.
- **Its prerequisites** (ADR 0679 §16): three node-engine capabilities, built first in the same milestone under issue
1979, with their readers in mesh-sdk and the manifest validator.
```mermaid
flowchart LR
operator[the operator] -->|sets a config value| config[mesh-config]
config -->|the module's config file| engine[the node-engine]
engine -->|packages, files, units| node[ZFS on the node]
engine -->|restarts on its config file| apply[zfs-tools apply, root]
apply -->|zpool add, remove, set; zfs set, inherit; zgenhostid| node
sched[the scheduled run] -->|scrub, trim, ZFS snapshots and their removal| node
follower[the event follower] -->|scrub ended, device appeared: start| apply
apply -->|config.applied, refused, waiting| stream[(events stream)]
sched -->|snapshot.taken.schedule, removed, skipped| stream
apply --> applied[(state applied)]
sched --> ledger[(ledger snapshots)]
follower -->|findings| keeper[the condition keeper]
tools[the module's tools] -->|read| applied
tools -->|read| ledger
```
**Acceptance tests** (ADR 0679, *How it is checked*), each with its level; every live test is read by a tool call:
1. *Live.* Placing the new version on the home server changes nothing: `zfs_config` shows every value "not managed",
and `zpool history` read before and after shows no command but the scheduled scrub.
2. *Live.* Setting `cache-devices` puts both cache devices in the pool by their stable names; after a reboot that
swaps the drives' kernel names, both stay ONLINE (`zfs_pool_layout`).
3. *Live.* The node-engine's apply report shows the module's run timer active before the distribution's scrub timer
is stopped, and `systemd-analyze calendar` of the generated `OnCalendar` passes with a next run within 15 minutes.
4. *Live.* With `hostid` unset, `/etc/hostid` is not written (`<node>/node-reads.stat`); `zfs_config` shows it "not
managed".
5. *Live.* With `snapshots` set, the next run's ZFS snapshot is in `zfs_snapshots` with `mesh:schedule` and in the
ledger (`zfs_snapshots_schedule`); after its keep count passes, its removal is in both and in `zfs_module_events`.
6. *Live.* A value of a refused form makes `zfs_health` unhealthy naming the key; a declared device that is not
present makes it a warning naming what it waits on.
7. *Live.* With `zed` on, `<node>/node-files.list` of `/etc/zfs/mesh-zed.d` shows its `zed.rc` and only the handlers
set, and `<node>/node-service-manager.status` shows `zfs-zed` running with the drop-in; with `zed` off, stopped.
8. *Live, on a test placement.* After the module leaves, `zfs-import-cache`, `zfs-mount` and `zfs.target` are still
running (`<node>/node-service-manager.status`) and `zfs_pools` shows the pool imported.
9. *Unit and integration.* The milestone part's §31 unit tests pass within the module's budget of 500, and its §5
integration test passes in the node-engine.
## Milestones
| milestone | what it builds | part | state |
|---|---|---|---|
| zfs-owns-zfs | the zfs module's ownership of ZFS (ADR 0679), with its three node-engine prerequisites and their readers, under issue 1979 | [42-milestones/zfs-owns-zfs.md](42-milestones/zfs-owns-zfs.md) | designed |
The modules of the tables above were built before designs were cut into milestone parts; their remaining lines move
into a part of their own at their next amendment (playbook 02, *The shape of a design*).
## Phase 2 — both workstations
In order:
@@ -2,8 +2,10 @@
layer: to-be
status: in-progress
code: [mesh-controller, mesh-catalog modules/mesh-delivery-gate, mesh-catalog modules/gitea, mesh-delivery, mesh-host, mesh-sdk, mesh-vault, mesh-contracts, mesh-tools, mesh-networking, hq 00-META/checks]
updated: 2026-11-11
updated: 2026-11-20
decisions:
- "ADR 0682"
- "ADR 0681"
- "ADR 0673"
- "ADR 0672"
- "ADR 0668"
@@ -195,6 +197,16 @@ acting parts, the kept data on the bus restored with a delivery, and the verbs a
section this file names in italics and does not hold is there, under the same name. A sentence that holds a delivered
line and G's change together stays here.
**From milestone H's delivery, a delivery starts at the merge through the mesh** (ADR 0682; the operator,
2026-11-20). One **merge call** of the seat `git`'s verb `merge-pull`, naming one or more pull requests, is a delivery's
start and its group; the gate names the merged heads one source revision per watched branch and opens its delivery
record, the indexer takes it in and names its **movers**, one pipeline runs per take-in and none in parallel, and a
want names the newest released version whose pipeline passed. The forge bridge's one message per move of a watched
branch's head is the gate's watchdog: a head no merge call delivered is an **untaken head**, said and delivered by
nothing. Every line milestone H builds is in its part, opened by the plan
[47-milestones/H-deliver-the-delivery-system.md](47-milestones/H-deliver-the-delivery-system.md) and cited as "design
47 H §n" (§734 on); where an H line and a G line differ, the H line holds and the G line says so.
This is the delivery of [to-be 10](10-delivery.md) carried out. To-be 10 says what is built: the comparison
of source and artifacts decides, and nothing here changes that. This design says who answers for one
commit's journey, in what order the steps are allowed, and where each fact of it is kept. It was rewritten on
@@ -1508,6 +1520,23 @@ way is written down before the switch (ADR 0526, which ADR 0522 §6 asked of R4g
running versions are kept outside the artifact store on two nodes, each by digest with its module, artifact, commit, Go version and the
steps that put it back, because the store's nightly collection removes a blob the controller did not record (ADR 0526 §6).
## Every delivery part wakes on its inputs alone
*ADR 0682 §11; issue 1982; the plan of milestone H, section 3.6.* A delivery part (the forge module, the forge
bridge, the gate, the indexer, mesh-config, the runner, the builder, the build modules, the assigner, the node-engine,
the grants part, the watchman, the condition keeper, the status view, the teller and the tool runner) keeps a watched
copy of each of its own states, through one shape in mesh-sdk's state package (the shape the held pull request
mesh-catalog #708 built for mesh-config, moved into mesh-sdk), and runs a pass only when an input it consumes changed,
taking only the keys that input names. It keeps one timer, set to its earliest real deadline, a bound it states; it
polls nothing, reads nothing of its own whole on a wake, and asks no call again on a timer. Which part moves onto the
shape in which release, and its cost (the shape's release in mesh-sdk rebuilds nearly every module, so H4 alone
carries it), is design 47 H §762. How it is checked: the code review of every delivery module from milestone
H1 on refuses a timer that is no stated deadline, a poll and a whole re-read; mesh-sdk ships a test helper that counts
the requests a pass makes, and each delivery module's integration test that starts it whole against the bus (the mesh's
instruction *how-work-is-done*) asserts that a pass after one changed key requests that key alone; live, milestone H4 is proven by the bus's
slow consumers and consumers behind at 0 for an hour, read with `mesh-broker.rates` (H §760) and the bus module's
consumer reads.
## Acceptance tests
What the build proves before this design is implemented (research 055's direction):
@@ -1658,12 +1687,13 @@ list:
point while the reverted manifest declares no catch-up tool), and only then are the reverted
assigner and gate wanted; a module delivered during milestone G keeps its fingerprint while they wait; no want goes
to a fingerprint older than the trunk's; the operator is asked again only for an ask raised after the restore
point. A revert whose restore point is missing is held, naming it. Proved with the real builds of the indexer, the
assigner and the gate from before milestone G, not fixtures, started by their fingerprints in the artifact store
(whole, in `mesh-host`: checker, gate, assigner, indexer, node-engine, backup holder, bus module; design 47 G §405).
point. A revert whose restore point is missing is held, naming it. Proved in two parts (the operator, 2026-11-12): each module's integration test proves its own wiring
of the undo with every other module a stand-in (the node-engine's: wants held until the restore and the catch-up,
a missing restore point held, naming it), and the whole undo end to end belongs to the test lab, which is paused until its
performance is fixed; no check starts real builds.
37. **Nothing is delivered ahead.** Research 085's milestone is delivered with no part delivered ahead of it, read
from its delivery record (ADR 0656, How it is checked).
38. **A newer indexer is reached.** A merged revision naming a newer indexer gives, from the running indexer, a catalog
38. **A newer indexer is reached.** *(Retires at milestone H, design 47 H §764.)* A merged revision naming a newer indexer gives, from the running indexer, a catalog
graph revision that is the previous one with only the indexer's entry replaced; no other want moves; the new
indexer is wanted, granted, started, and takes the revision in.
39. **Revisions are kept, and stores say their fill.** A revision pinned by two records stays until both free it, one
@@ -1705,7 +1735,7 @@ Each change ADR 0656 makes in an earlier record, and its test:
are read by the indexer's candidate pass and by no running part (whole).
48. **A process reports its handed build** (ADR 0639 §7). A part started while its node's want differs from what runs
reports the build it was started with, and the node-engine seat's verb `process-builds` reads it (whole, node-engine).
49. **The forge bridge reads a group from the gate's verb** (ADR 0633 §4, §5). The forge bridge sets the group on each
49. **The forge bridge reads a group from the gate's verb** *(Retires at milestone H, design 47 H §764.)* (ADR 0633 §4, §5). The forge bridge sets the group on each
merged message and publishes a group's end again from the seat `mesh-delivery`'s verb `groups`, and its account
holds no read of the gate's `merges` state, so a read of it is refused (whole, forge bridge).
@@ -1727,11 +1757,9 @@ What milestone G's prepare found, and its test:
(whole, gate, checker and forge module).
53. **What is owed is said, answered and kept.** An `owed` said while the forge bridge is stopped is performed once after
its restart; the bridge stopped between an act and its `owed.ended` repeats it and the forge holds it once; an
undecodable act is said `undecodable`; an act unanswered 15 minutes is listed by `stalled`; the switch with a merge
handed and not yet merged opens no `forge-made` record; a merge made at the forge opens one, said as `transition`
with why `forge-made`, and a later merge in its repository follows it; the checker's `mesh/check` is performed by
the bridge from the checker's `owed`, and a checker status the forge refuses is recorded in the checker's own
state and listed in its stalled read (whole, gate, checker and forge bridge).
undecodable act is said `undecodable`; an act unanswered 15 minutes is listed by `stalled` (whole, gate and forge bridge). The rows of a `forge-made` record
and of the checker's `mesh/check` went: no record is marked `forge-made` (design 47 G §151), a head moved outside
the mesh is an untaken head (design 47 H §740), and the checker goes (corrected in place by design 47 H §763).
54. **One reader of the seat list per part, and one view machinery.** Every part that reads the seat list has the two
tools of ADR 0636 §7 from the runtime and no wiring of its own; every part that takes a first view answers its
held and awaited revision in `<module>_first_views`. With the forge on its old build, serving no verb of the seat
@@ -1864,9 +1892,9 @@ No module ends the milestone with more tests than it starts with, counted per ca
The failure paths:
81. **A group that never completes** raises `take-in-waits` at 30 minutes, and none of its members is delivered (whole,
81. **A group that never completes** *(Retires at milestone H, design 47 H §764.)* raises `take-in-waits` at 30 minutes, and none of its members is delivered (whole,
indexer and watchman).
82. **An indexer whose manifest its validator refuses** leaves its revision pending, holds only its own watched branch,
82. **An indexer whose manifest its validator refuses** *(Retires at milestone H, design 47 H §764.)* leaves its revision pending, holds only its own watched branch,
raises `take-in-waits` at 60 minutes, a later merge on that branch waits behind it and is not taken in past it, and
a revert taken in moves the branch on (whole, indexer).
83. **A declined registration change, and an unprotected branch,** each write nothing: the first after its Decline, the
@@ -1952,13 +1980,13 @@ ADR 0667's checks, of milestone G itself:
package rebuilds it, started by the runner after its `outdated` ask, one that leaves its digest as it was rebuilds nothing, and a change of the Go build module's
own code rebuilds no module; a `beta` build's entries compare by digest (whole, indexer, builder and runner,
mesh-delivery).
105. **One query finds what is behind** (design 47 G §375). With the runner stopped while mesh-sdk `0.1.16` is
105. **One query finds what is behind** *(Retires at milestone H, design 47 H §764.)* (design 47 G §375). With the runner stopped while mesh-sdk `0.1.16` is
released, `outdated` names the module's kind-1 edge at `0.1.15` against `0.1.16`, and at its restart the runner
starts that module's pipeline once, keyed by mesh-sdk's source revision; `runner_catch_up` does it by hand and
writes the hand-act log
(whole, indexer and runner, mesh-delivery). After the first fill (§377), a mesh running its newest builds is
answered with nothing behind.
106. **A delivery is waited for mesh-wide** (design 47 G §376, §379, §380). A module ordered after a provider's
106. **A delivery is waited for mesh-wide** *(Retires at milestone H, design 47 H §764.)* (design 47 G §376, §379, §380). A module ordered after a provider's
new version is wanted only once `version-delivered` says every present machine placing the provider runs it; with
one machine away the module's status reads "waiting for delivery of" the provider, naming the machine, and it
catches up when that machine is back; with every placing machine away the provider reads "waiting for <machine>
@@ -1971,9 +1999,85 @@ ADR 0667's checks, of milestone G itself:
`condition-raised` (whole, condition keeper and a fixture observer, mesh-catalog and mesh-sdk). Live: after G's
delivery, a node-engine restarted with the full seat list clears its `seat-list-unread`, read with
`mesh-conditions.conditions`.
108. **One composition run per candidate and machine** (design 47 G §718 to §723, §727 to §733). Two composition
steps of one candidate started at once make one key, one request and one run ask; three steps of one revision on
two machines start two runs, each step reading both verdicts. A machine whose verdict blames one module fails that
module's composition step alone and says it as a warning in the others; a verdict with no `blamed` is judged as
today, naming no culprits. A run with no `step-ended` within its bound ends `could not run` with its readers; steps
asked again together start one run per machine that did not pass and move every former reader, a reopened
pipeline saying `pipeline-ended` again; a run that keeps saying its progress past 30 minutes is not ended, and a
taken ask silent for 30 minutes ends `could not run`. Both drop tools end
the readers, and a reader-only account calling one is refused (whole, assigner and the node-engine's composer,
mesh-delivery and `mesh-host`). Live: in the first publish after G's delivery, the composition run asks of a
revision number at most its machines, read with `assigner_compositions` and `assigner_inputs`.
109. **One test run per level and tested packages** (design 47 G §724 to §733). A module whose program and tools
bundle test one directory runs its unit and integration tests once per level, both artifacts' pipeline steps
ending with that result and naming it in `shared`, a failing test failing once, and `pipeline-ended` counting the
module's tests once. A rerun that passes moves both artifacts' steps and the pipeline ends again; a runner
restarted during a run takes it up again; a replaced reader leaves the ask to the others; at the cap a step ends
`could not run` naming the fill; a second revision with the same digests runs a failed test again; a test run queued past five minutes with a
holder present is not failed (design 47 G A-466y) (whole, runner
and Go build module, mesh-delivery and mesh-catalog). Live: each module's test steps run once per level, read with
`runner_test_runs`. A reader no part ends raises `pipeline-stands` within five minutes of its last sign of life
(whole, watchman; design 47 G §732).
110. **One merge call is delivered end to end with no hand act** (design 47 H §734 to §738, §743, §746, §750, §751,
§771). This is the live proof of the chain (the plan's section 5, step 7), read with the tools and quoted with its
times, not one test: with `pipelines-at-once` at 1 and one placing machine away, a merge call naming one pull
request that changes one module says one `merge-called`; the gate writes one source revision and opens one record;
the indexer says one `take-in.taken` naming that module alone; the runner runs one pipeline; once it passes and the
version is released, the module is wanted and runs on every present placing machine, the record ends naming the
machine away, and that machine applies its want when back. Each part's half is a whole test in its own repository
(H-A-17): the forge module's (§734 to §736, §766), the gate's (§737, §738), the indexer's (§743), the runner's
(§746), the assigner's (§750, §751) and the node-engine's (§771).
111. **A head moved outside the mesh delivers nothing and is said** (design 47 H §739 to §742, §766). A merge made in
the forge's screen gives one `head-moved`, no source revision and no pipeline; `head-untaken` is raised within
`untaken-bound`, naming the repository, branch and head; a later merge call in that repository clears it;
`gate_head_take` delivers such a head by hand, written in the hand-act log; and a forge module stopped between its
last merge and the write of that member ends as an untaken head recovered so (whole, forge bridge and gate in
mesh-delivery and mesh-catalog; the stop case in the forge module's whole test).
112. **One take-in is one pipeline, and pipelines run one at a time** (design 47 H §743, §746 to §748). Split per
module (H-A-17): the forge module's whole test that a call naming a mesh-sdk change and an importer merges both or,
with one refused, neither; the indexer's that its `source-moved` names mesh-sdk, that importer and mesh-sdk's other
importers as movers; the runner's that they are one pipeline in which every importer builds after mesh-sdk's
`package-published`, that a second take-in waits and is placed on the first's end, on a cancel and on a set-aside,
that a pipeline waiting on its `approval` step does not count and is placed first when answered, that a newer
take-in moving the same module supersedes it in the waiting pipeline, that `pipelines-stalled` is raised when
pipelines wait and none runs, and that a restart starts no pipeline of its own.
113. **A want is the newest released version whose pipeline passed, written tier by tier** (design 47 H §750, §751,
§771, §772). The assigner's whole test: a module released with a passed pipeline is wanted on every placing
machine whatever build an acting part runs; a version whose pipeline failed is not wanted; an older end heard after
a newer one writes nothing; a placement `build` names the want's version; a consumer's want is written only after its
provider's tier runs, and a tier that does not run within `tier-bound` raises `tier-late`; a node-engine without the
want-by-version capability is said held. The node-engine's whole test: the bus module's and the backup holder's
changed wants apply first, then by `rank`, its own last.
114. **A head whose `required` step failed is refused** (design 47 H §735). The forge module's whole test: a runner's
`step-ended` naming a failed `required` step at a head's fingerprint makes `merge-pull` refuse that head, naming the
step; a later passed run asked again by the operator lets it merge.
115. **A member refused mid-call is said and raised** (design 47 H §767). The forge module's whole test against a
fixture forge that refuses the second merge: one `merge-called` with the first member and `refused`, `merge-partial`
raised by the call, cleared by a later call landing the refused member and by `forge_partial_clear`.
116. **A take-in held on a full store** (design 47 H §744). The indexer's whole test: with the catalog store full a
`source-moved` is held unacknowledged, said once as `take-in.pending`, not redelivered on a timer, and taken in on
`room`; another branch's take-in goes on meanwhile; `indexer_take_in_skip` ends it in the hand-act log.
117. **`validate` refuses a manifest problem and a cycle** (design 47 H §745). The assigner's and the runner's whole
tests: a take-in whose manifest names an unknown field fails `validate` with `manifest-refused` naming it and asks
no composition; one that makes a cycle fails it with `cycle` naming the cycle; the indexer's manifest runs no
validator.
118. **Every account calls every verb; a module publishes only what it declares** (design 47 H §752). The grants
part's whole test: a module calls a verb its manifest does not invoke and is answered, publishes an event its
manifest does not declare and is refused, and an enrolling node's account is held to its own grant.
119. **The builder's lines** (design 47 H §753 to §758). The Go build module's whole test takes the delivery queue
first; the builder's whole tests: a done, unreserved fingerprint asked by a build step ends carried with a version,
a failed 0.1.19 built again is 0.1.19, a catalog entry heard with no step ask builds nothing, `build.ended` names its
version; the runner's: a step with nothing to run ends `nothing to run` and its pipeline passes; the indexer's: a
registration with every step `bypass` is refused, naming them.
## What retires
- From milestone H's delivery: everything design 47 H §764 lists (the per-pull-request paths of the gate and the forge
bridge, the catch-up by comparison, the runner's sweep, the start-time `outdated`, the checker, the groups by branch
name, the want holds A-478 ends), and the stale state H §765 drops once.
- The "release branches" and the controller's check of them (ADR 0358, superseded by ADR 0401).
- The toolchain image and its module (ADR 0405).
- The window cutter, the merge catch-up timer, the rollout ticker, mesh-delivery's tick, reconcile and
@@ -2067,6 +2171,7 @@ release reports the controller's code lines against research 063's baseline (acc
| L7 | History and records leave the controller (ADR 0571): the builder keeps its build log, one entry at a build's start and one at its end, from which build history and durations are read and the module mesh-catalog asks the builds it missed; the artifact sweep is the seat `mesh-artifact-sweep`, held by artifact-store-tools beside the artifact store, its keep set from the store's own listing, the wants and the build log, sweeping at each build's end from the lease write and recording each deletion in the hand-act log; disk readings are disk-load's own state on every node; who holds which seat is the state `seat-holders` of the seat `mesh-placement` (now `mesh-module-assigner`), and tools are found by the tool runners' announcements; what a node runs is its want and its have; the grants part writes `grants.<module>.<fingerprint>` and keeps memberships in its own state; root-free is a probe of the self-check; no manifest but the controller's reads, invokes or consumes `mesh-controller`, but a named list kept to the lease write, so the lease write's check passes (ADR 0189, ADR 0547 §11, ADR 0549 §6) | — | mesh-sdk, mesh-controller (its pin only), mesh-delivery (builder, indexer, assigner, grants part, view), mesh-catalog (artifact-store-tools, disk-load, the backup seat's holder, mounts, nfs-server, minio, mesh-watcher, the messenger, the self-check, the module mesh-catalog, docker), mesh-tools (the tool runner) | 1955 |
| B0 | The bootstrap delivery: every check, a lone pull request's as a group of one and a verdict carried after a trunk move included, is judged by a checking program built from the change's own heads in the build seat's sandbox, which also makes the heads' one seat list that the check hands the manifest validator and the composer; it brings no seat definition and no manifest field, so the running checker checks it (ADR 0644; *The bootstrap delivery, and the one milestone after it*) | 26 needs it | mesh-sdk (`go/delivery`: the seat `node-build-go`'s ask `run` and the checker's record of which checking program judged; `go/composer`: the request's seat list), mesh-catalog (mesh-build-go: the run step, the refused answer, the kept programs' tools and sweep), mesh-delivery (checker: the checking program and its command), hq (this design, the glossary) | 1921 |
| G | Two graphs and one revision view: the catalog graph and the assignment graph kept per revision, a change delivered as its graph difference, the acting parts' rules on their seats as bounded waits that hold their modules when the new version fails, the check on the change's own acting parts, the revision view and each process's own build, the gate's delivery record, and the trace's links (ADR 0656); no part reads a pull request's description (ADR 0659); every delivery part reaches the forge through the seat `git` and names no other module; nothing holds an approved merge for another check; and, one milestone with them, research 086's pipelines: a change of any module goes from a commit on a watched branch to the machines through its module's pipeline, its policy in its registration, ordered by edges between artifacts, with no Approve per merge and no hand act, the checker gone (ADR 0666, ADR 0667). Test counts at its start (G's prepare, 2026-11-09): mesh-delivery 665 unit and 68 integration, the node-engine (`mesh-host`) 1,742 unit; each other repository's and each catalog module's from the last check's verdict, read in the joint prepare | 26 to 62, 63 to 106 | mesh-sdk (the runtime: the fingerprint, the view, the definition reader, the seat list's one wiring), mesh-contracts and the domains' contracts modules (`acts`, the new verbs and events, the seat `mesh-grants`, the seat `git`'s verbs), mesh-delivery (indexer, assigner, checker until its removal, builder, grants part, gate's view, forge bridge, watchman, the new pipeline runner `mesh-delivery-pipeline`, `contracts` and `sdk` moved under `modules/`), mesh-catalog (the gate, the build modules, the forge module, mesh-issues, mesh-knowledge, the `node-backup` holder, the router, nats: a module's kept data on the bus as a backed-up item and the object store beside each state), mesh-sdk (also its small object store package, for values of any size), the node-engine (`mesh-host`), hq | 1966, 1961 (retargeted to this row's shape), 1660, 1972, 1721, 1783, 1785, 1794, 1791, 1373, 595; 1962 goes back with 1958, whose assignment entry it needs (ADR 0641 §3) |
| H | The build-and-delivery system delivers itself by its one model, in six releases (H0 to H5, the plan's section 6): one merge call of the seat `git`'s `merge-pull` naming one or more pull requests is a delivery's start and its group; the gate names the merged heads one source revision and opens its record; the indexer takes it in (a commit, the fingerprints of its repositories' modules, one catalog revision) and names the movers; one pipeline per take-in, none in parallel (`pipelines-at-once`, default 1); a want is the newest released version whose pipeline passed; the forge's event is the watchdog (`head-untaken`); every delivery part wakes on its inputs alone and reads no other part's state; the per-pull-request paths, the catch-up by comparison, the sweep and the checker go; one clean state placed by hand once, after which every release is delivered by its own pipeline (ADR 0682, ADR 0681, ADR 0666, ADR 0667; design 47 H §734 to §774) | 110 to 119 | mesh-delivery, mesh-catalog, `mesh-host`, mesh-tools, mesh-sdk, mesh-contracts, hq | opened by each release's prepare |
An issue is in one row only (ADR 0493 §2): where a row named an issue another row names too, the last row keeps it and the
earlier row says so in words (the operator, 2026-10-26). Milestone M1 makes each row a record of the issue tracker
@@ -84,9 +84,10 @@ check and deliver milestone G itself (ADR 0667 §2); each of them says so in a l
what moved); the verb `registrations` answers every registration, or one with its history. The indexer derives the
modules it keeps from them, and the forge bridge its watched branches, each by a first view of `registrations` and
then that event, never by reading the ledger (ADR 0666 §3, ADR 0596).
- §5 **An unprotected branch is refused.** `register` and `watch` read a branch's protection through the seat `git`'s read
verb `branch` (its head, and whether a rule refuses a direct push and admits only merges), and refuse a watched branch
the forge does not protect, naming it (ADR 0666 §3).
- §5 **An unprotected branch is not refused at registration** (corrected in place by design 47 H §763). `register`
and `watch` read no branch's protection and refuse no watched branch for it: the operator approved removing the
check on 2026-11-14 (G-23, *Met during G's start*), and ADR 0682 §13 ends ADR 0666 §3's refusal, `merge-pull`'s
protection judgement and §17's `branch-unprotected` (design 47 H §735, §739).
- §6 **The foundation parts are the manifest validator's list.** The manifest validator's list (ADR 0619 §3) holds
exactly the foundation parts, ADR 0619 §1's, the runner, which joins them (ADR 0666 §4), and the forge and image
registry modules (§584); the checker leaves the
@@ -317,8 +318,10 @@ check and deliver milestone G itself (ADR 0667 §2); each of them says so in a l
removed with the checker's buckets and bus account, after the first pipeline after G's delivery has delivered a change
end to end and on the operator's word (ADR 0667 §12; *How milestone G itself is checked and delivered*); the forge bridge hears the landed commit as it hears every commit of a watched
branch.
- §40 **The operator-channel hides no ask.** It keeps design 46's three open asks per asker, never holds the newest back,
and replaces an open ask by the same asker's ask with the same `about` (ADR 0666 §12; design 46 §6).
- §40 **The operator-channel hides no ask.** It keeps no count of open asks per asker and holds none back: every ask
is offered when it is raised (A-424, the operator, 2026-11-15 about 15:50 CET), and it replaces an open ask by the
same asker's ask with the same `about` (ADR 0682 §14, which ends ADR 0666 §12's three open asks per asker; design 46 §6;
corrected in place by design 47 H §763).
- §41 **How it is checked.** Whole (forge module, forge bridge): a session's `merge-pull` at its head merges with no run yet,
and with a passed one, and asks no Approve; with the runner stopped a head merges; a head at whose fingerprint any
run failed a `required` step, a head that moved and a branch whose protection was removed since its last move are
@@ -242,8 +242,9 @@ each the design's choice with its reason, §468 to §479 those of the runner's,
whole (forge module), a head that passed, then another commit at its fingerprint failed a `required` step, is
refused; its `seen` key goes when the pull request closes.
- §476 **`take-in.taken`'s body and its type.** (§493) The indexer's own `take-in.taken` carries, beside what it carries on
main, `branch` (the watched branch), `source` (the source revision taken in) and `entries`, one `{module, commit,
fingerprint}` per module of that revision. Its body is defined in the seat `mesh-catalog`'s definition, in its
main, `branch` (the watched branch), `source` (the source revision taken in) and `entries`, one
`{module, commit, fingerprint, repository}` per mover of that take-in (design 47 H §743; corrected in place by H §763, where this line
said one entry per module of the revision). Its body is defined in the seat `mesh-catalog`'s definition, in its
section `bodies` (§439, §454), so the generated contract carries the type the indexer writes and the runner reads,
and neither imports the other (§333). Why: a body said on a module's own stream and read by others is a `bodies`
entry (§439), never a client's hand-written type (develop question Q-RN4). How it is checked: unit (seat generator),
@@ -384,12 +384,15 @@ that round are written into the lines they name, here. Questions that an earlier
- §535 **A missing build seat and a seat with no holder, each read where it shows.** The runner reads that no build
seat serves an artifact's language from the catalog half of its revision view: no entry whose `acts`, the acting
rules of the seats it claims, hold a rule `build` with `on` naming that language (§323); the pipeline then ends
failed at once, naming the language and the missing build seat. It reads that a seat has no holder from the step
itself: an ask on that seat's work queue whose `step-started` is not heard within five minutes ends the pipeline
failed, naming the seat (§32). It reads neither from the seat list, which answers definitions alone (§527), nor
from any holding. Why: §32 already ends a pipeline whose step nothing starts, and the catalog half is the runner's
one view (develop question Q-RN7). How it is checked: whole (runner), a fixture language with no build seat ends at
once, naming it; a seat whose holder is stopped ends within five minutes, naming the seat.
failed at once, naming the language and the missing build seat. *Amended by A-466y and A-466z (2026-11-17):* it reads that
a seat has no holder only when the seat `mesh-module-assigner`'s view `seat-holders` names none for it (G-21 §717's
follower; never the seat list, which answers definitions alone, §527), and a seat with none ends the pipeline failed
at once, naming it; an ask waiting for an existing holder is timed by §86's `build-capacity-waits` and A-466s's
`run-untaken-bound` (G-24 §720, §725), never by five minutes from the ask. Why: §32 already ends a pipeline whose
step nothing starts, and the catalog half is the runner's one view (develop question Q-RN7); a queued step ended
failed for "no holder" while its holder is present would say what is not true (principle 3). How it is checked:
whole (runner), a fixture language with no build seat ends at once, naming it; a seat the seat-holders view names
no holder for ends at once, naming the seat; a step queued past five minutes with a holder present is not failed.
- §539 **The runner's tools are named `runner_`.** The runner's module, `mesh-delivery-pipeline`, names its tools with
the prefix `runner_`, so the design's `runner_catch_up`, `runner_waits`, `runner_release` and `runner_health`
stand, and its first-view tool is `runner_first_views`; `<module>_first_views` (§205) carries the prefix the
@@ -327,7 +327,7 @@ for several build maps is answered once, and the maps' names for it are given in
- §636 **The private network module's name is its own manifest's.** (§428) `overlay.Name` stays the `module` the private network package's (`overlay`)
computed manifest names itself; mesh-networking removes the fixed `mesh-provisioner` alone, read from the seat
list's holder of `mesh-provisioner`. [the node-engine's map, RQ-11.] How it is checked: the code review.
- §637 **Test 36 reads the builds of before G through the registry seat.** (§405, §555, §610) Test 36's run, in the
- §637 **Withdrawn (the operator, 2026-11-12; A-320).** **Test 36 reads the builds of before G through the registry seat.** (§405, §555, §610) Test 36's run, in the
check the running checker makes of G (ADR 0667 §2), fetches the builds of before G and the recovery module by their
fingerprints through the seat `oci-artifact-registry`, read-only, under the checker's account, its manifest naming
the fetch in `invokes`, granted by §610's default. [the node-engine's map, RQ-12.] How it is checked: test 36 runs in that check.
@@ -378,12 +378,21 @@ for several build maps is answered once, and the maps' names for it are given in
- §646 **The runner's bodies name `fingerprint`.** (§585) The runner's `step-ended`, pipeline and wait bodies name the
build-input fingerprint `fingerprint`, not `fp`, as §585 reads it. [mesh-delivery DQ-2.] How it is checked: unit
(runner's contract).
- §647 **The runner times an ask from `ask-taken`.** (§535, §602) §535's five minutes run from the ask until the build
seat holder's `ask-taken` (§602), which the runner consumes; `step-started` is the runner's own. [mesh-delivery
DQ-3.] How it is checked: whole (runner), an ask no holder takes ends its pipeline after the setting.
- §648 **A `take-in.taken` entry carries the pull request.** (§476, §542) An entry is `{module, commit, fingerprint,
repository, pull}`, the last two from a `merged` message and absent for a `pushed` one. [mesh-delivery DQ-5.] How it
is checked: unit (indexer's contract).
- §647 **The runner times an ask from `ask-taken`.** (§535, §602; A-466y) The runner consumes the build seat holder's
`ask-taken` (§602); `step-started` is the runner's own. *Amended by A-466y and A-466z (2026-11-17):* §535's five
minutes from the ask until `ask-taken` go. A seat for which the seat `mesh-module-assigner`'s view `seat-holders`
names no holder ends the pipeline failed at once, naming it, judged only once that view's first view is read, never
from the not-ready picture `FollowSeat` answers before it (principle 3). The runner's manifest gains the `consumes`
entry `seat:mesh-module-assigner.views.seat-holders` (on main it has none: its `invokes` names only
`seat:mesh-module-assigner.assignments`); an
ask waiting for an existing holder is timed by §86's `build-capacity-waits` and by A-466s's `run-untaken-bound`
(G-24 §720, §725), and from its `ask-taken` by its step's bound (A-466p). [mesh-delivery DQ-3.] How it is checked:
whole (runner), a seat with no holder ends the pipeline at once, naming it; an ask a present holder has not taken
past five minutes is not failed (test 109).
- §648 **A `take-in.taken` entry names its repository, never a pull request.** (§476) An entry is `{module, commit,
fingerprint, repository}`, the repository from the gate's `source-moved` (design 47 H §743); the field `pull` goes,
since nothing reads a pull request after the merge call (ADR 0682 §1; corrected in place by H §763). [mesh-delivery
DQ-5.] How it is checked: unit (indexer's contract).
- §649 **`ParseStepKey` answers the asker.** (§484) `buildstep.ParseStepKey(key)` answers `(asker, node, id, err)`,
`asker` empty for main's form. [mesh-delivery DQ-8.] How it is checked: unit, both forms.
- §650 **The `mesh-builds` client's name.** (§586) It is `contracts/go/clients/meshbuildsclient`, with `Reserved`.
@@ -400,9 +409,8 @@ for several build maps is answered once, and the maps' names for it are given in
- §654 **The readers of the forge module's old events and tools move to the seat `git`.** (§310, §311, §313, §431;
ADR 0659 §1) [mesh-catalog Q-F1.]
- **mesh-config** consumes `git`'s `pull-merged` and `pull-closed` in place of `gitea.pull.merged`,
`gitea.pull.closed` and `gitea.forge.pull-request.closed`, and invokes `seat:git.pull` in place of
`gitea.gitea_get_pull_request`; **the records module** consumes `git.pull-merged`.
- **mesh-config** consumes no pull request event and invokes no `seat:git.pull` (ADR 0681 §1, which replaces this
bullet's first form; corrected in place by design 47 H §763); **the records module** consumes `git.pull-merged`.
- **The order.** Main's forge module says its own `pull.merged`, not the seat's events, so each consumer of
`git.pull-merged` or `pull-closed` is ordered after the forge module's version that says them, by the edge of kind
6 its `consumes` gives (§558); its durable consumer is made from the stream's first message, so no merge said
@@ -3,7 +3,7 @@ layer: to-be
status: in-progress
design: 47
milestone: G
updated: 2026-11-11
updated: 2026-11-17
decisions:
- "ADR 0667"
- "ADR 0666"
@@ -149,7 +149,7 @@ One file of milestone G's part of [design 47](../47-delivery-from-commit-to-deli
| `pipeline-started`, `pipeline-ended` | a pipeline's start, and its end with every step's result, its test counts, the source revision and `widens` |
| `group-ended` | a group's one pipeline's end, on which alone its wants are written |
| `run-started` | a run on request's start, with its members at their commits |
| `step-started`, `step-ended` | each step's start and end: the step, its status in the policy, its outcome, its build-input fingerprint, its test counts, for a carried result what it was carried from, and for a rerun that it is one and the caller the runtime proved; a bypassed step too |
| `step-started`, `step-ended` | each step's start and end: the step, its status in the policy, its outcome, its build-input fingerprint, its test counts, for a carried result what it was carried from, and for a rerun that it is one and the caller the runtime proved, for a step that read a test run or a composition run another step asked its `shared` (G-24 §729); a bypassed step too |
| `wait-held`, `wait-ended` | a step's wait: on a person (approval, code review), on a build node, on the revision view |
- §74 **What a session hears after its merge.** Between its `merge-pull` and the delivery, a session waits with `mesh_wait`
@@ -195,14 +195,14 @@ four lines a module's tools answer; every read tool of a store also answers its
| Part (seat) | Read everything it holds | Do by hand what it does itself | Recover without help |
|---|---|---|---|
| the runner (`mesh-pipeline-runner`) | `show` (one pipeline whole, its steps, step log and outputs), `list` (the pipelines of a module, a branch or a commit), `stands` (what stands still, since when), `why-carried` (where a step's result was carried from), `kept` (the kept results by digest) | `start` (a delivering pipeline for a watched branch's head), `run` (the run on request), `rerun` (one step again) | `accept` (a failed `optional` step, with why), `cancel` (a pipeline, dropping its asks), `ask-again` (a declined `approval`) |
| the runner (`mesh-pipeline-runner`) | `show` (one pipeline whole, its steps, step log and outputs), `list` (the pipelines of a module, a branch or a commit), `stands` (what stands still, since when), `why-carried` (where a step's result was carried from), `kept` (the kept results by digest), `runner_test_runs` (each test run, G-24 §728) | `start` (a delivering pipeline for a watched branch's head), `run` (the run on request), `rerun` (one step again) | `accept` (a failed `optional` step, with why), `cancel` (a pipeline, dropping its asks), `ask-again` (a declined `approval`), `runner_test_runs_drop` |
| the indexer (`mesh-catalog`) | `registrations` (with each one's history); `indexer_edges` (an artifact's edges per watched branch), `indexer_order` (the order of a change, its cycles named), `indexer_catalog_difference` (two revisions); `indexer_pending` (a group with its missing members) | `register`, `policy`, `watch`, `unwatch` (each on the operator's Approve) | `indexer_seed_again` (the first registrations' ask raised again), `indexer_take_in_pending` (a group taken in as gathered), `indexer_drop_pending` (dropped) |
| the gate (`mesh-delivery`) | `source` with a branch (`gate_source`: every branch's source revision) | — | `gate_source_again` (say `source-moved` again for a branch) |
| the forge module (`git`) | `git_failed_steps` (the failed `required` steps it holds, by module and fingerprint, with the run that failed each) | — | `git_failed_steps_drop` (drop one, with why) |
| the grants part (`mesh-grants`) | `grants_callers` (the callers each verb admits, read from the seat definitions) | — | `grants_why_refused` (for an account and a verb, the grant it lacks and the definition's line that leaves it out) |
| the build seats | `steps` (the steps detected for an artifact) | `steps` with `again` (detect again) | `drop` (ADR 0664 §4) |
| the builder (`mesh-builds`) | `builder_reserved` (each module's reserved version, §369); the released versions are the catalog's `versions` | `builder_publish_again` (publish the missing artifacts under the reserved version) | — |
| the assigner (`mesh-wants`) | `assigner_why_not` (why a module is not on a machine yet: the pipeline it waits for, its hold, the placement, the node's last `running`) | — | `assigner_release` |
| the assigner (`mesh-wants`) | `assigner_why_not` (why a module is not on a machine yet: the pipeline it waits for, its hold, the placement, the node's last `running`), `assigner_compositions` (each composition run, G-24 §728) | — | `assigner_release`, `assigner_compositions_drop` |
| the watchman | `watchman_views` (how far behind each part's view is, from each part's `view-waits` and first-view tools) | — | each part's `<module>_first_view_again` |
| the operator-channel | `asks` (with each asker's asks held back) | — | `ask-again` (offer a held-back ask now) |
| every module that imports mesh-sdk's small object store package | `<module>_state_objects`, `<module>_sent_objects` | — | `<module>_state_objects_drop`, `<module>_sent_objects_drop` |
@@ -230,6 +230,8 @@ and an estimated 2 mesh-sdk publishes a day, each rebuilding about 120 artifacts
| the builder | `reserved`: one key per module and `MAJOR.MINOR` (§369) | old `state` section | until its `version-released`, a release of another `MAJOR.MINOR` of the module, or `builder_reserved_drop` | a few KiB; at the cap the builder reserves nothing and says why |
| the assigner | `written`: the last source revision and end count per module and watched branch (§352) | old `state` section | until the branch is unwatched | a few KiB |
| the indexer and the assigner | `inputs`: a `run` ask's input by write time and sha256 (§354) | old `state` section | until the ask's `step-ended`, at most a day | 64 MiB; an estimated 300 asks a day of under 100 KiB each is under 30 MiB; at the cap the asker refuses the ask loudly, naming the store |
| the assigner | `composition-runs`: one key per candidate and machine, its program, input, ask, readers and verdict (G-24 §719) | old `state` section, `max-mib` the setting `composition-runs-cap-mib` | the setting `composition-runs-kept` (default 24 hours) after its end; deleted by the assigner (§719) | default 16 MiB; an estimated 30 candidates a day on four machines, 120 keys of at most 8 KiB, is under 1 MiB a day |
| the runner | `test-runs`: one key per candidate, level and tested packages, its ask, readers, outcome and counts (G-24 §725) | old `state` section, `max-mib` the setting `test-runs-cap-mib` | the setting `test-runs-kept` (default 7 days) after its end, deleted by the runner in the step log's order with its output object in `test-runs-objects` (§330) | default 16 MiB; an estimated 1,000 test runs a day of about 1 KiB is about 7 MiB at 7 days |
| the runner and the assigner | `findings` (§355), read by their own read tools alone; the keeper hears the findings as events (§383) | old `state` section | an entry deleted when its finding clears | a few KiB |
| every observer (§387) | the stream `<module>-findings`: `finding-written`, `finding-cleared`, `findings-stated` (§383) | old `streams` section for a foundation part, the module's `streams` otherwise | 7 days, its oldest dropped when full; the next statement covers a lost one (§384) | 16 MiB; an estimate of a few hundred findings a day of about 1 KiB is under 2 MiB a week |
| the condition keeper | `findings-views`: one key per observer and node, its last stated set, pending keys and open asks (§388) | the form of its `conditions` | deleted when the module leaves the catalog or the node (§365) | under 1 MiB; about 30 observers on four machines |
@@ -275,3 +275,416 @@ names the principle that settles it, and is cited as "design 47 G A-n".
- **A-70** (§572, A-45; the rule that a process answers no call) The builder's tools bundle serves `reserved` and
`builder_versions`, following the catalog half's view itself as other bundles follow views; the builder's process
serves no call.
- **A-73** (§588, §369; principle 7) To publish again, the builder takes each artifact's kind and package name from the
catalog entry of the reserved commit, and sends the registry seat's `publish` with the digest and no parts: the
holder takes the bytes from the artifact store, addressed by digest (A-50). "Not stored" is the holder's refusal;
the entry then ends failed, said with its reason.
- **A-74** (§700; principle 1, no module names another) The indexer reads the router's `asks` through the seat
`operator-channel`: its manifest `uses` that seat, and the bucket is formed from the seat's holder on the seat list
and the contract's `StateAsks`, never a module's name in code; the teller's and the node-engine's `messenger_asks`
constant goes the same way in their own change.
- **A-75** (§654, §610; principle 7, and who may do what is no question) mesh-issues shows the pipeline rows where it
already shows a delivery: its `DeliveryLine` gains `pipelines`, one row per module with its steps, `no run` where the
runner's list answers none. A runner verb's old callers list does not refuse a module: from G no verb names its
callers (§610), so the class's default holds.
- **A-76** (§588, §568, A-73; principle 7) A reservation keeps the fingerprint of the catalog entry it was made from
(`versions.Source` gains it), so publish again reads that entry; the registry seat for an artifact is found from its
package ecosystem as the builder's seat hearing already maps it. A transport fault's class (`no responders`, `name
lookup`, `connection`, `deadline`) is the one the existing retake reads from the call's error (ADR 0664, ADR 0668).
- **A-77** (§373; principles 1 and 7) A wait's bound is a bound key with its own time to live in the waiting part's own
state, as the condition keeper times its two hours (COND7): its expiry is heard as the bus's event and ends the wait
then, failing the step naming the member; no timer in the process and no looking only at the next event.
- **A-78** (§374, §375, §377, §354; principles 1 and 7) For `outdated` and its inputs, the indexer keeps what it hears:
(a) `acted.<acting part>.<dependent>` in its own state, the newest `wait-ended` (ran or released) with the build it
acted for, compared with the dependent's current build (its newest entry's fingerprint); (b) what a delivered
version serves is read from that version's catalog entry (its manifest's `serves` and words); (c) a derived edge is
marked by a field `filled: true` the contract's `VersionEdge` gains, the machines that place a module come from the
assigner's `placement` (A-62), and each node's last `running` from the node-engine's stream read whole at start
(§556); (d) an `inputs` entry is also keyed by its run ask's id, so the build seat's `step-ended` of that ask finds
and deletes it.
- **A-79** (§558, §614, §684, §196, §444; principle 7) As built in mesh-delivery 6d483af2: the gate's `source` is named
in the short `invokes` form (the manifest's `invokes` is a list of names); the catalog half's rows go into the part's
existing `grants_first_views`; while the catalog half is unread the part keeps what the bus loaded and only adds,
which is §684's way past the cycle, so no registered branch holds nothing. The part's remaining reads of the
indexer's `manifests`, `modules` and `verdicts` go too (§196): the catalog half answers them.
- **A-80** (A-66, A-68, A-69, §375, §73; principles 7 and 8) What the indexer keeps as heard (`steps-since`, `toolchain`,
`delivered`, `pending`, `acted`) lives in one state of its own, `heard`, not in `own-build`, which keeps its one key;
every key part is escaped as a name (§73), so a dotted module name parses; a kind-3 edge compares its artifact's
language with `toolchain.<language>`.
- **A-81** (§588, §369; principle 7) As built in mesh-delivery f12883b2: the publish-again queue key is
`<holder>.<module>.<version>`; the holders and their nodes are what the builder hears on `running` (read whole at its
start, §556, so a restart rebuilds them); `running` means not stopped, with a fingerprint; a not-stored artifact is
remembered on the reservation (`Unstored`); the tool's request rides a reasks mode `republish`; a message the state
cannot take is not acknowledged, as the other parts do.
- **A-82** (§7, §428, §704's seed; principle 1, no module names another) The builder finds a build module the way the
indexer's seed does (mesh-delivery d73aeb02): the build seat whose acting rule `build` has an `on` matching the
artifact's language or `kind:image`, and that seat's holder on the seat list. `Task.Module` and every lane key are
that holder's name as the seat list gives it; a plan's artifact, the toolchain sources, `UnpublishedModules` and
`builder_stuck` all derive from it, and `builder_stuck` reads each build seat's steps through the seat (`<seat>.steps`)
rather than a named module's state. The floor's sources are the holders of the seats `git` (tags) and `mesh-catalog`
(requirements) on the seat list.
- **A-83** (§374, A-78, A-80; principles 1 and 7) `BuildEdges.fp` is the fingerprint of the branch's catalog entry at
the revision `source` names, which the indexer holds itself; no field is added to `package-published`. For a build
of another watched branch, kind 1 compares with that branch's newest build, kept as heard in `heard` as
`branch-build.<module>.<branch>` (the digest `package-published` carries), not with a released digest.
- **A-84** (§194 and its candidate's-view line, §348, §473; principle 1) The builder follows no candidate: only a run's
steps read a candidate's view, so the builder learns a candidate's build from the run's build step ask, which names
each entry by fingerprint; it reads each entry through `mesh-catalog.entry` (repository and commit are the member's
head) and needs no pull request number, a build being per fingerprint. Its read of the indexer's `candidates` view
goes.
- **A-85** (§291, ADR 0666 §6, §9, §614, A-83; principle 7) The indexer keeps a catalog revision per watched branch, as
it keeps the trunk's: objects `branch.<branch>.<n>` (the branch escaped as a name) beside `trunk.<n>`, the trunk being
the first watched branch's; the branch follower's per-branch `revision` reads them, and `BuildEdges.fp` is the entry's
fingerprint in the revision whose `source` the build names.
- **A-86** (§354, §375; principle 7) `KeepInput` is called by the indexer's own `input` verb, when a run on request's asker
hands an input; the indexer asks no `run` itself. A kind-3 edge's language is its catalog edge's target artifact's
language, else the one language the entry's artifacts share, as built in mesh-delivery 652285f0.
- **A-87** (§568, §589, A-70, A-76; principle 7) As built in mesh-delivery bd228d51: a fault with no node says `no node`;
`FaultClass` maps `buildstep.PassingCause`'s words onto A-76's four classes. `builder_build`'s `newest: <branch>` is
read by the tools bundle following the catalog half itself, as A-70 has it for `reserved`.
- **A-88** (§610, the main file's item 85; principle 7) mesh-networking's A-N1 (callers named in its seven seat
definitions) is not brought in: from G no verb names its callers (§610), which supersedes item 85's reading.
- **A-89** (§37, §700, A-74; principle 7, one way for every asker) The runner reads its approval ask's warrant from the
router's record of its ask, through the seat `operator-channel` as A-74 has it, never from the decided event's body;
the decided event only wakes it.
- **A-90** (§13, §14, §291, ADR 0666 §6, A-85; principle 7) A non-first branch's revision is made by the same take-in as
the trunk's, taken per watched branch: `sourceFollow` takes `source.<branch>` for every watched branch, and the
source path (`ApplySource`, the catch-up, the heads' take-in) runs with the branch as its argument, writing that
branch's revision (corrected by A-93).
- **A-91** (§26, §37, §700, Q-RN8; principle 7) The router's record value carries its `warrant` as §700 says: the
operator-channel contract's `AsksByAskerIDValue` gains the field. A step the module's policy does not name is no step
of its pipeline, so `Status` has no open question for it. The runner places a pipeline's steps when it starts it and
asks each build seat for its step, as its asking half; that half is built in G.
- **A-92** (§560, A-77, §627; principle 7, and who may do what is no question) The node-engine's bound keys live in a new
state `bounds` of the seat `node-engine`'s definition, declared in its old section as a foundation part's states are
(§627), key `<what>.<id>` with its own time to live; the node-engine's account holds it as it holds its other states.
- **A-93** (§13, §14, §291, ADR 0666 §6, A-85, A-90; principle 7; corrects A-90's trunk) A non-first branch's take-in
is a pure computation from that branch's merged messages straight into its revision (`KeepBranchEntries`): each
module's fingerprint, inputs and graph node at the branch's heads, computed as the trunk's are, with no modules view
or bucket of its own; the trunk's `modules`, `manifests` and graph stay the trunk's alone. The trunk stays the
mesh-wide branch `main` (ADR 0666's default watched branch), named once in the indexer; a registration's own first
branch decides only which of its branches it delivers from.
- **A-94** (§379, §525, §526; principle 1, a part asks for another's data or hears its events) The assigner hears the
builder's `build.ended` event (§379 names it) and reads no builder state such as `build-log`. A want for a trunk
revision's entry takes `version` and its parts' digests from the `version-released` whose `source` is that revision;
a build `build.ended` marks kept (its keeping node) is a kept build, its parts and `kept-on` from that event; a build
of another watched branch is the one whose `build.ended` names that branch, its parts from that event.
- **A-95** (§421, §683, §698, A-47; principle 7) As built in the node-engine's commits 7703162c and 97d3df3e: the entry key is
`entry.<digits>` (a key takes no colon); `want.<module>` holds the want with its own `since`; an entry another node
runs is learned from `running`; the refusal "no entry of fingerprint" is `not-found`; `first-view-again` refuses in
words, the node-engine following no view. Still owed in G: a restart composes the bus module and the indexer from the
kept entries and wants while both are down, without waiting for every input (§683's purpose), and the
`entry-not-found` finding (§614).
- **A-96** (§379, G-4's event table, §529, A-67; principles 1 and 7) The builder says `build.ended` itself, as a module
event on its own stream: a foundation part's old `streams` entry `mesh-delivery-builder-builds`, 7 days, kept last per
subject `build.ended.<module>.<fingerprint>` (each escaped), its body the build log entry's `module`, `fingerprint`,
`made` (artifact → digest), `kept-on` and `branch`; the assigner `consumes` `mesh-delivery-builder.build.ended`. A
want's source revision is the one its pass's kept assignment graph revision was computed from (A-67), matched to
`version-released.source`; `parts` stay keyed `<module>:<artifact>`, the contract's comment corrected to say so.
- **A-97** (§230, §194, §473, A-84, A-91; principle 7) A candidate's build is asked by the runner as a pipeline step of
its own: the runner's asking half asks the seat `mesh-builds` a `build` step naming each entry by fingerprint, and the
builder takes that ask (its one entry point for a candidate) and answers the step's end; `StepRun`'s steps stay lint,
unit and integration on the build seats. With the candidate coming that way, the builder's watch of the gate's
`source` for candidate base merges goes. A kind-3 dependency's `part` is the entry's kind-3 edge, as built in
2dc51626.
- **A-98** (§297; principles 3 and 7) The node agent gains one act, `Env.Stop`: it stops a module's units and containers
and removes nothing, so a revert's data survives; the revert stops the newer build with it, asks `restore-kept`, and
then `Apply` starts the reverted build. `Remove` keeps its meaning.
- **A-99** (§230, A-91, A-97; principle 7) `build` is a step every pipeline has, placed first and required whatever its
policy names, so the runner's step enum gains `build`; each module's pipeline asks the build of its own module's
entry only, and a group's members are built by their own pipelines.
- **A-100** (§379, A-96; principle 7) As built in mesh-delivery a5e1a5e5 and 5a352482: `build.ended` is said for a done
build only; its `branch` is empty for the trunk; its old-section stream keeps 7 days with no keep-last setting (an
old `streams` entry has none), which A-96's "kept last per subject" gives up.
- **A-101** (§532, §521, A-74, A-89; principles 1, 3 and 7, shared code in mesh-sdk) mesh-sdk's `stdio.TopicMatches`
understands the bus's own `>`, so an adopted follower's `<seat>.<event>.>` hears every event, not the first view only.
The operator-channel asker (the seat holder found on the seat list, the ask published, the router's record read for
the warrant, `decided` heard) is one mesh-sdk helper that the builder, the teller, the indexer and the runner use; no
module keeps its own copy. A step's own bound is a key with its own time to live too (A-77), not a timer.
- **A-102** (§22, §24, A-97; principle 7) A part that puts work on a seat's accepted kind names it in `invokes` as
`seat:<seat>.<kind>` (the runner: `seat:mesh-builds.step` and each build seat's `check.step`), and the grants part
composes the publish of that accept subject from it, as it composes a verb's call.
- **A-103** (§532, §614; principle 7, shared code in the follower) When two watched branches list one module, the
module's own registration decides: its first branch is the one read. The `Entry` and `Ready` helpers over the branch
follower, the `<module>_entry_again` tool, the `entry-not-found` finding and the entries rows of
`<module>_first_views` are built once, in `meshcatalogclient` and mesh-sdk's views, and every reader uses them.
- **A-104** (§22, §70, §482, §25, §416, §535, §647, A-70, A-77, A-68; principle 7) The runner's write verbs (`review`,
`rerun`, `accept`, `cancel`) are served by its tools bundle, which writes the state `pipelines` by compare-and-set and
says `step-ended`; an optional step still waiting does not hold a pipeline's end, only a required one does. A step
ask's kept results are the `kept` entries whose `package` is the artifact's package (from the entry); its
`toolchain` is the runner's `toolchain.<language>` kept as heard from `toolchain-agreed`. An unanswered ask is read
from the build seat holder's `ask-taken` as §647 says (not the seat list), its five minutes a key with its own time to
live in a state `bounds` of the runner.
- **A-105** (A-104; principle 7) The runner keeps what it hears of `toolchain-agreed` in a state of its own,
`toolchains` (history 1), key `<language>`, value its language, version and digests; a step ask's `toolchain` is read
there.
- **A-106** (§25, §416, §535, §647, A-104; principle 7) As built on the runner's recover branch (239a6693, e8b69509,
2d9c6591): a kept result counts for an artifact when its package is the artifact's or lies beneath it; the ask's
toolchain carries language and version; only the three build seats' asks are bounded by `ask-taken`; the five
minutes are a constant; an expired step ends `could not run` and the others run on. The runner's write verbs wait on
the operator's answer whether a process may answer calls (then the process writes `pipelines` by compare-and-set
itself); the runner gains a whole-module integration test against the bus in G.
- **A-107** (the operator, 2026-11-11 about 23:45 CET: yes, a process may answer calls; principles 1 and 7; withdraws
A-45, A-59, A-60's bundle principal, A-70, A-87's bundle part and A-104's bundle part) mesh-sdk's rule that a process
answers no call (issue 1171, AC3) is removed: a process answers its seat's verbs directly over the bus, with the
proved caller, through one mesh-sdk call. The part that holds the data answers for it: the bus module's keeper serves
`mesh-broker`'s verbs and sends the chunks itself; the builder's process serves `reserved` and `builder_build`; the
runner's process serves `review`, `rerun`, `accept` and `cancel`, writing `pipelines` by compare-and-set; the chunk
subjects go to the process that answers.
- **A-108** (§630, §214, §406, §516; principle 7) The catch-up is the node agent's: after the restore and the `Apply` of
the reverted build, it calls the point's recorded `{tool, arguments}` as that module's tool on its own node through
the tool runner, as `holder:node-engine` is granted (§406); `restore-kept` carries the snapshot only. §630's "passes
its catch-up to restore-kept" reads "runs its catch-up after it".
- **A-109** (A-107, §681, ADR 0675; principles 6 and 7) A process that answers its seat's verbs declares them in its
manifest's process section as `serves` (mesh-sdk's `ProcessBus` takes the field, its old "a process serves nothing"
gone), and the grants part composes the process account's subscribe of `mesh.seat.<seat>.call.<verb>.*` and
`.tool.<verb>` from it, plus, for a `chunks: true` verb, the publish of `.chunk.<verb>.>` and the subscribe of
`.ack.<verb>.*.*`. A snapshot's chunks are a transfer, published on the core bus with no stream; any caller of
`snapshot-get` receives the chunks (who may hear them is no question), a protected snapshot never.
- **A-110** (A-109; principle 7) A process's `serves` is a list of `seat:<seat>.<verb>` strings, the form of `invokes`
beside it; whether a verb sends chunks is read from its seat definition (`chunks: true`), never declared again.
- **A-111** (§22, §70, §482, A-104, A-107; principle 7) As built in mesh-delivery 210abfc8 and bb51e59a: a rerun's ask id
carries its time; a rerun carries the kept results and toolchain; `rerun` of `approval` is refused naming
`ask-again`; `cancel` drops the asks' bounds and leaves what the build seats already took; the hand act's verb is
`mesh-pipeline-runner.<verb>`; a review ends every running pipeline at that commit and fingerprint waiting on one. A
review given after a pipeline ended passed is refused, as built.
- **A-112** (§633, A-71; principle 7, one way per kind of part) A process reads its settings as the builder does
(A-71): a file its manifest declares, its content `${config:<key>}`, read at its start; so the node-engine reads
`recovery-wait-minutes` from such a file, default 90 when it is missing. A bundle keeps `stdio.Config`.
- **A-113** (§297, §560, §541; principle 3, failure is loud and leaves nothing broken) A revert whose restore fails
after `Env.Stop` starts the newer build again and holds the move, saying why; a module is never left stopped. A form
change whose entries are not yet answered waits for them, never moves without its restore point. The hold says
`wait-held` (§541) as every wait does.
- **A-114** (§693, A-61; principle 7) The seat `mesh-wants`' `wanted` stream keeps the last message per subject with no
age limit (`max-age-days: 0`): it is each want's last word, read whole at a start.
- **A-115** (A-107, A-109, A-110; principle 7; corrects both) `serves` is a field of a process itself, beside its
`bus`, not inside it: the grants part adds the serve subjects to whichever account that process runs on, the
module's own when it declares no `bus`, so a process keeps hearing what it heard. Only a seat's verbs move to the
process: a module tool such as `builder_build` stays its tools bundle's (A-87).
- **A-116** (§636, §616; principle 7) A read of a seat holder's state names the seat, as §616 does for views:
`reads` takes `seat:<seat>.<state>` (route-proxy: `seat:mesh-provisioner.plans`); the grants part resolves it to the
holder on record as it resolves a seat's views, and the module finds the holder through mesh-sdk's seat-list reader
(the holder of the seat), naming no module in code; the tests that held code to a fixed name hold it to the seat form.
- **A-117** (§683, §614, §560, A-95; principle 7) At a start, until its assignments, haves and resolved values are read,
the node-engine's pass composes only the modules whose kept want and kept entry it holds, a kept want standing for
their placement, and leaves every other module as it runs; the full pass follows once the inputs are read. It writes
`entry-not-found` itself through its own writer (kind added, scope `module`, id the fingerprint, escaped). The seat
`mesh-recovery`'s `ended` and `restored` events gain `why` (the hand act's words for a cancel), regenerated, which the
recovery module fills and the node-engine's hold says.
- **A-118** (A-77, A-101, §167's checker that goes with G; principle 7) The shared `Asker` takes optional bound keys;
the builder arms them in its `bounds` state. The checker, which the runner replaces and which goes after G, keeps its
step bound as today and gains no `bounds` state.
- **A-119** (§7, §616, A-82, A-116; principles 1 and 7) The builder's floor takes its requirements from the catalog
half it already follows (each entry's dependencies), so `indexer_requirements` goes; it is woken by the catalog
revisions it already hears, so the forge stream's consume goes; the assignments view is named in the seat form of
§616 (`consumes` `seat:mesh-module-assigner.views.assignments`, `reads` `seat:mesh-module-assigner.assignments`, A-116),
its first view through the seat's verb `assignments`. No module is named.
- **A-120** (A-117, A-95; principles 2 and 7) The early pass takes the node's own record from the statement the
node-engine makes of itself (its tunnel key, sealing key and capabilities), held in memory and built before the
composer's watch starts, without the bus; no copy of the record is kept in the composition state.
- **A-121** (§554; principles 7 and 8) An old section's kept data is named as the bus composer of mesh-sdk names it
when it makes it: a state `KV_` and its bucket name (module and name joined by `_`), a log its log stream name
(`LOG_`, module, `_`, name), a stream its declared name as is, an objects section `OBJ_` and module and name joined
by `_`. The recovery module calls those mesh-sdk names; it writes no name of its own.
- **A-122** (A-116, §324; principle 7) The node-build-image seat's `build` act takes the bound the other build seats
take, `60m`.
- **A-123** (§682, §554; principle 2) `aside` takes its bus names from the catalog entry of the fingerprint the
node-engine's placement runs for the module: what is set aside is the data that runs.
- **A-124** (§682; principle 7) The seat's aside names every bus object of the kept data: `Aside.name` becomes the list
`names` in the mesh-recovery contract, regenerated; no names joined into one string.
- **A-125** (§655) The restore of one stream moves into mesh-sdk's bussnap beside its snapshot, and the bus module
imports it from there; the recovery module's builder moves it, in the same work.
- **A-126** (A-82, A-101; principle 7) Who holds a seat now is read by one mesh-sdk helper beside the seat list
(`seatlist`), through the assigner's `assignments` verb; operatorask and the view call it, and no part keeps its own
copy. The builder's holder at a catalog revision (`versions.HolderOf`) answers another question and stays.
- **A-127** (A-115 over A-109, A-110) `serves` is read only beside a process's `bus`: mesh-sdk's process parse, the
grants part's process-serve composition and the validator's test follow A-115; a `serves` inside `bus` is refused.
- **A-128** (A-116; principle 7) A `reads` in seat form `seat:<seat>.<state>` is parsed by mesh-sdk's state reader as
its own kind, kept apart from a module's read; the validator checks the seat declares the state, and the holder is
resolved where it is read, by A-126's helper.
- **A-129** (§657; principle 4) The seat's `kept-points` answer gains `unrestored`, the asides whose record ended at
`removed`, read from the engine; the tool `recovery_kept_points` shows it, and the health check reads the same.
- **A-130** (A-124, §557; principle 7) The events `set-aside` and `aside-discarded` carry `names` as `Aside` does; the
recovery module's two bounds are the settings `dump-wait-minutes` (default 60) and `point-keep-days`.
- **A-131** (corrects A-119's first view; §616; principle 7) The builder's first view of the assignments is asked of
the view's own first-view tool on its holder (`<holder>.assignments`), the holder found at runtime by A-126's helper
and the builder among the view's callers; the seat-form `consumes` of the view covers it, and the seat verb
`assignments` keeps its own answer.
- **A-132** (A-123, §556; principle 1) The recovery module learns the fingerprint a node runs for a module from the
node-engine seat's `running` event, kept last per subject and read as §556 (a `consumes` of its manifest); no call.
- **A-133** (§657, §567, §554; principles 3 and 7) The recovery module's manifest follows the validator: (a) its health
check is its tool beside the process check the other modules declare; (b) the `digests` state's cap is given in the
template's own form at 4 MiB, never as a second option beside it; (c) the template states `digests` and `findings`
are the module's own by its `requires` and are not listed again in the process's `bus`, which keeps its own account.
- **A-134** (A-16, A-26, A-28; principles 7 and 8) The licence manager's `binding.changed` carries the consumer as its
further part (`binding.changed.<consumer>`), the one form of G's seat events; mesh-vault and claude-code adopt it
through their views reader, and mesh-vault's two followers share its one writer.
- **A-135** (corrects A-133(b); ADR 0595 §3; principle 7) The state template takes no cap: `digests` declares none and
the template's fixed cap stands; §567's 4 MiB is the size expected, not a setting.
- **A-136** (§483, §496; principle 1) The watchman's read of the build seats' steps goes, as §483 says: it times a
running ask from the build seat's step-progress event; its `reads seat:node-build-*.steps` and the holder lookup
for it go with it, and no holder event is needed.
- **A-137** (§681, A-123; principle 2) Before a keeper's snapshot is restored, the recovery module sets aside the bus
names of the restore's module and kept data from the catalog entry of the fingerprint the node is running; for an
unprotected snapshot, the `stream` snapshot-get answers.
- **A-138** (§557, §551, A-77, A-130; principles 1 and 7) The wait on snapshot-restored and the expiry are bounds as
well: settings `snapshot-restore-wait-minutes` (default 90) and `expire-every-hours` (default 24); every bound of
the module may be a fraction, so a whole test sets seconds; the expiry runs on a bound key's expiry, not a timer.
- **A-139** (§681; principle 7; code shared between modules is in mesh-sdk) The chunks of a seat verb's answer are
received with mesh-sdk's own form (`buscalls`), the one the bus module sends with; where mesh-sdk has no receive,
it is added there, never built in the recovery module.
- **A-140** (§681; principles 3 and 7) After its cancel is asked at the bound, the recovery module waits one more bound
of `snapshot-restore-wait-minutes` for that act's snapshot-restored; none heard is "answers neither". A keeper that
answers `busy` ends the act failed before any aside, naming the keeper's running act.
- **A-141** (§562; principles 1 and 7) The recovery module learns of a move from its own stop: from the stop signal
on it answers every new call with an error naming the stop, cancels the running act so its own failure path runs,
and ends every accepted act not ended `stopped` with its ending event; a restart is the same.
- **A-142** (§496, §602; principles 1 and 7) A `step-ended` said while the watchman was down reaches it on its
start through its durable consumer of EVENTS, and ends the stuck ask then; nothing re-reads the steps and no
expiry is added.
- **A-143** (A-77, A-138; principle 1) The recovery module's dump wait and snapshot-restored wait are bound keys in
its state `bounds` as well, their expiry heard on its watch; no timer stays in the process.
- **A-144** (ADR 0625 §4 over §614 and §670's placing; principle 7) A client imports only its own seat's contract,
mesh-sdk and its domain SDK: the key codec `meshcatalogkey` moves into mesh-delivery's domain SDK, imported there
by the builder and the catalog client, and the source-branches follower's use of the `mesh-delivery` seat's types
moves into the domain SDK too; the catalog client keeps the mesh-catalog contract and the domain SDK only.
- **A-145** (§621, §494, §697, ADR 0633 §6; principle 7) The second reader release carries only §621's words and what
the trunk validator needs to judge the new indexer's manifest and the `by-caller` definitions; §529's finding-stream
rules and A-116/A-128's seat reads are G's own validator rules, judged by the change's validator, and stay in G.
- **A-146** (A-145, §529, A-30; principle 5) The second reader release also carries §529/A-30's exception for a
foundation part's kept old sections, and only that, since the trunk validator must accept the new indexer manifest.
- **A-147** (A-123, A-132, A-137; principle 3) While a module runs at two fingerprints (a move under way), a recovery
act on its kept data is refused, naming both; the caller asks again once the move has ended.
- **A-148** (A-145; principle 7, one release one check) A trunk fault that fails a release's own check rides that
release as its own commit, as fix 1975's distribution test did: the second reader release carries the builder's
by-hand answer fix (an ask is answered as put only after its put; issue 1126, ADR 0668 §1).
- **A-149** (§634, §527, A-120; principles 2 and 7) The node-engine knows its own name at start from its applied
store: the record of the module whose fingerprint is its own `MESH_FINGERPRINT`; the finding writer, discovery and
the vault login use it. Only on a first start with no such record do they wait for the first composing to name it.
- **A-150** (§563, A-107, A-115; principles 1 and 7) restic's `night` process, which dumps, gets a `bus` of its own
(its own broker account, as the recovery module's process has) and says item-started and item-ended and reads the
recovery module's events itself; no local request to the tools runtime, and the backup does not move into it.
- **A-151** (§465, ADR 0614 §2; principle 7) The three build modules `require` the provision `artifact-store` to read a
group member's build, with a `binds` file as go-package-registry's (`at`, `serves.port`), and read the blob by the
store's own path `<at>:<port>/v2/<module>/<artifact>/blobs/<digest>`; they never write into it, so ADR 0614 §2
holds, and their manifest tests assert the read.
- **A-152** (§472, §492; principles 3 and 7) The toolchain's `digest` is the sha256 of the toolchain program the build
module runs (the `go` or `node` it finds), computed at its start and again when the toolchain's version changes; no
field is added to the provision.
- **A-153** (§559, E §1; principles 7 and 8) The tool runner resolves a `deliver: new` subscription's key
`<emitter>.<event>` to its subjects with mesh-sdk's `buscompose.EventSubjects`, the one rule from an event name to
its subjects (a seat's event subject or the module's); a pattern with a wildcard is refused with `{error}`.
- **A-154** (design 46 approval mark §4, §16, §19; principles 7 and 8) The approval mark's three findings take scope
`machine` and the id `<node>.<module>`, `<node>.<ask id>` or `<node>.approvals`, escaped as a key's name, with the
subject of the tool runner on that machine, as the runner's first-view findings already do.
- **A-155** (§561, §563, §302, A-77; principles 1, 2 and 3) restic's put-off wait for a restore is a bound key in a
state of its own on the bus, bounded by the setting `put-off-bound`: the key is the put-off record `backed-up` reads,
its expiry raises `backup-waits` and ends the wait, so the night never holds its lock without a bound and no file
or timer keeps it. BKP7 is not built: §555 gives `restore` its class's default with no own-item limit.
- **A-156** (§610, A-82, design 51 *The move*; principle 7) Once distribution's `callers` list goes, the windows'
driver takes "every build module" as the modules that claim a build seat (`node-build-*`) in the catalog half it
follows, the one source A-82 gives; the holder's own per-verb `Allowed` checks go with the list, since §610's class
defaults are applied where the call is read, and the refusal of an unproven caller is that reader's.
- **A-157** (design 46 approval mark §16, §19, ADR 0668 §1, A-77; principles 1 and 3) Each try of `warranted` is a
`DoKept`; past its bound the call is made again when the hand-act seat's holder is heard again (the seat-holders
view the runner follows) and at each start; `call-unanswered` is raised on the expiry of a five-minute bound key per
ask, not a timer. A failed read or write of `approvals` is made again at the next marked call and at the next
membership change the runner hears.
- **A-158** (design 46 approval mark §16, §677; principle 8) A marked call's answer is `{answer, approval}`: the tool's
own answer and the line naming the approval, the form a process holder's `gated-ended` has, so a caller reads one
form from both gates. A-157's bound key lives in the runner's state `bound` as `<node>.unanswered.<ask id>`.
- **A-159** (§466, §472; principles 3 and 7) A build's `resolved{package, version, digest}` names what was used: its
`version` is the commit the ask names, and its `digest` the sha256 of what was laid (the Go module cache zip, the
npm tarball), or the member build's digest when it was laid from `builds`.
- **A-160** (§64, §190, §321, A-85, A-93; principle 7) A run's candidate is keyed by its run id `run-<id>` from the
runner's `run-started`, beside `try-<n>`; each member {module, commit, branch} maps to its repository by the
registrations and to the branch's revision view as its trunk; its manifests and fingerprints come from the same
branch take-in the indexer computes for any commit (its files read through the seat `git`), so no checker preview
is heard.
- **A-161** (§522, §81, §170; principle 1) An event carries what its hearers need to say it: `recovery-merged` gains
`module` and `branch`, and a forge-made record's `record-opened` gains `repository`, `pull`, `commit` and `branch`,
in their contracts and from their emitters; the teller makes no call per message.
- **A-162** (amends A-100; §575, A-94, ADR 0596; principle 1) The builder's `build.ended` is said for every end of a
build, carrying `outcome` (done or failed) and, when failed, `error`; the assigner's hold says "failed: <error>"
from it and "is being built" while no `build.ended` of that fingerprint is heard. The assigner never reads the
builder's `builds` bucket; its read there (put.go:85, the manifest's `reads`) goes.
- **A-163** (§543, §544; principles 7 and 8) The asker in an ask's accept subject is the asking seat's own name
(`mesh-pipeline-runner`, `mesh-catalog`, `mesh-wants`, `mesh-builds`, `mesh-delivery-checker`), not a nickname, so
steprun checks it against the callers the build seat's definition lists, read from the seat list; no table of its
own and no name map. A body's kind is the word the seat definition gives; a queue keeps its own name.
- **A-164** (§468, §76, §495, A-115; principles 4 and 7) The runner's process writes each durable consumer's oldest
unacknowledged age into a state of the runner's own when it changes; the bundle's `runner_health` reads that state,
its own module's, and asks no seat verb of itself; tools stay the bundle's (A-115).
- **A-165** (§610, A-156; principles 3 and 7) The class defaults of §610 are applied where a seat's verb is answered:
mesh-sdk's seat server (`conn.AnswerSeat`) and the tool runner's `serveSeats` read `seatdef.EffectiveCallers` and
refuse a caller outside them, the unproven one included, before the holder runs; a holder keeps no caller check of
its own.
- **A-166** (A-164, §76, §495; principles 1 and 7) The runner keeps a state `consumers` (history 1, a key per
consumer) holding the time its oldest unacknowledged message was delivered, written when a message is delivered or
acknowledged; `runner_health` works the age out as now minus that time when it is read, so nothing is read on a
timer.
- **A-167** (§354, §63, §22, §64, §357, §298; principles 1, 2, 3 and 7) For the assigner's composition step (AS5): its
`run` builds the node-engine's composer (`mesh-compose`) at the fingerprint the node-engine runs; each machine's
input is asked of that node's engine by `compose-candidate`; the machines are the nodes the branch's revision places
the module on; a node is asleep when the watchman's `machine-away` is heard for it; `mesh-compose` reading
`MESH_RUN_INPUT` and answering the run's output is the node-engine's, a row of its own. An entry held for want of a
provider (AS14) carries a field `held` naming the candidates, never only a log line. A revert (AS17) is a want that
goes back to an earlier fingerprint, which the assigner computes itself; a kept data's `form` is read from the
catalog entry's kept declarations (`catalogue.KeptDeclarations`). AS14's named seat and contribution edge, and
AS17's ask of the operator, go to a design line.
- **A-168** (E §33, design 46 approval mark §5; principle 3) For a marked wait on a module the runner does not serve,
the marks are the union of the newest entry of every followed branch; where the runner serves the module, its
served entry is added to that union. A mark is never lost.
- **A-169** (§579; principles 2 and 7) A pins state keys a revision by the revision object's own name (the assigner's
`trunk.<n>`, the indexer's `<branch>.<revision>`), value `{records, missing?}`, and holds two more keys in the same
form in every holder of pins: `made`, written once by create-only when the state is first used, and
`pins-stated`, the `at` of the applied event; pins count only once a `pins-stated` later than `made` is applied.
- **A-170** (§600, §481, §415, A-163; principles 7 and 8) Every ask to a build seat rides `accept.<queue>.<asker>`;
its kind is in its body only, as §600 says. A build seat definition's `stream` names only the queue, and the
generated accept subjects follow; the kind in the subject goes. §543's main subject takes `build` and `run` as
written, the checker's asks riding it until it goes.
- **A-171** (§579, A-169; principles 2 and 8) The `pinned` event's `catalog` entries name their branch: each is
`{branch, revision}`, in the mesh-delivery seat's definition and from the gate that says it, so a holder keys the
pin `<branch>.<revision>` from what the event says.
- **A-172** (§653, §431, A-161; principles 1 and 7) With the Approve per merge gone, the teller's merge-ask path goes
whole (its reads of the gate's `asks`, its handlers and their tests); the teller keeps `answers` and `answered` for
the assigner's asks only. A view's answer reaches it by the view's event, as §431 says, never by reading the
view's state. The gate fills `recovery-merged`'s `branch` from the branch it merged into and its `module` from the
catalog half's registrations; while no path of the gate opens a forge-made record, the teller says none.
- **A-173** (§507, §512, §532, A-103; principle 7) The view derives each watched branch's source on its own: the
source row and `delivered` per branch, a repository's reach from the source of the first branch of its
registration (before the first registrations, the branches `source` answers), and `view_tiers` with no revision
answering per branch; no branch is named in its code.
- **A-174** (§64, §190, A-160, A-93; principles 2 and 7) The indexer keeps a state `runs` (key `run-<id>`, value the
members and the modules whose pipeline ended), written on `run-started` and on each of the run's `pipeline-ended`,
removed with the candidate, so a restart loses nothing. A member on a branch its registration does not watch takes
the trunk's revision view as the base of its take-in; one on a watched branch takes that branch's.
- **A-175** (§512, §431, A-43, A-172; principles 1 and 7) The teller says its `answers` as a plain views family
`views.answers`, and the view says its own `answers` the same way; each follows the other's by mesh-sdk's
`ProcessReader.Follow` (first view through the owner's tool, then its views family). That is the "event" A-172 and
§431 mean; no own follower and no module-event adopt are added.
- **A-176** (A-166, §579, §76; principle 7; code shared between modules is in mesh-sdk) A process writes its durable
consumers' facts (stream, name, acknowledged sequence, pending, last event applied and its `at`, and when its oldest
unacknowledged message was delivered) into its module's own state `consumers` (history 1, a key per consumer) through
one mesh-sdk helper, after each message it applies; the runner and the indexer use it, and their tools read that
state.
- **A-177** (design 46 approval mark §4; principle 7) mesh-sdk's compiled `catalogue.Verb` gains `NeedsApproval`,
copied by `SeatsFromDefinitions` from the definition, so the validator and every reader of the seat list read a
verb's mark from one place.
- **A-178** (A-175, A-43; principles 7 and 8) The view says its `answers` as other owners say theirs: a read tool
`view_read_answers` (mesh-sdk `views.ReadTool`, in the view's tools bundle, the teller among its callers) and a
marks state `view-marks` (history 1), as the assigner and the indexer have; the teller's side is the same, with
`teller_read_answers` and `teller-marks`.
- **A-179** (refines A-165; §610, §336; principles 3 and 7) Where a seat's verb is answered, an unproven caller is
refused, and so is every caller when the verb's effective callers are empty; a proven caller is taken as among
them, since the grants part composes a verb's call subject only for the callers its effective list names, so the
bus holds the rest out. `seatdef.DefaultCallers` follows §610 (act, warrant and accept: operator, sessions and
invokers).
- **A-180** (§64, §420, A-160, A-174; principles 1 and 7) The runner places a run's pipelines when it hears the
catalog seat's `catalog-revision` for the candidate `run-<id>` (a candidate's revision, its subject naming it),
reading the candidate's entries and fingerprints through the seat's `revision` verb with the candidate's group;
`<id>` is a random 12-hex id the runner makes, so two runs of one commit are two pipelines.
- **A-181** (amends A-100 and A-162; §556; principles 1 and 2) The builder's `build.ended` stream keeps the last
message per subject (one per fingerprint), and the assigner reads it whole at its start as §556 reads a kept
stream, then hears it; so what was built, and a failed build's error, survive its restart and it reads no builder
bucket. `assigner_put`'s fingerprint-prefix form goes: a put names the whole fingerprint.
@@ -0,0 +1,379 @@
---
layer: to-be
status: in-progress
design: 47
milestone: G
updated: 2026-11-12
decisions:
- "ADR 0666"
- "ADR 0656"
- "ADR 0596"
- "ADR 0567"
- "ADR 0565"
- "ADR 0540"
- "ADR 0633"
- "ADR 0579"
- "ADR 0571"
- "ADR 0564"
- "ADR 0539"
- "ADR 0330"
- "ADR 0429"
- "ADR 0259"
- "ADR 0126"
- "ADR 0112"
- "ADR 0084"
---
# 47, milestone G: the provider a requirement points to, the ask of a held revert, the edge an acting rule gives, the take-in of every watched branch, and the seats of the status view's and the assigner's views
One file of milestone G's part of [design 47](../47-delivery-from-commit-to-delivered.md); the part opens at
[G.md](G.md). Its design lines are numbered across every file of the part and cited as "design 47 G §n".
*§708 to §710 answer the assigner's develop questions on build-map rows AS14 and AS17 (2026-11-12), which the lead's
answer A-167 ([G-20](G-20-lead-answers.md)) sent to a design line: which field names the seat whose holder provides a
requirement, which field says a requirement carries contributed values and the edge's kind word (§357), and the form
of the assigner's ask when a revert is held (§300). §711 answers the indexer's develop question on build-map row IX8
(2026-11-12), which the lead's answer A-212 (G-22, the lead's second answers file) sent to a design line: which acting steps
give an edge of kind 5 (§47), between which entries, and what a catalog entry's `acts` holds. §712 to §715 answer
the indexer's develop questions on rows IX5 to IX7 (2026-11-12), which A-213 sent to design lines: the validation's
run before take-in, what holds a pending revision while it runs, and how a watched branch other than the trunk gets
its merges, its pending revision and its groups. §716 answers the lead's question of 2026-11-12 (A-279) that no
principle settles: where the gate keeps a group's members and each member's base before the take-in. §717 answers
developer J27's question of 2026-11-12 on A-210: which seat the status view's answers and the assigner's asks are
views of, and how a follower starts before their holder is known. Each is the
design's choice within the record it cites, tested against [the principles](../../../00-META/principles.md).*
## The provider a requirement points to
- §708 **The named seat is the seat that delivers the requirement's provision; no catalog entry field names it.**
(ADR 0330 §2; ADR 0126 §3; ADR 0084 §3, §4; ADR 0571 §4; design 27 *A module provider*) This completes §357's
order for the assigner's `Compute`. A catalog entry's `requires` stay bare provision names. For each requirement
R of a placed module on node N, in this order:
1. **The named seat's holder.** The seat whose definition's field `delivers` (mesh-sdk `seatdef`) is R, among the
seat definitions the entry's catalog graph revision names in its `definitions` (each read whole through the
seat `mesh-catalog`'s verb `seat-definitions`, as every part reads the catalog half). Its holder is read from
the same revision's placements, from their `holds`, as the assigner's state `seat-holders` keeps them: the key
`<seat>` for a seat held once for the mesh, `<seat>.<N>` for a node seat. A seat that delivers R and that no
placement holds holds the entry, naming the seat; no other step is tried (design 27, step 1).
2. **A pin.** The placed module's `bindings` entry for R, else N's placement `pins` entry for R.
3. **The provider on N.** The one module placed on N whose catalog entry's `provides` names R.
4. **The only provider.** The one module placed on any node whose catalog entry's `provides` names R.
Each step that answers gives the entry the edge of kind `provisioning`, its `node`, `module` and `fp` the
provider's and its `provision` R. Where no step answers and more than one candidate is placed, the entry carries
`held`, a list with one item per requirement held: `requirement` R, `seat` (the unheld seat, step 1 only) and
`candidates`, each `{node, module}`, sorted; the assigner writes no want from a held entry, so the node keeps what
it runs, and the field is read with the entry through the seat `mesh-wants`' verbs. An optional requirement
(ADR 0330 §3) with no candidate is left absent: no edge, no hold. A hard requirement with no candidate is held
with `candidates` empty. Why: the seat definition already carries `delivers`, and the assigner already keeps who
holds which seat from the placements, so nothing new is declared and no part outside the assigner's inputs is read
(ADR 0656 §2; principles 1 and 7); a hold is said in the graph, never only in a log (principle 3; design 47 G
A-167). How it is checked: unit (assignment graph), one row per step, the seat's holder winning over a provider
on N, an unheld delivering seat holding the entry with `seat` named, two candidates and none on N held with both
named, an optional requirement with none left absent.
- §709 **A requirement carries contributed values where the manifest's `contributes` names it; its edge is of kind
`contribution`.** (ADR 0656 §2; §174, §175, §357, §442) This completes §357's contribution edge. The catalog entry
gains `contributes`: the requirement names the manifest's `contributes` object has as keys, sorted, its local
names not carried; the indexer fills it, since it alone reads a manifest (§442). `requires` keeps naming every
requirement, those only `contributes` names included, as mesh-sdk's `catalogue.Manifest.Wants` lists them, since
contributing to a requirement is requiring it. For each requirement in `contributes` that §708 resolves, the
consumer's entry carries, beside its `provisioning` edge, an edge of kind `contribution` to the same provider, its
`provision` the requirement. The kind word is `contribution`, the glossary's and the seat `mesh-wants`' `Edge`
`kind` (provisioning, contribution or acting); the assigner's `EdgeContribution` joins `EdgeProvisioning` and
`EdgeActing`. The `Edge` fields' descriptions in the seat `mesh-wants`' definition become: `provision`, for
provisioning and contribution, the requirement; `seat`, for acting only, the seat whose rule gave the edge. A seat
contribution (the manifest's `contributions`, a piece given to a seat's holder on the node) gives no edge in G.
Why: the manifest already says which requirements carry contributed values, and the edge kind already has its word
in the glossary and the contract (principles 7 and 8). How it is checked: unit (indexer), a manifest whose
`contributes` names `route` gives an entry whose `contributes` and `requires` both name it; unit (assignment
graph), that entry gets a `provisioning` and a `contribution` edge to the route's provider, and an entry with no
`contributes` gets none of kind `contribution`.
## The ask of a held revert
- §710 **The assigner asks the operator about a held revert as it asks about a failed backup.** (ADR 0539 §16;
ADR 0259 §3, §4; ADR 0564 §2; §297, §300, §363, §461, §541, §700, §706) This completes §300. When a node's have
says the phase `held` for a revert, with the reason `restore point missing` (§300, a missing point or no
`restored`) or `restore point damaged` (§567), the assigner:
- **Asks**, through mesh-sdk's `operatorchannelclient` on the seat `operator-channel`, as its other asks are made,
an ask of the new kind `revert`, kept in its state `asks` under `revert.<node>.<module>.<fingerprint hex>`, the
fingerprint the reverted build's; like the backup ask it needs no proof of who answered, so the view may answer
it. Its headline: "The revert of <module> on <node> has no restore point". Its explanation names the reverted
fingerprint, the kept data, its form and the node's reason in its own words, and says "<module> keeps running
its newer build until you answer. Started on the live data, the older build reads data written in the newer
form." Two options, each of level acknowledge: `hold`, "Keep it held", does "the node keeps running the newer
build, and the revert waits"; `live`, "Start on the live data", does "the node starts the older build on the
live data as it is, with nothing restored". It expires after the assigner's `AskLasts`, `OnExpiry` "the module
keeps running its newer build". The answer is read from the router's record of the ask (§700).
- **Raises the condition**, through mesh-sdk's finding writer (§461), with the finding `revert-held` (scope
`delivery`, id `<node>.<module>`), so the condition keeper's key is `delivery.<node>.<module>.revert-held`;
severity `warning`; its summary "The revert of <module> on <node> is held: <reason> (<kept data>, form <form>);
the ask about it waits for your answer"; its `needs` "Nothing for you to do.", so the operator's one message is
the ask (§706).
- **On the answer**: `live` writes the node's want again with the want's new field `revert` `live` and `words`
"the operator answered \"live\" to the revert ask (asking <n>)", as the backup's answer is written; the node
agent, reading `revert` `live` from its own want and from nothing else, starts the reverted build with no
`restore` and no aside taken, calls no catch-up tool, and applies as any want. `hold` writes nothing: the hold
stands. The finding is cleared once the reverted build runs, or when a newer want of that module on that node
replaces the held one, which also drops the ask (§363). An ask that ends unanswered is raised again at once
while the hold stands; one answered `hold` is not asked again.
- **Its tools**: `assigner_read_asks` reads the ask and `assigner_read_findings` the finding, both existing;
`assigner_ask_again` raises it again by hand.
Why: ADR 0539 §16 has the assigner ask, raise the condition and write the want again naming the answer for a hold
before an apply, and the backup ask is that shape already built (principle 7); the finding writer is the one way
G's parts raise a condition (§383); the ask alone reaches the operator, as O-9 had it for §706 (principle 3, the
hold is still loud in the condition). How it is checked: whole (assigner, a fixture node agent saying `held` with
`restore point missing`): the ask under `revert.<node>.<module>.<hex>` with both options and the finding raised;
`hold` writes no want and the newer build keeps running; `live` writes the want with `revert` `live` and its
words, and the finding clears once the have names the reverted build; a newer want drops the ask and clears the
finding; an unanswered ask raised again. Unit (node-engine): a want with `revert` `live` starts the reverted build
with no `restore` call; unit (`meshwantsclient`): a `revert` other than `live` is refused.
## The edge an acting rule gives
- §711 **An acting rule gives an edge of kind 5 from the acting part to each entry it acts on, in the steps that act on
a delivered version.** (ADR 0656 §1; ADR 0666 §14, §19; §47, §49, §203, §265, §266, §270, §324, §374, §378, §535,
§569, A-208) This completes §47's row 5 for the indexer, which writes a catalog entry's edges (A-208).
- **The entry's `acts`.** The indexer fills a catalog entry's field `acts` when it makes the entry: for each seat
its manifest's `claims` names, each acting rule that seat's definition carries, among the definitions the entry's
catalog graph revision names in its `definitions` (read through the seat `mesh-catalog`'s verb
`seat-definitions`, as §708), as one item `{seat, step, on, bound}`: `seat` the claimed seat, `step`, `on` and
`bound` as the definition writes them, `bound` left absent where the rule names none (its step's default, §266,
is the reader's). Items sorted by `seat`, then `step`; a module that claims no seat with a rule has no `acts`. It
is what the runner (§535) and the builder (§546) read, and what the edges below are derived from; nothing else
writes it. The contract's description of `step` gains `pipeline` (§203).
- **The steps.** `grant`, `compose`, `place` and `check`, and from G's delivery `pipeline` in `check`'s place
(ADR 0666 §19; §65), each give kind 5: a grant or a credential, a composition, a placement, a verdict, each made
for the dependent's new version (ADR 0666 §14). `build` gives kind 3 (§47, §267), never kind 5. `take-in` and
`validate` give no edge: an entry is in a revision only once the indexer has taken it in and validated it, so
such an edge would always be met (principle 7).
- **Between which entries.** For each entry B with such a rule, and each other entry A of the same revision that
the rule's `on` matches (`every`; a language, A having an artifact of that language; `kind:image`, A having an
artifact of kind image, §324): one edge `kind` 5, `from` B's delivered artifact, `to` A's delivered artifact (the
artifact the entry's first process resource runs, else its first, as kinds 4 and 6 have it), `word` `acts`, `why`
`<seat> <step>`, `stale` false (it only orders, §378), `declared` false. No edge goes to B itself, nor to an entry
B's new version is built from or needs: one with a path of edges of kinds 1 to 4 to B in that revision (a
package, a fetched artifact, a build module or base, a provider), which B's running version acts on (§270). An
entry with no artifact has no edge. A rule of a seat no entry claims gives none; the step's own holder says that
(§233, §535).
- **How it is met.** The edge is met when B's new version has acted for A's build, as the holder's `wait-ended`
says and §374 records; for `compose` per node, by the assigner (§268). It is a delivery edge, so a cycle of it
with kinds 2, 4 and 6 only is delivered as one step, and one with kind 1 or 3 is refused naming it (§49, §569).
Why: the rule already says the step and the entries, and the artifact a delivery orders is the one kinds 4 and 6
already name, so no manifest word is added and no module is named in code (principles 7 and 8); a cycle left by a
rule is refused loudly at the check (principle 3). How it is checked: unit (indexer's graph), an entry claiming a
seat with rules `grant` on `every` and `build` on `go` carries both in `acts` with its seat; a grants part of rule
`grant` on `every` gives kind 5 to every other entry but none to itself nor to the build module and package it is
built from; a rule `compose` on `kind:image` gives edges only to entries with an image artifact; a rule `build`
gives no kind 5; an entry with no rule has no `acts`.
## The validation before take-in, and the take-in of every watched branch
- §712 **The validation is one `run` of the indexer's manifest validator over two cases, refusing only what the revision causes.**
(ADR 0666 §5, §6; ADR 0579 §2; ADR 0578 §2; §16, §206, §338, §354, §467, §481, §493, A-213) This completes §16's ask.
For a pending revision of watched branch B (§713), the running indexer asks the seat `node-build-go` the accepted
kind `run`, on `mesh.seat.node-build-go.accept.run.indexer` (§481; its callers §338), its step key
`indexer.<node>.<id>` (§467), `<id>` `validate-<s>-<n>`, `<s>` the stream sequence of the newest merge the revision
covers and `<n>` the count of asks for it, from 1. Its job:
- **`program`**: the indexer's own program `cmd/mesh-judge`, under the Go module the `package` of the indexer
entry's Go artifact names, at that entry's `path`, built at the revision's head of that entry's `repository`;
the indexer entry is the entry of B's revision being validated that claims the seat `mesh-catalog`, else, when
B watches no indexer, the trunk's current revision's. No repository or module name is fixed in code (ADR 0666
§5); the program's own directory is the indexer's own code.
- **`heads`**: none, since the manifest validator reads only its request; **`args`**: none; **`reader`** "manifest validator of
<B> at <s>".
- **`input`**: the manifest validator's request, served by the seat `mesh-catalog`'s verb `input` and kept in `inputs` as §354
has it, any size (ADR 0666 §16): case `change`, every module of B's current revision by its entry's manifest,
each one the pending merges carry replaced by the merged message's manifest bytes, one added for a new
directory; case `trunk`, every module of B's current revision as it stands (the name is the validator's, not the
branch); `seats` the definitions the merges' trees carry (the main file, *Validated with the seat definitions
its merges carry*); `packages` and `predefined` as the take-in's own manifest validator has them; no `machines`.
- **Its verdict.** The revision is refused when the case `change` refuses a manifest the revision adds or changes
(its digest differs from the `trunk` case's) with a problem the `trunk` case lacks, or names a problem `(between
manifests)` the `trunk` case lacks (ADR 0579 §2). A problem only in unchanged manifests refuses nothing; their
entries keep their verdicts (ADR 0579 §1). A refusal sets the pending value's `refused` to each manifest and its
problems, said in `take-in.pending` (§493).
Why: the manifest validator already answers two cases for exactly this rule, as the checker ran it, and the build seat's `run`
is the one way a program built from heads runs (principle 7; ADR 0666 §6). How it is checked: whole (indexer, a
fixture Go build module): a revision whose changed manifest gains a problem stays pending, `refused` naming it; a
revision whose unchanged manifest has one is taken in; the job names the indexer entry's repository, path and the
revision's head, and no heads.
- §713 **A pending revision names its ask, and resumes on the ask's end; a run that could not validate is no
refusal.** (ADR 0666 §6, §18, §24; ADR 0633 §5; §16, §18, §19, §24, §269, §483, A-213; the main file *A wait is
bounded, said and recoverable*) This completes §16's wait, and amends the main file's *A revision that names another
indexer moves only that indexer* in that every revision now waits there for its validation. Every merge of a watched branch is first written to
`pending` as the main file has it (key `m.<sequence>`, or a group's key, §715), its value gaining `validation`:
`ask` (the `run` ask's id), `asked` (when) and `input` (its digest). The indexer puts the ask, acknowledges the
merged message, and the take-in ends there. It hears the end through a durable consumer of its own of the seat
`node-build-go`'s event `step-ended` (§24), taking only ends whose step key starts with `indexer.`, and reads the
answer from that step key; at its start it reads each pending value's `validation` and its step key, so an end said
while it was down is not lost. An end whose ask is not the one the pending value names now is dropped, written in
its journal. A later merge of B while an ask is out joins the pending revision (the main file) and is asked anew
with the next `<n>`. On the end:
- **accepted**: the revision is taken in as the main file has it, by the indexer it names (§16), and its keys go;
- **refused**: it stays pending with `refused` (§712), asked again only as part of a later merge of B, as a
revert is (§19);
- **could not validate**: the step ended `could not run`, the program exited other than 0, or its answer holds not
both cases: it stays pending with `validation`'s new field `failed`, the build seat's words, said in
`take-in.pending`, never as a refusal and never as passed (ADR 0666 §18; principle 3). It is asked again by a
later merge of B and by the indexer's new tool `indexer_validate_again` (key; class `act`, §391's default callers,
written in the hand-act log), which also reads the ask's state.
An ask no build node takes waits on the work queue, said by `build-capacity-waits` after 60 minutes (§483); every
case is timed by `take-in-waits` at 60 minutes (§19). `indexer_pending` shows `validation` whole. Why: a take-in that
holds no call open survives a restart from its own state, and only an answer the manifest validator gave refuses (principles 1,
3 and 4). How it is checked: whole (indexer): a restart while the ask is out takes the revision in on the end; a
`could not run` end leaves it pending with `failed` and `indexer_validate_again` asks `<n>`+1; an end of a replaced
ask is dropped.
- §714 **Every watched branch's merges come on the forge bridge's stream, each naming its branch.** (ADR 0666 §6,
§11; §11, §13, §18, §493, A-90, A-93, A-208) This completes A-208's per-branch take-in. The forge bridge publishes
the merged message of every landed commit of every watched branch the registrations name, heard on `branch-moved`
and read by the seat `git`'s verb `branch` as §11 has it, the trunk's included, since from G no merge is the gate's
(ADR 0666 §11). The merged message (`forgemsg.Forge`) gains `base`, the watched branch it landed on; the forge
bridge's filters to the trunk alone (its merged message and its forge-made merge) go. The indexer's `pending` keeps
its key `m.<sequence>`, the stream's sequence being one across branches, and its value names `base`; a merge waits
only behind a pending value of its own `base` (§18), and is taken in by A-93's take-in of that branch. A value
written before G names no `base` and is the trunk's, the only branch the forge bridge published before G. The
gate's `source-moved` takes nothing in. Why: one take-in for every branch, from the stream every merge already
comes on, and no second source of the same merges (principles 1 and 7). How it is checked: whole (forge bridge,
indexer): a merge on `beta` publishes a merged message with `base` `beta`, pending behind a pending `beta` revision
while a `main` merge is taken in.
- §715 **A group gathers per watched branch, and its end names that branch.** (ADR 0666 §13; ADR 0633 §5; §42 to
§46, §293, §714, A-208) This completes §43 and §44 for a branch other than the trunk. A group's members on watched
branch B are those whose `base` in the seat `mesh-delivery`'s verb `groups` is B (its `Member` carries `base`). The
forge bridge sets the group on each landed member's merged message of any watched branch, and publishes
`forge.group.merged` (`forgemsg.ForgeGroupEnd`, gaining `base`) once `groups` says every member with that `base`
has landed, once per `base`. The indexer gathers the members in `pending` under `g.<group>.<base>`, each part
escaped as a key name, and takes them in as one source revision of B on that end, after §712's validation; a key
`g.<group>` written before G is the trunk's. `indexer_pending`, `indexer_take_in_pending`, `indexer_drop_pending` and
`bridge_group_end_again` take the `base`; a group that never ends on B is said at 30 minutes (§45). Why: a group
is delivered on the branch its members land on, read from the one verb that knows its members (principles 1
and 7). How it is checked: whole (forge bridge, indexer): two members landing on `beta` give one `forge.group.merged`
with `base` `beta` and one `beta` source revision; a group whose `beta` member never lands raises `take-in-waits`
at 30 minutes.
- §716 **The gate keeps a group's members from their announcement, in its states `deliveries` and `groups`, heard on
the seat `git`'s pull events.** (ADR 0666 §13; ADR 0656 §7; ADR 0633 §4, §5; §42, §43, §45, §151, §156, §613, §715,
A-236) This completes §42 and §715: ADR 0666 §13 has the gate form a group and its group verb say every member, and
before G's delivery the gate kept a group from the announcement in `deliveries` and `groups`, which §613 already
moves to template states under the same names; §716 has G's gate go on writing them. The gate's manifest `consumes`
the seat `git`'s `pull-updated` beside the `pull-merged` and `pull-closed` it consumes, through its one durable
consumer, and `invokes` `seat:git.open-pulls` and `seat:git.pull`. Each event carries the pull request's
repository, number, head, `base` and head branch (`branch`).
- **What it writes, in today's forms.** On `pull-updated` the gate writes the delivery under its id
`<repository>@<first 12 of the head>`, escaped as a key name, as today, with `repository`, `number`, `commit` (the
head), `base`, `branch`, `group` and `state` `open`; a newer head of the same pull request takes the older's place
in its group and the older key is deleted. Pull requests with one head branch form one group, keyed by that branch
escaped as a key name, its `members` the delivery ids, as today (§42): a group of one with no member in a record is
no group: its key is deleted and its member's `group` cleared. `pull-merged` sets the delivery's `state` to `merged`. A delivery copied from
before G (§613) in another state of the old table counts `open`. Only the gate writes either state.
- **Who deletes it.** The gate: a delivery on `pull-closed` of a pull request not merged; a delivery once the record
that carries it opens (§151's take-in, or §156's switch), its `base` copied onto the record's member (`RecordPull`
gains `base`) and, for a member with no delivery, the take-in's `branch`, said in its journal; a group key once no
member remains outside a record. A deletion is made in the old section too (§613).
- **How `groups` answers.** A group is answered from its records and its `groups` key together, each member once,
a record's first: a record's member with its copied `base` and `state` `merged`, a kept member with its delivery's
`base`, `head`, `state` and `open` while not merged. So before any take-in the verb names every member and its
base, and the forge bridge reads them as §715 has it (A-236).
- **When a member has landed.** For §715, a member has landed once `groups` says it `merged` and the bridge has
published its merged message. The bridge asks `groups` at each such message it publishes and at each
`pull-merged` it hears of a group it holds open (`bridge_groups`), so the end follows whichever comes last, never
a timer.
- **At its start**, after §613's copy, the gate reads `open-pulls` once and writes each open pull request it lacks
or keeps at another head. For each delivery it keeps `open` that the answer does not name, it reads `pull`: merged
sets `merged`, closed deletes it. A read that fails is said in its journal and made again at the next start. Until
then, a group whose end never comes is said by §45's 30-minute `take-in-waits`, and the indexer's
`indexer_take_in_pending` takes it in as gathered.
`merges` stays as §156 has it, read by the switch alone. Why: the gate forms the group and its verb says every
member (ADR 0666 §13), from its own states heard on the seat `git`'s events. It keeps the two states and forms it
already holds, adding no state and no new tool (principles 1, 4 and 7). A missed event is put right from the forge's
own record at the start, and a group that stays open is said (principle 3). How it is checked: whole (gate), two
pull requests on one head branch, bases `main` and `beta`. `groups` names both with their bases before any
take-in; a newer head replaces its member; a `pull-closed` before the merge removes it. A `take-in.taken` of the
`main` member opens a record with `base` `main`, and the `beta` member stays in `groups`. A `pull-merged` missed
while the gate was down is set from `pull` at its start. Whole (forge bridge): the group's end is published once
both the member's merged message and its `pull-merged` have come, in either order.
## The seats of the status view's and the assigner's views
- §717 **The status view's answers are a view of the seat `mesh-delivery-view`, the assigner's asks and wants are
views of the seat `mesh-wants`, and a follower finds each by its seat and starts without it.** (ADR 0540 §1, §6;
ADR 0429 §3; ADR 0567 §5, §6; ADR 0571 §6; ADR 0565; ADR 0539 §16; ADR 0596; §7, §200, §428, §532, §616, §699,
§710, §614, A-126, A-131, A-175, A-178, A-210, A-295) This answers developer J27's question of 2026-11-12, met building A-210
and A-296 (G-22): A-210 has a part find another module as the holder of the seat it holds, but the status view
claims no seat while the teller follows its `answers` by its module name, and the assigner holds two seats while
the teller follows its `asks` by its module name. It completes A-175 and A-178 for both views.
- **The seat `mesh-delivery-view`.** ADR 0540 §1 names the seat the status view holds, `mesh-delivery-view`; G
defines it. Its definition is in the Delivery domain's contracts module, `seats/mesh-delivery-view/` beside the
domain's other seats, with a states fixture as theirs have: `scope` mesh, `grain` whole, `domain` Delivery,
`decision` ADR 0540. It serves no verb and declares no seat event and no `family`: the status view's tools stay
its own (one seat, many tools), each caller reaching them at the holder A-210 finds, and its events `delivered`,
`moving`, `settled` and `stuck` stay the holder's own on the subjects ADR 0540 §1 names, so every `consumes` of
them keeps its entry and a part that builds their subject in code builds it from the holder A-210 finds. It
declares one state, `answers` (template state, history 5, `view: true` by §699), whose one key form is
`<ask key>.view`, `<ask key>` a key of the seat `mesh-wants`' state `asks` of a kind that needs no proof of who
answered, and whose value is the status view's answer: `v`, `asking` (the asking it answers), `option`, `words`.
Only the holder writes it, the person's answer in the web view, and only the holder deletes a key: once the ask's
key has left `asks`, heard on the `asks` view it follows, so no answer outlives its ask. The status view's manifest `claims` the seat with scope mesh and an empty `serves`. Its
first-view tool of `answers` is named for the state, `answers` (mesh-sdk's `views.ReadTool`, the teller among
its callers, A-131's form), in place of A-178's `view_read_answers`, which goes.
- **The seat `mesh-wants` owns `asks` and `wants`.** Every kind the assigner keeps in its state `asks` (hold,
restore, backup, record, outside, revert and a placement proposal's `assignments`) is an ask whether what a node
runs moves, and ADR 0567 §6 names the states of `mesh-module-assigner` without `asks`, so `asks` is a state of
`mesh-wants`: its definition gains `asks` (template state, history 5, `view: true`), its key forms the eight kinds'
keys as the assigner's `asks` package writes them, its value the ask as the assigner composes it. Its `wants`,
which the definition already declares, gains `view: true`. The holder's first-view tools are named for the
states: `wants`, as it exists, and `asks`, new, in place of `assigner_read_asks`, which goes.
- **The followers name the seat.** The teller's manifest `consumes` `seat:mesh-wants.views.asks` and
`seat:mesh-delivery-view.views.answers` in place of `mesh-delivery-assigner.views.asks` and
`mesh-delivery-view.views.answers`, and its `invokes` loses `mesh-delivery-assigner.assigner_read_asks` and
`mesh-delivery-view.view_read_answers`, the seat-form `consumes` covering each first view (A-131). The status
view's manifest `consumes` `seat:mesh-wants.views.asks`, `seat:mesh-wants.views.wants` and
`seat:mesh-module-assigner.views.assignments` in place of the three `mesh-delivery-assigner.views` entries, and
its `invokes` loses `assigner_read_asks`, `assigner_read_wants` and `assigner_read_assignments`. Neither part's
code names the assigner or the status view (§7, §428).
- **What the seat form puts on the bus.** A seat's view is said where its holder says it, on the holder's own
subject `mesh.mod.<holder>.event.views.<state>`, and the grants part resolves a `consumes` entry
`seat:<seat>.views.<state>` to that subject for the seat's holder on record, granting nothing while the seat has
none (§616). The subject is module-scoped, so a follower must know the holder, and follows it as it moves.
- **A follower finds and re-finds the holder from the seat-holders view.** mesh-sdk's `views.ProcessReader` gains
`FollowSeat`, given a seat and a state, and the holder function A-295 gives a part, which answers from what the
part last heard of the seat `mesh-module-assigner`'s view `seat-holders`. The part follows that view as the tool
runner does (§616): the module that claims `mesh-module-assigner` is read from the catalog half the part follows
(§614, the trunk's entry whose manifest `claims` the seat), so no code names the assigner's module; the view is
named `seat:mesh-module-assigner.views.seat-holders` in the part's `consumes`, its first view asked of the
claimant's tool `seat-holders`, and a catalog revision naming another claimant drops it and follows the new one
(§532). `FollowSeat` returns at once a picture that reads as empty, its follower not ready, and never fails for
want of a holder. At each change of the seat-holders view it reads the seat's holder: on a first holder it follows
as `Follow` does after `Start` (§532), the first view asked of the holder's tool named for the state, then its
views family; on another holder it drops the view of the old one and follows the new one, the picture handing on
the new holder's state whole; with no holder it keeps the picture it has and follows nothing. Nothing is asked
again on a timer. While no holder is followed the follower's status names the seat in place of its owner, waiting
since its start or since its holder left, and past five minutes the reader writes §200's `view-waits` naming the
seat and the state, cleared when a holder's first view arrives. The teller's two follows and the status view's
three go through `FollowSeat`, each apart, so the teller raises the assigner's asks whether or not the status
view's answers are read (issue 1906, as today); the teller gains the catalog half's reader of §614 for this. The
builder's and the checker's own loop for the assignments, buildrun's `AssignerHolder`, which asks every 5 seconds,
goes: both follow `assignments` through `FollowSeat`. `seatlist.HolderOf`'s call stays for a caller that asks
once, as A-210 has it.
Why: ADR 0540 §1 already names the seat the status view holds, and §616 and §699 give a view named by its seat;
`asks` goes where the kinds it holds belong, its proposal kind kept with them so the teller follows one view. The
holder is heard from the seat-holders view as A-295 has it, never asked on a timer, and a moved holder is followed
as it moves (principles 1, 3, 7 and 8). How it is checked: unit (mesh-sdk `views`), a `FollowSeat` with no holder
returns at once and writes `view-waits` naming the seat past five minutes; a seat-holders change naming a holder
takes its first view from `<holder>.<state>` and hears its family; a second change naming another holder drops the
first and follows the second; no ask is made between changes. Unit (manifest validator):
`seat:mesh-delivery-view.views.answers` and `seat:mesh-wants.views.asks` are accepted, and a seat view of a state
without `view` is refused. Whole (teller): started before any module holds `mesh-wants`, it raises an assigner's
ask once the holder is placed, and takes an answer the status view writes. The code review: no module name of the
assigner or the status view in the teller's, the status view's, the builder's or the checker's code, and no
timer that asks for a holder again.
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,209 @@
---
layer: to-be
status: in-progress
design: 47
milestone: G
updated: 2026-11-17
decisions:
- "ADR 0667"
---
# 47, milestone G — what is owed once G is delivered
The list of what waits for G's delivery: the operator's remarks deferred while G was brought up, the stand-ins the
lead's answers mark to go after G, the hand state of G's live start, and the faults met on the way. It is checked when
G is delivered: each item is then removed, taken into a design or a record through its playbook, or noted on the issue
that covers it (asking the operator before a new issue). An item is struck from this list in the same pull request that
deals with it, which is how the list is kept true.
## The operator's remarks (2026-11-14, deferred until G is live)
1. **Two graphs only:** the catalog graph and the assignment graph. Each node's modules publish the state they own and
the version they run on the bus; a gap between the assignments and what a node says is closed by the node-engine.
2. **What a node can run is checked only on assignment and un-assignment** (for the modules that depend on it), never
as an input to every computation. The glossary's *assignment graph* and ADR 0656 say the assigner computes from the
catalog graph, the placements and the nodes' capabilities: check the record and the code against this.
3. **Assignments enter as commands** (the seat `mesh-module-assigner`'s `propose`: place, take off, ...); the assigner
computes no placement, it only derives each placed module's version from the catalog graph into the wants. Check the
glossary's wording against this.
4. **A pin** ("use this provider for this provision") may not belong in the assignments at all: question it, and what
the provision wiring should be instead.
5. **Who says a node's running versions:** the node-engine (its haves) or each module itself. The operator's picture
is each module; check which the design means.
6. **One address for a seat's view.** A reader's manifest names the assigner's view by its seat, the reader's code asks
the holder module's tool by its module name, and the grants part translates one into the other (and gave only the
events, not the right to ask: the indexer's first view was refused at G's live start). One address, the same in
manifest, code and rights.
7. **A registration is part of the module graph, not a list beside it.** After G's start the module graph held 178
modules while the registrations held none, with a seed ask to copy them from the old registry. Check the design
against one graph whose entries are the registrations and what each registered repository says.
8. **One bookmark (durable consumer) per process, never shared** (A-397). A module's program and its tool runner read
events under one durable name; the runner took all 178 first registrations and the program heard none, silently.
Share a durable name only for shared work (a queue). Owed: amend design 19's "one durable consumer per module"
(written when a module was one process) and the lines of designs 25, 32 §3, 57, G-5 and G-8 that follow it; build
per-process names in the grants part, mesh-sdk's process hub and the tool runner, with a start refusal and a log
line; the test of two processes of one module both hearing one event on a real bus; a check that a durable has one
reader; and a design-review playbook question: "what if two processes of one module do this?"
9. **The same mistake elsewhere.** A survey at G's start found it live in three modules (the assigner, the indexer and
the grants part: the runner acks and drops what no tool view wants) and possible in every module whose tool runner
arrives later (builder, checker, forge bridge, pipeline runner, teller, view, watchman, distribution, recovery).
Already avoided: the bus and zfs keepers (A-340), the node-engine, work queues. Also: a seat verb served by both a
program and its runner in one queue group splits the answers between them; durables nothing reads keep pending
messages.
10. **`registration-changed` is said for a first registration too:** check the event's name against what it says.
11. **Silent waits met during G's start:** the indexer's first versions fill returns without a word while another fill
runs, so a hung fill held every later one silently for two hours; `grants_membership` and `grants_assert` time out
after 30 seconds with no log line; the tool runner says a dropped event once per key.
12. **The module graph's edges are dependencies, never verbs or bus subjects** (2026-11-16; principle 9): a manifest
says what its module depends on, a seat where the need is meant to be interchangeable and otherwise a module (a
build dependency on a package module, a program needing another module), and the graph's edges come from that
alone. The verb edges of ADR 0614 §2 and §3, and the cycle exceptions they needed (A-361, A-428, A-437), go; whether
`invokes`, `uses` and the `views` forms stay in a manifest at all is asked with the research on the mesh's
accounts, and "each fact is declared in one place".
13. **A full delivery cycle by hand** (the operator, 2026-11-17 about 09:00: "make sure that every part of the
build-and-delivery system is also doable by hand via mcp tools", "so you can fully take control of a full cycle";
asked when, "after G"; principle 4). A survey of 2026-11-17 found, along the cycle merge, the gate's source,
take-in, entries, pipeline, steps, release, wants, grants, put and running: about 52 acts a module does by itself
with no hand tool, about 110 bus states with no per-key clear and 26 with no read tool, all but one of about 25 capped
states with no fill against their cap, and 14 recoveries with no tool. One milestone: the SDK's state tools for
every declared state (read, fill against cap, clear a key, drop key-gone objects), the missing hand acts per module,
a summary of the pipeline runner's pipelines by outcome, `source-moved` and the runner's `ended` declared so they
can be waited on, and the catalog check that refuses a module whose state or act has no tool. Also a consumer
composed from the union of the want's and the trunk's manifests, as grants already are (a bundle's new `consumes`
is unbound until a want names its build).
14. **No pass waits on a call** (principle 1; from the node-engine's #233 (`mesh-host`), A-461b): the node-engine's composer asks the seat
mesh-catalog's `module` for a trunk build at the top of every pass and waits up to the call's bound, so a seat that
answers slowly stalls every pass. The ask goes beside the pass, which composes with what it holds and takes the
answer at the next pass.
## Met during G's start (2026-11-14)
- **The seed of registrations** left out modules whose manifest lives in the application's own repository on its
watched branch, so they were assigned but unheld and the assigner refused every proposal (ADR 0567 §2). The seed
should register every assigned module from where its manifest is.
- **The indexer's catch-up and take-in** say nothing in the indexer program's journal.
- **The provisioner** drops a published composition with neither plan nor refusal silently and then removes the
node's plans; no read tool shows a node's composition.
- **The node-engine** is refused the builder's `build.ended` by the bus every five minutes: the grants part does not
give it; to fix before builds matter.
- **The register verb refuses an unprotected watched branch:** the operator approved removing the check (from the
seat `mesh-catalog`'s definition and the indexer that serves `register`).
## Stand-ins the lead's answers mark to go after G (2026-11-16)
- **A-436 with A-430b:** a want carries parts beside its version for a node-engine that reads parts, and a module
wanted with no passed pipeline names the parts its `build.ended` made until its release is heard.
- **A-438:** for an acting wait, a running have whose node-engine states no health counts as healthy, and an online
node runs its node-engine; goes when every node-engine states health.
- **A-439:** `assigner_written` with `why` answering for `assigner_why`.
- **A-434:** every account may do everything, and every seat verb admits every caller, until the research on the
mesh's accounts replaces it (the operator, 2026-11-15: three accounts, mesh, agent and operator; approval only as a
per-tool mark for agent calls).
## Hand state of G's live start (2026-11-16)
- **Runtime drop-ins on the control-node** that pin a hand-made fingerprint (and the tool runner's environment) for
the grants part, the teller, the forge bridge and the tool runner. A delivery does not remove them: each goes before
its module restarts on the delivered build, or the module believes it runs the old one.
- **Hand-placed builds** (the indexer and its tools, the tool runner, the control-node's node-engine, the assigner) are
replaced only by their deliveries; check each is.
- **About 80 hand-built modules on the control-node have no catalog entry:** their first move is held for a backup
(the kept-form hold).
## Faults met on the way (2026-11-16; note each on the issue that covers it)
- `node-files.delete` cannot move a root-owned file to the trash; `node-service-manager` has no daemon-reload.
- The indexer does not stop on SIGTERM: it keeps draining build-log entries until systemd kills it.
- The backup ask's headline says "backup failed" for a kept-form hold.
- The assigner logs a line naming about 140 modules every one to three seconds, and did not raise the backup ask
again after a restart.
- `mesh_wait` refuses the operator channel's events: `operator-channel` is neither a seat nor a module of the catalog
half.
- Four tests of mesh-delivery fail on main, reading files that do not exist there: `sdk`'s
`TestThePackageArtifactNamesNoPathForTheWholeDirectory`, `sdk/buildstep`'s two fixture tests and
`meshdeliveryclient`'s `TestTheRemovedVerbsAreTheDefinitionsRemovedRows`.
- The node-engine's repository holds about 1721 unit tests against the budget of 500.
- The live indexer was seen refusing the assigner's manifest for claiming `mesh-placement`, which neither main nor
G's branch claims: confirm the verdict after G's take-in.
## Tests run against what runs (the operator, 2026-11-16 about 13:00 CET)
- **A test runs against the bus as the mesh composes it.** The pipeline runner's integration test made its own
shared event stream catching every seat event, so a step's end reached the runner there; on the live bus a step's
end is a kept event on a stream of its own, which the runner never bound, and no pipeline could pass (fixed in the
runner at G's start, 2026-11-16). Wanted: a principle ("a test runs against what the module runs against: the bus as
the mesh composes it from the manifest, never a layout written in the test"); the shared library gives an
integration test the streams, kept streams and consumers the composition makes for the module's manifest; every
integration test that creates its own streams moves onto it (count them first); the runner's test publishes a step's
end on the kept stream.
- **A handler of a kept event is heard or fails loudly.** Starting a program's events binds only the shared stream;
kept seat events need a second call, and a program that registers a handler for one and never makes it hears
nothing and says nothing. The shared library binds the kept streams of every registered handler itself, or refuses
to start.
## One way of asking work (2026-11-16)
- The builder, the pipeline runner, the indexer (its validation before a take-in) and the checker each ask the build
seats in a shape of their own; the validation rides the check queue behind pipeline steps (a 6-second validation
waited over 20 minutes). Parked by the operator for research right after G: one generic pipeline for work and gates.
- An ask given again after a fix keeps its old form (a step asked with no module directory came back without one).
- The builder asks a failing build again every two to three minutes, reserving a new version each time.
- The builder's queue tool lists only the oldest 50 waiting entries (left over from 2026-11-14), so it cannot show
what waits now.
- The pipeline runner serves no tools on the control-node and logs nothing per step; the build seat's step events say
no pipeline before a step ends; `mesh_wait` refuses the build seats' and the runner's events; the bus's stream reader
cuts a body at 4 KiB; a running test step logs nothing.
- `TestTheBuildModulesKeepNoCopyOfTheDeliverySDKsStepCode` fails on mesh-catalog's main (the empty
`modules/mesh-build-go/buildstep` directory); the seven `checks/` tests, nats-tools and distribution fail in a run over
the whole of mesh-catalog.
- The glossary's **pipeline** and **pipeline step** entries leave out the build, which the runner asks as the step
`build` of the seat `mesh-builds`: correct them.
- A pipeline the runner set aside before A-446 with steps already written (`main.940.mesh-delivery-sdk`) is started
again by neither of the runner's start paths.
- The node-engine's journal and the have's phases say a module is "held" and that the node "keeps running what it
runs" for one thing: a module left on the build it runs, its new build not applied. The operator, 2026-11-17, wants
those words gone: retire "held" and "kept" in that sense from the node-engine's lines and the glossary, with one
glossary word in their place.
- A composition that passes on every machine as "not judged: the composer was handed no seat list" is reported as
passed: a composition step that judged nothing must fail or say so (principle 3).
## From the composition runs of 2026-11-17
- **The node-engine answers `compose-candidate` with different bytes for one candidate.** Within 30 seconds the
assigner kept twelve inputs of exactly 1,491,623 bytes with different digests for the same revision. The bytes differ
in the node-engine's answer, not in the assigner's request; a guess, not checked: a slice whose order changes between
asks, perhaps `ComposedHow.Running`. Under design 47 G §718 one composition run per candidate and machine asks each
node once, so this no longer multiplies anything and stays out of G (principle 7; the coordinator, 2026-11-17). After
G: find it by comparing two kept inputs of one node, read by digest through `mesh-wants`' `input`, and decide whether
the answer must be the same bytes while the node is unchanged.
- **Design 47's main file and G-22 are split** (playbook 02, *The shape of a design*). The main file is about 250 KB
against its 80 KB bound, and G-22 about 165 KB against a milestone file's 60 KB. The operator decided at 10:31 CET on
2026-11-17 that the split comes after G, as a separate amendment.
## Faults met on the way (2026-11-17; note each on the issue that covers it)
- **The assigner's long line, met a second time.** On 2026-11-17 from 11:02 CET the assigner on the stable node logs,
several times a minute, that "the manifest of the running build of" about 100 modules "cannot be read, so what the
module graph says they serve is counted as served". Cause not yet known: nearly every module is named, so the
assigner reads the running builds' manifests where none is kept. Being the second meeting, its fix is folded into
G-24's assigner change once A1 to A7 are built. Cause found the same day: the assigner reads a running build's
manifest only from the builder's end in its stream, which the builder has said only since 2026-11-11, so no build
made before then has one. G-24 says the list once per change of the set; after G, the builder says the end of each
build it keeps into its stream once (principle 1; the alternative, reading the catalog entry at that fingerprint,
reads another module's data).
- **The Node build modules disagree on their toolchain.** On 2026-11-17 shanks's recipe differed from the other three
nodes', and g14 ran Node v26.13.1 against v26.13.0, so no version and recipe held a majority, and lidarr, radarr and
gitea had no fingerprint at revision 449 (A-470j keeps that from leaving whole machines not judged). After G: one
version and one recipe declared through the mesh on every build node.
- **The catalog had not taken in the node-engine's merge #234** by revision 450 (2026-11-17 about 11:50 CET), and the
indexer's module reads answered "no responders": read why after G-24's delivery.
- **The builder's and teller's integration tests fail only the 30 s setup bound under load**, and pass idle: the bound's
kind (a setup bound judged on a busy build node) is decided after G.
- The runner's journal floods with ends that name `pipeline ""`: the build seats' run asks are heard on the runner's
subjects.
- `TestAProposalIsAnsweredApprovedAndWritten` (assigner) fails on main; `TestTheNodeComposesItsWantsFromTheBus`
(node-engine) fails now and then.
- `mesh-enrolment` is placed on no node, so its composition step can never run and it never releases.
- `claude_code_wait`'s `said` refused a wait past its bound; `mesh_wait` cannot wait on the gate's `source-moved` nor on
the runner's events.
@@ -0,0 +1,290 @@
---
layer: to-be
status: in-progress
design: 47
milestone: G
updated: 2026-11-17
decisions:
- "ADR 0667"
- "ADR 0666"
- "ADR 0596"
- "ADR 0564"
- "ADR 0267"
---
# 47, milestone G: one composition run per candidate and machine, one test run per level and tested packages
One file of milestone G's part of [design 47](../47-delivery-from-commit-to-delivered.md); the part opens at
[G.md](G.md). Its design lines are numbered across every file of the part and cited as "design 47 G §n".
*§718 to §733 come from milestone G's live delivery of 2026-11-17. The 24 pipelines of one catalog revision asked 96
composition runs, one per pipeline and machine, and 80 more when they were asked again. Each run kept its own copy of
a node's input of 1.1 to 1.5 MB in the assigner's state `inputs`, which reached its 64 MiB cap twice. The indexer's
and the teller's same failing tests failed once per artifact. The operator, 2026-11-17 about 10:20 CET: "In G, now".
Each line is a choice within ADR 0666 §7, §8 and §17, settled by the principle it names. The review by architectural
domain of 2026-11-17 was answered by the lead in A-466 to A-466l (G-22), each cited at the line it settles.*
### Composition runs
- §718 **One composition run per candidate and machine.** (§354, A-226, A-243, A-252, A-466l; ADR 0666 §17; principle
7) The assigner, holding the seat `mesh-wants`, composes each machine once per candidate, whatever number of
composition steps name it. The candidate is named by its key (A-226): `<branch>.<revision>` for a branch pipeline,
`run-<id>` for a run on request. The first composition step of a candidate that needs a machine starts that machine's
composition run: one `compose-candidate` ask of the node, its request kept once in `inputs`, one `run` ask on
`node-build-go`. Every other composition step of that candidate whose module is placed on that machine (A-252) reads
that run's verdict, under §720's rules. The request carries the candidate's manifests, verdicts and seat
definitions, depth compose, the one machine and the case `change`, and the node's own `compose-candidate` answer at
the moment the run started; it carries nothing of the module whose pipeline asked it. A step of the same candidate
that comes later so reuses a verdict composed from the node's answer of that earlier moment, knowingly: within one
candidate, that answer is the machine as the candidate is judged on it (A-466l). The composer program is chosen once,
when the run starts, by A-252's and A-451's rule, and recorded in the run. This replaces "one run ask per machine" for
each composition step (A-243, A-252) with one per candidate and machine.
- §719 **Kept in the assigner's state `composition-runs`.** (§354, §85; ADR 0666 §4, §7; A-466e; principles 1, 2, 7 and
11) Each composition run is one key of the assigner's old `state` section `composition-runs`, whose `max-mib` is the
assigner's setting `composition-runs-cap-mib`, default 16. The key is `<candidate key>.<machine>`, each part escaped as
a key's name (`keys.EscapeName`). The step that starts the run writes the key create-only, so two steps of one
candidate starting at once start one run and the second reads it. The value holds:
- `candidate` and `machine`;
- `program`: repository, commit, directory, and the node-engine fingerprint it was chosen from;
- `input`: the digest of the kept request;
- `ask`: the id of the build seat's run ask;
- `started`;
- `readers`: the step keys of the composition steps reading the run, each added and removed by compare-and-set;
- at the run's end, `ended`, `outcome` (`passed`, `failed` or `could not run`, with its words) and `verdict` (that
machine's composer verdict, §721).
A step waiting on a running composition run hears its end through the assigner's own watch of that key (a module
watches its own state, principle 1). At its start the assigner takes up again each key with no `ended`, by its
`ask`'s `step-ended` (A-240) and the bound of §720. The assigner deletes a key once the time its setting
`composition-runs-kept`, default 24 hours, names has passed since its `ended`; both this and the bound are judged as
the state `inputs` is (A-465b). At the cap no run is started, and its steps end `could not run`, naming the fill (as
A-465a).
- §720 **What a run's result serves, and its bound.** (§75, §86, §718; ADR 0666 §8, §17; ADR 0596; ADR 0564 §2;
A-466, A-466b, A-466n, A-466p, A-466q, A-466s; principles 1 and 3)
- **Within its candidate only.** An ended run's verdict is read only by composition steps of the same candidate. A
step of another candidate starts a run of its own; nothing composed for one candidate crosses to another.
- **`could not run` is never read.** A step that finds an ended run whose outcome is `could not run` starts a new
run, replacing the key by compare-and-set; its former readers have already ended `could not run` with it.
- **The bound times owed progress, not run length** (§75; ADR 0564 §2; A-466n, A-466p). A run has one clock: a bound
key `bound.<run key>` in `composition-runs`, with its own time to live (A-77, A-101). The assigner writes it at
the build seat's `ask-taken` of the run's ask, and writes it again at each `step-progress` of that ask, its time
to live the assigner's setting `composition-step-bound`, default 30 minutes. An ask still waiting in the queue has
no clock: it is timed by §86's build-capacity finding, since a `could not run` for a run that only waited for a
build node would say what is not true. A run that runs past 30 minutes and keeps saying its progress is never
ended by it.
- **When the clock ends.** Its expiry, heard as the bus's event, ends the run: the assigner drops its ask (§119,
A-182), writes `ended` with `could not run` naming the ask and the bound, and ends every reader `could not run`
with it. A `step-ended` of that ask heard later is ignored, said in its journal with the ask and the run's key.
- **A run never taken** (A-466s). A run whose ask has no `ask-taken` within the assigner's setting
`run-untaken-bound` after its `started`, default 24 hours, ends `could not run` the same way, naming the bound;
§86's `build-capacity-waits` says it meanwhile.
- **What the assigner hears** (A-240, A-466q). Its manifest gains `consumes` entries for the build seats'
`ask-taken` and `step-progress`, heard on its durable consumer as A-240 hears `step-ended`. The assigner never
reads the build seat's state (ADR 0596).
- §721 **A machine's verdict names the modules it blames.** (ADR 0666 §17; A-452, A-466g, A-466h, A-466r, A-466u; principles 10, 3, 7
and 11) The composer's verdict of a machine (mesh-delivery-sdk's `composer.Machine`, answered by the node-engine's
`mesh-compose`) gains `blamed`, a list of `{module, problem}`.
- **What it names.** Each module that the candidate's composition of the machine holds or refuses and the
composition without the candidate does not (the modules in its input's `HeldBefore` are left out). Two modules
owning one path are each blamed, with that path. `composes` stays false when the machine does not compose with
every module of the candidate. A machine that does not compose and blames no module fails on the node's own
account (its own composition, or no module composed at all, as A-452 has it).
- **How culprits are found, and its bound.** Only the candidate's changed modules placed on the machine (those whose
entry in the candidate differs from the composition without it) are held, one at a time, each try composing once
more; the search ends at the first module whose hold ends the problem, as the indexer's validator names a manifest
whose removal ends a problem. It composes at most once per such module plus once, never more than `blame-tries`, the
assigner's setting, default 20, carried in the run's request to the composer (the request's field
`blame-tries`), since the composer program has no settings of its own (A-466r); past that bound, the modules not yet tried are named in `blamed` with the words
"not tried: the search reached its bound".
- **An old composer.** A verdict with no `blamed` field (a node-engine's composer from before this line) is judged as
today: a machine that does not compose fails every composition step placing a module on it, with the warning "the
composer names no culprits".
- **No order between them.** mesh-delivery-sdk's `composer` package is published before the node-engine and the
assigner build (an edge of kind 1, as for every package); nothing orders the node-engine's composer before the
assigner, since an assigner meeting an old composer judges as today (A-466u).
- §722 **One module's fault fails only its own pipelines.** (§721; ADR 0666 §9, §17; A-452; principles 10 and 3) A
composition step judges each of its machines from that machine's verdict:
- `failed` when the verdict blames the step's module, or when the machine does not compose and blames no module;
- `could not run` when the composition run could not run;
- `passed` otherwise, with a warning for each module blamed there that is not the step's own (`<machine> holds
<module>: <problem>`). Another module's fault is so said in every pipeline it touches and fails none of them.
The step's outcome then follows from its machines, as today: failed before could not run before passed (§354). A
machine that is away passes with a warning and is not composed (§64).
- §723 **How a composition run ends and is said.** (§73, §116, §119, §496, A-182; ADR 0666 §7, §21; A-466j;
principles 1, 7 and 8) A composition run says no event of its own. Its end is the build seat's `step-ended` of its
`ask`, which the assigner alone hears (A-240). Each composition step reading the run says its own `step-ended` on
`mesh-wants`, as today, with its own build-input fingerprint and `shared` (§729), naming per machine the run it read,
that run's `ask` and its verdict: the result was taken from the build seat's holder once, at that ask, and the step
names it, as §25's carry names where a carried result came from (ADR 0666 §21). Each reading step says its
`step-progress` once a minute while it waits (A-262), naming the runs' asks in `shared`. A step that is superseded or
cancelled leaves `readers`. The run's `ask` is dropped (§119, A-182) only when no reader is left, so a superseded
pipeline never takes away another pipeline's composition run.
### Test runs
- §724 **One test run per level and tested packages.** (§22, §25, §27, §416; ADR 0666 §8, §17; ADR 0267 §1; A-466,
A-466d; principles 3 and 7) The runner asks a lint, unit test or integration test step of a build seat once per
candidate, level and tested packages, whatever number of artifacts' steps name them. A test step's candidate is its
pipeline's in A-226's form: `<branch>.<revision>`, or `run-<id>` for a run on request. A module's program and its
tools bundle are built from different import closures (ADR 0267 §1), but their test steps run the packages of one
directory (the build seat's `steps`, §22), so one set of tests is run. The share digest is the sha256 of:
- the step's build-input fingerprint with the artifact's own part left out (its program's package and recipe), so two
artifacts of one directory meet;
- the step's status in the policy (§23), so the key is §25's carry key: two artifacts whose policies differ do not
share;
- the sorted lines `<package>@<digest>`, one for each package the step would run after its carry (§25: those with no
kept result for their digest), the digests being those the runner already reads for its carry (§416).
The first step of a key puts the build seat's `step` ask; every other step of the same candidate with that key reads
its result. An ended run's result is read only within its candidate; a step of another candidate asks a new run, and
a passed result crosses candidates only as §25's carry, through `kept`. A `could not run` result is never read: a
step finding one asks a new run, replacing the key by compare-and-set. So within a candidate the same failing tests
fail once, not once per artifact, and a second revision with the same digests runs a failed test again.
- §725 **Kept in the runner's state `test-runs`.** (§27, §85, §330; ADR 0666 §4; A-466e, A-466f, A-466p, A-466v; principles 1, 2, 3, 7
and 11) Each test run is one key of the runner's old `state` section `test-runs`, whose `max-mib` is the runner's setting
`test-runs-cap-mib`, default 16. The key is `<candidate key>.<level>.<digest>`, each part escaped as a key's name,
written create-only by the step that asks the run. The value holds:
- `level` and `digest`; the list of packages with their digests is in the run's output object, never in the key or
the value;
- `seat` and `ask`, and `node` once a holder has taken the ask;
- `started`;
- `readers`: each reading step's pipeline key and artifact, added and removed by compare-and-set;
- at the run's end, `ended`, `outcome`, its test counts, and the name of its output object.
A test run's output object is kept in the state's own object store `test-runs-objects`, an old `objects` section
with no age of its own, so it lives exactly as long as its key, whatever `step-outputs`' 7 days (A-466v); a step's
own output stays in `step-outputs` as today. A reader whose run's object is gone (a drop, a fault) answers its run
without the packages, saying "the run's output is gone".
The runner hears the run's end as the build seat's `step-ended` of its `ask`, on its durable consumer, as it hears
every step (§24). A test run has §720's one clock, a bound key `bound.<run key>` in `test-runs`, written at the
build seat's `ask-taken` of its ask and again at each `step-progress` of it, its time to live the runner's setting
`test-step-bound`, default 30 minutes; an ask still in the queue is timed by §86's build-capacity finding alone. Its
expiry ends the run as §720's does: the ask dropped (§119), every reader ended `could not run`, a later
`step-ended` of the ask ignored and said in the journal. A run whose ask is never taken ends `could not run` at the
runner's setting `run-untaken-bound`, default 24 hours after its `started` (A-466n, A-466p, A-466s). The runner
consumes `ask-taken` already (§647); its manifest gains `step-progress` where it does not consume it. At its start the runner takes up again each key with no `ended`, by its
`ask` and that bound. It deletes a key once the time its setting `test-runs-kept`, default 7 days, names has passed
since its `ended`, in the step log's order as §330 ages its `pipelines`, and deletes the run's output object from
`test-runs-objects` with the key, after the last reader's end. At the cap no run is asked, and the step ends `could not run`, naming the fill, as
§719 has it, with no condition of its own. A passed run's results go into `kept` per package, as today (§27), so a
step asked after the key is deleted carries them.
- §726 **How a test run ends and is said.** (§24, §73, §119, §419, §496; ADR 0666 §8, §21; A-466i, A-466j; principles
3, 7 and 1)
- **Each reading step is said.** Each step reading a test run says its own `step-started` and `step-ended`, with its
own build-input fingerprint and `shared` (§729). Its `step-ended` carries the run's outcome and counts. Its
`step-started` names the run's `ask`, so the watchman times it from that ask's `step-progress` (§496). The result
was taken from the build seat's holder once, at that ask, which the step names, as §25's carry does (ADR 0666 §21).
- **Counted once.** `pipeline-ended` counts a module's tests once per pipeline and test run, never once per step
reading it (§24, §419).
- **Dropped only with its last reader.** A step that is superseded or cancelled leaves `readers`, and the run's ask
is dropped (§119) only when no reader is left.
### For both kinds
- §727 **Asking a run again moves every reader.** (§30, §73, §83 `rerun`, §29; ADR 0666 §9, §11, §24; A-466a;
principle 3) One rule for composition runs and test runs. A `rerun` of a composition step (for each machine whose
verdict in it was not `passed`) or of a test step joins the run of its key while that run is running, reads one that
started after the step's last end, or otherwise starts a new run, replacing the ended key by compare-and-set and
carrying the former run's `readers` into the new value. The new run's end moves every step that read the former run
and did not pass: each says `step-ended` again with the new outcome, marked as a rerun with the caller of the step
asked again (§73). A moved step reopens its pipeline, which says `pipeline-ended` again with a higher end count; the
assigner writes wants only from a pipeline's latest end (§29). A step a person `accepted` (§30) does not move: a
person's act stands. A machine that passed in a composition step keeps its verdict. A step left reading a failed
result would say what is no longer true. So twenty composition steps of one revision asked again together start one
run per machine.
- §728 **The tools.** (§83, §391; ADR 0666 §25; A-466c; principle 4) Two for each new state, in §83's table:
- `assigner_compositions` (class `read`) takes a candidate, a machine, or neither, and answers each composition run
with its program, input digest, ask, readers, outcome and verdict, and the state's fill against its cap.
- `assigner_compositions_drop` (class `act`, §391's default callers) takes `{candidate, machine, why}`. It writes the
hand-act log first, drops the run's ask, ends each reader `could not run` naming the drop, and deletes the key.
- `runner_test_runs` (class `read`) takes a candidate, a level, a digest, a module, or none of them, and answers each
test run with its packages (read from its output object), ask, node, readers, outcome and counts, and the state's
fill against its cap.
- `runner_test_runs_drop` (class `act`, §391's default callers) takes `{key, why}` and does the same as
`assigner_compositions_drop`, deleting the run's output object with the key.
- §729 **`shared` in the seat contracts.** (§73, §116, §496; ADR 0666 §21, §24; A-466j; principles 1 and 8) The seat
definitions in mesh-delivery's `mesh-delivery-contracts` change, and the contracts' code is generated from them by
`seatgen`, never edited by hand:
- **`mesh-wants`' `step-ended`** gains `shared`: a list of `{machine, run, ask}`, one per machine composed, `run` the
`composition-runs` key and `ask` its run ask's id, all strings.
- **The composer's request** (mesh-delivery-sdk's `composer.Request`) gains `blame-tries` (a number, §721).
- **`mesh-wants`' `step-progress`** gains the same `shared` list, naming the runs the step waits on.
- **`mesh-pipeline-runner`'s `step-started`** gains `shared`: `{run, ask}` for a test step, `run` the `test-runs` key
and `ask` its build seat ask's id, strings.
- **`mesh-pipeline-runner`'s `step-ended`** gains `shared`: `{run, ask, asked-by}`, `asked-by` being `{pipeline,
artifact}` of the step that asked the run (strings), left out for that step itself.
- **`mesh-pipeline-runner`'s `stands`** answer: each entry gains `ask` (string) and `shared` (`{run, ask}`, strings,
where the runner knows it), as §731 says.
A step that names `shared` names its own build-input fingerprint beside it, as every `step-ended` does (§73). A
composition step's `step-started` is said by the runner when it asks the assigner, before any run is chosen, so it
cannot name the runs' asks; the assigner, the part that knows them, names them in its `step-progress`, and the
watchman times a composition step from that (§496, A-262, A-466m).
- §730 **What runs in flight, and going back.** (§65, §78; ADR 0666 §19, §24; ADR 0667 §9; A-466k; principle 3) A
composition step or test step asked before the new assigner or the new runner runs ends by the path it was asked
under, one run per step; composition runs and test runs are made only for steps asked after the new part runs. A
return to an earlier build (§78) leaves `composition-runs` and `test-runs` unread; their readers are ended `could not
run` by the bound of §720 and §725 once the new build runs again. Until then the earlier build applies no such bound,
and a reader standing still is said by the watchman as `pipeline-stands`, by §732 (A-466o).
- §731 **The runner's `stands` names what a reading step waits on.** (§75, §83; A-466t; principles 3 and 4) `stands`
already answers every pipeline step started and not ended whose outcome is running or waiting (mesh-delivery's
runner on main, its `Stands` read), so a composition step waiting on the assigner is in it. Each of its entries
gains `ask`, the step's own ask (§496), and `shared` where the runner knows it (§729, a test step's run key and
ask). At its start the watchman seeds §732's open steps from it, each clock begun at that moment, and times each by
those asks from then on.
- §732 **The watchman times every step that reads a run.** (§75, §496, §602; ADR 0564 §2, §4; ADR 0666 §24; A-466o;
principles 3 and 1) §75 and §496 time each pipeline step from its `step-started` or its latest `step-progress`, but
the watchman on main times only a build seat's running ask (its `ask-taken` and `step-progress`) and a step queued
for a build node; a step whose run has ended, or a composition step waiting on the assigner, is timed by nothing.
From G the watchman also:
- **hears** the runner's `step-started` and `step-ended` of every pipeline step (it consumes them already, for the
build capacity), and `mesh-wants`' `step-progress`, a `consumes` entry its manifest gains;
- **keeps** each started step with no `step-ended` in memory under `<pipeline>/<step>`, its clock begun at its
`step-started` and begun again at each `step-progress` whose `ask` is the step's own ask (§496) or an ask its
`shared` names (§729), and at the `step-ended` of the run's ask a test step names;
- **raises** `pipeline-stands` for that step when its clock passes the watchman's existing five-minute progress bound
(§75), naming the pipeline, the step and the ask it last heard of, and clears it at the step's `step-ended`. A
step said waiting on a person, or queued for a build node (§86), is owed no progress, as today;
- **seeds** its open steps at its start from the runner's `stands`, as §75 has it.
So a reader that neither the assigner nor the runner ends, after a return to an earlier build or any fault, is said
within five minutes of its last sign of life.
- §733 **How it is checked.** Tests 108 and 109.
- **Whole (assigner, mesh-delivery), test 108.** Two composition steps of one candidate started at once make one key,
one request and one run ask. Three composition steps of one revision on two machines start two runs, and each step
reads both verdicts. A machine whose verdict blames module A fails A's composition step and passes B's, with a
warning naming A; a machine that does not compose and blames no module fails both; a verdict with no `blamed` is
judged as today and says "the composer names no culprits". A step of another candidate starts its own run, and a
`could not run` result starts a new one. A taken ask with no `step-ended` and no `step-progress` for 30 minutes
ends `could not run`, with its readers and its ask dropped, and a `step-ended` of that ask heard later is ignored
and said in the journal; a run past 30 minutes that keeps saying its progress is not ended; an ask never taken
ends `could not run` at `run-untaken-bound`. Steps asked again together start one run per machine that did not
pass, and move every former reader; a reopened pipeline says `pipeline-ended` again. A superseded step leaves the run running for its other readers. An assigner restarted during a run takes it
up again by its ask. At the cap a step ends `could not run`, naming the fill. `assigner_compositions_drop` ends the
readers and deletes the key, and a reader-only account calling it is refused.
- **Whole (the node-engine's composer, `mesh-host`).** A fixture module whose manifest is refused on the machine is
blamed by name, two modules owning one path are both blamed, and the search past the request's `blame-tries` names
the untried.
- **Whole (runner and Go build module, mesh-delivery and mesh-catalog), test 109.** A module whose program and bundle
test one directory asks one unit step and one integration step, and both artifacts' steps end with that result and
`shared`. A failing test fails once, and `pipeline-ended` counts the module's tests once. A rerun of one artifact's
failed step that passes moves the other artifact's step to passed too, and the pipeline says `pipeline-ended` again;
an `accepted` step does not move. A runner restarted during a run takes it up again by its ask. A replaced reader
leaves the ask to the other readers. At the cap a step ends `could not run`, naming the fill. A run past 30
minutes that keeps saying its progress is not ended, and a taken ask silent for 30 minutes ends `could not run`
with its readers. A test run queued past five minutes with a holder present is not failed (A-466y). A second
revision with the same digests runs a failed test again. `runner_test_runs_drop` deletes the key and its output object, and a
reader-only account calling it is refused.
- **Unit (runner).** A test run whose output object is gone is answered by `runner_test_runs` and its readers
without its packages, saying "the run's output is gone"; the object outlives `step-outputs`' 7 days while its
key lives.
- **Whole (watchman), tests 108 and 109.** A composition step whose `mesh-wants` `step-progress` stops raises
`pipeline-stands` within five minutes; a test step whose run's ask ended with no `step-ended` of the step raises it
five minutes later; each clears at the step's `step-ended`; a step waiting on a person raises nothing; a watchman
restarted while a composition step waits on the assigner seeds it from `stands` and raises it if no progress
follows.
- **Live.** In the first publish after G's delivery, the composition run asks of each revision number at most its
machines, read with `assigner_compositions` and `assigner_inputs`; each module's test steps run once per level, read
with `runner_test_runs`.
@@ -103,7 +103,9 @@ record says so in its Why. Round 3 of the review by architectural domain (2026-1
`*.findings-stated` are the first. The manifest validator takes `*` only as the whole emitter, and only before an
event that a seat's definition or a contract in mesh-sdk defines, with its fields (for the finding events, the seat `mesh-conditions`' definition, §439); it refuses `*.>` and `*` in part of an emitter's name, and a `*` entry before any other event keeps its meaning on main (§474). The grants part,
from the catalog graph as it derives every grant (§59, §442), makes on each declaring module's stream one durable consumer
for the consumer, named `<machine>_<module>` as ADR 0363 §5 names one, with its grants to read and acknowledge it and
for each process of the consumer that hears it, named as A-397 names a process's durable (`<machine>_<module>` for
its program, `<machine>_<module>_tools` for its tool runner, `<machine>_<module>_<process>` for another; corrected in
place by design 47 H §763, where one per module stood), with its grants to read and acknowledge it and
its membership's word to bind it; it drops that consumer when the module no longer declares the event, and makes one
for a module that declares it later, with no change to the consumer's manifest. A `*` entry never reaches a
restricted stream (one with a `grant`, ADR 0363 §4). Why: the keeper hears modules it finds in the catalog and its
+12 -2
View File
@@ -3,7 +3,7 @@ layer: to-be
status: in-progress
design: 47
milestone: G
updated: 2026-11-11
updated: 2026-11-17
decisions:
- "ADR 0500"
- "ADR 0673"
@@ -45,10 +45,12 @@ decisions:
- "ADR 0573"
- "ADR 0571"
- "ADR 0567"
- "ADR 0565"
- "ADR 0564"
- "ADR 0563"
- "ADR 0551"
- "ADR 0548"
- "ADR 0540"
- "ADR 0539"
- "ADR 0534"
- "ADR 0525"
@@ -72,6 +74,10 @@ decisions:
- "ADR 0259"
- "ADR 0235"
- "ADR 0233"
- "ADR 0330"
- "ADR 0126"
- "ADR 0112"
- "ADR 0084"
---
# 47, milestone G — every line milestone G builds
@@ -82,7 +88,7 @@ file on 2026-11-10, and is cited as "design 47 G §n". A sentence that holds a d
stayed in the main file, and G builds what it says from G's delivery. A section named in italics is in this part, or,
when it is not here, in the main file.
The part is eighteen files, each read whole, its design lines numbered across them:
The part is twenty-four files, each read whole, its design lines numbered across them:
- [G-1-pipelines-registration-and-steps](G-1-pipelines-registration-and-steps.md): pipelines per module: registration, watched branches, steps and policy, what holds a delivery, approval, groups, dependencies, a publish.
- [G-2-pipelines-sizes-checks-and-tools](G-2-pipelines-sizes-checks-and-tools.md): pipelines per module: any size, the pipeline makes the check, who may say what, health, recovery, tools, kept data, how G itself is delivered, the choices under ADR 0666 and ADR 0667.
@@ -104,5 +110,9 @@ The part is eighteen files, each read whole, its design lines numbered across th
- [G-18-fix-round-six-seven](G-18-fix-round-six-seven.md): the fix round of §587 to §676: the approval mark once no verb names its callers, the keeper's snapshots, the recovery module's verbs, the node-engine's kept entries, the gate before a marked verb's running, develop's D-16 to D-49, and a delivery's wait on another machine's network (§677 to §705).
- [G-19-outside-wait-and-refusals](G-19-outside-wait-and-refusals.md): a delivery's wait on an outside cause, written whole once (§706, in place of §705), and the finding writer's own refusals in every bundle (§707, amending §580).
- [G-20-lead-answers](G-20-lead-answers.md): the lead's one-line answers to develop's questions, each tested against the principles (A-1 on).
- [G-21-provider-and-revert-ask](G-21-provider-and-revert-ask.md): the provider a requirement points to, the named seat and the contribution edge (§708, §709, completing §357), and the assigner's ask of a held revert (§710, completing §300), the edge an acting rule gives (§711, completing §47's kind 5), the validation before take-in (§712, §713, completing §16), the take-in and groups of every watched branch (§714, §715), where the gate keeps a group's members (§716) and the seats of the status view's and the assigner's views, followed before their holder is known (§717).
- [G-22-lead-answers-2](G-22-lead-answers-2.md): the lead's answers continued, from A-182.
- [G-23-after-delivery](G-23-after-delivery.md): what is owed once G is delivered.
- [G-24-composition-runs-and-test-runs](G-24-composition-runs-and-test-runs.md): one composition run per candidate and machine, one test run per level and tested packages, from G's live delivery of 2026-11-17 (§718 to §733).
Design 34's milestone [every-event](../34-milestones/every-event.md) and design 46's milestone [7-approval-mark](../46-milestones/7-approval-mark.md) ship in milestone G's release, built in its repositories beside G's lines (lead-47, 2026-11-11 15:30 CET); where one of their lines and a line of G differ, G's later line holds and the other is corrected in place (§624 to §626).
@@ -0,0 +1,297 @@
---
layer: to-be
status: in-progress
design: 47
milestone: H
updated: 2026-11-20
decisions:
- "ADR 0682"
- "ADR 0681"
- "ADR 0667"
- "ADR 0666"
- "ADR 0656"
- "ADR 0633"
- "ADR 0596"
- "ADR 0573"
---
# 47, milestone H: the merge call, the watchdog, the take-in and one pipeline at a time
One file of milestone H's part of [design 47](../47-delivery-from-commit-to-delivered.md); the plan that opens the part
is [H-deliver-the-delivery-system](H-deliver-the-delivery-system.md). Its design lines continue the numbering of
milestone G's part after §733 and are cited as "design 47 H §n". Each line says which release of the plan's section 6
builds it (H1 to H5), how it is checked, and which line of G or lead's answer it replaces; where the code it lands in
is named, it is named by module and function, from the gap tables of 2026-11-20, for the builder to find it.
*The operator, 2026-11-19 about 23:30 CET: "Nobody should 'take in a merge', only commits to the configured branch of
registered modules." 2026-11-20 about 01:10 CET: "parallel pipelines sounds like a very bad idea". 01:15 to 01:20 CET:
a delivery is started by hand by the merge it already needs, the lead named principle 3 (a start a person forgets is
a silent non-delivery), and the operator chose "A": the merge through the mesh is the start and the group, and the
forge's event is the watchdog. ADR 0682 records it (cited by the clause numbers of its version 8, fourteen clauses). The chain these lines build, in one sentence: a **merge call**
(the seat `git`'s `merge-pull` naming one or more pull requests) merges the heads, the gate names them one source
revision per watched branch and opens its delivery record, the indexer takes that revision in and names the movers,
the runner runs one pipeline for it when no other runs, and the assigner wants the newest passed release; the forge
bridge's one message per head move is heard only by the gate's watchdog, which raises an **untaken head** for a head
no merge call delivered.*
```mermaid
flowchart LR
S[session or operator] -->|git.merge-pull pulls| F[forge module, seat git]
F -->|merge-called| G[gate, seat mesh-delivery]
G -->|source-moved| I[indexer, seat mesh-catalog]
I -->|take-in.taken: movers| R[runner, seat mesh-pipeline-runner]
R -->|pipeline-ended| A[assigner, seat mesh-wants]
F -->|branch-moved| B[forge bridge]
B -->|head-moved| G
G -.->|head-untaken| K[condition keeper]
```
### The merge call
- §734 **One merge call is a delivery's start and its group.** (ADR 0682 §1, §2; ADR 0666 §11; the operator, 2026-11-20
01:20 CET; principle 3) The seat `git`'s verb `merge-pull` takes `pulls`, a list of one or more members
`{repository, number, head}` (the head the caller names, as ADR 0666 §11 has it), and `by`, the caller as who@node;
the forge module records `by` beside the bus account the tool runner proves for the call. The members named in one
call are one delivery and, with two or more, its group; nothing else makes a group. The verb's single-pull form goes:
a call naming one pull request is a list of one, and its callers change with it in H1 (the tool runner's
`merge-pull` tool and its description, the claude-code module's instructions and playbook 07's merge step, which name
one pull request). The verb answers `call` (§766) at once and the members' outcome when the call ends. Built in H1 in
the forge module's `merge-pull` handler and the seat `git`'s contract in mesh-delivery-contracts. How it is checked:
whole (forge module): a call naming two pull requests in two repositories merges both and says one `merge-called`
(§736). Replaces G §38's one-pull form.
- §735 **Every member is judged before any is merged.** (ADR 0682 §1, §13; ADR 0666 §11; principle 3) The verb judges
each member as ADR 0666 §11 does, but for the branch protection (still the pull request's head; no run at the head's
build-input fingerprint failed a `required` step), all of them first. It judges no branch protection: a watched
branch need not be protected (ADR 0682 §13), and a head moved outside the mesh, a push included, is the watchdog's
untaken head (§740). When one member is
refused, none is merged, and the answer names every refused member and why. Then it merges the members in the order
the call names them. The forge module's `failed-steps` that this judges is written from the runner's `step-ended`,
whose body names the mover, its commit and its build-input fingerprint (H-A-18). Why judging first: a group merged in
part lands half a delivery. Built in H1 (forge module). How it is checked: whole (forge module): a call whose second
member's head moved merges neither and names it; a head at whose fingerprint a `required` step failed is refused,
naming the step (acceptance test 114).
- §766 **The call is written before its first merge and said again at the forge module's start.** (H-A-18; principles
3 and 4) Before it merges anything, the forge module writes the call's key `call.<call>` in its own template state
`calls` (value: `by`, the bus account, `at`, the members, each with `state` `judged`, `merged` with its commit, or
`refused` with why), and updates each member as it merges. At its start it reads every call whose event it has not
said (`said` false) and says `merge-called` for what landed, so a stop between the last merge and the event loses
nothing it recorded. A call is kept `call-retention` (a setting, default 30 days), then deleted by the forge module.
Its tools: `forge_calls` (the calls, newest first, with each member's state) and `forge_call_say_again` (with `call`
and `why`, says its `merge-called` again, written in the hand-act log). A stop between a merge and the write of that
member's `merged` leaves a head the call never names: it is an untaken head (§740), recovered with `gate_head_take`
(§742). Built in H1 (forge module). How it is checked: whole (forge module): a restart after the second of three
merges says one `merge-called` naming the two that landed; acceptance test 111's stop case.
- §767 **A member refused after every member was judged is said and raised.** (H-A-1; principle 3) When the forge
refuses a member after all were judged (a conflict that appears between the judging and its merge, the forge down
mid-call), the forge module stops merging, says `merge-called` with the members that landed and `refused`, one
`{repository, number, why}` per member not merged, and raises the finding `merge-partial`, scope `delivery`, id the
call, naming each refused member. The landed members are delivered as any call's. It clears the finding when a later
call lands every refused member (read from its own `calls`), or by its tool `forge_partial_clear` with `call` and
`why`, written in the hand-act log. A call that landed no member says no `merge-called`. Built in H1 (forge module).
How it is checked: whole (forge module): a fixture forge that refuses the second merge gives one `merge-called` with
the first member and `refused`, and `merge-partial` raised and cleared by a later call (acceptance test 115).
- §736 **The merge call says one event.** (ADR 0682 §1; principles 1 and 11) Once its members are merged or refused,
the forge module says the seat `git`'s event `merge-called` on `mesh.seat.git.event.merge-called.<call>`, kept on
the stream `SEAT_git_merge-called` for `merge-called-retention` (a setting, default 30 days) and up to
`merge-called-cap` (a setting, default 64 MiB), its body in the seat's `bodies`: `call` (16 lowercase hex, made once
per call), `by`, `account`, `at` (the time of the last merge), `members`, one `{repository, number, branch, head,
commit}` per landed member, where `branch` is the pull request's base (a watched branch) and `commit` the merge
commit the forge records for that pull request, and `refused` (§767). Only the forge module says it. Its one consumer
is the gate (§737), on a durable consumer of its program. Why 30 days: the gate takes in a call heard after a long
stop, as the forge module's `seen` keys are kept (G §585). Built in H1 (forge module, the seat `git`'s definition and
contract). How it is checked: unit (the seat definition: the event and its body); whole (forge module) as §734.
- §737 **The gate names the merged heads one source revision per call and opens the record.** (ADR 0682 §1, §2; H-A-13,
H-A-19; principles 1, 3 and 12) The gate consumes `merge-called`. For each watched branch its members name, it writes
`source.<branch>` once, by compare-and-set keyed by the call (the revision carries `call`, and a revision of that
branch already carrying that call writes nothing): the branch's previous heads with each member's repository at its
`commit`, where two members of one repository on one branch name the last member's commit in call order, numbered one
above the branch's newest. It opens one delivery record per such revision, keyed `<branch>.<source>` (A-33 stands),
its members the call's members on that branch, `call`, `by` and `account` in its trace; says `record-opened` on
`mesh.seat.mesh-delivery.event.record-opened.<call>` with `branch` and `source`, so the session that called can wait
on its own call; and says `source-moved` on `mesh.seat.mesh-delivery.event.source-moved.<branch>.<source>` with
`branch`, `source`, `call`, `start` (false; true only for a branch's first revision, §768) and `heads` (the
repositories it moved, each `{repository, commit}`). A call whose members name two branches is two source revisions
and two records, each naming the call. The gate numbers every source revision; no other part keeps a number of its
own. `source-moved` is kept for `source-moved-retention` (a setting, default 30 days). Built in H1 in the gate: its
`moveSource` moves from the `take-in.taken` handler to a `merge-called` handler; `ForgeMerged`, `moveHead` and
`gate_source_follow` go (§764). How it is checked: whole (gate): a `merge-called` with two members on one branch gives
one revision, one record and one `source-moved`; heard twice it gives one; two members of one repository give its
last member's commit. Replaces A-34, G §291, A-431's numbering by the indexer, and A-464 to A-464e.
- §738 **A delivery record follows its pipeline to the machines.** (ADR 0666 §9; G §141 to §147) The record opened by
§737 is the record of G §141 to §147, one per source revision: it consumes the runner's `pipeline-started` and
`pipeline-ended` (§746) of its source revision, and of the pipelines `package-published` starts from it (§747), the
parts' `wait-held` and `wait-ended`, the assigner's `wanted` and the node-engine seat's `running`, on the gate's own
durable consumer; writes its trace (the assignment graph revisions it moved between, from `wanted`); and ends as G §147
says, or `failed` when the assigner says a tier late (§751). A take-in with no movers ends its record at once as
`nothing to deliver`. Built in H3 in the gate's consumer (`stepFamilies`) and record (`SetTrace`, `EndIfRun`). How it
is checked: whole (gate): a record of a one-module delivery ends when the module runs on every present placing
machine.
### The forge bridge's one message, and the watchdog
- §739 **The forge bridge says one message per move of a watched branch's head.** (ADR 0682 §3; G §11, A-236) On every
`git.branch-moved` of a watched branch, and at its start for every watched branch's head, the bridge reads the head
through `git.branch` (never the event's body) and writes one message `head-moved` on its stream `forge`, subject
`forge.<repository>.<branch>.head-moved`, kept `head-moved-retention` (a setting, default 7 days): `repository`,
`branch`, `head`, `before` (the head it held for that branch in its state `heads`, empty the first time) and `start`
(true when said at its start). It writes it whether the head moved by a merge call, a merge in the forge's screen or
an admitted push: it reads no pull request and no tree. A head equal to the one it holds writes nothing. It
reads no branch protection: an unprotected watched branch moves like any other, and `branch-unprotected` (G §17)
ends (ADR 0682 §13). Its one consumer is the gate (§740). Built in H1 in the bridge; the messages `merged` and `pushed`, their `base`, their trees in its state
`inputs`, and its call of `git.pull` for a merged commit go (§764). How it is checked: whole (bridge): a merge, an
admitted push and a restart each give one `head-moved`; a head heard twice gives one. Replaces G §509 and §714's
message form.
- §740 **A head no merge call delivered is an untaken head.** (ADR 0682 §3; principles 1, 3 and 11) The gate consumes
`head-moved` and keeps, in its template state `heads` (one key `<repository>.<branch>`, value `{head, since}`, deleted
by the gate when `source.<branch>` names that head), each head that `source.<branch>` does not name for that
repository. When `untaken-bound` (a setting of the gate, default 10 minutes, at least 1) passes and `source.<branch>`
still does not name that head, the gate raises the finding `head-untaken`, scope `delivery`, id
`<repository>.<branch>`, naming the repository, the branch, the head, since when, and "moved outside the mesh:
delivered by nothing". It clears it when `source.<branch>` names that repository at the newest head `head-moved`
said (a later merge call or §742's hand take). The gate keeps one deadline timer, set to the earliest `since` plus the
bound, and no other clock. Built in H1 in the gate. How it is checked: whole (gate, bridge): a head moved by a merge
call raises nothing; a head pushed outside the mesh raises `head-untaken` within the bound, starts no pipeline, and
clears when a later merge call takes its repository in (acceptance test 111). Replaces A-463's `merge-untaken` and
the head half of G §12. An acknowledge tool that silences a known `head-untaken` without delivering it was proposed
by the review and is not built: no record or answer asks for it (noted for H4's tools table).
- §741 **`pipeline-stands` times a pipeline's steps, not a head.** (ADR 0682 §7; ADR 0666 §24; principle 7) The
watchman's finding `pipeline-stands` (G §12, §75) is raised for a pipeline step standing still five minutes; a watched
branch's head that starts no pipeline is the gate's `head-untaken` (§740) alone, so the watchman learns no head. A
pipeline waiting its turn (§748) is progress not owed and raises neither. Built in H1 in the watchman's `takein` and
`signals` parts. How it is checked: whole (watchman): a pipeline waiting behind another raises nothing.
- §742 **Taking an untaken head in by hand.** (ADR 0682 §3; principle 4) The gate's tool `gate_heads` reads the state
`heads` with each head's since and finding; `gate_head_take`, with `repository`, `branch` and `why`, names that head
a source revision as §737 does, its `call` `hand.<by>.<time>`, written in the hand-act log, and the chain follows.
Nothing else delivers an untaken head. Built in H1 (gate tools). How it is checked: unit (gate tools); whole (gate):
a hand take writes one revision and clears the finding.
- §768 **The clean state seeds every watched branch's first source revision.** (H-A-15; ADR 0682 §12; principles 2 and
3) Before the runner starts at milestone H1's clean state (the plan's section 5), the gate's tool `gate_source_seed`
(with `why`, written in the hand-act log) writes, for every watched branch the registrations name, one source
revision at each repository's current head read through `git.branch`, with `start` true and `call`
`seed.<by>.<time>`, and says `source-moved`; the indexer takes each in with no mover (§743), so the newest catalog
revision of every branch names those heads, and the forge bridge's `head-moved` at its start then matches
`source.<branch>` and no `head-untaken` is raised mesh-wide. The tool answers the branches and repositories it wrote,
counted. A branch newly watched later starts the same way, by A-401's start pass, which stays and writes through this
path. Built in H1 (gate tools; indexer). How it is checked: whole (gate, indexer, bridge): after the seed a bridge
restart raises no `head-untaken`; live, the counts read at plan step 5.
- §769 **`predefined` is read from the take-in of the catalog's commit.** (ADR 0681 §2; ADR 0682 §1) The indexer's state
`predefined`, which ADR 0681 §2 has it read from the forge bridge's merged message of the catalog repository, is read
at the take-in of a source revision that moves the catalog repository, from that commit's trees (§743), the merged
message being gone (§739). Built in H1 (indexer). How it is checked: whole (indexer): a merge call landing a catalog
commit that changes a predefined key rewrites `predefined`. ADR 0681 §2's words "the forge bridge's merged message"
are owed an insight in that record.
### The take-in
- §743 **The indexer takes in what the gate names.** (ADR 0682 §4; A-476, A-476a; principles 7 and 10) The indexer
consumes the gate's `source-moved` on one durable consumer per watched branch, named `<node>_<indexer>_<branch>` (the
branch's name escaped as a key's name is), each delivering one message at a time, acknowledged once its catalog
revision and `take-in.taken` are written. For each repository the event moves it reads the trees at the named commit
through `git.trees` (one of its kept calls, A-190), computes the build-input fingerprints of the modules registered for
that repository (a registration's git origin), and takes as movers those whose fingerprint differs from their entry
in the branch's newest catalog revision, and every module, in any repository, that imports a package of one of them
(A-476a; ADR 0573 §3). It writes one catalog revision of that branch, keyed `<branch>.<source>` by compare-and-set,
pins it for the pipeline of §746 in the same write (A-449a, key `pipeline.<branch>.<source>`) when it has a mover,
and says `take-in.taken` once, with `branch`, `source`, `revision`, `call` and `entries`, one `{module, commit,
fingerprint, repository}` per mover (§763 corrects G §476 and §648: no `pull`). It validates no manifest and holds
nothing for the indexer a revision names; it takes in with the build it runs (A-476 (a), (b)). A `source-moved` with
no mover, a branch's first revision (`start` true, §768) included, says `take-in.taken` with no entries and pins
nothing (H-A-19); its entries are the base the branch's later take-ins are held against. Built in H1: the indexer's
take-in part written again (today `Arrive`, `evaluate`, `takeInWhole`, `takenWhat`, `nextSource` and
`ApplyBranchSource`, fed by the bridge's messages); its storage, entries, pins' state, versions and verbs
(`KeepView`, `keepBranchEntries`) stay. How it is checked: whole (indexer): a `source-moved` naming a mesh-sdk commit
names mesh-sdk and its importers; one changing only a document names no mover and pins nothing; a restart between
the revision's write and the acknowledgement writes no second revision. Replaces G §16, §19, §509, §712 to §715 and
the main file's *Taken in by the indexer it names* (§764).
- §744 **A take-in that cannot be written is held, said and skippable.** (ADR 0682 §4; H-A-12; principles 1, 3 and 4) A take-in that
cannot be written (the catalog store `full`, G §181) is held: its `source-moved` stays unacknowledged and is not
redelivered on the acknowledgement timer (the consumer's wait for an acknowledgement is longer than any hold, and it
is redelivered with no delay only when the indexer asks); the indexer takes it again when the bus module's `room` for
that store wakes it, with no timer. A `git.trees` call unanswered is its kept call's own (A-190) and holds the same
way. While held the indexer says `take-in.pending` once per source, with `branch`, `source` and `why`, and the
watchman raises `take-in-waits` when no `take-in.taken` for that source follows within `take-in-bound` (a setting,
default 60 minutes; G §497). Take-ins of one branch go in source order; another branch's go on. `indexer_pending`
reads each branch's held `source-moved` and why; `indexer_take_in_pending` takes it again now; `indexer_take_in_skip`,
with `branch`, `source` and `why`, acknowledges it unwritten, says `take-in.taken` with no entries and `skipped`, and
writes the hand-act log. The state `pending`, its keys `m.<sequence>` and `g.<group>`, and `indexer_drop_pending` go
(§764). Built in H1 (indexer). How it is checked: whole (indexer): with the store full a `source-moved` is held, said
once, taken in on `room`; a second branch's take-in goes on meanwhile; a skip ends it in the hand-act log (acceptance
test 116). ADR 0682 §4 keeps `take-in.pending`, `take-in-waits`, `indexer_pending` and `indexer_take_in_pending` and
ends `indexer_drop_pending`.
- §745 **Manifest validation is the pipeline step `validate`.** (ADR 0682 §5; H-A-6; A-476 (a); ADR 0666 §17) The step
`validate` is served by the assigner as an accepted kind `step` of the seat `mesh-wants`, the seat that serves the
composition step (G §22), asked by the runner for each mover as the step before its composition step: the assigner
runs the manifest validator built from the take-in's own heads, in the sandbox, as it runs the composer (G §718), over
the revision's manifests, refusing only a problem in a manifest the revision alters or one between manifests an
altered one takes part in (ADR 0578 §2). It ends `failed` with the reason `manifest-refused` naming each problem, or
`cycle` naming the cycle the revision makes (the cycle refusal A-326 and G §569 made at the take-in), and `passed`
otherwise. Its status is `required` in every policy by default: the seed (A-441) writes it, and §22's list of steps
gains it. The indexer's events `manifest-refused` and `manifest-accepted` (G §500, §668) go; their readers read the
step's end (§764). Built in H1 (assigner: the step; runner: the order; indexer: the seed's default). How it is
checked: whole (assigner, runner): a take-in whose manifest names an unknown field fails `validate` naming it and asks
no composition; a take-in making a cycle fails it naming the cycle (acceptance test 117).
### One take-in, one pipeline, none in parallel
- §746 **One take-in is one pipeline.** (ADR 0682 §6; the operator, 2026-11-20 01:10 CET; ADR 0666 §1, §7, §9 read per
source revision) On a `take-in.taken` with entries the runner starts exactly one pipeline, keyed `<branch>.<source>`
by compare-and-set on its absence, whose movers are the event's entries. It asks each mover's pipeline steps in the
catalog graph's build order (a mover's build waits for the `package-published` of each mover it has a "published
before it builds" edge to, toolchain edges first), and computes the movers' delivery order in ADR 0666 §14's order as
tiers (acting parts first, providers before their consumers; movers no edge orders share a tier). The pipeline passes
when every mover's `required` steps passed, a `required` step ending `nothing to run` counting as passed (ADR 0682 §8; H-A-3), and
fails when one did not. Its events (G §73) move to `mesh.seat.mesh-pipeline-runner.event.<event>.<branch>.<source>`
for `pipeline-started` and `pipeline-ended`: `pipeline-started` names `pipeline`, `branch`, `source`, `call`,
`revision` and the movers; `pipeline-ended` is said once with `pipeline`, `branch`, `source`, `call`, `revision`, the
outcome and, per mover, `module`, `fingerprint`, the released `version` (absent when none was released), its step
results and its `tier`. The step events keep their subject per module (`...<event>.<module>.<branch>.<commit>`) and
gain `pipeline`. Who hears them now: the assigner (wants, §750, §751), the gate (the record, §738), the indexer (pins,
§749), the status view, and a session, which waits on `record-opened.<call>` (§737) and then on
`pipeline-ended.<branch>.<source>`, never per module (G §74's wait per module and G-4's subject row are corrected so,
§763). The runner says no `group-ended`. Built in H1 in the runner (the key `<branch>.<source>.<module>` becomes
`<branch>.<source>`, its step keys gain the mover) and in the seat's definition. How it is checked: whole (runner):
a take-in naming mesh-sdk and one importer is one pipeline whose importer builds after mesh-sdk's
`package-published`, and one `pipeline-ended` naming both with their tiers (acceptance test 112).
- §770 **`pipeline-failed` is one finding per failing mover.** (H-A-19; ADR 0666 §24; ADR 0505 §5, §6) The runner's
finding `pipeline-failed` (G §33, §113) has id `<module>.<branch>`, one per mover whose `required` step failed or
could not run, naming the pipeline and the step, the commit's author's for two hours then the operator's; it is
cleared by that module's next passed pipeline on that branch. Built in H1 (runner). How it is checked: whole (runner):
a pipeline with two failing movers raises two findings; a later pipeline passing one clears that one.
- §747 **A start names an event, never a sweep or a comparison.** (ADR 0682 §6; H-A-19; G §12, §112; principle 1) The
runner starts a pipeline on `take-in.taken` with entries, and on `package-published`, whose body gains `branch` and
`source`, the source revision whose pipeline published: when that pipeline runs and moves the dependent, the
dependent waits in it (§746) and nothing starts; otherwise (a publish again of an older build, G §588, or a kind-1
dependent that pipeline does not move) one pipeline keyed `<branch>.<source>.published.<package>.<version>` starts,
its movers the package's kind-1 dependents it does not move. That pipeline pins the publishing source's catalog
revision and belongs to that source's delivery record (§738). A hand `start`, `run`, the runner's other verbs (ADR
0666 §10, §18, §25) and its taking up of pipelines in flight after a restart (§19) stay, as do the set-aside keys of
A-446. The sweep (`StartUnstarted`, `Unstarted`; `StartHeld` of the held pull request mesh-delivery #262), the
start-time `outdated` of G §375 and `runner_catch_up` go: the runner's durable consumer of `package-published`
delivers a publish heard after a stop. Built in H1 (runner: `Starter`, `run`'s `resume`). How it is checked: whole
(runner): a restart with modules whose fingerprint has no pipeline starts none; a publish heard after a stop starts
its dependents once.
- §748 **At most `pipelines-at-once` pipelines run; the others wait in order.** (ADR 0682 §7; H-A-14; the operator,
2026-11-20 01:10 CET; principles 3 and 11) The runner's setting `pipelines-at-once` (default 1, from 1 to 8) bounds
the pipelines whose steps are asked at once. A pipeline written over the bound gets `seq`, the next value of the
runner's own counter in its state (one key `queue.next`, written by compare-and-set), and state `waiting`, with no
step asked; it says `wait-held` with `step` `pipeline` and `on` `pipelines-at-once`. The runner places the lowest `seq`
waiting at its start, from its own state, and on every end of a running one: `pipeline-ended`, a cancel and a
set-aside alike, with no timer, and says `wait-ended`. A pipeline waiting on the operator's `approval` step does not
count against the bound, and when its approval is answered it is placed first, ahead of every `seq`. When pipelines
wait and none runs after a placing, the runner raises its finding `pipelines-stalled`, naming the first waiting, and
clears it when one runs. At most `pipelines-waiting-cap` pipelines wait (a setting, default 64): a start over it
leaves its `take-in.taken` unacknowledged, raises `queue-full`, and is taken on the next end. Superseding (ADR 0682 §7): a waiting
pipeline's mover that a newer waiting pipeline of the same branch also moves leaves the older one, which ends
`superseded` when no mover is left; a running pipeline runs to its end (G §31's supersession of running steps no
longer applies across pipelines). A waiting pipeline is progress not owed (§741). The runner's tool `runner_waiting`
lists the waiting pipelines in their order; `runner_place`, with a pipeline's key and `why`, places one ahead of its
turn, written in the hand-act log. Built in H1 (runner). How it is checked: whole (runner): two take-ins in a row run
one after the other, the second said waiting; a cancel places the next; an approval answered places first; a newer
take-in moving the same module supersedes it in the waiting one (acceptance test 112).
- §749 **A pipeline's pins are the indexer's, freed on its end.** (ADR 0666 §9; A-449a; principle 12) The indexer pins
a take-in's revision in the take-in's write (§743), and a pipeline §747 starts on its `pipeline-started`, which
carries `revision`; it frees the pin on that pipeline's `pipeline-ended`, both heard on durable consumers of its own.
At its start it judges each kept revision against the pins its own state holds, never against a count of pins
stated. The runner says no `pinned` or `freed`; §153's rule that only the gate's account says them stands. Built in
H1 (indexer: `JudgePins`; runner). How it is checked: whole (indexer): a restart while a pipeline runs on revision
510 keeps 510. Corrects A-449 (§763).
@@ -0,0 +1,197 @@
---
layer: to-be
status: in-progress
design: 47
milestone: H
updated: 2026-11-20
decisions:
- "ADR 0682"
- "ADR 0666"
- "ADR 0656"
- "ADR 0596"
- "ADR 0595"
- "ADR 0573"
- "ADR 0548"
- "ADR 0525"
---
# 47, milestone H: the want rule, the builder's lines, the reads of other parts and the missing read tools
One file of milestone H's part of [design 47](../47-delivery-from-commit-to-delivered.md); the part opens at
[H-deliver-the-delivery-system](H-deliver-the-delivery-system.md), and its lines are numbered after
[H-1](H-1-the-merge-call-and-the-take-in.md)'s and cited as "design 47 H §n". These are items 8 and 11 to 13 of the
plan's section 4, and A-434 as a line. The wake-up rule (item 9) is one rule for every delivery part and is in the
main file, *Every delivery part wakes on its inputs alone*; §762 here says which part moves onto it where.
### The want rule
- §750 **A want names the newest released version whose pipeline passed.** (ADR 0682 §8, §9; A-478; the operator,
2026-11-17 about 21:45 CET; principles 2 and 7) For every machine whose assignment places module M on watched branch
B (the placement's branch, the registration's first by default), the assigner writes `want.<node>.<M>` naming
`version`, the highest version of M released on B (`version-released`) whose pipeline's `pipeline-ended` passed, with
`pipeline` (the pipeline's key) and `rank` (the mover's tier in it, §746); it writes it as §751 orders, by
compare-and-set on a newer version, so an older end heard later writes nothing (G §352's state `written` keeps, per
module and branch, the newest passed version). A want names a version, never a part's digest (A-430): A-436's
stand-in ends, and G §379's digests go. The one exception is a return to an earlier build: the placement's value
`build` (G §361), set through the seat `mesh-module-assigner`'s `propose` like any placement change and read through that seat's verb
`placement` (A-62), whose answer shows the `build` value beside the branch, is read before
the rule and names the want's version (H-A-5; ADR 0682 §8). The want is held for nothing else. These holds end, with
their states, findings and tools: the canary and the "at most `step` ahead" rule, every provider healthy, the grant
exists (ADR 0429 §6), the served verb, the bus state (rule 8), the acting part's new version first (ADR 0656 §4; G
§266, §268, §269, §274, §276: `acting-part-late`, `assigner_waits`'s acting rows, `assigner_release`), the
dependency's `version-delivered` (G §376, A-189, A-246, A-250: `delivery-waits`, `assigner_delivered_again`, the event
`version-delivered`), and the parts check (G §524, the `want-parts` capability). The backup before the apply and the
operator's yes on a failed backup and on a held revert are the node-engine's and the asker's (A-478 (c); G §296,
§710); a failing new version holds on its own machine while the old runs, by its node-engine's apply (ADR 0682 §9).
Built in H1: the assigner's want rule (`wants.go` and the want half of its pass) written again; the old holds
deleted. How it is checked: whole (assigner, in mesh-delivery): a module released with a passed pipeline is wanted on
every placing machine, whatever build an acting part runs; a version whose pipeline failed is not wanted; an older
end heard after a newer one writes nothing; a placement `build` names the want's version (acceptance test 113).
Replaces G §29's per-revision want, §291 and §292 in their want half, and design 47's six rules in *Where it goes*.
- §751 **One pipeline's wants are written tier by tier.** (ADR 0682 §8, §9; H-A-10; ADR 0666 §14; principles 3 and 7) On a
passed `pipeline-ended` the assigner writes the wants of its tier-1 movers on every placing machine; once each of them
reports `running` at that version on every present placing machine (the node-engine seat's `running`), it writes the
next tier's, and so on. Each tier has `tier-bound` (a setting of the assigner, default 30 minutes): a tier whose
movers do not all run within it ends the delivery loudly: the assigner writes no later tier, raises its finding
`tier-late`, scope `delivery`, id the pipeline, naming the movers and machines not running, and says `wanted` with
`outcome` `tier-late`, on which the gate ends the record `failed` (§738). A machine away is not waited for; it
applies its wants when back. The validate and composition steps composed the candidate against the whole graph
before any want (ADR 0682 §9). The wants of one tier are written at once. Built in H1 (assigner). How it is checked:
whole (assigner, in mesh-delivery): a pipeline of a provider and its consumer writes the consumer's want only after the
provider's `running`; a provider that never runs raises `tier-late` within the bound and writes no consumer want.
- §771 **The order on one machine is the node-engine's apply order, by rank.** (H-A-9; ADR 0682 §9; A-478b; principles
9 and 12) The node-engine, which applies its wants one module at a time (R6), takes its changed wants in this order:
the holder of the seat `node-backup` and the bus module first; then each pipeline's wants by `rank`; then the rest by
name; its own want last; at a revert, the reverted module first. It reads the order from the wants alone and consumes
no event of the runner. The assigner's order waits (`order.<node>.<module>.<part>` in its state `waits`, step
`placing`, G §298, A-245, A-258 to A-260) go. The node-engine's tool `engine_apply_order` answers the order it will
apply its changed wants in, with why; the assigner's `assigner_delivery_order` of the first version of this part is
not built. Built in H1 (node-engine apply pass; assigner). How it is checked: whole (node-engine, in `mesh-host`):
wants of the bus module, the backup holder and two movers of ranks 2 and 1 changed at once apply in that order.
- §772 **A machine away at the clean state is placed by hand when it is back.** (H-A-15; principle 2) A machine away at
milestone H1's clean state runs a node-engine that cannot read a want without digests, so the assigner keeps its wants
held, said as `held` with why `awaits its hand placement`, until its node-engine says, through the seat
`node-engine`'s capability event `manifest-reads-changed` (G §590), that it reads a want by version; when the machine
is back, its hand placement (the plan's section 5, step 5) runs before anything else on it. Built in H1 (assigner).
How it is checked: whole (assigner): a node whose node-engine lacks the capability gets no want of the new form and is
said held; live, plan step 5 reads it.
### Accounts
- §752 **Every account may call every verb; a module publishes only what it declares.** (ADR 0682 §10; A-434, H-A-11;
ADR 0666 §21; principle 6) The grants part grants every module's account every verb and every subscription; it grants
a module's account publication only of the events, step results and state its manifest declares (ADR 0666 §21 stays),
and an enrolling node's account keeps its own grant. No seat definition names callers, and the `callers` lists of
every seat contract go (G §610's class defaults are not built); approval marks stay. Acceptance tests 40, 51 (its
callers row) and 85 are not checked. Built in H1 (seat contracts in mesh-contracts and mesh-delivery-contracts; the
grants part). How it is checked: unit (seat definition reader: a definition naming callers is refused); whole (grants
part, in mesh-delivery): a module calls a verb its manifest does not invoke and is answered; it publishes an event
its manifest does not declare and is refused; an enrolling node's account is held to its grant (acceptance test 118).
### Builds and the builder
- §753 **A build module takes deliveries first.** (ADR 0525 §4; G §86; H-A-8) Each build module pulls its delivery queue
first, then its check queue, then its recheck queue, taking from a later queue only while the earlier is empty, and
waits on the bus's pull with no idle re-pull: the five-second idle pull of the shared step runner in
mesh-delivery-sdk goes. The turns the code takes today cite an operator's yes of 2026-11-15 that no record holds; if
H2's prepare finds it, ADR 0525 gets an insight. Built in H2 (mesh-delivery-sdk's step runner, `buildrun`). How it is
checked: whole (Go build module, in mesh-catalog): with three queues full the delivery asks run first (acceptance
test 119).
- §754 **A done build with no reservation is reserved by the builder itself.** (G §369, A-455; principle 3) When the
runner's build step asks a fingerprint whose build is done and carries no reserved version, the builder reserves the
next version for it at that ask, says it in its journal and in the step's end, and answers the step carried. Nothing
else reserves an old build. Built in H2 (builder: its reserver, and the look that writes "done build no version
reserved", which goes). How it is checked: whole (builder, in mesh-delivery): a build step for a done, unreserved
fingerprint ends carried with a version (acceptance test 119).
- §755 **A failed fingerprint built again keeps its reservation.** (G §369, A-490b; principle 7) When a key is built
again (a step ask, an event or `builder_build_again`), the reserver takes that key's own standing reservation as its
number; a key with none takes one above the higher of the highest released and the highest any other key reserved.
No number is skipped. Built in H2 (builder's reserver). How it is checked: unit (reserver): a failed 0.1.19 built
again is 0.1.19; acceptance test 119.
- §756 **A build is entered only by the runner's build step.** (G §473, A-97) The builder builds only what a pipeline's
build step asks: it builds no catalog entry it hears and follows no gate `source`; the pre-G numbering beside the
reservations goes, with its floor wait. `build.ended` carries the reserved `version` (A-430b), for every watched
branch. Built in H2 (builder). How it is checked: whole (builder): a catalog entry heard with no step ask builds
nothing; `build.ended` names its version (acceptance test 119).
- §757 **The steps a mover can run are asked at every pipeline.** (ADR 0666 §7; G §8, §22; H-A-3) At each pipeline's
start the runner asks each build seat's `steps` for each mover's artifacts, never only at the seed; a step the answer
says has nothing to do ends `nothing to run`, which counts as passed for the pipeline (§746; ADR 0682 §8). Built in H2 (runner).
How it is checked: whole (runner): a library module whose unit tests vanish ends that step `nothing to run` and its
pipeline passes (acceptance test 119).
- §758 **A registration whose pipeline would have no step is refused.** (ADR 0666 §2; acceptance test 67) `register`
and `policy` refuse a registration whose policy, read against the build seats' `steps` for its artifacts, leaves no
step that runs, naming each artifact and step. A package module with no registration has no pipeline and is never
built; the seed (A-441) registers every package module the graph holds, `mesh-delivery-sdk` among them. Built in H2
(indexer: `register`, `policy`, the seed). How it is checked: whole (indexer): a registration with every step
`bypass` is refused naming them (acceptance test 119).
### Reads of another part's data become its events and verbs
- §759 **The status view and the watchman read no other part's bus state.** (ADR 0596 §2, §4; principles 1 and 9)
Each read of another module's bucket becomes the owner's event, and the first view the owner's seat verb, in H4:
the node-engine's `have` becomes the seat `node-engine`'s event `running` and, for the first view, the verb `haves`
the seat gains (what the node runs per module, from its own state); the builder's `builds` becomes the seat
`mesh-builds`' `build.ended` and the verb `builds` with `since`; the indexer's `taken` becomes `take-in.taken` and the
seat `mesh-catalog`'s verb `revision`; the watchman's `presence` and `stuck` become the seat `mesh-watchdogs`' verbs
`presence` and `stuck` and the findings it says (`*.finding-written`, `*.finding-cleared`, G §386's form); the
indexer's `candidates` and the teller's `answers` go with their uses (G §512). The watchman's read of the
provisioner's `provisions` becomes §773's event. Every other bucket watch of the view the H4 prepare lists against an
owner's event; one with none stops that subtask for the lead. How it is checked: unit (each manifest declares no
`reads` of another module); whole (view, watchman, in mesh-delivery) against the owners' events.
- §773 **Four owners say their changes as events, for H4b.** (H-A-4; ADR 0596; principle 1) Each is a seat event kept
on its seat's stream for 7 days (a setting of its owner), with a first-view verb; until H4b builds them, the reads
they replace stand and are named leftovers in the gap table:
- the seat `mesh-provisioner`: `provision-changed` on `mesh.seat.mesh-provisioner.event.provision-changed.<provision>`,
body `{provision, reference, state, at}`; first view its verb `provisions`;
- the seat `mesh-vault`: `account-changed` on `mesh.seat.mesh-vault.event.account-changed.<user>`, body `{user, hash,
at}`, and `node-login-changed` on `...node-login-changed.<node>`, body `{node, hash, at}`; first view its verbs
`accounts` and `node-logins`;
- the seat `mesh-grants`: `user-list-changed` on `mesh.seat.mesh-grants.event.user-list-changed`, body `{revision,
users, at}`, consumed by the bus node's agent in place of its watch of the key `user-list`; first view its verb
`user-list`;
- the enrolment module: `enrolment-changed`, body `{node, state, at}`; its seat and its first-view verb are read
from the module's manifest at H4b's prepare, which writes them into this line.
The grants part then consumes them, and calls the bus module only through the seat `mesh-broker`'s verbs (`list`,
`show`, and `users` and `streams`, which the seat gains in place of the module tools `nats_users` and `nats_streams`
the grants part calls today). Built in H4b. How it is checked: unit (the owners' seat definitions); whole (grants
part): a changed account reaches the user list with no read of the vault's bucket.
- §760 **Rates on the bus are read on the seat `mesh-broker`.** (ADR 0595 §5; principle 4) The seat `mesh-broker`
gains the read verb `rates`, with `window` (seconds, default 10, from 1 to 60): it reads the bus server's counters of
each connection and each stream twice, `window` apart, within the call, and answers per connection (its account's
module and node) and per stream the messages and bytes in and out per second, and the slow consumers counted. Its call
is bounded at `window` plus 5 seconds, at most 65 seconds. A verb's call timeout is a bound per verb in its seat
definition, `timeout`, defaulting to the tool runner's own (principle 11); `rates` names 70 seconds, and the tool
runner waits a verb's `timeout` when its definition names one. The field, its schema, the tool runner's wait and
`merge-pull`'s 120 seconds are built in H1 (H-A-43: a merge call of several members is cut at a fixed 30 seconds
otherwise); the `rates` verb itself in H4 (the bus module). How it is checked: whole (bus module): a fixture publishing 100 messages a second reads between 90 and 110.
### The read tools found missing
- §761 **One revision, narrowed, and its differences, in the indexer.** (ADR 0666 §25; principle 4) The indexer gains
the tools `indexer_revision` (`branch`, `revision`, optional `module` and `kind`: one catalog revision of any watched
branch, narrowed to a module's entries and edges or to one edge kind), `indexer_difference` (`branch`, `from`, `to`:
the modules and edges that differ), `indexer_build_order` (`branch`, `modules`: the order the build edges give, its
cycles named) and `indexer_built_from` (`fingerprint`: the source revision and commit it was taken in at);
`indexer_edges` (G §380) gains `kind`. The node-engine's `engine_build` answers its own fingerprint, version and
commit, and `engine_apply_order` is §771's. An answer over the bus's per-message limit is an object's name (ADR 0666
§16). The callers of tools no part serves go: the checker's of `indexer_read_candidates` (it goes, §764), and the
health checks' and the first views' of `indexer_read_modules`. Built in H4. How it is checked: unit (each tool's
answer); the principle-4 table of each module's pull request.
- §762 **Every delivery part moves onto the wake-up shape.** (ADR 0682 §11; main file, *Every delivery part wakes on
its inputs alone*) The parts and what goes, from the gap table of 2026-11-20 (part F, question 2): mesh-config's
key-by-key pass, five-minute sweep and minute's read (`sources`, the held pull request mesh-catalog #708, H1); the
grants part's whole recompose (`Compose`, H4b); the indexer's re-read of every module, graph key and manifest after
each write (`KeepView`, `viewEntries`, `heldModules`, H4); the builder's start sweep and `builder_stuck`'s read of
every key (`Sweep`; it answers from the builder's own index of what builds, H4); the assigner's input sweep and its
ten-second poll of `backed-up` (`inputKeeper.sweep`, `snapshotTheBus`, H4); the watchman's five-minute recount of
dead letters (H4); the build modules' stale round and idle pull (`EndStaleRound`, §753, H2); mesh-sdk's first view
asked again with a backoff (`views` reader, H4); the view's five-second retries (§759, H4); the forge module's
one-minute poll and ten-minute timer (H3). The decided pulses (G §496's minute of `step-progress`, G §606) are real
deadlines and stay. Its cost: the shape lives in mesh-sdk's state package, so its release rebuilds nearly every
module (every module that imports that package, about 120 by the graph of 2026-11-20); it is carried by H4 alone, one
release, delivered by the pipelines of the movers it names; H1's mesh-sdk change is only the seat definitions' copies
and the `timeout` field (H-A-42, H-A-43), published first. How it is checked: as the main file's rule says.
### Questions this file leaves open
None: the enrolment event's seat and first-view verb (§773) are owed to H4b's prepare.
@@ -0,0 +1,125 @@
---
layer: to-be
status: in-progress
design: 47
milestone: H
updated: 2026-11-20
decisions:
- "ADR 0682"
- "ADR 0681"
- "ADR 0667"
- "ADR 0666"
- "ADR 0633"
- "ADR 0595"
---
# 47, milestone H: the corrections made in place, the stale state, and what retires
One file of milestone H's part of [design 47](../47-delivery-from-commit-to-delivered.md); the part opens at
[H-deliver-the-delivery-system](H-deliver-the-delivery-system.md), and its lines follow
[H-2](H-2-wants-builds-reads-and-tools.md)'s, cited as "design 47 H §n".
- §763 **The small contradictions are corrected in place.** (plan item 10; each line names its source) These lines of
milestone G and the main file now say what holds, each marked "corrected in place by design 47 H §763":
- G §5: `register` and `watch` refuse no unprotected branch (ADR 0682 §13, which ends ADR 0666 §3; the operator,
2026-11-14, G-23 *Met during G's start*). G §17, G §38's and G §41's protection judgement of `merge-pull`: no part
reads a branch's protection (ADR 0682 §13, which ends ADR 0666 §11's protection judgement and §6's condition).
- G §654: mesh-config consumes no pull request event and calls no `git.pull` (ADR 0681 §1).
- A-449 and A-449a: the runner says no `pinned` or `freed`; the indexer pins and frees a pipeline's revision (§749).
- Acceptance test 53: its `forge-made` and checker rows go (G §151; §740; the checker goes).
- G §476 and §648: `take-in.taken` carries one entry per mover, `{module, commit, fingerprint, repository}`, no
`pull` (§743).
- G §40: the operator channel keeps no count of open asks per asker and offers every ask (ADR 0682 §14, which ends
ADR 0666 §12's three; A-424, the operator, 2026-11-15).
- G §386: the grants part makes one durable consumer per process that hears a `*` event, named as A-397 names it.
- G §73's subject table and G-4's row of the runner's events, and G §74's wait per module: `pipeline-started` and
`pipeline-ended` are said per source revision and waited for so (§746).
How it is checked: hq's review of this amendment reads each corrected line against its source.
- §764 **What retires at milestone H's delivery.** (ADR 0682 §1 to §4, §6, §8, §9, §13, §14; ADR 0681; ADR 0667 §12) Each is
removed in the release named, with its code, its state (dropped by §765), its tools, its events in the seat
definitions, its readers and its tests; nothing of it is kept unread.
- **The forge module (H1, H3):** the single-pull form of `merge-pull` (§734); the merge-check machinery: the
`mesh/merge-gate` pending statuses, the weighing of trunk and sibling moves (`announceHead`, `passPulls`,
`trunksMoved`, `siblingMoves`, `GateWriter`) and its files on disk, its one-minute poll and ten-minute timer (H3).
The forge's branch protections drop the required statuses `mesh/merge-gate` and `mesh/repo-check` in H1, through
the forge module's protection setting, so no merge waits on a status nothing writes (H-A-15).
- **The branch protection (H1; ADR 0682 §13):** `merge-pull`'s judgement of a branch's protection, the bridge's
read of it on every move and its finding `branch-unprotected` (G §17), and the protection rows of G §41's test.
- **The operator channel's limit (ADR 0682 §14):** any count of open asks per asker, and ADR 0666 §25's tool for
asks held back, which reads empty and goes.
- **The forge bridge (H1):** the messages `merged` and `pushed` and their `base` (§739), with their readers, the
indexer's take-in and the gate's `ForgeMerged`; its state `inputs` and its read of trees; its call of `git.pull`
for a merged commit; the group it sets on a member, `forge.group.merged`, `bridge_groups` and
`bridge_group_end_again` (G §43, §45, §157, §715); its hearing of the checker's `owed` and the merge act of a
switched key (`OwedActMerge`, its `invokes` of `seat:git.merge-pull`, G §510).
- **The gate (H1, H3):** the source per merged message (A-464 to A-464e: `ForgeMerged`, `moveHead`,
`gate_source_follow`, the start's comparison with the forge's heads) and its consumption of the bridge's `merged`;
the source moved on `take-in.taken` (A-34; §737); the groups from a branch name (G §42, §716, A-279): its states
`deliveries` and `groups`, its consumption of `pull-updated`, `pull-merged` and `pull-closed`, its start
reconciliation through `open-pulls` and `pull`, and the verb `groups` (the verbs `deliveries` and `show` answer
from the records, A-24); the switch and the carried approval (G §156, §169, §542, A-281: `approval-carried`,
`approval-carried-open`); the states `merges`, `owed` (the old bucket), `asks`, `pulls` and `turns`, and the seat
definition's entries for them.
- **The indexer (H1):** the take-in fed by the bridge's messages; the state `pending` with its keys `m.<sequence>`
and `g.<group>`; the hold for the indexer a revision names (ADR 0633 §1, the main file's *Taken in by the indexer it
names*) and `indexer_drop_pending`; the validation at the take-in (G §16, §19, §237, §712, §713; A-475, A-475a),
which becomes §745's step; its events `manifest-refused` and `manifest-accepted`, with their reader, the watchman's
findings `manifest-refused` and `manifest-outgrown` raised from them; the catch-up by comparison (A-463, A-463a,
A-490k, G §177's first-start half, G §362: `kickBehind`, `TakeInBehind`, `sayUntaken`, `takeInHeads`,
`kickCatchUp`, `CatchUp`) and its condition `merge-untaken`; the source numbering in memory (A-431,
`nextSource`); the 30-minute group wait of `take-in-waits`; the field `pull`; the config candidates (ADR 0681 §2).
- **The runner (H1):** the sweep (`StartUnstarted`, `Unstarted`; `StartHeld` of mesh-delivery #262, closed
unmerged); the start-time `outdated` (G §375) and `runner_catch_up`, never built; `group-ended` (G §332) and its
stream `SEAT_mesh-pipeline-runner_group-ended`; the pipeline key per module; its `pinned` and `freed`.
- **The assigner (H1):** the holds §750 names, with `acting-part-late`, `delivery-waits`, `version-delivered`,
`assigner_delivered_again`, the acting rows of `assigner_waits` and `assigner_release`; the order waits
(`order.<node>.<module>.<part>` in its state `waits`, §771); the parts check and the `want-parts` capability; A-436's
digests in a want.
- **mesh-config (H1):** its pull request path (ADR 0681 §1, §7) and A-490l's pull sweep.
- **The checker (H1):** `mesh-delivery-checker` whole, with its verdict verb, its calls of
`indexer_read_candidates`, `mesh/check` and its try; it is not placed at the clean state.
- **Every seat contract (H1):** the `callers` lists (§752).
- **Acceptance tests:** 38, 49, 81, 82, 105 and 106 as written; tests 110 to 119 hold what remains of them, and test
67 is read with a merge call naming its three repositories.
How it is checked: after each release, a search of the trunks of mesh-catalog, mesh-delivery, mesh-sdk,
mesh-contracts, `mesh-host` and mesh-tools for each name above finds it in no file outside tests that assert its
absence, and `mesh-broker.list` shows no bucket or stream of a state above.
- §765 **The stale state goes once, after the new programs run.** (ADR 0682 §12; H-A-15, H-A-19; the operator,
2026-11-20 about 01:10 CET: "I don't care about old data at this moment, I want a working mesh again") At milestone
H1's clean state, after the new programs run on every present machine (the plan's section 5, after step 5.6) and
before the runner starts, every state §764 retires goes, and with it: the gate's 833 open records; the indexer's pins
that name no running pipeline; the pipelines of the earlier model; the stopped runner's queue of `take-in.taken` of
the old form, with the consumer that holds it; every held or failed want. Each goes as ADR 0595 §4 removes kept data,
on that word, through the tool named for it: a record through `gate_record_end`, a pin through the indexer's
`indexer_pin_drop` (with `key` and `why`, which H1 adds), a pipeline through the runner's `cancel`, a held or failed
want through the assigner's `assigner_want_drop` (with `node`, `module` and `why`, which H1 adds), and every retired
state, once no running module declares it (an orphan `orphans` lists), through the seat `mesh-broker`'s `drop`. The
bus module's stream snapshot taken before the first drop is the rollback. The pack says what it deleted, counted.
Every durable consumer the new programs make starts at the newest message of its stream and refuses an event of the
old form (one with no field its new form requires) with a journal line naming it. The delivery records of the one
model start from the clean state. How it is checked: the lead reads `mesh-broker.list` and each module's read tools
before and after, and quotes the counts; the snapshot's restore is tested before the first drop (ADR 0595 §4).
- §774 **Tests per module, against the budget, and where H1's run before its merge.** (H-A-16, H-A-17; the test
budget, 50 integration and 500 unit tests per module) Each acceptance test of H is one whole test per module, in that
module's repository (tests 110 to 119 name which); the chain of test 110 is the live proof. The counts, read from the
gap tables of 2026-11-20 (unit, then integration), and what H adds:
| module | today | H adds (whole tests) | H retires |
|---|---|---|---|
| forge module (seat `git`) | 177 Go and 196 TypeScript, 1 | 1 TypeScript whole test of the seat `git` (§734 to §736, §766, §767; tests 114, 115) | the merge-check machinery's tests |
| forge bridge | 45, 8 | none: its whole test is rewritten for `head-moved` | the `merged`, `pushed`, group and owed-merge tests |
| gate | 38, 2 | 1 (the merge call, the record, the watchdog; tests 110, 111) | the source-follow, group and switch tests |
| indexer | 194, 13 | none: its whole test is rewritten for the take-in (tests 112, 116) | the pending, catch-up, validation and group tests |
| runner | 78, 3 | 1 (the queue; test 112) | the sweep's tests and `group-ended`'s |
| assigner | 126, 13 | none: its whole test is rewritten for §750 and §751 (tests 113, 117) | `TestEachRuleHoldsTheWantBack` and the hold tests |
| node-engine | 1,719, 10 | 1 (the apply order; test 113) | the want-parts tests; over the unit budget, every H change to it deletes at least as many unit tests as it adds |
| grants part | 78, 1 | none: its whole test gains §752's cases (test 118) | — |
| builder | 154, 18 | none: its whole test gains §754 to §756 (test 119) | the pre-G numbering's tests |
| tool runner | 152, 7 | 1 that starts it whole (H-A-16's gap) | — |
Every module stays within 50 integration tests; acceptance tests 38, 49, 81, 82, 105 and 106 retire (§764). Before
H1's merge its integration tests are run once locally against an embedded bus, as the mesh's instruction
*how-work-is-done* allows, and each pull request says so; the chain's live proof (the plan's section 5, step 7) is
H1's check, and from H1 on the pipeline makes the check (H-A-16, a rule weighed and said). The counts above are per
module; the count per release and the number of tests each retired test frees are each milestone's prepare's, written
in its milestone file. How it is checked: each pull request of H states its module's counts against the
budget; the review refuses a count over it.
@@ -0,0 +1,479 @@
---
layer: to-be
status: in-progress
design: 47
milestone: H
updated: 2026-11-20
decisions:
- "ADR 0682"
- "ADR 0681"
- "ADR 0667"
- "ADR 0666"
- "ADR 0656"
- "ADR 0633"
- "ADR 0596"
- "ADR 0595"
- "ADR 0573"
- "ADR 0548"
- "ADR 0525"
---
# 47, milestone H — the plan to deliver the build-and-delivery system properly
The operator, 2026-11-19 about 23:30 CET: "This mess has been going on for too long and I want to fix it properly.
Write out a plan to deliver our mesh build-and-delivery system. Thoroughly. The research and design 47 should have
all the details of what it should look like and what it should do. Unfortunately, the code is very very poor. So we
need to fix it. What is our best approach? I'm willing to do some hand-deploys to get us into a clean state." And:
"Nobody should 'take in a merge', only commits to the configured branch of registered modules."
This file is that plan. It was written by the lead (lead-47) on 2026-11-20 between 00:00 and 01:00 CET from seven
readings by agents: one specification per part of the design (what design 47, its milestone G, research 086 and their
records say the part does; no code read) and one gap table per part (main's code of 2026-11-19 held line by line
against that specification, with what runs live on each machine). The readings are in the working folder
`.work/plan-47/` of the lead's hq working copy (`spec/`, `gaps/`, `live-state.md`); their findings are summarised
here, and every number below comes from them unless it says otherwise. The plan is the lead's; the operator reads it
before any code is written.
**Milestone H's part.** This file opens the part; its design lines (section 4's items as lines, numbered after G's
§733 and cited as "design 47 H §n") are in three files, each read whole:
- [H-1-the-merge-call-and-the-take-in](H-1-the-merge-call-and-the-take-in.md): the merge call, the gate's source
revision and record, the forge bridge's one message and the watchdog, the take-in, the step `validate`, one pipeline
per take-in and none in parallel, a pipeline's pins, the clean state's seed (§734 to §749, §766 to §770).
- [H-2-wants-builds-reads-and-tools](H-2-wants-builds-reads-and-tools.md): the want rule, the order on one machine,
every account may call every verb, the builder's lines, the reads of other parts made events, rates on the bus, the
missing read tools, which part moves onto the wake-up shape in which release, the four owners' events and a machine
away at the clean state (§750 to §762, §771 to §773).
- [H-3-corrections-and-what-retires](H-3-corrections-and-what-retires.md): the contradictions corrected in place, what
retires, the stale state dropped once, and the tests per module against the budget (§763 to §765, §774).
The wake-up rule itself is in the main file, *Every delivery part wakes on its inputs alone*. Where an H line and a G
line or lead's answer differ, the H line holds, and the G line it corrects in place says so.
## 1. Where the system stands (read 2026-11-20 00:05 to 00:30 CET)
**What works.** One pipeline delivered one module end to end with no hand act on 2026-11-19 at 22:48 (the image
registry, main.1039). The shape of the design is in the code: of 619 table rows of design lines held against main, 413 are built by their contract: 78
per cent of the 527 rows judged (the rest belong to another part's code) (per part: runner 87 of 100 judged, gate and bridge 71 of 93, indexer 70 of
89, assigner and node-engine 56 of 76). No part needs to be written again whole.
**What does not work.** The system cannot deliver itself today:
| symptom (live) | count | cause (from the gap tables) |
|---|---|---|
| wants held or failed on the four machines | 205 held, 66 failed | the catalog half holds no entry for their fingerprints; the node-engines compose nothing new |
| compositions fail on shanks | entries `asked` since 2026-11-18 03:09, unready answers seen from 2026-11-19 11:56 | an entry ask that failed in transport is never asked again; the node-engine's shadow waits on it without bound (the surveyor's reading); other compositions failed on the removed revision trunk.510 and on a call-token refusal |
| delivery records open, none ended | 833 open, 0 ended since 2026-11-14 | the gate hears only `take-in.taken`; nothing writes a record's trace, so its difference is never known |
| pipelines about to start at the next take-in | about 60 (reasoned from the sweep's rule; no tool reads the runner's waiting starts) | the runner's sweep starts a pipeline for every module whose fingerprint has none (b9c50ef0, 2026-11-16); no design line allows it |
| source revision moved twice | both paths on main | A-464 (per merged message) wins live over A-34 (on the take-in): a group's members become separate revisions; a pushed commit reaches the source only through the take-in or the gate's comparison at its next start |
| catalog revision removed while pipelines name it | trunk.510 at 22:51 | pins are judged at restart against a key written once; only the take-in pins pipelines |
| stale bus state | 753 merges, 6,951 owed, 898 asks, 1,256 pulls keys; 5 pipelines running since midday; 31 stale pin records | buckets of the pre-G model never dropped; no tool reads their contents |
| bus load | 98 slow consumers, 117 consumers behind; the watchman 39,037 events behind | mesh-config passes every 5 minutes and polls every minute on main (fixed on the held pull requests); the forge module polls every minute |
| hand-placed programs | every delivery module but the indexer, the image registry and the tool runner (on ace and g14) | G's live start of 2026-11-16 and after; 16 drop-in files under `/run/systemd/system` on the four machines (4 of them `.pre-g` copies), lost at a reboot |
**Every node, every module** (the assigner's assignments at revision 339, unchanged since 2026-11-18 02:08 UTC; the
node-engines' haves; read 00:47 to 00:54 CET):
| machine | placed | running | held | failed |
|---|---|---|---|---|
| the control node | 90 | 10 | 53 (entry missing) | 24 |
| the build node | 80 | 12 | 59 (entry asked) | 7 |
| the desktop | 83 | 24 | 33 (entry missing) | 26 |
| the laptop | 76 | 6 | 60 (45 entry asked, 15 entry missing) | 9 |
65 of the 66 failed wants fail for one reason: the want names no digest for the module's files, code or tools (the
A-430 stand-in, a want naming its parts, left half built). The one other is the desktop's node-engine ("operation not
permitted" unpacking a version). No service is failed on any machine; the 25 open conditions are warnings. Every
delivery module's want is held by the assigner's rule 2 (no passed pipeline at the graph's fingerprint); before it,
rule 8 held the 23 bus-state modules because the bus module's have is held although the bus runs. The haves are wrong
about what runs for three modules (the tool runner on two machines, the indexer): `node-engine.process-builds` is the
tool that says it, found only in this second reading.
**The module graph** (the indexer, trunk revision 512, source 1038): 193 modules; 269 package edges (published before
it builds), 178 toolchain edges, 208 provider and requirement edges, 212 served-verb edges (19 verbs served by no
module), 30 await edges; the acting-part and contribution edges are not in the graph's state. The other watched branches
stand at revision 1 since 2026-11-14. No tool answers a build order or a deploy order for a set of modules, the
difference between two revisions, a revision narrowed by module or edge kind, or which source commit a fingerprint was
built from; the whole revision is 1.3 MB, over the bus's message size. Those reads are tools milestone H4 builds in the
indexer and the assigner (one-question-one-tool; section 4, item 12).
**No pull request is checked today.** The checker's verdict verb asks the indexer `indexer_read_candidates`, which no
running indexer answers (503 no responders), so no `mesh/check` status is ever set; the forge calls every pull request
mergeable because main requires no status. Nine open conditions ask `indexer_read_modules` the same way. Tools were
removed or renamed while their callers still name them; by design 47 G the pipeline makes the check and the checker
goes (G-2), which milestone H1 builds for hq too (hq is a registered module whose one step is its Go checks).
**The root of it, in one sentence.** The design settled on one model (a change is a commit on a watched branch of a
registered module; the forge bridge says it, the indexer takes it in per branch, the runner starts exactly the movers,
the gate follows), but the code carries that model and the earlier per-pull-request model side by side, and the live
patches of 2026-11-16 and 2026-11-17 (the sweep, the source per merged message, the catch-up by comparison) were
written on the earlier one. Every list above is a consequence.
## 2. The approach, decided
1. **One model, no leftovers.** A change is a commit on a watched branch of a registered module (design 47 G §11,
ADR 0666 §6). The forge bridge says every move of a watched branch's head, and at its start reads every watched
branch's head and says it (G §11, A-236). The indexer takes a move in per watched branch (A-476: the commit, the
fingerprints of that repository's modules, a catalog revision; `take-in.taken` names the movers by A-476a). The
runner starts one pipeline per mover and nothing else (G §12, §112: never by a sweep). The gate moves the
source revision on `take-in.taken` alone (A-34, G §592). Everything of the earlier model goes: the gate's and the
bridge's pull-request paths, the source per merged message (A-464 series), the catch-up by comparison (A-463,
A-490k), the runner's sweep, the start-time `outdated` by digest comparison (G §375; a kind-1 dependent is started
by `package-published`, which the runner's durable consumer delivers also after a stop), the forge module's
merge-check machinery and its polls. Principles 1 and 7 settle this; design 10 names a change found by comparison
as a failure mode.
2. **Fix in place, every module; write one part again.** Each gap table judged its modules by the share of lines
built and by whether their events, verbs and kept data are the design's. All say fix in place, mostly by deletion,
but two parts: the assigner's want rule (about 2,600 lines of `wants.go` and the want half of its pass, written again
to A-478) and the indexer's take-in part (about 3,400 of its 34,000 lines: pending, source numbering, behind, the
branch take-in, the pull-request candidates and previews) is written again as one take-in per watched branch fed
by the forge stream alone; its storage, entries, pins, versions and verbs stay.
3. **The design first, then code.** Where the operator's words and the lead's live answers departed from the
written lines and records, the lines and records are brought in line before any code (implement-the-design,
design-it-as-it-should-be): section 4 lists them. No lead answer patches a design question this time.
4. **One clean state by hand, once.** The system cannot deliver the fixes to itself, so milestone H1's programs are
built from main after its merges and placed by hand on the four machines as one mutually consistent set, the
stale bus state is dropped, and from that moment nothing is placed by hand again: every later milestone is
delivered by a pipeline, and that delivery is its proof (principle 5). Section 5 is the step list.
5. **Milestones in dependency order, one release each**, each proven by one pipeline delivering it, with the
guards of section 7 so it does not rot again.
## 3. The six parts: findings and the decision per module
Each part's specification and gap table hold the line-by-line detail; this is the summary a reader needs to judge
the plan.
### 3.1 The forge bridge and the gate (mesh-delivery: the bridge and both seat contracts; mesh-catalog: the gate and the forge module)
Built 71, built otherwise 5, contradicts 10, missing 7, not judged 15 (of 108). No gap is large alone.
- **No delivery record ever ends.** The gate consumes only `take-in.taken`. It must consume the runner's
`pipeline-ended`, the node-engines' `running`, the `wait-held` and `wait-ended` events and the assigner's families
(G §5, §146) to write a record's trace and end it (G-3 "The delivery record").
- **Two paths move the source revision**; the per-merge one (A-464, about 330 lines) acts live and the design's
(A-34, about 75 lines) is left without effect. A-464 goes.
- **The per-pull-request model** is about 1,300 of the gate's 5,475 lines and about 1,050 of the bridge's 4,281.
It goes, apart from what the operator's answer on groups keeps (section 4, question 1).
- **The forge module** holds no failed pipeline step (`failed-steps` has 0 entries, so `merge-pull` refuses
nothing), and still runs the old merge-check machinery: `mesh/merge-gate` statuses, weighing kept in files on disk,
a one-minute poll and a ten-minute timer. All of it goes.
- **Decision:** fix in place, mostly deletion. Gate: consume the two events, end records, one source path, drop the
pull-request model. Bridge: drop the pull-message path, the checker's owed acts and the merge act. Forge module:
drop the merge-check machinery and the polls; find why `seen` is empty (the surveyor's guess: the hand-placed
runner says `step-ended` without commit and fingerprint). Seat contracts: drop `asks` and `turns` and the callers
lists (small).
### 3.2 The indexer and mesh-config (mesh-delivery: the indexer; mesh-catalog: mesh-config)
Built 70, built otherwise 8, contradicts 7, missing 4, not judged 18 (of 107). Seven medium gaps in the indexer are
one problem: the take-in's shape.
- **The take-in is the trunk's alone, fed by two paths**: a `merged` or `pushed` message of any branch lands in the
trunk's one view (a `pushed` message has no base), other watched branches get revisions only by comparing against
the gate's `source-moved`, one `pending` holds every branch, and the catch-up takes heads in outside `pending`.
- **Revisions are made at every keep, not only at a take-in**: "27 changed" counts entries whose stored form differs
from the newest kept revision; two revisions were kept at the 22:51 restart with no `take-in.taken`.
- **Pins** are judged at restart against a `made` key written once in the state's life and against the server's
pending count, which is 0 at start, so the last restatement counts at once and trunk.510 was removed while
pipelines named it. Source numbers live in memory and restart from the gate's number while later pipelines exist.
- **mesh-config** on main passes every 5 minutes, polls every minute and reads its states key by key (issue 1982);
the held pull requests mesh-catalog #708, mesh-contracts #16, mesh-sdk #200 and mesh-delivery #261 make it wake
on events and one deadline timer, reading from watched copies, and remove its pull-request path (ADR 0681).
- **Decision:** write the take-in part again (one take-in per watched branch, from the forge stream alone, movers by
A-476a, source numbers on the bus, pins restated by every asker and judged against what is pinned now, never
against a count); keep storage, entries, pins' state, versions and verbs. mesh-config: merge the four held pull
requests; its reads of the indexer and the assigner through module tools (principle 9) and its full pass per
event are a later milestone's.
### 3.3 The pipeline runner (mesh-delivery: mesh-delivery-pipeline)
Built 87, built otherwise 5, contradicts 2, missing 6, not judged 19 (of 119). No large gap; 4 medium, 9 small.
- **The sweep** (`StartUnstarted`) runs after every take-in and at every start; removing it is small. The held pull
request mesh-delivery #262 adds a third start path (`StartHeld`); it is closed, not merged.
- **The refused step ends naming an empty pipeline** are the assigner's composition runs on the Go build seat: the
runner reads the pipeline field before the asker field. Skip an end whose asker is not the runner (small).
- **Missing, medium each:** `toolchain-agreed` starts no kind-3 rebuild (G §376); nothing consumes `approval-carried`
(G §542); each repository's own checks are not a step (G-2); the start-time `outdated` and `runner_catch_up` (G §375)
do not exist, and by decision 1 they are not built: a kind-1 dependent is started by `package-published`, which the
durable consumer delivers also after a stop (section 4, item 7 says it as a line).
- **A bound on pipelines at once** has no design line; principle 11 makes it a setting (`pipelines-at-once`). A start
over the bound is written with no steps and placed when the runner's own `pipeline-ended` comes, no timer
(medium). What a waiting pipeline reports against G §12's `pipeline-stands` is a design line (section 4).
- **Timers found:** mesh-sdk's view catch-up asks again on a timer (against A-490k's "no timer"); a one-minute
ticker while the step log is full. Both go in the class fix of section 3.6.
- **Decision:** fix in place. The self-hold A-446 removed is already gone from main (commit 070a5dd3).
### 3.4 Builds, the builder and the registries (mesh-delivery: the builder, the artifact holder; mesh-catalog: the build modules, the forge's package registry, the image registry)
Built 73, built otherwise 3, contradicts 8, missing 2, not judged 24 (of 110). 85 per cent of the judged rows
built; no large gap, five medium.
- **A failed key taken again skips a version** (G §369): the reserver treats a key's own standing reservation as its
floor unless the source says rebuild, and only the hand tool `builder_build_again` says so; a failed key taken again
by a look, an event or the start moves its number on by one. This is the 0.1.19 skip. Small.
- **The pre-G numbering still runs beside the reservations** (design 51's versions, replaced): it numbers every trunk
build from its own state and floor, can hold a build waiting for that floor, and its late look writes the live "done
build no version reserved" line. Medium; it goes.
- **The builder is not entered only through the runner's `build` step** (G §473, A-97): it builds every catalog entry
it hears and still follows the gate's `source`. Medium; it goes.
- **`build.ended` carries no version** (A-430b), and builds of other branches reserve nothing.
- **The build modules** pull their three queues in turns, not deliveries first (ADR 0525 §4, G §86; a code comment
cites an operator's yes of 2026-11-15; the surveyor did not search the knowledge base for it, so H2's prepare does: if
the yes was recorded, the record and the lines are out of date, not the code), and when idle re-pull every 5 seconds, a poll. The artifact
store is read by raw HTTP in group runs; the registries are reached through bus verbs. Two copies of the client that
asks `reserved` differ (the forge's and the image registry's).
- **The publish again** runs in one shape, A-457's retried items with A-473's ask at build end as their first try;
§588's event path is gone and its queue remains as plumbing. Live, all 42 publish retries ended after 8 tries,
unreleased, and 37 reservations built since 2026-11-18 were never published (cause a guess, in the table).
- **From the specification:** a module with no registration has no pipeline and is never built, so
mesh-delivery-sdk's missing registration blocks mesh-delivery-contracts by design; a `required` step ending
`nothing to run` holds the delivery and no line works it out again later; no line has the builder reserve an old done
build by itself. Each is a design line to write (section 4, item 11).
- **Decision:** fix in place, all three. Builder: remove the numbering, the gate-source follow, the builds without a
step ask and the other pre-G mechanisms the table lists; fix the reserver's floor and the version on `build.ended`.
Build modules: deliveries first and no idle poll in the shared step runner; the store read over the bus. Registries:
one `reserved` client, the forge's form moved into `mesh-delivery-contracts` as the surveyor recommends. The delivery
budget (G-2) is checked by nothing; medium, H2.
### 3.5 The assigner, the node-engine and the tool runner (mesh-delivery: the assigner; `mesh-host`: the node-engine; `mesh-tools`: the tool runner)
Built 56, built otherwise 8, contradicts 9, missing 3, not judged 7 (of 83). Assigner 31 of 44 built, node-engine
17 of 27, tool runner 8 of 12.
- **The want rule A-478 is not built** (the newest released version whose pipeline passed, on every machine that
places the module; the operator, 2026-11-17). Every old rule still holds wants: canary, grant, provisions, served
verbs, bus state, the acting-part waits (about 450 lines), the `version-delivered` holds (about 500), the parts
check (about 250), the rest about 300. All of it goes; the backup, the yes on a failed backup or a held revert, and
A-478b's order waits on one machine stay (the order waits reshaped to order one machine's apply, not hold wants).
- **The assigner reads every have** whole and with history (§520 says it goes); wants are not written from the kept assignment graph revision. Medium each, H1. (The node-engine's read of
every node's record stays: it feeds the composer; H-A-60 corrects the earlier reading of §459.)
- **The shanks shadow fault**: the entries client leaves an entry `asked` after a transport failure and never asks
again; about 110 entries on shanks have stood `asked` since 2026-11-18 03:09. Ask again on failure, with a bound
(small). The surveyor's reading, to be confirmed by `entry-again` on one entry during the clean state.
- **The tool runner:** A-490m is ready on mesh-tools #77 (merge); it lacks a test that starts it whole.
- **Tests:** the node-engine has 1,719 unit tests against a budget of 500; every change to it shrinks that.
- **Decision:** fix in place, all three. The want rule is rewritten to A-478 in `wants.go` and the want half of the
pass; the old holds are deleted.
### 3.6 The status view, the watchman, health, the tools and the grants part (mesh-delivery: the view, the watchman, the grants part; mesh-catalog: the bus's module; mesh-tools; mesh-sdk)
Built 56, built otherwise 11, contradicts 5, missing 11, not judged 9 (of 92).
- **The status view, the watchman and the grants part read other modules' buckets directly**, against ADR 0596: the
view watches twelve such buckets, retries each every 5 seconds, and still follows the teller's answers and the gate's
source, which §512 retires. Large, with the want rule, the take-in and the SDK's generic state tools (the fill against
a cap in every module's tools, the grants part's `filling` and `room`) the large gaps of the survey.
- **The kind of fault behind issue 1982 is in more modules than mesh-config.** The grants part recomposes everything
and reads its own states key by key on every change; the indexer re-reads every module, every graph key and every
manifest after each verdict, import or source move (its modules state stands at revision 1,789,962); the view
retries twelve watches every 5 seconds; the forge module polls every minute; the build modules re-pull every 5
seconds when idle; mesh-sdk's view catch-up asks again on a timer. The gap table's section 5 has the table of
modules, functions and intervals. The fix belongs in mesh-sdk, for every module at once (fix-a-bug-met-twice).
- **`builder_stuck` times out** for a fixed cost, measured in the tool runner's journal on shanks: 1,010 values took
52.5 seconds and 53 values took 44.5 seconds. Each call starts a tool process that lists every key of `builds` and of
every build seat's `steps`, then reads one value per request. The builder keeps its own index of what is building
and answers from it. Medium.
- **The runner's live seat serves five read verbs and no act**; main has them all (commit 8fa1b8ae). The surveyors'
guess is a hand-placed build from before it, or an older tools bundle; the clean state ends either.
- **Who may call what** stands in two forms: §610's class defaults and A-434's stand-in that every account may do
everything. **The lead's answer: principle 6 settles it** (inside the mesh every module is trusted, who may do what
is not a question): A-434 stands, the callers lists go from every seat contract, and tests 40, 51 and 85 are not
checked while it holds.
- **No line names rates on the bus**; the bus's module gives connections and consumers, not rates. A tool to build in
the bus's module (principle 4), named in section 4 so the design says it.
- **Decision:** fix in place, every module. View: replace the bucket watches with events (the large gap, H4).
Watchman (16 of 23 built) and condition keeper (14 of 18): fix in place; their live builds predate milestone G. Grants
part: the re-read through the SDK shape in H4, its move from reads to events a release of its own (H4b). Bus module and tool runner: the
rate read and the SDK's generic state tools.
- **The wake-up rule is a class fix:** one shared shape in mesh-sdk (watched copies of a module's own states, a pass
only on a changed input, one deadline timer for its real deadlines, no poll), every delivery module moved onto it in
H4, and the review refuses a timer, a poll or a full re-read in any delivery module from H1 on.
## 4. What the design must say before code (milestone H0)
The design's lines and the records carry the operator's later words only in the lead's answers, and in places not
at all. Before any code, `hq-design-writer` writes these as design lines in this milestone's part and
`hq-record-writer` proposes the records, in one batch read by the four reviewers by architectural domain (playbook
02). The lead decides none of them.
**Questions for the operator** (each changes how the operator works or removes data; the lead's recommendation first):
1. **How a change across repositories lands together.** The design forms a group from pull requests' head branch
names (G §42, §716); the operator's rule is that the mesh knows only commits on watched branches. Recommendation:
a group is a trailer in each member commit's message (`Mesh-Group: <name>`, the name chosen by the author); the
forge bridge reads it from the commit and the gate forms the group from it; nothing is read from a pull request.
The alternative is no groups at all, with the order between modules left to the artifact dependency edges, which
does not cover a seat contract change that several modules must follow at once.
2. **Data the clean state removes:** the gate's `merges`, `owed`, `asks` and `pulls` buckets, its 833 open records,
the indexer's stale pins and the 5 pipelines running since 2026-11-19 midday, every held or failed want, and the
19 drop-in files. Recommendation: remove all of it; none is a record anyone reads (no tool reads what the buckets
hold), and the delivery records of the one model start from the clean state.
3. **Pipelines one at a time** until the operator raises it: the setting `pipelines-at-once` with default 1.
Recommendation: yes for the clean state and the first milestones; the operator raises it when the chain has proven
itself on about ten deliveries.
4. **The one hand placement** of milestone H1 at the operator's terminal, one command at a time as before, after
which no pack is run again except the ones this plan names. Recommendation: yes; it is what the operator offered.
**The operator's answers (2026-11-20 about 01:10 CET).** Question 2: "I don't care about old data at this moment, I want
a working mesh again": the stale state goes. Question 3: "for my part, pipelines don't exist, or a group of commits
form one big pipeline, but parallel pipelines sounds like a very bad idea": no two pipelines run at once, and one
take-in is one pipeline (design 47 G §44 already says it for a group: one source revision, one pipeline per watched
branch; the single commit is the case of one member); the setting of item 7 keeps the bound at one by its default and
the design says serial. Question 4: "I don't mind doing hand placements": yes. Question 1: the operator's first idea was a
build plan and a deploy plan per change (ADR 0238 §2, "one commit, one change plan", the glossary's *delivery plan*,
deleted at release 6 of ADR 0429 and replaced by ADR 0666's pipelines per module ordered by edges, from research 086);
what remained open was how the mesh learns which commits belong together, since ADR 0666 §13 reads a shared branch
name through pull requests. The operator, 01:15 CET: since every version is deployed by a merge into main, an action,
they have no objection to kicking the build-and-delivery process off by hand instead of listening to the forge's
hooks; the lead named principle 3 (a start a person forgets is a silent non-delivery) and proposed the merge through
the mesh as the start with the forge's event kept as the watchdog; the operator chose it (01:20 CET, "A, go
ahead"): one call of the seat `git`'s verb `merge-pull` naming one or more pull requests is the delivery's start and
the group; nothing reads a pull request after it; a head moved outside the mesh raises a condition and delivers
nothing. Item 1 below is answered so; item 6 is written from it. The operator also said they would not mind a start from scratch; the lead's answer is in
section 2 (fix in place, two parts written again) with the reason: 78 per cent of the lines are built by their contract,
and the parts that are the earlier model are named and bounded.
**Design lines and records to write** (no operator decision; `hq-design-writer` and `hq-record-writer`):
5. The take-in by A-476, as a record: it changes ADR 0666 §6 and ends ADR 0633 §1's hold for manifest validation
and the "pending revision"; the manifest validation becomes a pipeline step with a name, a server and a policy
default (A-476 names none), and `manifest-refused` and the cycle refusal move with it.
6. The forge bridge's one message for a watched branch's head moving, replacing the `merged`/`pushed` pair where
they differ (a `pushed` message carries no base today), and the end of A-464 to A-464e, A-463 and A-490k.
7. One take-in, one pipeline, and no two at once: the pipeline is per source revision of a watched branch, its steps per
mover in the graph's build order, delivered in the deploy order (the operator, 2026-11-20); the setting
`pipelines-at-once` with default 1 (principle 11), the order waiting take-ins are placed in, and that a waiting
pipeline is not owed progress under G §12. A record, since ADR 0666 §1 and §7 speak per module.
8. The want rule A-478 and A-478b as design lines, with the list of holds they end (§266, §268, §269, §376, A-189,
§524) and the reshaped order wait on one machine.
9. The wake-up rule for every delivery part (section 3.6) as a design line in design 47's main file, with how it is
checked (the review and the integration test that starts the module whole).
10. The small contradictions the specifications list, corrected in place: G §5's unprotected-branch refusal (removed
by the operator, still in ADR 0666 §3), G §654 (replaced by ADR 0681 §1), A-449's `pinned`/`freed` publisher,
test 53's `forge-made`, G §476's "one entry per module of that revision", ADR 0666 §12's three open asks (A-424),
§386's per-module durable consumer (A-397).
11. The builder's lines the specification found missing: a done build with no reservation is reserved by the builder
itself (not only by a hand tool); a failed fingerprint built again keeps its reservation; a `required` step with
nothing to run is worked out again at every pipeline, not only at the seed; a registered module whose pipeline has
no steps is refused at registration, naming the step (test 67); and the record of the build modules' queue order
(deliveries first, ADR 0525, or the turns the code takes on an operator's yes no record holds).
12. The reads the status view, the watchman and the grants part make of other parts' buckets, each turned into the
event or verb of the part that owns the data (ADR 0596), and the rate read on the seat `mesh-broker`.
13. The read tools the second live reading found missing (one-question-one-tool): in the indexer, one revision
narrowed by module or edge kind, a non-trunk branch's revision, the edges by kind, the difference between two
revisions, a build order for a set of modules, the source commit a fingerprint was built from; in the assigner, a
deploy order per machine; in the node-engine, its own build. Also the checker's and the conditions' calls of
indexer tools no indexer serves (`indexer_read_candidates`, `indexer_read_modules`), removed with their callers.
## 5. The clean state, by hand once (milestone H1's delivery)
Milestone H1 is "the one chain": the smallest set of fixes that makes a commit on a watched branch reach a running
module through the design's path with no hand act, in every module of the chain. It is built, reviewed and merged
like any milestone, but its delivery is by hand, because the running system cannot carry it. The steps, in order;
the operator runs each pack one command at a time and says "done"; the lead checks each with the tools before the
next:
1. **Freeze.** No merge to any delivery repository but H1's own. The runner on novox is stopped through the service
seat so no take-in starts a pipeline during the freeze; the assigner stays, so nothing moves.
2. **Merge H1's set to main**, in this order, each reviewed: mesh-contracts #16 and mesh-sdk #200 (held), then
mesh-catalog #708 and mesh-delivery #261 (held, mesh-config), mesh-tools #77 (held), and H1's own pull requests
(indexer take-in, runner, gate, bridge, assigner, node-engine). mesh-delivery #262 is closed as superseded. The
stopped runner starts nothing; the indexer takes the commits in and the gate follows, as the old programs still
running during the freeze do. The new programs take every head in once, at the seed (step 5.9).
3. **Build H1's programs from main** with the packs (the g-start phases, one per program), on shanks and novox as
before, from main's head after step 2 so that main is what runs.
4. **Take the stream snapshot that is the drop's rollback** (design 47 H §765) and test its restore; nothing is
dropped yet. The drop-ins are removed and the units the node-engine writes take their place as the wants compose.
5. **Place the programs** in the order the graph gives (derived by the reader of 00:54 CET from the package,
toolchain and provision edges; no tool answers it yet), each step read with the tools before the next:
1. keep the bus, the forge and the image registry running; make the bus module's have `running` (else the
assigner's rule 8 holds the 23 bus-state modules);
2. the packages first: `mesh-sdk`, `mesh-contracts`, `mesh-delivery-sdk` published (every Go module needs them;
`mesh-delivery-sdk` needs its registration first, section 3.4);
3. build with the running Go build module (it is what breaks the cycle "every Go module, the build module itself
included, is built by a running build module"), the builder first, then the indexer, the forge bridge, the
runner, the assigner; then the three build modules (they need the builder's package), the gate (needs the
indexer's and the bridge's packages) and the grants part; then the node-engine;
4. place on the control node: the indexer, the forge bridge, the gate, the forge module, mesh-config; on the build
node the builder; on the desktop the assigner;
5. place the node-engines: the control node, then the build node, the desktop, the laptop;
6. place the watchman, the status view, the teller, the grants part and the hand-act log on the control node;
the checker is not placed (it goes, section 1);
7. after each machine, read its health, its first views, its `process-builds` against its haves, and the bus's
consumers;
8. **drop the stale state** (question 2's yes), now that the new programs run: every state design 47 H §764
retires, the records, the pins, the pipelines of the earlier model, the stopped runner's queue of old
`take-in.taken`, the held and failed wants, each through the tool H §765 names, the pack saying what it
deleted, counted;
9. **seed every watched branch's first source revision** with `gate_source_seed` (H §768): each branch's current
heads, taken in with no mover, so the newest catalog revision names them; read and counted, and a bridge
restart then raises no `head-untaken`;
10. a machine away at this moment gets its hand placement when it is back, before anything else (H §772).
6. **Start the runner last**, with `pipelines-at-once` at 1.
7. **Prove it.** One single-module change (a comment in a module with lint, unit and composition steps only), merged
to main through a merge call (`merge-pull`, design 47 H §734), followed from `take-in.taken` through `pipeline-ended` to the node-engine's `running` and the gate's
ended record, with no hand act; then one two-module change along a dependency edge (mesh-sdk and a module that
requires it published), merged in one merge call, the same way. Each proof read with the tools and quoted with its times.
8. **Lift the freeze.** From here every merge is delivered by its pipeline; a hand pack is a breach the lead names.
## 6. The milestones after the clean state
Each is one release of playbook 07 (prepare by `mesh-preparer`, develop, one review, one check, delivered by its
own pipeline), in this order, the next starting when the previous one's delivery is read on the machines:
| # | outcome | repositories | proof |
|---|---|---|---|
| H0 | the design says the one model whole (section 4) | hq, the knowledge base | the four reviewers by architectural domain approve the batch; the operator's four answers are in |
| H1 | the one chain works with no hand act (section 5) | `mesh-delivery`, `mesh-catalog`, `mesh-host`, `mesh-tools`, `mesh-sdk`, `mesh-contracts` | the two proofs of step 7 |
| H2 | the builder, the build modules and the registries follow the latest lines (section 3.4; versions, publish again, the floor, a step with nothing to run, a module with no registration) | mesh-delivery, mesh-catalog | a version is skipped by nothing; every registered module has a pipeline with steps |
| H3 | the gate and the forge module carry only the one model; groups by the operator's answer; the forge module without its merge-check machinery | mesh-catalog, mesh-delivery | a group of two repositories delivers as one; every delivery record ends |
| H4 | every delivery part wakes on its inputs alone and is steered by its tools (sections 3.6, 7): the shared wake-up shape (mesh-config's full pass per event and its reads through module tools, the indexer's re-read after every verdict, the node-engine's retry clocks, the build modules' idle pull), the view and the watchman without reads of another part's state, the SDK's generic state tools with the fill against a cap, the missing tools per module, rates on the bus | `mesh-sdk`, `mesh-delivery`, `mesh-catalog`, `mesh-host` | the bus's slow consumers and behind counts at 0 for an hour; every module's tools pass the principle-4 table |
| H4b | the grants part says what it holds as events and reads nothing of another part's bus state (ADR 0596) | `mesh-delivery` | the grants part's own `filling` and `room` and no bucket watch in its code |
| H5 | tests to budget and one integration test per module that starts it whole (ADR 0548); the catalog check that refuses a module whose state has no read tool | every delivery repository, mesh-catalog's check | the check reports each module's counts within budget |
Milestone H1 is large for one release (six repositories); it is not cut (how-work-is-done), its subtasks are split
at the prepare, one developer per repository on the larger model for the indexer and the gate (their parts meet at
`take-in.taken` and the source revision), the smaller model for the rest.
## 7. The guards, so it does not rot again
- **An integration test per module that starts it whole** against a real bus and store (ADR 0548), run in the one
check per release, and the change to how a module runs carries it in the same commit.
- **The review reads against the one model:** a sweep, a poll, a timer for another part, a comparison in place of an
event, a read of another part's state or a per-pull-request path is a finding that fails the review.
- **The tools table per module** (principle 4) in every pull request of a delivery module, and the catalog check of
H5 that refuses a module without its read tool.
- **No hand pack after the clean state.** A delivery that fails is fixed in its repository and delivered by its
pipeline; a pack is a breach the lead names, with the one exception the operator grants in words.
- **The test budget** per module (50 integration, 500 unit) reported by the check; a module over it shrinks with
every change.
- **Live answers become design lines the same day** (implement-the-design): a lead answer that patches a model
question is a breach the reviewer reports.
## 8. What the plan does not do
- It does not merge the six held pull requests now; they merge in H1's step 2, and one (#262) is closed.
- It does not touch the controller, the vault or the recovery module beyond what the chain needs; the recovery
module is not placed and is a later milestone's.
- It does not change the catalog's module set or the build nodes (novox's build agent stays paused).
- It leaves what the surveyors could not read as named guesses, each with how to check it, in the gap tables'
last sections; the prepare of each milestone checks them.
## 9. H1's develop: who builds what, and why (the lead, 2026-11-20 02:27 CET)
Six `mesh-developer` agents, one branch each, from the six build maps of the prepare (the lead's working folder,
`prepare/H1-*.md`) and the lead's answers H-A-21 to H-A-62; each commits locally and cites its lines; none pushes before
the one review (`mesh-code-reviewer`, at most three rounds).
| repository | branch | scope | model and reason |
|---|---|---|---|
| `mesh-delivery` | feat/47-H1-contracts-indexer-bridge | the seat contracts (C0 to C3, C-R, C-W), the indexer's take-in written again, the forge bridge | larger: its parts meet at `source-moved`, `take-in.taken` and the contracts every other branch starts from |
| `mesh-delivery` | feat/47-H1-runner-assigner | the runner's queue and events, the assigner's want rule and tiers | larger: it meets the indexer at the pins and `take-in.taken`, and the node-engine at the want's form |
| `mesh-catalog` | feat/47-H1-gate-forge | the gate's merge-call path and record, the forge module's merge call and `merge-called`, #708 onto main | larger: the gate and the forge module meet at `merge-called` and the bridge at `head-moved` |
| `mesh-host` | feat/47-H1-node-engine | the entries asked again, the apply by rank and `apply-order`, the want by version | smaller: a leaf, its contract given |
| `mesh-tools` | feat/47-H1-tool-runner (from #77) | the per-verb `timeout`, no `admitted` hook, the whole test | smaller: a leaf |
| `mesh-sdk` and `mesh-contracts` | feat/47-H1-seats (from #200 and #16) | the copies, `timeout` in `seatdef`, no `Callers`, `placement`'s `build`, `apply-order`, `held-back` gone | smaller: contracts and copies, published first |
The order between branches is the prepare's dependency table: contracts and copies first (published as the next
mesh-sdk and mesh-contracts versions at the clean state's step 5.2), then the modules; the runner-and-assigner branch
rebases onto the contracts commits before the review.
@@ -0,0 +1,570 @@
---
layer: to-be
status: in-progress
design: 47
milestone: H
updated: 2026-11-20
decisions:
- "ADR 0682"
---
# 47, milestone H — the lead's answers
The lead's one-line answers to the questions the design writer and the builders could not answer from the records,
each tested against the principles (`00-META/principles.md`) and naming the one that settles it (implement-the-design).
A question no principle settles goes to the operator or to a record; it is marked so here.
## From the design writer (2026-11-20 01:36 CET)
- **H-A-1 A member refused after every member was judged** (a forge failure between the judgement and the last merge):
the forge module says the members that landed, marks the call `refused` and raises the finding `merge-partial`;
the landed members are taken in as one source revision, so what landed is delivered and what did not is loud.
Principle 3.
- **H-A-2 The delivery order once the want holds for nothing**: the runner's `pipeline-ended` carries its movers in
ADR 0666 §14's delivery order, and the node-engine applies one pipeline's wants on its machine in that order
(A-478b's order on one machine). The order travels in the event; no part reads another part's state for it.
Principles 1 and 9.
- **H-A-3 A `required` step whose run ends "nothing to run"** counts as passed for the want, as `bypass` does: a hold
with nothing behind it protects nothing. Principle 7. A clause of ADR 0682 says it (asked of the record writer, 01:38).
- **H-A-4 Reads whose owner says no event today** (the provisioner's provisions, the vault's bus accounts and node
logins, the enrolment module's enrolments, the grants part's user list): each owner says one change event and the
readers consume it, in milestone H4b; until then the read stands and is named a leftover in the gap table.
Principle 1 (ADR 0596).
- **H-A-5 A revert against the whole want rule**: a return to an earlier build stays one value in the placement, read
by the assigner before the rule, the one exception; ADR 0682's review raised it and the record says it. Principle 4.
- **H-A-6 The seat that serves `validate`**: the seat that runs the composition step, which G §22 names `mesh-wants`;
ADR 0682 §4's "mesh-module-assigner" is corrected to that seat (asked of the record writer, 01:38). Principle 9.
- **H-A-7 The main file's size** (258 KB against the 80 KB bound of playbook 02): the reshaping of design 47's main
file into its milestones' parts is a change of its own after H0, not folded into this one (rules-are-weighed: the
bound protects a reader, and the plan's reader has the three H part files; a 180 KB move in the same pull request
would hide the lines under review). Said to the operator at 01:38.
- **H-A-8 The build modules' queue order**: deliveries first (ADR 0525 §4), as §753 writes; the operator's yes to the
turns of 2026-11-15 is in no record, so the record holds. If H2's prepare finds it, the record gets an insight.
## From the review by architectural domain (2026-11-20 01:40 to 01:44 CET; four reviewers, one round)
- **H-A-9 How the apply order reaches the node-engine**: the want carries its `pipeline` and its `rank` in that
pipeline's delivery order, written by the assigner from `pipeline-ended`; the node-engine applies a pipeline's wants
on its machine by rank and consumes no event of the runner. The apply-order read tool is the node-engine's.
Principles 9 and 12.
- **H-A-10 Order across machines** (ADR 0666 §14's "delivered before" edge between machines): the order lives inside the
one pipeline, never as a hold of a want on another delivery (A-478 b: "the order between modules moves into the
pipeline"): the assigner writes one pipeline's wants tier by tier in §14's order, a later tier once the earlier
movers report `running` on their machines, with a bound per tier (a setting) whose end ends the delivery record `failed` with the finding `tier-late`,
the pipeline's own outcome staying what its steps said; the
composition step composed the whole graph before any want was written. ADR 0682 says it (the record writer, 01:50).
Principles 3 and 7.
- **H-A-11 Publishing an event family stays the producer's**: every account may call every verb (ADR 0682), but a
module publishes only the events its manifest declares, as ADR 0666 §21 has it for a step's result; the mechanism
stays whole, who is on which side is not asked (who-may-is-not-the-operators-question). An enrolling node's account
keeps its own grant. Principle 6.
- **H-A-12 The indexer's consumer and a blocked `source-moved`**: one durable consumer per watched branch; a
`source-moved` the indexer cannot take in (the store full) is held, unacknowledged, until the bus module's `room`
wakes it, never on the ack timer; a hand tool skips it with `why`, written in the hand-act log. `take-in.pending`,
`take-in-waits` and `indexer_pending` stay (ADR 0633 §5). Principles 1, 3 and 4.
- **H-A-13 A source revision written once per call**: the gate keys its write by the call id with compare-and-set, so a
redelivered `merge-called` numbers nothing twice. Principle 3.
- **H-A-14 The waiting queue of the runner**: ordered by the runner's own counter at the moment it writes the pipeline;
placed at the runner's start from its own state and on every end, a cancel and a set-aside included; a finding when
pipelines wait while none runs; a pipeline waiting on the operator's `approval` step does not count against
`pipelines-at-once` and re-enters the queue first when approved; the queue's cap is a setting. Principles 3 and 11.
- **H-A-15 The clean state's seams** (plan section 5): before the runner starts, every watched branch's current head is
its first source revision with no movers (§745) and the newest catalog revision names it, read and counted; the state
of the earlier model is dropped after the new programs run (after step 5.6), each item through the tool named for it,
the backup snapshot being the rollback; every new durable consumer starts at the newest message and refuses an event
of the old form with a journal line; the stopped runner's queue of old `take-in.taken` goes with the state; a machine
away at the clean state gets its hand placement when it is back, before anything else; the forge's branch protections
drop the required statuses `mesh/merge-gate` and `mesh/repo-check` in H1. Principles 2 and 3.
- **H-A-16 Where H1's integration tests run before its merge**: once, locally against an embedded bus, said in each
pull request (how-work-is-done allows it); the chain's live proof (plan step 7) is H1's check; from H1 on the
pipeline makes the check. Rules-are-weighed, said.
- **H-A-17 The whole tests**: one per module, in that module's repository; tests 110, 112 and 113 are split per module
and the chain stays the live proof; the design gives the count per module per release and names the retired tests
that free room (the budget is per module, 50 and 500).
- **H-A-18 The forge module's call**: a call key written before the first merge and said again at start; `refused` in
the event's body; `merge-partial` keyed by the call, cleared when a later call lands the refused members or by a
hand clear; tools `forge_calls` and a say-again; `by` recorded beside the caller's bus account; `failed-steps` is
written from the runner's `step-ended` (mover, commit, fingerprint). Principles 3 and 4.
- **H-A-19 Small forms**: no pin for a take-in with no mover; a call with two members on one branch names the last
member's commit in call order; `package-published` carries the source revision that published and its pipeline pins
it and belongs to that merge call's delivery record; `pipeline-ended` carries per mover the released version and
fingerprint and the delivery order, on the subject `...pipeline-ended.<branch>.<source revision>`; `pipeline-failed`
is one finding per failing mover, cleared by that module's later passed pipeline; every fixed value (30 days, 64 MiB,
60 minutes, 10 minutes) is a setting with that default; §765 drops every state §764 retires. Principles 7 and 11.
- **H-A-20 The main file's size**, a must for three reviewers: the lead's bending of the bound (H-A-7) is said to the
operator at 01:48 with the question whether the reshape follows H0 as its own change; until the answer the bound
stands bent, said.
## From H1's prepare (2026-11-20 01:55 to 02:20 CET; six build maps, 92 questions merged in the lead's working folder)
Each answer names the item of the merged list (Q1 to Q92), then the principle. "Both" means the preparers agreed.
Where two preparers disagreed, the chosen one is named.
- **H-A-21 (Q1)** `merge-pull` answers once, at the call's end, naming `call` and each member's outcome. P1.
- **H-A-22 (Q2)** Its caller `id` goes (the call names it); an already-merged member is refused `already-merged` with
its commit; the answer is `{repository, number, state, commit|why}` per member; `protected` goes; `calls` is declared
in the seat definition. P3, P7.
- **H-A-23 (Q3)** A kept stream's age and cap are its definition's `keep` (30 days, 64 MiB as defaults there); the
word "setting" is dropped from those lines. H-A-19 is read so: a value stated once outside code. P11.
- **H-A-24 (Q4)** A call is 16 lowercase hex characters, one subject token; `hand`, `seed`, `by` and the time live in the
record's trace (sdk). P8.
- **H-A-25 (Q5)** `record-opened` and `record-ended` carry `branch`, `source`, `call`; `milestone` stays as
`<branch>.<source>` for the teller and the watchman (cat); the verb `source` answers `call`. P7.
- **H-A-26 (Q6)** `source-moved`'s wildcard has two tokens; its body as §737 with `v`; every decoding reader is named
with its change in its repository's map. P7.
- **H-A-27 (Q7)** `head-moved` on `forge.<owner>.<name>.<escaped branch>.head-moved` under the module stream prefix; its
form in `forgemsg`, series 0.1. P8.
- **H-A-28 (Q8)** Everything of the earlier model leaves in H1: the gate's states and `approval-carried`, `groups` and the
group model, the forge module's merge-check machinery, the knowledge base's `groups` invoke (cat); `heads` is declared
in the seat definition. One model, no second one left running. P7; ADR 0682 §2.
- **H-A-29 (Q9)** §738's delivery record is built in H1: the gate consumes the new `take-in.taken` for entries and
outcome and reads a record by its key `<branch>.<source>`, never every record. P3.
- **H-A-30 (Q10)** The grants part makes one durable consumer per registered watched branch from the registrations
(`MaxAckPending` 1), as it makes every consumer today; mesh-sdk binds a consumer by the name its caller gives;
`source-moved` gets a kept stream (sdk, with ib's stream). P7 over P12 here: the maker of consumers exists, and a
second maker would be a second mechanism.
- **H-A-31 (Q11)** `take-in.taken` and `take-in.pending` carry only the lines' fields, plus `by` and `why` for a hand act;
readers pair by `<branch>.<source>`. P7.
- **H-A-32 (Q12)** The catalog revision's number is the source's; its name `<escaped branch>.<source>` for every branch,
the trunk included; written once by read-before-write under the branch's one-at-a-time consumer. P3.
- **H-A-33 (Q13)** The source value carries `source` and `call`; the next number is the branch's newest plus one; a
`merge-called` whose call the newest already carries writes nothing. P3 (with H-A-13).
- **H-A-34 (Q14)** The assigner builds the validator from the change's heads on `node-build-go` as it builds the
composer, its input on `mesh-wants`' `input`; `RefusedCycle` moves to `mesh-delivery-sdk/graph` first; the program's
source stays where it is until a later cleanup (ra). P9; ADR 0682 §5.
- **H-A-35 (Q15)** A pipeline's kept value holds `movers` as `{module, commit, fingerprint, repository, tier}`; each step
result names its module; `list` filters by a mover; the runner's contract lands first. P7, P10.
- **H-A-36 (Q16)** A runner state `queue` holds `queue.next` and one key per waiting pipeline; the pipeline's outcome
value is `waiting`; an over-cap start is acknowledged and kept there, never left unacknowledged. P1, P3.
- **H-A-37 (Q17)** A want keeps `fp`, `hold` and `words`; `parts`, `rule`, `newest`, `kept-on` and `composed` go; `rank`
is an integer from 1, absent for a placement's `build` and for the node's own want (host's set, ra's drops). P7;
ADR 0682 §8 ("never digests" reads `fp` as the build's name).
- **H-A-38 (Q18)** A candidate's `added` names a version alone; the shadow resolves it as it resolved parts; `parts`
leaves the assigner seat's contract. P7.
- **H-A-39 (Q19)** `ModulePlacement` gains `build` (one row per branch and build), a fingerprint; the assigner wants the
version released at it. P7 (with H-A-5).
- **H-A-40 (Q20)** The next tier is released on `running` matched by the mover's fingerprint from `pipeline-ended`;
`running` gains no version in H1 (ra). P7.
- **H-A-41 (Q21)** The callers type and functions, every holder's list, the step runner's asker judgement and the tool
runner's `admitted` hook go in H1, in one group; the vault's enrolment caller stays; a step run carries `asker`. P6;
ADR 0682 §10.
- **H-A-42 (Q22)** H1 carries a mesh-sdk change beside #200: the new byte-equal copies of the seat definitions and the
checker's copy dropped, published first as the next version; §762's "mesh-sdk in H4" is read as the wake shape alone
and corrected in place in this branch. P5.
- **H-A-43 (Q23, Q24)** The per-verb `timeout` is built in H1 (a merge call of several members is cut at a fixed 30 s
otherwise): the field in the seat definition and its schema, whole seconds 1 to 600, others refused; `merge-pull`
names 120; the tool runner's own default is the setting `call-timeout`, 30 s; every caller and the serving runner wait
it; module processes through mesh-sdk. §760's "H4" is corrected in place. P3, P11.
- **H-A-44 (Q25)** Writers the maps did not name: the watchman's and the view's take-in readers, `sourcebranches` and
`meshcatalogclient` are the indexer-and-bridge developer's; the teller, the knowledge base's and the issue tracker's
readers are the gate-and-forge developer's; mesh-sdk's copies are the sdk developer's; the knowledge base reads
`pipeline-ended` in place of `group-ended`. The lead's order of work.
- **H-A-45 (Q26)** The word is `want:version`, a constant of the node-engine seat contract, stated in `manifest-reads`
and read from `manifest-reads-changed` alone; the assigner holds any node not stating it (host). P8, P1.
- **H-A-46 (Q27)** The apply order is a read verb `apply-order` on the seat `node-engine` (contract and sdk copy first),
one row per unapplied changed want: `module, pipeline, rank, position, why, waits`; H-A-9's "read tool" is read so.
P4, P9.
- **H-A-47 (Q28 to Q36)** A member whose base is no watched branch is refused at judging, naming the base (P3). The
call's value gains `said` (P3). A call past retention is deleted on each new call's write, oldest first (P1). A merge
call with no caller account the tool runner proved is refused, saying why (P3). FORGE-1 builds `step-unread`; the
clean state reads `failed-steps` after the first failed step; a one-event read tool is H4's (P3, P4). A session reads
its record by `call` through the gate's verbs after the answer, then waits on `pipeline-ended`, re-reading (P1).
"The tool runner's `merge-pull` tool" reads as the seat `git`'s definition and its sdk copy (P8). The seed opens no
record (P7). `gate_source_start` and `gate_source_again` stay, the first writing through the seed's path (P4).
- **H-A-48 (Q37 to Q43)** Every indexer and bridge part no line names (`Src` stamps, the builder-log index,
`TakeInMerge`, the own-build hold, previews, `taken`, the `pull` and `open` messages, the bridge's finding writer) goes
in H1 and is added to §764's lists (P7). `pins-stated`, `heads-replaced`, `pinned`, `freed` and the gate's pin
operations go; the indexer pins in its own state (P7). The gate's stalled conditions go, the watchman's `record-open`
being the one signal; `untaken-bound` runs on the gate's one timer; the start loops are waits for the bus, said (P7;
ADR 0682 §11). `transition` leaves `emits` (P7). A record's member is `<repository>@<number>` for a call and
`<repository>@<commit 12>` for a hand take (P8). The bridge's `heads` gets a read tool, no say-again (P4).
`git.branch` becomes a kept call that waits on the holder's return, no redelivery timer (P1).
- **H-A-49 (Q44, Q45)** Every reader of `manifest-accepted` and `manifest-refused` (the builder's floor, the watchman,
mesh-config on #708, the tool runner's ledgers, membership) reads the mover's entry on `take-in.taken`; #708 moves to
`catalog-revision` before it merges. Only a take-in keeps a catalog revision; a toolchain change reaches pipelines
through `toolchain-agreed`. P1, P9; ADR 0682 §4.
- **H-A-50 (Q46)** The event that wakes a held take-in is the indexer's own `room` on the seat `mesh-catalog` (the store
is the indexer's); H-A-12 is read so. P12.
- **H-A-51 (Q47 to Q51)** One `validate` run per take-in revision, every mover's step reading it; the runner's and
`mesh-wants`' contracts add `validate` (P7). Every step of a mover waits for its dependency's publish (P3; ADR 0682
§6). Tiers come from edge kinds 2, 4, 5 and 6; a cycle among movers is one tier, said in the journal (P3; ADR 0666
§14). `widens` is per mover in its entry (P10). Lines already built (`branch` and `source` on `package-published`,
`pipeline` on step events) are read as built (P7).
- **H-A-52 (Q52 to Q59)** The runner consumes `version-released` in H1 and writes the version into the mover's entry
(P1). A run on request stays per member, in the same queue (ADR 0682 §7). A hand `start` keys the newest revision's
`<branch>.<source>` with that module as its one mover, refused when the key exists (P4). The runner asks `outdated`
no more; kind-1 dependents come from the edges it holds (P1; ADR 0682 §6). A waiting pipeline says
`pipeline-started` at its write, so its revision is pinned while it waits (P3). Its wait is said on
`…wait-held.<branch>.<source>`; the enums gain `pipeline` and `pipelines-at-once` (P8). `pipelines-stalled` and
`queue-full` have scope `delivery`, one each for the mesh; `queue-full` clears when the over-cap start is taken (P3).
- **H-A-53 (Q61 to Q64)** One `approval` step per mover whose policy names it (P10). `runner_place` is backed by a verb
`place` (`pipeline`, `why`) on the runner's seat (P4). A mover left in an older pipeline whose dependency was
superseded out builds against the newest published package, said in its step's why (P3; ADR 0682 §7). "A set-aside"
reads as `pipeline-ended` and `cancel` alone (P7).
- **H-A-54 (Q65)** The indexer's §749 pins land with the runner's R3 and are reviewed together. The lead's order.
- **H-A-55 (Q66, Q67)** Rule 2, rule 7, the network hold and A-428's exceptions end; the record-policy yes and the
outside wait stay as the asker's. `assigner_release` stays for puts and outside waits, losing its acting, order and
delivery steps. P7, P4; ADR 0682 §9.
- **H-A-56 (Q69, Q70)** Tier progress is the assigner's state `written`, key `pipeline.<branch>.<source>` with
`{tier, since, movers}`, one deadline timer; a tier counts placed movers only; `wanted` gains `pipeline`; `tier-late`
clears when the late movers run or a later pipeline passes; the end is said on `…wanted.<branch>.<source>` with
`outcome`. P4, P7, P1, P3.
- **H-A-57 (Q71 to Q74)** `acts` stays for the builder's build seats; `bound`, `DefaultBound`, `Wait` and the other
acting entries go (P7). The seat `mesh-delivery-checker` goes with every copy and its `check` and `recheck` kinds
(P7). The operator channel's limit, `held-back` and `ask-again` go in H1 with their state, verb, sdk reads and the
tool runner's row (P7; ADR 0682 §14). `indexer_unpin` is renamed to take the pin's key; one tool (P7).
- **H-A-58 (Q75 to Q78)** "Every durable starts at the newest and refuses the old form" holds for consumers of event
streams, not for watches of last-per-subject state; the refusal is in the shared follower; old means a
`take-in.taken` without `call` or a pipeline value without `movers`; the gate's and the forge module's durables are
dropped at the clean state's drop step, named there (P2, P3). The new `cancel` reads no old pipelines: they are
dropped (ADR 0682 §12). `assigner_want_drop` deletes the key, written in the hand-act log; the next pass writes the
new form (P4). A run's candidate graph is dropped on the `pipeline-ended` of its last member (P1).
- **H-A-59 (Q79 to Q84)** `pipeline-failed` has scope `delivery`, its owner as today (P8). A higher rank waits for a
lower rank of its pipeline on this machine alone, said as `wait-held` step `placing` (P3; ADR 0682 §9). When two
pipelines' wants changed at once, the older source first (ADR 0682 §7). "Its own want last" is the node-engine's
module; the node's composition stays first (P8). The bus module and the backup holder are found by claim
(`mesh-broker`, `node-backup`) from the entries the composer holds (P9). A revert is a want naming a fingerprint this
node ran before, read from the applied record (P1, with H-A-5).
- **H-A-60 (Q85 to Q88)** The entry asked again: on `catalog-revision` and on the link's reopening, at most `entry-asks`
times (default 5), then `unanswered` and the finding `entry-unanswered`; built in mesh-delivery's `meshcatalogclient`
(P3, P11). The node-engine's read of every node's record stays: it feeds the composer; the plan's section 3.5 and gap
table E row 67 are corrected (P9). Its wait on `restic.backed-up` by name is out of H1, a leftover in the gap table
(P9). Existing timers, polls and whole reads in files H1 touches stay for H4 (§762); new runner code reads only its
`queue` keys (ADR 0682 §11, P1).
- **H-A-61 (Q89 to Q92)** mesh-contracts' five modules are registered at the clean state's step 5.2 (P5). The whole
tests: the forge module's is a Go integration test running its bundle; the tool runner's `main` gains an entry; the
request-count assertion is H4's (with H-A-17). #708's description drops the words "config candidates" before it
merges (P8). Tests that use the checker's state as a fixture rename it to a state that stays (P7).
- **H-A-62 (Q68, for the operator)** Until H2, a version is released only for a registration's first watched branch, so
a placement on another branch gets no want and is said. Recommendation: accept for H1; H2 releases per branch. Asked
of the operator 2026-11-20 02:25 CET.
## From H1's develop (2026-11-20 from 02:27 CET)
- **H-A-63 (seats developer, 02:31)** The `apply-order` row's `waits` is a list of module names the want waits on
(strings), empty when it waits for nothing; `why` stays the one sentence. P8 (one form, named by the rows' own
modules).
- **H-A-64 (seats developer, 02:33)** The word `want:version` is a generated constant of the node-engine seat contract:
the seat generator's identifier function splits on `:` as it splits on its other separators (one more rune, no
existing output changes; a subtask of the contracts-indexer-bridge developer in `mesh-delivery-sdk/seatgen`), and the
node-engine definition gains the enum `ManifestReadWord` with that value. P9 (every reader takes it from the generated
package), P7.
- **H-A-65 (tool runner developer, 02:33)** How the setting `call-timeout` reaches the tool runner: not in H1. The
node-engine composes the tool runner's unit as a special case (two environment variables, no config file), so the
setting's path is the generic manifest `config` with its file resource, built in H4 when that special case goes
(principle 7, no module special-cased in shared code). In H1 the runner's own bound is a constant of 30 seconds and the
per-verb `timeout` carries every real need (`merge-pull` 120); the manifest declares no setting it does not read
(principle 3). Rules-are-weighed: principle 11 bent for one release, said to the operator.
- **H-A-66 (seats developer, 02:36)** H-A-41's set is the whole of it: mesh-sdk's `go/callers.go` (`stdio.Callers`,
`VerbCallers`, `ParseVerbCallers`, `ConfiguredVerbCallers`, `HoldVerbCallers`), the `callers` parameter of
`seatlist.NewPart`, `Tools` and `Refusal`, of `views.FirstViewTool`, `ParseCallers`, `Refusal` and `CallersEnv`, and
`approval.ViewCallersPrefix` go in H1, as the sdk developer's subtask `sdk-holder-callers-gone`; every gated first-view
tool and seat-list tool is open to every caller. The holders' call sites in mesh-delivery and mesh-catalog are their
developers' subtasks, from the signatures the sdk developer reports (the lead relays them). P6, P7 (code that gates
callers protects nothing once every account may call every verb); ADR 0682 §10.
- **H-A-67 (node-engine developer, 02:37)** The node-engine seat's `Wait.step` enum gains `placing` (the seats developer
in mesh-contracts, with the sdk copy); the hold of a higher rank behind a lower one is said with it. P8.
- **H-A-68 (node-engine developer, 02:37)** A revert is a want with no `pipeline` and no `rank` (a placement's `build`,
H-A-37) naming a fingerprint other than the one running; the applied record keeps no history for it. "Read from the
applied record" in H-A-59 reads so: the running fingerprint is what it compares with. P7.
- **H-A-69 (seats developer, 02:38)** How the approval gate knows a module's own first-view tool once the callers env
marker goes: by the tool's name, the forms `<module>_first_views` and `<module>_first_view_again` that mesh-sdk's views
already serve; no environment marker and no tool runner change. P7 (what exists over a new side channel).
- **H-A-70 (contracts-indexer-bridge developer, 02:40)** `acts` stays everywhere as a declaration: it is what the
catalog graph's kind-5 edge ("B has acted for A") is built from, and H-A-51 orders the pipeline's tiers by that edge.
So the `acts` entries of the seats mesh-catalog (take-in, validate), mesh-wants (place) and the build seats stay, as do
`ActingRule` and `CatalogEntry.acts`; what goes is the hold and its wait: `bound` on the build seats' `acts` and every
reader that waits or holds on an acting part (the builder's bound reader and its re-asks, the assigner's acting holds,
the runner's acting waits), each in its own developer's subtask citing this answer (builder and assigner readers:
the runner-and-assigner developer; the pipeline's: the same; the indexer's edge builders stay unchanged). P7 (the
declaration serves the order; only the hold had no need left); ADR 0682 §9.
- **H-A-71 (contracts-indexer-bridge developer, 02:49)** (1) The seat mesh-delivery's state `owed` stays in H1: the
bridge's owed path and the client's check read it (P7 removes only what nothing reads); its stale keys of the earlier
model go at the clean state's drop step (ADR 0682 §12), and §764's "owed (the old bucket)" reads so. (2) The call's
kept member gains `branch`, so the forge module can say `merge-called` again after a stop (P3). (3) The step runner's
asker judgement in `mesh-delivery-sdk/steprun` (H-A-41) is the contracts-indexer-bridge developer's subtask, since
that package is mesh-delivery's shared code and it already writes there; the three build modules' wiring stays
mesh-catalog's BUILD-1. The lead's order of work.
- **H-A-72 (contracts-indexer-bridge developer, 02:53; the runner's and mesh-wants' seats)** (1) The pipeline value:
`group` goes; `module`, `commit`, `fingerprint`, `repository`, `version`, `widens`, `tests` and `over-budget` move into
each mover; `run`, `published`, `unlogged` and `end-count` stay on the pipeline (P7). (2) The runner's state `queue`:
`queue.next` and one key `waiting.<sequence, 20 digits>` with value `{pipeline}`, so the lowest sequence is read by key
order (P1). (3) `wait-held` and `wait-ended` move to the one subject form `<branch>.<source>`, the body naming the
module for a step's wait (P8). (4) The step events and `run-started` keep `<module>.<branch>.<commit>`, the
commit-or-group token becoming `<commit>` (P8). (5) `pipeline-ended` carries per mover its step results as a list of
step results, each naming its module (H-A-35, P10). (6) The tier end is a second event of the seat mesh-wants,
`pipeline-wanted.<branch>.<source>` with `outcome`; `wanted` stays per node and module (P8); H-A-56 reads so.
- **H-A-73 (runner-and-assigner developer, 02:55; the map's Q-32)** Where §772's "held, awaits its hand placement" is
said: in the want's own `hold` field (H-A-37 keeps `hold` and `words`), with the word `awaits-hand-placement`, written
by the assigner for a node whose node-engine does not state `want:version`; no second event. P7.
- **A note on placement (02:55):** a developer's `go.work` per module pointing at the H1 worktrees is the build map's
placement, whatever small script wrote it; it is not a placement of the developer's own. The lead's reading.
- **H-A-74 (runner-and-assigner developer, 02:59)** H-A-70's builder part is only a reader of the build seats' `bound`
field, now absent from the contracts; the builder has none, so nothing of the builder changes in H1. G §672's
toolchain wait (the state `waits`, its events, tools and setting) is a build's wait for its toolchain, not a want's
hold on another delivery, and stays: §764 names no builder item, and the builder's lines are H2's. P7; ADR 0682 §9.
- **H-A-75 (contracts-indexer-bridge developer, 03:02; the seat mesh-wants)** (1) `pipeline-wanted.<branch>.<source>` is
said once per pipeline, at its end: `outcome` is `running` when every tier's movers run (the node-engine seat's word,
P8) and `tier-late` when a tier passed its bound, the body `{v, pipeline, branch, source, outcome}` and, for
`tier-late`, the movers and machines not running. (2) H-A-37's drop of `composed` is the module want's alone; the
node's own want `want.<node>.node` `{composed, words, self}` is unchanged, and `rank` is absent from it. P7.
- **H-A-76 (gate-and-forge developer, 03:04)** (1) `gate_source_again` says `source-moved` again with the `heads` the
source value keeps (every watched repository's head at that source) and `start` false; the indexer finds the movers
from the fingerprints, not from `heads` (A-476a). P7. (2) The clean state drops the source bucket (plan step 5.8)
before the seed (5.9); the seed numbers from 1 on an empty bucket and refuses to run while a key of the earlier form
exists, naming it, so a missed drop is loud and nothing is overwritten. P2, P3; ADR 0682 §12.
- **H-A-77 (node-engine developer, 03:08)** With `kept-on` gone from the want (H-A-37), nothing names the build node that
keeps a kept build, so the node-engine fetches every artifact from the artifact store; G §526's fetch through a build
node's `kept-artifact` has no input left and retires in H1 (added to what retires). P7 (a want names a version; the
store answers for it).
- **H-A-78 (contracts-indexer-bridge developer, 03:10)** (1) A want counts as applied when the have's fingerprint is
the want's (ADR 0682 §8 reads `fp` as the build's name); `motion.Want.Composed` goes from mesh-sdk (the seats
developer's subtask), the view passes the fingerprint. P7. (2) The view's source readers, the watchman's source-moved,
manifest-accepted and manifest-refused readers, and the grants part's readers of the removed caller invokers in
mesh-sdk are the contracts-indexer-bridge developer's subtasks after B4, with the watchman's acting-part-late (H-A-44
gives them the view's and watchman's readers; the grants part is mesh-delivery's shared code). The lead's order of work.
- **H-A-79 (indexer developer, 03:13)** With the validation gone from the take-in (§745, ADR 0682 §4): the state
`verdicts` leaves the seat mesh-catalog's contract (a small commit C1b by the contracts-indexer-bridge developer, the
seat's one writer) and the indexer with its tools `verdicts` and `indexer_verdicts`; the grants part's invoke of
`verdicts` and the watchman's invoke of `indexer_verdicts` go from their manifests (the contracts-indexer-bridge
developer's readers subtasks, with H-A-49: what they need they read from the mover's entry on `take-in.taken`). The
`oldsections` count and `indexer_old_sections` stay as they are: the validator still reads the foundation list there
(ADR 0619 §3), no line moves it in H1. P7; ADR 0682 §4.
- **H-A-80 (indexer developer, 03:14)** The indexer's tool `indexer_consumer` goes with the state `consumers` no ledger
writes any more (P7). A run's ended modules are read from `movers` (C-R), as the developer did. A developer who stops
with work in the tree commits it as "in progress: <subtask>" so the next developer starts from a commit, never from a
dirty worktree (the lead's order of work).
- **H-A-81 (gate-and-forge developer, 03:15)** `head-untaken` (scope delivery, id `<repository>.<branch>`): severity
warning, resolver operator (only `gate_head_take` delivers it, §742), no owner: nothing runs wrong, something is not
delivered. `merge-partial` (§767, keyed by the call): severity urgent, resolver operator: the repositories stand
half-merged until the refused members land or the call is cleared. P3.
- **H-A-82 (indexer developer, 03:16)** With `version-delivered` retired (§764, C-W), the indexer reads nothing in its
place: the fill of delivered versions into the graph's edges (versions_edges, versions_fill_edges) served the
assigner's holds, which are gone; the kind-2 edge stays as a declaration (H-A-51's tiers), its "delivered" fact is
nobody's to keep. The indexer's consume of `mesh-wants.version-delivered` goes from its manifest. P7; ADR 0682 §9.
- **H-A-83 (runner developer, 03:19)** (1) A run on request is one pipeline per run with the named commits' modules as
its movers (one take-in, one pipeline, ADR 0682 §6; the run delivers nothing), keyed `<branch>.run.<run id>` in the
runner's state `pipelines`: the seat gains that key form (a small commit C-R2 by the contracts-indexer-bridge
developer); H-A-52's "per member" is corrected to this. P8. (2) Inside a pipeline, a mover's build waits on a kind-1
edge for the From mover's `package-published`, and on a kind-3 edge (a build module, an image base, which publishes no
package) for the From mover's build step ending passed, which the runner hears as its own step end; toolchain edges
first. P3, P7.
- **H-A-84 (runner developer, 03:20)** A mover's heard dependencies are kept on the mover: a list `published` of the
artifact references whose `package-published` (and, for a kind-3 edge, whose build step's passed end) was heard at
that pipeline's branch and source, written with the pipeline by compare-and-set, so the wait survives a restart (a
C-R2 field, the contracts developer's). P3, P1.
- **H-A-85 (contracts-indexer-bridge developer, 03:21)** (1) The bridge's read tool of its state `heads` is
`bridge_heads`, in the bridge's tools, answering the state's keys with each head, read-only (H-A-48). P4. (2) A run's
pipeline puts in `source` the newest source revision of its branch at the run's start (what the run is checked
against), its key being `<branch>.run.<run>`. P7.
- **H-A-86 (assigner developer, 03:22)** The assigner's pins of assignment graph revisions go whole (the state `pins`,
the tools `assigner_pins` and `assigner_unpin`, the hearer of the gate's pin events): nothing feeds them once the gate's
pin operations are gone (H-A-28, H-A-48). An assignment graph revision that is not current and that no want or
running build names is removed at the same judging moments as today, pins aside. P7; §764.
- **H-A-87 (gate-and-forge developer, 03:24)** (1) The forge module's whole test is a Go integration test that runs
its bundle against an embedded bus (H-A-61 stands over §774's "TypeScript"; §774 is read so). (2) The gate's source
key is read with the same escaping it is written with (the fault in `merges.go`, where `Set` escapes the branch and
`Read` does not): fixed in GATE-9 with a test for a branch holding `/`. P3.
- **H-A-88 (assigner developer, 03:27)** The seat mesh-wants' `StepRun` gains `asker`, the seat name of the part asking
the step (the runner writes `mesh-pipeline-runner`), a small commit C-W2 by the contracts-indexer-bridge developer;
the assigner names a step's progress with that asker (A11, H-A-41). P8.
- **H-A-89 (gate-and-forge developer, 03:29; the record's pipeline families, §738)** All five as recommended: (1) each
per-mover step result becomes one record outcome, its step the result's step, its outcome the result's own word
(passed, failed, nothing to run, bypass), its why the result's, the entry (module, fingerprint, no node). (2)
`wait-ended` writes over `wait-held`'s `held` under the same outcome key, the outcome the wait's `how` (answered,
ran, superseded). (3) A `pipeline-ended` not passed (failed, refused, cancelled, superseded) ends the record `failed`
naming the pipeline's why. (4) `pipeline-wanted` with outcome `running` ends the record (every tier's movers run on
every present placing machine); `running` events are still written as running-healthy outcomes; `tier-late` ends it
`failed` naming the movers and machines not running. (5) The trace's `from` is the lowest and `to` the highest
assignment graph revision of this pipeline's `wanted` events, each want an entry (module, fingerprint, node) with
outcome `wanted`; a removed want writes nothing. P3, P7.
- **H-A-90 (indexer developer, 03:31)** (1) mesh-sdk gains `process.Account.NamedEventConsumer(ctx, js, stream, suffix)`,
binding the durable `<node>_<module>_<suffix>` (the seats developer's subtask); the indexer binds one per watched
branch with the escaped branch as the suffix (§743). (2) The indexer binds a newly watched branch's consumer on its
own `registration-changed`, not only at its start. P1, P8.
- **H-A-91 (bridge developer, 03:34)** (1) A newly registered branch adopted while the bridge runs says `head-moved` with
`start` true, like the start pass: `start` means "a read of the head, not a move", so the indexer takes it in as the
branch's first revision with no movers (§745). P8. (2) The watchman's `delivery-waits` finding goes with
`acting-part-late` (§764), in the same pass. (3) The seat mesh-delivery's contract drops the owed act `merge`
(OwedActMerge), a small commit C3b by the contracts developer; the bridge's refusal of it as undecodable then has
nothing to refuse. P7.
- **H-A-92 (indexer developer, 03:37)** A catalog revision carries its movers (option c): a redelivered `source-moved`
whose revision is already kept says `take-in.taken` again from the kept revision's movers, recomputing nothing, so the
pin judge may remove the revision before as today and a restart between the write and the acknowledgement loses
nothing. P3 (an idempotent re-say), P7 (no extra kept revision, no extra record).
- **H-A-93 (gate-and-forge developer, 03:41)** The forge module's finding `step-unread` (G §585) is one per unread
step: scope `module`, its subject the step's module, its key `<run>.<module>.<step>`, severity warning, resolver
operator, no owner, cleared by that step's later `step-ended` carrying its fingerprint; the body's `fingerprint`
alone is read. P3, P8.
- **H-A-94 (readers developer, 03:42; the watchman)** (1) The watchman learns the bus-state entries a mover's manifest
asks for from the mover's catalog entry, read by fingerprint through the seat mesh-catalog's verb, never from a
retired event (P1, P9); `bus-state-overdue` stays, timed from `take-in.taken`. (2) Its take-in reader is rewritten now to
the seat's `TakeInTaken` and `TakeInPending`, seeded from `indexer_pending`'s answer in the contract's form
`{branch, source, why}` (build against the contract, not an indexer commit); the wait's key is `<branch>.<source>` and its
`since` the message's own time; the bound is the watchman's setting `take-in-bound`, default 60 minutes; the
30-minute group bound goes (§764). (3) §741: the watchman learns no head; the head timing of pipelines.go goes with
its source-moved reader's change. P3, P11.
- **H-A-95 (readers developer, 03:44)** (1) A want with `hold` (awaiting its hand placement, §772) is not timed by the
watchman: a hold is not progress owed (as H-A-14 reads a waiting pipeline). (2) The Owed definition's `ask` and
`group` fields, kept "for a merge", go with the act (C3c, the contracts' writer); nothing reads them. P7.
- **H-A-96 (runner developer, 03:48)** The runner's state `queue` gains a third key form `running.<pipeline key>` with
value `{pipeline}`, written by compare-and-set when a pipeline is placed and deleted at its end, its cancel or its
approval wait; `pipelines-at-once` is judged against the `running.*` keys alone (a C-R3 field, the contracts' writer).
P1, P3; H-A-60 holds (the runner reads only its queue keys).
- **H-A-97 (indexer developer, 03:49)** A held take-in is kept in a small indexer state `held`, one key per branch
`{branch, source, why, since}`, written when a `source-moved` is held and deleted at its take-in or skip (option c):
`indexer_pending` reads it, and the watchman seeds from it (H-A-94). P4 (what the module holds is read, not derived
from a scan of events), P3 (`since` is kept for the bound). The retired state `pending` was the pending revision of
the manifest validation (ADR 0633 §1); this is not it. `indexer_take_in_pending` and `indexer_take_in_skip` are asks in
the state `takeins`, the existing hand-act path. P7.
- **H-A-98 (runner developer, 03:50)** No shared follower exists, so in H1 each consumer's own handler refuses an
old-form event: the contract's strict decode (a required field such as `call` missing) is the refusal, the handler
writes one journal line naming the subject and ends the message. H-A-58's "shared follower" is read so for H1; a
shared shape, if any, is H4's with the wake-up rule. P3, P7.
- **H-A-99 (assigner developer, 03:51)** The placement's `build` is read as the want's target before the rule (option
b): the want's `fp` is that build and its `version` the one released at it, with no pipeline, no rank and no put steps;
`placementPuts` goes. "Read before the rule" literally, with no hold. P7.
- **H-A-100 (gate-and-forge developer, 03:51; the forge module's merge-check machinery)** As recommended: the poll that
goes is the pass's pull-passing half with its 60-second retry, the timer the 10-minute keep-main-rules step (it keeps
a protection ADR 0682 §13 no longer judges); the repository poll (`repo.created`) and the start's whole read stay.
`announceHead` goes whole with its pending status and sibling weighing; `pull.updated` is said by the webhook path
alone; the poll of merged and closed pulls stays. The seat verb `status` writes a head's status through the client
directly; `GateWriter` and its chain go. P7; §764.
- **H-A-101 (runner developer, 03:52)** (1) The runner's verbs `rerun`, `accept` and `ask-again` name the mover's
`module` beside the pipeline and step, so a pipeline of several movers is never ambiguous (a C-R4 change of the
runner's seat by the contracts' writer); a call naming no module on a pipeline of one mover is taken as that mover.
P8, P3. (2) A step of a mover whose dependency did not build ends with its own `step-ended`, outcome `not asked`,
naming the dependency, so nothing ends silently. P3.
- **H-A-102 (readers developer, 03:53)** `indexer_pending` answers `{"held": [{branch, source, why, since}]}`, `since`
in RFC 3339, one form with the indexer's state `held` (H-A-97); the watchman reads it with a local type over the
seat's `TakeInPending` plus `since`. P7, P8.
- **H-A-103 (indexer developer, 03:55; two things held in memory)** (1) Between take-ins the indexer's view of a module
change (a build's imports, a toolchain change, the reconcile) is derived state: the kept revision is the truth and a
restart rebuilds the view from it and the events after it, so nothing kept lives only in memory. (2) A held
message's acknowledgement handle is the bus consumer's; after a restart the bus redelivers the message and the state
`held` says why it was held. Neither is a kept truth in memory; the review reads them so. P2, P3.
- **H-A-104 (assigner developer, 03:57)** (1) The assigner keeps each node's words in its own state `engine-reads`
(key the node, value `{words, at}`), written when it hears `manifest-reads-changed`, so a restart loses no node's
words and no verb is asked; the shared client stays as it is, used for the event alone. P1, P2. (2) `RefusedCycle`
moves into `mesh-delivery-sdk/graph` on the contracts branch (a small commit by the readers developer, the branch's
writer of shared code), so the assigner's `validate` step and the indexer both read it from there (H-A-34). P9.
- **H-A-105 (indexer developer, 03:59)** (a) `indexer_take_in` goes whole with the builder-log index (H-A-48, §742:
the gate's `gate_head_take` is the one hand take of a head and nothing else delivers an untaken head; acceptance
test 36 and G-5's restore step are corrected to name `gate_head_take` when the design is next amended). P7. (b) The
run candidate's check of a module named twice with different manifests stays: it guards a run on request, which
stays (H-A-58); only the pull-request candidates go. P7.
- **H-A-106 (runner developer, 04:06; the queue)** (a) A start over the cap is written as an ordinary waiting pipeline
(its value `waiting`, its `waiting.<seq>` key) beyond the cap; `queue-full` is raised naming it and cleared when an end
brings the waiting count back to the cap or below; nothing is left unacknowledged (H-A-36 over §748's wording). P1,
P3. (b) A pipeline whose approval is answered and still runs has its `running.<pipeline>` key written at once, over the
bound, since it asks nothing new but its end; "waiting on its approval step" means every step not ended is an approval
asked of the operator. P3. (c) `pipelines-stalled` and `queue-full` have the kind as their id, severity warning, no
owner (the operator's), like `pipeline-failed`'s writer. P8.
- **H-A-107 (runner developer, 04:09)** The pipeline value keeps `superseded`, the modules a newer queued take-in took out
of it (written with the movers by compare-and-set; a C-R5 field of the seat, the contracts' writer); at the pipeline's
placing the runner writes a mover's build-step why from it (H-A-53). P1, P4.
- **H-A-108 (assigner developer, 04:10; the validate step)** All four as recommended: (1) the revision's validate run is
a key `<pipeline>.validate` of the state `composition-runs` in the CompositionRun form with no machine, taken up at
start like the composer's runs (P1, P7); (2) the validator's request carries no predefined key list and no known
package names until a design line names the verb that gives them: the validator takes every fallback as declared and
judges no package name (P7); (3) "a manifest the revision alters" is judged against the branch's previous revision,
read through the seat mesh-catalog's verb `revision` (P1); (4) one run, one verdict per revision: every mover's
validate step ends the same, failed with `manifest-refused` naming every problem of the revision (P3).
- **H-A-109 (readers developer, 04:12; the view's held take-ins)** A held take-in names no module in the view: its
movers are not known until it is taken in, so the view says the branch's held take-in in the tiers' pending words
(branch, source, why, since) and holds no module for it (option b). P3 (no module named on a guess).
- **H-A-110 (node-engine developer, 04:13)** Within one link, the node-engine asks its unanswered entries again when it
hears the seat mesh-catalog's `catalog-revision` (one per take-in): the composer consumes that event for this alone and
calls the entries client's `AskAgain`; and once more at each link's start. No timer. P1.
- **H-A-111 (node-engine developer, 04:15)** With no verdict state (H-A-79, ADR 0682 §4), the node-engine's reading of
a taken module (frombus `taken`) drops the verdict branch and decodes the manifest alone: a module in a catalog
revision is accepted by being there; the validate step judged it before any want. P7.
- **H-A-112 (node-engine developer, 04:18)** The composer (mesh-compose) likewise drops the verdict branch of its parse
and its case verdict, and the request field `Case.Verdicts` goes: its one writer was the checker, which goes in H1
(H-A-57); the assigner's composition step sets no verdicts (H-A-108: the validate step judges before the composition
step). P7.
- **H-A-113 (readers developer, 04:20; the grants part)** (1) `grants_callers` goes whole with the callers lists;
`grants_why_refused` stays, answering the bus's own verdict for the account and the verb's call subject (a refusal
is still readable, P4). (2) §752 and ADR 0682 §10 mean every verb of every seat: the grants part grants each module's
account every seat's verbs, not only the seats its manifest invokes (acceptance test 118's case); that change is this
developer's, in the same pass. P6.
- **H-A-114 (indexer developer, 04:40; a held take-in across a restart)** A held take-in is acknowledged on the bus and
kept only in the indexer's state `held` (H-A-97); the indexer takes the held ones in again from that state on its own
`room` and at its start. No message stays unacknowledged, so the consumer's acknowledgement wait bounds nothing and a
restart loses nothing; H-A-12's and H-A-50's "held, unacknowledged" are read so. P3 (a stuck message for the length of
the acknowledgement wait would be a silent failure), P2.
- **H-A-115 (indexer developer, 04:40; the movers' code dependents)** In H1 a code dependent of a mover is a module
whose Go module requires the mover's (the go.sum reading built), which moves a module that requires the package
without importing a changed package; the finer reading by imported package is H2's refinement of the same line
(§743, A-476a). P7 for H1, said.
- **H-A-116 (readers developer, 04:43; the builder's floor)** In H1 the builder's version floor wakes on every
`take-in.taken` (it consumes the indexer's `take-in.taken` in place of the retired `manifest-accepted`, H-A-49) and
looks at every module again as it does today; the finer wake on a mover's new entry is H2's with the builder's own
lines. The mechanical changes SDK-C forces on the builder's seat-list calls are in scope. P1, P7.
- **H-A-117 (build-modules developer, 04:57)** The build seats' step kinds `check` and `recheck` stay in H1: they carry
the composer's and the validator's runs (a compose or run ask is kind `check` of the Go seat), and §753's queues are
H2's to rename with the builder's lines; H-A-57 is narrowed to the checker's seat, its copies and its own verdict
verb. The runs' input moves from the checker's `input` to the seat mesh-wants' `input`, which the assigner serves
(H-A-34), not to mesh-catalog. P7; rules-are-weighed, said.
- **H-A-118 (join developer, 05:03; the held take-in's form)** (1) The state `held`'s value carries the held
`source-moved` whole beside H-A-97's four fields: `call`, `heads` and `start`, so a take-in after a restart reads
nothing from any verb (P2). (2) A later `source-moved` of a held branch is held behind the earlier one: the branch's
key holds its held events in order, each acknowledged once written there, and the indexer takes them in in that order
on `room` and at start; no source revision ends silently (P3).
- **H-A-119 (join developer, 05:09; the teller)** `pipeline-ended`'s per-mover entry gains `commit` and `widens`
(a C-R6 change of the runner's seat, the runner writing them from its pipeline value), so the teller says one widening
per mover from the event alone and reads no other module's state (P10, P1). The teller's hearing of `record-opened`
and its consume go: the record's H1 form carries no forge-made, and §763 retires acceptance test 53's rows (P7).
- **H-A-120 (fixer, 05:29; the build seats' queue order)** The build seats serve their kinds in turn, as lead answer
A-440 (the operator's yes of 2026-11-15) decided and the code since 2026-11-15 does; the red test still asserting ADR
0525 §4's deliveries first is corrected to the turns (delivery, check, delivery), citing A-440. H-A-8 and H-A-51's
"deliveries first" were wrong: a line existed. ADR 0525 §4 gets a progressive insight in H2 with the builder's lines.
P7 (build what the last decided line says).
- **H-A-121 (the clean state's drop tools, 05:46; corrected 05:52)** The plan's step 5.8 needs tools no module serves
(the reader of 05:43): (1) the bus module gains two tools beside the seat mesh-broker's verbs: `nats_drop_bucket`
(bucket, why: drops one named bucket after a snapshot) and `nats_consumer_delete` (stream, durable, why: deletes one
durable consumer); both written in the hand-act log. They are the operator's hand tools for one module's own kept
data, not a need another module fills: a module tool, not a seat verb (P9; the seat's definition stays as reviewed).
(2) `gate_record_end`, `assigner_want_drop` and `indexer_pin_drop` take an `all` form (every open record, every held
or failed want, every stale pin) beside their one-item form, each saying what it dropped, counted. (3) The source
bucket's old keys go by `nats_drop_bucket` of that bucket before `gate_source_seed`. Built in H1 on the H1 branches as
the clean state's own tools. P4 (everything that goes wrong can be recovered through tools), P3.
- **H-A-122 (the mail reader's callers list, 05:52)** Goes, like every other holder's (H-A-41, H-A-66; ADR 0682: every
account may call every verb). The mesh has one user and is assumed not compromised (the operator, 2026-11-11); who
inside the mesh may read mail through a verb is who-may, a design detail, not public exposure: nothing here puts mail
outside the mesh. ADR 0459 §2's protection of mail data stays in what the verbs answer, not in who may call them. P1.
- **H-A-123 (what `assigner_want_drop all` drops, 05:53)** There is no failed want: a want has `hold` and nothing
else that marks a fate (the node-engine's report of a failed have is the node-engine's state, not the want's). The
`all` form drops every want key in the wants bucket, held or not, and every value of an earlier form the decoder
refuses; it answers the count per kind (held, current, undecodable). The clean state drops every want before the
seed (plan step 5.8; the operator, 2026-11-20: old data may go). H-A-121 (2) is read that way. P4.
- **H-A-124 (what `indexer_pin_drop all` drops, 05:56)** Every pin in the indexer's pins state, as H-A-123 drops every
want: the indexer knows a running pipeline only through its own pins, so no other reading of "stale" exists without
a read of another module's state (P9 forbids it). The `all` form is the clean state's tool, run while no pipeline
runs (plan step 5.8, after the runner is stopped); it answers the count dropped and the pipelines they named. P4, P9.
- **H-A-125 (the knowledge base's delivery block, 05:58)** Goes whole: the overview's delivery source, its
`delivery-groups` block, the progress verb's groups lines, and with them the knowledge base's consumes of
`pull-merged`, `transition` and `group-ended`; `pipeline-ended` is then not consumed by the knowledge base at all,
which corrects H-A-44's reading. The block showed another module's state (the deliveries), which only the status view
owns (P9: a module's state is read through its owner's view, never copied); a pipelines block belongs in the status
view and is parked as an idea, not built in H1. Told to the operator as a change of what they see: the knowledge
base's overview page no longer shows deliveries. P9, P5.
- **H-A-126 (the bus module's drop tools exist; H-A-121 (1) withdrawn, 06:12)** No new tool: the bus module already
serves them (the developer's reading of 06:11). A retired state bucket (the gate's `merges`, a seat's `asks` and
`turns`, mesh-config's `pulls`, the indexer's `pending`) is kept data no accepted manifest asks for once H1's
manifests are taken in, so the keeper's `nats_drop` drops it, by warrant, after its snapshot, as today. The source
bucket's old keys go by `nats_bucket_remove` with the prefix, before `gate_source_seed`. A durable consumer goes by
`nats_consumer_remove`; it refuses only a consumer an accepted manifest asks for, and no longer every consumer of a
kept-data stream: one no manifest names is an orphan on that stream, removed by warrant (`why` required) and
written in the hand-act log as the keeper's requests are. The clean state's step 5.8 names these three. P4, P7 (no
second tool for one act).
- **H-A-127 (`nats_consumer_remove`: what it refuses and what warrants it, 06:16)** (1) No manifest field names a
durable; the mesh names a module's durable `<node>_<module>`. The tool refuses a durable whose name is that form for
a module of an accepted manifest on that node (the keeper's accepted set), on any stream; every other durable is an
orphan and goes. The judgement is by name, not by stream (H-A-126). (2) `why` is the warrant: the tool acts at once
and writes the hand act through mesh-hand-acts as `nats_bucket_expiry` does. The clean state runs at the operator's
terminal, so an ask of the operator would answer the operator's own call (P7). P4, P7.
- **H-A-128 (`nats_consumer_remove`: the name rule is a prefix, 06:24)** H-A-127's rule is read as a prefix: a durable
is a module's when its name is `<node>_<module>` or begins with `<node>_<module>_` for a module of an accepted
manifest on any node (the keeper's accepted set holds modules, not nodes; the developer's reading of 06:23), since a
module may name more than one durable with a suffix. The tool refuses those and removes every other. P3 (a wrong
removal of a live consumer is a silent failure), P4.
@@ -0,0 +1,34 @@
---
layer: to-be
status: draft
updated: 2026-11-12
decisions: ["ADR 0593", "ADR 0606", "ADR 0429"]
code: [mesh-host, mesh-catalog]
---
# A placed module whose build failed: the lead's answers for a small fix on main
The small fix of a provisioner held unhealthy since 2026-11-09: a placed module whose newest build the builder holds
failed (a Go package, which the builder refuses today) is never published by the node-engine, so the provisioner waits
for its composition at every pass, says itself unhealthy, and the assigner holds every new provisioner build. The fix
goes alone on main and milestone G joins it, since G rewrites the same files.
- **U1** (who answers): the node-engine, which publishes for every placed module (ADR 0593 §6), writes a refused key at
the newest fingerprint for a placed module whose newest build is failed, with the build's words; a build queued or
running stays unpublished (P2, P3).
- **U2** (the Go package build itself, against ADR 0606 §1 and §7): not in this fix; milestone G builds it (P5).
- **U3** (whether mesh-wireguard is a module the mesh provides): not in this fix; the node-engine's special case stays
until a design says otherwise (P7).
- **U4** (a lasting unpublished hold in the provisioner's own health): not in this fix; noted on the issue the fix runs
under (P7).
- **U5** (held fingerprints of superseded provisioner builds): after the fix is delivered, the eight older holds are
released through the assigner's hold ask, told to the operator in one line; their cleanup by the assigner is noted
(P3, P7).
- **U6** (the provisioner's comment at holder.go:113-114 says an unpublished module stops retirement on the whole node;
the code keeps only that module's keys): the comment is corrected to the code, in the same group (P3, P8).
- **U7** (the provisioner's retiring asks whose id is over 64 characters are refused at every pass, and the key's why says
it waits for an open ask): the ask id is bounded, made from the key, and a refused ask is said in the key's why and
in provisioner_health, in the same group (P3).
- **U8** (develop, U1's trigger): the node-engine writes U1's refused key on the event that the placed module's newest
build ended failed, not at the next pass some other input starts; a refusal written late is a wait nobody can read
(P1, P3).
@@ -0,0 +1,59 @@
---
layer: to-be
design: 50
milestone: resolver-wait
updated: 2026-11-12
code: [mesh-catalog modules/systemd-resolved, mesh-host internal/compose/resolution]
decisions:
- "ADR 0678"
- "ADR 0247"
- "ADR 0223"
---
# Design 50, milestone resolver-wait — the own resolver's file waits longer than its pass
**What it builds.** On a machine where a module holds the node seat `node-resolver`, the file `/etc/resolv.conf`
gives its programs a wait longer than the own resolver's pass over one silent mesh resolver to the next, so a lookup
behind a silent first mesh resolver answers late instead of failing (ADR 0678 §1). The value is the main file's,
[§2](../50-split-dns-on-a-machine-with-a-vpn-client.md#2-the-file-and-the-resolver):
`options timeout:3 attempts:2 edns0`. This part holds every line the milestone builds, cited as "design 50 resolver-wait §n". It is built under
issue 1748.
**Where.** Two repositories: mesh-catalog (the module `systemd-resolved`, holder of `node-resolver`: §1) and `mesh-host`
(the node-engine's names check and its test: §3). One milestone, its two pull requests one delivery group with one
check. No ordering edge joins them: once §3's test reads the options from the catalog's template, each repository's
check passes against the other's main, whichever merges first.
## Lines
1. **The own resolver's template carries the longer options.** The module `systemd-resolved` renders the file twice
from one template, its facts `resolvers` (the live file) and `kept` (the kept copy beside resolved's
configuration, which the guard puts back); both carry the options line of design 50 §2, `options timeout:3
attempts:2 edns0`, in place of `options timeout:1 attempts:2 edns0`, which goes from the template. The one
`nameserver` line, the machine's private address, is unchanged. The node-engine writes both when it renders the
module, the kept copy first (design 50, *As built*), so the guard never compares a new live file with an old copy.
Read by `<node>/node-reads.read` of the file and by the uplink seat's `resolvers` verb, as today. Checked by the
module's manifest test, which asserts the one server and this options line in both facts; the guard's own test,
which holds a literal of the file, carries the new line.
2. **Nothing else of the resolver changes** (ADR 0678 §2). resolved's drop-in stays as it is: no cache, the mesh's
resolvers as its servers in the order of the module's roster (ADR 0223 §9), `~.`, no fallback, its extra listener
on the private address. The uplink modules' files (`networkmanager`, `systemd-networkd`) keep both mesh resolvers
with `timeout:1 attempts:2`, held by the existing test over every uplink's resolver file. The captured copies of
the catalog in other repositories' test data are left as they are: no check reads them.
3. **The names check judges the file with the wait its programs give it.** The node-engine's names check already
bounds each ask by the `timeout:` of the file it judges, never under 1 s; that stays, so on a machine holding
`node-resolver` each ask's bound becomes 3 s. Its test that composes the catalog's own resolver on a machine
reads the expected options line from the catalog's `systemd-resolved` template beside it, in place of the literal
`timeout:1 attempts:2 edns0` it asserts today (ADR 0678, *How it is checked*). The reason: a test literal of
another repository's template fails one repository's check on whichever merges first, the kind issue 1748's note
of 2026-11-10 met.
4. **The value stays 3 s per try until the pass can be read.** design 50 §2's `timeout:3 attempts:2` stays ADR
0678's starting value until a read of resolved's own server switches exists. A restart of resolved and lookups
at the own resolver with its first mesh resolver silent answered in 44 to 46 ms (the lead's reading of
2026-11-12 18:05 CET, issue 1748), so a restart and a timed ask do not catch the pass. After the delivery, on the
workstation first and then the laptop, `<node>/node-reads.read` of `/etc/resolv.conf` shows the one server and
§1's line; the proof that the wait outlasts the pass is §5's.
5. **The live proof.** At the next silence of the first mesh resolver, `mesh-build-go.build_go_steps` lists no Go
build step on a machine holding `node-resolver` failed with `i/o timeout` at that machine's own address. Issue
1748 is resolved once §4's read of the file holds, naming this line as where the proof will show, and reopened
if it fails.
@@ -6,11 +6,13 @@ code:
- mesh-controller internal/catalogue/seats.go, declaration.go, resolve.go
- mesh-catalog modules/systemd-resolved (the resolver, its guard and its verbs)
- mesh-catalog modules/forticlient (the VPN client's adapter)
updated: 2026-10-07
- mesh-host internal/compose/resolution, internal/network (the names check of the file, milestone resolver-wait)
updated: 2026-11-12
decisions:
- "ADR 0247"
- "ADR 0223"
- "ADR 0241"
- "ADR 0678"
---
# 50 — Split DNS on a machine with a VPN client
@@ -66,8 +68,14 @@ not share a machine.
## 2. The file and the resolver
- **The file** names the machine's private address alone, with ADR 0223's options, and begins as every
mesh resolver file does, so the uplink's `resolvers` verb and the node-engine read it as the mesh's.
- **The file** names the machine's private address alone and begins as every mesh resolver file does, so
the uplink's `resolvers` verb and the node-engine read it as the mesh's.
- **The file's options wait longer than resolved's pass** over one silent mesh resolver to the next
(ADR 0678 §1): `options timeout:3 attempts:2 edns0`, a total wait of 6 s, the timeout times the attempts, where
ADR 0223's `timeout:1 attempts:2` gave about 2 s. Its program asks only the own resolver, so it waits on that
pass; a file that lists the mesh's resolvers keeps `timeout:1 attempts:2`, because its programs try the second
after one second (ADR 0678 §2, design 08 §2). The value stays ADR 0678's 3 s per try until a read of resolved's
own server switches exists, since no read today catches the pass (milestone resolver-wait §4).
- **The uplink's holder steps back** from that path on that machine, by the controller's rule. It does not
write the file and lose a race; it is never given the file to write.
- **resolved** is given every mesh resolver as its global servers, with `~.` so they answer every name no
@@ -122,12 +130,24 @@ resolver's hold, and is therefore raised. A VPN that tells resolved its link's D
## 6. What it costs and what it does not do
- The client's search domains route full names. They do not complete short ones.
- A name no mesh resolver answers takes the file's total wait to fail on that machine: 6 s, about 4 s longer
than before (ADR 0678).
- resolved down is no names on that machine. Its `unit` health, and the node-engine's names check against
the address the file lists, say so.
- resolved should take no servers from the resolver file, because its own are configured. The live test
confirms this while a write stands.
- A container started before the resolver keeps the mesh's two resolvers until it restarts.
## How it is checked
| Check | Defends |
|---|---|
| the own resolver module's manifest test: its file names one server, the machine's private address, with §2's options | ADR 0247 §6, ADR 0678 §1 |
| the node-engine's test that composes the catalog's own resolver on a machine reads the options from the catalog's template, not a literal, and its names check bounds each ask by the file's `timeout:` | ADR 0678 §1 |
| the test over every uplink's resolver file: both mesh resolvers, `timeout:1 attempts:2` | ADR 0678 §2, design 08 §2 |
| live, on a machine holding `node-resolver`: at the next silence of its first mesh resolver no Go build step there fails on `i/o timeout` (milestone resolver-wait §5); a timed lookup waits for a read of resolved's own server switches (§4) | ADR 0678 §1 |
| each phase's *Done when* below | ADR 0247 |
## Phases
| Phase | Repository | Delivers | Done when |
@@ -135,6 +155,7 @@ resolver's hold, and is therefore raised. A VPN that tells resolved its link's D
| A — the seat | mesh-controller | `node-resolver` and its verbs; the uplink stepping back | its tests pass; the controller is running on the mesh |
| B — the resolver | mesh-catalog `systemd-resolved` | the module, its guard and verbs | its tests pass; assigned to every machine that runs the VPN client's module, each one's file names its own address, `routes` answers |
| C — the adapter | mesh-catalog `forticlient` | `split-dns` required; the adapter | its tests pass; on the laptop, connected, a company name and a mesh name both resolve and no rewrite stays raised |
| resolver-wait | mesh-catalog `systemd-resolved`, `mesh-host` | design 50 §2's options (ADR 0678), under issue 1748; its part is [`50-milestones/resolver-wait.md`](50-milestones/resolver-wait.md) | its tests pass; *How it is checked*'s live row holds |
## As built
+2 -2
View File
@@ -29,7 +29,7 @@ document is written and this one's status becomes `implemented`.
| [`17-raising-a-mesh.md`](17-raising-a-mesh.md) | How a mesh comes into existence, and how a machine joins one that exists | ADR 0067, ADR 0006, ADR 0005 |
| [`18-building-a-module.md`](18-building-a-module.md) | How a build is modelled, and why a recipe that is always a Dockerfile does not fit what a module is | ADR 0040, ADR 0039, ADR 0009 |
| [`19-the-module-protocol.md`](19-the-module-protocol.md) | What a module's code and the mesh say to each other; an SDK is an implementation of it | ADR 0074, ADR 0042, ADR 0043 |
| [`20-writing-a-module.md`](20-writing-a-module.md) | A worked guide: one module, four capabilities, four languages, and the packages it publishes | ADR 0074, ADR 0040, ADR 0039 |
| [`20-writing-a-module.md`](20-writing-a-module.md) | A worked guide: what a module is built of, the manifest form the manifest validator accepts for each part, and the packages it publishes | ADR 0578, ADR 0595, ADR 0074, ADR 0040 |
| [`21-the-installation-in-full.md`](21-the-installation-in-full.md) | Every step from a bare machine to a mesh that maintains itself, and what is not yet true | ADR 0067, ADR 0073, ADR 0014 |
| [`22-the-work-ahead.md`](22-the-work-ahead.md) | Everything decided and not yet built, in dependency order, each phase ending at a run | ADR 0074, ADR 0075, ADR 0014 |
| [`23-choosing-a-provider.md`](23-choosing-a-provider.md) | Which of several providers of a kind serves a consumer, and when a module carries its own instead | ADR 0084, ADR 0027 |
@@ -49,7 +49,7 @@ document is written and this one's status becomes `implemented`.
| [`46-the-conversation-with-the-operator.md`](46-the-conversation-with-the-operator.md) | **Designed.** The mesh tells and asks its operator over channels that are holders of two kinded benches, `channel` and `intake`, declaring capabilities from a fixed vocabulary; the router orders them by work context and never lowers the bar; an answer that performs an action is checked and performed by the controller, on a TOTP code or a verified Telegram sender, never on a desk click alone; operator messages addressed or answered by the mesh's responder, untrusted input kept as data, references for what words may not carry, and a recoverable factor; Telegram first, in six phases | ADR 0234, ADR 0227 |
| [`47-delivery-from-commit-to-delivered.md`](47-delivery-from-commit-to-delivered.md) | **Designed.** A delivery is one commit in one repository, from its pull request's head to every machine; a delivery group is deliveries sharing a branch name, ordered and checked as one future state; both owned by the `mesh-delivery` module with one state table, its state on the bus, every transition said, noted on the commit and shown on the pull request; the controller keeps the planner, the gate, sending and the rollout, and the core's own updates never wait for the module | ADR 0239, ADR 0238, ADR 0236 |
| [`49-the-mesh-in-domains.md`](49-the-mesh-in-domains.md) | **In progress.** Every concept belongs to one of eleven domains, which owns its one word; the glossary is organised by them and is the authority, a retired word is named on its replacement's line with its scope, and two checks hold this repository's documents and the catalog's tool descriptions to it | ADR 0244, ADR 0006, ADR 0008, ADR 0302 |
| [`50-split-dns-on-a-machine-with-a-vpn-client.md`](50-split-dns-on-a-machine-with-a-vpn-client.md) | **In progress.** A machine whose VPN client pushes servers of its own runs a resolver of its own, on a node seat, that routes the VPN's domains over its link and every other name to the mesh's resolvers; the VPN client's module carries the adapter | ADR 0247, ADR 0223 |
| [`50-split-dns-on-a-machine-with-a-vpn-client.md`](50-split-dns-on-a-machine-with-a-vpn-client.md) | **In progress.** A machine whose VPN client pushes servers of its own runs a resolver of its own, on a node seat, that routes the VPN's domains over its link and every other name to the mesh's resolvers; the VPN client's module carries the adapter | ADR 0247, ADR 0223, ADR 0678 |
| [`51-the-registries-keep-what-is-named.md`](51-the-registries-keep-what-is-named.md) | **In progress.** The artifact store, the package registry and each machine's container runtime get tools that say what they hold, what names each thing and what could go; every removal is a dry run unless a person asks and says why, and what decides is always a record | ADR 0251, ADR 0189 |
| [`52-shares-and-mounts.md`](52-shares-and-mounts.md) | **In progress.** A node shares one folder at a time through `nfs-server`, which provides it as a provision to the private network only, mapping every client to the folder's owner; a node that asks mounts it through `mounts`, a mount unit and an automount per share, so nothing mounts or fails at boot; a device that comes and goes is an occasional source whose absence is a state | ADR 0263, ADR 0051, ADR 0092 |
| [`53-the-issue-tracker.md`](53-the-issue-tracker.md) | **Designed.** The mesh keeps its issues in one module, `issues`, on the control-node: every number from one counter advanced by compare-and-set, the cycle's issue rules refused at the write, an event per change; an issue lives whole in the tracker, hq keeping no issue content (ADR 0291) | ADR 0275, ADR 0291 |
+9 -3
View File
@@ -22,11 +22,17 @@ try in process. Four more carry playbook 07: `mesh-preparer` (the prepare step),
`mesh-code-reviewer` (the review) and `mesh-watcher` (every wait). A tenth, `hq-design-writer`, writes one set of design amendments
(playbook 02, *Amending an existing design*) from accepted decisions and a milestone's findings, in a worktree of its
own, ready for the review by architectural domain. An eleventh, `hq-record-writer`, proposes one decision record or
research effort to the knowledge base from a draft (playbooks 01 and 02) and follows its review to approve. An agent that researches, decides, designs or reviews a design starts
research effort to the knowledge base from a draft (playbooks 01 and 02) and follows its review to approve. Two more serve a design
delivered again part by part (design 47, milestone H): `spec-reader` writes one part's specification from the design and its
records (no code read), and `gap-surveyor` holds main's code against that specification and writes the part's gap table
(read-only on the mesh and every working copy). An agent that researches, decides, designs or reviews a design starts
from the knowledge base and maps each interaction onto a mesh path. An agent that prepares, builds or reviews code
starts from the milestone's part of its design alone, builds what its design lines say, and decides nothing: what
the design does not answer is a design question for the operator, answered in the design before any code
(playbook 07). The lead writes only the handover, never an agent's way of working and never an answer to a design
the design does not answer is a design question, answered in an hq commit before any code (playbook 07). The prepare
also reads the code each design line lands in and lists every place where a line and the code disagree. The lead
answers each such question in one line against [`00-META/principles.md`](00-META/principles.md); only one no
principle settles goes to the operator (when it changes what they see or how they work, removes data or needs their
terminal) or to `hq-design-writer` as a design line (playbook 07, step 0b). The lead writes only the handover, never an agent's way of working and never an answer to a design
question. A subagent runs in the session that started it, from hq: its way of working comes from its definition and hq's playbooks, its knowledge from the knowledge base or, for building, the design; one given a coding task works in a worktree under hq's `.work/` and also reads the conventions of the repository it changes, and where those contradict hq, hq wins and the agent says so.
## The development cycle