Compare commits

...
Author SHA1 Message Date
jschoubben ce7669d433 Builder: its whole test waits on version-reserved by name after a reservation
The publish queue's whole test reserves m4 and waits on the seat
mesh-builds' version-reserved by its subject, said as the process says it
(sayReservedOn, now one function main and the test share); without the
event the step fails. Also gofmt of the pipeline's order_test.go.

Builds: design 47 H2 §821, §805; review round 2 finding 2
2026-11-22 03:58:49 +01:00
jschoubben 473451f7e6 Builder: its process runs on the module's account again, with no bus
A process account is granted only what its bus names, never its seat's
work, so a builder on an account of its own could build nothing at its
first start. The process declares no bus and takes the module's broker
credential, as before B13; as the module's one process it is the one
reader of the work queue publishes. Class, caps, settings and the
publish-queue removal stay. The validator built at this head accepts the
builder in the change case (the trunk case refuses it: no class, uncapped
states).

Builds: design 47 H2 §793, §820; H-A-464 (corrects H-A-454 second addendum); review round 2
2026-11-22 03:56:30 +01:00
jschoubben 5f090cd99f Indexer judge: one busless process is its module's work-queue reader
A module whose one process declares no bus runs that process on the
module's account, so its work-queue stream is read by exactly one process
without naming it in bus.queues; two processes, or one with a bus, still
name the reader. Lets the builder keep its process on the module's account.

Builds: design 47 H2 §793, §820; H-A-464 (ADR 0436 §6); review round 2
2026-11-22 03:52:44 +01:00
jschoubben a5e10c70e2 Join: merge feat/47-H2-f3 into feat/47-H2 2026-11-22 03:39:45 +01:00
jschoubben b0a614779d Join: merge feat/47-H2-f2 into feat/47-H2 2026-11-22 03:39:45 +01:00
jschoubben c9d7b1365a Join: merge feat/47-H2-f1 into feat/47-H2 2026-11-22 03:39:45 +01:00
jschoubben 342da2c625 I4 fix: §805's whole criterion is a step of the indexer's whole packages test
Review round 1 found §805's whole criterion (a release of a module
importing twenty packages of its own pipeline keeps one re-pin revision)
unit-tested only. It becomes a step of
TestASourceRevisionMovingMeshSDKNamesItAndItsImporters, the indexer whole
against an embedded bus: twenty version-reserved of mesh-sdk in main's
revision are kept in heard, its pipeline-started keeps one re-pin revision
(importer its mover, pinned to the reserved version), and the next
pipeline's reservation keeps the revision after it. The bed's indexer
durable on EVENTS now takes version-reserved, as the manifest's consumes
name it. The step fails when pipeline-started does not settle the
gathering.

Builds: design 47 H2 §805; H-A-453 (3)
2026-11-22 03:37:26 +01:00
jschoubben e611103ec9 §819: the delivery SDK's count of transport-fault runs is a row of the again table
The test that a transport fault counts the runs that started, not the bus's
deliveries, is folded into the again-delays table as its second run, so the
SDK's unit tests fall by one instead of rising.

Builds: design 47 H2 §819 (H-A-453 (4): a module's count never rises in a change)
2026-11-22 03:31:56 +01:00
jschoubben dde4108504 I1 fix: §802's whole criterion is a step of the indexer's whole packages test
Review round 1 found §802's whole criterion (a commit touching two test
files of two modules of 36 moves those two and their importers alone)
unit-tested only. It becomes a step of
TestASourceRevisionMovingMeshSDKNamesItAndItsImporters, the indexer whole
against an embedded bus: the catalogue holds 36 modules, lib-a and lib-b
among them, required by app-a (require) and app-b (require and replace);
a commit changing lib-a's and lib-b's trees alone moves lib-a, lib-b,
app-a and app-b and none of the other 32. The step fails when the
repository's commit enters the tree input, and when a derived directory
does not.

Builds: design 47 H2 §802; H-A-453 (3)
2026-11-22 03:31:00 +01:00
jschoubben 81ea73a45f R1 (§775): a composition ask whose holder is away passes its step, a step of the runner's whole test
The holder of mesh-wants is away while a re-pin asks the composition again:
the put meets no responders, is put again at the kept-call pace (a hundredth
of its default, so 40 s is 400 ms) and lands once the holder is back; the step
then passes with no hand act.

Builds: design 47 H2 §775 (H-A-453 (3): the whole criterion proven at its level)
2026-11-22 03:30:37 +01:00
jschoubben d68e71700a builder: the slow-event and events-behind-bound bounds are settings (F3)
The review found §794's two bounds fixed in code: the builder's 100 ms
for saying a slow event's handling, and builder_health's five minutes
for naming a consumer behind. Both become settings read at run time,
slow-event (100ms) and events-behind-bound (5m), declared in the
manifest's config with those defaults; a value that is no duration
refuses the builder's start, and makes the health say it.

Builds: design 47 H2 §794, H-A-461 (2)
2026-11-22 03:30:26 +01:00
jschoubben c0489000ba I6 fix: the seat-list's whole criterion is a step of the indexer's whole input test
Review round 1 found §814's whole criterion (a run by hand against
seat-list gives the live validate's verdicts for the builder's and the
runner's manifests) unit-tested only. It becomes a step of
TestIndexerAnswersARunsInputOverOneMiBInChunks, the indexer started whole
against an embedded bus: with the tests' seat list in seat-definitions the
indexer keeps it in seat-lists and hands it by the verb seat-list in
chunks; the object read by its address gives the same bytes, and the
judge's verdicts for the two manifests from the verb's bytes and from a
request file read again as cmd/mesh-judge reads it are the same.

Builds: design 47 H2 §814; H-A-453 (3)
2026-11-22 03:29:51 +01:00
jschoubben eac4dca2a7 builder: prove the tag at another commit and the six-minute backlog whole (F2)
The review found §794's backlog and §796's tag at another commit proven
only by unit tests. Both become steps of the builder's whole test on the
embedded bus: a reservation skips 0.2.0 whose tag stands at another
commit, takes 0.2.1 with the finding version-tagged-elsewhere, the
release writes modules/m4/v0.2.1 at the build's commit and the
version-released heard from the bus clears the finding; a message the
handler asks again is kept on its consumer's ledger in the state
consumers on the bus, and the health held six minutes names it.
The health judgement moves from the tools program's main into
internal/versions (BuilderHealth), which the tools program calls, so the
whole test can prove it. The test's comment no longer says the old state
is dropped through the bus module (F1).

Builds: design 47 H2 §794, §796, H-A-453 (3), H-A-435, H-A-462
2026-11-22 03:28:57 +01:00
jschoubben 7cf8ea380e D2 (§821): the runner says re-pinned where a re-pin lands; its whole test waits on its events by name
A kept mover's re-pin was declared in the runner's seat but never said, so a
wait on mesh-pipeline-runner.re-pinned was never answered. The runner's whole
test now waits on pipeline-started, step-ended, pipeline-ended and re-pinned by
seat and name, a same-source re-pin revision being one of its steps.

Builds: design 47 H2 §821 (round-1 finding: EventRePinned unused outside the contracts)
2026-11-22 03:27:57 +01:00
jschoubben 61d6424c44 I2 fix: a take-in's waiting line and bound are settings
Review round 1 found the take-in's waiting bounds fixed in code
(takein_waiting.go:23-24, one and five minutes). They become the settings
take-in-waiting-line (default 1m) and take-in-waiting-bound (default 5m),
declared in the manifest and read at the start as reserved-keep is; zero
on the indexer takes the defaults. The waiting test gains a row with the
settings at 2m and 10m and checks the bounds the wait asks; the manifest
test's settings rows gain the two keys.

Builds: design 47 H2 §803; H-A-461 (2), P11
2026-11-22 03:25:03 +01:00
jschoubben a75d2d07bf I6 fix: the indexer's heard is capped at 32 MiB, above its live fill
Review round 1 found heard capped at 8 MiB (module.json:137) while its
live fill is above a quarter of that. Fill read 2026-11-22 02:23 UTC with
nats.nats_buckets on novox (the bus module's show makes no entry for a
foundation part's old-section state): mesh-delivery-indexer_heard
4,654,001 bytes (4.44 MiB), 5,499 values. Four times the fill is
17.75 MiB; the smallest power of two above it is 32 MiB (H-A-437).

Builds: design 47 H2 §814, §820; H-A-461 (3), H-A-437
2026-11-22 03:23:37 +01:00
jschoubben 3ff3987aa2 builder: remove the old publish-queue bucket itself after the move (F1)
The bus module's keeper made no entry for the builder's old-section
publish-queue, so nats_drop refused it at every start and the move
re-put its items after the 24 h window. The builder, which made the
bucket, now deletes it itself once every item is on the work queue;
the manifest no longer names publish-queue nor invokes nats.nats_drop.
The whole test proves the move and the removal on the embedded bus,
and a second move of the same items after a stopped start puts each
once. Also corrects the publishes comment: the process consumes the
work queue on its own account (H-A-454 second addendum).

Builds: design 47 H2 §793, H-A-461 (1), H-A-454 (second addendum)
2026-11-22 03:23:19 +01:00
jschoubben a63f4e001b I6 fix: the seat-list's unit test is a row of TestTheControlRecords
Review round 1 found the indexer's unit tests rose by one in H2
(seatlists_test.go:75, TestTheSeatListIsOneObjectByItsDigest). §819 as
H-A-453 (4) reads it: a module's count never rises in a change. The test
becomes the row "seat-list" of TestTheControlRecords, its steps unchanged,
so the count stands where main has it.

Builds: design 47 H2 §819, §814; H-A-453 (4)
2026-11-22 03:22:39 +01:00
jschoubben abfe37e690 Join: merge feat/47-H2-b into feat/47-H2
No conflicts. The mesh-builds contract is regenerated with seatgen: -b's
publish-queue verb and feat/47-H2's descriptions meet in one
VerbDescription (seatgen -check clean).

Builds: design 47 H2 (join of the develop step, playbook 07)
2026-11-22 02:49:04 +01:00
jschoubben 56ca9a9791 M-class (view): class core, every state capped, the finding stream at 8 MiB
The view claims the seat mesh-delivery-view, so its class is core and every
store it keeps names its cap. Fills read on novox (nats_buckets, 2026-11-22
02:50), all under a quarter of 8 MiB, so 8 MiB each: reach 280,654 bytes,
waits 39,678, first-views 7,521, findings 3,400, view-marks 237, answers 0.
Its finding stream keeps 7 days at 8 MiB, not 16.

Builds: design 47 H2 §810, §812, §814, §820; H-A-394 (1), H-A-437
2026-11-22 02:48:54 +01:00
jschoubben 380412d94f M-class (assigner): class core, every state capped above its live fill
It claims the seat mesh-wants, so its class is core, and every state it
keeps names its cap. Fills read on novox (nats_buckets, 2026-11-22 02:50):
findings 3,507,749 and proposals 3,648,514 bytes, above a quarter of 8 MiB,
so 16 MiB (the power of two above four times the fill); every other state
under 2 MiB, so 8: wants 1,737,869, written 889,116, waits 780,485,
candidates 564,884, asks 513,017, puts 442,260, placement 221,392,
differences 176,358, assignments 147,691, seat-holders 80,508, engine-reads
38,397, pulses 5,100, first-views 4,631, view-marks 1,776, copies 140,
policies 0, put-waits 0.

Builds: design 47 H2 §810, §812, §814; H-A-394 (1), H-A-437
2026-11-22 02:48:27 +01:00
jschoubben 1146a6a37f M-class (teller): class leaf, the finding stream at 8 MiB
The teller claims no seat, so its class is leaf, declared by the same rule;
its finding stream keeps 7 days at 8 MiB, not 16.

Builds: design 47 H2 §810, §820; H-A-394 (1)
2026-11-22 02:48:06 +01:00
jschoubben eb02389d45 M-class (watchman): class core, the finding stream at 8 MiB
It claims a seat, so its class is core; its finding stream keeps 7 days at
8 MiB, not 16.

Builds: design 47 H2 §810, §814, §820; H-A-394 (1)
2026-11-22 02:48:06 +01:00
jschoubben 6545469a2b M-class (enrolment): class core, the finding stream at 8 MiB
It claims the seat mesh-node-enroller, so its class is core; its finding
stream keeps 7 days at 8 MiB, not 16, as every module's does (live fill of
its findings state: 0 bytes).

Builds: design 47 H2 §810, §814, §820; H-A-394 (1)
2026-11-22 02:47:46 +01:00
jschoubben 8c50d77b04 M-class (grants): the grants part's manifest says class core
It claims the seat mesh-grants, so its delivery carries a contract of the
mesh; the manifest check refuses a seat-claiming manifest with no class.

Builds: design 47 H2 §810, §814; H-A-394 (1)
2026-11-22 02:47:46 +01:00
jschoubben bb1ab9f10d M-class (pipeline): the runner's manifest says class core
The runner claims the seat mesh-pipeline-runner, so its delivery carries a
contract of the mesh: the manifest check refuses a seat-claiming manifest
with no class. Its states already name their caps.

Builds: design 47 H2 §810, §814; H-A-394 (1)
2026-11-22 02:47:10 +01:00
jschoubben f756718324 B10: build_current asks every build seat's holder its current, in turn
The tools bundle follows the seat-holders view of the claimant of
mesh-module-assigner, names each build seat's holder per node from it, asks
each holder's current at its node one after another and answers them
together, a holder that does not answer listed with why; it reads no presence
and chooses no node. The manifest lists the tool and the three build seats'
current among the module's invokes, outside the process's bus.

Builds: design 47 H2 §801; H-A-446 (1)
2026-11-22 02:44:18 +01:00
jschoubben 5e6ebefd47 B13: the builder's manifest names what its process does, on an account of its own
The manifest says class core (it claims a seat), caps every state by the fill
read on the bus (builds 128 MiB, findings and versions 32, bounds 16, the rest
8; H-A-437), keeps the findings history at 8 MiB for 7 days, invokes the bus
module's nats_drop for the moved bucket, and bounds publish-tries at 10 with 5
as its default. The process gains a bus of its own naming the work queue
publishes in queues with the module's emits, consumes, state and invokes, its
credential broker-builder, so the validator accepts the work-queue stream read
by exactly one process. Verdict: the judge at feat/47-H2-i ce6c39e4 accepts the
builder in the change case and refuses it in the trunk case (no class,
uncapped states).

Builds: design 47 H2 §783, §812, §814, §820; H-A-394 (1), H-A-437, H-A-446 (2), H-A-454 second and third addenda
2026-11-22 02:41:30 +01:00
jschoubben 726592b74c V1 usage by current: build_usage judges a build seat by what its holder runs
A held module still runs its asks, and a have that says running proves
nothing about the holder: the usage view asks each build seat's verb current
on each node at once, says the seat held where its holder answers, counts the
asks it lists as running, and says a step key it does not list left running.
The node-engine's phase is shown and judges nothing. The manifest invokes the
three build seats' current.

Builds: design 47 H2 §813 (9), §801
2026-11-22 02:40:15 +01:00
jschoubben b6a7e0bad3 B4 (H-A-454): publishes is the builder's own work-queue stream, read by the verb publish-queue
The work queue publishes is declared in the manifest's old streams section
(retention work-queue, duplicates 24 h, max-deliveries 10, 64 MiB, 7 days), the
module's own stream consumed on the module's account, so the bus binding asked
of the broker seat goes; the consumers per holder and class are still made at
run time. The seat mesh-builds gains the read verb publish-queue, served by the
builder from its own stream (counts per holder and class, oldest and newest, a
list capped at 50, capped past 4,000 items read), and builder_publish_queue asks
it in place of the runtime's stream and work-queue reads. Two whole tests of a
gone artifact are folded into one, so the builder's integration count stays at
18 with the publishes whole test.

Builds: design 47 H2 §793, §819, §820; H-A-440 (1), H-A-446 (2), H-A-454 and its addendum
2026-11-22 02:35:32 +01:00
jschoubben b65b617361 Join fix: the forge bridge reads the kept-call pace as mesh-sdk's function
mesh-sdk a323a3fd made busretry.KeptPace a function read once and held
atomically; the bridge (from feat/47-H2-a) still read it as a variable and
did not compile against it.

Builds: design 47 H2 §782
2026-11-22 02:35:19 +01:00
jschoubben 474ef0335a Join: merge feat/47-H2-a into feat/47-H2
No conflicts; no side raised a form of mesh-wants or mesh-delivery, so both stay
at 2. The mesh-wants contract is regenerated with seatgen: the keep-now verb
(-a) and the drop verb's description (feat/47-H2) meet in one VerbDescription
(seatgen -check clean).

Builds: design 47 H2 (join of the develop step, playbook 07)
2026-11-22 02:33:58 +01:00
jschoubben ed3c4a2297 Join: merge feat/47-H2-i into feat/47-H2
No conflicts; the mesh-catalog seat's form 5 is -i's (feat/47-H2 left it at 3),
and its contract is regenerated with seatgen so the seat-list verb's description
follows the merged seat.json (seatgen -check clean).

Builds: design 47 H2 (join of the develop step, playbook 07)
2026-11-22 02:33:37 +01:00
jschoubben ce6c39e46c I6 (5): the judge's tests read the catalogue at the group's head
The captured catalogue beside the judge (testdata/beside) is re-archived from
mesh-catalog 30a3e665 (feat/47-H2, the delivery group's catalogue head), so the
judge's rules are tested against manifests that name their class where they
claim a seat; the catalogue fixtures of judge and internal/index move from
835bf22b and a67f0196 to 30a3e665 (ca-trust refreshed; avahi, audit-logger and
netcheck kept at a67f0196, which they still match). Tested against mesh-sdk
a323a3fd (seatlisttest holds the group's definitions); the build seats' check
now holds current, pause and resume among the verbs the seats' definitions
serve, which have grown since 1887.

Builds: design 47 H2 §814, H-A-428, H-A-452
2026-11-22 02:31:52 +01:00
jschoubben d6d15a5497 B4: the publish items travel on the work queue publishes, live first
The bucket publish-queue listed and reread itself before each send; its items
now ride the builder's work queue publishes, pulled per holder and class by
consumers the builder makes as it learns a holder, the live class first, a
failed send handed back with the pause, an item acknowledged when its publish
is heard and terminated when its build is withdrawn, superseded or dropped.
builder_publish_drop and builder_publish_first act through reasks after the
hand-act log; builder_publish_queue reads the queue through the runtime. The
old state's items are moved once at the start, then dropped through the bus
module.

Builds: design 47 H2 §793, §820; H-A-290, H-A-291, H-A-440, H-A-446 (2), H-A-448
2026-11-22 02:22:59 +01:00
jschoubben 80ff1afacc §819: the runner's tests folded to 104 unit and 3 integration
Eight unit tests and two integration tests become rows of the test they
sit beside (t.Run of the same body), so the runner ends below its start
of 105 unit and 4 integration tests counted by top-level function.

Builds: design 47 H2 §819
2026-11-22 02:19:17 +01:00
jschoubben 5e94328066 I7 (4b): a repository with no module registers as a source alone
register takes the source form (a check of a build seat and a step kind,
no module, no path, one branch) and keeps it, its history and its
registration-changed under source.<owner>.<name>. One whose tree at the
branch's head holds a module.json at its root or under modules/, read
through the seat git's trees, is refused holds-manifest. A move of its
branch is taken in with no movers.

Builds: design 47 H2 §815, §806; H-A-349 DQ-9, H-A-438, H-A-450
2026-11-22 02:17:59 +01:00
jschoubben 3e90604eb4 D (H-A-450): register's refused names holds-manifest
A source-only registration whose repository holds a manifest is refused
by a value the enum names, so a caller registers its module instead. The
seat's form rises to 5; regenerated with seatgen, -check clean.

Builds: design 47 H2 §815; H-A-450 (1)
2026-11-22 02:16:59 +01:00
jschoubben 205a9256b8 H-A-401: the build-step part's drop says a dropped step ends could not run
The step-ended outcomes gain no dropped: the drop verb's description now
says both a waiting and a running ask end their step could not run, the
why naming the drop and who asked it, one way for an ask that never ran.

Builds: design 47 H2 H-A-401
2026-11-22 02:16:43 +01:00
jschoubben 14cd44b98e §823: the stale copies contracts/ and sdk/ at the repository's root go
No module built from them: every reader uses modules/mesh-delivery-contracts
and modules/mesh-delivery-sdk. Neither held a manifest, so the indexer's
module graph is unchanged. The repository check of the delivery SDK now
refuses a go.mod or Go import naming either root path again.

Builds: design 47 H2 §823
2026-11-22 02:16:07 +01:00
jschoubben 67caa79640 H-A-376: the runner's list answers short rows, show each mover's row
list answers by default the newest 20 short rows (key, call, start, end,
outcome, movers' count and the first failed or could-not-run step with its
module and why), and the whole pipelines only with full and a limit. show
answers one mover's steps when it names one, the steps its filters hold,
or else each mover's row, never every step of every mover. The tools
program describes each seat verb's tool from its contract, which seatgen
now generates a VerbDescription for; runner_cancel reads the whole
pipelines with full. The runner seat's form is 6.

Builds: design 47 H2 H-A-376, H-A-449, §789
2026-11-22 02:14:51 +01:00
jschoubben 9ab1c3b8f3 H-A-375: a declined pipeline step is put again on a node that has its need
A holder whose node lacks what a step's packages need (the artifact's
check-needs, now named on the integration step's ask) says the step's end
declined with needs and lacks, in place of could not run. The runner puts
it again under a new ask id naming in not-on the nodes that declined it;
a holder on a listed node hands it back at once. The nodes that can take it
are the holders of the step's seat and of the need's seat less those that
declined; when none is left the step ends could not run naming the need
and the nodes asked. The build-step part's form is 3, the runner seat's 5.

Builds: design 47 H2 H-A-375, H-A-445 (ADR 0552 §2, §4)
2026-11-22 02:08:40 +01:00
jschoubben 6b0ccc5d27 I6 (4a): the indexer builds no candidate for a source-only check
A run member or mover named source.<owner>.<name> is a source-only
registration's check, which the runner runs as one step: StartRun builds
it no candidate and keeps no run, and its pipeline-ended keeps none either.

Builds: design 47 H2 §815; H-A-438, H-A-442
2026-11-22 02:07:36 +01:00
jschoubben 7d58b2e56f H-A-441: the validate step takes the trunk's seat list from seat-list and names its digest
A revision that names no definitions of its own is judged by the trunk's
seat list as the seat mesh-catalog's chunked verb seat-list hands it, asked
as a kept call under the run's ask: its bytes fill Request.Seats and its
digest is the request's seat-list, the bytes refused when their size or
sha256 is not the answer's, so every validate run of one list judges the
same bytes and the validator reads no bus. A revision naming its own
definitions keeps them, sorted by seat, and names the sha256 of those
bytes. The manifest invokes seat:mesh-catalog.seat-list.

Builds: design 47 H2 §814; H-A-441, H-A-443
2026-11-22 02:06:47 +01:00
jschoubben f838a6c34c I6 (3): the indexer's manifest names its class, a cap on every state, and the kept-call pace
class core (it claims mesh-catalog). Every state names its cap. Fills read
with the bus module's nats_buckets on novox, 2026-11-22 ~02:20 CET (its
show answers only entries the bus module made, not old sections):
candidates 3,963,006 B (3.78 MiB) -> 16 MiB; manifests 5,463,959 B
(5.21 MiB) -> 32 MiB; seat-definitions 4,392,352 B (4.19 MiB) -> 32 MiB;
at 8 MiB, each at or below 2 MiB: packages 767,959; takeins 468,577;
findings 293,571; registrations 111,058; inputs 26,473; taken 5,595;
predefined 4,215; requirements 3,945; view-marks 3,068; first-views 1,554;
oldsections 256; runs 152; held 140; build-edges 0. Seventeen states, not
the sixteen the handover counted. The findings stream keeps 8 MiB, 7 days.
kept-call-pace-first 1s and kept-call-pace-max 30s, runtime settings, as
it makes kept calls.

Builds: design 47 H2 §775, §783, §810, §812, §814, §820; H-A-394 (1), H-A-411 (1) (2), H-A-437
2026-11-22 02:05:29 +01:00
jschoubben 381934396b I6 (2c): the indexer keeps the seat list at its start too
Once the seat definitions' state is bound at the start, the indexer keeps
the seat list in seat-lists, so seat-list answers from the first delivery
and never refuses "not kept yet" for want of a trunk definition's move.

Builds: design 47 H2 §814, §820; H-A-447
2026-11-22 02:04:18 +01:00
jschoubben 6ebc63dce3 Merge commit 'c8ba4863' into feat/47-H2-a 2026-11-22 02:04:13 +01:00
jschoubben a343fddfe7 I6 (1): the indexer's integration fixtures that claim a seat name their class
The whole indexer's hand manifests of a build module and of the assigner's
holder claim a seat, so they name class core, as the judge now asks; with
none, every take-in of those tests refused them and waited out its bound.

Builds: design 47 H2 §814; H-A-394 (1)
2026-11-22 02:03:04 +01:00
jschoubben c8ba486318 I6 (2b): the indexer keeps the seat list as one object and hands it by seat-list
At each trunk seat-definition move (said or not) the indexer writes the
trunk's definitions, resolved, as one JSON array sorted by seat into its
objects seat-lists under its sha256, when not held, and deletes every
object but the newest two, never the one just kept; one journal line per
write and delete. Its process serves the chunked verb seat-list: digest,
size and chunks, then the object's bytes; a list not kept yet is refused
naming it. The manifest serves seat-list and declares seat-lists in its old
objects section at 64 MiB. composer.Request gains seat-list, the digest of
the bytes Seats were filled from; the judge reads Seats alone.

Builds: design 47 H2 §814, §820; H-A-441, H-A-443 (1)
2026-11-22 02:00:07 +01:00
jschoubben 92ba593639 I6 (2a): the seat mesh-catalog's seat-list hands the seat list's bytes in chunks
seat-list is a chunked read verb, as input is: input call (128 random
bits), answer digest (the list's sha256, its object's name in seat-lists),
size and chunks, then the bytes on the call's chunk subject. The object
name leaves the answer. The seat's form rises to 4; regenerated with
seatgen, -check clean; the fixtures read so.

Builds: design 47 H2 §814, §820; H-A-441, H-A-443 (1)
2026-11-22 01:57:10 +01:00
jschoubben b45f12f70f B8: the builder's record of a build carries its end and outcome
The artifact store's sweep read each done key's history to learn when its build ended.
A done or failed key now carries ended and outcome, written with its end (kept as it was
when the same end is written again), so a reader of the builds reads no key history.

Builds: design 47 H2 §797
2026-11-22 01:57:04 +01:00
jschoubben c8cc249a90 B7: a tag names its commit; the builder reads a module's tags before it reserves
A number whose tag stood at another commit was reserved again, and a Go package outside
mesh-sdk's go directory was tagged go/v<version>, which the Go toolchain never reads. The
builder now reads the Go package's tags once per catalog revision, skips a number tagged at
another commit with the finding version-tagged-elsewhere (cleared at the next release), and
tags <directory>/v<version>, the directory read from the package's module path.

Builds: design 47 H2 §796
2026-11-22 01:54:49 +01:00
jschoubben b3724ca0f4 Merge feat/47-H2-sdk (9a7cc2b6) into feat/47-H2
The delivery SDK's step parts land beside the runner's work, so H-A-375
builds on them. The registrations client's test names no other seat, as
the generator's check of ADR 0625 §4 asks.

Builds: design 47 H2 H-A-375 (its base)
2026-11-22 01:50:22 +01:00
jschoubben ba54f82a70 I6 (1): the judge refuses an uncapped delivery store and a seat claim with no class
A delivery module (one claiming a seat of the delivery system, read from the
seat list's definitions) is refused for a state, log or objects entry with no
cap, in its old section or in requires; a seat-claiming manifest names class
core or leaf; finding-events is 8 MiB, 7 days; the objects template takes
max-age-days. internal/beside says a group's check reads the catalog member's
head beside it, main only when the catalog is not in the group.

Red until the captured catalog is refreshed (I6 (5)): judge
TestRulesSecrets/EveryCatalogueIdentityFitsWhatItRequires,
TestRulesSecrets/ParseManifestForInputsReadsAValueFallingBackToAPredefinedKey,
TestRulesPlacement/TheCataloguesBarPlacesBlocksAndItsShapeCoversEveryShow,
TestRulesBus/NoCatalogueManifestNamesAnInstallation; internal/index
TestAnArtifactOfNoToolchainHasNoLanguageAndNoLock,
TestAMergedManifestIsKeptOnceByItsDigestAndNamedByTheModule,
TestAModuleWithNoToolchainArtifactGetsItsFingerprintAtOnce,
TestAManifestFallingBackToAPredefinedKeyIsRead (each a captured catalog
manifest with no class, or finding-events at 16).

Builds: design 47 H2 §814, §820, §783; H-A-394 (1), H-A-411 (1) (4), H-A-415 (1), H-A-428, H-A-430 (3), H-A-434
2026-11-22 01:49:26 +01:00
jschoubben 76b1ea11a9 R13 (H-A-406): a build that passes places again the steps not asked on it
A mover's build that passes, a rerun's among them, takes out of its
pipeline the steps that ended not asked because it did not build, by the
same take-out a hand-off uses, and the pipeline's placing places those
movers again: their dependents need no hand rerun. The journal says it.

Builds: design 47 H2 H-A-406 (H-A-361's kind)
2026-11-22 01:48:41 +01:00
jschoubben 8e926283e3 R12: the runner's manifest: its findings history drops its oldest at 8 MiB, every state capped, the kept call's pace
The findings stream is 8 MiB, kept 7 days, its oldest dropped when full
(no findings-max-age setting: nothing reads one). Every state names its
cap: 8 MiB, bounds 16 MiB above four times its live fill (2,188,123 bytes
on novox, 2026-11-22 00:16 UTC; queue 50,604, findings 285,807, the rest
under 3 KB). ask-silent-bound, its file and its environment go. The kept
call's pace is declared, kept-call-pace-first 1s and kept-call-pace-max
30s, read at runtime. The runner consumes mesh-builds' and mesh-wants'
ask-taken and invokes their drop. The whole test writes 10,000 findings
past the manifest's cap and none is refused.

Builds: design 47 H2 §783, §775, §777, §778, §820; H-A-411 (1), (2), H-A-437
2026-11-22 01:47:16 +01:00
jschoubben 13d960a120 F1: an owed act failing on a part away stays owed, and a record's acts are performed again
An owed act met by the forge away (401 while the store was replaced) ended
could not be performed and nothing performed it again. Each act is now a kept
call at the module's pace (kept-call-pace-first, kept-call-pace-max) until
owed-away-bound (60 minutes), then ends could not be performed naming every
try. Before each try the bridge reads the pull request through the seat git's
pull: one closed unmerged ends owed.ended not-needed, never performed. The
gate's owed event gains record (the delivery record's source revision), kept
with the act in performed, and bridge_owed_again by record and why performs
again every act of that record that ended could not be performed, written in
the hand-act log first.

Builds: design 47 H2 §807, §775, §819, H-A-432
2026-11-22 01:46:49 +01:00
jschoubben 29162d170c B5 (H-A-435 second addendum): the builder's process health stays kind unit, builder_health a tool beside it
A tool-only health is refused by the validator (ADR 0227 rule 8, ADR 0240 rule 2), as the
runner's manifest has it: the unit check stays, the tool reads the consumers beside it.

Builds: design 47 H2 §794; H-A-435 second addendum
2026-11-22 01:46:25 +01:00
jschoubben aac7476cfe B11: a package's number newly reserved is said as version-reserved
The indexer re-pinned every importer at each publish; it re-pins once at the reservation
when the builder says version-reserved, with the package's path and the indexer's revision name.

Builds: design 47 H2 §805; H-A-420 (2)
2026-11-22 01:43:29 +01:00
jschoubben 515688cf6f R11: a source-only registration's head is run on request as its check's one step
A run whose one member is a source-only registration's key
source.<owner>.<name> runs that registration's check: one step of its
kind on the build seat it names, at the repository's root, asked on the
seat's check stream as every step, its status the registration's policy's.
Its mover is the registration's key, its repository the origin and its
fingerprint the commit's root tree hash, read through the seat git's trees
as a kept call; so its step-ended names the key, escaped into one subject
part, and the tree. A candidate's revision places nothing of it; at its
turn in the queue its step is placed from its registration. A source member
beside another, or a key with no source-only registration, is refused. The
registrations follower keys a source-only registration by its key.

Builds: design 47 H2 §815, §775; H-A-408, H-A-438
2026-11-22 01:43:20 +01:00
jschoubben 83caf486b6 B5 (H-A-435): the builder's health is builder_health, and a slow event is one journal line
The builder said nothing when its events backed up or one handling stood still; its health
now reads each durable consumer's oldest unacknowledged message from its state consumers,
and an event handled over 100 ms is said with the part that took it.

Builds: design 47 H2 §794, §820; H-A-435 and its addendum
2026-11-22 01:41:11 +01:00
jschoubben bcff47d257 B6 (H-A-425): a plan no seat builds is kept in the state unbuildable and said in one line
A line per module drowned the journal at 6,500 plans; the plans live on the bus, where
builder_unbuildable reads them, and the builder says them once per start and per seat list change.

Builds: design 47 H2 §795, §820; H-A-425
2026-11-22 01:37:32 +01:00
jschoubben b76b9c58f4 F2: the bridge's state performed is capped and pruned toward its cap at the bridge's own writes
performed filled on 2026-11-21 with nothing to stop it. It is now bound through
mesh-sdk's process.PrunedState: its figures are read when the bridge opens the
bucket its binding names, each write is counted, and past prune-mark (70 %) the
oldest acts are purged to prune-target (50 %) in one journal line, a key kept
under _keep/<key> staying. The bus drops acts older than three days by the
entry's TTL (performed-keep). performed, heads and owed-asks name an 8 MiB cap.
The tools bundle serves mesh-delivery-forge-bridge_state_prune_now and
_state_keep from stateobjects.PruneTools, each written in the hand-act log.

Builds: design 47 H2 §812, §819, H-A-380, H-A-386, H-A-411 (2), H-A-433
2026-11-22 01:36:34 +01:00
jschoubben 40c2870a71 I4: a release re-pins once, at its reservation
The builder's version-reserved writes the series' numbered version with the
contents of the module's entry commit, so acceptedSeries and releasedPins pin
it; the indexer keeps each reservation in heard (reserved.<revision>.<module>,
reserved-keep) and gathers a revision's reservations until its pipeline's
start, its first step-ended or the expiry of settling.<revision>
(reserved-settle), then keeps one re-pin revision of that branch. The release's
package-published moves no fingerprint; a pipeline-ended not passed withdraws
its reservations to the newest released version.

Builds: design 47 H2 §805; H-A-418, H-A-420, H-A-424, H-A-436
2026-11-22 01:35:56 +01:00
jschoubben 9a7cc2b632 BM publish version (sdk): publishParts refuses a Go package or a bundle that names no version
A publish by its digest alone marks no reservation, so no build module may publish a Go package or a
bundle without the version its ask reserved; the refusal is loud and comes before the seat is asked.
An archive may still publish by its digest.

Builds: design 47 H2 H-A-373, H-A-373 (addendum)
2026-11-22 01:35:11 +01:00
jschoubben 38ad9ed84d R10: a step's output is read where its build seat's holder keeps it
runner_step_output (pipeline, mover, step) reads the step from the state
pipelines and asks the verb output of the build seat's holder on the node
its step key names, by the step's ask, once per artifact the step ran for;
a step that reads a shared run is answered by that run's ask. The runner
keeps no output of its own: the objects step-outputs go, with the step's
and the log entry's output and show's outputs; the runner seat's form
rises to 4. The manifest invokes the three build seats' output.

Builds: design 47 H2 §791; H-A-412 (1)
2026-11-22 01:34:54 +01:00
jschoubben d096ba37e3 BM3 install queue (sdk): DeclareAskWorkers declares a seat's every queue, the Node seat's install too
A node puller bound no install worker, so the Node build seat stopped taking its install asks: the
workers are now declared per AskQueues(language), not AskKinds.

Builds: design 47 H2 H-A-403
2026-11-22 01:33:35 +01:00
jschoubben 7ed668fa53 I7: a catalog entry carries its manifest's class
The gate reads a mover's class from its catalog entry when it opens the
delivery record, so the indexer writes the manifest's class there.

Builds: design 47 H2 §810; H-A-394 (1), H-A-431 (1)
2026-11-22 01:32:06 +01:00
jschoubben 9b2b2a934c Merge commit '84989daf' into feat/47-H2-i 2026-11-22 01:31:32 +01:00
jschoubben 84989dafb2 D7: a catalog entry carries its class
The seat mesh-catalog's CatalogEntry gains class, core or leaf; an entry
without it reads as leaf. The indexer writes it from the manifest. The
seat's form rises to 3; regenerated with seatgen, -check clean.

Builds: design 47 H2 §810; H-A-394 (1), H-A-431 (1)
2026-11-22 01:28:07 +01:00
jschoubben d13efa8abe R9: the stalled bound is the setting stalled-bound; the health names a step whose ask is untaken past it
Builds: design 47 H2 §790, §778 (the health line), §781 (read through mesh-sdk's settings reader)
2026-11-22 01:23:58 +01:00
jschoubben 40ad2650bd A4: a want of no pipeline carries the newest source held for it
A placement's build or a put written after a delivery carried the kept
graph's trunk source as its run, which can be older than the delivered
want's, so the compare-and-set refused a person's act (the whole test of a
placement back at a module's first build). The newest source the assigner
holds for such a want is now the kept trunk source or the run of the want
written, whichever is newer.

Builds: design 47 H2 §813 (1); H-A-416
2026-11-22 01:22:52 +01:00
jschoubben 43a88ef96c R7: the registration check waits for its view; runner_health answers registrations-read
Builds: design 47 H2 §788
2026-11-22 01:19:27 +01:00
jschoubben b9bc44024d A2: the seat mesh-wants' drop says the step ends could-not-run
The drop's description said a dropped ask's step ends "dropped", an outcome
the step-ended has not: it ends could-not-run, its why naming the drop and
who asked it, as the assigner says it.

Builds: design 47 H2 §778; H-A-401
2026-11-22 01:19:20 +01:00
jschoubben 477d351fc0 A4: a want carries its run and is written by compare-and-set refusing a lower one
Two writers of a node's want could leave it at an older delivery, and the
node-engine could not tell a newer want from an older one. Each want now
carries run: the source revision of the pipeline that released it, or, for a
want of no pipeline (a put, a placement's build, a removal), the newest
source the assigner holds. It is written by compare-and-set (create, or
update at the revision read), refusing a want whose run is lower than the
one written, said in the journal; a want that differs only by its run stands,
so no node composes again for it. The answer's other half is the node-engine's:
its manifest states declaration-reads and declaration-writes, the assigner's
neither.

Builds: design 47 H2 §813 (1); H-A-355 (1), H-A-416
2026-11-22 01:19:20 +01:00
jschoubben 8f89dd29f5 A2: the assigner reads an oversized run answer through the build seat's verb answer
The build-step part's output verb loses call and chunks (form 2): a
composition or validate run's answer over the inline bound is read through
the Go build seat's read verb answer (buildstep.StepEnded.ReadOutput, the
chunked call), so the manifest invokes seat:node-build-go.answer in place of
seat:node-build-go.output.

Builds: design 47 H2 §791; H-A-412 and its addendum
2026-11-22 01:19:20 +01:00
jschoubben 346b37d623 B2 (H-A-401): the seat mesh-builds' drop says a dropped ask's step ends could-not-run
Builds: design 47 H2 §778, H-A-401
2026-11-22 01:17:53 +01:00
jschoubben a43b722dbb BM4 kit (sdk): the conformance kit judges the build-step part's form 2
StepEnds also refuses steps that keep no outputs. SeatVerbs, which every build
module runs with its seat tools and steps, judges current, output and answer at
form 2, and runs a pipeline step whose test answer holds the level's text, a
NOT RUN skip and a failure, naming an install archive: its end must carry the
not-run, the archive must reach the test call and the run's output must be
read back through the module's verb output; an install is judged only where
the steps install, on node-build-node alone.

Builds: design 47 H2 §791, §800, §801; H-A-367, H-A-412, H-A-421
2026-11-22 01:16:57 +01:00
jschoubben 8d43ce0cb9 R6: a kept mover waiting on its kept revision says so; the record's kept-revisions are read past, not dropped
The runner seat's Mover gains unplaced (kept-revision-unread) and revision, the seat's form 3.

Builds: design 47 H2 §787, §780 (fate: the drop of kept-revisions before the decode goes)
2026-11-22 01:16:51 +01:00
jschoubben c623987fcc B1 (H-A-412): the builder reads an oversized step end through the build seat's verb answer
The wait answered "no verb to read" for every step whose end is kept as its
answer object: the process never set the asker's reader and its manifest
invoked no build seat's answer.

Builds: design 47 H2 §791, H-A-412 (addendum)
2026-11-22 01:16:34 +01:00
jschoubben 1aba89e8ba A6: a validate step counts only problems new against its case before
A take-in that touched a manifest failed its validate step on every problem
that manifest already had, so an old problem blocked any change to it. The
step now counts, for every manifest and between manifests, only the problems
the case before does not hold; assigner_validate_before (pipeline, module)
answers from the kept validate run the ones it holds and did not count.

Builds: design 47 H2 §814
2026-11-22 01:15:54 +01:00
jschoubben 7c9da7d0cb A5: a failed keeping of the assignment graph runs again, and by hand
A keeping that failed was handed again only by the next pass, so with no
change of inputs no revision was kept and no want said as wanted. A failed
keeping now runs again after keeping-retry (a runtime setting, 30s, the
holder's own deadline), unless a newer revision was handed meanwhile, and
raises keeping-failed (scope module) at the third failure in a row, cleared at
the next keeping that succeeds. The seat mesh-wants gains the act keep-now,
which the assigner's process serves: it keeps the pass's newest computed
revision at once, one keeping at a time, and answers the revision kept or the
fault met; the tool assigner_keep_now writes the hand act first and calls it.

Builds: design 47 H2 §813 (2); H-A-417
2026-11-22 01:14:05 +01:00
jschoubben 427885013e R8: a pipeline is read in parts: show filters while reading and pages at 768 KB; runner_show, runner_movers
Builds: design 47 H2 §789, §779 (the cursor), §811
2026-11-22 01:12:57 +01:00
jschoubben 02ec2f00d9 BM4 (sdk): a run's test output is kept as <node>.<ask> and read by the verb output
A test step takes the level's text out of its test answers (their member
output) and keeps it in the holder's outputs objects as <node>.<ask id>, a
header of its size and the failing tests with their words from the level's
results beside the text; a check ask's answer keeps none. The verb output at
the part's form 2 takes the ask and answers the text's last 64 KB, its size and
the failing tests from the header; no-longer-kept only when this node's steps
key shows the ask ended more than the max-age (7 days) ago, an ask never run
here refused naming it.

Builds: design 47 H2 §791, §820; H-A-367 (1), H-A-412 (1) and its second and third addenda
2026-11-22 01:12:46 +01:00
jschoubben 6ea33475b6 B1 (H-A-412): a step's oversized end is read as its answer object
The delivery SDK's build-step part keeps a step's end over the steps state's
value as the object answer.<ask>, read through the build seat's verb answer;
OutputObject is gone. The builder's wait names the answer object it could
not read.

Builds: design 47 H2 §775, §791; H-A-412
2026-11-22 01:12:25 +01:00
jschoubben cc5f803f87 I5: the registrations are read in one call, filtered and paged
The verb registrations and the new tool indexer_registrations filter by
module and repository while they read, at most 768 KB a page, capped with
the cursor next: the tools bundle reads the state from the bus's cursor
(mesh/state.page), a store that pages none by its keys in order; total is
said when one page holds the whole read.

Builds: design 47 H2 §806, §811, §779
2026-11-22 01:12:04 +01:00
jschoubben fad9f059ee BM4b (sdk): an end over the steps state's value is read through the verb answer
A step's end is an event, not a verb's answer, so an end over what the steps
state's value or step-ended carries has a reader of its own: keepOver keeps it
in the steps objects as answer.<ask>, the step key and step-ended carry
answer-object in place of output-object, and the build seats gain the read
verb answer (ask and call, marked chunks); output stays the run text's reader.
Step.Whole and StepEnded.ReadOutput read through answer.

Builds: design 47 H2 §791; H-A-412 (2) and its addendum
2026-11-22 01:08:58 +01:00
jschoubben d719a69b7d I3: a dry run keeps its packages in its own scratch state
A branch's take-in, a run's candidate and a branch's re-pin compute as dry
runs whose packages went to the trunk's packages state. They now write them
to the state dry-runs under <branch>.<call>.packages.<name>, read through to
the live state, deleted when the dry run answers and every key at the
indexer's start; the manifests stay create-once by digest as every take-in's.
indexer_dry_runs reads the state; the manifest asks for it, 16 MiB, one
hour's TTL.

Builds: design 47 H2 §804, §820; H-A-413 and its addendum
2026-11-22 01:08:34 +01:00
jschoubben 905a055a1e B2: the builder serves the seat mesh-builds' drop and its queue's tools
A caller whose step ended by its bound could not stop the builder working on
its ask, and nobody could see what waited on the seat's work queue. The
builder now serves the seat's verb drop: an ask it runs is cancelled, one not
pulled yet is kept dropped in its state taken (dropped.<ask>, for
ask-taken-bound); both end the step could-not-run naming the drop and who
asked it. builder_asks reads the waiting asks through the runtime and the
taken ones and the drops from the state taken; builder_ask_drop asks the
seat's drop once the hand act is recorded.

Builds: design 47 H2 §777, §778; H-A-401, H-A-404, H-A-410
2026-11-22 01:08:30 +01:00
jschoubben 48aa36120d A3: an answered validate or composition ask is one journal line
The journal said a step's end only when it failed to say it, so an ask's
answer could not be followed by reading the journal. The assigner writes
"answered <ask> <pipeline> <movers> <step> <outcome>" where the step's end is
said, the one place a validate or composition ask is answered.

Builds: design 47 H2 §792
2026-11-22 01:07:50 +01:00
jschoubben e216e94029 A1: the assigner asks each machine's compose-candidate as a kept call
A composition step ended at a node-engine's first "no responders": the
engine between two lives gave no input. The holder of mesh-wants now asks
compose-candidate through mesh-sdk's kept chunked call, under the ask id
<step ask>.<node> the engine takes once, called again at the kept-call pace
through transport faults until compose-ask-bound (a runtime setting, 10s).

Builds: design 47 H2 §775; H-A-405, H-A-364
2026-11-22 01:07:22 +01:00
jschoubben dc72860ce0 A2: the assigner pulls the seat mesh-wants' work queue and takes each ask once
A step ask put while the assigner was down waited for nobody: the plain
subscription heard only what came while it ran. The assigner now pulls every
waiting ask from the seat's one worker, takes it once by its id in its state
taken (for ask-taken-bound), says ask-taken at the pull, sends in-progress
while the step runs and acknowledges once the step's end is said. It serves
the seat's act drop: a running ask is cancelled, one not yet pulled is kept in
taken as dropped.<ask>; either ends its step could not run naming the drop.
assigner_asks reads what waits on the queue (stdio.QueueWaiting) and what is
taken or dropped; assigner_ask_drop ends one ask, written in the hand-act log.
The manifest declares taken, drop, the two tools, ask-taken-bound and the
kept-call pace as runtime settings.

Builds: design 47 H2 §777, §775, §778, §820; H-A-381, H-A-401, H-A-404, H-A-410
2026-11-22 01:05:07 +01:00
jschoubben 62e8274bf9 R5: a mover left unfinished by another's failure is put in a pipeline again
A pipeline ending failed or cancelled keeps each mover whose own required
steps passed or never ran in the runner's state unfinished and names it in
pipeline-ended's unfinished; the branch's next kept catalog revision carries
it, or starts a pipeline for it alone. runner_unfinished reads the state,
runner_unfinished_drop drops one key, runner_unfinished_place asks the new
seat verb place-unfinished (contracts regenerated), both hand acts.

Builds: design 47 H2 §786, §820 (unfinished), H-A-398
2026-11-22 01:02:58 +01:00
jschoubben 8bd66112f0 I2: a take-in says what it waits on
A source-moved take-in waiting over a minute on the seat git writes one
journal line and its waiting-on (part, verb, since) in the state takeins
under running.<source revision>, removed at the take-in's end; past five
minutes it raises take-in-waiting (scope merge), cleared when the wait
ends. indexer_pending answers the running take-ins beside the held ones.
The wait is measured by a context's bound, no timer (ADR 0437 §8).

Builds: design 47 H2 §803, H-A-409
2026-11-22 01:02:11 +01:00
jschoubben 8617b521a6 BM5 (sdk): a build seat's current says what it takes and every ask it runs
The verb current answers at the part's form 2: the node, whether it takes
asks and why not (paused, capacity 0, unhealthy) since when, its capacity, and
every ask it runs with who asked it. Each judgement keeps since when.

Builds: design 47 H2 §801; H-A-367 (2), H-A-399 (1)
2026-11-22 01:00:22 +01:00
jschoubben 8813c4e9e9 BM4a (sdk): a build seat's holder keeps its outputs in its outputs objects
steprun.OutputsStore names the holder's `outputs` objects, which its manifest
requires with their cap and max-age, in place of the steps state's own
objects store.

Builds: design 47 H2 §791, §820; H-A-399 (1)
2026-11-22 01:00:22 +01:00
jschoubben b00cf73d77 BM3 (sdk): an install is a StepAsk of the kind install, dispatched by RunAsk
node-build-node accepts install as a StepAsk holding an install job (the
InstallAsk's fields and the module's fingerprint) under the version its
archive is published with; install is its own queue on that seat alone and
its holder pulls it. RunAsk dispatches the kind to the module's install body,
which publishes the archive <module>:node-modules to the artifact store, and
the install's end names the reference it answered.

Builds: design 47 H2 §800; H-A-367 (4), H-A-379, H-A-399 (1) (2), H-A-403
2026-11-22 01:00:22 +01:00
jschoubben 7ffec1b56b I1: a module's fingerprint takes a package by what is published, never by a commit of its repository
A package of another repository none publishes leaves the module without a
fingerprint (NoPackageVersion) instead of taking the gate's source head; one
of the module's own repository none publishes enters by its directory's tree,
which the tree input carries, so the same source gives the same fingerprint.

Builds: design 47 H2 §802, H-A-349 DQ-8, H-A-350 DMC-5
2026-11-22 00:53:49 +01:00
jschoubben 592637e6d7 BM2b (sdk): a step's install archive reaches its test calls
The integration step's ask names the install archive; the step run carries
it on the check job it runs and hands it to every test call as its argument
archive, for the Go build module to unpack into the workspace.

Builds: design 47 H2 §800; H-A-367 (4), H-A-399 (1)
2026-11-22 00:53:20 +01:00
jschoubben 3fce8700bf BM2 (sdk): a test that cannot run says NOT RUN; a starved setup runs again
ReadGoTest answers the skips whose words open "NOT RUN:" as not-run with
their reasons; a pipeline test step carries them into its end, the level
passing. A level whose every failure is a starved setup (testbus.SetupStarved)
ends its run again by the again-delays; its third run ends the step could
not run "the bus did not answer in setup within <bound> under load", never
failed. A step's last run that meets a fetch or publish fault now says its
end failed with the why it opens with, so the runner hears it.

Builds: design 47 H2 §800, §799; H-A-294, H-A-367 (3), H-A-368, H-A-399 (1)
2026-11-22 00:53:20 +01:00
jschoubben 3a647a8e2d B3: an answered build ask is one journal line naming its ask
The line a build step's finish wrote named no ask, so an answer could not be
matched to the ask the runner put. BuildStep now takes the ask's id and its
finish writes "answered <ask> <pipeline> <movers> <step> <outcome>".

Builds: design 47 H2 §792
2026-11-22 00:52:34 +01:00
jschoubben 7dbd440a4e B1: the builder pulls the seat mesh-builds' work queue and takes each ask once
An ask put while the builder is down waited for nobody: the plain subscription
heard only what came while it ran. The builder now pulls every waiting ask from
the seat's one worker, takes it once by its id in its state taken (for
ask-taken-bound), says ask-taken at the pull, sends in-progress while it builds
and acknowledges once the step's end is said. Its publish to a registry seat is
a kept call carrying the publish's ask id. The manifest declares taken and the
kept-call pace and ask-taken-bound as runtime settings.

Builds: design 47 H2 §775, §777, §820; H-A-381
2026-11-22 00:45:40 +01:00
jschoubben 9acf583daf R3: a step's end is one journal line, said in one place; Resume puts no taken ask again
Every step-ended goes through sayStepEnded, which writes "step ended <pipeline>
<mover> <step> <outcome> in <duration>"; the cancel verb now says each step it
ends. Resume at a start puts again only an open step's ask no holder took.

Builds: design 47 H2 §784, §777 (H-A-397)
2026-11-22 00:35:13 +01:00
jschoubben f420a8213a R2: an ask's bound counts from the pull and ends its step, dropped
The bound key ask.<seat>.<ask> is armed at the put, again at the holder's
ask-taken (heard now for mesh-builds and mesh-wants too) with what is left
since taken-at, again from now at each step-progress, and at a start for every
open ask whose key is gone; it is deleted at the step's end. Past it the step
ends could-not-run, naming an untaken ask's seat holder as taking none, and its
ask is dropped through the seat's drop. The silent seats' bound, the second put
under AgainID, the ask2. keys and the put again at a holder's running go; a put
refused by a full work queue is said and put again at the kept-call pace.

Builds: design 47 H2 §777, §778 (H-A-349 DQ-4, H-A-395)
2026-11-22 00:30:56 +01:00
jschoubben e7d9849efa R4: pipeline-ended carries the pipeline's phases
taken (the record's start at its take-in), placed (the earliest step start),
ended, and per step kind the earliest start and latest end across movers, so
the gate reads where a pipeline's time went.

Builds: design 47 H2 §785
2026-11-22 00:22:50 +01:00
jschoubben f6e7f4210b B9: a fetch or a publish met away ends its run again, by again-delays, with no seat call
The build modules' shared steprun parts of §799: again-delays (15s,60s) read
into a Puller's Delay; a fetch's 401/5xx or connection fault and a publish's
no responders or exited bundle are transport faults whose why opens fetch: or
publish:; the assigner call that named a silent holder goes. The builder reads
an exited bundle as no responders and keeps the part in a key's fault words.

Builds: design 47 H2 §799 (H-A-390)
2026-11-22 00:20:17 +01:00
jschoubben 1058b0eec6 R1: the runner puts a step's ask and asks published as kept calls, paced, within ask-unanswered-bound
A put that met a transport fault is put again under the ask's own id at the
kept-call pace instead of failing the step at the first fault.

Builds: design 47 H2 §775
2026-11-22 00:15:07 +01:00
jschoubben 125d6382ea D6: the delivery seat's deliveries filters before it sizes
deliveries filters by repository, module, outcome and since while it reads,
pages by the cursor next and answers its deliveries with capped and total.
The seat's form rises to 2.

Builds: design 47 H2 §779, §811
2026-11-22 00:09:51 +01:00
jschoubben d2d3ebbf44 D5: the git seat's tags name their commits, and a holder says away
tags answers items {tag, commit}; trees' description says a missing directory
answers not-found; the error kind away joins refused, not-found and failed,
every answer carrying part and words with it; tag's description names the
<directory>/v<version> form. The seat's form rises to 2. The builder's,
bridge's and indexer's readers take the tag's name from the item.

Builds: design 47 H2 §776, §796; H-A-350 DMC-2, DMC-3, H-A-354
2026-11-22 00:08:50 +01:00
jschoubben 278310cc67 D4: the catalog seat pages registrations, says the seat list, takes a source alone
registrations filters by repository beside module while it reads, pages by
the cursor next and answers capped and total. The read verb seat-list answers
the seat list's object in seat-lists by digest, size and name. A registration
takes a source-only form under source.<owner>.<name>, with origin, one branch,
policy and check (a build seat and a step kind), naming no module; its history
keeps the same key. The seat's form rises to 2.

Builds: design 47 H2 §806, §811, §814, §815; H-A-349 DQ-9, DQ-10
2026-11-22 00:05:48 +01:00
jschoubben 1767d7b4e9 D3b: an install ends in a step-ended naming the step install
The build-step part's step enum and the delivery SDK's PipelineSteps gain
install; an install's end copies the module and the commit its ask names and
carries the archive, and the SDK's check takes it so.

Builds: design 47 H2 §800; H-A-367 (4), H-A-379
2026-11-22 00:04:05 +01:00
jschoubben ac99946fcb D4a: the registry's list takes module and a cursor, and pages at 768 KB
oci-artifact-registry's list filters by module beside name while it reads,
continues from the opaque cursor next and answers capped and total; the
seat's form rises to 2. The shared remove no longer judges its caller for a
retention removal.

Builds: design 47 H2 §779, §811, §813 (7); H-A-350 DMC-10
2026-11-22 00:02:21 +01:00
jschoubben 4749c686eb D3: the build-step part says output, current, not-run and install in its form 2
output takes the ask and answers the output's last 64 KB, its size, the
failing tests with their words, or no longer kept; its call and chunks go.
current answers the node, whether it takes asks and why not since when, its
capacity and every ask it runs with its asker. A step's end gains not-run and
archive, a step ask names the archive to unpack, and node-build-node accepts
install. The delivery SDK's neutral forms carry the same fields.

Builds: design 47 H2 §791, §800, §801; H-A-350 DMC-16, H-A-367
2026-11-22 00:00:41 +01:00
jschoubben 1f5b0f813d Merge origin/main into feat/47-H2 2026-11-21 23:53:44 +01:00
mesh-tools fe5fa6ac94 Merge pull request 'The runner takes out the stayers' steps not asked on a mover that left and places them again at the hand-off (H-A-361)' (#321) from fix/47-H2-end-after-handoff into main 2026-11-21 22:38:18 +00:00
jschoubben 99b25a7db4 H-A-361: a hand-off places again the stayers not asked on a mover that left
On 21 Nov the order was the reverse of the first commit's: mesh-contracts'
old build was withdrawn first (21:50:16), so the stayers that awaited it
were placed not asked, and only then did the hand-offs take it away. A
mover that left is still a dependency of those stayers: their not-asked
steps held the pipeline's end as failures. At the hand-off the steps of
each stayer that ended not asked on a dependency that left, directly or
through a mover itself taken out, are taken out, so the placing that
follows places them again against the newest published package; a
dependency that truly did not build is named again at that placing. The
journal says which movers are placed again.

Builds: design 47 H H-A-361, H-A-53, H-A-223
2026-11-21 23:34:24 +01:00
jschoubben a559b0e7c9 D1b: the two seats' work queues carry their settings, derived once in mesh-sdk
mesh-builds' and mesh-wants' accepted kind step names max-age 24h, max-msgs
10,000, ack-wait 60s, in-progress 20s, max-ack-pending 1,000, max-deliveries 5
and a duplicates window of 2m; the grants part makes each seat's ask stream
through mesh-sdk's buscompose.SeatQueue and says a seat whose settings it
refuses, and its own copy of the derivation goes.

Builds: design 47 H2 §777; H-A-350 DMC-1, H-A-362
2026-11-21 23:23:04 +01:00
jschoubben 7606d515fd H-A-361: a hand-off places the movers that stay; a mover that left is not awaited
main.158 and main.163 ended failed seconds after newer pipelines took
movers away: the movers that stay still awaited the movers that left,
whose builds had ended superseded, so the next placing ended them "not
asked: its dependency did not build" and the end judgement counted
them as failures. A mover that left is no longer awaited (the stayer
builds against the newest published package, H-A-53), is never placed
in the older pipeline, and the hand-off places what stays at once and
says in the journal which movers stay.

Builds: design 47 H H-A-361, H-A-53, H-A-223
2026-11-21 23:17:59 +01:00
jschoubben b40745534f D2: the runner's seat says phases, unfinished and re-pinned, and pages show
A step keeps asked-at and taken-at; pipeline-ended carries phases and
unfinished; show takes step and state filters and the cursor next, and
answers capped and total; re-pinned is declared. The seat's form rises to 2.

Builds: design 47 H2 §778, §785, §786, §789, §821; H-A-349 DQ-13
2026-11-21 23:17:31 +01:00
jschoubben c1ec75789f Readers of mesh-contracts' regenerated seats take the form
The node enroller's and the watchdogs' generated decoders answer the form
they read (mesh-contracts K1); their readers here take it.

Builds: design 47 H2 §780
2026-11-21 23:15:31 +01:00
jschoubben 75208ffcba D1: mesh-builds and mesh-wants say ask-taken, take drop, and the want carries run
Both seats declare ask-taken (ask, node, at) on ask-taken.<ask> and gain the
act drop; mesh-builds declares version-reserved; the want value the
node-engine applies carries run, the composition run's pipeline sequence, and
mesh-wants' form rises to 2. The queue settings of the accepted kind wait on
mesh-sdk's seatdef and buscompose (H-A-362, D1b).

Builds: design 47 H2 §777, §778, §805, §813 (1), §821; H-A-349 DQ-1, H-A-350 DMC-15, H-A-355 (1)
2026-11-21 23:15:31 +01:00
jschoubben 6046ebe2e0 G1: the fields digest is kept per type
A type added or removed whole changes no reader's value; only a type whose
fields changed while the form did not fails the compare.

Builds: design 47 H2 §780; H-A-352 (2)
2026-11-21 23:15:31 +01:00
jschoubben ff7db33720 G1, D0: seat readers decode tolerantly and say their form
The seat generator gives every value, event and answer the wire field form
(left out while 1) and a tolerant decoder answering the form it read; each
contract carries its forms and a digest of its fields, and the compare fails
a definition whose fields changed while its form did not. Every delivery seat
is regenerated, and the readers take the form.

Builds: design 47 H2 §780; H-A-352
2026-11-21 23:11:10 +01:00
jschoubben 2df32b7892 T1: the teller's ask-again for want of room goes
The channel holds no room to wait for (A-424): a refusal for want of room is
said as any refusal is, and its waiting, its bound of refusals and their tests
go. The wait for asks the router did not take stays.

Builds: design 47 H2 §813 (10)
2026-11-21 23:03:08 +01:00
mesh-tools 7e597a623e Merge pull request 'The runner and the builder write a journal line per step end, ask placed and ask answered (H-A-320, H-A-333)' (#320) from fix/47-H2-journal-lines into main 2026-11-21 21:01:55 +00:00
jschoubben 6a847a8d9c H-A-333: the ended line at every said end, the answered line at every answer
The runner's ended line was written only for a heard step-ended and its run's
readers; the unanswered-bound end, the end at placing, a supersede, a re-pin,
the approval's end, the start pass and the verbs said their ends silently. It
is now written in Hearer.say, the one place that says step-ended, and at the
starter's two sayers that call stepEvent directly (repin, sayNotAsked). The
builder's answered line sat on four of buildEntry's returns; the ask's answer
is now one line in BuildStep's finish, naming the pipeline, the movers, the
step and the outcome, the per-entry existing/built-now line kept beside it.

Builds: design 47 H H-A-320 (1), H-A-333
2026-11-21 21:58:36 +01:00
jschoubben dc83ef3e27 H-A-320 (1): a journal line per step end, step ask and build answer
A working 36-mover pipeline was read as stalled twice: the runner wrote no
line when a step ended or was asked, and the builder none when it answered a
step ask. The runner now writes "<pipeline> <mover> <step> ended <outcome>
(<node>, <duration>)" at each step end it writes (the asking step, every
reader of its test run, and each reader EndRun ends), and "<pipeline> <mover>
<step> asked on <seat>" for each ask put (the re-ask paths keep their own
line). The builder writes "<module>@<fingerprint> build step answered
<outcome> for <pipeline> (existing build / built now)".

Builds: design 47 H H-A-320 (1)
2026-11-21 21:50:48 +01:00
mesh-tools 600c13b9e9 Merge pull request 'Design 47 H: the runner redoes a cut placing, places on a late end, names a stalled pipeline, and reads a prior publish from the build seat (H-A-311, H-A-313, H-A-326, H-A-328, H-A-331)' (#319) from fix/47-H1-runner-placing-redone into main 2026-11-21 20:48:59 +00:00
mesh-tools 5396dc9b11 Merge pull request 'The teller's want-of-room test bed answers the seat-holder ask; one taker of registration-changed (H-A-295)' (#318) from fix/47-H1-teller-test-want-of-room into main 2026-11-21 20:48:56 +00:00
mesh-tools 425dbaef99 Merge pull request 'Design 47 H: a passed pipeline whose movers' versions arrive late still writes its wants (H-A-270, H-A-273, H-A-277)' (#317) from fix/47-H1-end-taken-when-versioned into main 2026-11-21 20:48:49 +00:00
jschoubben 714c2c1ccc H-A-331: the published answer carries the publish time and digest where kept; a withdrawn number is never published
The verb published answered no time, and after a release no digest,
while the seat form says both come when published. The builder now
keeps when it heard or confirmed each publish on the mark, and each
published digest on a kept release; marks and releases written before
answer without them. A number a take-over withdrew is not published.
The runner drops a pipeline's kept answers at its end.

Builds: design 47 H H-A-331, H-A-328
2026-11-21 21:38:50 +01:00
jschoubben e583dce741 H-A-326 (1), (3): a mover's wait on a package is a read first, an event second
main.137 stood twenty minutes with nats and mesh-vault waiting on
mesh-grants packages published at 20:00, before the wait was written,
so no publish event came. The runner now asks the build seat's
published when it writes the wait and places the mover when the
package is published, saying so in the journal apart from an event.

Builds: design 47 H H-A-326 (1), H-A-326 (3), H-A-328
2026-11-21 21:25:03 +01:00
jschoubben 5e76fdf725 H-A-328: the seat mesh-builds answers published; the builder serves it
A package published before a pipeline existed is in no record of the
runner, so the builder, which owns publishes, answers whether an
artifact built at a fingerprint is published, from its reservations
(marked from the registries' record) and its releases.

Builds: design 47 H H-A-328, H-A-326 (1), H-A-274
2026-11-21 21:25:03 +01:00
jschoubben 438c8740a6 H-A-326 (2): a pipeline waiting only on packages is named stalled
A step held on a package's publish counted as open, so a pipeline whose
only movers waited on publishes that had come before their wait was
never named by runner_health (main.137, twenty minutes).

Builds: design 47 H H-A-326 (2), H-A-311 (3)
2026-11-21 21:18:32 +01:00
jschoubben 05d9f90bdb H-A-311 (3) review: the health reads records keeping revisions; a required step waiting is open
runner_health, show, list and stands refused every pipeline record
carrying the runner's own kept-revisions ("unknown field
kept-revisions" on main.131 and main.137): the field is now dropped
before the seat's strict decode. A required step waiting (an approval,
a pin-held step) now counts as open, as the end's judgement holds it.

Builds: design 47 H H-A-311 (3), H-A-313, H-A-285, H-A-309, H-A-322
2026-11-21 20:53:04 +01:00
jschoubben f22945c26a H-A-311 (3): runner_health names a running pipeline with nothing open and nothing placed for five minutes
main.137 stood seventeen minutes with nothing open while runner_health
said healthy. The tools program says each such pipeline in its journal
once per key (H-A-313).

Builds: design 47 H H-A-311 (3), H-A-313
2026-11-21 20:44:43 +01:00
jschoubben e137df7189 H-A-311 (2): a step-progress or step-end heard late still places what its end unlocks
A late progress or end moved nothing, so movers waiting on what the
step's end gave stayed unplaced: main.137 placed nothing after its
lint's late progress at 20:17:55.

Builds: design 47 H H-A-311 (2), H-A-286, H-A-288
2026-11-21 20:43:02 +01:00
jschoubben 6c66bf9a5a H-A-311 (1): a placing cut by a concurrent write is done again from the record read again
A placing whose compare-and-set was refused because the pipeline was
written meanwhile was dropped and never done again: main.137 stood
seventeen minutes with eleven steps placed until a restart.

Builds: design 47 H H-A-311 (1), H-A-288
2026-11-21 20:41:29 +01:00
jschoubben b79fd19c84 Teller: hear registration-changed on the views reader's one subscription
Since mesh-sdk heard a seat's event on its bare subject too (H-A-166), the teller's
own hub handler of registration-changed overlapped the one the views reader makes
for the catalog half's followers: the hub refused the reader's, said "a message has
one taker", and registered none of the reader's adopted events after it, so the
catalog half's registrations and source branches were their first views' alone.
The widenings now hear the event through ProcessReader.AdoptEvent beside the
followers; a failed handling is given back for the bus to ask again, as before.
The carry test now fails when any of the reader's events is refused.

issue 1960 (H1), test stability.

Builds: design 47 G A-199, A-222, §532, §335
2026-11-21 19:24:22 +01:00
jschoubben 70bb8f7f51 Teller test bed: answer who holds operator-channel, so a catch-up does not hold the asks' watch
The want-of-room test failed most runs since 20 Nov: the teller's picture of the
assigner's asks hands the first ask on twice (its first view, then again), and the
second sight of an open asking catches up with the router's record, which first asks
the seat mesh-module-assigner's assignments who holds operator-channel. The bed
neither granted nor answered that call, so it waited out its call timeout on the
watch's goroutine, and the second ask, written meanwhile, was not raised within the
test's 10 s. The bed now grants and answers the call as the live seat does, naming
ops-router, so the catch-up reads ops-router_asks at once (20 of 20 runs pass, were
0 of 20 locally).

issue 1960 (H1), test stability.

Builds: design 47 G §570 (issue 1610 AC1, the refused ask asked again), §717
2026-11-21 19:21:24 +01:00
mesh-tools e196064e51 Merge pull request 'Design 47 H: the builder's publish queue: live asks first, newest per series, one listing per pass (H-A-290..293)' (#316) from fix/47-H1-builder-publish-queue into main 2026-11-21 18:00:25 +00:00
jschoubben 2eaa41a420 H-A-292, H-A-293: builder_publish_queue reads one page; a build is retired only within its series
The review found two faults. The tool paged on through a state of any size, one replay of the bucket per page; it now
reads one page of each of its own states and, when the state holds more, answers that page capped, with the keys read
and the state's size from its info, never asking a second page and never refusing. And the retiring of superseded done
builds keyed the newest reservation and release by module alone, so a standing 0.2 would retire a done 0.1.x; both are
now found per module and series (MAJOR.MINOR).

Builds: design 47 H H-A-292, H-A-293, H-A-291 (1), H-A-290 (5)
2026-11-21 18:59:58 +01:00
jschoubben 90ff867e7a lock the test fakes' maps
Two tests failed under -race on main too: the re-ask state fake's maps were written by a try on the watch's goroutine while
the test read and deleted them, and the operator-ask test read the build store unlocked and waited on the builder while
the build its answer starts could still be counting itself in. The fake's maps are locked and read through it, the store
is read under its lock, and the builder is waited on only once that build has claimed its key.

Builds: design 47 H H-A-290 (the module's tests pass with -race, as its checks ask)
2026-11-21 18:59:58 +01:00
jschoubben 77fb6c4ab1 H-A-291: a start publishes only each module's newest done build; a live enqueue cuts a start list short
A start asked a publish again for every unreleased done build, older ones whose digests a newer reservation or release
of the same module made dead included, and a live publish queued during a long start pass waited for its end. A done
build a newer reservation or release (the builder's own record) supersedes is now retired at the start and at the pass:
its key dropped, its publish item ended, said in the journal; the start asks only each module's newest. A live enqueue
marks its holder, and a pass about to send a start-class item stops there, lets the sends in flight end and lists again,
so the live one goes next; a start-class enqueue never does.

Builds: design 47 H H-A-291 (1), (2), H-A-290, H-A-275
2026-11-21 18:59:58 +01:00
jschoubben bda61ae64c H-A-290: the builder's publish queue sends live publishes first, in passes, never a withdrawn build
The tool runner's release waited forty minutes behind old versions: every start asked a publish again for every done
build, and each send relisted and reread the whole queue. A publish whose build ended in this run now goes before any
asked again at a start (the class kept on the key's value, a live key of a build before the start made a start key at
the start); a pass lists a holder's keys once and sends them four at a time; a withdrawn or taken-over build is dropped
with its publish item ended at enqueue, at the pass and at the start; a send that returns unsent says why, and every call
it makes honours its one bound; builder_publish_queue reads its states in pages and answers counts per holder and class,
the oldest and newest queue time, a list capped at fifty and one module's items with their class.

Builds: design 47 H H-A-290 (1)-(5), H-A-269, H-A-271, H-A-275
2026-11-21 18:59:58 +01:00
mesh-tools 5547fd028e Merge pull request 'Design 47 H: a pipeline with nothing open ends at once; the end's reads are made once (H-A-288, H-A-289)' (#315) from fix/47-H1-runner-end-when-empty into main 2026-11-21 17:22:44 +00:00
jschoubben d51d389c1b Runner: a pipeline with nothing open ends at once (47-H1-runner-end-when-empty)
main.117 judged its end at 17:45:19 and never wrote it: every mover's widens
was read inside the end's compare-and-set loop, 126 movers each cut on
grants-for, so each try took about eleven minutes and every write was refused
as changed until the restart, whose start pass judged no end.

The reads an end needs are made once, before the compare-and-set, shared by
every mover and every retry; the runner's start pass ends each running
pipeline with nothing open before the queue is placed; every end says its
outcome in the journal.

Builds: design 47 H H-A-288, H-A-289, H-A-223, H-A-243
2026-11-21 18:18:32 +01:00
mesh-tools c6edd5987f Merge pull request 'Design 47 H: a re-pin of the same source keeps a mover in its pipeline (H-A-283..286)' (#314) from fix/47-H1-runner-same-source-repin into main 2026-11-21 17:00:58 +00:00
jschoubben 9a49b0f4f7 Give a kept mover's asks ids of its kept revision and place it from that revision (H-A-286)
Review round 1: a kept mover's ask ids still came from the pipeline's start
time, so a pin-held ask or a composition took the id of an ask the runner
had just dropped for the old fingerprint, and a restart never matched the
steps placed again; and a kept mover placed later read the branch's held
view, so a lagging view gave the new fingerprint the old pins. Every ask id
of a kept mover's steps (build, tests, validate, pin-held asks,
composition, rerun, restart) now mixes its kept revision into the id's
sum, and every placing of a kept mover (at once, later, at a restart, a
rerun) reads its entries at its kept revision by number, waiting while
that revision cannot be read. The test's starter gets a clock that moves.

Builds: design 47 H H-A-286 (amending H-A-284; with H-A-283, H-A-285)
2026-11-21 17:58:07 +01:00
jschoubben 47f81051be Keep a same-source re-pin's mover in its pipeline and build it again there (H-A-283)
A module importing packages its own pipeline releases was re-pinned at
each publish; each re-pin revision of the same source took it out of the
running pipeline, and each newer build withdrew the older reservation, so
nothing ever published. A revision of the same source now moves no mover
out of the open pipeline of that source: the pipeline keeps it at its new
fingerprint, ends every step of it superseded (said at the old
fingerprint, its asks dropped, its runs left) and places them again from
the re-pin revision's entry under new asks, the build first, still naming
the pipeline's revision. The revision the mover is kept at rides in the
record's kept-revisions, beside the movers, where the pin check reads its
entry. A revision whose every mover is kept starts no pipeline; one of a
new source moves movers as before.

Builds: design 47 H H-A-283, H-A-284, H-A-285 (with H-A-223, H-A-244, ADR 0682)
2026-11-21 17:47:54 +01:00
mesh-tools 769d701e2b Merge pull request 'Design 47 H1: a published event reads each reservation once, only the unbuilt ones on a miss (H-A-280)' (#313) from fix/47-H1-builder-published-read-once into main 2026-11-21 15:47:49 +00:00
jschoubben ece9d6b18f Builder: a published reads each reservation once, and only the unbuilt ones on a miss
Live, a published at a version fourteen reservations share cost three seconds:
the fallback by version read every reservation there, and the journal line
read them all again, so the backlog drained at fifty a minute.

The published now hands the reservations it read (each once, a second pass
taking what the first read) to its journal line. The fallback reads the new
index key of the reservations at a version whose build has not recorded every
digest (kept at reserve and where a digest is recorded, written again at the
start), the only ones a published can be kept on; the line counts the rest from
the index by version without reading them. Before that pass the handler says
in progress to the bus.

Builds: design 47 H H-A-280, H-A-271
2026-11-21 16:45:25 +01:00
mesh-tools 93495203b5 Merge pull request 'Design 47 H1: the builder hears a published once by digest; no publish asked again while one is unheard; a held number is never reserved (H-A-269)' (#312) from fix/47-H1-builder-published-once into main 2026-11-21 14:59:17 +00:00
jschoubben 5628ca2919 Builder: a build whose number a registry holds elsewhere is built again, never moved
Every artifact carries its version from its build (a Go module zip's paths, a
program's stamped version, an image's and a bundle's build environment), so
no digest survives a change of number: the move that kept digests would have
published a binary saying 0.1.37 under another number.

The try, on a number a registry holds at another digest, withdraws it on the
reservation (a gap) and raises version-held-elsewhere naming both digests,
then asks the build of the same fingerprint again through the build-again
path of a done key whose version is not released. Its reserve never takes a
withdrawn number again, skips every number a registry holds, and the build
records fresh digests and runs its own publish; the takeover ends the old
number's publish item and bound.

Builds: design 47 H H-A-275, H-A-279, H-A-226
2026-11-21 15:56:04 +01:00
jschoubben 070f60404e Assigner: a passed mover with no version yet holds its tier
The tier progress started at the lowest tier of the versioned movers, so every
lower tier counted as run and a mover whose version came late was wanted after
its consumer. The progress now holds every passed mover, and a tier with one
whose version is not written does not run until it is.

Builds: design 47 H H-A-270, H-A-273, H-A-277 (1)
2026-11-21 15:55:30 +01:00
jschoubben 7f855f0e52 Runner: say the end again only for a passed pipeline, and again on a version heard again
A say that failed after the version was written was lost: the redelivery found
the version held and said nothing. A failed, superseded or cancelled end writes
no want, so it is not said again.

Builds: design 47 H H-A-270 (2), H-A-277 (2), (3)
2026-11-21 15:52:18 +01:00
jschoubben 05c59ae000 Builder: the registry's record ends a publish or moves a number it holds elsewhere
A publish item skipped while the registry held the version would stay skipped
for ever once its published event was lost; and node-tools 0.1.37, held by the
artifact registry at another digest than the build's, was asked again for ever
and never released.

When every missing artifact is held at its version with the built digest the
builder marks it published from the registry's record and says
package-published, as a heard published would; the release follows from the
catalog. Before reserving, the registry seats' versions of the module's
artifacts are read and every number one holds is skipped (version-held-elsewhere,
scope module); a read that fails lets the reserve proceed. A done build whose
number a registry holds at another digest moves to the next free number, its
digests kept, the old number withdrawn as a gap; its old item and bound end and
its publish is asked under the new number. The finding clears at the module's
version-released.

Builds: design 47 H H-A-274, H-A-275, H-A-245, H-A-226
2026-11-21 15:51:21 +01:00
jschoubben 3dfc18023a Assigner: a mover whose version came late joins the tier progress at its tier
The tier progress was written once, from the movers the first end named, so
a mover taken from the end said again was wanted out of tier order: a late
tier-2 consumer and the tier above it were wanted together. It now joins
the progress at its tier, and is wanted at once only when that tier ran.

Builds: design 47 H H-A-270, H-A-273
2026-11-21 15:44:58 +01:00
jschoubben 1489493431 Assigner: say a passed mover with no version yet; one registration-changed handler
The holder skipped such a mover silently, so a passed pipeline wrote no want
and nothing said why; the runner now says the end again once the version is
written, and the holder takes it then. The pipeline ends took registrations
from a second handler that the hub refused at every start (a message has one
taker); they are told by the catalog half's one follower instead.

Builds: design 47 H H-A-270 (1), (3)
2026-11-21 15:41:03 +01:00
jschoubben e1630b57c6 Builder: no publish asked again while its published may be unheard or the registry holds it
The publish item's try asked the registry to publish node-tools 0.1.37 again
every few minutes while the registry had published it and the builder's own
consumer stood thousands of messages behind, adding events to the backlog.
Before each try the builder reads its durable on the events stream (pending
plus unacknowledged): at a hundred or more the try asks nothing. Below it the
registry seats' own record (their verb versions) is read: every missing
artifact held at the version with its built digest asks nothing either. A
skipped try is said in the journal, written again with its pause and spends
no try; a count or record that cannot be read holds no ask.

Builds: design 47 H H-A-269 (2), H-A-272
2026-11-21 15:40:19 +01:00
jschoubben 5c4c4bc821 Builder: a published finds its reservation through an index by digest and by version
The builder's consumer of the registry seats' published stood thousands behind:
each published, and each one that marked nothing, read every reservation.
An index beside the reservations (three-token keys in the same state, which the
reservations' two-token filter never lists) names the reservation keys holding
a built digest and those standing at a version; it is kept at reserve, at a
digest recorded, at release and at drop, and written again once at the start.
A published reads its digest's entry and that reservation; a digest no
reservation holds is judged from its version's entry, never a scan.

The test stores and the tools' read store now read a key filter token by token
as the bus does, which showed the publish queue's resume listing three-token
keys with the two-token filter: it lists them with its own filter now.

Builds: design 47 H H-A-269 (1), H-A-271
2026-11-21 15:37:44 +01:00
jschoubben e927bb8971 Runner: a version written after a pipeline's end says pipeline-ended again
The seat mesh-wants' holder skips a passed mover with no version yet; the
version-released arrives late, so the end it took named none and no want was
written. Saying the same pipeline-ended again, naming the version, lets the
holder take the mover it skipped.

Builds: design 47 H H-A-270 (2)
2026-11-21 15:34:34 +01:00
mesh-tools 599bf62d23 Merge pull request 'Design 47 H1: a module entering the trunk's graph is registered at its take-in; the runner says registration-missing (H-A-262)' (#311) from fix/47-H1-indexer-register-at-take-in into main 2026-11-21 12:22:04 +00:00
jschoubben 0de195c5aa Design 47 H1: test that a module entering the graph watches its siblings' alike branch
Review round 2. The siblings watched main, which is also the default
branch, so no test held the alike rule; they now watch stable and the
entering module is asserted to watch it.

Builds: design 47 H H-A-265, H-A-266
2026-11-21 13:20:54 +01:00
jschoubben 3160bb1fb8 Design 47 H1: registration-missing clears when no running pipeline waits on the registration
Review round 1. A pipeline that ended (failed, cancelled) with a mover
still waiting left the finding for ever. It is now judged at every
pipeline's end and in Waiting: cleared when the registration is held, or
when no running pipeline still has an unplaced mover of the module.

Builds: design 47 H H-A-262, H-A-265
2026-11-21 13:18:41 +01:00
jschoubben 93efda5db3 Design 47 H1: the graph skips a pending register, the seed's left-out, and reads the branch
Review round 1. A module with a register proposal pending is skipped (the
operator's Approve registers it); a module the seed left out keeps
seed-left-out and is not registered; the branch is the first watched
branch the repository's registered modules hold alike, else its default
branch read through the seat git, and a module whose default branch is not
read is skipped and said, registered at the next kept trunk revision. One
listing of the registrations finds the modules with none, so a revision
whose modules are all registered reads no registration.

Builds: design 47 H H-A-262, H-A-263, H-A-264, H-A-265, H-A-266
2026-11-21 13:18:41 +01:00
jschoubben f01731fd4e Design 47 H1: the runner raises registration-missing while a mover waits on its registration
A mover with no registration had its wait said only in the journal. The
runner now raises the finding registration-missing (scope module, id the
module) through its finding writer as it places a pipeline whose mover has
no registration, and clears it when the module's registration arrives or
the registrations held name it.

Builds: design 47 H H-A-262, G A-327, ADR 0666 §2
2026-11-21 13:09:23 +01:00
jschoubben 251745f859 Design 47 H1: the indexer registers a module that enters the trunk's module graph
Four modules added to a repository after the registrations' seed were never
registered, so a pipeline's steps for them waited on a registration nobody
asked. A kept trunk revision of any kind now registers each of its modules
with no registration, before the revision is said, with no ask: origin its
repository, path its manifest's, the first watched branch, the steps its
repository's other modules hold alike (else the seed's) and a per-artifact
status only where every sibling naming that artifact holds it identically,
said registration-changed. The start does the same once for the current
trunk graph. With no registration held the seed stays the only writer; a
module that leaves the graph keeps its registration.

Builds: design 47 H H-A-262, H-A-263, H-A-264, G A-327, ADR 0666 §2
2026-11-21 13:09:23 +01:00
mesh-tools d1ec9d9072 Merge pull request 'Design 47 H1: the assigner's pass never waits on the keeping of revisions; no want before a revision is kept (H-A-259)' (#310) from fix/47-H1-assigner-pass-on-ended into main 2026-11-21 11:40:59 +00:00
jschoubben 14254dd0ba Assigner: no want before a revision is kept; the full-store verdict stays the pass's
Review round 1: the start handed a removal-only keeping to the background
while passes wrote wants with no revision kept, so their wanted was never
said. A pass now writes no want until the first keeping keeps a revision
(that keeping wakes the pass), the start's removal folds into the first
pass's keeping, and the pass judges the store's fill itself, through a
handle of its own, before it writes. The integration bed makes the
revisions' object store, as the grants part does from the manifest.

Builds: design 47 H H-A-259, H-A-261; ADR 0682
2026-11-21 12:40:15 +01:00
jschoubben 1e50642e3c Assigner: the pass never waits on the keeping of revisions (H-A-259)
A pass that kept a fresh assignment graph revision sat six to eight minutes
keeping it and removing the revisions not current, so the wakes of
pipeline-ended and running waited for it. The keeping now runs off the pass
loop, one at a time and folded; the removal takes each entry's module and
fingerprint from the store's listing instead of reading every entry object;
each pass and each keeping says its duration.

Builds: design 47 H H-A-259; ADR 0682
2026-11-21 12:40:15 +01:00
mesh-tools b0082ec04f Merge pull request 'Design 47 H1: every ask the runner makes is bounded; a shared validate ask is never read as one mover's; a moved mover leaves a waiting pipeline (H-A-235)' (#309) from fix/47-H1-runner-asks-bounded into main 2026-11-21 11:02:21 +00:00
jschoubben 6b6e4c81f0 Judge a missed first bound by the first read's own entries (H-A-238)
The start read the second bound with a get, which says not found both
for a key never armed and for one the holder's ask-taken deleted, so
every later start asked an answered step once more. The first read
keeps each key's last entry; a first bound's expiry is taken only when
its second bound left no entry at all, and with both passed only the
second is taken, ending the step without asking it again.

Builds: design 47 H H-A-238 (5)
2026-11-21 12:02:02 +01:00
jschoubben 374d060cc0 Take an ask's bound that expired while the runner was down (H-A-238)
The bounds were watched for updates only, so an expiry marker written
while the runner was down was never heard and that ask had no bound.
At the start each ask key's last entry is read; an expiry marker is
taken then. A running heard before the seat-holders view is read is
heard again after a delay instead of at once.

Builds: design 47 H H-A-238 (5), H-A-243 (1)
2026-11-21 12:02:02 +01:00
jschoubben 1f878eec58 A validate rerun moves every mover's validate and reopens its compositions (H-A-236)
The rerun put only the named mover's validate under the new ask; the
others stayed failed under the old one, so the pipeline failed again
and a second rerun made a second validate ask, breaking the pipeline's
one validate ask. The compositions its failed validate ended not asked
now wait again, asked once validate passes as at the placing.

Builds: design 47 H H-A-51, H-A-236
2026-11-21 12:02:02 +01:00
jschoubben c9515da86f Take a validate end by its ask alone, ending every mover's validate (H-A-252)
The pipeline's one validate ask names no mover, but its end names the
mover whose body the holder took; the runner compared that mover with
the first step carrying the ask and dropped a passed validate, so the
pipeline held its slot (main.88).

Builds: design 47 H H-A-236, H-A-252
2026-11-21 12:02:02 +01:00
jschoubben 5f7137e676 A moved mover leaves an older waiting pipeline whenever a newer one starts (H-A-244)
Only a newer pipeline that waited took movers out of older waiting ones;
one placed at once left them, so main.84 was placed nine hours later
with a mover a newer revision had moved and built a stale fingerprint.

Builds: design 47 H H-A-223, H-A-244 (1)
2026-11-21 12:02:02 +01:00
jschoubben 902947a044 Bound a silent seat's ask once; put it again when its holder starts (H-A-243)
mesh-builds and mesh-wants say nothing before a step's end, so asking
them again at the short bound would double a running build. Their ask
has one bound, ask-silent-bound, and is put again when the node-engine
says the holder running, since the holder takes asks on a plain
subscription and loses those put while it is down. An ask asked again
on a build seat carries a second id derived in the accepted form.

Builds: design 47 H H-A-235, H-A-238, H-A-241, H-A-243
2026-11-21 12:02:02 +01:00
jschoubben b95b3ef989 Bound every ask the runner puts on a seat (H-A-235)
An ask whose holder lost it (the seat mesh-wants' holder restarted) held
its pipeline's turn for nine hours. Every ask but a test run's now arms
a key of the state bounds before it is put; its expiry asks once more,
said in the journal, and the second ends the step could not run with
the finding call-unanswered, so the pipeline ends and its turn frees.

Builds: design 47 H H-A-235, H-A-238 (1)-(5)
2026-11-21 12:02:02 +01:00
jschoubben 0f167db73d Rerun of validate or composition asks the shared ask (H-A-236)
The rerun verb looked a step's ask up by the mover's id, but the validate
ask is one per pipeline and names no mover, so every validate rerun, and
a composition rerun, was refused "placed no ask now".

Builds: design 47 H H-A-236
2026-11-21 12:02:02 +01:00
mesh-tools e5f54c5cdb Merge pull request 'Design 47 H1: the indexer declares the finding kinds it raises; its unanswered calls get a kind of its own (H-A-247)' (#308) from fix/47-H1-indexer-finding-kinds into main 2026-11-21 10:57:52 +00:00
jschoubben bdb4edd820 Design 47 H1: the indexer's retired call-unanswered names scope call
The tool runner's approval findings of call-unanswered are of scope machine;
the indexer's entry now names scope call, so no approval key is cleared even
where an id form would match. The test's negative ids take the approval form.

Builds: design 47 H H-A-249, G §580
2026-11-21 11:50:27 +01:00
jschoubben 31c2c5c7fe Design 47 H1: the indexer retires call-unanswered by the ids it wrote under it
The daemon's call-unanswered keys from before the rename would be seeded and
stated by the tool runner's writer, which owns that kind, and never cleared.
The retired list now names call-unanswered with the indexer's own id forms
(the seed's node-build-<kind>.steps, the floor's
mesh-catalog.versions-floor.<module>, the versions fill's
mesh-delivery-builder.builder_versions), so those keys clear once and the
tool runner's approval findings stay.

Builds: design 47 H H-A-247 (3), H-A-249, G §580
2026-11-21 11:50:27 +01:00
jschoubben ad0052c6f5 Design 47 H1: the indexer owns the SDK parts' kinds, its own unanswered-call kind and a retired list
The daemon's writer is handed to the process reader (event-unhandled) and the
heard writer (family-not-heard), kinds its list lacked; and call-unanswered
belongs to the tool runner's writer over the same state. The daemon's
unanswered calls are now indexer-call-unanswered (same scope and id), its list
holds the SDK parts' kinds, and merge-untaken is retired, so its live key and
condition clear at the next start. The test reads the SDK parts handed the
writer and refuses a retired kind still raised.

Builds: design 47 H H-A-242, H-A-247 (1) (2) (3), H-A-82, G §580
2026-11-21 11:50:27 +01:00
jschoubben aef8632d95 Design 47 H1: the indexer's writer owns the kinds its code raises, held by a test
The daemon's writer owned every kind while the tool runner's writer shares the
state `findings`; under G §580 each bundle states only its own kinds. The
daemon's writer is now made with FindingKinds, the ten kinds its code raises,
and a unit test reads the daemon's code for every kind it gives the writer and
fails on one the list does not declare.

Builds: design 47 H H-A-240, H-A-242 (2), H-A-233, G §580
2026-11-21 11:50:27 +01:00
mesh-tools dedcc3ead7 Merge pull request 'Design 47 H1: a done build whose series moved says stale, not 'no version is reserved' (H-A-244)' (#307) from fix/47-H1-builder-stale-and-tag into main 2026-11-21 10:37:56 +00:00
jschoubben a40bbec44a Builder: a done build whose series was taken over fails stale, naming the newer build
A pipeline placed long after its take-in found its old build done but holding no
number, and was told to reserve one; the series had moved to a newer fingerprint.
The step now says it is stale and names that fingerprint and its version.

Builds: design 47 H H-A-244 (2), H-A-226
2026-11-21 11:34:25 +01:00
mesh-tools fe6c5961ae Merge pull request 'Design 47 H1: a repository's packages are those in the merge's tree (H-A-232)' (#306) from fix/47-H1-indexer-gone-packages into main 2026-11-21 02:09:12 +00:00
jschoubben 588a6ff8d5 Design 47 H1: only the trunk's merge drops a gone package; a commit's tree tells an all-gone repository (H-A-232, H-A-233)
Review round 1. A branch's take-in runs through the dry indexer, which
shares the live packages state, so a branch cut before main added a
module would have deleted main's key: publish drops a kept key only on
the real indexer at the trunk's merge. And a repository whose every
asked directory is gone (one key, or all gone) returned the whole error
and raised packages-not-published at every take-in: the seat's trees of
the commit now tell a gone directory from a commit with no tree.

Builds: design 47 H H-A-232, H-A-233, H-A-234; issue 1585
2026-11-21 03:07:02 +01:00
jschoubben ced27928d9 Design 47 H1: the indexer publishes a repository's packages in the merge's tree (H-A-232, H-A-233, H-A-234)
A Go module mesh-catalog removed stayed in the packages state, so every
publish of mesh-catalog asked the forge for its directory, the seat git
answered not-found, and the one-directory fallback (issue 1585) ran only
on an answer without the directory: nothing of the repository was
published and its packages' digests froze unsaid.

filesVia takes the seat's not-found as a failure of the tree, so the
fallback runs; publish drops the kept key of a package whose directory
the trunk's merge no longer holds, said in the journal; a listing that
fails for another reason raises the finding packages-not-published
(scope merge, id the repository), cleared at the next publish that lists.

Builds: design 47 H H-A-232, H-A-233, H-A-234; issue 1585
2026-11-21 02:54:58 +01:00
mesh-tools 2cb6971194 Merge pull request 'Design 47 H1: a receiver reads its store's fill once per transfer (H-A-227, H-A-228)' (#305) from fix/47-H1-receiver-fill-once into main 2026-11-21 01:12:32 +00:00
jschoubben 6a730c33e6 H-A-227, H-A-228: the receiver reads its objects' fill once per transfer
A fill read on every chunk made the tool runner list the registry's
incoming store per chunk. The kept transfer now holds the fill read at its
open and the bytes taken since; each chunk tells their sum, written with
the put already made per chunk, and the store is read again only at the
finish, a drop, or when a part's chunks are dropped.

Builds: design 47 H H-A-227, H-A-228
2026-11-21 02:11:39 +01:00
mesh-tools d1aab1d08d Merge pull request 'Design 47 H1: the validate and composition run asks carry their entry's pins (H-A-203)' (#304) from fix/47-H1-runner-validate-pins into main 2026-11-21 01:09:03 +00:00
jschoubben c6b4b6054b Design 47 H1: the validator's and the composer's run asks are built against their entry's pins (H-A-203)
The validate step's run ask built the manifest validator from the indexer's
tree with no pins, so the Go build module refused it for a requirement of
another repository (main.74's feh validate, main.67's mesh-sdk validate);
the composition step's run ask built the composer from the node-engine's
tree the same way. The seat mesh-wants' holder builds both asks: each now
carries the pins of the entry its program is built from, the indexer's
entry at the step's own revision and the node-engine entry chosen per
machine, those with a version, in the form the entry keeps and the
builder sends.

Builds: design 47 H H-A-203, H-A-192, H-A-205
2026-11-21 02:03:18 +01:00
mesh-tools 4df45a3793 Merge pull request 'Design 47 H1: the builder keeps a reservation for its fingerprint and withdraws a taken-over build (H-A-225, H-A-226)' (#303) from fix/47-H1-builder-reservation-kept into main 2026-11-21 00:41:48 +00:00
jschoubben e2e13ddd29 Drop withdrawn versions the catalog released past; a dropped number stays a gap (H-A-226)
The series key's Withdrawn grew at every take-over and was never pruned. At each write it now keeps only the
withdrawn versions above the catalog's highest released (those at or below it are refused by the plain rule anyway),
carried across a renumbering of the same fingerprint too; a dropped number is never reused (H-A-226 withdraws
H-A-225's freeing). The comment of the rebuild's reservation now states A-490b as H-A-225 amends it.

Builds: design 47 H H-A-225, H-A-226
2026-11-21 01:40:18 +01:00
jschoubben dcf5b7fa8f Keep a reservation for its fingerprint until released; withdraw a taken-over build (H-A-225)
After a builder restart, the run already building a module carried its reserved number while a re-run of the same
fingerprint reserved the next, so its publish was refused "has no version reserved or released" (main.61: the builder
0.1.111 vs 0.1.112, mesh-grants 0.1.52 vs 0.1.54, and others reserved twice within seconds). A take-over by another
fingerprint dropped the older reservation but let the older build run on and publish a number that no longer existed.

Reserve now answers the standing reservation of the same fingerprint while it is unreleased and above the catalog's
highest, a build again or a re-run alike (A-490b amended so). A take-over keeps the dropped version in Withdrawn and
withdraws the older build (ended superseded, ADR 0664 §4); a late publish of it is refused as withdrawn, naming the
fingerprint that took it over.

Builds: design 47 H H-A-225; G A-490b as amended; ADR 0664 §4
2026-11-21 01:36:32 +01:00
mesh-tools 1fe6ade359 Merge pull request 'Design 47 H1: a same-repository module named only by a replace is a requirement of the module graph (H-A-224)' (#302) from fix/47-H1-indexer-replace-required into main 2026-11-21 00:30:50 +00:00
jschoubben 9e09767a4b Indexer: a same-repository module named only by a replace is a requirement
The watchman's go.mod names buildrun in a replace directive with no require
line, and the walk of the module graph followed require lines only, so
buildrun's requirement of the module assigner's client was never pinned and
every test step of the watchman failed "no pin". The walk now takes the
same-repository modules a go.mod replaces by a directory as required, with
the same same-repository test, so their go.mod files are read and their
other-repository requirements pinned, transitively.

Builds: design 47 H-A-224, H-A-201
2026-11-21 01:26:29 +01:00
mesh-tools 59443ab3f7 Merge pull request 'Design 47 H1: a mover a newer revision moved leaves a running pipeline too (H-A-223)' (#301) from fix/47-H1-runner-moved-leaves into main 2026-11-21 00:24:57 +00:00
mesh-tools 92d0ab8602 Merge pull request 'Design 47 H1: the indexer's test fakes answer what the SDK's pull guard reads (H-A-196)' (#300) from fix/47-H1-indexer-fake-consumer into main 2026-11-21 00:24:55 +00:00
jschoubben 3a31331ad3 Design 47 H1: a mover leaving a running pipeline has its build-node asks dropped (H-A-223)
A moved mover's steps ended superseded, but their asks kept running on the
build nodes. Each such step holding its own ask on a node-build seat, one
reading no shared run, now has the seat's drop asked with the newer
pipeline's why, through the drop the runner already bounds and keeps. The
seat mesh-builds serves no drop, so a build ask there runs to its end,
which the runner ignores: the step is no longer open.

Builds: design 47 H H-A-223
2026-11-21 01:22:10 +01:00
jschoubben d1581666d2 Design 47 H1: the start of a newer pipeline is held to take moved movers out, and reads its branch alone (H-A-223)
No test failed when Start stopped calling the supersede of running
pipelines, the path the live runner takes. Two rows now start a newer
pipeline through Start, a take-in's and a release revision's, with the
supersede wired to a hearer over the same store, and hold that the older
running pipeline's moved mover left it. The supersede lists only the keys
of the newer pipeline's branch instead of every pipeline's.

Builds: design 47 H H-A-223
2026-11-21 01:18:55 +01:00
jschoubben d4d7895392 Indexer: the branch consumer fake answers its CachedInfo and ends when stopped
With the SDK's guard of one pull per durable (pullOnce reads the consumer's
CachedInfo and releases on the consume's Closed), the fake of a branch's
durable embedded a nil consumer and a nil consume context, so
TestABranchDurableNotThereIsMadeAndHeard panicked. The fake now answers a
ConsumerInfo with its stream, name and a created time of its own, and its
consume context closes when stopped. No other fake in mesh-delivery embeds
jetstream.Consumer; the assigner's, runner's, builder's, watchman's and
grants' unit suites pass with the new SDK unchanged.

Builds: design 47 H-A-196, H §774
2026-11-21 01:18:22 +01:00
mesh-tools d6c209a10c Merge pull request 'Design 47 H1: the catalog seat's revision verb answers the store; the builder's picture holds a kept revision by number (H-A-222)' (#299) from fix/47-H1-revision-verb-store into main 2026-11-21 00:14:44 +00:00
mesh-tools 51ac838732 Merge pull request 'Design 47 H1: the indexer decodes every hand tool's ask (H-A-208, H-A-210)' (#298) from fix/47-H1-indexer-again-decode into main 2026-11-21 00:14:40 +00:00
jschoubben 06a52a10e0 Design 47 H1: a moved mover leaves a running pipeline too (H-A-223)
A release re-pinned node-tools while main.54 still built it at its old
fingerprint; the build failed and failed the pipeline for its other 119
movers, because supersession took movers out of waiting pipelines only.
Every start of a newer revision's pipeline now also walks the older running
pipelines of its branch: each mover whose fingerprint it moved leaves, its
open steps ending superseded with a why naming the newer pipeline, a step
reading a test run leaving it as a cancel's does, and the mover kept in the
pipeline's superseded. The end judgement counts a left mover's steps as
neither holding nor failed, so the pipeline ends by its other movers alone;
one every mover left ends superseded. A run on request's pipeline is never
touched.

Builds: design 47 H H-A-223, H-A-163, H-A-213
2026-11-21 01:13:57 +01:00
jschoubben 773e2e33a1 Builder: a kept revision of another source or fingerprint fails the ask at once
Review round 1: an ask names the revision and the source of one revision, so a
kept revision read by number whose source differs from the ask's is not the
ask's; the check is restored, naming both sources. And a kept revision naming
another source or other fingerprints is a mismatch no wait can mend: the step
fails at once, loud, instead of waiting out revision-wait-minutes; only a
revision the catalog does not answer is waited for.

Builds: design 47 H-A-222 (2), H-A-218
2026-11-21 01:10:37 +01:00
jschoubben d817d85fca Builder: an ask naming a revision is held by that revision read by number
An ask of the very source the picture holds, whose entries the picture no
longer names (a re-pin keeps a later revision of the same source), waited for
the picture and failed past its bound, because the kept revision was read by
number only for a source below the picture's. Now an ask naming a revision is
read by number whenever the picture does not name its entries, and is built
when the catalog keeps it and it names every fingerprint asked, whatever the
source says; the source is compared only for an ask naming no revision.

Builds: design 47 H-A-222 (2), H-A-205, H-A-213
2026-11-21 01:07:18 +01:00
jschoubben 6d5000871d Indexer: the revision verb answers the newest kept revision from the store
The tools bundle answered the catalog seat's revision verb from its view of the
trunk in memory, which ran one or more revisions behind what the indexer kept
until it heard the event, so the runner and the builder waited on revisions the
bus held all along. The verb now reads which revision is newest from the store
at the time of the ask (a listing and one object) and takes the view's entries
only when the view holds that very revision.

Builds: design 47 H-A-222 (1), H-A-205, H-A-213
2026-11-21 01:05:55 +01:00
jschoubben 5c7648744d Indexer: read a takeins value's hand acts from TakeInAsk's tags, not a hand-kept list
indexer_take_in_again wrote TakeInAsk{Again} and DecodeTakeIn refused it: its
hand-kept list of act fields lacked Again, so the handler never reached its
Again branch. Every field of TakeInAsk now says by its tag takein whether it is
an act, an argument or of the ask; DecodeTakeIn reads the acts from the tags,
and a table test builds every hand tool's value by its own Run path, decodes it
and acts on it through takenIn, and refuses a field left unclassed.

Builds: design 47 H §774, H-A-208, H-A-210
2026-11-21 01:03:32 +01:00
mesh-tools 8802f16019 Merge pull request 'Design 47 H1: the pin rule whole: revisions numbered by the indexer with their call, a re-pin or recompute keeps a revision, pins carried in every ask, pipelines keyed by revision (H-A-203 to H-A-221)' (#297) from fix/47-H1-pin-kind-join into main 2026-11-20 23:49:57 +00:00
jschoubben 6087306dfd Design 47 H1: the pipelines store guards its shared maps, so the runner's start no longer crashes (H-A-187)
The runner crashed at every start on a live bus with "concurrent map
writes" in MoverStore.Get: the waiting pipelines of each branch are placed
from goroutines of their own, and the store's last reads and inline marks
were written under each pipeline's own lock alone. The store's mutex now
guards the lock table, the last reads and the inline marks; behaviour is
unchanged. The run test starts the runner over six kept pipelines in the
old form, one of 437 steps, so the start path runs under the race detector.

Builds: design 47 H H-A-187, H §774
2026-11-21 00:43:16 +01:00
jschoubben 667aa87611 Join fix/47-H1-builder-revision-picture 2026-11-21 00:27:10 +01:00
jschoubben 0f2fd1a171 Join fix/47-H1-runner-published-revision
# Conflicts:
#	modules/mesh-delivery-indexer/internal/index/catalog_revisions.go
#	modules/mesh-delivery-pipeline/internal/pipeline/start.go
2026-11-21 00:27:04 +01:00
jschoubben e1ce5cc8ed Join fix/47-H1-indexer-take-in-again 2026-11-21 00:26:46 +01:00
jschoubben 7794ee9d2d Join fix/47-H1-sdk-empty-pin 2026-11-21 00:26:46 +01:00
jschoubben 396893dcac Design 47 H1: the pipeline-runner seat names a pipeline's key and its subjects by revision
The seat's key form of a pipeline is <branch>.<revision>, and its four per-pipeline
subjects are said on <branch>.<revision> (the definition and generated contracts the
same as the runner branch's). The indexer pins a revision for the pipeline keyed
PipelinesByBranchRevisionKey, and this branch's runner copy follows the renamed
generated functions; the wire form is unchanged.

Builds: design 47 H H-A-213 (4), H-A-219, H-A-221
2026-11-21 00:25:58 +01:00
jschoubben 626a6fb358 Design 47 H1: the pipeline-runner seat names a pipeline's key and its subjects by revision
A pipeline is keyed by its catalog revision's number, so the seat's key form is
<branch>.<revision> (the generated PipelinesByBranchRevisionKey and its siblings; the
fixtures follow), and pipeline-started, pipeline-ended, wait-held and wait-ended are
said on <branch>.<revision>, carrying the same number as the key; every reader takes
the body. The client's SourceSubject is RevisionSubject. The published key form, under
which pipelines were kept before, stays.

Builds: design 47 H H-A-213 (4), H-A-219, H-A-221
2026-11-21 00:25:08 +01:00
jschoubben 20ee1cae7b Merge the runner branch into the builder branch, so both merge into main as one
The builder's step end reports the pins it built with (H-A-207, from the runner
branch) and names the run's catalog revision on its origin (H-A-218, H-A-220); step.go
keeps both. The seat mesh-builds carries packages on step-ended and revision on
package-published once each; seatgen -check is clean.

Builds: design 47 H H-A-207, H-A-218, H-A-220
2026-11-21 00:22:19 +01:00
jschoubben 671dc5a963 Design 47 H1 (5c): the runner takes a publish into the pipeline of the revision it names
One source now has several catalog revisions, so the publishing pipeline is found by
the branch and revision the package-published names. A publish naming no revision,
from a reservation made before the field, goes to its source's lowest-numbered
revision, the take-in's. The seat mesh-builds' package-published gains its optional
revision here too, identical to the builder branch's, so this branch compiles alone.

Builds: design 47 H H-A-218, H-A-220
2026-11-21 00:17:55 +01:00
jschoubben 3f62410c22 Design 47 H1 (5c): a package-published names the catalog revision its build was made from
One source now has several catalog revisions, so a publish naming branch and source
alone does not say which pipeline published it. The seat mesh-builds'
package-published gains an optional revision (seatgen regenerated). The version
reserved for a build keeps the catalog revision number: from the picture's half when
the picture starts the build (the same revision its source comes from), from the step
ask's run when the ask reaches the build first. Its package-published says it. A
reservation from before the field says none.

Builds: design 47 H H-A-218, H-A-220
2026-11-21 00:17:17 +01:00
jschoubben 4af1ba99cf Design 47 H1 (5a): the runner's integration tests key a pipeline by its catalog revision
The queue's and the test runs' integration tests took several sources in at one
catalog revision, which now are one key. Each take-in has its own revision; the
test runs' test also checks that a test ask names revision and source. A replaced
reader of another pipeline's run stays the unit tests' (one revision is one pipeline).

Builds: design 47 H H-A-213 (4), H-A-219
2026-11-21 00:12:36 +01:00
jschoubben 91b5e8d086 Design 47 H1 (5b): a release, take-in again or recompute revision starts one pipeline, read by its number
A re-pin on a module's release, a take-in again and a recompute that moves a
fingerprint each keep a catalog revision of their own. The runner hears a trunk
catalog-revision of those kinds, reads that revision by its number through the catalog
seat's revision verb, and starts one pipeline keyed <branch>.<revision> with the
revision's movers. A package-published no longer starts per-artifact pipelines: it
only places the movers waiting for it. A branch's newest pipeline for a mover is the
one of the highest revision number.

Builds: design 47 H H-A-212, H-A-213 (2) and (4), H-A-217
2026-11-21 00:07:55 +01:00
jschoubben 189d75ad40 Design 47 H1 (5a): a pipeline is keyed by its catalog revision, and every step ask names revision and source
One source now has several catalog revisions, so a pipeline keyed by its source could
not tell them apart. A pipeline is keyed <branch>.<revision>; one of a source (a
publish's, a version-released's) is found by the source it names, never by its key, so
pipelines kept under their source are read as they are. The Go, Node and image step
asks name the catalog revision in revision and the gate's source in a new optional
source (the build-step part of the seats node-build-go, node-build-node and
node-build-image, seatgen regenerated).

Builds: design 47 H H-A-211, H-A-213 (4), H-A-219
2026-11-21 00:02:48 +01:00
jschoubben 595510ef38 Design 47 H1 (9): a recompute that moves a fingerprint keeps a revision of kind recompute
Every whole recompute of the modules state (a toolchain reported, the toolchains read, the assignments of a build module, the indexer's start, a hand act) moved fingerprints with no kept catalog revision. It now runs as a re-pin does: when at least one fingerprint moved against the trunk's newest revision, it keeps the trunk's next revision of the same source, its movers the moved modules, its call-kind recompute (the seat mesh-catalog's enumeration gains it, seatgen regenerated) and its call naming the reason; one that moves none keeps nothing.

Builds: design 47 H H-A-211, H-A-213 (2), H-A-217
2026-11-20 23:50:50 +01:00
jschoubben 04f54d7773 Design 47 H1 (7): a registry's published recomputes no module
The indexer kept a registry's published in its series and then recomputed every module, moving fingerprints with no kept catalog revision beside the re-pin a release's package-published starts. It keeps the version in its series and recomputes nothing: a fingerprint moves only with a kept revision, one per module release, kept by the re-pin. The seat mesh-wants' pipeline-wanted subject names its last token revision, the number of the runner's key (its form unchanged).

Builds: design 47 H H-A-211, H-A-213 (2), H-A-213 (4) (the subject's token), H-pins-spec-and-gaps leftover L3
2026-11-20 23:48:08 +01:00
jschoubben 07dc14bf53 Design 47 H1 (6): pipeline-wanted names the pipeline's revision, and the indexer frees that revision's pins
The seat mesh-wants' pipeline-wanted gains revision, the pipeline's catalog revision number (seatgen regenerated, additive). The assigner keeps the source the pipeline-ended names in its tier progress and says it beside the revision, the number of the pipeline's key; a progress kept before the field says the key's number as both. The indexer frees the pins of the revision the event names, not of another revision of the same source, and for an event naming none takes the source's lowest-numbered revision, the take-in's.

Builds: design 47 H H-A-213 (4), H-A-214, H-A-216
2026-11-20 23:46:25 +01:00
jschoubben 9b3a728f9e Design 47 H1 (8): a catalog revision's call names its kind, one of three constants
The seat mesh-catalog's CatalogRevision and catalog-revision gain call-kind, an enumeration the seat's schema validates (take-in, release, take-in-again), with module and version for a release and repository for a take-in again, beside call, the words for a person (regenerated by seatgen, additive). The indexer's three writers set them: a take-in's from the gate's call, a re-pin's on a module's release, a take-in again's; no reader parses the words.

Builds: design 47 H H-A-213 (3), H-A-214, H-A-215
2026-11-20 23:43:33 +01:00
jschoubben 83e4470757 Design 47 H1 (1), review round 1: a source answers its take-in's revision
The revision verb's source input, and the pipeline-wanted that frees pins by it, answer the lowest-numbered revision of a source (the take-in's), never a later re-pin's of the same source. TestIndexerWhole asks the exact first number: the bed seeds main.1 of source 0, so source 10's is 2 (no source is kept twice).

Builds: design 47 H-A-213 (1), (4), H-A-211
2026-11-20 23:39:53 +01:00
jschoubben 1b1fd9a711 Design 47 H1 (2): a take-in again keeps the trunk's next catalog revision of the same source
The take-in again keeps what it recomputed as a re-pin does: the trunk's next revision of the newest's source, its call 'take-in again of <repository>', its movers every module whose fingerprint moved, pinned for its pipeline, said as catalog-revision.

Builds: design 47 H-A-208, H-A-210 as H-A-211 and H-A-212 amend it, H-A-213 (1), (3)
2026-11-20 23:36:39 +01:00
jschoubben 47ea130332 Design 47 H1 (1): a release re-pin keeps the next catalog revision of the same source on every watched branch
A branch's revision number is the indexer's own count (the newest + 1); the gate's source is the revision's field source, which the take-in's dedupe and source-to-take read. A catalog revision carries its call (the seat mesh-catalog's CatalogRevision and catalog-revision gain call, regenerated by seatgen). A re-pin on a module's release runs on every watched branch holding a module that names its package (the first on the modules state, another on its newest revision's picture), and keeps, where a fingerprint moved, the branch's next revision of the same source with the call 'release of <module> <version>' and the moved modules as its movers, pinned for the release's pipeline, and says catalog-revision; no take-in.taken.

Builds: design 47 H S11, S12, S13, S14 (H-pins-spec-and-gaps item 1), H-A-211, H-A-212, H-A-213 (1)-(4: the pin of every revision a pipeline runs on), H-A-147
2026-11-20 23:36:39 +01:00
jschoubben 52f7a5b6f6 Design 47 H1 (4): a candidate's entry may name a package with no version yet
An entry names an unpublished package with an empty version, never left out, so a run on request's candidate checks its packages as an entry's (CheckEntry), not as an ask's. Built against the SDK head aee7e4c2 (fix/47-H1-sdk-empty-pin), which goes in the same merge call.

Builds: design 47 H S8 (H-pins-spec-and-gaps item 4, L10), H-A-204
2026-11-20 23:25:24 +01:00
jschoubben aee7e4c26c mesh-delivery-sdk: an entry's packages may name an empty version (H item 4, the SDK's half)
The indexer names a package of another repository with no version published yet by an empty
version, which waits for its publish; PackageVersions.Check refused it, so a run on request of such a
module failed its candidate check. CheckEntry is the entry form, allowing an empty version, while
Check (an ask's pins) still refuses one.

Builds: design 47 H S8, S9, L10 (H-pins-spec-and-gaps section 8 item 4); H-A-204, H-A-165
2026-11-20 23:24:16 +01:00
jschoubben 64d5490ea2 Design 47 H1 (3): a publish whose recompute fails is not acknowledged
The registry's published is offered again when the recompute of its users fails, as a failed series write already was.

Builds: design 47 H S15 (H-pins-spec-and-gaps item 3), H-A-167
2026-11-20 23:21:23 +01:00
jschoubben 7199824e9d Design 47 H1: indexer_take_in_again re-reads a repository at its kept merge
A repository with no merge since the walk of the module graph keeps its
modules' direct requirements only, and no tool took it in again. The tool
asks the indexer, through the state takeins, to read the repository's trees
at the merge its taken key keeps and apply them as a take-in does, whose
recompute of the modules state is the one a publish re-pin runs; kept
requirements and pins gain the transitive packages. An unknown repository,
or one never taken in, is refused in the answer and as the tool's error.
It keeps no catalog revision yet: H-A-211's revision follows with the
re-pin's.

Builds: design 47 H H-A-208, H-A-210, H-A-201 (hq a7b876c1, d7d18ef0)
2026-11-20 23:16:25 +01:00
jschoubben c418f49038 Design 47 H1: held test steps are asked from the pipeline's own catalog revision (H-A-205, H-A-207)
The runner built the asks of the steps that waited for their pins from the
branch's newest catalog half, so a newer revision that moved the module
changed what a passed build's tests fetched. The entry is now read at the
pipeline's own revision through the runner's revision reader, which keeps
what it read; a revision that cannot be read, or whose entry is of another
fingerprint than the mover's, ends the held steps could not run, naming
why.

Builds: design 47 H H-A-205, H-A-207, H-A-203
2026-11-20 23:13:47 +01:00
jschoubben e29aa8aca9 Design 47 H1: a done build key keeps the pins it was built with, and its step's end reports those (H-A-207)
A build step whose key was done before reported the pins it resolved at
that moment, so a publish since would have the runner ask the waiting
test steps against a version the build was never built with. The done
key's record keeps the versions its Go ask was built with, beside its
digests, and the step's end reports the record's; a done key keeping none
reports none, so the runner ends those steps could not run, loud.

Builds: design 47 H H-A-207, H-A-203
2026-11-20 23:12:29 +01:00
jschoubben 64cba95a10 Design 47 H1: a held test step is asked with the pins its build passed with (H-A-207)
When the build of an entry with an empty pin passed, its held lint, unit
and integration steps had no pin to run with and nothing ended them, so a
pipeline stood running and, one pipeline at a time, the queue stopped. The
runner reads the pins the build's end names and, when the build passed,
asks each held step with them, its fetch the entry's as placed; a passed
build whose end names no pins ends the held steps could not run, naming
why, as does an artifact the branch's half no longer names.

Builds: design 47 H H-A-207, H-A-206, H-A-203
2026-11-20 23:07:33 +01:00
jschoubben cb26645614 Design 47 H1: the build step's end reports the pins it was built with (H-A-207)
A test step held for an entry's empty pin had nothing to run with once the
build passed: the builder took the pin from the registry and kept it to
itself. The seat mesh-builds' step end gains packages, and the builder sets
it from the pins each entry was built with, the registry's included, so the
runner asks the held steps with what the build was built against. The
seat's definition changes: its Go and TypeScript contracts are generated
again.

Builds: design 47 H H-A-207
2026-11-20 23:05:08 +01:00
jschoubben b0d2d22002 Design 47 H1: indexer_entry reads one entry's pins and paths at a revision
A reader twice could not read one entry's pins because the whole revision
(1.3 MB) exceeds what the bus carries; the tool answers one module's
packages, paths per artifact, fingerprint and manifest digest, at the
newest trunk revision (read as entryOf reads it) or at a given one from
its kept list and that one entry object.

Builds: design 47 H H-A-204 (hq f977c0e2); tools-are-how-a-module-is-spoken-to
2026-11-20 23:04:07 +01:00
jschoubben 014f7b7c2f Reserve the version of an ask admitted by its kept revision (H-A-205)
An ask of an older kept revision was admitted, but after a builder restart its fingerprint had never been heard on
the branch, so its build neither reserved a version nor was checked against one and passed silently. Each asked
fingerprint is now recorded as the branch's (its source revision, and first as the module's registration says),
without moving what the picture heard, so the newer fingerprint's build is not superseded.

Builds: design 47 H H-A-205, H-A-155
2026-11-20 23:03:45 +01:00
jschoubben 0fcc614e25 Build an ask of an older kept revision by reading it by number, never waiting (H-A-205)
Two pipelines of consecutive revisions ran at once (main.45, 22:5x CET): the picture held source revision 46, whose
entries had moved on, so the older pipeline's builds waited for a picture that only moves forward and failed "revision
45 of main not in the builder's picture within 2m0s". An ask of a source revision below the newest the picture holds
now reads its catalog revision by number through the catalog seat's verb revision (kept while its pipeline runs,
H-A-147) and is built when that revision is of its source and names every entry it asks; only a revision above the
newest is waited for (H-A-155).

Builds: design 47 H H-A-205, H-A-147, H-A-155
2026-11-20 22:59:31 +01:00
jschoubben e3fed77515 Design 47 H1: a Go step waits for its entry's pins as the build does (H-A-206)
An entry may name a package with no version yet, and the runner cannot pin
it from a publish it does not hear, so a step asked then is refused by the
Go build module. The placing now asks a Go artifact's lint, unit and
integration steps only when every pin of the entry has a version; until
then each stands waiting, its why "waits on the publish of <path>" as the
build's wait reads, said in the journal and read by show. When the mover's
build ends without passing, the held steps end as it ended; the publish
re-pins the entry and moves the mover, whose pipeline runs them. A held
step still counts in the judgement of a seat with no holder.

Builds: design 47 H H-A-206, H-A-203, H-A-165
2026-11-20 22:58:30 +01:00
jschoubben 94202fb651 Design 47 H1: a release re-pins every entry naming its package
A release re-pinned only the entries whose pins already named one of its
packages, so an entry whose module did not change and whose pins left the
package out was never re-pinned. Every kept entry whose pins or kept
requirements name a package of the released module is now re-pinned, of
any repository and changed or not; its fingerprint moves with the pin.

Builds: design 47 H H-A-204, H-A-165, H-A-167, H-A-201
2026-11-20 22:58:06 +01:00
jschoubben 0418a2b94b Design 47 H1: an entry's packages never leave out a requirement
Build asks were refused for a requirement with no pin: the import form's
versions name only what the last build imported, and the version line
leaves out a package none publishes, so the pins kept only those. The pins
now name every other-repository package of the module's go.mod graph (its
kept packages), at the newest published version of its accepted series, or
with no version while none is published, so the builder waits for it.

Builds: design 47 H H-A-204, H-A-201, H-A-165, H-A-167
2026-11-20 22:57:26 +01:00
jschoubben a926a40eed Design 47 H1: every step ask fetches with the entry's pins, as the build does (H-A-203)
The runner's lint, unit and integration asks carried no pins, only the
build ask did, so the Go build module, which refuses a requirement of
another repository with no pin, could not run twelve test steps of the
contracts mover (main.45). stepAsk now puts the entry's packages into the
fetch in the form the entry keeps and the builder sends, so a test runs
against what the build was built against; a package the entry names with
no pin yet is left out.

Builds: design 47 H H-A-203, H-A-192, H-A-183
2026-11-20 22:55:36 +01:00
mesh-tools b9cc97470b Merge pull request 'Design 47 H1: the entry pins every requirement of the module graph; same-repository directories move the fingerprint (H-A-201, H-A-202)' (#296) from fix/47-H1-package-tree-paths into main 2026-11-20 21:37:24 +00:00
mesh-tools ae91f91e88 Merge pull request 'Design 47 H1: the catalog seat's hand-written digest helpers live in its client (H-A-200)' (#295) from fix/47-H1-contracts-steps into main 2026-11-20 21:37:22 +00:00
jschoubben 4664eb1b00 Design 47 H1: the entry pins every requirement of the module graph
The Go build module borrowed a sibling's version for a mesh package the
entry did not pin (a transitive requirement), and given no pin it now
refuses. The indexer now pins, in the entry's packages, every mesh package
of another repository that the go.mod of the module's directory, of each
Go package artifact's directory and of every same-repository module they
require transitively names. A module of the module's own repository is
never pinned, whatever a build reported: it is built from the tree.

Builds: design 47 H H-A-201, H-A-183, H-A-157, H-A-202
2026-11-20 22:30:45 +01:00
jschoubben d9a3458927 Design 47 H1: a Go build's same-repository modules move its fingerprint
A Go build resolves the same-repository modules its go.mod files require at
the zero version, transitively, from the fetched tree; a change in one of
them must move the fingerprint, whatever the module's form. The indexer
walks the go.mod graph of the module's directory and its Go package
artifacts at the take-in and appends a line per derived directory and its
git object to the tree input; the entry's paths keep the manifest's form,
and the Go build module derives the same directories itself.

Builds: design 47 H H-A-202, H-A-172, H-A-157, H-A-198
2026-11-20 22:29:15 +01:00
jschoubben b058389d46 Contracts: the catalog seat's manifest-digest helpers move to its client, out of the generated root (H-A-200)
The seat generator's check failed every unit step of the contracts mover (pipeline main.43): manifestdigest.go was
written by hand under go/seats/meshcatalog (598125a1), a generated root every file of which is the generator's. The two
helpers move to the seat's hand-written client meshcatalogclient and their callers in the builder and the indexer
follow; the generator then writes the contract as the module holds it. steprun's generator test now also holds this
repository's own contracts module in step under both roots.

Builds: design 47 G §370, G §578, H §774, H-A-200 (ADR 0608 §5)
2026-11-20 22:18:00 +01:00
jschoubben 6c65e82926 Design 47 H1: a step's named path may leave the module's directory, never the repository
A package artifact's tree names same-repository siblings its go.mod requires
as "../<module>/<dir>"; the fetch request's check and the narrowing refused
them as leaving the module. They are now accepted when their join with the
module's directory stays inside the repository, narrowed from the root, and
refused when they leave the repository.

Builds: design 47 H H-A-198, H-A-199, H-A-157, H-A-172
2026-11-20 22:14:53 +01:00
mesh-tools d40f314e52 Merge pull request 'Design 47 H1: the grants holder keeps the catalog revisions it read and learns the newest from the event (H-A-193, H-A-195)' (#294) from fix/47-H1-grants-for-cache into main 2026-11-20 20:56:03 +00:00
mesh-tools fc85f7b936 Merge pull request 'Design 47 H1: the assigner's test helper holds its map writes under a lock (H §774)' (#293) from fix/47-H1-assigner-test-race into main 2026-11-20 20:52:56 +00:00
mesh-tools 37a8f7a83e Merge pull request 'Design 47 H1: a pipeline's steps and unlogged entries live under one key per mover (H-A-187, H-A-189, H-A-190, H-A-191)' (#292) from fix/47-H1-runner-steps-per-mover into main 2026-11-20 20:52:51 +00:00
mesh-tools 9ef830d224 Merge pull request 'Design 47 H1: the builder fetches a module whole and never computes a pin (H-A-186, H-A-192, H-A-194)' (#291) from 47-H1-builder-program-paths into main 2026-11-20 20:52:45 +00:00
jschoubben 120a0554d6 mesh-grants: grants-for keeps a bounded cache of the followed branches
The kept catalog revisions had no design line and their bound stood in
the code. They are now bounded per branch by the module's setting
grants-for-revisions-per-branch (default 4, oldest dropped, a run's
candidate counted within its branch's), read at the start from the file
the manifest writes, and kept only for the watched branches the part's
branch follower follows: a branch that leaves them is freed at the next
grants-for or catalog-revision event. A kept revision is a cache of the
catalog seat's own truth, never a state of the mesh.

Builds: design 47 G §441, §401; H H-A-195, H-A-193
2026-11-20 21:51:43 +01:00
jschoubben d8a900dac0 Read what the registry seat holds before a build waits for an unpinned package (H-A-194)
The publishes the builder heard lived only in its memory, so a build waiting for a package published before a
restart waited the whole bound and failed although the registry held the version. Before it waits, the build asks
the Go package registry seat's versions once for each unpinned path and takes the newest in the accepted series
through PackagePublished; a failed read is said and the wait goes on by the published events.

Builds: design 47 H H-A-194, H-A-192, H-A-165
2026-11-20 21:48:40 +01:00
jschoubben a62f7b40c1 mesh-grants: grants-for learns the newest revision from the event
A grants-for call still read the first page of each revision (up to
768 KB) only to learn its number. The grants holder already hears the
seat mesh-catalog's catalog-revision event, which names each branch's
newest trunk revision and the source revision it was taken in from; the
part now records both from the event and asks the revision verb only for
a revision it does not hold, by its number. Before the first event after
a start the first ask's answer names the newest once. An event below the
newest held is the numbering started again: what is kept of the branch
is dropped.

Builds: design 47 G §441, §401; H H-A-193
2026-11-20 21:44:06 +01:00
jschoubben 429f03d4cf Pin an unpinned package only at the version its registry publish carries (H-A-192)
A step ask waiting for a package the entry names with no pin took the release number of the module holding it
("v" + release), and the lane of an entry taken in dropped the empty pin and asked its build without one, so the Go
build module took another package's version: both built against versions never published (main.41, v0.1.25,
v0.1.97, v0.1.103 of the builder's builds). The builder now hears each package registry seat's published (the
package path and the version it carries) and keeps the newest per series; a build, the step's and the lane's alike,
waits for one in the series its module's manifest accepts (packages, else the default) up to package-wait-minutes,
and past it fails naming the package. The release-number pin (VersionReleased, NewestReleased) is gone.

Builds: design 47 H H-A-192, H-A-183, H-A-184, H-A-185, H-A-165
2026-11-20 21:42:33 +01:00
jschoubben 20d59ff4f0 mesh-grants: grants-for keeps the catalog revisions it read
grants-for read two whole catalog revisions page by page on every call
(about 1.4 MB each) and answered in 3.4 to 5.0 s, so the pipeline
runner's 5 s read bound cut it and every widening touching the vault
said "could not run". A revision never changes, so the part now keeps
each revision it read whole, by branch, kind, group, heads and number,
the newest four per branch for the process's life (as the runner keeps
its revisionCache); once a first page names a kept revision the pages
after it are not read. The branch's newest is read on by the number its
first page names, and a revision whose pages name another is not kept.

Quick fix (not chosen): raise the runner's widens read bound, a catalog
merge that hides the cost. Thorough fix (chosen): the cache here. The
compose of every account twice is kept whole: narrowing it to the
candidate's modules would stop a refused principal elsewhere from
failing grants-for, which is not obviously safe.

Builds: design 47 G §441, §401; H §774
2026-11-20 21:40:15 +01:00
jschoubben 12b18721b9 Build a module with a program naming no paths from its whole directory (H-A-186)
Since #290 the builder's manifest declares its packages builds and buildrun with paths beside the program and
tools, which name none. ModuleOf took the entry's named paths of any artifact as the module's, so the lane's one
fetch was narrowed to builds/ and buildrun/: the module's go.mod and cmd/ were removed and the program's build
failed with "go: cannot find main module" (main.42, 21:10 and 21:13 CET). An artifact without paths keeps its
module's directory as its build source (ADR 0499 clause 1); only a module whose every artifact names its paths is
built from those alone (clauses 2 and 4), as the indexer's own value already has it.

Builds: design 47 H H-A-186, H-A-188; ADR 0499 clauses 1, 2, 4
2026-11-20 21:28:39 +01:00
jschoubben 3183e0e056 Design 47 H1: a mover's unlogged entries live under its mover key, each entry names its mover, and list answers records with counts (H-A-189, H-A-190, H-A-191)
The record still kept every ended step's unlogged step-log entry, so a step
log outage across a large pipeline grew the record as its steps had. A
mover key now holds its steps and its unlogged entries, written in the same
compare-and-set; the record keeps neither. An entry of the step log names
its mover's module, set where an entry is made, so two movers' approvals
ending at one moment are filed under their own keys and told apart when
read back; an older entry naming none goes under the one mover whose step it
matches, else stays in the record. list answers each pipeline's record with
its movers and steps counted and its steps empty; show keeps the steps. The
seat's definition changes: its Go and TypeScript contracts are generated
again.

Builds: design 47 H H-A-187, H-A-189, H-A-190, H-A-191
2026-11-20 21:22:09 +01:00
jschoubben 30ccad4edc Assigner tests: hold putInto's writes one at a time
The composition step starts its machines' runs side by side, and each may
raise assignment-unlisted into the test's map: unguarded, the unit suite
crashed now and then with concurrent map writes. Only the test raced; the
running module writes the bus's findings state.

Builds: design 47 H §774
2026-11-20 21:15:50 +01:00
jschoubben 4e585f02b1 Design 47 H1: the runner keeps each mover's steps under its own key, so a record never grows with the catalog (H-A-187)
The runner's state pipelines held a pipeline's every step in its record, and
a record of 112 or 129 movers exceeded the bus's 1 MiB message limit (ADR
0486), so main.26 and main.30 placed no step. One MoverStore per process now
reads and writes the state: the record keeps the movers, tiers, call, source
and outcome with its own steps empty, each mover's steps are written under
steps.<pipeline>.<mover> by compare-and-set as the record is, and nothing is
written when the record or a mover key changed since the read. Every read
and judgement of steps goes through it, so the placing, the step ends, the
end judgement, the hand acts and the ageing see one composed pipeline; show,
list, stands and why-carried compose from the mover keys, and show naming a
mover answers its steps alone. A record still carrying its steps inline is
read whole, said once in the journal, and split at its next write, its
mover keys written before the record.

Builds: design 47 H H-A-187
2026-11-20 21:11:59 +01:00
jschoubben f2d3172eac Design 47 H1: the seat mesh-pipeline-runner keeps a mover's steps under its own key, and show names a mover (H-A-187)
A pipeline record of 112 or 129 movers exceeded the bus's message limit once
its steps were placed (main.26, main.30), so its steps could never be
written. The state pipelines gains the key form steps.<pipeline>.<mover>,
one mover's steps, and show takes an optional mover whose steps it answers
alone. The seat's definition changes: its Go and TypeScript contracts are
generated again.

Builds: design 47 H H-A-187
2026-11-20 21:11:59 +01:00
mesh-tools e4781edcd6 Merge pull request 'Design 47 H1: the Go packages other modules import are declared artifacts of their modules (H-A-186, H-A-188)' (#290) from fix/47-H1-declare-package-artifacts into main 2026-11-20 20:08:40 +00:00
jschoubben 1db38fcc72 Declare asks in the assigner's version series, and have the teller and the view accept it there (H-A-188)
The builder numbers every artifact of a release in its module's version, so the assigner's package asks is
published in 0.3, not the 0.1 eba4309b declared: asks now names series 0.3, and the teller and the view, which
import it, accept it at 0.3 in their manifests' packages. The other eight packages' modules are all at 0.1, so
their series stand. The gate in mesh-catalog, which imports asks too, follows with the catalog's next change.

Builds: design 47 G §370, H-A-186, H-A-188
2026-11-20 21:05:39 +01:00
jschoubben eba4309b19 Declare every Go package another module imports as a package artifact of its module (H-A-186)
mesh-build-go and other modules import packages of this repository that no manifest declared, so no release
published them and the registry holds no version: their importers stay unpinned and fail past the bound. Each
module now declares its imported packages in the form they had before issue 1966's bootstrap took them out:
asks (assigner), builds and buildrun (builder), forgemsg (forge bridge), takein (indexer), tellerevents
(teller), viewstate (view), grantsstate and busgrants (grants), each a Go package of series 0.1. Each
module's manifest test asserts its packages again.

Builds: design 47 G §370, H-A-186
2026-11-20 20:58:06 +01:00
mesh-tools a7fc37561e Merge pull request 'Design 47 H1: a pin is the version the registry published for the package path within the module's accepted series (H-A-183, H-A-184, H-A-185)' (#287) from fix/47-H1-pins-by-package-path into main 2026-11-20 19:15:04 +00:00
jschoubben e93575ffe7 mesh-delivery-indexer: the accepted series is the manifest's, contents or none
The pin fell back to the path's newest publish while no series value
held contents, which live none does, so a publish in a series a module
does not accept pinned it. The series a module accepts is the one its
manifest names, or the default; the pin is the newest version published
for the package path within it.

Builds: design 47 H H-A-185, H-A-184
2026-11-20 20:13:15 +01:00
jschoubben 859f88b2f0 mesh-delivery-indexer: a pin stays within the series the module accepts
A pin by the package path across every series moved a module to a
series it does not accept while its contents came from the accepted
one. The pin is the accepted series' newest published version where
that series gives the contents; only where none does yet is it the
newest published of the path. A publish in another series pins nothing
and moves nothing.

Builds: design 47 H H-A-184, H-A-183
2026-11-20 20:07:46 +01:00
jschoubben 517a4b3cf1 mesh-delivery-indexer: a pin is the version the registry published for the package's path
At main.39 every importer of a nested package was pinned to the release
number of the module holding it (v0.1.97 of the builder for its package
builds), and the Go seat found no tag <package dir>/v0.1.97. A Go
package's version is its tag: the pin is now the newest version the
registry published for that package path (the seats' published, kept in
the package's series), never a module's release; a package the
registry never published stays unpinned.

Builds: design 47 H H-A-183, H-A-167, G §370
2026-11-20 20:05:52 +01:00
mesh-tools 7f88916863 Merge pull request 'Design 47 H1: the forge bridge keeps only an act's outcome and pull request; the act stays in the gate's stream (H-A-181, H-A-182)' (#286) from fix/47-H1-bridge-performed-cap into main 2026-11-20 18:46:57 +00:00
jschoubben 5dee4cb263 mesh-delivery-forge-bridge: owed again refuses a performed value of the old form
A value kept before this change names no pull request, so bridge_owed_again read the subject owed..0 and said the
stream no longer held the act while it did. Every act the bridge decodes names its repository, so a value without
one is the old form: refused with what is true, never read again; it expires with the state's TTL.

Builds: design 47 G §163; H-A-182
2026-11-20 19:45:38 +01:00
jschoubben 77b683c1c1 mesh-delivery-forge-bridge: performed keeps the outcome and the pull request, not the act
The state performed filled to 77% of its template's 64 MiB (19,530 keys, 2.6 KB each): the bridge kept every owed
event whole beside its outcome. performed's value is now the outcome said as owed.ended, with when, and the
repository and number the act names (groups.Performed); bridge_owed_again reads the act from the gate's stream owed
on its pull request's subject through an ordered consumer, the stream being the act's one copy; bridge_owed reads
one act or one pull request's acts, never the whole state, whose answer had grown past what the bus carries.

Builds: design 47 G §163, §162, §168; H-A-181, H-A-182
2026-11-20 19:38:34 +01:00
mesh-tools 60e32772a5 Merge pull request 'Design 47 H1: the composition step of a module no machine holds ends nothing to run (H-A-179)' (#285) from fix/47-H1-composition-nothing-to-run into main 2026-11-20 18:08:15 +00:00
jschoubben fd2ef6c7e8 assigner: a mover no machine holds has nothing to compose (H-A-179)
A package module with a required composition step and no node placing
it ended could not run, so its pipeline could never pass. A step with
nothing to judge ends nothing to run, which counts as passed, saying why.

Builds: design 47 H H-A-179
2026-11-20 19:05:49 +01:00
mesh-tools 71371df160 Merge pull request 'Design 47 H1: proof 2, a two-module change along a dependency edge delivered by its pipeline (H §5 step 7)' (#284) from proof/47-H1-two-modules-2 into main 2026-11-20 17:55:44 +00:00
jschoubben b2d5644c34 Design 47 H1: proof 2, a two-module change along a dependency edge delivered by its pipeline (H §5 step 7) 2026-11-20 18:55:12 +01:00
mesh-tools 9598b92c39 Merge pull request 'Design 47 H1: the runner's integration tests make the module's findings stream (H §743)' (#283) from fix/47-H1-runner-queue-test into main 2026-11-20 17:37:22 +00:00
mesh-tools f00d34673f Merge pull request 'Design 47 H1: the indexer's runs-candidate test is folded into TestIndexerWhole and waits for the run-started's acknowledgement (H §743)' (#282) from fix/47-H1-indexer-runs-test into main 2026-11-20 17:35:17 +00:00
jschoubben 87357d84bd mesh-delivery-pipeline: the queue and run tests make the module's findings stream
Built against mesh-sdk at its pin (H-A-166, H-A-169), the runner counts every
event no handler takes as a finding; with no stream for its finding events each
write waited its 3 s for the bus, holding the event loop, so the queue test ran
into its 90 s bound. The tests now make the stream the manifest asks for.

Builds: design 47 H H-A-176, H-A-175 (the tests of the runner's placing), H-A-166, H-A-169
2026-11-20 18:31:59 +01:00
jschoubben 08dde53e33 mesh-delivery-indexer: the run on request's bed lives in TestIndexerWhole, its restart after the run-started's acknowledgement
TestIndexerBuildsARunsCandidateAndDropsItWhenEveryMembersPipelineEnded failed on the build node
under load (pipelines main.29 and main.31). It restarted the indexer as soon as the candidate was
written, before the run-started was acknowledged (the write comes first), and it polled both
waits with sleeps: the same kind as the toolchains bed's restart fixed in 20a7bd0f. A stop
between the write and the acknowledgement leaves the run-started for redelivery after its
acknowledgement wait, which writes the candidate again once its run has ended.

The run is now one more step of TestIndexerWhole around its restart: run-started of run 9 writes
candidates.run-9 and the run's key (watched, not polled), the restart waits for the run-started's
acknowledgement beside the source-moved's, and the member's pipeline-ended after the restart drops
both. The separate test is removed: the module's integration tests go from 541 to 540; no test
added.

Builds: design 47 H §743
2026-11-20 18:30:27 +01:00
mesh-tools c772eb0683 Merge pull request 'Design 47 H1: a build module's inputs do not wait for its toolchain; a cycle among unplaced movers ends loud (H-A-175, H-A-176)' (#281) from fix/47-H1-runner-order-cycle into main 2026-11-20 17:17:28 +00:00
jschoubben a7b2fb0ffa mesh-delivery-pipeline: a cycle ends only its own steps; the end judgement ends the pipeline
A cycle ended every open step of the pipeline at once and named edges outside
it. It now ends not asked only the steps of the movers without steps, names
the edges inside a strongly connected group alone, and leaves the pipeline's
end to the end judgement, so running steps run to their end.

Builds: design 47 H H-A-176, H-A-175, H-A-163, G §270, G-22 A-326
2026-11-20 18:15:47 +01:00
jschoubben ef086e0b75 mesh-delivery-pipeline: a cycle among unplaced movers ends the pipeline failed
A cycle the running build module does not break left a pipeline running with
journal lines only, since validate is asked only for a placed mover. The
placing now ends it failed, its why naming each artifact and edge kind.

Builds: design 47 H H-A-175, G §270, G-22 A-326, H-A-101 (2)
2026-11-20 18:12:04 +01:00
jschoubben a8adda1a8c mesh-delivery-pipeline: a build module's own inputs await not its toolchain edge
A pipeline moving the Go build module with a package it imports (mesh-sdk,
mesh-delivery-contracts) placed nothing: the package's build awaited the new
build module's files, the build module awaited the package. What a build
module's new version is built from is built by its running version.

Builds: design 47 G §270, G-22 A-326, H §746, H-A-83 (2)
2026-11-20 18:09:07 +01:00
mesh-tools e1f0c1a1cc Merge pull request 'Design 47 H1: a release pins the revision its entry lives in; freed by the module's next release (H-A-168, H-A-170, H-A-173, H-A-174)' (#280) from fix/47-H1-release-pins into main 2026-11-20 17:03:27 +00:00
jschoubben bf24bb9740 mesh-delivery-indexer: a tier-late pipeline-wanted frees no release
A tier-late pipeline's later-tier movers released a version, so the newer revision holds their
release record, yet their wants were not written: freeing their older release on the tier-late
event would remove the revision their want names. HeardPipelineWanted now reads the event's outcome:
tier-late frees nothing, and the same pipeline's later pipeline-wanted with outcome running frees as
before. The pins test's freeing sequence says a tier-late event first (nothing freed), then the
running one (the older release freed); the events test's row hands the outcome on. No test added.

Builds: design 47 H-A-174 (hq design/47-H1-answers-59 84e2514d), H-A-173
2026-11-20 18:01:56 +01:00
jschoubben 814244fd5a mesh-delivery-indexer: a release pin only for a released mover, freed only by a newer release of it
A passed pipeline's movers include ones the assigner never takes (superseded, no version released,
a tier-late pipeline's later tiers); freeing their older release on the newer pipeline-wanted would
remove the revision their want still names, and a mover releasing nothing would pin a revision per
pipeline for good. The release record is now written only for a mover that released a version in
the pipeline, and pipeline-wanted frees a module's older record only where the newer pipeline's own
revision holds that module's release record.

Tests: a pins table row (a passed mover with no version pins nothing), the freeing sequence (a
passed pipeline releasing no version frees no older release, the next one that releases does), and
TestIndexerWhole now says a pipeline-wanted on the bus after main.12's passed end and waits for
main.11's release to be freed and main.11 removed, so the indexer's hearing of pipeline-wanted is
tested end to end (review round 1). No test added.

Builds: design 47 H-A-173 (hq design/47-H1-answers-59 21297155), H-A-170, H-A-168
2026-11-20 17:58:45 +01:00
mesh-tools 442b03f61d Merge pull request 'Design 47 H1: package edges from go.mod; a pin is the newest released version, in every form's fingerprint; a release re-pins its importers (H-A-157, H-A-161, H-A-165, H-A-167, H-A-172)' (#279) from fix/47-H1-package-edges-from-gomod into main 2026-11-20 16:53:25 +00:00
mesh-tools fb23967de3 Merge pull request 'Design 47 H1: a pipeline ends failed as soon as it can no longer pass; end-again judges it by hand (H-A-163, H-A-164, H-A-171)' (#278) from fix/47-H1-runner-ends-multi-mover into main 2026-11-20 16:51:19 +00:00
jschoubben 9083287d57 mesh-delivery-indexer: a passed pipeline's release pins its revision until a newer one is the want
The pin judge removed main.23 and its entries when main.24 became current, while the assigner had
just written main.23's builder as the want: the node-engine asked its entry and was told none is
kept, holding the want for good. A passed pipeline-ended now pins the pipeline's kept revision
under a record release.<branch>.<module>, one per mover, beside the pipeline's own pin; the seat
mesh-wants' pipeline-wanted of a newer pipeline on that branch (its wants written to the end,
tier-late included) frees that record from every revision below the newer one, for each module the
newer revision's movers name. The indexer consumes pipeline-wanted (its manifest says so). A
revision a release pin holds keeps its entries, as removeUnlisted already does for any kept revision.

Tests: rows in the pins table (a passed pipeline's revision kept once no longer current; a failed
one's goes), the freeing in the pins test (a release past a failed pipeline, freed by the next
passed one's pipeline-wanted, twice changing nothing), and a pipeline-wanted row in the events
test. TestIndexerWhole now reads main.11's release beside its validate base, and waits for the held
source-moved's acknowledgement before it reads the consumer (the write comes first). No test added.

Builds: design 47 H-A-168, H-A-170 (hq design/47-H1-answers-59 87b43ec8), H-A-147, H §749
2026-11-20 17:50:08 +01:00
jschoubben 07dd8ea842 Design 47 H1: the end names why each mover has no step, its registration or a publish (H-A-171)
The end judgement took every mover with no step as waiting on its
registration; one may wait for the publish of a mover it builds on. The
registration lookup tells them apart, and the why names each with its own
reason.

Builds: design 47 H §746, H-A-163, H-A-171, G A-327
2026-11-20 17:48:10 +01:00
jschoubben d0436bb38c mesh-delivery-indexer: pins are in every form's fingerprint
The import form's fingerprint left the pins out, so an importer whose
trunk build reported its imports never moved on a re-pin and was never
built again against the release. Every form now takes its sorted pins;
a build that stands keeps its fingerprint while its pins are the ones
it was built with, and a fingerprint with no pin stays as it was.

Builds: design 47 H H-A-172, H-A-167
2026-11-20 17:46:53 +01:00
jschoubben fe51379ee2 mesh-delivery-indexer: a release re-pins or is not acknowledged; pins enter the version line's fingerprint
A re-pin that left the fingerprint as it was left the build made
against the older pin as the one the mesh runs. The version line's
fingerprint now takes the pins, so a re-pin moves the importer, which
becomes a mover built against the release. An accepted series' older
version no longer stands over a newer release. A re-pin that fails
returns its error before the heard artifacts are forgotten, and a
package-published heard again for a released version re-pins, so the
redelivery recovers it. The release path and the seed's pins carry
tests that fail without them (review round 2).

Builds: design 47 H H-A-165, H-A-167, H-A-161
2026-11-20 17:46:53 +01:00
jschoubben 037cb9555e mesh-delivery-indexer: a version-released re-pins the modules holding the package
Pins moved to a new released version only at the next merge, toolchain
report or hand recompute. The release now starts the pass of H-A-161
for the modules whose packages hold a package of the released module
alone; every other module stands as held.

Builds: design 47 H H-A-165 (the indexer's part), H-A-161
2026-11-20 17:46:53 +01:00
jschoubben 5c5136d6d1 mesh-delivery-indexer: the requirements state reads the go.sum whatever packages the reader carried
With the go.mod's mesh requires carried at every take-in, requirementsOf
returned early for every module requiring a mesh package: its go.sum was
never read and keepRequirements never cleared an old version it named
(indexer_requirements for mesh-sdk still names v0.1.13). The go.sum is
read whenever its hash moved or this process has not kept it yet.

Builds: design 47 H H-A-157 (review round 1)
2026-11-20 17:46:53 +01:00
jschoubben c43e7a5d1c mesh-delivery-indexer, mesh-delivery-builder: a package is pinned by its released version, never by a commit
The indexer filled a module's packages with the commit of a module value
it holds, which Go turned into a pseudo-version of whatever that tree
was (mesh-delivery-sdk at an 11-19 commit, nodeengine pre-H1). A pin is
now the newest released version of the module holding the package (the
versions state version-released says), an accepted series' version
stands, and a package with none released is kept with no version: its
kind-1 edge stands and the builder asks no pin for it. A commit of
another repository moves a module only through a package of it the
module imports (A-476a), now that pins name no commit.

Builds: design 47 H H-A-161, G §370, H §746, H-A-157 (kind-1 edges)
2026-11-20 17:46:53 +01:00
jschoubben e04321acae mesh-delivery-indexer: a build's reported imports refine the go.mod's packages, never empty them
An import form whose imports name no package of another repository, or a
build that stands with versions held empty from the go.sum era, wrote an
empty package set while the go.mod requires a mesh package: no kind-1
edge. The version line's versions of the go.mod's set stand then.

Builds: design 47 H H-A-157, G §47 (kind 1)
2026-11-20 17:46:53 +01:00
jschoubben 4c2914194b mesh-delivery-indexer: a module's mesh packages are what its go.mod requires
At main's revision 21, 64 of 82 Go modules carried no package edge: the
version line read the mesh packages go.sum names, and go.sum names none
required at the zero version (ADR 0573 §2). The take-in now reads them
from the go.mod's require lines, at any version, with no build needed;
the go.sum is read only for the requirements state. The sibling rule
(replaces by a directory) stands.

Builds: design 47 H H-A-157, H-A-136 (sibling rule), G §47 (kind 1)
2026-11-20 17:46:53 +01:00
mesh-tools 277c53067e Merge pull request 'Design 47 H1: proof 2, a two-module change along a dependency edge delivered by its pipeline (H §5 step 7)' (#273) from proof/47-H1-two-modules into main 2026-11-20 16:44:51 +00:00
mesh-tools 227f6e68ce Merge pull request 'Design 47 H1: a build with an unpinned package waits for its release (H-A-165)' (#277) from fix/47-H1-builder-waits-package into main 2026-11-20 16:41:47 +00:00
jschoubben 521cbf089e Design 47 H1: the seat mesh-pipeline-runner gains end-again, a hand act judging a pipeline's end once more (H-A-164)
A pipeline the end judgement before H-A-163 left running had no way to end
but a cancel. The runner's process answers end-again, so the end takes its
turn in the queue; runner_end_again asks it. The seat's definition changes:
its Go and TypeScript contracts are generated again.

Builds: design 47 H §746, H-A-163, H-A-164
2026-11-20 17:38:20 +01:00
jschoubben 39a2c6a944 Design 47 H1: a pipeline ends failed once it can no longer pass, a mover waiting on its registration named (H-A-163)
main.20 and main.22 never ended: a mover with no step placed (no registration)
held the end even after a placed mover's required step failed and nothing was
open. It now holds the end only while the pipeline could still pass.

Builds: design 47 H §746, H-A-163, G A-327
2026-11-20 17:38:20 +01:00
jschoubben 577ec05205 Design 47 H1: the runner says a mover waits on its registration when placed from the half or the queue (A-327)
A pipeline placed at its turn in the queue, or once its branch's half was held,
dropped its movers with no registration without a word: main.20 and main.22 sat
running with every step ended and nothing said why (their mover
mesh-delivery-contracts has no registration, so it is never placed and the
pipeline never ends).

Builds: design 47 G A-327, design 47 H §746
2026-11-20 17:38:20 +01:00
jschoubben 744204c5ab Builder: releases heard wake the package wait; its setting package-wait-minutes (H-A-165)
The process tells the builder each version-released it takes in and
gives it the newest release its record keeps, so an unpinned package's
step ask wakes on the event and pins the release; the wait's bound is
the setting package-wait-minutes (default 10), carried as a file under
the state dir like revision-wait-minutes.

Builds: design 47 H H-A-165, H-A-156, H-A-155
2026-11-20 17:37:25 +01:00
jschoubben 0f41b405ba Builder: a step ask naming a package with no pin waits for its release (H-A-165)
An entry keeps a mesh package with no released version unpinned
(H-A-161). Its step ask now waits, in the wait of H-A-155, for the
release of the module holding the package, heard or kept in the
builder's record of releases, and builds with that release as the pin;
past the bound the step fails naming the package and builds nothing.

Builds: design 47 H H-A-165, H-A-155, H-A-161
2026-11-20 17:37:25 +01:00
mesh-tools 20f0e9baaf Merge pull request 'Design 47 H1: a build waits for its revision and never builds without a version; a run's ask names no source (H-A-155, H-A-156, H-A-162)' (#276) from fix/47-H1-builder-waits-revision into main 2026-11-20 16:35:46 +00:00
mesh-tools 75c636a5ec Merge pull request 'Design 47 H1: the builder numbers nothing of its own; a published of other bytes leaves a kept entry (H-A-159)' (#275) from fix/47-H1-builder-versions-record into main 2026-11-20 16:32:12 +00:00
jschoubben 0cbabe9860 Runner and builder: a run's build step ask names no source; a held revision wakes the builder's wait (H-A-162)
A run on request copied its pipeline's source onto its build step ask,
so the builder waited for the run's candidate fingerprints in its
picture of the branch, where they never come, and failed every run past
the bound. The seat mesh-builds' contract leaves a run's source absent:
the runner now does. A revision the builder's view takes in whole that
changes no entry now also wakes a waiting ask, told by the catalog
client's new Held.

Builds: design 47 H H-A-162, H-A-155
2026-11-20 17:30:56 +01:00
jschoubben d2c9dc7de6 builder: builder_floor_again refuses; it asks no floor any more
With nothing numbered of the builder's own, the tool answered that a floor
would be asked at the next claim and looked again, doing nothing.

Builds: design 47 H H-A-159, G §369
2026-11-20 17:30:49 +01:00
jschoubben 53199f16ce Builder: the revision wait reads the picture and its setting revision-wait-minutes (H-A-155, H-A-156)
The process gives the builder its picture of each watched branch (the
source revision the branch's view holds) and the bound of a step ask's
wait for its revision, read from the setting revision-wait-minutes
(default 2) carried as a file under the state dir like
toolchain-wait-minutes.

Builds: design 47 H H-A-155, H-A-156, H-A-141
2026-11-20 17:27:37 +01:00
jschoubben 256eb34a0d Builder: a build step ask waits for its revision before it builds (H-A-155)
A step ask reached the builder before its picture of main's catalog
revisions held the revision the pipeline builds; the fingerprint was
built as no first branch's build, reserved no version, and the step
failed on builder_reserve_done's words. The ask now waits, woken by each
entry the picture takes in, until the picture holds its source revision
and the asked entry from its branch; past the bound it fails naming the
revision and builds nothing.

Builds: design 47 H H-A-155, H-A-141
2026-11-20 17:27:37 +01:00
jschoubben a47c8e7922 builder: number nothing of its own; the reservation numbers
Every look numbered one more patch in the state versions (claims carry no
source revision since H-A-48): nodeengine 0.1.5 to 0.1.36, beside the
reservation's numbers.

Builds: design 47 H H-A-159, G §348, §349, §369
2026-11-20 17:24:48 +01:00
jschoubben 16f9ad2950 builder: a published of other bytes leaves a kept versions entry as it is
The reservation's published of nodeengine 0.1.4 (9724da7a) was taken into the
state versions' entry 0.1.4, numbered for an older fingerprint, which turned
published and kept the old digest c0ef9a3d.

Builds: design 47 H H-A-159, G §369, A-415; ADR 0605 §4
2026-11-20 17:23:19 +01:00
mesh-tools b1f25f91d5 Merge pull request 'Design 47 H1: validate reads the base the take-in names on the catalog revision; the indexer's restart tests wait for the bus (H-A-151, H-A-154, H §743)' (#274) from fix/47-H1-indexer-toolchains-test into main 2026-11-20 16:09:50 +00:00
jschoubben d281faeeb7 mesh-delivery-assigner: the validate test judges a revision whose base is below its number minus one
Every revision the validate test judged with a base had it at its number minus one, so the test
passed with the case before read as the number before (review round 1). Revision 12 now names base
7 with 8 to 11 never kept: it ends manifest-refused against base 7's manifests, and could not run
when the case before is read as the number minus one. No test added.

Builds: design 47 H-A-154 (hq design/47-H1-answers-59 01842bbe), H-A-151
2026-11-20 17:08:23 +01:00
jschoubben e312999843 Design 47 H1: proof 2, a two-module change along a dependency edge delivered by its pipeline (H §5 step 7) 2026-11-20 17:06:04 +01:00
jschoubben 5dba7fe68b mesh-catalog's revision names its base; validate's case before reads it, not the number before
A take-in that moves nothing keeps no revision for its source number, so validate's case before,
read as the step's revision minus one, named a revision never kept and could not run. The take-in
now writes, on the catalog revision it keeps, the field base: the newest kept revision below it,
the one it pins for its pipeline, in the same write; absent on the branch's first take-in. The
assigner's validate reads the base from the revision it already asks for; where the revision names
none the case before is empty and its end says so, never a could-not-run.

- mesh-delivery-contracts: the seat mesh-catalog's CatalogRevision gains base (schema, fixture,
  generated Go and TypeScript by seatgen).
- mesh-delivery-indexer: keepBranchEntries names the base it pins; the pin test's rows check it.
- mesh-delivery-assigner: before reads the base; the validate test asks a revision with none, and
  both stand-ins name the base as the take-in does.

Builds: design 47 H-A-151, H-A-154 (hq design/47-H1-answers-59 01842bbe), H-A-147, H-A-108 (3), design 47 H §743
2026-11-20 17:00:55 +01:00
mesh-tools f0f28c56a4 Merge pull request 'Design 47 H1: an assignment no watched branch lists is left out of a machine's composition, said and raised as a finding (H-A-148, H-A-149, H-A-152, H-A-153)' (#272) from fix/47-H1-unlisted-assignment-left-out into main 2026-11-20 15:54:36 +00:00
jschoubben 20a7bd0f3c mesh-delivery-indexer: the restart tests wait for the take-in's end and the bus's close
TestIndexerCountsOnlyThePlacedBuildNodesToolchains failed on the build node under load
(pipeline main.18) in two ways, both of the test, not of the indexer's count of the
placed build nodes' toolchains:

- it restarted the indexer as soon as the module was written, before its take-in
  ended: the stop cancelled the take-in, its source-moved stayed unacknowledged, and
  the branch's durable (one message at a time) held the next one behind it for its
  acknowledgement wait, past the test's 20 s bound. Each restart now waits for the
  source-moved's acknowledgement; TestIndexerWhole's restart the same way.
- a source-moved said right after a restart could reach the stopped program's pull,
  still counted until the bus closed its connection. restart now returns only once
  the bus has closed every connection of the stopped program, heard on the system
  account's disconnect events, with no sleep.

Under load (8 runs side by side, GOMAXPROCS=1) the test failed 5 of 80 runs before,
2 of 240 with the first change alone, and 0 of 600 with both; TestIndexerWhole 0 of 600.
No test added.

Builds: design 47 H §743
2026-11-20 16:54:26 +01:00
jschoubben 0b1ce08985 assigner: one set of unlisted assignments, carried on the run (H-A-152, H-A-153)
The leaving-out took every assigned module the case's manifests lacked,
while the judgement said only those the watched branches' newest
revisions list nowhere, read again at judgement time. Now the set is read
once from the newest revisions when the run starts, written on the run,
and used for the leaving-out, the finding and every step's judgement and
the resume. The candidate never enters it: a module the change drops
while still assigned stays in and fails the composition as its own
fault. While no newest revision is followed nothing is left out.

Builds: design 47 H H-A-152, H-A-153
2026-11-20 16:51:28 +01:00
jschoubben f053e3b041 mesh-wants: a composition run carries its unlisted assignments (H-A-153)
The judgement of every step reading a run, and the resume after a
restart, read only the stored run; the set of assignments left out is
written there when the run starts, so it is not kept in a step's memory.

Builds: design 47 H H-A-153
2026-11-20 16:47:57 +01:00
jschoubben d428650ce4 assigner: raise assignment-unlisted where a step leaves one out, clear it in the pass (H-A-149)
A stale assignment left out of a machine's composition is now a finding the
condition keeper carries: kind assignment-unlisted, scope delivery, id
<node>.<module>, a warning, raised by the composition step that leaves it
out. The pass over the assignments clears it when the assignment is gone or a
watched branch of the module lists it again, so the clear never waits for the
next step on that machine.

Builds: design 47 H H-A-149, H-A-148
2026-11-20 16:31:50 +01:00
mesh-tools 351eda0867 Merge pull request 'indexer: a take-in pins the branch's previous revision for its pipeline, so validate's base stays (H-A-147)' (#271) from fix/47-H1-validate-previous-revision into main 2026-11-20 15:31:05 +00:00
jschoubben 5e3d92ae33 assigner: leave a stale assignment out of a machine's composition (H-A-148)
The retired checker's assignment on the control-node made every composition
there refuse "nothing provides", so every composition step on that machine
ended could not run. A module assigned to a machine that the case's manifests
do not hold (no watched branch lists it) is now left out of the case's
assignments as well, said in the journal and at the judgement as unlisted, and
the machine is judged on what remains: a stale assignment is a fault of the
assignments, not of the change judged.

Builds: design 47 H H-A-148, H-A-143; ADR 0578 §2
2026-11-20 16:29:16 +01:00
jschoubben e5e5c50e67 mesh-delivery-indexer: a take-in pins the branch's previous revision for its pipeline, so validate's base stays
The pin judge removed the branch's previous revision in the very write that took the next one in
(pipelines main.13 and main.15 on 2026-11-20), so the validate step's case before could not be read
and the composition was never asked. The take-in now pins the newest revision it kept before its
write under the same pipeline record as its own, and the pipeline's end frees the record on every
key it pins; a take-in with no revision before it pins only its own and says so.

Builds: H-A-147 (hq design/47-H1-answers-59 310f8955ba16a1ca8ae9661d8196cab16e3d9597), design 47 H §743, §749, H-A-108 (3)
2026-11-20 16:27:21 +01:00
mesh-tools 8167d825ed Merge pull request 'mesh-grants: the marks subtest calls on the caller's granted token and waits for its refusals; the test's nats_streams stand-in skips a consumer gone' (#270) from fix/47-H1-grants-marks-test into main 2026-11-20 15:19:12 +00:00
jschoubben ac95e5628c mesh-grants: the test's stand-in nats_streams skips a consumer gone between its listing and its read
Under load (8 copies side by side) TestTheGrantsPartWhole panicked at
integration_test.go:151 at abb7cfcf too: st.Consumer's error was dropped
and a consumer deleted after ConsumerNames listed it gave a nil one.

Builds: design 47 H §746 (the pipeline's integration step)
2026-11-20 16:11:14 +01:00
jschoubben bed9b61d5a mesh-grants: the marks subtest calls on the caller's granted token and waits for its refusals
The subtest "a runtime denied the marks is delivered no call on a marked
subject" published the caller-named call on mesh.mod.shell.call.execute.asker~a,
a token the composer never grants (buscompose.CallerToken gives a~asker
for the user a.asker), so the server refused it every time; the test
passed only because it read the refusals with a non-blocking select
right after Flush, before the client's error callback had run. Under
load the callback won the race and the pipeline's integration step
failed (main.12, 15:50). The call now uses CallerToken, and a probe on
another caller's token is published last: the server refuses in order,
so waiting for the probe's refusal waits on every refusal asserted.

Builds: design 47 H §746 (the pipeline's integration step), G A-203 (AM-D4)
2026-11-20 16:09:35 +01:00
mesh-tools 67ef449230 Merge pull request 'mesh-grants: bring a held kept stream to its definition's source filter (H-A-145)' (#269) from fix/47-H1-kept-stream-source-filter into main 2026-11-20 14:47:59 +00:00
mesh-tools 8a52b6f801 Merge pull request 'forge bridge: adopt only an added branch; its integration tests wait on what they assert' (#268) from fix/47-H1-forge-bridge-integration into main 2026-11-20 14:46:50 +00:00
jschoubben 380d4781e6 mesh-grants: bring a held kept stream to its definition's source filter
The kept stream of the runner's pipeline-ended was made at G's
definition, sourced by a three-part subject; H1 moved the event to
<branch>.<source>, so the stream took nothing in since 08:13 and the
assigner, which hears a kept event from its kept stream, heard no end.
createKept left every held kept stream as it was. It now brings a held
one's source filter from the events stream to the definition's in place
(a stream update, its messages and other settings kept, never made
again) and says the held and the composed filter in the journal and the
pass; the same holds for pipeline-started and wait-held.

Builds: design 47 H H-A-145 (hq design/47-H1-answers-59 0787704b), §746
2026-11-20 15:42:24 +01:00
jschoubben 7534bf5c07 forge bridge: adopt only an added branch; its integration tests wait on what they assert
Pipeline main.8 failed TestBridgeSaysOneHeadMovedPerMove and TestBridgePerformsWhatIsOwedOnce on
shanks; both fail the same way at 403fb306, before the catalog client change, under load.

- The bridge read every head again, start true, whenever the registrations' first view said its
  values after the start had begun, so a head moved just after the start was said as a start.
  Only a registration adding a watched branch is adopted now (Watched.Set says so), decided under
  one lock with the start's read.
- The head-moved test moved the head before the restart's read was answered, and read the state
  heads before the bridge wrote it; it now waits for the stand-in's answer and watches heads.
- The owed test stopped the bridge while an outcome's publish was on its way (heard again after
  the start), and an act said while the bridge stops can be handed to the stopped bridge's pull,
  which the bus hands again only after the consumer's acknowledgement wait (30 s) past the
  test's 20 s bound. It now hears the bridge's acknowledgements before the stop and waits the
  consumer's acknowledgement wait for the act said meanwhile.

Builds: design 47 H §739; design 47 G §532; design 47 H-A-48
2026-11-20 15:41:10 +01:00
mesh-tools 08fe40f233 Merge pull request 'assigner: a machine's composition across the watched branches (H-A-143, H-A-144)' (#267) from fix/47-H1-compose-across-branches into main 2026-11-20 14:38:28 +00:00
jschoubben 27e96a2a1b assigner: say an unlisted module on every path; no registration, no branches (H-A-144)
Review round 1: an unlisted module was lost where the composer blamed a module.
It is now said in the failed or could-not-run words where one is set, else as a
warning. Once registrations are held, a module none names has no watched
branches and is unlisted, never composed from the branches the client follows;
before the first registrations the gate's source's branches stand in, in its
order. A module is judged unlisted by its own watched branches.

Builds: design 47 H H-A-143, H-A-144, G §532
2026-11-20 15:35:59 +01:00
jschoubben f98d5ec748 assigner: compose a machine across every watched branch (H-A-143)
The composition step judged a machine at the step's one branch revision, so an
app registered on another watched branch was missing and the machine failed
"nothing provides", ending every mover there "could not run". Each module's
entry now comes from the newest revision of the first of its watched branches,
in its registration's order, that lists it; the candidate's revision replaces
its branch's newest for the modules it moves. A module assigned to the machine
that no watched branch lists is said in the machine's reason.

Builds: design 47 H H-A-143, G §532
2026-11-20 15:28:29 +01:00
mesh-tools abb7cfcf5d Merge pull request 'meshcatalogclient: a revision below the held one asks the first view again (H-A-141)' (#266) from fix/47-H1-catalog-client-numbering-restart into main 2026-11-20 14:09:37 +00:00
jschoubben 3956c0cf94 meshcatalogclient: a revision below the held one asks the first view again
A reader whose picture held the earlier model's revision 528 skipped
revisions 1 to 7 of the new numbering in silence: the builder built
every pipeline step as a candidate's, unversioned, so nothing was
released and no want moved. An event below the held revision is now
the state made again: said with both revisions, the view's made time
moved on (so the follower forgets the old numbering's revisions heard
and is not left behind for good), and the first view asked again. An
event equal to the held revision is still dropped.

Builds: design 47 H H-A-141 (hq design/47-H1-answers-59 3d722934), §750, §754
2026-11-20 15:05:06 +01:00
mesh-tools 403fb3068b Merge pull request 'The indexer makes its own per-branch durables and drops the earlier model's revisions at a take-in (design 47 H, H-A-134, H-A-135)' (#265) from fix/47-H1-indexer-durables into main 2026-11-20 11:21:50 +00:00
jschoubben e54bf7f346 indexer: a branch's durable it makes waits 30 s, delivers 5 times, starts from now
As the grants part gives a module's consumer on a seat event's stream kept by age:
without a start from now a made durable would replay every past source-moved of the
branch past the start's guard; the current revision is read at the start already.

Builds: design 47 H §743, H-A-134 (hq 8d30cc42), H-A-129, H-A-130

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 12:19:50 +01:00
jschoubben f95a164941 indexer: drop the earlier model's trunk and branch revisions at a take-in
catalog-revisions kept trunk.<n> and branch.<branch>.<n> objects beside the
branch-keyed revisions, the newest trunk one marked current, so a reader heard
revision 528 while its picture held 1. A branch's take-in now drops every such
object no record pins, says the count in the journal, and the revisions tool marks
each branch's newest revision current.

Builds: design 47 H §743, H-A-135

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 12:12:23 +01:00
jschoubben 0cf419619e indexer: make a watched branch's source-moved durable when the bus holds none
The grants part composes no per-branch durable on the source-moved stream, so the
indexer never heard a source revision after its start. Its bind now makes the
durable itself, as a module's seat-event consumer is made (SeatEventConsumerConfig,
named <node>_<indexer>_<branch>, filtered to the branch, one message at a time),
and binds an existing one as it stands.

Builds: design 47 H §743, H-A-134

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 12:10:46 +01:00
mesh-tools 8b6f6b22d4 Merge pull request 'The indexer reads a branch's source by the verb when its consumer is not bound (design 47 H, H-A-129, H-A-130)' (#264) from fix/47-H1-indexer-bootstrap into main 2026-11-20 09:46:08 +00:00
jschoubben 9cddb5921a indexer: take a watched branch's source revision in from the gate's source when its consumer cannot be bound
At a clean state the grants part makes the per-branch consumers of source-moved only from the modules view, which the
indexer answers only after its first take-in, so nothing ever took the trunk in. At its start, and again at each
failed bind, the indexer now reads the branch's current source revision through mesh-delivery.source and takes it in
as a heard source-moved of it would, when its view keeps no revision of the branch at or above it: start true exactly
when it keeps none, every repository the answer names a head. No timer; binding on registration-changed is unchanged.

Builds: design 47 H §743, §768, H-A-129, H-A-130

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 10:39:45 +01:00
mesh-tools 842da1be85 Merge pull request 'Design 47 H1: the one chain (take-in, forge bridge, pipeline runner, assigner, teller, view, watchman, grants; checker gone)' (#263) from feat/47-H1 into main 2026-11-20 07:15:12 +00:00
jschoubben 3090a80a09 indexer: indexer_pin_drop's all form drops every pin for the clean state
Review round 1, H-A-121 (2): beside the one-item form, all true drops
every pin of the state pins, each recorded through mesh-hand-acts and
asked of the indexer as the one-item form is; it answers the count
dropped and the pipelines the pins named.

Builds: design 47 H §765, H-A-121, H-A-124

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:55:59 +01:00
jschoubben 03c0b627ad assigner: assigner_want_drop's all form drops every want for the clean state
Review round 1, H-A-121 (2): beside the one-item form, all true drops
every want key, held or not, and every value of an earlier form the
decoder refuses, each act recorded through mesh-hand-acts first; it
answers what it dropped, counted per kind (held, current, undecodable).

Builds: design 47 H §765, H-A-121, H-A-123

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:54:39 +01:00
jschoubben af5d5f87dd forge bridge: the stream forge keeps head-moved 7 days
Review round 1, must 6: the stream's definition names its keep, as the
manifest template states a stream's age (max-age-days).

Builds: design 47 H §739, H-A-23

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:51:33 +01:00
jschoubben fbd75dfac4 indexer: what nothing reads goes
packageEntries, manifestBytes, writtenModules, WriteHeard, heldOldSections, keepOldSections,
the overlay's written and changed, moduleOfDir with moduleAt, EncodeSeriesPackage,
InputDigest, HoldSeats and the barBlock shape's functions are referenced by no file of the
repository; with HoldSeats gone the seat list's lock is a plain mutex WithSeats takes.
barShows and barOption stay: a judge test reads them.

Builds: design 47 H §764; lead answer H-A-48

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:32:16 +01:00
jschoubben 40bd5cf69d steprun: the pull-order test asserts the kinds' turns, as the code has since 2026-11-15
TestPullOrderAndCapacityOnTheBus still asserted deliveries first, red since 773f89e9 made
the build seats' queue kinds take turns (not since 83d45421: it fails at 83d45421^ too).
It now asserts a delivery, then the check in its turn, then the other delivery; it fails
on a pull that takes deliveries first.

Builds: design 47 H H-A-41, H-A-117, H-A-120; G A-440

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:30:42 +01:00
jschoubben a94b275a9c I-114 fix: a state held not there yet holds nothing to take in first
Before the state held is bound, hearing a source-moved read it to hold the event behind
earlier ones, failed and left every message unacknowledged, so nothing was taken in (two of
the indexer's integration tests, which make no held state). A state not there yet holds
nothing: the event is taken in; holding it still needs the state.

Builds: design 47 H H-A-114, H-A-118
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:24:20 +01:00
jschoubben 12b48debe9 T-119: the teller says one widening per mover; record-opened is no longer heard
The teller reads pipeline-ended's H1 form, saying each mover's widening once for its module,
watched branch and commit; its hearing of record-opened, whose forge-made record H §763
retires, goes with its consume in the manifest.

Builds: design 47 H H-A-119, H-A-72, H-A-51, §763
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:18:13 +01:00
jschoubben 05b91a6281 C-R6: pipeline-ended names each mover's commit and widens
The seat mesh-pipeline-runner's MoverEnded gains commit and widens (regenerated, with a
fixture row), and the runner writes them from its pipeline value when it says
pipeline-ended, so the teller says a widening from the event alone.

Builds: design 47 H H-A-119, H-A-72, H-A-51
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:18:13 +01:00
jschoubben ecc87a6510 I-114: a held take-in is acknowledged and kept whole, in order, in the state held
A source-moved the indexer cannot take in is written into the state held, the event whole
(call, heads, start beside branch, source, why, since), and acknowledged once written; a later
source-moved of a held branch is held behind it, and the branch's key keeps them in order.
The indexer takes them in again from that state alone, in their order, on its own room and
at its start; one neither taken in nor written stays unacknowledged. The whole test's held
case reads the new form and that nothing is left unacknowledged.

Builds: design 47 H §744, H-A-114, H-A-118
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:15:02 +01:00
jschoubben 76b2e8dc7d A-60: the assigner asks an unreached entry again to entry-asks, then writes entry-unanswered
The passer's catalog entries are the followed branches' own, so each catalog-revision asks
again an entry whose ask failed to reach the holder, and so does each reopening of the
assigner's link to the bus; the manifest's setting entry-asks (default 5) bounds it, and past
it the assigner's finding writer writes entry-unanswered (and entry-not-found) through the
entries client.

Builds: design 47 H H-A-60
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:10:24 +01:00
jschoubben 6b50f3eb9d V1 join: indexer_pending has one form; the take-in package's old answer goes
The view's tools already read indexer_pending's {held: [{branch, source, why, since}]} through
view.DecodeHeldTakeIns at the joined base; the take-in package's earlier PendingAnswer,
PendingWait and DecodePendingAnswer, read by nothing since, go with their test.

Builds: design 47 H H-A-102, H-A-97
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:05:13 +01:00
jschoubben c9f0beedd1 X1 join: the checker's generated packages, requires and askers go
The seat mesh-delivery-checker's generated Go seat, client and TypeScript package go from
mesh-delivery-contracts (and their entries in its manifest), with the old copies under
contracts/go; the indexer, the forge bridge and the assigner require them no more, and the
assigner judges with its own internal/assignment verdict constants. The git, node-build-go
and node-build-node fixtures, the buildstep and steprun tests and the indexer's and
assigner's whole tests name the seat mesh-wants (the asker of every check-kind run in H1)
or the runner where they named the checker; the indexer's unused CheckerModule and the
judge's stream exemption for the checker go. The step kinds check and recheck stay with
their queues (H-A-117).

Builds: design 47 H H-A-57, H-A-117
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:04:11 +01:00
jschoubben 5f4eb03fcf Join: the assigner's composition-run test reads no case verdicts
The assigner branch was built before SDK-C took Case.Verdicts out of the composer's request;
its test still read the field, so the joined line did not compile.

Builds: design 47 H H-A-112
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:04:11 +01:00
jschoubben 20bbf346dc A13: the whole test follows the newest passed version, tier by tier
The assigner's whole tests no longer assume wants follow the trunk's
fingerprint: a runner's pipeline-ended names the movers and versions, the
wants are written tier by tier on running, and pipeline-wanted says running
at the end. Test 113's cases: a provider and its consumer in tiers, the
acting part's build and the old holds ignored, a failed pipeline's version
and an older end heard late writing nothing, a placement's build reverting
the want, tier-late after tier-bound with no later tier written, and a node
not stating want:version held awaiting its hand placement. Test 117's cases
run the step validate whole: a refused manifest, a pass and a cycle. The
first views answer every account (no callers), and tier-bound's unit is a
variable the whole test shortens.

Builds: design 47 H §774, §750, §751, §772, §745, §752; acceptance tests 113, 117; lead answers H-A-10, H-A-37, H-A-40, H-A-41, H-A-56, H-A-73, H-A-75, H-A-99, H-A-108

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:57:45 +01:00
jschoubben 0bb24f91a8 H-A-112: the composition step's case carries no verdicts
The composer's Case.Verdicts goes (its one writer was the checker); the
validate step judges the manifests before the composition step, so caseOf
answers the manifests and none words alone.

Builds: design 47 H §745; lead answers H-A-112, H-A-108

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:57:45 +01:00
jschoubben 70ccb470a7 Rebase onto C1d: the assigner reads no source stamp of a catalog entry
The seat mesh-catalog's module value and entry inputs lose src and fp-src
(C1d), so a trunk entry's release is the version-released whose parts are
what its build.ended made, the one way left of the two the assigner had.

Builds: design 47 H §764; lead answer H-A-48

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:57:45 +01:00
jschoubben e4d51a47f7 A10: the step validate, one run per take-in revision before the composition
The assigner takes the seat mesh-wants' step validate beside the composition
step. Every mover's validate step of one take-in reads one run, the key
<pipeline>.validate of composition-runs with no machine, taken up at the
start like the composer's runs: a cycle the revision's entries make
(graph.RefusedCycle) ends it at once; else the manifest validator built from
the revision's entry of the module holding mesh-catalog runs on the Go build
seat, its input kept and served on mesh-wants' input, over the revision's
manifests and the branch's previous revision's. The step ends failed cycle,
failed manifest-refused naming every problem the revision causes, or passed.

Builds: design 47 H §745; H-A-34, H-A-51, H-A-108

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:57:45 +01:00
jschoubben 1ede9a5f11 H-A-104: the assigner keeps each node's engine words in its own state engine-reads
The words of each node-engine's manifest-reads-changed are written into the
assigner's state engine-reads, key the node, value {words, at}, before the
event is acknowledged, and read back from the state's watch at the start, so
a restart loses no node's words. The verb manifest-reads is no longer asked:
the keeper's asks, the unanswered-call finding and the node-record fallback go,
with the invoke in module.json. assigner_engine_reads lists the state.

Builds: design 47 H §772; H-A-104 (1), H-A-45

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:57:45 +01:00
jschoubben 79322692c6 A8: a placement's build names the want's version
The pass reads each node's placement before the rule: a placement naming a
build has its want name that build, by the version released at it (the kept
end's when it is that build, else the release whose parts the build made),
with no pipeline and no rank; with no released version known no want is
written, said once. A placement's build is no longer made a held put:
placementPuts and its test go, and a placement naming no build any more
gives the node back to the rule.

Builds: design 47 H §750, H-A-5, H-A-37, H-A-39, H-A-99

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:57:45 +01:00
jschoubben 037cb74640 A7: one pipeline's wants are written tier by tier
On a passed pipeline-ended the assigner keeps the tier progress of the
pipeline in its state written (`pipeline.<branch>.<source>`, {tier, since,
movers}) and writes the wants of the movers of the current tier only; once
each of them runs at its fingerprint on every present placing machine, the
next tier's wants are written in the same pass, and after the last tier
pipeline-wanted says running and the progress goes. A tier counts placed
movers; a machine away is not waited for; a mover a later pipeline moved
counts as run. A tier past the setting tier-bound (default 30 minutes, a
config file the manifest declares) raises the finding tier-late (scope
delivery, id the pipeline) naming the movers and machines not running, says
pipeline-wanted tier-late and writes no later tier; the finding clears when
the late movers run or a later pipeline moves them. One timer wakes the pass
at the earliest deadline. wanted names the pipeline its want follows.

Builds: design 47 H §751, H-A-10, H-A-40, H-A-56, H-A-72 (6), H-A-75

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:57:45 +01:00
jschoubben 46f1a54189 A6: the whole test of the composition runs says a superseded run's end in the new form
Its pipeline-ended names a source and its mover, as the runner's client reads it.

Builds: design 47 H §746, §750

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:57:45 +01:00
jschoubben bdbfa12aa1 A9: a node whose node-engine reads no want by version is held, awaiting its hand placement
The want of a node whose node-engine does not state the word want:version of
the seat node-engine, as the engine reads keeper holds it from
manifest-reads-changed, is written with hold and the words
awaits-hand-placement; once the engine states the word, the next pass writes
the want unheld.

Builds: design 47 H §772; H-A-45, H-A-73

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:57:45 +01:00
jschoubben 4923d22ac6 A12: assigner_want_drop drops one want by hand, recorded first
The tool takes node, module and why: the act is recorded through the seat
mesh-hand-acts, then the key want.<node>.<module> is deleted from the state
wants; the next pass writes the want of the new form. Refused with no want
under the key, no why, no proven caller, or when the act is not recorded.

Builds: design 47 H §765; H-A-58

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:57:45 +01:00
jschoubben 4613300bcd A5, A6: a want names the newest version released whose pipeline passed, held for nothing else
The want rule is written again (internal/assign Wants): for every node the
module is assigned to, the want names the version, the pipeline and the
mover's rank kept for the module on the placement's branch from the runner's
pipeline-ended; a put owns its node's want as before. The state written keeps
per module and branch the newest passed version, by compare-and-set on a
newer version: a failed pipeline, a mover whose required step failed, an
older version, the same one again and a run on request keep nothing; a run's
end drops its candidate graph (H-A-58). group-ended is no longer heard.

The old holds go with their code, findings, asks and tests: the canary and
step, every provider healthy, the grant, the composition and reader
capabilities, the provisions (the provisioner's read, its findings), the served
verbs, the bus state, rule 2 (the held fingerprint, its hold and restore asks,
its lift and conditions), the neither list, the network hold and A-428's
exceptions (H-A-55). The record yes stays as the node-engine's have asks it.
A want names no composition, so the backup ask is bound to the build.

The callers API's call sites go (H-A-66): the seat list's callers, the
first-view callers lists in the manifest, the step asker judgement, the
enrolment caller read locally. The assigner's revision pins go whole with the
gate's pin events (H-A-86): a revision not current is removed when one ceases
to be current and at the start.

Builds: design 47 H §750, §752, §764, §765 (assigner part); H-A-37, H-A-55, H-A-58, H-A-66, H-A-86

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:57:44 +01:00
jschoubben 1cf2ea46ff A11: a composition step's progress names the asker its step run carries
With no callers list on the seat mesh-wants, the asker a step's progress names is
the one the runner writes on the StepRun it asks (C-W2), mesh-pipeline-runner.

Builds: design 47 H §752 (consequence), G §496; H-A-41, H-A-88

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:57:44 +01:00
jschoubben 2a93cbcd9b R17: the queue's whole test against the bus
The runner started whole with pipelines-at-once 1 and pipelines-waiting-cap 1: a second take-in
waits, saying wait-held, and is placed with wait-ended on the first's end; a newer waiting take-in
takes its shared movers out of an older waiting one, which ends superseded; a start over the cap
waits and raises queue-full, cleared on the count; a cancel places the next; a pipeline on its
approval alone gives up its place and, answered while it still runs, is keyed running at once; a
placing the bus refuses raises pipelines-stalled, cleared when the next start places the waiting
from the runner's own state, which starts no pipeline of its own. The tools runner_rerun,
runner_accept and runner_ask_again are shown to take the mover's module.

Builds: design 47 H §748, §774; acceptance test 112 (the runner's half); lead answers H-A-14, H-A-36, H-A-52, H-A-53, H-A-96, H-A-101, H-A-106, H-A-107

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben 0548dc8f80 R13: a mover whose dependency was superseded out says so in its build's why
A waiting pipeline keeps in superseded (C-R5) the modules a newer waiting pipeline of its branch
took out of it, written with its movers by compare-and-set; at its placing each mover building on
one of them (an edge of a kind its build waits on) has its build step's why say that dependency was
taken out and that it builds against the newest published package.

Builds: design 47 H §748; lead answers H-A-53, H-A-107

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben 213668df49 R14: the queue's tools, runner_waiting and runner_place over the verb place
The seat verb place places a waiting pipeline ahead of its turn, written in the hand-act log first:
its running key now, over the bound, its waiting key deleted, its steps placed as at its turn with
wait-ended; a pipeline not waiting is refused. The tool runner_place asks it with the pipeline and
why; runner_waiting lists the waiting pipelines, lowest sequence first, from the state queue. Both
are in the manifest's tools.

Builds: design 47 H §748; lead answer H-A-53

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben bb930de377 R12: the queue's approval wait, stall and cap
A pipeline whose every step not ended is an approval asked of the operator leaves the bound: its
running key goes and the next waiting is placed; answered and still running, it is keyed running
at once, over the bound. After every placing, pipelines waiting with none running raise the finding
pipelines-stalled naming the first waiting, cleared once one runs. A start beyond
pipelines-waiting-cap is an ordinary waiting pipeline and raises queue-full naming it, cleared when
an end brings the waiting back to the cap. Both findings are the scope delivery's, the kind as id,
warnings with no owner.

Builds: design 47 H §748; lead answers H-A-14, H-A-36, H-A-52, H-A-106

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben bbdd1741fa R13: a newer waiting pipeline supersedes the older one's movers
When a pipeline is written waiting, each older waiting pipeline of its branch loses the movers the
newer one also moves (read from the queue's waiting keys and each pipeline by its key); one left
with no mover ends superseded, its waiting key deleted, saying wait-ended (how superseded) and its
pipeline-ended. A running pipeline is never touched and runs to its end. The queue test's fixture
is shared, its take-ins moving distinct modules.

Not built: H-A-53's why of a mover whose dependency was superseded out (asked of the lead: no field
keeps the movers that left).

Builds: design 47 H §748; ADR 0682 §7; lead answer H-A-53

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben 63bb53bb6b R11: at most pipelines-at-once pipelines run; the others wait in order
The runner's settings pipelines-at-once (default 1, from 1 to 8) and pipelines-waiting-cap (default
64) are written to files by the manifest and read at the start; its state queue holds queue.next,
waiting.<sequence> and running.<pipeline>. A start (a take-in's, a publish's, a hand start's, a run
on request's) judged against the running keys alone either runs, its running key written after its
pipeline, or is written waiting under the next sequence, its waiting key first, with no step asked,
saying pipeline-started and wait-held step pipeline on pipelines-at-once. Every end, a cancel's too,
deletes the running key and places the lowest sequence, which says wait-ended and has its steps
placed (a run's from its candidate's newest revision). At the start a running key whose pipeline
runs no more is deleted and the queue placed. The test runs' whole test sets pipelines-at-once 8, as
its candidates run side by side.

Builds: design 47 H §748; lead answers H-A-14, H-A-36, H-A-52, H-A-53, H-A-60, H-A-72, H-A-96

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben cf703c2a7b H-A-101: the hand verbs name the mover's module; a step not asked says its own end
rerun, accept and ask-again take the mover's module beside the pipeline and step (C-R4): a call
naming none is taken as the pipeline's one mover and refused on a pipeline of several, and a module
the pipeline does not move is refused; the tools runner_rerun, runner_accept and runner_ask_again
pass it. A step of a mover whose dependency did not build, placed not asked, now says its own
step-ended naming the dependency, so nothing ends silently.

Builds: design 47 H §746, §748; lead answer H-A-101

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben 1bd410522e R4 correction: a run on request is refused when its branch has no source revision yet
A run's pipeline puts in source the newest source revision of its branch (H-A-85); a branch whose
view holds none yet is refused, naming it, and nothing is written, never a pipeline of source 0.

Builds: design 47 H §746; lead answer H-A-85, H-A-83

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben 79e4688744 R16: a take-in.taken of the old form is refused by the strict decode
The runner's take-in handler decodes take-in.taken strictly by the seat's contract: an event
missing a field its new form requires (branch, source, call) is refused, said in one journal line
naming the subject and what it lacks, and ended. The cancel reads no old pipeline (they are
dropped at the clean state). Unit tests 84 to 85.

Builds: design 47 H §765; lead answers H-A-58, H-A-98

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben c9fd571e8e R15: pipeline-failed is one finding per failing mover
The finding pipeline-failed has scope delivery and id <module>.<branch>, one per mover whose
required step failed or could not run, naming the pipeline and the steps, owned by the commit's
author as before; that module's next passed pipeline on that branch clears it. Unit tests 84 to
84 (the newer-revision test replaced).

Builds: design 47 H §770; lead answers H-A-19, H-A-59

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben 8da18c37c5 R10: a publish starts only what its source's pipeline does not move
A package-published is heard in the running pipeline of the source revision that published it,
where its dependents wait (R7); every module the catalog half holds a kind-1 edge from the
package into that this pipeline does not move (a publish again of an older build, a dependent it
does not move) is a mover of one pipeline keyed <branch>.<source>.published.<package>.<version>,
at the publishing source's catalog revision and call. The dependents come from the edges the
runner holds: the runner asks outdated no more (its invoke leaves the manifest). A publish heard
before its branch's half is held is heard again once it is; the durable consumer delivers one
heard after a stop, the key written once. Unit tests 83 to 84.

Builds: design 47 H §747; lead answers H-A-19, H-A-52

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben c3d17f6b5a R7: a mover's build waits for its dependencies inside the pipeline
A mover with a kind-1 edge from another mover (a package) is placed once that mover's
package-published of the pipeline's branch and source is heard, written into the publishing
mover's published by compare-and-set; one with a kind-3 edge (a build module, an image base)
once that mover's build step passed, heard as the runner's own step end; toolchain edges first.
A publish of a mover of the running pipeline of its source starts nothing and asks no outdated.
A mover whose dependency's build ended without passing is placed with every step not asked.
Unit tests 82 to 83.

Builds: design 47 H §746 (the build order); lead answers H-A-51, H-A-83 (2), H-A-84

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben e5a79db912 R9: validate comes before composition, one run per pipeline
Each mover gets a validate step on the seat mesh-wants before its composition, its status from
the policy; one ask per pipeline that every mover's validate step reads (a mover placed later
reads it, its result too). A mover's composition waits until validate ends: asked once it
passed, ended not asked when it did not, so a manifest the validator refuses is never composed.
The step runs name the runner's seat as their asker. Unit tests 81 to 82.

Builds: design 47 H §745 (the runner's order); lead answers H-A-51, H-A-88

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben f9d403ffea R8: a mover's released version is heard from version-released
The runner consumes mesh-catalog.version-released and writes its version into the mover of that
module in the pipeline of the source revision built, on the branch the version was released for
(the registration's first watched branch), by compare-and-set, so pipeline-ended names the version
released. Unit tests 80 to 81.

Builds: design 47 H §746 (the released version per mover); lead answers H-A-52, H-A-62

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben a755925024 R4, R5, R6, R8: one take-in is one pipeline, its movers placed, ended and said per source revision
A take-in.taken with entries starts one pipeline keyed <branch>.<source> by compare-and-set, its
movers the entries; each mover's steps are placed from its own registration and entry, each step
and ask id naming its mover; a step end is matched to its mover's commit and fingerprint; the
pipeline passes when every mover's required steps passed, a required "nothing to run" counting
as passed. The movers get tiers from the delivery edges (kinds 2, 4, 5, 6; a cycle one tier,
said). pipeline-started and pipeline-ended are said on <branch>.<source>, the end once with per
mover its fingerprint, version, steps and tier, in tier order; waits on <branch>.<source>; step
events on <module>.<branch>.<commit>; no group-ended. Approval is one step per mover. A run on
request is one pipeline keyed <branch>.run.<id>, its source the branch's newest, members of one
branch only. A running pipeline is superseded no more. A composition step names the runner as
its asker. The seat's verb place is served, refusing every pipeline until the queue (R11, R14).
The seat list part takes no callers (H-A-66). Unit tests 77 to 80, integration 3.

Builds: design 47 H §746, §747 (run, start, a publish's key), §748 (a running pipeline runs to its end), §764 (group-ended, the key per module); lead answers H-A-3, H-A-35, H-A-51, H-A-52, H-A-53, H-A-66, H-A-70, H-A-72, H-A-83 (1), H-A-85, H-A-88

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben 10c806fe6f A4: a want names a version, never a part's digest or a keeping node
withKept names the released version alone; the want-parts reading
(Nodes.ReadsParts, WantParts, the node record's capabilities read for it) and
sayParts, which said why a want named no parts, go. The builder's parts and
keeping node stay read only to find a build's released version.

Builds: design 47 H §750, §764; H-A-37

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben c67bfcdc0f A3: the assigner keeps no order waits; the order on a machine is its node-engine's
The order waits go whole: orderwaits.go (order.<node>.<module>.<part> in the state
waits, their wait-held and wait-ended, the catalog entries read for a form change),
the package internal/acting, the want rule's acting edges (Module.Acting,
actingWaiting, ActingRuns, Nodes.Serves), the why record's acting reads, the release
how `now` and the order rows of assigner_waits, and the consumption of the indexer's
take-in.taken that fed the taken-in edge. assigner_waits and assigner_release keep
the outside waits and the puts.

Builds: design 47 H §771, §764; H-A-55

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben ff2211b3a1 A2: the assigner holds no want for an acting part's new version
The acting waits go whole: actingwaits.go (the waits acting.<node>.<module>.<part>,
their wait-held and wait-ended, the acting-cycle finding), the acting half of
internal/acting, the cycles among the acting waits and the node-engine read for them
(assigngraph's Cycles, HeldCycles, Engines) and the wait's bound on an acting edge;
the edge itself stays, kind acting, for the order it gives. assigner_waits and
assigner_release keep the order waits (A3) and the outside waits.

Builds: design 47 H §750, §764; H-A-70

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben e94a5d1256 R1: the test runs' whole test waits for its take-in's pipeline
It ended the build of main.3.app before the take-in had written it,
which passed only because the runner's resume swept the pipeline in
first; with no sweep the take-in alone starts it.

Builds: design 47 H §747

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben b53555c5bf A1: the assigner holds no want for a dependency's delivery
The version-delivered holds go whole: delivered.go (the delivery judgement,
the delivery waits, the asks to say a version delivered again), the states
delivery-waits and delivered-again, the tool assigner_delivered_again, the
consumption of mesh-wants.version-delivered and assigner_release's step
delivery. What it also heard and the want rule reads (version-released,
machine-away, machine-back) stays, in releases.go.

Builds: design 47 H §750, §764

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben 3ad2ac455a R3: the runner says no pinned or freed; a pipeline's pins are the indexer's
The runner's pins of a pipeline's catalog revision (pins.go, PinRunning at its
start, the pin at a start, a rerun and an ask again, the free at an end) go;
the indexer pins on the take-in's write and on pipeline-started, and frees on
pipeline-ended (its half of §749, written by the indexer's developer).

Builds: design 47 H §749, §763, §764

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben def28437ce R2: the runner hears only the ends of the steps it asked itself
A build seat's step-ended naming another asker (the assigner's composer build,
which names no pipeline) was read against the runner's store, refused and
terminated; it is now taken as nothing, read before any pipeline, and
acknowledged.

Builds: design 47 G §24, §69

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben 5009109fad R1: the runner starts no pipeline by sweep, only on the events that name one
A take-in starts its own entries' pipelines alone; neither it nor the runner's
resume starts a module whose fingerprint has no pipeline (StartUnstarted,
Unstarted removed, their test turned into its inverse).

Builds: design 47 H §747, §764

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:31 +01:00
jschoubben dad31f49c5 H-A-48: the own build and the pull-request candidates' leftovers go
Nothing of the one model reads which build the indexer runs: the take-in holds nothing for the
indexer a revision names and indexer_pending answers the state held alone, so FixOwnBuild, the
state own-build, the ask of the node-engine's composition and its invoke go. No pull request's
candidate is written any more, so what only it read goes: the member heads' packages
(candidatePublished), SameCandidate, headOf and CandidatesKey; and consumerSink with the state
consumers (H-A-80). The state taken stays: the view reads it. The run on request's candidate
stays (H-A-105 b). The manifest test holds the state and the invoke absent.

Builds: design 47 H §743 (holds nothing for the indexer), §764 (the indexer); H-A-48, H-A-80, H-A-102, H-A-105

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:28 +01:00
jschoubben 1a3664ad77 I10: the indexer's integration tests drive the one model
The whole test starts the indexer against an embedded bus with the gate's source-moved on its
kept stream and a durable per watched branch: a first revision with start true and no movers;
one revision per take-in carrying its movers, pinned pipeline.<branch>.<source> and said as
take-in.taken; the same source-moved given again said from the kept movers with no second
revision; pipeline-started pinning, a restart keeping a running pipeline's revision; a take-in
on a full store held, said once as take-in.pending and in the state held, taken again on the
indexer's own room once pipeline-ended frees a pin; another branch's held take-in leaving
main going on, skipped by hand with why in the hand-act log; a branch watched later bound on
registration-changed. The packages test takes a mesh-sdk commit in and names mesh-sdk and the
module requiring it, not the one requiring nothing of it. The toolchain test drives take-ins;
the tests of the forge messages, the verdicts, the pins events of the gate and the view moving
between take-ins (H-A-49, H-A-103) go. 7 integration tests (was 13).

Builds: design 47 H §743, §744, §749, §768; H-A-12, H-A-30, H-A-49, H-A-50, H-A-90, H-A-92, H-A-97, H-A-102, H-A-103

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:28 +01:00
jschoubben c2e4d7914a H-A-48: the tests read no source stamp the seat's modules value no longer has
C1d takes src and fp-src from the seat mesh-catalog's modules value, so the checks of their
absence are held by the type and go.

Builds: design 47 H §764 (the indexer); H-A-48

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:28 +01:00
jschoubben fd68792614 meshcatalogclient: an unreached entry is asked again, at most entry-asks times
An entry whose ask failed in transport is asked again when the followed branch says
catalog-revision and when the part's link opens again (AskAgain), at most Asks times (the
part's setting entry-asks, default 5); one more failure makes it unanswered, and
WriteEntryFindings writes the finding entry-unanswered, cleared by its answer or its release.

Builds: design 47 H (H-A-60, the entry asked again)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:28 +01:00
jschoubben 4611f263f3 H-A-48: the takeins ask keeps no field of the earlier take-in
The pending wait, the abandon, the merge by hand with its repository and sequence, and their
ask builders go; an ask naming only one of them is refused as naming no hand act.

Builds: design 47 H §744, §764 (the indexer); H-A-48

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:27 +01:00
jschoubben 1ece9449fd H-A-48, H-A-105: the builder-log index and indexer_take_in go
TakeIn, TakeInRepository, the catch-up, IndexRegistered and RetryUnread go: a module is taken in
only from a source revision, and the gate's gate_head_take is the one hand take of a head. The
manifest serves no indexer_take_in and names no catch-up tool beside the catalog revisions.

Builds: design 47 H §742, §764 (the indexer); H-A-48, H-A-105 (a)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:27 +01:00
jschoubben 8d2d490637 H-A-48: no source stamp on a module; the take-in's commit names it
srcOf and the Src and FpSrc stamps go with the source per merged message: a module's value and
its catalog entry carry where it was taken in by its commit alone.

Builds: design 47 H §764 (the indexer); H-A-48

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:27 +01:00
jschoubben e102f7dbc6 H-A-48: a pull request's seat definitions go; the trunk's alone are kept
keepPull, dropPull, ApplyVerdict and the pull form of the seat-definitions key go with the
pull and open messages and the checker's verdict; indexer_seat_definitions_again and
indexer_seat_definition name the trunk alone.

Builds: design 47 H §764 (the indexer); H-A-48

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:27 +01:00
jschoubben 204cf3e16a H-A-80: indexer_consumer goes with the state consumers
No ledger writes the state consumers any more, so the tool indexer_consumer, its reader and
the state's declaration go; the manifest test holds their absence.

Builds: design 47 H §764 (the indexer); H-A-80

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:27 +01:00
jschoubben 3447dd5f4d I6: indexer_pin_drop drops a pin by its key; the held asks are read
I6: indexer_unpin is renamed indexer_pin_drop and takes the pin's key <branch>.<revision>
and why: it drops every record's pin of that key, clears its finding pin-missing and the
removal rule then applies; a hand act recorded in the hand-act log before it is asked
(§765, H-A-57).

I5 follow-up: the asks of indexer_take_in_pending and indexer_take_in_skip were refused by
the ask reader (DecodeTakeIn named no held branch); they are read now, and
indexer_pending answers {held: [{branch, source, why, since}]}, since in RFC 3339, the
state held's form (H-A-102). The test drives each tool's ask through the reader.

Builds: design 47 H §765 (indexer_pin_drop), §744 (the held tools); H-A-57, H-A-97, H-A-102

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:27 +01:00
jschoubben 1b8f377cad I5: a take-in that cannot be written is held, said once and skippable
A source-moved the indexer cannot take in (the catalog store full, a read unanswered) stays
unacknowledged on its branch's consumer, so that branch's next waits while another branch's
go on; it is written in the new state held, one key per branch {branch, source, why, since}
(H-A-97), and said once per source as take-in.pending {branch, source, why}. A full store
sets heldFull, so RoomAgain says room once it has room, and the indexer's own room (H-A-50),
heard on its events consumer, takes every held one again, never a timer. indexer_pending
reads the state held; indexer_take_in_pending takes a branch's held one again now and
indexer_take_in_skip, with branch, source and why, acknowledges it unwritten, says
take-in.taken with no entries, skipped, by and why, and is recorded in the hand-act log;
both are asks in the state takeins. The held key goes at the take-in or the skip.

Builds: design 47 H §744; H-A-12, H-A-50, H-A-97

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:27 +01:00
jschoubben 9ee012bce5 I1: one durable consumer per watched branch hears source-moved
The indexer binds one durable consumer per watched branch on the stream of the gate's
source-moved, named <node>_<indexer>_<escaped branch> through mesh-sdk's
Account.NamedEventConsumer; it takes each message in with TakeInSource and acknowledges it
once its revision and take-in.taken are written, and leaves it unacknowledged when the
take-in fails. The watched branches are the registrations'; a newly watched branch's
consumer is bound on the indexer's own registration-changed, which the manifest now
consumes. A source-moved of the old form (no call) is refused for good with a journal line.

Builds: design 47 H §743 (one durable per watched branch), §765 (the old form refused); H-A-30, H-A-90

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:27 +01:00
jschoubben d40e922be4 I4: predefined is read from the take-in of the catalog's commit
The take-in of a source revision moving the catalogue repository reads predefined.json from
that commit's trees through the seat git (wholeAt) and rewrites the state predefined when a
key changes. The read was already the take-in's (I8's wholeAt); this test holds it at the
take-in, and fails when the take-in writes no predefined.

Builds: design 47 H §769

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:27 +01:00
jschoubben b4f0c3ec88 I3: a branch's first source revision is taken in with no movers
A source-moved with start true, the seed of a branch's first revision, keeps its revision
with every module's entry at the heads it names and says take-in.taken with no entries and
no pin; a later take-in's movers are judged against those entries.

Builds: design 47 H §768 (the indexer's half), §743 (no mover); H-A-19

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:27 +01:00
jschoubben abdd70d918 I2b: one catalog revision per take-in, <branch>.<source>, carrying its movers
TakeInSource takes a gate's source-moved in: the trees of each repository it moves at the
named commit through the seat git, the fingerprints of the modules registered for it, the
movers against the branch's newest catalog revision, and one revision <escaped
branch>.<source> for every branch, the trunk included, numbered by the source and written
once by read before write. The revision carries its movers, and a redelivery whose revision
is kept says take-in.taken again from them, recomputing nothing (H-A-92). It is pinned for
the take-in's pipeline as pipeline.<branch>.<source> in the same write when it has a mover,
none for a take-in with no mover. take-in.taken carries branch, source, revision, call and
the movers' entries alone, under a duplicate id of its branch and source (H-A-31). A
source-moved with no call is refused as the old form (§765).

Only a take-in keeps a catalog revision (H-A-49): the recompute, the build ends' imports and
the start's reconcile keep none, and KeepView, keepEntries, keepTrunkRevision and
PinPipelines go. Another branch than the first is taken in on its newest revision's view.

Builds: design 47 H §743, §749 (the pin in the take-in's write), §765 (the old form); H-A-31, H-A-32, H-A-49, H-A-92

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:27 +01:00
jschoubben d00ee48363 I2a: the movers of a take-in are the moved fingerprints and their importers
A take-in's movers are the modules registered for a repository the source revision moved
whose fingerprint differs from their entry in the branch's newest catalog revision, and
every module, in any repository, importing a package one of them publishes. A module of
another repository is no mover by its fingerprint alone; one with no build is none.

Builds: design 47 H §743 (movers); A-476a

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:27 +01:00
jschoubben 1e826ff008 I8, H-A-82: the earlier take-in goes; no delivered version is kept
I8: the take-in fed by the forge bridge's messages goes with B1's forgemsg: the FORGE
consumer and its handlers, the group end, the pending state with its keys, claims, dry
take-in and hand tools (indexer_pending, indexer_take_in_pending, indexer_drop_pending,
indexer_take_in_merge, kept again for the held take-in in I5), the catch-up by comparison
(kickBehind, TakeInBehind, sayUntaken, takeInHeads, kickCatchUp, CatchUp, merge-untaken),
the source numbering in memory (nextSource), the source verb's follow and Src stamping on
a source answer, the bridge's merged message call, the pull request candidates written
from pull and open messages, the checker's previews and verdict hearing. A repository's
trees at a commit are the internal whole (wholeAt), which ApplyMessage takes in; the dry
indexer stays for a run on request's candidate. The manifest drops the consumes of
forge.**, the checker's verdict and version-delivered, the reads of the checker's
previews and the invokes of open-pulls, bridge_merged_message and mesh-delivery.source.
RoomAgain says room when a take-in is held on a full store (heldFull, I5 holds it).

H-A-82: the fill of delivered versions into the edges goes: HearVersionDelivered, the
delivered.<module> key, the first fill's kinds 2, 4 and 6 from the placement and the
stream running, and outdated's kinds 2, 4 and 6; their entries read not yet delivered.

The tests of the removed paths go (index_test's candidate groups, source_test,
branch_take_in_test, previews_test, candidate_manifests_test, the FORGE handle tests);
the versions tests now hold kinds 2, 4 and 6 as declarations. The integration tests
still drive FORGE and are rewritten in I10.

Builds: design 47 H §743, §744, §764 (the indexer); H-A-48, H-A-82

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:27 +01:00
jschoubben ea28f39319 I7, I6 (the pins' events): no validation at the take-in; a pipeline's events pin its revision
I7: the indexer judges no manifest. The judge pass, its verdicts and unjudged states,
the events manifest-accepted and manifest-refused, the tools verdicts, indexer_verdicts,
indexer_judge and indexer_say_accepted, and the take-in's wait for the verdicts state
go; indexer_bus_state answers from the modules state at its mark. The seed writes
validate required in every policy. oldsections stays (H-A-79).

I6, the half that follows C-R: the gate's pinned, freed, heads-replaced and
pins-stated are no longer heard. A pipeline-started pins the revision it names under
pipeline.<branch>.<source>, its pipeline-ended frees it, each on a durable of its own
stream; kept revisions are judged against the pins the state holds, never a count
(made and pins-stated go). A take-in pins its revision once, for its one pipeline.
indexer_pin_drop (§765) is still to do.

The entry's pull goes (§763). The tests of the old take-in (pending, behind, pushed)
go with it, ahead of I8. The unit suite is green except manifest_test's check that
the watchman's and the grants part's invokes of the indexer's verdicts tools are
served: their removal is the contracts developer's (H-A-79).

Builds: design 47 H §743, §745, §749, §763, §764 (the indexer); H-A-48, H-A-49, H-A-79

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:27 +01:00
jschoubben 930d09cadc H-A-66: the indexer's revision verb, first views and seat-list part keep no callers
Every account may call every verb: the verb revision answers every caller, so its
callers list and the node-engine account's mapping go; the first-view tools take no
callers list and the tools bundle's env carries none; the seat-list part is made
without one.

Red only from the contract removals C1 and C3 (I7's manifest events, the gate's pin
events, the entry's pull), followed in the next commits.

Builds: design 47 H §752, §764 (every seat contract: callers); H-A-41, H-A-66

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:27 +01:00
jschoubben cbf1dbb15d I9: register, watch and the seed read no branch's protection
The forge's branch protection is no longer a condition of the mesh: register and watch
refuse only a reserved branch name, and the seed leaves out no module for its default
branch's protection and reads none.

The module compiles again only once C0 to C3's removals are all followed (H-A-66's
callers, I7's manifest events, the gate's pin events, the entry's pull); its unit
suite runs green from that commit on.

Builds: design 47 H §763 (G §5), §764 (the branch protection)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:56:27 +01:00
jschoubben f9e2dc38d8 W1: the watchman's whole test: a pipeline waiting behind another raises nothing
The indexer holds a source and takes it in, the runner writes its pipeline
waiting its turn (wait-held, step pipeline, on pipelines-at-once) ten minutes
back with no step asked, and the pipeline ahead of it stands: no take-in-waits,
no pipeline-stands and no head-untaken name the waiting one.

Builds: design 47 H §741, §748

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:51:07 +01:00
jschoubben 94d3f02f76 B-src: the builder's floor wakes on the indexer's take-in.taken
The seat mesh-catalog defines no manifest-accepted any more: the builder
consumes the indexer's take-in.taken in its place (module.json, names.go's
patterns) and wakes its floor on every one, looking at every module again as
before (versions.go, the wake take-in.taken). With the in-progress commit
before it the builder reads no source stamp and its untagged suite is green.

Builds: design 47 H §764 (the indexer: its events manifest-refused and manifest-accepted, with their reader); lead answers H-A-48, H-A-49, H-A-66, H-A-116 (hq 508faf0c)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:48:48 +01:00
jschoubben 11a22fdff7 X1: the checker goes: its module, its seat definition and its readers
The module mesh-delivery-checker goes whole with its manifest, and its seat's
definition leaves the seat list. The status view reads no tries: build_usage
answers no tries running and counts no step as a try. The grants part grants
main's accept subject to the builder alone. The tests name no checker as an
asker or a seat. The seat's generated packages, the indexer's readers and the
assigner's verdict constants go in the join's cleanup, once those branches
stand on this one (the lead, 2026-11-20).

Builds: design 47 H §764 (the checker (H1): mesh-delivery-checker whole); lead answer H-A-57 (hq f599b761)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:47:16 +01:00
jschoubben 90f53608bc B-src (in progress): the builder reads no source stamp
A module value carries no source stamp (C1d): ModuleOf takes none from the
entry's inputs, a build's claim is numbered per fingerprint naming no source
revision and no merge, and the log's started entry names none. The seat list's
parts take no callers and resolve no caller's holder (mesh-sdk's NewPart without
callers, SDK-C). internal/... is green; cmd/mesh-delivery-builder still hears
manifest-accepted (names.go:21, versions.go:192, module.json:57), which the
seat mesh-catalog no longer defines: its floor's wake is H-A-49's, asked of the
lead.

Builds: design 47 H §764 (the indexer: the field pull, the source numbering); lead answers H-A-48, H-A-66 (hq f599b761)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:43:10 +01:00
jschoubben 2bb08b9306 G1: the grants part's tests read no verdicts and no callers
The root package's tests and the part's whole test no longer write or read the
indexer's verdicts: a value whose verdict field says refused is composed as
ever (a module in a revision is accepted by being there), and a held module is
one whose manifest the part cannot read. The verdicts' first view row reads the
four first views; the no-verdict window and the want's newest build rows go; the
compare rows carry the denies every account now has, being granted every verb of
every seat; the seat list's again tool's caller row goes with the callers; the
captured nats manifest consumes catalog-revision, as the catalog's does, not the
retired manifest-accepted.

Builds: design 47 H §745, §752, §764 (every seat contract: the callers lists); lead answers H-A-66, H-A-79, H-A-113 (hq f599b761)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:39:46 +01:00
jschoubben ffb5c48dd2 SDK-C: a composer case carries no verdicts
The composer judges no manifest and the assigner's composition step sets
no verdicts, so Case.Verdicts goes with its words; a case carrying
verdicts was read before and is refused by a strict reader now.

Builds: design 47 H §745, §764 (the indexer: the validation at the take-in); lead answer H-A-112

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:28:59 +01:00
jschoubben 6b43adafca G1 (in progress): the grants part reads no callers and no verdicts
Every account may call every verb: the grants part reads no definition's
callers (callerOf, the verb and accept callers, admits) and grants every
module's account every verb of every seat (mesh.seat.*.tool.> and its
caller-named form), a sent store to every module invoking a verb of its
claimant's seat, and every queue's named ask to every asker. grants_callers
goes; grants_why_refused answers the bus's own verdict. The indexer keeps
no verdicts: their first view, events, invoke and the engine's read go, and
a want names its build alone (no newest). internal/... and cmd/... tests are
green; the root package's grants_test.go still reads the verdicts (rows at
grants_test.go:303-307, 741, 1184, 3700-3870, 4560-4615) and does not compile.

Builds: design 47 H §745, §750, §752, §764 (every seat contract: the callers lists); lead answers H-A-37, H-A-66, H-A-79, H-A-113 (hq f599b761)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:28:04 +01:00
jschoubben f8eea0000a V1: the view reads the H1 want, source, source-moved and held take-ins
A want counts as applied by its fingerprint and a motion event is keyed by
it; the want's newest and rule, and the state held back read from them, go
with the assigner's holds. A branch's source is {v, source, call, heads}
with no group, its source-moved is read by its source, and the delivered
event names no group. indexer_pending's held take-ins are said in the
tiers' pending words with their branch, source, why and since, naming no
module. The view reads no source stamp on a module. Its seat list, its
first-view tool answers and its manifest name no callers; its source invoke
reads call, not group.

Builds: design 47 H §737, §744, §750, §752, §764 (the gate's groups; the indexer's pending and groups; the assigner's holds; the callers lists); lead answers H-A-26, H-A-37, H-A-48, H-A-66, H-A-78, H-A-102, H-A-109 (hq 3433db0e)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:20:33 +01:00
jschoubben 9a55e6e8c0 C1d: the seat mesh-catalog's module and inputs carry no source stamps
The indexer stamps no source revision on a module (the take-in's commit
names it), so the seat mesh-catalog's state modules value and EntryInputs
lose src and fp-src, and the fixture rows their stamps. A module value or an
entry's inputs carrying either was read before and is refused now.

Builds: design 47 H §764 (the indexer); lead answer H-A-48

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:15:20 +01:00
jschoubben 78e169a8c6 C-R5: the runner's pipeline keeps the movers superseded out of it
The seat mesh-pipeline-runner's Pipeline gains superseded, the modules a
newer waiting take-in of the same branch took out of the pipeline, written
with the movers by compare-and-set, so the runner writes a mover's
build-step why from it at the pipeline's placing. A fixture row of a waiting
pipeline naming one failed to read back before the field was defined.

Builds: design 47 H §748; lead answer H-A-107 (hq fabb927f)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:11:18 +01:00
jschoubben f6163349af W1: the watchman reads the H1 take-in, the mover's entry and the want
The watchman follows the one model in one pass. Its take-in waits are the seat's take-in.pending
and take-in.taken, keyed <branch>.<source>, timed from the message's own time by the setting
take-in-bound (60 minutes by default), and seeded from indexer_pending's held take-ins; the group
bound goes. A taken-in mover's bus state is read from its catalog entry by fingerprint through
the seat mesh-catalog's verb entry, bus-state-overdue timed from the take-in. The manifest
verdicts and their findings, the head timing of source-moved, acting-part-late and
delivery-waits go, with their readers, consumes and the indexer_verdicts invoke. A want awaiting
its hand placement is not timed, and the want readers follow the H1 want. A record-opened is
heard on record-opened.<call>.

Builds: design 47 H §741, §744, §764 (the indexer: manifest-refused, manifest-accepted, the
watchman's findings; the assigner: acting-part-late, delivery-waits), §772; lead answers H-A-25,
H-A-37, H-A-49, H-A-70, H-A-78 (2), H-A-79, H-A-91 (2), H-A-94, H-A-95 (1), H-A-97, H-A-102

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:05:11 +01:00
jschoubben 5bf6fd9b01 graph: the refused cycle is shared code, read by the indexer and the validate step
RefusedCycle, with its running-version break and its path search, moves from the indexer's
internal/index into mesh-delivery-sdk/graph, so the assigner's validate step reads the same rule
the indexer's take-in does; the indexer calls the shared function. The rule's table test moves
with it; the indexer keeps its test of the trunk catalogues against the shared rule.

Builds: design 47 H §745; lead answers H-A-34, H-A-104 (2)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:00:13 +01:00
jschoubben 89e0926feb C-R4: the runner's rerun, accept and ask-again name the mover's module
A pipeline of several movers is never ambiguous: the seat mesh-pipeline-runner's verbs rerun,
accept and ask-again gain the optional input module, the mover's; a call naming none on a
pipeline of one mover is taken as that mover. Fixture rows of each verb's input name a module
and failed to read back before the field was defined.

Builds: design 47 H §746; lead answer H-A-101 (1)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:52:48 +01:00
jschoubben c94e8564e6 C-R3: the runner's queue keeps the pipelines running
The seat mesh-pipeline-runner's state queue gains the key form running.<pipeline>, value
{pipeline}, written when a pipeline is placed and deleted at its end, its cancel or its approval
wait, so pipelines-at-once is judged against the running keys alone. A fixture row reads the new
form; the generator refused it before the form was defined.

Builds: design 47 H §748; lead answer H-A-96

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:49:06 +01:00
jschoubben 969caea37f C3c: the seat mesh-delivery's owed acts keep no merge's ask or group
The Owed definition's fields ask and group were kept only for a merge, and the owed act merge
went in C3b; nothing reads them, so they leave the definition and the generated contracts. A row
of the client's test reads the definition and fails while either field is in it.

Builds: design 47 H §764 (the forge bridge: the merge act of a switched key); lead answer H-A-95 (2)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:48:23 +01:00
jschoubben be741a7a8f C1c: a catalog revision carries its movers
The seat mesh-catalog's CatalogRevision gains movers, the take-in's entries
({module, commit, fingerprint, repository}), so a redelivered source-moved whose revision is
already kept says take-in.taken again from them, recomputing nothing. The branch revision's
fixture names one mover; the generated fixture test fails without the field.

Builds: design 47 H §743; lead answer H-A-92 (hq 8c0b04e3)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:40:18 +01:00
jschoubben f79c0a7b78 C3b: the seat mesh-delivery's owed acts name no merge
The bridge performs no merge since the merge call (design 47 H §764), so the owed act merge
(OwedActMerge) leaves the seat's definition, its fixture and the generated contracts; the
bridge's tests no longer read a merge fixture to refuse. A row of the client's test reads the
definition's act enum and fails while merge is in it.

Builds: design 47 H §764 (the forge bridge: the merge act of a switched key); lead answer H-A-91 (3)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:39:29 +01:00
jschoubben 9fe6330d79 B4: the bridge's whole test says head-moved; bridge_heads reads the heads held
The bridge's whole test runs the program against an embedded bus as the node does: a start, a
merge, an admitted push to an unprotected branch and a restart after a move each give one
head-moved naming the head read through the seat git's branch and the head held before (start
true at a start); a head heard twice, a branch not watched and a restart at the head held give
none, and the bridge asks the seat git nothing but branch. Its bus permissions are composed for
the manifest as it now stands. The pull, open pull request, group and unprotected-branch tests
go; the owed test performs the gate's statuses once, after a restart and again by hand.

bridge_heads answers each key of the state heads with the head the bridge holds, read-only.

Builds: design 47 H §739 (how checked), §774; lead answers H-A-48, H-A-85 (1)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:34:07 +01:00
jschoubben 7ac48fd882 B2, B3: the forge bridge says head-moved and carries the one model
B2: on every branch-moved of a watched branch, and at its start for every watched branch's head,
the bridge reads the head through the seat git's verb branch, as a kept call that waits on the
holder's return while the branch is watched, and writes one head-moved (repository, branch,
head, before the head held in its state heads, start) on its stream forge; a head equal to the
one held writes nothing. It reads no pull request, no tree, no file and no protection: the
merged and pushed messages, their inputs and the state inputs, the call of git.pull, the finding
branch-unprotected with its held finding writer, and the ten-second redelivery go. A move whose
head cannot be read is left unacknowledged for the bus to deliver again.

B3: the pull-message path (Convert, the open pull requests at start and reconnect, the
forge-delete message), the groups (internal/groups' group part, forge.group.merged, end-asks,
bridge_groups, bridge_group_end_again), bridge_merged_message with the forge-made reader, the
checker's owed and the merge act of a switched key (with the switch's bookkeeping read) go, with
their consumes, invokes, states and requires. The gate's owed path stays (H-A-71), its catch-up
from the gate's verb groups gone with that verb.

The two meet in main.go and the package compiles only with both, as it did not since B1. The
unit suites pass; the whole test (integration) is rewritten in B4.

Builds: design 47 H §739, §764 (the forge bridge; the branch protection); lead answers H-A-23, H-A-27, H-A-48, H-A-71

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:31:04 +01:00
jschoubben 3560362330 C-W2: a step the assigner serves names its asker
The seat mesh-wants' StepRun gains asker, the seat name of the part asking the step (the runner
writes mesh-pipeline-runner), so the assigner names a step's progress with it. Optional in the
definition: the line names its writer, not that a step without it is refused. Both accept:step
fixtures carry it; the generated fixture test fails without the field.

Builds: design 47 H §745; lead answer H-A-88 (hq 2c6c7c03), H-A-41

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:27:41 +01:00
jschoubben 87e9084e15 C-R2: the runner's pipelines key a run on request; a mover keeps its heard publishes
The seat mesh-pipeline-runner's state pipelines gains the key form <branch>.run.<run>, one
pipeline per run on request, its movers the named commits' modules (it delivers nothing). Its
Mover gains published, the artifact references whose package-published (or, on a kind-3 edge,
whose build step's passed end) the runner heard at the pipeline's branch and source, kept with
the pipeline so a dependency's wait survives a restart. A fixture of the new key form with a
mover naming one heard publish proves both.

Builds: design 47 H §746; lead answers H-A-83 (1) (hq ae7fc40a), H-A-84 (hq main 0631f43f+)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:21:43 +01:00
jschoubben b75dcc947c C1b: the seat mesh-catalog keeps no state verdicts
With the validation gone from the take-in, the state verdicts, its value and the client's
helpers over it (VerdictsKey, TakeVerdict, VerdictWhy, ModuleVerdict, the codec) leave the
seat's contract; a module's own verdict field keeps its three states.

Builds: design 47 H §745, §764 (the indexer: the validation at the take-in); lead answer H-A-79

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:15:15 +01:00
jschoubben 630c099972 B1: the forge bridge's one message, head-moved
forgemsg holds one message per move of a watched branch's head: head-moved with repository,
branch, head, before and start, on forge.<owner>.<name>.<escaped branch>.head-moved, refusing
a head equal to the one held and any field it does not have (trees, base). The messages pull,
merged, pushed, refused and open, their trees, inputs, group and members, and the group's end
forge.group.merged go; owed.ended stays.

Builds: design 47 H §739, §764 (the forge bridge: merged, pushed, base, the group's end); lead answers H-A-27, H-A-48

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:13:15 +01:00
jschoubben f9fa0ec2b2 C-W: a want awaiting its hand placement is held
The assigner holds the want of a node whose node-engine does not state want:version in the
want's hold field, its words awaits-hand-placement; the client takes that hold beside a put's
and refuses a hold with other words.

Builds: design 47 H §772; lead answer H-A-73

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:09:23 +01:00
jschoubben 83d454217f steprun: the asker judgement goes; every asker's kind is taken
The step runner no longer reads the seat list for the callers a build seat's definition
lists, refuses an asker it does not name, or gives an ask back until the list says:
Puller.Callers, CallersFromDefinitions, SeatListCallers and the seat list reader's start
go, since no seat definition names callers and every account may call every verb. The
step is still keyed under the asker its subject names, and main's subject still takes
only a build, a run and the checker's check and recheck. mesh-delivery-sdk builds again
against mesh-sdk without seatdef callers.

Builds: design 47 H §752, §764 (every seat contract: the callers lists); lead answers H-A-41, H-A-66, H-A-71 (3)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:09:01 +01:00
jschoubben 4599d2e60f C-W: the seat mesh-wants: a want by version, pipeline and rank; pipeline-wanted; validate
A module want names its fingerprint and released version with the pipeline (<branch>.<source>)
and rank (its tier, from 1) it was written from, neither for a placement's build; parts, rule,
newest, kept-on and composed go, and the client checks a rank with its pipeline instead of a
composition and a rule. The node's own want is unchanged. The accepted step and its end take
validate beside composition. wanted gains pipeline; pipeline-wanted.<branch>.<source> says a
pipeline's wants once at their end, running or tier-late with the movers and machines not
running. version-delivered goes.

Builds: design 47 H §745, §750, §751, §764 (the assigner: version-delivered, the digests in a want); lead answers H-A-37, H-A-51, H-A-56, H-A-72 (6), H-A-75

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:05:15 +01:00
jschoubben b7b4087095 C-R: the runner's seat: one pipeline per take-in, its movers, the queue and place
The pipeline is keyed <branch>.<source> (and <branch>.<source>.published.<package>.<version>
for a publish), its movers {module, commit, fingerprint, repository, tier} carry what was
per module (version, widens, tests, over-budget); group goes, run, published, unlogged and
end-count stay; call and seq are added and the outcome gains waiting. Each step result
names its module and the step enum gains validate. pipeline-started names the movers;
pipeline-ended carries per mover its fingerprint, version, steps and tier. pipeline-started,
pipeline-ended, wait-held and wait-ended are said on <branch>.<source>; the step events and
run-started on <module>.<branch>.<commit>. A wait gains step pipeline and on
pipelines-at-once. The state queue holds queue.next and waiting.<sequence>; the verb place
takes pipeline and why. group-ended and its body go. The client builds and parses both
subject forms.

Builds: design 47 H §745, §746, §747, §748, §764 (the runner: group-ended, the key per module); lead answers H-A-35, H-A-36, H-A-51, H-A-52, H-A-53, H-A-72 (1) to (5)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:01:24 +01:00
jschoubben d24d6a0890 C2: a kept call's member names its base branch
So the forge module can say merge-called for what landed after a restart
without reading the forge again, each member of the state calls keeps the
pull request's base, read at judging.

Builds: design 47 H §766; lead answer H-A-71 (2)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:51:26 +01:00
jschoubben 5042d9c426 C-acts: the build seats' acting rules name no bound
acts stays as the declaration the graph's edges and tiers are built from; the
bound of the build seats' rule goes with the acting part's hold. The generated
contracts do not change.

Builds: design 47 H §750, §764 (the acting part's hold); lead answers H-A-57, H-A-70

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:51:01 +01:00
jschoubben 6e027de597 C3: the source revision's contract: source-moved per source, record-opened per call, heads
source-moved is said on source-moved.<branch>.<source> with v, branch, source,
call, start and heads [{repository, commit}], kept 30 days and 64 MiB on its
own stream; its wildcard has two tokens (H-A-26). record-opened is said on
record-opened.<call>; it and record-ended carry branch, source and call, the
milestone <branch>.<source>, no forge-made fields (H-A-25). The source value
carries source and call, the verb source answers call; the state heads keeps
each untaken head {head, since} by <repository>.<branch>. The states merges,
asks and turns, the verb groups, and the events approval-carried, pinned,
freed, pins-stated and heads-replaced go (H-A-28, H-A-48), with their helpers
in meshdeliveryclient.

Builds: design 47 H §737, §740, §749, §764 (the gate's states, groups and switch); lead answers H-A-23, H-A-25, H-A-26, H-A-28, H-A-33, H-A-48

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:49:32 +01:00
jschoubben f8bbde9627 C2: the merge call's contract: merge-pull takes pulls and by, merge-called, calls
merge-pull takes a list of one or more members {repository, number, head} and
by, judges no branch protection and answers once, at the call's end, the call
and each member's outcome {repository, number, state, commit|why} (H-A-21,
H-A-22); its caller id goes, and it names a timeout of 120 s (H-A-43). The
seat says merge-called on merge-called.<call>, kept 30 days and 64 MiB on
SEAT_git_merge-called, its body in bodies; the state calls keeps each call
with said (H-A-47). branch answers no protected.

Builds: design 47 H §734, §735, §736, §766, §767, §764 (the single-pull form, the protection judgement); lead answers H-A-21, H-A-22, H-A-23, H-A-24, H-A-43, H-A-47

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:44:23 +01:00
jschoubben f006ab50bc C1: the take-in's form is the lines' fields; policies gain validate
take-in.taken carries branch, source, revision, call, entries (one
{module, commit, fingerprint, repository} per mover, no pull), skipped, and by
and why for a hand act; take-in.pending carries branch, source and why; the
keys, kinds, merges, groups and the other fields of the earlier take-in go, so
readers pair a wait by <branch>.<source> (H-A-31). StepStatuses gains
validate before composition; the seat says no manifest-accepted or
manifest-refused.

Builds: design 47 H §743, §744, §745, §763 (G §476, §648), §764 (the indexer's manifest events); lead answer H-A-31

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:41:07 +01:00
jschoubben 8e5e5dbb42 seatgen: an identifier splits on ':' too, so want:version is a Go constant
The node-engine seat's enum value want:version must yield a parseable Go
constant; ':' splits as '-', '_', '.' and a space do. No existing generated
output changes (the generator's check of mesh-delivery-contracts is unchanged).

Builds: design 47 H lead answer H-A-64

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:36:37 +01:00
jschoubben ce6edcd9b9 C0: no seat definition names callers; the generator refuses one that does
Every account may call every verb (ADR 0682 §10), so the callers lists of every
seat definition and part of mesh-delivery-contracts go, and the generator, the
one reader of definitions in this repository, refuses a verb or accepted kind
that names callers instead of checking its forms. The generated contracts do
not change: the generator made nothing of callers.

Builds: design 47 H §752, §764 (every seat contract: the callers lists)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:36:30 +01:00
jschoubben bf642c45b7 mesh-delivery: the old hand-kept mesh-catalog contract copy loses the config-candidates layout (issue 1982; ADR 0681 §2)
The copy under contracts/go/seats/meshcatalog still held the layout, its key helpers, its constant and two fixture cases; nothing
in contracts/ or sdk/ uses them, and ADR 0681 §7's check greps the trunk for the name.

Builds: ADR 0681 §2 (mesh-sdk keeps no config-candidate layout; the contract keeps none), §7.
2026-11-19 23:05:21 +01:00
jschoubben 64ae24aef7 mesh-delivery: remove the indexer's state config-candidates and its readers (issue 1982; ADR 0681 §2)
The mesh knows no pull request (design 47 G, G-1 §38-39), so the indexer keeps no pull request's config declarations.
Removed: the code that writes the state (control_records.go: the candidate writes after a merge and for a pull
message), its bucket, view family (views.config-candidates) and read tool (indexer_read_config_candidates) in the
indexer's module.json, the view's tool indexer_config_candidates and its read of the indexer's tool, the state and its
fixtures in the seat mesh-catalog's definition (generated Go and TypeScript regenerated by seatgen). indexer_config_readers
no longer names an open pull request as a reader of a key. The state `predefined` stays.

Builds: ADR 0681 §2 (the indexer keeps no config candidate: state, read tool and view, the seat contract's layout; `predefined` stays), §1 (indexer_config_readers names no pull request).

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 22:47:44 +01:00
mesh-tools 0ea4b60dbd Merge pull request 'steprun: only runs that started count toward poison; every end of an ask is written, said and acknowledged (A-489, A-489a, A-489b, A-489c)' (#257) from fix/build-node-step-ends into main 2026-11-19 21:40:15 +00:00
mesh-tools 5da42d1775 Merge pull request 'Catalog versions: each module's version floor from its Go tags and its package holders, per module, as a kept call (A-490c..A-490i, §412)' (#260) from fix/catalog-versions-first-fill into main 2026-11-19 21:40:12 +00:00
mesh-tools 0639ec4bca Merge pull request 'Builder: build again a done trunk key whose version is unreleased, reserved afresh; a trunk build without its version fails (A-490, A-490b; carries the reservation takeover A-455..A-473)' (#259) from fix/builder-unreleased-build-again into main 2026-11-19 21:40:10 +00:00
mesh-tools ac833a48f8 Merge pull request 'publishconformance: the cases every package holder is held to for a publish with a digest and no parts (A-490, A-490a)' (#258) from fix/gitea-publish-by-digest into main 2026-11-19 21:40:02 +00:00
jschoubben d9596548f9 publishconformance: a version held under another digest is refused though reserved with no digest yet (A-490j, A-490a)
Builds: design 47 G A-490j, A-490a

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 21:39:21 +01:00
jschoubben 9a7cd5861d Builder: a published kept at a version whose recorded digests none matches raises the finding at once, the version taken and never released (A-490j)
Builds: design 47 G A-490j

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 21:34:58 +01:00
jschoubben 95b4b308ad publishconformance: the cases of a one-part publish made while the build runs, reserved with no digest yet among them (A-490j)
Builds: design 47 G A-490j, A-490a

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 21:33:46 +01:00
jschoubben b413949ea8 Catalog versions: the floor's finding clears on every exit of the fill, and the integration test shows the kept call asked again
FillFloor clears the module's call-unanswered finding and its call-since key on every exit but the end of its context (a release
gave the module a version, it left the trunk, the callee answered with a failure), as ADR 0668 §3 has: FloorModules never
picks the module again. The module's clock starts at its first unanswered try, not when the form gives up. The integration test
sets the form's bound to one second, waits for the module's call-since key in the state heard, and only then serves git.tags;
it fails with `return err` at the unanswered try. Unit cases for the three exits.

Builds: design 47 G §412, A-490g, A-490h, A-490i
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 17:42:56 +01:00
jschoubben 69d17f139f Catalog versions: a floor read is a kept call asked until it answers, one module at a time, and the indexer holds no timer
A-490i corrects A-490h: the growing-pause timer is gone (floorpause.go and the guard's exemption removed; ADR 0437 §8 stands).
Each module's floor is read on its own (FloorModules, FillFloor); a read is a kept call through mesh-sdk's form, asked again
at once when the form gives up, so it has no bound; the first unanswered try starts the module's clock and the finding
call-unanswered is written five minutes later and cleared on answer. The integration test leaves the forge unserved until
a delay, and the fill follows with no restart and no revision.

Builds: design 47 G §412, A-490c, A-490d, A-490e, A-490f, A-490g, A-490h, A-490i
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 17:36:05 +01:00
jschoubben 1175fef241 Catalog versions: the floor reads every package's holders too, asks again on a growing pause, and a floor entry takes its release
The floor of a module with no version is the highest among its Go tags and the versions each package holder answers through
its seat's verb versions (npm-package-registry, go-package-registry; the sdk's npm 0.1.18 above its Go tags 0.1.16). An
unanswered read is asked again on a growing pause (5 s, 15 s, 30 s, 1, 2, 5 min) until it answers, with call-unanswered five
minutes after the first. A floor entry holds no artifacts, so a package-published heard later at its version is recorded as
its release and says version-released. One whole-indexer integration test on a real bus with a stand-in seat git and holder.

Builds: design 47 G §412, A-490c, A-490d, A-490e, A-490f, A-490g, A-490h
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 17:33:06 +01:00
jschoubben d822259cfa Builder: the rebuild path passes Rebuild to the reserver, and a build-level test through the real reserver proves it (A-490b)
Builds: design 47 G A-490b, §369

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 17:11:52 +01:00
jschoubben ea4fe471e2 Catalog versions: fill the tag floor per module with no version, from the forge's Go tags
mesh-catalog.versions answered [] for mesh-sdk although the forge holds go/v0.1.12..v0.1.16: the first fill read only
builder_versions, so a module the builder held nothing of was filled with nothing, and the once-only key closed it. The
indexer now reads, for every module of the newest trunk revision the versions hold none of, every tag of its Go package
from the seat git's verb tags (repository of its catalog entry, prefix the package's directory + "/v", "v" at the root),
fills the highest as its version, at each start and each catalog revision kept, and raises call-unanswered after five
minutes when the forge does not answer.

Builds: design 47 G §412, A-490b, A-490c, A-490d, A-490e
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 17:11:15 +01:00
jschoubben ff7a27f36f Builder: a build again reserves above the catalog's highest alone, its own standing number no floor (A-490b)
Reserver.Reserve takes Source.Rebuild: this fingerprint's standing reservation is replaced (Took told) and is no floor; another
fingerprint's stays one. Tested against the real reserver, standing below and above the catalog's highest.

Builds: design 47 G A-490b, §369

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 17:10:15 +01:00
jschoubben 7de5814a26 publishconformance: the other digest does not contain the digest; the holds-nothing case checks the words not stored (A-490, A-490a)
Builds: design 47 G A-490, A-490a

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 17:09:16 +01:00
jschoubben dfdfd84efe publishconformance: the holder that holds the version under another digest refuses it as not stored (A-490, A-490a)
Builds: design 47 G A-490, A-490a (stays in mesh-delivery-sdk beside the build modules' conformance kit, §680)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 17:04:55 +01:00
jschoubben 68048619d9 Builder: a done key built again by hand reserves afresh above the released versions, never keeping the standing number (A-490b)
Builds: design 47 G A-490b, A-490, A-455, §369, §412

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 17:04:27 +01:00
jschoubben 8f17d59f5c Builder: a trunk build that reserves is never made without its version, and a done key whose version is not released is built again by hand (A-490)
Quick fix: loosen the refusal of builder_build_again for the one key. Thorough fix (built): a reservation that cannot be made fails the key
instead of building and ending done unreserved (the kind met three times on 2026-11-19), and builder_build_again takes a done key whose
version is not released, claims it as a new revision, keeps or makes its reservation and builds it whole so the build's own publish runs.

Builds: design 47 G A-490, A-417, A-473, §369

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 17:01:00 +01:00
jschoubben 50734000c3 Merge origin/main into the builder reservation takeover work 2026-11-19 16:59:19 +01:00
jschoubben 2bc9ea9377 publishconformance: the cases every publish holder is held to for a publish with a digest and no parts
Builds: design 47 G A-73, A-417, A-490

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 16:51:10 +01:00
jschoubben 7617dda5f6 steprun: an ask naming no recipe is not declined for its recipe
The runner names a step ask's toolchain by language and version; every node sat out every TypeScript step.

Builds: design 47 G §416 (A-104)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 16:27:26 +01:00
jschoubben 13db05ce60 steprun: the decline of a pipeline step is held by a test; RunsCounted cites A-489c
Builds: design 47 G §24; lead answers A-489a, A-489c

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 15:45:48 +01:00
jschoubben 334bc54767 steprun: an unread ask whose refusal cannot be written is given back; the unwritten-end and said-end cases assert what they claim; kit case RunsCounted
Builds: design 47 G §24; lead answers A-489a, A-489b

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 15:42:16 +01:00
mesh-tools 6f8ba0bf69 Merge pull request 'The seat-holder answer is read from the assigner's watched copy, so asking who holds a seat no longer takes 14 s (issue 1982)' (#256) from fix/1982-seat-holders-from-watched-copy into main 2026-11-19 14:41:47 +00:00
jschoubben 92196dde3a steprun: an ask on its last delivery is ended, every end is acknowledged, an unwritten end is given back (A-489a)
Builds: design 47 G §24, §25; lead answers A-489, A-489a

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 15:38:16 +01:00
jschoubben 16feb56fd4 steprun: PriorRuns reads a module's ReadSteps shape
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 15:24:37 +01:00
jschoubben 78adc23d70 steprun: only runs that started count toward poison; an ended ask is acknowledged and its poison end said (A-489)
The bus counts an ask given back before it ran as a delivery, so four asks were ended 'poison' having never run. Puller.Prior
(PriorRuns) counts the runs the step key says started. A poisoned pipeline step now says its step-ended, so the runner stops
waiting. refuseUnread, refuseAsker and the poison path acknowledge the ask once its end is written, not terminate it.

Builds: design 47 G §24, §25; lead answer A-489 (G-22-lead-answers-2.md)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 15:23:13 +01:00
jschoubben 79bca88c8a steprun: a build module whose steps cannot say a step's end fails its own test (conformance.StepEnds)
A step ask refused live with 'this build module says no step's end' (mesh-build-node set no SayStep). AskSteps.SaysItsEnds
and the kit case conformance.StepEnds refuse that where the module is built.

Builds: design 47 G §24 (Asked on a work queue, ended by an event)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 15:23:13 +01:00
jochen 5bca54bb59 assigner: the verb assignments with seats answers from the watched copy of seat-holders, falling back to a direct listing only while it cannot be read (issue 1982) 2026-11-19 14:32:37 +01:00
mesh-tools 1751bff172 Merge pull request 'A pipeline step's ask names its build seat's language; the toolchain stays keyed by the artifact's (A-488, A-488b)' (#255) from fix/ask-language-from-seat into main 2026-11-19 12:51:10 +00:00
jschoubben 2e03fcb875 A step ask's toolchain is read by the artifact's toolchain language, not the ask's
The ask's language names the seat (A-488), so the runner read the toolchain of node for a TypeScript step and none matched. Asked carries
the artifact's language, and the placement test holds a go and a TypeScript artifact to their seats and their toolchains.

Builds: design 47 G A-488, A-488b (hq 57c14047)
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 13:48:29 +01:00
jschoubben b3e52ecdef A pipeline step's ask names the language of the build seat it is asked of
stepAsk took the artifact's language word (typescript), which node-build-node's module refuses as unreadable (go, node, image). The
language is now derived from the chosen seat (buildstep.AskLanguageOfSeat), and the placement test holds every ask to its seat.

Builds: design 47 G A-488 (hq 25df48ad)
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 13:41:48 +01:00
mesh-tools 1eec825926 Merge pull request 'Every reader of the newest catalog revision reads the newest again when it is removed under it (A-487d)' (#254) from fix/newest-readers-again into main 2026-11-19 11:54:40 +00:00
jschoubben 04500fa29d Outdated says a trunk read that fails twice instead of leaving out its kinds 3 and 5
Builds: design 47 G A-487d (hq 61bf1215)
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 12:53:33 +01:00
jschoubben 900316e4bd The tool indexer_catalog_revision and the verb revision of a watched branch read the newest again
The default read of the tool and the newest revision of a branch other than the trunk use readNewestOf; a read by number keeps
failing loudly. One table covers every reader of the newest revision in the indexer program.

Builds: design 47 G A-487d (hq 61bf1215)
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 12:51:40 +01:00
mesh-tools 233824eeeb Merge pull request 'takein: the test's pending revision names a lost merge (TestTakeInEvents fails on main since A-476 b)' (#253) from fix/takein-test-sample into main 2026-11-19 11:51:17 +00:00
jschoubben 6d6caf20e1 takein: the test's pending revision names a lost merge, since A-476 (b) no longer counts a build it waits for
TestTakeInEvents failed on main since A-476 (b) dropped WaitsFor as a reason a pending revision holds; its sample and one
refusal case still named only that. Seen in main.1025.mesh-delivery-indexer, unit and integration.

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 12:50:53 +01:00
jschoubben 00b452e57b The readers of the newest trunk revision read the newest again when it is removed under them
ModuleInNewestView, SeedEntryHeld, entryOf, SeedModulesFrom, the first fill of the versions, the outdated tool's trunk read and the verb
revision without a kept view use readNewestOf; none of them holds keepMu.

Builds: design 47 G A-487d (hq 61bf1215)
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 12:48:14 +01:00
mesh-tools e952ab721b Merge pull request 'A read of the newest catalog revision reads the newest again when its revision is removed under it (A-487d)' (#252) from fix/catalog-revision-read-race into main 2026-11-19 11:47:37 +00:00
jschoubben 33143527f2 A read of the newest revision names the newest again while it is newer than the one that failed
Replaces the five tries: progress bounds the loop, the same revision failing twice is the read's failure. One helper,
readNewestOf, serves the kept trunk's reads, TrunkView and BranchView; a read by number still fails loudly.

Builds: design 47 G A-487d (hq 61bf1215), A-487, A-487b
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 12:17:40 +01:00
jschoubben 1dd16bc783 The kept trunk reads the newest revision again when the one named is removed under the read
The pin judge removes a trunk revision, its list and its entries, as soon as a newer one is kept; take-ins keep one every few
seconds, so the read of the newest revision failed with no such object and the first view of the catalog half never came.

Builds: design 47 G A-487, A-487b
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 12:10:51 +01:00
mesh-tools 7ba0eddd92 Merge pull request 'Catalog answers from its newest trunk revision in memory (A-479, A-487, A-487b, A-487c)' (#251) from fix/catalog-answers-from-memory into main 2026-11-19 10:48:58 +00:00
jschoubben 37dd3dac13 Merge fix/a479-catalog-answers-in-time (ea106ea8) into the catalog-answers-from-memory branch
Builds: design 47 G A-487..A-487c, A-479

# Conflicts:
#	modules/mesh-delivery-indexer/cmd/mesh-delivery-indexer-tools/catalog.go
#	modules/mesh-delivery-indexer/cmd/mesh-delivery-indexer-tools/main.go
2026-11-19 01:24:39 +01:00
jschoubben 533a9e4ca9 Revision, module and provides answer from the held trunk revision; a failed re-read is said as behind
KeptTrunk also holds the newest revision and its entries, and the manifests the entries carry by digest.
The verb revision asked of the trunk's newest and the manifests the verbs module and provides read come
from it, with no read of the bucket or the manifests state; a candidate, a branch and an older number
still read the bucket. A failed re-read says the view is BEHIND and the next heard catalog-revision
reads again. The follower's state is named catalog-half.

Builds: design 47 G §421, lead answers A-487, A-487b, A-487c (03-DESIGN/01-to-be/47-milestones/G-22-lead-answers-2.md)
2026-11-19 01:19:32 +01:00
jschoubben efd8c7b34f Catalog half reads its own objects at the start and on the heard catalog-revision; no invoke of its own seat
KeptTrunk reads the newest trunk revision from catalog-revisions once at the start (a follower of the
bundle's views.Reader, adopted on the seat's event catalog-revision) and re-reads once for each heard
event of a newer trunk revision; reads list nothing. The invoke seat:mesh-catalog.revision and the
meshcatalogclient follower are removed; the consume stays.

Builds: design 47 G §421, lead answers A-487 and A-487b (03-DESIGN/01-to-be/47-milestones/G-22-lead-answers-2.md)
2026-11-19 01:04:33 +01:00
jschoubben 80cfaa175f Catalog answers from the newest trunk revision held in memory, and module reads one module
The tools bundle's view of the trunk (KeptTrunk) is made from the half of the catalog its own follower
of the seat holds (meshcatalogclient.WireCatalog on a views.Reader: the newest revision once at the
start, again on the seat's event catalog-revision), once per revision, and says each read with its
revision, module count and time. A read no longer lists catalog-revisions or fetches the newest
revision object. The verb module reads the one module it is asked (CatalogRead.Module). The manifest
consumes mesh-catalog.catalog-revision and invokes seat:mesh-catalog.revision for the follower.

Builds: design 47 G §421, lead answer A-487 (03-DESIGN/01-to-be/47-milestones/G-22-lead-answers-2.md)
2026-11-19 01:02:43 +01:00
mesh-tools 16b795af70 Merge pull request 'Pipeline runner: a tool for every seat verb no tool reaches (A-486)' (#250) from fix/runner-verb-tools into main 2026-11-18 21:37:19 +00:00
jschoubben 59ca36e55b G1: tools runner_start, runner_run, runner_accept, runner_ask_again over the runner's seat verbs
Each tool asks its served verb with the same arguments and answers its answer; the verb records the hand act, as for runner_rerun. Declared in the manifest.
The seat has no verb release: no tool for it.
Lead answer A-486 (G-22-lead-answers-2.md): tools are how a module is spoken to.

Builds: design 47 G §83, §84, A-486
2026-11-18 02:22:54 +01:00
mesh-tools 09be0bc27f Merge pull request 'Judge: a process's own secrets belong to the account it runs as (ADR 0680)' (#249) from fix/adr0680-credential-owner into main 2026-11-18 01:18:50 +00:00
jschoubben 3a47cccbee Judge: a process's own secrets belong to the account it runs as, whatever that account (ADR 0680)
The refusals of root and the operator account as an own secret's owner and as a bus process's account end; the
secrets-owner is held to the accounts an own secret's owner is; a process naming an own secret (a word equal to its
path) it runs neither as the owner of nor as root is refused, container modules excepted (lead answer A-485).
Restic's captured manifest is re-captured from mesh-catalog cd3b8fe8 by CAPTURED's recipe.

Builds: ADR 0680 §2, §3, §4; lead answer A-485
2026-11-18 02:11:47 +01:00
jschoubben ea106ea8b9 A-479: the seat mesh-catalog's verbs answer from memory, one read of the trunk view per call
The tools bundle's verbs module, modules, provides and dependents read the modules and the module graph key by key from
the newest trunk revision, and each key listed the whole catalog-revisions bucket again (6 s per call at 11 000 objects,
35 s with 12 callers); seat-definitions read its state once per seat. The view is read once per call (SourceValues), the
seat definitions come from a watched copy, a manifest is read once by its digest.

Builds: design 47 G (the seat mesh-catalog's verbs served by the indexer's tools bundle; ADR 0604 §2, ADR 0580 clause 1)
2026-11-17 22:43:08 +01:00
jschoubben ae91c7e73a Builder: remove Republisher.Ended, which nothing calls since the publish item asks at a build's end (A-457a, A-473)
Builds: design 47 G A-457a, A-473
2026-11-17 21:26:46 +01:00
jschoubben 378853a97d Builder: a late look that numbers a done build with no reservation says so aloud and names builder_reserve_done (A-455, G §349)
Builds: design 47 G A-455, A-473, §349
2026-11-17 21:23:37 +01:00
jschoubben 33e5c3a105 Builder: tests that fail without the round-2 changes (publish item kept with its artifacts published, asked at the build's end and at the start, unreadable plan)
Builds: design 47 G A-456b, A-457a
2026-11-17 21:22:31 +01:00
jschoubben 91f3ef809c Builder: remove the setting republish-max-versions, which nothing reads since A-457a
Builds: design 47 G A-457a
2026-11-17 21:22:31 +01:00
jschoubben 9e793e0142 Builder: review round 2 of the publish items and the release record (A-456b)
QueueDone removed; an item is deleted only with its release, drop or takeover; releases kept
one key per module (released-kept, 16); a plan that cannot be read ends the step could not run;
the wiring of the items to the reservations and the re-ask watch is tested.

Builds: design 47 G A-456b, A-457a, A-456a
2026-11-17 21:22:31 +01:00
jschoubben 65c4dcbf73 Builder: a version's publish is a publish item of the re-ask state, tried with a growing pause until its release (A-457a)
Asked when the build ends and at the start, deleted by the release, ended loudly after publish-tries
tries and readable in builder_publish_queue; settings publish-pause, publish-pause-max, publish-tries.
The publish no longer waits on running or manifest-reads-changed.

Builds: design 47 G A-457, A-457a, §588
2026-11-17 21:22:31 +01:00
jschoubben 43ec4017be Builder: a released build counts as reserved for the build step (A-456a)
Builds: design 47 G A-456a, A-456
2026-11-17 21:22:09 +01:00
jschoubben ab8a8ddfc4 Builder: a build step passes a reserving build only with a version reserved for its fingerprint (A-456)
Builds: design 47 G A-456, §369, §588, A-455
2026-11-17 21:22:09 +01:00
jschoubben 22f252251c Builder: test the reserve-done act, its reasks dispatch and its tool (A-455 review round 1)
Builds: design 47 G A-455, §369, §588
2026-11-17 21:22:09 +01:00
jschoubben bec4d43da6 Builder: a build takes over an older unreleased reservation; builder_reserve_done reserves for a done build
A trunk build reserving while its series is reserved by an older build never
released drops the older reservation's bound and finding and says so in the
journal. builder_reserve_done (a hand act, reasks mode reserve-done) reserves
the series' next version for a done trunk build that reserved none, with the
done key's digests, and queues its publish as builder_publish_again does.

Builds: design 47 G A-455, §369, §588
2026-11-17 21:22:09 +01:00
jschoubben d006132c2a A-476 (b): the watchman and the view no longer name an indexer build a revision waits for
A pending revision now holds a lost or unread message or a refusal; the watchman's finding and the view's wait say so, the take-in
event no longer requires WaitsFor (old values still decode), and the hand take-in comment loses the build.

Builds: design 47 G A-476 (b)
2026-11-17 20:37:32 +01:00
jschoubben 763d6a107a A-476, principle 4: indexer_take_in_pending takes a pending revision in again, and a group
A revision whose message is unread or lost, or held for room, has a hand recovery; its description says nothing of an indexer build.

Builds: design 47 G A-476
2026-11-17 20:34:49 +01:00
jschoubben a79b811113 A-476 r1: no merge waits for the build the indexer runs; leftovers of the validation and the hold go; a commit's scope is decided inside the recompute
ErrOwnBuildUnknown, its say and the own-build-unknown wait, TakeIn.Unknown and Failed go; the build only names the writer.
indexer_take_in_pending takes only a group in. The node-build-go accept.check and output invokes go. A module of another
repository stays as held inside of(), so a base of this repository's module is not given a value that is never written
(A-476 c, A-476a); one case in the toolchains test proves it.

Builds: design 47 G A-476, A-476a
2026-11-17 20:33:52 +01:00
jschoubben 40b6ced375 A-476a: a commit moves its own repository's modules and the importers of what it moved; A-471 toolchain test data
The recompute of a merge leaves a module of another repository as held unless its imported package versions changed
(ADR 0593 §3 stands). TestIndexerCountsOnlyThePlacedBuildNodesToolchains reports language versions (A-471).

Builds: design 47 G A-476a, A-471
2026-11-17 20:22:55 +01:00
jschoubben 9768d0b67d A-476: the take-in asks no validation, holds for no indexer build, and moves only its repository's modules
(a) validation_wait.go and validate.go go with the validation ask, its end consumer, indexer_validate_again and
Pending.Validation; (b) evaluate always takes the revision in with the build the program runs (holdFor and the build
comparison go); (c) a merge's recompute writes only the modules registered for its repository.

Builds: design 47 G A-476 (a), (b), (c)
2026-11-17 20:20:45 +01:00
mesh-tools 0adcfbbbdb Merge pull request 'A-471: a build toolchain is agreed by its language version, not its patch' (#248) from fix/a471-toolchain-language-version into main 2026-11-17 14:56:46 +00:00
jschoubben 109a3e1e49 A-471: buildrun and refusal texts name the language version
buildrun tests expect the agreed toolchain as ToolchainAgreement gives it; the guard's
refusal and a decline name the language version alone.

Builds: design 47 G A-471 (G-22-lead-answers-2.md)
2026-11-17 15:53:05 +01:00
jschoubben a66583236a A-471: a toolchain is agreed, reported and named by its language version alone
A build node whose installed patch differs from the ask's takes the ask: one shared
comparison in mesh-delivery-sdk buildstep (LanguageVersion, SameToolchainVersion),
used by the agreement (indexer, builder, checker), a build node's step guard and ask
check, and the builder's digest list. A fingerprint names the language version, so
every module's fingerprint changes once.

Builds: design 47 G A-471 (G-22-lead-answers-2.md)
2026-11-17 15:53:05 +01:00
mesh-tools 80a7061efa Merge pull request 'G-24 tests on main: the assigner hears presence once; grants composes each module's consumer from its own subjects' (#247) from fix/g24-tests-on-main into main 2026-11-17 14:35:31 +00:00
jschoubben 10d87dcc77 mesh-grants: a module's consumer is composed from its own subjects, not from its account's wide grant
ConsumerFor drew its filters from PermissionsFor, which since every account may subscribe to every subject (e1476cfd) is ">": no filter
named an event, so no module got an account consumer on EVENTS. The scoped permissions give them again. The integration subtests that
read each account's own subjects run with the wide grant off, as the unit tests do.

Builds: design 47 G A-434 (G-22-lead-answers-2.md: every account may do everything, the mechanisms stay whole), the grants part's account consumers (ADR 0561 §6)
2026-11-17 15:31:00 +01:00
mesh-tools 1cd984a4c7 Merge pull request 'A-473: the builder asks the tagged publish of a reserved version when its build ends' (#246) from fix/a473-builder-publishes-at-build-end into main 2026-11-17 14:09:34 +00:00
jschoubben b31924a2f5 A-473: the builder asks the tagged publish of a reserved version when its build ends
Reserved build ends (built-at set, every digest known) now queue that version at each
artifact's registry seat holder and drain it, as a holder's running does.

Builds: design 47 G A-473 (design 51 Publishing, A-417)
2026-11-17 15:06:38 +01:00
mesh-tools 7654838182 Merge pull request 'A-472: a pipeline's end waits on no other part' (#245) from fix/a472-runner-end-waits-on-nothing into main 2026-11-17 14:00:25 +00:00
jschoubben 3f51d83147 Runner: widens-read-bound and revisions-kept are the module's settings (A-472a)
Declared in module.json's config and written to state files as test-step-bound is; runner_cancel keeps its note.

Builds: design 47 G A-472a
2026-11-17 14:59:25 +01:00
jschoubben 0be2b3d01a assigner: the watchman's machine-away and machine-back have one hearer, the world's, so a durable on their streams no longer splits them
The composition step's own hub handler for machine-away and machine-back shared the durable of hearDelivery on the kept streams, so
each event went to one of the two and a machine away was often not known away to the delivery judge. The step now asks the world.

Builds: design 47 G §389, §64
2026-11-17 14:57:12 +01:00
jschoubben 871f75acd3 Runner: a pipeline's end waits on no other part (A-472)
The runner keeps each catalog revision it read, bounds every read widens makes to 5 s and says each read's duration, failure or cut in the journal and in could-not-run; runner_cancel reads the pipeline after an ask that did not answer.

Builds: design 47 G A-472
2026-11-17 14:55:27 +01:00
mesh-tools 4b75791d3d Merge pull request 'G-24: one composition run per candidate and machine, one test run per level, every reading step timed' (#244) from fix/47-G-shared-runs into main 2026-11-17 12:15:35 +00:00
jschoubben 4205f63786 Merge branch 'fix/47-G-shared-runs-watchman' into fix/47-G-shared-runs 2026-11-17 13:14:44 +01:00
jschoubben 2438f4a108 Merge branch 'fix/47-G-shared-runs-runner' into fix/47-G-shared-runs 2026-11-17 13:14:44 +01:00
jschoubben 9081966682 assigner: a case holding that a take-up says an end again under the open run's ask, a first end under the ask's id (A-470q)
Builds: design 47 G §719; A-470q.
2026-11-17 13:12:57 +01:00
jschoubben 16cb874ccc watchman: the integration test proves the end of a run's ask begins a test step's clock again (W1)
Builds: design 47 G-24 §732, §733 (watchman case)
2026-11-17 13:10:25 +01:00
jschoubben 20d6a68bfb assigner: a reader that leaves a run not yet taken, or whose place a rerun takes, has its wait ended superseded at once (A-470u)
Builds: design 47 G §727, §723; A-469y, A-470u.
2026-11-17 13:09:18 +01:00
jschoubben 21bef6c044 assigner: a drop ends each reader whose end is owed, once, and moves no reader (A-470r)
A carried reader that ended passed keeps its verdict; a reader marked rerun is ended by the drop alone, not again by the run's
move.

Builds: design 47 G §728; A-470r, A-470m.
2026-11-17 13:07:21 +01:00
jschoubben ae105b4631 runner: test 109 reads a step's end said again from EVENTS through a durable consumer
The runner keeps no message id on its step events (A-470t), so the bus's deduplication drops no end
said again (A-470q); test 109 now reads the tools' unit step-ended from the stream through a durable
consumer, its first end failed and the end said again by the move passed, both kept.

Builds: design 47 G §727; A-470d, A-470q, A-470t
2026-11-17 13:06:46 +01:00
jschoubben b58a8b2e7f assigner: an end said again is published under a message id naming the run that makes it say again, so the bus never drops it (A-470q)
A move names the moved run's ask, a take-up of a reader that ended the open run's, a drop the dropped run's; a first end keeps
the ask's id. Test 108 reads the ends through a durable consumer, as the runner hears them.

Builds: design 47 G §727; A-470d, A-470q.
2026-11-17 13:06:36 +01:00
jschoubben 533a076eb3 runner: test 109 asserts a queued ask has no bound in the state bounds
The case of a test run waiting with its holder present was asserted just after placing, so a
five-minute bound put back on the ask failed no test; test 109 now reads the state bounds after the
asks are put and holds only drops' keys there.

Builds: design 47 G §647 (as A-466y amends it), §535
2026-11-17 13:05:11 +01:00
jschoubben 4e33533bd0 assigner: a case holding that an end names its run's ask, so a replaced run's late end ends nothing (A-470n)
Builds: design 47 G §719; A-470n.
2026-11-17 13:04:19 +01:00
jschoubben 1f344bd47c assigner: a step asked again that joins a run not yet taken says its wait held, as join does (A-469y)
Builds: design 47 G §727; A-469y.
2026-11-17 13:04:02 +01:00
jschoubben 5b8fa23a8d watchman: the integration test seeds steps through the runner's stands verb; its findings name the runner's verbs (W1)
Builds: design 47 G-24 §731, §732, §733 (watchman case); A-469p
2026-11-17 13:03:57 +01:00
jschoubben ed78003b23 assigner: a composition reader names when its step said its end, so a take-up says no end again for a carried reader that passed (A-470l, A-470m)
The step's end, once said, is written on its reader in each run of its candidate naming it, by compare-and-set; a rerun's run
carries it with the reader; the take-up at the start skips a reader that ended and is not marked rerun.

Builds: design 47 G §719, §727; A-470l, A-470m.
2026-11-17 12:50:38 +01:00
jschoubben 20e966b9cd contracts: a composition reader names when its step ended, so a take-up tells a reader that passed from one that joined later (A-470m)
Builds: design 47 G §719; A-470l, A-470m. Generated by seatgen from the mesh-wants definition.
2026-11-17 12:47:39 +01:00
jschoubben 7697ef5988 assigner: a run's bound holds its ask, armed by compare-and-set, and its end comes before the input's delete (A-470n, A-470o, A-470p)
A bound was armed by a delete and a create with no revision, holding nothing, so a late ask-taken or
step-progress of a replaced run armed a clock that later ended the run asked next, and an expiry heard
after the bound was armed again ended a run that kept saying progress. A bound key now holds its run's
ask, published at the key's latest revision with its own time to live, and is deleted at its own
revision when the run read again no longer names that ask; a late signal moves nothing and is
journaled; an expiry ends the run only while its bound is still absent when read again and the run is
taken (bound.) or untaken (untaken.), the untaken expiry's readers said superseded as the key is gone.
A step-ended's run end is written before the kept input is deleted; a failed delete asks the event
again, whose redelivery finds the run ended and still deletes the input.

Builds: design 47 G §720, §719; A-470n, A-470o, A-470p
2026-11-17 12:39:12 +01:00
jschoubben 768213b816 Merge branch 'fix/47-G-shared-runs-watchman' into fix/47-G-shared-runs 2026-11-17 12:30:47 +01:00
jschoubben f9dd20e86d Merge branch 'fix/47-G-shared-runs-runner' into fix/47-G-shared-runs 2026-11-17 12:30:47 +01:00
jschoubben a96f873e21 runner: test 109, the test runs whole against the real bus
The runner whole against an embedded bus: one unit and one integration run per level read by both
artifacts, a failing run counted once, a rerun moving the other reader and not the accepted one, a
restart's take-up, progress past the bound, a replaced reader, a silent ask ending could not run with
its readers and its ask dropped, a second revision's own runs, a seat with no holder failing its
pipeline at once with its other steps not asked, test-runs and test-runs-drop over the bus, and the cap.
The finding writer's stream is hosted, as on the mesh.

Builds: design 47 G §733, §724, §725, §726, §727, §728, §535, §647; A-468f, A-470f, A-470g, A-470h, A-470i, A-470n
2026-11-17 12:30:19 +01:00
jschoubben ab9d9604b4 runner: a run's bound holds its ask, armed by compare-and-set, and its end is written before the step's finding (A-470n, A-470o)
A bound was armed by a delete and a create with no revision, so a late ask-taken or step-progress of a
replaced run could arm a clock for the run asked next, an expiry heard after the bound was armed again
ended the run, and a step-ended's run end waited behind its finding's event (3 s in test 109, past its
bound). A bound key now holds the run's ask and is published at the key's latest revision with its own
time to live, read against the run after it is written and deleted at its own revision when the run no
longer names that ask; a late signal moves nothing and is journaled; an expiry ends the run only while
its bound is still absent when read again; the run's end is written as its step-ended is heard, before
the finding.

Builds: design 47 G §720, §725, §726; A-470n, A-470o
2026-11-17 12:28:26 +01:00
jschoubben 2a90323af3 runner: no write of a test run acts on a read made before its latest change
The age and test-runs-drop deleted a run's key whatever was written after their read, an expiry or the
last reader's leave ended whatever run the key held by then, a rerun answered a write between its read
and its write as an error, and a step-progress heard as its run ended wrote a clock that later ended
the run asked next. A delete of test-runs is now a compare-and-set at the revision read, retried from
the latest read; a run's end ends only the run under the ask its caller judged; the last reader ends
the run in its own leave; a rerun writes its new run from the latest read; a clock is read against the
run after it is written, and a clock of a run not taken ends nothing.

Builds: design 47 G §725, §726, §727, §728; A-469l, A-469z, A-470d
2026-11-17 12:23:40 +01:00
jschoubben 00e1588ef9 assigner: no delete of composition-runs lands on a value newer than the one it judged
Every value write of the state was already a compare-and-set from the latest revision, retried on
conflict; the deletes were not. The sweep and the drop deleted a run's key whatever it held, so a
rerun's run replacing the key between the read and the delete was lost; the end of a run, the
ask-taken and a rerun deleted bound keys a newer run of the key may have armed. Each delete is now
at the revision just read, while the key holds the run it was judged from, judged again on a
conflict (the kind the runner's test 109 met in test-runs).

Builds: design 47 G §719 (readers added and removed by compare-and-set; the key deleted after composition-runs-kept), §720 (the bound keys)
2026-11-17 12:23:38 +01:00
jschoubben a439b8da47 runner: a carried reader with rerun false says no step-ended again at a take-up (A-470l)
The runner's take-up of a rerun's test run already ends only the readers marked rerun and the open
ones (endReader); this table case holds it there, so a reader that passed is never said again.

Builds: design 47 G §725 (take-up), §727; A-470d, A-470l
2026-11-17 12:16:01 +01:00
jschoubben a2f4e8b499 assigner: the running builds whose manifest is not read are said once per change of their set
The assigner said the same list of about 100 modules every two or three seconds, once per
pass (live on the stable node since 2026-11-17 11:02 CET, the second meeting); it now says
the list once each time it changes. Why their manifests cannot be read is the builder's
stream of build ends, which holds no end of a build made before 2026-11-11, said apart.

Builds: design 47 G G-23 (the assigner's long line, met a second time)
2026-11-17 12:11:38 +01:00
jschoubben 8e95c2486f assigner: a composition run's request names the revision's modules with no fingerprint (A-470j)
A module whose build can never be made left its machine not judged, so every step of the
candidate could not run; the case now carries none, the revision's words for each module it
gives no fingerprint, for the composer to blame that module alone.

Builds: design 47 G §721, §722; A-470j, A-470k
2026-11-17 12:08:44 +01:00
jschoubben 1878607208 assigner: test 108, the composition runs started whole against the bus
One test of the whole assigner: one run per candidate and machine read by every step, a
module's fault failing only its own steps, the bound of owed progress, the untaken ask, a
step-ended after the bound ignored, a rerun moving the reader that did not pass, a
superseded step leaving its run, a restart taking a run up by its ask, the drop verb and
the cap.

Builds: design 47 G §733 (test 108); A-470f
2026-11-17 12:07:56 +01:00
jschoubben 930a407a3a assigner: a composition run is found by the keys its state's watch handed, beside the listing
A bucket's listing misses a key that is being written at that moment (97 of 300 listings on
an embedded bus while one key was updated), so a run's end, its ask-taken or a moved reader
could miss the run being written. Every lookup of composition-runs now takes the keys the
state's own watch handed beside the listing.

Builds: design 47 G §719 (the assigner's own watch of its state), §720, §727; A-468, A-470d
2026-11-17 12:07:56 +01:00
jschoubben eadfcd4cf8 composer: a case names the modules the revision gives no fingerprint, with its none words (G-24 H3)
The assigner fills it from the revision; the node-engine's composer reads it alone to tell a build that can
never be made, and judges the machine with that module held instead of leaving it not judged.

Builds: design 47 G §721, §722, A-470j, A-470k
2026-11-17 12:01:12 +01:00
jschoubben 19fbc076d6 runner: test-runs is answered by the process, its fill said against test-runs-cap-mib (A-470g, A-470i)
The bundle said test-runs' fill against the bucket's 64 MiB ceiling, a cap that refuses nothing; the
process, which holds test-runs-cap-mib and judges it, now answers the verb test-runs, its fill's cap
being that setting, and runner_test_runs calls the verb.

Builds: design 47 G §728, §725 (the cap); A-469d, A-470g, A-470i
2026-11-17 12:00:35 +01:00
jschoubben 1a924f2ca7 runner: a seat with no holder ends its pipeline failed at once, its other steps not asked (A-470g, A-470h)
A pipeline with a step whose seat the seat-holders view names no holder for was failed only once its
other steps ended, after their asks ran for nothing; it now ends failed at placing, naming the seat,
with every other step not asked and said, and none of its steps asked.

Builds: design 47 G §32, §535, §647 (as A-466y and A-466z amend them); A-470g, A-470h
2026-11-17 11:58:25 +01:00
jschoubben ebe49b9bdd runner: a test run's steps are said waiting for a build node until the holder takes the run's ask (A-469b)
A test step queued on a build seat was said running, so the watchman's build-capacity waits never saw
it; every step of a test run now waits for a build node from the run's ask, and at the holder's
ask-taken each is said started again, running.

Builds: design 47 G §725, §732, §86; A-469b
2026-11-17 11:48:28 +01:00
jschoubben 7923ab63b1 runner: the test runs are read and dropped by the seat's verbs test-runs and test-runs-drop (R7)
A test run had no tool to read or recover it; test-runs answers each run with its packages from its
output object, or says the output gone, with the state's fill, and test-runs-drop, answered by the
process, records the hand act first, ends the readers naming the drop and deletes the key and its
object; runner_test_runs and runner_test_runs_drop call them.

Builds: design 47 G §728, §725 (the output object), §733 (unit); A-466v, A-469f, A-469g, A-469u, A-469v
2026-11-17 11:47:05 +01:00
jschoubben 09224d2cdf assigner: the composition runs are read and dropped through mesh-wants' verbs (A7)
A composition run must be seen and recoverable without a hand act on the bus: the seat
mesh-wants' verbs compositions and compositions-drop are answered by the process, the drop
recorded in the hand-act log first, its readers ended could not run naming it; the tools
assigner_compositions and assigner_compositions_drop call them.

Builds: design 47 G §728 (the assigner's two); A-469f, A-469u, A-469v
2026-11-17 11:46:29 +01:00
jschoubben 167a9f2818 assigner: a rerun of a composition step moves every reader that did not pass (A6)
Steps asked again together start one run per machine they did not pass: a rerun keeps the
verdict of a machine it passed, joins a running run, reads one it did not read, or starts
a new run carrying every former reader, those that did not pass marked rerun with the
caller; at the new run's end each marked reader says its end again, naming the new ask,
and a reader that passed does not move.

Builds: design 47 G §727 (composition part); A-468g, A-469l, A-470d, A-470e
2026-11-17 11:44:43 +01:00
jschoubben ad40520e89 runner: stands names a waiting step's ask and its run, and every step asked says step-started (R6)
The watchman could not time a step reading a run: stands named no ask, and step-started was said
only on rerun and ask-again. A waiting step now stands with its own ask and, for a test step, the
run's key and ask; each step asked at a start, a resume, a placing or a run says step-started,
naming its run in shared with no asker.

Builds: design 47 G §731, §729, §726 (step-started of a reading step); A-468e, A-469a, A-469q, A-469r, A-469v
2026-11-17 11:43:52 +01:00
jschoubben 2b3a9e4a6a runner: asking a test run again moves every reader that did not pass (R5)
A rerun of one artifact's failed test step left the other artifact's step failed on a result no
longer true; the rerun now joins, reads or starts the key's run, carrying the former readers
marked in the key, and the new run's end moves the marked ones, said again as a rerun by its
caller and naming the new ask, the pipeline reopened; an accepted step does not move.

Builds: design 47 G §727 (test part); A-469l, A-470d, A-470e
2026-11-17 11:42:09 +01:00
jschoubben 72ebb4deb6 runner: no holder is read from the seat-holders view, and an ask waits for its holder with no five-minute bound (R4)
A step queued for a present holder was ended failed after five minutes; the five-minute ask bound
goes, and a seat ends its steps could not run only when the seat mesh-module-assigner's view
seat-holders, followed from its first view on, names no holder for it.

Builds: design 47 G §535, §647 (as A-466y and A-466z amend them), §717 (the follower)
2026-11-17 11:38:22 +01:00
jschoubben d957a60286 assigner: a reading step names the runs it read, and a superseded step leaves them (A5)
A step's end and its progress name per machine the composition run and its ask, so a
result is traced to the one ask that made it; a superseded or cancelled pipeline's
composition step leaves the runs it reads, the run going on for its other readers, and a
run left with no reader drops its ask and ends could not run.

Builds: design 47 G §723, §729 (mesh-wants' step-ended and step-progress shared); A-469n, A-469t, A-469z
2026-11-17 11:38:10 +01:00
jschoubben ba11ff58dd assigner: a composition run's bound times owed progress, its untaken ask its own (A4)
A run whose build node stops saying progress, or whose ask no build node takes, would hold
its readers for ever: ask-taken arms bound.<run key> and each step-progress arms it again;
untaken.<run key> times the queue from the start, the readers said waiting for a build node
meanwhile; an expiry drops the ask and ends the run could not run naming the bound, and a
step-ended heard after it is ignored and journaled. Readers of a run left open at a restart
are taken up from the keys.

Builds: design 47 G §719 (take-up at start), §720 (the bound, when the clock ends, a run never taken, what the assigner hears); A-466q, A-466s, A-468, A-468b, A-469b, A-469s, A-469y, A-470
2026-11-17 11:36:15 +01:00
jschoubben 97f68b04ea runner: a test run's end moves every step reading it, counted once, dropped only with its last reader (R3)
The run's ask's end now ends each reading step with the run's outcome, counts and shared, its
output kept in test-runs-objects; a pipeline counts a run's tests once; a superseded or cancelled
step leaves the run, the last to leave dropping its ask and ending it; a composition step keeps
the runs mesh-wants names.

Builds: design 47 G §726, §725 (output object), §724 (an ended run read), §729; A-466i, A-468d, A-469m, A-469t, A-469z
2026-11-17 11:33:54 +01:00
jschoubben 61a11f8c15 assigner: a composition step judges each machine by the modules its verdict blames (A3)
One module's fault fails only its own pipelines: a machine blaming module A fails A's step
and passes B's with a warning naming A; a machine that blames none fails every step on it;
a composer before blamed is judged as before, saying it names no culprits; a module the
search did not try is could not run for its own step. Each request carries blame_tries.

Builds: design 47 G §721 (an old composer, its bound), §722; A-466r, A-468a, A-469h, A-470b
2026-11-17 11:32:19 +01:00
jschoubben cd08f1e1c2 runner: a test run is kept in the state test-runs with one clock, a cap and an age (R2)
A test run is now one key of test-runs: its untaken bound written at its start, its clock at
ask-taken and each step-progress, an expiry ending the run and every reader could not run and
dropping its ask, a run past its bound while the runner was away ended at its start, the cap
judged by the process, and an ended run aged with its output object in the step log's order.

Builds: design 47 G §725, §720 (When the clock ends, A run never taken); A-466n, A-466p, A-466s, A-468b, A-468c, A-469d, A-469e, A-469w, A-469x, A-470, A-470a
2026-11-17 11:31:26 +01:00
jschoubben afa95fd0df assigner: one composition run per candidate and machine, every step reading it (A2)
The steps of one candidate share a machine's run, so a revision of 24 pipelines composes
each machine once: the step that starts a run asks the node's input, keeps one request,
chooses and records the composer program, and puts one run ask; every other step reads
the run's verdict from its key, its end written there from the build seat's step-ended.

Builds: design 47 G §718, §719, §720 (within its candidate only, could not run is never read); A-468, A-468a
2026-11-17 11:31:05 +01:00
jschoubben ef5e5d13e0 assigner: the state composition-runs, one key per candidate and machine (A1)
A composition run is kept once per candidate and machine, so steps of one candidate share
it: the key is written create-only, a reader is the step's StepRun with its ask id, a run
that could not run is replaced, a run past composition-runs-kept goes at the next start,
and at the cap no run starts, naming the fill. The settings reach the process through
resource files.

Builds: design 47 G §718, §719, §720 (could not run is never read); A-468, A-468b, A-468c, A-469d, A-469w, A-469x, A-470
2026-11-17 11:26:51 +01:00
jschoubben 5388bbce43 runner: a test step is asked once per candidate, level and share digest, the others read it (R1)
Two artifacts of one directory ran the same tests twice and failed them twice; the first step of
a test-runs key now asks the run, written create-only, and every other step of the candidate reads it.

Builds: design 47 G §724, §725 (the key), §730; A-468k, A-469c, A-469m, A-469q
2026-11-17 11:22:55 +01:00
jschoubben 185fe0ae1d watchman: times every step that reads a run, seeded from the runner's stands (W1)
The watchman keeps each started step under <pipeline>/<step>/<artifact>, begins
its clock at step-started and at each mesh-wants step-progress, build seat
step-progress or step-ended of the step's ask or an ask its shared names, raises
pipeline-stands past five minutes, clears it at the step's step-ended, owes none
to a step on a person or queued for a build node, and seeds from stands at start.

Builds: design 47 G-24 §731, §732, §733 (watchman case); A-468j, A-469, A-469o, A-469p, A-469t, A-469r
2026-11-17 11:20:22 +01:00
jschoubben 8fa1b8aee7 contracts: shared on a step's end and progress, ask and shared on stands, the four run verbs (C1)
A step that read a composition run or a test run names it in shared, so the result is
traced to the one ask that made it; stands names what a reading step waits on; the
runs' read and drop are seat verbs with their class (seatgen regenerated, no hand edit).

Builds: design 47 G §728, §729, §731; A-468d, A-468e, A-469f, A-469q, A-469r, A-469t, A-469u, A-469v
2026-11-17 11:15:55 +01:00
jschoubben c17ccd3070 composer: a request carries blame_tries, a machine's verdict names the modules it blames (K1)
The assigner bounds the composer's culprit search through the request, since the composer program has no settings; a
verdict always writes blamed, an empty list when it blames none, so an old composer's absent field stays tellable.

Builds: design 47 G §721, §729; A-469h, A-469i
2026-11-17 11:10:46 +01:00
jschoubben 9849c49920 assigner: the key form of the state inputs is the assigner's own; an ask's key holds digest and time (A-465b)
The state inputs leaves the seat mesh-wants' definition (seatgen regenerated, no hand
edit). An ask's key holds {digest, at}; the sweep deletes an ask's key a day after its
time and an input with its object once no ask's key names it; keys of the old form
<time>.<digest> go by the time they carry, never earlier.

Builds: design 47 G A-465a, A-465b
2026-11-17 11:05:12 +01:00
jschoubben 4cdf14680e assigner: a composition input is kept once per content, by its sha256 (A-465a)
The key of the state inputs is the digest alone (seat mesh-wants' key form <digest>);
each ask's name holds the digest, the input and its object end with the last ask that
names it or a day after its last write (at.<digest>); the contract files of the seat are
edited by hand (generator not found).

Builds: design 47 G A-465a
2026-11-17 11:05:12 +01:00
mesh-tools bf5f794553 Merge pull request 'assigner: a composition step with no machine judged never passes (A-467a)' (#243) from fix/47-G-composition-none-judged into main 2026-11-17 09:49:30 +00:00
jschoubben 34da4fe001 assigner: a composition step with no machine judged ends could not run (A-467a)
A step whose every machine is away never passes: it ends could not run, naming each machine and why. An away machine is still
not asked and still said as a warning when another machine is judged.

Builds: design 47 G A-467a, A-467
2026-11-17 10:49:05 +01:00
mesh-tools 2406bb4000 Merge pull request 'assigner: a composition step never passes on a machine it did not judge (A-467)' (#242) from fix/47-G-composition-judges into main 2026-11-17 09:47:26 +00:00
jschoubben db62653472 assigner: a composition step never passes on a machine it did not judge, and hands the composer the trunk seat list (A-467)
A machine the composer says `not judged` ends the step could not run, naming why (was a warning). A revision that names no seat
definition (A-234's stand-in) hands the composer every definition of the trunk seat list, read through mesh-catalog's
seat-definitions; a list or definition not read ends the step could not run, naming it (was an empty list, no error). The
integration bed makes the inputs object store, which a request carrying the seat list needs.

Builds: design 47 G A-467, A-234, A-252, A-261
2026-11-17 10:45:20 +01:00
mesh-tools 6bb6452603 Merge pull request 'pipeline runner: a step-log read never waits for a batch it cannot fill' (#241) from fix/47-G-runner-ends into main 2026-11-17 09:40:11 +00:00
jschoubben 8d93c3ff9f Pipeline runner: the ageing reads the step log without waiting for a batch the log cannot fill
Every step's end waited 2 s per retention (6 s) in the step log's Fetch when fewer than 20 entries lay past the aged pointer, so ends were taken one in 6 s serially.

Builds: design 47 G §330 (ageing of the runner's own data at each step's end)
2026-11-17 10:38:13 +01:00
mesh-tools f93e8b9750 Merge pull request 'indexer test: seed a want and a running build before an entry may be removed' (#240) from fix/47-G-integration-tests into main 2026-11-17 08:44:59 +00:00
jschoubben 9a8609f770 Indexer test: seed a want and a running build, since no entry is removed before both streams read non-empty
Builds: design 47 G §675 (kept while named)
2026-11-17 09:43:05 +01:00
mesh-tools 39162a4435 Merge pull request 'assigner: composition inputs end with their objects; assigner_inputs_drop (A-465)' (#239) from fix/47-G-inputs-objects into main 2026-11-17 08:23:36 +00:00
jschoubben 1ccde6fc3e assigner: assigner_inputs says when the key-gone objects cannot be listed; the start's drop is asserted (A-465)
Builds: design 47 G-22 A-465
2026-11-17 09:22:14 +01:00
jschoubben 45f7bf8e01 assigner: an input the assigner ends ends its object too; the objects of deleted keys go at the start and by assigner_inputs_drop (A-465)
Builds: design 47 G-22 A-465
2026-11-17 09:02:34 +01:00
mesh-tools eed0833a29 Merge pull request 'indexer: take in a merge it never took in, and read takeins (A-463, A-463a, A-464a)' (#238) from fix/47-G-untaken-merge into main 2026-11-17 01:13:06 +00:00
jschoubben 223b096295 indexer: a head the pending holds is not behind; a revision heard during a catch-up is compared after it (A-463a)
Builds: design 47 G-22 A-463a, A-463
2026-11-17 02:10:17 +01:00
jschoubben 1987a3915e indexer: correct the comment on movedPackages, which A-464 made untrue
Builds: design 47 G-22 A-464
2026-11-17 02:02:12 +01:00
jschoubben 250a0f1b12 indexer: take in a merge it never took in, and say so while it is behind (A-463)
At its start and on every source revision the indexer compares each repository's taken merge with the head the gate's source names; a repository behind is taken in as its merged message would have been, with the finding merge-untaken raised until it is.

Builds: design 47 G-22 A-463
2026-11-17 01:55:46 +01:00
jschoubben 61843f823d indexer: the tool indexer_read_takeins reads the state takeins (A-464a)
Builds: design 47 G-22 A-464a
2026-11-17 01:55:46 +01:00
mesh-tools 44bdbbcbed Merge pull request 'assigner: a backup ask only for a failed backup (A-453, A-453a)' (#237) from fix/47-G-backup-ask-only-for-failed-backup into main 2026-11-16 23:51:25 +00:00
jschoubben 482a618d1e assigner: a held have names the build it keeps running; only a have not held at another fingerprint is past the hold (A-453a)
Builds: design 47 G A-453, A-453a, ADR 0539 §16
2026-11-17 00:49:26 +01:00
jschoubben 1a187445a5 assigner: a backup ask stands while its have is mid-move; it goes only past the hold (A-453a)
Builds: design 47 G A-453, A-453a, ADR 0539 §16
2026-11-17 00:46:47 +01:00
jschoubben 8ab75bb727 assigner: the backup question is asked only for a held have with no wait (A-453)
A held have that carries a wait is a hold of the composition, not a failed backup; a backup ask whose have now carries a wait or is no longer held is withdrawn with its condition.

Builds: design 47 G A-453, ADR 0539 §16, §541
2026-11-17 00:41:00 +01:00
mesh-tools 8c4489fb3d Merge pull request 'assigner: its calls wait 3 minutes, so a node composing a candidate is answered' (#236) from fix/assigner-waits-for-composing into main 2026-11-16 22:41:19 +00:00
jschoubben a2bcb23f0e assigner: its calls wait 3 minutes, so a node composing a candidate is answered
compose-candidate composes a whole revision in shadow on each node and
answered in about 34 s on g14 and shanks (2026-11-16 23:27), past the
SDK's 30 s call bound, so node-tools' composition step could not run. A
responder that is absent still answers at once. Quick fix; the thorough
one is a bound per verb from the seat's definition (after G).
2026-11-16 23:41:01 +01:00
mesh-tools 43050bf20a Merge pull request 'Pipeline runner tools: runner_rerun, the runner's rerun is reachable as a tool' (#235) from feat/runner-rerun-tool into main 2026-11-16 22:34:16 +00:00
jschoubben 8710148ce0 Pipeline runner tools: runner_rerun, the runner's rerun is reachable as a tool
main.981.node-tools passed build, lint, unit and integration; only its
composition step could not run (g14 and shanks composed in about 34 s,
past the assigner's 30 s, while shanks ran the pipeline's own tests).
The seat verb rerun asks one step again, but no tool reached it.

Builds: design 47 G §482
2026-11-16 23:33:57 +01:00
mesh-tools 6618925841 Merge pull request 'Hand acts name their cause: the runner's write verbs and the checker's requests drop' (#234) from fix/hand-acts-name-their-cause into main 2026-11-16 22:13:04 +00:00
jschoubben 1eb090d407 hand acts name their cause: the runner's write verbs and the checker's requests drop
mesh-hand-acts 0.1.13 refuses a hand act with no cause; the pipeline
runner's record (cancel, rerun, accept, run, ask-again, review, start) and
the checker tools' requests drop gave none, so every one was refused and
nothing was done (runner_cancel, 2026-11-16 23:12: 96 of 96 refused). The
cause is the verb's own word, the one a second act for the same reason uses.
2026-11-16 23:12:51 +01:00
mesh-tools f373cf4ae6 Merge pull request 'Pipeline runner tools: runner_cancel, the runner's cancel is reachable as a tool' (#233) from fix/pipeline-runner-ends-stale into main 2026-11-16 22:05:02 +00:00
jschoubben e040cc5fc2 Pipeline runner tools: runner_cancel, the runner's cancel is reachable as a tool
Builds: design 47 G §482 (cancel)
2026-11-16 23:04:07 +01:00
mesh-tools 38f1c2f10a Merge pull request 'assigner: a composition step reads its catalog revision once and again on a timeout' (#232) from fix/composition-reads-revision-once into main 2026-11-16 20:32:07 +00:00
jschoubben bece2421f1 assigner: a composition step reads its catalog revision once and again on a timeout
Builds: design 47 G §354, A-252, A-261
2026-11-16 21:31:34 +01:00
mesh-tools fb257f549b Merge pull request 'pipeline runner: a pipeline for every module whose fingerprint has none, on a take-in and at start-up' (#231) from fix/pipelines-for-every-moved-module into main 2026-11-16 20:15:27 +00:00
jschoubben b9c50ef0c5 pipeline runner: a pipeline for every module whose fingerprint has none, on a take-in and at start-up
A batched take-in names only its newest revision's movers; the other modules it moved never got a pipeline.
Starter.TakenIn and the runner's first-half pickup now start one for each module of the branch's head with no pipeline at its fingerprint.

Builds: design 47 G §44, §54, §88, §476
2026-11-16 21:14:46 +01:00
mesh-tools f7e0619b24 Merge pull request 'indexer: no catalog graph entry is removed before what is wanted and running was read in full' (#230) from fix/indexer-graph-removal-needs-full-read into main 2026-11-16 19:56:34 +00:00
mesh-tools d351ec5932 Merge pull request 'teller: hold an answer's warrant to the ask as the channel was asked it' (#229) from fix/teller-short-words-warrant into main 2026-11-16 19:21:28 +00:00
jschoubben 4eef3e6c4d teller: hold an answer's warrant to the ask as the channel was asked it, its words cut
#228 cut long hexadecimal runs from an assigner ask's words but checked the warrant against the assigner's whole words:
the operator's answer to mesh-hand-acts' backup ask on novox (20:19) was refused as no longer the ask answered.
2026-11-16 20:21:17 +01:00
mesh-tools 92c87aac6c Merge pull request 'teller: cut long hexadecimal runs from an assigner ask's words' (#228) from fix/teller-short-fingerprints into main 2026-11-16 19:15:43 +00:00
jschoubben 34310504b5 teller: cut long hexadecimal runs from an assigner ask's words, so the operator channel does not refuse it as a secret
The backup ask of mesh-hand-acts on novox (2026-11-16 19:53) carried the node-engine's whole fingerprints and was refused
by the channel; nothing reached the operator and the module stayed held.
2026-11-16 20:15:19 +01:00
jschoubben 5188d36a5c indexer: no catalog graph entry is removed before what is wanted and running was read in full
Builds: design 47 G §675 (kept while named). A start read that ended with a stream empty, or with an event whose set was not
written, leaves the sets not ready; an entry is also kept when a heard want or running build names it though its set key is
missing; a removal says how many wants and running builds it read.
2026-11-16 20:03:19 +01:00
mesh-tools bfea3d36ad Merge pull request 'assigner: a want held at an older build names that build's release while the trunk's fingerprint has no passed pipeline' (#227) from fix/assigner-want-older-build into main 2026-11-16 18:51:38 +00:00
jschoubben 592278441c assigner: a want held at an older build names that build's release while the trunk's fingerprint has no passed pipeline
novox 2026-11-16: mesh-hand-acts' want stayed at 4eb3cf48 with no version because the pass returned at
no-passed-pipeline before it named a build. Now each held want without a version, at a fingerprint other than the
trunk's, takes the release whose parts that build made (and parts where its engine reads them); nothing else changes.

Builds: design 47 G §379, §526 (A-96, A-421, A-430a)
2026-11-16 19:50:45 +01:00
mesh-tools 48ba977270 Merge pull request 'assigner: a want held at an older build names that build's release by its parts' (#226) from fix/assigner-held-build-release into main 2026-11-16 17:53:02 +00:00
jschoubben 8671d1062b assigner: a want held at an older build names that build's release by its parts
novox 2026-11-16 18:46: the mesh-sdk merge moved mesh-hand-acts' fingerprint to 9b3a5534; rule 2 holds the want at
4eb3cf48 (no pipeline passed at the new one), and namedBuild named a release only for the trunk's fingerprint, so the
held want never got version 0.1.13 though it was released at 18:04:46. Now a held build takes the release whose parts
are exactly what it made (A-421's match).

Quick fix = thorough fix here: namedBuild is the one place a want's release is looked up.
2026-11-16 18:52:50 +01:00
mesh-tools 7c3b6211b0 Merge pull request 'assigner: name a release by its parts when its source is not the entry's fp-src' (#225) from fix/assigner-release-by-parts into main 2026-11-16 17:07:26 +00:00
jschoubben cd6a452c08 assigner: name a release by its parts when its source is not the entry's fp-src
novox 2026-11-16: mesh-hand-acts 0.1.13 was released from source 962 (the builder's reservation), its catalog entry's
fp-src is 963, so the assigner found no release and the want on novox named no version and no parts. When no release of
the fp-src is heard, the release whose parts are exactly the digests this fingerprint's build made is this build's (A-421's
match, extended).

Quick fix (this): the assigner matches by parts, which are the evidence. Thorough fix (noted, not here): the builder's
reservation records the entry's fp-src as its source, so both name the same revision.
2026-11-16 18:07:17 +01:00
mesh-tools 7b71766ab4 Merge pull request 'builder: drain every holder a publish again queued at, whatever a later version met' (#224) from fix/builder-drain-after-entry-error into main 2026-11-16 16:55:24 +00:00
jschoubben a90c4bfbf5 builder: drain every holder a publish again queued at, whatever a later version met
queue() returned on the first version whose catalog entry could not be read, before it started the drain of the
holders it had already queued at: on 2026-11-16 17:20 mesh-hand-acts 0.1.13 was queued at distribution, then
mesh-delivery-indexer 0.1.14's entry was not kept, and the queued publish was never sent, so no version was
released. Now an unreadable entry leaves only its own version unqueued, the error is still answered (heard again),
and the drain of every holder given a version is started in all cases (design 47 G section 588).

Quick fix and thorough fix are the same here: queue() is the one place that starts a holder's drain.
2026-11-16 17:55:06 +01:00
mesh-tools cdcab2370d Merge pull request 'mesh-grants: a grant waits only for what the loaded list does not allow' (#223) from fix/grants-waits-by-coverage into main 2026-11-16 16:30:42 +00:00
jschoubben 30f67f0471 mesh-grants: a grant waits only for what the loaded list does not allow
GrantWaits compared permissions by their text, so a composed subject or allow-responses counted as
missing though the loaded list's '>' already allowed it: all 182 grants waited on '1 permissions'
from 15:43 on 2026-11-16 and no want moved. A subject a loaded one covers is carried now, and
answering is carried where the loaded user may publish every subject.
2026-11-16 17:30:29 +01:00
mesh-tools 28b5724871 Merge pull request 'mesh-grants: say what each pass did with the grants' (#222) from fix/grants-pass-says-its-grants into main 2026-11-16 16:26:07 +00:00
jschoubben 298f4de168 mesh-grants: say what each pass did with the grants
A grant held (kept or waiting) or left out was read only from the pass object, which no tool opens,
and the assigner's sixth rule waited on it in silence: no grant for any module was written after
15:43 on 2026-11-16 and nothing said why. Each pass now says its grants: wanted, written, deleted,
and every kept, waiting and missing one with its reason.
2026-11-16 17:25:49 +01:00
mesh-tools bf2962dc29 Merge pull request 'Assigner: bind the kept seat events, so a composition run's end is heard' (#221) from fix/assigner-hears-kept-step-ends into main 2026-11-16 15:04:19 +00:00
jschoubben c1fc670af4 Assigner: bind the kept seat events, so a composition run's end is heard
The build seats' step-ended is a kept seat event on its own stream, never on EVENTS. The assigner
registered its handler on the hub but never bound the kept streams, so every composition step
waited for ever after its composer run passed (pipeline main.961.mesh-hand-acts, 2026-11-16).
Design 47 G §354, A-240.
2026-11-16 16:03:59 +01:00
mesh-tools 91b65d0180 Merge pull request 'Indexer: an input leaves nothing in its object store; a full store is said by name and fill' (#220) from fix/indexer-inputs-retention into main 2026-11-16 14:39:19 +00:00
jschoubben ac0befa9b9 Indexer: an input leaves nothing in its object store; a full store is said by name and fill
The indexer's inputs-objects bucket filled twice: deleting an input's key (step-ended, the day sweep)
left its object, which only the person's drop tool removed. The input's key and object now go together,
each write first drops the objects no key names, and a write the store refuses names the store and its fill.

Builds: design 47 G §354, §712, A-237
2026-11-16 15:31:26 +01:00
mesh-tools 4fabf9d26c Merge pull request 'G starts: grants composes the first rights from the trunk, the indexer answers at once and knows its build, unpublished packages build at the source commit' (#217) from fix/47-G-start-2 into main 2026-11-16 14:15:12 +00:00
jschoubben 3d5ea26605 Merge branch 'fix/447-builder-names-dir' into prep/delivery 2026-11-16 15:07:25 +01:00
jschoubben 10b879bc31 assigner: a machine whose node-engine is not heard running composes with the revision's node-engine entry, said (A-451)
Live, 2026-11-16: main.953's composition could not run, 'novox: no build of mesh-host is heard running there'.
2026-11-16 14:52:43 +01:00
jschoubben 00de5a7f43 assigner: comments of the chunked composition input cite A-237c
Builds: design 47 G (G-22 lead answers 2) A-237c; A-237b
2026-11-16 14:49:47 +01:00
jschoubben 0ee747cf1b assigner: the composition step takes a node's input through the chunked seat call, with a call token (A-237b)
Builds: design 47 G (G-22 lead answers 2) A-237b; A-237, A-249
2026-11-16 14:39:30 +01:00
jschoubben d69ee47321 indexer: a node-engine's call of the verb revision is proved as node.<machine> and stands for the module holding the seat node-engine (A-450)
Builds: design 47 G (G-22 lead answers 2) A-450; ADR 0621 §2, ADR 0663 §2
2026-11-16 14:13:31 +01:00
jschoubben 05c765e36d pipeline runner: the pipeline-ended is said, with its widens, before the pipeline's pin is freed (A-449)
Builds: design 47 G (G-22 lead answers 2) A-449
2026-11-16 14:02:25 +01:00
jschoubben 7c0b835ce3 assigner: the composition step builds its compose-candidate key with the node-engine client's builders (A-226b)
Builds: design 47 G (G-22 lead answers 2) A-226b
2026-11-16 13:59:29 +01:00
jschoubben c44a42fc16 indexer: a take-in reads and pins its revision holding keepMu, so no other keep removes it first (A-449a)
Builds: design 47 G (G-22 lead answers 2) A-449a; §579
2026-11-16 13:48:33 +01:00
jschoubben 5632924c4f pipeline runner and indexer: review fixes (advance only places waiting steps, view re-read after the starts, one freed) and the indexer pins a take-in's revision for its pipelines (A-448, A-449a)
Builds: design 47 G (G-22 lead answers 2) A-448, A-449, A-449a; §153, §200, §579
2026-11-16 13:46:17 +01:00
jschoubben bbcad0845a pipeline runner: a take-in's pipelines start at its own catalog revision, wait for the view, and pin the revision while they run (A-448, A-449)
Builds: design 47 G (G-22 lead answers 2) A-448, A-449; §153, §200, §476, §579
2026-11-16 13:38:57 +01:00
jschoubben d0efbee65b take-in.taken names the catalog graph revision the take-in made (A-448)
Builds: design 47 G (G-22 lead answers 2) A-448; §476, §493
2026-11-16 13:36:49 +01:00
jschoubben c5799d2f9b assigner: find the node-engine's entry by its served verbs in the catalog's seat: form (composition could never run) 2026-11-16 13:02:04 +01:00
jschoubben 19758f44cf pipeline runner: bind the kept seat events' streams, so a step's end is heard (G-1 §24) 2026-11-16 12:55:59 +01:00
jschoubben f5880d449b pipeline runner: a step's fetch always names its module's directory, paths when the entry has them (principle 10, A-447) 2026-11-16 12:22:52 +01:00
jschoubben d0e7dee951 Builder names the module's directory on every fetch; the fetch request accepts dir with no paths (A-447)
Builds: design 47 G (G-22 lead answers 2) A-447
2026-11-16 12:22:37 +01:00
jschoubben a5a5d9a16f A check for a module tests that module directory's modules alone (A-447c)
Builds: design 47 G (G-22 lead answers 2) A-447c
2026-11-16 11:37:54 +01:00
jschoubben 41821c841a Compose jobs of the checker name their module's directory in the fetch (A-447b)
Builds: design 47 G (G-22 lead answers 2) A-447b
2026-11-16 11:34:43 +01:00
jschoubben 017451762d Builder names the module's directory on every fetch; the fetch request accepts dir with no paths (A-447)
Builds: design 47 G (G-22 lead answers 2) A-447
2026-11-16 11:09:26 +01:00
jschoubben e7c05c5370 pipeline runner: say pipeline-started when placing a pipeline never asked; drop the runner version wait's leftovers
Placing the steps of a pipeline that has none says its pipeline-started, a
set-aside one included. The seat's acts entry for step `pipeline`, the wait step
value `pipeline` and the wait's `clock-from` go.

Builds: design 47 G A-446, A-446a
2026-11-16 10:36:19 +01:00
jschoubben 070a5dd35b pipeline runner: no pipeline is set aside for the runner's own new version
A take-in that changes the runner starts its pipelines as any take-in does; the
state bounds' held keys, the wait's `on` value `runner version`, the finding
pipeline-waits, the verb release (and the tools runner_release and runner_waits
that only served it), the Held field and the runner's build-end and running
hearing go. A pipeline a previous runner left set aside is placed and asked
at the runner's start as a newly started one.

Builds: design 47 G A-446 (replaces A-195, A-206, A-218, §266's hold)
2026-11-16 10:34:12 +01:00
jschoubben 57025ccb3b assigner: manifest test lists assigner_why; ask-operator-for description names its real default
Builds: design 47 G A-439 (assigner_why), A-425 (the ask-operator-for default)
2026-11-16 09:44:37 +01:00
jschoubben fb588e85c0 indexer: say the start replay's progress every 50000 entries, so a normal start does not fill the journal 2026-11-16 09:25:44 +01:00
jschoubben bfb80605c3 Merge remote-tracking branch 'origin/main' into fix/47-G-start-2 2026-11-16 09:25:11 +01:00
jschoubben e4302579ce indexer: each start step says when it begins and how long it took, and the build-end replay and package publishing say their progress, so a start that does not end is read in the journal 2026-11-16 02:13:58 +01:00
jschoubben 2979bc3b84 assigner: an ask's words cut each digest and fingerprint to 12 digits, so the router no longer refuses every backup ask as a secret; the backup ask binds its composition by that prefix 2026-11-16 01:25:22 +01:00
jschoubben 8f20ca8fdc assigner: a module wanted with no passed pipeline names the parts its build.ended made until its release is heard (design 47 G §16, A-428) 2026-11-16 00:19:35 +01:00
jschoubben e67f77f8e6 assigner: an online node runs its node-engine for an acting wait on the seat node-engine, whatever its have of itself says 2026-11-16 00:05:44 +01:00
jschoubben 7c338230de assigner: a part no running statement names is read from its have for an acting wait, on every node (A-426) 2026-11-16 00:02:55 +01:00
jschoubben 7548314b95 assigner: a have with no health counts as running for an acting wait where its engine states no running 2026-11-16 00:02:21 +01:00
jschoubben e78b3eea0a assigner: a node whose node-engine states no running is read from its have: a part running healthy there ends an acting wait (A-426) 2026-11-16 00:02:01 +01:00
jschoubben 7989ddc227 assigner: the holder of mesh-catalog is wanted with no passed pipeline: every pipeline runs on a revision it took in (design 47 G §16, G-5 whole test) 2026-11-15 23:57:14 +01:00
jschoubben 4abb853400 assigner: assigner_written with why answers the wants' whys until the manifest naming assigner_why is taken in 2026-11-15 23:54:17 +01:00
jschoubben bda4abb13e assigner: assigner_why says why a want is what it is: the pass step that decided it and what it read (tools rule) 2026-11-15 23:47:23 +01:00
jschoubben 63dff99f11 grants: no seat can lose its holder when every account subscribes to every subject
The list giving every account every subject was held at 23:20:32: the guard reads each seat's holders from the text of
the subjects users subscribe to, and > names no seat, so it saw every seat lose its holder.
2026-11-15 23:22:18 +01:00
jschoubben e1476cfdf9 grants: every mesh account may publish and subscribe on every subject
The operator, 2026-11-15 23:12 CET: the mesh accounts should have all the permissions, otherwise it becomes a mess;
the operator can do everything, always. Permissions derived per module refused the indexer's chunks, seat asks and
seat verbs again and again while G is delivered. The approval mark's and the desk's denies stay; an enrolling node
keeps its few subjects. The research after G replaces the accounts themselves (mesh, agent, operator).
2026-11-15 23:14:36 +01:00
jschoubben 7c33a2cf4c grants: a module's own account sends the chunks of a verb of a seat it holds (A-115)
The validation of mesh-delivery #219 failed twice: the indexer answered seat:mesh-catalog.input, and the bus refused
its chunks, since only an account whose process repeats the verb in serves was granted to send them. The indexer's
and the assigner's programs answer their seat's input verb on the module's own account; their claims say they serve it.
2026-11-15 22:40:36 +01:00
jschoubben 2682a623de grants: a module left out of the shadow list says why no manifest was found (the pass's gaps naming it) 2026-11-15 22:34:45 +01:00
jschoubben 7d97516c3b pipeline: a step's fetch names the module directory only with its artifact's paths
Every step of the first pipelines ended 'could not run (the request names a module directory and no path)': the runner put
the entry's directory in the fetch without paths, which the build seat refuses. It now names the directory with the
artifact's named paths from the entry, and else neither, so the commit is fetched whole.
2026-11-15 18:58:23 +01:00
jschoubben 485c2f10b1 grants: every account may receive a chunked verb's answer (principle 6)
The validation of mesh-delivery #219 failed: the check program on shanks asked seat:mesh-catalog.input, whose answer comes
in chunks, and the bus delivered none, since only an account naming the verb in invokes was granted its chunk subjects.
Inside the mesh any module may call any seat verb (the operator, 2026-11-15).
2026-11-15 18:51:42 +01:00
jschoubben bb164bb2b8 steprun: the line of an ask's end names a pipeline step's own outcome
An ask's end read 'passed' when its end was said, whatever the step's outcome: five pipeline steps read passed after 0 s
and nothing said whether they ran tests, carried them or had nothing to run (failure must be loud).
2026-11-15 18:50:49 +01:00
mesh-tools 479b5b5521 Merge pull request 'takein: require the meshcatalog contract its taken event now carries' (#219) from fix/47-G-takein-requires-meshcatalog into main 2026-11-15 17:47:33 +00:00
jschoubben 7d6eeed8ae takein: require the meshcatalog contract its taken event now carries 2026-11-15 18:47:25 +01:00
jschoubben 16517579b2 takein: require the meshcatalog contract its taken event now carries
The check of 901c800c failed: modules/mesh-delivery-indexer/takein imports seats/meshcatalog for TakeInEntry (#218) and
its go.mod did not name it, so a shut-off step could not build it.
2026-11-15 18:47:24 +01:00
jschoubben 4289d5583b grants: the part's account may create the seats' ask streams it makes
The bus refused SEAT_MESH_BUILDS's and SEAT_MESH_WANTS's create: the part's account is granted each stream it creates by
name, and the ask streams were not named. They join the declared streams, as the kept-event streams do.
2026-11-15 18:36:55 +01:00
jschoubben 773f89e9de steprun: the build seats' queue kinds take turns
A build module pulled a waiting delivery before any check, so 89 queued deliveries held every pipeline's check back on
shanks for an hour and more. The pull now starts at the kind after the one its last ask came from; neither kind starves
the other (the operator's yes, 2026-11-15).
2026-11-15 18:33:37 +01:00
jschoubben fe3bdb5d10 grants: make each seat's ask stream the bus lacks, from the seat list
The pipeline runner's step ask to mesh-builds timed out: it publishes on the seat's accept subject through JetStream and
no stream held mesh.seat.mesh-builds.accept.>. Before G the controller made SEAT_<SEAT> for every seat that accepts work;
the seats whose queues came with G (mesh-builds, mesh-wants) had none. The grants part now makes each such stream, from
the seat list, at every pass, as it makes the seats' kept-event streams: only where the bus holds none.
2026-11-15 18:30:47 +01:00
jschoubben 6b5099c8d7 grants: every module account may put an ask on any seat (principle 6)
The bus refused the indexer's validation ask and the pipeline runner's step asks: a named ask was granted only from the
seat definition's callers and a composed manifest, and both accounts were kept from the list in force without them. The
operator, 2026-11-15 about 18:10 CET: no fine-grained permissions inside the mesh; every account of a module, its
processes, its node and the tool runner is granted mesh.seat.*.accept.>, composed or kept. A seat's events and verbs keep
their own rules until the research after G decides the whole shape.
2026-11-15 18:19:03 +01:00
mesh-tools 901c800c62 Merge pull request 'G start: take-in.taken names its branch, source revision and entries; a taken event with no entries starts nothing' (#218) from fix/47-G-take-in-carries-entries into main 2026-11-15 16:58:03 +00:00
jschoubben 6a02d80072 graph: a node may leave out a package's seat call word it does not invoke itself (A-361)
The indexer leaves out a package's call word on a cycle (withCallsLeftOut, A-361), but the node check refused a left-out
word the module's own invokes do not name: once the node-engine's manifest stopped naming mesh-catalog.registrations
(mesh-host #229), the trunk revision the indexer wrote could not be read back, and the indexer stopped at its start.
2026-11-15 17:56:59 +01:00
jschoubben ba2a7d73b7 graph: a node may leave out a package's seat call word it does not invoke itself (A-361)
The indexer leaves out a package's call word on a cycle (withCallsLeftOut, A-361), but the node check refused a left-out
word the module's own invokes do not name: once the node-engine's manifest stopped naming mesh-catalog.registrations
(mesh-host #229), the trunk revision the indexer wrote could not be read back, and the indexer stopped at its start.
2026-11-15 17:56:58 +01:00
jschoubben f1231fccb0 indexer: take-in.taken names its branch, source revision and entries; runner: one with no entries starts nothing
The pipeline runner heard every take-in.taken with branch "" and source 0 and started no pipeline, asking the bus
for each again for ever: the indexer's event body never gained design 47 G §476, §493 and §648's fields. Every taken
event of one take-in now names the watched branch, the source revision it makes (one above the newest seen or said,
A-431) and one entry per module written; a taken event with no entries starts nothing and is journaled (§493).
2026-11-15 17:54:13 +01:00
jschoubben 310d4817ca indexer: take-in.taken names its branch, source revision and entries; runner: one with no entries starts nothing
The pipeline runner heard every take-in.taken with branch "" and source 0 and started no pipeline, asking the bus
for each again for ever: the indexer's event body never gained design 47 G §476, §493 and §648's fields. Every taken
event of one take-in now names the watched branch, the source revision it makes (one above the newest seen or said,
A-431) and one entry per module written; a taken event with no entries starts nothing and is journaled (§493).
2026-11-15 17:50:46 +01:00
jschoubben 5126d83722 assigner: a parts-reading node's want carries the parts beside the version, until G is delivered
Bootstrap circle on novox: the node-engine's grant to ask a registry's versions follows the node-engine build wanted
there, which needs a passed pipeline, which needs the pipeline runner that this want composes. With the parts beside
the version, the node-engine (8a0c392) composes by its parts and asks no registry. Recovery (lead-47).
2026-11-15 17:31:45 +01:00
jschoubben 40771c41ab grants: say each pass's errors and its sealed result in the journal (recovery, lead-47) 2026-11-15 17:25:07 +01:00
jschoubben 7507a250c7 grants: say each pass's decision on the user list; stop creating buckets for the pass once the bus refuses one
The user list in force on novox stayed at 14:53 UTC while the shadow list changed, and the pass said nothing of why;
each refused create of a state's object store waited out its bound, one after another. Recovery mode (lead-47).
2026-11-15 17:20:35 +01:00
jschoubben 260dab75d5 grants: every state's object store beside it is made and granted to its owner
A state of the field state had no <state>-objects store: the grants part made and granted object buckets from
the manifest's objects alone, so the indexer's state inputs (A-237) had no inputs-objects, and every validation
failed on a refused STREAM.INFO of OBJ_mesh-delivery-indexer_inputs-objects; the assigner's inputs likewise.
objectsOf now gives each such state its store (its size, 16 MiB when it names none; none for a state only read),
so the grants part creates it and grants it to its owner as the module's own bucket.

And a state asked in requires by the template state: the bus module's process may now make its store too (the
grants part's BusStateStreams names it, as mesh-sdk's does), and a kept binding's objects is among its streams.

Builds: design 47 G §58, §607, A-237
2026-11-15 17:13:54 +01:00
jschoubben f0e7631d11 assigner: test that a placed node's want held at F names its release
The rules' hold at F rebuilt the want without its version, so novox's want of mesh-delivery-pipeline stood as
{fp, self}; 98875eba names the release after the self derivation. This row fails without it.

Builds: design 47 G A-430a
2026-11-15 16:53:48 +01:00
jschoubben 98875eba70 assigner: a want names its build's version, never its artifacts' digests
A want of a released build names the module's version and no parts (A-430, A-430a): the node-engine resolves each
artifact at that version through its kind's registry seat. Every want that names a build gets it, whichever rule made
or kept it, a self want held at its fingerprint included: novox's want of mesh-delivery-pipeline stood as {fp, self}
since the rules held it at its fingerprint and that path never named the release. A candidate's added module carries
the version alone. A build the assigner knows no version of (another branch's, a kept one: build.ended names none) is
named by its parts as before, until the builder says the version it numbered it under. The release lookup says why it
misses when no assignment graph revision is kept.

Builds: design 47 G A-430, A-430a, §379, §526
2026-11-15 16:47:16 +01:00
jschoubben c62f8e07fd assigner: say why a want names no parts, and a want held for a dependency's delivery
The want of mesh-delivery-pipeline on novox stayed with no version and no parts after d1ed5fd5, and the assigner said
nothing. Each want the pass writes or keeps at a fingerprint with no parts is now said once per reason: whether the
node's engine reads parts (its record's capabilities) and whether a release or kept build of it is found. A want held
for its dependency's delivery (§376) is said when the hold starts.

Builds: design 47 G §379, §525, §376, A-420 (a path that says nothing)
2026-11-15 16:43:04 +01:00
jschoubben d1ed5fd555 assigner: read want-parts from a node record's capabilities
The want of mesh-delivery-pipeline on novox named no version and no part digests, so novox's node-engine of G composed
nothing: the assigner looked for want-parts among a node's manifest reads, while a node-engine of G states it among its
record's capabilities (design 47 G §525), so no node ever read as able to take parts. Both are read now.

Builds: design 47 G §525, §526, §379
2026-11-15 16:36:54 +01:00
jschoubben ba0d2eeacc assigner: ask the operator only for the change kinds the setting ask-operator-for names
Every proposal whose verdict passed waited on the operator's yes. Which are asked is now the assigner's setting
ask-operator-for, a list of change kinds (place, take-off, pin, unpin, hold, unhold, decide, config, add-node,
remove-node, and stops for a verdict whose answers say a node would stop a module), its default take-off, remove-node,
stops. A proposal none of whose changes is listed is applied at once, said in the log and by assignments-changed,
naming who proposed it and why. The key is declared in the manifest as the two others, filling a file the process reads
at each pass; a change of it is said.

Builds: design 47 G A-425, A-425a
2026-11-15 16:22:37 +01:00
jschoubben e0f12c8c37 assigner: rule 8 counts a healthy build that serves the verb whatever its phase says of the catalog
The pipeline runner's want on novox waited under rule 8 for seat:mesh-hand-acts.hand-act, which mesh-hand-acts serves on
novox from a healthy build the catalog holds no entry of: its have stands in phase held (entry-missing), and rule 8
counted only phase running. A node that runs a healthy build of a part serves what that build serves, whatever its
version and whether the catalog lists it: a healthy have held or waiting for a yes counts, unless its running statement
says it stopped or is not healthy, and the rule says which build it counted.

Builds: design 47 G A-426a, A-426, ADR 0614 §2
2026-11-15 16:19:01 +01:00
jschoubben d57fa43bcc assigner: a released build counts as done for rule 1
Rule 1 held mesh-delivery-pipeline's want as being built after a restart lost its build end, though 0.1.6 was released.
A build whose version is released counts as done for rule 1, and its build.ended counts only for a build not released.

Builds: design 47 G A-429, §379
2026-11-15 16:16:17 +01:00
jschoubben e0f0a56630 assigner: an acting wait ends when its part runs any build serving the edge's seat
The pipeline's want on novox waited for an assigner build not yet built, while a working assigner ran. An acting wait now
holds only while the acting part runs nothing serving the edge's seat on its node: a running build whose manifest claims
the seat (or one whose manifest cannot be read, the part holding the seat by its claim) ends it at once, whatever its
newest is, and the end says which build it took. A wait on a version not yet built is never held for that alone.

Builds: design 47 G A-426, §266, §268
2026-11-15 16:15:41 +01:00
jschoubben 0fe5f0aaaf assigner: read the builder's build ends whole from the first message at its start
Rule 1 held mesh-delivery-pipeline's want on novox as being built, though its build ended at 00:57:36: the assigner
reads the builder's stream of build ends whole at its start only when the bus keeps it last per subject, and the bus
keeps MESH_DELIVERY_BUILDER_BUILDS by age (168 hours, no max per subject), so after each restart it heard only the ends
said since. It now reads the stream from its first message whichever way it is kept (A-233), the last end of each
fingerprint standing. The integration test's stream is kept by age, as live.

Builds: design 47 G A-181, A-233, §556
2026-11-15 16:13:03 +01:00
jschoubben 9bb02a2cb2 assigner: want the pipeline runner's first build with no passed pipeline while no runner runs
The pipeline runner could never be wanted: a want follows a passed pipeline (§29), and nothing passes one before a runner
runs. While no module claiming the seat mesh-pipeline-runner runs on any node (read from the node-engine's running
statements), a module claiming it skips that gate and is wanted from the trunk's entry by the other rules, said once.
Every other module still waits for a passed pipeline.

Builds: design 47 G A-428, §29
2026-11-15 16:05:02 +01:00
jschoubben d4ed5ae13f assigner: say a want held for want of a passed pipeline, and what a refused put's node runs
The want of mesh-delivery-pipeline on novox was not written and the assigner said nothing: a module whose fingerprint no
pipeline passed at on its branch gets none (design 47 G §29), and that return was silent. It is now said as any rule's
reason, once per node. A put refused because the builder holds no build of its fingerprint now names the build the
node's running statement says it runs, so the put of A-427 can name it.

Builds: design 47 G §29, A-427, A-420 (a path that says nothing)
2026-11-15 16:03:29 +01:00
jschoubben 21523a449f assigner: a put may hold the build a node runs now
A put of ace's assigner at the build it runs (a hand start) was refused, since the builder's store holds no build of
it, so the trunk's newest build would replace it. Where the store holds none, a put naming the fingerprint the node's
running statement names is held there with the composition the node's have names; the store is not asked. A have
naming no composition at that fingerprint refuses it, saying so.

Builds: design 47 G A-427, A-426
2026-11-15 15:58:00 +01:00
jschoubben ad3d73d9bd assigner: say a want held by an acting part's version
The want of mesh-delivery-pipeline on novox was not written after the operator's yes, and the assigner said nothing:
its entry's acting edge place waits for the assigner's own catalog version to run on ace. Each acting wait the
assigner starts is now said, naming the entry, the part, the step, the version waited for and how it ends.

Builds: design 47 G §266, §268, A-420 (a path that says nothing)
2026-11-15 15:55:22 +01:00
jschoubben 9be15fe393 teller: ask every assigner ask at once; drop a lapsed or unknown key; the view never holds a raise back
The operator channel keeps no count of an asker's open asks (A-424), so the teller waits for no room: each of the
assigner's asks is asked when it is written, and the asks it could not hand the router are asked again at each end and
at its start. A key whose ask lapsed (its proposal ended) or that is of no kind the teller knows is dropped with a line,
never asked. The view's answer only fills an answer given there; one it cannot read is said and the ask is raised all
the same (it never held the raise back; its line said so wrongly).

Builds: design 47 G A-424
2026-11-15 15:54:32 +01:00
jschoubben 1f1126d4ec assigner: say a proposal's ask when it is written
The ask of proposal p-20261115t143855-09a7bc was written and the assigner's journal said nothing of it, so where it
stopped was found only in the teller's. The assigner now says each proposal it asks, with the ask's id and key.

Builds: design 47 G A-420 (a path that says nothing)
2026-11-15 15:46:36 +01:00
jschoubben af61faf706 teller: give the assigner's asks every place the router gives the teller
The ask of proposal p-20261115t143855-09a7bc never reached the operator: the teller kept it waiting for room, since two
old asks of the assigner (mailu's restore and hold, open since 2026-11-14) filled the two places it allowed, one being
kept free for the merge ask, which went with the Approve per merge (design 47 G §653). The assigner's are the only asks
the teller makes at the router now, so they take every place it gives (occ.MostOpen).

Builds: design 47 G §653
2026-11-15 15:46:24 +01:00
jschoubben 06ff2dc2c6 assigner: read an entry's fp-src, and key a release's parts by the reference it names
The candidate placing mesh-delivery-pipeline 0.1.6 on novox carried no parts, though its version-released was heard:
the assigner's module value of a catalog entry dropped the entry's inputs, so every trunk entry had fp-src 0 and A-419
never matched; and a release's parts were keyed <module>:<artifact> by prefixing the module to the artifact the event
names, which the contract gives whole (mesh-delivery-pipeline:program), so every release's parts read
mesh-delivery-pipeline:mesh-delivery-pipeline:program and A-421's match by digests missed too. The value now carries
the entry's src and fp-src, and a release's part is keyed by its reference as named.

Builds: design 47 G A-419, A-421, A-96
2026-11-15 04:02:09 +01:00
jschoubben b0242f68fe indexer: hear the kept seat events on their own streams
The two package-published of mesh-delivery-pipeline 0.1.6 sit on SEAT_mesh-builds_package-published, where the
indexer's program durable novox_mesh-delivery-indexer holds them pending and was never pulled: the program bound only
its durable on EVENTS, and a kept seat event is never there. So no version was released. The same holds for
toolchain-agreed (2 pending) and node-build-go's step-ended (10 pending). The program now binds, once its EVENTS
durable is bound, its durable on each kept stream whose event it handles, as the builder does.

Builds: design 47 G A-397, §349
2026-11-15 03:48:13 +01:00
jschoubben 240015c814 indexer: say every end of a package-published heard
A package-published of mesh-delivery-pipeline 0.1.6 left the catalog's versions empty and the indexer's journal
silent: the hearer said nothing when it heard one, waited for the module's other artifacts, took it as another
branch's, found the version released already or released it. Each of those ends is now said, naming the artifact,
the version, the branch and source, the artifacts still awaited and the fingerprint of the entry compared.

Builds: design 47 G §349, §371, A-420
2026-11-15 03:47:47 +01:00
jschoubben 61fff7da67 builder: say a message given up on the last delivery its consumer allows
The builder leaves an event it cannot take for the bus to give again, and the bus drops it after the fifth delivery its
durable allows without a word: the 0.1.6 published was lost so. On that last delivery the builder now says it gives the
message up, naming its subject, what it carries (a registry outcome's name and version, a version-released's module and
version) and the last refusal.

Builds: design 47 G A-420
2026-11-15 03:19:10 +01:00
jschoubben c677534e11 assigner: match a trunk entry with no fp-src to the release of what its build made
An entry whose fingerprint moved with no merge names no fp-src (ADR 0601 §1), so A-419 found no release for it and its
wants and candidates carried no parts. Such an entry now takes the release whose parts' digests are the digests its
fingerprint's build.ended made; one found by neither way is said, naming which was tried.

Builds: design 47 G A-421, A-419
2026-11-15 03:18:31 +01:00
jschoubben 8e3b44c6fc indexer: say a message given up on the last delivery its consumer allows
The indexer leaves an event it cannot take for the bus to give again, and the bus drops it after the fifth delivery
its durable allows without either saying so: a package-published lost so leaves a version unreleased silently. On
that last delivery the indexer now says it gives the message up, naming its subject, what it carries (for a
package-published the artifact and version) and the last refusal.

Builds: design 47 G A-420
2026-11-15 03:17:11 +01:00
jschoubben ce839ba602 assigner: match a trunk build's release by the source its fingerprint was built at
namedBuild matched a trunk entry's version-released by the kept assignment graph's source revision, so after any merge
that does not rebuild a module its wants and candidates carry no version and no parts. It now matches by the entry's
fp-src, the source revision its fingerprint was built at, which is version-released.source for that build; an entry
whose release is not heard, or that names no fp-src, is said once, naming the module, the fingerprint and the source.

Builds: design 47 G A-419, A-96, A-67
2026-11-15 03:15:58 +01:00
jschoubben 2beb39c371 builder: take a registry outcome the old numbering does not hold through to the reservation
oci-artifact-registry's published of mesh-delivery-pipeline/program@0.1.6 was refused as 'not numbered by the builder'
and left for the bus, up to its consumer's five deliveries, and no package-published was said: the version is the
reservation's (§369), never an entry of the state versions, design 51's numbering by name, which G keeps only until
it is removed (§372). Such an outcome is now taken: the reservations mark it and say package-published (A-415). The
log of an outcome left for the bus names its delivery count.

Builds: design 47 G §369, §372, §52, A-415
2026-11-15 03:13:22 +01:00
jschoubben e84e2adff0 builder: answer reserved for a bundle's or an archive's name, and log a name no entry carries
distribution's tag of mesh-delivery-pipeline 0.1.6 was refused: reserved answered 'no entry carries the name
mesh-delivery-pipeline/program', since the lookup matched only an artifact's package name and a bundle's entry
names none. A bundle's or an archive's name is <module>/<artifact>, read from its reference through NameOf; a
name no entry carries is said in the builder's log with the entries looked at.

Builds: design 47 G A-418, §478, §572
2026-11-15 03:00:14 +01:00
jschoubben 2394dec1c5 builder: name a publish again's transfer as a valid transfer id
The registry refused builder_publish_again of mesh-delivery-pipeline 0.1.6 with 'transfer ... is no transfer id':
the name carried the version's dots, which mesh-sdk's parts receiver refuses. The transfer stays the builder's own
name (the registry part's publish), with the refused characters made dashes.

Builds: design 47 G §588, A-73
2026-11-15 02:36:13 +01:00
jschoubben e75112baec builder: know a registry seat's holder from the seat-holders view from the start, not from running heard
builder_publish_again for mesh-delivery-pipeline 0.1.6 queued nothing after a restart: the holder was learnt only
from node-engine running events heard since the builder started. The Republisher now reads each registry seat's
holder from the catalog's SeatHolders, the holder function the builder's FollowSeat of the assignments takes;
publish again and a node's returned queue at it. A running still queues the versions waiting on its module.
A seat with no holder is logged by name.

Builds: design 47 G §588, A-416, A-416a
2026-11-15 02:18:38 +01:00
jschoubben f89f34ce7b builder: keep a published heard before the build's digests and say package-published when they are recorded
A trunk build's registry publishes during the build, before the builder records the digests on the reservation;
such a published was acknowledged and lost, so package-published was never said. It is now kept on the reservation
(name, version, digest) and marks its artifact when the digests are recorded; one that never matches is logged.

Builds: design 47 G §588, §52, §334, A-73, A-415
2026-11-15 02:07:47 +01:00
jschoubben 1506507f21 builder, assigner: say why a package-published is not said and why an added module carries no parts
Builds: design 47 G §588, §52, §334, A-73, A-316
2026-11-15 02:04:23 +01:00
jschoubben 8a340b5297 steprun: retry the seat list reader's start with backoff and say why asks are given back
Builds: design 47 G §543, A-163, §543 (lead-47 2026-11-15: the reader's start is retried)
2026-11-15 01:15:29 +01:00
jschoubben e0632b2c0e mesh-grants: the part makes the build seats' named workers its composed holders name (A-413)
Builds: design 47 G A-413, A-414
2026-11-15 01:03:52 +01:00
jschoubben 69c24b5270 mesh-grants: named asks stay in use while a wanted build invokes a queue; the named-asks decision is said (A-413, A-414)
Builds: design 47 G A-413, A-414
2026-11-15 00:49:09 +01:00
jschoubben 9496c57d41 mesh-grants: say how a want's newest build was read and which left-out modules' seat workers are not created (A-413, A-414)
Builds: design 47 G A-413, A-414
2026-11-15 00:32:20 +01:00
jschoubben 84e640b7d2 mesh-grants: a running build with no catalog entry is composed from the entry of its want's newest build (A-414)
Builds: design 47 G A-414 (A-407, A-413)
2026-11-15 00:24:41 +01:00
jschoubben c636642864 mesh-grants: named asks stay in use while a held membership publishes one (A-413)
Builds: design 47 G §544, A-413, A-231
2026-11-15 00:11:16 +01:00
jschoubben 9eb143ab6c mesh-grants: named asks stay in use while an account is granted to publish one (A-413)
Builds: design 47 G §544, A-413, A-231
2026-11-15 00:04:42 +01:00
jschoubben 598125a1d5 Builder: an entry's manifest digest is taken bare through the catalog contract's reading; a look that writes nothing says why
Builds: design 47 G A-412, A-412a
2026-11-14 23:46:01 +01:00
jschoubben 218d5cb67f Builder: read the last versions-filled at start from its kept stream, not EVENTS
The seat event's own stream is heard from its first message through the SDK's HearSeatEvents with FromFirst; nothing of EVENTS is read and no new grant is needed.

Builds: design 47 G A-411 (replaces A-408's read of EVENTS)
2026-11-14 23:39:06 +01:00
jschoubben c625733a33 Indexer: catalog-revision's duplicate id names the branch and it is published through the bus's acknowledgement
Builds: design 47 G A-409
2026-11-14 22:55:59 +01:00
jschoubben da82c2cf80 Grants: a consumed seat event matches the seat's event of that name whatever parts its subject has; a consume of a seat that says no such event is refused aloud, never a module's event
Builds: design 47 G A-409
2026-11-14 22:55:59 +01:00
jschoubben 0071181fb1 Builder: read the last versions-filled at start
The builder kept the catalog's versions-filled in memory only and its durable
consumer took the event once, so a restart left every build wait-held. It now
reads the last message of the subject from the events stream at its start (a
read that fails is retried with backoff in the background).

Builds: design 47 G A-408, §369, §372
2026-11-14 22:49:04 +01:00
jschoubben 1b3cc20127 Indexer: a head the source names with no merged message, or none it can read, is read whole through the seat git and taken in as a merge of every file of its tree, with its templates' needs and the predefined list (A-401, A-402)
Builds: design 47 G A-401, A-402, A-93, A-85
2026-11-14 22:17:44 +01:00
jschoubben 5b0925ce3a Indexer: take a registered module in at the head of its first watched branch when no build record names it: f1-circuits (master), link2pay and photos (nox-mesh) could not be held, so the assigner refused every proposal (design 47 G A-85) 2026-11-14 21:45:27 +01:00
jschoubben c9f70c9287 Assigner: read a whole state in pages, not a key at a time: the assignments took 27 s to read and a proposal outlasted its caller's 30 s, the same kind as the indexer's view of the trunk 2026-11-14 21:42:05 +01:00
jschoubben 7ce4720854 Assigner: say each step of a proposal with its time, and a node record slow or failing to read: a proposal that passed timed out at 30 s with no word of where 2026-11-14 21:36:46 +01:00
jschoubben 9a3a6bd3ba Forge bridge: say each member of a delivery group once: the seat named novox/mesh-sdk#189 twice in feat/47-G-join11, and every repository with a branch of that name was refused its take-in whole 2026-11-14 21:22:07 +01:00
jschoubben 3cdd4943f0 Indexer tools: keep the view of the trunk while its revision stays the newest, and page it: every key re-read the whole revision, so propose timed out on a first view of about 11 s a page
The assigner says each indexer view it reads, how many pages and how long, and a page that does not answer.
2026-11-14 20:59:31 +01:00
jschoubben 4ee5b45cb8 Grants: say each consumer it creates, and once each it cannot create: which bookmarks exist was readable only on the bus 2026-11-14 20:24:10 +01:00
jschoubben ddee3bf9af Assigner: a seat no assignments holds is written in seat-holders as held by the assigned module whose manifest claims it, and said (A-400): the indexer waited for a holder of mesh-module-assigner for ever 2026-11-14 20:21:17 +01:00
jschoubben 4a83418c02 Builder: says each toolchain it hears, and whether it changed what it knew 2026-11-14 19:00:01 +01:00
jschoubben 5f7f6b3e40 Grants make the tool runner's twin of each module durable with its rights; the builder binds its kept seat events (A-397) 2026-11-14 18:58:20 +01:00
jschoubben 5b4c454ca2 Grants: the holder of a seat pulled by kind says the seat's own events, on its machine where the subject names <node> (A-399): a build seat's step-ended and toolchain-reported were granted to nobody 2026-11-14 18:39:45 +01:00
jschoubben b0756f8b45 Grants: a seat-form read, view or view tool resolves to the assigned claimant when no holder is on record (A-398): the builder's reads of the build seats' steps stayed unresolved and refused 2026-11-14 18:17:20 +01:00
jschoubben 1695075836 Indexer: a seed's registration write ends no proposal key (an empty key stopped the seed after its first module); the history fill is read within a second and its failure said 2026-11-14 17:13:11 +01:00
jschoubben 306534fdf0 Indexer: a registration's write logs each step with its time; a first registration prunes nothing; a seed stopped part way writes what it has not 2026-11-14 17:01:52 +01:00
jschoubben 0933144535 Indexer: a take-in ask logs its start and end, and the seed logs each step, so a request that hangs says where 2026-11-14 16:55:48 +01:00
jschoubben 86fb18afb7 Indexer: a seed asked again writes the registrations its key composed, with no build seat asked again 2026-11-14 16:55:09 +01:00
jschoubben a6ab2e54cd Indexer: the first registrations are written from the module graph it holds, with no ask (the operator, 2026-11-14: a module in the module graph is a registration) 2026-11-14 16:44:13 +01:00
jschoubben 5255ffa0c4 Grants: a seat-named view also grants asking its holder's first-view tool, so a reader's first view is not refused by the bus (design 47 G §616; live start: the indexer's seat-holders view) 2026-11-14 16:26:59 +01:00
jschoubben b0d263c336 Indexer: a registration's ask names the module and its repository, not the manifest path (A-402)
Live on novox 2026-11-14 15:20 the operator channel refused the seed's ask: its lines named paths (modules/<m>/module.json),
which the messenger's check refuses as a file path or a random-looking run. Checked against the messenger's Check: the
seed's whole words pass.
2026-11-14 15:23:35 +01:00
jschoubben ba50db813a Test: the holder's own tools read its catalog revision (A-401) 2026-11-14 15:03:30 +01:00
jschoubben 3303e9170c Indexer: the seed's ask says a short digest, and the holder's own tools read its catalog revision (A-400, A-401)
Live on novox 2026-11-14 15:01 the operator channel refused the seed's ask for a 64-hex digest in its words, as a secret;
the Approve binds the whole digest through the option. The tool runner reads the catalog half for the indexer's own tools
on its account and was refused every minute.
2026-11-14 15:03:12 +01:00
jschoubben 6a91fa15f6 Indexer seed: the module directory goes with named paths only (ADR 0499 clause 4)
Live on novox the Go and Node build seats refused every seed steps call with 'the request names a module directory and no path': the trunk entries name no paths, and the seed sent the directory alone.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 12:17:27 +01:00
jschoubben 7e4c9b9992 Grants: every module is composed as invoking the tool runner's own reads (A-396)
Live on shanks the build runtimes' seat list and catalog-half reads were refused on their caller-named subjects, since the modules' manifests do not invoke them, and the no-caller fallback is answered by nobody.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 12:09:51 +01:00
jschoubben 34e1938df1 Indexer: every trunk part and the tool runner may read the catalog half (A-395)
Live on novox the tool runner's first view of catalog-revisions was refused 54 times: the revision verb answered only the parts declaring it in invokes, and the runner reads it for every module it serves.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 12:00:53 +01:00
jschoubben 990f6c6598 mesh-grants: a node seat's verb is also granted without the machine
Holders subscribe and callers publish on mesh.seat.<seat>.tool.<verb> (and its call form) beside the machine-named subject, so a verb asked of no machine is answered by any one holder in a queue group.

Builds: lead answer A-393 (design 47 G)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 11:32:20 +01:00
jschoubben e5bb4fa9bc indexer seed: an unanswering build seat is called once per seed
Later artifacts of a seat that did not answer stay unanswered without a call; one log line says so when the seat first goes unanswered. Per lead answer A-392.

Builds: design 47 G §704, lead answer A-392

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 11:25:20 +01:00
jschoubben acb12fea95 Test: the bus module's keeper consumer filters a watched mesh-seat event on its parts
Covers busstate.go keeperConsumer for the seat definition subject catalog-revision.<branch>: restoring the old body fails the table test.

Builds: design 47 G (seat definition subjects with parts)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 04:37:15 +01:00
jschoubben c37426f64b Grants: a watched seat event takes its definition's subject parts as * for any scope
mesh-catalog's seat.json gives catalog-revision the subject catalog-revision.<branch> (likewise source-moved.<branch>,
group-ended.<branch>.<group>, owed.<repository>.<number>). watchedEvents widened only a node seat the node-engine holds
(machineEvent), so the consumer and subscribe grant of a module consuming mesh-catalog.catalog-revision (node-tools,
builder, teller, pipeline) stayed on the bare subject and never took the branch-form event. One rule now
(watchedEventSubject, used by the grants and the bus module's consumer): each part is *. A held consumer gains the
filter through AddFilters (grants/consumers.go).

Builds: design 47 G (seat definition subjects with parts)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 04:33:47 +01:00
jschoubben 6edb9ab526 Indexer: say catalog-revision on its branch's subject, the one the bus allows
The bus refused the bare subject mesh.seat.mesh-catalog.event.catalog-revision: the seat definition
(mesh-delivery-contracts/seats/mesh-catalog/seat.json) gives the event the subject catalog-revision.<branch>, and the
holder is granted catalog-revision.*. The publish now uses meshcatalog.SubjectCatalogRevision(the event's branch); an event
with no branch is refused loudly, never given a bare subject.

Builds: design 47 G, the seat definition mesh-catalog (event catalog-revision, subject catalog-revision.<branch>)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 04:21:50 +01:00
jschoubben dc4f1dff39 Indexer: the start replay keeps the view once, and only when a build end wrote
lead answer A-391: the start replay keeps the view once (measured: 50 min CPU per start).
applyBuildEnd reports whether it wrote; ApplyBuildEnd keeps the view only then;
ApplyBuildEndsAtStart applies every entry and keeps the view once if any wrote.

Builds: design 47 G lead answer A-391

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 04:04:45 +01:00
jschoubben 6c47ffcf8f Indexer: a single * in invokes declares the verb revision (A-390)
The verb revision's callers rule matched seat:mesh-catalog.revision by exact text only; the grants part reads a single * as every seat verb, so node-tools was refused. Match that reading; the holder stays off the list.

Builds: design 47 G, lead answer A-390

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 03:20:47 +01:00
jschoubben 0259d77d11 mesh-catalog seat: class modules, module, provides, dependents and seat-definitions as reads
Before its catalog half is read, a tool runner's gate lets through the
verbs its held definition classes read; these five read only and are
now classed so.

Builds: design 47 G lead answers A-387

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 02:23:38 +01:00
jschoubben 1ed86db4aa mesh-delivery-forge-bridge: read the open groups, and one group by its id, never every ended group in one answer
The merged message and the catch-up asked the seat's groups with all=true, whose answer outgrew one bus message
(2888983 bytes, live 02:06), so no take-in answered. Read asks the open groups, MergedOf the one group its branch
names (group=<id>); the list a person asks (bridge_groups) keeps ReadAll.

Builds: lead: principle 7, live 02:06

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 02:12:17 +01:00
jschoubben 21b53f5dfb mesh-grants: read the loaded list one user per answer, so no answer exceeds one bus message
lead: principle 7, live hold 02:0x (nats_users for the whole list was 1086642 bytes, over 1048576).
Builds: design 47 G, lead's handover (no design line beyond principle 7)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 02:01:49 +01:00
jschoubben fa5df62e97 A-386 runner-left-out-is-kept-and-carried: a tool runner of the list in force that the pass composes no account for is kept as it runs and written as a carrying runner
Builds: design 47 G A-386 (G-22-lead-answers-2.md)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 01:53:44 +01:00
jschoubben 54a19f3f64 A-373 tools-read: a reader that cannot open a list or pass object is shown its small fields and where the rest is, so what the last pass said of the sealed list is readable
Builds: design 47 G A-373 (G-22-lead-answers-2.md), the tools' read of the keys list and pass

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 01:51:19 +01:00
jschoubben 6edfe1da8d A-386 kept-runner-carries-a-module-known-by-its-bindings: a module placed on a node whose manifest is unreadable is carried by a kept runner by its kept bindings alone
Builds: design 47 G A-386 (G-22-lead-answers-2.md), live read of the gate's membership

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 01:42:00 +01:00
jschoubben 89e36241cb A-386 kept-runner-gains-its-carried-modules-grants: a runner kept as it runs is the union of the list in force and a carrying runner's grants from the modules placed on its node
Builds: design 47 G A-386 (G-22-lead-answers-2.md)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 01:33:48 +01:00
jschoubben 14901e8723 A-385 runner-reads-a-carried-modules-bound-ledger: the tool runner carrying a module with a bound ledger reads its state, indexes, history and snapshots, and writes its state
Builds: design 47 G A-385 (G-22-lead-answers-2.md), their bindings

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 01:26:46 +01:00
jschoubben 66ae3cd918 A-385 kept-accounts-are-a-union: an account kept beyond a pass is the union of the list in force and what the pass composes for it, a held runner composed from its running build's manifest
Builds: design 47 G A-385 (G-22-lead-answers-2.md)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 01:09:07 +01:00
jschoubben c3fd353abe A-384 runner-hears-new-events: every tool runner account carries the ordered consumer of EVENTS and each kept seat stream, kept or held ones included
Builds: design 47 G A-384 (G-22-lead-answers-2.md)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 00:44:32 +01:00
jschoubben 968e1b7493 A-383 kept-accounts-gain-the-right-every-account-carries: a kept or held account of the list in force gains the streams' names, as every composed one does
Builds: design 47 G A-383 (G-22-lead-answers-2.md)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 00:23:49 +01:00
jschoubben 0ad09c7382 A-382 every-account-lists-stream-names: the composer gives every module, process, node and runner account the streams' names, in place of grants' own row
Builds: design 47 G A-382 (G-22-lead-answers-2.md), replaces A-381's special case

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 00:07:55 +01:00
jschoubben 8604d121eb A-381 grants-account-lists-stream-names: grants' account may ask the names of the bus's streams, which creating a kept event's stream asks first
Builds: design 47 G A-381 (G-22-lead-answers-2.md)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 23:59:38 +01:00
jschoubben d6d6bd1891 A-373 round 2: grants' account reads back its own objects; withheld is answered from a small key beside the list
Builds: design 47 G A-373 (G-22-lead-answers-2.md)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 22:09:21 +01:00
jschoubben e2eb99fc19 A-373 grants-list-and-pass-as-objects: the keys list and pass of user-list name an object of the part's bucket, since each outgrows one bucket value
Builds: design 47 G A-373 (G-22-lead-answers-2.md)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 22:04:21 +01:00
jschoubben fc51bf4832 Round 2: grants says the absent stream in its status and pass result; tests that fail without A-372's settle call and without Ready's reading of the first views
mesh/delivery ready: it is merged on the Approve
mesh/delivery-group group fix/47-G-start-2 checking: 2 of 2 member(s) ready
Builds: design 47 G A-371 health clause, A-372, A-368 (G-22-lead-answers-2.md)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 21:03:59 +01:00
jschoubben 3c929d518c A-365: a test through ApplySource sees the fingerprint computed again when a package's repository head moves
Builds: design 47 G A-365

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 21:03:09 +01:00
jschoubben e383004afc A-372 assigner-settles-on-a-mesh-naming-no-branch: the assigner's first pass is told once when the catalog client says the registrations and the source name no branch
Builds: design 47 G A-372 (G-22-lead-answers-2.md, hq design/47-G-lead-answers-31)
Also: Ready reads what the first views hold, since a first view closes before the follower's change is taken into the branches followed; Branches.FirstViews says when both are in.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 20:57:52 +01:00
jschoubben 27072735e9 gofmt 2026-11-13 20:57:34 +01:00
jschoubben 30f8e7407b A-370: the verb registrations is answered from its state at once, not queued behind a take-in
Builds: design 47 G A-370

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 20:57:29 +01:00
jschoubben 6458b72062 A-371 grants-empty-first-view-of-its-own-stream: a kept stream grants creates and the bus lacks is an empty first view, no wait
Builds: design 47 G A-371 (G-22-lead-answers-2.md, hq design/47-G-lead-answers-31)
Note: the earlier commit 7f3aeedf (A-369, grants' Waiting asks Ready) is titled S6 by mistake.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 20:56:33 +01:00
jschoubben 49fbb17db9 Review r1: candidates and the trunk take the source's head for an unpublished package; the own build is read inside ownBuildVia
Builds: design 47 G A-365, A-366

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 20:56:19 +01:00
jschoubben ff8b27c89b Merge branch 'fix/47-G-start-2-index' into fix/47-G-start-2 2026-11-13 20:45:59 +01:00
jschoubben 7f3aeedfc0 S6 grants-wait-asks-ready: grants' wait for its catalog half asks the catalog client's Ready, so a mesh naming no branch is none-yet
Builds: design 47 G A-369 (G-22-lead-answers-2.md)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 20:45:47 +01:00
jschoubben eaa903a8ec S4 catalog-ready-on-a-fresh-mesh: with the registrations and the gate's source answered and naming no branch, Ready is nil and the view is empty
Builds: design 47 G A-368 (G-22-lead-answers-2.md), start-waits.md S4

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 20:43:21 +01:00
jschoubben 72aba8c415 S2 grants-account-creates-kept-streams: a test holds that the grants account carries the create of each kept event stream of the seat list
Builds: design 47 G A-364 (G-22-lead-answers-2.md), start-waits.md S2

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 20:42:36 +01:00
jschoubben a118867b43 S1 grants-unread-catalog-no-hold: an entry not answered while the catalog half is unread is no failed read, so the list composes from the trunk and the want's entry
Builds: design 47 G A-363 (G-22-lead-answers-2.md), start-waits.md S1

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 20:41:44 +01:00
jschoubben 69b6fa7393 S5b: a mesh Go package no module publishes is built at the source's commit of its repository
Builds: design 47 G A-365

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 20:39:59 +01:00
jschoubben b2bddecde2 S3: the indexer takes its own build from MESH_FINGERPRINT first
Builds: design 47 G A-366

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 20:37:25 +01:00
jschoubben bac26c8a28 Merge pull request 'G start: the indexer serves modules again, the watchman builds, the graph's order comes from the verbs a package calls' (#216) from fix/47-G-start into main
Reviewed-on: #216
2026-11-13 19:08:09 +00:00
jschoubben 536c573223 A-361: a package's seat call words obey the cycle rule
mesh/delivery merged: source.main moved to novox/mesh-delivery@bac26c8a288b
mesh/delivery-group group fix/47-G-start merged: every member is merged
The graph left out only invoked verbs on a cycle, so a package's seat call word's kind-6 edge stayed on a cycle (the
gate and the indexer, the gate and mesh-hand-acts at every SDK release). The module graph's LeaveOut now runs over the
entries with each package's seat call words counted among the invokes of every module built against it, and what it
leaves out joins each entry's LeftOut.

Builds: design 47 G A-361, A-357; ADR 0614 §3
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 17:45:43 +01:00
jschoubben ec58535ca0 A-360: the indexer says each new trunk revision's change of modules on views.modules
The grants part follows the first view modules on the indexer's views family after its first ask. G's indexer keeps
no state modules, so nothing said its changes and a newly merged module reached grants only when it asked again. A
new trunk revision that changes the modules is now said as the mark of modules at that revision's number (the number
the first view answers every value at), after which a reader short of it asks the first view once; views.modules is
among the indexer's emits.

Builds: design 47 G A-360, A-354
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 17:33:57 +01:00
jschoubben 359c37d17f A-357: a package's seat-verb call word orders its users after the verb's server
A package's `calls` names the seat verbs its code calls on a module's behalf in the invokes form; the indexer derives
an edge of kind 6 from such a word against the verb's server, as from `invokes`, so every module built against the
SDK is delivered after the running versions that serve its start. The path for stated capability words stays.

Builds: design 47 G A-357, §47 (kind 6)
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 17:31:54 +01:00
jschoubben a015b5ed24 A-354: the indexer serves the first view modules again, for the grants part
The grants part reads mesh-delivery-indexer.modules as one of its five first views; G's indexer stopped serving it
(deb88b17), so the read is a failed gap and grants issues no new right once G's indexer runs. The tool comes back in
its form before G (the first-view tool over the state modules, its callers list), answered from the newest trunk
revision, until grants reads the catalog half.

Builds: design 47 G A-354
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 17:30:39 +01:00
jschoubben 4c112de4d5 A-355: the watchman requires and replaces the build seats it imports
cmd/mesh-delivery-watchman imports the seats nodebuildimage and nodebuildnode, but its go.mod named only
nodebuildgo, so the watchman did not build from main. Every G part builds from main before any is placed.

Builds: design 47 G A-355
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 17:28:04 +01:00
mesh-tools 21eaa55b27 Merge pull request 'Bridge for G's take-in: the pre-G package directories again, unused' (#215) from fix/47-G-bridge into main 2026-11-13 13:40:32 +00:00
jschoubben 541eaa20fe Bridge for G's take-in: the pre-G package directories contracts/go and sdk again, unused
mesh/delivery merged: source.main moved to novox/mesh-delivery@21eaa55b277a
mesh/delivery-group group fix/47-G-bridge merged: every member is merged
mesh/check checking 541eaa20fec4 on 21eaa55b277a
The running pre-G indexer publishes a repository's packages only when every package directory it published last is
still in the tree; G moved contracts/go and sdk to modules/, so mesh-delivery's packages, G's renamed paths among them,
are never published and nothing importing them builds (2026-11-13, indexer journal 'its packages are not published').
These are the trees of e70754ef, unchanged, without sdk/module.json (no second module). Nothing imports them; they go
once G's indexer runs and publishes without them.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 14:34:40 +01:00
mesh-tools 93e222a8a8 Merge pull request 'Milestone 47 G: mesh-delivery's part of the one release' (#214) from feat/47-G-join12 into main 2026-11-13 13:08:58 +00:00
1216 changed files with 81773 additions and 70429 deletions
@@ -1,225 +0,0 @@
package main
import (
"context"
"maps"
"slices"
"strings"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"mesh-delivery-assigner/internal/acting"
"mesh-delivery-assigner/internal/assign"
"mesh-delivery-assigner/internal/assigngraph"
"mesh-delivery-assigner/internal/assignment"
"mesh-delivery-assigner/internal/buckets"
)
// The waits for an acting part's new version in the steps the assigner holds (design 47 G §266, §268, §276): an entry of the assignment
// graph whose acting edge names composing or placing waits, its want held, until the part's version runs on the edge's node. The wait is
// kept in the state `waits` under `acting.<node>.<module>.<part>`, said as `wait-held` when it starts and `wait-ended` (ran, released,
// replaced) when it ends; `assigner_waits` reads it and `assigner_release` with how `now` lets the entry move with the part's running
// version. A node away starts no wait: its clock starts when the node is present (§268).
// actingOf is the Module.Acting of module: the held acting edges of its entry on a node, those whose wait was not released left out.
func (p *passer) actingOf(module string, released map[string]bool) func(node string) []assign.ActingEdge {
return func(node string) []assign.ActingEdge {
var out []assign.ActingEdge
if p.engineOn(node) == module {
return nil // the node-engine's own want is held by no acting edge, so it is written first (§268, A-323, A-330)
}
for _, e := range p.entryEdges(node, module) {
if acting.Held(e.Step) && !released[acting.Key(node, module, e.Module)+"@"+e.Fp] {
out = append(out, assign.ActingEdge{Node: e.Node, Part: e.Module, Fp: e.Fp, Step: e.Step})
}
}
return out
}
}
// engineOn is the module that holds the seat node-engine on node in the revision the pass computed, read from the acting edges'
// seat (A-330); "" when none is read.
func (p *passer) engineOn(node string) string {
if p.graph == nil {
return ""
}
return assigngraph.Engines(slices.Collect(maps.Values(p.graph.computed.Entries)))[node]
}
// entryEdges are the acting edges of the entry of module on node in the revision the pass computed.
func (p *passer) entryEdges(node, module string) []seat.Edge {
g := p.graph
if g == nil {
return nil
}
for _, ref := range g.computed.Revision.Entries {
if ref.Node == node && ref.Module == module {
var out []seat.Edge
for _, e := range g.computed.Entries[ref.Digest].Edges {
if e.Kind == "acting" {
out = append(out, e)
}
}
return out
}
}
return nil
}
// actingReleased is the waits released by hand and not yet run, by `<key>@<part's fingerprint>`.
func (p *passer) actingReleased() map[string]bool {
out := map[string]bool{}
for key, raw := range p.w.read(buckets.Waits()) {
if w, err := acting.Decode(raw); err == nil && w.Released && (acting.Is(key) || acting.IsOrder(key)) {
out[key+"@"+w.Fp] = true
}
}
return out
}
// actingWaits keeps the acting waits after the pass's wants: it starts the wait of each entry held for a part's version, ends the
// wait of one that ran, was replaced or was released, and says each.
func (p *passer) actingWaits(ctx context.Context, n assign.Nodes, wanted map[string]map[string]meshwants.Want) {
g := p.graph
if g == nil || p.kvs[buckets.Waits()] == nil {
return
}
now := p.clock()
kept := p.w.read(buckets.Waits())
standing := map[string]bool{}
engines := assigngraph.Engines(slices.Collect(maps.Values(g.computed.Entries)))
held := map[string]bool{} // `<node>/<module>` of each entry held for a part's version
for _, ref := range g.computed.Revision.Entries {
entry := g.computed.Entries[ref.Digest]
if w, ok := wanted[ref.Module][ref.Node]; ok && w.Fp == entry.Fp {
continue // the entry's version is wanted already: nothing moves, so nothing waits
}
if engines[ref.Node] == ref.Module {
continue // the node-engine's own want waits for no acting part (§268, A-323, A-330)
}
for _, e := range entry.Edges {
if e.Kind != "acting" || !acting.Held(e.Step) {
continue
}
key := acting.Key(ref.Node, ref.Module, e.Module)
if n.Runs(assign.ActingEdge{Node: e.Node, Part: e.Module, Fp: e.Fp, Step: e.Step}) {
continue
}
standing[key] = true
held[ref.Node+"/"+ref.Module] = true
if raw := kept[key]; raw != nil {
if w, err := acting.Decode(raw); err == nil && w.Entry == entry.Fp && w.Fp == e.Fp {
p.actingReleaseSaid(ctx, key, w)
continue
}
}
if !n.Online[ref.Node] {
continue // a node away holds only itself, and its clock has not started (§268)
}
w := acting.Wait{Step: e.Step, Node: ref.Node, Module: ref.Module, Part: e.Module, PartNode: e.Node, Fp: e.Fp, Entry: entry.Fp,
Since: now, ClockFrom: now, Bound: acting.BoundOf(e).String()}
if err := p.wantsSay(seat.EventWaitHeld, acting.Body(w, assignment.Module()), key+"."+e.Fp+"."+entry.Fp); err != nil {
p.logf("the wait of %s on %s for %s is not said, and is said at the next pass: %v", ref.Module, ref.Node, e.Module, err)
continue
}
p.put(ctx, buckets.Waits(), key, func() ([]byte, error) { return acting.Encode(w) })
}
}
p.actingCycles(g.computed.Entries, engines, held, n)
for key, raw := range kept {
if !acting.Is(key) || standing[key] {
continue
}
w, err := acting.Decode(raw)
if err != nil {
continue
}
how := acting.HowRan
if w.Released {
how = acting.HowReleased
} else if e, ok := p.edgeOf(w); !ok || !n.Runs(e) {
how = acting.HowReplaced
}
if !w.EndSaid {
body := acting.Body(w, assignment.Module())
body.How = how
if err := p.wantsSay(seat.EventWaitEnded, body, key+"."+w.Fp+"."+w.Entry+"."+how); err != nil {
p.logf("the end of the wait of %s on %s for %s is not said, and is said at the next pass: %v", w.Module, w.Node, w.Part, err)
continue
}
}
p.remove(ctx, buckets.Waits(), key)
}
}
// actingReleaseSaid says wait-ended of a wait released by hand, once, and keeps its record so the entry is not held again.
func (p *passer) actingReleaseSaid(ctx context.Context, key string, w acting.Wait) {
if !w.Released || w.EndSaid {
return
}
body := acting.Body(w, assignment.Module())
body.How = acting.HowReleased
body.By = w.By
if err := p.wantsSay(seat.EventWaitEnded, body, key+"."+w.Fp+"."+w.Entry+"."+acting.HowReleased); err != nil {
p.logf("the release of the wait of %s on %s for %s is not said, and is said at the next pass: %v", w.Module, w.Node, w.Part, err)
return
}
w.EndSaid = true
p.put(ctx, buckets.Waits(), key, func() ([]byte, error) { return acting.Encode(w) })
}
// edgeOf is the edge a kept wait stands on, as an acting edge.
func (p *passer) edgeOf(w acting.Wait) (assign.ActingEdge, bool) {
return assign.ActingEdge{Node: w.PartNode, Part: w.Part, Fp: w.Fp, Step: w.Step}, true
}
// actingCycles writes the finding acting-cycle of each held want whose holding edges lie on a cycle no rule breaks, and clears it of
// every other want, a finding a pass before or another process wrote included (design 47 G A-323, A-330). An edge holds while its
// step is the assigner's, its part's version does not run and its wait was not released; the node-engine's own want is held by none.
func (p *passer) actingCycles(entries map[string]seat.AssignmentEntry, engines map[string]string, held map[string]bool, n assign.Nodes) {
if p.findings.Put == nil {
return
}
released := p.actingReleased()
cycles := assigngraph.HeldCycles(slices.Collect(maps.Values(entries)), func(e seat.AssignmentEntry, edge seat.Edge) bool {
return held[e.Node+"/"+e.Module] && engines[e.Node] != e.Module && edge.Kind == "acting" && acting.Held(edge.Step) &&
!released[acting.Key(e.Node, e.Module, edge.Module)+"@"+edge.Fp] && !n.Runs(assign.ActingEdge{Node: edge.Node, Part: edge.Module, Fp: edge.Fp, Step: edge.Step})
})
raised := map[string]bool{}
for _, at := range slices.Sorted(maps.Keys(cycles)) {
node, module, _ := strings.Cut(at, "/")
o := assign.ActingCycleFinding(node, module, cycles[at])
key := mcseatKey(o)
raised[key] = true
if p.said[key+"="+o.Summary] {
continue // written already as it stands
}
if err := p.findings.Put(o.Finding(p.clock())); err != nil {
p.logf("the finding %s is not written: %v", key, err)
continue
}
p.said[key+"="+o.Summary] = true
}
if p.findings.Keys == nil || p.findings.Delete == nil {
return
}
keys, err := p.findings.Keys()
if err != nil {
p.logf("the findings %s are not read, so none is cleared this pass: %v", assign.KindActingCycle, err)
return
}
for _, key := range keys {
if strings.HasSuffix(key, "."+assign.KindActingCycle) && !raised[key] {
if err := p.findings.Delete(key); err != nil {
p.logf("the finding %s is not cleared: %v", key, err)
continue
}
for said := range p.said {
if strings.HasPrefix(said, key+"=") {
delete(p.said, said)
}
}
}
}
}
@@ -1,184 +0,0 @@
package main
import (
"context"
"encoding/json"
"strings"
"testing"
"time"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
mcseat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
mwc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"mesh-delivery-assigner/internal/acting"
"mesh-delivery-assigner/internal/assign"
"mesh-delivery-assigner/internal/buckets"
)
// Design 47 G §266, §268, §276 (AS9): an entry with an acting edge in composing waits for the part's version to run on the edge's node;
// the wait is kept, said as wait-held with its bound and clock-from, read by assigner_waits, released by assigner_release with how
// `now` and ended when the version runs.
func TestAnEntryWaitsForItsActingPartAndTheWaitIsKeptSaidAndEnded(t *testing.T) {
now := time.Date(2026, 11, 12, 9, 0, 0, 0, time.UTC)
p := newPasser(kvSet{buckets.Waits(): &memKV{values: map[string][]byte{}}}, now)
var events []string
var bodies []meshwants.Wait
p.publishWants = func(event string, body any, id string) error {
events = append(events, event)
bodies = append(bodies, body.(meshwants.Wait))
return nil
}
entry := meshwants.AssignmentEntry{Node: "ace", Module: "nats", Fp: fpTest, Edges: []meshwants.Edge{
{Kind: "acting", Node: "ace", Module: "mesh-host", Fp: "src2:new", Seat: "node-engine", Step: "compose", Bound: "15m"},
{Kind: "acting", Node: "ace", Module: "indexer", Fp: "src2:idx", Seat: "mesh-catalog", Step: "take-in"}}}
p.graph = &graphKeeper{}
p.graph.computed.Revision.Entries = []meshwants.NodeEntryRef{{Node: "ace", Module: "nats", Digest: "d1"}}
p.graph.computed.Entries = map[string]meshwants.AssignmentEntry{"d1": entry}
n := assign.Nodes{Online: map[string]bool{"ace": true}, Running: map[string]map[string]nodeengine.Running{"ace": {"mesh-host": {Fingerprint: "src2:old"}}}}
wanted := map[string]map[string]mwc.Want{"nats": {"ace": {Fp: "src2:older"}}}
ctx := context.Background()
if got := p.actingOf("nats", nil)("ace"); len(got) != 1 || got[0].Part != "mesh-host" {
t.Fatalf("the assigner holds composing only: %+v", got)
}
p.actingWaits(ctx, n, wanted)
p.actingWaits(ctx, n, wanted) // said once
if len(events) != 1 || events[0] != meshwants.EventWaitHeld {
t.Fatalf("events %v", events)
}
b := bodies[0]
if b.Step != "compose" || b.Part != "mesh-host" || b.Fp != "src2:new" || b.Bound != "15m0s" || b.ClockFrom == nil || !b.ClockFrom.Equal(now) || b.Owner == "" {
t.Errorf("wait-held %+v", b)
}
key := acting.Key("ace", "nats", "mesh-host")
if _, err := acting.Decode(p.w.read(buckets.Waits())[key]); err != nil {
t.Fatalf("the wait is kept: %v", err)
}
// a release by hand lets the entry move, and ends the wait once
w, _ := acting.Decode(p.w.read(buckets.Waits())[key])
w.Released = true
raw, _ := acting.Encode(w)
p.w.put(buckets.Waits(), key, raw)
if got := p.actingOf("nats", p.actingReleased())("ace"); len(got) != 0 {
t.Errorf("a released wait still holds: %+v", got)
}
p.actingWaits(ctx, n, wanted)
p.actingWaits(ctx, n, wanted)
if len(events) != 2 || events[1] != meshwants.EventWaitEnded || bodies[1].How != acting.HowReleased {
t.Fatalf("events %v bodies %+v", events, bodies)
}
// the version runs: the record goes, said nothing more
n.Running["ace"]["mesh-host"] = nodeengine.Running{Fingerprint: "src2:new"}
p.actingWaits(ctx, n, wanted)
if len(p.w.read(buckets.Waits())) != 0 || len(events) != 2 {
t.Errorf("kept %v events %v", p.w.read(buckets.Waits()), events)
}
}
func TestAnActingWaitOfANodeAwayStartsNoClockAndAnEntryWantedAlreadyWaitsNot(t *testing.T) {
p := newPasser(kvSet{buckets.Waits(): &memKV{values: map[string][]byte{}}}, time.Now())
p.publishWants = func(string, any, string) error { t.Fatal("said"); return nil }
p.graph = &graphKeeper{}
p.graph.computed.Revision.Entries = []meshwants.NodeEntryRef{{Node: "ace", Module: "nats", Digest: "d1"}}
p.graph.computed.Entries = map[string]meshwants.AssignmentEntry{"d1": {Node: "ace", Module: "nats", Fp: "src2:a", Edges: []meshwants.Edge{
{Kind: "acting", Node: "ace", Module: "mesh-host", Fp: "src2:new", Step: "compose"}}}}
n := assign.Nodes{Online: map[string]bool{}}
p.actingWaits(context.Background(), n, map[string]map[string]mwc.Want{})
n.Online["ace"] = true
p.actingWaits(context.Background(), n, map[string]map[string]mwc.Want{"nats": {"ace": {Fp: "src2:a"}}})
if len(p.w.read(buckets.Waits())) != 0 || strings.Contains(p.graph.computed.Entries["d1"].Fp, "x") {
t.Errorf("kept %v", p.w.read(buckets.Waits()))
}
}
func TestTheToolsReadAndReleaseAnActingWait(t *testing.T) {
var acts []string
s := newPutTools(memStore{waitsState: &memKV{values: map[string][]byte{}}, buckets.DeliveryWaitsState: &memKV{values: map[string][]byte{}}, buckets.DeliveredAgainState: &memKV{values: map[string][]byte{}}}, func(key string, body any) (json.RawMessage, error) {
acts = append(acts, key)
return json.RawMessage(`{"ok":true,"log":"logged"}`), nil
})
w := acting.Wait{Step: "compose", Node: "ace", Module: "nats", Part: "mesh-host", PartNode: "ace", Fp: "src2:new", Entry: "src2:a", Since: time.Now(), ClockFrom: time.Now(), Bound: "30m0s"}
raw, _ := acting.Encode(w)
s.st.put(waitsState, acting.Key("ace", "nats", "mesh-host"), raw)
got, err := s.doWaits(map[string]any{"module": "nats"})
if list := got.(map[string]any)["waits"].([]any); err != nil || len(list) != 1 || list[0].(actingSaid).BoundEnds == "" {
t.Fatalf("assigner_waits = %+v %v", got, err)
}
if _, err := s.doRelease(map[string]any{"node": "ace", "module": "nats", "how": "now"}, "x"); err == nil {
t.Error("a release with no why is taken")
}
if _, err := s.doRelease(map[string]any{"node": "ace", "module": "nats", "how": "now", "why": "the new engine is known good"}, "shanks.node-tools"); err != nil || len(acts) == 0 {
t.Fatalf("%v %v", err, acts)
}
raw, _, _, _ = s.st.get(waitsState, acting.Key("ace", "nats", "mesh-host"))
if r, _ := acting.Decode(raw); !r.Released || !strings.Contains(r.By, "known good") {
t.Errorf("wait = %+v", r)
}
}
// Design 47 G §268, A-323, A-330: the assigner and the node-engine on a node are one step: the node-engine's own want waits for no
// acting part, so it moves first, and the node's other wants, the assigner's own included, wait for the new node-engine; a want held
// on a cycle no rule breaks is the finding acting-cycle (scope module, id <node>.<module>) naming each edge's step, cleared by the
// next pass that finds it on none.
func TestTheNodeEngineIsWantedFirstAndAWantHeldOnACycleIsAFinding(t *testing.T) {
p := newPasser(kvSet{buckets.Waits(): &memKV{values: map[string][]byte{}}}, time.Date(2026, 11, 13, 2, 0, 0, 0, time.UTC))
p.publishWants = func(string, any, string) error { return nil }
findings := map[string]mcseat.Finding{}
p.findings = assign.Findings{
Put: func(f mcseat.Finding) error { findings[f.Scope+"."+f.ID+"."+f.Kind] = f; return nil },
Delete: func(key string) error { delete(findings, key); return nil },
Keys: func() ([]string, error) {
var keys []string
for k := range findings {
keys = append(keys, k)
}
return keys, nil
}}
compose := meshwants.Edge{Kind: "acting", Node: "ace", Module: "mesh-host", Fp: "src2:engine", Seat: "node-engine", Step: "compose"}
place := meshwants.Edge{Kind: "acting", Node: "ace", Module: "assigner", Fp: "src2:assigner", Seat: "mesh-wants", Step: "place"}
entries := map[string]meshwants.AssignmentEntry{
"d1": {Node: "ace", Module: "mesh-host", Fp: "src2:engine", Edges: []meshwants.Edge{place}},
"d2": {Node: "ace", Module: "assigner", Fp: "src2:assigner", Edges: []meshwants.Edge{compose}},
"d3": {Node: "ace", Module: "app", Fp: "src2:app", Edges: []meshwants.Edge{compose, place}},
}
p.graph = &graphKeeper{}
for d, e := range entries {
p.graph.computed.Revision.Entries = append(p.graph.computed.Revision.Entries, meshwants.NodeEntryRef{Node: e.Node, Module: e.Module, Digest: d})
}
p.graph.computed.Entries = entries
n := assign.Nodes{Online: map[string]bool{"ace": true}, Running: map[string]map[string]nodeengine.Running{"ace": {
"mesh-host": {Fingerprint: "src2:old"}, "assigner": {Fingerprint: "src2:old"}}}}
wanted := map[string]map[string]mwc.Want{}
if got := p.actingOf("mesh-host", nil)("ace"); len(got) != 0 {
t.Errorf("the node-engine's want is held by %+v, want by no acting edge", got)
}
if got := p.actingOf("assigner", nil)("ace"); len(got) != 1 || got[0].Part != "mesh-host" {
t.Errorf("the assigner's own want is held by %+v, want by the new node-engine", got)
}
p.actingWaits(context.Background(), n, wanted)
kept := p.w.read(buckets.Waits())
if kept[acting.Key("ace", "mesh-host", "assigner")] != nil || kept[acting.Key("ace", "assigner", "mesh-host")] == nil || kept[acting.Key("ace", "app", "mesh-host")] == nil {
t.Errorf("the waits kept: %v", kept)
}
if len(findings) != 0 {
t.Errorf("the cycle the node-engine's want breaks is a finding: %v", findings)
}
// Two parts holding each other across compose and place, neither the node-engine: no rule breaks it.
entries["d4"] = meshwants.AssignmentEntry{Node: "ace", Module: "x", Fp: "src2:x", Edges: []meshwants.Edge{{Kind: "acting", Node: "ace", Module: "y", Fp: "src2:y", Seat: "s-y", Step: "place"}}}
entries["d5"] = meshwants.AssignmentEntry{Node: "ace", Module: "y", Fp: "src2:y", Edges: []meshwants.Edge{{Kind: "acting", Node: "ace", Module: "x", Fp: "src2:x", Seat: "s-x", Step: "compose"}}}
p.graph.computed.Revision.Entries = append(p.graph.computed.Revision.Entries, meshwants.NodeEntryRef{Node: "ace", Module: "x", Digest: "d4"},
meshwants.NodeEntryRef{Node: "ace", Module: "y", Digest: "d5"})
p.actingWaits(context.Background(), n, wanted)
f, ok := findings["module.ace.x.acting-cycle"]
if len(findings) != 2 || !ok || !strings.Contains(f.Summary, "ace/x -[place]-> ace/y -[compose]-> ace/x") {
t.Fatalf("the findings of a cycle no rule breaks: %v", findings)
}
// x's new version runs: y no longer waits, so neither is held on a cycle, and both findings clear.
n.Running["ace"]["x"] = nodeengine.Running{Fingerprint: "src2:x"}
p.actingWaits(context.Background(), n, wanted)
if len(findings) != 0 {
t.Errorf("the findings after the cycle broke: %v", findings)
}
}
@@ -0,0 +1,117 @@
package main
import (
"errors"
"io/fs"
"os"
"slices"
"strings"
mmac "git.novox.be/novox/mesh-contracts/go/clients/meshmoduleassignerclient"
mma "git.novox.be/novox/mesh-contracts/go/seats/meshmoduleassigner"
"mesh-delivery-assigner/internal/judge"
)
// Which proposals the assigner asks of the operator is its setting ask-operator-for (design 47 G A-425, A-425a): a list of change
// kinds, set at mesh level with mesh-config's config, its default take-off, remove-node and stops. A proposal none of whose changes
// is listed is applied at once when its verdict passes, said in the log and by assignments-changed; one with a listed kind is
// asked as before. The setting is read from the file the manifest declares with the content ${config:ask-operator-for}, which the
// environment names (A-112), at every pass, and a change of it is said.
// KindStops is the change kind of a verdict whose answers say a node would stop running a module.
const KindStops = "stops"
// defaultAskOperatorFor is the setting's default.
var defaultAskOperatorFor = []string{mmac.OpTakeOff, mmac.OpRemoveNode, KindStops}
// askKinds are the kinds the setting may name.
var askKinds = []string{mmac.OpPlace, mmac.OpTakeOff, mmac.OpPin, mmac.OpUnpin, mmac.OpHold, mmac.OpUnhold, mmac.OpDecide, mmac.OpConfig,
mmac.OpAddNode, mmac.OpRemoveNode, KindStops}
// parseAskOperatorFor reads the setting's value: kinds separated by commas or spaces; empty is the default. A kind it does not
// know is answered apart and named nowhere in the list.
func parseAskOperatorFor(raw string) (kinds, unknown []string) {
fields := strings.FieldsFunc(raw, func(r rune) bool { return r == ',' || r == ' ' || r == '\n' || r == '\t' })
if len(fields) == 0 {
return slices.Clone(defaultAskOperatorFor), nil
}
for _, f := range fields {
f = strings.ToLower(strings.TrimSpace(f))
switch {
case !slices.Contains(askKinds, f):
unknown = append(unknown, f)
case !slices.Contains(kinds, f):
kinds = append(kinds, f)
}
}
slices.Sort(kinds)
return kinds, unknown
}
// readAskOperatorFor reads the setting's file: the default for no path or no file.
func readAskOperatorFor(path string) (kinds, unknown []string, err error) {
if path == "" {
k, u := parseAskOperatorFor("")
return k, u, nil
}
raw, err := os.ReadFile(path)
if errors.Is(err, fs.ErrNotExist) {
k, u := parseAskOperatorFor("")
return k, u, nil
}
if err != nil {
return nil, nil, err
}
k, u := parseAskOperatorFor(string(raw))
return k, u, nil
}
// askOperatorFor is the setting as this pass read it: the file read again each pass, a change said once, a file that cannot be
// read keeping what was read last (the default before any).
func (p *passer) askOperatorFor() []string {
kinds, unknown, err := readAskOperatorFor(p.askForFile)
if err != nil {
if p.askFor == nil {
p.askFor = slices.Clone(defaultAskOperatorFor)
}
p.logf("the setting ask-operator-for cannot be read from %s, so %s stands: %v", p.askForFile, strings.Join(p.askFor, ", "), err)
return p.askFor
}
if !slices.Equal(kinds, p.askFor) {
words := "the setting ask-operator-for is " + strings.Join(kinds, ", ") + ": a proposal with a change of another kind only is applied with no ask"
if len(unknown) > 0 {
words += "; kinds it names that are none are left out: " + strings.Join(unknown, ", ")
}
p.logf("%s", words)
p.askFor = kinds
}
return p.askFor
}
// asksFor says whether a proposal of these change kinds is asked of the operator.
func (p *passer) asksFor(kinds []string) bool {
set := p.askOperatorFor()
for _, k := range kinds {
if slices.Contains(set, k) {
return true
}
}
return false
}
// proposalKinds are the change kinds of a proposal whose verdict is v: each change's op, and stops when an answer says a node
// would stop running a module.
func proposalKinds(prop mma.Proposal, v mma.Verdict) []string {
var out []string
for _, c := range prop.Changes {
if c.Op != "" && !slices.Contains(out, c.Op) {
out = append(out, c.Op)
}
}
if len(judge.Stops(v)) > 0 {
out = append(out, KindStops)
}
slices.Sort(out)
return out
}
@@ -0,0 +1,162 @@
package main
import (
"encoding/json"
"errors"
"fmt"
"slices"
"strings"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/process"
)
// The seat mesh-wants' work queue read and steered by hand (design 47 H2 §777, the tools table; H-A-410): assigner_asks
// answers what waits on the seat's queue (read by the runtime without taking it) and what the assigner took and keeps
// dropped in its state taken; assigner_ask_drop ends one ask through the seat's act drop, written in the hand-act log first.
const (
asksTool = "assigner_asks"
askDropTool = "assigner_ask_drop"
)
// asksAnswerMost is the most an asks answer carries of the taken keys (§811: at most 768 KB with capped and total).
const asksAnswerMost = 768 << 10
// takenReader is what assigner_asks reads of the state taken (stdio.KeptState).
type takenReader interface {
Keys() ([]string, error)
Get(key string) (*stdio.StateEntry, error)
}
// asksOf is assigner_asks' answer: the asks on the seat's queue, each waiting, waiting again or held, the ids taken (key mesh-wants.<ask>) and the drops of
// asks not pulled yet (dropped.<ask>), each list cut at the answer's bound with capped and total.
func asksOf(waiting func(seat string) (stdio.Waiting, error), taken takenReader) (map[string]any, error) {
w, err := waiting(meshwants.Seat)
if err != nil {
return nil, fmt.Errorf("the asks waiting on the seat %s's work queue are not read: %w", meshwants.Seat, err)
}
keys, err := taken.Keys()
if err != nil {
return nil, fmt.Errorf("the state %s is not listed: %w", process.TakenState, err)
}
slices.Sort(keys)
// An ask the queue handed out and not acknowledged (again) is held when this holder took it, else it waits again after a
// nak (H-A-410's addenda): the bus says what it knows, the state taken the rest.
size := 0
waits := make([]map[string]any, 0, len(w.Asks))
for _, a := range w.Asks {
size += len(a.ID) + len(a.Module) + 64
state := "waiting"
if a.Again {
state = "waiting again"
if slices.Contains(keys, process.TakenKey(meshwants.Seat, a.ID)) {
state = "held"
}
}
waits = append(waits, map[string]any{"id": a.ID, "module": a.Module, "age_seconds": a.AgeSeconds, "state": state})
}
takenIDs, dropped := []string{}, []map[string]any{}
total, capped := 0, w.Capped
for _, k := range keys {
if id, ok := strings.CutPrefix(k, process.TakenKey(meshwants.Seat, "")); ok {
total++
if size += len(id) + 4; size > asksAnswerMost {
capped = true
continue
}
takenIDs = append(takenIDs, id)
continue
}
id, ok := strings.CutPrefix(k, droppedPrefix)
if !ok {
continue
}
total++
e, err := taken.Get(k)
if err != nil || e == nil {
continue
}
var d askDrop
if json.Unmarshal(e.Value, &d) != nil {
continue
}
if size += len(id) + len(d.By) + len(d.Why) + 64; size > asksAnswerMost {
capped = true
continue
}
dropped = append(dropped, map[string]any{"id": id, "by": d.By, "why": d.Why, "at": d.At})
}
return map[string]any{"waiting": waits, "taken": takenIDs, "dropped": dropped, "capped": capped, "total": total + len(w.Asks)}, nil
}
// asksTools are the module's tools of the seat's work queue.
func asksTools(waiting func(string) (stdio.Waiting, error), taken takenReader, ask func(string, any) (json.RawMessage, error)) []stdio.Tool {
return []stdio.Tool{
{Name: asksTool, Description: "The asks of the seat mesh-wants' work queue (design 47 H2 §777): each one on it (its id, the module " +
"that asked it, its age and whether it waits, waits again after a hand-back or is held here), the ids the assigner took (kept for ask-taken-bound) and the drops of asks not pulled yet, " +
"cut at 768 KB with capped and total. Read-only.",
Input: schema(map[string]string{}, nil),
Run: func(map[string]any) (any, error) {
return asksOf(waiting, taken)
}},
{Name: askDropTool, Description: "End one ask of the seat mesh-wants by hand (design 47 H2 §777, §778): written in the hand-act log " +
"first, then the seat's act drop ends it: one running is cancelled, one waiting is ended when it is pulled; either ends " +
"its step could not run naming the drop and who asked it.",
Input: schema(map[string]string{"ask": "the ask's id", "why": "why the ask is ended"}, []string{"ask", "why"}),
Run: func(args map[string]any) (any, error) {
id, why := strings.TrimSpace(arg(args, "ask")), strings.TrimSpace(arg(args, "why"))
if id == "" || why == "" {
return nil, errors.New("name the ask and why it is ended")
}
by := stdio.CallerOf(args)
taken, err := meshhandactsclient.Recorder{Ask: ask}.Record(meshhandactsclient.Request{What: askDropTool + " " + id, Why: why + " (" + by + ")", Cause: "ask-drop"})
if err != nil {
return nil, fmt.Errorf("the hand act was not recorded, so nothing was dropped: %w", err)
}
raw, err := ask("seat:"+meshwants.Seat+"."+meshwants.VerbDrop, meshwants.DropInput{ID: id, By: askDropTool + " (" + by + ")", Why: why})
if err != nil {
return nil, err
}
var out map[string]any
if err := json.Unmarshal(raw, &out); err != nil {
return nil, fmt.Errorf("%s answered what is not JSON: %w", meshwants.VerbDrop, err)
}
out["hand-act"] = taken.Log
return out, nil
}},
}
}
// keepNowTool is the tool assigner_keep_now (design 47 H2 §813 (2); H-A-417): written in the hand-act log first, then the seat
// mesh-wants' act keep-now runs the keeping of the assignment graph's revisions at once in the assigner's process.
const keepNowTool = "assigner_keep_now"
func keepNowTools(ask func(string, any) (json.RawMessage, error)) []stdio.Tool {
return []stdio.Tool{{Name: keepNowTool, Description: "Keep the assignment graph's revisions now (design 47 H2 §813 (2)): written in the " +
"hand-act log first, then the assigner keeps the pass's newest computed revision at once and answers the revision kept, or " +
"the fault the keeping met (a failed keeping runs again after keeping-retry; keeping-failed is raised at the third in a row).",
Input: schema(map[string]string{"why": "why the keeping runs now"}, []string{"why"}),
Run: func(args map[string]any) (any, error) {
why := strings.TrimSpace(arg(args, "why"))
if why == "" {
return nil, errors.New("say why the keeping runs now")
}
taken, err := meshhandactsclient.Recorder{Ask: ask}.Record(meshhandactsclient.Request{What: keepNowTool, Why: why + " (" + stdio.CallerOf(args) + ")", Cause: "keep-now"})
if err != nil {
return nil, fmt.Errorf("the hand act was not recorded, so nothing was kept: %w", err)
}
raw, err := ask("seat:"+meshwants.Seat+"."+meshwants.VerbKeepNow, meshwants.KeepNowInput{Why: why})
if err != nil {
return nil, err
}
var out map[string]any
if err := json.Unmarshal(raw, &out); err != nil {
return nil, fmt.Errorf("%s answered what is not JSON: %w", meshwants.VerbKeepNow, err)
}
out["hand-act"] = taken.Log
return out, nil
}}}
}
@@ -68,7 +68,7 @@ func TestTheAssignersAsksAreTheSeatMeshWantsAsks(t *testing.T) {
if err != nil {
t.Fatal(err)
}
if v, err := meshwants.DecodeAsksByHoldModuleFingerprintValue(raw); err != nil || v.Asking != 2 {
if v, _, err := meshwants.DecodeAsksByHoldModuleFingerprintValue(raw); err != nil || v.Asking != 2 {
t.Errorf("the ask %s is not the seat's Ask: %+v, %v", raw, v, err)
}
}
@@ -4,6 +4,9 @@ import (
"context"
"encoding/json"
"fmt"
"maps"
"strconv"
"strings"
"sync"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
@@ -97,7 +100,7 @@ func (r *releasedVersions) put(data []byte) error {
}
parts := map[string]string{}
for _, a := range e.Artifacts {
parts[e.Module+":"+a.Artifact] = a.Digest
parts[partRef(e.Module, a.Artifact)] = a.Digest
}
r.mu.Lock()
defer r.mu.Unlock()
@@ -116,6 +119,41 @@ func (r *releasedVersions) put(data []byte) error {
return nil
}
// withParts is the version of module whose release named exactly parts (`<module>:<artifact>` -> digest), the newest such when
// more than one did; false when none did or parts is empty (design 47 G A-421).
func (r *releasedVersions) withParts(module string, parts map[string]string) (assign.KeptBuild, bool) {
if len(parts) == 0 {
return assign.KeptBuild{}, false
}
r.mu.Lock()
defer r.mu.Unlock()
var out assign.KeptBuild
found := false
for key, k := range r.seen {
if m, _, ok := strings.Cut(key, "@"); !ok || m != module || !maps.Equal(k.Parts, parts) {
continue
}
if !found || compareVersion(k.Version, out.Version) > 0 {
out, found = k, true
}
}
return out, found
}
// madeOf is what module's done build at fp made, by `<module>:<artifact>`, as its build.ended names it; none for a build not heard
// or not done (design 47 G A-421).
func (b *builtEnds) madeOf(module, fp string) map[string]string {
e, ok := b.endOf(module, fp)
if !ok || e.Outcome != builds.BuildDone {
return nil
}
parts := map[string]string{}
for name, digest := range e.Made {
parts[module+":"+name] = digest
}
return parts
}
// of is the version of module released from the source revision, with its parts' digests; false before it is heard.
func (r *releasedVersions) of(module string, source int64) (assign.KeptBuild, bool) {
r.mu.Lock()
@@ -143,7 +181,7 @@ func hearBuilds(ctx context.Context, js jetstream.JetStream, ends *builtEnds, wa
logf("acknowledging %s: %v", m.Subject(), err)
}
wake()
}, logf)
}, logf, process.FromFirst()) // read whole from its first message whether the bus keeps it last per subject or by age (A-181, A-233)
if err != nil {
nh.NotHeard(buildsStreamName, "what the builder built is not heard until the assigner starts again, so no want names a build's parts or its keeping node and no put goes on", err)
return
@@ -155,16 +193,29 @@ func hearBuilds(ctx context.Context, js jetstream.JetStream, ends *builtEnds, wa
}()
}
// hearTaken registers the hub's taker of the indexer's take-in.taken, each waking the pass (orderwaits.go, §298, A-260); before
// the hub starts.
func hearTaken(hub *process.EventHub, taken *takenSources, wake func(), logf func(string, ...any)) error {
return hub.Handle(takenSubject, func(m jetstream.Msg) {
if err := taken.put(m.Data()); err != nil {
logf("%s is not kept: %v", m.Subject(), err)
// compareVersion orders two MAJOR.MINOR.PATCH versions by their numbers; a part that is no number counts as 0.
func compareVersion(a, b string) int {
pa, pb := strings.Split(a, "."), strings.Split(b, ".")
for i := 0; i < 3; i++ {
var x, y int
if i < len(pa) {
x, _ = strconv.Atoi(pa[i])
}
if err := m.Ack(); err != nil {
logf("acknowledging %s: %v", m.Subject(), err)
if i < len(pb) {
y, _ = strconv.Atoi(pb[i])
}
wake()
})
if x != y {
return x - y
}
}
return 0
}
// partRef is a release's artifact as a part's key, `<module>:<artifact>`: the contract's VersionArtifact names the artifact
// reference whole (an ArtifactRef), as the catalog's version-released says it; a bare name is taken as the module's (A-96).
func partRef(module, artifact string) string {
if strings.Contains(artifact, ":") {
return artifact
}
return module + ":" + artifact
}
@@ -2,7 +2,9 @@ package main
import (
"encoding/json"
"fmt"
"reflect"
"strings"
"testing"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-builder/builds"
@@ -54,11 +56,12 @@ func TestAVersionReleasedHeardNamesItsVersionAndPartsBySource(t *testing.T) {
}
}
// Design 47 G §379, A-96: the trunk's entry takes its version and parts from the version-released of the kept assignment graph
// revision's source; a kept build from its end; no revision kept, or another fingerprint, names none.
func TestATrunkEntryTakesItsVersionFromTheReleaseOfTheKeptRevisionsSource(t *testing.T) {
// Design 47 G §379, A-96, A-421; H §764, H-A-48: the trunk's entry, which the catalog stamps with no source, takes its version and
// parts from the version-released whose parts are what its build.ended made; a kept build from its end; no revision kept, another
// fingerprint and a build whose parts no release names name none, and an unheard release is said once.
func TestATrunkEntryTakesItsVersionFromTheReleaseOfItsBuildsParts(t *testing.T) {
w := newWorld()
raw, _ := json.Marshal(meshcatalog.VersionReleasedEvent{Module: "mail", Source: 7, Version: "1.2.3", Artifacts: []meshcatalog.VersionArtifact{{Artifact: "image", Digest: "sha256:9"}}})
raw, _ := json.Marshal(meshcatalog.VersionReleasedEvent{Module: "mail", Source: 7, Version: "1.2.3", Artifacts: []meshcatalog.VersionArtifact{{Artifact: "mail:image", Digest: "sha256:9"}}})
if err := w.released.put(raw); err != nil {
t.Fatal(err)
}
@@ -66,45 +69,44 @@ func TestATrunkEntryTakesItsVersionFromTheReleaseOfTheKeptRevisionsSource(t *tes
if err := w.ends.put(endRaw); err != nil {
t.Fatal(err)
}
p := &passer{w: w, graph: &graphKeeper{ok: true, source: 7}}
var logs []string
p := &passer{w: w, graph: &graphKeeper{ok: true, source: 7}, logf: func(f string, a ...any) { logs = append(logs, fmt.Sprintf(f, a...)) }}
named := p.namedBuild("mail", "t")
if k, ok := named("t"); !ok || k.Version != "1.2.3" || k.Parts["mail:image"] != "sha256:9" || k.KeptOn != "" {
t.Errorf("trunk entry = %+v, %v", k, ok)
if _, ok := named("t"); ok {
t.Error("a trunk entry whose build.ended is not heard names a version")
}
_, _ = named("t")
if k, ok := named("k"); !ok || k.KeptOn != "g14" || k.Version != "" {
t.Errorf("kept build = %+v, %v", k, ok)
}
if _, ok := named("other"); ok {
t.Error("another fingerprint names a release")
}
p.graph.source = 8
if _, ok := named("t"); ok {
t.Error("a source with no release names a version")
// A build held back at an older fingerprint names the release whose parts are exactly what it made.
heldRaw, _ := json.Marshal(builds.BuildEnded{Module: "mail", Fingerprint: "old", Made: map[string]string{"image": "sha256:9"}})
if err := w.ends.put(heldRaw); err != nil {
t.Fatal(err)
}
if k, ok := named("old"); !ok || k.Version != "1.2.3" {
t.Errorf("a held build whose parts were released = %+v, %v; want 1.2.3", k, ok)
}
// The entry's module value carries no source stamp: the catalog writes none (H-A-48).
if v, _, _ := fromEntry(meshcatalog.CatalogEntry{Module: "mail", Fp: "t", Inputs: &meshcatalog.EntryInputs{}}); v.Fp2 != "t" {
t.Errorf("the entry's module value is %+v", v)
}
made, _ := json.Marshal(builds.BuildEnded{Module: "mail", Fingerprint: "t", Made: map[string]string{"image": "sha256:9"}})
if err := w.ends.put(made); err != nil {
t.Fatal(err)
}
p.graph.source = 8 // a later merge that did not rebuild mail
if k, ok := named("t"); !ok || k.Version != "1.2.3" || k.Parts["mail:image"] != "sha256:9" {
t.Errorf("the trunk entry whose build made the released digests: %+v, %v", k, ok)
}
if len(logs) != 1 || !strings.Contains(logs[0], "the release of mail at fingerprint t is not heard: no version-released of it names the parts its build.ended made") {
t.Errorf("logs = %q, want the unheard release said once, naming the module and the fingerprint", logs)
}
p.graph.ok = false
if _, ok := p.namedBuild("mail", "t")("t"); ok {
t.Error("no revision kept names a release")
}
}
// A-162: the assigner knows a failed build from its `build.ended`: the error whole; a done end or none heard is not failed.
func TestTheStandingOfABuildIsHeardFromItsEnd(t *testing.T) {
w := newWorld()
say := func(e builds.BuildEnded) {
raw, _ := json.Marshal(e)
if err := w.ends.put(raw); err != nil {
t.Fatal(err)
}
}
if failed, _ := w.buildStanding("web", "fp1"); failed {
t.Error("a build nothing was heard of failed")
}
say(builds.BuildEnded{Module: "web", Fingerprint: "fp1", Outcome: builds.BuildFailed, Error: "transport fault: connection"})
if failed, why := w.buildStanding("web", "fp1"); !failed || why != "transport fault: connection" {
t.Errorf("failed end: failed %v why %q", failed, why)
}
say(builds.BuildEnded{Module: "web", Fingerprint: "fp1", Outcome: builds.BuildDone})
if failed, _ := w.buildStanding("web", "fp1"); failed {
t.Error("a later done end leaves the build failed")
}
}
@@ -28,18 +28,25 @@ func (p *passer) addedOf(node string, laid *mma.Assignments, current map[string]
if p.ends.following() {
branch = p.ends.branchOf(module, placed[module])
}
fp := p.w.trunkOf(branch)[module].Fp2
entry := p.w.trunkOf(branch)[module]
fp := entry.Fp2
if fp == "" {
p.skippedAdd(node, module, "", "the branch "+branch+" names no fingerprint of it")
continue
}
k, ok := p.namedBuild(module, fp)(fp)
if !ok {
p.skippedAdd(node, module, fp, "no version-released of it is heard for that fingerprint, so the candidate carries no version and no parts")
continue
}
if out == nil {
out = map[string]mma.AddedModule{}
}
out[module] = mma.AddedModule{Version: k.Version, Parts: k.Parts}
added := mma.AddedModule{Version: k.Version, Parts: k.Parts}
if k.Version != "" {
added.Parts = nil // a released build is named by its version alone (design 47 G A-430, A-430a)
}
out[module] = added
}
return out
}
@@ -48,3 +55,18 @@ func (p *passer) addedOf(node string, laid *mma.Assignments, current map[string]
func (p *passer) candidateOf(id, node string, laid *mma.Assignments, current map[string]mma.Assignments) mma.CandidatesByProposalNodeValue {
return mma.CandidatesByProposalNodeValue{Proposal: id, Assignments: laid, Added: p.addedOf(node, laid, current)}
}
// skippedAdd says once per node, module and fingerprint why a module the candidate adds is not listed in `added`.
func (p *passer) skippedAdd(node, module, fp, why string) {
key := node + "/" + module + "@" + fp + ": " + why
if p.skipped[key] {
return
}
if p.skipped == nil {
p.skipped = map[string]bool{}
}
p.skipped[key] = true
if p.logf != nil {
p.logf("the candidate adds %s to %s with no parts: %s (fingerprint %q)", module, node, why, fp)
}
}
@@ -20,21 +20,25 @@ func TestACandidateThatAddsAModuleCarriesItsParts(t *testing.T) {
w.putModule("main", m, meshcatalog.ModulesByModuleValue{Fp2: "fp-" + m}, graph.Node{}, nil)
}
w.first = "main"
rel, _ := json.Marshal(meshcatalog.VersionReleasedEvent{Module: "mail", Source: 7, Version: "1.2.3", Artifacts: []meshcatalog.VersionArtifact{{Artifact: "image", Digest: "sha256:9"}}})
rel, _ := json.Marshal(meshcatalog.VersionReleasedEvent{Module: "mail", Source: 7, Version: "1.2.3", Artifacts: []meshcatalog.VersionArtifact{{Artifact: "mail:image", Digest: "sha256:9"}}})
if err := w.released.put(rel); err != nil {
t.Fatal(err)
}
built, _ := json.Marshal(builds.BuildEnded{Module: "mail", Fingerprint: "fp-mail", Made: map[string]string{"image": "sha256:9"}})
if err := w.ends.put(built); err != nil {
t.Fatal(err)
}
end, _ := json.Marshal(builds.BuildEnded{Module: "db", Fingerprint: "fp-db", Made: map[string]string{"program": "sha256:3"}, KeptOn: "g14"})
if err := w.ends.put(end); err != nil {
t.Fatal(err)
}
w.put(buckets.Wants(), "want.ace.web", []byte(`{}`))
p := &passer{w: w, graph: &graphKeeper{ok: true, source: 7}}
p := &passer{w: w, graph: &graphKeeper{ok: true, source: 9}} // a later merge: the release is matched by the parts its build made (A-421, H-A-48)
laid := &mma.Assignments{Node: "ace", Modules: []mma.PlacedModule{{Module: "mail"}, {Module: "web"}, {Module: "db"}, {Module: "old"}}}
current := map[string]mma.Assignments{"ace": {Node: "ace", Modules: []mma.PlacedModule{{Module: "old"}}}}
c := p.candidateOf("p1", "ace", laid, current)
want := map[string]mma.AddedModule{
"mail": {Version: "1.2.3", Parts: map[string]string{"mail:image": "sha256:9"}},
"mail": {Version: "1.2.3"}, // a released build is named by its version alone (A-430a)
"db": {Parts: map[string]string{"db:program": "sha256:3"}},
}
if c.Proposal != "p1" || c.Assignments != laid || !reflect.DeepEqual(c.Added, want) {
@@ -0,0 +1,380 @@
package main
import (
"context"
"encoding/json"
"errors"
"fmt"
"slices"
"strings"
"time"
"github.com/nats-io/nats.go/jetstream"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/nodebuildgo"
"git.novox.be/novox/mesh-sdk/go/buscalls"
)
// A composition run's bound (design 47 G §720; A-466n, A-466p, A-466q, A-466s, A-468b, A-469b, A-469s, A-469y, A-470): a run
// has one clock, the key `bound.<run key>` of composition-runs with its own time to live composition-step-bound, written at the
// build seat's ask-taken of the run's ask and written again at each step-progress of that ask; an ask still waiting in the queue
// has no clock but `untaken.<run key>`, written at the run's start with the time to live run-untaken-bound. Either's expiry,
// heard as the bus's event, ends the run: its ask dropped through the build seat's drop, the run ended could not run naming the
// ask and the bound, so every reader ends could not run with it. While the ask waits for a build node each reader is said waiting
// by a wait-held on mesh-wants (`on: build node`), ended `ran` at ask-taken or `superseded` when the run ends untaken.
// waitOnBuildNode is what a composition run's waiting reader waits on (A-469b, A-469y).
const waitOnBuildNode = "build node"
// dropVerbKey is the Go build seat's drop, asked as a kept call (§119, A-182).
const dropVerbKey = "seat:" + nodebuildgo.Seat + "." + nodebuildgo.VerbDrop
// dropOver asks the Go build seat's drop of a run ask as a kept call, of any holder, which records it (A-469s).
func dropOver(call func(key string, body any) (json.RawMessage, error)) func(ask, why string) error {
return func(ask, why string) error {
raw, err := call(dropVerbKey, nodebuildgo.DropInput{ID: ask, Why: why, By: runAsker})
if err != nil {
return err
}
if _, said, ok := buscalls.Unwrap(raw); !ok {
return fmt.Errorf("%s answered: %s", dropVerbKey, said)
}
return nil
}
}
// waitOf is a reader's wait for a build node to take its run's ask (A-469y).
func waitOf(run meshwants.CompositionRun, reader meshwants.CompositionReader) meshwants.Wait {
w := meshwants.Wait{Step: "pipeline", Owner: meshwants.Seat, Module: reader.Module, Node: run.Machine, On: waitOnBuildNode, Fp: reader.Fingerprint,
Words: fmt.Sprintf("the composition step of %s waits for a build node to take the composition run %s of %s (ask %s)", reader.Pipeline,
runKeyOf(run.Candidate, run.Machine), run.Machine, run.Ask)}
if run.Started != nil {
w.Since = *run.Started
}
return w
}
// sayWaits says, for each reader, its wait held or ended (how: ran, superseded); a wait that cannot be said is journaled.
func (r *compositionRuns) sayWaits(run meshwants.CompositionRun, readers []meshwants.CompositionReader, how string) {
if r.say == nil {
return
}
for _, c := range readers {
w := waitOf(run, c)
event, id := meshwants.EventWaitHeld, "composition."+runKeyOf(run.Candidate, run.Machine)+"."+run.Ask+"."+c.ID+".held"
if how != "" {
w.How, event, id = how, meshwants.EventWaitEnded, strings.TrimSuffix(id, ".held")+".ended"
}
if err := r.say(event, w, id); err != nil {
r.logf("the %s of %s on the composition run of %s is not said: %v", event, c.Pipeline, run.Machine, err)
}
}
}
// untaken is whether the run of ask has not been taken yet: its untaken key stands holding that ask (A-470n).
func (r *compositionRuns) untaken(key, ask string) bool {
held, _, standing, err := r.boundOf(runUntakenPrefix + key)
return err == nil && standing && held == ask
}
// boundOf reads a bound key: the ask it holds and its revision; standing false when it is not written.
func (r *compositionRuns) boundOf(boundKey string) (string, uint64, bool, error) {
raw, rev, err := r.kv.get(boundKey)
if err != nil || raw == nil {
return "", 0, false, err
}
var v boundValue
_ = json.Unmarshal(raw, &v)
return v.Ask, rev, true, nil
}
// armBound writes the bound key prefix+key holding ask, judged from a read of the run, then reads the run again (A-470n): when
// it no longer names ask, or has ended, the bound just written is deleted at its revision, so no bound written from the earlier
// read ends the run after it, and a bound another run wrote since is kept. It answers whether the bound stands for the run.
func (r *compositionRuns) armBound(prefix, key, ask string, ttl time.Duration) (bool, error) {
rev, err := r.kv.arm(prefix+key, ask, ttl)
if err != nil {
return false, err
}
run, _, ok, err := r.read(key)
if err != nil {
return false, err
}
if ok && run.Ended == nil && run.Ask == ask {
return true, nil
}
if err := r.kv.delAt(prefix+key, rev); err != nil && !errors.Is(err, errRunChanged) {
return false, err
}
return false, nil
}
// heardAskTaken begins a run's clock at its ask's ask-taken: the bound key armed holding the ask, the untaken key of that ask
// deleted, each reader's wait ended ran. An ask no running run names is another asker's, or a late signal of a run replaced or
// ended, which moves nothing and is journaled (A-470n).
func (r *compositionRuns) heardAskTaken(e nodebuildgo.AskTaken) error {
key, run, err := r.runOfAsk(e.Asker, e.Ask)
if err != nil {
return err
}
if key == "" {
r.late("ask-taken", e.Asker, e.Ask)
return nil
}
armed, err := r.armBound(runBoundPrefix, key, e.Ask, r.set.stepBound)
if err != nil {
return fmt.Errorf("the bound of the composition run %s is not armed: %w", key, err)
}
if !armed {
r.late("ask-taken", e.Asker, e.Ask)
return nil
}
if r.untaken(key, e.Ask) {
if err := r.clearBounds(key, e.Ask, runUntakenPrefix); err != nil {
return err
}
r.sayWaits(run, run.Readers, "ran")
}
return nil
}
// heardProgress begins a running run's clock again at each step-progress of its ask (§720: owed progress, not run length); a
// late one moves nothing and is journaled (A-470n).
func (r *compositionRuns) heardProgress(e nodebuildgo.StepProgress) error {
key, _, err := r.runOfAsk(e.Asker, e.Ask)
if err != nil {
return err
}
armed := false
if key != "" {
if armed, err = r.armBound(runBoundPrefix, key, e.Ask, r.set.stepBound); err != nil {
return err
}
}
if !armed {
r.late("step-progress", e.Asker, e.Ask)
}
return nil
}
// late journals a signal of an ask the assigner put whose run no key names running any more (A-470n).
func (r *compositionRuns) late(signal, asker, ask string) {
if asker == runAsker && ask != "" {
r.logf("the %s of the run ask %s is late: no composition run names it running, so it moves nothing (A-470n)", signal, ask)
}
}
// runOfAsk is the running run of an ask the assigner put, or none.
func (r *compositionRuns) runOfAsk(asker, ask string) (string, meshwants.CompositionRun, error) {
if asker != runAsker || ask == "" {
return "", meshwants.CompositionRun{}, nil
}
key, run, err := r.keyOfAsk(ask)
if err != nil || key == "" || run.Ended != nil {
return "", meshwants.CompositionRun{}, err
}
return key, run, nil
}
// expired ends the run whose bound key's time to live ended (§720): its ask dropped, the run ended could not run naming the
// ask and the bound. A run that ended already, or a key of none, takes nothing.
func (r *compositionRuns) expired(boundKey string) {
key, bound, setting := "", time.Duration(0), ""
switch {
case strings.HasPrefix(boundKey, runBoundPrefix):
key, bound, setting = strings.TrimPrefix(boundKey, runBoundPrefix), r.set.stepBound, "composition-step-bound"
case strings.HasPrefix(boundKey, runUntakenPrefix):
key, bound, setting = strings.TrimPrefix(boundKey, runUntakenPrefix), r.set.untaken, "run-untaken-bound"
default:
return
}
run, _, ok, err := r.read(key)
if err != nil || !ok || run.Ended != nil {
return
}
// The marker of an expiry holds no value (A-470o): the run ends only while its bound is still absent when read again, and
// the run is taken for bound., untaken for untaken., so an expiry heard after a bound was armed again, or of a run replaced
// since, ends nothing.
other := runUntakenPrefix
if setting == "run-untaken-bound" {
other = runBoundPrefix
}
_, _, armed, err := r.boundOf(boundKey)
if err != nil {
r.logf("the bound %s is not read again, so its expiry ends nothing: %v", boundKey, err)
return
}
held, _, standing, err := r.boundOf(other + key)
if err != nil {
r.logf("the bound %s is not read, so the expiry of %s ends nothing: %v", other+key, boundKey, err)
return
}
if armed || (standing && held == run.Ask) {
r.logf("the expiry of %s ends nothing: the bound is armed again, or the run of ask %s is not where it bounds (A-470o)", boundKey, run.Ask)
return
}
said := fmt.Sprintf("%s: its run ask %s said no progress within %s (%s)", run.Machine, run.Ask, bound, setting)
if setting == "run-untaken-bound" {
said = fmt.Sprintf("%s: its run ask %s was taken by no build node within %s (%s)", run.Machine, run.Ask, bound, setting)
}
if r.drop != nil {
if err := r.drop(run.Ask, said); err != nil {
r.logf("the drop of the run ask %s of the composition run %s is not answered: %v", run.Ask, key, err)
}
}
// The untaken key is gone with its expiry, so the run ended by it is said untaken here: its readers' waits end superseded.
if _, err := r.endRunOf(key, run.Ask, meshwants.CompositionRunOutcomeCouldNotRun, said, nil, setting == "run-untaken-bound"); err != nil {
r.logf("the composition run %s past its bound is not ended: %v", key, err)
}
}
// endRun ends a run (end) and clears its bounds: the untaken key's readers said superseded, both bound keys deleted.
func (r *compositionRuns) endRun(key, ask, outcome, said string, verdict map[string]any) (bool, error) {
return r.endRunOf(key, ask, outcome, said, verdict, r.untaken(key, ask))
}
// endRunOf is endRun of a run whose ask is untaken, or not, as its caller judged.
func (r *compositionRuns) endRunOf(key, ask, outcome, said string, verdict map[string]any, untaken bool) (bool, error) {
return r.endRunMoving(key, ask, outcome, said, verdict, untaken, true)
}
// endRunMoving is endRunOf, moving the readers a rerun carried or not: a drop says its readers' ends itself (A-470r).
func (r *compositionRuns) endRunMoving(key, ask, outcome, said string, verdict map[string]any, untaken, move bool) (bool, error) {
// The readers a rerun carried move with the run's end (§727, A-470d): chosen before the end is written, while the rerun's own
// step still waits on it, so it alone says its own end; each mover waits for the end in the key.
if moved := r.moved.Load(); moved != nil && move {
if run, _, ok, err := r.read(key); err == nil && ok && run.Ended == nil && run.Ask == ask {
(*moved)(run)
}
}
ended, err := r.end(key, ask, outcome, said, verdict)
if err != nil || !ended {
return ended, err
}
if untaken {
if run, _, ok, err := r.read(key); err == nil && ok {
r.sayWaits(run, run.Readers, "superseded")
}
}
if err := r.clearBounds(key, ask, runBoundPrefix, runUntakenPrefix); err != nil {
r.logf("the bound keys of the ended composition run %s are not deleted: %v", key, err)
}
return true, nil
}
// readersOfOpen are the readers of every run with no `ended`, each with its ask's id once: what the assigner takes up again at
// its start (§719), each reader's end said from the keys alone (A-468). A reader whose step said its end already, carried into a
// rerun's run, is taken up only when it is marked `rerun` (A-470l, A-470m); each with the ask of the open run it is taken up from.
func (r *compositionRuns) readersOfOpen() ([]openReader, error) {
all, err := r.keys()
if err != nil {
return nil, err
}
seen := map[string]bool{}
var out []openReader
for _, key := range all {
if !isRunKey(key) {
continue
}
run, _, ok, err := r.read(key)
if err != nil || !ok || run.Ended != nil {
continue
}
for _, c := range run.Readers {
if c.Ended != nil && !c.Rerun {
continue // it ended passed already: only a reader marked rerun says its end again
}
if !seen[c.ID] {
seen[c.ID] = true
out = append(out, openReader{CompositionReader: c, ask: run.Ask})
}
}
}
return out, nil
}
// openReader is a reader taken up at the start and the ask of the open run it is taken up from.
type openReader struct {
meshwants.CompositionReader
ask string
}
// keysOf are the keys of the candidate's runs that the reader reads.
func (r *compositionRuns) keysOf(candidate, id string) ([]string, error) {
all, err := r.keys()
if err != nil {
return nil, err
}
var out []string
prefix := keysPart(candidate) + "."
for _, key := range all {
if !isRunKey(key) || !strings.HasPrefix(key, prefix) {
continue
}
if run, _, ok, err := r.read(key); err == nil && ok && hasReader(run.Readers, id) {
out = append(out, key)
}
}
slices.Sort(out) // by machine, as a step names its machines
return out, nil
}
// hearRunBounds hears the build seats' ask-taken and step-progress on the assigner's durable consumer (§720, A-466q): each
// handed to the runs; one that cannot be written is given again by the bus.
func hearRunBounds(hub interface {
Handle(string, func(jetstream.Msg)) error
}, r *compositionRuns, logf func(string, ...any)) error {
if err := hub.Handle(nodebuildgo.SubjectAskTakenAll, func(m jetstream.Msg) {
var e nodebuildgo.AskTaken
if err := json.Unmarshal(m.Data(), &e); err != nil {
logf("%s holds what is no ask-taken, left: %v", m.Subject(), err)
_ = m.Ack()
return
}
ackOrNak(m, r.heardAskTaken(e), logf)
}); err != nil {
return err
}
return hub.Handle(nodebuildgo.SubjectStepProgressAll, func(m jetstream.Msg) {
var e nodebuildgo.StepProgress
if err := json.Unmarshal(m.Data(), &e); err != nil {
logf("%s holds what is no step-progress, left: %v", m.Subject(), err)
_ = m.Ack()
return
}
ackOrNak(m, r.heardProgress(e), logf)
})
}
func ackOrNak(m jetstream.Msg, err error, logf func(string, ...any)) {
if err != nil {
logf("%s is not taken, so the bus gives it again: %v", m.Subject(), err)
_ = m.Nak()
return
}
_ = m.Ack()
}
// takeUp says, at the assigner's start, the end of each reader of a run with no `ended` once its runs end (§719, A-468): the
// step's goroutine is gone, so its end is judged from the candidate's keys naming it.
func (c *compositionSteps) takeUp(ctx context.Context, r *compositionRuns) {
readers, err := r.readersOfOpen()
if err != nil {
c.logf("composition-runs: the runs standing at the start are not read, so their readers are not taken up: %v", err)
return
}
for _, reader := range readers {
c.logf("the composition step %s of %s is taken up again by its runs (ask %s)", reader.Pipeline, reader.Module, reader.ID)
again := "" // a reader whose step said its end already says it again under the open run's ask (A-470q)
if reader.Ended != nil {
again = reader.ask
}
how := c.howOf(reader.Step, true)
if how == nil {
c.logf("the step %s of %s is not taken up again: it is no composition or validate step (%q)", reader.ID, reader.Module, reader.Step)
continue
}
go c.say1(ctx, reader.ID, stepRunOf(reader.CompositionReader), how, again)
}
}
@@ -3,22 +3,24 @@ package main
import (
"bytes"
"context"
"crypto/rand"
"encoding/base64"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"slices"
"strconv"
"sync"
"time"
nec "git.novox.be/novox/mesh-contracts/go/clients/nodeengineclient"
ne "git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-sdk/go/keys"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/process"
)
// The inputs of a composition step (design 47 G §354, A-243, A-252): one request per machine, each carrying that machine's input,
// asked of the machine's node-engine by the seat's verb compose-candidate.
// The inputs of a composition run (design 47 G §354, §718, A-243, A-252): one request per candidate and machine, carrying that
// machine's input, asked of the machine's node-engine by the seat's verb compose-candidate when the run starts.
// composeCandidateKey is the seat verb's call key, asked of one node.
const composeCandidateKey = "seat:" + ne.Seat + "." + ne.VerbComposeCandidate
@@ -28,11 +30,11 @@ const composeCandidateKey = "seat:" + ne.Seat + "." + ne.VerbComposeCandidate
func candidateKeyOf(run meshwants.StepRun) (string, error) {
switch {
case run.Run != "":
return "run-" + run.Run, nil
return nec.RunKey(run.Run)
case run.Branch == "" || run.Revision <= 0:
return "", errors.New("the step names neither a run on request nor a branch's revision, so no candidate is named")
}
return keys.EscapeName(run.Branch) + "." + strconv.FormatInt(run.Revision, 10), nil
return nec.RevisionKey(run.Branch, run.Revision) // built by the seat's client, never by hand (A-226b)
}
// machinesFor are the machines of a step (A-252): the nodes whose placement of the module names the step's branch (a placement
@@ -72,62 +74,64 @@ type nodeInput struct {
// compositionInputs asks the machines of a step for their inputs.
type compositionInputs struct {
machines func(module, branch string) []string
// call asks one node's seat verb (process.Conn.CallKeptOn).
call func(node, key string, body any) (json.RawMessage, error)
// callFile asks a seat verb marked chunks as a kept call (process.Conn.CallFileKept; design 47 H2 §775, H-A-405), addressed to
// one node as `seat:<seat>.<verb>@<node>`, carrying the ask's id and stopping at its bound, and answers the verb's answer with
// the whole file received added as its member `file`, base64 (design 47 G A-237b, A-237c, A-249). The call token is the
// body's `call`.
callFile func(ask process.KeptAsk, key string, body any) (json.RawMessage, error)
// bound is compose-ask-bound: how long a machine's compose-candidate is asked again through a transport fault (§775).
bound time.Duration
}
// gather asks each machine of the step's module and branch for its input with the step's candidate key, and answers every machine in
// name order: one away (away) is not asked; a node that is silent, unready or answers no input has Why set; no machine at all is an
// error. The run keeps each request built from an input under its run ask (compositionRun.machine).
func (c *compositionInputs) gather(ctx context.Context, run meshwants.StepRun, away func(node string) bool) ([]nodeInput, error) {
key, err := candidateKeyOf(run)
// composeAskBoundSetting is the holder's bound on its compose-candidate asks (design 47 H2 §775): past it the machine gave no
// input, naming every call.
const (
composeAskBoundSetting = "compose-ask-bound"
defaultComposeAskBound = 10 * time.Second
)
// composeAskBound reads the setting compose-ask-bound (§781).
func composeAskBound() (time.Duration, error) {
d, err := stdio.SettingDuration(composeAskBoundSetting, defaultComposeAskBound)
if err != nil {
return nil, err
return 0, errors.New("the assigner's " + err.Error())
}
nodes := c.machines(run.Module, run.Branch)
if len(nodes) == 0 {
return nil, fmt.Errorf("no node places %s on the branch %q, so the composition step has no machine to compose", run.Module, run.Branch)
}
bound := c.bound
if bound <= 0 {
bound = nec.AnswerBound
}
out := make([]nodeInput, len(nodes))
var wg sync.WaitGroup
for i, node := range nodes {
if away != nil && away(node) {
out[i] = nodeInput{Node: node, Away: true}
continue
}
wg.Add(1)
go func() {
defer wg.Done()
out[i] = c.one(ctx, bound, node, key)
}()
}
wg.Wait()
return out, nil
return d, nil
}
// one asks one node for its input.
func (c *compositionInputs) one(ctx context.Context, bound time.Duration, node, key string) nodeInput {
// composeAskID is the id of the compose-candidate ask of the step asked under stepAsk to node (H-A-405 (2)): one per node per
// step, so the engines' mesh-wide state taken keeps each apart, and a repeat to the same node carries the same id.
func composeAskID(stepAsk, node string) string { return stepAsk + "." + node }
// of asks the machine node for its input with the candidate's key (§718), as a kept call under the id of stepAsk, the step
// that starts the machine's composition run: asked once per candidate and machine, again only through a transport fault until
// compose-ask-bound (§775). A node that is silent past the bound, unready or answers no input has Why set.
func (c *compositionInputs) of(ctx context.Context, node, candidate, stepAsk string) nodeInput {
bound := c.bound
if bound <= 0 {
bound = defaultComposeAskBound
}
in := nodeInput{Node: node}
at, cancel := context.WithTimeout(ctx, bound)
defer cancel()
type reply struct {
raw json.RawMessage
err error
}
got := make(chan reply, 1)
go func() {
raw, err := c.call(node, composeCandidateKey, ne.ComposeCandidateInput{Candidate: key, Input: true})
// The input is any size, so the verb sends it in chunks on the call token chosen here, and the file is the input (A-237b, A-237c).
var bits [16]byte
if _, err := rand.Read(bits[:]); err != nil {
got <- reply{nil, err}
return
}
raw, err := c.callFile(process.KeptAsk{ID: composeAskID(stepAsk, node), Bound: bound}, composeCandidateKey+"@"+node,
ne.ComposeCandidateInput{Candidate: candidate, Input: true, Call: hex.EncodeToString(bits[:])})
got <- reply{raw, err}
}()
var raw json.RawMessage
select {
case <-at.Done():
in.Why = "no answer within its bound: " + at.Err().Error()
case <-ctx.Done():
in.Why = "its step's wait ended: " + context.Cause(ctx).Error()
return in
case r := <-got:
if r.err != nil {
@@ -148,17 +152,36 @@ func (c *compositionInputs) one(ctx context.Context, bound time.Duration, node,
case a.Verdict == nec.Unready:
in.Why = "unready: " + a.Refused
return in
case len(a.Input) == 0:
case a.Chunks == 0 && len(a.Input) == 0:
in.Why = "the engine answered no composition input"
if a.Refused != "" {
in.Why += ": " + a.Refused
}
return in
}
body, err := json.Marshal(a.Input)
if err != nil {
in.Why = "its composition input cannot be encoded again: " + err.Error()
return in
var body []byte
if a.Chunks > 0 {
// The composition input is the file the chunks carried, the engine's own bytes (numbers as written).
var whole struct {
File string `json:"file"`
}
if err := json.Unmarshal(raw, &whole); err != nil {
in.Why = "its answer is not a compose-candidate answer: " + err.Error()
return in
}
file, err := base64.StdEncoding.DecodeString(whole.File)
if err != nil || len(file) == 0 {
in.Why = fmt.Sprintf("the engine named %d chunks of composition input and the file received is empty or not base64: %v", a.Chunks, err)
return in
}
body = file
} else {
// An answer with the input inline (an engine before A-237b, read until the checker is removed, A-237c, G-6 §321): the object, as it was.
var err error
if body, err = json.Marshal(a.Input); err != nil {
in.Why = "its composition input cannot be encoded again: " + err.Error()
return in
}
}
in.Body = body
return in
@@ -2,13 +2,17 @@ package main
import (
"context"
"encoding/base64"
"encoding/json"
"errors"
"git.novox.be/novox/mesh-sdk/go/process"
"regexp"
"strings"
"sync"
"testing"
"time"
nec "git.novox.be/novox/mesh-contracts/go/clients/nodeengineclient"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
)
@@ -21,12 +25,21 @@ func TestTheCandidateKeyOfAStep(t *testing.T) {
}{
{run: meshwants.StepRun{Run: "r1", Branch: "main"}, want: "run-r1"},
{run: meshwants.StepRun{Branch: "feat/x", Revision: 42}, want: "feat/x.42"},
{run: meshwants.StepRun{Branch: "main", Revision: 362}, want: "main.362"},
{run: meshwants.StepRun{Branch: "main"}, fail: true},
{run: meshwants.StepRun{Branch: "main", Revision: 100000000000}, fail: true}, // a number the client's key would read as a heads hash
{run: meshwants.StepRun{Run: "a.b"}, fail: true}, // a run id the client refuses
} {
got, err := candidateKeyOf(c.run)
if (err != nil) != c.fail || got != c.want {
t.Errorf("%+v: %q, %v; want %q", c.run, got, err, c.want)
}
// A-226b: the node-engine reads every key the step names with the client's one parser.
if !c.fail {
if _, err := nec.ParseCandidateKey(got); err != nil {
t.Errorf("%+v: the key %q is refused by the seat's parser: %v", c.run, got, err)
}
}
}
}
@@ -56,13 +69,15 @@ func TestTheMachinesOfAStep(t *testing.T) {
// §354, A-243, A-252, §64: each machine is asked compose-candidate with the step's key and input true, its numbers as written; a
// silent or unready node says why, and a machine away is not asked.
func TestAStepsInputsAreAskedOfEachMachine(t *testing.T) {
// gather asks the machines side by side, so the record of what each was asked is guarded.
// the machines are asked side by side, so the record of what each was asked is guarded.
var mu sync.Mutex
asked := map[string]string{}
call := func(node, key string, body any) (json.RawMessage, error) {
asks := map[string]process.KeptAsk{}
call := func(ask process.KeptAsk, key string, body any) (json.RawMessage, error) {
raw, _ := json.Marshal(body)
key, node, _ := strings.Cut(key, "@") // addressed to one node (A-237b)
mu.Lock()
asked[node] = key + " " + string(raw)
asked[node], asks[node] = key+" "+string(raw), ask
mu.Unlock()
switch node {
case "g14":
@@ -72,25 +87,82 @@ func TestAStepsInputsAreAskedOfEachMachine(t *testing.T) {
}
return json.RawMessage(`{"candidate":"run-r1","node":"` + node + `","verdict":"composed","input":{"n":12345678901234567890,"node":"` + node + `"},"modules":[],"own":{},"took":1,"v":1}`), nil
}
c := &compositionInputs{machines: func(module, branch string) []string { return []string{"ace", "g14", "novox", "shanks"} }, call: call, bound: time.Second}
got, err := c.gather(context.Background(), meshwants.StepRun{Module: "m", Branch: "main", Run: "r1"}, func(node string) bool { return node == "shanks" })
c := &compositionInputs{machines: func(module, branch string) []string { return []string{"ace", "g14", "novox", "shanks"} }, callFile: call, bound: time.Second}
got, err := gatherAll(c, meshwants.StepRun{Module: "m", Branch: "main", Run: "r1"}, func(node string) bool { return node == "shanks" })
if err != nil || len(got) != 4 {
t.Fatalf("%+v %v", got, err)
}
if want := `seat:node-engine.compose-candidate {"candidate":"run-r1","input":true}`; asked["ace"] != want {
t.Errorf("asked %q, want %q", asked["ace"], want)
// With a call token of 128 random bits (32 hex digits), the verb being marked chunks.
if k, body, _ := strings.Cut(asked["ace"], " "); k != "seat:node-engine.compose-candidate" ||
!regexp.MustCompile(`^\{"call":"[0-9a-f]{32}","candidate":"run-r1","input":true\}$`).MatchString(body) {
t.Errorf("asked %q", asked["ace"])
}
if got[0].Node != "ace" || got[0].Why != "" || !strings.Contains(string(got[0].Body), "12345678901234567890") {
t.Errorf("ace: %+v", got[0])
}
// Design 47 H2 §775, H-A-405: each machine is asked as a kept call under the step's ask with the node, until compose-ask-bound.
if asks["ace"] != (process.KeptAsk{ID: "step-1.ace", Bound: time.Second}) || asks["g14"].ID != "step-1.g14" {
t.Errorf("the kept asks %+v", asks)
}
if !strings.Contains(got[1].Why, "no responders") || !strings.Contains(got[2].Why, "unready") || got[1].Body != nil || got[2].Body != nil {
t.Errorf("g14 and novox: %+v %+v", got[1], got[2])
}
if _, was := asked["shanks"]; was || !got[3].Away {
t.Errorf("the machine away is asked or not said away: %+v", got[3])
}
none := &compositionInputs{machines: func(string, string) []string { return nil }, call: call}
if _, err := none.gather(context.Background(), meshwants.StepRun{Module: "m", Run: "r1"}, nil); err == nil {
none := &compositionInputs{machines: func(string, string) []string { return nil }, callFile: call}
if _, err := gatherAll(none, meshwants.StepRun{Module: "m", Run: "r1"}, nil); err == nil {
t.Error("a step with no machine is gathered")
}
}
// A-237b: the composition input is any size, so a node names the chunks it sent and the assigner reads the file the chunked call
// received as the input, its numbers as written; a node that names chunks and sends no file is said so.
func TestAStepsInputIsTheFileOfTheNodesChunks(t *testing.T) {
input := `{"n":12345678901234567890,"big":"` + strings.Repeat("x", 1<<20) + `"}`
file := base64.StdEncoding.EncodeToString([]byte(input))
call := func(_ process.KeptAsk, key string, body any) (json.RawMessage, error) {
_, node, _ := strings.Cut(key, "@")
answer := `{"candidate":"run-r1","node":"` + node + `","verdict":"composed","modules":[],"own":{},"took":1,"v":1,"chunks":3`
if node == "g14" {
return json.RawMessage(answer + `}`), nil // names chunks, none received
}
return json.RawMessage(answer + `,"file":"` + file + `"}`), nil
}
c := &compositionInputs{machines: func(module, branch string) []string { return []string{"ace", "g14"} }, callFile: call, bound: time.Second}
got, err := gatherAll(c, meshwants.StepRun{Module: "m", Branch: "main", Run: "r1"}, func(string) bool { return false })
if err != nil || len(got) != 2 {
t.Fatalf("%+v %v", got, err)
}
if got[0].Why != "" || string(got[0].Body) != input {
t.Errorf("ace: why %q, %d bytes, want the file received (%d bytes) as the input", got[0].Why, len(got[0].Body), len(input))
}
if !strings.Contains(got[1].Why, "chunks") || got[1].Body != nil {
t.Errorf("g14: %+v", got[1])
}
}
// gatherAll asks each machine of a step for its input as each run's start does (compositionInputs.of), side by side; a machine away
// is not asked; no machine is an error.
func gatherAll(c *compositionInputs, run meshwants.StepRun, away func(string) bool) ([]nodeInput, error) {
key, err := candidateKeyOf(run)
if err != nil {
return nil, err
}
nodes := c.machines(run.Module, run.Branch)
if len(nodes) == 0 {
return nil, errors.New("no machine")
}
out := make([]nodeInput, len(nodes))
var wg sync.WaitGroup
for i, node := range nodes {
if away != nil && away(node) {
out[i] = nodeInput{Node: node, Away: true}
continue
}
wg.Add(1)
go func() { defer wg.Done(); out[i] = c.of(context.Background(), node, key, "step-1") }()
}
wg.Wait()
return out, nil
}
@@ -0,0 +1,181 @@
package main
import (
"context"
"encoding/json"
"fmt"
"strings"
"sync"
"time"
mcc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
"git.novox.be/novox/mesh-sdk/go/buscalls"
)
// The reads of a composition step (design 47 G §354, A-252, A-261): the entries of one catalog revision are read once and shared by
// every composition step of that revision, since an entry is content-addressed and a revision never changes; a read that times out
// or fails in transport is made again with a growing wait for a bounded time, said in the journal, and only then ends the step as
// could not run.
const (
// readsBound is how long a read is made again before the step could not run.
readsBound = 3 * time.Minute
// readsFirstWait and readsMaxWait bound the wait between two tries.
readsFirstWait = time.Second
readsMaxWait = 15 * time.Second
// readsKept is how many catalog revisions' halves are kept; the oldest read goes first.
readsKept = 8
)
// readKey names one revision of one watched branch.
type readKey struct {
branch string
revision int
}
// readSlot is one revision's read: done closes when half or err is set.
type readSlot struct {
done chan struct{}
half mcc.Half
err error
}
// compositionReads shares the reads of composition steps.
type compositionReads struct {
mu sync.Mutex
revs map[readKey]*readSlot
order []readKey
seats map[string]json.RawMessage // by seat and digest: the definition, raw
}
// transient says whether a read's fault is of the transport or a timeout, so that it is worth reading again.
func transient(err error, said string) bool {
text := said
if err != nil {
text = err.Error() + " " + said
}
text = strings.ToLower(text)
for _, w := range []string{"deadline exceeded", "timeout", "timed out", "no responders", "connection", "i/o", "eof", "broken pipe", "unavailable"} {
if strings.Contains(text, w) {
return true
}
}
return false
}
// callRetry calls the seat verb key, again with a growing wait while its fault is transient, for readsBound; it answers the body of
// a good answer, or the last fault.
func (r *compositionRun) callRetry(ctx context.Context, key string, body any) (json.RawMessage, string, error) {
start := r.now()
wait := readsFirstWait
for try := 1; ; try++ {
raw, err := r.call(key, body)
var inner json.RawMessage
var said string
if err == nil {
var ok bool
if inner, said, ok = buscalls.Unwrap(raw); ok {
return inner, "", nil
}
}
if !transient(err, said) {
return nil, said, err
}
if r.now().Sub(start)+wait > readsBound {
return nil, said, err
}
r.logf("composition step: %s is not read (try %d, %v %s), read again in %s", key, try, err, said, wait)
if serr := r.waitFor(ctx, wait); serr != nil {
return nil, said, serr
}
if wait *= 2; wait > readsMaxWait {
wait = readsMaxWait
}
}
}
// waitFor waits d, or until ctx ends.
func (r *compositionRun) waitFor(ctx context.Context, d time.Duration) error {
if r.sleep != nil {
return r.sleep(ctx, d)
}
t := time.NewTimer(d)
defer t.Stop()
select {
case <-ctx.Done():
return ctx.Err()
case <-t.C:
return nil
}
}
// half is the revision's half, read once for every step of it: a step that finds it being read waits for that read, and a read that
// failed is not kept, so the next step reads again.
func (r *compositionRun) half(ctx context.Context, key readKey, read func() (mcc.Half, error)) (mcc.Half, error) {
c := r.reads
c.mu.Lock()
if c.revs == nil {
c.revs = map[readKey]*readSlot{}
}
if s, ok := c.revs[key]; ok {
c.mu.Unlock()
select {
case <-s.done:
if s.err == nil {
return s.half, nil
}
case <-ctx.Done():
return mcc.Half{}, ctx.Err()
}
// The read this step waited for failed: read it here (the failed slot is already dropped).
return r.half(ctx, key, read)
}
s := &readSlot{done: make(chan struct{})}
c.revs[key] = s
c.order = append(c.order, key)
for len(c.order) > readsKept {
delete(c.revs, c.order[0])
c.order = c.order[1:]
}
c.mu.Unlock()
s.half, s.err = read()
if s.err != nil {
c.mu.Lock()
if c.revs[key] == s {
delete(c.revs, key)
}
for i, k := range c.order {
if k == key {
c.order = append(c.order[:i], c.order[i+1:]...)
break
}
}
c.mu.Unlock()
}
close(s.done)
return s.half, s.err
}
// seatKept is the definition kept of a seat at a digest.
func (c *compositionReads) seatKept(seat, digest string) (json.RawMessage, bool) {
c.mu.Lock()
defer c.mu.Unlock()
d, ok := c.seats[seat+"@"+digest]
return d, ok
}
func (c *compositionReads) keepSeat(seat, digest string, def json.RawMessage) {
c.mu.Lock()
defer c.mu.Unlock()
if c.seats == nil {
c.seats = map[string]json.RawMessage{}
}
c.seats[seat+"@"+digest] = def
}
func unreadErr(what string, err error, said string) error {
if err != nil {
return fmt.Errorf("%s: %w", what, err)
}
return fmt.Errorf("%s: %s", what, said)
}
File diff suppressed because it is too large Load Diff
@@ -4,17 +4,25 @@ import (
"context"
"encoding/json"
"errors"
"git.novox.be/novox/mesh-sdk/go/process"
"maps"
"slices"
"strings"
"sync"
"testing"
"time"
mmac "git.novox.be/novox/mesh-contracts/go/clients/meshmoduleassignerclient"
mma "git.novox.be/novox/mesh-contracts/go/seats/meshmoduleassigner"
ne "git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
mcseat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
mcc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
meshcatalog "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/composer"
"git.novox.be/novox/mesh-sdk/go/keys"
"mesh-delivery-assigner/internal/assign"
)
const (
@@ -30,13 +38,23 @@ type runStand struct {
requests map[string]composer.Request // by node
entries []string // the fingerprints `entry` was asked
r *compositionRun
runs *compositionRuns
puts int // the run asks put
// noDefinitions: the revision names no seat definition (A-234's stand-in); trunkSeats: the trunk's seat list as (seat, digest)
// pairs; unjudged: the machine the composer does not judge; listFault: the trunk's seat list cannot be read.
noDefinitions bool
trunkSeats []meshcatalog.SeatDefinitionsAnswerSeatsItem
unjudged string
listFault error
// verdict, when set, is the composer's verdict of a machine (by node), else the stand's own.
verdict func(node string) (composer.Machine, bool)
}
func newRunStand(t *testing.T, revisionEngine, trunkEngine, seatDigest string) *runStand {
s := &runStand{asks: map[string]buildstep.StepAsk{}, requests: map[string]composer.Request{}}
engine := func(fp, commit string) meshcatalog.CatalogEntry {
return meshcatalog.CatalogEntry{Module: "engine", Fp: fp, Repository: "novox/mesh-host", Commit: commit, Path: ".", Serves: []string{ne.Seat + ".composition"},
Manifest: map[string]any{"module": "engine"}}
Manifest: map[string]any{"module": "engine"}, Packages: map[string]string{"git.novox.be/novox/mesh-sdk/go": "v0.1.25-" + fp, "git.novox.be/novox/x/go": ""}}
}
revisionCommit := commitE1
if revisionEngine != "src2:e1" {
@@ -46,7 +64,8 @@ func newRunStand(t *testing.T, revisionEngine, trunkEngine, seatDigest string) *
"": {Revision: &meshcatalog.CatalogRevision{Revision: 7, Branch: "main", Definitions: []meshcatalog.CatalogRevisionDefinitionsItem{{Seat: "s1", Digest: "d1"}}},
Entries: []meshcatalog.CatalogEntry{engine(revisionEngine, revisionCommit), {Module: "bad", Verdict: mcc.VerdictRefused, Inputs: &meshcatalog.EntryInputs{Problems: []string{"no seat x"}},
Manifest: map[string]any{"module": "bad"}}}, Next: "bad"},
"bad": {Revision: &meshcatalog.CatalogRevision{Revision: 7}, Entries: []meshcatalog.CatalogEntry{{Module: "m", Verdict: mcc.VerdictAccepted, Manifest: map[string]any{"module": "m"}}}},
"bad": {Revision: &meshcatalog.CatalogRevision{Revision: 7}, Entries: []meshcatalog.CatalogEntry{{Module: "m", Verdict: mcc.VerdictAccepted, Manifest: map[string]any{"module": "m"}},
{Module: "lidarr", None: "builders disagree: node", Manifest: map[string]any{"module": "lidarr"}}}}, // no fingerprint (A-470j)
}
call := func(key string, body any) (json.RawMessage, error) {
raw, _ := json.Marshal(body)
@@ -57,8 +76,22 @@ func newRunStand(t *testing.T, revisionEngine, trunkEngine, seatDigest string) *
if in.Revision != 7 || in.Branch != "main" {
return nil, errors.New("asked another revision")
}
return json.Marshal(pages[in.After])
page := pages[in.After]
if s.noDefinitions && page.Revision != nil {
rev := *page.Revision
rev.Definitions = nil
page.Revision = &rev
}
return json.Marshal(page)
case seatDefinitionsKey:
var sin meshcatalog.SeatDefinitionsInput
_ = json.Unmarshal(raw, &sin)
if sin.Seat == "" {
if s.listFault != nil {
return nil, s.listFault
}
return json.Marshal(meshcatalog.SeatDefinitionsAnswer{Seats: s.trunkSeats})
}
return json.Marshal(meshcatalog.SeatDefinitionsAnswer{Found: true, Entry: &meshcatalog.SeatDefinitionsAnswerEntry{Seat: "s1", Digest: seatDigest, Definition: map[string]any{"seat": "s1"}}})
case entryVerbKey:
var in meshcatalog.EntryInput
@@ -71,17 +104,17 @@ func newRunStand(t *testing.T, revisionEngine, trunkEngine, seatDigest string) *
}
return nil, errors.New("no such verb " + key)
}
engines := func(node, _ string, _ any) (json.RawMessage, error) {
engines := func(_ process.KeptAsk, key string, _ any) (json.RawMessage, error) {
_, node, _ := strings.Cut(key, "@") // addressed to one node (A-237b)
return json.RawMessage(`{"candidate":"main.7","node":"` + node + `","verdict":"composed","input":{"node":"` + node + `"},"modules":[],"own":{},"took":1,"v":1}`), nil
}
running := map[string]string{"ace": "src2:e1", "g14": "src2:e2"}
away := &awayNodes{}
away.set("shanks", true)
away := func(machine string) bool { return machine == "shanks" }
keeper := testKeeper(&objectsMem{objs: map[string][]byte{}}, time.Now)
ends := &runEnds{}
s.r = &compositionRun{
inputs: &compositionInputs{machines: func(string, string) []string { return []string{"ace", "g14", "shanks"} }, call: engines, bound: time.Second},
keeper: keeper, call: call, ends: ends, away: away, now: time.Now, logf: t.Logf,
s.runs = newCompositionRuns(newRunsMem(), defaultRunSettings, time.Now, t.Logf)
s.r = &compositionRun{runs: s.runs,
inputs: &compositionInputs{machines: func(string, string) []string { return []string{"ace", "g14", "shanks"} }, callFile: engines, bound: time.Second},
keeper: keeper, reads: &compositionReads{}, call: call, away: away, now: time.Now, logf: t.Logf,
trunk: func() (mcc.Half, bool) {
return mcc.Half{Entries: map[string]meshcatalog.CatalogEntry{"engine": engine(trunkEngine, commitE1)}}, true
},
@@ -103,11 +136,27 @@ func newRunStand(t *testing.T, revisionEngine, trunkEngine, seatDigest string) *
s.asks[node], s.requests[node] = a, req
s.mu.Unlock()
m := composer.Machine{Composes: true}
if node == "g14" {
override, set := composer.Machine{}, false
if s.verdict != nil {
override, set = s.verdict(node)
}
if set {
m = override
} else if node == s.unjudged {
m = composer.Machine{NotJudged: "the composer was handed no seat list"}
} else if node == "g14" {
m = composer.Machine{Reason: "two modules own one path", Problems: []string{"/etc/x is m's and bad's"}}
}
v, _ := json.Marshal(composer.Verdict{V: composer.Version, Cases: []composer.CaseVerdict{{Name: changeCase, Machines: map[string]composer.Machine{node: m}}}})
go ends.heard(buildstep.StepEnded{Ask: a.ID, Asker: runAsker, Node: "builder1", Outcome: buildstep.OutcomePassed, Output: string(v)})
s.mu.Lock()
s.puts++
s.mu.Unlock()
go func() {
if err := s.runs.heardEnd(buildstep.StepEnded{Ask: a.ID, Asker: runAsker, Node: "builder1", Outcome: buildstep.OutcomePassed, Output: string(v)},
func(e buildstep.StepEnded) ([]byte, error) { return []byte(e.Output), nil }); err != nil {
t.Error(err)
}
}()
return nil
},
}
@@ -115,15 +164,16 @@ func newRunStand(t *testing.T, revisionEngine, trunkEngine, seatDigest string) *
}
// Design 47 G §354, §63, §64, A-226, A-238, A-240, A-243, A-252, A-254, A-261: one request and one run ask per machine, the request
// depth compose with the one machine and one case `change`, its manifests, verdicts and seats from the step's revision; the
// depth compose with the one machine and one case `change`, its manifests and seats from the step's revision, no verdicts (H-A-112); the
// composer is the node-engine build each machine runs, its entry read through `entry`, or the revision's where it differs from the
// trunk's; the run's verdict is read from its step-ended; a machine away passes with a warning, one not composing fails the step.
// trunk's, or the revision's for a machine whose node-engine is not heard running (A-451); the run's verdict is read from its step-ended; a machine away passes with a warning, one not composing fails the step.
func TestTheCompositionStepRunsOneAskPerMachine(t *testing.T) {
step := meshwants.StepRun{Module: "m", Branch: "main", Revision: 7, Step: meshwants.StepRunStepComposition}
s := newRunStand(t, "src2:e1", "src2:e1", "d1")
out := s.r.run(context.Background(), "ask-step", step)
if out.Outcome != meshwants.StepEndedOutcomeFailed || !strings.Contains(out.Said, "g14 does not compose") || !strings.Contains(out.Said, "/etc/x") ||
strings.Contains(out.Said, "ace") || len(out.Warnings) != 1 || !strings.Contains(out.Warnings[0], "shanks is away") {
strings.Contains(out.Said, "ace") || len(out.Warnings) != 2 || !strings.Contains(out.Warnings[0], "shanks is away") ||
out.Warnings[1] != "g14: the composer names no culprits" {
t.Fatalf("the step came to %+v", out)
}
if len(s.asks) != 2 {
@@ -137,14 +187,20 @@ func TestTheCompositionStepRunsOneAskPerMachine(t *testing.T) {
if s.asks["g14"].Run.Program.Commit != commitE2 {
t.Errorf("g14's composer is built at %s, want the build its node-engine runs", s.asks["g14"].Run.Program.Commit)
}
if req.Depth != composer.DepthCompose || len(req.Machines) != 1 || req.Machines[0] != "ace" || len(req.Cases) != 1 || req.Cases[0].Name != changeCase ||
// Each composer is built against the pins of the node-engine entry it is built from, a pin with no version left out
// (H-A-203, H-A-192).
for node, fp := range map[string]string{"ace": "src2:e1", "g14": "src2:e2"} {
if got := s.asks[node].Packages; len(got) != 1 || got["git.novox.be/novox/mesh-sdk/go"] != "v0.1.25-"+fp {
t.Errorf("%s's composer is built against the pins %v; want its entry's", node, got)
}
}
if req.Depth != composer.DepthCompose || req.BlameTries != 20 || len(req.Machines) != 1 || req.Machines[0] != "ace" || len(req.Cases) != 1 || req.Cases[0].Name != changeCase ||
string(req.Input) != `{"node":"ace"}` || len(req.Seats) != 1 || string(req.Seats[0]) != `{"seat":"s1"}` {
t.Errorf("the request of ace %+v", req)
}
c := req.Cases[0]
if string(c.Manifests["m"].Raw) != `{"module":"m"}` || len(c.Manifests) != 3 || len(c.Verdicts) != 1 || !strings.Contains(string(c.Verdicts["bad"]), `"refused"`) ||
!strings.Contains(string(c.Verdicts["bad"]), "no seat x") {
t.Errorf("the case %+v %s", c.Manifests, c.Verdicts)
if string(c.Manifests["m"].Raw) != `{"module":"m"}` || len(c.Manifests) != 4 || len(c.None) != 1 || c.None["lidarr"] != "builders disagree: node" {
t.Errorf("the case %+v", c.Manifests)
}
if strings.Join(s.entries, " ") == "" {
t.Error("no node-engine entry is read through entry")
@@ -159,6 +215,18 @@ func TestTheCompositionStepRunsOneAskPerMachine(t *testing.T) {
t.Errorf("the change's node-engine does not compose every machine: %+v %+v %v", changed.asks["ace"].Run.Program, changed.asks["g14"].Run.Program, changed.entries)
}
// No running of the node-engine is heard on g14: its composer is the revision's entry, and no entry is asked for it (A-451).
unheard := newRunStand(t, "src2:e1", "src2:e1", "d1")
unheard.r.running = func(node, module string) (ne.Running, bool) {
return ne.Running{Node: node, Module: module, Fingerprint: "src2:e1"}, node == "ace" && module == "engine"
}
if out := unheard.r.run(context.Background(), "ask-step", step); out.Outcome != meshwants.StepEndedOutcomeFailed || !strings.Contains(out.Said, "g14 does not compose") {
t.Fatalf("the step with g14's node-engine not heard came to %+v", out)
}
if unheard.asks["g14"].Run == nil || unheard.asks["g14"].Run.Program.Commit != commitE1 {
t.Errorf("g14's composer with no running heard is %+v, want the revision's entry", unheard.asks["g14"].Run)
}
// A seat digest neither the revision nor the trunk holds: could not run, naming the seat and the digest (A-261).
other := newRunStand(t, "src2:e1", "src2:e1", "d2")
if out := other.r.run(context.Background(), "ask-step", step); out.Outcome != meshwants.StepEndedOutcomeCouldNotRun ||
@@ -166,6 +234,147 @@ func TestTheCompositionStepRunsOneAskPerMachine(t *testing.T) {
t.Errorf("a seat digest not held came to %+v, %d asks", out, len(other.asks))
}
// A revision naming no definition (A-234's stand-in): the composer is handed the trunk seat list's definitions, read through
// seat-definitions (A-467); a list that cannot be read, or names no seat, ends the step could not run, naming it, with no ask put.
bare := newRunStand(t, "src2:e1", "src2:e1", "d1")
bare.noDefinitions, bare.trunkSeats = true, []meshcatalog.SeatDefinitionsAnswerSeatsItem{{Seat: "s1", Digest: "d1"}}
if out := bare.r.run(context.Background(), "ask-step", step); out.Outcome != meshwants.StepEndedOutcomeFailed ||
len(bare.requests["ace"].Seats) != 1 || string(bare.requests["ace"].Seats[0]) != `{"seat":"s1"}` {
t.Errorf("a revision with no definitions came to %+v, seats %v", out, bare.requests["ace"].Seats)
}
for name, fault := range map[string]error{"unreadable": errors.New("no responder"), "empty": nil} {
s := newRunStand(t, "src2:e1", "src2:e1", "d1")
s.noDefinitions, s.listFault = true, fault
if out := s.r.run(context.Background(), "ask-step", step); out.Outcome != meshwants.StepEndedOutcomeCouldNotRun ||
!strings.Contains(out.Said, "seat list is not read") || len(s.asks) != 0 {
t.Errorf("the %s seat list came to %+v, %d asks", name, out, len(s.asks))
}
}
// A machine the composer did not judge is could not run, naming why: a step that judged nothing never passes (A-467).
nj := newRunStand(t, "src2:e1", "src2:e1", "d1")
nj.unjudged = "g14"
if out := nj.r.run(context.Background(), "ask-step", step); out.Outcome != meshwants.StepEndedOutcomeCouldNotRun ||
!strings.Contains(out.Said, "g14 was not judged: the composer was handed no seat list") {
t.Errorf("a machine not judged came to %+v", out)
}
// No machine judged: every machine away, or no machine, never passes; each is named with why (A-467a).
for name, machines := range map[string][]string{"every machine away": {"shanks"}, "no machine": {}} { // none placed: the inputs say so already
want := "no machine was judged"
if len(machines) == 0 {
want = "has no machine to compose"
}
none := newRunStand(t, "src2:e1", "src2:e1", "d1")
none.r.inputs.machines = func(string, string) []string { return machines }
outcome := meshwants.StepEndedOutcomeCouldNotRun
if len(machines) == 0 { // a mover no machine holds: nothing to run, saying why (H-A-179)
outcome = meshwants.StepEndedOutcomeNothingToRun
}
if out := none.r.run(context.Background(), "ask-step", step); out.Outcome != outcome ||
!strings.Contains(out.Said, want) || (len(machines) > 0 && !strings.Contains(out.Said, "shanks is away")) || len(none.asks) != 0 {
t.Errorf("%s came to %+v, %d asks", name, out, len(none.asks))
}
}
// Another watched branch's app is in every machine's case, and a module assigned there that no watched branch lists is said in
// the machine's reason (H-A-143, §532).
across := newRunStand(t, "src2:e1", "src2:e1", "d1")
across.r.newest = func() map[string]mcc.Half {
return map[string]mcc.Half{"master": {Revision: meshcatalog.CatalogRevision{Branch: "master", Revision: 2},
Entries: map[string]meshcatalog.CatalogEntry{"f1-circuits": {Module: "f1-circuits", Fp: "f1", Manifest: map[string]any{"module": "f1-circuits"}}}}}
}
across.r.watched = func(module string) []string {
if module == "checker" || module == "lidarr" { // no registration names them; lidarr is on main's revision all the same (H-A-144)
return nil
}
return []string{"main", "master"}
}
across.r.assigned = func(node string) []string { return []string{"m", "f1-circuits", "checker", "lidarr"} }
if out := across.r.run(context.Background(), "ask-step", step); out.Outcome != meshwants.StepEndedOutcomeFailed ||
!strings.Contains(out.Said, "g14 is assigned checker, which no watched branch lists (H-A-143)") ||
!strings.Contains(out.Said, "g14 is assigned lidarr, which no watched branch lists (H-A-143)") {
t.Errorf("the step across the watched branches came to %+v", out)
}
if c := across.requests["ace"].Cases[0]; string(c.Manifests["f1-circuits"].Raw) != `{"module":"f1-circuits"}` || len(c.Manifests) != 4 ||
c.Manifests["lidarr"].Raw != nil {
t.Errorf("the case across the watched branches holds %v", slices.Sorted(maps.Keys(c.Manifests)))
}
if c := across.requests["ace"].Cases[0]; c.Assignments != nil {
t.Errorf("with no assignments held the case composes the input's, it carries %v", c.Assignments)
}
// A stale assignment is left out of the case's assignments as well, said, and the machine composes; a listed module stays in
// (H-A-148, ADR 0578 §2). The one set is the watched branches' newest revisions', carried on the run (H-A-152, H-A-153): a module
// the candidate drops while the newest still lists it stays in, the change's own fault, and while no newest revision is followed
// nothing is left out.
dropsWeb := func() map[string]mcc.Half {
h := across.r.newest()
h["main"] = mcc.Half{Revision: meshcatalog.CatalogRevision{Branch: "main", Revision: 6},
Entries: map[string]meshcatalog.CatalogEntry{"m": {Module: "m", Manifest: map[string]any{"module": "m"}},
"web": {Module: "web", Fp: "w1", Manifest: map[string]any{"module": "web"}}}}
return h
}
for _, tc := range []struct {
name string
assigned []string
newest func() map[string]mcc.Half // nil: across's
want []string // the case's modules of ace; nil: the input's assignments
}{
{"a stale assignment left out and said, the machine composes", []string{"m", "f1-circuits", "checker"}, nil, []string{"m", "f1-circuits"}},
{"listed modules alone: the input's assignments", []string{"m", "f1-circuits"}, nil, nil},
{"a module the candidate drops, the newest lists: kept", []string{"m", "f1-circuits", "web"}, dropsWeb, nil},
{"no newest revision followed: nothing left out", []string{"m", "checker"}, func() map[string]mcc.Half { return map[string]mcc.Half{} }, nil},
} {
left := newRunStand(t, "src2:e1", "src2:e1", "d1")
left.r.newest, left.r.watched = across.r.newest, across.r.watched
if tc.newest != nil {
left.r.newest = tc.newest
}
left.r.assigned = func(string) []string { return tc.assigned }
left.r.assignment = func(node string) (mma.Assignments, bool) {
a := mma.Assignments{Node: node}
for _, m := range tc.assigned {
a.Modules = append(a.Modules, mma.PlacedModule{Module: m})
}
return a, true
}
left.verdict = func(string) (composer.Machine, bool) { return composer.Machine{Composes: true}, true }
raised := map[string][]byte{}
left.r.findings = assign.Findings{Put: putInto(raised)}
out := left.r.run(context.Background(), "ask-step", step)
// H-A-149: the step that leaves an assignment out raises assignment-unlisted, scope delivery, id <node>.<module>, a warning.
var f mcseat.Finding
_ = json.Unmarshal(raised[assign.UnlistedKey("ace", "checker")], &f)
if want := tc.want != nil; want != (f.Kind == assign.KindAssignmentUnlisted && f.Scope == "delivery" && f.ID == "ace.checker" &&
f.Severity == mcseat.FindingSeverityWarning) || (!want && len(raised) != 0) {
t.Errorf("%s: raised %v", tc.name, raised)
}
said := "ace is assigned checker, which no watched branch lists (H-A-143)"
if out.Outcome != meshwants.StepEndedOutcomePassed || (tc.want != nil) != slices.Contains(out.Warnings, said) {
t.Errorf("%s: the step came to %+v", tc.name, out)
}
if run, _, _, _ := left.runs.read(runKeyOf("main.7", "ace")); (tc.want != nil) != slices.Equal(run.Unlisted, []string{"checker"}) ||
(tc.want == nil && run.Unlisted != nil) {
t.Errorf("%s: the run carries the unlisted %v", tc.name, run.Unlisted)
}
raw, ok := left.requests["ace"].Cases[0].Assignments["ace"]
if tc.want == nil {
if ok {
t.Errorf("%s: the case carries assignments %s", tc.name, raw)
}
continue
}
a, err := mmac.DecodeAssignments(raw)
var got []string
for _, m := range a.Modules {
got = append(got, m.Module)
}
if err != nil || !slices.Equal(got, tc.want) {
t.Errorf("%s: the case composes ace with %v (%v), want %v", tc.name, got, err, tc.want)
}
}
// At the inputs state's cap the ask is refused, naming the store (§354).
full := newRunStand(t, "src2:e1", "src2:e1", "d1")
full.r.keeper.used = func() (int64, error) { return inputsCap, nil }
@@ -174,3 +383,425 @@ func TestTheCompositionStepRunsOneAskPerMachine(t *testing.T) {
t.Errorf("an ask at the cap came to %+v, %d asks", out, len(full.asks))
}
}
// Design 47 G §354, A-252: the entries of one catalog revision are read once for every step of it, and a read that times out is
// made again with a growing wait for a bounded time, said in the journal, before the step could not run.
func TestTheCompositionStepReadsTheRevisionOnceAndAgainOnATimeout(t *testing.T) {
step := meshwants.StepRun{Module: "m", Branch: "main", Revision: 7, Step: meshwants.StepRunStepComposition}
for _, tc := range []struct {
name string
faults int // consecutive faults of the `revision` read before it answers
fault error // the fault
steps int
want string // the outcome of the last step
revisionCalls int
waits int
}{
{"two steps of one revision read it once", 0, nil, 2, meshwants.StepEndedOutcomeFailed, 2, 0},
{"a timeout is read again", 3, errors.New("context deadline exceeded"), 1, meshwants.StepEndedOutcomeFailed, 5, 3},
{"a fault that stays ends could not run", 1000, errors.New("nats: timeout"), 1, meshwants.StepEndedOutcomeCouldNotRun, -1, -1},
{"a fault of the answer is not read again", 1, errors.New("no such revision"), 1, meshwants.StepEndedOutcomeCouldNotRun, 1, 0},
} {
t.Run(tc.name, func(t *testing.T) {
s := newRunStand(t, "src2:e1", "src2:e1", "d1")
inner := s.r.call
var mu sync.Mutex
calls, faults := 0, tc.faults
s.r.call = func(key string, body any) (json.RawMessage, error) {
if key == mcc.RevisionVerb {
mu.Lock()
calls++
f := faults > 0
faults--
mu.Unlock()
if f {
return nil, tc.fault
}
}
return inner(key, body)
}
clock := time.Unix(1000, 0)
var waits []time.Duration
s.r.now = func() time.Time { mu.Lock(); defer mu.Unlock(); return clock }
s.r.sleep = func(_ context.Context, d time.Duration) error {
mu.Lock()
defer mu.Unlock()
waits = append(waits, d)
clock = clock.Add(d)
return nil
}
var wg sync.WaitGroup
outs := make([]stepOutcome, tc.steps)
for i := range outs {
wg.Add(1)
go func() { defer wg.Done(); outs[i] = s.r.run(context.Background(), "ask-step", step) }()
}
wg.Wait()
for _, o := range outs {
if o.Outcome != tc.want {
t.Fatalf("a step came to %+v, want %s", o, tc.want)
}
}
if tc.waits == -1 { // never answers: bounded, growing waits
if len(waits) < 3 || waits[0] != readsFirstWait || waits[1] != 2*readsFirstWait || waits[len(waits)-1] != readsMaxWait {
t.Errorf("the waits %v do not grow to %s", waits, readsMaxWait)
}
var total time.Duration
for _, w := range waits {
total += w
}
if total > readsBound {
t.Errorf("read again for %s, bound %s", total, readsBound)
}
if !strings.Contains(outs[0].Said, "catalog revision is not read") || !strings.Contains(outs[0].Said, "timeout") {
t.Errorf("the step said %q", outs[0].Said)
}
return
}
if calls != tc.revisionCalls || len(waits) != tc.waits {
t.Errorf("`revision` asked %d times with %d waits, want %d and %d", calls, len(waits), tc.revisionCalls, tc.waits)
}
})
}
}
// Design 47 G §718, §719, §720: three composition steps of one revision on two machines start two runs, one request and one run
// ask per machine, and each step reads both verdicts; the run records its program with the node-engine fingerprint it was chosen
// from and the digest of its kept request, which names no module of the asking pipeline; a step of another candidate starts its
// own runs, and a run that could not run is never read again.
func TestTheStepsOfOneCandidateReadOneRunPerMachine(t *testing.T) {
s := newRunStand(t, "src2:e1", "src2:e1", "d1")
s.r.inputs.machines = func(string, string) []string { return []string{"ace", "g14"} }
var wg sync.WaitGroup
outs := make([]stepOutcome, 3)
for i, m := range []string{"m", "m2", "m3"} {
wg.Add(1)
go func() {
defer wg.Done()
outs[i] = s.r.run(context.Background(), "ask-"+m, meshwants.StepRun{Pipeline: "main.7." + m, Module: m, Branch: "main", Revision: 7, Step: meshwants.StepRunStepComposition})
}()
}
wg.Wait()
for i, o := range outs {
if len(o.Shared) != 2 || o.Shared[0].Machine != "ace" || o.Shared[0].Run != runKeyOf("main.7", "ace") || o.Shared[0].Ask == "" ||
o.Shared[1].Machine != "g14" || o.Shared[1].Ask == o.Shared[0].Ask { // §723, §729: per machine the run read and its ask
t.Errorf("step %d names the runs %+v", i, o.Shared)
}
if o.Outcome != meshwants.StepEndedOutcomeFailed || !strings.Contains(o.Said, "g14 does not compose") {
t.Errorf("step %d came to %+v, want both machines read", i, o)
}
}
if s.puts != 2 {
t.Fatalf("%d run asks put, want one per machine", s.puts)
}
ace, _, _, _ := s.runs.read(runKeyOf("main.7", "ace"))
g14, _, _, _ := s.runs.read(runKeyOf("main.7", "g14"))
if len(ace.Readers) != 3 || len(g14.Readers) != 3 || ace.Program == nil || ace.Program.Fingerprint != "src2:e1" || ace.Program.Commit != commitE1 ||
g14.Program == nil || g14.Program.Fingerprint != "src2:e2" || ace.Input == "" || ace.Input != digestOf(mustJSON(t, s.requests["ace"])) ||
ace.Outcome != meshwants.CompositionRunOutcomePassed || g14.Outcome != meshwants.CompositionRunOutcomePassed || g14.Verdict["composes"] != false {
t.Errorf("the runs: ace %+v, g14 %+v", ace, g14)
}
if req := s.requests["ace"]; strings.Contains(string(mustJSON(t, req)), "main.7.m") || string(req.Input) != `{"node":"ace"}` {
t.Errorf("the request names the asking pipeline or not the node's input: %s", mustJSON(t, req))
}
// Another candidate (a run on request) starts its own runs.
if o := s.r.run(context.Background(), "ask-r", meshwants.StepRun{Pipeline: "run-r1.m", Module: "m", Branch: "main", Revision: 7, Run: "r1", Step: meshwants.StepRunStepComposition}); o.Outcome != meshwants.StepEndedOutcomeFailed || s.puts != 4 {
t.Errorf("a step of another candidate came to %+v with %d asks, want its own two runs", o, s.puts)
}
// A run whose ask could not be put could not run; the next step of the candidate starts it again.
f := newRunStand(t, "src2:e1", "src2:e1", "d1")
f.r.inputs.machines = func(string, string) []string { return []string{"ace"} }
put, refused := f.r.put, 0
f.r.put = func(ctx context.Context, a buildstep.StepAsk) error {
if refused == 0 {
refused++
return errors.New("no stream")
}
return put(ctx, a)
}
first := f.r.run(context.Background(), "ask-1", meshwants.StepRun{Pipeline: "main.7.m", Module: "m", Branch: "main", Revision: 7, Step: meshwants.StepRunStepComposition})
second := f.r.run(context.Background(), "ask-2", meshwants.StepRun{Pipeline: "main.7.m2", Module: "m2", Branch: "main", Revision: 7, Step: meshwants.StepRunStepComposition})
if first.Outcome != meshwants.StepEndedOutcomeCouldNotRun || !strings.Contains(first.Said, "is not put") || second.Outcome != meshwants.StepEndedOutcomePassed || f.puts != 1 {
t.Errorf("after a run that could not run: %+v then %+v, %d asks", first, second, f.puts)
}
}
func mustJSON(t *testing.T, v any) []byte {
t.Helper()
raw, err := json.Marshal(v)
if err != nil {
t.Fatal(err)
}
return raw
}
// Design 47 G §721, §722, A-470b: a step judges each machine from its verdict's `blamed`: a verdict blaming the step's module fails
// it and passes another module's step with a warning naming the module; a machine that does not compose and blames no module fails
// every step; a verdict with no `blamed` is judged as before and says "the composer names no culprits"; a module the search did not
// try is could not run for its own step; a run that could not run is could not run.
func TestAMachineIsJudgedByTheModulesItBlames(t *testing.T) {
at := time.Now()
runOf := func(verdict string) meshwants.CompositionRun {
var v map[string]any
if err := json.Unmarshal([]byte(verdict), &v); err != nil {
t.Fatal(err)
}
return meshwants.CompositionRun{Candidate: "main.7", Machine: "ace", Ended: &at, Outcome: meshwants.CompositionRunOutcomePassed, Verdict: v}
}
blamesA := `{"composes":false,"reason":"two modules own one path","blamed":[{"module":"a","problem":"/etc/x is a's and c's"}]}`
for _, tc := range []struct {
name, module string
run meshwants.CompositionRun
failed, couldNo string
warnings []string
unlisted []string
}{
{"blamed module fails", "a", runOf(blamesA), "ace holds a: /etc/x is a's and c's", "", nil, nil},
{"another module passes with a warning", "b", runOf(blamesA), "", "", []string{"ace holds a: /etc/x is a's and c's"}, nil},
{"blames no module fails both", "b", runOf(`{"composes":false,"reason":"the node's own composition","blamed":[]}`), "ace does not compose and blames no module: the node's own composition", "", nil, nil},
{"an old composer", "b", runOf(`{"composes":false,"reason":"x"}`), "ace does not compose: x", "", []string{"ace: the composer names no culprits"}, nil},
{"composes", "b", runOf(`{"composes":true,"blamed":[]}`), "", "", nil, nil},
{"own module not tried", "a", runOf(`{"composes":false,"blamed":[{"module":"a","problem":"not tried: the search reached its bound"}]}`), "",
"ace holds a untried: the composer's search for culprits reached its bound of blame_tries (A-470b)", nil, nil},
{"another not tried", "b", runOf(`{"composes":false,"blamed":[{"module":"a","problem":"not tried: the search reached its bound"}]}`), "", "",
[]string{"ace holds a: not tried: the search reached its bound"}, nil},
{"not judged", "a", runOf(`{"composes":false,"not_judged":"no seat list","blamed":[]}`), "", "ace was not judged: no seat list", nil, nil},
{"could not run", "a", meshwants.CompositionRun{Machine: "ace", Ended: &at, Outcome: meshwants.CompositionRunOutcomeCouldNotRun, Said: "ace: gone"}, "", "ace: gone", nil, nil},
// H-A-143: a module assigned there that no watched branch lists is said in the reason, or as a warning where it composes.
{"an unlisted module in the reason", "b", runOf(`{"composes":false,"reason":"nothing provides \"photos\"","blamed":[]}`),
"ace does not compose and blames no module: nothing provides \"photos\"; ace is assigned photos, which no watched branch lists (H-A-143)", "", nil, []string{"photos"}},
{"does not compose, blames a module, an unlisted module", "a", runOf(`{"composes":false,"reason":"nothing provides \"photos\"","blamed":[{"module":"a","problem":"nothing provides \"photos\""}]}`),
"ace holds a: nothing provides \"photos\"; ace is assigned photos, which no watched branch lists (H-A-143)", "", nil, []string{"photos"}},
{"another module blamed, an unlisted module", "b", runOf(`{"composes":false,"blamed":[{"module":"a","problem":"x"}]}`), "", "",
[]string{"ace holds a: x", "ace is assigned photos, which no watched branch lists (H-A-143)"}, []string{"photos"}},
{"could not run, an unlisted module", "a", meshwants.CompositionRun{Machine: "ace", Ended: &at, Outcome: meshwants.CompositionRunOutcomeCouldNotRun, Said: "ace: gone"},
"", "ace: gone; ace is assigned photos, which no watched branch lists (H-A-143)", nil, []string{"photos"}},
{"an unlisted module where it composes", "b", runOf(`{"composes":true,"blamed":[]}`), "", "",
[]string{"ace is assigned photos, which no watched branch lists (H-A-143)"}, []string{"photos"}},
} {
t.Run(tc.name, func(t *testing.T) {
run := tc.run
run.Unlisted = tc.unlisted // the set the run's start wrote (H-A-153)
e := judgeRun(tc.module, run)
if e.failed != tc.failed || e.couldNot != tc.couldNo || !slices.Equal(e.warnings, tc.warnings) {
t.Errorf("judged %+v, want failed %q, could not run %q, warnings %q", e, tc.failed, tc.couldNo, tc.warnings)
}
})
}
}
// Design 47 G §727, A-468g, A-470d: a rerun of a composition step starts a new run only on the machine it did not pass, replacing
// that key and carrying every former reader, the one that did not pass marked rerun with the rerun's caller; at the new run's end
// that reader says its end again, marked rerun, naming the new run's ask; a reader that passed does not move; the machine the
// step passed keeps its verdict.
func TestARerunMovesEveryReaderThatDidNotPass(t *testing.T) {
s := newRunStand(t, "src2:e1", "src2:e1", "d1")
s.r.inputs.machines = func(string, string) []string { return []string{"ace", "g14"} }
var mu sync.Mutex
fixed := false
s.verdict = func(node string) (composer.Machine, bool) {
mu.Lock()
defer mu.Unlock()
m := composer.Machine{Composes: true}
m.Blamed = []struct {
Module string `json:"module"`
Problem string `json:"problem"`
}{}
if node == "g14" && !fixed {
m.Composes, m.Reason = false, "two modules own one path"
m.Blamed = append(m.Blamed, struct {
Module string `json:"module"`
Problem string `json:"problem"`
}{"a", "/etc/x"}, struct {
Module string `json:"module"`
Problem string `json:"problem"`
}{"d", "/etc/x"})
}
return m, true
}
ends := make(chan meshwants.StepEnded, 16)
msgIDs := map[string]string{} // the message id of each step's latest end
steps := &compositionSteps{node: "n1", now: time.Now, logf: t.Logf, run: s.r.run, resume: s.r.resume, ended: s.runs.stepEnded,
say: func(event string, body any, msgID string) error {
if e, ok := body.(meshwants.StepEnded); ok {
mu.Lock()
msgIDs[e.ID] = msgID
mu.Unlock()
ends <- e
}
return nil
}}
move := steps.move(context.Background())
s.runs.moved.Store(&move)
step := func(m string, rerun bool) []byte {
raw, _ := json.Marshal(meshwants.StepRun{Pipeline: "main.7." + m, Module: m, Branch: "main", Revision: 7, Step: meshwants.StepRunStepComposition, Rerun: rerun, By: map[bool]string{true: "op@n1"}[rerun]})
return raw
}
got := map[string]meshwants.StepEnded{}
for _, m := range []string{"a", "b", "d"} {
pullOne(steps, "ask-"+m, step(m, false))
e := <-ends
got[e.Module] = e
}
if got["a"].Outcome != meshwants.StepEndedOutcomeFailed || got["d"].Outcome != meshwants.StepEndedOutcomeFailed || got["b"].Outcome != meshwants.StepEndedOutcomePassed {
t.Fatalf("the first ends: %+v", got)
}
former := got["d"].Shared[1].Ask
mu.Lock()
fixed = true
mu.Unlock()
pullOne(steps, "ask-a2", step("a", true))
moved := map[string]meshwants.StepEnded{}
for range 2 {
select {
case e := <-ends:
moved[e.ID] = e
case <-time.After(5 * time.Second):
t.Fatalf("the ends after the rerun: %+v", moved)
}
}
a, d := moved["ask-a2"], moved["ask-d"]
if a.Outcome != meshwants.StepEndedOutcomePassed || d.Outcome != meshwants.StepEndedOutcomePassed || !d.Rerun || d.By != "op@n1" ||
len(d.Shared) != 2 || d.Shared[1].Machine != "g14" || d.Shared[1].Ask == former || d.Shared[1].Ask != a.Shared[1].Ask {
t.Fatalf("after the rerun: a %+v, d %+v", a, d)
}
mu.Lock()
// A-470q: the first end keeps the ask's id; the end said again names the moved run's ask, so the bus does not drop it.
if msgIDs["ask-a2"] != "ask-a2" || msgIDs["ask-d"] != "ask-d."+a.Shared[1].Ask || msgIDs["ask-b"] != "ask-b" {
t.Errorf("the message ids of the ends: %v", msgIDs)
}
mu.Unlock()
if s.puts != 3 {
t.Errorf("%d run asks, want one more for the machine a did not pass", s.puts)
}
select {
case e := <-ends:
t.Errorf("a reader that passed moved: %+v", e)
case <-time.After(50 * time.Millisecond):
}
run, _, _, _ := s.runs.read(runKeyOf("main.7", "g14"))
marks := map[string]bool{}
for _, c := range run.Readers {
marks[c.ID] = c.Rerun
}
if len(run.Readers) != 3 || !marks["ask-d"] || marks["ask-b"] || !marks["ask-a2"] {
t.Errorf("the new run's readers %+v", run.Readers)
}
// A-470m: each reader's `ended` is written once its step said its end, and ask-b's carried into the new run.
deadline := time.After(5 * time.Second)
for {
wake := s.runs.wake()
run, _, _, _ = s.runs.read(runKeyOf("main.7", "g14"))
if !slices.ContainsFunc(run.Readers, func(c meshwants.CompositionReader) bool { return c.Ended == nil }) {
break
}
select {
case <-wake:
case <-deadline:
t.Fatalf("a reader of the new run names no end: %+v", run.Readers)
}
}
}
// Design 47 H-A-143, G §532: a machine's composition takes each module's entry from the newest revision of the first of its
// watched branches, in its registration's order, that lists it; the candidate's revision replaces its branch's newest for the
// modules it moves, and whole where it is that branch's newest; the half keeps the candidate's revision.
func TestACompositionTakesEachModuleAcrossTheWatchedBranches(t *testing.T) {
entry := func(module, fp string) meshcatalog.CatalogEntry {
return meshcatalog.CatalogEntry{Module: module, Fp: fp, Manifest: map[string]any{"module": module}}
}
half := func(branch string, revision int64, movers []string, entries ...meshcatalog.CatalogEntry) mcc.Half {
h := mcc.Half{Revision: meshcatalog.CatalogRevision{Branch: branch, Revision: revision, Definitions: []meshcatalog.CatalogRevisionDefinitionsItem{{Seat: "s1", Digest: branch}}},
Entries: map[string]meshcatalog.CatalogEntry{}}
for _, m := range movers {
h.Revision.Movers = append(h.Revision.Movers, meshcatalog.TakeInEntry{Module: m})
}
for _, e := range entries {
h.Entries[e.Module] = e
}
return h
}
newest := map[string]mcc.Half{
"main": half("main", 4, nil, entry("engine", "e1"), entry("a", "a1"), entry("both", "main")),
"master": half("master", 9, nil, entry("f1-circuits", "f1")),
"nox-mesh": half("nox-mesh", 3, nil, entry("link2pay", "l1"), entry("photos", "p1"), entry("both", "nox")),
}
registrations := map[string][]string{"both": {"nox-mesh", "main"}, "f1-circuits": {"master"}, "link2pay": {"nox-mesh"}, "photos": {"nox-mesh"}}
registrations["engine"], registrations["a"] = []string{"main"}, []string{"main"}
watched := func(module string) []string { return registrations[module] } // a module no registration names has none (H-A-144)
for _, tc := range []struct {
name string
step meshwants.StepRun
candidate mcc.Half
newest map[string]mcc.Half
want map[string]string // module -> fingerprint
}{
{"the newest of main, the others' apps beside it", meshwants.StepRun{Branch: "main", Module: "a", Revision: 5},
half("main", 5, []string{"a"}, entry("engine", "e1"), entry("a", "a2"), entry("both", "main")), newest,
map[string]string{"engine": "e1", "a": "a2", "both": "nox", "f1-circuits": "f1", "link2pay": "l1", "photos": "p1"}},
{"an older candidate moves only its movers", meshwants.StepRun{Branch: "nox-mesh", Module: "link2pay", Revision: 2},
half("nox-mesh", 2, []string{"photos"}, entry("link2pay", "l0"), entry("both", "nox0")), newest,
map[string]string{"engine": "e1", "a": "a1", "both": "nox", "f1-circuits": "f1", "link2pay": "l0"}},
{"a branch not yet held is the candidate's", meshwants.StepRun{Branch: "master", Module: "f1-circuits", Revision: 1},
half("master", 1, nil, entry("f1-circuits", "f0")), map[string]mcc.Half{"main": newest["main"]},
map[string]string{"engine": "e1", "a": "a1", "both": "main", "f1-circuits": "f0"}},
{"no view held yet: the candidate alone", meshwants.StepRun{Branch: "main", Module: "a", Revision: 5},
half("main", 5, nil, entry("a", "a2")), nil, map[string]string{"a": "a2"}},
{"a module no registration names is not composed", meshwants.StepRun{Branch: "main", Module: "a", Revision: 5},
half("main", 5, nil, entry("a", "a2"), entry("checker", "c1")), nil, map[string]string{"a": "a2"}},
} {
t.Run(tc.name, func(t *testing.T) {
got := acrossBranches(tc.step, tc.candidate, tc.newest, watched)
fps := map[string]string{}
for name, e := range got.Entries {
fps[name] = e.Fp
}
if !maps.Equal(fps, tc.want) {
t.Errorf("composed from %v, want %v", fps, tc.want)
}
if got.Revision.Revision != tc.candidate.Revision.Revision || len(got.Revision.Definitions) != 1 || got.Revision.Definitions[0].Digest != tc.step.Branch {
t.Errorf("the half keeps revision %d with definitions %v, want the candidate's %d with its own", got.Revision.Revision, got.Revision.Definitions,
tc.candidate.Revision.Revision)
}
})
}
}
// Design 47 H-A-149: the pass over the assignments clears assignment-unlisted when the assignment is gone or one of the module's
// watched branches lists it again, and keeps it while it stands; another finding is left alone.
func TestThePassClearsAnUnlistedAssignmentsFinding(t *testing.T) {
for _, tc := range []struct {
name string
assigned []string // novox's modules
listed bool
kept bool
}{
{"still assigned and listed nowhere: kept", []string{"checker"}, false, true},
{"the assignment gone: cleared", []string{"web"}, false, false},
{"listed again: cleared", []string{"checker"}, true, false},
} {
t.Run(tc.name, func(t *testing.T) {
w := newWorld()
a := mma.Assignments{V: keys.Version, Node: "novox"}
for _, m := range tc.assigned {
a.Modules = append(a.Modules, mma.PlacedModule{Module: m})
}
putAssignments(w, a)
findings := map[string][]byte{}
f, _ := assign.UnlistedFinding("novox", "checker", time.Now())
_ = putInto(findings)(f)
other, _ := assign.UnplacedFinding("g14", time.Now())
_ = putInto(findings)(other)
p := &passer{w: w, logf: t.Logf, listed: func(string) bool { return tc.listed }, findings: assign.Findings{Put: putInto(findings),
Delete: func(k string) error { delete(findings, k); return nil },
Keys: func() ([]string, error) { return slices.Collect(maps.Keys(findings)), nil }}}
p.clearUnlisted()
if _, ok := findings[assign.UnlistedKey("novox", "checker")]; ok != tc.kept {
t.Errorf("the finding kept %v, want %v", ok, tc.kept)
}
if _, ok := findings[assign.UnplacedKey("g14")]; !ok {
t.Error("another finding is cleared")
}
})
}
}
@@ -0,0 +1,916 @@
package main
import (
"context"
"encoding/json"
"errors"
"fmt"
"io/fs"
"os"
"slices"
"strings"
"sync"
"sync/atomic"
"time"
"github.com/nats-io/nats.go/jetstream"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-sdk/go/keys"
"mesh-delivery-assigner/internal/buckets"
)
// The composition runs (design 47 G §718, §719; A-468, A-469d, A-469w, A-469x): the assigner composes each machine once per
// candidate, whatever number of composition steps name it. Each run is one key of its old state `composition-runs`,
// `<candidate key>.<machine>`, each part escaped as a key's name; the step that starts a run writes the key create-only,
// so two steps of one candidate starting at once start one run and the second reads it. A reader is the composition step's
// StepRun with its ask's id (A-468), added and removed by compare-and-set. A key is deleted once composition-runs-kept has
// passed since its `ended`, judged at each new run over at most 20 of the oldest ended keys, as the state inputs is
// (A-465b, A-468b); at the cap (composition-runs-cap-mib, the manifest's max-mib its ceiling, A-469d) no run is started.
const (
// runsSwept is how many of the oldest ended keys each new run judges.
runsSwept = 20
// runBoundPrefix and runUntakenPrefix open a run's two bound keys, each with its own time to live (§720, A-468b,
// A-470): `bound.<run key>` from the ask's ask-taken, `untaken.<run key>` from the run's start.
runBoundPrefix = "bound."
runUntakenPrefix = "untaken."
)
// runKeyOf is the key of a candidate's composition run of a machine (§719).
func runKeyOf(candidate, machine string) string {
return keysPart(candidate) + "." + keys.EscapeName(machine)
}
// keysPart is a name as a key's part.
func keysPart(name string) string { return keys.EscapeName(name) }
// isRunKey is whether a key of the state is a run's own, not one of its bound keys.
func isRunKey(key string) bool {
return !strings.HasPrefix(key, runBoundPrefix) && !strings.HasPrefix(key, runUntakenPrefix)
}
// runSettings are the settings of the composition runs, each read at the start from the file the manifest declares.
type runSettings struct {
// capBytes is composition-runs-cap-mib in bytes.
capBytes int64
// kept is composition-runs-kept, stepBound composition-step-bound, untaken run-untaken-bound (A-469x).
kept, stepBound, untaken time.Duration
// blameTries is blame-tries, carried in each run's request (§721).
blameTries int
}
// defaultRunSettings are the settings' defaults, as the manifest gives them.
var defaultRunSettings = runSettings{capBytes: 16 << 20, kept: 24 * time.Hour, stepBound: 30 * time.Minute, untaken: 24 * time.Hour, blameTries: 20}
// runSettingsOf reads the settings composition-runs-cap-mib, composition-runs-kept, composition-step-bound,
// run-untaken-bound and blame-tries from the files the environment names (A-469x, as outsideSettings): a missing or empty
// file is its default; a content that is no positive whole number or Go duration is an error naming the file.
func runSettingsOf(getenv func(string) string) (runSettings, error) {
s := defaultRunSettings
mib, err := settingFile(getenv("MESH_ASSIGNER_COMPOSITION_RUNS_CAP_MIB_FILE"))
if err != nil {
return s, err
}
if mib > 0 {
s.capBytes = int64(mib) << 20
}
tries, err := settingFile(getenv("MESH_ASSIGNER_BLAME_TRIES_FILE"))
if err != nil {
return s, err
}
if tries > 0 {
s.blameTries = tries
}
for env, to := range map[string]*time.Duration{"MESH_ASSIGNER_COMPOSITION_RUNS_KEPT_FILE": &s.kept,
"MESH_ASSIGNER_COMPOSITION_STEP_BOUND_FILE": &s.stepBound, "MESH_ASSIGNER_RUN_UNTAKEN_BOUND_FILE": &s.untaken} {
d, err := durationFile(getenv(env))
if err != nil {
return s, err
}
if d > 0 {
*to = d
}
}
return s, nil
}
// durationFile reads one setting's file holding a Go duration: 0 for no path, no file or an empty one.
func durationFile(path string) (time.Duration, error) {
if path == "" {
return 0, nil
}
raw, err := os.ReadFile(path)
if errors.Is(err, fs.ErrNotExist) {
return 0, nil
}
if err != nil {
return 0, err
}
v := strings.TrimSpace(string(raw))
if v == "" {
return 0, nil
}
d, err := time.ParseDuration(v)
if err != nil || d <= 0 {
return 0, fmt.Errorf("%s holds %q, which is not a positive Go duration such as 30m", path, v)
}
return d, nil
}
// errRunChanged is a compare-and-set of a run's key that met another write.
var errRunChanged = errors.New("the composition run's key changed")
// runsKV is the state composition-runs: the bus bucket, or a test's.
type runsKV interface {
// get is a key's value and revision; nil for a key not there.
get(key string) ([]byte, uint64, error)
// create writes a key that does not stand, update one at its revision: errRunChanged when it does not stand so.
create(key string, value []byte) (uint64, error)
update(key string, value []byte, revision uint64) (uint64, error)
// delAt deletes a key at its revision: errRunChanged when it no longer stands so, nothing for a key not there. No write
// of the state is made from a value read before its latest change.
delAt(key string, revision uint64) error
keys() ([]string, error)
// arm writes a bound key afresh holding the ask of the run it bounds, with its own time to live (§720, A-470n): at the key's
// latest revision, a delete marker counted, read again when another write came between; its expiry is the bus's event. It
// answers the revision written.
arm(key, ask string, ttl time.Duration) (uint64, error)
// used is how many bytes the state holds.
used() (int64, error)
}
// busRuns is runsKV over the bus bucket.
type busRuns struct {
ctx context.Context
js jetstream.JetStream
kv jetstream.KeyValue
}
func (b busRuns) get(key string) ([]byte, uint64, error) {
e, err := b.kv.Get(b.ctx, key)
if errors.Is(err, jetstream.ErrKeyNotFound) {
return nil, 0, nil
}
if err != nil {
return nil, 0, err
}
return e.Value(), e.Revision(), nil
}
func (b busRuns) create(key string, value []byte) (uint64, error) {
rev, err := b.kv.Create(b.ctx, key, value)
if errors.Is(err, jetstream.ErrKeyExists) {
return 0, errRunChanged
}
return rev, err
}
func (b busRuns) update(key string, value []byte, revision uint64) (uint64, error) {
rev, err := b.kv.Update(b.ctx, key, value, revision)
if errors.Is(err, jetstream.ErrKeyExists) || errors.Is(err, jetstream.ErrKeyRevisionMismatch) {
return 0, errRunChanged
}
return rev, err
}
func (b busRuns) delAt(key string, revision uint64) error {
err := b.kv.Delete(b.ctx, key, jetstream.LastRevision(revision))
if errors.Is(err, jetstream.ErrKeyExists) || errors.Is(err, jetstream.ErrKeyRevisionMismatch) {
return errRunChanged
}
return err
}
func (b busRuns) keys() ([]string, error) {
l, err := b.kv.ListKeys(b.ctx)
if err != nil {
return nil, err
}
var out []string
for k := range l.Keys() {
out = append(out, k)
}
return out, nil
}
// boundValue is a bound key's value: the key and the ask of the run it bounds (A-470n).
type boundValue struct {
Bound string `json:"bound"`
Ask string `json:"ask"`
}
// arm publishes the bound key holding ask with ttl as its own time to live, expecting the key's latest message (a delete
// marker counted), so a write between is read again and never overwritten unseen (A-470n); the earlier message, replaced,
// takes its time to live with it, so the expiry is heard only ttl after the last write.
func (b busRuns) arm(key, ask string, ttl time.Duration) (uint64, error) {
if b.js == nil {
return 0, errors.New("no bus to arm a bound on")
}
raw, err := json.Marshal(boundValue{Bound: key, Ask: ask})
if err != nil {
return 0, err
}
subject := "$KV." + b.kv.Bucket() + "." + key
for {
st, err := b.js.Stream(b.ctx, "KV_"+b.kv.Bucket())
if err != nil {
return 0, err
}
var last uint64
m, err := st.GetLastMsgForSubject(b.ctx, subject)
switch {
case err == nil:
last = m.Sequence
case !errors.Is(err, jetstream.ErrMsgNotFound):
return 0, err
}
ack, err := b.js.Publish(b.ctx, subject, raw, jetstream.WithMsgTTL(ttl), jetstream.WithExpectLastSequencePerSubject(last))
if err != nil && strings.Contains(err.Error(), "wrong last sequence") {
continue
}
if err != nil {
return 0, err
}
return ack.Sequence, nil
}
}
func (b busRuns) used() (int64, error) {
st, err := b.kv.Status(b.ctx)
if err != nil {
return 0, err
}
return int64(st.Bytes()), nil
}
// compositionRuns keeps the composition runs in the state composition-runs.
type compositionRuns struct {
kv runsKV
set runSettings
now func() time.Time
logf func(string, ...any)
mu sync.Mutex
// changed is closed and replaced at each change of the state heard (heard): a step waiting on a run reads its key again.
changed chan struct{}
// seen are the keys the state's watch handed and has not seen deleted: a listing of the bucket misses a key that is
// being written at that moment, so every lookup takes these beside it (keys).
seen map[string]bool
// say says an event of the seat mesh-wants (a reader's wait, A-469y); drop asks the build seat's drop of a run ask (§119);
// nil says or drops nothing.
say publisher
drop func(ask, why string) error
// moved is told each run that ended, for the readers a rerun carried to say their end again (compositionSteps.move).
// Set once the steps are served, after the hub starts.
moved atomic.Pointer[func(run meshwants.CompositionRun)]
}
func newCompositionRuns(kv runsKV, set runSettings, now func() time.Time, logf func(string, ...any)) *compositionRuns {
return &compositionRuns{kv: kv, set: set, now: now, logf: logf, changed: make(chan struct{})}
}
// heard takes a change of the state from its watch (a module watches its own state, principle 1).
func (r *compositionRuns) heard() {
r.mu.Lock()
close(r.changed)
r.changed = make(chan struct{})
r.mu.Unlock()
}
// saw keeps a key the state's watch handed: standing, or deleted or expired.
func (r *compositionRuns) saw(key string, standing bool) {
r.mu.Lock()
defer r.mu.Unlock()
if r.seen == nil {
r.seen = map[string]bool{}
}
if standing {
r.seen[key] = true
} else {
delete(r.seen, key)
}
}
// keys are the state's keys: the bucket's listing with the keys its watch handed beside it, sorted. A key read gone later
// is skipped by its reader.
func (r *compositionRuns) keys() ([]string, error) {
all, err := r.kv.keys()
if err != nil {
return nil, err
}
r.mu.Lock()
for key := range r.seen {
all = append(all, key)
}
r.mu.Unlock()
slices.Sort(all)
return slices.Compact(all), nil
}
// wake is closed at the next change heard.
func (r *compositionRuns) wake() <-chan struct{} {
r.mu.Lock()
defer r.mu.Unlock()
return r.changed
}
// read is a run's value and revision, or false.
func (r *compositionRuns) read(key string) (meshwants.CompositionRun, uint64, bool, error) {
raw, rev, err := r.kv.get(key)
if err != nil || raw == nil {
return meshwants.CompositionRun{}, 0, false, err
}
var run meshwants.CompositionRun
if err := json.Unmarshal(raw, &run); err != nil {
return meshwants.CompositionRun{}, 0, false, fmt.Errorf("the composition run %s does not read: %w", key, err)
}
return run, rev, true, nil
}
// change writes a run's key by compare-and-set: f changes the value read and says whether to write it; false leaves it.
// It answers the value written or left, and false for a key not there.
func (r *compositionRuns) change(key string, f func(*meshwants.CompositionRun) bool) (meshwants.CompositionRun, bool, error) {
for {
run, rev, ok, err := r.read(key)
if err != nil || !ok {
return run, ok, err
}
if !f(&run) {
return run, true, nil
}
raw, err := json.Marshal(run)
if err != nil {
return run, true, err
}
if _, err := r.kv.update(key, raw, rev); errors.Is(err, errRunChanged) {
continue
} else if err != nil {
return run, true, err
}
r.heard()
return run, true, nil
}
}
// fill is the state's fill against its cap.
func (r *compositionRuns) fill() (meshwants.Fill, error) {
at := r.now().UTC()
used, err := r.kv.used()
return meshwants.Fill{Store: buckets.CompositionRunsState, Bytes: used, Cap: r.set.capBytes, At: &at}, err
}
// joined is a reader's place in a run: the run's key, whether this reader started it (so it composes the machine), and the
// value as it stood.
type joined struct {
key string
started bool
run meshwants.CompositionRun
}
// join finds or starts the candidate's run of the machine for reader (§718, §719, §720): a run that stands and has not
// ended, or that ended other than could not run, is read, the reader added; none, or one that could not run, is started:
// written create-only (or replacing the ended key by compare-and-set), the reader its first, ask its run ask's id. At the
// cap no run is started, an error naming the fill.
func (r *compositionRuns) join(reader meshwants.CompositionReader, candidate, machine, ask string) (joined, error) {
return r.joinAt(runKeyOf(candidate, machine), reader, candidate, machine, ask)
}
// joinAt is join of the run under key: a machine's composition run, or a revision's validate run with no machine (H-A-108).
func (r *compositionRuns) joinAt(key string, reader meshwants.CompositionReader, candidate, machine, ask string) (joined, error) {
for {
run, rev, ok, err := r.read(key)
if err != nil {
return joined{}, err
}
if ok && (run.Ended == nil || run.Outcome != meshwants.CompositionRunOutcomeCouldNotRun) {
if hasReader(run.Readers, reader.ID) {
return joined{key: key, run: run}, nil
}
run.Readers = append(run.Readers, reader)
raw, err := json.Marshal(run)
if err != nil {
return joined{}, err
}
if _, err := r.kv.update(key, raw, rev); errors.Is(err, errRunChanged) {
continue
} else if err != nil {
return joined{}, err
}
r.heard()
if run.Ended == nil && r.untaken(key, run.Ask) {
r.sayWaits(run, []meshwants.CompositionReader{reader}, "")
}
return joined{key: key, run: run}, nil
}
if err := r.room(); err != nil {
return joined{}, err
}
started := r.now().UTC()
fresh := meshwants.CompositionRun{Candidate: candidate, Machine: machine, Ask: ask, Started: &started,
Readers: []meshwants.CompositionReader{reader}}
raw, err := json.Marshal(fresh)
if err != nil {
return joined{}, err
}
if ok {
_, err = r.kv.update(key, raw, rev) // could not run is never read: a new run replaces it (§720)
} else {
_, err = r.kv.create(key, raw)
}
if errors.Is(err, errRunChanged) {
continue
} else if err != nil {
return joined{}, err
}
r.heard()
// An ask waiting in the queue has no clock but run-untaken-bound from its start (A-466s, A-468b, A-470, A-470n).
if _, err := r.armBound(runUntakenPrefix, key, ask, r.set.untaken); err != nil {
r.logf("the untaken bound of the composition run %s is not armed: %v", key, err)
}
r.sayWaits(fresh, fresh.Readers, "")
return joined{key: key, started: true, run: fresh}, nil
}
}
// room sweeps the state and says whether a new run may start: an error naming the fill at the cap (as A-465a).
func (r *compositionRuns) room() error {
if err := r.sweep(); err != nil {
r.logf("composition-runs: the keys past composition-runs-kept are not all deleted: %v", err)
}
f, err := r.fill()
if err != nil {
return fmt.Errorf("the fill of the state %s is not read, so no composition run is started: %w", buckets.CompositionRunsState, err)
}
if f.Bytes >= f.Cap {
return fmt.Errorf("the state %s is at its cap of %d MiB (%d bytes kept), so no composition run is started", buckets.CompositionRunsState,
f.Cap>>20, f.Bytes)
}
return nil
}
// sweep deletes, among the 20 oldest ended runs, those ended more than composition-runs-kept ago, with their bound keys.
func (r *compositionRuns) sweep() error {
all, err := r.keys()
if err != nil {
return err
}
type endedAt struct {
key string
at time.Time
}
var ended []endedAt
for _, key := range all {
if !isRunKey(key) {
continue
}
run, _, ok, err := r.read(key)
if err != nil || !ok || run.Ended == nil {
continue
}
ended = append(ended, endedAt{key, *run.Ended})
}
slices.SortFunc(ended, func(a, b endedAt) int { return a.at.Compare(b.at) })
if len(ended) > runsSwept {
ended = ended[:runsSwept]
}
var errs []error
for _, e := range ended {
if r.now().Sub(e.at) >= r.set.kept {
errs = append(errs, r.deleteRun(e.key, func(run meshwants.CompositionRun) bool {
return run.Ended != nil && r.now().Sub(*run.Ended) >= r.set.kept
}))
}
}
return errors.Join(errs...)
}
// deleteRun deletes a run's key with its bound keys while the value it holds is still one gone judges gone, each delete at the
// revision just read and judged again on a conflict: a run that replaced the key meanwhile, and its bounds, stand.
func (r *compositionRuns) deleteRun(key string, gone func(meshwants.CompositionRun) bool) error {
for {
run, rev, ok, err := r.read(key)
if err != nil || !ok || !gone(run) {
return err
}
if err := r.clearBounds(key, run.Ask, runBoundPrefix, runUntakenPrefix); err != nil {
return err
}
if err := r.kv.delAt(key, rev); errors.Is(err, errRunChanged) {
continue
} else if err != nil {
return err
}
r.heard()
return nil
}
}
// clearBounds deletes the bound keys of the run of ask while key holds that run (or none) and the bound holds that ask: each at
// the revision it was read at, read again on a conflict, so a bound a newer run of the key armed is never deleted.
func (r *compositionRuns) clearBounds(key, ask string, prefixes ...string) error {
var errs []error
for _, prefix := range prefixes {
for {
run, _, ok, err := r.read(key)
if err != nil {
errs = append(errs, err)
break
}
if ok && run.Ask != ask {
break // a newer run holds the key: its bounds are its own
}
held, rev, standing, err := r.boundOf(prefix + key)
if err != nil || !standing {
errs = append(errs, err)
break
}
if held != ask {
break // the bound of another ask (A-470n): not this run's to delete
}
if err := r.kv.delAt(prefix+key, rev); errors.Is(err, errRunChanged) {
continue
} else if err != nil {
errs = append(errs, err)
}
break
}
}
return errors.Join(errs...)
}
// stepEnded writes at as the `ended` of the reader asked under id in each run of its step's candidate naming it, by
// compare-and-set (A-470m): the time its step said its end, carried with it into a rerun's run.
func (r *compositionRuns) stepEnded(id string, step meshwants.StepRun, at time.Time) {
keys, err := r.keysOfStep(step, id)
if err != nil {
r.logf("the end of the composition step %s is not written on its runs: %v", id, err)
return
}
at = at.UTC()
for _, key := range keys {
if _, _, err := r.change(key, func(c *meshwants.CompositionRun) bool {
i := slices.IndexFunc(c.Readers, func(c meshwants.CompositionReader) bool { return c.ID == id })
if i < 0 {
return false
}
c.Readers[i].Ended = &at
return true
}); err != nil {
r.logf("the end of the composition step %s is not written on the composition run %s: %v", id, key, err)
}
}
}
// keysOfStep are the keys of the runs the step asked under id reads: its revision's validate run for a validate step, its
// candidate's runs naming it for a composition step.
func (r *compositionRuns) keysOfStep(step meshwants.StepRun, id string) ([]string, error) {
if step.Step == meshwants.StepRunStepValidate {
key, err := validateKeyOf(step)
if err != nil {
return nil, err
}
return []string{key}, nil
}
candidate, err := candidateKeyOf(step)
if err != nil {
return nil, err
}
return r.keysOf(candidate, id)
}
// hasReader is whether readers holds the step asked under id.
func hasReader(readers []meshwants.CompositionReader, id string) bool {
return slices.ContainsFunc(readers, func(c meshwants.CompositionReader) bool { return c.ID == id })
}
// readerOf is a composition step as a run's reader: its StepRun with its ask's id (A-468).
func readerOf(id string, s meshwants.StepRun) meshwants.CompositionReader {
return meshwants.CompositionReader{ID: id, Pipeline: s.Pipeline, Step: s.Step, Module: s.Module, Branch: s.Branch, Commit: s.Commit,
Revision: s.Revision, Source: s.Source, Fingerprint: s.Fingerprint, Run: s.Run, Rerun: s.Rerun, By: s.By}
}
// stepRunOf is a reader's StepRun again, for its step-ended.
func stepRunOf(c meshwants.CompositionReader) meshwants.StepRun {
return meshwants.StepRun{Pipeline: c.Pipeline, Step: c.Step, Module: c.Module, Branch: c.Branch, Commit: c.Commit, Revision: c.Revision,
Source: c.Source, Fingerprint: c.Fingerprint, Run: c.Run, Rerun: c.Rerun, By: c.By}
}
// watchRuns hears the changes of the state composition-runs (principle 1): each change wakes the steps waiting on a run, and
// the expiry of a bound key, the bus's marker, is handed to expired (§720). After the values that stand, ready is called.
func watchRuns(ctx context.Context, kv jetstream.KeyValue, r *compositionRuns, expired func(key string), ready func()) error {
w, err := kv.WatchAll(ctx)
if err != nil {
return err
}
go func() {
defer func() { _ = w.Stop() }()
for {
select {
case <-ctx.Done():
return
case e, ok := <-w.Updates():
if !ok {
return
}
if e == nil {
if ready != nil {
ready()
ready = nil
}
continue
}
r.saw(e.Key(), e.Operation() == jetstream.KeyValuePut)
if e.Operation() == jetstream.KeyValuePurge && !isRunKey(e.Key()) && expired != nil {
expired(e.Key())
}
r.heard()
}
}
}()
return nil
}
// end ends the run of ask in its key with an outcome, its words and the machine's verdict, by compare-and-set; it answers
// false when the key holds another run or the run has ended already.
func (r *compositionRuns) end(key, ask, outcome, said string, verdict map[string]any) (bool, error) {
ended := false
_, _, err := r.change(key, func(c *meshwants.CompositionRun) bool {
if c.Ask != ask || c.Ended != nil {
return false
}
at := r.now().UTC()
c.Ended, c.Outcome, c.Said, c.Verdict = &at, outcome, said, verdict
ended = true
return true
})
return ended, err
}
// keyOfAsk is the key of the run whose ask is ask, or none.
func (r *compositionRuns) keyOfAsk(ask string) (string, meshwants.CompositionRun, error) {
all, err := r.keys()
if err != nil {
return "", meshwants.CompositionRun{}, err
}
for _, key := range all {
if !isRunKey(key) {
continue
}
run, _, ok, err := r.read(key)
if err == nil && ok && run.Ask == ask {
return key, run, nil
}
}
return "", meshwants.CompositionRun{}, nil
}
// heardEnd ends the run of the ask a build seat's step-ended names (§719, A-240): a run ask that ended other than passed
// could not run; a passed one's answer, read with read, is the machine's verdict, or why it is none. An end of an ask no run
// names is another asker's, or of a run gone, and changes nothing.
func (r *compositionRuns) heardEnd(e buildstep.StepEnded, read func(buildstep.StepEnded) ([]byte, error)) error {
if e.Asker != runAsker || e.Ask == "" {
return nil
}
key, run, err := r.keyOfAsk(e.Ask)
if err != nil || key == "" {
return err
}
if run.Ended != nil { // ended by its bound or a drop: the end heard later is ignored (§720)
r.logf("the step-ended of the run ask %s is ignored: its composition run %s ended before it (%s)", e.Ask, key, run.Said)
return nil
}
node := run.Machine
outcome, said := meshwants.CompositionRunOutcomeCouldNotRun, ""
var verdict map[string]any
if e.Outcome != buildstep.OutcomePassed {
said = fmt.Sprintf("%s: its run ask %s ended %s on %s: %s", node, e.Ask, e.Outcome, e.Node, e.Said)
} else if answer, err := read(e); err != nil { // the program's last line of standard output (A-254)
said = node + ": " + err.Error()
} else if isValidateRun(run) {
if verdict, said = validateRunVerdict(answer); said == "" {
outcome = meshwants.CompositionRunOutcomePassed
}
} else if verdict, said = runVerdict(node, answer); said == "" {
outcome = meshwants.CompositionRunOutcomePassed
}
_, err = r.endRun(key, e.Ask, outcome, said, verdict)
return err
}
// await waits until each run of keys has ended, through the state's changes heard, or ctx ends: it answers each run as it
// stands then; a key gone could not run.
func (r *compositionRuns) await(ctx context.Context, keys []string) map[string]meshwants.CompositionRun {
out := map[string]meshwants.CompositionRun{}
for {
wake := r.wake()
open := false
for _, key := range keys {
run, _, ok, err := r.read(key)
switch {
case err != nil:
open = true
continue
case !ok:
at := r.now().UTC()
candidate, machine, _ := strings.Cut(key, ".")
run = meshwants.CompositionRun{Candidate: unescape(candidate), Machine: unescape(machine), Ended: &at,
Outcome: meshwants.CompositionRunOutcomeCouldNotRun, Said: unescape(machine) + ": its composition run " + key + " is gone"}
case run.Ended == nil:
open = true
}
out[key] = run
}
if !open {
return out
}
select {
case <-ctx.Done():
return out
case <-wake:
}
}
}
// unescape is a key's part as a name again; a part that does not read stays as it is.
func unescape(part string) string {
if name, err := keys.UnescapeName(part); err == nil {
return name
}
return part
}
// sharedOf names per machine the runs of keys and their asks (§729): from runs where given, else as each key stands.
func (r *compositionRuns) sharedOf(keys []string, runs map[string]meshwants.CompositionRun) []meshwants.Shared {
out := []meshwants.Shared{}
for _, key := range keys {
run, ok := runs[key]
if !ok {
if run, _, ok, _ = r.read(key); !ok {
continue
}
}
out = append(out, meshwants.Shared{Machine: run.Machine, Run: key, Ask: run.Ask})
}
return out
}
// leave removes the composition steps of a superseded or cancelled pipeline from every run's readers (§723, A-469n), and answers
// their asks' ids, each told to stop before a run is ended; a running run left with no reader has its ask dropped and ends could not run, "no reader is left" (A-469z),
// so a later step of the candidate starts a new run. A run other readers read goes on for them.
func (r *compositionRuns) leave(pipeline string, stop func(ids []string)) ([]string, error) {
all, err := r.keys()
if err != nil {
return nil, err
}
var ids []string
var errs []error
for _, key := range all {
if !isRunKey(key) {
continue
}
var left []string
var leaving []meshwants.CompositionReader
run, ok, err := r.change(key, func(c *meshwants.CompositionRun) bool {
left, leaving = nil, nil
keep := c.Readers[:0:0]
for _, reader := range c.Readers {
if reader.Pipeline == pipeline && reader.Step == meshwants.CompositionReaderStepComposition {
left = append(left, reader.ID)
leaving = append(leaving, reader)
continue
}
keep = append(keep, reader)
}
c.Readers = keep
return len(left) > 0
})
if err != nil {
errs = append(errs, err)
continue
}
if !ok || len(left) == 0 {
continue
}
ids = append(ids, left...)
if run.Ended == nil && r.untaken(key, run.Ask) { // a reader leaving a run not yet taken: its wait ends at once (A-470u)
r.sayWaits(run, leaving, "superseded")
}
if stop != nil {
stop(left) // the steps that left say no end, the run's included
}
if run.Ended != nil || len(run.Readers) > 0 {
continue
}
why := "no reader is left: the pipeline " + pipeline + " is superseded or cancelled"
if r.drop != nil {
if err := r.drop(run.Ask, why); err != nil {
r.logf("the drop of the run ask %s of the composition run %s is not answered: %v", run.Ask, key, err)
}
}
if _, err := r.endRun(key, run.Ask, meshwants.CompositionRunOutcomeCouldNotRun, run.Machine+": "+why, nil); err != nil {
errs = append(errs, err)
}
}
return ids, errors.Join(errs...)
}
// passedOn is whether the step of module passed on the machine of an ended run (§722): neither failed nor could not run there.
func passedOn(module string, run meshwants.CompositionRun) bool {
e := judgeVerdict(module, run) // the unlisted modules change only the words, never whether it passed
return e.failed == "" && e.couldNot == ""
}
// formerOf is the place in readers of a step's former ask: the reader of the same pipeline's composition step, or -1.
func formerOf(readers []meshwants.CompositionReader, pipeline string) int {
return slices.IndexFunc(readers, func(c meshwants.CompositionReader) bool {
return c.Pipeline == pipeline && c.Step == meshwants.CompositionReaderStepComposition
})
}
// rejoin is join for a step asked again (§727, A-468g, A-470d): on a machine whose ended run it passed it keeps that verdict,
// reading the run under its new ask; a running run it joins; an ended run it did not read and that could run it reads, as one
// started after its last end; otherwise it starts a new run, replacing the ended key by compare-and-set and carrying every former
// reader into the new value: each that did not pass on the former run marked `rerun` with by the rerun's caller, each that passed
// not (A-470d).
func (r *compositionRuns) rejoin(reader meshwants.CompositionReader, candidate, machine, ask string) (joined, error) {
key := runKeyOf(candidate, machine)
for {
run, rev, ok, err := r.read(key)
if err != nil {
return joined{}, err
}
if !ok {
return r.join(reader, candidate, machine, ask)
}
at := formerOf(run.Readers, reader.Pipeline)
ended := run.Ended != nil
keep := ended && at >= 0 && passedOn(reader.Module, run)
read := !ended || (at < 0 && run.Outcome != meshwants.CompositionRunOutcomeCouldNotRun)
if keep || read {
if at >= 0 && run.Readers[at].ID == reader.ID {
return joined{key: key, run: run}, nil
}
var former []meshwants.CompositionReader
if at >= 0 {
former = []meshwants.CompositionReader{run.Readers[at]}
run.Readers[at] = reader
} else {
run.Readers = append(run.Readers, reader)
}
if err := r.write(key, run, rev); errors.Is(err, errRunChanged) {
continue
} else if err != nil {
return joined{}, err
}
if run.Ended == nil && r.untaken(key, run.Ask) { // as join: a reader of a run not yet taken waits for a build node (A-469y)
r.sayWaits(run, former, "superseded") // the place it takes: that wait ends at once (A-470u)
r.sayWaits(run, []meshwants.CompositionReader{reader}, "")
}
return joined{key: key, run: run}, nil
}
if err := r.room(); err != nil {
return joined{}, err
}
started := r.now().UTC()
fresh := meshwants.CompositionRun{Candidate: candidate, Machine: machine, Ask: ask, Started: &started}
for i, c := range run.Readers {
if i == at {
continue
}
c.Rerun, c.By = !passedOn(c.Module, run), ""
if c.Rerun {
c.By = reader.By
}
fresh.Readers = append(fresh.Readers, c)
}
fresh.Readers = append(fresh.Readers, reader)
if err := r.clearBounds(key, run.Ask, runBoundPrefix, runUntakenPrefix); err != nil { // the former run's bounds go with it
r.logf("the bound keys of the former composition run %s are not deleted: %v", key, err)
}
if err := r.write(key, fresh, rev); errors.Is(err, errRunChanged) {
continue
} else if err != nil {
return joined{}, err
}
if _, err := r.armBound(runUntakenPrefix, key, ask, r.set.untaken); err != nil {
r.logf("the untaken bound of the composition run %s is not armed: %v", key, err)
}
r.sayWaits(fresh, fresh.Readers, "")
return joined{key: key, started: true, run: fresh}, nil
}
}
// write writes a run's value at its revision.
func (r *compositionRuns) write(key string, run meshwants.CompositionRun, rev uint64) error {
raw, err := json.Marshal(run)
if err != nil {
return err
}
if _, err := r.kv.update(key, raw, rev); err != nil {
return err
}
r.heard()
return nil
}
@@ -0,0 +1,404 @@
//go:build integration
package main
import (
"encoding/json"
"fmt"
"strings"
"sync"
"testing"
"time"
"github.com/nats-io/nats.go"
"github.com/nats-io/nats.go/jetstream"
"git.novox.be/novox/mesh-contracts/go/clients/nodeengineclient/enginereads"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
mpr "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/nodebuildgo"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/composer"
"mesh-delivery-assigner/internal/buckets"
)
// Test 108 (design 47 G §733; §718 to §723, §727, §728; A-468 to A-470f): the assigner started whole against the bus composes
// each machine once per candidate. Two or three composition steps of one candidate on two machines make one key, one request and
// one run ask per machine, and each step reads both verdicts; a machine blaming a and b fails their steps and passes c's with a
// warning; a verdict with no `blamed` is judged as before, "the composer names no culprits", and a machine blaming none fails
// every step; a step of another candidate starts its own runs. A taken ask that keeps saying progress is not ended by the bound,
// one silent past it ends could not run with its ask dropped, a step-ended after that is ignored and journaled, and an ask never
// taken ends at run-untaken-bound; a bound holds its run's ask (A-470n). A rerun of a starts one run on the machine it did not
// pass and moves b; a superseded step leaves
// a run running for its other reader; an assigner restarted during a run takes it up by its ask; compositions-drop ends the
// readers and deletes the key; at the cap a step ends could not run, naming the fill.
func TestOneCompositionRunPerCandidateAndMachine(t *testing.T) {
b := startBed(t, "")
b.settings = map[string]string{"MESH_ASSIGNER_COMPOSITION_STEP_BOUND_FILE": "2s", "MESH_ASSIGNER_RUN_UNTAKEN_BOUND_FILE": "15s", // past a restart
"MESH_ASSIGNER_COMPOSITION_RUNS_CAP_MIB_FILE": "1"}
nc, err := nats.Connect(b.srv.ClientURL())
if err != nil {
t.Fatal(err)
}
t.Cleanup(nc.Close)
const commit = "1111111111111111111111111111111111111111"
if _, err := b.js.CreateOrUpdateConsumer(b.ctx, "EVENTS", jetstream.ConsumerConfig{Durable: "n1_mesh-delivery-assigner",
FilterSubjects: []string{enginereads.SubjectPrefix + "*", "mesh.mod." + buckets.IndexerModule + ".event.views.>", meshcatalog.SubjectCatalogRevisionAll,
nodebuildgo.SubjectStepEndedAll, nodebuildgo.SubjectAskTakenAll, nodebuildgo.SubjectStepProgressAll, pipelineEndedSubject},
AckPolicy: jetstream.AckExplicitPolicy, AckWait: 2 * time.Second}); err != nil { // an event handed to the stopped assigner's pull comes again soon
t.Fatal(err)
}
for _, node := range []string{"n1", "n2"} {
raw, _ := json.Marshal(nodeengine.Running{V: 1, Node: node, Module: "engine", Fingerprint: "src2:e1", At: time.Now().UTC()})
if _, err := b.js.Publish(b.ctx, nodeengine.SubjectRunning(node, "engine"), raw); err != nil {
t.Fatal(err)
}
}
awaitKept(t, b, nodeengine.StreamRunning, 2)
engine := meshcatalog.CatalogEntry{Module: "engine", Fp: "src2:e1", Repository: "novox/mesh-host", Commit: commit, Path: ".",
Serves: []string{nodeengine.Seat + ".composition"}, Manifest: map[string]any{"module": "engine", "version": "0.1"}}
b.cat.mu.Lock()
b.cat.entries[trunkBranch] = map[string]meshcatalog.CatalogEntry{"engine": engine}
for _, m := range []string{"a", "b", "c"} {
b.cat.entries[trunkBranch][m] = meshcatalog.CatalogEntry{Module: m, Fp: "src2:" + m, Repository: "novox/" + m, Commit: commit, Path: ".", Manifest: map[string]any{"module": m}}
}
b.cat.rev[trunkBranch] = 3
b.cat.mu.Unlock()
for _, node := range []string{"n1", "n2"} {
for _, m := range []string{"a", "b", "c"} {
b.place(t, node, m)
}
}
var mu sync.Mutex
inputsAsked := map[string]int{} // by candidate and node
var drops []string
respond := func(subject string, f func(m *nats.Msg) any) {
sub, err := nc.Subscribe(subject, func(m *nats.Msg) {
raw, _ := json.Marshal(map[string]any{"result": f(m), "node": "n0"})
_ = m.Respond(raw)
})
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = sub.Unsubscribe() })
}
respond("mesh.seat.node-engine.call.compose-candidate.*.*", func(m *nats.Msg) any {
node := strings.Split(m.Subject, ".")[5]
var in nodeengine.ComposeCandidateInput
_ = json.Unmarshal(m.Data, &in)
mu.Lock()
inputsAsked[in.Candidate+" "+node]++
mu.Unlock()
return map[string]any{"candidate": in.Candidate, "node": node, "verdict": "composed", "input": map[string]any{"node": node}, "modules": []any{}, "own": map[string]any{}, "took": 1, "v": 1}
})
respond("mesh.seat.mesh-catalog.call.entry.*", func(*nats.Msg) any { return meshcatalog.EntryAnswer{Entry: engine} })
respond("mesh.seat.node-build-go.call.drop.*", func(m *nats.Msg) any {
var in nodebuildgo.DropInput
_ = json.Unmarshal(m.Data, &in)
mu.Lock()
drops = append(drops, in.ID)
mu.Unlock()
return map[string]any{}
})
respond("mesh.seat.mesh-hand-acts.call.hand-act.*", func(*nats.Msg) any { return map[string]any{"log": "hand-act-1"} })
// The ends are read from the stream through a durable consumer, as the runner hears them: an end the bus drops as a
// repeated message id is never heard (A-470q).
ended := make(chan meshwants.StepEnded, 32)
runner, err := b.js.CreateOrUpdateConsumer(b.ctx, "EVENTS", jetstream.ConsumerConfig{Durable: "runner-stand-in",
FilterSubject: "mesh.seat.mesh-wants.event.step-ended.n1", AckPolicy: jetstream.AckExplicitPolicy, DeliverPolicy: jetstream.DeliverNewPolicy})
if err != nil {
t.Fatal(err)
}
heard, err := runner.Consume(func(m jetstream.Msg) {
var e meshwants.StepEnded
_ = json.Unmarshal(m.Data(), &e)
_ = m.Ack()
ended <- e
})
if err != nil {
t.Fatal(err)
}
t.Cleanup(heard.Stop)
subscribed(t, nc)
from := b.journal.mark()
_, stop := b.startStoppable(t)
b.journal.await(t, from, "the composition step is pulled from", "the composition step served", 30*time.Second)
select {
case <-b.seatListRead:
case <-time.After(30 * time.Second):
t.Fatal("the assigner did not read the seat list within 30 s")
}
queue, _ := buildstep.AskStream(buildstep.AskGo)
worker, err := b.js.CreateOrUpdateConsumer(b.ctx, queue, jetstream.ConsumerConfig{Durable: "stand-in", FilterSubject: "mesh.seat.node-build-go.accept.check.mesh-wants",
AckPolicy: jetstream.AckExplicitPolicy})
if err != nil {
t.Fatal(err)
}
step := func(id, module, run string, rerun bool) {
t.Helper()
s := meshwants.StepRun{Pipeline: "main.3." + module, Step: meshwants.StepRunStepComposition, Module: module, Branch: trunkBranch, Revision: 3,
Commit: commit, Fingerprint: "src2:" + module, Run: run, Rerun: rerun}
if run != "" {
s.Pipeline = "run-" + run + "." + module
}
if rerun {
s.By = "op@n1"
}
raw, _ := json.Marshal(s)
msg := nats.NewMsg(meshwants.AcceptSubjectStep)
msg.Header.Set("x-event-id", id)
msg.Data = raw
if err := nc.PublishMsg(msg); err != nil {
t.Fatal(err)
}
}
type asked struct {
ask buildstep.StepAsk
machine string
}
// asks takes n run asks of the stand-in build seat, each with the machine its request composes.
asks := func(n int) []asked {
t.Helper()
var out []asked
for range n {
got, err := worker.Next(jetstream.FetchMaxWait(20 * time.Second))
if err != nil {
t.Fatalf("%d of %d run asks put: %v", len(out), n, err)
}
_ = got.Ack()
a, err := buildstep.DecodeStepAsk(got.Data())
if err != nil || a.Run == nil {
t.Fatalf("the run ask %s does not read: %v", got.Data(), err)
}
req, err := composer.Decode(readInput(t, nc, a.Run.Input))
if err != nil || len(req.Machines) != 1 || req.BlameTries != 20 {
t.Fatalf("the request of %s: %+v %v", a.ID, req, err)
}
out = append(out, asked{a, req.Machines[0]})
}
return out
}
noMoreAsks := func(what string) {
t.Helper()
if got, err := worker.Next(jetstream.FetchMaxWait(300 * time.Millisecond)); err == nil {
t.Fatalf("%s: one more run ask is put: %s", what, got.Data())
}
}
say := func(event string, node string, body any) {
t.Helper()
raw, _ := json.Marshal(body)
if _, err := b.js.Publish(b.ctx, "mesh.seat.node-build-go.event."+event+"."+node, raw); err != nil {
t.Fatal(err)
}
}
answer := func(a asked, machine string) {
t.Helper()
v := fmt.Sprintf(`{"v":%d,"cases":[{"name":"change","manifests":{},"machines":{%q:%s}}]}`, composer.Version, a.machine, machine)
say("step-ended", "b1", buildstep.StepEnded{V: 1, ID: a.ask.ID, Ask: a.ask.ID, Asker: runAsker, Node: "b1", Outcome: buildstep.OutcomePassed, Output: v, At: time.Now().UTC()})
}
ends := func(n int, what string) map[string]meshwants.StepEnded {
t.Helper()
out := map[string]meshwants.StepEnded{}
for len(out) < n {
select {
case e := <-ended:
out[e.ID] = e
case <-time.After(20 * time.Second):
t.Fatalf("%s: %d of %d steps ended: %+v", what, len(out), n, out)
}
}
return out
}
runKeys := func(candidate string) []string {
all, _ := b.buckets[buckets.CompositionRuns()].Keys(b.ctx)
var out []string
for _, k := range all {
if isRunKey(k) && strings.HasPrefix(k, keysPart(candidate)+".") {
out = append(out, k)
}
}
return out
}
// readers waits, through a watch of the key, until the run of key has n readers.
readers := func(key string, n int) {
t.Helper()
w, err := b.buckets[buckets.CompositionRuns()].Watch(b.ctx, key)
if err != nil {
t.Fatal(err)
}
defer func() { _ = w.Stop() }()
deadline := time.After(10 * time.Second)
for {
select {
case e := <-w.Updates():
var run meshwants.CompositionRun
if e != nil && json.Unmarshal(e.Value(), &run) == nil && len(run.Readers) == n {
return
}
case <-deadline:
t.Fatalf("the run %s has not %d readers", key, n)
}
}
}
blames := `{"composes":false,"reason":"two modules own one path","blamed":[{"module":"a","problem":"/etc/x is a's and b's"},{"module":"b","problem":"/etc/x is a's and b's"}]}`
composes := `{"composes":true,"blamed":[]}`
// One candidate, three steps, two machines: two runs.
for _, m := range []string{"a", "b", "c"} {
step("step-"+m, m, "", false)
}
first := asks(2)
noMoreAsks("three steps of one candidate")
for _, a := range first {
answer(a, map[string]string{"n1": composes, "n2": blames}[a.machine])
}
got := ends(3, "the three steps")
if a, bb, c := got["step-a"], got["step-b"], got["step-c"]; a.Outcome != meshwants.StepEndedOutcomeFailed || !strings.Contains(a.Said, "n2 holds a") ||
bb.Outcome != meshwants.StepEndedOutcomeFailed || c.Outcome != meshwants.StepEndedOutcomePassed || len(c.Warnings) != 2 ||
!strings.Contains(c.Warnings[0], "n2 holds a") || len(c.Shared) != 2 || c.Shared[0].Ask == c.Shared[1].Ask {
t.Fatalf("the steps of one candidate: %+v", got)
}
if keys := runKeys("main.3"); len(keys) != 2 || inputsAsked["main.3 n1"] != 1 || inputsAsked["main.3 n2"] != 1 {
t.Fatalf("keys %v, inputs asked %v: want one run and one input per machine", keys, inputsAsked)
}
// Another candidate (a run on request): its own runs; an old composer and a machine blaming none fail.
step("step-r1", "a", "r1", false)
for _, a := range asks(2) {
answer(a, map[string]string{"n1": `{"composes":false,"reason":"x"}`, "n2": `{"composes":false,"reason":"own","blamed":[]}`}[a.machine])
}
if e := ends(1, "another candidate")["step-r1"]; e.Outcome != meshwants.StepEndedOutcomeFailed || !strings.Contains(e.Said, "n2 does not compose and blames no module") ||
len(e.Warnings) != 1 || e.Warnings[0] != "n1: the composer names no culprits" {
t.Fatalf("a step of another candidate: %+v", e)
}
// The bound: n1's ask taken and saying progress past the bound, then silent; n2's never taken.
from = b.journal.mark()
step("step-r2", "a", "r2", false)
bound := asks(2)
var n1 asked
for _, a := range bound {
if a.machine == "n1" {
n1 = a
}
}
say("ask-taken", "b1", nodebuildgo.AskTaken{Ask: n1.ask.ID, Asker: runAsker, At: time.Now().UTC(), Node: "b1"})
for i := range 3 { // past the 2 s bound, each beat within it
select {
case e := <-ended:
t.Fatalf("a run saying its progress ended: %+v", e)
case <-time.After(time.Second):
}
if i == 0 { // the bound holds its run's ask, published at the key's latest revision with its own time to live (A-470n)
runs := b.buckets[buckets.CompositionRuns()]
all, _ := runs.Keys(b.ctx)
held := ""
for _, k := range all {
if strings.HasPrefix(k, runBoundPrefix) {
if e, err := runs.Get(b.ctx, k); err == nil {
var v boundValue
_ = json.Unmarshal(e.Value(), &v)
held += v.Ask
}
}
}
if held != n1.ask.ID {
t.Fatalf("the bound keys hold the asks %q, want n1's %s alone", held, n1.ask.ID)
}
}
say("step-progress", "b1", nodebuildgo.StepProgress{Ask: n1.ask.ID, Asker: runAsker, At: time.Now().UTC(), Phase: "run"})
}
e := ends(1, "the bounds")["step-r2"]
if e.Outcome != meshwants.StepEndedOutcomeCouldNotRun || !strings.Contains(e.Said, "said no progress within 2s (composition-step-bound)") ||
!strings.Contains(e.Said, "taken by no build node within 15s (run-untaken-bound)") {
t.Fatalf("past the bounds: %+v", e)
}
mu.Lock()
dropped := len(drops)
mu.Unlock()
if dropped != 2 {
t.Fatalf("%d asks dropped past their bounds, want 2", dropped)
}
answer(n1, composes) // heard after the bound: ignored and journaled
b.journal.await(t, from, "the step-ended of the run ask "+n1.ask.ID+" is ignored", "a late step-ended", 10*time.Second)
// A rerun of a: n1 it passed keeps its verdict; n2 it failed starts one run carrying b, which moves.
step("step-a2", "a", "", true)
again := asks(1)
noMoreAsks("a rerun of a")
if again[0].machine != "n2" {
t.Fatalf("the rerun composes %s, want only the machine a did not pass", again[0].machine)
}
answer(again[0], composes)
moved := ends(2, "the rerun")
if a2, bb := moved["step-a2"], moved["step-b"]; a2.Outcome != meshwants.StepEndedOutcomePassed || bb.Outcome != meshwants.StepEndedOutcomePassed ||
!bb.Rerun || bb.By != "op@n1" || len(bb.Shared) != 2 || bb.Shared[1].Ask != again[0].ask.ID {
t.Fatalf("after the rerun (asked again %s): a2 %+v; b %+v", again[0].ask.ID, moved["step-a2"].Shared, moved["step-b"])
}
// A superseded step leaves the runs; its other reader goes on.
step("step-r3a", "a", "r3", false)
step("step-r3b", "b", "r3", false)
sup := asks(2)
readers(runKeyOf("run-r3", "n1"), 2)
readers(runKeyOf("run-r3", "n2"), 2)
pe, _ := json.Marshal(mpr.PipelineEnded{V: 1, Pipeline: "run-r3.a", Branch: trunkBranch, Source: 1, Outcome: mpr.PipelineEndedOutcomeSuperseded, Run: "r3", Movers: []mpr.MoverEnded{{Module: "a", Steps: []mpr.StepResult{}}}})
if _, err := b.js.Publish(b.ctx, "mesh.seat."+mpr.Seat+".event."+mpr.EventPipelineEnded+".n1", pe); err != nil {
t.Fatal(err)
}
for _, a := range sup {
answer(a, composes)
}
if got := ends(1, "the superseded run"); got["step-r3b"].Outcome != meshwants.StepEndedOutcomePassed {
t.Fatalf("the other reader: %+v", got)
}
select {
case e := <-ended:
t.Fatalf("a superseded step said its end: %+v", e)
case <-time.After(200 * time.Millisecond):
}
// Restarted during a run: the new assigner takes it up by its ask.
step("step-r4", "c", "r4", false)
restart := asks(2)
stop()
for _, a := range restart {
answer(a, composes)
}
from = b.journal.mark()
b.startStoppable(t)
b.journal.await(t, from, "is taken up again by its runs (ask step-r4)", "the take-up", 30*time.Second)
if e := ends(1, "the take-up")["step-r4"]; e.Outcome != meshwants.StepEndedOutcomePassed || len(e.Shared) != 2 {
t.Fatalf("the step taken up: %+v", e)
}
// compositions-drop: the readers ended naming the drop, the key deleted.
step("step-r5", "a", "r5", false)
asks(2)
body, _ := json.Marshal(meshwants.CompositionsDropInput{Candidate: "run-r5", Machine: "n1", Why: "stuck"})
reply, err := nc.Request("mesh.seat.mesh-wants.call.compositions-drop.n1~mesh-delivery-pipeline", body, 10*time.Second)
if err != nil || !strings.Contains(string(reply.Data), `"ended":[`) {
t.Fatalf("compositions-drop answered %s %v", reply.Data, err)
}
if e := ends(1, "the drop")["step-r5"]; e.Outcome != meshwants.StepEndedOutcomeCouldNotRun || !strings.Contains(e.Said, "dropped by hand: stuck") {
t.Fatalf("a reader of the dropped run: %+v", e)
}
if keys := runKeys("run-r5"); len(keys) != 1 {
t.Errorf("the keys of run-r5 after the drop: %v, want n2's alone", keys)
}
// At the cap of 1 MiB no run starts: the step ends could not run, naming the fill.
for i := range 2 {
if _, err := b.buckets[buckets.CompositionRuns()].Put(b.ctx, fmt.Sprintf("fill%d", i), make([]byte, 700<<10)); err != nil {
t.Fatal(err)
}
}
step("step-r6", "a", "r6", false)
if e := ends(1, "the cap")["step-r6"]; e.Outcome != meshwants.StepEndedOutcomeCouldNotRun || !strings.Contains(e.Said, "is at its cap of 1 MiB") {
t.Fatalf("at the cap: %+v", e)
}
}
@@ -0,0 +1,642 @@
package main
import (
"context"
"encoding/json"
"fmt"
"maps"
"os"
"path/filepath"
"slices"
"strings"
"sync"
"testing"
"time"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/nodebuildgo"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
)
// runsMem is the state composition-runs in memory, its bound keys' times to live kept beside.
type runsMem struct {
mu sync.Mutex
vals map[string][]byte
revs map[string]uint64
ttl map[string]time.Duration
bytes int64
n uint64
// beforeDel, when set, runs once before the next delete: another write landing between a read and the delete.
beforeDel func()
// beforeArm, when set, runs once before the next arm: another write landing between a read and the arm.
beforeArm func()
}
func (k *runsMem) another() {
k.mu.Lock()
f := k.beforeDel
k.beforeDel = nil
k.mu.Unlock()
if f != nil {
f()
}
}
func newRunsMem() *runsMem {
return &runsMem{vals: map[string][]byte{}, revs: map[string]uint64{}, ttl: map[string]time.Duration{}}
}
func (k *runsMem) get(key string) ([]byte, uint64, error) {
k.mu.Lock()
defer k.mu.Unlock()
return k.vals[key], k.revs[key], nil
}
func (k *runsMem) create(key string, v []byte) (uint64, error) {
k.mu.Lock()
defer k.mu.Unlock()
if _, ok := k.vals[key]; ok {
return 0, errRunChanged
}
k.n++
k.vals[key], k.revs[key] = v, k.n
return k.n, nil
}
func (k *runsMem) update(key string, v []byte, rev uint64) (uint64, error) {
k.mu.Lock()
defer k.mu.Unlock()
if k.revs[key] != rev {
return 0, errRunChanged
}
k.n++
k.vals[key], k.revs[key] = v, k.n
return k.n, nil
}
func (k *runsMem) delAt(key string, rev uint64) error {
k.another()
k.mu.Lock()
defer k.mu.Unlock()
if _, ok := k.vals[key]; !ok {
return nil
}
if k.revs[key] != rev {
return errRunChanged
}
delete(k.vals, key)
delete(k.revs, key)
delete(k.ttl, key)
return nil
}
func (k *runsMem) keys() ([]string, error) {
k.mu.Lock()
defer k.mu.Unlock()
var out []string
for key := range k.vals {
out = append(out, key)
}
slices.Sort(out)
return out, nil
}
func (k *runsMem) arm(key, ask string, ttl time.Duration) (uint64, error) {
k.mu.Lock()
f := k.beforeArm
k.beforeArm = nil
k.mu.Unlock()
if f != nil {
f()
}
raw, _ := json.Marshal(boundValue{Bound: key, Ask: ask})
k.mu.Lock()
defer k.mu.Unlock()
k.n++
k.vals[key], k.revs[key], k.ttl[key] = raw, k.n, ttl
return k.n, nil
}
// expire ends a bound key's time to live: the key gone, as the bus's marker leaves it.
func (k *runsMem) expire(key string) {
k.mu.Lock()
defer k.mu.Unlock()
delete(k.vals, key)
delete(k.revs, key)
delete(k.ttl, key)
}
func (k *runsMem) used() (int64, error) {
k.mu.Lock()
defer k.mu.Unlock()
if k.bytes > 0 {
return k.bytes, nil
}
var n int64
for _, v := range k.vals {
n += int64(len(v))
}
return n, nil
}
// Design 47 G §718, §719, §720, A-468, A-469d, A-469x: a run's key is `<candidate key>.<machine>`, each part escaped; two
// steps of one candidate joining at once start one run and the second reads it; a run that could not run is replaced; at the
// cap no run starts, naming the fill; a run is deleted composition-runs-kept after its end; the settings are read from their files.
func TestACompositionRunIsOneKeyPerCandidateAndMachine(t *testing.T) {
now := time.Date(2026, 11, 17, 12, 0, 0, 0, time.UTC)
step := func(id, module string) meshwants.CompositionReader {
return readerOf(id, meshwants.StepRun{Pipeline: "main.3." + module, Step: meshwants.StepRunStepComposition, Module: module, Branch: "main", Revision: 3})
}
t.Run("key", func(t *testing.T) {
if k := runKeyOf("main.3", "n1"); k != "main=2e3.n1" {
t.Errorf("the key is %q, want each part escaped as a key's name", k)
}
if isRunKey(runBoundPrefix+"main=2e3.n1") || isRunKey(runUntakenPrefix+"main=2e3.n1") || !isRunKey("main=2e3.n1") {
t.Error("a bound key is taken for a run's or a run's for a bound key")
}
})
t.Run("one run for two steps at once", func(t *testing.T) {
kv := newRunsMem()
r := newCompositionRuns(kv, defaultRunSettings, func() time.Time { return now }, t.Logf)
var wg sync.WaitGroup
got := make([]joined, 2)
for i, m := range []string{"a", "b"} {
wg.Add(1)
go func() {
defer wg.Done()
j, err := r.join(step("ask-"+m, m), "main.3", "n1", "run-"+m)
if err != nil {
t.Error(err)
}
got[i] = j
}()
}
wg.Wait()
runKeys := func() []string {
all, _ := kv.keys()
return slices.DeleteFunc(all, func(k string) bool { return !isRunKey(k) })
}
if got[0].started == got[1].started {
t.Fatalf("started %v and %v: want exactly one step to start the run", got[0].started, got[1].started)
}
keys := runKeys()
run, _, _, _ := r.read(runKeyOf("main.3", "n1"))
if len(keys) != 1 || len(run.Readers) != 2 || run.Candidate != "main.3" || run.Machine != "n1" || run.Started == nil {
t.Errorf("keys %v, run %+v: want one key read by both", keys, run)
}
if j, _ := r.join(step("ask-a", "a"), "main.3", "n1", "run-c"); j.started || len(j.run.Readers) != 2 {
t.Errorf("a reader joining again is added again or starts a run: %+v", j)
}
})
t.Run("could not run is never read", func(t *testing.T) {
kv := newRunsMem()
r := newCompositionRuns(kv, defaultRunSettings, func() time.Time { return now }, t.Logf)
if _, err := r.join(step("ask-a", "a"), "main.3", "n1", "run-1"); err != nil {
t.Fatal(err)
}
key := runKeyOf("main.3", "n1")
_, _, _ = r.change(key, func(c *meshwants.CompositionRun) bool {
c.Ended, c.Outcome = &now, meshwants.CompositionRunOutcomeCouldNotRun
return true
})
j, err := r.join(step("ask-b", "b"), "main.3", "n1", "run-2")
if err != nil || !j.started || j.run.Ask != "run-2" || len(j.run.Readers) != 1 || j.run.Ended != nil {
t.Errorf("after a could not run: %+v %v, want a new run read by its starter alone", j, err)
}
_, _, _ = r.change(key, func(c *meshwants.CompositionRun) bool {
c.Ended, c.Outcome = &now, meshwants.CompositionRunOutcomePassed
return true
})
if j, _ := r.join(step("ask-c", "c"), "main.3", "n1", "run-3"); j.started || j.run.Ask != "run-2" {
t.Errorf("a passed run is not read: %+v", j)
}
if j, _ := r.join(step("ask-d", "d"), "main.4", "n1", "run-4"); !j.started {
t.Errorf("a step of another candidate reads the first's run: %+v", j)
}
})
t.Run("cap", func(t *testing.T) {
kv := newRunsMem()
kv.bytes = 16 << 20
r := newCompositionRuns(kv, defaultRunSettings, func() time.Time { return now }, t.Logf)
_, err := r.join(step("ask-a", "a"), "main.3", "n1", "run-1")
if err == nil || !strings.Contains(err.Error(), "at its cap of 16 MiB (16777216 bytes kept)") {
t.Errorf("at the cap: %v, want the fill named", err)
}
})
t.Run("kept", func(t *testing.T) {
kv := newRunsMem()
at := now
r := newCompositionRuns(kv, defaultRunSettings, func() time.Time { return at }, t.Logf)
for _, c := range []string{"main.1", "main.2"} {
if _, err := r.join(step("ask-"+c, "a"), c, "n1", "run-"+c); err != nil {
t.Fatal(err)
}
}
old := now.Add(-25 * time.Hour)
_, _, _ = r.change(runKeyOf("main.1", "n1"), func(c *meshwants.CompositionRun) bool { c.Ended, c.Outcome = &old, "passed"; return true })
_, _ = kv.arm(runBoundPrefix+runKeyOf("main.1", "n1"), "run-main.1", time.Minute)
recent := now.Add(-time.Hour)
_, _, _ = r.change(runKeyOf("main.2", "n1"), func(c *meshwants.CompositionRun) bool { c.Ended, c.Outcome = &recent, "passed"; return true })
if _, err := r.join(step("ask-x", "a"), "main.9", "n1", "run-9"); err != nil {
t.Fatal(err)
}
keys, _ := kv.keys()
for _, k := range []string{runBoundPrefix, runUntakenPrefix} {
if v, _, _ := kv.get(k + runKeyOf("main.1", "n1")); v != nil {
t.Errorf("the key %s stays past its run", k+runKeyOf("main.1", "n1"))
}
}
keys = slices.DeleteFunc(keys, func(k string) bool { return !isRunKey(k) })
if want := []string{runKeyOf("main.2", "n1"), runKeyOf("main.9", "n1")}; !slices.Equal(keys, want) {
t.Errorf("keys %v, want %v: a run ended more than a day ago goes with its bound key at the next run", keys, want)
}
})
t.Run("a listing that misses a key being written", func(t *testing.T) {
kv := &missingRuns{runsMem: newRunsMem()}
r := newCompositionRuns(kv, defaultRunSettings, func() time.Time { return now }, t.Logf)
if _, err := r.join(step("ask-a", "a"), "main.3", "n1", "run-1"); err != nil {
t.Fatal(err)
}
kv.hide = runKeyOf("main.3", "n1")
if key, _, _ := r.keyOfAsk("run-1"); key != "" {
t.Fatalf("the stand's listing does not hide the key")
}
r.saw(kv.hide, true) // as the state's watch hands it
if key, _, _ := r.keyOfAsk("run-1"); key != kv.hide {
t.Errorf("the run of ask run-1 is not found by the keys the watch handed: %q", key)
}
r.saw(kv.hide, false)
if keys, _ := r.keys(); slices.Contains(keys, kv.hide) {
t.Errorf("a key the watch saw deleted is still listed: %v", keys)
}
})
// No delete lands on a value newer than the one it was judged from (the kind test 109 met in test-runs): a rerun's run
// replacing the key, and its untaken bound, stand.
for _, c := range []struct {
name string
ended time.Time
act func(r *compositionRuns, key string) error
}{
{"the sweep of a run replaced meanwhile", now.Add(-25 * time.Hour), func(r *compositionRuns, _ string) error { return r.sweep() }},
{"the end of a run replaced meanwhile", time.Time{}, func(r *compositionRuns, key string) error {
_, err := r.endRun(key, "run-1", meshwants.CompositionRunOutcomePassed, "", nil)
return err
}},
} {
t.Run(c.name, func(t *testing.T) {
kv := newRunsMem()
r := newCompositionRuns(kv, defaultRunSettings, func() time.Time { return now }, t.Logf)
if _, err := r.join(step("ask-a", "a"), "main.3", "n1", "run-1"); err != nil {
t.Fatal(err)
}
key := runKeyOf("main.3", "n1")
if !c.ended.IsZero() {
_, _, _ = r.change(key, func(run *meshwants.CompositionRun) bool { run.Ended, run.Outcome = &c.ended, "failed"; return true })
}
_, _ = kv.arm(runBoundPrefix+key, "run-1", time.Minute)
kv.beforeDel = func() { // a rerun replaces the key and arms its untaken bound
for {
raw, rev, _ := kv.get(key)
var run meshwants.CompositionRun
_ = json.Unmarshal(raw, &run)
if run.Ended == nil {
at := now
run.Ended, run.Outcome = &at, "failed"
}
fresh, _ := json.Marshal(meshwants.CompositionRun{Candidate: "main.3", Machine: "n1", Ask: "run-2", Started: &now, Readers: run.Readers})
if _, err := kv.update(key, fresh, rev); err == nil {
break
}
}
_, _ = kv.arm(runUntakenPrefix+key, "run-2", time.Hour)
}
if err := c.act(r, key); err != nil {
t.Fatal(err)
}
if run, _, ok, _ := r.read(key); !ok || run.Ask != "run-2" || run.Ended != nil {
t.Errorf("the key holds %+v (stands %v), want the rerun's running run-2", run, ok)
}
if v, _, _ := kv.get(runUntakenPrefix + key); v == nil {
t.Error("the untaken bound the rerun's run armed is deleted")
}
})
}
t.Run("settings", func(t *testing.T) {
dir := t.TempDir()
files := map[string]string{"MESH_ASSIGNER_COMPOSITION_RUNS_CAP_MIB_FILE": "8", "MESH_ASSIGNER_COMPOSITION_RUNS_KEPT_FILE": "2h",
"MESH_ASSIGNER_COMPOSITION_STEP_BOUND_FILE": "2s", "MESH_ASSIGNER_RUN_UNTAKEN_BOUND_FILE": "", "MESH_ASSIGNER_BLAME_TRIES_FILE": "5"}
env := map[string]string{}
for name, content := range files {
p := filepath.Join(dir, name)
if err := os.WriteFile(p, []byte(content), 0o600); err != nil {
t.Fatal(err)
}
env[name] = p
}
s, err := runSettingsOf(func(k string) string { return env[k] })
if err != nil || s.capBytes != 8<<20 || s.kept != 2*time.Hour || s.stepBound != 2*time.Second || s.untaken != 24*time.Hour || s.blameTries != 5 {
t.Errorf("settings %+v %v", s, err)
}
_ = os.WriteFile(env["MESH_ASSIGNER_COMPOSITION_STEP_BOUND_FILE"], []byte("30"), 0o600)
if _, err := runSettingsOf(func(k string) string { return env[k] }); err == nil || !strings.Contains(err.Error(), "not a positive Go duration") {
t.Errorf("a bound of no unit: %v", err)
}
if s, err := runSettingsOf(func(string) string { return "" }); err != nil || s != defaultRunSettings {
t.Errorf("no files: %+v %v, want the defaults", s, err)
}
})
raw, _ := json.Marshal(step("x", "a"))
if !strings.Contains(string(raw), `"id":"x"`) {
t.Errorf("a reader names no ask id: %s", raw)
}
}
// Design 47 G §720, A-466s, A-468b, A-469y, A-470: a run's untaken bound is armed at its start and each reader said waiting for a
// build node; ask-taken arms the bound of composition-step-bound and ends the waits ran; each step-progress arms it again; the
// bound's expiry drops the ask and ends the run could not run naming the ask and the bound, a step-ended heard later ignored and
// journaled; the untaken bound's expiry ends it naming run-untaken-bound, the waits superseded; the readers of a run with no end
// are taken up at the start.
func TestACompositionRunsBoundTimesOwedProgress(t *testing.T) {
now := time.Date(2026, 11, 17, 12, 0, 0, 0, time.UTC)
reader := func(id string) meshwants.CompositionReader {
return readerOf(id, meshwants.StepRun{Pipeline: "main.3." + id, Step: meshwants.StepRunStepComposition, Module: id, Branch: "main", Revision: 3})
}
type said struct{ event, how, module string }
setup := func(t *testing.T) (*runsMem, *compositionRuns, *[]said, *[]string, *[]string) {
kv := newRunsMem()
var saids []said
var drops, journal []string
var mu sync.Mutex
r := newCompositionRuns(kv, defaultRunSettings, func() time.Time { return now }, func(f string, a ...any) {
mu.Lock()
journal = append(journal, fmt.Sprintf(f, a...))
mu.Unlock()
})
r.say = func(event string, body any, _ string) error {
w := body.(meshwants.Wait)
if w.On != waitOnBuildNode || w.Step != "pipeline" || w.Owner != meshwants.Seat || w.Node == "" {
t.Errorf("the wait said %+v", w)
}
saids = append(saids, said{event, w.How, w.Module})
return nil
}
r.drop = func(ask, why string) error { drops = append(drops, ask+": "+why); return nil }
return kv, r, &saids, &drops, &journal
}
key := runKeyOf("main.3", "n1")
t.Run("taken, progress, bound", func(t *testing.T) {
kv, r, saids, drops, journal := setup(t)
if _, err := r.join(reader("a"), "main.3", "n1", "run-1"); err != nil {
t.Fatal(err)
}
if _, err := r.join(reader("b"), "main.3", "n1", "run-2"); err != nil {
t.Fatal(err)
}
if kv.ttl[runUntakenPrefix+key] != 24*time.Hour || !slices.Equal(*saids, []said{{meshwants.EventWaitHeld, "", "a"}, {meshwants.EventWaitHeld, "", "b"}}) {
t.Fatalf("at the start: untaken %v, said %v", kv.ttl, *saids)
}
if err := r.heardAskTaken(nodebuildgo.AskTaken{Ask: "run-1", Asker: "someone-else"}); err != nil || kv.ttl[runBoundPrefix+key] != 0 {
t.Fatalf("another asker's ask-taken arms a bound: %v %v", kv.ttl, err)
}
if err := r.heardAskTaken(nodebuildgo.AskTaken{Ask: "run-1", Asker: runAsker, Node: "b1"}); err != nil {
t.Fatal(err)
}
_, untaken, _ := kv.get(runUntakenPrefix + key)
if kv.ttl[runBoundPrefix+key] != 30*time.Minute || untaken != 0 || len(*saids) != 4 || (*saids)[2].how != "ran" || (*saids)[3].how != "ran" {
t.Fatalf("at ask-taken: %v, said %v", kv.ttl, *saids)
}
before := kv.revs[runBoundPrefix+key]
if err := r.heardProgress(nodebuildgo.StepProgress{Ask: "run-1", Asker: runAsker}); err != nil || kv.revs[runBoundPrefix+key] == before {
t.Fatalf("a step-progress does not arm the bound again: %v", err)
}
kv.expire(runBoundPrefix + key)
r.expired(runBoundPrefix + key)
run, _, _, _ := r.read(key)
if run.Outcome != meshwants.CompositionRunOutcomeCouldNotRun || run.Said != "n1: its run ask run-1 said no progress within 30m0s (composition-step-bound)" ||
len(*drops) != 1 || !strings.HasPrefix((*drops)[0], "run-1: ") {
t.Fatalf("past the bound: %+v, drops %v", run, *drops)
}
if got := judgeRun("a", run); got.couldNot != run.Said {
t.Errorf("a reader of the run past its bound: %+v", got)
}
late := buildstep.StepEnded{Ask: "run-1", Asker: runAsker, Outcome: buildstep.OutcomePassed, Output: "{}"}
if err := r.heardEnd(late, func(e buildstep.StepEnded) ([]byte, error) { return []byte(e.Output), nil }); err != nil {
t.Fatal(err)
}
if again, _, _, _ := r.read(key); again.Said != run.Said || !slices.ContainsFunc(*journal, func(l string) bool {
return strings.Contains(l, "step-ended of the run ask run-1 is ignored") && strings.Contains(l, key)
}) {
t.Errorf("a step-ended after the bound: %+v, journal %v", again, *journal)
}
if keys, _ := kv.keys(); !slices.Equal(keys, []string{key}) {
t.Errorf("the bound keys stay past the run's end: %v", keys)
}
})
t.Run("untaken", func(t *testing.T) {
kv, r, saids, drops, _ := setup(t)
if _, err := r.join(reader("a"), "main.3", "n1", "run-1"); err != nil {
t.Fatal(err)
}
kv.expire(runUntakenPrefix + key)
r.expired(runUntakenPrefix + key)
run, _, _, _ := r.read(key)
if run.Outcome != meshwants.CompositionRunOutcomeCouldNotRun || run.Said != "n1: its run ask run-1 was taken by no build node within 24h0m0s (run-untaken-bound)" ||
len(*drops) != 1 || !slices.Equal(*saids, []said{{meshwants.EventWaitHeld, "", "a"}, {meshwants.EventWaitEnded, "superseded", "a"}}) {
t.Errorf("untaken past its bound: %+v, drops %v, said %v", run, *drops, *saids)
}
r.expired(runUntakenPrefix + key) // a run ended takes nothing
if len(*drops) != 1 {
t.Errorf("an ended run is dropped again: %v", *drops)
}
})
// A-470n, A-470o: a bound holds its run's ask, armed for it alone; a late signal of a run replaced moves nothing and is
// journaled; an expiry ends the run only while its bound is still absent and the run taken (bound.) or untaken (untaken.).
rerun := func(kv *runsMem, r *compositionRuns) func() { // a rerun replaces run-1 by run-2, its bounds gone, run-2's untaken armed
return func() {
_, _, _ = r.change(key, func(c *meshwants.CompositionRun) bool { c.Ask = "run-2"; return true })
kv.expire(runBoundPrefix + key)
_, _ = kv.arm(runUntakenPrefix+key, "run-2", time.Hour)
}
}
taken := func(t *testing.T, r *compositionRuns) {
if err := r.heardAskTaken(nodebuildgo.AskTaken{Ask: "run-1", Asker: runAsker, Node: "b1"}); err != nil {
t.Fatal(err)
}
}
for _, c := range []struct {
name string
act func(t *testing.T, kv *runsMem, r *compositionRuns)
ended bool
bound string // the ask the bound key holds, "" for none
untaken string
journal string
}{
{"a late ask-taken of a run replaced as it is heard", func(t *testing.T, kv *runsMem, r *compositionRuns) {
kv.beforeArm = rerun(kv, r)
taken(t, r)
}, false, "", "run-2", "the ask-taken of the run ask run-1 is late"},
{"a late step-progress of a run replaced as it is heard", func(t *testing.T, kv *runsMem, r *compositionRuns) {
taken(t, r)
kv.beforeArm = rerun(kv, r)
if err := r.heardProgress(nodebuildgo.StepProgress{Ask: "run-1", Asker: runAsker}); err != nil {
t.Fatal(err)
}
kv.expire(runBoundPrefix + key) // a bound left standing would end run-2 here
r.expired(runBoundPrefix + key)
}, false, "", "run-2", "the step-progress of the run ask run-1 is late"},
{"a step-progress of a run gone", func(t *testing.T, kv *runsMem, r *compositionRuns) {
taken(t, r)
rerun(kv, r)()
if err := r.heardProgress(nodebuildgo.StepProgress{Ask: "run-1", Asker: runAsker}); err != nil {
t.Fatal(err)
}
}, false, "", "run-2", "the step-progress of the run ask run-1 is late"},
{"an expiry heard after the bound was armed again", func(t *testing.T, kv *runsMem, r *compositionRuns) {
taken(t, r)
r.expired(runBoundPrefix + key)
}, false, "run-1", "", "the expiry of " + runBoundPrefix + key + " ends nothing"},
{"the bound's expiry of a run not taken", func(t *testing.T, kv *runsMem, r *compositionRuns) {
_, _ = kv.arm(runBoundPrefix+key, "run-1", time.Minute)
kv.expire(runBoundPrefix + key)
r.expired(runBoundPrefix + key)
}, false, "", "run-1", "the expiry of " + runBoundPrefix + key + " ends nothing"},
{"the untaken expiry of a run taken", func(t *testing.T, kv *runsMem, r *compositionRuns) {
_, _ = kv.arm(runBoundPrefix+key, "run-1", time.Minute)
kv.expire(runUntakenPrefix + key)
r.expired(runUntakenPrefix + key)
}, false, "run-1", "", "the expiry of " + runUntakenPrefix + key + " ends nothing"},
{"an end of another ask", func(t *testing.T, kv *runsMem, r *compositionRuns) {
if ended, err := r.end(key, "run-0", meshwants.CompositionRunOutcomePassed, "", nil); ended || err != nil {
t.Errorf("the end of run-0 ended the run of run-1: %v %v", ended, err)
}
}, false, "", "run-1", ""},
{"the ask-taken of the run's own ask", func(t *testing.T, kv *runsMem, r *compositionRuns) {
taken(t, r)
}, false, "run-1", "", ""},
} {
t.Run(c.name, func(t *testing.T) {
kv, r, _, _, journal := setup(t)
if _, err := r.join(reader("a"), "main.3", "n1", "run-1"); err != nil {
t.Fatal(err)
}
c.act(t, kv, r)
run, _, _, _ := r.read(key)
if (run.Ended != nil) != c.ended {
t.Errorf("the run ended %v (%s), want %v", run.Ended != nil, run.Said, c.ended)
}
for prefix, want := range map[string]string{runBoundPrefix: c.bound, runUntakenPrefix: c.untaken} {
if held, _, _, _ := r.boundOf(prefix + key); held != want {
t.Errorf("%s holds the ask %q, want %q", prefix+key, held, want)
}
}
if c.journal != "" && !slices.ContainsFunc(*journal, func(l string) bool { return strings.Contains(l, c.journal) }) {
t.Errorf("the journal %v does not say %q", *journal, c.journal)
}
})
}
// A-469y, A-470u: a step asked again that joins a running run not yet taken, beside a reader or in its pipeline's former
// reader's place, says its own wait held, as join does; the former reader's wait, and that of a reader leaving, ends at once
// superseded.
held := func(m string) said { return said{meshwants.EventWaitHeld, "", m} }
gone := func(m string) said { return said{meshwants.EventWaitEnded, "superseded", m} }
for _, c := range []struct {
name string
act func(t *testing.T, r *compositionRuns)
want []said
}{
{"a rerun joins", func(t *testing.T, r *compositionRuns) {
again := reader("b")
again.Rerun = true
if _, err := r.rejoin(again, "main.3", "n1", "run-2"); err != nil {
t.Fatal(err)
}
}, []said{held("a"), held("b")}},
{"a rerun takes its former place", func(t *testing.T, r *compositionRuns) {
again := reader("a2")
again.Pipeline, again.Module, again.Rerun = "main.3.a", "a2", true
if _, err := r.rejoin(again, "main.3", "n1", "run-2"); err != nil {
t.Fatal(err)
}
}, []said{held("a"), gone("a"), held("a2")}},
{"a reader leaves", func(t *testing.T, r *compositionRuns) {
if _, err := r.join(reader("b"), "main.3", "n1", "run-2"); err != nil {
t.Fatal(err)
}
if _, err := r.leave("main.3.a", nil); err != nil {
t.Fatal(err)
}
}, []said{held("a"), held("b"), gone("a")}},
} {
t.Run(c.name, func(t *testing.T) {
_, r, saids, _, _ := setup(t)
if _, err := r.join(reader("a"), "main.3", "n1", "run-1"); err != nil {
t.Fatal(err)
}
c.act(t, r)
if !slices.Equal(*saids, c.want) {
t.Errorf("said %v, want %v", *saids, c.want)
}
})
}
t.Run("taken up at the start", func(t *testing.T) {
_, r, _, _, _ := setup(t)
for _, c := range []struct{ id, machine string }{{"a", "n1"}, {"a", "n2"}, {"b", "n1"}} {
if _, err := r.join(reader(c.id), "main.3", c.machine, "run-"+c.machine); err != nil {
t.Fatal(err)
}
}
ended := now
_, _, _ = r.change(runKeyOf("main.3", "n2"), func(c *meshwants.CompositionRun) bool { c.Ended, c.Outcome = &ended, "passed"; return true })
// A rerun's run carrying readers whose steps said their end (A-470l, A-470m): c passed and is not taken up, d is marked rerun.
_, _, _ = r.change(runKeyOf("main.3", "n1"), func(run *meshwants.CompositionRun) bool {
for _, id := range []string{"c", "d"} {
c := reader(id)
c.Ended, c.Rerun = &ended, id == "d"
run.Readers = append(run.Readers, c)
}
return true
})
readers, err := r.readersOfOpen()
if err != nil || len(readers) != 3 || readers[0].ID != "a" || readers[1].ID != "b" || readers[2].ID != "d" {
t.Fatalf("the readers taken up: %+v %v", readers, err)
}
if keys, _ := r.keysOf("main.3", "a"); !slices.Equal(keys, []string{runKeyOf("main.3", "n1"), runKeyOf("main.3", "n2")}) {
t.Errorf("the runs of reader a: %v", keys)
}
// A-470q: a reader with no `ended` says its first end under its ask's id; d, marked rerun, says its end again under
// `<id>.<the open run's ask>`.
ids := make(chan [2]string, 3)
steps := &compositionSteps{node: "n1", now: func() time.Time { return now }, logf: t.Logf,
resume: func(context.Context, string, meshwants.StepRun) stepOutcome {
return stepOutcome{Outcome: meshwants.StepEndedOutcomePassed}
},
say: func(_ string, body any, id string) error {
ids <- [2]string{body.(meshwants.StepEnded).ID, id}
return nil
}}
steps.takeUp(context.Background(), r)
got := map[string]string{}
for range 3 {
select {
case e := <-ids:
got[e[0]] = e[1]
case <-time.After(5 * time.Second):
t.Fatalf("the ends of the take-up: %v", got)
}
}
if want := map[string]string{"a": "a", "b": "b", "d": "d.run-n1"}; !maps.Equal(got, want) {
t.Errorf("the message ids of the take-up's ends: %v, want %v", got, want)
}
})
}
// missingRuns is runsMem whose listing misses one key, as a bucket's listing misses a key being written at that moment.
type missingRuns struct {
*runsMem
hide string
}
func (k *missingRuns) keys() ([]string, error) {
all, err := k.runsMem.keys()
return slices.DeleteFunc(all, func(key string) bool { return key == k.hide }), err
}
@@ -0,0 +1,162 @@
package main
import (
"encoding/json"
"errors"
"fmt"
"slices"
"strings"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/process"
)
// The composition runs' read and drop (design 47 G §728; A-469f, A-469u, A-469v): the seat mesh-wants' verbs `compositions`
// (class read) and `compositions-drop` (class act, §391's default callers), answered by the assigner's process, which keeps the
// runs and says the readers' ends; the module's tools `assigner_compositions` and `assigner_compositions_drop` call them.
// The tools that call the two verbs.
const (
compositionsTool = "assigner_compositions"
compositionsDropTool = "assigner_compositions_drop"
)
// compositions answers each composition run the state keeps, under §719's field names plus its key, with the candidate and the
// machine named only those, and the state's fill against its cap.
func (r *compositionRuns) compositions(in meshwants.CompositionsInput) (meshwants.CompositionsAnswer, error) {
all, err := r.keys()
if err != nil {
return meshwants.CompositionsAnswer{}, fmt.Errorf("the state %s is not listed: %w", "composition-runs", err)
}
slices.Sort(all)
out := meshwants.CompositionsAnswer{Runs: []meshwants.CompositionRun{}}
for _, key := range all {
if !isRunKey(key) {
continue
}
run, _, ok, err := r.read(key)
if err != nil || !ok || (in.Candidate != "" && run.Candidate != in.Candidate) || (in.Machine != "" && run.Machine != in.Machine) {
continue
}
run.Key = key
out.Runs = append(out.Runs, run)
}
out.Fill, err = r.fill()
return out, err
}
// drop drops one composition run by hand (§728): the act and why written in the hand-act log first (record), then a running run's
// ask dropped, each of its readers' waits stopped and, for each reader whose end is owed (no `ended`, or marked rerun), its end
// said could not run naming the drop, once (A-470r), and the key deleted with its bound keys. It answers the entry deleted and
// the readers it ended.
func (c *compositionSteps) drop(r *compositionRuns, record func(meshhandactsclient.Request) error, caller string, in meshwants.CompositionsDropInput) (meshwants.CompositionsDropAnswer, error) {
why := strings.TrimSpace(in.Why)
if in.Candidate == "" || in.Machine == "" || why == "" {
return meshwants.CompositionsDropAnswer{}, errors.New("name the candidate, the machine and why the composition run is dropped")
}
key := runKeyOf(in.Candidate, in.Machine)
run, _, ok, err := r.read(key)
if err != nil {
return meshwants.CompositionsDropAnswer{}, err
}
if !ok {
return meshwants.CompositionsDropAnswer{}, fmt.Errorf("no composition run of %s on %s is kept", in.Candidate, in.Machine)
}
if err := record(meshhandactsclient.Request{What: meshwants.VerbCompositionsDrop + " " + key, Why: why + " (" + caller + ")", Cause: "compositions-drop"}); err != nil {
return meshwants.CompositionsDropAnswer{}, fmt.Errorf("the hand act was not recorded, so nothing was dropped: %w", err)
}
said := fmt.Sprintf("%s: the composition run %s was dropped by hand: %s", in.Machine, key, why)
answer := meshwants.CompositionsDropAnswer{Run: run}
answer.Run.Key = key
if run.Ended == nil {
if r.drop != nil {
if err := r.drop(run.Ask, said); err != nil {
r.logf("the drop of the run ask %s of the composition run %s is not answered: %v", run.Ask, key, err)
}
}
ids := make([]string, 0, len(run.Readers))
for _, reader := range run.Readers {
ids = append(ids, reader.ID)
}
c.leave(ids) // their waits say no end of their own
// The run ends without moving its readers: the drop says each owed end itself, once (A-470r).
if _, err := r.endRunMoving(key, run.Ask, meshwants.CompositionRunOutcomeCouldNotRun, said, nil, r.untaken(key, run.Ask), false); err != nil {
return answer, err
}
shared := []meshwants.Shared{{Machine: run.Machine, Run: key, Ask: run.Ask}}
for _, reader := range run.Readers {
if reader.Ended != nil && !reader.Rerun {
continue // it ended passed already and keeps its verdict (A-470r)
}
again := "" // a reader whose step said its end already says it again under the dropped run's ask (A-470q)
if reader.Ended != nil {
again = run.Ask
}
c.sayEnd(reader.ID, stepRunOf(reader), nil, stepOutcome{Outcome: meshwants.StepEndedOutcomeCouldNotRun, Said: said, Shared: shared}, again)
answer.Ended = append(answer.Ended, reader)
}
}
// The dropped run's key goes while it holds that run: a run started on it since stands.
err = r.deleteRun(key, func(c meshwants.CompositionRun) bool { return c.Ask == run.Ask })
r.heard()
return answer, err
}
// compositionVerbs are the process's handlers of the seat mesh-wants' verbs compositions and compositions-drop.
func compositionVerbs(r *compositionRuns, c *compositionSteps, record func(meshhandactsclient.Request) error) map[string]process.SeatHandler {
return map[string]process.SeatHandler{
meshwants.VerbCompositions: func(_ string, raw json.RawMessage) (any, error) {
var in meshwants.CompositionsInput
if len(raw) > 0 {
if err := json.Unmarshal(raw, &in); err != nil {
return nil, fmt.Errorf("the arguments are not JSON: %w", err)
}
}
return r.compositions(in)
},
meshwants.VerbCompositionsDrop: func(caller string, raw json.RawMessage) (any, error) {
var in meshwants.CompositionsDropInput
if err := json.Unmarshal(raw, &in); err != nil {
return nil, fmt.Errorf("the arguments are not JSON: %w", err)
}
return c.drop(r, record, caller, in)
},
}
}
// compositionsTools are the module's tools of §728's names, each calling its verb (A-469f).
func compositionsTools(ask func(string, any) (json.RawMessage, error)) []stdio.Tool {
call := func(verb string, args map[string]any, names ...string) (any, error) {
in := map[string]any{}
for _, n := range names {
if v := arg(args, n); v != "" {
in[n] = v
}
}
raw, err := ask("seat:"+meshwants.Seat+"."+verb, in)
if err != nil {
return nil, err
}
var out any
if err := json.Unmarshal(raw, &out); err != nil {
return nil, fmt.Errorf("%s answered what is not JSON: %w", verb, err)
}
return out, nil
}
return []stdio.Tool{
{Name: compositionsTool, Description: "The composition runs the assigner keeps, one per candidate and machine (design 47 G §719, §728): each with " +
"its program, input digest, ask, readers, outcome and verdict, and the state's fill against its cap; with candidate or machine, only those. Read-only.",
Input: schema(map[string]string{"candidate": "the candidate's key: <branch>.<revision>, or run-<id>", "machine": "a machine"}, nil),
Run: func(args map[string]any) (any, error) {
return call(meshwants.VerbCompositions, args, "candidate", "machine")
}},
{Name: compositionsDropTool, Description: "Drop one composition run by hand (design 47 G §728): written in the hand-act log first, then its ask " +
"is dropped, each reader ended could not run naming the drop, and the key deleted.",
Input: schema(map[string]string{"candidate": "the candidate's key", "machine": "the machine", "why": "why the run is dropped"}, []string{"candidate", "machine", "why"}),
Run: func(args map[string]any) (any, error) {
return call(meshwants.VerbCompositionsDrop, args, "candidate", "machine", "why")
}},
}
}
@@ -0,0 +1,91 @@
package main
import (
"encoding/json"
"errors"
"strings"
"testing"
"time"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
)
// Design 47 G §728, A-469f, A-469u, A-469v: compositions answers each run with its key and the fill, only those of a candidate or
// machine when named; compositions-drop writes the hand act first (nothing is dropped when it is not recorded), drops a running
// run's ask, ends each reader could not run naming the drop and deletes the key with its bound keys; the tools call the verbs.
func TestTheCompositionRunsAreReadAndDroppedByTheirVerbs(t *testing.T) {
now := time.Date(2026, 11, 17, 12, 0, 0, 0, time.UTC)
kv := newRunsMem()
r := newCompositionRuns(kv, defaultRunSettings, func() time.Time { return now }, t.Logf)
var drops []string
r.drop = func(ask, why string) error { drops = append(drops, ask); return nil }
ends := newSaidEvents()
var endIDs []string // the message id of each end said
c := &compositionSteps{node: "n1", now: func() time.Time { return now }, logf: t.Logf, say: func(event string, body any, id string) error {
endIDs = append(endIDs, id)
return ends.say(event, body, id)
}}
moves := 0
move := func(meshwants.CompositionRun) { moves++ }
r.moved.Store(&move)
for _, m := range []string{"n1", "n2"} {
if _, err := r.join(readerOf("ask-a", meshwants.StepRun{Pipeline: "main.3.a", Step: meshwants.StepRunStepComposition, Module: "a"}), "main.3", m, "run-"+m); err != nil {
t.Fatal(err)
}
}
// A-470r: n2's run carries a reader that ended passed (p) and one marked rerun (q); only q's end is owed, said once.
_, _, _ = r.change(runKeyOf("main.3", "n2"), func(run *meshwants.CompositionRun) bool {
for _, id := range []string{"ask-p", "ask-q"} {
c := readerOf(id, meshwants.StepRun{Pipeline: "main.3." + id, Step: meshwants.StepRunStepComposition, Module: id})
c.Ended, c.Rerun = &now, id == "ask-q"
run.Readers = append(run.Readers, c)
}
return true
})
var recorded []meshhandactsclient.Request
record := func(q meshhandactsclient.Request) error { recorded = append(recorded, q); return nil }
verbs := compositionVerbs(r, c, record)
out, err := verbs[meshwants.VerbCompositions]("op", json.RawMessage(`{"machine":"n2"}`))
read, _ := out.(meshwants.CompositionsAnswer)
if err != nil || len(read.Runs) != 1 || read.Runs[0].Key != runKeyOf("main.3", "n2") || read.Runs[0].Ask != "run-n2" || len(read.Runs[0].Readers) != 3 ||
read.Fill.Store != "composition-runs" || read.Fill.Cap != 16<<20 || read.Fill.Bytes == 0 {
t.Fatalf("compositions = %+v %v", out, err)
}
refuse := compositionVerbs(r, c, func(meshhandactsclient.Request) error { return errors.New("no holder") })
if _, err := refuse[meshwants.VerbCompositionsDrop]("op", json.RawMessage(`{"candidate":"main.3","machine":"n2","why":"stuck"}`)); err == nil ||
!strings.Contains(err.Error(), "nothing was dropped") || len(drops) != 0 {
t.Fatalf("a drop not recorded: %v, drops %v", err, drops)
}
out, err = verbs[meshwants.VerbCompositionsDrop]("op@n1", json.RawMessage(`{"candidate":"main.3","machine":"n2","why":"stuck"}`))
dropped, _ := out.(meshwants.CompositionsDropAnswer)
if err != nil || dropped.Run.Key != runKeyOf("main.3", "n2") || len(dropped.Ended) != 2 || dropped.Ended[0].ID != "ask-a" || dropped.Ended[1].ID != "ask-q" ||
moves != 0 || len(endIDs) != 2 || endIDs[0] != "ask-a" || endIDs[1] != "ask-q.run-n2" ||
len(recorded) != 1 || recorded[0].Why != "stuck (op@n1)" || len(drops) != 1 || drops[0] != "run-n2" {
t.Fatalf("compositions-drop = %+v %v, recorded %+v, drops %v, moves %d, ends %v", out, err, recorded, drops, moves, endIDs)
}
end, _ := ends.said[meshwants.EventStepEnded+".n1"].(meshwants.StepEnded)
if end.ID != "ask-q" || end.Outcome != meshwants.StepEndedOutcomeCouldNotRun || !strings.Contains(end.Said, "dropped by hand: stuck") ||
len(end.Shared) != 1 || end.Shared[0].Ask != "run-n2" {
t.Errorf("the reader's end %+v", end)
}
if keys, _ := kv.keys(); len(keys) != 2 || keys[0] != runKeyOf("main.3", "n1") {
t.Errorf("keys after the drop %v, want n1's run and its untaken key", keys)
}
// The tools call the verbs with what they were given.
var asked []string
tools := compositionsTools(func(key string, body any) (json.RawMessage, error) {
raw, _ := json.Marshal(body)
asked = append(asked, key+" "+string(raw))
return json.RawMessage(`{"runs":[],"fill":{"store":"composition-runs","bytes":0,"cap":1}}`), nil
})
for _, tool := range tools {
if _, err := tool.Run(map[string]any{"candidate": "main.3", "machine": "n1", "why": "x"}); err != nil {
t.Fatal(err)
}
}
if len(tools) != 2 || tools[0].Name != compositionsTool || tools[1].Name != compositionsDropTool ||
asked[0] != `seat:mesh-wants.compositions {"candidate":"main.3","machine":"n1"}` || asked[1] != `seat:mesh-wants.compositions-drop {"candidate":"main.3","machine":"n1","why":"x"}` {
t.Errorf("the tools asked %v", asked)
}
}
@@ -2,16 +2,11 @@ package main
import (
"context"
"encoding/json"
"strings"
"errors"
"sync"
"time"
"github.com/nats-io/nats.go"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-sdk/go/process"
"git.novox.be/novox/mesh-sdk/go/seatdef"
)
// The composition step (design 47 G §22, §354, §63): the assigner takes the seat mesh-wants' accepted kind `step`, the
@@ -23,6 +18,8 @@ type stepOutcome struct {
Outcome string
Said string
Warnings []string
// Shared names per machine composed the composition run the step read and its ask (design 47 G §723, §729).
Shared []meshwants.Shared
}
// compositionSteps takes the composition steps and says their ends.
@@ -30,49 +27,58 @@ type compositionSteps struct {
node string
// say says one event of the seat mesh-wants (wantsPublisher).
say publisher
// run runs one step and answers what it came to.
run func(ctx context.Context, id string, run meshwants.StepRun) stepOutcome
now func() time.Time
logf func(string, ...any)
// asker is the name the step's progress names as its asker, read when it is said (stepAskerOf).
asker func() string
// run runs one step and answers what it came to; resume judges a step taken up at the start from its runs (takeUp).
run func(ctx context.Context, id string, run meshwants.StepRun) stepOutcome
resume func(ctx context.Context, id string, run meshwants.StepRun) stepOutcome
// validate runs one validate step and resumeValidate judges one taken up at the start (validatestep.go, design 47 H §745);
// nil takes no validate step.
validate func(ctx context.Context, id string, run meshwants.StepRun) stepOutcome
resumeValidate func(ctx context.Context, id string, run meshwants.StepRun) stepOutcome
// ended writes, once the step asked under id said its end, that time on its reader in each run naming it (A-470m); nil
// writes none.
ended func(id string, run meshwants.StepRun, at time.Time)
now func() time.Time
logf func(string, ...any)
// ticks is a ticker of every d, its channel and its stop (time.NewTicker); nil is the clock's. A test hands its own.
ticks func(d time.Duration) (<-chan time.Time, func())
}
// stepAskerOf is the asker a composition step's progress names: the one caller the seat mesh-wants' definition lists for its
// accepted kind step, read from the seat list when it is said, since that subject names no asker (design 47 G A-294, which
// corrects A-267). Empty while the seat list holds no definition naming exactly one.
func stepAskerOf(definition func() (seatdef.Definition, bool)) func() string {
return func() string {
d, ok := definition()
if !ok {
return ""
}
var one string
for _, m := range d.Accepts {
if m.Name != meshwants.AcceptStep || m.Callers == nil {
continue
}
for _, e := range m.Callers.List {
name, isSeat := strings.CutPrefix(e, seatdef.CallerSeatPrefix)
if !isSeat || (one != "" && one != name) {
return ""
}
one = name
}
}
return one
}
// taken is the state taken (stepqueue.go): each ask pulled is taken once by its id, for takenBound; the drops of asks not
// pulled yet are kept there too (H-A-404).
taken takenStore
takenBound time.Duration
// inProgress is how often a running step's pulled ask is said in progress: the seat definition's in-progress (§777).
inProgress func() time.Duration
mu sync.Mutex
// stops ends the wait of a running step by its ask's id, when its pipeline is superseded or cancelled (leave), or the ask is
// dropped (the cause an *askDrop).
stops map[string]context.CancelCauseFunc
// held are the messages pulled from the seat's work queue for each running step's ask, acknowledged once its end is said.
held map[string][]queueMsg
}
// progressEvery is how often a running composition step says its progress (design 47 G §496, A-262).
const progressEvery = time.Minute
// stepPhase is the phase a running step is in: fetch, build, run or report (§496), set by the run through its context.
// stepPhase is the phase a running step is in: fetch, build, run or report (§496), set by the run through its context, and the
// composition runs it waits on (§723, §729).
type stepPhase struct {
mu sync.Mutex
phase string
mu sync.Mutex
phase string
shared []meshwants.Shared
}
// setShared names the runs the step ctx runs waits on, when it runs one.
func setShared(ctx context.Context, shared []meshwants.Shared) {
if p, ok := ctx.Value(phaseKey{}).(*stepPhase); ok {
p.mu.Lock()
p.shared = shared
p.mu.Unlock()
}
}
func (p *stepPhase) waitsOn() []meshwants.Shared {
p.mu.Lock()
defer p.mu.Unlock()
return p.shared
}
type phaseKey struct{}
@@ -92,37 +98,133 @@ func (p *stepPhase) get() string {
return p.phase
}
// take takes one ask of the accepted kind `step` by its id and body: a step that is no composition step, or an ask with no
// id, is left with a log line; one taken is run in its own goroutine and its end said.
func (c *compositionSteps) take(ctx context.Context, id string, data []byte) bool {
var run meshwants.StepRun
if err := json.Unmarshal(data, &run); err != nil || id == "" || run.Step != meshwants.StepRunStepComposition {
c.logf("a step ask that is no composition step with an id is left: %v", err)
return false
// howOf is what runs a step, or judges it once taken up at the start: by its step, composition or validate; nil for another.
func (c *compositionSteps) howOf(step string, resumed bool) func(context.Context, string, meshwants.StepRun) stepOutcome {
switch {
case step == meshwants.StepRunStepComposition && resumed:
return c.resume
case step == meshwants.StepRunStepComposition:
return c.run
case step == meshwants.StepRunStepValidate && resumed:
return c.resumeValidate
case step == meshwants.StepRunStepValidate:
return c.validate
}
go c.runOne(ctx, id, run)
return true
return nil
}
// runOne runs one step and says its end.
func (c *compositionSteps) runOne(ctx context.Context, id string, run meshwants.StepRun) {
// say1 runs one step with how and says its end, naming in `shared` the runs it read (§723); again is, for an end said again, the
// ask of the run whose end makes it say again (sayEnd). A step whose wait was ended by its pipeline's supersede or cancel (leave)
// says nothing: the runner ended it already.
func (c *compositionSteps) say1(parent context.Context, id string, run meshwants.StepRun, how func(context.Context, string, meshwants.StepRun) stepOutcome, again string) {
started := c.now().UTC()
ctx, stopWait := context.WithCancelCause(parent)
c.mu.Lock()
if c.stops == nil {
c.stops = map[string]context.CancelCauseFunc{}
}
if c.stops[id] != nil { // the step asked under id is running already: it says its own end
c.mu.Unlock()
stopWait(nil)
return
}
c.stops[id] = stopWait
c.mu.Unlock()
defer func() {
c.mu.Lock()
delete(c.stops, id)
c.mu.Unlock()
stopWait(nil)
}()
phase := &stepPhase{phase: meshwants.StepProgressEventPhaseFetch}
stop := c.sayProgress(id, phase)
o := c.run(context.WithValue(ctx, phaseKey{}, phase), id, run)
stop := c.sayProgress(id, run.Asker, phase)
stopInProgress := c.inProgressEvery(id)
o := how(context.WithValue(ctx, phaseKey{}, phase), id, run)
stopInProgress()
stop()
if ctx.Err() != nil {
if parent.Err() != nil { // the assigner stops: its pulled asks are handed again to its next start
return
}
var d *askDrop
if errors.As(context.Cause(ctx), &d) { // dropped through the seat's drop (§778, H-A-401)
c.sayEnd(id, run, &started, stepOutcome{Outcome: meshwants.StepEndedOutcomeCouldNotRun, Said: d.Error(), Shared: o.Shared}, again)
return
}
c.logf("the composition step %s of %s says no end: its wait ended (%v)", id, run.Pipeline, context.Cause(ctx))
c.settle(id, true) // the runner ended it already: its ask is over
return
}
c.sayEnd(id, run, &started, o, again)
}
// sayEnd says the end of the step asked under id as the seat's step-ended.<node>, its id the ask's; once said, its time is
// written as its reader's `ended` (A-470m). Its first end's message id is the ask's id; an end said again is published under
// `<ask id>.<again>`, again the ask of the run whose end makes it say again, so the bus's deduplication never drops it (A-470q).
func (c *compositionSteps) sayEnd(id string, run meshwants.StepRun, started *time.Time, o stepOutcome, again string) {
ended := c.now().UTC()
end := meshwants.StepEnded{V: 1, ID: id, Pipeline: run.Pipeline, Step: meshwants.StepEndedStepComposition, Module: run.Module,
if started == nil {
started = &ended
}
step := meshwants.StepEndedStepComposition
if run.Step == meshwants.StepRunStepValidate {
step = meshwants.StepEndedStepValidate
}
end := meshwants.StepEnded{V: 1, ID: id, Pipeline: run.Pipeline, Step: step, Module: run.Module,
Commit: run.Commit, Fingerprint: run.Fingerprint, Node: c.node, Outcome: o.Outcome, Said: o.Said, Warnings: o.Warnings,
Rerun: run.Rerun, By: run.By, Started: &started, Ended: &ended}
if err := c.say(meshwants.EventStepEnded+"."+c.node, end, id); err != nil {
c.logf("saying the end of the composition step %s: %v", id, err)
Rerun: run.Rerun, By: run.By, Started: started, Ended: &ended, Shared: o.Shared}
msgID := id
if again != "" {
msgID = id + "." + again
}
if err := c.say(meshwants.EventStepEnded+"."+c.node, end, msgID); err != nil {
c.logf("saying the end of the composition step %s: %v; its ask is handed again", id, err)
c.settle(id, false)
return
}
c.settle(id, true) // the ask's end is said: its pulled messages leave the seat's work queue (§777)
// One journal line per ask answered, in the one place it is answered (design 47 H2 §792).
c.logf("answered %s %s %s %s %s", id, run.Pipeline, run.Module, step, o.Outcome)
if c.ended != nil {
c.ended(id, run, ended)
}
}
// move says the end again of each reader a rerun carried into an ended run, marked rerun (§727, A-470d): its machines judged
// from the candidate's keys naming it, the run's new ask in `shared`. A reader running here says its own end.
func (c *compositionSteps) move(ctx context.Context) func(run meshwants.CompositionRun) {
return func(run meshwants.CompositionRun) {
for _, reader := range run.Readers {
if !reader.Rerun || c.running(reader.ID) {
continue
}
c.logf("the composition step %s of %s moves with the composition run of %s (ask %s)", reader.ID, reader.Pipeline, run.Machine, run.Ask)
go c.say1(ctx, reader.ID, stepRunOf(reader), c.resume, run.Ask) // said again under the moved run's ask (A-470q)
}
}
}
// running is whether the step asked under id runs here.
func (c *compositionSteps) running(id string) bool {
c.mu.Lock()
defer c.mu.Unlock()
return c.stops[id] != nil
}
// leave ends the waits of the steps asked under ids (§723: a superseded or cancelled step leaves its runs).
func (c *compositionSteps) leave(ids []string) {
c.mu.Lock()
defer c.mu.Unlock()
for _, id := range ids {
if stop := c.stops[id]; stop != nil {
stop(nil)
}
}
}
// sayProgress says the step's progress on the seat's step-progress.<node> once a minute until the returned stop is called (design
// 47 G §496, A-262): a ticker inside the running step, as the build seats' step runner says its own beat.
func (c *compositionSteps) sayProgress(id string, phase *stepPhase) (stop func()) {
func (c *compositionSteps) sayProgress(id, asker string, phase *stepPhase) (stop func()) {
ticks := c.ticks
if ticks == nil {
ticks = func(d time.Duration) (<-chan time.Time, func()) { t := time.NewTicker(d); return t.C, t.Stop }
@@ -139,7 +241,7 @@ func (c *compositionSteps) sayProgress(id string, phase *stepPhase) (stop func()
return
case <-tick:
at := c.now().UTC()
p := meshwants.StepProgressEvent{Ask: id, Asker: c.asker(), Phase: phase.get(), At: at}
p := meshwants.StepProgressEvent{Ask: id, Asker: asker, Phase: phase.get(), At: at, Shared: phase.waitsOn()}
if err := c.say(meshwants.EventStepProgress+"."+c.node, p, id+".progress."+at.Format(time.RFC3339Nano)); err != nil {
c.logf("saying the progress of the composition step %s: %v", id, err)
}
@@ -148,21 +250,3 @@ func (c *compositionSteps) sayProgress(id string, phase *stepPhase) (stop func()
}()
return func() { close(done); <-ended }
}
// stepAskID is an ask's id as the asker names it: its event id, else its message id.
func stepAskID(m *nats.Msg) string {
if id := m.Header.Get("x-event-id"); id != "" {
return id
}
return m.Header.Get(nats.MsgIdHdr)
}
// serveCompositionSteps hears the composition step asks on the seat mesh-wants' accept subject.
func serveCompositionSteps(ctx context.Context, conn process.Subscriber, c *compositionSteps) error {
sub, err := conn.Subscribe(meshwants.AcceptSubjectStep, func(m *nats.Msg) { c.take(ctx, stepAskID(m), m.Data) })
if err != nil {
return err
}
go func() { <-ctx.Done(); _ = sub.Drain() }()
return nil
}
@@ -5,6 +5,7 @@ package main
import (
"bytes"
"encoding/json"
"fmt"
"strings"
"testing"
"time"
@@ -105,7 +106,7 @@ func TestTheCompositionStepComposesEachMachineThroughTheBuildSeat(t *testing.T)
from := b.journal.mark()
b.start(t)
b.journal.await(t, from, "the composition step is heard on", "the composition step served", 30*time.Second)
b.journal.await(t, from, "the composition step is pulled from", "the composition step served", 30*time.Second)
b.journal.await(t, from, "n3 is away (machine-away)", "the machine-away of n3 heard", 30*time.Second)
select {
@@ -113,14 +114,8 @@ func TestTheCompositionStepComposesEachMachineThroughTheBuildSeat(t *testing.T)
case <-time.After(30 * time.Second):
t.Fatal("the assigner did not read the seat list within 30 s")
}
step, _ := json.Marshal(meshwants.StepRun{Pipeline: "main.3.m", Step: meshwants.StepRunStepComposition, Module: "m", Branch: trunkBranch,
putStep(b.ctx, t, b.js, "step-ask-1", meshwants.StepRun{Pipeline: "main.3.m", Step: meshwants.StepRunStepComposition, Module: "m", Branch: trunkBranch,
Revision: 3, Commit: engineCommit, Fingerprint: "src2:m1"})
msg := nats.NewMsg(meshwants.AcceptSubjectStep)
msg.Header.Set("x-event-id", "step-ask-1")
msg.Data = step
if err := nc.PublishMsg(msg); err != nil {
t.Fatal(err)
}
// The stand-in Go build seat takes the run asks put under the assigner's name, reads each request by the verb input and says
// its end with the composer's verdict: n1 composes, n2 does not.
@@ -146,6 +141,9 @@ func TestTheCompositionStepComposesEachMachineThroughTheBuildSeat(t *testing.T)
if err != nil || len(req.Machines) != 1 {
t.Fatalf("the request of %s: %+v %v", a.ID, req, err)
}
if len(req.Seats) == 0 { // the revision names no definition: the request carries the trunk seat list's (A-467)
t.Errorf("the request of %s carries no seat definition", a.ID)
}
node := req.Machines[0]
programs[node] = a.Run.Program.Commit
m := composer.Machine{Composes: true}
@@ -165,7 +163,8 @@ func TestTheCompositionStepComposesEachMachineThroughTheBuildSeat(t *testing.T)
t.Fatal("the composition step said no end")
}
if e.ID != "step-ask-1" || e.Outcome != meshwants.StepEndedOutcomeFailed || !strings.Contains(e.Said, "n2 does not compose") ||
strings.Contains(e.Said, "n1") || len(e.Warnings) != 1 || !strings.Contains(e.Warnings[0], "n3 is away") {
strings.Contains(e.Said, "n1") || len(e.Warnings) != 2 || !strings.Contains(e.Warnings[0], "n3 is away") ||
e.Warnings[1] != "n2: the composer names no culprits" {
t.Fatalf("the step ended %+v", e)
}
if programs["n1"] != engineCommit || programs["n2"] != engineCommit {
@@ -177,10 +176,26 @@ func TestTheCompositionStepComposesEachMachineThroughTheBuildSeat(t *testing.T)
t.Error("the machine away was asked for its input")
}
}
keys, _ := b.buckets[buckets.Inputs()].Keys(b.ctx)
if len(keys) != 0 {
t.Errorf("the inputs stay kept past their step-ended: %v", keys)
// The run's end comes before the input's delete (A-470o, A-470p): the inputs go after the step's end, heard by their watch.
inputs := b.buckets[buckets.Inputs()]
w, err := inputs.WatchAll(b.ctx)
if err != nil {
t.Fatal(err)
}
defer func() { _ = w.Stop() }()
deadline := time.After(10 * time.Second)
for {
keys, _ := inputs.Keys(b.ctx)
if len(keys) == 0 {
break
}
select {
case <-w.Updates():
case <-deadline:
t.Fatalf("the inputs stay kept past their step-ended: %v", keys)
}
}
queueEmpty(b.ctx, t, b.js) // the step's ask acknowledged at its end (design 47 H2 §777)
}
// readInput reads a run's input as a build seat does: the seat mesh-wants' verb input answers its digest and chunk count, then its
@@ -222,3 +237,162 @@ func readInput(t *testing.T, nc *nats.Conn, in buildstep.RunInput) []byte {
}
return out.Bytes()
}
// Design 47 H §745 (acceptance test 117, the assigner's half; H-A-108), started whole on the bus: the assigner serves the step
// validate on the seat mesh-wants. A take-in whose manifest names an unknown field fails it `manifest-refused` naming it, the
// validator being the revision's own entry of the module holding the seat mesh-catalog, run on the Go build seat over the
// revision's manifests and the previous revision's; a take-in that changes a manifest with no problem passes it; a take-in whose
// entries make a cycle fails it `cycle` naming the cycle, with no validator asked.
func TestTheValidateStepServedWholeRefusesAManifestProblemAndACycle(t *testing.T) {
b := startBed(t, "")
nc, err := nats.Connect(b.srv.ClientURL())
if err != nil {
t.Fatal(err)
}
t.Cleanup(nc.Close)
const commit = "2222222222222222222222222222222222222222"
if _, err := b.js.CreateOrUpdateConsumer(b.ctx, "EVENTS", jetstream.ConsumerConfig{Durable: "n1_mesh-delivery-assigner",
FilterSubjects: []string{enginereads.SubjectPrefix + "*", "mesh.mod." + buckets.IndexerModule + ".event.views.>", meshcatalog.SubjectCatalogRevisionAll,
nodebuildgo.SubjectStepEndedAll}, AckPolicy: jetstream.AckExplicitPolicy}); err != nil {
t.Fatal(err)
}
indexer := meshcatalog.CatalogEntry{Module: "indexer", Repository: "novox/mesh-delivery", Commit: commit, Path: "modules/mesh-delivery-indexer",
Fp: "src2:ix", Serves: []string{"seat:" + meshcatalog.Seat + ".revision"}, Manifest: map[string]any{"module": "indexer"}, ManifestDigest: "d-ix"}
entry := func(module, digest string, manifest map[string]any, edges ...meshcatalog.Edge) meshcatalog.CatalogEntry {
manifest["module"] = module
return meshcatalog.CatalogEntry{Module: module, Manifest: manifest, ManifestDigest: digest, Edges: edges}
}
b.cat.mu.Lock()
b.cat.rev[trunkBranch] = 9
b.cat.at = map[string]map[int64][]meshcatalog.CatalogEntry{trunkBranch: {
6: {indexer, entry("web", "d-web-1", map[string]any{"version": "1"})},
7: {indexer, entry("web", "d-web-2", map[string]any{"version": "2", "colour": "red"})},
8: {indexer, entry("web", "d-web-3", map[string]any{"version": "3"})},
9: {indexer, entry("a", "d-a", map[string]any{}, meshcatalog.Edge{From: "a:x", To: "b:y", Kind: 3}, meshcatalog.Edge{From: "b:y", To: "a:x", Kind: 3}),
entry("b", "d-b", map[string]any{})},
}}
b.cat.mu.Unlock()
ended := make(chan meshwants.StepEnded, 4)
ends, err := nc.Subscribe("mesh.seat.mesh-wants.event.step-ended.n1", func(m *nats.Msg) {
var e meshwants.StepEnded
_ = json.Unmarshal(m.Data, &e)
ended <- e
})
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = ends.Unsubscribe() })
subscribed(t, nc)
// Design 47 H2 §777: a validate ask put while the assigner is stopped waits on the seat's work queue, and is taken (ask-taken)
// and ended after its start.
taken := make(chan *nats.Msg, 8)
takens, err := nc.ChanSubscribe(meshwants.SubjectAskTakenAll, taken)
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = takens.Unsubscribe() })
subscribed(t, nc)
putStep(b.ctx, t, b.js, "validate-9", meshwants.StepRun{Pipeline: trunkBranch + ".9", Step: meshwants.StepRunStepValidate, Module: "a",
Branch: trunkBranch, Revision: 9, Commit: commit})
from := b.journal.mark()
b.start(t)
b.journal.await(t, from, "the composition step is pulled from", "the steps served", 30*time.Second)
select {
case m := <-taken:
var at meshwants.AskTakenEvent
if err := json.Unmarshal(m.Data, &at); err != nil || at.Ask != "validate-9" || at.Node != "n1" || at.At.IsZero() || m.Subject != meshwants.SubjectAskTaken("validate-9") {
t.Fatalf("ask-taken on %s = %+v, %v; want validate-9 taken on n1", m.Subject, at, err)
}
case <-time.After(30 * time.Second):
t.Fatal("no ask-taken within 30 s of the start for the ask put while the assigner was stopped")
}
select {
case e := <-ended:
if e.ID != "validate-9" || e.Outcome != meshwants.StepEndedOutcomeFailed || e.Said != reasonCycle+": a:x → b:y → a:x" {
t.Errorf("the validate step of a take-in making a cycle ended %+v", e)
}
case <-time.After(30 * time.Second):
t.Fatal("the validate ask put while the assigner was stopped said no end")
}
select {
case <-b.seatListRead:
case <-time.After(30 * time.Second):
t.Fatal("the assigner did not read the seat list within 30 s")
}
queue, _ := buildstep.AskStream(buildstep.AskGo)
worker, err := b.js.CreateOrUpdateConsumer(b.ctx, queue, jetstream.ConsumerConfig{Durable: "stand-in", FilterSubject: "mesh.seat.node-build-go.accept.check.mesh-wants", AckPolicy: jetstream.AckExplicitPolicy})
if err != nil {
t.Fatal(err)
}
ask := func(revision int64, module string, run func()) meshwants.StepEnded {
t.Helper()
id := fmt.Sprintf("validate-%d", revision)
step, _ := json.Marshal(meshwants.StepRun{Pipeline: fmt.Sprintf("%s.%d", trunkBranch, revision), Step: meshwants.StepRunStepValidate, Module: module,
Branch: trunkBranch, Revision: revision, Commit: commit})
var asked meshwants.StepRun
_ = json.Unmarshal(step, &asked)
putStep(b.ctx, t, b.js, id, asked)
if run != nil {
run()
}
for {
select {
case e := <-ended:
if e.ID == id {
return e
}
case <-time.After(30 * time.Second):
t.Fatalf("the validate step of revision %d said no end", revision)
}
}
}
// The stand-in Go build seat runs the validator: it refuses a manifest naming the field colour, and accepts every other.
validator := func() {
t.Helper()
got, err := worker.Next(jetstream.FetchMaxWait(30 * time.Second))
if err != nil {
t.Fatalf("no validator run is asked: %v", err)
}
_ = got.Ack()
a, err := buildstep.DecodeStepAsk(got.Data())
if err != nil || a.Run == nil || a.Run.Program.Repository != "novox/mesh-delivery" || a.Run.Program.Commit != commit {
t.Fatalf("the validator's run ask %s: %v", got.Data(), err)
}
req, err := composer.Decode(readInput(t, nc, a.Run.Input))
if err != nil || len(req.Cases) != 2 || req.Cases[0].Name != changeCase || req.Cases[1].Name != beforeCase {
t.Fatalf("the validator's request: %+v %v", req, err)
}
// The revision names no definitions: the request holds the trunk's seat list as seat-list handed it, named by its digest (H-A-443).
if list, digest := seatListBytes(); req.SeatList != digest {
t.Errorf("the validator's request names the seat list %q, want %q", req.SeatList, digest)
} else if got, _ := json.Marshal(req.Seats); string(got) != string(list) {
t.Errorf("the validator's request holds seats %d bytes long, not the seat list's %d", len(got), len(list))
}
v := composer.Verdict{V: composer.Version}
for _, c := range req.Cases {
reads := map[string]composer.ManifestRead{}
for module, m := range c.Manifests {
reads[module] = composer.ManifestRead{Accepted: true}
if strings.Contains(string(m.Raw), "colour") {
reads[module] = composer.ManifestRead{Refused: `unknown field "colour"`}
}
}
v.Cases = append(v.Cases, composer.CaseVerdict{Name: c.Name, Manifests: reads})
}
out, _ := json.Marshal(v)
end, _ := json.Marshal(buildstep.StepEnded{V: 1, ID: a.ID, Ask: a.ID, Asker: runAsker, Node: "b1", Outcome: buildstep.OutcomePassed, Output: string(out), At: time.Now().UTC()})
if _, err := b.js.Publish(b.ctx, nodebuildgo.SubjectStepEnded("b1"), end); err != nil {
t.Fatal(err)
}
}
if e := ask(7, "web", validator); e.Outcome != meshwants.StepEndedOutcomeFailed || !strings.HasPrefix(e.Said, reasonManifestRefused+": ") || !strings.Contains(e.Said, `web: unknown field "colour"`) {
t.Errorf("the validate step of a manifest naming an unknown field ended %+v", e)
}
if e := ask(8, "web", validator); e.Outcome != meshwants.StepEndedOutcomePassed {
t.Errorf("the validate step of a manifest with no problem ended %+v", e)
}
if info, err := worker.Info(b.ctx); err != nil || info.NumPending != 0 {
t.Errorf("a validator is asked for the cycle: %+v %v", info, err)
}
queueEmpty(b.ctx, t, b.js) // every ask acknowledged at its end (§777)
}
@@ -3,14 +3,115 @@ package main
import (
"context"
"encoding/json"
"git.novox.be/novox/mesh-sdk/go/seatdef"
"errors"
"fmt"
"slices"
"strings"
"sync"
"testing"
"time"
"github.com/nats-io/nats.go"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
stdio "git.novox.be/novox/mesh-sdk/go"
)
// fakeMsg is one ask pulled from the seat's work queue, recording how it was settled.
type fakeMsg struct {
data []byte
h nats.Header
mu sync.Mutex
acks, naks, terms, inProgresss int
}
func (m *fakeMsg) Data() []byte { return m.data }
func (m *fakeMsg) Headers() nats.Header { return m.h }
func (m *fakeMsg) count(n *int) error { m.mu.Lock(); *n++; m.mu.Unlock(); return nil }
func (m *fakeMsg) Ack() error { return m.count(&m.acks) }
func (m *fakeMsg) Nak() error { return m.count(&m.naks) }
func (m *fakeMsg) Term() error { return m.count(&m.terms) }
func (m *fakeMsg) InProgress() error { return m.count(&m.inProgresss) }
func (m *fakeMsg) settled() (acks, naks, terms, progress int) {
m.mu.Lock()
defer m.mu.Unlock()
return m.acks, m.naks, m.terms, m.inProgresss
}
// fakeTaken is the state taken: its keys, each with its time to live, and a refusal of TakeOnce when refuse is set.
type fakeTaken struct {
mu sync.Mutex
values map[string][]byte
ttls map[string]time.Duration
refuse error
}
func newFakeTaken() *fakeTaken {
return &fakeTaken{values: map[string][]byte{}, ttls: map[string]time.Duration{}}
}
func (f *fakeTaken) TakeOnce(seat, ask string, bound time.Duration) (bool, error) {
f.mu.Lock()
defer f.mu.Unlock()
if f.refuse != nil {
return false, f.refuse
}
key := seat + "." + ask
if _, ok := f.values[key]; ok {
return false, nil
}
f.values[key], f.ttls[key] = []byte(`{}`), bound
return true, nil
}
func (f *fakeTaken) Get(key string) (*stdio.StateEntry, error) {
f.mu.Lock()
defer f.mu.Unlock()
v, ok := f.values[key]
if !ok {
return nil, nil
}
return &stdio.StateEntry{Key: key, Value: v}, nil
}
func (f *fakeTaken) RenewTTL(key string, value any, ttl time.Duration) (uint64, error) {
raw, err := json.Marshal(value)
f.mu.Lock()
defer f.mu.Unlock()
f.values[key], f.ttls[key] = raw, ttl
return 1, err
}
func (f *fakeTaken) Delete(key string) error {
f.mu.Lock()
defer f.mu.Unlock()
delete(f.values, key)
return nil
}
func (f *fakeTaken) Keys() ([]string, error) {
f.mu.Lock()
defer f.mu.Unlock()
var out []string
for k := range f.values {
out = append(out, k)
}
return out, nil
}
// pullOne hands c one ask pulled from the seat's work queue under id, with a state taken of its own when c has none.
func pullOne(c *compositionSteps, id string, body []byte) *fakeMsg {
if c.taken == nil {
c.taken = newFakeTaken()
}
m := &fakeMsg{data: body, h: nats.Header{}}
if id != "" {
m.h.Set("x-event-id", id)
}
c.pulled(context.Background(), m)
return m
}
// saidEvents keeps what a publisher says.
type saidEvents struct {
mu sync.Mutex
@@ -37,23 +138,34 @@ func TestTheCompositionStepIsTakenAndItsEndSaid(t *testing.T) {
said := newSaidEvents()
at := time.Date(2026, 11, 12, 9, 0, 0, 0, time.UTC)
var asked meshwants.StepRun
c := &compositionSteps{node: "n1", say: said.say, now: func() time.Time { return at }, logf: t.Logf,
var lines []string
var linesMu sync.Mutex
logf := func(f string, a ...any) {
linesMu.Lock()
lines = append(lines, fmt.Sprintf(f, a...))
linesMu.Unlock()
}
c := &compositionSteps{node: "n1", say: said.say, now: func() time.Time { return at }, logf: logf,
run: func(_ context.Context, id string, run meshwants.StepRun) stepOutcome {
asked = run
return stepOutcome{Outcome: meshwants.StepEndedOutcomeFailed, Said: "a and b own /etc/x", Warnings: []string{"n3 asleep"}}
return stepOutcome{Outcome: meshwants.StepEndedOutcomeFailed, Said: "a and b own /etc/x", Warnings: []string{"n3 asleep"},
Shared: []meshwants.Shared{{Machine: "n1", Run: "main=2e4.n1", Ask: "run-1"}}}
}}
other, _ := json.Marshal(map[string]any{"pipeline": "main.4.m", "step": "build", "module": "m"})
if c.take(context.Background(), "ask-0", other) {
if m := pullOne(c, "ask-0", other); m.terms != 1 {
t.Fatal("a step ask of another step is taken")
}
body, _ := json.Marshal(meshwants.StepRun{Pipeline: "main.4.m", Step: meshwants.StepRunStepComposition, Module: "m", Branch: "main",
Commit: "c0ffee", Revision: 4, Fingerprint: "fp1", Rerun: true, By: "lead@n1"})
if c.take(context.Background(), "", body) {
if m := pullOne(c, "", body); m.terms != 1 {
t.Fatal("a step ask with no id is taken")
}
if !c.take(context.Background(), "ask-1", body) {
if m := pullOne(c, "ask-1", body); m.terms != 0 {
t.Fatal("the composition step is not taken")
}
if e := <-said.heard; e != meshwants.EventAskTaken+".ask-1" { // said at the pull (H2 §777)
t.Fatalf("said %s first, want ask-taken", e)
}
select {
case <-said.heard:
case <-time.After(5 * time.Second):
@@ -67,9 +179,215 @@ func TestTheCompositionStepIsTakenAndItsEndSaid(t *testing.T) {
if asked.Module != "m" || end.ID != "ask-1" || end.Pipeline != "main.4.m" || end.Step != meshwants.StepEndedStepComposition ||
end.Module != "m" || end.Commit != "c0ffee" || end.Fingerprint != "fp1" || end.Node != "n1" ||
end.Outcome != meshwants.StepEndedOutcomeFailed || end.Said != "a and b own /etc/x" || len(end.Warnings) != 1 ||
!end.Rerun || end.By != "lead@n1" || end.Started == nil || end.Ended == nil {
!end.Rerun || end.By != "lead@n1" || end.Started == nil || end.Ended == nil ||
len(end.Shared) != 1 || end.Shared[0] != (meshwants.Shared{Machine: "n1", Run: "main=2e4.n1", Ask: "run-1"}) { // §723, §729
t.Fatalf("step-ended %+v", end)
}
// Design 47 H2 §792: the ask answered is one journal line, said where its end is said.
linesMu.Lock()
answered := slices.DeleteFunc(slices.Clone(lines), func(l string) bool { return !strings.HasPrefix(l, "answered ") })
linesMu.Unlock()
if !slices.Equal(answered, []string{"answered ask-1 main.4.m m composition failed"}) {
t.Errorf("the journal says %q, want one answered line", answered)
}
// Design 47 H2 §777, §775 (H-A-381, H-A-401, H-A-404): the asks of the seat's work queue, taken once by id, said ask-taken at
// the pull, in progress while they run, acknowledged once their end is said, and ended by the seat's drop.
t.Run("work queue", queueCases)
}
func queueCases(t *testing.T) {
at := time.Date(2026, 11, 22, 1, 0, 0, 0, time.UTC)
body, _ := json.Marshal(meshwants.StepRun{Pipeline: "main.4.m", Step: meshwants.StepRunStepValidate, Module: "m", Branch: "main", Revision: 4})
type bed struct {
c *compositionSteps
said *saidEvents
taken *fakeTaken
runs chan string
release chan struct{}
tick chan time.Time
}
newBed := func() *bed {
b := &bed{said: newSaidEvents(), taken: newFakeTaken(), runs: make(chan string, 8), release: make(chan struct{}), tick: make(chan time.Time)}
b.said.heard = make(chan string, 16)
run := func(ctx context.Context, id string, _ meshwants.StepRun) stepOutcome {
b.runs <- id
select {
case <-b.release:
case <-ctx.Done():
}
return stepOutcome{Outcome: meshwants.StepEndedOutcomePassed}
}
b.c = &compositionSteps{node: "n1", say: b.said.say, now: func() time.Time { return at }, logf: t.Logf, taken: b.taken, takenBound: 10 * time.Minute,
validate: run, inProgress: func() time.Duration { return 20 * time.Second },
ticks: func(d time.Duration) (<-chan time.Time, func()) {
if d == 20*time.Second {
return b.tick, func() {}
}
return make(chan time.Time), func() {}
}}
return b
}
ended := func(t *testing.T, b *bed) meshwants.StepEnded {
t.Helper()
for {
select {
case e := <-b.said.heard:
if e == meshwants.EventStepEnded+".n1" {
b.said.mu.Lock()
defer b.said.mu.Unlock()
return b.said.said[e].(meshwants.StepEnded)
}
case <-time.After(5 * time.Second):
t.Fatal("no step-ended is said")
}
}
}
settledAt := func(t *testing.T, m *fakeMsg, acks int) {
t.Helper()
deadline := time.After(5 * time.Second)
for {
if a, _, _, _ := m.settled(); a == acks {
return
}
select {
case <-deadline:
t.Fatalf("the ask is acknowledged %d times, want %d", m.acks, acks)
case <-time.After(time.Millisecond):
}
}
}
t.Run("taken once, said, in progress, acknowledged at its end", func(t *testing.T) {
b := newBed()
m := pullOne(b.c, "ask-1", body)
if id := <-b.runs; id != "ask-1" {
t.Fatalf("ran %s", id)
}
b.said.mu.Lock()
taken, ok := b.said.said[meshwants.EventAskTaken+".ask-1"].(meshwants.AskTakenEvent)
takenID := b.said.ids[meshwants.EventAskTaken+".ask-1"]
b.said.mu.Unlock()
if !ok || taken.Ask != "ask-1" || taken.Node != "n1" || !taken.At.Equal(at) || takenID != "ask-1.taken" || b.taken.ttls["mesh-wants.ask-1"] != 10*time.Minute {
t.Fatalf("ask-taken %+v under %q, taken %v", taken, takenID, b.taken.ttls)
}
b.tick <- at
b.tick <- at
// handed again while it runs: held for the run, which answers both at its one end
again := pullOne(b.c, "ask-1", body)
if a, n, _, p := m.settled(); a != 0 || n != 0 || p < 1 {
t.Fatalf("before its end the ask is acked %d, nakked %d, in progress %d times", a, n, p)
}
close(b.release)
if e := ended(t, b); e.ID != "ask-1" || e.Outcome != meshwants.StepEndedOutcomePassed {
t.Fatalf("step-ended %+v", e)
}
settledAt(t, m, 1)
settledAt(t, again, 1)
select {
case id := <-b.runs:
t.Fatalf("the ask handed again ran again (%s)", id)
default:
}
})
t.Run("taken before is run again, said no ask-taken", func(t *testing.T) {
b := newBed()
_, _ = b.taken.TakeOnce(meshwants.Seat, "ask-2", time.Minute)
close(b.release)
m := pullOne(b.c, "ask-2", body)
<-b.runs
ended(t, b)
settledAt(t, m, 1)
b.said.mu.Lock()
_, said := b.said.said[meshwants.EventAskTaken+".ask-2"]
b.said.mu.Unlock()
if said {
t.Fatal("ask-taken is said again for an ask taken before")
}
})
t.Run("a refused take is handed again", func(t *testing.T) {
b := newBed()
b.taken.refuse = errors.New("no bus")
m := pullOne(b.c, "ask-3", body)
if _, n, _, _ := m.settled(); n != 1 || len(b.runs) != 0 {
t.Fatalf("nakked %d, ran %d", n, len(b.runs))
}
})
t.Run("dropped while it runs", func(t *testing.T) {
b := newBed()
m := pullOne(b.c, "ask-4", body)
<-b.runs
if _, err := b.c.dropAsk("n1.mesh-pipeline-runner", meshwants.DropInput{ID: "ask-4"}); err == nil {
t.Fatal("a drop with no why is taken")
}
a, err := b.c.dropAsk("n1.mesh-pipeline-runner", meshwants.DropInput{ID: "ask-4", Why: "its bound passed"})
if err != nil || a["held"] != true {
t.Fatalf("drop answered %v, %v", a, err)
}
e := ended(t, b)
if e.Outcome != meshwants.StepEndedOutcomeCouldNotRun || e.Said != "the ask was dropped by n1.mesh-pipeline-runner: its bound passed" {
t.Fatalf("step-ended %+v", e)
}
settledAt(t, m, 1)
})
t.Run("dropped before it was pulled", func(t *testing.T) {
b := newBed()
a, err := b.c.dropAsk("n1.mesh-pipeline-runner", meshwants.DropInput{ID: "ask-5", By: "the runner", Why: "its bound passed"})
if err != nil || a["held"] != false || b.taken.ttls["dropped.ask-5"] != 10*time.Minute {
t.Fatalf("drop answered %v, %v; taken %v", a, err, b.taken.ttls)
}
m := pullOne(b.c, "ask-5", body)
e := ended(t, b)
if e.ID != "ask-5" || e.Outcome != meshwants.StepEndedOutcomeCouldNotRun || e.Said != "the ask was dropped by the runner: its bound passed" {
t.Fatalf("step-ended %+v", e)
}
settledAt(t, m, 1)
if len(b.runs) != 0 {
t.Fatal("a dropped ask ran")
}
if v, _ := b.taken.Get("dropped.ask-5"); v != nil {
t.Fatal("the drop's key stays once its ask ended")
}
})
t.Run("the asks tools", func(t *testing.T) {
taken := newFakeTaken()
_, _ = taken.TakeOnce(meshwants.Seat, "ask-6", time.Minute)
_, _ = taken.RenewTTL("dropped.ask-7", askDrop{By: "the runner", Why: "its bound passed", At: at}, time.Minute)
waiting := func(seat string) (stdio.Waiting, error) {
if seat != meshwants.Seat {
t.Errorf("the waiting asks of %s are read", seat)
}
return stdio.Waiting{Asks: []stdio.WaitingAsk{{ID: "ask-8", Module: "mesh-delivery-pipeline", AgeSeconds: 3},
{ID: "ask-6", Module: "mesh-delivery-pipeline", Again: true}, {ID: "ask-9", Module: "mesh-delivery-pipeline", Again: true}}}, nil
}
var asked []string
ask := func(key string, body any) (json.RawMessage, error) {
raw, _ := json.Marshal(body)
asked = append(asked, key+" "+string(raw))
if strings.HasSuffix(key, "."+meshwants.VerbDrop) {
return json.RawMessage(`{"held":false}`), nil
}
return json.RawMessage(`{}`), nil
}
tools := map[string]stdio.Tool{}
for _, tool := range asksTools(waiting, taken, ask) {
tools[tool.Name] = tool
}
out, err := tools[asksTool].Run(map[string]any{})
a, _ := out.(map[string]any)
w, _ := a["waiting"].([]map[string]any)
d, _ := a["dropped"].([]map[string]any)
if err != nil || len(w) != 3 || w[0]["id"] != "ask-8" || w[0]["state"] != "waiting" || w[1]["state"] != "held" || w[2]["state"] != "waiting again" || !slices.Equal(a["taken"].([]string), []string{"ask-6"}) || len(d) != 1 ||
d[0]["id"] != "ask-7" || d[0]["by"] != "the runner" || a["total"] != 5 || a["capped"] != false {
t.Fatalf("assigner_asks answered %+v, %v", out, err)
}
if _, err := tools[askDropTool].Run(map[string]any{"ask": "ask-8"}); err == nil || len(asked) != 0 {
t.Fatalf("a drop with no why: %v, asked %v", err, asked)
}
out, err = tools[askDropTool].Run(map[string]any{"ask": "ask-8", "why": "stuck"})
if err != nil || len(asked) != 2 || !strings.HasPrefix(asked[0], "seat:mesh-hand-acts.hand-act ") || !strings.Contains(asked[0], askDropTool+" ask-8") ||
!strings.HasPrefix(asked[1], "seat:mesh-wants.drop ") || !strings.Contains(asked[1], `"id":"ask-8"`) || !strings.Contains(asked[1], `"why":"stuck"`) {
t.Fatalf("assigner_ask_drop answered %v, %v; asked %v", out, err, asked)
}
})
}
// Design 47 G §496, A-262: a running composition step says step-progress.<node> on every tick of its ticker, with the ask, its
@@ -80,23 +398,7 @@ func TestARunningCompositionStepSaysItsProgress(t *testing.T) {
stopped := make(chan struct{})
at := time.Date(2026, 11, 12, 9, 0, 0, 0, time.UTC)
release := make(chan struct{})
// A-294: the asker is the one caller mesh-wants' definition lists for step, read from the seat list; none while unread
// or while it lists more than one.
runner := seatdef.Definition{Seat: meshwants.Seat, Accepts: []seatdef.Message{{Name: meshwants.AcceptStep,
Callers: &seatdef.Callers{List: []string{"seat:mesh-pipeline-runner"}}}}}
two := seatdef.Definition{Seat: meshwants.Seat, Accepts: []seatdef.Message{{Name: meshwants.AcceptStep,
Callers: &seatdef.Callers{List: []string{"seat:mesh-pipeline-runner", "seat:mesh-catalog"}}}}}
for _, d := range []struct {
def seatdef.Definition
read bool
want string
}{{runner, true, "mesh-pipeline-runner"}, {runner, false, ""}, {two, true, ""}} {
if got := stepAskerOf(func() (seatdef.Definition, bool) { return d.def, d.read })(); got != d.want {
t.Errorf("the asker of %+v (read %v) = %q, want %q", d.def.Accepts, d.read, got, d.want)
}
}
c := &compositionSteps{node: "n1", say: said.say, now: func() time.Time { return at }, logf: t.Logf,
asker: stepAskerOf(func() (seatdef.Definition, bool) { return runner, true }),
ticks: func(d time.Duration) (<-chan time.Time, func()) {
if d != time.Minute {
t.Errorf("the progress ticks every %s, want a minute", d)
@@ -105,13 +407,16 @@ func TestARunningCompositionStepSaysItsProgress(t *testing.T) {
},
run: func(ctx context.Context, _ string, _ meshwants.StepRun) stepOutcome {
setPhase(ctx, meshwants.StepProgressEventPhaseRun)
setShared(ctx, []meshwants.Shared{{Machine: "n1", Run: "main=2e4.n1", Ask: "run-1"}})
<-release
return stepOutcome{Outcome: meshwants.StepEndedOutcomePassed}
}}
body, _ := json.Marshal(meshwants.StepRun{Pipeline: "main.4.m", Step: meshwants.StepRunStepComposition, Module: "m", Branch: "main"})
if !c.take(context.Background(), "ask-1", body) {
// A11/AC1 (design 47 H §752, H-A-88): with no callers in mesh-wants, the progress names the asker the step run carries.
body, _ := json.Marshal(meshwants.StepRun{Pipeline: "main.4", Step: meshwants.StepRunStepComposition, Module: "m", Branch: "main", Asker: "mesh-pipeline-runner"})
if m := pullOne(c, "ask-1", body); m.terms != 0 {
t.Fatal("the composition step is not taken")
}
<-said.heard // ask-taken, at the pull (H2 §777)
progress := meshwants.EventStepProgress + ".n1"
for range 2 {
tick <- at
@@ -122,7 +427,8 @@ func TestARunningCompositionStepSaysItsProgress(t *testing.T) {
said.mu.Lock()
p, ok := said.said[progress].(meshwants.StepProgressEvent)
said.mu.Unlock()
if !ok || p.Ask != "ask-1" || p.Asker != "mesh-pipeline-runner" || p.Phase != meshwants.StepProgressEventPhaseRun || !p.At.Equal(at) {
if !ok || p.Ask != "ask-1" || p.Asker != "mesh-pipeline-runner" || p.Phase != meshwants.StepProgressEventPhaseRun || !p.At.Equal(at) ||
len(p.Shared) != 1 || p.Shared[0].Ask != "run-1" { // the runs the step waits on (§723)
t.Fatalf("step-progress %+v", p)
}
close(release)
@@ -135,3 +441,70 @@ func TestARunningCompositionStepSaysItsProgress(t *testing.T) {
t.Fatal("the ticker is not stopped when the step has ended")
}
}
// Design 47 G §723, A-469n, A-469z: a superseded or cancelled pipeline's composition step leaves the runs it reads and says no end;
// a run another pipeline's step reads goes on for it; a run left with no reader has its ask dropped and ends could not run, "no
// reader is left", so a later step starts a new run.
func TestASupersededStepLeavesItsRuns(t *testing.T) {
now := time.Date(2026, 11, 17, 12, 0, 0, 0, time.UTC)
r := newCompositionRuns(newRunsMem(), defaultRunSettings, func() time.Time { return now }, t.Logf)
var drops []string
r.drop = func(ask, why string) error { drops = append(drops, ask+": "+why); return nil }
step := func(pipeline string) meshwants.StepRun {
return meshwants.StepRun{Pipeline: pipeline, Step: meshwants.StepRunStepComposition, Module: pipeline, Branch: "main", Revision: 3}
}
said := newSaidEvents()
c := &compositionSteps{node: "n1", say: said.say, now: func() time.Time { return now }, logf: t.Logf,
run: func(ctx context.Context, id string, s meshwants.StepRun) stepOutcome {
j, err := r.join(readerOf(id, s), "main.3", "n1", "run-"+id)
if err != nil {
t.Error(err)
}
r.await(ctx, []string{j.key})
return stepOutcome{Outcome: meshwants.StepEndedOutcomePassed}
}}
body := func(s meshwants.StepRun) []byte { raw, _ := json.Marshal(s); return raw }
for _, p := range []string{"main.3.a", "main.3.b"} {
if m := pullOne(c, "ask-"+p, body(step(p))); m.terms != 0 {
t.Fatal("not taken")
}
}
key := runKeyOf("main.3", "n1")
for {
wake := r.wake()
if run, _, _, _ := r.read(key); len(run.Readers) == 2 {
break
}
<-wake
}
ids, err := r.leave("main.3.a", c.leave)
run, _, _, _ := r.read(key)
if err != nil || !slices.Equal(ids, []string{"ask-main.3.a"}) || run.Ended != nil || len(run.Readers) != 1 || len(drops) != 0 {
t.Fatalf("after a's supersede: %v %v, run %+v, drops %v: want the run going on for b", ids, err, run, drops)
}
_, err = r.leave("main.3.b", c.leave)
run, _, _, _ = r.read(key)
if err != nil || run.Outcome != meshwants.CompositionRunOutcomeCouldNotRun || !strings.Contains(run.Said, "no reader is left") || len(drops) != 1 ||
!strings.HasPrefix(drops[0], run.Ask+": no reader is left") {
t.Fatalf("after b's supersede: %v, run %+v, drops %v", err, run, drops)
}
deadline := time.After(5 * time.Second)
for {
c.mu.Lock()
n := len(c.stops)
c.mu.Unlock()
if n == 0 {
break
}
select {
case <-deadline:
t.Fatal("the steps that left still wait")
case <-time.After(time.Millisecond):
}
}
said.mu.Lock()
defer said.mu.Unlock()
if _, ok := said.said[meshwants.EventStepEnded+".n1"]; ok {
t.Errorf("a step that left says its end: %v", said.said)
}
}
@@ -1,451 +0,0 @@
package main
import (
"context"
"encoding/json"
"fmt"
"slices"
"sort"
"strings"
"sync"
"time"
"github.com/nats-io/nats.go/jetstream"
wd "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshwatchdogs"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/process"
"mesh-delivery-assigner/internal/assign"
"mesh-delivery-assigner/internal/assignment"
"mesh-delivery-assigner/internal/buckets"
)
// A delivery is waited for mesh-wide (design 47 G §376, §389, A-189, A-246). At its start the assigner reads whole, from their first
// message, the streams of the catalog seat's version-released and of its own version-delivered (mesh-sdk process.FromFirst, A-233),
// and the watchman's machine-away and machine-back, never its state; then it hears them. A released version of a module is said
// version-delivered on the seat mesh-wants once, when every present machine placing it on the branch it is released from runs, healthy,
// the want the assigner wrote naming that version; a version no present machine places is not delivered. A dependent whose want
// changes fingerprint waits, by an edge of kind 2, 4 or 6, for its dependency's newest released version not yet said delivered, on
// the branch it is released from; on another branch no version is released and nothing waits. The wait is said wait-held, step
// delivery, bound 60 minutes from the version's release, kept in the state delivery-waits under the dependent's name, and said
// wait-ended when the version is delivered (ran) or released by hand (assigner_release, released).
// deliveryWaitBound is a dependent's delivery wait's bound, from its dependency's version-released.
const deliveryWaitBound = 60 * time.Minute
// Wait-ended's how of a delivery wait.
const (
deliveryWaitRan = "ran"
deliveryWaitReleased = "released"
)
// releaseHeard is one version-released heard: the version, each part's digest, the source revision and when it was said.
type releaseHeard struct {
Version string
Parts map[string]string
Source int64
At time.Time
}
// newestOf is the newest version of module released, the last heard of it in the stream's order.
func (r *releasedVersions) newestOf(module string) (releaseHeard, bool) {
r.mu.Lock()
defer r.mu.Unlock()
h, ok := r.newest[module]
return h, ok
}
// deliveredVersions are the version-delivered said, the assigner's own, by module and version: each is said once.
type deliveredVersions struct {
mu sync.Mutex
said map[string]bool
}
func (d *deliveredVersions) key(module, version string) string { return module + "@" + version }
// put takes one version-delivered in.
func (d *deliveredVersions) put(data []byte) error {
var e meshwants.VersionDeliveredEvent
if err := json.Unmarshal(data, &e); err != nil {
return fmt.Errorf("a version-delivered that is none: %w", err)
}
if e.Module == "" || e.Version == "" {
return fmt.Errorf("a version-delivered naming no module or version: %s", data)
}
d.mark(e.Module, e.Version)
return nil
}
func (d *deliveredVersions) mark(module, version string) {
d.mu.Lock()
defer d.mu.Unlock()
if d.said == nil {
d.said = map[string]bool{}
}
d.said[d.key(module, version)] = true
}
// has says whether version-delivered of module's version was said.
func (d *deliveredVersions) has(module, version string) bool {
d.mu.Lock()
defer d.mu.Unlock()
return d.said[d.key(module, version)]
}
// presenceOf reads one machine-away or machine-back: the machine and when it was said.
func presenceOf(data []byte) (string, time.Time, error) {
var e wd.MachineAwayEvent // machine-back has the same fields
if err := json.Unmarshal(data, &e); err != nil {
return "", time.Time{}, err
}
if e.Machine == "" {
return "", time.Time{}, fmt.Errorf("it names no machine: %s", data)
}
return e.Machine, e.At, nil
}
// hearDelivery reads whole, then follows, the four streams a delivery is judged from: version-released, version-delivered,
// machine-away and machine-back. A stream not heard is said as the assigner's finding, and what it carries is not known until
// the assigner starts again.
func hearDelivery(ctx context.Context, js jetstream.JetStream, w *world, wake func(), findings assign.Findings, logf func(string, ...any)) {
acct := process.Account{Node: thisNode, Module: assignment.Module()}
nh := notHeardWriter(findings, logf)
for _, s := range []struct {
stream, words string
take func([]byte) error
}{
{meshcatalog.StreamVersionReleased, "no want names a released version and no delivery is judged", w.released.put},
{meshwants.StreamVersionDelivered, "a version said delivered before is said again once it is judged", w.delivered.put},
{wd.StreamMachineAway, "no machine is known away, so a delivery waits for a machine that is away", func(data []byte) error {
m, at, err := presenceOf(data)
if err == nil {
w.heardPresence(m, true, at)
}
return err
}},
{wd.StreamMachineBack, "a machine once away is not known back", func(data []byte) error {
m, at, err := presenceOf(data)
if err == nil {
w.heardPresence(m, false, at)
}
return err
}},
} {
take := s.take
cc, err := acct.HearSeatEvents(ctx, js, s.stream, func(m jetstream.Msg) {
if err := take(m.Data()); err != nil {
logf("%s is not kept: %v", m.Subject(), err)
}
if err := m.Ack(); err != nil {
logf("acknowledging %s: %v", m.Subject(), err)
}
wake()
}, logf, process.FromFirst())
if err != nil {
nh.NotHeard(s.stream, s.words+" until the assigner starts again", err)
continue
}
nh.Heard(s.stream)
go func() {
<-ctx.Done()
cc.Stop()
}()
}
}
// releaseBranch is the branch module's versions are released from: the first watched branch of its registration (§371).
func (p *passer) releaseBranch(module string) string {
if p.ends.following() {
return p.ends.branchOf(module, "")
}
return p.w.trunkName()
}
// placing is every machine placing module on the branch its versions are released from, sorted.
func (p *passer) placing(module string) []string {
branch := p.releaseBranch(module)
var out []string
for node, placed := range p.w.placedBranches()[module] {
if p.ends.following() {
placed = p.ends.branchOf(module, placed)
} else {
placed = p.w.trunkName() // the trunk-only form: every placement runs the trunk's
}
if placed == branch {
out = append(out, node)
}
}
sort.Strings(out)
return out
}
// deliveryStanding is where module's version stands: the present placing machines not yet running it healthy as its want names
// it, and the placing machines away.
func (p *passer) deliveryStanding(module, version string) (notRunning, away []string, placing int) {
gone := p.w.awayNow()
n := assign.Nodes{Running: p.w.runningNow()}
wanted := p.w.wantsOf()[module]
nodes := p.placing(module)
for _, node := range nodes {
if gone[node] {
away = append(away, node)
continue
}
want, ok := wanted[node]
if !ok || want.Removed || want.Version != version || !n.RunsHealthy(node, module, want.Fp) {
notRunning = append(notRunning, node)
}
}
return notRunning, away, len(nodes)
}
// judgeDelivered says version-delivered of each module's newest released version not said yet, once every present machine placing
// it runs it healthy; judged again at each pass, which each running, machine-away, machine-back and placement change wakes.
func (p *passer) judgeDelivered() {
for _, module := range p.releasedModules() {
rel, _ := p.w.released.newestOf(module)
if p.w.delivered.has(module, rel.Version) {
continue
}
notRunning, away, placing := p.deliveryStanding(module, rel.Version)
if placing == 0 || len(away) == placing || len(notRunning) > 0 {
continue
}
if err := p.sayDelivered(module, rel, away); err != nil {
p.logf("version-delivered of %s %s is not said, and is judged again at the next pass: %v", module, rel.Version, err)
}
}
}
// sayDelivered says version-delivered of module's release rel, with the machines away, and keeps it said.
func (p *passer) sayDelivered(module string, rel releaseHeard, away []string) error {
at := p.clock().UTC()
body := meshwants.VersionDeliveredEvent{V: keys.Version, Module: module, Version: rel.Version, Parts: rel.Parts, Away: away, At: &at}
if err := p.wantsSay(meshwants.EventVersionDelivered, body, fmt.Sprintf("%s.%s.%s.%s", meshwants.EventVersionDelivered, module, rel.Version, at.Format(time.RFC3339Nano))); err != nil {
return err
}
p.w.delivered.mark(module, rel.Version)
return nil
}
// releasedModules is every module a version-released was heard of, sorted.
func (p *passer) releasedModules() []string {
r := &p.w.released
r.mu.Lock()
defer r.mu.Unlock()
out := make([]string, 0, len(r.newest))
for m := range r.newest {
out = append(out, m)
}
sort.Strings(out)
return out
}
// deliveryWait is what a dependent waits for: its dependency, the version and the machines not yet running it.
type deliveryWait struct {
dependency string
rel releaseHeard
notRunning []string
away []string
}
// waitsForDelivery says whether module, whose want on its nodes changes to fp on branch, waits for a dependency's delivery: by
// each edge of kind 2, 4 or 6 into it in branch's catalog half, the dependency's newest released version on branch not yet said
// delivered. A want that changes no fingerprint waits for nothing; on a branch no version is released from, nothing waits.
func (p *passer) waitsForDelivery(module, fp, branch string, nodes []string) (deliveryWait, bool) {
wanted := p.w.wantsOf()[module]
changes := false
for _, node := range nodes {
if w, ok := wanted[node]; !ok || w.Removed || w.Fp != fp {
changes = true
}
}
if !changes || fp == "" {
return deliveryWait{}, false
}
var deps []string
for _, e := range p.w.edgesOf(branch, module) {
if e.Kind != 2 && e.Kind != 4 && e.Kind != 6 {
continue
}
dep, _, _ := strings.Cut(e.From, ":")
if dep != "" && dep != module && !slices.Contains(deps, dep) {
deps = append(deps, dep)
}
}
sort.Strings(deps)
for _, dep := range deps {
if p.releaseBranch(dep) != branch {
continue
}
rel, ok := p.w.released.newestOf(dep)
if !ok || p.w.delivered.has(dep, rel.Version) {
continue
}
notRunning, away, _ := p.deliveryStanding(dep, rel.Version)
return deliveryWait{dependency: dep, rel: rel, notRunning: notRunning, away: away}, true
}
return deliveryWait{}, false
}
// words is a delivery wait in plain words, as assigner_why_not and the status view say it.
func (d deliveryWait) words() string {
if len(d.notRunning) == 0 && len(d.away) > 0 {
return fmt.Sprintf("waiting for %s to be back", strings.Join(d.away, ", "))
}
return fmt.Sprintf("waiting for delivery of %s %s on %s", d.dependency, d.rel.Version, strings.Join(d.notRunning, ", "))
}
// deliveryWaitBody is the wait-held of module's delivery wait d.
func deliveryWaitBody(module, fp string, d deliveryWait, since time.Time) meshwants.Wait {
from := d.rel.At.UTC()
if from.IsZero() {
from = since.UTC()
}
return meshwants.Wait{Step: meshwants.WaitStepDelivery, Owner: meshwants.Seat, Module: module, Version: fp, Part: d.dependency,
On: d.dependency + "@" + d.rel.Version, Machines: d.notRunning, Since: since.UTC(), ClockFrom: &from, Bound: deliveryWaitBound.String(),
Words: d.words()}
}
// deliveryWaiting is one delivery wait the state delivery-waits keeps, by its dependent's name: the wait-held said, and a release
// by hand written by assigner_release.
type deliveryWaiting struct {
meshwants.Wait
// Released is set by assigner_release: the wait ends released and the dependent's want is written.
Released bool `json:"released,omitempty"`
}
// saidDeliveryWaits is every delivery wait the state delivery-waits holds, by module; a value that does not decode is said and left.
func (p *passer) saidDeliveryWaits() map[string]deliveryWaiting {
out := map[string]deliveryWaiting{}
for key, value := range p.w.read(buckets.DeliveryWaits()) {
var w deliveryWaiting
if err := json.Unmarshal(value, &w); err != nil || w.Module == "" {
p.logf("%s %s holds no delivery wait, left: %v", buckets.DeliveryWaits(), key, err)
continue
}
out[w.Module] = w
}
return out
}
// holdForDelivery says whether module's want, changing to fp on branch, is held for a dependency's delivery this pass: it says
// wait-held once and keeps it; a wait released by hand holds nothing; a wait that no longer holds is ended ran.
func (p *passer) holdForDelivery(ctx context.Context, module, fp, branch string, nodes []string) bool {
if p.kvs[buckets.DeliveryWaits()] == nil {
return false
}
key := keys.EscapeName(module)
said, was := p.saidDeliveryWaits()[module]
d, waits := p.waitsForDelivery(module, fp, branch, nodes)
switch {
case was && said.Released:
p.endDeliveryWait(ctx, key, said, deliveryWaitReleased) // the want is written now, so it changes nothing at the next pass
return false
case !waits:
if was {
p.endDeliveryWait(ctx, key, said, deliveryWaitRan)
}
return false
}
body := deliveryWaitBody(module, fp, d, p.clock())
if was && said.On == body.On && said.Version == fp && slices.Equal(said.Machines, body.Machines) {
return true
}
if was {
body.Since = said.Since
}
id := fmt.Sprintf("%s.delivery.%s.%s.%s", key, fp, body.On, strings.Join(body.Machines, ","))
if err := p.wantsSay(meshwants.EventWaitHeld, body, id); err != nil {
p.logf("the delivery wait of %s is not said, and is said at the next pass: %v", module, err)
return true
}
kept := deliveryWaiting{Wait: body}
p.put(ctx, buckets.DeliveryWaits(), key, func() ([]byte, error) { return json.Marshal(kept) })
return true
}
// endDeliveryWait says wait-ended of a delivery wait with how and removes it from the state.
func (p *passer) endDeliveryWait(ctx context.Context, key string, w deliveryWaiting, how string) {
body := w.Wait
body.How = how
if err := p.wantsSay(meshwants.EventWaitEnded, body, key+".delivery."+body.Version+"."+how); err != nil {
p.logf("the end of the delivery wait of %s is not said, and is said at the next pass: %v", w.Module, err)
return
}
p.remove(ctx, buckets.DeliveryWaits(), key)
}
// againAsk is one ask of assigner_delivered_again, kept in the state delivered-again under its module (A-250): the version to say
// delivered again, who asked and why, and, while it does not hold, why not.
type againAsk struct {
Module string `json:"module"`
Version string `json:"version"`
By string `json:"by"`
Why string `json:"why"`
Waits string `json:"waits,omitempty"`
}
// releaseOf is the release heard of module's version.
func (r *releasedVersions) releaseOf(module, version string) (releaseHeard, bool) {
r.mu.Lock()
defer r.mu.Unlock()
if h, ok := r.newest[module]; ok && h.Version == version {
return h, true
}
for key, k := range r.seen {
if strings.HasPrefix(key, module+"@") && k.Version == version {
return releaseHeard{Version: version, Parts: k.Parts}, true
}
}
return releaseHeard{}, false
}
// deliveredAgain takes each ask of assigner_delivered_again, heard at once through the watch of the state delivered-again: it says
// version-delivered again when every present machine placing the module runs that version healthy and removes the ask, else keeps
// it with why it does not hold, which assigner_waits reads.
func (p *passer) deliveredAgain(ctx context.Context) {
if p.kvs[buckets.DeliveredAgain()] == nil {
return
}
for key, value := range p.w.read(buckets.DeliveredAgain()) {
var a againAsk
if err := json.Unmarshal(value, &a); err != nil || a.Version == "" {
p.logf("%s %s holds no ask, left: %v", buckets.DeliveredAgain(), key, err)
continue
}
module := a.Module
if module == "" {
module = key
}
waits := ""
rel, ok := p.w.released.releaseOf(module, a.Version)
notRunning, away, placing := p.deliveryStanding(module, a.Version)
switch {
case !ok:
waits = fmt.Sprintf("no version-released of %s %s is heard", module, a.Version)
case placing == 0:
waits = fmt.Sprintf("no machine places %s", module)
case len(away) == placing:
waits = fmt.Sprintf("every machine placing %s is away: %s", module, strings.Join(away, ", "))
case len(notRunning) > 0:
waits = fmt.Sprintf("%s %s does not run healthy on %s", module, a.Version, strings.Join(notRunning, ", "))
}
if waits == "" {
if err := p.sayDelivered(module, rel, away); err != nil {
p.logf("version-delivered of %s %s asked again is not said, and is asked at the next pass: %v", module, a.Version, err)
continue
}
p.logf("version-delivered of %s %s said again, asked by %s: %s", module, a.Version, a.By, a.Why)
p.remove(ctx, buckets.DeliveredAgain(), key)
continue
}
if a.Waits != waits {
a.Waits = waits
p.put(ctx, buckets.DeliveredAgain(), key, func() ([]byte, error) { return json.Marshal(a) })
}
}
}
@@ -1,188 +0,0 @@
package main
import (
"context"
"encoding/json"
"strings"
"testing"
"time"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
mwc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"mesh-delivery-assigner/internal/buckets"
)
// Design 47 G §376, §389, §498, A-189, A-246: a released version is said version-delivered once, when every present machine placing
// it runs healthy the want naming it, a machine away named and not waited for, none when every placing machine is away; a dependent
// whose want changes fingerprint waits by an edge of kind 2, 4 or 6 for its dependency's newest released version not yet said
// delivered, said wait-held (step delivery, 60 minutes from the release) once and kept in delivery-waits, and wait-ended ran once
// the version is delivered; a kind-1 edge, or a dependency with no version released, waits for nothing; one released by hand ends
// released and its want is written.
func TestADependentWaitsForItsDependencysDelivery(t *testing.T) {
ctx := context.Background()
at := time.Date(2026, 11, 12, 9, 0, 0, 0, time.UTC)
waits := &memKV{values: map[string][]byte{}}
again := &memKV{values: map[string][]byte{}}
p := newPasser(kvSet{buckets.Wants(): &memKV{values: map[string][]byte{}}, buckets.DeliveryWaits(): waits, buckets.DeliveredAgain(): again}, at)
p.logf = t.Logf
var events []said
p.publishWants = func(event string, body any, id string) error {
raw, _ := json.Marshal(body)
events = append(events, said{event, id, raw})
return nil
}
p.w.runningHeard = true
placeOn(t, p.w, "ace", "db", "app")
placeOn(t, p.w, "g14", "db")
fp := func(c string) string { return meshcatalogclient.SourcePrefix2 + strings.Repeat(c, 64) }
want := func(node, module, fp, version string) {
key, _ := mwc.WantKey(node, module)
raw, err := mwc.EncodeWant(mwc.Want{Fp: fp, Version: version, Self: true})
if err != nil {
t.Fatal(err)
}
p.w.put(buckets.Wants(), key, raw)
}
runs := func(node, module, fp string) {
raw, _ := json.Marshal(map[string]any{"v": 1, "node": node, "module": module, "fingerprint": fp, "at": at})
if err := p.w.hearRunning("running", raw); err != nil {
t.Fatal(err)
}
}
source := int64(3)
release := func(module, version string) {
source++
raw, _ := json.Marshal(meshcatalog.VersionReleasedEvent{V: 1, Module: module, Version: version, Source: source, At: &at,
Artifacts: []meshcatalog.VersionArtifact{{Artifact: "program", Digest: "sha256:d"}}})
if err := p.w.released.put(raw); err != nil {
t.Fatal(err)
}
}
saidOf := func(event string) []said {
var out []said
for _, e := range events {
if e.event == event {
out = append(out, e)
}
}
return out
}
want("ace", "app", fp("1"), "")
// No version of db is released: app's new fingerprint waits for nothing.
p.w.putEdges(trunkBranch, "app", []meshcatalog.Edge{{Kind: 4, From: "db:program", To: "app:program"}})
if p.holdForDelivery(ctx, "app", fp("2"), trunkBranch, []string{"ace"}) {
t.Fatal("app waits with no version of db released")
}
release("db", "1.1.0")
want("ace", "db", fp("d"), "1.1.0")
want("g14", "db", fp("d"), "1.1.0")
runs("ace", "db", fp("d"))
// A kind-1 edge orders nothing.
p.w.putEdges(trunkBranch, "app", []meshcatalog.Edge{{Kind: 1, From: "db:program", To: "app:program"}})
if p.holdForDelivery(ctx, "app", fp("2"), trunkBranch, []string{"ace"}) {
t.Fatal("a kind-1 edge holds app")
}
p.w.putEdges(trunkBranch, "app", []meshcatalog.Edge{{Kind: 4, From: "db:program", To: "app:program"}})
// app's want unchanged waits for nothing.
if p.holdForDelivery(ctx, "app", fp("1"), trunkBranch, []string{"ace"}) {
t.Fatal("app's unchanged want waits")
}
// g14 places db and does not run 1.1.0 yet: not delivered, and app's new version waits, said once.
p.judgeDelivered()
if !p.holdForDelivery(ctx, "app", fp("2"), trunkBranch, []string{"ace"}) || !p.holdForDelivery(ctx, "app", fp("2"), trunkBranch, []string{"ace"}) {
t.Fatal("app does not wait for db 1.1.0")
}
if len(saidOf(meshwants.EventVersionDelivered)) != 0 {
t.Fatalf("db is said delivered while g14 does not run it: %+v", events)
}
held := saidOf(meshwants.EventWaitHeld)
if len(held) != 1 {
t.Fatalf("wait-held said %d times, want once", len(held))
}
var w meshwants.Wait
_ = json.Unmarshal(held[0].body, &w)
if w.Step != meshwants.WaitStepDelivery || w.Part != "db" || w.Module != "app" || w.Version != fp("2") || w.Bound != "1h0m0s" ||
w.ClockFrom == nil || !w.ClockFrom.Equal(at) || len(w.Machines) != 1 || w.Machines[0] != "g14" || w.Words != "waiting for delivery of db 1.1.0 on g14" {
t.Errorf("the wait said is %+v", w)
}
if _, ok := waits.values["app"]; !ok {
t.Errorf("the wait is not kept in delivery-waits: %v", waits.values)
}
// g14 away: every present machine runs it, so it is delivered, g14 named away; once only.
p.w.heardPresence("g14", true, at)
p.judgeDelivered()
p.judgeDelivered()
delivered := saidOf(meshwants.EventVersionDelivered)
var d meshwants.VersionDeliveredEvent
if len(delivered) != 1 || json.Unmarshal(delivered[0].body, &d) != nil || d.Module != "db" || d.Version != "1.1.0" ||
len(d.Away) != 1 || d.Away[0] != "g14" || d.Parts["db:program"] != "sha256:d" {
t.Fatalf("version-delivered said %+v", delivered)
}
// The wait ends ran, and app's want goes on.
if p.holdForDelivery(ctx, "app", fp("2"), trunkBranch, []string{"ace"}) {
t.Fatal("app still waits once db 1.1.0 is delivered")
}
ended := saidOf(meshwants.EventWaitEnded)
if len(ended) != 1 || json.Unmarshal(ended[0].body, &w) != nil || w.How != deliveryWaitRan {
t.Errorf("wait-ended said %+v", ended)
}
if _, ok := waits.values["app"]; ok {
t.Error("the ended wait is kept")
}
// A newer release with every placing machine away is not delivered, and its wait says the machines it waits to be back.
release("db", "1.2.0")
p.w.heardPresence("ace", true, at)
p.judgeDelivered()
if len(saidOf(meshwants.EventVersionDelivered)) != 1 {
t.Error("a version is said delivered while every placing machine is away")
}
if !p.holdForDelivery(ctx, "app", fp("3"), trunkBranch, []string{"ace"}) {
t.Fatal("app does not wait for db 1.2.0")
}
held = saidOf(meshwants.EventWaitHeld)
if json.Unmarshal(held[len(held)-1].body, &w) != nil || w.Words != "waiting for ace, g14 to be back" {
t.Errorf("the wait while every machine is away says %q", w.Words)
}
// Released by hand (assigner_release writes it): the wait ends released and app's want is written.
var kept deliveryWaiting
_ = json.Unmarshal(waits.values["app"], &kept)
kept.Released = true
raw, _ := json.Marshal(kept)
p.w.put(buckets.DeliveryWaits(), "app", raw)
if p.holdForDelivery(ctx, "app", fp("3"), trunkBranch, []string{"ace"}) {
t.Fatal("a released wait holds app")
}
ended = saidOf(meshwants.EventWaitEnded)
if json.Unmarshal(ended[len(ended)-1].body, &w) != nil || w.How != deliveryWaitReleased {
t.Errorf("the released wait ended %+v", w)
}
// Presence: the later of machine-away and machine-back holds, whichever stream is read first.
p.w.heardPresence("ace", false, at.Add(time.Minute))
p.w.heardPresence("ace", true, at)
if p.w.awayNow()["ace"] || !p.w.online()["ace"] {
t.Error("an older machine-away read after a newer machine-back leaves ace away")
}
// A-250: an ask of assigner_delivered_again of 1.1.0, which ace (present) runs and g14 (away) does not, is said again and taken
// away; one of 1.2.0, which no machine runs, is kept with why.
ask := func(version string) {
raw, _ := json.Marshal(againAsk{Module: "db", Version: version, By: "op", Why: "the catalog missed it"})
p.w.put(buckets.DeliveredAgain(), "db", raw)
}
before := len(saidOf(meshwants.EventVersionDelivered))
ask("1.1.0")
p.deliveredAgain(ctx)
if len(saidOf(meshwants.EventVersionDelivered)) != before+1 || p.w.has(buckets.DeliveredAgain(), "db") {
t.Errorf("the ask of 1.1.0 said %d version-delivered and is kept %v", len(saidOf(meshwants.EventVersionDelivered))-before, p.w.has(buckets.DeliveredAgain(), "db"))
}
ask("1.2.0")
p.deliveredAgain(ctx)
var a againAsk
if json.Unmarshal(p.w.value(buckets.DeliveredAgain(), "db"), &a) != nil || a.Waits != "db 1.2.0 does not run healthy on ace" ||
len(saidOf(meshwants.EventVersionDelivered)) != before+1 {
t.Errorf("the ask of 1.2.0 = %+v", a)
}
}
@@ -0,0 +1,153 @@
package main
import (
"encoding/json"
"errors"
"fmt"
"maps"
"slices"
"sync"
"time"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
stdio "git.novox.be/novox/mesh-sdk/go"
)
// engineWords is one node's key of the assigner's state engine-reads (design 47 H-A-104): the words its node-engine said it
// reads in the last manifest-reads-changed the assigner heard of it, and when the engine said them.
type engineWords struct {
Words []string `json:"words"`
At time.Time `json:"at"`
}
// engineReadsKept is what the assigner holds of its state engine-reads (design 47 H-A-104, §772): written when it hears the
// node-engine seat's manifest-reads-changed, and read back from the state's watch at the start, so a restart loses no node's
// words; no verb is asked and no node's record is read in its place.
type engineReadsKept struct {
mu sync.Mutex
by map[string]engineWords
// put writes one node's key; nil keeps the words in memory only (the state could not be opened).
put func(node string, value []byte) error
// changed wakes a pass when a node's words changed; nil wakes nothing.
changed func()
}
// heard keeps what one manifest-reads-changed says of its node: written into the state first, then held.
func (k *engineReadsKept) heard(e nodeengine.ManifestReadsChangedEvent) error {
at, err := time.Parse(time.RFC3339Nano, e.At)
if err != nil {
return fmt.Errorf("at %q is no RFC 3339 time", e.At)
}
v := engineWords{Words: slices.Clone(e.ManifestReads), At: at}
if k.put != nil {
raw, err := json.Marshal(v)
if err != nil {
return err
}
if err := k.put(e.Node, raw); err != nil {
return fmt.Errorf("the words of %s are not written into the state engine-reads: %w", e.Node, err)
}
}
k.hold(e.Node, v, false)
return nil
}
// take takes in one key of the state as its watch hands it: at the start every node's words, later the assigner's own writes
// (which change nothing) and a key dropped.
func (k *engineReadsKept) take(node string, raw []byte, deleted bool) error {
if deleted {
k.hold(node, engineWords{}, true)
return nil
}
var v engineWords
if err := json.Unmarshal(raw, &v); err != nil {
return fmt.Errorf("the key %s of the state engine-reads does not read: %w", node, err)
}
k.hold(node, v, false)
return nil
}
// hold sets one node's words, waking a pass when they changed.
func (k *engineReadsKept) hold(node string, v engineWords, deleted bool) {
k.mu.Lock()
old, had := k.by[node]
switch {
case deleted:
delete(k.by, node)
default:
if k.by == nil {
k.by = map[string]engineWords{}
}
k.by[node] = v
}
changed := (had && deleted) || (!deleted && (!had || !old.At.Equal(v.At) || !slices.Equal(old.Words, v.Words)))
k.mu.Unlock()
if changed && k.changed != nil {
k.changed()
}
}
// words is what node's engine said it reads, and whether the assigner holds its key; nil k holds none.
func (k *engineReadsKept) words(node string) ([]string, bool) {
if k == nil {
return nil, false
}
k.mu.Lock()
defer k.mu.Unlock()
v, ok := k.by[node]
return slices.Clone(v.Words), ok
}
// nodes is every node whose key the assigner holds, sorted.
func (k *engineReadsKept) nodes() []string {
if k == nil {
return nil
}
k.mu.Lock()
defer k.mu.Unlock()
return slices.Sorted(maps.Keys(k.by))
}
// engineReadsTool lists the assigner's state engine-reads: what each node's node-engine said it reads, and when.
const engineReadsTool = "assigner_engine_reads"
// readEngineReads is the state engine-reads, every node's key or node's alone.
func readEngineReads(st store, node string) (any, error) {
keys := []string{node}
if node == "" {
var err error
if keys, err = st.keys(engineReadsState); err != nil {
return nil, err
}
slices.Sort(keys)
}
out := map[string]engineWords{}
for _, key := range keys {
raw, _, found, err := st.get(engineReadsState, key)
if err != nil {
return nil, err
}
if !found {
if node != "" {
return nil, fmt.Errorf("the assigner holds no words of %s: its node-engine said no %s it heard", node, nodeengine.EventManifestReadsChanged)
}
continue
}
var v engineWords
if err := json.Unmarshal(raw, &v); err != nil {
return nil, errors.Join(fmt.Errorf("the key %s does not read", key), err)
}
out[key] = v
}
return map[string]any{"nodes": out}, nil
}
// engineReadsTools is the tool over the runtime's state.
func engineReadsTools(st store) []stdio.Tool {
return []stdio.Tool{{Name: engineReadsTool, Description: "What each node's node-engine says it reads of a manifest, as the " +
"assigner keeps it in its state engine-reads (design 47 H-A-104): per node the words of the last manifest-reads-changed " +
"it heard and when the engine said them. A node with no key states nothing the assigner heard, so its wants are held " +
"awaiting its hand placement (§772). With node, that node's key alone.",
Input: schema(map[string]string{"node": "one node; every node when left out"}, nil),
Run: func(a map[string]any) (any, error) { return readEngineReads(st, arg(a, "node")) }}}
}
@@ -15,7 +15,21 @@ import (
// fillOf is the store's fill now: its bytes and cap, when the bucket says them and has a cap.
func (g *graphKeeper) fillOf(ctx context.Context) (used, capacity int64, ok bool) {
f, is := g.objects.(assigngraph.Filler)
return fillIn(ctx, g.objects)
}
// passObjects is the store as the pass reads its fill: a handle of its own where one is given, so the pass's read never shares one
// with a keeping that runs beside it (design 47 H-A-261).
func (g *graphKeeper) passObjects() assigngraph.Objects {
if g.reads != nil {
return g.reads
}
return g.objects
}
// fillIn is the fill of the bucket o, when it says one and has a cap.
func fillIn(ctx context.Context, o assigngraph.Objects) (used, capacity int64, ok bool) {
f, is := o.(assigngraph.Filler)
if !is {
return 0, 0, false
}
@@ -35,13 +49,13 @@ func (p *passer) sayFill(event, about string, used, capacity int64, refused stri
// its cap), so a fill reached while the process was down is said too.
func (p *passer) fillAtStart(ctx context.Context) {
g := p.graph
used, capacity, ok := g.fillOf(ctx)
used, capacity, ok := fillIn(ctx, g.passObjects())
if !ok {
return
}
switch {
case used >= capacity:
g.full = true
g.setFull(true)
p.sayFill(meshwants.EventFull, "start", used, capacity, "the next revision")
case used*5 >= capacity*4:
p.sayFill(meshwants.EventFilling, "start", used, capacity, "")
@@ -52,20 +66,20 @@ func (p *passer) fillAtStart(ctx context.Context) {
// 80 % again. It answers true while the store is full.
func (p *passer) fullBefore(ctx context.Context, c assigngraph.Computed) bool {
g := p.graph
used, capacity, ok := g.fillOf(ctx)
used, capacity, ok := fillIn(ctx, g.passObjects())
if !ok {
return false
}
if g.full && used*5 < capacity*4 {
g.full = false
if g.isFull() && used*5 < capacity*4 {
g.setFull(false)
p.sayFill(meshwants.EventRoom, fmt.Sprint(used), used, capacity, "")
}
if used+assigngraph.NewBytes(ctx, g.objects, c) <= capacity {
g.full = false
if used+assigngraph.NewBytes(ctx, g.passObjects(), c) <= capacity {
g.setFull(false)
return false
}
if !g.full {
g.full = true
if !g.isFull() {
g.setFull(true)
p.sayFill(meshwants.EventFull, fmt.Sprint(used), used, capacity, "the next revision")
}
p.logf("the assignment graph revision is not kept: %s is full (%d of %d bytes), the last revision stays and no want is written until there is room", assigngraph.RevisionsObjects, used, capacity)
@@ -61,14 +61,14 @@ func TestTheAssignmentGraphStoreSaysFillingFullAndRoom(t *testing.T) {
if len(events) != 0 {
t.Fatalf("events %v", events)
}
o.base = 700
o.base, o.cap = 8500, 10000 // past 80 %, with room for the next revision, which the pass judges itself (H-A-261)
p.graph.started = false
p.keepGraph(ctx)
p.keepGraph(ctx) // a start again: its first pass judges the fill
if len(events) != 1 || events[0] != meshwants.EventFilling {
t.Fatalf("at the start past 80 %%: %v", events)
}
c := assigngraph.Computed{Revision: meshwants.AssignmentRevision{Entries: []meshwants.NodeEntryRef{}}}
o.base = 990
o.base, o.cap = 990, 1000
if !p.fullBefore(ctx, c) || !p.graph.full || events[len(events)-1] != meshwants.EventFull {
t.Fatalf("a revision that does not fit: events %v", events)
}
@@ -76,8 +76,15 @@ func TestTheAssignmentGraphStoreSaysFillingFullAndRoom(t *testing.T) {
if n := len(events); n != 2 {
t.Errorf("full is said once: %v", events)
}
// H-A-261: the verdict is the pass's own: with the store full the pass writes no want, though a revision is kept.
if held := p.keepGraph(ctx); held != heldFull {
t.Errorf("a pass with the store full answers %q, want %q", held, heldFull)
}
o.base = 100
if p.fullBefore(ctx, c) || p.graph.full || events[len(events)-1] != meshwants.EventRoom {
t.Errorf("room: events %v", events)
}
if held := p.keepGraph(ctx); held != "" {
t.Errorf("a pass with room and a revision kept answers %q, want the wants written", held)
}
}
@@ -5,18 +5,25 @@ import (
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"maps"
"slices"
"strings"
"sync"
"time"
mcc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
mcc "git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshconditionsclient"
mcseat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
mcatc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/process"
"git.novox.be/novox/mesh-sdk/go/views"
"mesh-delivery-assigner/internal/assign"
"mesh-delivery-assigner/internal/assigngraph"
"mesh-delivery-assigner/internal/assignment"
)
// graphKeeper is the pass's assignment graph (design 47 G §292, A-67): per catalog revision taken in it computes the revision
@@ -25,83 +32,288 @@ import (
// that follows are written from the revision it holds.
type graphKeeper struct {
objects assigngraph.Objects
// reads is the same store through a handle of the pass's own, for the pass's read of its fill (graphfill.go); nil reads objects.
reads assigngraph.Objects
// halves is every followed branch's catalog graph revision held now.
halves func() map[string]mcc.Half
// last is the revision last computed, so a pass whose inputs did not change keeps and says nothing.
last meshwants.AssignmentRevision
has bool
halves func() map[string]mcatc.Half
// mu guards what the keeping writes and the pass reads: the revision kept, full, and the need handed over (design 47 H-A-259).
mu sync.Mutex
// handedRev is the revision last handed to the keeping, so a pass whose inputs did not change hands nothing; handed is false
// until one is, and again when its keeping failed or found the store full, so the next pass hands it again.
handedRev meshwants.AssignmentRevision
handed bool
// handedOnce says a revision was handed: the first carries the start's removal (H-A-261).
handedOnce bool
// kept is the revision the wants follow, and kept's source the trunk's source revision it carries; ok is false until one is kept.
kept meshwants.AssignmentRevision
source int64
ok bool
said string
// cycled is the cycles last said (assigngraph.Cycles).
cycled string
// full says the next revision did not fit the store, so no want is written (graphfill.go); started says the first pass judged the fill.
full, started bool
// pins removes a revision that ceased to be current once nothing pins it (pins.go); nil keeps every revision.
pins *pinKeeper
// computed is the revision computed by the last pass, with its entries: the edges the wants wait on (actingwaits.go).
computed assigngraph.Computed
// revisions removes a revision that ceased to be current (revisions.go, H-A-86); nil keeps every revision.
revisions *revisionRemover
// computed is the revision computed by the last pass, with its entries: its edges; hasComputed says a pass computed one.
computed assigngraph.Computed
hasComputed bool
// keepMu runs one keeping at a time, the pass's (keepOne) or one by hand (keepNow).
keepMu sync.Mutex
// The keeping off the pass loop (H-A-259): need is what waits to be kept, keeping says one runs; background runs it (nil: at
// once, in the caller), and wake makes a pass once a keeping changed what the pass reads.
need *keepNeed
keeping bool
background func(func())
wake func()
// A keeping that fails runs again after retry, keeping-retry, by after (time.AfterFunc; a test hands its own); failures
// counts the failures in a row, and keeping-failed is raised at the third (design 47 H2 §813 (2)).
retry time.Duration
after func(d time.Duration, f func())
failures int
}
// keepGraph computes the revision of this pass and keeps it when the pass's inputs differ from the last computed.
func (p *passer) keepGraph(ctx context.Context) {
// The keeping's setting and finding (design 47 H2 §813 (2); ADR 0682 §11: the holder's own deadline).
const (
keepingRetrySetting = "keeping-retry"
defaultKeepingRetry = 30 * time.Second
kindKeepingFailed = "keeping-failed"
// keepingFailedAt is the failures in a row that raise keeping-failed.
keepingFailedAt = 3
)
// keepingRetry reads the setting keeping-retry (§781).
func keepingRetry() (time.Duration, error) {
d, err := stdio.SettingDuration(keepingRetrySetting, defaultKeepingRetry)
if err != nil {
return 0, errors.New("the assigner's " + err.Error())
}
return d, nil
}
// keepNeed is one need of the keeping: a computed revision to keep (nil: none), and whether the revisions not current are judged.
type keepNeed struct {
c *assigngraph.Computed
judge bool
}
// keptNow is the revision the wants follow, with its trunk source, and whether one is kept.
func (g *graphKeeper) keptNow() (meshwants.AssignmentRevision, int64, bool) {
g.mu.Lock()
defer g.mu.Unlock()
return g.kept, g.source, g.ok
}
// isFull says the store did not hold the last revision handed over, so no want is written (design 47 G §181).
func (g *graphKeeper) isFull() bool {
g.mu.Lock()
defer g.mu.Unlock()
return g.full
}
func (g *graphKeeper) setFull(full bool) {
g.mu.Lock()
g.full = full
g.mu.Unlock()
}
// heldNoRevision is the pass's words while no assignment graph revision is kept: it writes no want (design 47 H-A-261).
const heldNoRevision = "held: no assignment graph revision is kept yet, so no want is written until the first keeping ends (H-A-261)"
// heldFull is the pass's words while the next revision does not fit its store (design 47 G §181).
const heldFull = "the assignment graph store is full: no want is written (design 47 G §181)"
// keepGraph computes the revision of this pass, judges the store's fill itself, and hands the revision to the keeping when the
// pass's inputs differ from the last handed. The keeping and the removing of revisions run off the pass loop, one at a time, and the
// pass never waits on them: it judges and writes the wants from the graph it holds (design 47 H-A-259). It answers why the pass
// writes no want, or "" when it writes them: none while the next revision does not fit the store (G §181), and none while no
// revision is kept (H-A-261), whose keeping wakes a pass when it ends.
func (p *passer) keepGraph(ctx context.Context) string {
g := p.graph
if g == nil || g.objects == nil || g.halves == nil {
return
return ""
}
c := assigngraph.Compute(p.graphInputs())
g.computed = c
if p.ends != nil {
p.ends.setRunner(assigngraph.Runner(slices.Collect(maps.Values(c.Entries)))) // the runner's member of a group goes first (A-334)
}
g.mu.Lock()
g.computed, g.hasComputed = c, true
g.mu.Unlock()
for _, u := range c.Uncomputed {
if g.said != u {
g.said = u
p.logf("the assignment graph leaves out %s", u)
}
}
if cycles := strings.Join(c.Cycles, "; "); cycles != g.cycled {
g.cycled = cycles
if cycles != "" {
p.logf("the assignment graph holds a cycle among the acting waits, within one step or across steps: %s", cycles)
}
}
if !g.started {
if !g.started { // the first pass judges the fill once (graphfill.go)
g.started = true
p.fillAtStart(ctx)
}
if g.has && g.ok && assigngraph.Same(g.last, c.Revision) {
return
}
used, _, _ := g.fillOf(ctx)
if p.fullBefore(ctx, c) {
return
g.mu.Lock()
g.handed = false // handed once it fits
g.mu.Unlock()
return heldFull
}
rev, fresh, err := assigngraph.Keep(ctx, g.objects, c, meshwants.EventAssignmentRevision, p.clock())
if err != nil {
p.logf("the assignment graph revision is not kept, so no want is said as wanted until it is: %v", err)
return
g.mu.Lock()
same := g.handed && assigngraph.Same(g.handedRev, c.Revision)
first := !g.handedOnce
if !same {
g.handedRev, g.handed, g.handedOnce = c.Revision, true, true
}
g.last, g.has, g.kept, g.ok = c.Revision, true, rev, true
g.source = 0
for _, cat := range rev.Catalogs {
if cat.Branch == p.w.trunkName() {
g.source = cat.Source
g.mu.Unlock()
if !same {
// The start's removal of the revisions not current folds into the first keeping: it keeps the first pass's revision, then
// removes (H-A-261).
p.needKeeping(ctx, keepNeed{c: &c, judge: first})
}
if _, _, ok := g.keptNow(); !ok {
return heldNoRevision
}
return ""
}
// needKeeping hands a need to the keeping: one keeping runs at a time, and a need that comes while one runs is folded into the one
// that waits (the newest revision, and a judging asked by either), so it runs once more (design 47 H-A-259).
func (p *passer) needKeeping(ctx context.Context, n keepNeed) {
g := p.graph
g.mu.Lock()
if w := g.need; w != nil {
n.judge = n.judge || w.judge
if n.c == nil {
n.c = w.c
}
}
if !fresh {
g.need = &n
if g.keeping {
g.mu.Unlock()
return
}
p.fillingAfter(ctx, used)
if g.pins != nil {
g.pins.judge() // the revision before ceased to be current
g.keeping = true
g.mu.Unlock()
run := func() {
for {
g.mu.Lock()
next := g.need
g.need = nil
if next == nil {
g.keeping = false
g.mu.Unlock()
return
}
g.mu.Unlock()
p.keepOne(ctx, *next)
}
}
if g.background != nil {
g.background(run)
return
}
run()
}
// keepOne keeps one computed revision, says assignment-revision for a revision kept now and removes the
// revisions that ceased to be current; it says its duration in the journal, and wakes a pass when it changed what the pass reads.
func (p *passer) keepOne(ctx context.Context, n keepNeed) {
g := p.graph
g.keepMu.Lock()
defer g.keepMu.Unlock()
start := time.Now()
changed := false
defer func() {
p.logf("the keeping of the assignment graph took %s", time.Since(start).Round(time.Millisecond))
if changed && g.background != nil && g.wake != nil {
g.wake()
}
}()
if n.c != nil {
_, _, had := g.keptNow()
fresh := p.keepRevision(ctx, *n.c)
_, _, has := g.keptNow()
n.judge = n.judge || fresh
changed = fresh || had != has // the first revision kept: the pass writes the wants it held (H-A-261)
}
if n.judge && g.revisions != nil {
g.revisions.judge() // the revision before ceased to be current
}
}
// keepRevision keeps c when the store holds it, and says whether a revision was kept now.
func (p *passer) keepRevision(ctx context.Context, c assigngraph.Computed) bool {
fresh, _ := p.keepRevisionOf(ctx, c)
return fresh
}
// keepRevisionOf is keepRevision answering the fault the keeping met too.
func (p *passer) keepRevisionOf(ctx context.Context, c assigngraph.Computed) (bool, error) {
g := p.graph
again := func() { // the next pass hands this revision again
g.mu.Lock()
g.handed = false
g.mu.Unlock()
}
used, _, _ := g.fillOf(ctx)
rev, fresh, err := assigngraph.Keep(ctx, g.objects, c, meshwants.EventAssignmentRevision, p.clock())
if err != nil {
again()
p.keepingFailed(ctx, c, err)
return false, err
}
p.keepingSucceeded()
var source int64
for _, cat := range rev.Catalogs {
if cat.Branch == p.w.trunkName() {
source = cat.Source
}
}
g.mu.Lock()
g.kept, g.ok, g.source = rev, true, source
g.mu.Unlock()
if !fresh {
return false, nil
}
p.fillingAfter(ctx, used)
id := fmt.Sprintf("%s-%s-%d", meshwants.EventAssignmentRevision, rev.Kind, rev.Revision)
if err := p.wantsSay(meshwants.EventAssignmentRevision, assigngraph.Event(rev), id); err != nil {
p.logf("the assignment revision %d is kept but not said: %v", rev.Revision, err)
}
return true, nil
}
// keepNow is the seat mesh-wants' act keep-now (design 47 H2 §813 (2); H-A-417): the keeping of the pass's newest computed
// revision, run at once, one at a time with the pass's; it answers the revision kept, or the fault the keeping met (a failed
// one is run again after keeping-retry, as every keeping is). The hand act is the tool's to write, before it calls.
func (p *passer) keepNow(ctx context.Context, in meshwants.KeepNowInput) (meshwants.KeepNowAnswer, error) {
g := p.graph
if strings.TrimSpace(in.Why) == "" {
return meshwants.KeepNowAnswer{}, errors.New("say why the keeping runs now")
}
if g == nil || g.objects == nil {
return meshwants.KeepNowAnswer{}, errors.New("the assigner keeps no assignment graph here")
}
g.mu.Lock()
c, ok := g.computed, g.hasComputed
g.mu.Unlock()
if !ok {
return meshwants.KeepNowAnswer{}, errors.New("no pass has computed an assignment graph revision yet")
}
g.keepMu.Lock()
defer g.keepMu.Unlock()
p.logf("the keeping of the assignment graph runs now by hand: %s", in.Why)
if _, err := p.keepRevisionOf(ctx, c); err != nil {
return meshwants.KeepNowAnswer{Fault: err.Error()}, nil
}
rev, _, _ := g.keptNow()
return meshwants.KeepNowAnswer{Revision: &rev}, nil
}
// keepNowVerb is the process's handler of the seat mesh-wants' act keep-now.
func keepNowVerb(ctx context.Context, p *passer) map[string]process.SeatHandler {
return map[string]process.SeatHandler{
meshwants.VerbKeepNow: func(_ string, raw json.RawMessage) (any, error) {
var in meshwants.KeepNowInput
if err := json.Unmarshal(raw, &in); err != nil {
return nil, fmt.Errorf("the arguments are not JSON: %w", err)
}
return p.keepNow(ctx, in)
},
}
}
// graphInputs are what the pass's assignment graph is computed from: every followed branch's catalog half, the placements, each
@@ -131,16 +343,12 @@ func (p *passer) capabilityDigests() []meshwants.AssignmentRevisionCapabilitiesI
slices.Sort(known)
var out []meshwants.AssignmentRevisionCapabilitiesItem
for _, node := range known {
read := p.reads != nil && p.reads.Known(node)
reads, read := p.reads.words(node)
rec, recorded := records[node]
if !read && !recorded {
continue
}
var reads []string
if read {
reads = slices.Clone(p.reads.Reads([]string{node})[node])
slices.Sort(reads)
}
slices.Sort(reads)
item := meshwants.AssignmentRevisionCapabilitiesItem{Node: node, Readings: slices.Clone(rec.RunnerCapabilities),
Fingerprint: rec.RunnerFingerprint}
slices.Sort(item.Readings)
@@ -158,19 +366,25 @@ func (p *passer) capabilityDigests() []meshwants.AssignmentRevisionCapabilitiesI
// sayWanted says `wanted` for a want written or removed now, from the revision the pass keeps (A-61, A-67); with none kept, it is
// said in the log that it was not said. fp is the want's, and for a removal the fingerprint last wanted there.
func (p *passer) sayWanted(node, module, fp string, removed bool) {
func (p *passer) sayWanted(node, module, fp, pipeline string, removed bool) {
if p.publishWants == nil {
return
}
g := p.graph
if g == nil || !g.ok {
var kept meshwants.AssignmentRevision
var source int64
ok := false
if g != nil {
kept, source, ok = g.keptNow()
}
if !ok {
p.logf("the want of %s on %s is written, but no assignment graph revision is kept, so wanted is not said", module, node)
return
}
at := p.clock().UTC()
body := meshwants.WantedEvent{V: keys.Version, Node: node, Module: module, Fp: fp, Removed: removed, Revision: g.kept.Revision, Source: g.source, At: &at}
body := meshwants.WantedEvent{V: keys.Version, Node: node, Module: module, Fp: fp, Pipeline: pipeline, Removed: removed, Revision: kept.Revision, Source: source, At: &at}
event := strings.TrimPrefix(meshwants.SubjectWanted(keys.EscapeName(node), keys.EscapeName(module)), "mesh.seat."+meshwants.Seat+".event.")
id := fmt.Sprintf("wanted.%s.%s.%s.%t.%d.%s", keys.EscapeName(node), keys.EscapeName(module), fp, removed, g.kept.Revision, at.Format(time.RFC3339Nano))
id := fmt.Sprintf("wanted.%s.%s.%s.%t.%d.%s", keys.EscapeName(node), keys.EscapeName(module), fp, removed, kept.Revision, at.Format(time.RFC3339Nano))
if err := p.wantsSay(event, body, id); err != nil {
p.logf("wanted of %s on %s is not said: %v", module, node, err)
}
@@ -178,15 +392,121 @@ func (p *passer) sayWanted(node, module, fp string, removed bool) {
// namedBuild answers what a want of module at fp names of its build (design 47 G §379, §526, A-96): a kept build's or another watched
// branch's parts and keeping node from the builder's `build.ended`; for the trunk's entry (fp is the module's, trunkFP), the released
// version and the parts of the `version-released` whose source is the one the kept assignment graph revision was computed from (A-67).
func (p *passer) namedBuild(module, trunkFP string) func(fp string) (assign.KeptBuild, bool) {
// version and the parts of the `version-released` whose parts are the digests its build.ended made (A-421): the catalog stamps no
// source on an entry (design 47 H §764, H-A-48). A trunk entry whose release is not heard is said, once, naming which was tried.
func (p *passer) namedBuild(module, trunkFP string, unreleased ...bool) func(fp string) (assign.KeptBuild, bool) {
return func(fp string) (assign.KeptBuild, bool) {
if k, ok := p.w.ends.partsOf(module, fp); ok {
return k, true
}
if fp != trunkFP || p.graph == nil || !p.graph.ok {
if len(unreleased) > 0 && unreleased[0] && fp == trunkFP {
// Wanted with no passed pipeline (the holder of mesh-catalog, the runner's first start): no pipeline released it,
// so its want names the parts its build.ended made, until a release of it is heard (design 47 G §16, A-428).
if k, ok := p.w.released.withParts(module, p.w.ends.madeOf(module, fp)); ok {
return k, true
}
if made := p.w.ends.madeOf(module, fp); len(made) > 0 {
return assign.KeptBuild{Parts: made}, true
}
}
if fp != trunkFP {
// A want held back at an older build (rule 2: no pipeline passed at the trunk's newer fingerprint) names that build's
// release when one names exactly the digests it made (novox 2026-11-16: mesh-hand-acts 0.1.13 held at 4eb3cf48 after
// the mesh-sdk merge moved its fingerprint).
return p.w.released.withParts(module, p.w.ends.madeOf(module, fp))
}
if _, _, kept := p.graphKept(); !kept {
p.unheardRelease(module, fp, "no assignment graph revision is kept yet, so no release is looked up")
return assign.KeptBuild{}, false
}
return p.w.released.of(module, p.graph.source)
if k, ok := p.w.released.withParts(module, p.w.ends.madeOf(module, fp)); ok {
return k, true
}
p.unheardRelease(module, fp, "no version-released of it names the parts its build.ended made")
return assign.KeptBuild{}, false
}
}
// unheardRelease says once per module, fingerprint and why that a trunk entry's release is not heard, so its wants and candidates
// carry no version and no parts (design 47 G A-419).
func (p *passer) unheardRelease(module, fp, why string) {
key := "release " + module + "@" + fp + ": " + why
if p.skipped[key] {
return
}
if p.skipped == nil {
p.skipped = map[string]bool{}
}
p.skipped[key] = true
if p.logf != nil {
p.logf("the release of %s at fingerprint %s is not heard: %s; its wants and candidates carry no version and no parts", module, fp, why)
}
}
// graphKept is the revision the wants follow, with its trunk source, and whether one is kept; with no graph kept, none is.
func (p *passer) graphKept() (meshwants.AssignmentRevision, int64, bool) {
if p.graph == nil {
return meshwants.AssignmentRevision{}, 0, false
}
return p.graph.keptNow()
}
// keepingFailed marks the keeping of c wanted again after keeping-retry (design 47 H2 §813 (2)): run then unless a newer
// revision was handed meanwhile, whose own keeping runs. The third failure in a row raises keeping-failed (scope module).
func (p *passer) keepingFailed(ctx context.Context, c assigngraph.Computed, err error) {
g := p.graph
g.mu.Lock()
g.failures++
n, retry, after := g.failures, g.retry, g.after
g.mu.Unlock()
if retry <= 0 {
retry = defaultKeepingRetry
}
if after == nil {
after = func(d time.Duration, f func()) { time.AfterFunc(d, f) }
}
p.logf("the assignment graph revision is not kept (%d in a row), so no want is said as wanted until it is; kept again in %s: %v", n, retry, err)
if n == keepingFailedAt && p.findings.Put != nil {
if err := p.findings.Put(keepingFailedFinding(n, err).Finding(p.clock())); err != nil {
p.logf("the finding %s is not written: %v", kindKeepingFailed, err)
}
}
after(retry, func() {
g.mu.Lock()
newer := g.handed && !assigngraph.Same(g.handedRev, c.Revision)
if !newer {
g.handedRev, g.handed = c.Revision, true
}
g.mu.Unlock()
if !newer {
p.needKeeping(ctx, keepNeed{c: &c})
}
})
}
// keepingSucceeded ends a run of failures: keeping-failed, raised at the third, is cleared.
func (p *passer) keepingSucceeded() {
g := p.graph
g.mu.Lock()
n := g.failures
g.failures = 0
g.mu.Unlock()
if n >= keepingFailedAt && p.findings.Delete != nil {
o := keepingFailedFinding(n, nil)
if err := p.findings.Delete(views.FindingKey(o.Scope, assign.KeyID(o.ID), o.Kind)); err != nil {
p.logf("the finding %s is not deleted: %v", kindKeepingFailed, err)
}
}
}
// keepingFailedFinding is keeping-failed of the assigner on this node, after n failures in a row (design 47 H2 §813 (2)).
func keepingFailedFinding(n int, err error) assign.Observed {
summary := fmt.Sprintf("the keeping of the assignment graph revisions failed %d times in a row", n)
if err != nil {
summary += ": " + err.Error()
}
return assign.Observed{Scope: mcc.ScopeModule, ID: assignment.Module() + "." + thisNode, Kind: kindKeepingFailed,
Severity: mcseat.FindingSeverityWarning, Summary: summary, Headline: "The assignment graph is not kept",
Explanation: summary + ". No want is said as wanted until a keeping succeeds; it is run again after keeping-retry.",
Source: "assigner." + kindKeepingFailed}
}
@@ -3,17 +3,24 @@ package main
import (
"context"
"encoding/json"
"errors"
"fmt"
"slices"
"strings"
"sync"
"testing"
"time"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
mcseat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
mcc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
mwc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
mpr "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"mesh-delivery-assigner/internal/assign"
"mesh-delivery-assigner/internal/assigngraph"
"mesh-delivery-assigner/internal/buckets"
)
@@ -88,6 +95,35 @@ func TestTheWantsAreSaidWantedFromTheKeptAssignmentGraphRevision(t *testing.T) {
if err := json.Unmarshal(events[len(events)-1].body, &w); err != nil || len(events) != 3 || !w.Removed || w.Fp != fpTest {
t.Errorf("a removing want said %+v (%v), %d events", w, err, len(events))
}
// Design 47 H2 §813 (1), H-A-416: a want carries its run, its pipeline's source in decimal, or the newest source held for a
// want of no pipeline; it is written by compare-and-set refusing a lower run, and one that differs only by its run stands.
t.Run("a want's run", func(t *testing.T) {
wkey, _ := mwc.WantKey("g14", "db")
stored := func() mwc.Want { w, _ := mwc.DecodeWant(kv.values[wkey]); return w }
p.putWant(ctx, "g14", "db", mwc.Want{Fp: fpTest, Version: "0.1.2", Pipeline: "main.12", Rank: 1})
if w := stored(); w.Run != "12" || w.Pipeline != "main.12" {
t.Fatalf("the want of pipeline main.12 is %+v, want run 12", w)
}
puts := kv.puts
p.putWant(ctx, "g14", "db", mwc.Want{Fp: fpTest, Version: "0.1.1", Pipeline: "main.11", Rank: 1})
if w := stored(); w.Run != "12" || w.Version != "0.1.2" || kv.puts != puts {
t.Errorf("a want of a lower run replaced %+v (%d writes)", w, kv.puts-puts)
}
p.putWant(ctx, "g14", "db", mwc.Want{Fp: fpTest, Version: "0.1.2", Pipeline: "main.12", Rank: 1})
if kv.puts != puts {
t.Error("a want that stands was written again")
}
skey, _ := mwc.WantKey("shanks", "db")
p.putWant(ctx, "shanks", "db", mwc.Want{Fp: fpTest, Put: true, Words: "put: by hand"})
if w, _ := mwc.DecodeWant(kv.values[skey]); w.Run != "9" {
t.Errorf("a put's want is %+v, want the newest source held, 9", w)
}
// a placement's build after the delivery of run 12: the newest source held for it is the want's own, never refused
p.putWant(ctx, "g14", "db", mwc.Want{Fp: fpTest, Version: "0.1.0"})
if w := stored(); w.Run != "12" || w.Version != "0.1.0" {
t.Errorf("a placement's want after run 12 is %+v, want it written at run 12", w)
}
})
// A-201, A-235: a run's candidate catalog revision, read whole through the seat's verb revision, keeps the run's assignment
// graph under candidate.<group>.<heads> in place of its branch's half; it says nothing and writes no want, a try's candidate
@@ -132,3 +168,202 @@ func TestTheWantsAreSaidWantedFromTheKeptAssignmentGraphRevision(t *testing.T) {
t.Errorf("dropping the run's candidate dropped trunk: %v", err)
}
}
// blockedObjects is an object bucket whose listing waits while a gate stands: a keeping that does not end until it is opened.
type blockedObjects struct {
memObjects
mu sync.Mutex
gate chan struct{}
}
func (b *blockedObjects) Names(ctx context.Context) ([]string, error) {
b.mu.Lock()
gate := b.gate
b.mu.Unlock()
if gate != nil {
<-gate
}
b.mu.Lock()
defer b.mu.Unlock()
return b.memObjects.Names(ctx)
}
func (b *blockedObjects) Put(ctx context.Context, name string, data []byte) error {
b.mu.Lock()
defer b.mu.Unlock()
return b.memObjects.Put(ctx, name, data)
}
func (b *blockedObjects) Get(ctx context.Context, name string) ([]byte, error) {
b.mu.Lock()
defer b.mu.Unlock()
return b.memObjects.Get(ctx, name)
}
// block stands a gate, opened by the function it answers.
func (b *blockedObjects) block() func() {
gate := make(chan struct{})
b.mu.Lock()
b.gate = gate
b.mu.Unlock()
return func() {
b.mu.Lock()
b.gate = nil
b.mu.Unlock()
close(gate)
}
}
// Design 47 H-A-259, H-A-261: the keeping of the assignment graph runs off the pass loop. At the start, while the first keeping is
// blocked, a pass returns and writes no want; the keeping's end wakes a pass, which writes the passed pipeline's want. Later, while a
// keeping of new inputs is blocked, a pass writes the wants from the revision it holds, and a pass of the same inputs hands nothing
// more. Each pass and each keeping says its duration.
func TestAPassWritesWantsWhileAKeepingIsBlocked(t *testing.T) {
fp := mcc.SourcePrefix2 + strings.Repeat("a", 64)
wantsKV := &memKV{values: map[string][]byte{}}
p := newPasser(kvSet{buckets.Wants(): wantsKV, buckets.Asks(): &memKV{values: map[string][]byte{}}}, time.Now())
var mu sync.Mutex
var journal strings.Builder
p.logf = func(f string, a ...any) { mu.Lock(); fmt.Fprintf(&journal, f+"\n", a...); mu.Unlock() }
said := func(words string) bool {
mu.Lock()
defer mu.Unlock()
return strings.Contains(journal.String(), words)
}
mdigest := strings.Repeat("e", 64)
mod, _ := mcc.EncodeModule(meshcatalog.ModulesByModuleValue{Fp2: fp, Manifest: mdigest, Repository: "novox/web", Commit: strings.Repeat("1", 40), Path: mcc.RootPath})
putModuleRaw(p.w, trunkBranch, "web", mod)
p.w.manifests[mdigest] = parsed{module: "web", manifest: catalogue.Manifest{Module: "web"}}
placeOn(t, p.w, "ace", "web")
p.ends = newPipelineEnds(newMemEnds(), func() {}, t.Logf)
p.ends.trunk = p.w.trunkName
_, _ = p.ends.take(ended(trunkBranch, 5, mpr.PipelineEndedOutcomePassed, mover("web", fp, "0.1.2", 1, mpr.StepResultOutcomePassed)))
objects := &blockedObjects{memObjects: memObjects{}}
var kept sync.WaitGroup
woke := make(chan struct{}, 8)
half := mcc.Half{Revision: meshcatalog.CatalogRevision{Branch: trunkBranch, Kind: "trunk", Revision: 4, Source: 9,
Entries: []meshcatalog.EntryRef{{Module: "web", Digest: "sha256:" + strings.Repeat("a", 64)}}},
Entries: map[string]meshcatalog.CatalogEntry{"web": {Module: "web", Fp: fp}}}
p.graph = &graphKeeper{objects: objects, halves: func() map[string]mcc.Half { return map[string]mcc.Half{trunkBranch: half} },
background: func(f func()) { kept.Go(f) }, wake: func() { woke <- struct{}{} }}
pass := func() {
t.Helper()
done := make(chan struct{})
go func() { p.pass(context.Background()); close(done) }()
select {
case <-done:
case <-time.After(10 * time.Second):
t.Fatal("the pass waits on the keeping of the assignment graph")
}
}
wantOf := func(node string) (mwc.Want, error) {
key, _ := mwc.WantKey(node, "web")
return mwc.DecodeWant(wantsKV.values[key])
}
open := objects.block()
t.Cleanup(func() { // the keeping ends before the test does, and says its duration
objects.mu.Lock()
standing := objects.gate != nil
objects.mu.Unlock()
if standing {
open()
}
kept.Wait()
if !said("the keeping of the assignment graph took ") {
t.Error("the keeping does not say its duration")
}
})
pass() // the start: the first keeping is blocked
if _, err := wantOf("ace"); err == nil {
t.Error("a pass at the start wrote a want before an assignment graph revision is kept")
}
open()
select {
case <-woke:
case <-time.After(10 * time.Second):
t.Fatal("the first keeping's end wakes no pass")
}
pass()
if w, err := wantOf("ace"); err != nil || w.Fp != fp || w.Version != "0.1.2" {
t.Errorf("the want of web on ace = %+v (%v), want the passed version once a revision is kept", w, err)
}
open = objects.block() // a keeping of new inputs is blocked
placeOn(t, p.w, "g14", "web")
pass()
pass() // the same inputs again
if w, err := wantOf("g14"); err != nil || w.Fp != fp || w.Version != "0.1.2" {
t.Errorf("the want of web on g14 = %+v (%v), want the passed version while a keeping is blocked", w, err)
}
p.graph.mu.Lock()
keeping, waiting := p.graph.keeping, p.graph.need
p.graph.mu.Unlock()
if !keeping || waiting != nil {
t.Errorf("keeping %v, need waiting %+v: the pass of the same inputs handed its revision again", keeping, waiting)
}
if !said("the pass took ") {
t.Error("the pass does not say its duration")
}
open()
kept.Wait()
// Design 47 H2 §813 (2): a keeping that fails runs again after keeping-retry with no pass, raising keeping-failed at the third
// failure in a row, cleared at the next that succeeds.
t.Run("a failed keeping runs again", func(t *testing.T) {
failing := &failingObjects{blockedObjects: objects, fail: 3}
var retries []time.Duration
var put []mcseat.Finding
var deleted []string
p.findings = assign.Findings{Put: func(f mcseat.Finding) error { put = append(put, f); return nil },
Delete: func(key string) error { deleted = append(deleted, key); return nil }}
p.graph.objects, p.graph.background, p.graph.retry = failing, nil, 30*time.Second
p.graph.after = func(d time.Duration, f func()) { retries = append(retries, d); f() }
placeOn(t, p.w, "shanks", "web") // new inputs: a keeping is handed
pass()
if len(retries) != 3 || retries[0] != 30*time.Second || len(put) != 1 || put[0].Kind != kindKeepingFailed || put[0].Scope != "module" ||
len(deleted) != 1 || !strings.Contains(deleted[0], kindKeepingFailed) || p.graph.failures != 0 {
t.Fatalf("retries %v, raised %+v, cleared %v, failures %d", retries, put, deleted, p.graph.failures)
}
if _, _, ok := p.graph.keptNow(); !ok || failing.fail != 0 {
t.Fatal("the revision is not kept once the store takes it")
}
// keep-now (H-A-417): the keeping by hand answers the revision kept, or the fault met; it needs a why.
if _, err := p.keepNow(context.Background(), meshwants.KeepNowInput{}); err == nil {
t.Error("a keeping by hand with no why runs")
}
if a, err := p.keepNow(context.Background(), meshwants.KeepNowInput{Why: "the store was full"}); err != nil || a.Revision == nil || a.Fault != "" {
t.Errorf("keep-now answered %+v, %v; want the revision kept", a, err)
}
failing.fail, retries = 2, nil
p.graph.after = func(d time.Duration, _ func()) { retries = append(retries, d) }
placeOn(t, p.w, "novox", "web") // a new revision, whose keeping the store refuses at the pass and again by hand
pass()
if a, err := p.keepNow(context.Background(), meshwants.KeepNowInput{Why: "again"}); err != nil || a.Revision != nil || !strings.Contains(a.Fault, "the store answers nothing") || len(retries) != 2 {
t.Errorf("keep-now on a refusing store answered %+v, %v, retries %v; want the fault and a retry", a, err, retries)
}
var asked []string
tool := keepNowTools(func(key string, body any) (json.RawMessage, error) {
raw, _ := json.Marshal(body)
asked = append(asked, key+" "+string(raw))
return json.RawMessage(`{}`), nil
})[0]
if _, err := tool.Run(map[string]any{"why": "by hand"}); err != nil || len(asked) != 2 || !strings.HasPrefix(asked[0], "seat:mesh-hand-acts.hand-act ") ||
asked[1] != `seat:mesh-wants.keep-now {"why":"by hand"}` {
t.Errorf("assigner_keep_now: %v, asked %v", err, asked)
}
})
}
// failingObjects refuses the next fail puts, then is objects.
type failingObjects struct {
*blockedObjects
fail int
}
func (f *failingObjects) Put(ctx context.Context, name string, data []byte) error {
if f.fail > 0 {
f.fail--
return errors.New("the store answers nothing")
}
return f.blockedObjects.Put(ctx, name, data)
}
@@ -6,6 +6,7 @@ import (
"encoding/hex"
"encoding/json"
"slices"
"strings"
"sync"
"time"
@@ -13,6 +14,7 @@ import (
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/graph"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/views"
)
@@ -35,6 +37,10 @@ type halves struct {
// settled is told once when the first watched branch's first view is answered, for the first pass to wait on.
settled chan<- struct{}
told bool
// regMu orders the registrations told to registered: the ones held when it is set, then each change (H-A-270 (3)).
regMu sync.Mutex
registered func(reg meshcatalog.Registration, gone bool)
}
// follow makes the branch follower on the reader; the reader's start asks the first views.
@@ -48,12 +54,51 @@ func (h *halves) follow() error {
h.changed(branch, module, entry, deleted)
}
b.Adopted = h.adopted
// The one handler of registration-changed is the follower's (H-A-270 (3)): the pipeline ends are told each change from it,
// never from a second handler on the hub.
reconcile := b.Registrations.Follower.Changed
b.Registrations.Follower.Changed = func(module string, value json.RawMessage, gone bool, at time.Time) {
if reconcile != nil {
reconcile(module, value, gone, at)
}
h.tellRegistration(module, value, gone)
}
h.mu.Lock()
h.branches = b
h.mu.Unlock()
h.settleWhenNoBranch()
return nil
}
// settleWhenNoBranch tells the first pass once, when the registrations and the gate's source are answered and name no branch: the
// trunk is none-yet and the world is empty, as the catalog client's Ready says it (design 47 G, A-372). A mesh that names a branch is
// told by adopted, when that branch's first view is answered.
func (h *halves) settleWhenNoBranch() {
if h.settled == nil {
return
}
h.mu.Lock()
b := h.branches
h.mu.Unlock()
go func() {
select {
case <-b.FirstViews(h.ctx):
case <-h.ctx.Done():
return
}
if len(b.Followed()) > 0 || b.Ready() != nil {
return
}
h.mu.Lock()
told := h.told
h.told = true
h.mu.Unlock()
if !told {
h.settled <- struct{}{}
}
}()
}
// first is the first watched branch followed, the trunk's: "" while none is.
func (h *halves) first() string {
h.mu.Lock()
@@ -161,3 +206,61 @@ func (h *halves) views() map[string]mcc.Half {
}
return out
}
// watchedOf is module's watched branches in its registration's order (the branch `register` named first, then each branch in the
// order `watch` added it). Once registrations are held, a module none names has none: it is unlisted (H-A-144). Only before the
// first registrations are held do the gate's source's branches stand in (the branches followed then), in the order the source
// gives them, by their names escaped as its keys are (design 47 G §532, H-A-143, H-A-144).
func (h *halves) watchedOf(module string) []string {
h.mu.Lock()
b := h.branches
h.mu.Unlock()
if b == nil {
return nil
}
if b.Registrations != nil && len(b.Registrations.All()) > 0 {
if reg, ok := b.Registrations.Registration(module); ok {
return slices.Clone(reg.Branches)
}
return nil
}
out := b.Followed()
slices.SortStableFunc(out, func(x, y string) int { return strings.Compare(keys.EscapeName(x), keys.EscapeName(y)) })
return out
}
// tellRegistration tells registered of one registration the follower holds now, or of one removed.
func (h *halves) tellRegistration(module string, value json.RawMessage, gone bool) {
h.regMu.Lock()
defer h.regMu.Unlock()
if h.registered == nil {
return
}
reg := meshcatalog.Registration{Module: module}
if !gone {
if err := json.Unmarshal(value, &reg); err != nil {
h.logf("the registration of %s does not read: %v", module, err)
return
}
}
h.registered(reg, gone)
}
// followRegistrations tells registered of every registration the branch follower holds and then of each change it takes
// (design 47 G §353): the registrations are followed once, by the follower's one handler of registration-changed (H-A-270
// (3)). It says false when no follower is made.
func (h *halves) followRegistrations(registered func(meshcatalog.Registration, bool)) bool {
h.mu.Lock()
b := h.branches
h.mu.Unlock()
if b == nil || b.Registrations == nil {
return false
}
h.regMu.Lock()
defer h.regMu.Unlock()
h.registered = registered
for _, reg := range b.Registrations.All() {
registered(reg, false)
}
return true
}
@@ -0,0 +1,107 @@
package main
import (
"context"
"encoding/json"
"errors"
"slices"
"testing"
"time"
mcc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-sdk/go/views"
)
// Design 47 G A-372: the assigner's wait for its catalog half asks the catalog client's Ready as well: a mesh whose registrations and
// gate's source are answered and name no branch is none-yet, and the first pass is told so once; before they answer it is not told.
func TestAMeshThatNamesNoBranchSettlesTheAssignersFirstPass(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
call := func(key string, _ any) (json.RawMessage, error) {
if key == mcc.RegistrationsVerb {
return json.Marshal(seat.RegistrationsAnswer{Registrations: []seat.Registration{}})
}
return json.Marshal(map[string][]string{"branches": {}})
}
for _, answered := range []bool{false, true} {
settled := make(chan struct{}, 2)
reader := &views.ProcessReader{Module: "mesh-delivery-assigner", Call: call, Logf: t.Logf}
h := &halves{w: newWorld(), call: call, reader: reader, wake: func() {}, logf: t.Logf, ctx: ctx, settled: settled}
if err := h.follow(); err != nil {
t.Fatal(err)
}
if answered {
for _, f := range reader.Followers() {
if err := f.Start(ctx); err != nil {
t.Fatal(err)
}
}
select {
case <-settled:
case <-ctx.Done():
t.Fatal("a mesh that names no branch never settled the first pass")
}
}
select {
case <-settled:
t.Errorf("answered %v: the first pass was told twice or before the first views", answered)
default:
}
}
}
// Design 47 H-A-143, H-A-144, G §532: a module's watched branches are its registration's, in its order; once registrations are held a
// module none names has none; before the first registrations the gate's source's branches stand in, in the source's order.
// H-A-270 (3): the pipeline ends are told the registrations by the same follower, whether set before its first view or after.
func TestAModulesWatchedBranchesAreItsRegistrations(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
for _, tc := range []struct {
name string
regs []seat.Registration
module string
want []string
}{
{"its registration's order", []seat.Registration{{Module: "link2pay", Branches: []string{"nox-mesh", "main"}}}, "link2pay", []string{"nox-mesh", "main"}},
{"no registration names it", []seat.Registration{{Module: "link2pay", Branches: []string{"nox-mesh", "main"}}}, "checker", nil},
{"before the first registrations, the source's", []seat.Registration{}, "checker", []string{"main", "master"}},
} {
t.Run(tc.name, func(t *testing.T) {
call := func(key string, _ any) (json.RawMessage, error) {
switch key {
case mcc.RegistrationsVerb:
return json.Marshal(seat.RegistrationsAnswer{Registrations: tc.regs})
case mcc.SourceVerb:
return json.Marshal(map[string][]string{"branches": {"master", "main"}})
}
return nil, errors.New("not answered here")
}
reader := &views.ProcessReader{Module: "mesh-delivery-assigner", Call: call, Logf: t.Logf}
h := &halves{w: newWorld(), call: call, reader: reader, wake: func() {}, logf: t.Logf, ctx: ctx}
if err := h.follow(); err != nil {
t.Fatal(err)
}
var live, held []string
if !h.followRegistrations(func(reg seat.Registration, gone bool) { live = append(live, reg.Module) }) {
t.Fatal("no follower of the registrations")
}
for _, f := range reader.Followers()[:2] { // the registrations and the gate's source
if err := f.Start(ctx); err != nil {
t.Fatal(err)
}
}
h.followRegistrations(func(reg seat.Registration, gone bool) { held = append(held, reg.Module) })
var regs []string
for _, r := range tc.regs {
regs = append(regs, r.Module)
}
if !slices.Equal(live, regs) || !slices.Equal(held, regs) {
t.Errorf("the ends were told %v at the first view and %v held, want %v", live, held, regs)
}
if got := h.watchedOf(tc.module); !slices.Equal(got, tc.want) {
t.Errorf("the watched branches of %s are %v, want %v", tc.module, got, tc.want)
}
})
}
}
@@ -16,6 +16,7 @@ import (
"github.com/nats-io/nats.go/jetstream"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
stdio "git.novox.be/novox/mesh-sdk/go"
@@ -24,14 +25,17 @@ import (
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/process"
"git.novox.be/novox/mesh-sdk/go/stateobjects"
"mesh-delivery-assigner/internal/buckets"
)
// A step's input by its digest (design 47 G §354, §712, A-237, A-243): the assigner keeps the input of each composition step
// request it asked a build seat to run in its state `inputs`, one key `<time>.<digest>` per input, the value the input's bytes in
// request it asked a build seat to run in its state `inputs`, one key per input, its sha256 alone (A-465a), the value the input's bytes in
// base64 with the state's object store `inputs-objects` holding one over a key's limit (mesh-sdk stateobjects), and the seat
// mesh-wants' verb `input` answers one by its digest in chunks, to the holders of the build seats alone (the verb's callers, §338).
// An input is deleted when the build seat's step-ended of its ask is heard, or a day after its write, whichever is first, the day
// judged at each new ask over at most 20 of the oldest keys. `assigner_inputs` reads them. This mirrors the indexer's
// An input is kept once per content: every ask that names its digest shares it (A-465a). It is deleted, with its object, when the
// step-ended of the last ask that names it is heard, or a day after its last write, whichever is first, the day judged at each new
// ask over at most 20 of the oldest inputs. `assigner_inputs` reads them. This mirrors the indexer's
// (mesh-delivery-indexer internal/index/run_inputs.go): the two are separate modules' code, owed to mesh-sdk.
// inputsTool is the tool that reads the kept inputs.
@@ -44,10 +48,39 @@ const (
inputsSwept = 20
inputsTime = "20060102T150405Z"
// inputsAskPrefix opens the keys that name an input by the id of the ask it was kept for: ask.<id>, the id escaped as a name,
// holding the input's own key, so the build seat's step-ended of that ask finds it.
// holding the digest of the input the ask uses, so the build seat's step-ended of that ask finds it.
inputsAskPrefix = "ask."
)
// inputAsk is what an ask's key holds (A-465b): the digest of the input the ask uses and the time the ask wrote it, in inputsTime.
type inputAsk struct {
Digest string `json:"digest"`
At string `json:"at"`
}
// readAsk reads an ask's key: the JSON form, or the bare key of the old form `<time>.<digest>` an earlier assigner wrote, which
// carries its time in the key itself.
func readAsk(raw []byte) (digest string, at time.Time) {
var a inputAsk
if json.Unmarshal(raw, &a) == nil && a.Digest != "" {
at, _ = time.Parse(inputsTime, a.At)
return a.Digest, at
}
digest = string(raw)
t, _, _ := strings.Cut(digest, ".")
at, _ = time.Parse(inputsTime, t)
return digest, at
}
// isDigest is whether a key is an input's own key: 64 hex digits.
func isDigest(key string) bool {
if len(key) != 64 {
return false
}
_, err := hex.DecodeString(key)
return err == nil
}
// digestOf is an input's digest as the ask names it: its sha256 in hex.
func digestOf(b []byte) string { sum := sha256.Sum256(b); return hex.EncodeToString(sum[:]) }
@@ -63,8 +96,9 @@ type inputKeeper struct {
used func() (int64, error)
}
// keep keeps the exact bytes of the input of the ask under their write time and sha256, after sweeping the keys more than a day old
// among the 20 oldest, and names it by the ask's id; it answers the digest. The same bytes written again in the same second are one key.
// keep keeps the exact bytes of the input of the ask under their sha256, after sweeping, and names the digest and the time in the
// ask's key; it answers the digest. The same bytes asked again are the same one input (A-465a, A-465b). The ask's key is written
// first, so a sweep never finds the input unnamed.
func (k *inputKeeper) keep(ask string, body []byte) (string, error) {
if ask == "" {
return "", errors.New("name the ask the input is kept for")
@@ -72,29 +106,43 @@ func (k *inputKeeper) keep(ask string, body []byte) (string, error) {
if err := k.sweep(); err != nil {
k.logf("inputs: the keys older than a day are not all deleted: %v", err)
}
if k.used != nil {
used, err := k.used()
if err != nil {
return "", fmt.Errorf("the fill of the state %s is not read, so no input is kept: %w", meshwants.StateInputs, err)
}
if used+int64(len(body)) > inputsCap {
return "", fmt.Errorf("the state %s is at its cap of %d MiB (%d bytes kept), so the ask's input of %d bytes is refused",
meshwants.StateInputs, inputsCap>>20, used, len(body))
}
}
digest := digestOf(body)
key := meshwants.InputsByTimeDigestKey(k.now().UTC().Format(inputsTime), digest)
if err := k.vals.Put(key, base64.StdEncoding.EncodeToString(body)); err != nil && !errors.Is(err, stateobjects.ErrChanged) {
raw, err := json.Marshal(inputAsk{Digest: digest, At: k.now().UTC().Format(inputsTime)})
if err != nil {
return "", err
}
if err := k.vals.KV.Create(inputsAskPrefix+keys.EscapeName(ask), []byte(key)); err != nil && !errors.Is(err, stateobjects.ErrChanged) {
askKey := inputsAskPrefix + keys.EscapeName(ask)
if err := k.vals.KV.Create(askKey, raw); err != nil && !errors.Is(err, stateobjects.ErrChanged) {
return "", err
}
have, err := k.vals.KV.Get(digest)
if err != nil {
return "", err
}
if have != nil {
return digest, nil
}
if k.used != nil {
used, err := k.used()
if err == nil && used+int64(len(body)) > inputsCap {
err = fmt.Errorf("the state %s is at its cap of %d MiB (%d bytes kept), so the ask's input of %d bytes is refused",
buckets.InputsState, inputsCap>>20, used, len(body))
} else if err != nil {
err = fmt.Errorf("the fill of the state %s is not read, so no input is kept: %w", buckets.InputsState, err)
}
if err != nil {
_ = k.vals.KV.Delete(askKey)
return "", err
}
}
if err := k.vals.Put(digest, base64.StdEncoding.EncodeToString(body)); err != nil && !errors.Is(err, stateobjects.ErrChanged) {
return "", err
}
return digest, nil
}
// ended deletes the input kept for an ask when the build seat's step-ended of that ask is heard; an ask that kept none, or whose
// input a sweep deleted, changes nothing.
// ended removes the ask's key when the build seat's step-ended of that ask is heard, and deletes the input it named, with its
// object, when no other ask's key names it (A-465a); an ask that kept none changes nothing.
func (k *inputKeeper) ended(ask string) error {
if ask == "" {
return nil
@@ -104,66 +152,165 @@ func (k *inputKeeper) ended(ask string) error {
if err != nil || e == nil {
return err
}
if err := k.vals.KV.Delete(string(e.Value)); err != nil {
digest, _ := readAsk(e.Value)
if err := k.vals.KV.Delete(askKey); err != nil {
return err
}
return k.vals.KV.Delete(askKey)
named, err := k.named()
if err != nil {
return err
}
if named[digest] {
return nil // another running ask still names it
}
return k.deleteInput(digest)
}
// sweep deletes, among the 20 oldest keys, those written more than a day ago, and a name by ask whose input is gone.
// named is the inputs some ask's key names now.
func (k *inputKeeper) named() (map[string]bool, error) {
all, err := k.vals.KV.Keys()
if err != nil {
return nil, err
}
named := map[string]bool{}
for _, key := range all {
if !strings.HasPrefix(key, inputsAskPrefix) {
continue
}
o, err := k.vals.KV.Get(key)
if err != nil {
return nil, err
}
if o != nil {
d, _ := readAsk(o.Value)
named[d] = true
}
}
return named, nil
}
// deleteInput deletes an input's key and the object that key names, when it names one (A-465): an owner that ends its own key
// ends its object. A key already gone leaves nothing to remove here; the start and assigner_inputs_drop remove what a key left.
func (k *inputKeeper) deleteInput(key string) error {
e, err := k.vals.KV.Get(key)
if err != nil {
return err
}
if err := k.vals.KV.Delete(key); err != nil {
return err
}
if e == nil {
return nil
}
if ref, ok := stateobjects.ReadRef(e.Value); ok {
if err := k.vals.Objects.Delete(ref.Object); err != nil {
return fmt.Errorf("the object %s of %s: %w", ref.Object, key, err)
}
}
return nil
}
// dropKeyGone removes every object of the state whose key is gone and answers their count and bytes (A-465).
func (k *inputKeeper) dropKeyGone() (dropped []stateobjects.Kept, bytes int64, err error) {
kept, err := k.vals.Kept()
if err != nil {
return nil, 0, err
}
names, err := k.vals.DropKeyGone()
gone := map[string]bool{}
for _, n := range names {
gone[n] = true
}
for _, o := range kept {
if gone[o.Name] {
dropped = append(dropped, o)
bytes += o.Size
}
}
return dropped, bytes, err
}
// dropAtStart removes the objects whose key is gone at the program's start, said with their count and bytes (A-465). An object
// store not on the bus yet is said and left.
func (k *inputKeeper) dropAtStart() {
dropped, bytes, err := k.dropKeyGone()
if err != nil {
k.logf("inputs: the objects of deleted keys are not all removed at the start (%d objects, %d bytes removed): %v", len(dropped), bytes, err)
return
}
k.logf("inputs: %d objects of deleted keys removed at the start, %d bytes", len(dropped), bytes)
}
// sweep deletes, among the 20 oldest ask keys, those written more than a day ago; every input of the digest form no ask's key names
// now, with its object; a key of the old form `<time>.<digest>` a day after the time it carries; and an old-form ask key whose
// input is gone (A-465b).
func (k *inputKeeper) sweep() error {
all, err := k.vals.KV.Keys()
if err != nil {
return err
}
var errs []error
var inputs, asks []string
type askAt struct {
key string
at time.Time
}
var asks []askAt
var inputs []string
for _, key := range all {
if strings.HasPrefix(key, inputsAskPrefix) {
asks = append(asks, key)
} else {
inputs = append(inputs, key)
}
}
slices.Sort(inputs) // the write time leads the key, so the oldest come first
if len(inputs) > inputsSwept {
inputs = inputs[:inputsSwept]
}
for _, key := range inputs {
t, _, ok := meshwants.ParseInputsByTimeDigestKey(key)
at, perr := time.Parse(inputsTime, t)
if !ok || perr != nil || k.now().Sub(at) < inputsKeptFor {
continue
}
if err := k.vals.KV.Delete(key); err != nil {
errs = append(errs, err)
}
}
for _, key := range asks {
if e, err := k.vals.KV.Get(key); err == nil && e != nil {
if gone, err := k.vals.KV.Get(string(e.Value)); err == nil && gone == nil {
if err := k.vals.KV.Delete(key); err != nil {
errs = append(errs, err)
e, err := k.vals.KV.Get(key)
if err != nil || e == nil {
continue
}
d, at := readAsk(e.Value)
if !isDigest(d) {
if gone, err := k.vals.KV.Get(d); err == nil && gone == nil {
errs = append(errs, k.vals.KV.Delete(key))
}
}
asks = append(asks, askAt{key, at})
continue
}
if !isDigest(key) {
t, _, _ := strings.Cut(key, ".")
if at, err := time.Parse(inputsTime, t); err == nil && k.now().Sub(at) >= inputsKeptFor {
errs = append(errs, k.deleteInput(key))
}
continue
}
inputs = append(inputs, key)
}
slices.SortFunc(asks, func(a, b askAt) int { return a.at.Compare(b.at) })
if len(asks) > inputsSwept {
asks = asks[:inputsSwept]
}
for _, a := range asks {
if !a.at.IsZero() && k.now().Sub(a.at) >= inputsKeptFor {
errs = append(errs, k.vals.KV.Delete(a.key))
}
}
named, err := k.named()
if err != nil {
return errors.Join(append(errs, err)...)
}
for _, key := range inputs {
if !named[key] {
errs = append(errs, k.deleteInput(key))
}
}
return errors.Join(errs...)
}
// keyOf is the key of the input of the digest, or none.
// keyOf is the key of the input of the digest, or none: the digest itself.
func (k *inputKeeper) keyOf(digest string) (string, error) {
all, err := k.vals.KV.Keys()
if err != nil {
if !isDigest(digest) {
return "", nil
}
e, err := k.vals.KV.Get(digest)
if err != nil || e == nil {
return "", err
}
slices.Sort(all)
for _, key := range all {
if _, d, ok := meshwants.ParseInputsByTimeDigestKey(key); ok && d == digest && !strings.HasPrefix(key, inputsAskPrefix) {
return key, nil
}
}
return "", nil
return digest, nil
}
// body is the exact bytes of the input of the digest, checked against it, whatever its size.
@@ -173,7 +320,7 @@ func (k *inputKeeper) body(digest string) ([]byte, error) {
}
key, err := k.keyOf(digest)
if err != nil {
return nil, fmt.Errorf("the state %s cannot be read: %w", meshwants.StateInputs, err)
return nil, fmt.Errorf("the state %s cannot be read: %w", buckets.InputsState, err)
}
if key == "" {
return nil, fmt.Errorf("the assigner keeps no input with the digest %s", digest)
@@ -241,7 +388,7 @@ func (o *inputObjects) open() (stateobjects.Objects, error) {
}
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
store, err := o.js.ObjectStore(ctx, catalogue.BusName(o.module, catalogue.StateObjectsName(meshwants.StateInputs)))
store, err := o.js.ObjectStore(ctx, catalogue.BusName(o.module, catalogue.StateObjectsName(buckets.InputsState)))
if errors.Is(err, jetstream.ErrBucketNotFound) || errors.Is(err, jetstream.ErrStreamNotFound) {
return nil, fmt.Errorf("the object store of the state inputs is not on the bus yet: %w", process.ErrNotYet)
}
@@ -292,7 +439,7 @@ func inputsOver(kv jetstream.KeyValue, js jetstream.JetStream, module string, lo
return nil
}
objects := &inputObjects{js: js, module: module}
v := stateobjects.Values{KV: stateobjects.BusKV{KV: kv}, Objects: objects, Store: catalogue.StateObjectsName(meshwants.StateInputs)}
v := stateobjects.Values{KV: stateobjects.BusKV{KV: kv}, Objects: objects, Store: catalogue.StateObjectsName(buckets.InputsState)}
used := func() (int64, error) {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
@@ -333,12 +480,21 @@ func inputsRead(k *inputKeeper) stdio.Tool {
return nil, fmt.Errorf("the inputs cannot be listed: %w", err)
}
slices.Sort(all)
lastAsk := map[string]string{} // the latest write time an ask's key names for each input
for _, key := range all {
if e, err := k.vals.KV.Get(key); err == nil && e != nil && strings.HasPrefix(key, inputsAskPrefix) {
if d, at := readAsk(e.Value); !at.IsZero() && at.Format(inputsTime) > lastAsk[d] {
lastAsk[d] = at.Format(inputsTime)
}
}
}
out := []inputSaid{}
for _, key := range all {
t, d, ok := meshwants.ParseInputsByTimeDigestKey(key)
if !ok || strings.HasPrefix(key, inputsAskPrefix) || (want != "" && d != want) {
d := key
if !isDigest(key) || (want != "" && d != want) {
continue
}
t := lastAsk[key]
var text string
if found, err := k.vals.Get(key, &text); err != nil || !found {
continue
@@ -352,26 +508,74 @@ func inputsRead(k *inputKeeper) stdio.Tool {
}
out = append(out, said)
}
return map[string]any{"inputs": out}, nil
gone := []map[string]any{}
var goneBytes int64
answer := map[string]any{"inputs": out}
kept, err := k.vals.Kept()
if err != nil {
// never an empty list for objects that could not be read (A-465)
answer["key-gone-error"] = fmt.Sprintf("the objects of the state inputs cannot be listed, so key-gone objects are not known: %v", err)
return answer, nil
}
for _, o := range kept {
if o.KeyGone {
gone = append(gone, map[string]any{"object": o.Name, "key": o.Key, "size": o.Size})
goneBytes += o.Size
}
}
answer["key-gone"], answer["key-gone-bytes"] = gone, goneBytes
return answer, nil
}}
}
// heardStepEnded deletes the input kept for the ask a build seat's step-ended names (design 47 G §354), and hands the end to the
// composition run that waits for that ask (A-240); one whose input cannot be deleted is given again by the bus.
func heardStepEnded(k *inputKeeper, ends *runEnds, m jetstream.Msg, logf func(string, ...any)) {
// inputsDropTool is the tool that removes the objects whose key is gone.
const inputsDropTool = "assigner_inputs_drop"
// inputsDrop is the tool assigner_inputs_drop (A-465): a hand act, recorded first, that removes the objects of the state inputs
// whose key is gone now and answers what it removed.
func inputsDrop(k *inputKeeper, ask func(string, any) (json.RawMessage, error)) stdio.Tool {
return stdio.Tool{Name: inputsDropTool, Description: "Remove the objects of the assigner's state inputs whose key is gone now (design 47 G A-465), " +
"and answer which and how many bytes. An object a key names is never removed. Recorded as a hand act; assigner_inputs lists them as key-gone.",
Input: schema(map[string]string{"why": "why the objects of deleted keys are dropped now"}, []string{"why"}), Run: func(args map[string]any) (any, error) {
why := strings.TrimSpace(arg(args, "why"))
if why == "" {
return nil, errors.New("say why the objects of deleted keys are dropped")
}
taken, err := meshhandactsclient.Recorder{Ask: ask}.Record(meshhandactsclient.Request{What: inputsDropTool, Why: why + " (" + stdio.CallerOf(args) + ")", Cause: "inputs-drop"})
if err != nil {
return nil, fmt.Errorf("the hand act was not recorded, so nothing was removed: %w", err)
}
dropped, bytes, err := k.dropKeyGone()
out := []map[string]any{}
for _, o := range dropped {
out = append(out, map[string]any{"object": o.Name, "key": o.Key, "size": o.Size})
}
return map[string]any{"dropped": out, "count": len(out), "bytes": bytes, "hand-act": taken.Log}, err
}}
}
// heardStepEnded hands the end a build seat's step-ended names to the composition run of that ask (A-240, §719), which writes it
// in the run's key, and then deletes the input kept for the ask (design 47 G §354): the run's end first, so no other act delays
// it past its bound (A-470o, A-470p). One whose run's end cannot be written, or whose input cannot be deleted, is given again by
// the bus; its redelivery finds the run ended, said as ignored for the run, and still deletes the input.
func heardStepEnded(k *inputKeeper, runEnded func(buildstep.StepEnded) error, m jetstream.Msg, logf func(string, ...any)) {
var e buildstep.StepEnded
if err := json.Unmarshal(m.Data(), &e); err != nil {
logf("%s holds what is no step-ended, left: %v", m.Subject(), err)
_ = m.Ack()
return
}
if runEnded != nil {
if err := runEnded(e); err != nil {
logf("the composition run of the ask %s is not ended, so the bus gives its step-ended again: %v", e.Ask, err)
_ = m.Nak()
return
}
}
if err := k.ended(e.Ask); err != nil {
logf("inputs: the input of the ask %s could not be deleted, so the bus gives it again: %v", e.Ask, err)
_ = m.Nak()
return
}
if ends != nil {
ends.heard(e)
}
_ = m.Ack()
}
@@ -3,8 +3,10 @@ package main
import (
"bytes"
"crypto/rand"
"encoding/base64"
"encoding/json"
"errors"
"fmt"
"sort"
"strings"
"sync"
@@ -14,6 +16,7 @@ import (
"github.com/nats-io/nats.go"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-sdk/go/buscalls"
"git.novox.be/novox/mesh-sdk/go/stateobjects"
)
@@ -22,6 +25,8 @@ type kvMem struct {
mu sync.Mutex
vals map[string][]byte
revs map[string]uint64
// delErr, when set, fails the next Delete once.
delErr error
}
func newKVMem() *kvMem { return &kvMem{vals: map[string][]byte{}, revs: map[string]uint64{}} }
@@ -56,6 +61,10 @@ func (k *kvMem) Update(key string, v []byte, rev uint64) error {
func (k *kvMem) Delete(key string) error {
k.mu.Lock()
defer k.mu.Unlock()
if err := k.delErr; err != nil {
k.delErr = nil
return err
}
delete(k.vals, key)
return nil
}
@@ -71,8 +80,9 @@ func (k *kvMem) Keys() ([]string, error) {
}
type objectsMem struct {
mu sync.Mutex
objs map[string][]byte
mu sync.Mutex
objs map[string][]byte
listErr error // List fails with it
}
func (*objectsMem) MostBytes() int { return 0 }
@@ -91,8 +101,24 @@ func (o *objectsMem) Get(name string) ([]byte, error) {
}
return d, nil
}
func (o *objectsMem) Delete(string) error { return nil }
func (o *objectsMem) List() ([]stateobjects.Object, error) { return nil, nil }
func (o *objectsMem) Delete(name string) error {
o.mu.Lock()
defer o.mu.Unlock()
delete(o.objs, name)
return nil
}
func (o *objectsMem) List() ([]stateobjects.Object, error) {
o.mu.Lock()
defer o.mu.Unlock()
if o.listErr != nil {
return nil, o.listErr
}
var out []stateobjects.Object
for n, d := range o.objs {
out = append(out, stateobjects.Object{Name: n, Size: int64(len(d))})
}
return out, nil
}
// lineMem is a core bus in memory: a chunk published is kept, and its acknowledgement heard at once.
type lineMem struct {
@@ -228,4 +254,250 @@ func TestAnInputIsDeletedAtItsStepEndedOrAfterADay(t *testing.T) {
if _, err := k.body(d2); err == nil {
t.Error("an input a day old is still kept at the next ask")
}
// A-470o, A-470p: the step-ended's run end is written before the input is deleted; a delete that fails asks the event again,
// whose redelivery finds the run ended and still deletes the input; a run end not written asks it again with the input kept.
for _, c := range []struct {
name string
delErr error
runErr error
naked bool
runs int
deleted bool
}{
{name: "the run's end before the input's delete", runs: 1, deleted: true},
{name: "an input not deleted asks the event again", delErr: errors.New("the bus is away"), naked: true, runs: 2, deleted: true},
{name: "a run's end not written asks the event again", runErr: errors.New("the run is not read"), naked: true, runs: 1},
} {
t.Run(c.name, func(t *testing.T) {
k := testKeeper(&objectsMem{objs: map[string][]byte{}}, time.Now)
d, _ := k.keep("ask/run", []byte(`{"heads":"abc"}`))
k.vals.KV.(*kvMem).delErr = c.delErr
runs := 0
runEnded := func(e buildstep.StepEnded) error {
runs++
if _, err := k.body(d); err != nil {
t.Errorf("the run's end is written after the input's delete (%d)", runs)
}
return c.runErr
}
raw, _ := json.Marshal(buildstep.StepEnded{Ask: "ask/run"})
m := &heardMsg{data: raw, subject: "step-ended"}
heardStepEnded(k, runEnded, m, t.Logf)
if m.naked != c.naked || m.acked == c.naked {
t.Fatalf("acked %v, naked %v, want naked %v", m.acked, m.naked, c.naked)
}
if m.naked && c.delErr != nil { // the redelivery
m = &heardMsg{data: raw, subject: "step-ended"}
heardStepEnded(k, func(e buildstep.StepEnded) error { runs++; return nil }, m, t.Logf)
}
if _, err := k.body(d); runs != c.runs || (err != nil) != c.deleted {
t.Errorf("the run's end heard %d times (want %d), the input deleted %v (want %v)", runs, c.runs, err != nil, c.deleted)
}
})
}
}
// Design 47 G A-465: an input the assigner ends itself (the step-ended of its ask, the sweep of a day-old key) ends its object
// too; the objects of keys another part deleted are removed by dropKeyGone and by the tool assigner_inputs_drop, which lists
// them as key-gone first, and never removes an object a key names.
func TestAnEndedInputEndsItsObjectAndTheDropToolRemovesWhatAKeyLeft(t *testing.T) {
now := time.Date(2026, 11, 17, 10, 0, 0, 0, time.UTC)
objs := &objectsMem{objs: map[string][]byte{}}
k := testKeeper(objs, func() time.Time { return now })
big := func(b byte) []byte { return bytes.Repeat([]byte{b}, 2<<20) }
if _, err := k.keep("ask-one", big('a')); err != nil {
t.Fatal(err)
}
if _, err := k.keep("ask-two", big('b')); err != nil {
t.Fatal(err)
}
if len(objs.objs) != 2 {
t.Fatalf("objects = %d, want 2", len(objs.objs))
}
if err := k.ended("ask-one"); err != nil || len(objs.objs) != 1 {
t.Fatalf("the step-ended left %d objects (%v), want 1", len(objs.objs), err)
}
now = now.Add(25 * time.Hour)
if _, err := k.keep("ask-three", big('c')); err != nil {
t.Fatal(err)
}
if len(objs.objs) != 1 {
t.Fatalf("after the sweep of the day-old input %d objects, want only the new one", len(objs.objs))
}
// An object whose key another part deleted is listed as key-gone and removed by the tool; a live one stays.
keys, _ := k.vals.KV.Keys()
for _, key := range keys {
if !strings.HasPrefix(key, inputsAskPrefix) {
if err := k.vals.KV.Delete(key); err != nil {
t.Fatal(err)
}
}
}
live := []byte(`{"heads":"x"}`)
if _, err := k.keep("ask-four", append(live, make([]byte, 2<<20)...)); err != nil {
t.Fatal(err)
}
list, err := inputsRead(k).Run(map[string]any{})
if err != nil || len(list.(map[string]any)["key-gone"].([]map[string]any)) != 1 {
t.Fatalf("assigner_inputs key-gone = %+v %v, want the one object of the deleted key", list, err)
}
ask := func(string, any) (json.RawMessage, error) {
return json.RawMessage(`{"answer":{"log":"hand-acts"}}`), nil
}
if _, err := inputsDrop(k, ask).Run(map[string]any{}); err == nil {
t.Error("dropped with no reason")
}
out, err := inputsDrop(k, ask).Run(map[string]any{"why": "a key left its object"})
if err != nil || out.(map[string]any)["count"] != 1 || len(objs.objs) != 1 {
t.Fatalf("assigner_inputs_drop = %+v %v, %d objects left: want one removed and the live one kept", out, err, len(objs.objs))
}
// The start drops what a key left, said with its count and bytes.
if _, err := k.keep("ask-five", live); err != nil {
t.Fatal(err)
}
for _, key := range keysOf(t, k) {
if !strings.HasPrefix(key, inputsAskPrefix) {
_ = k.vals.KV.Delete(key)
}
}
var logged []string
k.logf = func(f string, a ...any) { logged = append(logged, fmt.Sprintf(f, a...)) }
before := len(objs.objs)
k.dropAtStart()
if len(objs.objs) != 0 || before == 0 || len(logged) != 1 || !strings.Contains(logged[0], fmt.Sprintf("%d objects of deleted keys removed at the start", before)) || !strings.Contains(logged[0], " bytes") {
t.Errorf("the start left %d of %d objects and said %q: want every key-gone object removed and its count and bytes said", len(objs.objs), before, logged)
}
}
func keysOf(t *testing.T, k *inputKeeper) []string {
t.Helper()
keys, err := k.vals.KV.Keys()
if err != nil {
t.Fatal(err)
}
return keys
}
// Design 47 G A-465: assigner_inputs says why key-gone objects are not known when the objects cannot be listed, and never
// answers them as none.
func TestAssignerInputsSaysWhenTheKeyGoneObjectsCannotBeListed(t *testing.T) {
objs := &objectsMem{objs: map[string][]byte{}, listErr: errors.New("the object store does not answer")}
k := testKeeper(objs, time.Now)
out, err := inputsRead(k).Run(map[string]any{})
if err != nil {
t.Fatal(err)
}
m := out.(map[string]any)
if msg, _ := m["key-gone-error"].(string); !strings.Contains(msg, "does not answer") {
t.Errorf("answer %+v: want key-gone-error naming the failure", m)
}
if _, has := m["key-gone"]; has {
t.Errorf("answer %+v: an unreadable store is not answered as no key-gone objects", m)
}
}
// Design 47 G A-465a: an input is kept once per content under its sha256 alone; every ask names the digest it uses, and the input
// goes, with its object, at the step-ended of the last ask that names it, or a day after its last write; a request the cap still
// refuses says the fill; an input of the old form (a key that is no digest) is ended with its object.
func TestAnInputIsKeptOncePerContentAndEndsWithItsLastAsk(t *testing.T) {
now := time.Date(2026, 11, 17, 10, 0, 0, 0, time.UTC)
objs := &objectsMem{objs: map[string][]byte{}}
k := testKeeper(objs, func() time.Time { return now })
body := bytes.Repeat([]byte{'n'}, 2<<20)
var digests []string
for _, ask := range []string{"ask-1", "ask-2", "ask-3"} {
d, err := k.keep(ask, body)
if err != nil {
t.Fatal(err)
}
digests = append(digests, d)
}
if digests[0] != digestOf(body) || digests[1] != digests[0] || digests[2] != digests[0] {
t.Fatalf("digests = %v, want the sha256 of the bytes each time", digests)
}
if _, err := k.vals.KV.Get(digests[0]); err != nil {
t.Fatal(err)
}
if e, _ := k.vals.KV.Get(digests[0]); e == nil || len(objs.objs) != 1 {
t.Fatalf("one key by the digest and one object wanted, got entry %v and %d objects", e, len(objs.objs))
}
for _, key := range keysOf(t, k) {
if !strings.HasPrefix(key, inputsAskPrefix) && key != digests[0] {
t.Errorf("a key %q beside the one input", key)
}
}
if e, _ := k.vals.KV.Get(inputsAskPrefix + "ask-2"); e == nil || !strings.Contains(string(e.Value), digests[0]) || !strings.Contains(string(e.Value), "20261117T100000Z") {
t.Errorf("the ask does not name the digest it uses: %v", e)
}
for _, ask := range []string{"ask-1", "ask-2"} {
if err := k.ended(ask); err != nil {
t.Fatal(err)
}
if _, err := k.body(digests[0]); err != nil {
t.Fatalf("the input went at the end of %s while ask-3 still names it: %v", ask, err)
}
}
if err := k.ended("ask-3"); err != nil {
t.Fatal(err)
}
if _, err := k.body(digests[0]); err == nil || len(objs.objs) != 0 || len(keysOf(t, k)) != 0 {
t.Errorf("the last step-ended left the input (%v), %d objects, keys %v", err, len(objs.objs), keysOf(t, k))
}
// a day after its last write, a renewed write counted
if _, err := k.keep("ask-4", body); err != nil {
t.Fatal(err)
}
now = now.Add(20 * time.Hour)
if _, err := k.keep("ask-5", body); err != nil {
t.Fatal(err)
}
now = now.Add(20 * time.Hour)
if _, err := k.keep("ask-6", []byte("other")); err != nil {
t.Fatal(err)
}
if _, err := k.body(digests[0]); err != nil {
t.Errorf("an input written again 20 hours ago was swept: %v", err)
}
now = now.Add(25 * time.Hour)
if _, err := k.keep("ask-7", []byte("another")); err != nil {
t.Fatal(err)
}
if _, err := k.body(digests[0]); err == nil || len(objs.objs) != 0 {
t.Errorf("an input a day after its last write is kept (%v), %d objects", err, len(objs.objs))
}
// an input of the old form goes a day after the time its key carries, with its object, never earlier
old := "20261117T090000Z." + digestOf([]byte("old"))
if err := k.vals.Put(old, base64.StdEncoding.EncodeToString(bytes.Repeat([]byte{'o'}, 2<<20))); err != nil {
t.Fatal(err)
}
recent := now.Add(-time.Hour).Format(inputsTime) + "." + digestOf([]byte("recent"))
if err := k.vals.Put(recent, "cmVjZW50"); err != nil {
t.Fatal(err)
}
if err := k.sweep(); err != nil {
t.Fatal(err)
}
if e, _ := k.vals.KV.Get(old); e != nil || len(objs.objs) != 0 {
t.Errorf("the input of the old form is kept (%v) with %d objects", e, len(objs.objs))
}
if e, _ := k.vals.KV.Get(recent); e == nil {
t.Error("an input of the old form under a day old was deleted early")
}
// a new content the cap refuses says the fill; the same content, already kept, needs no room
full := newTestKeeperWithFill(objs, now, inputsCap-10)
if _, err := full.keep("ask-8", []byte("fits")); err != nil {
t.Fatalf("a content that fits is refused: %v", err)
}
if _, err := full.keep("ask-9", []byte("does not fit at all")); err == nil || !strings.Contains(err.Error(), "bytes kept") {
t.Errorf("the refusal does not name the fill: %v", err)
}
if _, err := full.keep("ask-10", []byte("fits")); err != nil {
t.Errorf("the content already kept is refused at the cap: %v", err)
}
}
func newTestKeeperWithFill(objs *objectsMem, now time.Time, used int64) *inputKeeper {
k := testKeeper(objs, func() time.Time { return now })
k.used = func() (int64, error) { return used, nil }
return k
}
File diff suppressed because it is too large Load Diff
@@ -9,9 +9,12 @@ package main
import (
"context"
"fmt"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/nodebuildgo"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-sdk/go/buscalls"
"git.novox.be/novox/mesh-sdk/go/buscompose"
"io"
"log"
"maps"
@@ -22,6 +25,7 @@ import (
"os/signal"
"slices"
"strings"
"sync/atomic"
"syscall"
"time"
@@ -30,7 +34,6 @@ import (
mma "git.novox.be/novox/mesh-contracts/go/seats/meshmoduleassigner"
mcseat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshwatchdogs"
occ "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/clients/operatorchannelclient"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
@@ -40,12 +43,16 @@ import (
"git.novox.be/novox/mesh-sdk/go/seatlist"
"git.novox.be/novox/mesh-contracts/go/clients/nodeengineclient/enginereads"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
"git.novox.be/novox/mesh-sdk/go/views"
"mesh-delivery-assigner/internal/assign"
plc "mesh-delivery-assigner/internal/assignment"
)
// composeCallBound is how long the program's calls wait for an answer (main).
const composeCallBound = 3 * time.Minute
func main() {
if os.Getenv(process.BrokerFileEnv) == "" {
// Started by the tool runner, with no credential of its own: the put's tools (ADR 0546), served through the runtime,
@@ -56,6 +63,10 @@ func main() {
}
return
}
// A call waits up to composeCallBound for its answer: compose-candidate composes a whole revision in shadow on each node and
// answered in about 34 s on g14 and shanks (2026-11-16 23:27), past the SDK's 30 s, so every composition step could not run.
// A responder that is absent still answers at once. To be replaced by a bound per verb from the seat's definition.
process.CallTimeout = composeCallBound
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
if err := run(ctx, os.Getenv, os.Stderr); err != nil {
@@ -69,7 +80,6 @@ func main() {
var readBuckets = []string{
buckets.Grants,
buckets.Have,
buckets.Provisions,
}
// readFamilies are the states kept one bucket per node the assigner reads, each named in its manifest's reads: every
@@ -82,11 +92,11 @@ func ownBuckets() []string {
return []string{buckets.Asks(), buckets.Differences(),
buckets.Puts(), buckets.Wants(), plc.AssignmentsBucket(), plc.ProposalsBucket(),
plc.CandidatesBucket(), plc.PulsesBucket(), assign.FindingsBucket(), assign.PoliciesBucket(), plc.SeatHoldersBucket(),
engineReadsBucket(), retiredBucket(), copiesBucket(), writtenBucket(), buckets.Waits(), buckets.PutWaits(), buckets.DeliveryWaits(), buckets.DeliveredAgain(), buckets.Inputs(), pinsBucket()}
engineReadsBucket(), retiredBucket(), copiesBucket(), writtenBucket(), buckets.Waits(), buckets.PutWaits(), buckets.Inputs(), buckets.CompositionRuns(), buckets.Taken()}
}
// engineReadsState is the assigner's state of what each node's engine states it reads (ADR 0618 §3), one key `<node>`, as
// the verb manifest-reads last answered it or the fallback read it: what assigner_engine_reads lists and asks again.
// engineReadsState is the assigner's state of what each node's engine says it reads (design 47 H-A-104), one key `<node>`
// whose value is the words and the time of the last manifest-reads-changed heard of it: what assigner_engine_reads lists.
const engineReadsState = "engine-reads"
// engineReadsBucket is that state's bucket.
@@ -126,11 +136,10 @@ var keptStates = []announce.State{
{Name: copiesState, Readable: true},
{Name: writtenState, Readable: true},
{Name: buckets.WaitsState, Readable: true},
{Name: buckets.PutWaitsState, Readable: true}, // the put waits said (putwaits.go, design 47 G A-211)
{Name: buckets.DeliveryWaitsState, Readable: true}, // the delivery waits said (delivered.go, design 47 G A-246)
{Name: buckets.DeliveredAgainState, Readable: true}, // the asks of assigner_delivered_again (delivered.go, design 47 G A-250)
{Name: buckets.InputsState, Readable: true}, // read by the tool process alone: the verb input and assigner_inputs (design 47 G §354)
{Name: pinsState, Readable: true}, // the records pinning each assignment graph revision (design 47 G §579)
{Name: buckets.PutWaitsState, Readable: true}, // the put waits said (putwaits.go, design 47 G A-211)
{Name: buckets.InputsState, Readable: true}, // read by the tool process alone: the verb input and assigner_inputs (design 47 G §354)
{Name: buckets.CompositionRunsState, Readable: true}, // the composition runs, read by the process and its tools (design 47 G §719, A-468c)
{Name: process.TakenState, Readable: true}, // the asks of the seat mesh-wants taken once, and their drops (design 47 H2 §775, §777)
}
// kvSet is every bucket the assigner opened, by name.
@@ -159,12 +168,6 @@ func open(ctx context.Context, js process.BucketOpener, logf func(string, ...any
logf("the bucket %s cannot be opened (%v): it is bound once the bus says it was made", name, err)
continue
}
if name == buckets.Provisions && err != nil {
// The seat mesh-provisioner's state, with its own delivery (ADR 0570 §4): bound once the bus says it was made;
// until then no want waits for a provision, as before.
logf("the bucket %s cannot be opened (%v): it is bound once the bus says it was made", name, err)
continue
}
if name == assign.PoliciesBucket() && err != nil {
// The seat mesh-wants' state, new with it (ADR 0565 §7): bound once the bus says it was made; until then no
// person's policy is read, so the controller's beside each composition holds, as before.
@@ -178,8 +181,8 @@ func open(ctx context.Context, js process.BucketOpener, logf func(string, ...any
continue
}
if name == engineReadsBucket() && err != nil {
// New with ADR 0618 §3: without it the statements the verb answers are kept in memory only, and
// assigner_engine_reads lists nothing.
// Without it the words each manifest-reads-changed says are kept in memory only, and assigner_engine_reads
// lists nothing.
logf("the bucket %s cannot be opened (%v): what each node's engine reads is kept in memory only until it starts again", name, err)
continue
}
@@ -188,27 +191,12 @@ func open(ctx context.Context, js process.BucketOpener, logf func(string, ...any
logf("the bucket %s cannot be opened (%v): it is read by the tool process alone", name, err)
continue
}
if name == pinsBucket() && err != nil {
// New with the pins (design 47 G §579): without it no pin is kept and no revision is removed.
logf("the bucket %s cannot be opened (%v): no pin is kept and no revision removed until it starts again", name, err)
continue
}
if name == buckets.Waits() && err != nil {
// New with the wait on an outside cause (design 47 G §706): without it no wait is made, and a failing check is judged
// as before.
logf("the bucket %s cannot be opened (%v): no outside wait is kept until the assigner starts again", name, err)
continue
}
if name == buckets.DeliveredAgain() && err != nil {
// New with A-250: without it assigner_delivered_again is not taken until the assigner starts again.
logf("the bucket %s cannot be opened (%v): no version is said delivered again until the assigner starts again", name, err)
continue
}
if name == buckets.DeliveryWaits() && err != nil {
// New with A-246: without it no dependent waits for its dependency's delivery until the assigner starts again.
logf("the bucket %s cannot be opened (%v): no delivery wait is kept until the assigner starts again", name, err)
continue
}
if name == buckets.PutWaits() && err != nil {
// New with A-211: without it no put's wait is said until the assigner starts again.
logf("the bucket %s cannot be opened (%v): no put's wait is said until the assigner starts again", name, err)
@@ -237,8 +225,8 @@ func open(ctx context.Context, js process.BucketOpener, logf func(string, ...any
// states and those new with a delivery of their own, bound once made, and the two that choose the grants' source.
func startsWithout(name string) bool {
switch name {
case plc.SeatHoldersBucket(), buckets.Provisions, assign.PoliciesBucket(), assign.FindingsBucket(),
buckets.Puts(), engineReadsBucket(), retiredBucket(), writtenBucket(), buckets.Waits(), buckets.PutWaits(), buckets.DeliveryWaits(), buckets.DeliveredAgain(), buckets.Inputs(), pinsBucket():
case plc.SeatHoldersBucket(), assign.PoliciesBucket(), assign.FindingsBucket(),
buckets.Puts(), engineReadsBucket(), retiredBucket(), writtenBucket(), buckets.Waits(), buckets.PutWaits(), buckets.Inputs():
return true
}
return slices.Contains(seatBuckets(), name) || name == buckets.Grants
@@ -294,10 +282,10 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
// The inputs of the composition steps it asks a build seat to run: the seat mesh-wants' verb input is answered here in chunks
// of the core connection, of any size (design 47 G §354, §712, A-237).
inputs := inputsOver(kvs[buckets.Inputs()], js, account.Module, logger.Printf)
// The seat list (seatlist.go), followed in follow over the connection and the hub: the verb input's callers are checked
// against the seat's definition it holds (A-186).
gate := seatlist.NewPart("assigner", seatListAgainCallers)
// The seat list (seatlist.go), followed in follow over the connection and the hub.
gate := seatlist.NewPart("assigner")
if inputs != nil {
inputs.dropAtStart() // the objects of keys another part deleted (A-465)
stopInput, err := said.AnswerSeat(meshwants.Seat, seatlist.Definition(gate.Reader, meshwants.Seat), map[string]process.SeatHandler{meshwants.VerbInput: inputs.verb(conn, buscalls.SeatAckWithin)})
if err != nil {
return fmt.Errorf("answering the verb input: %w", err)
@@ -378,14 +366,11 @@ func watched() []string {
buckets.Differences(),
buckets.Wants(),
assign.PoliciesBucket(),
buckets.Provisions,
plc.SeatHoldersBucket(),
engineReadsBucket(),
writtenBucket(),
buckets.Waits(),
buckets.PutWaits(),
buckets.DeliveryWaits(),
buckets.DeliveredAgain(), // its watch wakes a pass at once on an ask of assigner_delivered_again (A-250)
}
}
@@ -393,8 +378,6 @@ func watched() []string {
// each change; changes that come during a pass make one more. It returns when ctx ends or a watch ends.
func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber, kvs kvSet, say func(oc.Condition) error, findings assign.Findings, bus caller, iv *catalogViews, inputs *inputKeeper, gate *seatlist.Part, logger *log.Logger, getenv func(string) string) error {
w := newWorld()
// The callers' seat entries are resolved from the assigner's own seat-holders as it last read them (A-298).
gate.Holders(seatlist.HoldersIn(func() (map[string][]byte, error) { return w.read(plc.SeatHoldersBucket()), nil }))
dirty := make(chan struct{}, 1)
wake := func() {
select {
@@ -404,16 +387,11 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
}
errs := make(chan error, len(watched())+2)
settled := make(chan struct{}, len(watched())+2)
// What each node's engine reads (ADR 0618 §3, §4): asked through the seat's verb, kept in the state engine-reads, read
// from the node's record where the engine does not answer (the fallback, said in the journal).
reads := &enginereads.Keeper{Fallback: w.recordReads, Changed: wake, Logf: logger.Printf}
if bus != nil {
reads.Call = bus.CallKeptOn // a kept call, called again through a transport fault (ADR 0668 §1)
reads.Once = bus.CallOn // its fault keeps the fallback at once while the kept call asks on (ADR 0668 §3)
}
// What each node's engine reads (design 47 H-A-104): the words of its manifest-reads-changed, kept in the state
// engine-reads and read back from its watch, so a restart loses none; no verb is asked.
reads := &engineReadsKept{changed: wake}
if kv := kvs[engineReadsBucket()]; kv != nil {
reads.Put = func(node string, v []byte) error { _, err := kv.Put(ctx, node, v); return err }
reads.Delete = func(node string) error { return kv.Delete(ctx, node) }
reads.put = func(node string, v []byte) error { _, err := kv.Put(ctx, node, v); return err }
}
watch := func(name string, opts ...jetstream.WatchOpt) error {
kw, err := kvs[name].WatchAll(ctx, opts...)
@@ -449,7 +427,9 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
value = e.Value()
}
if name == engineReadsBucket() {
reads.Heard(e.Key(), value, value == nil) // it wakes a pass when a statement changed
if err := reads.take(e.Key(), value, value == nil); err != nil { // it wakes a pass when the words changed
logger.Printf("%v", err)
}
continue
}
w.putEntry(name, e.Key(), value, e.Revision(), e.Created())
@@ -516,17 +496,35 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
gate.Follow(seatlist.ProcessBus(bus.Call, hub), wake, logger.Printf)
}
// The build seat's step-ended of an ask deletes the input kept for it (design 47 G §354) and ends the composition run that waits
// for it (A-240); the watchman's machine-away and machine-back say which machines a composition step does not compose (§64,
// §389). Registered before the hub starts.
ends, away := &runEnds{}, &awayNodes{}
if inputs != nil {
if err := hub.Handle(nodebuildgo.SubjectStepEndedAll, func(m jetstream.Msg) { heardStepEnded(inputs, ends, m, logger.Printf) }); err != nil {
// for it (A-240). The machines a composition step does not compose are the watchman's machine-away, heard once, in the world (§64, §389).
// The composition runs (design 47 G §718, §719), watched in their own state; a build seat's step-ended of a run's ask ends
// the run in its key.
var runs *compositionRuns
if kv := kvs[buckets.CompositionRuns()]; kv != nil {
set, err := runSettingsOf(getenv)
if err != nil {
return err
}
runs = newCompositionRuns(busRuns{ctx, js, kv}, set, time.Now, logger.Printf)
if js != nil {
runs.say = wantsPublisher(ctx, js, thisNode)
}
if bus != nil {
runs.drop = dropOver(bus.CallKept)
}
// The build seats' ask-taken and step-progress begin a run's clock (§720, A-466q).
if err := hearRunBounds(hub, runs, logger.Printf); err != nil {
logger.Printf("the build seats' ask-taken and step-progress are not heard, so a composition run is ended by no bound: %v", err)
}
}
for subject, isAway := range map[string]bool{meshwatchdogs.SubjectMachineAwayAll: true, meshwatchdogs.SubjectMachineBackAll: false} {
if err := hub.Handle(subject, func(m jetstream.Msg) { heardPresence(away, isAway, m, logger.Printf) }); err != nil {
logger.Printf("%s is not heard, so a composition step asks a machine that sleeps: %v", subject, err)
if inputs != nil {
var runEnded func(buildstep.StepEnded) error
if runs != nil && bus != nil {
read := func(e buildstep.StepEnded) ([]byte, error) { return e.ReadOutput(buildstep.AskGo, bus.CallFile) }
runEnded = func(e buildstep.StepEnded) error { return runs.heardEnd(e, read) }
}
if err := hub.Handle(nodebuildgo.SubjectStepEndedAll, func(m jetstream.Msg) { heardStepEnded(inputs, runEnded, m, logger.Printf) }); err != nil {
return err
}
}
// The indexer's manifests, modules and module graph, through its first views and views family, never its buckets
@@ -558,7 +556,7 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
}
}
// And the two that choose where grants are read from, with the same delivery as the grants part that writes one.
for _, name := range []string{buckets.Grants, assign.PoliciesBucket(), buckets.Provisions, plc.SeatHoldersBucket()} {
for _, name := range []string{buckets.Grants, assign.PoliciesBucket(), plc.SeatHoldersBucket()} {
if kvs[name] == nil && js != nil {
name := name
process.AwaitBucket(ctx, js, nc, name, "until then the bucket is not read",
@@ -587,7 +585,14 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
}
}
p := &passer{kvs: kvs, w: w, logf: logger.Printf, say: say, findings: findings, said: map[string]bool{}, answeredAt: map[string]uint64{},
reads: reads, seats: gate}
reads: reads, seats: gate, askForFile: getenv("MESH_ASSIGNER_ASK_OPERATOR_FOR_FILE"), listed: iv.listed}
p.askOperatorFor() // the setting ask-operator-for said once at the start (design 47 G A-425a)
// The setting tier-bound (design 47 H §751) and the one timer that wakes the pass at a tier's deadline (H-A-56).
tierBound, err := tierBoundSetting(getenv)
if err != nil {
return err
}
p.tierBound, p.tierWake = tierBound, wake
// The wait on an outside cause (outside.go, design 47 G §706): the keeper's three events say when to judge again, and the
// seat mesh-wants' wait-held and wait-ended are said; registered before the hub starts.
if bus != nil && kvs[buckets.Waits()] != nil {
@@ -607,39 +612,38 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
logger.Printf("%s is not heard, so a wait on an outside cause is judged again only when its check changes: %v", subject, err)
}
}
p.outside.readStart()
}
if js != nil {
p.publishWants = wantsPublisher(ctx, js, thisNode)
if iv != nil && iv.h != nil {
objects := newBusObjects(js, process.Account{Node: thisNode, Module: assignment.Module()}, assigngraph.RevisionsObjects)
p.graph = &graphKeeper{objects: objects, halves: iv.h.views}
// The keeping and removing of revisions runs off the pass loop, and a keeping that changed what the pass reads wakes
// one (design 47 H-A-259).
retry, err := keepingRetry()
if err != nil {
return err
}
p.graph = &graphKeeper{objects: objects, halves: iv.h.views, background: func(f func()) { go f() }, wake: wake, retry: retry,
reads: newBusObjects(js, process.Account{Node: thisNode, Module: assignment.Module()}, assigngraph.RevisionsObjects)}
keep := func(ctx context.Context, ev meshcatalog.CatalogRevisionEvent) error {
return p.keepCandidate(ctx, iv.call, ev)
}
iv.candidates.Store(&keep)
// A held revert's running entry and its want's, asked of the seat mesh-catalog's verb entry (design 47 G §710, A-217).
p.entries = meshcatalogclient.NewEntries(iv.h.call)
p.entries.Changed = func(meshcatalogclient.EntryRow) { wake() }
// The pins of the revisions (pins.go, design 47 G §579): the gate's pinned, freed, heads-replaced and pins-stated
// on the hub, registered before it starts.
if kv := kvs[pinsBucket()]; kv != nil {
k := &pinKeeper{ctx: ctx, st: kvEnds{ctx, kv}, objects: objects, inUse: inUseOf(w), findings: findings, now: time.Now, logf: logger.Printf}
if err := k.made(); err != nil {
logger.Printf("the state %s is not marked made, so no revision is removed until it is: %v", pinsState, err)
}
if err := hearPins(hub, k); err != nil {
logger.Printf("a pin is not heard, so no revision is removed until the assigner starts again: %v", err)
} else {
p.graph.pins = k
k.watchUnpins(kv)
}
entryAsks, err := settingFile(getenv("MESH_ASSIGNER_ENTRY_ASKS_FILE"))
if err != nil {
return err
}
p.entries = entriesOf(iv.h.branches, iv.h.call, entryAsks, iv.writer, wake)
askAgainOnReconnect(ctx, nc, p.entries)
// The revisions that are not current are removed when one ceases to be current and once now (revisions.go,
// design 47 H §764, H-A-86).
p.graph.revisions = &revisionRemover{ctx: ctx, objects: objects, inUse: inUseOf(w), logf: logger.Printf}
// The start's removal of the revisions not current folds into the first pass's keeping (H-A-261).
}
}
// The node-engine seat's manifest-reads-changed, for one node (ADR 0618 §4): that node is asked again, with no timer.
// Heard on the assigner's durable consumer on EVENTS, which the grants part makes from the manifest's consumes; where it
// is not there yet, a node is asked again only when it comes back online.
// The node-engine seat's manifest-reads-changed, for one node (design 47 H-A-104): its words are written into the state
// engine-reads. Heard on the assigner's durable consumer on EVENTS, which the grants part makes from the manifest's consumes.
if js != nil {
// The teller's ask-ended (issue 1966): an ask ended at the channel without an answer is written again; registered
// before hearReadsChanged starts the hub.
@@ -653,19 +657,16 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
p.ends = newPipelineEnds(kvEnds{ctx, kv}, wake, logger.Printf)
p.ends.trunk = w.trunkName
p.ends.runEnded = func(group string) error { return p.dropCandidate(ctx, group) }
err := hearEnds(hub, p.ends)
if err == nil && bus != nil {
err = followRegistrations(ctx, hub, bus.Call, p.ends)
if err := hearEnds(hub, p.ends); err != nil {
logger.Printf("a pipeline's end is not heard, so the wants keep the trunk-only form until the assigner starts again: %v", err)
}
if err != nil {
logger.Printf("a pipeline's end or a registration is not heard, so the wants keep the trunk-only form until the assigner starts again: %v", err)
// The registrations come from the catalog half's one follower, its one handler of registration-changed (H-A-270 (3)).
if iv == nil || iv.h == nil || !iv.h.followRegistrations(p.ends.registered) {
logger.Printf("the registrations are not followed, so the wants keep the trunk-only form until the assigner starts again: the catalog half is not followed")
}
}
hearDelivery(ctx, js, w, wake, findings, logger.Printf) // version-released, version-delivered, machine-away and machine-back
hearReleases(ctx, js, w, wake, findings, logger.Printf) // version-released, machine-away and machine-back
hearBuilds(ctx, js, &w.ends, wake, findings, logger.Printf)
if err := hearTaken(hub, &w.taken, wake, logger.Printf); err != nil {
logger.Printf("the indexer's take-ins are not heard, so an entry held by an order edge waits until the assigner starts again: %v", err)
}
hearReadsChanged(ctx, js, hub, reads, findings, gate.EventsLive, logger.Printf)
hearRunning(ctx, js, w, wake, findings, logger.Printf)
}
@@ -673,15 +674,64 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
p.acts = newPutActs(bus, wake, logger.Printf)
}
// The composition step (design 47 G §22, §354): the seat mesh-wants' accepted kind step, run by one run ask per machine.
if bus != nil && js != nil && inputs != nil && p.publishWants != nil {
run := &compositionRun{inputs: &compositionInputs{machines: w.machinesOf, call: bus.CallKeptOn}, keeper: inputs, call: bus.CallKept,
trunk: trunkOf(iv, w.trunkName), running: w.runningOf, away: away, put: runAskPublisher(js), ends: ends, ask: bus.CallFile, now: time.Now, logf: logger.Printf}
steps := &compositionSteps{node: thisNode, say: p.publishWants, run: run.run, now: time.Now, logf: logger.Printf,
asker: stepAskerOf(seatlist.Definition(gate.Reader, meshwants.Seat))}
if err := serveCompositionSteps(ctx, nc, steps); err != nil {
logger.Printf("the composition step is not heard, so no composition step runs until the assigner starts again: %v", err)
} else {
logger.Printf("the composition step is heard on %s", meshwants.AcceptSubjectStep)
if bus != nil && js != nil && inputs != nil && p.publishWants != nil && runs != nil {
askBound, err := composeAskBound()
if err != nil {
return err
}
run := &compositionRun{runs: runs, inputs: &compositionInputs{machines: w.machinesOf, callFile: bus.CallFileKept, bound: askBound}, keeper: inputs, reads: &compositionReads{}, call: bus.CallKept, callFile: bus.CallFileKept,
trunk: trunkOf(iv, w.trunkName), newest: iv.newestOf(), watched: iv.watchedOf, assigned: w.assignedOn, assignment: w.assignmentOf, findings: findings, running: w.runningOf, away: func(machine string) bool { return w.awayNow()[machine] }, put: runAskPublisher(js), ask: bus.CallFile, now: time.Now, logf: logger.Printf}
// The seat's work queue (design 47 H2 §777): pulled through its one worker, each ask taken once in the state taken.
takenBound, err := askTakenBound()
if err != nil {
return err
}
var ackWait atomic.Int64 // the worker's ack wait, read when it is bound
ackWait.Store(int64(buscompose.SeatQueueDefaultAckWait))
steps := &compositionSteps{node: thisNode, say: p.publishWants, run: run.run, resume: run.resume,
validate: run.validate, resumeValidate: run.resumeValidate, ended: runs.stepEnded, now: time.Now, logf: logger.Printf,
takenBound: takenBound, inProgress: inProgressOf(seatlist.Definition(gate.Reader, meshwants.Seat), func() time.Duration { return time.Duration(ackWait.Load()) })}
if e, ok := bus.(emitting); ok {
steps.taken = e.State(process.TakenState)
}
move := steps.move(ctx) // the readers a rerun carried (§727, A-470d)
runs.moved.Store(&move)
// The state's watch wakes the steps waiting on a run and hears a bound's expiry; the runs standing at the start are taken up
// once the values that stand are read (§719, §720).
if err := watchRuns(ctx, kvs[buckets.CompositionRuns()], runs, runs.expired, func() { steps.takeUp(ctx, runs) }); err != nil {
return fmt.Errorf("the state %s is not watched: %w", buckets.CompositionRunsState, err)
}
// The runs' read and drop, the seat mesh-wants' verbs compositions and compositions-drop (§728, A-469f), answered here
// where the runs are kept and the readers' ends said; the drop's hand act recorded through the seat mesh-hand-acts first.
if e, ok := bus.(emitting); ok {
record := func(q meshhandactsclient.Request) error {
_, err := meshhandactsclient.Recorder{Ask: bus.Call}.Record(q)
return err
}
verbs := compositionVerbs(runs, steps, record)
maps.Copy(verbs, dropVerb(steps)) // the seat's act drop (§778, H-A-404)
if p.graph != nil {
maps.Copy(verbs, keepNowVerb(ctx, p)) // the keeping by hand (§813 (2), H-A-417)
}
stopVerbs, err := e.AnswerSeat(meshwants.Seat, seatlist.Definition(gate.Reader, meshwants.Seat), verbs)
if err != nil {
logger.Printf("the verbs %s, %s and %s are not answered until the assigner starts again: %v", meshwants.VerbCompositions, meshwants.VerbCompositionsDrop, meshwants.VerbDrop, err)
} else {
go func() { <-ctx.Done(); stopVerbs() }()
}
}
// A superseded or cancelled pipeline's composition step leaves the runs it reads (§723, A-469n).
if p.ends != nil {
left := func(pipeline string) error {
_, err := runs.leave(pipeline, steps.leave)
return err
}
p.ends.left.Store(&left)
}
if steps.taken == nil {
logger.Printf("the state %s is not bound, so no composition step is pulled until the assigner starts again", process.TakenState)
} else if err := serveStepQueue(ctx, nc, js, steps, func(d time.Duration) { ackWait.Store(int64(d)) }); err != nil {
logger.Printf("the composition step is not pulled, so no composition step runs until the assigner starts again: %v", err)
}
}
if bus != nil {
@@ -746,48 +796,51 @@ func sayVia(ctx context.Context, js jetstream.JetStream) func(oc.Condition) erro
}
}
// readsChangedHandler is what the assigner does with each event manifest-reads-changed: acknowledges it, keeps what it says
// of the node (a statement older than it does not stand) and asks the node again.
func readsChangedHandler(reads *enginereads.Keeper, logf func(string, ...any)) func(jetstream.Msg) {
// readsChangedHandler is what the assigner does with each event manifest-reads-changed: writes the words it says of its node
// into the state engine-reads, then acknowledges it; an event not written is not acknowledged, so the bus delivers it again.
func readsChangedHandler(reads *engineReadsKept, logf func(string, ...any)) func(jetstream.Msg) {
return func(m jetstream.Msg) {
node, ours, err := enginereads.NodeOf(m.Subject(), m.Data())
if ours && err == nil {
var e nodeengine.ManifestReadsChangedEvent
if e, err = enginereads.DecodeChanged(m.Data()); err == nil {
if err = reads.heard(e); err != nil {
logf("%s of %s: %v", enginereads.Event, node, err)
if nerr := m.Nak(); nerr != nil {
logf("not acknowledging %s: %v", m.Subject(), nerr)
}
return
}
}
}
if ours && err != nil {
logf("%s holds what is not %s, and is not kept: %v", m.Subject(), enginereads.Event, err)
}
if err := m.Ack(); err != nil {
logf("acknowledging %s: %v", m.Subject(), err)
}
node, ours, err := enginereads.NodeOf(m.Subject(), m.Data())
switch {
case !ours:
case err != nil:
logf("%s holds what is not %s, and %s is asked again all the same: %v", m.Subject(), enginereads.Event, node, err)
reads.AskNode(node, enginereads.Event+" that does not read")
default:
// What the event says is kept first: a statement older than it does not stand while the node is asked again.
if e, derr := enginereads.DecodeChanged(m.Data()); derr == nil {
reads.HeardChanged(e)
}
reads.AskNode(node, enginereads.Event)
}
}
}
// hearReadsChanged hears the node-engine seat's event manifest-reads-changed on the assigner's one hub of its durable
// consumer on EVENTS, and asks the node it names again; the hub also hands the indexer's views to the followers of
// consumer on EVENTS, and keeps the words of the node it names; the hub also hands the indexer's views to the followers of
// indexerViews, and starts once both are registered.
func hearReadsChanged(ctx context.Context, js jetstream.JetStream, hub *process.EventHub, reads *enginereads.Keeper, findings assign.Findings, live func(), logf func(string, ...any)) {
func hearReadsChanged(ctx context.Context, js jetstream.JetStream, hub *process.EventHub, reads *engineReadsKept, findings assign.Findings, live func(), logf func(string, ...any)) {
account := process.Account{Node: thisNode, Module: assignment.Module()}
w := notHeardWriter(findings, logf)
handle := readsChangedHandler(reads, logf)
err := hub.Handle(enginereads.SubjectPrefix+"*", handle)
// At each bind every node the assigner holds a statement of is asked again: an event said before its consumer existed
// is not delivered to it (issue 1966 note 155: ace's bootstrapped statement stood; ADR 0668 §4).
hub.OnBound(reads.AtBind(func() []string { return slices.Sorted(maps.Keys(reads.Statements())) }))
if err == nil {
err = hub.Start(ctx, js, account)
}
if err != nil {
w.NotHeard(process.EventsStream, enginereads.Event+" is not heard until the assigner starts again (a node is asked again when it comes back online)", err)
w.NotHeard(process.EventsStream, enginereads.Event+" is not heard until the assigner starts again, so no node's new words are kept", err)
return
}
w.Heard(process.EventsStream)
// The build seats' step-ended is a kept seat event, on its own stream and never on EVENTS: bound here, or no composition
// run's end is heard and every composition step waits for ever (design 47 G §354, A-240; mesh-sdk EventHub.StartKept).
logf("the kept seat events heard: %d streams bound", hub.StartKept(ctx, js, account))
if live != nil {
live() // the seat list, unread while the seat was silent, is read now (seatlist.Part.EventsLive)
}
@@ -796,3 +849,35 @@ func hearReadsChanged(ctx context.Context, js jetstream.JetStream, hub *process.
hub.Stop()
}()
}
// entriesOf are the catalog entries the passer asks by fingerprint: the followed branches' own, so each catalog-revision asks
// again an entry whose ask failed to reach the holder, at most asks times (the setting entry-asks, 0 its default), and the
// assigner's finding writer writes entry-not-found and entry-unanswered of them (design 47 H, H-A-60). Each change wakes a pass.
func entriesOf(b *meshcatalogclient.Branches, call meshcatalogclient.Call, asks int, w views.WireWriter, wake func()) *meshcatalogclient.Entries {
if b == nil || b.Entries == nil {
b = &meshcatalogclient.Branches{Entries: meshcatalogclient.NewEntries(call)}
}
b.Entries.Asks = asks
if w == nil {
b.Entries.Changed = func(meshcatalogclient.EntryRow) { wake() }
return b.Entries
}
b.WriteEntryFindings(w, func(meshcatalogclient.EntryRow) { wake() })
return b.Entries
}
// askAgainOnReconnect asks the entries again whose ask failed each time the assigner's link to the bus opens again (design 47
// H, H-A-60), after whatever the connection already does then.
func askAgainOnReconnect(ctx context.Context, nc process.Subscriber, e *meshcatalogclient.Entries) {
conn, ok := nc.(*nats.Conn)
if !ok || conn == nil {
return
}
before := conn.Opts.ReconnectedCB
conn.SetReconnectHandler(func(c *nats.Conn) {
if before != nil {
before(c)
}
e.AskAgain(ctx)
})
}
@@ -16,8 +16,10 @@ import (
"os"
"path/filepath"
"reflect"
"runtime"
"slices"
"strings"
"sync"
"testing"
"time"
@@ -26,6 +28,7 @@ import (
mmac "git.novox.be/novox/mesh-contracts/go/clients/meshmoduleassignerclient"
mma "git.novox.be/novox/mesh-contracts/go/seats/meshmoduleassigner"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/process"
"git.novox.be/novox/mesh-sdk/go/seatlist"
@@ -125,7 +128,7 @@ func TestOpensWhatItsManifestNames(t *testing.T) {
}
kvs[buckets.Puts()].(*watchKV).closed = true
kvs[buckets.Wants()].(*watchKV).wrote = wrote
go follow(ctx, nil, nil, kvs, func(oc.Condition) error { return nil }, assign.Findings{}, nil, nil, nil, seatlist.NewPart("assigner", seatListAgainCallers), log.New(io.Discard, "", 0), func(string) string { return "" })
go follow(ctx, nil, nil, kvs, func(oc.Condition) error { return nil }, assign.Findings{}, nil, nil, nil, seatlist.NewPart("assigner"), log.New(io.Discard, "", 0), func(string) string { return "" })
select {
case key := <-wrote:
if key != "want.ace.node" {
@@ -201,11 +204,57 @@ func (w *watchKV) Keys(context.Context, ...jetstream.WatchOpt) ([]string, error)
return nil, jetstream.ErrNoKeysFound
}
// putIntoMu holds putInto's writes one at a time: the composition step starts its machines' runs side by side, and each may
// raise a finding into the same map.
var putIntoMu sync.Mutex
// putInto is an assign.Findings Put that keeps each finding in into, as the finding writer would, by its key and its words.
func putInto(into map[string][]byte) func(mcseat.Finding) error {
return func(f mcseat.Finding) error {
raw, err := json.Marshal(f)
putIntoMu.Lock()
into[views.FindingKey(f.Scope, f.ID, f.Kind)] = raw
putIntoMu.Unlock()
return err
}
}
// fakeWire is a views part's finding writer that hands each written finding's kind on.
type fakeWire struct{ written chan string }
func (f fakeWire) WriteWire(_ context.Context, finding map[string]any) error {
k, _ := finding["kind"].(string)
f.written <- k
return nil
}
func (fakeWire) Clear(context.Context, string, string, string, string) error { return nil }
func (fakeWire) ModuleNode() (string, string) { return "mesh-delivery-assigner", "n1" }
// H-A-60: the assigner's entries are asked again to the setting entry-asks, then written through its finding writer as the
// finding entry-unanswered.
func TestAnUnreachedEntryEndsInTheAssignersFindingEntryUnanswered(t *testing.T) {
ctx := context.Background()
unreached := func(string, any) (json.RawMessage, error) { return nil, errors.New("no responders") }
w := fakeWire{written: make(chan string, 4)}
e := entriesOf(nil, unreached, 1, w, func() {})
if e.Asks != 1 {
t.Fatalf("entry-asks %d, want 1 from the setting", e.Asks)
}
e.Need(ctx, "src2:u")
deadline := time.Now().Add(5 * time.Second)
for {
select {
case kind := <-w.written:
if kind != meshcatalogclient.EntryUnansweredKind {
t.Fatalf("the finding written is %q, want %s", kind, meshcatalogclient.EntryUnansweredKind)
}
return
default:
}
if time.Now().After(deadline) {
t.Fatal("no finding entry-unanswered is written past the bound")
}
e.AskAgain(ctx)
runtime.Gosched()
}
}
@@ -0,0 +1,26 @@
package main
import (
"testing"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
)
// The module claiming the seat node-engine is found by its served verbs, in the catalog's form `seat:<seat>.<verb>`
// and in the bare form (live, 2026-11-16: every composition step said "holds no module claiming the seat node-engine").
func TestTheNodeEngineEntryIsFoundByItsServedVerbs(t *testing.T) {
for _, c := range []struct {
name string
serves []string
found bool
}{
{"the catalog's seat form", []string{"seat:node-engine.compose", "seat:node-engine.acts"}, true},
{"the bare form", []string{"node-engine.compose"}, true},
{"another seat", []string{"seat:node-engine-x.compose", "seat:mesh-wants.ask"}, false},
} {
e, ok := nodeEngineEntry(map[string]meshcatalog.CatalogEntry{"other": {Serves: []string{"seat:mesh-builds.ask"}}, "engine": {Serves: c.serves}})
if ok != c.found || (ok && e.Serves[0] != c.serves[0]) {
t.Errorf("%s: found %v (%v), want %v", c.name, ok, e.Serves, c.found)
}
}
}
@@ -88,6 +88,43 @@ func (b *busObjects) Names(ctx context.Context) ([]string, error) {
return names, nil
}
// PutDescribed stores data under name with the entry's module and fingerprint in its metadata, which the listing says (assigngraph.Describer,
// design 47 H-A-259).
func (b *busObjects) PutDescribed(ctx context.Context, name string, data []byte, module, fp string) error {
o, err := b.open(ctx)
if err != nil {
return err
}
_, err = o.Put(ctx, jetstream.ObjectMeta{Name: name, Metadata: map[string]string{entryModuleMeta: module, entryFpMeta: fp}}, bytes.NewReader(data))
return err
}
// Described is every object with the module and fingerprint its metadata says, in one listing.
func (b *busObjects) Described(ctx context.Context) ([]assigngraph.Described, error) {
o, err := b.open(ctx)
if err != nil {
return nil, err
}
infos, err := o.List(ctx)
if errors.Is(err, jetstream.ErrNoObjectsFound) {
return []assigngraph.Described{}, nil
}
if err != nil {
return nil, err
}
out := make([]assigngraph.Described, 0, len(infos))
for _, i := range infos {
out = append(out, assigngraph.Described{Name: i.Name, Module: i.Metadata[entryModuleMeta], Fp: i.Metadata[entryFpMeta]})
}
return out, nil
}
// The metadata keys of an entry object's module and fingerprint.
const (
entryModuleMeta = "module"
entryFpMeta = "fp"
)
// Delete removes the object of that name; one not held is no error (design 47 G §579: a revision nothing pins is removed).
func (b *busObjects) Delete(ctx context.Context, name string) error {
o, err := b.open(ctx)
@@ -1,296 +0,0 @@
package main
import (
"context"
"encoding/json"
"fmt"
"strconv"
"sync"
"git.novox.be/novox/mesh-contracts/go/seats/meshbroker"
mma "git.novox.be/novox/mesh-contracts/go/seats/meshmoduleassigner"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
mwc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/process"
"git.novox.be/novox/mesh-sdk/go/seatdef"
"mesh-delivery-assigner/internal/acting"
"mesh-delivery-assigner/internal/assign"
"mesh-delivery-assigner/internal/assigngraph"
"mesh-delivery-assigner/internal/assignment"
"mesh-delivery-assigner/internal/buckets"
)
// The three order edges of a delivery that crosses a form change (design 47 G §298, A-245, A-258, A-259, A-260). Each is an acting wait of the
// assigner, kept in the state `waits` under `order.<node>.<module>.<part>` beside the acting waits, in the step placing, said as wait-held
// when a want is held for it and wait-ended (ran, released, replaced) when it moves; assigner_waits reads them and assigner_release with
// how `now` releases them, as it does an acting wait. The holders of the seats are read from the seat holders the assignments compose
// (assignment.SeatHoldersOf), never named:
// - the node-backup holder's and the bus module's (the holder of the seat mesh-broker) new versions run before a module whose kept data's
// form changes is moved, since the restore point needs both (OrderBackup);
// - at a revert a node's node-engine goes back last on that node, after every module it restores there runs the reverted build, which it
// starts only once it has said `restored` (OrderEngineLast);
// - the reverted assigner and gate are wanted only once the indexer's take-in.taken of the trunk branch names a source revision at least
// the trunk's head, the highest `src` of the trunk branch's module values (OrderTakenIn, A-260).
// takenSubject is the indexer's event take-in.taken on its own stream, as the manifest's consumes names it.
var takenSubject = process.ModuleStreamSubject(buckets.IndexerModule, "take-in.taken")
// takenSources are the newest source revisions a take-in.taken named, by watched branch, as heard (hearBuildsAndReleases).
type takenSources struct {
mu sync.Mutex
own map[string]int64
}
// put takes one take-in.taken in. A hand drop, and a taken with no source revision (one said before G), take nothing in.
func (t *takenSources) put(data []byte) error {
var e meshcatalog.TakeInTaken
if err := json.Unmarshal(data, &e); err != nil {
return fmt.Errorf("a take-in.taken that is none: %w", err)
}
if e.Dropped || e.Source == 0 || e.Branch == "" {
return nil
}
t.mu.Lock()
defer t.mu.Unlock()
if t.own == nil {
t.own = map[string]int64{}
}
t.own[e.Branch] = max(t.own[e.Branch], e.Source)
return nil
}
// of is the newest source revision of branch taken in; 0 before one is heard.
func (t *takenSources) of(branch string) int64 {
t.mu.Lock()
defer t.mu.Unlock()
return t.own[branch]
}
// orderEdge is one order edge held on module's want on node: part's version fp must run on partNode (OrderBackup, OrderEngineLast), or the
// trunk's source revision source be taken in (OrderTakenIn).
type orderEdge struct {
node, module, part, partNode, fp, entry, order string
source int64
}
func (e orderEdge) key() string { return acting.OrderKey(e.node, e.module, e.part) }
func (e orderEdge) acting() assign.ActingEdge {
return assign.ActingEdge{Node: e.partNode, Part: e.part, Fp: e.fp, Step: seatdef.StepPlace}
}
// orderRuns says an order edge is met: its part runs the version, or the source revision is taken in.
func (p *passer) orderRuns(n assign.Nodes, e orderEdge) bool {
if e.order == acting.OrderTakenIn {
return p.w.taken.of(p.w.trunkName()) >= e.source
}
return n.Runs(e.acting())
}
// seatHolders are the holders of each seat as the assignments compose them, by seat name.
func (p *passer) holdersBySeat() map[string][]mma.SeatHoldersHoldersItem {
out := map[string][]mma.SeatHoldersHoldersItem{}
for _, sh := range assignment.SeatHoldersOf(p.w.assignments()) {
out[sh.Seat] = append(out[sh.Seat], sh.Holders...)
}
return out
}
// orderEdgesOf computes §298's edges on the wants of module m on each of its nodes, into p.orders. wanted is m's wants by node; trunk the
// trunk's module values. A node that has no running build heard, runs m at its trunk version already, or is wanted that version already
// has none: nothing moves. It answers, by node, whether an edge still stands that cannot be recorded as a wait because the catalog entry
// it reads is not answered yet (asked, and its answer wakes a pass): the want is held meanwhile, never written across a form change unread.
func (p *passer) orderEdgesOf(ctx context.Context, m assign.Module, wanted map[string]mwc.Want, trunk map[string]meshcatalog.ModulesByModuleValue) map[string]bool {
unread := map[string]bool{}
p.orderVisited[m.Name] = true
if m.FP == "" || p.graph == nil || p.entries == nil {
return unread
}
var holders map[string][]mma.SeatHoldersHoldersItem
for _, node := range m.Nodes {
if w, ok := wanted[node]; ok && !w.Removed && w.Fp == m.FP {
continue // the version is wanted already: nothing moves, so nothing waits
}
run, heard := p.w.runningOf(node, m.Name)
if !heard || run.Stopped || run.Fingerprint == "" || run.Fingerprint == m.FP {
continue
}
if holders == nil {
holders = p.holdersBySeat()
}
held := func(seatName string) bool {
for _, h := range holders[seatName] {
if h.Module == m.Name && h.Node == node {
return true
}
}
return false
}
add := func(e orderEdge) {
e.node, e.module, e.entry = node, m.Name, m.FP
p.orders[e.key()] = e
}
// 1. a kept data's form changes: the restore point needs the new node-backup holder and bus module.
changes, known := p.formChange(ctx, m.Name, run.Fingerprint, m.FP)
if !known {
unread[node] = true
}
if len(changes) > 0 {
for seatName, onNode := range map[string]bool{catalogue.BackupSeat: true, meshbroker.Seat: false} {
for _, h := range holders[seatName] {
if h.Module == m.Name || (onNode && h.Node != node) || trunk[h.Module].Fp2 == "" {
continue
}
add(orderEdge{part: h.Module, partNode: h.Node, fp: trunk[h.Module].Fp2, order: acting.OrderBackup})
}
}
}
if !held(nodeengine.Seat) && !held(mma.Seat) && !held(meshdelivery.Seat) {
continue
}
reverted, err := assigngraph.Reverted(ctx, p.graph.objects, node, m.Name, run.Fingerprint, m.FP)
if err != nil {
p.logf("whether the want of %s on %s at %s is a revert is not read: %v", m.Name, node, m.FP, err)
continue
}
if !reverted {
continue
}
// 2. at a revert the node-engine goes back last on its node: after every module that is set back there across a form change runs.
if held(nodeengine.Seat) {
for module, byNode := range p.w.wantsOf() {
// What it is set back to is its trunk version, which the rules write as its want in this pass.
target := trunk[module].Fp2
if w, ok := byNode[node]; module == m.Name || !ok || w.Removed || target == "" {
continue
}
xrun, heard := p.w.runningOf(node, module)
if !heard || xrun.Stopped || xrun.Fingerprint == "" || xrun.Fingerprint == target {
continue
}
if back, err := assigngraph.Reverted(ctx, p.graph.objects, node, module, xrun.Fingerprint, target); err != nil || !back {
continue
}
xchanges, known := p.formChange(ctx, module, xrun.Fingerprint, target)
if !known {
unread[node] = true
}
if len(xchanges) > 0 {
add(orderEdge{part: module, partNode: node, fp: target, order: acting.OrderEngineLast})
}
}
}
// 3. the reverted assigner and gate wait for the indexer to take in the trunk's head.
if held(mma.Seat) || held(meshdelivery.Seat) {
var head int64
for _, v := range p.w.trunkOf(p.w.trunkName()) {
head = max(head, v.Src)
}
if head > 0 {
add(orderEdge{part: buckets.IndexerModule, fp: strconv.FormatInt(head, 10), source: head, order: acting.OrderTakenIn})
}
}
}
return unread
}
// orderActing is the order edges of module on node that still hold its want, as acting edges: those not met, and not released by hand. A
// node whose catalog entry is not read yet holds its want too, on a stand-in edge no part runs.
func (p *passer) orderActing(module string, released map[string]bool, unread map[string]bool, n func() assign.Nodes) func(node string) []assign.ActingEdge {
return func(node string) []assign.ActingEdge {
var out []assign.ActingEdge
nodes := n()
for _, e := range p.orders {
if e.module == module && e.node == node && !released[e.key()+"@"+e.fp] && !p.orderRuns(nodes, e) {
out = append(out, assign.ActingEdge{Node: e.partNode, Part: e.part, Fp: e.fp, Step: seatdef.StepPlace})
}
}
if unread[node] {
out = append(out, assign.ActingEdge{Node: node, Part: "the catalog entry", Step: seatdef.StepPlace})
}
return out
}
}
// orderWaits keeps the order waits after the pass's wants, as actingWaits keeps the acting waits: it starts the wait of each edge not met,
// ends the wait of one that ran, was replaced or was released, and says each.
func (p *passer) orderWaits(ctx context.Context, n assign.Nodes, wanted map[string]map[string]mwc.Want) {
if p.kvs[buckets.Waits()] == nil {
return
}
now := p.clock()
kept := p.w.read(buckets.Waits())
trunk := p.w.trunk()
if p.orderSaid == nil {
p.orderSaid = map[string]bool{}
}
standing := map[string]bool{}
for key, e := range p.orders {
if w, ok := wanted[e.module][e.node]; ok && !w.Removed && w.Fp == e.entry {
continue
}
if p.orderRuns(n, e) {
continue
}
standing[key] = true
if raw := kept[key]; raw != nil {
if w, err := acting.Decode(raw); err == nil && w.Entry == e.entry && w.Fp == e.fp {
if !w.Released && !p.orderSaid[key] {
// A wait still held after a restart is said again, as wait-held (A-260).
if err := p.wantsSay(seat.EventWaitHeld, acting.Body(w, assignment.Module()), key+"."+e.fp+"."+e.entry+".again"); err != nil {
p.logf("the wait of %s on %s for %s is not said again, and is said at the next pass: %v", e.module, e.node, e.part, err)
} else {
p.orderSaid[key] = true
}
}
p.actingReleaseSaid(ctx, key, w)
continue
}
}
if !n.Online[e.node] {
continue // a node away holds only itself, and its clock has not started (§268)
}
w := acting.Wait{Step: seatdef.StepPlace, Node: e.node, Module: e.module, Part: e.part, PartNode: e.partNode, Fp: e.fp, Entry: e.entry, Order: e.order,
Since: now, ClockFrom: now, Bound: acting.BoundOf(seat.Edge{Step: seatdef.StepPlace}).String()}
if err := p.wantsSay(seat.EventWaitHeld, acting.Body(w, assignment.Module()), key+"."+e.fp+"."+e.entry); err != nil {
p.logf("the wait of %s on %s for %s is not said, and is said at the next pass: %v", e.module, e.node, e.part, err)
continue
}
p.put(ctx, buckets.Waits(), key, func() ([]byte, error) { return acting.Encode(w) })
p.orderSaid[key] = true
}
for key, raw := range kept {
if !acting.IsOrder(key) || standing[key] {
continue
}
w, err := acting.Decode(raw)
if err != nil {
continue
}
if _, there := trunk[w.Module]; there && !p.orderVisited[w.Module] {
continue // the module was not looked at in this pass (no pipeline passed for it yet): its wait stands as kept
}
how := acting.HowRan
switch e, there := p.orders[key]; {
case w.Released:
how = acting.HowReleased
case there && e.fp != w.Fp, !there && wanted[w.Module][w.Node].Fp != w.Entry:
how = acting.HowReplaced
}
if !w.EndSaid {
body := acting.Body(w, assignment.Module())
body.How = how
if err := p.wantsSay(seat.EventWaitEnded, body, key+"."+w.Fp+"."+w.Entry+"."+how); err != nil {
p.logf("the end of the wait of %s on %s for %s is not said, and is said at the next pass: %v", w.Module, w.Node, w.Part, err)
continue
}
}
p.remove(ctx, buckets.Waits(), key)
delete(p.orderSaid, key)
}
}
@@ -1,351 +0,0 @@
package main
import (
"context"
"encoding/json"
"fmt"
"strings"
"testing"
"time"
mmac "git.novox.be/novox/mesh-contracts/go/clients/meshmoduleassignerclient"
"git.novox.be/novox/mesh-contracts/go/clients/nodeengineclient"
"git.novox.be/novox/mesh-contracts/go/seats/meshbroker"
mma "git.novox.be/novox/mesh-contracts/go/seats/meshmoduleassigner"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
mwc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-grants/grantsstate"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/seatdef"
"mesh-delivery-assigner/internal/acting"
"mesh-delivery-assigner/internal/assigngraph"
plc "mesh-delivery-assigner/internal/assignment"
"mesh-delivery-assigner/internal/buckets"
)
// orderFP is a fingerprint of the form the trunk keeps, made of one letter.
func orderFP(c string) string {
return meshcatalogclient.SourcePrefix2 + strings.Repeat(fmt.Sprintf("%x", c[0]&15), 64)
}
// orderMod is one module of an order test: the fingerprint it runs on ace and the one the trunk holds, the form of its kept data at each
// fingerprint (0: it keeps none), the seats it holds and the source revision of its trunk value.
type orderMod struct {
name string
run, trunk string
forms map[string]int
holds []string
src int64
}
type orderFixture struct {
t *testing.T
p *passer
wants *memKV
events []string
bodies []meshwants.Wait
answers chan struct{}
}
// newOrderFixture is a pass on node ace, which composes its own modules, with each module running its fingerprint healthy, built and
// granted at the trunk's, an older want, the catalog's entries answered and each held seat as the assignments say it. history lists the
// fingerprints of each module by assignment graph revision, oldest first (the objects Reverted reads).
func newOrderFixture(t *testing.T, mods []orderMod, history ...map[string]string) *orderFixture {
t.Helper()
ctx := context.Background()
f := &orderFixture{t: t, wants: &memKV{values: map[string][]byte{}}, answers: make(chan struct{}, 64)}
f.p = newPasser(kvSet{buckets.Wants(): f.wants, buckets.Asks(): &memKV{values: map[string][]byte{}}, buckets.Waits(): &memKV{values: map[string][]byte{}}}, time.Now())
p := f.p
p.logf = t.Logf
p.say = func(oc.Condition) error { return nil }
p.publishWants = func(event string, body any, id string) error {
f.events = append(f.events, event)
f.bodies = append(f.bodies, body.(meshwants.Wait))
return nil
}
digest := "sha256:" + strings.Repeat("c", 64)
pl := mma.Assignments{Node: "ace"}
forms := map[string]int{} // by fingerprint: each module's own
modules := []string{}
for _, m := range mods {
modules = append(modules, m.name)
pl.Modules = append(pl.Modules, mma.PlacedModule{Module: m.name})
for _, seat := range m.holds {
scope := "node"
if seat != catalogue.BackupSeat && seat != nodeengine.Seat {
scope = "mesh"
}
pl.Holds = append(pl.Holds, mma.Holding{Claim: seat, Module: m.name, Scope: scope})
}
for fp, form := range m.forms {
forms[fp] = form
}
mdigest := fmt.Sprintf("%064x", len(modules))
mod, _ := meshcatalogclient.EncodeModule(meshcatalog.ModulesByModuleValue{Fp2: m.trunk, Manifest: mdigest, Repository: "novox/" + m.name, Commit: strings.Repeat("1", 40), Path: meshcatalogclient.RootPath, Src: m.src})
putModuleRaw(p.w, trunkBranch, m.name, mod)
p.w.manifests[mdigest] = parsed{module: m.name, manifest: catalogue.Manifest{Module: m.name}}
endDone(t, p.w, m.name, m.trunk, mdigest)
gkey, _ := grantsstate.PartGrantKey(m.name, m.trunk)
grant, _ := grantsstate.EncodeGrant(grantsstate.Grant{})
p.w.put(buckets.Grants, gkey, grant)
f.runs(m.name, m.run)
wkey, _ := mwc.WantKey("ace", m.name)
old, _ := mwc.EncodeWant(mwc.Want{Fp: m.run, Self: true})
p.w.put(buckets.Wants(), wkey, old)
f.wants.values[wkey] = old
}
composes(t, p.w, "ace", digest)
values, err := mmac.AssignmentsValues(pl)
if err != nil {
t.Fatal(err)
}
for key, raw := range values {
p.w.put(plc.AssignmentsBucket(), key, raw)
}
p.w.heardPresence("ace", false, time.Now()) // ace is online: its last presence event heard is machine-back
objects := memObjects{}
for i, at := range history {
half := meshcatalogclient.Half{Revision: meshcatalog.CatalogRevision{Branch: trunkBranch, Kind: "trunk", Revision: int64(i + 1), Source: int64(i + 1)},
Entries: map[string]meshcatalog.CatalogEntry{}}
for _, module := range modules {
digest := fmt.Sprintf("sha256:%064x", (i+1)*1000+len(half.Entries))
half.Revision.Entries = append(half.Revision.Entries, meshcatalog.EntryRef{Module: module, Digest: digest})
half.Entries[module] = meshcatalog.CatalogEntry{Module: module, Fp: at[module]}
}
placed := mma.Assignments{Node: "ace"}
for _, module := range modules {
placed.Modules = append(placed.Modules, mma.PlacedModule{Module: module})
}
in := assigngraph.Inputs{Halves: map[string]meshcatalogclient.Half{trunkBranch: half}, FirstBranch: func(string) string { return trunkBranch },
Placements: map[string]mma.Assignments{"ace": placed}}
if _, _, err := assigngraph.Keep(ctx, objects, assigngraph.Compute(in), "test", time.Now()); err != nil {
t.Fatal(err)
}
}
p.graph = &graphKeeper{objects: objects}
p.entries = meshcatalogclient.NewEntries(func(_ string, body any) (json.RawMessage, error) {
in := body.(meshcatalog.EntryInput)
entry := meshcatalog.CatalogEntry{Module: "m", Fp: in.Fingerprint, Manifest: map[string]any{"module": "m"}}
if form := forms[in.Fingerprint]; form > 0 {
entry.Manifest = map[string]any{"module": "m", "state": []any{map[string]any{"name": "sessions", "form": form}}}
}
return json.Marshal(meshcatalog.EntryAnswer{Entry: entry})
})
p.entries.Changed = func(meshcatalogclient.EntryRow) { f.answers <- struct{}{} }
return f
}
// runs says module runs fp healthy on ace, heard as the node-engine seat's running and in the have.
func (f *orderFixture) runs(module, fp string) {
have, _ := nodeengineclient.EncodeHave(nodeengine.HaveByNodeModuleValue{Fp: fp, Composed: "sha256:" + strings.Repeat("c", 64), Phase: nodeengineclient.PhaseRunning, Health: nodeengineclient.HealthOK})
f.p.w.put(buckets.Have, "ace."+module, have)
f.p.w.running["ace."+module] = nodeengine.Running{Node: "ace", Module: module, Fingerprint: fp}
}
// pass makes a pass, and after it every catalog entry it asked is answered.
func (f *orderFixture) pass() {
f.t.Helper()
f.p.wants(context.Background())
asked := 0
for _, row := range f.p.entries.Rows() {
if row.State == meshcatalogclient.EntryAsked {
asked++
}
}
for range asked {
select {
case <-f.answers:
case <-time.After(10 * time.Second): // a bound on a failure only: the answers come at once
f.t.Fatal("an entry asked was not answered")
}
}
}
// wantAt is the fingerprint module is wanted at on ace.
func (f *orderFixture) wantAt(module string) string {
f.t.Helper()
key, _ := mwc.WantKey("ace", module)
w, err := mwc.DecodeWant(f.wants.values[key])
if err != nil {
f.t.Fatal(err)
}
return w.Fp
}
func (f *orderFixture) waits() []string {
var out []string
for key := range f.p.w.read(buckets.Waits()) {
if acting.IsOrder(key) {
out = append(out, key)
}
}
return out
}
// Design 47 G §298 first edge, A-258, A-259: a module whose kept data's form changes is not moved until the new version of the node-backup
// holder and of the holder of the seat mesh-broker run; the wait is kept under `order.` in the state waits, said as wait-held, and ends
// ran (wait-ended) when the holders run; a module whose kept data keeps its form is moved at once.
func TestAModuleWhoseKeptDataChangesFormWaitsForTheNewBackupHolderAndTheBusModule(t *testing.T) {
f := newOrderFixture(t, []orderMod{
{name: "web", run: orderFP("a"), trunk: orderFP("b"), forms: map[string]int{orderFP("a"): 1, orderFP("b"): 2}},
{name: "plain", run: orderFP("c"), trunk: orderFP("d"), forms: map[string]int{orderFP("c"): 1, orderFP("d"): 1}},
{name: "backup", run: orderFP("e"), trunk: orderFP("f"), holds: []string{catalogue.BackupSeat}},
{name: "bus", run: orderFP("g"), trunk: orderFP("h"), holds: []string{meshbroker.Seat}},
})
f.pass() // the entries are asked: no want crosses a form change unread
if got := f.wantAt("web"); got != orderFP("a") {
t.Fatalf("web is wanted at %s before the entries are read", got)
}
f.pass()
if got := f.wantAt("web"); got != orderFP("a") {
t.Fatalf("web moved across a form change at %s while the new node-backup holder and bus module do not run", got)
}
if got := f.wantAt("plain"); got != orderFP("d") {
t.Errorf("a module whose kept data keeps its form is wanted at %s, not moved", got)
}
if len(f.waits()) != 2 || len(f.events) != 2 || f.events[0] != meshwants.EventWaitHeld || f.bodies[0].Step != seatdef.StepPlace || f.bodies[0].Module != "web" {
t.Fatalf("waits %v events %v bodies %+v: want two wait-held in the step place, `order.ace.web.backup` and `order.ace.web.bus`", f.waits(), f.events, f.bodies)
}
if _, err := acting.Decode(f.p.w.read(buckets.Waits())[acting.OrderKey("ace", "web", "backup")]); err != nil {
t.Fatalf("the wait is not kept under its key: %v", err)
}
f.pass()
if len(f.events) != 2 {
t.Fatalf("a pass that changed nothing said %v", f.events)
}
f.runs("backup", orderFP("f"))
f.pass()
if got := f.wantAt("web"); got != orderFP("a") || len(f.events) != 3 || f.events[2] != meshwants.EventWaitEnded || f.bodies[2].How != acting.HowRan {
t.Fatalf("with the bus module still old: web at %s, events %v", got, f.events)
}
f.runs("bus", orderFP("h"))
f.pass()
f.pass()
if got := f.wantAt("web"); got != orderFP("b") || len(f.waits()) != 0 || len(f.events) != 4 {
t.Fatalf("with both running: web at %s, waits %v, events %v", got, f.waits(), f.events)
}
}
// §298 first edge, the hand: assigner_waits reads an order wait and assigner_release with how `now` lets the module move.
func TestAnOrderWaitIsReadAndReleasedByTheExistingTools(t *testing.T) {
f := newOrderFixture(t, []orderMod{
{name: "web", run: orderFP("a"), trunk: orderFP("b"), forms: map[string]int{orderFP("a"): 1, orderFP("b"): 2}},
{name: "backup", run: orderFP("e"), trunk: orderFP("f"), holds: []string{catalogue.BackupSeat}},
})
f.pass()
f.pass()
var acts []string
s := newPutTools(memStore{waitsState: f.p.kvs[buckets.Waits()].(*memKV), buckets.DeliveryWaitsState: &memKV{values: map[string][]byte{}}, buckets.DeliveredAgainState: &memKV{values: map[string][]byte{}}}, func(key string, body any) (json.RawMessage, error) {
acts = append(acts, key)
return json.RawMessage(`{"ok":true,"log":"logged"}`), nil
})
got, err := s.doWaits(map[string]any{"module": "web"})
if list := got.(map[string]any)["waits"].([]any); err != nil || len(list) != 1 || list[0].(actingSaid).Key != "order.ace.web.backup" {
t.Fatalf("assigner_waits = %+v %v", got, err)
}
if _, err := s.doRelease(map[string]any{"node": "ace", "module": "web", "how": "now", "why": "the restore point is taken by hand"}, "shanks.node-tools"); err != nil || len(acts) == 0 {
t.Fatalf("%v %v", err, acts)
}
f.p.w.put(buckets.Waits(), "order.ace.web.backup", f.p.kvs[buckets.Waits()].(*memKV).values["order.ace.web.backup"])
f.pass()
f.pass()
if got := f.wantAt("web"); got != orderFP("b") || f.bodies[len(f.bodies)-1].How != acting.HowReleased {
t.Fatalf("after the release: web at %s, last %+v", got, f.bodies[len(f.bodies)-1])
}
}
// §298 second edge, A-259: at a revert the node-engine goes back last on its node, after every module that is set back there across a
// form change runs the reverted build.
func TestAtARevertTheNodeEngineGoesBackLast(t *testing.T) {
old, now := map[string]string{"web": orderFP("a"), "engine": orderFP("c")}, map[string]string{"web": orderFP("b"), "engine": orderFP("d")}
f := newOrderFixture(t, []orderMod{
{name: "web", run: orderFP("b"), trunk: orderFP("a"), forms: map[string]int{orderFP("a"): 1, orderFP("b"): 2}},
{name: "engine", run: orderFP("d"), trunk: orderFP("c"), holds: []string{nodeengine.Seat}},
}, old, now)
f.pass()
f.pass()
if f.wantAt("web") != orderFP("a") {
t.Fatalf("web is wanted at %s: the module set back is not held", f.wantAt("web"))
}
if got := f.wantAt("engine"); got != orderFP("d") {
t.Fatalf("the node-engine is set back to %s before web runs its reverted build", got)
}
if w := f.waits(); len(w) != 1 || w[0] != "order.ace.engine.web" || f.bodies[len(f.bodies)-1].Module != "engine" {
t.Fatalf("waits %v bodies %+v", w, f.bodies)
}
f.runs("web", orderFP("a"))
f.pass()
f.pass()
if got := f.wantAt("engine"); got != orderFP("c") || len(f.waits()) != 0 {
t.Fatalf("with web back: the node-engine is wanted at %s, waits %v", got, f.waits())
}
}
// §298 third edge, A-259, A-260: the reverted assigner and gate are wanted only once the indexer's take-in.taken of the trunk branch names a
// source revision at least the trunk's head (the highest src of the trunk's module values).
func TestTheRevertedAssignerAndGateWaitForTheIndexerToTakeInTheTrunksHead(t *testing.T) {
old, now := map[string]string{"asg": orderFP("a"), "gate": orderFP("c"), "idx": orderFP("e")}, map[string]string{"asg": orderFP("b"), "gate": orderFP("d"), "idx": orderFP("f")}
f := newOrderFixture(t, []orderMod{
{name: "asg", run: orderFP("b"), trunk: orderFP("a"), holds: []string{mma.Seat}, src: 6},
{name: "gate", run: orderFP("d"), trunk: orderFP("c"), holds: []string{meshdelivery.Seat}, src: 7},
{name: "idx", run: orderFP("e"), trunk: orderFP("e"), src: 7},
}, old, now)
f.pass()
f.pass()
if f.wantAt("asg") != orderFP("b") || f.wantAt("gate") != orderFP("d") {
t.Fatalf("the reverted assigner (%s) and gate (%s) are wanted before the head is taken in", f.wantAt("asg"), f.wantAt("gate"))
}
if len(f.waits()) != 2 || f.bodies[0].Part != "mesh-delivery-indexer" {
t.Fatalf("waits %v bodies %+v", f.waits(), f.bodies)
}
taken := func(branch string, source int64) {
raw, _ := json.Marshal(meshcatalog.TakeInTaken{Kind: "taken", Key: "m.1", Branch: branch, Source: source})
if err := f.p.w.taken.put(raw); err != nil {
t.Fatal(err)
}
}
taken("beta", 9) // another branch, and
taken(trunkBranch, 6)
f.pass()
if f.wantAt("asg") != orderFP("b") {
t.Fatal("a source revision before the trunk's head was taken in, and the assigner was wanted")
}
taken(trunkBranch, 7)
f.pass()
f.pass()
if f.wantAt("asg") != orderFP("a") || f.wantAt("gate") != orderFP("c") || len(f.waits()) != 0 {
t.Fatalf("after the head is taken in: asg %s gate %s waits %v", f.wantAt("asg"), f.wantAt("gate"), f.waits())
}
}
// A-260: an order wait still held after a restart is said again as wait-held, by a pass that remembers nothing, and ends at the next
// take-in.taken that names the trunk's head.
func TestAnOrderWaitHeldAfterARestartIsSaidAgain(t *testing.T) {
old, now := map[string]string{"asg": orderFP("a")}, map[string]string{"asg": orderFP("b")}
f := newOrderFixture(t, []orderMod{{name: "asg", run: orderFP("b"), trunk: orderFP("a"), holds: []string{mma.Seat}, src: 7}}, old, now)
f.pass()
f.pass()
if len(f.events) != 1 {
t.Fatalf("events %v", f.events)
}
f.p.orderSaid = nil // a process started again
f.pass()
if len(f.events) != 2 || f.events[1] != meshwants.EventWaitHeld || len(f.waits()) != 1 {
t.Fatalf("events %v waits %v", f.events, f.waits())
}
raw, _ := json.Marshal(meshcatalog.TakeInTaken{Kind: "taken", Key: "m.1", Branch: trunkBranch, Source: 8})
if err := f.p.w.taken.put(raw); err != nil {
t.Fatal(err)
}
f.pass()
f.pass()
if f.wantAt("asg") != orderFP("a") || len(f.waits()) != 0 || f.events[len(f.events)-1] != meshwants.EventWaitEnded {
t.Fatalf("asg at %s, waits %v, events %v", f.wantAt("asg"), f.waits(), f.events)
}
}
@@ -76,9 +76,6 @@ type outsideActs struct {
cleared map[string]bool
// sigs is each check's last signature, by node.module.
sigs map[string]string
// own is the machines whose own network is open; ownRead says the read at the start was answered.
own map[string]bool
ownRead bool
// causes is, by condition key, the nodes whose waits stand on it, as the last pass kept them.
causes map[string][]string
// started says the first pass judged every wait again.
@@ -93,7 +90,7 @@ func newOutsideActs(call func(string, any) (json.RawMessage, error), wake func()
settle = outside.DefaultSettle
}
return &outsideActs{call: call, wake: wake, logf: logf, bound: bound, settle: settle, reading: map[string]bool{}, answered: map[string][]outside.Cond{},
dirty: map[string]bool{}, cleared: map[string]bool{}, sigs: map[string]string{}, own: map[string]bool{}, causes: map[string][]string{}}
dirty: map[string]bool{}, cleared: map[string]bool{}, sigs: map[string]string{}, causes: map[string][]string{}}
}
// outsideSettings are the bounds of the wait, the settings outside-wait-minutes and outside-settle-seconds (design 47 G §633, §706),
@@ -135,31 +132,8 @@ func settingFile(path string) (int, error) {
return n, nil
}
// readStart reads the open conditions of every machine once at the start, for the machines whose own network is held.
func (o *outsideActs) readStart() {
go func() {
answer, err := o.call(conditionsVerb, map[string]any{"scope": "machine"})
if err != nil {
o.logf("the open conditions are not read at the start (%v): no machine is held for its own network until its event is heard", err)
return
}
conds, err := outside.ParseConditions(answer)
if err != nil {
o.logf("%v", err)
return
}
o.mu.Lock()
for m := range outside.OwnNetwork(conds) {
o.own[m] = true
}
o.ownRead = true
o.mu.Unlock()
o.wake()
}()
}
// Heard is one of the seat's events condition-raised, -changed or -cleared: it says which machines to judge again and keeps the
// machines whose own network is open; nothing is kept of the condition.
// Heard is one of the seat's events condition-raised, -changed or -cleared: it says which machines to judge again; nothing is kept
// of the condition (the network hold ends, design 47 H §750, H-A-55).
func (o *outsideActs) Heard(subject string, body []byte) {
var e mcseat.ConditionEvent
if err := json.Unmarshal(body, &e); err != nil || e.Key == "" {
@@ -168,9 +142,6 @@ func (o *outsideActs) Heard(subject string, body []byte) {
}
cleared := strings.HasSuffix(subject, "."+mcseat.EventConditionCleared)
o.mu.Lock()
if p := strings.Split(e.Key, "."); len(p) == 3 && p[0] == "machine" && p[2] == "network" {
o.own[p[1]] = !cleared
}
if cleared {
for _, node := range o.causes[e.Key] {
o.dirty[node] = true
@@ -186,16 +157,6 @@ func (o *outsideActs) Heard(subject string, body []byte) {
o.wake()
}
// Held says whether machine's own network is open: no want moves to it.
func (o *outsideActs) Held(machine string) bool {
if o == nil {
return false
}
o.mu.Lock()
defer o.mu.Unlock()
return o.own[machine]
}
// take is the conditions read for machine, consumed (one answer is one judging), or false while the kept call is unanswered,
// which it starts when none is in flight.
func (o *outsideActs) take(machine string) ([]outside.Cond, bool) {
@@ -237,29 +237,12 @@ func TestTheWaitOnAnOutsideCause(t *testing.T) {
})
}
func TestAMachineWhoseOwnNetworkIsOpenGetsNoWant(t *testing.T) {
m := assign.Module{Name: "nats", FP: fpTest, Built: true, Nodes: []string{"ace"}, MachineHeld: func(node string) bool { return node == "ace" }}
ok, rule, why := assign.Holds(m, "ace", assign.Nodes{Online: map[string]bool{"ace": true}})
if ok || rule == 0 || !strings.Contains(why, "machine.ace.network") {
t.Errorf("holds = %v %d %q", ok, rule, why)
}
o := newOutsideActs(nil, func() {}, func(string, ...any) {}, 0, 0)
o.Heard("mesh.seat.mesh-conditions.event.condition-raised", []byte(`{"key":"machine.ace.network","subject":{"id":"ace","scope":"machine","machine":"ace"}}`))
if !o.Held("ace") || o.Held("g14") {
t.Error("the own network condition's event does not hold the machine")
}
o.Heard("mesh.seat.mesh-conditions.event.condition-cleared", []byte(`{"key":"machine.ace.network","subject":{"id":"ace","scope":"machine","machine":"ace"}}`))
if o.Held("ace") {
t.Error("the machine is held after its condition cleared")
}
}
func TestTheToolsReadAndReleaseAnOutsideWait(t *testing.T) {
r := newOutsideRig(t)
r.cond("machine.hub.unreachable", "ace")
r.review(false, nil)
var acts []string
s := newPutTools(memStore{waitsState: &memKV{values: map[string][]byte{}}, buckets.DeliveryWaitsState: &memKV{values: map[string][]byte{}}, buckets.DeliveredAgainState: &memKV{values: map[string][]byte{}}}, func(key string, body any) (json.RawMessage, error) {
s := newPutTools(memStore{waitsState: &memKV{values: map[string][]byte{}}}, func(key string, body any) (json.RawMessage, error) {
acts = append(acts, key)
return json.RawMessage(`{"ok":true,"log":"logged"}`), nil
})
@@ -296,38 +279,4 @@ func TestTheToolsReadAndReleaseAnOutsideWait(t *testing.T) {
if r.bodies[len(r.bodies)-1].How != "go-on" || n.Haves["ace"]["nats"].Health != nodeengineclient.HealthOK {
t.Errorf("last %+v health %s", r.bodies[len(r.bodies)-1], n.Haves["ace"]["nats"].Health)
}
// A-246: a dependent's delivery wait is listed beside them, and released by its module and step delivery, its hand act first.
dw, _ := json.Marshal(deliveryWaiting{Wait: meshwants.Wait{Step: meshwants.WaitStepDelivery, Module: "app", Part: "db", On: "db@1.1.0", Machines: []string{"g14"}}})
s.st.put(buckets.DeliveryWaitsState, "app", dw)
got, err = s.doWaits(map[string]any{"node": "g14"})
if d := got.(map[string]any)["delivery"].([]deliveryWaiting); err != nil || len(d) != 1 || d[0].Module != "app" {
t.Errorf("the delivery waits listed = %+v %v", got, err)
}
if _, err := s.doRelease(map[string]any{"module": "app", "step": "build", "why": "x"}, "shanks.node-tools"); err == nil {
t.Error("a release of another step is taken")
}
if _, err := s.doRelease(map[string]any{"module": "web", "step": "delivery", "why": "x"}, "shanks.node-tools"); err == nil {
t.Error("a release of a module waiting for no delivery is taken")
}
before := len(acts)
if _, err := s.doRelease(map[string]any{"module": "app", "step": "delivery", "why": "db is fine as it runs"}, "shanks.node-tools"); err != nil {
t.Fatal(err)
}
raw, _, _, _ = s.st.get(buckets.DeliveryWaitsState, "app")
var released deliveryWaiting
if json.Unmarshal(raw, &released) != nil || !released.Released || !strings.Contains(released.By, "db is fine") || len(acts) != before+1 {
t.Errorf("the delivery wait after its release = %+v, hand acts %v", released, acts[before:])
}
// A-250: assigner_delivered_again records its hand act, writes the ask and answers asked; assigner_waits lists it.
if _, err := s.doDeliveredAgain(map[string]any{"module": "db", "version": "1.1.0"}, "op"); err == nil {
t.Error("an ask with no why is taken")
}
ans, err := s.doDeliveredAgain(map[string]any{"module": "db", "version": "1.1.0", "why": "the catalog missed it"}, "op")
if err != nil || ans.(map[string]any)["asked"] != "db" || len(acts) != before+2 {
t.Fatalf("assigner_delivered_again = %+v %v", ans, err)
}
got, _ = s.doWaits(map[string]any{})
if a := got.(map[string]any)["delivered-again"].([]againAsk); len(a) != 1 || a[0].Version != "1.1.0" || a[0].By != "op" {
t.Errorf("the asks listed = %+v", a)
}
}
@@ -1,7 +1,6 @@
package main
import (
"encoding/json"
"errors"
"fmt"
"slices"
@@ -10,11 +9,8 @@ import (
"time"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/keys"
"mesh-delivery-assigner/internal/acting"
"mesh-delivery-assigner/internal/buckets"
"mesh-delivery-assigner/internal/outside"
)
@@ -37,13 +33,6 @@ type waitSaid struct {
BoundEnds string `json:"bound-ends,omitempty"`
}
// actingSaid is one wait for an acting part's new version as assigner_waits answers it (actingwaits.go).
type actingSaid struct {
Key string `json:"key"`
acting.Wait
BoundEnds string `json:"bound-ends,omitempty"`
}
// doWaits is the tool assigner_waits.
func (s *putTools) doWaits(args map[string]any) (any, error) {
keys, err := s.st.keys(waitsState)
@@ -57,16 +46,6 @@ func (s *putTools) doWaits(args map[string]any) (any, error) {
if err != nil || !found {
continue
}
if acting.Is(key) || acting.IsOrder(key) {
if a, err := acting.Decode(raw); err == nil && (arg(args, "node") == "" || a.Node == arg(args, "node")) && (arg(args, "module") == "" || a.Module == arg(args, "module")) {
said := actingSaid{Key: key, Wait: a}
if d, err := time.ParseDuration(a.Bound); err == nil && !a.Released {
said.BoundEnds = a.ClockFrom.Add(d).UTC().Format("2006-01-02T15:04:05Z")
}
out = append(out, said)
}
continue
}
w, err := outside.Decode(raw)
if err != nil || (arg(args, "node") != "" && w.Node != arg(args, "node")) || (arg(args, "module") != "" && w.Module != arg(args, "module")) {
continue
@@ -79,120 +58,13 @@ func (s *putTools) doWaits(args map[string]any) (any, error) {
}
out = append(out, said)
}
// And each dependent's wait for its dependency's delivery (design 47 G §376, A-246), from the state delivery-waits.
delivery := []deliveryWaiting{}
dkeys, err := s.st.keys(buckets.DeliveryWaitsState)
if err != nil {
return nil, fmt.Errorf("the delivery waits cannot be listed: %w", err)
}
sort.Strings(dkeys)
for _, key := range dkeys {
raw, _, found, err := s.st.get(buckets.DeliveryWaitsState, key)
if err != nil || !found {
continue
}
var w deliveryWaiting
if json.Unmarshal(raw, &w) != nil || (arg(args, "module") != "" && w.Module != arg(args, "module")) ||
(arg(args, "node") != "" && !slices.Contains(w.Machines, arg(args, "node"))) {
continue
}
delivery = append(delivery, w)
}
// And each ask of assigner_delivered_again not yet holding, with why (A-250).
again := []againAsk{}
akeys, err := s.st.keys(buckets.DeliveredAgainState)
if err != nil {
return nil, fmt.Errorf("the asks to say a version delivered again cannot be listed: %w", err)
}
sort.Strings(akeys)
for _, key := range akeys {
raw, _, found, err := s.st.get(buckets.DeliveredAgainState, key)
var a againAsk
if err != nil || !found || json.Unmarshal(raw, &a) != nil || (arg(args, "module") != "" && a.Module != arg(args, "module")) {
continue
}
again = append(again, a)
}
return map[string]any{"waits": out, "delivery": delivery, "delivered-again": again}, nil
}
// toolDeliveredAgain is the tool that asks version-delivered said again for one version (design 47 G §376, A-250).
const toolDeliveredAgain = "assigner_delivered_again"
// doDeliveredAgain is assigner_delivered_again: the hand act is recorded first, then the ask is written into the state
// delivered-again, whose watch the assigner's process hears at once; it answers that it is asked.
func (s *putTools) doDeliveredAgain(args map[string]any, by string) (any, error) {
module, version, why := arg(args, "module"), arg(args, "version"), arg(args, "why")
if module == "" || version == "" || why == "" {
return nil, errors.New("assigner_delivered_again names the module, its version and why: it is kept in the hand-act log")
}
rec := meshhandactsclient.Recorder{Ask: s.ask}
taken, err := rec.Record(meshhandactsclient.Request{What: fmt.Sprintf("assigner_delivered_again %s %s", module, version), Why: why,
Cause: "version-delivered", Verb: "mesh-wants.assigner_delivered_again"})
if err != nil {
return nil, fmt.Errorf("the hand act could not be recorded, so nothing was asked: %w", err)
}
data, err := json.Marshal(againAsk{Module: module, Version: version, By: by, Why: why})
if err != nil {
return nil, err
}
if err := s.st.put(buckets.DeliveredAgainState, keys.EscapeName(module), data); err != nil {
return nil, fmt.Errorf("the ask of %s %s is not written: %w", module, version, err)
}
return map[string]any{"asked": module, "version": version, "hand-act": taken.Log,
"follow": "the assigner says version-delivered again once every present machine placing it runs it healthy; assigner_waits says why it does not yet"}, nil
}
// deliveredAgainTool is assigner_delivered_again as the runtime serves it.
func (s *putTools) deliveredAgainTool() stdio.Tool {
return stdio.Tool{Name: toolDeliveredAgain, Description: "Say version-delivered again for one version of a module, for the operator and the healers " +
"(design 47 G §376): written in the hand-act log first, then asked of the assigner, which says it once every present machine placing " +
"the module runs that version healthy; until then assigner_waits lists the ask with why it does not hold. Answers that it is asked.",
Input: schema(map[string]string{"module": "the module", "version": "its MAJOR.MINOR.PATCH", "why": "why, kept in the hand-act log"},
[]string{"module", "version", "why"}),
Run: func(a map[string]any) (any, error) { return s.doDeliveredAgain(a, stdio.CallerOf(a)) }}
}
// doReleaseDelivery is assigner_release with step delivery: the hand act is recorded first, then the release is written on the
// module's delivery wait, which the assigner's process ends released at its next pass, writing the module's want.
func (s *putTools) doReleaseDelivery(args map[string]any, by string) (any, error) {
module, why := arg(args, "module"), arg(args, "why")
if why == "" {
return nil, errors.New("release says why: it is kept in the hand-act log")
}
key := keys.EscapeName(module)
raw, _, found, err := s.st.get(buckets.DeliveryWaitsState, key)
if err != nil {
return nil, fmt.Errorf("the delivery wait of %s is not read: %w", module, err)
}
var w deliveryWaiting
if !found || json.Unmarshal(raw, &w) != nil || w.Released {
return nil, fmt.Errorf("%s waits for no delivery: assigner_waits lists the delivery waits", module)
}
rec := meshhandactsclient.Recorder{Ask: s.ask}
taken, err := rec.Record(meshhandactsclient.Request{What: fmt.Sprintf("assigner_release %s step delivery (waits on %s)", module, w.On), Why: why,
Cause: "delivery-wait", Verb: "mesh-wants.assigner_release"})
if err != nil {
return nil, fmt.Errorf("the hand act could not be recorded, so nothing was released: %w", err)
}
w.Released, w.By = true, by+": "+why
data, err := json.Marshal(w)
if err != nil {
return nil, err
}
if err := s.st.put(buckets.DeliveryWaitsState, key, data); err != nil {
return nil, fmt.Errorf("the release of %s's delivery wait is not written: %w", module, err)
}
return map[string]any{"released": module, "step": meshwants.WaitStepDelivery, "by": by, "hand-act": taken.Log}, nil
return map[string]any{"waits": out}, nil
}
// doReleaseWait is assigner_release with how: the hand act is recorded first, then the release is written on the wait of node and
// module, which the assigner's process takes at its next pass.
func (s *putTools) doReleaseWait(args map[string]any, by string) (any, error) {
node, module, how, why := arg(args, "node"), arg(args, "module"), arg(args, "how"), arg(args, "why")
if how == acting.HowNow {
return s.doReleaseActing(node, module, why, by)
}
if !slices.Contains([]string{outside.HowGoOn, outside.HowFailed, outside.HowRejudge}, how) {
return nil, fmt.Errorf("how is %s, %s or %s, not %q", outside.HowGoOn, outside.HowFailed, outside.HowRejudge, how)
}
@@ -238,61 +110,9 @@ func (s *putTools) doReleaseWait(args map[string]any, by string) (any, error) {
return map[string]any{"released": key, "how": how, "by": by, "hand-act": taken.Log}, nil
}
// doReleaseActing is assigner_release with how `now`: the entry of module on node moves with its acting parts' running versions. The
// hand act is recorded first; the release is written on each standing wait of the entry, and the process says wait-ended at its next pass.
func (s *putTools) doReleaseActing(node, module, why, by string) (any, error) {
if why == "" {
return nil, errors.New("release says why: it is kept in the hand-act log")
}
keys, err := s.st.keys(waitsState)
if err != nil {
return nil, fmt.Errorf("the waits cannot be listed: %w", err)
}
type one struct {
key string
w acting.Wait
}
var held []one
prefix, orderPrefix := acting.Prefix+node+"."+module+".", acting.OrderPrefix+node+"."+module+"."
for _, k := range keys {
if !strings.HasPrefix(k, prefix) && !strings.HasPrefix(k, orderPrefix) {
continue
}
raw, _, found, err := s.st.get(waitsState, k)
if err != nil || !found {
continue
}
if w, err := acting.Decode(raw); err == nil && !w.Released {
held = append(held, one{k, w})
}
}
if len(held) == 0 {
return nil, fmt.Errorf("%s holds no wait of %s for an acting part: assigner_waits lists them", node, module)
}
rec := meshhandactsclient.Recorder{Ask: s.ask}
taken, err := rec.Record(meshhandactsclient.Request{What: fmt.Sprintf("assigner_release %s %s %s", node, module, acting.HowNow), Why: why,
Cause: "acting-wait", Verb: "mesh-wants.assigner_release"})
if err != nil {
return nil, fmt.Errorf("the hand act could not be recorded, so nothing was released: %w", err)
}
released := []string{}
for _, h := range held {
h.w.Released, h.w.By, h.w.Why = true, by+": "+why, why
data, err := acting.Encode(h.w)
if err != nil {
return nil, err
}
if err := s.st.put(waitsState, h.key, data); err != nil {
return nil, fmt.Errorf("the release of %s on %s is not written: %w", module, node, err)
}
released = append(released, h.key)
}
return map[string]any{"released": released, "how": acting.HowNow, "by": by, "hand-act": taken.Log}, nil
}
// waitsTool is assigner_waits as the runtime serves it.
func (s *putTools) waitsTool() stdio.Tool {
return stdio.Tool{Name: toolWaits, Description: "Every wait of the delivery and where it stands: an entry waiting for an acting part's new version in composing or placing (§266, §268), with its part, version, step, clock-from and bound; and a moved module's failing health check on a " +
return stdio.Tool{Name: toolWaits, Description: "Every wait of the delivery and where it stands: a moved module's failing health check on a " +
"machine whose open conditions name a cause outside the delivery (design 47 G §706), with its module, machine, fingerprint, the " +
"condition's key, what it stands `on`, its clock-from, bound, its ask and its state; a settle shows as settling with its end. Narrowed by " +
"machine or module. Read-only.",
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
@@ -1,539 +0,0 @@
package main
import (
"context"
"encoding/json"
"errors"
"fmt"
"slices"
"sort"
"strconv"
"strings"
"sync"
"time"
"github.com/nats-io/nats.go/jetstream"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
mdseat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/process"
"mesh-delivery-assigner/internal/assign"
"mesh-delivery-assigner/internal/assigngraph"
"mesh-delivery-assigner/internal/assignment"
)
// The pins of the assignment graph revisions (design 47 G §153, §178, §216, §579; A-169): the gate says on the seat
// mesh-delivery which revisions a delivery record starts (`pinned`) and stops (`freed`) pointing at, and once at each of its
// starts `pins-stated`. The assigner hears them on its durable consumer of the events stream and keeps, in its old `state`
// section `pins` (4 MiB), one key `trunk.<n>` per assignment graph revision whose value is the list of the records pinning
// it, added or removed by compare-and-set before the event is acknowledged; a record heard twice pins once. Two more keys:
// `made`, written once when the state is first used, and `pins-stated`, the `at` of the last pins-stated applied. A revision
// is removed, its object and its key and the entry objects no kept revision lists and no want or running build names
// (§179), when its list is empty and it is not current (the newest the assigner wrote), only while the consumer is caught up
// and once a pins-stated said after `made` was applied; judged on a freed, on a revision ceasing to be current, on being
// caught up, and at start once both hold. Never on a timer, and never by reading the gate's state.
const (
pinsState = "pins"
pinsTool = "assigner_pins"
unpinTool = "assigner_unpin"
pinsMadeKey = "made"
pinsStatedKey = "pins-stated"
pinsCapBytes = 4 << 20
pinMissingKind = "pin-missing"
)
// PinsValue is one value of the state pins: the records that pin the revision, and whether the revision was no longer held
// when a record pinned it.
type PinsValue struct {
Records []string `json:"records"`
Missing bool `json:"missing,omitempty"`
}
// pinKey is the key of an assignment graph revision, its object's own name (A-169).
func pinKey(revision int64) string { return assigngraph.TrunkObject(revision) }
// pinRevision is the revision a key of the state names, and whether it names one.
func pinRevision(key string) (int64, bool) {
n, ok := strings.CutPrefix(key, "trunk.")
if !ok {
return 0, false
}
r, err := strconv.ParseInt(n, 10, 64)
return r, err == nil && r > 0
}
// pinObjects is the object bucket of the revisions as the pins remove from it.
type pinObjects interface {
assigngraph.Objects
Delete(ctx context.Context, name string) error
}
// pinKeeper keeps the pins and removes what nothing pins.
type pinKeeper struct {
ctx context.Context
st endStore
objects pinObjects
// inUse says a want or a running build names the module's fingerprint (§179).
inUse func(module, fp string) bool
findings assign.Findings
now func() time.Time
logf func(string, ...any)
mu sync.Mutex
// caught is whether the last event applied left none of the consumer's messages pending.
caught bool
}
// edit applies change to the value at key by compare-and-set, again while another write comes between.
func (k *pinKeeper) edit(key string, change func(v PinsValue, found bool) (PinsValue, bool)) error {
for {
raw, rev, err := k.st.get(key)
if err != nil {
return err
}
var v PinsValue
if raw != nil {
if err := json.Unmarshal(raw, &v); err != nil {
return fmt.Errorf("the pins of %s do not read: %w", key, err)
}
}
next, write := change(v, raw != nil)
if !write {
return nil
}
value, _ := json.Marshal(next)
if err := k.st.swap(key, value, rev); errors.Is(err, errSwapped) {
continue
} else {
return err
}
}
}
// held says the revision's object is kept.
func (k *pinKeeper) held(revision int64) (bool, error) {
_, err := k.objects.Get(k.ctx, assigngraph.TrunkObject(revision))
if errors.Is(err, assigngraph.ErrNoObject) {
return false, nil
}
return err == nil, err
}
// pin adds record to each assignment graph revision of p; a revision no longer held is written missing, with the finding
// pin-missing naming the record.
func (k *pinKeeper) pin(p mdseat.Pins) error {
for _, r := range p.Assignment {
held, err := k.held(r)
if err != nil {
return err
}
err = k.edit(pinKey(r), func(v PinsValue, _ bool) (PinsValue, bool) {
if slices.Contains(v.Records, p.Record) && (held || v.Missing) {
return v, false
}
if !slices.Contains(v.Records, p.Record) {
v.Records = append(v.Records, p.Record)
slices.Sort(v.Records)
}
v.Missing = v.Missing || !held
return v, true
})
if err != nil {
return err
}
if !held {
k.missing(r, p.Record)
}
}
return nil
}
// free removes record from each assignment graph revision of p; a freed applied twice changes nothing.
func (k *pinKeeper) free(p mdseat.Pins) error {
for _, r := range p.Assignment {
err := k.edit(pinKey(r), func(v PinsValue, found bool) (PinsValue, bool) {
i := slices.Index(v.Records, p.Record)
if !found || i < 0 {
return v, false
}
v.Records = slices.Delete(v.Records, i, i+1)
return v, true
})
if err != nil {
return err
}
}
return nil
}
// missing writes the finding pin-missing, scope the assigner, id the revision.
func (k *pinKeeper) missing(revision int64, record string) {
if k.findings.Put == nil {
k.logf("the revision %d the record %s pins is not held, and no finding writer is wired to say so", revision, record)
return
}
o := assign.Observed{Scope: assignment.Module(), ID: strconv.FormatInt(revision, 10), Kind: pinMissingKind,
Summary: fmt.Sprintf("the delivery record %s pins the assignment graph revision %d, which the assigner no longer holds", record, revision),
Headline: "A delivery record pins a revision the assigner no longer holds",
Explanation: fmt.Sprintf("The record %s pinned revision %d after it was removed; %s clears it.", record, revision, unpinTool),
Source: assignment.Module()}
if err := k.findings.Put(o.Finding(k.now())); err != nil {
k.logf("the finding %s of revision %d is not written: %v", pinMissingKind, revision, err)
}
}
// made writes the key made once, create-only; one there already stays.
func (k *pinKeeper) made() error {
raw, _, err := k.st.get(pinsMadeKey)
if err != nil || raw != nil {
return err
}
value, _ := json.Marshal(k.now().UTC())
if err := k.st.swap(pinsMadeKey, value, 0); err != nil && !errors.Is(err, errSwapped) {
return err
}
return nil
}
// timeAt is the time a key holds; false when it holds none.
func (k *pinKeeper) timeAt(key string) (time.Time, bool, error) {
raw, _, err := k.st.get(key)
if err != nil || raw == nil {
return time.Time{}, false, err
}
var t time.Time
if err := json.Unmarshal(raw, &t); err != nil {
return t, false, fmt.Errorf("the key %s does not read: %w", key, err)
}
return t, true, nil
}
// stated keeps the at of a pins-stated applied.
func (k *pinKeeper) stated(at time.Time) error {
for {
raw, rev, err := k.st.get(pinsStatedKey)
if err != nil {
return err
}
var was time.Time
if raw != nil && json.Unmarshal(raw, &was) == nil && !at.After(was) {
return nil
}
value, _ := json.Marshal(at.UTC())
if err := k.st.swap(pinsStatedKey, value, rev); errors.Is(err, errSwapped) {
continue
} else {
return err
}
}
}
// statedSinceMade says a pins-stated said after the state was made was applied.
func (k *pinKeeper) statedSinceMade() (bool, error) {
made, ok, err := k.timeAt(pinsMadeKey)
if err != nil || !ok {
return false, err
}
at, ok, err := k.timeAt(pinsStatedKey)
if err != nil || !ok {
return false, err
}
return at.After(made), nil
}
// hear applies one of the seat mesh-delivery's events and acknowledges it only once applied.
func (k *pinKeeper) hear(m jetstream.Msg) {
err := k.apply(m.Subject(), m.Data())
if err != nil {
k.logf("%s: %v; it is heard again", m.Subject(), err)
_ = m.Nak()
return
}
_ = m.Ack()
caught := false
if meta, merr := m.Metadata(); merr == nil {
caught = meta.NumPending == 0
}
k.mu.Lock()
was := k.caught
k.caught = caught
k.mu.Unlock()
if caught && (!was || m.Subject() != mdseat.SubjectPinned) {
k.judge() // on a freed, on a candidate's heads replaced, on pins-stated, and on being caught up
}
}
// apply takes one event's body.
func (k *pinKeeper) apply(subject string, data []byte) error {
switch subject {
case mdseat.SubjectPinned, mdseat.SubjectFreed:
var p mdseat.Pins
if err := json.Unmarshal(data, &p); err != nil || p.Record == "" {
k.logf("%s holds no pins naming a record, and is not taken: %v", subject, err)
return nil
}
if subject == mdseat.SubjectPinned {
return k.pin(p)
}
return k.free(p)
case mdseat.SubjectPinsStated:
var s mdseat.PinsStatedEvent
if err := json.Unmarshal(data, &s); err != nil || s.At.IsZero() {
k.logf("%s holds no at, and is not taken: %v", subject, err)
return nil
}
return k.stated(s.At)
}
return nil // heads-replaced: a candidate's revision stops being current, judged after
}
// judge removes every revision neither pinned nor current, when the rule allows a removal at all.
func (k *pinKeeper) judge() {
k.mu.Lock()
caught := k.caught
k.mu.Unlock()
if !caught {
return
}
ok, err := k.statedSinceMade()
if err != nil {
k.logf("the pins are not judged: %v", err)
return
}
if !ok {
return // no pins-stated applied since the state was made: a pin said before may not be heard yet
}
if err := k.remove(); err != nil {
k.logf("the revisions nothing pins are not removed: %v", err)
}
}
// remove removes each kept revision that is not current and that no record pins, and then the entries left unlisted.
func (k *pinKeeper) remove() error {
names, err := k.objects.Names(k.ctx)
if err != nil {
return err
}
var kept []int64
for _, n := range names {
if r, ok := pinRevision(n); ok {
kept = append(kept, r)
}
}
if len(kept) == 0 {
return nil
}
current := slices.Max(kept)
listed := map[string]bool{}
removed := 0
for _, r := range kept {
raw, _, err := k.st.get(pinKey(r))
if err != nil {
return err
}
var v PinsValue
if raw != nil {
if err := json.Unmarshal(raw, &v); err != nil {
return fmt.Errorf("the pins of %d do not read: %w", r, err)
}
}
if r == current || len(v.Records) > 0 {
rev, err := assigngraph.ReadRevision(k.ctx, k.objects, r)
if err != nil {
return err
}
for _, e := range rev.Entries {
listed[e.Digest] = true
}
continue
}
if err := k.objects.Delete(k.ctx, assigngraph.TrunkObject(r)); err != nil {
return fmt.Errorf("revision %d: %w", r, err)
}
if raw != nil {
if err := k.st.drop(pinKey(r)); err != nil {
return fmt.Errorf("the pins of %d: %w", r, err)
}
}
removed++
}
if removed == 0 {
return nil
}
// A run's candidate kept now lists its entries too, until its group-ended drops it (A-201, A-235).
for _, n := range names {
group, heads, ok := meshwants.ParseAssignmentRevisionsByCandidateGroupHeadsKey(n)
if !ok {
continue
}
rev, err := assigngraph.ReadCandidate(k.ctx, k.objects, group, heads)
if err != nil {
return err
}
for _, e := range rev.Entries {
listed[e.Digest] = true
}
}
for _, n := range names {
digest, ok := strings.CutPrefix(n, "entry.")
if !ok || listed[digest] {
continue
}
e, err := assigngraph.ReadEntry(k.ctx, k.objects, digest)
if err != nil {
return err
}
if k.inUse != nil && k.inUse(e.Module, e.Fp) {
continue
}
if err := k.objects.Delete(k.ctx, n); err != nil {
return fmt.Errorf("the entry %s: %w", digest, err)
}
}
k.logf("%d assignment graph revisions no record pins and not current are removed", removed)
return nil
}
// hearPins registers the seat mesh-delivery's four events on the assigner's hub.
func hearPins(hub *process.EventHub, k *pinKeeper) error {
for _, s := range []string{mdseat.SubjectPinned, mdseat.SubjectFreed, mdseat.SubjectHeadsReplaced, mdseat.SubjectPinsStated} {
if err := hub.Handle(s, k.hear); err != nil {
return fmt.Errorf("%s: %w", s, err)
}
}
return nil
}
// pinsTools are assigner_pins and assigner_unpin over the runtime's states.
func pinsTools(st store, ask func(string, any) (json.RawMessage, error)) []stdio.Tool {
return []stdio.Tool{{Name: pinsTool, Description: "the assignment graph revisions the delivery records pin (design 47 G §579): per revision " +
"the records that pin it and whether it was missing when pinned, the newest revision kept (current, never removed), when the state " +
"was made, the last pins-stated applied, and the state's fill against its cap of 4 MiB.",
Run: func(map[string]any) (any, error) { return readPins(st) }},
{Name: unpinTool, Description: "Remove one record from a revision's pins, for a freed that was lost (design 47 G §579); written in the " +
"hand-act log first. The removal rule then applies.",
Input: schema(map[string]string{"revision": "the assignment graph revision's number", "record": "the delivery record's id",
"why": "why it is removed by hand"}, []string{"revision", "record", "why"}),
Run: func(a map[string]any) (any, error) {
record, _ := a["record"].(string)
why, _ := a["why"].(string)
return unpin(st, ask, fmt.Sprint(a["revision"]), record, why, stdio.CallerOf(a))
}}}
}
// readPins is what assigner_pins answers.
func readPins(st store) (any, error) {
ks, err := st.keys(pinsState)
if err != nil {
return nil, err
}
sort.Strings(ks)
revisions := map[string]PinsValue{}
out := map[string]any{"revisions": revisions}
var newest int64
bytes := 0
for _, key := range ks {
raw, _, found, err := st.get(pinsState, key)
if err != nil || !found {
continue
}
bytes += len(key) + len(raw)
if r, ok := pinRevision(key); ok {
var v PinsValue
if json.Unmarshal(raw, &v) == nil {
revisions[key] = v
}
newest = max(newest, r)
continue
}
out[key] = json.RawMessage(raw)
}
out["fill"] = meshwants.Fill{Store: pinsState, Bytes: int64(bytes), Cap: pinsCapBytes}
if newest > 0 {
out["newest-pinned"] = newest
}
return out, nil
}
// unpin removes one record from one revision's list, the hand act recorded first.
func unpin(st store, ask func(string, any) (json.RawMessage, error), revision, record, why, by string) (any, error) {
r, err := strconv.ParseInt(strings.TrimPrefix(revision, "trunk."), 10, 64)
switch {
case err != nil || r <= 0:
return nil, fmt.Errorf("revision %q is no assignment graph revision's number", revision)
case record == "" || why == "":
return nil, errors.New("name the record and say why")
case by == "" || by == stdio.Unproven:
return nil, errors.New("an unpin names who asks it, and the runtime proved no caller")
}
key := pinKey(r)
raw, _, found, err := st.get(pinsState, key)
if err != nil {
return nil, err
}
var v PinsValue
if found {
if err := json.Unmarshal(raw, &v); err != nil {
return nil, err
}
}
i := slices.Index(v.Records, record)
if i < 0 {
return nil, fmt.Errorf("the record %s does not pin revision %d: %s lists its pins", record, r, pinsTool)
}
taken, err := meshhandactsclient.Recorder{Ask: ask}.Record(meshhandactsclient.Request{What: unpinTool + " " + key + " " + record,
Why: why + " (" + by + ")", Cause: "unpin"})
if err != nil {
return nil, fmt.Errorf("the hand act is not recorded, so nothing is removed: %w", err)
}
v.Records = slices.Delete(v.Records, i, i+1)
value, _ := json.Marshal(v)
if err := st.put(pinsState, key, value); err != nil {
return nil, err
}
return map[string]any{"revision": r, "unpinned": record, "records": v.Records, "hand-act": taken.Log}, nil
}
// watchUnpins judges again when a revision's pins change in the state itself, as assigner_unpin writes them from the tool
// process: the assigner's own state, heard as it changes, never on a timer.
func (k *pinKeeper) watchUnpins(kv jetstream.KeyValue) {
w, err := kv.WatchAll(k.ctx, jetstream.UpdatesOnly())
if err != nil {
k.logf("the state %s is not watched, so a hand unpin is judged at the next freed or revision: %v", pinsState, err)
return
}
go func() {
defer func() { _ = w.Stop() }()
for e := range w.Updates() {
if e == nil {
continue
}
if _, ok := pinRevision(e.Key()); ok && e.Operation() == jetstream.KeyValuePut {
k.judge()
}
}
}()
}
// inUseOf says a want or a running build names the module's fingerprint, as the world holds them now.
func inUseOf(w *world) func(module, fp string) bool {
return func(module, fp string) bool {
for _, want := range w.wantsOf()[module] {
if want.Fp == fp {
return true
}
}
for _, mods := range w.runningNow() {
if r, ok := mods[module]; ok && r.Fingerprint == fp {
return true
}
}
return false
}
}
func pinsBucket() string { return assignment.Module() + "_" + pinsState }
@@ -1,119 +0,0 @@
package main
import (
"context"
"encoding/json"
"testing"
"time"
mcseat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
mdseat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"mesh-delivery-assigner/internal/assign"
"mesh-delivery-assigner/internal/assigngraph"
)
func (m memObjects) Delete(_ context.Context, name string) error { delete(m, name); return nil }
// The pins of the assignment graph revisions (design 47 G §153, §178, §579; A-169): a revision two records pin stays until
// both free it; a record pinning twice pins once; the current revision is never removed; nothing is removed before a
// pins-stated said after the state was made, nor while the consumer is behind; a revision no longer held is pinned missing,
// with the finding pin-missing; an entry another kept revision lists, or a want or a running build names, stays.
func TestPinsKeepARevisionWhileARecordPinsIt(t *testing.T) {
objects := memObjects{}
entry := func(module, fp string) string {
e := meshwants.AssignmentEntry{Node: "n1", Module: module, Fp: fp}
d := assigngraph.EntryDigest(e)
raw, _ := json.Marshal(e)
objects[assigngraph.EntryObject(d)] = raw
return d
}
shared, old, running := entry("a", "fp-a"), entry("b", "fp-b1"), entry("c", "fp-c1")
revision := func(n int64, digests ...string) {
rev := meshwants.AssignmentRevision{Revision: n}
for _, d := range digests {
rev.Entries = append(rev.Entries, meshwants.NodeEntryRef{Node: "n1", Digest: d})
}
raw, _ := json.Marshal(rev)
objects[assigngraph.TrunkObject(n)] = raw
}
// A run's candidate lists an entry no trunk revision lists (A-201): it stays while the candidate is kept.
cand := entry("d", "fp-d2")
candRaw, _ := json.Marshal(meshwants.AssignmentRevision{Revision: 1, Kind: "candidate", Group: "run-7", Heads: "h1",
Entries: []meshwants.NodeEntryRef{{Node: "n1", Module: "d", Digest: cand}}})
objects[assigngraph.CandidateObject("run-7", "h1")] = candRaw
revision(1, shared, old, running)
revision(2, shared, old)
revision(3, shared)
var found []mcseat.Finding
clock := time.Date(2026, 11, 12, 10, 0, 0, 0, time.UTC)
k := &pinKeeper{ctx: context.Background(), st: newMemEnds(), objects: objects, now: func() time.Time { return clock },
logf: t.Logf,
inUse: func(module, fp string) bool { return module == "c" && fp == "fp-c1" },
findings: assign.Findings{Put: func(f mcseat.Finding) error { found = append(found, f); return nil }}}
if err := k.made(); err != nil {
t.Fatal(err)
}
say := func(subject string, body any) {
t.Helper()
raw, _ := json.Marshal(body)
if err := k.apply(subject, raw); err != nil {
t.Fatal(err)
}
k.judge()
}
pins := func(record string, revs ...int64) mdseat.Pins { return mdseat.Pins{Record: record, Assignment: revs} }
has := func(n int64) bool { _, ok := objects[assigngraph.TrunkObject(n)]; return ok }
k.caught = true
say(mdseat.SubjectPinned, pins("r1", 1))
say(mdseat.SubjectPinned, pins("r1", 1))
say(mdseat.SubjectPinned, pins("r2", 1))
say(mdseat.SubjectFreed, pins("r9", 2)) // nothing pins 2, but no pins-stated since made: nothing removed
if !has(2) {
t.Fatal("revision 2 was removed before a pins-stated said after the state was made")
}
k.caught = false
say(mdseat.SubjectPinsStated, mdseat.PinsStatedEvent{At: clock.Add(time.Minute)})
if !has(2) {
t.Fatal("revision 2 was removed while the consumer was behind")
}
k.caught = true
say(mdseat.SubjectFreed, pins("r1", 1))
if has(2) {
t.Error("revision 2, neither pinned nor current, is kept")
}
if !has(1) || !has(3) {
t.Error("revision 1 (pinned by r2) or 3 (current) was removed")
}
raw, _, _ := k.st.get(pinKey(1))
if string(raw) != `{"records":["r2"]}` {
t.Errorf("the pins of 1 = %s, want r2 alone (r1 pinned twice pins once, and freed once)", raw)
}
say(mdseat.SubjectFreed, pins("r2", 1))
if has(1) {
t.Error("revision 1 is kept once both records freed it")
}
if _, ok := objects[assigngraph.EntryObject(old)]; ok {
t.Error("the entry no kept revision lists and nothing names is kept")
}
if _, ok := objects[assigngraph.EntryObject(running)]; !ok {
t.Error("the entry of a running build is removed")
}
if _, ok := objects[assigngraph.EntryObject(shared)]; !ok {
t.Error("the entry the current revision lists is removed")
}
if _, ok := objects[assigngraph.EntryObject(cand)]; !ok {
t.Error("the entry a run's kept candidate lists is removed")
}
say(mdseat.SubjectHeadsReplaced, mdseat.HeadsReplacedEvent{})
if _, ok := objects[assigngraph.CandidateObject("run-7", "h1")]; !ok {
t.Error("the gate's heads-replaced dropped a run's candidate")
}
say(mdseat.SubjectPinned, pins("r3", 2))
raw, _, _ = k.st.get(pinKey(2))
if string(raw) != `{"records":["r3"],"missing":true}` || len(found) != 1 || found[0].Kind != pinMissingKind || found[0].ID != "2" {
t.Errorf("a pin of a revision no longer held = %s, findings %+v", raw, found)
}
}
@@ -14,20 +14,21 @@ import (
"github.com/nats-io/nats.go/jetstream"
mcc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
mprc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshpipelinerunnerclient"
mwc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
mpcat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
mpr "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/process"
"mesh-delivery-assigner/internal/assign"
)
// The wants follow a passed pipeline (design 47 G §29, §35, §325, §352): the runner says each pipeline's end as
// pipeline-ended, and a group's as group-ended. The assigner keeps, in its old state `written`, one key per module and
// watched branch: the source revision and end count of the newest end it heard for it, and whether the wants were written
// from it. A newer end replaces it by compare-and-set; an older one, or the same one again, writes nothing.
// The wants follow a passed pipeline (design 47 H §750): the runner says each pipeline's end once, per source revision, as
// pipeline-ended on `pipeline-ended.<branch>.<source>`, naming per mover its fingerprint, its released version and its tier
// (§746). The assigner keeps, in its state `written` (G §352), one key per module and watched branch: the newest released
// version of the module on that branch whose pipeline passed, with the pipeline and the mover's rank in it. A newer version
// replaces it by compare-and-set; an older one, the same one again, a failed pipeline and a run on request write nothing.
// writtenState is the assigner's state of the pipeline ends its wants follow; writtenTool reads it.
const (
@@ -35,23 +36,17 @@ const (
writtenTool = "assigner_written"
)
// pipelineEndedSubject and groupEndedSubject are the runner's events the assigner consumes.
const (
pipelineEndedSubject = "mesh.seat." + mpr.Seat + ".event." + mpr.EventPipelineEnded + ".>"
groupEndedSubject = "mesh.seat." + mpr.Seat + ".event." + mpr.EventGroupEnded + ".>"
)
// pipelineEndedSubject is the runner's event the assigner consumes.
const pipelineEndedSubject = "mesh.seat." + mpr.Seat + ".event." + mpr.EventPipelineEnded + ".>"
// End is one value of the state written: the newest end of a module's pipeline on a watched branch.
// End is one value of the state written: the newest version of a module released on a watched branch whose pipeline passed.
type End struct {
Pipeline string `json:"pipeline"`
Source int64 `json:"source"`
EndCount int64 `json:"end-count"`
Fp string `json:"fp"`
Commit string `json:"commit,omitempty"`
// Passed: the pipeline ended passed, every required step passed (and, for a group, the group ended passed).
Passed bool `json:"passed"`
// Written: the wants were written from this end.
Written bool `json:"written,omitempty"`
Why string `json:"why,omitempty"`
Version string `json:"version"`
// Rank is the mover's tier in the pipeline's delivery order, from 1 (§746, §750).
Rank int64 `json:"rank"`
}
// endKey is the key of a module on a watched branch, each name escaped as a key's name is.
@@ -59,15 +54,10 @@ func endKey(module, branch string) string {
return keys.EscapeName(module) + "." + keys.EscapeName(branch)
}
// newer says whether an end of (source, count) replaces the one kept: a later source revision, or the same one ended again.
func (e End) newer(source, count int64) bool {
return source > e.Source || (source == e.Source && count > e.EndCount)
}
// requiredPassed says whether no required step of a pipeline stands failed, unasked or unended (design 47 G §30: a failed
// optional step holds nothing).
func requiredPassed(p mpr.PipelineEnded) bool {
for _, s := range p.Steps {
// moverPassed says whether no required step of a mover stands failed, unasked or unended: a required step ending "nothing to
// run" counts as passed, as a bypassed one does (design 47 H §746, H-A-3); a failed optional step holds nothing (G §30).
func moverPassed(m mpr.MoverEnded) bool {
for _, s := range m.Steps {
if s.Status != mpr.StepResultStatusRequired {
continue
}
@@ -78,7 +68,7 @@ func requiredPassed(p mpr.PipelineEnded) bool {
return false
}
}
return p.Outcome == mpr.PipelineEndedOutcomePassed
return true
}
// endStore is the kept state written: the bus bucket, or a test's.
@@ -139,128 +129,163 @@ func isWrongSequence(err error) bool {
return errors.As(err, &ae) && ae.ErrorCode == jetstream.JSErrCodeStreamWrongLastSequence
}
// pipelineEnds follows the runner's ends. A nil *pipelineEnds is the trunk-only want, kept until the first registrations
// (design 47 G §95, §353).
// pipelineEnds follows the runner's ends; a nil *pipelineEnds keeps none, and no want is written from it.
type pipelineEnds struct {
st endStore
wake func()
logf func(string, ...any)
// on is whether the wants follow the ends: set by the first registration heard, never before (design 47 G §95, §353).
// on says the first registration was heard (design 47 G §353), said once in the journal.
on atomic.Bool
mu sync.Mutex
// firsts is, by module, the first watched branch of its registration, the branch of a placement that names none (design
// 47 G §14).
firsts map[string]string
// runEnded is told a run on request's group-ended, its group `run-<id>`, to drop the run's candidate (A-235); nil drops nothing.
// runEnded is told a run on request's pipeline-ended, its group `run-<id>`, to drop the run's candidate (A-235, H-A-58); nil
// drops nothing.
runEnded func(group string) error
// left is told the key of a pipeline ended superseded or cancelled, whose composition steps leave the runs they read
// (design 47 G §723, A-469n); none tells nothing. Set once the composition steps are served, after the hub starts.
left atomic.Pointer[func(pipeline string) error]
// onBranches is told the branches a registration names, for the catalog half of each to be followed (design 47 G §14, §195).
onBranches func([]string)
// trunk names the first watched branch, the trunk's (design 47 G §507), the branch of a module registered with none.
trunk func() string
// runner is the module holding the seat mesh-pipeline-runner, as the last pass read it from the acting edges (A-334); nil
// until a pass read the graph.
runner atomic.Pointer[string]
// held are the group members' pipeline-ended heard before a pass read the graph, by their body: unacknowledged, so the
// bus keeps them, and taken once the runner is read (A-334), never dropped for the runner not being known yet.
held map[string]jetstream.Msg
}
// setRunner keeps the module holding the seat mesh-pipeline-runner, read by the pass from the acting edges (A-334); the
// first one takes the group members' ends held until the graph was read.
func (e *pipelineEnds) setRunner(module string) {
e.mu.Lock()
first := e.runner.Swap(&module) == nil
held := e.held
e.held = nil
e.mu.Unlock()
if !first {
return
}
for _, m := range held {
e.hearPipeline(m)
}
}
// holdUntilRead keeps m, a group member's pipeline-ended, until a pass reads the runner from the graph; false when the
// runner is read already, so m is taken now.
func (e *pipelineEnds) holdUntilRead(m jetstream.Msg) bool {
e.mu.Lock()
defer e.mu.Unlock()
if e.runner.Load() != nil {
return false
}
if e.held == nil {
e.held = map[string]jetstream.Msg{}
}
e.held[string(m.Data())] = m
e.logf("%s is a group member's end heard before the assignment graph is read: held until a pass reads which module is the runner (A-334)", m.Subject())
return true
}
// isRunner says whether module holds the seat mesh-pipeline-runner, as the last pass read it.
func (e *pipelineEnds) isRunner(module string) bool {
r := e.runner.Load()
return r != nil && *r != "" && *r == module
// now is the clock of the tier progress (tiers.go); nil is time.Now.
now func() time.Time
}
func newPipelineEnds(st endStore, wake func(), logf func(string, ...any)) *pipelineEnds {
return &pipelineEnds{st: st, wake: wake, logf: logf, firsts: map[string]string{}}
}
// take keeps one pipeline's end if it is newer than the one kept for its module and branch, by compare-and-set.
func (e *pipelineEnds) take(p mpr.PipelineEnded, passed bool) error {
key := endKey(p.Module, p.Branch)
for {
raw, rev, err := e.st.get(key)
if err != nil {
return err
// take keeps, for each mover of a passed pipeline that released a version, that version as the newest of its module on the
// pipeline's branch, by compare-and-set on a newer version (design 47 H §750): an older version, or the same one again, writes
// nothing. A passed mover with no version yet is said in the journal and taken when the runner says the end again naming it
// (H-A-270); it holds its tier in the pipeline's tier progress meanwhile (H-A-277 (1)). It says whether any key changed.
func (e *pipelineEnds) take(p mpr.PipelineEnded) (bool, error) {
if p.Outcome != mpr.PipelineEndedOutcomePassed || p.Run != "" {
return false, nil
}
changed := false
var kept []tierMover
versioned := map[string]bool{}
defer func() {
if err := e.startTiers(p.Pipeline, p.Source, kept, versioned); err != nil {
e.logf("the tier progress of %s is not written: %v", p.Pipeline, err)
}
if raw != nil {
var kept End
if err := json.Unmarshal(raw, &kept); err == nil && !kept.newer(p.Source, p.EndCount) {
return nil // an older end, or this one again
}()
for _, m := range p.Movers {
if m.Fingerprint == "" || !moverPassed(m) {
continue
}
if m.Version == "" {
// The runner writes a mover's version at its release's version-released, and says this end again once it does
// (H-A-270 (1), (2)): the skip is said, never silent.
e.logf("%s: %s passed with no version yet: taken again when its version is written", p.Pipeline, m.Module)
// It holds its tier in the progress until its version is written (H-A-277 (1)).
kept = append(kept, tierMover{Module: m.Module, Fp: m.Fingerprint, Tier: max(m.Tier, 1), NoVersion: true})
continue
}
versioned[m.Module] = true
key := endKey(m.Module, p.Branch)
for {
raw, rev, err := e.st.get(key)
if err != nil {
return changed, err
}
if raw != nil {
var kept End
if err := json.Unmarshal(raw, &kept); err == nil && compareVersion(m.Version, kept.Version) <= 0 {
break // an older version, or this one again
}
}
value, err := json.Marshal(End{Pipeline: p.Pipeline, Source: p.Source, Fp: m.Fingerprint, Version: m.Version, Rank: max(m.Tier, 1)})
if err != nil {
return changed, err
}
if err := e.st.swap(key, value, rev); errors.Is(err, errSwapped) {
continue
} else if err != nil {
return changed, err
}
changed = true
kept = append(kept, tierMover{Module: m.Module, Fp: m.Fingerprint, Tier: max(m.Tier, 1)})
break
}
end := End{Source: p.Source, EndCount: p.EndCount, Fp: p.Fingerprint, Commit: p.Commit, Passed: passed, Why: p.Why}
value, err := json.Marshal(end)
if err != nil {
return err
}
if err := e.st.swap(key, value, rev); errors.Is(err, errSwapped) {
continue
} else if err != nil {
return err
}
e.wake()
return nil
}
return changed, nil
}
// markWritten says the wants of module on branch were written from the end it keeps, if that is still the end of fp.
func (e *pipelineEnds) markWritten(module, branch, fp string) {
key := endKey(module, branch)
for {
raw, rev, err := e.st.get(key)
var kept End
if err != nil || raw == nil || json.Unmarshal(raw, &kept) != nil || kept.Fp != fp || kept.Written {
return
}
kept.Written = true
value, _ := json.Marshal(kept)
if err := e.st.swap(key, value, rev); errors.Is(err, errSwapped) {
continue
} else if err != nil {
e.logf("the end of %s on %s is not marked written: %v", module, branch, err)
}
return
// endOf is the end kept for module on branch: the newest version released there whose pipeline passed.
func (e *pipelineEnds) endOf(module, branch string) (End, bool) {
if e == nil {
return End{}, false
}
}
// passedAt says whether the newest end kept for module on branch passed at fp.
func (e *pipelineEnds) passedAt(module, branch, fp string) bool {
raw, _, err := e.st.get(endKey(module, branch))
var kept End
return err == nil && raw != nil && json.Unmarshal(raw, &kept) == nil && kept.Passed && kept.Fp == fp
if err != nil || raw == nil || json.Unmarshal(raw, &kept) != nil || kept.Fp == "" {
return End{}, false
}
return kept, true
}
// target is the build module's wants on branch name (design 47 H §750): the newest version released there whose pipeline
// passed, with the pipeline and the mover's rank; false when none is kept, or its pipeline's tier progress has not reached its
// rank (§751).
func (e *pipelineEnds) target(module, branch string) (assign.Target, bool) {
end, ok := e.endOf(module, e.branchOf(module, branch))
if !ok || !e.tierWritten(end) {
return assign.Target{}, false
}
return assign.Target{Fp: end.Fp, Version: end.Version, Pipeline: end.Pipeline, Rank: end.Rank}, true
}
// hearPipeline takes a pipeline-ended: a passed one's released versions are kept (take), and a run on request's drops the
// run's candidate assignment graph (A-235, H-A-58); a run delivers nothing (design 47 G §29, §64). A pipeline ended superseded or
// cancelled has its composition steps leave the runs they read (G §723).
func (e *pipelineEnds) hearPipeline(m jetstream.Msg) {
p, err := mprc.PipelineEnded(m.Data())
if err != nil {
e.logf("%s is not taken: %v", m.Subject(), err)
_ = m.Ack()
return
}
if left := e.left.Load(); left != nil && (p.Outcome == mpr.PipelineEndedOutcomeSuperseded || p.Outcome == mpr.PipelineEndedOutcomeCancelled) {
if err := (*left)(p.Pipeline); err != nil {
e.logf("%s: the composition steps of %s do not all leave their runs: %v; it is heard again", m.Subject(), p.Pipeline, err)
_ = m.Nak()
return
}
}
if p.Run != "" {
if e.runEnded != nil {
if err := e.runEnded(runGroupPrefix + p.Run); err != nil {
e.logf("%s: %v; it is heard again", m.Subject(), err)
_ = m.Nak()
return
}
}
_ = m.Ack()
return
}
changed, err := e.take(p)
if err != nil {
e.logf("%s: %v; it is heard again", m.Subject(), err)
_ = m.Nak()
return
}
if changed {
e.wake()
}
_ = m.Ack()
}
// hearEnds registers pipeline-ended on the assigner's hub.
func hearEnds(hub *process.EventHub, e *pipelineEnds) error {
if err := hub.Handle(pipelineEndedSubject, e.hearPipeline); err != nil {
return fmt.Errorf("%s: %w", pipelineEndedSubject, err)
}
return nil
}
// branchOf is the watched branch a placement names, else the first of the module's registration, else the trunk's.
@@ -279,84 +304,35 @@ func (e *pipelineEnds) branchOf(module, placed string) string {
return ""
}
// hearPipeline takes a pipeline-ended. A pipeline of a group writes nothing on its own end, but the runner's: in a group
// take-in that changes the runner it is the acting part the other members wait on, so it goes first, wanted on its own end
// once that passed, ahead of the group (A-334, as the node-engine does, §268). A run on request delivers nothing (design 47 G
// §29, §64).
func (e *pipelineEnds) hearPipeline(m jetstream.Msg) {
p, err := mprc.PipelineEnded(m.Data())
switch {
case err != nil:
e.logf("%s is not taken: %v", m.Subject(), err)
case p.Run == "" && p.Group != "" && e.holdUntilRead(m):
return
case p.Run != "" || (p.Group != "" && !e.isRunner(p.Module)):
default:
if err := e.take(p, requiredPassed(p)); err != nil {
e.logf("%s: %v; it is heard again", m.Subject(), err)
_ = m.Nak()
return
}
}
_ = m.Ack()
}
// hearGroup takes a group-ended: each member's end, passed only if the group passed. A run on request's (group `run-<id>`) delivers
// nothing: it drops the run's candidate assignment graph (A-235).
func (e *pipelineEnds) hearGroup(m jetstream.Msg) {
g, err := mprc.GroupEnded(m.Data())
if err != nil {
e.logf("%s is not taken: %v", m.Subject(), err)
_ = m.Ack()
return
}
if strings.HasPrefix(g.Group, runGroupPrefix) {
if e.runEnded != nil {
if err := e.runEnded(g.Group); err != nil {
e.logf("%s: %v; it is heard again", m.Subject(), err)
_ = m.Nak()
return
}
}
_ = m.Ack()
return
}
for _, p := range g.Pipelines {
if err := e.take(p, g.Outcome == mpr.GroupEndedOutcomePassed && requiredPassed(p)); err != nil {
e.logf("%s: %v; it is heard again", m.Subject(), err)
_ = m.Nak()
return
}
}
_ = m.Ack()
}
// hearEnds registers the two events on the assigner's hub.
func hearEnds(hub *process.EventHub, e *pipelineEnds) error {
if err := hub.Handle(pipelineEndedSubject, e.hearPipeline); err != nil {
return fmt.Errorf("%s: %w", pipelineEndedSubject, err)
}
if err := hub.Handle(groupEndedSubject, e.hearGroup); err != nil {
return fmt.Errorf("%s: %w", groupEndedSubject, err)
}
return nil
}
// writtenTools is the tool assigner_written: every key of the state written, with its end.
func writtenTools(st store) []stdio.Tool {
return []stdio.Tool{{Name: writtenTool, Description: "the pipeline ends the assigner's wants follow: per module and watched branch, the source revision and end count of the newest end heard, whether it passed and whether the wants were written from it.",
Run: func(map[string]any) (any, error) {
return []stdio.Tool{{Name: writtenTool, Description: "the pipeline ends the assigner's wants follow: per module and watched branch, the newest version released whose pipeline passed, with its pipeline and rank; per pipeline whose wants are written tier by tier, its tier progress (tier, since, movers); with why, why each want is what it is (as assigner_why).",
Input: schema(map[string]string{"why": "true: why each want is what it is", "module": "with why: a module's name", "node": "with why: a node's name"}, nil, "why"),
Run: func(args map[string]any) (any, error) {
if args["why"] == true || args["why"] == "true" {
return whyTools(st)[0].Run(args) // a want's why (why.go), until the manifest naming assigner_why is taken in
}
ks, err := st.keys(writtenState)
if err != nil {
return nil, err
}
sort.Strings(ks)
out := map[string]End{}
out := map[string]any{}
for _, k := range ks {
if strings.HasPrefix(k, whyPrefix) {
continue // a want's why (why.go), read by assigner_why
}
raw, _, ok, err := st.get(writtenState, k)
if err != nil || !ok {
continue
}
if isTierKey(k) { // a pipeline's tier progress (tiers.go)
var t tierProgress
if json.Unmarshal(raw, &t) == nil {
out[k] = t
}
continue
}
var e End
if json.Unmarshal(raw, &e) == nil {
out[k] = e
@@ -366,56 +342,6 @@ func writtenTools(st store) []stdio.Tool {
}}}
}
// branchesOf is the watched branches the placements of module chose, each once; the default branch when none names one.
func (e *pipelineEnds) branchesOf(module string, placed map[string]map[string]string) []string {
if !e.following() {
return nil
}
seen := map[string]bool{}
var out []string
for _, b := range placed[module] {
b = e.branchOf(module, b)
if !seen[b] {
seen[b] = true
out = append(out, b)
}
}
if len(out) == 0 {
out = append(out, e.branchOf(module, ""))
}
sort.Strings(out)
return out
}
// mayWant says whether module's wants may name fp: a pipeline passed at fp on every branch, or the wants name fp already
// (a node placed later, a module taken away).
func (e *pipelineEnds) mayWant(module, fp string, branches []string, wanted map[string]mwc.Want) bool {
if !e.following() {
return true
}
for _, w := range wanted {
if w.Fp == fp {
return true
}
}
for _, b := range branches {
if !e.passedAt(module, b, fp) {
return false
}
}
return true
}
// wrote marks the end the wants of module were written from.
func (e *pipelineEnds) wrote(module, fp string, branches []string) {
if !e.following() {
return
}
for _, b := range branches {
e.markWritten(module, b, fp)
}
}
// following says whether the wants follow the pipeline ends yet; a nil follower never does.
func (e *pipelineEnds) following() bool { return e != nil && e.on.Load() }
@@ -437,7 +363,7 @@ func (e *pipelineEnds) registered(reg mpcat.Registration, gone bool) {
prefix := keys.EscapeName(reg.Module) + "."
for _, k := range kept {
rest, ok := strings.CutPrefix(k, prefix)
if !ok {
if !ok || isTierKey(k) || strings.HasPrefix(k, whyPrefix) {
continue
}
branch, err := keys.UnescapeName(rest)
@@ -456,32 +382,3 @@ func (e *pipelineEnds) registered(reg mpcat.Registration, gone bool) {
}
e.wake()
}
// followRegistrations follows the registrations through the seat mesh-catalog (design 47 G §353): a first view of its verb
// and each registration-changed on the hub. It returns when the hub's handler is registered; the first view is asked on its own
// goroutine, the wants keep the trunk-only form until a registration is heard.
func followRegistrations(ctx context.Context, hub *process.EventHub, call mcc.Call, e *pipelineEnds) error {
regs := mcc.NewRegistrations(call)
regs.Follower.Logf = e.logf
regs.Follower.Changed = func(module string, value json.RawMessage, gone bool, _ time.Time) {
reg := mpcat.Registration{Module: module}
if !gone {
_ = json.Unmarshal(value, &reg)
}
e.registered(reg, gone)
}
if err := hub.Handle(mpcat.SubjectRegistrationChanged, func(m jetstream.Msg) {
if err := regs.Hear(ctx, m.Data()); err != nil {
e.logf("%s: %v", m.Subject(), err)
}
_ = m.Ack()
}); err != nil {
return err
}
go func() {
if err := regs.Start(ctx); err != nil && ctx.Err() == nil {
e.logf("the first view of the registrations is not answered: %v", err)
}
}()
return nil
}
@@ -4,34 +4,24 @@ import (
"context"
"encoding/json"
"fmt"
mmac "git.novox.be/novox/mesh-contracts/go/clients/meshmoduleassignerclient"
mma "git.novox.be/novox/mesh-contracts/go/seats/meshmoduleassigner"
plc "mesh-delivery-assigner/internal/assignment"
"slices"
"strings"
"testing"
"time"
mmac "git.novox.be/novox/mesh-contracts/go/clients/meshmoduleassignerclient"
mma "git.novox.be/novox/mesh-contracts/go/seats/meshmoduleassigner"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
mwc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
mpcat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
mpr "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"github.com/nats-io/nats.go/jetstream"
"git.novox.be/novox/mesh-delivery/modules/mesh-grants/grantsstate"
"git.novox.be/novox/mesh-contracts/go/clients/nodeengineclient"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
"mesh-delivery-assigner/internal/assigngraph"
plc "mesh-delivery-assigner/internal/assignment"
"mesh-delivery-assigner/internal/buckets"
mws "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
)
// memEnds is endStore over a map, with revisions.
@@ -71,239 +61,163 @@ func (m *heardMsg) Subject() string { return m.subject }
func (m *heardMsg) Ack() error { m.acked = true; return nil }
func (m *heardMsg) Nak() error { m.naked = true; return nil }
func pipe(module, branch string, source, count int64, fp, outcome string, steps ...mpr.StepResult) mpr.PipelineEnded {
return mpr.PipelineEnded{Module: module, Branch: branch, Source: source, EndCount: count, Fingerprint: fp, Outcome: outcome, Steps: steps,
Pipeline: branch + "." + module, Commit: "c"}
// mover is one mover at its pipeline's end, its required unit step ending outcome.
func mover(module, fp, version string, tier int64, outcome string) mpr.MoverEnded {
return mpr.MoverEnded{Module: module, Fingerprint: fp, Version: version, Tier: tier,
Steps: []mpr.StepResult{{Step: "unit", Status: mpr.StepResultStatusRequired, Outcome: outcome, Module: module}}}
}
func step(status, outcome string) mpr.StepResult {
return mpr.StepResult{Step: "unit", Status: status, Outcome: outcome}
// ended is the pipeline-ended of the take-in of source on branch, its movers given.
func ended(branch string, source int64, outcome string, movers ...mpr.MoverEnded) mpr.PipelineEnded {
return mpr.PipelineEnded{V: 1, Branch: branch, Source: source, EndCount: 1, Outcome: outcome, Movers: movers,
Pipeline: fmt.Sprintf("%s.%d", branch, source)}
}
// Design 47 G §29, §35, §325, §352 (tests 66, 67, 89): a want follows a passed pipeline, by compare-and-set per module and branch.
func TestAWantFollowsAPassedPipeline(t *testing.T) {
const fp1, fp2 = "fp1", "fp2"
// A6/AC1 to AC3 (design 47 H §750, H-A-3): a passed pipeline keeps each mover's released version as the newest of its module on
// the branch, with the pipeline and the mover's tier; a failed pipeline, a mover whose required step failed, one that released
// no version, an older version, the same one again and a run on request keep nothing.
func TestThePassedVersionIsKept(t *testing.T) {
pass, fail := mpr.PipelineEndedOutcomePassed, mpr.PipelineEndedOutcomeFailed
req, opt := mpr.StepResultStatusRequired, mpr.StepResultStatusOptional
ok, failed, nothing := mpr.StepResultOutcomePassed, mpr.StepResultOutcomeFailed, mpr.StepResultOutcomeNothingToRun
for _, c := range []struct {
name string
ends []mpr.PipelineEnded
group *mpr.GroupEnded
module string
branch string
fp string
may bool
name string
ends []mpr.PipelineEnded
want *End // nil: none kept for web on main
}{
{"a failed required step writes no want", []mpr.PipelineEnded{pipe("web", "main", 5, 1, fp1, fail, step(req, "failed"))}, nil, "web", "main", fp1, false},
{"a pipeline passed writes", []mpr.PipelineEnded{pipe("web", "main", 5, 1, fp1, pass, step(req, "passed"))}, nil, "web", "main", fp1, true},
{"a failed optional step holds nothing", []mpr.PipelineEnded{pipe("web", "main", 5, 1, fp1, pass, step(req, "passed"), step(opt, "failed"))}, nil, "web", "main", fp1, true},
{"a pipeline passed at another fingerprint", []mpr.PipelineEnded{pipe("web", "main", 5, 1, fp1, pass)}, nil, "web", "main", fp2, false},
{"an older revision ending after a newer one writes nothing", []mpr.PipelineEnded{pipe("web", "main", 6, 1, fp2, fail), pipe("web", "main", 5, 1, fp1, pass)}, nil, "web", "main", fp1, false},
{"another branch writes its own", []mpr.PipelineEnded{pipe("web", "main", 6, 1, fp2, fail), pipe("web", "beta", 5, 1, fp1, pass)}, nil, "web", "beta", fp1, true},
{"a later end of the same revision writes", []mpr.PipelineEnded{pipe("web", "main", 5, 1, fp1, fail, step(req, "failed")), pipe("web", "main", 5, 2, fp1, pass, step(req, "passed"))}, nil, "web", "main", fp1, true},
{"the same end again after a later one keeps the later", []mpr.PipelineEnded{pipe("web", "main", 5, 2, fp1, pass), pipe("web", "main", 5, 1, fp1, fail)}, nil, "web", "main", fp1, true},
{"a member's own end writes nothing", []mpr.PipelineEnded{func() mpr.PipelineEnded { p := pipe("web", "main", 5, 1, fp1, pass); p.Group = "g"; return p }()}, nil, "web", "main", fp1, false},
{"a group ended passed writes its members", nil, &mpr.GroupEnded{Branch: "main", Group: "g", Outcome: mpr.GroupEndedOutcomePassed, Pipelines: []mpr.PipelineEnded{pipe("web", "main", 5, 1, fp1, pass)}}, "web", "main", fp1, true},
{"a group ended failed writes none", nil, &mpr.GroupEnded{Branch: "main", Group: "g", Outcome: mpr.GroupEndedOutcomeFailed, Pipelines: []mpr.PipelineEnded{pipe("web", "main", 5, 1, fp1, pass)}}, "web", "main", fp1, false},
{"a passed pipeline keeps its version", []mpr.PipelineEnded{ended("main", 5, pass, mover("web", "fp1", "0.1.2", 2, ok))},
&End{Pipeline: "main.5", Source: 5, Fp: "fp1", Version: "0.1.2", Rank: 2}},
{"nothing to run counts as passed", []mpr.PipelineEnded{ended("main", 5, pass, mover("web", "fp1", "0.1.2", 1, nothing))},
&End{Pipeline: "main.5", Source: 5, Fp: "fp1", Version: "0.1.2", Rank: 1}},
{"a failed pipeline keeps nothing, a passed mover in it neither", []mpr.PipelineEnded{ended("main", 5, fail, mover("web", "fp1", "0.1.2", 1, ok),
mover("db", "fp9", "0.3.0", 1, failed))}, nil},
{"a mover whose required step failed keeps nothing", []mpr.PipelineEnded{ended("main", 5, pass, mover("web", "fp1", "0.1.2", 1, failed))}, nil},
{"no version released keeps nothing", []mpr.PipelineEnded{ended("main", 5, pass, mover("web", "fp1", "", 1, ok))}, nil},
{"an older end heard after a newer one keeps the newer", []mpr.PipelineEnded{ended("main", 6, pass, mover("web", "fp2", "0.1.3", 1, ok)),
ended("main", 5, pass, mover("web", "fp1", "0.1.2", 1, ok))}, &End{Pipeline: "main.6", Source: 6, Fp: "fp2", Version: "0.1.3", Rank: 1}},
{"a newer version replaces", []mpr.PipelineEnded{ended("main", 5, pass, mover("web", "fp1", "0.1.2", 1, ok)),
ended("main", 6, pass, mover("web", "fp2", "0.1.10", 1, ok))}, &End{Pipeline: "main.6", Source: 6, Fp: "fp2", Version: "0.1.10", Rank: 1}},
{"a run on request keeps nothing", []mpr.PipelineEnded{func() mpr.PipelineEnded {
p := ended("main", 5, pass, mover("web", "fp1", "0.1.2", 1, ok))
p.Run = "r1"
return p
}()}, nil},
} {
woken := 0
e := newPipelineEnds(newMemEnds(), func() { woken++ }, t.Logf)
e.on.Store(true)
e := newPipelineEnds(newMemEnds(), func() {}, t.Logf)
for _, p := range c.ends {
if p.Group != "" {
continue // heard and ignored, as hearPipeline does
}
if err := e.take(p, requiredPassed(p)); err != nil {
t.Fatal(err)
if _, err := e.take(p); err != nil {
t.Fatalf("%s: %v", c.name, err)
}
}
if g := c.group; g != nil {
for _, p := range g.Pipelines {
if err := e.take(p, g.Outcome == mpr.GroupEndedOutcomePassed && requiredPassed(p)); err != nil {
t.Fatal(err)
}
}
}
if got := e.mayWant(c.module, c.fp, []string{c.branch}, nil); got != c.may {
t.Errorf("%s: may want = %v, want %v", c.name, got, c.may)
got, kept := e.endOf("web", "main")
switch {
case c.want == nil && kept:
t.Errorf("%s: kept %+v", c.name, got)
case c.want != nil && (!kept || got != *c.want):
t.Errorf("%s: kept %+v (%v), want %+v", c.name, got, kept, *c.want)
}
}
// A run on request's group-ended (group run-<id>, A-235) writes no want and drops the run's candidate; a drop that fails is
// heard again.
{
e := newPipelineEnds(newMemEnds(), func() {}, t.Logf)
e.on.Store(true)
var dropped []string
fail := false
e.runEnded = func(group string) error {
dropped = append(dropped, group)
if fail {
return fmt.Errorf("the bucket is not open")
}
return nil
}
raw, _ := json.Marshal(mpr.GroupEnded{V: 1, Branch: "main", Group: "run-7", Outcome: mpr.GroupEndedOutcomePassed,
Pipelines: []mpr.PipelineEnded{func() mpr.PipelineEnded { p := pipe("web", "main", 5, 1, fp1, pass); p.Run = "7"; return p }()}})
m := &heardMsg{data: raw, subject: "mesh.seat.mesh-pipeline-runner.event.group-ended.x"}
e.hearGroup(m)
if e.mayWant("web", fp1, []string{"main"}, nil) || !slices.Equal(dropped, []string{"run-7"}) || !m.acked {
t.Errorf("a run's group-ended: may want %v, dropped %v, acked %v; want no want, run-7 dropped, acked",
e.mayWant("web", fp1, []string{"main"}, nil), dropped, m.acked)
}
fail = true
m = &heardMsg{data: raw, subject: m.subject}
e.hearGroup(m)
if !m.naked {
t.Error("a run's candidate not dropped is not heard again")
// The same end heard again changes nothing and wakes nothing; a run on request's end drops its candidate.
woken := 0
e := newPipelineEnds(newMemEnds(), func() { woken++ }, t.Logf)
var dropped []string
e.runEnded = func(group string) error { dropped = append(dropped, group); return nil }
p := ended("main", 5, pass, mover("web", "fp1", "0.1.2", 1, ok))
for range 2 {
raw, _ := json.Marshal(p)
m := &heardMsg{data: raw, subject: "mesh.seat.mesh-pipeline-runner.event.pipeline-ended.main.5"}
e.hearPipeline(m)
if !m.acked {
t.Error("the end was not acknowledged")
}
}
// A-334 (§29, §65, §268): in a group take-in that changes the runner, the runner's member (the holder of the seat
// mesh-pipeline-runner, read from the acting edges) is wanted on its own pipeline-ended once it passed, ahead of the group;
// the other members wait for group-ended.
{
e := newPipelineEnds(newMemEnds(), func() {}, t.Logf)
e.on.Store(true)
heard := func(p mpr.PipelineEnded) *heardMsg {
p.Group = "g"
raw, _ := json.Marshal(p)
m := &heardMsg{data: raw, subject: "mesh.seat.mesh-pipeline-runner.event.pipeline-ended.x"}
e.hearPipeline(m)
return m
}
hear := func(p mpr.PipelineEnded) {
if m := heard(p); !m.acked {
t.Errorf("the pipeline-ended of %s is not acknowledged", p.Module)
}
}
// The runner's end heard before a pass read the graph is held, unacknowledged, and taken once the runner is read.
early := heard(pipe("runner", "main", 5, 1, "fp-runner", pass, step(req, "passed")))
if early.acked || early.naked || e.mayWant("runner", "fp-runner", []string{"main"}, nil) {
t.Fatalf("the runner's end before the graph is read: acked %v, naked %v, wanted %v; want it held", early.acked, early.naked,
e.mayWant("runner", "fp-runner", []string{"main"}, nil))
}
e.setRunner(assigngraph.Runner([]mws.AssignmentEntry{{Node: "ace", Module: "web", Edges: []mws.Edge{
{Kind: assigngraph.EdgeActing, Node: "ace", Module: "runner", Seat: mpr.Seat, Step: "pipeline"}}}}))
if !early.acked {
t.Error("the runner's end held until the graph was read is not taken once it is")
}
hear(pipe("web", "main", 5, 1, fp1, pass, step(req, "passed")))
if !e.mayWant("runner", "fp-runner", []string{"main"}, nil) || e.mayWant("web", fp1, []string{"main"}, nil) {
t.Errorf("a group changing the runner: may want the runner %v, web %v; want the runner ahead of the group and web not yet",
e.mayWant("runner", "fp-runner", []string{"main"}, nil), e.mayWant("web", fp1, []string{"main"}, nil))
}
hear(pipe("runner", "main", 6, 1, "fp-runner-2", fail, step(req, "failed")))
if e.mayWant("runner", "fp-runner-2", []string{"main"}, nil) {
t.Error("the runner's member that failed is wanted")
}
}
// A want that names the fingerprint already is not held by a later failure (a node placed afterwards gets it).
e := newPipelineEnds(newMemEnds(), func() {}, t.Logf)
e.on.Store(true)
if !e.mayWant("web", fp1, []string{"main"}, map[string]mwc.Want{"g14": {Fp: fp1}}) {
t.Error("a want naming the fingerprint was held")
}
// markWritten keeps the end and says it was written from; a newer end replaces it unwritten.
st := newMemEnds()
e = newPipelineEnds(st, func() {}, t.Logf)
e.on.Store(true)
_ = e.take(pipe("web", "main", 5, 1, fp1, pass), true)
e.wrote("web", fp1, []string{"main"})
var end End
_ = json.Unmarshal(st.vals[endKey("web", "main")], &end)
if !end.Written || end.Source != 5 {
t.Errorf("end = %+v, want written at source 5", end)
}
_ = e.take(pipe("web", "main", 6, 1, fp2, pass), true)
end = End{}
_ = json.Unmarshal(st.vals[endKey("web", "main")], &end)
if end.Written || end.Source != 6 {
t.Errorf("a newer end = %+v, want unwritten at source 6", end)
run := p
run.Run = "r1"
raw, _ := json.Marshal(run)
e.hearPipeline(&heardMsg{data: raw, subject: "mesh.seat.mesh-pipeline-runner.event.pipeline-ended.main.5"})
if woken != 1 || !slices.Equal(dropped, []string{runGroupPrefix + "r1"}) {
t.Errorf("woken %d (want 1), dropped %v (want the run's candidate)", woken, dropped)
}
}
// Design 47 G §29: the wants of a pass follow a pipeline: with the follower on, a module whose fingerprint no pipeline passed at
// gets no want and one a pipeline passed at gets it; with it off (nil, the trunk-only want) the pass is as before.
func TestAPassWritesNoWantWithoutAPassedPipeline(t *testing.T) {
// A6/AC1, A5/AC1 (design 47 H §750): a pass writes, on every node the module is assigned to, the want naming the newest version
// released on its branch whose pipeline passed, with the pipeline and the rank; with none passed it writes none. No grant,
// canary, provider or composition is asked for. H-A-270 (1): a passed end whose mover names no version yet writes no want and
// says so in the journal; the same end said again naming the version writes it.
func TestAPassWritesTheWantOfThePassedVersion(t *testing.T) {
fp := meshcatalogclient.SourcePrefix2 + strings.Repeat("a", 64)
for _, c := range []struct {
name string
follow bool
passed bool
want bool
}{{"the trunk-only want", false, false, true}, {"no pipeline passed", true, false, false}, {"a pipeline passed", true, true, true}} {
for _, passed := range []bool{false, true} {
wantsKV := &memKV{values: map[string][]byte{}}
p := newPasser(kvSet{buckets.Wants(): wantsKV, buckets.Asks(): &memKV{values: map[string][]byte{}}}, time.Now())
p.say = func(oc.Condition) error { return nil }
mdigest := strings.Repeat("e", 64)
mod, _ := meshcatalogclient.EncodeModule(meshcatalog.ModulesByModuleValue{Fp2: fp, Manifest: mdigest, Repository: "novox/web", Commit: strings.Repeat("1", 40), Path: meshcatalogclient.RootPath})
putModuleRaw(p.w, trunkBranch, "web", mod)
p.w.manifests[mdigest] = parsed{module: "web", manifest: catalogue.Manifest{Module: "web"}}
endDone(t, p.w, "web", fp, mdigest)
gkey, _ := grantsstate.PartGrantKey("web", fp)
grant, _ := grantsstate.EncodeGrant(grantsstate.Grant{})
p.w.put(buckets.Grants, gkey, grant)
digest := "sha256:" + strings.Repeat("c", 64)
have, _ := nodeengineclient.EncodeHave(nodeengine.HaveByNodeModuleValue{Fp: fp, Composed: digest, Phase: nodeengineclient.PhaseRunning, Health: nodeengineclient.HealthOK})
p.w.put(buckets.Have, "g14.web", have)
composes(t, p.w, "g14", digest)
p.w.manifests[mdigest] = parsed{module: "web", manifest: catalogue.Manifest{Module: "web", Requires: []string{"database"}}}
placeOn(t, p.w, "g14", "web")
on := true
p.w.heardPresence("g14", !on, time.Now())
if c.follow {
p.ends = newPipelineEnds(newMemEnds(), func() {}, t.Logf)
p.ends.trunk = p.w.trunkName
p.ends.on.Store(true)
if c.passed {
_ = p.ends.take(pipe("web", trunkBranch, 5, 1, fp, mpr.PipelineEndedOutcomePassed), true)
placeOn(t, p.w, "ace", "web")
var journal []string
p.ends = newPipelineEnds(newMemEnds(), func() {}, func(f string, a ...any) { journal = append(journal, fmt.Sprintf(f, a...)) })
p.ends.trunk = p.w.trunkName
if passed {
_, _ = p.ends.take(ended(trunkBranch, 5, mpr.PipelineEndedOutcomePassed, mover("web", fp, "", 2, mpr.StepResultOutcomePassed)))
p.wants(context.Background())
if len(wantsKV.values) != 0 || !slices.Contains(journal, trunkBranch+".5: web passed with no version yet: taken again when its version is written") {
t.Errorf("an end naming no version wrote %d wants and said %q", len(wantsKV.values), journal)
}
_, _ = p.ends.take(ended(trunkBranch, 5, mpr.PipelineEndedOutcomePassed, mover("web", fp, "0.1.2", 2, mpr.StepResultOutcomePassed)))
}
p.wants(context.Background())
key, _ := mwc.WantKey("g14", "web")
if _, got := wantsKV.values[key]; got != c.want {
t.Errorf("%s: a want written = %v, want %v", c.name, got, c.want)
}
if c.follow && c.passed {
raw, _, _ := p.ends.st.get(endKey("web", trunkBranch))
var end End
_ = json.Unmarshal(raw, &end)
if !end.Written {
t.Errorf("%s: the end was not marked written", c.name)
for _, node := range []string{"g14", "ace"} {
key, _ := mwc.WantKey(node, "web")
raw, got := wantsKV.values[key]
if got != passed {
t.Errorf("passed %v: a want on %s written = %v", passed, node, got)
continue
}
if !passed {
continue
}
if w, err := mwc.DecodeWant(raw); err != nil || w.Fp != fp || w.Version != "0.1.2" || w.Pipeline != trunkBranch+".5" || w.Rank != 2 {
t.Errorf("the want on %s = %+v (%v)", node, w, err)
}
}
}
}
// Design 47 G §95, §130, §353, §352 (test 100): the wants keep the trunk-only form until the first registration is heard and
// switch on it; a branch a registration no longer watches loses its end, and its first branch is a placement's default.
func TestTheWantsSwitchOnTheFirstRegistration(t *testing.T) {
// Design 47 G §353, §352: a registration's first branch is a placement's default, and a branch it no longer watches loses its
// end; a registration gone loses them all.
func TestARegistrationNamesTheDefaultBranch(t *testing.T) {
st := newMemEnds()
woken := 0
e := newPipelineEnds(st, func() { woken++ }, t.Logf)
e.trunk = func() string { return trunkBranch }
_ = e.take(pipe("web", "main", 5, 1, "fp1", mpr.PipelineEndedOutcomeFailed), false)
_ = e.take(pipe("web", "beta", 5, 1, "fp1", mpr.PipelineEndedOutcomePassed), true)
if e.following() || !e.mayWant("web", "fp1", []string{"main"}, nil) {
t.Fatal("the follower held a want before any registration")
}
pass := mpr.PipelineEndedOutcomePassed
_, _ = e.take(ended("main", 5, pass, mover("web", "fp1", "0.1.1", 1, mpr.StepResultOutcomePassed)))
_, _ = e.take(ended("beta", 5, pass, mover("web", "fp2", "0.1.2", 1, mpr.StepResultOutcomePassed)))
e.registered(mpcat.Registration{Module: "web", Branches: []string{"beta"}}, false)
if !e.following() || woken == 0 {
t.Error("the first registration did not switch the wants on")
endsKept := func() (n int) { // a pipeline's tier progress is not a module's end
for k := range st.vals {
if !isTierKey(k) {
n++
}
}
return n
}
if e.mayWant("web", "fp1", []string{"main"}, nil) || !e.mayWant("web", "fp1", []string{"beta"}, nil) {
t.Error("after the switch the wants did not follow the ends")
if woken == 0 || endsKept() != 1 || e.branchOf("web", "") != "beta" || e.branchOf("other", "") != trunkBranch {
t.Errorf("ends kept %d, default branch %q: an unwatched branch's end stayed, or the default is wrong", endsKept(), e.branchOf("web", ""))
}
if len(st.vals) != 1 || e.branchOf("web", "") != "beta" || e.branchOf("other", "") != trunkBranch {
t.Errorf("ends kept %d, default branch %q: an unwatched branch's end stayed, or the default is wrong", len(st.vals), e.branchOf("web", ""))
if tg, ok := e.target("web", ""); !ok || tg.Fp != "fp2" {
t.Errorf("the default branch's target = %+v %v", tg, ok)
}
e.registered(mpcat.Registration{Module: "web"}, true)
if len(st.vals) != 0 {
t.Errorf("a registration gone left %d ends", len(st.vals))
if endsKept() != 0 {
t.Errorf("a registration gone left %d ends", endsKept())
}
}
// Design 47 G §14, §184 (test 68): a node's entry is computed from the catalog half of the branch its placement names, so a
// change on `beta` moves only the want of the node whose placement chose `beta`.
func TestACommitOnBetaMovesOnlyTheNodeThatChoseBeta(t *testing.T) {
// Design 47 G §14, §184 (test 68): a node's want follows the branch its placement names, so a version passed on `beta` moves only
// the want of the node whose placement chose `beta`.
func TestAVersionOnBetaMovesOnlyTheNodeThatChoseBeta(t *testing.T) {
fp := func(c string) string { return meshcatalogclient.SourcePrefix2 + strings.Repeat(c, 64) }
wantsKV := &memKV{values: map[string][]byte{}}
p := newPasser(kvSet{buckets.Wants(): wantsKV, buckets.Asks(): &memKV{values: map[string][]byte{}}}, time.Now())
@@ -311,15 +225,8 @@ func TestACommitOnBetaMovesOnlyTheNodeThatChoseBeta(t *testing.T) {
p.ends = newPipelineEnds(newMemEnds(), func() {}, t.Logf)
p.ends.trunk = p.w.trunkName
p.ends.registered(mpcat.Registration{Module: "web", Branches: []string{"main", "beta"}}, false)
digest := "sha256:" + strings.Repeat("c", 64)
on := true
for _, node := range []string{"g14", "ace"} {
composes(t, p.w, node, digest)
p.w.heardPresence(node, !on, time.Now())
}
for node, branch := range map[string]string{"g14": "", "ace": "beta"} {
pl := mma.Assignments{Node: node, Modules: []mma.PlacedModule{{Module: "web", Branch: branch}}}
values, err := mmac.AssignmentsValues(pl)
values, err := mmac.AssignmentsValues(mma.Assignments{Node: node, Modules: []mma.PlacedModule{{Module: "web", Branch: branch}}})
if err != nil {
t.Fatal(err)
}
@@ -327,24 +234,10 @@ func TestACommitOnBetaMovesOnlyTheNodeThatChoseBeta(t *testing.T) {
p.w.put(plc.AssignmentsBucket(), key, raw)
}
}
// publish makes the half of branch name web at fingerprint f: built, granted and passed by its pipeline.
publish := func(branch, f string, source int64) {
mdigest := strings.Repeat("e", 62) + fmt.Sprintf("%02d", source)
if branch == "beta" {
mdigest = strings.Repeat("f", 62) + fmt.Sprintf("%02d", source)
}
mod, _ := meshcatalogclient.EncodeModule(meshcatalog.ModulesByModuleValue{Fp2: f, Manifest: mdigest, Repository: "novox/web", Commit: strings.Repeat("1", 40), Path: meshcatalogclient.RootPath})
putModuleRaw(p.w, branch, "web", mod)
p.w.manifests[mdigest] = parsed{module: "web", manifest: catalogue.Manifest{Module: "web"}}
endDone(t, p.w, "web", f, mdigest)
gkey, _ := grantsstate.PartGrantKey("web", f)
grant, _ := grantsstate.EncodeGrant(grantsstate.Grant{})
p.w.put(buckets.Grants, gkey, grant)
_ = p.ends.take(pipe("web", branch, source, 1, f, mpr.PipelineEndedOutcomePassed), true)
}
run := func(node, f string) {
have, _ := nodeengineclient.EncodeHave(nodeengine.HaveByNodeModuleValue{Fp: f, Composed: digest, Phase: nodeengineclient.PhaseRunning, Health: nodeengineclient.HealthOK})
p.w.put(buckets.Have, node+".web", have)
mod, _ := meshcatalogclient.EncodeModule(meshcatalog.ModulesByModuleValue{Fp2: fp("a"), Manifest: strings.Repeat("e", 64), Repository: "novox/web", Commit: strings.Repeat("1", 40), Path: meshcatalogclient.RootPath})
putModuleRaw(p.w, "main", "web", mod)
passed := func(branch, f, version string, source int64) {
_, _ = p.ends.take(ended(branch, source, mpr.PipelineEndedOutcomePassed, mover("web", f, version, 1, mpr.StepResultOutcomePassed)))
}
fpWant := func(node string) string {
key, _ := mwc.WantKey(node, "web")
@@ -354,18 +247,16 @@ func TestACommitOnBetaMovesOnlyTheNodeThatChoseBeta(t *testing.T) {
}
return w.Fp
}
publish("main", fp("a"), 5)
publish("beta", fp("b"), 5)
run("g14", fp("a"))
run("ace", fp("b"))
passed("main", fp("a"), "0.1.1", 5)
passed("beta", fp("b"), "0.2.1", 5)
p.wants(context.Background())
if fpWant("g14") != fp("a") || fpWant("ace") != fp("b") {
t.Fatalf("each node is wanted at its branch's build: g14 %s, ace %s", fpWant("g14"), fpWant("ace"))
}
publish("beta", fp("d"), 6)
passed("beta", fp("d"), "0.2.2", 6)
p.wants(context.Background())
if fpWant("g14") != fp("a") || fpWant("ace") != fp("d") {
t.Errorf("a commit on beta moves only ace: g14 %s (want main's), ace %s (want beta's new)", fpWant("g14"), fpWant("ace"))
t.Errorf("a version on beta moves only ace: g14 %s (want main's), ace %s (want beta's new)", fpWant("g14"), fpWant("ace"))
}
}
@@ -1,95 +0,0 @@
package main
import (
"context"
"fmt"
"sort"
"mesh-delivery-assigner/internal/buckets"
"mesh-delivery-assigner/internal/puts"
)
// placementBy is who a put the placement's build makes names as its asker: the placement, whose proposal the operator
// approved, is the warrant (design 47 *Going back is one act*; ADR 0666 §24).
const placementBy = "the placement"
// placementPuts makes each placed module's `build` a held put of that build, and releases a put the placement made once its
// placement names that build no more (design 47 line 912: "a return to an earlier build is one value in the placement, the
// module's `build` in its placement key, set by a placement proposal"; ADR 0666 §24; B-K1). The put then goes its own steps
// (the builder's build, the composition, an ask where the module's policy needs one, the want, holding) and is read with
// `assigner_puts` and released with `assigner_release` like any other; a placement's build the builder never built is refused
// by its build step, said in the put's words. A put asked by a person stands until the placement names another build.
func (p *passer) placementPuts(ctx context.Context) {
kv := p.kvs[buckets.Puts()]
if kv == nil {
return
}
now := p.clock().UTC()
named := map[string]string{} // put key -> the build its placement names
for node, a := range p.w.assignments() {
for _, m := range a.Modules {
if m.Build == "" {
continue
}
if key, err := puts.Key(node, m.Module); err == nil {
named[key] = m.Build
}
}
}
held := p.w.read(buckets.Puts())
keys := make([]string, 0, len(named)+len(held))
for k := range named {
keys = append(keys, k)
}
for k := range held {
if _, there := named[k]; !there {
keys = append(keys, k)
}
}
sort.Strings(keys)
for _, key := range keys {
build, names := named[key]
var before *puts.Put
if raw, ok := held[key]; ok {
if got, err := puts.Decode(raw); err == nil {
before = &got
}
}
var next puts.Put
switch {
case names && before != nil && before.FP == build:
continue // made already, or a person's put of the same build: it goes its own steps, ended or not
case names:
words := fmt.Sprintf("asked by %s: it names build %s of %s", placementBy, shortFP(build), key)
if before != nil && !puts.Ended(before.Step) {
words += fmt.Sprintf("; it replaces the put of %s, which stood at %s", shortFP(before.FP), before.Step)
}
next = puts.Put{FP: build, Hold: true, Why: "the placement names this build (ADR 0666 §24)", By: placementBy, At: now}.Said(now, puts.Asked, words)
case before != nil && before.By == placementBy && !puts.Ended(before.Step):
next = before.Said(now, puts.Released, fmt.Sprintf("released by %s: it names no build of its own any more; the assigner's rules write the want again", placementBy))
default:
continue
}
data, err := puts.Encode(next)
if err != nil {
p.logf("the placement's put %s is not written: %v", key, err)
continue
}
if before == nil {
_, err = kv.Create(ctx, key, data)
} else if e, gerr := kv.Get(ctx, key); gerr != nil {
err = gerr
} else {
_, err = kv.Update(ctx, key, data, e.Revision())
}
if err != nil {
p.logf("the placement's put %s could not be written, and is written at the next pass: %v", key, err)
continue
}
p.w.put(buckets.Puts(), key, data)
p.logf("put %s: %s: %s", key, next.Step, next.Words)
if p.acts != nil {
p.acts.say(key, next)
}
}
}
@@ -0,0 +1,204 @@
package main
import (
"context"
"encoding/json"
"fmt"
mpr "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
"strings"
"testing"
"time"
mmac "git.novox.be/novox/mesh-contracts/go/clients/meshmoduleassignerclient"
"git.novox.be/novox/mesh-contracts/go/clients/nodeengineclient"
"git.novox.be/novox/mesh-contracts/go/seats/meshbroker"
mma "git.novox.be/novox/mesh-contracts/go/seats/meshmoduleassigner"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
mwc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-grants/grantsstate"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"mesh-delivery-assigner/internal/assigngraph"
plc "mesh-delivery-assigner/internal/assignment"
"mesh-delivery-assigner/internal/buckets"
)
// orderFP is a fingerprint of the form the trunk keeps, made of one letter.
func orderFP(c string) string {
return meshcatalogclient.SourcePrefix2 + strings.Repeat(fmt.Sprintf("%x", c[0]&15), 64)
}
// orderMod is one module of an order test: the fingerprint it runs on ace and the one the trunk holds, the form of its kept data at each
// fingerprint (0: it keeps none), the seats it holds and the source revision of its trunk value.
type orderMod struct {
name string
run, trunk string
forms map[string]int
holds []string
}
type orderFixture struct {
t *testing.T
p *passer
wants *memKV
events []string
bodies []meshwants.Wait
answers chan struct{}
}
// newOrderFixture is a pass on node ace, which composes its own modules, with each module running its fingerprint healthy, built and
// granted at the trunk's, an older want, the catalog's entries answered and each held seat as the assignments say it. history lists the
// fingerprints of each module by assignment graph revision, oldest first (the objects Reverted reads).
func newOrderFixture(t *testing.T, mods []orderMod, history ...map[string]string) *orderFixture {
t.Helper()
ctx := context.Background()
f := &orderFixture{t: t, wants: &memKV{values: map[string][]byte{}}, answers: make(chan struct{}, 64)}
f.p = newPasser(kvSet{buckets.Wants(): f.wants, buckets.Asks(): &memKV{values: map[string][]byte{}}, buckets.Waits(): &memKV{values: map[string][]byte{}}}, time.Now())
p := f.p
p.logf = t.Logf
p.say = func(oc.Condition) error { return nil }
p.publishWants = func(event string, body any, id string) error {
f.events = append(f.events, event)
f.bodies = append(f.bodies, body.(meshwants.Wait))
return nil
}
digest := "sha256:" + strings.Repeat("c", 64)
p.ends = newPipelineEnds(newMemEnds(), func() {}, t.Logf)
p.ends.trunk = p.w.trunkName
pl := mma.Assignments{Node: "ace"}
forms := map[string]int{} // by fingerprint: each module's own
modules := []string{}
for _, m := range mods {
modules = append(modules, m.name)
pl.Modules = append(pl.Modules, mma.PlacedModule{Module: m.name})
for _, seat := range m.holds {
scope := "node"
if seat != catalogue.BackupSeat && seat != nodeengine.Seat {
scope = "mesh"
}
pl.Holds = append(pl.Holds, mma.Holding{Claim: seat, Module: m.name, Scope: scope})
}
for fp, form := range m.forms {
forms[fp] = form
}
mdigest := fmt.Sprintf("%064x", len(modules))
mod, _ := meshcatalogclient.EncodeModule(meshcatalog.ModulesByModuleValue{Fp2: m.trunk, Manifest: mdigest, Repository: "novox/" + m.name, Commit: strings.Repeat("1", 40), Path: meshcatalogclient.RootPath})
putModuleRaw(p.w, trunkBranch, m.name, mod)
p.w.manifests[mdigest] = parsed{module: m.name, manifest: catalogue.Manifest{Module: m.name}}
endDone(t, p.w, m.name, m.trunk, mdigest)
gkey, _ := grantsstate.PartGrantKey(m.name, m.trunk)
grant, _ := grantsstate.EncodeGrant(grantsstate.Grant{})
p.w.put(buckets.Grants, gkey, grant)
f.runs(m.name, m.run)
// The trunk's build is released with a passed pipeline (design 47 H §750).
_, _ = p.ends.take(ended(trunkBranch, 1, mpr.PipelineEndedOutcomePassed, mover(m.name, m.trunk, "0.1.1", 1, mpr.StepResultOutcomePassed)))
wkey, _ := mwc.WantKey("ace", m.name)
old, _ := mwc.EncodeWant(mwc.Want{Fp: m.run, Self: true})
p.w.put(buckets.Wants(), wkey, old)
f.wants.values[wkey] = old
}
composes(t, p.w, "ace", digest)
values, err := mmac.AssignmentsValues(pl)
if err != nil {
t.Fatal(err)
}
for key, raw := range values {
p.w.put(plc.AssignmentsBucket(), key, raw)
}
p.w.heardPresence("ace", false, time.Now()) // ace is online: its last presence event heard is machine-back
objects := memObjects{}
for i, at := range history {
half := meshcatalogclient.Half{Revision: meshcatalog.CatalogRevision{Branch: trunkBranch, Kind: "trunk", Revision: int64(i + 1), Source: int64(i + 1)},
Entries: map[string]meshcatalog.CatalogEntry{}}
for _, module := range modules {
digest := fmt.Sprintf("sha256:%064x", (i+1)*1000+len(half.Entries))
half.Revision.Entries = append(half.Revision.Entries, meshcatalog.EntryRef{Module: module, Digest: digest})
half.Entries[module] = meshcatalog.CatalogEntry{Module: module, Fp: at[module]}
}
placed := mma.Assignments{Node: "ace"}
for _, module := range modules {
placed.Modules = append(placed.Modules, mma.PlacedModule{Module: module})
}
in := assigngraph.Inputs{Halves: map[string]meshcatalogclient.Half{trunkBranch: half}, FirstBranch: func(string) string { return trunkBranch },
Placements: map[string]mma.Assignments{"ace": placed}}
if _, _, err := assigngraph.Keep(ctx, objects, assigngraph.Compute(in), "test", time.Now()); err != nil {
t.Fatal(err)
}
}
p.graph = &graphKeeper{objects: objects}
p.entries = meshcatalogclient.NewEntries(func(_ string, body any) (json.RawMessage, error) {
in := body.(meshcatalog.EntryInput)
entry := meshcatalog.CatalogEntry{Module: "m", Fp: in.Fingerprint, Manifest: map[string]any{"module": "m"}}
if form := forms[in.Fingerprint]; form > 0 {
entry.Manifest = map[string]any{"module": "m", "state": []any{map[string]any{"name": "sessions", "form": form}}}
}
return json.Marshal(meshcatalog.EntryAnswer{Entry: entry})
})
p.entries.Changed = func(meshcatalogclient.EntryRow) { f.answers <- struct{}{} }
return f
}
// runs says module runs fp healthy on ace, heard as the node-engine seat's running and in the have.
func (f *orderFixture) runs(module, fp string) {
have, _ := nodeengineclient.EncodeHave(nodeengine.HaveByNodeModuleValue{Fp: fp, Composed: "sha256:" + strings.Repeat("c", 64), Phase: nodeengineclient.PhaseRunning, Health: nodeengineclient.HealthOK})
f.p.w.put(buckets.Have, "ace."+module, have)
f.p.w.running["ace."+module] = nodeengine.Running{Node: "ace", Module: module, Fingerprint: fp}
}
// pass makes a pass, and after it every catalog entry it asked is answered.
func (f *orderFixture) pass() {
f.t.Helper()
f.p.wants(context.Background())
asked := 0
for _, row := range f.p.entries.Rows() {
if row.State == meshcatalogclient.EntryAsked {
asked++
}
}
for range asked {
select {
case <-f.answers:
case <-time.After(10 * time.Second): // a bound on a failure only: the answers come at once
f.t.Fatal("an entry asked was not answered")
}
}
}
// wantAt is the fingerprint module is wanted at on ace.
func (f *orderFixture) wantAt(module string) string {
f.t.Helper()
key, _ := mwc.WantKey("ace", module)
w, err := mwc.DecodeWant(f.wants.values[key])
if err != nil {
f.t.Fatal(err)
}
return w.Fp
}
func (f *orderFixture) waits() []string {
var out []string
for key := range f.p.w.read(buckets.Waits()) {
out = append(out, key)
}
return out
}
// A3/AC1 (design 47 H §771, §764): given a module whose kept data's form changes while the new versions of the node-backup holder and
// of the bus module do not run, when the assigner passes, then the module is wanted at its new version, no `order.` key is kept and no
// wait is said: the order on a machine is its node-engine's apply order, by rank.
func TestNoWantWaitsForTheOrderOfADelivery(t *testing.T) {
f := newOrderFixture(t, []orderMod{
{name: "web", run: orderFP("a"), trunk: orderFP("b"), forms: map[string]int{orderFP("a"): 1, orderFP("b"): 2}},
{name: "backup", run: orderFP("e"), trunk: orderFP("f"), holds: []string{catalogue.BackupSeat}},
{name: "bus", run: orderFP("g"), trunk: orderFP("h"), holds: []string{meshbroker.Seat}},
})
f.pass()
f.pass()
if got := f.wantAt("web"); got != orderFP("b") || len(f.waits()) != 0 || len(f.events) != 0 {
t.Fatalf("web at %s, waits %v, events %v: want web at its new version, no wait kept or said", got, f.waits(), f.events)
}
}
@@ -21,6 +21,7 @@ import (
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
occ "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/clients/operatorchannelclient"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/process"
"mesh-delivery-assigner/internal/assign"
)
@@ -42,10 +43,10 @@ type caller interface {
CallOn(node, key string, body any) (json.RawMessage, error)
// CallKept is Call for a kept call, safe to call again (process.Conn.CallKept; ADR 0668).
CallKept(key string, body any) (json.RawMessage, error)
// CallKeptOn is CallOn for a kept call, safe to call again (process.Conn.CallKeptOn; ADR 0668).
CallKeptOn(node, key string, body any) (json.RawMessage, error)
// CallFile is Call of a verb marked chunks, its answer read whole (process.Conn.CallFile; design 47 G A-291).
CallFile(key string, body any) (json.RawMessage, error)
// CallFileKept is CallFile as a kept call carrying its ask's id, until its bound (process.Conn.CallFileKept; H2 §775).
CallFileKept(ask process.KeptAsk, key string, body any) (json.RawMessage, error)
Emit(eventType string, body any) error
}
@@ -106,7 +107,6 @@ func (p *passer) puts(ctx context.Context) {
if p.acts == nil {
return
}
p.placementPuts(ctx)
all := p.putsByModule()
defer func() { p.putWaits(ctx, p.putsByModule()) }()
if len(all) == 0 {
@@ -136,14 +136,6 @@ func (p *passer) puts(ctx context.Context) {
world := p.putWorld(node, module, put, manifest, assigned[node])
world.Snapshot, world.Snapshotting, world.SnapshotFailed = p.acts.state(id)
next := assign.StepPut(world)
// A held bus whose user list the rules moved on (ADR 0539 §7): the put follows the composition its want names.
if w, ok := wanted[module][node]; ok && w.Put && w.Fp == next.Put.FP && w.Composed != "" && w.Composed != next.Put.Composed &&
(next.Put.Step == puts.Wanted || next.Put.Step == puts.Holding) {
if d, _ := p.composedFor(node, module, w.Fp); d != nil && d.UserListOnly && d.Digest == w.Composed {
next.Put = next.Put.Said(world.Now, next.Put.Step, fmt.Sprintf("the bus's user list changed: the want names composition %s", shortHex(w.Composed)))
next.Put.Composed = w.Composed
}
}
// The bus's want is written only for the act the operator's yes bound (ADR 0546 clause 8).
if next.Put.Step == puts.Wanted && put.Step != puts.Wanted && world.Bus && next.Put.Ask != "" {
if err := p.performs(next.Put.Ask, assign.PutAct(node, module, next.Put.FP, next.Put.Composed)); err != nil {
@@ -0,0 +1,87 @@
package main
import (
"context"
"encoding/json"
"fmt"
"time"
"github.com/nats-io/nats.go/jetstream"
wd "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshwatchdogs"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-sdk/go/process"
"mesh-delivery-assigner/internal/assign"
"mesh-delivery-assigner/internal/assignment"
)
// releaseHeard is one version-released heard: the version, each part's digest, the source revision and when it was said.
type releaseHeard struct {
Version string
Parts map[string]string
Source int64
At time.Time
}
// presenceOf reads one machine-away or machine-back: the machine and when it was said.
func presenceOf(data []byte) (string, time.Time, error) {
var e wd.MachineAwayEvent // machine-back has the same fields
if err := json.Unmarshal(data, &e); err != nil {
return "", time.Time{}, err
}
if e.Machine == "" {
return "", time.Time{}, fmt.Errorf("it names no machine: %s", data)
}
return e.Machine, e.At, nil
}
// hearReleases reads whole, from their first message, then follows, the catalog seat's version-released and the watchman's
// machine-away and machine-back (mesh-sdk process.FromFirst, A-233), never their state. A stream not heard is said as the assigner's finding, and what it carries is not known until
// the assigner starts again.
func hearReleases(ctx context.Context, js jetstream.JetStream, w *world, wake func(), findings assign.Findings, logf func(string, ...any)) {
acct := process.Account{Node: thisNode, Module: assignment.Module()}
nh := notHeardWriter(findings, logf)
for _, s := range []struct {
stream, words string
take func([]byte) error
}{
{meshcatalog.StreamVersionReleased, "no want names a released version", w.released.put},
{wd.StreamMachineAway, "no machine is known away, so a delivery waits for a machine that is away", func(data []byte) error {
m, at, err := presenceOf(data)
if err == nil {
w.heardPresence(m, true, at)
logf("%s is away (machine-away): a composition step does not compose it until its machine-back", m)
}
return err
}},
{wd.StreamMachineBack, "a machine once away is not known back", func(data []byte) error {
m, at, err := presenceOf(data)
if err == nil {
w.heardPresence(m, false, at)
logf("%s is back (machine-back): a composition step composes it again", m)
}
return err
}},
} {
take := s.take
cc, err := acct.HearSeatEvents(ctx, js, s.stream, func(m jetstream.Msg) {
if err := take(m.Data()); err != nil {
logf("%s is not kept: %v", m.Subject(), err)
}
if err := m.Ack(); err != nil {
logf("acknowledging %s: %v", m.Subject(), err)
}
wake()
}, logf, process.FromFirst())
if err != nil {
nh.NotHeard(s.stream, s.words+" until the assigner starts again", err)
continue
}
nh.Heard(s.stream)
go func() {
<-ctx.Done()
cc.Stop()
}()
}
}
@@ -133,4 +133,22 @@ func TestAHeldRevertIsAskedAndALiveAnswerIsWrittenIntoTheWant(t *testing.T) {
if _, raised := findings[fkey]; raised || p.w.has(buckets.Asks(), rkey) {
t.Fatalf("a newer want left the ask (%v) or the finding (%v)", p.w.has(buckets.Asks(), rkey), raised)
}
// A-453: only a held have with no wait is a failed backup and asked; the node-engine's other holds carry a wait.
ukey, _ := asks.BackupAskKey("ace", "web", fpTest)
for _, withWait := range []bool{true, false} {
h := nodeengine.HaveByNodeModuleValue{Fp: fpTest, Phase: nodeengineclient.PhaseHeld, Health: nodeengineclient.HealthWaits, Detail: "no space left"}
if withWait {
h.Wait = &nodeengine.Wait{Step: nodeengine.WaitStepCompose, Reason: "entry-missing", Since: time.Now()}
}
raw, err := nodeengineclient.EncodeHave(h)
if err != nil {
t.Fatal(err)
}
p.w.put(buckets.Have, hkey, raw)
pass()
if got := p.w.has(buckets.Asks(), ukey); got == withWait {
t.Fatalf("a held have with a wait = %v: backup ask asked = %v", withWait, got)
}
}
}
@@ -0,0 +1,184 @@
package main
import (
"context"
"encoding/json"
"fmt"
"slices"
"strconv"
"strings"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"mesh-delivery-assigner/internal/assigngraph"
)
// The assignment graph revisions are removed when they are no longer current (design 47 H §764, H-A-86): the gate's pins of
// them went with its pinned, freed, heads-replaced and pins-stated (H-A-48), and with them the assigner's state pins and its
// tools assigner_pins and assigner_unpin. A revision that is not current (the newest the assigner wrote) is removed, its object
// and the entry objects no kept revision or candidate lists and no want or running build names (G §179), when a revision ceases
// to be current and once at the start. Never on a timer.
// revisionObjects is the object bucket of the revisions as the remover removes from it.
type revisionObjects interface {
assigngraph.Objects
Delete(ctx context.Context, name string) error
}
// revisionRemover removes the revisions that are not current.
type revisionRemover struct {
ctx context.Context
objects revisionObjects
// inUse says a want or a running build names the module's fingerprint (§179).
inUse func(module, fp string) bool
logf func(string, ...any)
}
// judge removes every revision that is not current; a removal that fails is said and made at the next judging.
func (k *revisionRemover) judge() {
if err := k.remove(); err != nil {
k.logf("the revisions that are not current are not removed: %v", err)
}
}
// trunkRevision is the revision an object of a trunk revision names, and whether it names one.
func trunkRevision(name string) (int64, bool) {
n, ok := strings.CutPrefix(name, "trunk.")
if !ok {
return 0, false
}
r, err := strconv.ParseInt(n, 10, 64)
return r, err == nil && r > 0
}
// remove removes each kept revision that is not current, and then the entries no kept revision or candidate lists and no want or
// running build names (design 47 G §179).
func (k *revisionRemover) remove() error {
names, described, err := k.listing()
if err != nil {
return err
}
var kept []int64
for _, n := range names {
if r, ok := trunkRevision(n); ok {
kept = append(kept, r)
}
}
if len(kept) == 0 {
return nil
}
current := slices.Max(kept)
listed := map[string]bool{}
removed := 0
for _, r := range kept {
if r == current {
rev, err := assigngraph.ReadRevision(k.ctx, k.objects, r)
if err != nil {
return err
}
for _, e := range rev.Entries {
listed[e.Digest] = true
}
continue
}
if err := k.objects.Delete(k.ctx, assigngraph.TrunkObject(r)); err != nil {
return fmt.Errorf("revision %d: %w", r, err)
}
removed++
}
if removed == 0 {
return nil
}
// A run's candidate kept now lists its entries too, until its run's pipeline-ended drops it (A-201, A-235).
for _, n := range names {
group, heads, ok := meshwants.ParseAssignmentRevisionsByCandidateGroupHeadsKey(n)
if !ok {
continue
}
rev, err := assigngraph.ReadCandidate(k.ctx, k.objects, group, heads)
if err != nil {
return err
}
for _, e := range rev.Entries {
listed[e.Digest] = true
}
}
for _, n := range names {
digest, ok := strings.CutPrefix(n, "entry.")
if !ok || listed[digest] {
continue
}
e, err := k.entryOf(n, digest, described)
if err != nil {
return err
}
if k.inUse != nil && k.inUse(e.Module, e.Fp) {
continue
}
if err := k.objects.Delete(k.ctx, n); err != nil {
return fmt.Errorf("the entry %s: %w", digest, err)
}
}
k.logf("%d assignment graph revisions not current are removed", removed)
return nil
}
// inUseOf says a want or a running build names the module's fingerprint, as the world holds them now.
func inUseOf(w *world) func(module, fp string) bool {
return func(module, fp string) bool {
for _, want := range w.wantsOf()[module] {
if want.Fp == fp {
return true
}
}
for _, mods := range w.runningNow() {
if r, ok := mods[module]; ok && r.Fingerprint == fp {
return true
}
}
return false
}
}
// listing is every object's name in one read and, where the bucket says them, each entry object's module and fingerprint by name
// (design 47 H-A-259); nil described where the bucket says none.
func (k *revisionRemover) listing() ([]string, map[string]assigngraph.Described, error) {
d, ok := k.objects.(assigngraph.Describer)
if !ok {
names, err := k.objects.Names(k.ctx)
return names, nil, err
}
listed, err := d.Described(k.ctx)
if err != nil {
return nil, nil, err
}
names := make([]string, 0, len(listed))
described := make(map[string]assigngraph.Described, len(listed))
for _, l := range listed {
names = append(names, l.Name)
described[l.Name] = l
}
return names, described, nil
}
// entryOf is the module and fingerprint of the entry object name: as the listing says them, with no read; an entry put before the
// listing said them is read once and put again with them, so no later judging reads it (design 47 H-A-259).
func (k *revisionRemover) entryOf(name, digest string, described map[string]assigngraph.Described) (meshwants.AssignmentEntry, error) {
if l, ok := described[name]; ok && l.Module != "" && l.Fp != "" {
return meshwants.AssignmentEntry{Module: l.Module, Fp: l.Fp}, nil
}
data, err := k.objects.Get(k.ctx, name)
if err != nil {
return meshwants.AssignmentEntry{}, fmt.Errorf("the entry %s: %w", digest, err)
}
var e meshwants.AssignmentEntry
if err := json.Unmarshal(data, &e); err != nil {
return e, fmt.Errorf("the entry %s: %w", digest, err)
}
if described != nil {
if err := assigngraph.PutEntry(k.ctx, k.objects, name, data, e); err != nil {
k.logf("the entry %s is not put again with its module and fingerprint, so the next judging reads it again: %v", digest, err)
}
}
return e, nil
}
@@ -0,0 +1,110 @@
package main
import (
"context"
"encoding/json"
"strings"
"testing"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"mesh-delivery-assigner/internal/assigngraph"
)
func (m memObjects) Delete(_ context.Context, name string) error { delete(m, name); return nil }
// describedObjects is memObjects whose listing says each entry's module and fingerprint (assigngraph.Describer), counting the
// entry objects read.
type describedObjects struct {
memObjects
meta map[string][2]string
reads int
}
func (d *describedObjects) Get(ctx context.Context, name string) ([]byte, error) {
if strings.HasPrefix(name, "entry.") {
d.reads++
}
return d.memObjects.Get(ctx, name)
}
func (d *describedObjects) PutDescribed(_ context.Context, name string, data []byte, module, fp string) error {
d.memObjects[name], d.meta[name] = data, [2]string{module, fp}
return nil
}
func (d *describedObjects) Described(context.Context) ([]assigngraph.Described, error) {
var out []assigngraph.Described
for n := range d.memObjects {
out = append(out, assigngraph.Described{Name: n, Module: d.meta[n][0], Fp: d.meta[n][1]})
}
return out, nil
}
// Design 47 H §764, H-A-86: with the gate's pins gone, an assignment graph revision that is not current is removed, with the
// entries no kept revision or candidate lists and no want or running build names; the current revision, the entries it lists,
// a running build's entry and a run's kept candidate with its entries stay.
// H-A-259: where the listing says each entry's module and fingerprint, the judging reads no entry object; an entry put before it
// said them is read once and put again with them.
func TestARevisionNotCurrentIsRemoved(t *testing.T) {
for _, listed := range []string{"plain", "described", "described-later"} {
objects := memObjects{}
described := &describedObjects{memObjects: objects, meta: map[string][2]string{}}
entry := func(module, fp string) string {
e := meshwants.AssignmentEntry{Node: "n1", Module: module, Fp: fp}
d := assigngraph.EntryDigest(e)
raw, _ := json.Marshal(e)
objects[assigngraph.EntryObject(d)] = raw
if listed == "described" {
described.meta[assigngraph.EntryObject(d)] = [2]string{module, fp}
}
return d
}
shared, old, running, cand := entry("a", "fp-a"), entry("b", "fp-b1"), entry("c", "fp-c1"), entry("d", "fp-d2")
revision := func(n int64, digests ...string) {
rev := meshwants.AssignmentRevision{Revision: n}
for _, d := range digests {
rev.Entries = append(rev.Entries, meshwants.NodeEntryRef{Node: "n1", Digest: d})
}
raw, _ := json.Marshal(rev)
objects[assigngraph.TrunkObject(n)] = raw
}
candRaw, _ := json.Marshal(meshwants.AssignmentRevision{Revision: 1, Kind: "candidate", Group: "run-7", Heads: "h1",
Entries: []meshwants.NodeEntryRef{{Node: "n1", Module: "d", Digest: cand}}})
objects[assigngraph.CandidateObject("run-7", "h1")] = candRaw
revision(1, shared, old, running)
revision(2, shared, old)
revision(3, shared)
var o revisionObjects = objects
if listed != "plain" {
o = described
}
k := &revisionRemover{ctx: context.Background(), objects: o, logf: t.Logf,
inUse: func(module, fp string) bool { return module == "c" && fp == "fp-c1" }}
k.judge()
has := func(name string) bool { _, ok := objects[name]; return ok }
for name, want := range map[string]bool{assigngraph.TrunkObject(1): false, assigngraph.TrunkObject(2): false, assigngraph.TrunkObject(3): true,
assigngraph.EntryObject(old): false, assigngraph.EntryObject(running): true, assigngraph.EntryObject(shared): true,
assigngraph.EntryObject(cand): true, assigngraph.CandidateObject("run-7", "h1"): true} {
if has(name) != want {
t.Errorf("%s: %s kept = %v, want %v", listed, name, has(name), want)
}
}
switch listed {
case "described":
if described.reads != 0 {
t.Errorf("described: the judging read %d entry objects, want none", described.reads)
}
case "described-later":
if described.meta[assigngraph.EntryObject(running)] != [2]string{"c", "fp-c1"} {
t.Errorf("described-later: the entry in use is not put again with its module and fingerprint: %v", described.meta)
}
reads := described.reads
revision(4, shared)
k.judge()
if described.reads != reads {
t.Errorf("described-later: a second judging read %d entry objects again", described.reads-reads)
}
}
}
}
@@ -17,7 +17,6 @@ import (
"git.novox.be/novox/mesh-contracts/go/clients/nodeengineclient"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-assigner/asks"
mdcc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshdeliverycheckerclient"
mdc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshdeliveryclient"
"github.com/nats-io/nats.go"
@@ -266,6 +265,7 @@ func (p *passer) ask(ctx context.Context, prop mma.Proposal, akey, brief string)
p.pulse(ctx, pk, assign.ExpiresAt(placed).Sub(p.clock()))
}
prop.State, prop.Ask = mmac.ProposalAsked, placed.ID
p.logf("the proposal %s is asked of the operator: its ask %s is written under %s, which the teller raises on the operator channel", prop.ID, placed.ID, akey)
return prop, true
}
@@ -340,12 +340,20 @@ func (p *passer) stepProposal(ctx context.Context, prop mma.Proposal, rev uint64
}
prop.Verdict = &v
switch v.State {
case mdcc.VerdictFail:
case plc.VerdictFail:
prop.State, prop.Ask = mmac.ProposalFailed, ""
case plc.VerdictWaits:
prop.State, prop.Ask = mmac.ProposalAnswering, ""
case mdcc.VerdictPass:
case plc.VerdictPass:
if prop.State != mmac.ProposalAsked || again {
// A proposal none of whose changes the setting ask-operator-for names is applied at once, with no ask (A-425a).
if kinds := proposalKinds(prop, v); !p.asksFor(kinds) {
words := fmt.Sprintf("applied with no ask: its changes (%s) are none of the kinds the setting ask-operator-for names (%s); proposed by %s: %s",
strings.Join(kinds, ", "), strings.Join(p.askOperatorFor(), ", "), prop.By, prop.Why)
p.logf("the proposal %s is %s", prop.ID, words)
p.apply(ctx, prop, rev, mdc.Answer{Words: words}, current, revs)
return
}
var ok bool
if prop, ok = p.ask(ctx, prop, akey, judge.Brief(prop, v)); !ok {
return
@@ -499,6 +507,12 @@ func (p *passer) warranted(ctx context.Context, prop mma.Proposal, rev uint64, a
return
}
answer, _ := p.w.answer(akey)
p.apply(ctx, prop, rev, answer, current, revs)
}
// apply writes a proposal's laid candidates, its answer carried by assignments-changed: the operator's warranted answer, or the
// words of a proposal applied with no ask (design 47 G A-425a).
func (p *passer) apply(ctx context.Context, prop mma.Proposal, rev uint64, answer mdc.Answer, current map[string]mma.Assignments, revs map[string]uint64) {
if moved(prop, revs) {
p.layAgain(ctx, prop, rev, current, revs, "a key moved since it was approved, so its warrant is spent")
return
@@ -7,6 +7,7 @@ import (
"fmt"
"maps"
"mesh-delivery-assigner/internal/buckets"
"os"
"slices"
"sort"
"strings"
@@ -67,13 +68,17 @@ func indexerView(ask func(string, any) (json.RawMessage, error), state string) (
}
page := views.AskVia(ask, tool)
out := map[string]json.RawMessage{}
started, pages := time.Now(), 0
for after := ""; ; {
a, err := page(context.Background(), after)
if err != nil {
fmt.Fprintf(os.Stderr, "mesh-delivery-assigner: %s does not answer page %d after %s: %v\n", tool, pages+1, time.Since(started).Round(time.Millisecond), err)
return nil, fmt.Errorf("%s does not answer: %w", tool, err)
}
pages++
maps.Copy(out, a.Values)
if a.Next == "" || a.Next == after {
fmt.Fprintf(os.Stderr, "mesh-delivery-assigner: %s read, %d values in %d pages, %s\n", tool, len(out), pages, time.Since(started).Round(time.Millisecond))
return out, nil
}
after = a.Next
@@ -88,6 +93,11 @@ type seatTools struct {
// seats is the seat list the bundle reads (seatlist.go): until it is read, propose judges no mesh seat the bootstrapped
// definitions do not name as held once (ADR 0636 §1). Nil reads nothing.
seatList *seatlist.Part
// watched is the tools process's watched copy of the state seat-holders (tools.go wants.watched, which gate.Holders
// also reads: A-298), read by the verb assignments with seats instead of a bus get per key (issue 1982: under load
// that took about 14 s, where the watched copy answers at once). Nil, or a call it cannot answer, falls back to a
// direct listing.
watched *stdio.WatchedStates
}
func newSeatTools(st seatStore, ask func(string, any) (json.RawMessage, error)) *seatTools {
@@ -103,25 +113,18 @@ type keyed struct {
// assignments reads every node's assignments and the revision of its node key (its legacy key's before it is converted),
// assembled from its keys in either form (mmac.Keys; research 072 row 37).
func (s *seatTools) assignments() (map[string]mma.Assignments, map[string]uint64, error) {
keys, err := s.st.keys(mma.StateAssignments)
all, err := readAll(s.st, mma.StateAssignments)
if err != nil {
return nil, nil, fmt.Errorf("assignments cannot be listed: %w", err)
return nil, nil, fmt.Errorf("assignments cannot be read: %w", err)
}
sort.Strings(keys)
keys := slices.Sorted(maps.Keys(all))
held := mmac.NewKeys()
var bad []string
for _, key := range keys {
if _, _, _, err := mmac.ParseKey(key); err != nil {
continue
}
raw, rev, found, err := s.st.get(mma.StateAssignments, key)
if err != nil {
return nil, nil, fmt.Errorf("assignments key %s cannot be read: %w", key, err)
}
if !found {
continue
}
if _, err := held.Put(key, raw, rev, false); err != nil {
if _, err := held.Put(key, all[key].raw, all[key].rev, false); err != nil {
bad = append(bad, err.Error())
}
}
@@ -145,20 +148,18 @@ func (s *seatTools) lays() (func(string) bool, func(string) bool, error) {
held[name] = true
}
}
haves, err := s.st.keys(haveState)
haves, err := readAll(s.st, haveState)
if err != nil {
return nil, nil, fmt.Errorf("the nodes' records cannot be listed: %w", err)
return nil, nil, fmt.Errorf("the nodes' records cannot be read: %w", err)
}
recorded := map[string]bool{}
for _, k := range haves {
for k, v := range haves {
node, _, isNode, err := nodeengineclient.ParseHaveKey(k)
if err != nil || !isNode {
continue
}
if raw, _, found, err := s.st.get(haveState, k); err == nil && found {
if h, err := nodeengineclient.DecodeHaveNode(raw); err == nil && h.Record != nil {
recorded[node] = true
}
if h, err := nodeengineclient.DecodeHaveNode(v.raw); err == nil && h.Record != nil {
recorded[node] = true
}
}
return func(m string) bool { return held[m] }, func(n string) bool { return recorded[n] }, nil
@@ -239,11 +240,21 @@ func (s *seatTools) doPropose(args map[string]any, by string) (any, error) {
return nil, errors.New("the seed is gone with adopt: propose takes place, take-off, pin, unpin, hold, unhold, decide and config")
}
}
started := time.Now()
step := func(what string, err error) {
if err != nil {
fmt.Fprintf(os.Stderr, "mesh-delivery-assigner: propose by %s: %s failed after %s: %v\n", by, what, time.Since(started).Round(time.Millisecond), err)
return
}
fmt.Fprintf(os.Stderr, "mesh-delivery-assigner: propose by %s: %s at %s\n", by, what, time.Since(started).Round(time.Millisecond))
}
current, revs, err := s.assignments()
step("assignments read", err)
if err != nil {
return nil, err
}
held, recorded, err := s.lays()
step("the indexer's modules and the nodes' records read", err)
if err != nil {
return nil, err
}
@@ -259,11 +270,15 @@ func (s *seatTools) doPropose(args map[string]any, by string) (any, error) {
findings = append(findings, refusal)
}
if len(findings) > 0 {
step(fmt.Sprintf("refused (%d findings)", len(findings)), nil)
return nil, fmt.Errorf("the proposal is refused: %s", strings.Join(findings, "; "))
}
step("judged", nil)
if err := s.write(p); err != nil {
step("the proposal "+p.ID+" written", err)
return nil, err
}
step("the proposal "+p.ID+" written", nil)
return proposed{Proposal: p, Follow: followProposal(p.ID)}, nil
}
@@ -297,10 +312,10 @@ func warrantOf(v any) (*mma.Warrant, error) {
// mesh-node-enroller when the proven caller is that module's (its bus user `<node>.<module>`, never a person's
// `person.<module>`), else the caller as proven, which the refusal names.
func moduleOfCaller(by string, enrollers []string) string {
for _, module := range enrollers {
if (stdio.Callers{module}).Allows(by) {
return module
}
// The enrolment's caller stays (design 47 H-A-41): a module's bus user is `<node>.<module>`, a person's `person.<name>`.
_, module, ok := strings.Cut(by, ".")
if ok && !strings.HasPrefix(by, "person.") && slices.Contains(enrollers, module) {
return module
}
return by
}
@@ -477,21 +492,17 @@ func (s *seatTools) doProposals(args map[string]any) (any, error) {
if err != nil {
return nil, fmt.Errorf("the candidates cannot be listed: %w", err)
}
haves, err := s.st.keys(haveState)
haves, err := readAll(s.st, haveState)
if err != nil {
return nil, fmt.Errorf("the nodes' haves cannot be listed: %w", err)
return nil, fmt.Errorf("the nodes' haves cannot be read: %w", err)
}
answers := map[string]map[string]nodeengine.CandidateAnswer{} // by proposal, then node
for _, k := range haves {
for k, v := range haves {
node, _, isNode, err := nodeengineclient.ParseHaveKey(k)
if err != nil || !isNode {
continue
}
raw, _, found, err := s.st.get(haveState, k)
if err != nil || !found {
continue
}
h, err := nodeengineclient.DecodeHaveNode(raw)
h, err := nodeengineclient.DecodeHaveNode(v.raw)
if err != nil {
continue
}
@@ -548,25 +559,43 @@ func (s *seatTools) tools() []stdio.Tool {
return out
}
// seats is the verb assignments with seats (ADR 0571 §4): who holds each seat and on which node, as the state seat-holders
// holds it; with node, the keys of seats held on that node.
func (s *seatTools) seats(node string) (any, error) {
// seatHolders is every key of the state seat-holders and its raw value: from the watched copy (s.watched) when
// there is one and it answers, else a direct listing, key by key, as the verb answered before (issue 1982).
func (s *seatTools) seatHolders() (map[string][]byte, error) {
if s.watched != nil {
if vals, err := s.watched.Values(mma.StateSeatHolders); err == nil {
return vals, nil
}
}
keys, err := s.st.keys(mma.StateSeatHolders)
if err != nil {
return nil, fmt.Errorf("seat-holders cannot be listed: %w", err)
}
sort.Strings(keys)
out := []mma.SeatHolders{}
out := make(map[string][]byte, len(keys))
for _, key := range keys {
raw, _, found, err := s.st.get(mma.StateSeatHolders, key)
if err != nil {
return nil, fmt.Errorf("seat-holders %s cannot be read: %w", key, err)
}
if !found {
continue
if found {
out[key] = raw
}
}
return out, nil
}
// seats is the verb assignments with seats (ADR 0571 §4): who holds each seat and on which node, as the state seat-holders
// holds it; with node, the keys of seats held on that node.
func (s *seatTools) seats(node string) (any, error) {
raws, err := s.seatHolders()
if err != nil {
return nil, err
}
keys := slices.Sorted(maps.Keys(raws))
out := []mma.SeatHolders{}
for _, key := range keys {
var sh mma.SeatHolders
if json.Unmarshal(raw, &sh) != nil {
if json.Unmarshal(raws[key], &sh) != nil {
continue
}
if node != "" && sh.Node != node && !slices.ContainsFunc(sh.Holders, func(h mma.SeatHoldersHoldersItem) bool { return h.Node == node }) {
@@ -20,11 +20,9 @@ import (
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/catalogkey"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/seatlist"
mmac "git.novox.be/novox/mesh-contracts/go/clients/meshmoduleassignerclient"
mma "git.novox.be/novox/mesh-contracts/go/seats/meshmoduleassigner"
"git.novox.be/novox/mesh-contracts/provisioning/go/clients/meshprovisionerclient"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/views"
@@ -270,19 +268,6 @@ func TestTheSeatsVerbs(t *testing.T) {
})
}
s.seatList = nil
t.Run("1966: the seat list's again tool answers an operator's session through the mesh MCP server", func(t *testing.T) {
// Such a session is proved as its machine's tool runner (issue 627); the healers too, no other module. The list names
// the seats, resolved from the assigner's own seat-holders (A-295, A-298): a module holding neither is refused.
held := map[string][]byte{"node-tool-runner.shanks": []byte(`{"holders":[{"module":"node-tools","node":"shanks"}]}`),
"mesh-healers": []byte(`{"holders":[{"module":"mesh-delivery-watchman","node":"ace"}]}`)}
holders := seatlist.HoldersIn(func() (map[string][]byte, error) { return held, nil })
for caller, refused := range map[string]bool{"person.jochen": false, "shanks.node-tools": false, "ace.mesh-delivery-watchman": false,
"ace.mesh-healers": true, "ace.messenger": true} {
if err := seatlist.RefusalWith("assigner_seat_list_again", seatListAgainCallers, caller, holders); (err != nil) != refused {
t.Errorf("%s: refused=%v, err %v", caller, refused, err)
}
}
})
t.Run("1953/D4-D6: the seat mesh-wants' upgrade and bus", wantsVerbs)
t.Run("1955/L7 (ADR 0571 §6): rule 7 reads the node's own composition; an unplaced node is said", func(t *testing.T) {
w := newWorld()
@@ -325,11 +310,11 @@ func TestTheSeatsVerbs(t *testing.T) {
place("ace", mma.Holding{Claim: "mesh-broker", Scope: "mesh", Module: "nats"}, mma.Holding{Claim: "node-shell", Scope: "node", Module: "web"})
place("g14", mma.Holding{Claim: "node-shell", Scope: "node", Module: "web"})
ctx := context.Background()
if p.seatHolders(ctx); writes != 0 {
if p.seatHolders(ctx, nil); writes != 0 {
t.Fatalf("seat-holders was written from an unread seat list: %v", kv.values)
}
p.seats = gateOver(t, false)
p.seatHolders(ctx)
p.seatHolders(ctx, nil)
var broker mma.SeatHolders
if err := json.Unmarshal(kv.values["mesh-broker"], &broker); err != nil || broker.Outside {
t.Errorf("mesh-broker's holders %+v, %v: a seat the list names is no seat outside it", broker, err)
@@ -337,12 +322,12 @@ func TestTheSeatsVerbs(t *testing.T) {
if writes != 3 || kv.values["mesh-broker"] == nil || kv.values["node-shell.ace"] == nil || kv.values["node-shell.g14"] == nil {
t.Fatalf("%d writes: %v", writes, kv.values)
}
p.seatHolders(ctx)
p.seatHolders(ctx, nil)
if writes != 3 {
t.Errorf("an unchanged assignments wrote %d keys", writes-3)
}
place("g14") // g14 holds nothing now
p.seatHolders(ctx)
p.seatHolders(ctx, nil)
if writes != 3 || kv.values["node-shell.g14"] != nil || kv.values["node-shell.ace"] == nil {
t.Errorf("after g14's change: %d writes, %v", writes, kv.values)
}
@@ -352,6 +337,53 @@ func TestTheSeatsVerbs(t *testing.T) {
t.Errorf("seats on ace = %+v, %v", out, err)
}
})
t.Run("issue 1982: assignments with seats reads the tools process's watched copy of seat-holders, the store only while it cannot", func(t *testing.T) {
seeded := map[string][]byte{}
put := func(seat, node string, holders ...mma.SeatHoldersHoldersItem) {
raw, err := json.Marshal(mma.SeatHolders{Seat: seat, Node: node, Holders: holders})
if err != nil {
t.Fatal(err)
}
seeded[seat] = raw
}
put("mesh-broker", "", mma.SeatHoldersHoldersItem{Module: "nats", Node: "ace"})
put("node-shell.g14", "g14")
st := &countingSeatStore{memStore: memStore{mma.StateSeatHolders: &memKV{values: seeded}}}
sv := newSeatTools(st, nil)
watches := 0
sv.watched = stdio.WatchedStatesOver(func(state string, handle func(stdio.StateChange) error) error {
watches++
for k, v := range seeded {
if err := handle(stdio.StateChange{Key: k, Op: stdio.OpPut, Value: v, Current: true}); err != nil {
return err
}
}
return nil
}, func(state, key string) ([]byte, bool, error) {
v, ok := seeded[key]
return v, ok, nil
})
out, err := sv.seats("")
if err != nil {
t.Fatal(err)
}
if got := out.(map[string]any)["seats"].([]mma.SeatHolders); len(got) != 2 || watches != 1 || st.keysCalls != 0 || st.getCalls != 0 {
t.Errorf("seats from the watched copy = %+v, watched %d time(s), the store's own keys %d get %d (want none)",
got, watches, st.keysCalls, st.getCalls)
}
// The lead's answer on issue 1982: the verb falls back to the store's own listing only while the watched copy
// cannot be read (here, its watch refused); the answer's form does not change.
sv.watched = stdio.WatchedStatesOver(func(string, func(stdio.StateChange) error) error {
return errors.New("refused")
}, func(state, key string) ([]byte, bool, error) { return nil, false, nil })
out, err = sv.seats("")
if err != nil {
t.Fatal(err)
}
if got := out.(map[string]any)["seats"].([]mma.SeatHolders); len(got) != 2 || st.keysCalls != 1 || st.getCalls != 2 {
t.Errorf("seats falling back to the store = %+v, the store's own keys %d get %d (want 1, 2)", got, st.keysCalls, st.getCalls)
}
})
t.Run("research 072 row 37: a node is written as its keys, and history reads the node key", func(t *testing.T) {
ctx := context.Background()
kv := &revKV{values: map[string][]byte{}, revs: map[string]uint64{}}
@@ -486,51 +518,14 @@ func TestTheSeatsVerbs(t *testing.T) {
})
}
})
t.Run("1954/D1: a failed provision is the assigner's finding until it is provided", func(t *testing.T) {
findings := map[string][]byte{}
p := &passer{w: newWorld(), logf: func(string, ...any) {}, kvs: kvSet{buckets.Provisions: nil}, findings: assign.Findings{
Put: putInto(findings),
Delete: func(k string) error { delete(findings, k); return nil }}}
failed, _ := meshprovisionerclient.Encode(meshprovisionerclient.Provision{Provision: "db", Consumer: meshprovisionerclient.End{Module: "photos", Node: "ace"},
Provider: meshprovisionerclient.End{Module: "postgres", Node: "novox"}, State: meshprovisionerclient.Failed, Why: "the role exists already"})
p.w.putEntry(buckets.Provisions, "ace.photos.db", failed, 1, time.Now())
p.kvs[buckets.Provisions] = &memKV{}
of := p.provisionsOf()
if got := of("photos")("ace"); got["ace.photos.db"].State != meshprovisionerclient.Failed {
t.Fatalf("provisions = %+v", got)
}
if _, ok := findings[assign.ProvisionFailedKey("ace.photos.db")]; !ok || len(findings) != 1 {
t.Fatalf("findings = %v", findings)
}
provided, _ := meshprovisionerclient.Encode(meshprovisionerclient.Provision{Provision: "db", Consumer: meshprovisionerclient.End{Module: "photos", Node: "ace"},
Provider: meshprovisionerclient.End{Module: "postgres", Node: "novox"}, State: meshprovisionerclient.Provided})
p.w.putEntry(buckets.Provisions, "ace.photos.db", provided, 2, time.Now())
p.provisionsOf()
if len(findings) != 0 {
t.Errorf("findings after provided = %v", findings)
}
// A required provision with no key: pulsed with the bound first, said once the pulse expired, ended once keyed.
ctx := context.Background()
p.kvs[plc.PulsesBucket()] = &memKV{values: map[string][]byte{}}
gone := map[string]bool{"ace.photos.s3": true}
p.provisionsMissing(ctx, gone)
if !p.pulsing("provision-missing.ace.photos.s3") || len(findings) != 0 {
t.Fatalf("first seen: pulsing %v, findings %v", p.pulsing("provision-missing.ace.photos.s3"), findings)
}
p.provisionsMissing(ctx, gone)
if len(findings) != 0 {
t.Fatal("said before its bound")
}
p.w.put(plc.PulsesBucket(), "provision-missing.ace.photos.s3", nil) // the server expired it
p.provisionsMissing(ctx, gone)
if _, ok := findings[assign.ProvisionMissingKey("ace.photos.s3")]; !ok {
t.Fatalf("past its bound: findings %v", findings)
}
p.provisionsMissing(ctx, map[string]bool{})
if len(findings) != 0 {
t.Errorf("keyed again: findings %v", findings)
}
})
// A whole state is read in pages where the store has them, never a key at a time (27 s for the assignments live,
// 2026-11-14): the paged read answers what the key-by-key read answers, and asks no key alone.
direct, err := readAll(st, haveState)
paged := &pagedStore{memStore: st}
viaPages, perr := readAll(paged, haveState)
if err != nil || perr != nil || len(viaPages) != len(direct) || paged.pages == 0 || paged.gets != 0 {
t.Errorf("readAll in pages = %d keys in %d pages with %d gets (%v, %v), want the %d keys of the direct read, no get", len(viaPages), paged.pages, paged.gets, err, perr, len(direct))
}
}
// wantsVerbs (novox/hq ADR 0565 §7, §8, §9): upgrade answers each module's policy and its source; a person's choice is
@@ -742,6 +737,23 @@ func readManifest() (catalogue.Manifest, error) {
return catalogue.Decode(raw)
}
// countingSeatStore is a memStore that counts its calls to keys and get, to prove a reader takes the state from the
// watched copy and the store only while that copy cannot be read (issue 1982).
type countingSeatStore struct {
memStore
keysCalls, getCalls int
}
func (c *countingSeatStore) keys(state string) ([]string, error) {
c.keysCalls++
return c.memStore.keys(state)
}
func (c *countingSeatStore) get(state, key string) ([]byte, uint64, bool, error) {
c.getCalls++
return c.memStore.get(state, key)
}
// countingKV is a memKV that counts its puts.
type countingKV struct {
memKV
@@ -943,3 +955,35 @@ func (f *fakeIndexer) answer(key string, body any) (json.RawMessage, bool, error
raw, err := json.Marshal(a)
return raw, true, err
}
// pagedStore is a memStore whose states are read in pages of one key, counting pages and single gets.
type pagedStore struct {
memStore
pages, gets int
}
func (p *pagedStore) get(state, key string) ([]byte, uint64, bool, error) {
p.gets++
return p.memStore.get(state, key)
}
func (p *pagedStore) page(state, after string) (stdio.StatePage, error) {
p.pages++
keys, err := p.memStore.keys(state)
if err != nil {
return stdio.StatePage{}, err
}
slices.Sort(keys)
for i, k := range keys {
if k <= after {
continue
}
raw, rev, _, _ := p.memStore.get(state, k)
pg := stdio.StatePage{Entries: []stdio.StateEntry{{Key: k, Value: raw, Revision: rev}}}
if i < len(keys)-1 {
pg.Next = k
}
return pg, nil
}
return stdio.StatePage{}, nil
}
@@ -1,16 +1,7 @@
package main
import (
stdio "git.novox.be/novox/mesh-sdk/go"
)
// The assigner reads the seat list as every part does, through mesh-sdk's one wiring (go/seatlist.Part; design 47 G §204): its
// reader over the seat mesh-catalog's verb seat-definitions and its two events, its tools `assigner_seat_list` and
// `assigner_seat_list_again`. What the reader holds is given to catalogue at every change, which the check of a proposal and the
// seat-holders state read; until the list is read, a mesh seat the bootstrapped definitions do not name is never judged held once
// (plc.CheckAssignments), and seat-holders is not written.
// A call through the mesh MCP server is proved only as its machine's tool runner (issue 627), so the holders of the seat
// node-tool-runner stand for an operator's session until a session is proved (issue 1966). The list names seats, never a
// module, resolved from the assigner's own seat-holders (design 47 G A-210, A-295, A-298).
var seatListAgainCallers = []string{stdio.AnyPerson, stdio.CallerSeatPrefix + "node-tool-runner", stdio.CallerSeatPrefix + "mesh-healers"}
@@ -60,7 +60,7 @@ func gateOver(t *testing.T, silent bool) *seatlist.Part {
// that waits for it to stay unread keeps short.
t.Cleanup(busretry.Waits(20*time.Millisecond, time.Millisecond, 5*time.Millisecond))
}
g := seatlist.NewPart("assigner", seatListAgainCallers)
g := seatlist.NewPart("assigner")
r := g.Follow(standInCatalog{silent: silent}, nil, t.Logf)
if r == nil {
t.Fatal("the reader did not start")
@@ -98,7 +98,7 @@ func TestTheSeatListIsWiredByTheSDKAlone(t *testing.T) {
// A-179, A-186: the definition the verb input's callers are checked against is the seat list's, none before the reader starts
// or while the seat mesh-catalog has not answered, and none for a seat the list does not hold.
func TestTheAnsweredSeatsDefinitionIsTheSeatListsOnceRead(t *testing.T) {
if _, ok := seatlist.Definition(seatlist.NewPart("assigner", seatListAgainCallers).Reader, "mesh-wants")(); ok {
if _, ok := seatlist.Definition(seatlist.NewPart("assigner").Reader, "mesh-wants")(); ok {
t.Error("a definition is answered before the seat list's reader started")
}
if _, ok := seatlist.Definition(gateOver(t, true).Reader, "mesh-wants")(); ok {
@@ -0,0 +1,18 @@
package main
import (
"strings"
"testing"
)
// A module a candidate adds with no release heard is said once, not each pass.
func TestASkippedAddIsSaidOncePerModuleAndFingerprint(t *testing.T) {
var logs []string
p := &passer{logf: func(f string, a ...any) { logs = append(logs, strings.TrimSpace(f)) }}
p.skippedAdd("n", "m", "fp", "why")
p.skippedAdd("n", "m", "fp", "why")
p.skippedAdd("n", "m", "fp2", "why")
if len(logs) != 2 {
t.Fatalf("said %d times, want 2: %v", len(logs), logs)
}
}
@@ -0,0 +1,318 @@
package main
import (
"context"
"encoding/json"
"errors"
"fmt"
"strings"
"sync"
"time"
"github.com/nats-io/nats.go"
"github.com/nats-io/nats.go/jetstream"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/buscompose"
"git.novox.be/novox/mesh-sdk/go/process"
"git.novox.be/novox/mesh-sdk/go/seatdef"
)
// **The seat mesh-wants takes its asks from a work queue and says ask-taken** (design 47 H2 §777, §775, §778; ADR 0525 §2,
// §6; ADR 0668 §2; H-A-381, H-A-401, H-A-404): the broker derives the seat's stream and its one shared worker from the seat's
// definition; the assigner pulls every ask waiting at once, takes each once by its id in its state taken (key
// <seat>.<ask>, for ask-taken-bound), says ask-taken at the pull, sends in-progress while the step runs and acknowledges an
// ask once it said the ask's end. An ask put while the assigner is down waits on the stream. The seat's act drop ends an ask
// its caller no longer waits for: one running here is cancelled, one not pulled yet is kept in taken as dropped.<ask> for
// ask-taken-bound, and either ends its step could not run naming the drop and who asked it.
// askTakenBoundSetting is the setting the taken key's time to live is (H-A-381 (2)): the holder never receives the
// caller's bound, so the largest caller's, the runner's ask-unanswered-bound, is its default.
const (
askTakenBoundSetting = "ask-taken-bound"
defaultAskTakenBound = 10 * time.Minute
)
// droppedPrefix keys a drop of an ask not pulled yet in the state taken (H-A-404).
const droppedPrefix = "dropped."
// takenStore is the state taken (process.State): an ask taken once by its id, and the drops of asks not pulled yet.
type takenStore interface {
TakeOnce(seat, ask string, bound time.Duration) (bool, error)
Get(key string) (*stdio.StateEntry, error)
RenewTTL(key string, value any, ttl time.Duration) (uint64, error)
Delete(key string) error
}
// queueMsg is what the steps read of a message pulled from the seat's work queue (jetstream.Msg).
type queueMsg interface {
Data() []byte
Headers() nats.Header
Ack() error
Nak() error
Term() error
InProgress() error
}
// askDrop is one drop of an ask: who asked it, why and when; the cause of a running step's end.
type askDrop struct {
By string `json:"by,omitempty"`
Why string `json:"why"`
At time.Time `json:"at"`
}
func (d *askDrop) Error() string {
by := d.By
if by == "" {
by = "its asker"
}
return fmt.Sprintf("the ask was dropped by %s: %s", by, d.Why)
}
// askIDOf is the ask's id a put carries: its event id, else its message id.
func askIDOf(h nats.Header) string {
if id := h.Get("x-event-id"); id != "" {
return id
}
return h.Get(nats.MsgIdHdr)
}
// pulled handles one ask pulled from the seat's work queue: an ask that is no composition or validate step with an id is
// terminated, said; one dropped before it was pulled ends could not run naming the drop; one running here already (handed
// again while it runs) is held for that run, which acknowledges it at its end; any other is taken once by its id (ask-taken
// said the first time) and run, in progress while it runs. A repeat of an id taken before that runs here no longer is run
// again against the runs as they stand (H-A-381 (1), H-A-401): its composition runs are joined, never run twice.
func (c *compositionSteps) pulled(ctx context.Context, m queueMsg) {
id := askIDOf(m.Headers())
var run meshwants.StepRun
err := json.Unmarshal(m.Data(), &run)
how := c.howOf(run.Step, false)
if err != nil || id == "" || how == nil {
c.logf("a step ask on the seat %s's work queue that is no composition or validate step with an id is ended: %v", meshwants.Seat, err)
_ = m.Term()
return
}
if d := c.droppedBefore(id); d != nil {
c.hold(id, m)
c.logf("the ask %s (%s) was dropped before it was pulled: %v", id, run.Pipeline, d)
c.sayEnd(id, run, nil, stepOutcome{Outcome: meshwants.StepEndedOutcomeCouldNotRun, Said: d.Error()}, "")
if err := c.taken.Delete(droppedPrefix + id); err != nil {
c.logf("the drop of the ask %s cannot be deleted from the state %s: %v", id, process.TakenState, err)
}
return
}
if c.running(id) {
c.hold(id, m)
c.logf("the ask %s (%s) was handed again while it runs here: its run answers it", id, run.Pipeline)
return
}
first, err := c.taken.TakeOnce(meshwants.Seat, id, c.takenBound)
if err != nil {
c.logf("the ask %s (%s) is not taken, the state %s refused it: %v; it is handed again", id, run.Pipeline, process.TakenState, err)
_ = m.Nak()
return
}
c.hold(id, m)
if first {
at := c.now().UTC()
if err := c.say(meshwants.EventAskTaken+"."+id, meshwants.AskTakenEvent{Ask: id, Node: c.node, At: at}, id+".taken"); err != nil {
c.logf("saying ask-taken of %s: %v", id, err)
}
} else {
c.logf("the ask %s (%s) was taken before: it is run again against its composition runs as they stand", id, run.Pipeline)
}
go c.say1(ctx, id, run, how, "")
}
// hold keeps m for the step asked under id: acknowledged once its end is said, in progress while it runs.
func (c *compositionSteps) hold(id string, m queueMsg) {
c.mu.Lock()
defer c.mu.Unlock()
if c.held == nil {
c.held = map[string][]queueMsg{}
}
c.held[id] = append(c.held[id], m)
}
// settle acknowledges (ack) or hands again (nak) every message held for id.
func (c *compositionSteps) settle(id string, ack bool) {
c.mu.Lock()
ms := c.held[id]
delete(c.held, id)
c.mu.Unlock()
for _, m := range ms {
if ack {
_ = m.Ack()
} else {
_ = m.Nak()
}
}
}
// inProgressEvery says every message held for id in progress every d, until the returned stop is called.
func (c *compositionSteps) inProgressEvery(id string) (stop func()) {
every := time.Duration(0)
if c.inProgress != nil {
every = c.inProgress()
}
if every <= 0 {
return func() {}
}
ticks := c.ticks
if ticks == nil {
ticks = func(d time.Duration) (<-chan time.Time, func()) { t := time.NewTicker(d); return t.C, t.Stop }
}
tick, stopTicks := ticks(every)
done, ended := make(chan struct{}), make(chan struct{})
go func() {
defer close(ended)
defer stopTicks()
for {
select {
case <-done:
return
case <-tick:
c.mu.Lock()
ms := append([]queueMsg(nil), c.held[id]...)
c.mu.Unlock()
for _, m := range ms {
_ = m.InProgress()
}
}
}
}()
return func() { close(done); <-ended }
}
// droppedBefore is the drop kept for an ask not pulled yet, nil for none.
func (c *compositionSteps) droppedBefore(id string) *askDrop {
if c.taken == nil {
return nil
}
e, err := c.taken.Get(droppedPrefix + id)
if err != nil {
c.logf("whether the ask %s was dropped cannot be read from the state %s: %v; it is taken", id, process.TakenState, err)
return nil
}
if e == nil {
return nil
}
var d askDrop
if json.Unmarshal(e.Value, &d) != nil {
return nil
}
return &d
}
// dropAsk is the seat's act drop (§778, H-A-404): a step running here for the ask is cancelled with the drop as its cause and
// ends could not run naming it; one not running here is kept in taken as dropped.<ask> for ask-taken-bound, so its pull ends
// it the same way. It answers whether the ask was held here.
func (c *compositionSteps) dropAsk(caller string, in meshwants.DropInput) (meshwants.DropAnswer, error) {
id, why := strings.TrimSpace(in.ID), strings.TrimSpace(in.Why)
if id == "" || why == "" {
return nil, errors.New("give the ask's id and why it is dropped")
}
by := strings.TrimSpace(in.By)
if by == "" {
by = caller
}
d := &askDrop{By: by, Why: why, At: c.now().UTC()}
c.mu.Lock()
stop := c.stops[id]
c.mu.Unlock()
if stop != nil {
stop(d)
c.logf("the ask %s running here is dropped: %v", id, d)
return meshwants.DropAnswer{"held": true}, nil
}
if c.taken == nil {
return nil, fmt.Errorf("the state %s is not bound, so the drop of %s cannot be kept", process.TakenState, id)
}
if _, err := c.taken.RenewTTL(droppedPrefix+id, d, c.takenBound); err != nil {
return nil, fmt.Errorf("writing the drop of %s in the state %s: %w", id, process.TakenState, err)
}
c.logf("the ask %s, not running here, is kept dropped until it is pulled: %v", id, d)
return meshwants.DropAnswer{"held": false}, nil
}
// dropVerb is the process's handler of the seat mesh-wants' act drop.
func dropVerb(c *compositionSteps) map[string]process.SeatHandler {
return map[string]process.SeatHandler{
meshwants.VerbDrop: func(caller string, raw json.RawMessage) (any, error) {
var in meshwants.DropInput
if err := json.Unmarshal(raw, &in); err != nil {
return nil, fmt.Errorf("the arguments are not JSON: %w", err)
}
return c.dropAsk(caller, in)
},
}
}
// inProgressOf is the seat's in-progress as its definition names it, once the seat list is read; before, a third of the
// worker's ack wait, which the broker derived from the same definition (60 s and 20 s, §777; H-A-401).
func inProgressOf(def func() (seatdef.Definition, bool), ackWait func() time.Duration) func() time.Duration {
return func() time.Duration {
if d, ok := def(); ok {
if _, worker, ok, err := buscompose.SeatQueue(meshwants.Seat, d.Accepts); err == nil && ok && worker.InProgressSeconds > 0 {
return time.Duration(worker.InProgressSeconds) * time.Second
}
}
return ackWait() / 3
}
}
// serveStepQueue pulls the seat's work queue through its one shared worker, every ask waiting at once (at most the worker's
// max ack pending), once the broker made it: a worker not there yet is said, and bound when the bus says it was created.
func serveStepQueue(ctx context.Context, conn process.Subscriber, js jetstream.JetStream, c *compositionSteps, ackWait func(time.Duration)) error {
stream, worker := buscompose.SeatQueueStreamName(meshwants.Seat), buscompose.SeatQueueWorkerName(meshwants.Seat)
var once sync.Once
bind := func() bool {
cons, err := js.Consumer(ctx, stream, worker)
if err != nil {
return false
}
bound := false
once.Do(func() {
bound = true
info := cons.CachedInfo()
if info != nil && info.Config.AckWait > 0 {
ackWait(info.Config.AckWait)
}
pending := 1000
if info != nil && info.Config.MaxAckPending > 0 {
pending = info.Config.MaxAckPending
}
cc, err := cons.Consume(func(m jetstream.Msg) { c.pulled(ctx, m) }, jetstream.PullMaxMessages(pending))
if err != nil {
c.logf("the seat %s's work queue %s is not pulled: %v", meshwants.Seat, worker, err)
return
}
c.logf("the composition step is pulled from %s on %s", worker, stream)
go func() { <-ctx.Done(); cc.Stop() }()
})
return bound
}
if bind() {
return nil
}
c.logf("the seat %s's work queue %s on %s is not there yet: its asks wait on it, and it is pulled when the bus says it was created", meshwants.Seat, worker, stream)
sub, err := conn.Subscribe("$JS.EVENT.ADVISORY.CONSUMER.CREATED."+stream+"."+worker, func(*nats.Msg) { go bind() })
if err != nil {
return fmt.Errorf("hearing the creation of the seat %s's work queue: %w", meshwants.Seat, err)
}
go func() { <-ctx.Done(); _ = sub.Unsubscribe() }()
if bind() { // made between the first look and the subscription
_ = sub.Unsubscribe()
}
return nil
}
// askTakenBound reads the setting ask-taken-bound (§781).
func askTakenBound() (time.Duration, error) {
d, err := stdio.SettingDuration(askTakenBoundSetting, defaultAskTakenBound)
if err != nil {
return 0, errors.New("the assigner's " + err.Error())
}
return d, nil
}
@@ -0,0 +1,69 @@
package main
import (
"errors"
"fmt"
"time"
stdio "git.novox.be/novox/mesh-sdk/go"
)
// kept is one key's value and revision, as a whole state read gives it.
type kept struct {
raw []byte
rev uint64
}
// pager is a store that reads a state's values many to a request (stdio.KeptState.Page): the runtime's store.
type pager interface {
page(state, after string) (stdio.StatePage, error)
}
// pageBytes and pageBudget bound one page of a whole state read, so its answer fits one bus message and its time.
const (
pageBytes = 768 * 1024
pageBudget = 10 * time.Second
)
func (runtimeStore) page(state, after string) (stdio.StatePage, error) {
return stdio.State(state).Page(after, pageBytes, pageBudget)
}
// readAll is every key of a state with its value and revision: in pages when the store has them, else key by key. Key by
// key cost one bus request each, so the assignments (about 330 keys) took 27 s to read and a proposal outlasted its
// caller's 30 s (2026-11-14), as the indexer's view of the trunk had the hour before.
func readAll(st store, state string) (map[string]kept, error) {
out := map[string]kept{}
if p, ok := st.(pager); ok {
for after := ""; ; {
pg, err := p.page(state, after)
if errors.Is(err, errors.ErrUnsupported) {
break
}
if err != nil {
return nil, fmt.Errorf("%s cannot be read: %w", state, err)
}
for _, e := range pg.Entries {
out[e.Key] = kept{raw: e.Value, rev: e.Revision}
}
if pg.Next == "" || pg.Next == after {
return out, nil
}
after = pg.Next
}
}
keys, err := st.keys(state)
if err != nil {
return nil, fmt.Errorf("%s cannot be listed: %w", state, err)
}
for _, k := range keys {
raw, rev, found, err := st.get(state, k)
if err != nil {
return nil, fmt.Errorf("%s %s cannot be read: %w", state, k, err)
}
if found {
out[k] = kept{raw: raw, rev: rev}
}
}
return out, nil
}
@@ -0,0 +1,360 @@
package main
import (
"encoding/json"
"errors"
"fmt"
"slices"
"sort"
"strings"
"time"
mcc "git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshconditionsclient"
mcseat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/views"
"mesh-delivery-assigner/internal/assign"
)
// One pipeline's wants are written tier by tier (design 47 H §751, H-A-10, H-A-56): on a passed pipeline-ended the assigner
// writes the wants of its first tier's movers; once each of them runs at the mover's fingerprint (the node-engine seat's
// `running`, H-A-40) on every present placing machine, it writes the next tier's, and so on. The tier progress is the key
// `pipeline.<branch>.<source>` of the state written, `{tier, since, movers}`; a tier counts placed movers only, and a machine away
// is not waited for. A tier whose movers do not all run within `tier-bound` ends the delivery loudly: no later tier is written,
// the finding `tier-late` (scope delivery, id the pipeline) is raised naming the movers and machines not running, and
// `pipeline-wanted` says outcome tier-late; once every tier runs it says outcome running and the key goes (H-A-75). tier-late
// clears when the late movers run or a later passed pipeline moves them (H-A-56).
// tierPrefix starts the key of a pipeline's tier progress in the state written.
const tierPrefix = "pipeline."
// kindTierLate is the finding of a tier not running within tier-bound (design 47 H §751).
const kindTierLate = "tier-late"
// defaultTierBound is tier-bound's default, 30 minutes (design 47 H §751).
const defaultTierBound = 30 * time.Minute
// tierMover is one mover of a passed pipeline whose version the state written keeps: its module, fingerprint and tier.
type tierMover struct {
Module string `json:"module"`
Fp string `json:"fp"`
Tier int64 `json:"tier"`
// NoVersion is a passed mover whose version is not yet written: its tier does not run until it is (H-A-277 (1)).
NoVersion bool `json:"no-version,omitempty"`
}
// tierProgress is a pipeline's tier progress (H-A-56): the tier whose wants are written, since when, the movers, and the source
// revision its pipeline-ended names, said in pipeline-wanted beside the key's revision (design 47 H-A-214, H-A-216); zero in a
// value kept before the field, read as the key's number.
type tierProgress struct {
Tier int64 `json:"tier"`
Since time.Time `json:"since"`
Movers []tierMover `json:"movers"`
Source int64 `json:"source,omitempty"`
}
// tierKey is the key of pipeline's tier progress; pipeline is the runner's key `<branch>.<source>`, its branch escaped.
func tierKey(pipeline string) string { return tierPrefix + pipeline }
// isTierKey says whether a key of the state written is a pipeline's tier progress: three parts, the first `pipeline` (a module's
// end has two).
func isTierKey(key string) bool {
return strings.HasPrefix(key, tierPrefix) && strings.Count(key, ".") == 2
}
// startTiers writes the tier progress of a passed pipeline, holding every passed mover, versioned or not, its first tier the
// lowest of theirs, since now (H-A-277 (1)). A pipeline heard again adds to the progress that stands each mover it does not hold,
// at the mover's tier, and marks versioned each held mover whose version is now written (H-A-270, H-A-273): its want is written
// when the progress reaches its tier, or at once when that tier ran already, never out of tier order.
func (e *pipelineEnds) startTiers(pipeline string, source int64, movers []tierMover, versioned map[string]bool) error {
for {
t, rev, ok := e.tiersOf(pipeline)
if !ok {
if len(movers) == 0 {
return nil
}
first := movers[0].Tier
for _, m := range movers {
first = min(first, m.Tier)
}
t = tierProgress{Tier: first, Since: e.clock().UTC(), Source: source}
}
moved := false
for i := range t.Movers {
if t.Movers[i].NoVersion && versioned[t.Movers[i].Module] {
t.Movers[i].NoVersion, moved = false, true
}
}
for _, m := range movers {
if !slices.ContainsFunc(t.Movers, func(h tierMover) bool { return h.Module == m.Module }) {
t.Movers, moved = append(t.Movers, m), true
}
}
if !moved {
return nil
}
value, err := json.Marshal(t)
if err != nil {
return err
}
err = e.st.swap(tierKey(pipeline), value, rev)
if errors.Is(err, errSwapped) {
if _, _, held := e.tiersOf(pipeline); !ok && !held {
return nil // a key that stands but does not read is left as it is
}
continue
}
if err == nil && ok {
e.logf("pipeline %s: a mover whose version came after its end is taken into the tier progress", pipeline)
}
return err
}
}
func (e *pipelineEnds) clock() time.Time {
if e.now != nil {
return e.now()
}
return time.Now()
}
// tiersOf is the tier progress of pipeline, with its revision; false when none stands.
func (e *pipelineEnds) tiersOf(pipeline string) (tierProgress, uint64, bool) {
raw, rev, err := e.st.get(tierKey(pipeline))
var t tierProgress
if err != nil || raw == nil || json.Unmarshal(raw, &t) != nil {
return tierProgress{}, 0, false
}
return t, rev, true
}
// tierWritten says whether the want of an end may be written: its pipeline's tier progress reached the end's rank, or no
// progress stands for its pipeline (every tier ran).
func (e *pipelineEnds) tierWritten(end End) bool {
t, _, ok := e.tiersOf(end.Pipeline)
return !ok || end.Rank <= t.Tier
}
// tierBound is the setting tier-bound; zero or less is its default.
func (p *passer) tierBoundOf() time.Duration {
if p.tierBound > 0 {
return p.tierBound
}
return defaultTierBound
}
// tiers moves each pipeline's tier progress (design 47 H §751): a tier whose placed movers all run on every present placing machine
// gives way to the next, the last to the end said `running`; a tier past tier-bound is late. placedOn is, by module, the nodes
// placing it on branch. It returns the earliest deadline still to come (zero: none), for one timer to wake the pass at.
func (p *passer) tiers(n assign.Nodes, placedOn func(module, branch string) []string) time.Time {
if p.ends == nil {
return time.Time{}
}
ks, err := p.ends.st.keys()
if err != nil {
p.logf("the tier progress cannot be listed: %v", err)
return time.Time{}
}
sort.Strings(ks)
now := p.clock().UTC()
bound := p.tierBoundOf()
var next time.Time
for _, key := range ks {
if !isTierKey(key) {
continue
}
pipeline := strings.TrimPrefix(key, tierPrefix)
branchEsc, number, _ := strings.Cut(pipeline, ".")
branch, err := keys.UnescapeName(branchEsc)
if err != nil {
continue
}
for {
t, rev, ok := p.ends.tiersOf(pipeline)
if !ok {
break
}
notRunning := p.notRunning(n, placedOn, pipeline, branch, t, t.Tier)
late := !now.Before(t.Since.Add(bound))
if late {
p.tierLate(pipeline, branch, number, t, notRunning)
break
}
if len(notRunning) > 0 {
if d := t.Since.Add(bound); next.IsZero() || d.Before(next) {
next = d
}
break
}
// The tier runs: the next tier's wants are written, or every tier ran.
later := int64(0)
for _, m := range t.Movers {
if m.Tier > t.Tier && (later == 0 || m.Tier < later) {
later = m.Tier
}
}
if later == 0 {
if err := p.ends.st.drop(key); err != nil {
p.logf("the tier progress %s is not deleted: %v", key, err)
break
}
p.sayPipelineWanted(pipeline, branch, number, t.Source, meshwants.PipelineWantedOutcomeRunning, nil)
break
}
value, err := json.Marshal(tierProgress{Tier: later, Since: now, Movers: t.Movers, Source: t.Source})
if err == nil {
err = p.ends.st.swap(key, value, rev)
}
if errors.Is(err, errSwapped) {
continue
}
if err != nil {
p.logf("the tier progress %s is not moved to tier %d: %v", key, later, err)
break
}
p.logf("pipeline %s: tier %d runs on every present placing machine, so tier %d's wants are written", pipeline, t.Tier, later)
}
}
return next
}
// notRunning is, of tier's movers in t whose kept end still names pipeline, those not running at their fingerprint on a present
// placing machine, with those machines. A mover a later pipeline moved counts as run; one placed nowhere counts as run.
func (p *passer) notRunning(n assign.Nodes, placedOn func(module, branch string) []string, pipeline, branch string, t tierProgress, tier int64) []meshwants.NotRunning {
var out []meshwants.NotRunning
for _, m := range t.Movers {
if m.Tier != tier {
continue
}
if m.NoVersion {
// A mover whose version is not yet written holds its tier, under the tier bound (H-A-277 (1)).
machines := []string{}
for _, node := range placedOn(m.Module, branch) {
if online, known := n.Online[node]; !known || online {
machines = append(machines, node)
}
}
sort.Strings(machines)
out = append(out, meshwants.NotRunning{Module: m.Module, Machines: machines})
continue
}
if end, ok := p.ends.endOf(m.Module, branch); !ok || end.Pipeline != pipeline {
continue // a later pipeline moved it
}
var machines []string
for _, node := range placedOn(m.Module, branch) {
if online, known := n.Online[node]; known && !online {
continue // a machine away is not waited for
}
r, ok := n.Running[node][m.Module]
if !ok || r.Stopped || r.Fingerprint != m.Fp {
machines = append(machines, node)
}
}
if len(machines) > 0 {
sort.Strings(machines)
out = append(out, meshwants.NotRunning{Module: m.Module, Machines: machines})
}
}
return out
}
// tierLate ends a pipeline's delivery at a tier past tier-bound: the finding tier-late is raised and pipeline-wanted says tier-late,
// once each; the finding clears once the late movers run or a later pipeline moved them. The progress stays, so no later tier is
// written, until no later tier's mover is kept at this pipeline any more.
func (p *passer) tierLate(pipeline, branch, number string, t tierProgress, notRunning []meshwants.NotRunning) {
o := tierLateFinding(pipeline, t.Tier, notRunning)
key := views.FindingKey(o.Scope, assign.KeyID(o.ID), o.Kind)
if len(notRunning) > 0 {
if !p.said[key+".raised"] {
if p.findings.Put != nil {
if err := p.findings.Put(o.Finding(p.clock())); err != nil {
p.logf("the finding %s is not written: %v", key, err)
return
}
}
p.said[key+".raised"] = true
delete(p.said, key+".cleared")
p.logf("pipeline %s: tier %d is late (tier-bound %s): %s; no later tier is written", pipeline, t.Tier, p.tierBoundOf(), o.Summary)
p.sayPipelineWanted(pipeline, branch, number, t.Source, meshwants.PipelineWantedOutcomeTierLate, notRunning)
}
} else if !p.said[key+".cleared"] {
if p.findings.Delete != nil {
if err := p.findings.Delete(key); err != nil {
p.logf("the finding %s is not deleted: %v", key, err)
return
}
}
p.said[key+".cleared"] = true
delete(p.said, key+".raised")
}
for _, m := range t.Movers {
if m.Tier <= t.Tier {
continue
}
if end, ok := p.ends.endOf(m.Module, branch); ok && end.Pipeline == pipeline {
return // a later tier's mover still kept at this pipeline: its want stays unwritten
}
}
if len(notRunning) == 0 {
if err := p.ends.st.drop(tierKey(pipeline)); err != nil {
p.logf("the tier progress of %s is not deleted: %v", pipeline, err)
}
}
}
// tierLateFinding is the finding tier-late of pipeline's tier, naming the movers and machines not running (design 47 H §751).
func tierLateFinding(pipeline string, tier int64, notRunning []meshwants.NotRunning) assign.Observed {
var named []string
for _, nr := range notRunning {
named = append(named, fmt.Sprintf("%s on %s", nr.Module, strings.Join(nr.Machines, ", ")))
}
summary := fmt.Sprintf("pipeline %s: tier %d does not run within tier-bound: %s", pipeline, tier, strings.Join(named, "; "))
return assign.Observed{Scope: mcc.ScopeDelivery, ID: pipeline, Kind: kindTierLate, Severity: mcseat.FindingSeverityWarning,
Summary: summary, Headline: "A delivery's tier does not run in time",
Explanation: summary + ". The assigner writes no later tier of this pipeline; the delivery ends here.",
Source: "assigner." + kindTierLate}
}
// sayPipelineWanted says the seat mesh-wants' pipeline-wanted of pipeline, once (its id the pipeline and the outcome): its
// revision the number of the pipeline's key `<branch>.<revision>`, its source the one the pipeline-ended named (design 47
// H-A-214, H-A-216), the key's number for a progress kept before it held one.
func (p *passer) sayPipelineWanted(pipeline, branch, number string, source int64, outcome string, notRunning []meshwants.NotRunning) {
var revision int64
_, _ = fmt.Sscan(number, &revision)
if source <= 0 {
source = revision
}
body := meshwants.PipelineWantedEvent{V: keys.Version, Pipeline: pipeline, Branch: branch, Source: source, Revision: revision, Outcome: outcome, NotRunning: notRunning}
event := meshwants.EventPipelineWanted + "." + pipeline
if err := p.wantsSay(event, body, "pipeline-wanted."+pipeline+"."+outcome); err != nil {
p.logf("pipeline-wanted of %s is not said: %v", pipeline, err)
}
}
// tierDeadline sets the one timer that wakes the pass at the earliest tier's deadline (H-A-56); zero stops it.
func (p *passer) tierDeadline(at time.Time) {
if p.tierWake == nil {
return
}
if p.tierTimer != nil {
p.tierTimer.Stop()
}
if at.IsZero() {
return
}
p.tierTimer = time.AfterFunc(max(at.Sub(p.clock()), 0), p.tierWake)
}
// tierBoundSetting is the setting tier-bound in minutes (design 47 H §751), read at the start from the file the manifest declares
// with the content ${config:tier-bound}; zero, its default, for a file missing or empty.
func tierBoundSetting(getenv func(string) string) (time.Duration, error) {
minutes, err := settingFile(getenv("MESH_ASSIGNER_TIER_BOUND_FILE"))
return time.Duration(minutes) * tierBoundUnit, err
}
// tierBoundUnit is the unit of the setting tier-bound, a minute; the whole test sets a shorter one, so a tier passes its bound
// without a test waiting minutes.
var tierBoundUnit = time.Minute
@@ -0,0 +1,210 @@
package main
import (
"context"
"encoding/json"
"strings"
"testing"
"time"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
mcseat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
mwc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
mpr "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/views"
"mesh-delivery-assigner/internal/assign"
"mesh-delivery-assigner/internal/buckets"
)
// A7/AC1, A7/AC2 (design 47 H §751, H-A-56): a pipeline of a provider (tier 1) and its consumer (tier 2) writes the provider's
// wants first and the consumer's only once the provider runs at its fingerprint on every present placing machine (one machine
// away is not waited for), then says pipeline-wanted running and drops its progress; a provider that never runs is late at
// tier-bound: the finding tier-late names it and its machine, pipeline-wanted says tier-late, and no consumer want is written.
func TestAPipelinesWantsAreWrittenTierByTier(t *testing.T) {
db, web := meshcatalogclient.SourcePrefix2+strings.Repeat("d", 64), meshcatalogclient.SourcePrefix2+strings.Repeat("c", 64)
for _, runs := range []bool{true, false} {
start := time.Date(2026, 11, 20, 4, 0, 0, 0, time.UTC)
now := start
wantsKV := &memKV{values: map[string][]byte{}}
p := newPasser(kvSet{buckets.Wants(): wantsKV, buckets.Asks(): &memKV{values: map[string][]byte{}}}, start)
p.now = func() time.Time { return now }
p.say = func(oc.Condition) error { return nil }
findings := map[string]mcseat.Finding{}
p.findings = assign.Findings{Put: func(f mcseat.Finding) error { findings[views.FindingKey(f.Scope, f.ID, f.Kind)] = f; return nil },
Delete: func(key string) error { delete(findings, key); return nil }}
var said []meshwants.PipelineWanted
p.publishWants = func(event string, body any, _ string) error {
if b, ok := body.(meshwants.PipelineWantedEvent); ok {
if event != "pipeline-wanted."+trunkBranch+".5" {
t.Errorf("pipeline-wanted said as %s", event)
}
said = append(said, b)
}
return nil
}
for i, m := range []struct{ name, fp string }{{"db", db}, {"web", web}} {
digest := strings.Repeat(string(rune('e'+i)), 64)
mod, _ := meshcatalogclient.EncodeModule(meshcatalog.ModulesByModuleValue{Fp2: m.fp, Manifest: digest, Repository: "novox/" + m.name, Commit: strings.Repeat("1", 40), Path: meshcatalogclient.RootPath})
putModuleRaw(p.w, trunkBranch, m.name, mod)
p.w.manifests[digest] = parsed{module: m.name, manifest: catalogue.Manifest{Module: m.name}}
}
placeOn(t, p.w, "g14", "db", "web")
placeOn(t, p.w, "ace", "db", "web")
p.w.heardPresence("ace", true, start) // away: not waited for
p.w.mu.Lock()
p.w.runningHeard = true
p.w.mu.Unlock()
p.ends = newPipelineEnds(newMemEnds(), func() {}, t.Logf)
p.ends.trunk, p.ends.now = p.w.trunkName, func() time.Time { return now }
// The pipeline of revision 5 (its key's number) of source 4: a re-pin's revision (H-A-213, H-A-216).
e := ended(trunkBranch, 5, mpr.PipelineEndedOutcomePassed, mover("db", db, "0.2.0", 1, mpr.StepResultOutcomePassed),
mover("web", web, "0.1.2", 2, mpr.StepResultOutcomePassed))
e.Source = 4
if _, err := p.ends.take(e); err != nil {
t.Fatal(err)
}
wanted := func(node, module string) bool {
key, _ := mwc.WantKey(node, module)
_, ok := wantsKV.values[key]
return ok
}
p.wants(context.Background())
if !wanted("g14", "db") || !wanted("ace", "db") || wanted("g14", "web") || wanted("ace", "web") {
t.Fatalf("runs %v: tier 1 alone is not what is wanted first: %v", runs, wantsKV.values)
}
if runs {
raw, _ := json.Marshal(nodeengine.Running{Node: "g14", Module: "db", Fingerprint: db})
if err := p.w.hearRunning("running.g14.db", raw); err != nil {
t.Fatal(err)
}
now = start.Add(time.Minute)
p.wants(context.Background())
if !wanted("g14", "web") || !wanted("ace", "web") {
t.Fatalf("the consumer's want is not written once its provider runs: %v", wantsKV.values)
}
raw, _ = json.Marshal(nodeengine.Running{Node: "g14", Module: "web", Fingerprint: web})
_ = p.w.hearRunning("running.g14.web", raw)
p.wants(context.Background())
if len(said) != 1 || said[0].Outcome != meshwants.PipelineWantedOutcomeRunning || said[0].Revision != 5 || said[0].Source != 4 || len(findings) != 0 {
t.Errorf("every tier runs: said %+v, findings %v", said, findings)
}
if _, _, ok := p.ends.tiersOf(trunkBranch + ".5"); ok {
t.Error("the tier progress stands after every tier ran")
}
continue
}
now = start.Add(29 * time.Minute)
p.wants(context.Background())
if len(findings) != 0 || len(said) != 0 {
t.Fatalf("late before tier-bound: %v, %+v", findings, said)
}
now = start.Add(30 * time.Minute)
p.wants(context.Background())
p.wants(context.Background())
f, ok := findings["delivery."+assign.KeyID(trunkBranch+".5")+".tier-late"]
if !ok || !strings.Contains(f.Summary, "db on g14") || strings.Contains(f.Summary, "ace") {
t.Errorf("tier-late is not raised naming db on g14 alone: %v", findings)
}
if len(said) != 1 || said[0].Outcome != meshwants.PipelineWantedOutcomeTierLate || len(said[0].NotRunning) != 1 || said[0].NotRunning[0].Module != "db" ||
said[0].Revision != 5 || said[0].Source != 4 {
t.Errorf("pipeline-wanted tier-late is not said once, naming revision 5 of source 4: %+v", said)
}
// A tier progress kept before it held its source says the key's number as both (H-A-216).
p.sayPipelineWanted(trunkBranch+".5", trunkBranch, "5", 0, meshwants.PipelineWantedOutcomeRunning, nil)
if len(said) != 2 || said[1].Revision != 5 || said[1].Source != 5 {
t.Errorf("a progress with no source: said %+v, want revision and source 5", said)
}
if wanted("g14", "web") || wanted("ace", "web") {
t.Error("a consumer's want is written after its provider's tier was late")
}
}
}
// H-A-270, H-A-273, H-A-277 (1): a pipeline's tier progress holds every passed mover, versioned or not, and a tier with a mover
// whose version is not yet written does not run until it is: no later tier is wanted out of order. When the lowest tier's version
// comes last, nothing is wanted before it; with db (1) and api (3) versioned and web (2) late, api is wanted only once web runs.
func TestALateMoverHoldsItsTier(t *testing.T) {
type step struct {
versions map[string]string // a pipeline-ended taken, each mover's version ("": none yet)
runs string // or: this module runs on g14
wanted string // then: the modules wanted, in order of the list
}
for _, c := range []struct {
name string
steps []step
}{
{"the lowest tier's version comes last", []step{
{versions: map[string]string{"db": "", "web": "0.1.2", "api": "0.3.0"}, wanted: ""},
{versions: map[string]string{"db": "0.2.0", "web": "0.1.2", "api": "0.3.0"}, wanted: "db"},
{runs: "db", wanted: "db,web"},
{runs: "web", wanted: "db,web,api"},
}},
{"a middle tier's version comes late", []step{
{versions: map[string]string{"db": "0.2.0", "web": "", "api": "0.3.0"}, wanted: "db"},
{runs: "db", wanted: "db"},
{versions: map[string]string{"db": "0.2.0", "web": "0.1.2", "api": "0.3.0"}, wanted: "db,web"},
{runs: "web", wanted: "db,web,api"},
}},
} {
t.Run(c.name, func(t *testing.T) {
fps := map[string]string{}
tiers := map[string]int64{"db": 1, "web": 2, "api": 3}
for i, m := range []string{"db", "web", "api"} {
fps[m] = meshcatalogclient.SourcePrefix2 + strings.Repeat(string(rune('a'+i)), 64)
}
start := time.Date(2026, 11, 21, 4, 0, 0, 0, time.UTC)
now := start
wantsKV := &memKV{values: map[string][]byte{}}
p := newPasser(kvSet{buckets.Wants(): wantsKV, buckets.Asks(): &memKV{values: map[string][]byte{}}}, start)
p.now = func() time.Time { return now }
p.say = func(oc.Condition) error { return nil }
p.publishWants = func(string, any, string) error { return nil }
for i, m := range []string{"db", "web", "api"} {
digest := strings.Repeat(string(rune('1'+i)), 64)
mod, _ := meshcatalogclient.EncodeModule(meshcatalog.ModulesByModuleValue{Fp2: fps[m], Manifest: digest, Repository: "novox/" + m, Commit: strings.Repeat("1", 40), Path: meshcatalogclient.RootPath})
putModuleRaw(p.w, trunkBranch, m, mod)
p.w.manifests[digest] = parsed{module: m, manifest: catalogue.Manifest{Module: m}}
}
placeOn(t, p.w, "g14", "db", "web", "api")
p.w.mu.Lock()
p.w.runningHeard = true
p.w.mu.Unlock()
p.ends = newPipelineEnds(newMemEnds(), func() {}, t.Logf)
p.ends.trunk, p.ends.now = p.w.trunkName, func() time.Time { return now }
for i, s := range c.steps {
if s.versions != nil {
var movers []mpr.MoverEnded
for _, m := range []string{"db", "web", "api"} {
movers = append(movers, mover(m, fps[m], s.versions[m], tiers[m], mpr.StepResultOutcomePassed))
}
if _, err := p.ends.take(ended(trunkBranch, 5, mpr.PipelineEndedOutcomePassed, movers...)); err != nil {
t.Fatal(err)
}
} else {
raw, _ := json.Marshal(nodeengine.Running{Node: "g14", Module: s.runs, Fingerprint: fps[s.runs]})
if err := p.w.hearRunning("running.g14."+s.runs, raw); err != nil {
t.Fatal(err)
}
}
now = now.Add(time.Minute)
p.wants(context.Background())
var got []string
for _, m := range []string{"db", "web", "api"} {
key, _ := mwc.WantKey("g14", m)
if _, ok := wantsKV.values[key]; ok {
got = append(got, m)
}
}
if strings.Join(got, ",") != s.wanted {
t.Fatalf("step %d: wanted %v, want %q", i+1, got, s.wanted)
}
}
})
}
}
@@ -1,7 +1,6 @@
package main
import (
mma "git.novox.be/novox/mesh-contracts/go/seats/meshmoduleassigner"
plc "mesh-delivery-assigner/internal/assignment"
"encoding/json"
@@ -22,13 +21,11 @@ import (
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/catalogkey"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/process"
"git.novox.be/novox/mesh-sdk/go/seatlist"
"git.novox.be/novox/mesh-sdk/go/stateobjects"
"mesh-delivery-assigner/internal/buckets"
"git.novox.be/novox/mesh-contracts/go/clients/nodeengineclient/enginereads"
)
// The assigner's tools (novox/hq ADR 0546), served through the tool runner from its bundle: a process never serves (ADR
@@ -36,9 +33,6 @@ import (
// every step as the event put. They are the module's own tools; the seat mesh-module-assigner's verbs are served beside them
// (seat_tools.go, ADR 0567 §10).
// engineReadsTool lists what each node's engine reads, as the assigner uses it, and asks one node's engine again.
const engineReadsTool = "assigner_engine_reads"
// putsState is the assigner's state of puts, as the runtime names a module's own state.
const putsState = "puts"
@@ -215,12 +209,6 @@ func (s *putTools) doRelease(args map[string]any, by string) (any, error) {
if arg(args, "how") != "" {
return s.doReleaseWait(args, by) // a wait on an outside cause (outside_tools.go, design 47 G §706)
}
if step := arg(args, "step"); step != "" {
if step != meshwants.WaitStepDelivery {
return nil, fmt.Errorf("step is %s, the one wait released by its step, not %q", meshwants.WaitStepDelivery, step)
}
return s.doReleaseDelivery(args, by) // a dependent's delivery wait (delivered.go, design 47 G §376, A-246)
}
node, module, why := arg(args, "node"), arg(args, "module"), arg(args, "why")
key, err := puts.Key(node, module)
if err != nil {
@@ -353,12 +341,10 @@ func (s *putTools) tools() []stdio.Tool {
"rules write the machine's want again from their next pass. Nothing changes on the machine until they move it.",
Input: schema(map[string]string{"node": "the machine", "module": "the module", "why": "why, kept with the put",
"how": "with how, the wait of the delivery on an outside cause (assigner_waits) is released, not a put: go-on (the module counts healthy there), " +
"failed (the failing check is the delivery's), rejudge (judge it again now), or now (the entry waiting for an acting part's new version moves with the running one); written in the hand-act log first",
"step": "delivery: the module's wait for its dependency's delivery (assigner_waits) is released, its want written now; no machine is named; written in the hand-act log first"},
"failed (the failing check is the delivery's), or rejudge (judge it again now); written in the hand-act log first"},
[]string{"module", "why"}),
Run: func(a map[string]any) (any, error) { return s.doRelease(a, stdio.CallerOf(a)) }},
s.waitsTool(),
s.deliveredAgainTool(),
{Name: toolPuts, Description: "Every put and where it stands (novox/hq ADR 0546): its version, hold, why, each step with " +
"its time and words. Narrowed by machine or module. Read-only.",
Input: schema(map[string]string{"node": "one machine", "module": "one module"}, nil),
@@ -403,7 +389,7 @@ func serveTools() error {
}
}()
// The seat list (seatlist.go), read through the runtime once Serve has its channel: the seat's verbs judge by it.
gate := seatlist.NewPart("assigner", seatListAgainCallers)
gate := seatlist.NewPart("assigner")
go func() {
<-stdio.Served()
gate.Follow(seatlist.StdioBus(), nil, func(f string, a ...any) { fmt.Fprintf(os.Stderr, "mesh-delivery-assigner: "+f+"\n", a...) })
@@ -417,17 +403,23 @@ func serveTools() error {
return stdio.SeatPublish(wantsEventSubject(e), b, id)
})
wants.watched = stdio.NewWatchedStates() // the large states read whole from one watched copy (ADR 0580 clause 3)
// The callers' seat entries are resolved from the assigner's own seat-holders, its watched copy (A-298).
gate.Holders(seatlist.HoldersIn(func() (map[string][]byte, error) { return wants.watched.Values(mma.StateSeatHolders) }))
// The verb assignments with seats answers from the same watched copy, so every caller of it is fast too (issue 1982).
seatVerbs.watched = wants.watched
wants.revisions = runtimeObjects{busstate.ObjectsOf(assigngraph.RevisionsObjects)}
tools = append(tools, wants.tools()...)
tools = append(tools, inputsRead(&inputKeeper{vals: stateobjects.ForState(buckets.InputsState), now: time.Now, logf: func(string, ...any) {}}))
keeper := &inputKeeper{vals: stateobjects.ForState(buckets.InputsState), now: time.Now, logf: func(string, ...any) {}}
tools = append(tools, inputsRead(keeper), inputsDrop(keeper, stdio.Ask))
tools = append(tools, compositionsTools(stdio.Ask)...) // the composition runs' read and drop, through their verbs (§728)
tools = append(tools, viewTools(os.Getenv, keptSource, time.Now)...)
// What each node's engine reads, as the assigner uses it (ADR 0618 §3): its own state engine-reads, asked again through it.
tools = append(tools, enginereads.Tool(engineReadsTool, "the assigner", enginereads.KeptState(stdio.State(engineReadsState)), false, time.Now))
// What each node's engine reads, as the assigner uses it: its own state engine-reads (design 47 H-A-104).
tools = append(tools, engineReadsTools(runtimeStore{})...)
tools = append(tools, writtenTools(runtimeStore{})...)
tools = append(tools, pinsTools(runtimeStore{}, stdio.Ask)...)
tools = append(tools, whyTools(runtimeStore{})...)
tools = append(tools, askAgainTools(runtimeStore{}, stdio.Ask, time.Now)...)
tools = append(tools, wantDropTools(runtimeStore{}, stdio.Ask)...)
tools = append(tools, asksTools(stdio.QueueWaiting, stdio.State(process.TakenState), stdio.Ask)...) // the seat's work queue (§777)
tools = append(tools, keepNowTools(stdio.Ask)...)
tools = append(tools, validateBeforeTools(runtimeStore{})...) // what a validate step did not count (§814) // the keeping by hand (§813 (2))
return stdio.Serve("", tools)
}
@@ -0,0 +1,493 @@
package main
import (
"context"
"crypto/rand"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"maps"
"slices"
"strings"
mcc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
meshcatalog "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/composer"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/graph"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/process"
"mesh-delivery-assigner/internal/buckets"
)
// The step validate (design 47 H §745; H-A-34, H-A-51, H-A-108): the assigner serves it as an accepted kind `step` of the seat
// mesh-wants, asked by the runner for each mover before its composition step. One run per take-in revision, a key
// `<pipeline>.validate` of the state composition-runs in the CompositionRun form with no machine, which every mover's step
// reads: the cycle the revision's entries make (graph.RefusedCycle) ends it at once; else the manifest validator built from
// the revision's own entry of the module holding the seat mesh-catalog, on the Go build seat as the composer is, runs in the
// sandbox over the revision's manifests and its base's (H-A-154), its input kept and served on mesh-wants' input.
// Every mover's step ends the same: failed `cycle` naming the cycle, failed `manifest-refused` naming every problem the case
// before does not hold (design 47 H2 §814; assigner_validate_before answers the ones it holds), or passed.
const (
// validatorPackage is the manifest validator's import path in the module holding the seat mesh-catalog (the indexer's
// cmd/mesh-judge, design 47 H-A-34).
validatorPackage = "mesh-delivery-indexer/cmd/mesh-judge"
// validateKeySuffix ends the key of a revision's validate run, `<pipeline>.validate` (H-A-108).
validateKeySuffix = "." + meshwants.StepRunStepValidate
// beforeCase is the validator's case of the revision's base, beside changeCase (H-A-108 (3), H-A-151, H-A-154).
beforeCase = "before"
// The reasons a validate step fails with, the first word of its said (§745).
reasonManifestRefused = "manifest-refused"
reasonCycle = "cycle"
// betweenManifests is the validator's name for what it judges between manifests (the catalogue as a whole).
betweenManifests = "(between manifests)"
)
// validateKeyOf is the key of the validate run of the step's take-in revision.
func validateKeyOf(step meshwants.StepRun) (string, error) {
if step.Pipeline == "" {
return "", errors.New("the step names no pipeline, so no validate run is named")
}
return step.Pipeline + validateKeySuffix, nil
}
// isValidateRun says whether a run of the state is a revision's validate run: one with no machine.
func isValidateRun(run meshwants.CompositionRun) bool { return run.Machine == "" }
// validate runs one mover's validate step: it joins or starts the revision's validate run and judges the step from its end.
func (r *compositionRun) validate(ctx context.Context, id string, step meshwants.StepRun) stepOutcome {
key, err := validateKeyOf(step)
if err != nil {
return couldNotRun(err.Error())
}
candidate, err := candidateKeyOf(step)
if err != nil {
return couldNotRun(err.Error())
}
j, err := r.runs.joinAt(key, readerOf(id, step), candidate, "", buildstep.NewID())
if err != nil {
return couldNotRun("the validate run " + key + " is not joined: " + err.Error())
}
if j.started {
go r.startValidate(ctx, key, j.run, step)
}
return r.readValidate(ctx, key, step)
}
// resumeValidate judges a validate step taken up at the assigner's start from its revision's run.
func (r *compositionRun) resumeValidate(ctx context.Context, _ string, step meshwants.StepRun) stepOutcome {
key, err := validateKeyOf(step)
if err != nil {
return couldNotRun(err.Error())
}
return r.readValidate(ctx, key, step)
}
// readValidate waits for the end of the validate run of key and judges the step from it.
func (r *compositionRun) readValidate(ctx context.Context, key string, step meshwants.StepRun) stepOutcome {
setShared(ctx, r.runs.sharedOf([]string{key}, nil))
setPhase(ctx, meshwants.StepProgressEventPhaseRun)
run := r.runs.await(ctx, []string{key})[key]
setPhase(ctx, meshwants.StepProgressEventPhaseReport)
out := r.judgeValidate(ctx, step, run)
out.Shared = r.runs.sharedOf([]string{key}, map[string]meshwants.CompositionRun{key: run})
return out
}
// judgeValidate is a step's end from its revision's validate run: could not run with the run's words; failed `cycle` naming
// the cycle; failed `manifest-refused` naming every problem the revision causes; else passed.
func (r *compositionRun) judgeValidate(ctx context.Context, step meshwants.StepRun, run meshwants.CompositionRun) stepOutcome {
if run.Ended == nil {
return couldNotRun("the step stopped before its validate run ended")
}
if run.Outcome != meshwants.CompositionRunOutcomePassed {
return couldNotRun(run.Said)
}
var v validateVerdict
if raw, err := json.Marshal(run.Verdict); err != nil || json.Unmarshal(raw, &v) != nil {
return couldNotRun("the validate run's verdict does not read")
}
if len(v.Cycle) > 0 {
return stepOutcome{Outcome: meshwants.StepEndedOutcomeFailed, Said: reasonCycle + ": " + cycleWords(v.Cycle)}
}
half, err := r.revision(ctx, step)
if err != nil {
return couldNotRun("the step's catalog revision is not read: " + err.Error())
}
// A revision that names no base (the branch's first take-in) is judged against an empty case before, and says so (H-A-151).
empty := ""
if half.Revision.Base <= 0 {
empty = emptyBeforeWords
}
if problems := causedProblems(v.Change, v.Before); len(problems) > 0 {
said := reasonManifestRefused + ": " + strings.Join(problems, "; ")
if empty != "" {
said += " (" + empty + ")"
}
return stepOutcome{Outcome: meshwants.StepEndedOutcomeFailed, Said: said}
}
return stepOutcome{Outcome: meshwants.StepEndedOutcomePassed, Said: empty}
}
// emptyBeforeWords say, in a validate step's end, that its revision names no base: the branch's first take-in, judged against
// an empty case before (H-A-151, H-A-154).
const emptyBeforeWords = "the case before is empty: the revision names no base, the branch's first take-in"
// validateVerdict is a validate run's verdict as the run keeps it: the cycle the revision makes, or the validator's two cases.
type validateVerdict struct {
Cycle []meshcatalog.ArtifactRef `json:"cycle,omitempty"`
Change composer.CaseVerdict `json:"change"`
Before composer.CaseVerdict `json:"before"`
}
// asVerdict is v as a run's verdict.
func (v validateVerdict) asVerdict() (map[string]any, error) {
raw, err := json.Marshal(v)
if err != nil {
return nil, err
}
var out map[string]any
return out, json.Unmarshal(raw, &out)
}
// cycleWords names a cycle as the artifacts it passes through.
func cycleWords(cycle []meshcatalog.ArtifactRef) string {
words := make([]string, len(cycle))
for i, a := range cycle {
words[i] = string(a)
}
return strings.Join(words, " → ")
}
// before is the case before of the step's revision half: the revision its base names, the newest kept revision below it that
// its take-in pinned, read through the seat mesh-catalog's verb revision (H-A-108 (3), H-A-151, H-A-154); empty where the
// revision names no base, the branch's first take-in.
func (r *compositionRun) before(ctx context.Context, step meshwants.StepRun, half mcc.Half) (mcc.Half, error) {
if half.Revision.Base <= 0 {
return mcc.Half{Entries: map[string]meshcatalog.CatalogEntry{}}, nil
}
base := step
base.Revision = half.Revision.Base
return r.revision(ctx, base)
}
// causedProblems are the problems the revision causes (ADR 0578 §2; design 47 H2 §814): of every manifest, and between
// manifests, each problem the case before did not have; a problem the case before holds is never counted, whether the
// revision alters that manifest or not (assigner_validate_before answers those).
func causedProblems(change, before composer.CaseVerdict) []string {
return problemsBy(change, before, false)
}
// uncountedProblems are the change case's problems the case before holds too, which causedProblems does not count (§814).
func uncountedProblems(change, before composer.CaseVerdict) []string {
return problemsBy(change, before, true)
}
// problemsBy are the change case's problems, per manifest, that the case before had (had) or did not have (!had).
func problemsBy(change, before composer.CaseVerdict, had bool) []string {
var out []string
for _, module := range slices.Sorted(maps.Keys(change.Manifests)) {
read := change.Manifests[module]
if read.Accepted || read.Refused == "" {
continue
}
held := map[string]bool{}
for _, p := range strings.Split(before.Manifests[module].Refused, "\n") {
held[p] = true
}
var named []string
for _, p := range strings.Split(read.Refused, "\n") {
if p != "" && held[p] == had {
named = append(named, p)
}
}
if len(named) == 0 {
continue
}
what := module
if module == betweenManifests {
what = "between manifests"
}
out = append(out, what+": "+strings.Join(named, "; "))
}
return out
}
// catalogEntry is the entry of the module that holds the seat mesh-catalog, or false.
func catalogEntry(entries map[string]meshcatalog.CatalogEntry) (meshcatalog.CatalogEntry, bool) {
for _, name := range slices.Sorted(maps.Keys(entries)) {
for _, s := range entries[name].Serves {
if strings.HasPrefix(strings.TrimPrefix(s, "seat:"), meshcatalog.Seat+".") {
return entries[name], true
}
}
}
return meshcatalog.CatalogEntry{}, false
}
// manifestsOf are the half's manifests whole, as the validator's case holds them.
func manifestsOf(half mcc.Half) (map[string]composer.Manifest, error) {
out := map[string]composer.Manifest{}
for name, e := range half.Entries {
if len(e.Manifest) == 0 {
continue
}
raw, err := json.Marshal(e.Manifest)
if err != nil {
return nil, fmt.Errorf("the manifest of %s cannot be encoded: %w", name, err)
}
out[name] = composer.Manifest{Raw: raw}
}
return out, nil
}
// startValidate runs the validate run the step started: the revision's cycle ends it at once; else the validator's request
// is kept once in `inputs`, its program and input recorded on the run, and one run ask put on the Go build seat. A fault ends
// the run could not run.
func (r *compositionRun) startValidate(ctx context.Context, key string, run meshwants.CompositionRun, step meshwants.StepRun) {
ask := run.Ask
end := func(outcome, said string, verdict map[string]any) {
if _, err := r.runs.endRun(key, ask, outcome, said, verdict); err != nil {
r.logf("the validate run %s is not ended: %v", key, err)
}
}
couldNot := func(said string) { end(meshwants.CompositionRunOutcomeCouldNotRun, said, nil) }
half, err := r.revision(ctx, step)
if err != nil {
couldNot("the step's catalog revision is not read: " + err.Error())
return
}
if cycle := graph.RefusedCycle(half.Entries); cycle != nil {
verdict, err := validateVerdict{Cycle: cycle}.asVerdict()
if err != nil {
couldNot(err.Error())
return
}
end(meshwants.CompositionRunOutcomePassed, "", verdict)
return
}
before, err := r.before(ctx, step, half)
if err != nil {
couldNot("the base of the case before is not read: " + err.Error())
return
}
entry, ok := catalogEntry(half.Entries)
if !ok {
couldNot(fmt.Sprintf("the catalog revision %d holds no module claiming the seat %s, so no manifest validator is built", half.Revision.Revision, meshcatalog.Seat))
return
}
program, err := programOfEntry(entry)
if err != nil {
couldNot(err.Error())
return
}
program.Package = validatorPackage
seats, list, err := r.validateSeats(ctx, ask, half.Revision.Definitions)
if err != nil {
couldNot(err.Error())
return
}
change, err := manifestsOf(half)
if err != nil {
couldNot(err.Error())
return
}
prior, err := manifestsOf(before)
if err != nil {
couldNot(err.Error())
return
}
// No predefined key list and no known package names until a design line names the verb that gives them (H-A-108 (2)).
req := composer.Request{V: composer.Version, Cases: []composer.Case{{Name: changeCase, Manifests: change}, {Name: beforeCase, Manifests: prior}},
Seats: seats, SeatList: list}
raw, err := json.Marshal(req)
if err != nil {
couldNot("its request cannot be encoded: " + err.Error())
return
}
digest, err := r.keeper.keep(ask, raw)
if err != nil {
couldNot("its request is not kept: " + err.Error())
return
}
ref, err := buildstep.RunInputOf(inputVerbKey, raw)
if err != nil {
couldNot(err.Error())
return
}
if _, _, err := r.runs.change(key, func(c *meshwants.CompositionRun) bool {
if c.Ask != ask || c.Ended != nil {
return false
}
c.Program = &meshwants.CompositionRunProgram{Repository: program.Repository, Commit: program.Commit, Directory: program.Dir, Fingerprint: entry.Fp}
c.Input = digest
return true
}); err != nil {
couldNot("the run's program and input are not written: " + err.Error())
return
}
a := buildstep.StepAsk{ID: ask, Kind: buildstep.AskCheck, Language: buildstep.AskGo, Asker: runAsker, At: r.now().UTC(),
Run: &buildstep.RunJob{Program: program, Heads: []buildstep.RunHead{}, Input: ref, Reader: "the manifest validator of " + step.Pipeline + " at " + program.Commit},
Packages: pinsOfEntry(entry)} // the validator is built against its entry's pins at the step's revision (H-A-203, H-A-192, H-A-205)
if err := r.put(ctx, a); err != nil {
couldNot("its run ask " + ask + " is not put: " + err.Error())
}
}
// validateRunVerdict reads the validator's answer: its two cases as the run keeps them, or why it is none.
func validateRunVerdict(answer []byte) (map[string]any, string) {
var v composer.Verdict
if err := json.Unmarshal(answer, &v); err != nil {
return nil, "the manifest validator answered no verdict: " + err.Error()
}
if v.V != composer.Version {
return nil, fmt.Sprintf("the manifest validator answered a verdict of version %d, the assigner reads %d", v.V, composer.Version)
}
var out validateVerdict
found := 0
for _, c := range v.Cases {
switch c.Name {
case changeCase:
out.Change, found = c, found+1
case beforeCase:
out.Before, found = c, found+1
}
}
if found != 2 {
return nil, "the manifest validator's verdict does not hold both the cases " + changeCase + " and " + beforeCase
}
verdict, err := out.asVerdict()
if err != nil {
return nil, "the manifest validator's verdict cannot be kept: " + err.Error()
}
return verdict, ""
}
// validateBeforeTool is the tool that answers what a validate step did not count (design 47 H2 §814).
const validateBeforeTool = "assigner_validate_before"
// validateBefore answers, for the validate run of pipeline, the problems of the change case that its case before holds too,
// which the step did not count, for module alone when one is named; read from the run the state composition-runs keeps.
func validateBefore(st store, pipeline, module string) (map[string]any, error) {
key, err := validateKeyOf(meshwants.StepRun{Pipeline: strings.TrimSpace(pipeline)})
if err != nil {
return nil, err
}
raw, _, ok, err := st.get(buckets.CompositionRunsState, key)
if err != nil {
return nil, fmt.Errorf("the state %s is not read: %w", buckets.CompositionRunsState, err)
}
if !ok {
return nil, fmt.Errorf("no validate run %s is kept", key)
}
var run meshwants.CompositionRun
if err := json.Unmarshal(raw, &run); err != nil {
return nil, fmt.Errorf("the validate run %s does not read: %w", key, err)
}
var v validateVerdict
if b, err := json.Marshal(run.Verdict); err != nil || json.Unmarshal(b, &v) != nil {
return nil, fmt.Errorf("the validate run %s holds no verdict that reads", key)
}
change, before := v.Change, v.Before
if module = strings.TrimSpace(module); module != "" {
change = composer.CaseVerdict{Name: change.Name, Manifests: map[string]composer.ManifestRead{module: change.Manifests[module]}}
}
uncounted := uncountedProblems(change, before)
if uncounted == nil {
uncounted = []string{}
}
return map[string]any{"run": key, "outcome": run.Outcome, "uncounted": uncounted}, nil
}
// validateBeforeTools are the module's tool of the validate step's before case.
func validateBeforeTools(st store) []stdio.Tool {
return []stdio.Tool{{Name: validateBeforeTool, Description: "The problems a validate step did not count (design 47 H2 §814): of the " +
"validate run of a pipeline's take-in revision, every problem of the change case its case before holds too, per manifest, " +
"for one module when named. Read-only.",
Input: schema(map[string]string{"pipeline": "the pipeline's key, <branch>.<revision>", "module": "one module; absent: every one"}, []string{"pipeline"}),
Run: func(args map[string]any) (any, error) {
return validateBefore(st, arg(args, "pipeline"), arg(args, "module"))
}}}
}
// seatListKey is the seat mesh-catalog's chunked read verb seat-list (design 47 H2 §814, H-A-441, H-A-443).
const seatListKey = "seat:" + meshcatalog.Seat + "." + meshcatalog.VerbSeatList
// validateSeats are the seat definitions a validate run judges by, as one JSON array in composer.Request.Seats' form sorted by
// seat, and their digest, the sha256 of those bytes (H-A-441, H-A-443): a revision that names its own definitions keeps them,
// each read through seat-definitions; one that names none takes the trunk's seat list, the bytes the seat mesh-catalog's verb
// seat-list hands, asked as a kept call under the run's ask.
func (r *compositionRun) validateSeats(ctx context.Context, ask string, defs []meshcatalog.CatalogRevisionDefinitionsItem) ([]json.RawMessage, string, error) {
if len(defs) == 0 {
return r.seatList(ask)
}
sorted := slices.Clone(defs)
slices.SortStableFunc(sorted, func(a, b meshcatalog.CatalogRevisionDefinitionsItem) int { return strings.Compare(a.Seat, b.Seat) })
seats, err := r.seats(ctx, sorted)
if err != nil {
return nil, "", err
}
raw, err := json.Marshal(seats)
if err != nil {
return nil, "", fmt.Errorf("the revision's seat definitions cannot be encoded: %w", err)
}
var list []json.RawMessage
if err := json.Unmarshal(raw, &list); err != nil {
return nil, "", fmt.Errorf("the revision's seat definitions do not read again: %w", err)
}
return list, seatListDigest(raw), nil
}
// seatListDigest is the digest of a seat list's bytes, as the indexer names its object in seat-lists: the sha256, hex.
func seatListDigest(raw []byte) string {
sum := sha256.Sum256(raw)
return hex.EncodeToString(sum[:])
}
// seatList is the trunk's seat list as the verb seat-list hands it (H-A-443): its digest and size, then the object's bytes in
// chunks; bytes whose size or sha256 is not the answer's, or that are no JSON array, are refused, so every run of one digest
// judges the same bytes.
func (r *compositionRun) seatList(ask string) ([]json.RawMessage, string, error) {
what := "the trunk's seat list is not read through " + seatListKey
if r.callFile == nil {
return nil, "", errors.New(what + ": the assigner holds no chunked call")
}
var bits [16]byte
if _, err := rand.Read(bits[:]); err != nil {
return nil, "", fmt.Errorf("%s: %w", what, err)
}
raw, err := r.callFile(process.KeptAsk{ID: ask + "." + meshcatalog.VerbSeatList, Bound: readsBound}, seatListKey,
meshcatalog.SeatListInput{Call: hex.EncodeToString(bits[:])})
if err != nil {
return nil, "", fmt.Errorf("%s: %w", what, err)
}
var a struct {
meshcatalog.SeatListAnswer
File string `json:"file"`
}
if err := json.Unmarshal(raw, &a); err != nil {
return nil, "", fmt.Errorf("%s: its answer does not read: %w", what, err)
}
if a.Digest == "" {
return nil, "", errors.New(what + ": its answer names no digest")
}
file, err := base64.StdEncoding.DecodeString(a.File)
if err != nil {
return nil, "", fmt.Errorf("%s: the bytes received are not base64: %w", what, err)
}
if int64(len(file)) != a.Size || seatListDigest(file) != a.Digest {
return nil, "", fmt.Errorf("%s: %d bytes of digest %s were received, the answer names %d bytes of digest %s", what, len(file),
seatListDigest(file), a.Size, a.Digest)
}
var list []json.RawMessage
if err := json.Unmarshal(file, &list); err != nil || len(list) == 0 {
return nil, "", fmt.Errorf("%s: the seat list %s is no JSON array of seat definitions", what, a.Digest)
}
return list, a.Digest, nil
}
@@ -0,0 +1,220 @@
package main
import (
"context"
"encoding/base64"
"encoding/json"
"errors"
"slices"
"strings"
"sync"
"testing"
"time"
mcc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
meshcatalog "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/composer"
"git.novox.be/novox/mesh-sdk/go/process"
"mesh-delivery-assigner/internal/buckets"
)
// A10/AC1, A10/AC2 (design 47 H §745; H-A-34, H-A-51, H-A-108): every mover's validate step of one take-in reads one validate
// run, `<pipeline>.validate` of the state composition-runs; a manifest the revision alters that names an unknown field fails
// it `manifest-refused` naming the problem, a problem of a manifest it leaves as it was does not, and the validator is the
// revision's own entry of the module holding the seat mesh-catalog, on the Go build seat; a revision whose entries make a cycle
// fails it `cycle` naming the cycle, with no validator asked. The case before is the revision its base names (H-A-151, H-A-154:
// the newest kept below it, which the stand-in names as the indexer does); a revision naming no base, the branch's first take-in,
// is judged against an empty case before, said in its end, and no revision below it is asked.
func TestTheValidateStepRefusesAManifestProblemAndACycle(t *testing.T) {
indexer := meshcatalog.CatalogEntry{Module: "indexer", Repository: "novox/mesh-delivery", Commit: commitE3, Path: "modules/mesh-delivery-indexer",
Fp: "src2:ix", Serves: []string{"seat:" + meshcatalog.Seat + ".revision"}, Manifest: map[string]any{"module": "indexer"}, ManifestDigest: "d-ix",
Packages: map[string]string{"git.novox.be/novox/mesh-contracts/go/clients/meshmoduleassignerclient": "v0.1.4"}}
entry := func(module, digest string, edges ...meshcatalog.Edge) meshcatalog.CatalogEntry {
return meshcatalog.CatalogEntry{Module: module, Manifest: map[string]any{"module": module, "d": digest}, ManifestDigest: digest, Edges: edges}
}
revisions := map[int64][]meshcatalog.CatalogEntry{
6: {indexer, entry("web", "d-web-1"), entry("db", "d-db")},
7: {indexer, entry("web", "d-web-2"), entry("db", "d-db")},
9: {indexer, entry("a", "d-a", meshcatalog.Edge{From: "a:x", To: "b:y", Kind: 3}, meshcatalog.Edge{From: "b:y", To: "a:x", Kind: 3}), entry("b", "d-b")},
3: {indexer},
12: {indexer, entry("web", "d-web-2"), entry("db", "d-db")},
}
// base is the newest kept revision below n, as the take-in names it; none below the first. Revision 12 names 7 with 8 to 11
// never kept, so a case before read as the number minus one could not run (H-A-154).
base := func(n int64) (b int64) {
if n == 12 {
return 7
}
for k := range revisions {
if k < n && k > b {
b = k
}
}
return b
}
call := func(key string, body any) (json.RawMessage, error) {
raw, _ := json.Marshal(body)
switch key {
case mcc.RevisionVerb:
var in meshcatalog.RevisionInput
_ = json.Unmarshal(raw, &in)
entries, ok := revisions[in.Revision]
if !ok || in.Branch != "main" {
return nil, errors.New("asked another revision")
}
// Revision 3 names no definitions of its own: it is judged by the trunk's seat list, the bytes seat-list hands (H-A-443 (2)).
var defs []meshcatalog.CatalogRevisionDefinitionsItem
if in.Revision != 3 {
defs = []meshcatalog.CatalogRevisionDefinitionsItem{{Seat: "s1", Digest: "sd"}}
}
return json.Marshal(meshcatalog.RevisionAnswer{Revision: &meshcatalog.CatalogRevision{Revision: in.Revision, Base: base(in.Revision),
Definitions: defs}, Entries: entries})
case seatDefinitionsKey:
return json.Marshal(meshcatalog.SeatDefinitionsAnswer{Found: true, Entry: &meshcatalog.SeatDefinitionsAnswerEntry{Seat: "s1", Digest: "sd", Definition: map[string]any{"seat": "s1"}}})
}
return nil, errors.New("no such verb " + key)
}
// The trunk's seat list as the verb seat-list hands it (H-A-443 (1)): digest and size, then the bytes, which CallFileKept adds as file.
trunkList := []byte(`[{"seat":"a-seat"},{"seat":"s1","v":2}]`)
listAnswer := func(file []byte, digest string, size int) json.RawMessage {
raw, _ := json.Marshal(map[string]any{"digest": digest, "size": size, "chunks": 1, "file": base64.StdEncoding.EncodeToString(file)})
return raw
}
var listAsks []process.KeptAsk
listed := listAnswer(trunkList, seatListDigest(trunkList), len(trunkList))
callFile := func(ask process.KeptAsk, key string, body any) (json.RawMessage, error) {
in, _ := body.(meshcatalog.SeatListInput)
if key != seatListKey || len(in.Call) != 32 {
return nil, errors.New("asked " + key + " with the call " + in.Call)
}
listAsks = append(listAsks, ask)
return listed, nil
}
var mu sync.Mutex
var asks []buildstep.StepAsk
var requests []composer.Request
keeper := testKeeper(&objectsMem{objs: map[string][]byte{}}, time.Now)
runs := newCompositionRuns(newRunsMem(), defaultRunSettings, time.Now, t.Logf)
r := &compositionRun{runs: runs, keeper: keeper, reads: &compositionReads{}, call: call, callFile: callFile, now: time.Now, logf: t.Logf,
put: func(_ context.Context, a buildstep.StepAsk) error {
body, err := keeper.body(a.Run.Input.Digest)
if err != nil {
return err
}
req, err := composer.Decode(body)
if err != nil {
return err
}
mu.Lock()
asks, requests = append(asks, a), append(requests, req)
mu.Unlock()
answer, _ := json.Marshal(composer.Verdict{V: composer.Version, Cases: []composer.CaseVerdict{
{Name: changeCase, Manifests: map[string]composer.ManifestRead{"web": {Refused: "unknown field \"colour\"\nan inherited problem"}, "db": {Refused: "an old problem"}, "indexer": {Accepted: true}}},
{Name: beforeCase, Manifests: map[string]composer.ManifestRead{"db": {Refused: "an old problem"}, "web": {Refused: "an inherited problem"}}}}})
go func() {
if err := runs.heardEnd(buildstep.StepEnded{Asker: runAsker, Ask: a.ID, Outcome: buildstep.OutcomePassed, Node: "novox"},
func(buildstep.StepEnded) ([]byte, error) { return answer, nil }); err != nil {
t.Error(err)
}
}()
return nil
}}
steps := &compositionSteps{validate: r.validate, run: r.run}
if steps.howOf(meshwants.StepRunStepValidate, false) == nil || steps.howOf("check", false) != nil {
t.Error("the validate step is not taken, or another step is")
}
step := func(module string, revision int64) meshwants.StepRun {
return meshwants.StepRun{Step: meshwants.StepRunStepValidate, Pipeline: "main." + string(rune('0'+revision)), Branch: "main", Module: module,
Revision: revision, Source: revision}
}
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
outs := make([]stepOutcome, 2)
var wg sync.WaitGroup
for i, module := range []string{"web", "db"} {
wg.Add(1)
go func() { defer wg.Done(); outs[i] = r.validate(ctx, "ask-"+module, step(module, 7)) }()
}
wg.Wait()
for i, o := range outs {
if o.Outcome != meshwants.StepEndedOutcomeFailed || !strings.HasPrefix(o.Said, reasonManifestRefused+": ") || !strings.Contains(o.Said, `web: unknown field "colour"`) ||
strings.Contains(o.Said, "an old problem") || strings.Contains(o.Said, "an inherited problem") { // H2 §814: only new problems
t.Errorf("mover %d's validate step ended %+v", i, o)
}
}
// assigner_validate_before (H2 §814): the problems the before case holds, which the step did not count.
runsKV := memStore{buckets.CompositionRunsState: &memKV{values: map[string][]byte{}}}
kept, _, _, _ := runs.read("main.7" + validateKeySuffix)
runsKV[buckets.CompositionRunsState].values["main.7"+validateKeySuffix], _ = json.Marshal(kept)
before, err := validateBeforeTools(runsKV)[0].Run(map[string]any{"pipeline": "main.7", "module": "web"})
if b, _ := before.(map[string]any); err != nil || !slices.Equal(b["uncounted"].([]string), []string{"web: an inherited problem"}) {
t.Errorf("assigner_validate_before answered %+v, %v", before, err)
}
if _, err := validateBeforeTools(runsKV)[0].Run(map[string]any{"pipeline": "main.6"}); err == nil {
t.Error("assigner_validate_before answers a run not kept")
}
if len(asks) != 1 {
t.Fatalf("%d validator asks were put for one take-in, want 1", len(asks))
}
if p := asks[0].Run.Program; p.Commit != commitE3 || p.Dir != "modules/mesh-delivery-indexer" || p.Package != validatorPackage || len(asks[0].Run.Heads) != 0 {
t.Errorf("the validator is built from %+v", asks[0].Run)
}
// The validator is built against the indexer entry's pins at the step's revision (H-A-203, H-A-192, H-A-205).
if got := asks[0].Packages; len(got) != 1 || got["git.novox.be/novox/mesh-contracts/go/clients/meshmoduleassignerclient"] != "v0.1.4" {
t.Errorf("the validator is built against the pins %v; want its entry's", got)
}
if c := requests[0].Cases; len(c) != 2 || c[0].Name != changeCase || c[1].Name != beforeCase || len(c[1].Manifests) != 3 || requests[0].Predefined != nil || requests[0].Packages != nil {
t.Errorf("the validator's request is %+v", requests[0])
}
// A revision naming its own definitions keeps them, and the request names the sha256 of their bytes (H-A-443 (2)); no seat
// list is asked.
if own := []byte(`[{"seat":"s1"}]`); requests[0].SeatList != seatListDigest(own) || len(requests[0].Seats) != 1 || string(requests[0].Seats[0]) != `{"seat":"s1"}` || len(listAsks) != 0 {
t.Errorf("a revision naming its definitions was judged by %s %s (%d seat-list asks), want %s", requests[0].SeatList, requests[0].Seats, len(listAsks), seatListDigest(own))
}
if _, _, ok, _ := runs.read("main.7" + validateKeySuffix); !ok {
t.Error("the validate run is not the key <pipeline>.validate of composition-runs")
}
o := r.validate(ctx, "ask-a", step("a", 9))
if o.Outcome != meshwants.StepEndedOutcomeFailed || o.Said != reasonCycle+": a:x → b:y → a:x" || len(asks) != 1 {
t.Errorf("a revision making a cycle ended %+v (%d validator asks)", o, len(asks))
}
// The stand-in validator answers its one verdict: judged against the empty case before, web's problem is the revision's.
if o := r.validate(ctx, "ask-first", step("indexer", 3)); o.Outcome != meshwants.StepEndedOutcomeFailed ||
o.Said != reasonManifestRefused+`: web: unknown field "colour" (`+emptyBeforeWords+")" || len(asks) != 2 || len(requests[1].Cases[1].Manifests) != 0 {
t.Errorf("a revision naming no base ended %+v (%d validator asks), want it judged against an empty case before, said", o, len(asks))
}
// Revision 3 names no definitions: Seats are the trunk's seat list's bytes as seat-list handed them, named by its digest,
// asked once as a kept call under the run's ask (H-A-441 (b), H-A-443).
if got, _ := json.Marshal(requests[1].Seats); requests[1].SeatList != seatListDigest(trunkList) || string(got) != string(trunkList) ||
len(listAsks) != 1 || listAsks[0].ID != asks[1].ID+"."+meshcatalog.VerbSeatList || listAsks[0].Bound <= 0 {
t.Errorf("a revision naming no definitions was judged by %s %s (asks %+v), want the trunk's seat list %s", requests[1].SeatList, got, listAsks, seatListDigest(trunkList))
}
// Bytes the answer does not name, by size or by digest, or that are no seat list, are refused: the run judges no other bytes.
for _, row := range []struct {
name string
answer json.RawMessage
}{
{"a digest of other bytes", listAnswer(trunkList, seatListDigest([]byte("[]")), len(trunkList))},
{"another size", listAnswer(trunkList, seatListDigest(trunkList), len(trunkList)+1)},
{"no digest", listAnswer(trunkList, "", len(trunkList))},
{"no JSON array", listAnswer([]byte(`{"seat":"s1"}`), seatListDigest([]byte(`{"seat":"s1"}`)), len(`{"seat":"s1"}`))},
{"an empty list", listAnswer([]byte(`[]`), seatListDigest([]byte(`[]`)), 2)},
} {
listed = row.answer
if seats, digest, err := r.seatList("ask-row"); err == nil || !strings.Contains(err.Error(), seatListKey) {
t.Errorf("%s: the seat list read %s %s, %v; want it refused, naming the verb", row.name, digest, seats, err)
}
}
listed = listAnswer(trunkList, seatListDigest(trunkList), len(trunkList))
// Revision 12 holds revision 7's manifests and names base 7: judged against it, web's problem is the revision's, db's old one
// is not, and the case before holds base 7's manifests.
if o := r.validate(ctx, "ask-base", step("web", 12)); o.Outcome != meshwants.StepEndedOutcomeFailed ||
o.Said != reasonManifestRefused+`: web: unknown field "colour"` || len(asks) != 3 {
t.Errorf("a revision naming base 7 below its number ended %+v (%d validator asks), want it judged against base 7", o, len(asks))
} else if web := requests[2].Cases[1].Manifests["web"]; len(requests[2].Cases[1].Manifests) != 3 || !strings.Contains(string(web.Raw), "d-web-2") {
t.Errorf("the case before of revision 12 is %+v, want base 7's manifests", requests[2].Cases[1].Manifests)
}
}
@@ -2,8 +2,11 @@ package main
import (
"slices"
"strings"
"sync"
"git.novox.be/novox/mesh-contracts/go/clients/nodeengineclient"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-builder/builds"
"git.novox.be/novox/mesh-sdk/go/catalogue"
@@ -21,26 +24,6 @@ import (
// moduleGraph is the module graph of the catalog half of branch, from the entries' invokes and serves (design 47 G §184, §195).
func (p *passer) moduleGraph(branch string) graph.Graph { return p.w.graphOf(branch) }
// keptInvokes are the verbs of module the graph keeps as edges: each it invokes and does not leave out, that a module
// other than itself serves. A verb no module of the graph serves is no edge, so it holds nothing; nil when the graph holds
// no node of module.
func keptInvokes(g graph.Graph, module string) []string {
n, ok := g[module]
if !ok {
return nil
}
var out []string
for _, v := range n.Invokes {
if slices.Contains(n.LeftOut, v) {
continue
}
if slices.ContainsFunc(g.Servers(v), func(s string) bool { return s != module }) {
out = append(out, v)
}
}
return out
}
// served is, for this pass, whether a build serving a verb runs healthy on some node (graph.Served): every running healthy
// have's build (the builder's builds key of its module and fingerprint) names its manifest, and the verbs that manifest
// serves are served. A healthy build whose manifest cannot be read counts what the graph says its module serves, said in
@@ -50,14 +33,33 @@ func (p *passer) served(g graph.Graph, n assign.Nodes) func(string) bool {
if len(g) == 0 {
return nil
}
served, unread := graph.Served(n.Haves, func(module, fp string) ([]string, bool) { return p.servesOf(module, fp) },
served, unread := graph.Served(servingHaves(n, p.countedServing), func(module, fp string) ([]string, bool) { return p.servesOf(module, fp) },
func(module string) []string { return g[module].Serves })
if len(unread) > 0 {
if p.unread.changed(unread) && len(unread) > 0 {
p.logf("the manifest of the running build of %v cannot be read, so what the module graph says they serve is counted as served", unread)
}
return served
}
// saidSet is the last set of names said, so a pass says a set again only when it changed.
type saidSet struct {
mu sync.Mutex
last string
}
// changed keeps names as the set said last and says whether it differs from the one before.
func (s *saidSet) changed(names []string) bool {
sorted := slices.Sorted(slices.Values(names))
key := strings.Join(sorted, " ")
s.mu.Lock()
defer s.mu.Unlock()
if key == s.last {
return false
}
s.last = key
return true
}
// offering is, for this pass, whether a build whose manifest offers a provision runs healthy on a node present (ADR 0603
// §5, ADR 0614 §5): every running healthy have on an online node, its build's manifest read as servesOf reads it. A have
// waiting for a person's yes on a newer build counts too: it names the build that still runs and that build's health, and
@@ -108,3 +110,40 @@ func (p *passer) manifestOf(module, fp string) (catalogue.Manifest, bool) {
}
return got.manifest, true
}
// servingHaves are the haves rule 8 counts (design 47 G A-426, A-426a): a node that runs a healthy build of a part serves what that
// build serves, whatever its version and whether or not the catalog lists it, so a have held (its build has no catalog entry, a
// put holds it) or waiting for a person's yes, whose build runs healthy, counts as running; a running statement that names a build
// stopped, or not healthy, does not. counted is told each build so counted that its phase alone would have left out.
func servingHaves(n assign.Nodes, counted func(node, module string, h nodeengine.HaveByNodeModuleValue)) map[string]map[string]nodeengine.HaveByNodeModuleValue {
out := map[string]map[string]nodeengine.HaveByNodeModuleValue{}
for node, haves := range n.Haves {
out[node] = map[string]nodeengine.HaveByNodeModuleValue{}
for module, h := range haves {
if (h.Phase == nodeengineclient.PhaseHeld || h.Phase == nodeengineclient.PhaseWaitingYes) && h.Health == nodeengineclient.HealthOK {
if r, ok := n.Running[node][module]; !ok || (!r.Stopped && (r.Healthy == nil || *r.Healthy)) {
if counted != nil {
counted(node, module, h)
}
h.Phase = nodeengineclient.PhaseRunning
}
}
out[node][module] = h
}
}
return out
}
// countedServing says once per node, module and build that rule 8 counted a build whose have is not in phase running as serving
// its verbs (A-426a): the rule says which build it counted.
func (p *passer) countedServing(node, module string, h nodeengine.HaveByNodeModuleValue) {
key := "serving " + node + "." + module + "@" + h.Fp + "." + h.Phase
if p.skipped[key] {
return
}
if p.skipped == nil {
p.skipped = map[string]bool{}
}
p.skipped[key] = true
p.logf("%s on %s runs %s healthy in phase %s: counted as serving what that build serves, whatever its version (design 47 G A-426a)", module, node, shortHex(h.Fp), h.Phase)
}
@@ -73,7 +73,7 @@ func viewTools(getenv func(string) string, state func(string) views.Source, now
marks := state(views.MarksState)
var out []stdio.Tool
for _, t := range firstViewTools {
out = append(out, views.FirstViewTool(assignment.Module(), t.tool, t.state, t.words, views.ParseCallers(getenv(views.CallersEnv(t.tool))), state(t.state), marks, now))
out = append(out, views.FirstViewTool(assignment.Module(), t.tool, t.state, t.words, state(t.state), marks, now))
}
for _, t := range readTools {
out = append(out, views.ReadTool(assignment.Module(), t.tool, t.state, t.words, state(t.state), marks, now))
@@ -0,0 +1,146 @@
package main
import (
"encoding/json"
"errors"
"fmt"
"slices"
"strings"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
mwc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
stdio "git.novox.be/novox/mesh-sdk/go"
)
// wantDropTool drops one want of a node for a module by hand (design 47 H §765, H-A-58): a held or failed want of the earlier
// model goes at the clean state, its key deleted and the act written in the hand-act log; the next pass writes the want of the
// new form.
const wantDropTool = "assigner_want_drop"
// wantsState is the state the wants are kept in.
const wantsState = "wants"
// dropWant deletes the want of module on node, the act first recorded through the seat mesh-hand-acts.
func dropWant(st seatStore, ask func(string, any) (json.RawMessage, error), node, module, why, by string) (any, error) {
switch {
case node == "" || module == "":
return nil, errors.New("name the node and the module whose want is dropped")
case why == "":
return nil, errors.New("a want dropped by hand says why")
case by == "" || by == stdio.Unproven:
return nil, errors.New("a want dropped by hand names who drops it, and the runtime proved no caller")
}
key, err := mwc.WantKey(node, module)
if err != nil {
return nil, err
}
raw, _, found, err := st.get(wantsState, key)
if err != nil {
return nil, err
}
if !found {
return nil, fmt.Errorf("the assigner holds no want under %s", key)
}
taken, err := meshhandactsclient.Recorder{Ask: ask}.Record(meshhandactsclient.Request{What: wantDropTool + " " + key, Why: why + " (" + by + ")", Cause: "want-drop"})
if err != nil {
return nil, fmt.Errorf("the drop of %s is not recorded, so the want stays: %w", key, err)
}
if err := st.del(wantsState, key); err != nil {
return nil, fmt.Errorf("the want %s is not dropped: %w", key, err)
}
return map[string]any{"key": key, "dropped": json.RawMessage(raw), "by": by, "hand-act": taken.Log}, nil
}
// The kinds the all form counts what it dropped by (design 47 H-A-123).
const (
dropHeld = "held"
dropCurrent = "current"
dropUndecodable = "undecodable"
)
// dropAllWants deletes every want key of the state wants, held or not, and every value of an earlier form the decoder refuses
// (the all form, design 47 H-A-121 (2), H-A-123): each act recorded through the seat mesh-hand-acts first, as the one-item form
// does; it answers what it dropped, counted per kind. A drop not recorded stops it, saying what went before.
func dropAllWants(st seatStore, ask func(string, any) (json.RawMessage, error), why, by string) (any, error) {
switch {
case why == "":
return nil, errors.New("a want dropped by hand says why")
case by == "" || by == stdio.Unproven:
return nil, errors.New("a want dropped by hand names who drops it, and the runtime proved no caller")
}
all, err := st.keys(wantsState)
if err != nil {
return nil, err
}
slices.Sort(all)
counted := map[string]int{dropHeld: 0, dropCurrent: 0, dropUndecodable: 0}
dropped := map[string][]string{}
answer := func() map[string]any {
return map[string]any{"dropped": dropped, "counted": counted, "by": by}
}
for _, key := range all {
if !strings.HasPrefix(key, "want.") {
continue
}
raw, _, found, err := st.get(wantsState, key)
if err != nil {
return answer(), fmt.Errorf("the want %s cannot be read, so the drop stops there: %w", key, err)
}
if !found {
continue
}
kind := wantKind(key, raw)
taken, err := meshhandactsclient.Recorder{Ask: ask}.Record(meshhandactsclient.Request{What: wantDropTool + " " + key, Why: why + " (" + by + ")", Cause: "want-drop"})
if err != nil {
return answer(), fmt.Errorf("the drop of %s is not recorded, so it and the wants after it stay: %w", key, err)
}
if err := st.del(wantsState, key); err != nil {
return answer(), fmt.Errorf("the want %s is not dropped: %w", key, err)
}
counted[kind]++
dropped[kind] = append(dropped[kind], key+" (hand act "+taken.Log+")")
}
return answer(), nil
}
// wantKind says how the all form counts a want: undecodable when its key or value is of no form the decoder takes, held when it
// holds, current otherwise (design 47 H-A-123).
func wantKind(key string, raw []byte) string {
if _, err := mwc.ParseWantNodeKey(key); err == nil {
if _, err := mwc.DecodeNodeWant(raw); err != nil {
return dropUndecodable
}
return dropCurrent
}
if _, _, err := mwc.ParseWantKey(key); err != nil {
return dropUndecodable
}
w, err := mwc.DecodeWant(raw)
switch {
case err != nil:
return dropUndecodable
case w.Hold:
return dropHeld
}
return dropCurrent
}
// wantDropTools is the tool over the runtime's states.
func wantDropTools(st seatStore, ask func(string, any) (json.RawMessage, error)) []stdio.Tool {
return []stdio.Tool{{Name: wantDropTool, Description: "Drop one want by hand (design 47 H §765): the want of module on node is " +
"deleted from the state wants, as the clean state drops a held or failed want of the earlier model; the next pass writes the " +
"want of the new form. Recorded as a hand act first; refused with no want under the key. With all true and no node or module, " +
"every want key goes, held or not, and every value of an earlier form the decoder refuses, each recorded as a hand act; it " +
"answers what it dropped, counted per kind (held, current, undecodable).",
Input: schema(map[string]string{"node": "the node's name", "module": "the module's name", "why": "why the want is dropped",
"all": "true drops every want of the state wants, naming no node or module"}, []string{"why"}, "all"),
Run: func(a map[string]any) (any, error) {
if arg(a, "all") == "true" {
if arg(a, "node") != "" || arg(a, "module") != "" {
return nil, errors.New("the all form drops every want: name no node or module with it")
}
return dropAllWants(st, ask, arg(a, "why"), stdio.CallerOf(a))
}
return dropWant(st, ask, arg(a, "node"), arg(a, "module"), arg(a, "why"), stdio.CallerOf(a))
}}}
}
@@ -0,0 +1,99 @@
package main
import (
"encoding/json"
"errors"
"strings"
"testing"
mwc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
)
// A12/AC1 (design 47 H §765, H-A-58): assigner_want_drop with node, module and why records the act in the hand-act log first
// and then deletes that want; with no want under the key, no why or no proven caller, and when the act is not recorded, nothing is
// dropped.
func TestAWantIsDroppedByHandAndRecorded(t *testing.T) {
key, _ := mwc.WantKey("ace", "web")
held, _ := mwc.EncodeWant(mwc.Want{Fp: fpTest, Put: true, Hold: true, Words: "put: x"})
for _, c := range []struct {
name, node, module, why, by string
refuse error
dropped bool
}{
{"dropped", "ace", "web", "the clean state", "person.jochen", nil, true},
{"no want there", "ace", "db", "the clean state", "person.jochen", nil, false},
{"no why", "ace", "web", "", "person.jochen", nil, false},
{"no caller", "ace", "web", "the clean state", "", nil, false},
{"not recorded", "ace", "web", "the clean state", "person.jochen", errors.New("no responders"), false},
} {
st := memStore{wantsState: &memKV{values: map[string][]byte{key: held}}}
var asked []string
ask := func(verb string, body any) (json.RawMessage, error) {
raw, _ := json.Marshal(body)
asked = append(asked, verb+" "+string(raw))
return json.RawMessage(`{}`), c.refuse
}
out, err := dropWant(st, ask, c.node, c.module, c.why, c.by)
_, there := st[wantsState].values[key]
switch {
case c.dropped && (err != nil || there || len(asked) != 1 || !strings.Contains(asked[0], "seat:mesh-hand-acts.hand-act ") || !strings.Contains(asked[0], wantDropTool+" "+key)):
t.Errorf("%s: %v, %v; the want left %v, asked %v", c.name, out, err, there, asked)
case !c.dropped && (err == nil || !there):
t.Errorf("%s: %v, %v; the want left %v, want it refused and kept", c.name, out, err, there)
}
}
}
// H-A-121 (2), H-A-123: assigner_want_drop's all form drops every want key, held or not, and every value of an earlier form,
// each recorded as a hand act first, answering the count per kind; a held fingerprint's key stays; a drop not recorded stops it;
// the all form names no node or module.
func TestEveryWantIsDroppedByHandAndCounted(t *testing.T) {
heldKey, _ := mwc.WantKey("ace", "web")
curKey, _ := mwc.WantKey("ace", "db")
nodeKey, _ := mwc.WantNodeKey("ace")
oldKey, _ := mwc.WantKey("g14", "web")
fpKey, _ := mwc.HeldKey("web", fpTest)
held, _ := mwc.EncodeWant(mwc.Want{Fp: fpTest, Put: true, Hold: true, Words: "put: x"})
cur, _ := mwc.EncodeWant(mwc.Want{Fp: fpTest})
node, _ := mwc.EncodeNodeWant(mwc.NodeWant{Self: true})
values := func() map[string][]byte {
return map[string][]byte{heldKey: held, curKey: cur, nodeKey: node, oldKey: []byte(`{"fingerprint":"old"}`), fpKey: []byte(`{}`)}
}
for _, c := range []struct {
name string
refuse error
left int
}{
{"dropped", nil, 1},
{"not recorded", errors.New("no responders"), 5},
} {
st := memStore{wantsState: &memKV{values: values()}}
var asked []string
ask := func(verb string, body any) (json.RawMessage, error) {
raw, _ := json.Marshal(body)
asked = append(asked, string(raw))
return json.RawMessage(`{}`), c.refuse
}
out, err := dropAllWants(st, ask, "the clean state", "person.jochen")
if left := len(st[wantsState].values); left != c.left || (c.refuse == nil) != (err == nil) {
t.Errorf("%s: %v, %v; %d keys left, want %d", c.name, out, err, left, c.left)
}
if c.refuse != nil {
continue
}
if _, ok := st[wantsState].values[fpKey]; !ok {
t.Errorf("the held fingerprint's key %s is dropped: it is no want", fpKey)
}
counted := out.(map[string]any)["counted"].(map[string]int)
if counted[dropHeld] != 1 || counted[dropCurrent] != 2 || counted[dropUndecodable] != 1 || len(asked) != 4 {
t.Errorf("counted %v, asked %d hand acts; want held 1, current 2, undecodable 1 and 4 acts", counted, len(asked))
}
}
if _, err := dropAllWants(memStore{wantsState: &memKV{values: values()}}, nil, "", "person.jochen"); err == nil {
t.Error("the all form dropped with no why")
}
run := wantDropTools(memStore{wantsState: &memKV{values: values()}}, nil)[0].Run
if _, err := run(map[string]any{"all": "true", "node": "ace", "why": "x"}); err == nil || !strings.Contains(err.Error(), "name no node") {
t.Errorf("the all form with a node: %v, want it refused", err)
}
}
@@ -71,21 +71,15 @@ func (s *wantsTools) values(state string) (map[string][]byte, error) {
return s.direct(state)
}
// direct reads a state key by key, for a small state of the seat's own.
// direct reads a state whole, in pages where the runtime has them (readAll).
func (s *wantsTools) direct(state string) (map[string][]byte, error) {
keys, err := s.st.keys(state)
all, err := readAll(s.st, state)
if err != nil {
return nil, fmt.Errorf("%s cannot be listed: %w", state, err)
return nil, err
}
out := map[string][]byte{}
for _, k := range keys {
raw, _, found, err := s.st.get(state, k)
if err != nil {
return nil, fmt.Errorf("%s %s cannot be read: %w", state, k, err)
}
if found {
out[k] = raw
}
out := make(map[string][]byte, len(all))
for k, v := range all {
out[k] = v.raw
}
return out, nil
}
@@ -0,0 +1,146 @@
package main
import (
"context"
"encoding/json"
"sort"
"strings"
"time"
mwc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
stdio "git.novox.be/novox/mesh-sdk/go"
"mesh-delivery-assigner/internal/assign"
)
// Why a want is what it is (lead-47 2026-11-15, the tools rule: novox's want of the indexer stood unwritten for a day and nothing
// said why). Each pass writes, in the state written beside the pipeline ends, one key `why.<node>.<module>`: the step of the pass
// that decided the want and what it read there. A key whose time stands still says the pass no longer judges that module.
// assigner_why reads them.
// whyPrefix starts every key of a want's why in the state written; a pipeline end's key starts with a module's name.
const whyPrefix = "why."
// whyTool is the tool that reads them.
const whyTool = "assigner_why"
// The steps of the pass that decide a want.
const (
whyNoPipeline = "no-passed-pipeline" // no version of the module released on the branch passed its pipeline: the want written stays
whyPassed = "passed-pipeline" // the want names the newest version released on the branch whose pipeline passed (design 47 H §750)
)
// whyStep is the step that decided a want: a passed pipeline's version, or none yet.
func whyStep(passed bool) string {
if passed {
return whyPassed
}
return whyNoPipeline
}
// wantWhy is one key's value.
type wantWhy struct {
At time.Time `json:"at"`
Branch string `json:"branch,omitempty"`
// Fp, Version and Pipeline are the build the want names and the pipeline whose passed end released it (design 47 H §750).
Fp string `json:"fp,omitempty"`
Version string `json:"version,omitempty"`
Pipeline string `json:"pipeline,omitempty"`
Step string `json:"step"`
// Before is the want that stood before the pass, After the one the pass wrote (none: it kept Before).
Before *mwc.Want `json:"before,omitempty"`
After *mwc.Want `json:"after,omitempty"`
}
func whyKey(node, module string) string { return whyPrefix + node + "." + module }
// sayWhy writes the why of module on each of nodes, once per change (the time aside): every put is a change its watchers hear.
func (p *passer) sayWhy(ctx context.Context, module string, nodes []string, w wantWhy, before map[string]mwc.Want, out *assign.Outcome) {
kv := p.kvs[writtenBucket()]
if kv == nil {
return
}
if p.whys == nil {
p.whys = map[string]string{}
}
for _, node := range nodes {
one := w
one.At = time.Now().UTC()
if b, ok := before[node]; ok {
one.Before = &b
}
if out != nil {
if a, ok := out.Wants[node]; ok {
one.After = &a
}
}
same := one
same.At = time.Time{}
cmp, _ := json.Marshal(same)
key := whyKey(node, module)
if p.whys[key] == string(cmp) {
continue
}
raw, err := json.Marshal(one)
if err != nil {
continue
}
if _, err := kv.Put(ctx, key, raw); err != nil {
p.logf("the why of %s on %s is not written: %v", module, node, err)
continue
}
p.whys[key] = string(cmp)
}
}
// whyTools is the tool assigner_why: every want's why, or those of one module or one node.
func whyTools(st store) []stdio.Tool {
return []stdio.Tool{{Name: whyTool, Description: "why a want is what it is: per node and module, the step of the assigner's last pass that decided the want (no passed pipeline yet, or a passed pipeline's version), the build, version and pipeline it names, the want before and the one written. A time that stands still says the pass no longer judges that module. Arguments: module and node narrow it.",
Input: schema(map[string]string{"module": "a module's name", "node": "a node's name"}, nil),
Run: func(args map[string]any) (any, error) {
ks, err := st.keys(writtenState)
if err != nil {
return nil, err
}
module, node := arg(args, "module"), arg(args, "node")
sort.Strings(ks)
out := map[string]wantWhy{}
for _, k := range ks {
rest, ok := strings.CutPrefix(k, whyPrefix)
if !ok {
continue
}
n, mod, _ := strings.Cut(rest, ".")
if (module != "" && mod != module) || (node != "" && n != node) {
continue
}
raw, _, ok, err := st.get(writtenState, k)
if err != nil || !ok {
continue
}
var w wantWhy
if json.Unmarshal(raw, &w) == nil {
out[rest] = w
}
}
return out, nil
}}}
}
// sayPass writes, under `why.pass`, whether the last pass judged the wants at all, once per change of its words.
func (p *passer) sayPass(ctx context.Context, words string) {
kv := p.kvs[writtenBucket()]
if kv == nil {
return
}
if p.whys == nil {
p.whys = map[string]string{}
}
if p.whys[whyPrefix+"pass"] == words {
return
}
raw, _ := json.Marshal(wantWhy{At: time.Now().UTC(), Step: words})
if _, err := kv.Put(ctx, whyPrefix+"pass", raw); err == nil {
p.whys[whyPrefix+"pass"] = words
}
}
@@ -12,7 +12,6 @@ import (
"git.novox.be/novox/mesh-contracts/go/clients/nodeengineclient"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-builder/builds"
mdc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshdeliveryclient"
mwc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
@@ -43,12 +42,8 @@ type world struct {
ends builtEnds
// released are the catalog's version-released heard, by module and source revision (buildended.go).
released releasedVersions
// delivered are the assigner's own version-delivered heard and said (delivered.go).
delivered deliveredVersions
// edges are, by watched branch and module, the edges into the module's artifacts its catalog entry names (§374's kinds).
edges map[string]map[string][]meshcatalog.Edge
// taken is the newest source revision of each watched branch the indexer's take-in.taken named, as heard (orderwaits.go, §298, A-260).
taken takenSources
// assignments is the seat's state assignments assembled node by node from its keys in either form (mesh-sdk
// mmac.Keys; research 072 row 37): the one reader of its keys in the assigner.
assignmentKeys *mmac.Keys
@@ -139,23 +134,6 @@ func (w *world) put(bucket, key string, value []byte) {
}
}
// lastHealthy is the newest fingerprint other than fp the node ran the module healthy at, or empty.
func (w *world) lastHealthy(node, module, fp string) string {
key, err := nodeengineclient.HaveKey(node, module)
if err != nil {
return ""
}
w.mu.Lock()
defer w.mu.Unlock()
list := w.healthy[key]
for i := len(list) - 1; i >= 0; i-- {
if list[i] != fp {
return list[i]
}
}
return ""
}
// read is a copy of what a bucket holds now.
func (w *world) read(bucket string) map[string][]byte {
w.mu.Lock()
@@ -414,11 +392,7 @@ func (w *world) nodes(manifests map[string]catalogue.Manifest, assigned map[stri
if err != nil {
continue
}
if isNode {
// What the node's engine reads (ADR 0614 §4); a record that states none is read as the baseline.
if h, err := nodeengineclient.DecodeHaveNode(value); err == nil && h.Record != nil {
n.Reads[node] = h.Record.ManifestReads
}
if isNode { // what the node's engine reads is the state engine-reads' alone (design 47 H-A-104)
continue
}
if h, err := nodeengineclient.DecodeHave(value); err == nil {
@@ -464,37 +438,6 @@ func (w *world) has(bucket, key string) bool {
return ok
}
// built says whether the builder's build of a module at a fingerprint is done, from its `build.ended` heard (design 47 G A-181).
func (w *world) built(module, fp string) bool {
e, ok := w.ends.endOf(module, fp)
return ok && e.Outcome == builds.BuildDone
}
// buildStanding says whether the builder's `build.ended` of module at fp said the build failed, and its error whole (design 47 G
// §575, A-162): the words of a hold under rule 1.
func (w *world) buildStanding(module, fp string) (failed bool, words string) {
if e, ok := w.ends.endOf(module, fp); ok && e.Outcome == builds.BuildFailed {
return true, e.Error
}
return false, ""
}
// buildNeeds are the reference forms the builder's done build of module at fp is written in (the build's end says them, ADR
// 0618 §1, A-181): nil when it is not done or names none.
func (w *world) buildNeeds(module, fp string) []string {
if e, ok := w.ends.endOf(module, fp); ok && e.Outcome == builds.BuildDone {
return e.Needs
}
return nil
}
// recordReads is what node's record `<node>.node` states its engine reads (ADR 0614 §4), and whether the assigner holds
// a record of it: the fallback where the engine does not answer the verb manifest-reads (enginereads.FromRecord).
func (w *world) recordReads(node string) ([]string, bool) {
r, ok := w.records()[node]
return r.ManifestReads, ok
}
// knownNodes is every node the assigner hears of: placed, with a record, or named by machine-away or machine-back.
func (w *world) knownNodes() []string {
set := map[string]bool{}
@@ -610,3 +553,18 @@ func (w *world) placedBranches() map[string]map[string]string {
}
return out
}
// assignedOn is the modules the assignments place on node.
func (w *world) assignedOn(node string) []string {
var out []string
for _, m := range w.assignments()[node].Modules {
out = append(out, m.Module)
}
return out
}
// assignmentOf is node's assignments, or false where none is held.
func (w *world) assignmentOf(node string) (mma.Assignments, bool) {
a, ok := w.assignments()[node]
return a, ok
}
-3
View File
@@ -89,16 +89,13 @@ replace git.novox.be/novox/mesh-delivery/modules/mesh-delivery-view/viewstate =>
require git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient v0.0.0-00010101000000-000000000000
require git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshdeliverycheckerclient v0.0.0-00010101000000-000000000000
replace git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshdeliverycheckerclient => ../mesh-delivery-contracts/go/clients/meshdeliverycheckerclient
require git.novox.be/novox/mesh-networking/modules/mesh-wireguard/go v0.0.0-00010101000000-000000000000
require (
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/containerimageregistryclient v0.0.0-00010101000000-000000000000 // indirect
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/containerimageregistry v0.0.0-00010101000000-000000000000 // indirect
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdeliverychecker v0.0.0-00010101000000-000000000000 // indirect
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/ociartifactregistry v0.0.0-00010101000000-000000000000 // indirect
git.novox.be/novox/mesh-networking/modules/mesh-connectivity-contracts/go/seats/theprivatenetwork v0.0.0-00010101000000-000000000000 // indirect
)
@@ -1,140 +0,0 @@
// Package acting is the assigner's wait for an acting part's new version (design 47 G §266, §268, §276): an entry of the assignment
// graph whose edge of kind acting names a step the assigner holds (composing, placing) waits until the acting part's version runs
// on the node of the edge, with the bound of the rule that gave the edge, or the step's default. The package holds the rules and
// the kept record; the assigner's process reads what runs, says the events and keeps the records in its state `waits`.
package acting
import (
"encoding/json"
"fmt"
"strings"
"time"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-sdk/go/seatdef"
)
// HowNow is the `how` of assigner_release for a wait for an acting part: the entry is wanted now, with the version running.
const HowNow = "now"
// The ways a wait ends, as `wait-ended` says them.
const (
HowRan = "ran"
HowReleased = "released"
HowReplaced = "replaced"
)
// Prefix opens the key of an acting wait in the state, apart from the outside waits' `<node>.<module>.<fingerprint hex>`.
const Prefix = "acting."
// OrderPrefix opens the key of an order wait (design 47 G §298, A-259): a want held for the order of a delivery that crosses a form change,
// kept beside the acting waits in the state `waits`, as `order.<node>.<module>.<part>`.
const OrderPrefix = "order."
// The three order edges of §298, as a kept wait's Order names them.
const (
// OrderBackup: the new versions of the node-backup holder and of the holder of the bus module's seat run before a module whose kept
// data's form changes is moved.
OrderBackup = "backup-and-broker-first"
// OrderEngineLast: at a revert a node's node-engine goes back last on that node.
OrderEngineLast = "node-engine-last"
// OrderTakenIn: the reverted assigner and gate are wanted only once the reverted indexer took in the trunk's head.
OrderTakenIn = "taken-in-first"
)
// Held says whether the assigner holds the entries of step: composing and placing (§276's table).
func Held(step string) bool { return step == seatdef.StepCompose || step == seatdef.StepPlace }
// Wait is one wait as kept: Module's entry on Node waits for Part's version Fp to run on PartNode, in Step.
type Wait struct {
V int `json:"v"`
Step string `json:"step"`
Node string `json:"node"`
Module string `json:"module"`
Part string `json:"part"`
PartNode string `json:"part-node"`
Fp string `json:"fp"`
Entry string `json:"entry"`
Since time.Time `json:"since"`
ClockFrom time.Time `json:"clock-from"`
Bound string `json:"bound"`
// Released is a release by hand: the entry moves on with the part's old version; EndSaid says wait-ended was said for it.
// Order is which of §298's edges the wait stands on; empty for an acting wait.
Order string `json:"order,omitempty"`
Released bool `json:"released,omitempty"`
EndSaid bool `json:"end-said,omitempty"`
By string `json:"by,omitempty"`
Why string `json:"why,omitempty"`
}
// Key is the key of a wait in the state.
func Key(node, module, part string) string { return Prefix + node + "." + module + "." + part }
// OrderKey is the key of an order wait in the state.
func OrderKey(node, module, part string) string {
return OrderPrefix + node + "." + module + "." + part
}
// IsOrder says a kept value is an order wait's record.
func IsOrder(key string) bool { return strings.HasPrefix(key, OrderPrefix) }
// Is says a kept value is an acting wait's record.
func Is(key string) bool { return strings.HasPrefix(key, Prefix) }
// Encode is w as JSON.
func Encode(w Wait) ([]byte, error) { w.V = 1; return json.Marshal(w) }
// Decode reads a kept wait.
func Decode(raw []byte) (Wait, error) {
var w Wait
if err := json.Unmarshal(raw, &w); err != nil {
return w, err
}
if w.V != 1 || w.Step == "" || w.Node == "" || w.Module == "" || w.Part == "" {
return w, fmt.Errorf("acting: %q is not a kept acting wait", raw)
}
return w, nil
}
// BoundOf is the bound of the edge's wait: its rule's, else its step's default (seatdef.ActingRule.Wait).
func BoundOf(e meshwants.Edge) time.Duration {
return seatdef.ActingRule{Step: e.Step, Bound: e.Bound}.Wait()
}
// Pending are the acting edges of the assigner's steps whose part's version does not run yet: runs says the edge's part runs
// its version on the edge's node.
func Pending(edges []meshwants.Edge, runs func(e meshwants.Edge) bool) []meshwants.Edge {
var out []meshwants.Edge
for _, e := range edges {
if e.Kind == "acting" && Held(e.Step) && !runs(e) {
out = append(out, e)
}
}
return out
}
// Body is the wait as the seat mesh-wants says it.
func Body(w Wait, owner string) meshwants.Wait {
since, from := w.Since.UTC(), w.ClockFrom.UTC()
return meshwants.Wait{Step: w.Step, Owner: owner, Node: w.Node, Module: w.Module, Part: w.Part, Fp: w.Fp, Since: since, ClockFrom: &from, Bound: w.Bound,
Words: words(w)}
}
func words(w Wait) string {
switch w.Order {
case OrderBackup:
return fmt.Sprintf("%s on %s moves its kept data across a form change: it waits in %s for %s at %s to run on %s, which the restore point needs", w.Module, w.Node, w.Step, w.Part, short(w.Fp), w.PartNode)
case OrderEngineLast:
return fmt.Sprintf("%s on %s goes back last on its node: it waits in %s for %s at %s to run on %s, restored", w.Module, w.Node, w.Step, w.Part, short(w.Fp), w.PartNode)
case OrderTakenIn:
return fmt.Sprintf("%s on %s goes back only once the indexer took in the trunk's head: it waits in %s for source revision %s to be taken in", w.Module, w.Node, w.Step, w.Fp)
}
return fmt.Sprintf("%s on %s waits in %s for %s at %s to run on %s", w.Module, w.Node, w.Step, w.Part, short(w.Fp), w.PartNode)
}
func short(fp string) string {
if len(fp) > 19 {
return fp[:19]
}
return fp
}
@@ -5,6 +5,7 @@ import (
"fmt"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-assigner/asks"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshdeliveryclient"
"regexp"
"time"
occ "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/clients/operatorchannelclient"
@@ -13,6 +14,10 @@ import (
// assignerAsk is the asking-th ask a, as the asks state holds it: the router's ask as JSON (asks.Ask.Ask).
func assignerAsk(asking int, a oc.Ask) asks.Ask {
a.Headline, a.Explanation, a.Details, a.OnExpiry = said(a.Headline), said(a.Explanation), said(a.Details), said(a.OnExpiry)
for i := range a.Options {
a.Options[i].Label, a.Options[i].Does = said(a.Options[i].Label), said(a.Options[i].Does)
}
raw, err := json.Marshal(a)
if err != nil { // an oc.Ask holds only strings, bools and a slice of them: it cannot fail
panic(fmt.Sprintf("assign: the ask %q does not marshal: %v", a.ID, err))
@@ -20,6 +25,17 @@ func assignerAsk(asking int, a oc.Ask) asks.Ask {
return asks.Ask{Asking: asking, Ask: raw}
}
// longHex is a digest or fingerprint whole: 64 hexadecimal digits.
var longHex = regexp.MustCompile(`[0-9a-f]{64}`)
// said is words as an ask carries them out of the mesh: each digest or fingerprint cut to its first 12 digits, which the
// router lets pass, where it refuses a long hexadecimal string as a secret's shape (mesh-sdk outward; novox 2026-11-16 01:24:
// every backup ask was refused for its "(composition sha256:…)" and the fingerprints in the node's words, and the operator
// was never asked).
func said(words string) string {
return longHex.ReplaceAllStringFunc(words, func(h string) string { return h[:12] })
}
// AskOf is the router's ask an asks-state value carries.
func AskOf(a asks.Ask) (oc.Ask, error) {
var ask oc.Ask
@@ -3,7 +3,6 @@ package assign
import (
"fmt"
"mesh-delivery-assigner/internal/assignment"
"regexp"
"strings"
"time"
@@ -16,56 +15,12 @@ import (
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
)
// HoldAsk is the ask about a module's fingerprint the assigner holds, at its key (asks.HoldAskKey): keep it held or
// release it. Releasing writes the held fingerprint's want again by the rules (ADR 0539 §19). node and words are the held
// record's: the machine whose health check failed and the hold's words (issue 1906). asking numbers the writing: 0 the first, a
// larger number an ask written again after a hold lifted by itself, so the router takes it as new.
func HoldAsk(key, module, fp, node, words string, asking int, now time.Time) asks.Ask {
return assignerAsk(asking, oc.Ask{
ID: meshdeliveryclient.AskingID(key, asking),
Headline: fmt.Sprintf("%s is held at %s", module, short(fp)),
Explanation: fmt.Sprintf("The health check of %s failed on %s at %s (%s), so the assigner holds that version and wants "+
"no node to move to it. It lifts the hold by itself once every node that runs %s runs it healthy; releasing it "+
"lets the wants move to it now.", module, node, short(fp), words, module),
Options: []oc.Option{
{ID: "keep", Label: "Keep it held", Does: "the version stays held", Level: occ.Acknowledge},
{ID: "release", Label: "Release it", Does: "the version is released and the wants move to it by the rules again", Level: occ.Acknowledge},
},
Who: occ.Operator,
Expires: occ.FormatTime(now.Add(AskLasts)),
OnExpiry: "the version stays held",
About: key,
})
}
// The options of the restore ask (ADR 0537 §3, ADR 0539 §19), and what each does on the node.
const (
OptionRestore = "restore"
OptionLeaveStopped = "leave-stopped"
)
// RestoreAsk is the ask about a module holding data whose fingerprint failed its health check on a node (ADR 0429 §6): it is
// not set back by itself, since a set-back would lose the writes made since. words is the check's words. asking is the writing's
// number (AskingSeconds): an ask taken away as stale and written again is another asking under an id of its own, since the
// router drops a second ask under an id it keeps and the teller took the first back (issue 1966). Restore sets the
// node back to the last healthy fingerprint and loses the newer writes; leaving it stopped keeps the data as it is.
func RestoreAsk(key, node, module, fp, words string, asking int, now time.Time) asks.Ask {
return assignerAsk(asking, oc.Ask{
ID: meshdeliveryclient.AskingID(key, asking),
Headline: fmt.Sprintf("%s failed its health check on %s", module, node),
Explanation: fmt.Sprintf("%s holds data, and its health check failed on %s at %s: %s. Setting it back to the version that ran healthy "+
"would lose the writes made since; leaving it stopped keeps the data as it is.", module, node, short(fp), words),
Options: []oc.Option{
{ID: OptionRestore, Label: "Restore it", Does: "the node is set back to the last healthy version and the newer writes are lost", Level: occ.Acknowledge},
{ID: OptionLeaveStopped, Label: "Leave it stopped", Does: "the module stays as it is on the node and the data is kept", Level: occ.Acknowledge},
},
Who: occ.Operator,
Expires: occ.FormatTime(now.Add(AskLasts)),
OnExpiry: "the module stays as it is on the node",
About: key,
})
}
// The options of the outside ask (design 47 G §706).
const (
OptionGoOn = "go-on"
@@ -106,92 +61,6 @@ func WaitsOutsideFinding(node, module, causeKey, on string, at time.Time) Observ
Needs: "Nothing for you to do.", Source: "assigner.delivery-waits-outside"}
}
// HeldCondition is the condition the assigner raises when it holds a fingerprint of a module (ADR 0429 §6, ADR 0539 §19), or
// clears (raised false) when the hold is released. It names the module, the node whose health check failed and the check's
// words, under the assigner's own name (ADR 0437 clause 9), keyed by the held fingerprint. needsYou is true for a module holding
// data, whose restore ask waits for the operator.
func HeldCondition(module, fp, node, words string, raised, needsYou bool) oc.Condition {
key := assignment.Module() + ".held." + module + "." + strings.TrimPrefix(fp, meshcatalogclient.SourcePrefix2)
subject := oc.ConditionSubject{Scope: "module", ID: module, Machine: node}
if !raised {
return oc.Condition{Key: key, Subject: subject, State: occ.StateCleared}
}
c := oc.Condition{Key: key, Severity: occ.SeverityWarning, Subject: subject, State: occ.StateRaised,
Summary: fmt.Sprintf("%s is held at %s", module, short(fp)),
Headline: fmt.Sprintf("%s is held at %s", module, short(fp))}
what := fmt.Sprintf("The health check of %s failed on %s at %s: %s. The assigner holds that version and wants no node to move to it.", module, node, short(fp), words)
if needsYou {
c.Needs = "answer whether to restore " + module + " on " + node
c.Explanation = occ.NeedsYou + c.Needs + ". " + what
} else {
c.Explanation = occ.NothingToDo + " " + what + " Nodes that wanted it are set back to the version that ran healthy."
}
return c
}
// NodeFailedCondition is the condition the assigner raises for a module whose newest fingerprint fp failed its health check on
// node while other nodes run it healthy (ADR 0557 §1, issue 1496): the failure is the node's, so nothing is held or set back and
// the node keeps its want. It names the node, the module, fp and the have's words, keyed by node and module, and is cleared
// (raised false) once the node no longer fails alone.
func NodeFailedCondition(node, module, fp string, f NodeFailure, raised bool) oc.Condition {
key := assignment.Module() + ".failed-alone." + node + "." + module
subject := oc.ConditionSubject{Scope: "module", ID: module, Machine: node}
if !raised {
return oc.Condition{Key: key, Subject: subject, State: occ.StateCleared,
Resolved: fmt.Sprintf("%s on %s no longer fails its health check alone.", module, node)}
}
headline := fmt.Sprintf("%s fails on %s alone", module, node)
if n := len([]rune(headline)); n > occ.HeadlineLength {
headline = string([]rune(headline)[:occ.HeadlineLength])
}
return oc.Condition{Key: key, Severity: occ.SeverityWarning, Subject: subject, State: occ.StateRaised,
Summary: headline, Headline: headline,
Explanation: fmt.Sprintf("%s The health check of %s at %s failed on %s (%s), while it runs healthy on %s. The failure is %s's, "+
"so the assigner holds nothing and sets no node back, and %s keeps its want. This clears once %s runs it healthy or "+
"another version is the newest.", occ.NothingToDo, module, short(fp), node, f.Words, strings.Join(f.Others, ", "), node,
node, node)}
}
// NeitherCondition is the condition of a module assigned to node that holds no want for it (issue 1945): the node's own composition
// gives up every module with a fingerprint of the new form, so nothing applies it there and its files are gone. It is raised (urgent)
// naming the module, the node and the rule holding its first want back with the rule's words, under the assigner's own name keyed by
// node and module, and cleared (raised false) when the node has a want for it again.
func NeitherCondition(node, module string, h Holding, raised bool) oc.Condition {
key := assignment.Module() + ".neither." + node + "." + module
subject := oc.ConditionSubject{Scope: "module", ID: module, Machine: node}
if !raised {
return oc.Condition{Key: key, Subject: subject, State: occ.StateCleared,
Resolved: fmt.Sprintf("%s on %s has a want again, so its own composition is applied there.", module, node)}
}
headline := fmt.Sprintf("%s on %s is on no list", module, node)
if n := len([]rune(headline)); n > occ.HeadlineLength {
headline = string([]rune(headline)[:occ.HeadlineLength])
}
return oc.Condition{Key: key, Severity: occ.SeverityUrgent, Subject: subject, State: occ.StateRaised,
Summary: headline, Headline: headline,
Explanation: fmt.Sprintf("%s %s is assigned to %s, but the node holds no want for it and the node's own composition does not "+
"hold it either, so nothing applies it there. The assigner's rule %d holds its first want back: %s. The assigner writes the want once the "+
"rule holds, and clears this.", occ.NothingToDo, module, node, h.Rule, h.Words)}
}
// NeitherLeftCondition clears the neither condition of module on node when it is no longer on neither list: why is "" when the
// node has a live want for it again, else why it has none (it is held, its move waits for an ask, the node no longer runs it), so
// the clear never says a want the node does not hold (issue 1945: "nats on novox has a want again" while it had none).
func NeitherLeftCondition(node, module, why string) oc.Condition {
c := NeitherCondition(node, module, Holding{}, false)
if why != "" {
c.Resolved = fmt.Sprintf("%s on %s is no longer on neither list and has no want: %s.", module, node, why)
}
return c
}
// LiftedCondition clears the condition of a held fingerprint the assigner lifted by itself, saying why (issue 1906).
func LiftedCondition(module, fp string) oc.Condition {
c := HeldCondition(module, fp, "", "", false, false)
c.Resolved = LiftedWords(module, fp) + "."
return c
}
// The options of the record ask (ADR 0539 §14) and of the backup ask (§16).
const (
OptionYes = "yes"
@@ -288,22 +157,6 @@ func NextBackupAsking(after int) int {
return max(after+1, 2)
}
var backupDigest = regexp.MustCompile(`\(composition (sha256:[0-9a-f]{64})\)`)
// BackupAskDigest is the digest of the composition a backup ask was made about, from its explanation; empty for an ask that names
// none. An answer is taken for the composition of the ask it answers, and a new revision at the same fingerprint is asked again
// under a new number (ADR 0539 §16).
func BackupAskDigest(a asks.Ask) string {
ask, err := AskOf(a)
if err != nil {
return ""
}
if m := backupDigest.FindStringSubmatch(ask.Explanation); m != nil {
return m[1]
}
return ""
}
// BackupAnswerWords are the words of a want carrying the answer to the asking-th ask: each asking's answer is another want
// value, so a backup that fails again after "back up again" and is answered "again" again changes the key and the node retries.
func BackupAnswerWords(option string, asking int) string {
@@ -311,14 +164,14 @@ func BackupAnswerWords(option string, asking int) string {
}
// BackupAsk is the ask about a backup of a module on node that failed before an apply (ADR 0539 §16): back up again, or go on
// without a backup. digest is the composition about to be applied and asking the number of the asking, 0 the first; words are the
// without a backup, at the build fp the want names. asking is the number of the asking, 0 the first; words are the
// backup's own words, from the node's have.
func BackupAsk(key, node, module, fp, digest, words string, asking int, now time.Time) asks.Ask {
func BackupAsk(key, node, module, fp, words string, asking int, now time.Time) asks.Ask {
return assignerAsk(asking, oc.Ask{
ID: meshdeliveryclient.AskingID(key, asking),
Headline: fmt.Sprintf("The backup of %s failed on %s", module, node),
Explanation: fmt.Sprintf("The backup before applying %s at %s on %s failed: %s. %s keeps running what it has until you answer. (composition %s)",
module, short(fp), node, words, module, digest),
Explanation: fmt.Sprintf("The backup before applying %s at %s on %s failed: %s. %s keeps running what it has until you answer.",
module, short(fp), node, words, module),
Options: []oc.Option{
{ID: OptionBackupAgain, Label: "Back up again", Does: "the node tries the backup again before it applies", Level: occ.Acknowledge},
{ID: OptionBackupSkip, Label: "Go on without a backup", Does: "the node applies the new version without a backup", Level: occ.Acknowledge},
@@ -5,6 +5,7 @@ import (
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-teller/tellerevents"
"mesh-delivery-assigner/internal/assignment"
"mesh-delivery-assigner/internal/puts"
"regexp"
"slices"
"strings"
"testing"
@@ -22,11 +23,10 @@ import (
"git.novox.be/novox/mesh-sdk/go/views"
)
// 1297/B9 (the assigner's half): the ask about a held fingerprint is a valid ask of the router and of mesh-sdk's layout at
// its key, of a kind the view may answer.
func TestTheHoldAskIsValid(t *testing.T) {
t.Run("hold", theHoldAskIsValid)
t.Run("restore", theRestoreAskIsValid)
// 1297/B9 (the assigner's half): the backup ask is a valid ask of the router and of mesh-sdk's layout at its key, of a kind the
// view may answer; the hold and restore asks went with the hold of a fingerprint (design 47 H §750, H-A-55).
func TestTheAssignersAsks(t *testing.T) {
t.Run("backup", theBackupAskIsValid)
t.Run("ended at the channel", anAskEndedAtTheChannelIsWrittenAgain)
t.Run("ended at the channel, read at bind", anAskEndedAtTheChannelIsReadAtBind)
}
@@ -39,8 +39,6 @@ func anAskEndedAtTheChannelIsWrittenAgain(t *testing.T) {
asked := time.Date(2026, 11, 9, 22, 0, 0, 0, time.UTC)
now := asked.Add(8 * 24 * time.Hour)
digest := "sha256:" + strings.Repeat("e", 64)
holdKey, _ := asks.HoldAskKey("nats", fNew)
restoreKey, _ := asks.RestoreAskKey("novox", "nats", fNew)
backupKey, _ := asks.BackupAskKey("novox", "nats", fNew)
revertKey, _ := asks.RevertAskKey("novox", "nats", fNew)
recordKey, _ := asks.RecordAskKey("novox", "nats", digest)
@@ -62,9 +60,7 @@ func anAskEndedAtTheChannelIsWrittenAgain(t *testing.T) {
put *puts.Put
why string // "" when it is written again
}{
{name: "hold", key: holdKey, a: ptr(HoldAsk(holdKey, "nats", fNew, "novox", "w", AskingSeconds(asked), asked)), outcome: occ.OutcomeExpired},
{name: "restore", key: restoreKey, a: ptr(RestoreAsk(restoreKey, "novox", "nats", fNew, "w", AskingSeconds(asked), asked)), outcome: occ.OutcomeCancelled},
{name: "backup", key: backupKey, a: ptr(BackupAsk(backupKey, "novox", "nats", fNew, digest, "w", 0, asked)), outcome: occ.OutcomeCancelled},
{name: "backup", key: backupKey, a: ptr(BackupAsk(backupKey, "novox", "nats", fNew, "w", 0, asked)), outcome: occ.OutcomeCancelled},
{name: "revert", key: revertKey, a: ptr(assignerAsk(AskingSeconds(asked), oc.Ask{ID: meshdeliveryclient.AskingID(revertKey, AskingSeconds(asked)),
Headline: "h", Explanation: "e", Who: occ.Operator, Expires: occ.FormatTime(asked.Add(AskLasts)), OnExpiry: "o",
Options: []oc.Option{{ID: "hold", Label: "Hold", Does: "d", Level: occ.Acknowledge}}})), outcome: occ.OutcomeExpired},
@@ -72,11 +68,11 @@ func anAskEndedAtTheChannelIsWrittenAgain(t *testing.T) {
{name: "record of another put", key: recordKey, a: &record, outcome: occ.OutcomeExpired, put: &other},
{name: "record a put asked", key: recordKey, a: &byPut, outcome: occ.OutcomeExpired, put: &put, why: "put"},
{name: "assignments", key: assignmentsKey, a: &assignments, outcome: occ.OutcomeExpired, why: "ADR 0567"},
{name: "another asking stands", key: holdKey, a: ptr(HoldAsk(holdKey, "nats", fNew, "novox", "w", AskingSeconds(now), now)),
ended: meshdeliveryclient.AskingID(holdKey, AskingSeconds(asked)), outcome: occ.OutcomeExpired, why: "holds the asking"},
{name: "taken away", key: holdKey, ended: "hold-x", outcome: occ.OutcomeExpired, why: "taken away"},
{name: "refused", key: holdKey, a: ptr(HoldAsk(holdKey, "nats", fNew, "novox", "w", 0, asked)), outcome: occ.OutcomeRefused, why: "refused"},
{name: "replaced", key: holdKey, a: ptr(HoldAsk(holdKey, "nats", fNew, "novox", "w", 0, asked)), outcome: occ.OutcomeReplaced, why: "replaced"},
{name: "another asking stands", key: backupKey, a: ptr(BackupAsk(backupKey, "novox", "nats", fNew, "w", AskingSeconds(now), now)),
ended: meshdeliveryclient.AskingID(backupKey, AskingSeconds(asked)), outcome: occ.OutcomeExpired, why: "holds the asking"},
{name: "taken away", key: backupKey, ended: "backup-x", outcome: occ.OutcomeExpired, why: "taken away"},
{name: "refused", key: backupKey, a: ptr(BackupAsk(backupKey, "novox", "nats", fNew, "w", 0, asked)), outcome: occ.OutcomeRefused, why: "refused"},
{name: "replaced", key: backupKey, a: ptr(BackupAsk(backupKey, "novox", "nats", fNew, "w", 0, asked)), outcome: occ.OutcomeReplaced, why: "replaced"},
} {
t.Run(c.name, func(t *testing.T) {
var current []byte
@@ -133,12 +129,12 @@ func anAskEndedAtTheChannelIsWrittenAgain(t *testing.T) {
// answered or another asker's ask, and one the key no longer holds, are not.
func anAskEndedAtTheChannelIsReadAtBind(t *testing.T) {
asked := time.Date(2026, 11, 9, 22, 0, 0, 0, time.UTC)
holdKey, _ := asks.HoldAskKey("nats", fNew)
restoreKey, _ := asks.RestoreAskKey("novox", "nats", fNew)
backupKey, _ := asks.BackupAskKey("novox", "nats", fNew)
hold := HoldAsk(holdKey, "nats", fNew, "novox", "w", AskingSeconds(asked), asked)
restore := RestoreAsk(restoreKey, "novox", "nats", fNew, "w", AskingSeconds(asked.Add(time.Hour)), asked.Add(time.Hour))
backup := BackupAsk(backupKey, "novox", "nats", fNew, "sha256:"+strings.Repeat("e", 64), "w", 0, asked.Add(-time.Hour)) // no asking
holdKey, _ := asks.BackupAskKey("g14", "nats", fNew)
restoreKey, _ := asks.BackupAskKey("ace", "nats", fNew)
hold := BackupAsk(holdKey, "g14", "nats", fNew, "w", AskingSeconds(asked), asked)
restore := BackupAsk(restoreKey, "ace", "nats", fNew, "w", AskingSeconds(asked.Add(time.Hour)), asked.Add(time.Hour))
backup := BackupAsk(backupKey, "novox", "nats", fNew, "w", 0, asked.Add(-time.Hour)) // no asking
held := map[string][]byte{}
for key, a := range map[string]asks.Ask{holdKey: hold, restoreKey: restore, backupKey: backup} {
v, err := EncodeAsk(key, a)
@@ -173,27 +169,27 @@ func anAskEndedAtTheChannelIsReadAtBind(t *testing.T) {
func ptr(a asks.Ask) *asks.Ask { return &a }
func theHoldAskIsValid(t *testing.T) {
key, err := asks.HoldAskKey("mail", fNew)
func theBackupAskIsValid(t *testing.T) {
key, err := asks.BackupAskKey("ace", "mail", fNew)
if err != nil {
t.Fatal(err)
}
now := time.Now()
a := HoldAsk(key, "mail", fNew, "ace", "health failed, phase running: connection refused", 0, now)
a := BackupAsk(key, "ace", "mail", fNew, "health failed, phase running: connection refused", 0, now)
if err := occ.Check(mustAsk(t, a), now); err != nil {
t.Errorf("the router refuses the ask: %v", err)
}
if _, err := EncodeAsk(key, a); err != nil {
t.Errorf("the ask cannot be written: %v", err)
}
// 1906/H3: the ask names the machine whose check failed and the hold's words.
// The ask names the machine whose backup failed and the backup's words.
if !strings.Contains(mustAsk(t, a).Explanation, "on ace") || !strings.Contains(mustAsk(t, a).Explanation, "connection refused") {
t.Errorf("the ask does not name the node and the hold's words: %q", mustAsk(t, a).Explanation)
}
// 1906/H2: an ask written again after a lift is another asking, under an id of its own.
again := HoldAsk(key, "mail", fNew, "ace", "x", 7, now)
// An ask written again is another asking, under an id of its own.
again := BackupAsk(key, "ace", "mail", fNew, "x", 7, now)
if again.Asking != 7 || mustAsk(t, again).ID != meshdeliveryclient.AskingID(key, 7) || mustAsk(t, again).ID == mustAsk(t, a).ID {
t.Errorf("the asking after a lift = %d %s", again.Asking, mustAsk(t, again).ID)
t.Errorf("the asking again = %d %s", again.Asking, mustAsk(t, again).ID)
}
if _, err := EncodeAsk(key, again); err != nil {
t.Errorf("the ask asked again cannot be written: %v", err)
@@ -203,7 +199,7 @@ func theHoldAskIsValid(t *testing.T) {
}
// The join (A1d ruling 1): mesh-sdk no longer refuses another id, no option or no ask in an assigner's ask; EncodeAsk does.
t.Run("EncodeAsk refuses what mesh-sdk no longer does", func(t *testing.T) {
good := HoldAsk(key, "mail", fNew, "ace", "x", 0, time.Unix(100, 0))
good := BackupAsk(key, "ace", "mail", fNew, "x", 0, time.Unix(100, 0))
other := good
other.Asking = 3 // its id is the asking 0's
empty := good
@@ -218,68 +214,11 @@ func theHoldAskIsValid(t *testing.T) {
})
}
// 1906/D3 (ADR 0539 §19): the ask about a data module held on a node is a valid ask of the router and of mesh-sdk's layout at
// its restore key, of a kind the view may answer; it offers restoring (losing the newer writes) and leaving it stopped.
func theRestoreAskIsValid(t *testing.T) {
key, err := asks.RestoreAskKey("ace", "mail", fNew)
if err != nil {
t.Fatal(err)
}
now := time.Now()
a := RestoreAsk(key, "ace", "mail", fNew, "connection refused", 2, now)
if err := occ.Check(mustAsk(t, a), now); err != nil {
t.Errorf("the router refuses the ask: %v", err)
}
if _, err := EncodeAsk(key, a); err != nil {
t.Errorf("the ask cannot be written: %v", err)
}
if _, err := viewstate.ViewAnswerKey(key); err != nil {
t.Errorf("the view may not answer it: %v", err)
}
var ids []string
for _, o := range mustAsk(t, a).Options {
ids = append(ids, o.ID)
}
if len(ids) != 2 || ids[0] != OptionRestore || ids[1] != OptionLeaveStopped {
t.Errorf("options = %v", ids)
}
if !strings.Contains(mustAsk(t, a).Explanation, "connection refused") || !strings.Contains(mustAsk(t, a).Explanation, "ace") {
t.Errorf("the ask does not name the node and the check's words: %q", mustAsk(t, a).Explanation)
}
}
// 1906/D3: the condition for a held fingerprint names the module, the node and the check's words, under the assigner's own
// name (ADR 0437 clause 9), and is cleared under the same key.
// 1952/WM6: the assigner's conditions are findings.
func TestTheAssignersConditions(t *testing.T) {
t.Run("the held condition names module, node and words", heldConditionNamesModuleNodeAndWords)
t.Run("a lifted hold clears its condition saying why", liftedHoldClearsItsConditionSayingWhy)
t.Run("1952/WM6: each said condition is a finding, its clear deletes it, said straight only with no findings bucket", saidConditionsAreFindings)
}
func heldConditionNamesModuleNodeAndWords(t *testing.T) {
c := HeldCondition("mail", fNew, "ace", "connection refused", true, true)
if _, err := occ.EncodeCondition(c); err != nil {
t.Fatalf("the condition is refused: %v", err)
}
if c.State != occ.StateRaised || c.Subject.ID != "mail" || c.Subject.Machine != "ace" || !strings.Contains(c.Explanation, "connection refused") || !strings.Contains(c.Key, "mail") {
t.Errorf("condition = %+v", c)
}
if got := HeldCondition("mail", fNew, "", "", false, false); got.State != occ.StateCleared || got.Key != c.Key {
t.Errorf("cleared = %+v", got)
}
}
// 1906/H2: a hold lifted by itself clears the held condition under its key, saying why.
func liftedHoldClearsItsConditionSayingWhy(t *testing.T) {
c := LiftedCondition("mail", fNew)
if _, err := occ.EncodeCondition(c); err != nil {
t.Fatalf("the condition is refused: %v", err)
}
if c.State != occ.StateCleared || c.Key != HeldCondition("mail", fNew, "ace", "x", true, false).Key || !strings.Contains(c.Resolved, "lifted its hold by itself") {
t.Errorf("condition = %+v", c)
}
}
// 1952/WM6 (ADR 0564 §2, issue 1952 note 16): every condition the assigner says is a finding in its own bucket, under
// `<scope>.<id>.<kind>`, written at the raise and deleted at the clear, and only as a finding: the keeper is the one
// source since the controller's end (novox/hq ADR 0590 §3, issue 1126 B8). Said straight to the router only where the
@@ -290,9 +229,6 @@ func saidConditionsAreFindings(t *testing.T) {
raised, cleared oc.Condition
key string
}{
{HeldCondition("mail", fNew, "ace", "refused", true, true), LiftedCondition("mail", fNew), "module.mail." + strings.TrimPrefix(fNew, meshcatalogclient.SourcePrefix2) + ".held"},
{NodeFailedCondition("ace", "mail", fNew, NodeFailure{Words: "x", Others: []string{"g14"}}, true), NodeFailedCondition("ace", "mail", fNew, NodeFailure{}, false), "module.ace.mail.failed-alone"},
{NeitherCondition("ace", "mail", Holding{Rule: 3, Words: "w"}, true), NeitherCondition("ace", "mail", Holding{}, false), "module.ace.mail.neither"},
{SeatWaitsCondition([]string{"assignments"}), SeatWaitsCondition(nil), "module.mesh-delivery-assigner.seat-states"},
{BackupCondition("ace", "mail", fNew, "disk full", true), BackupCondition("ace", "mail", fNew, "", false), "module.ace.mail." + strings.TrimPrefix(fNew, meshcatalogclient.SourcePrefix2) + ".backup"},
} {
@@ -335,8 +271,7 @@ func TestTheRecordAndBackupAsksAreValid(t *testing.T) {
if err != nil {
t.Fatal(err)
}
dgst := "sha256:" + strings.Repeat("b", 64)
b := BackupAsk(bkey, "ace", "mail", fNew, dgst, "no space left", 0, now)
b := BackupAsk(bkey, "ace", "mail", fNew, "no space left", 0, now)
vkey, err := asks.RevertAskKey("ace", "mail", fNew)
if err != nil {
t.Fatal(err)
@@ -359,15 +294,17 @@ func TestTheRecordAndBackupAsksAreValid(t *testing.T) {
if !strings.Contains(mustAsk(t, b).Explanation, "no space left") || mustAsk(t, b).Options[0].ID != mwc.BackupAgain || mustAsk(t, b).Options[1].ID != mwc.BackupSkip {
t.Errorf("the backup ask = %+v", mustAsk(t, b))
}
// the id binds the ask to the composition and to its number (review round 1, items 3 and 4)
if again := BackupAsk(bkey, "ace", "mail", fNew, dgst, "x", NextBackupAsking(0), now); mustAsk(t, again).ID == mustAsk(t, b).ID {
// the id binds the ask to its number (review round 1, item 4); its key binds it to the build (design 47 H §750: a want names no composition)
if again := BackupAsk(bkey, "ace", "mail", fNew, "x", NextBackupAsking(0), now); mustAsk(t, again).ID == mustAsk(t, b).ID {
t.Errorf("asked again under the same id")
}
if NextBackupAsking(-1) != 0 || NextBackupAsking(0) != 2 || NextBackupAsking(2) != 3 {
t.Errorf("the numbers of the askings: %d %d %d", NextBackupAsking(-1), NextBackupAsking(0), NextBackupAsking(2))
}
if BackupAskDigest(b) != dgst {
t.Errorf("the ask names composition %q, want %q", BackupAskDigest(b), dgst)
// novox 2026-11-16: the router refuses a long hexadecimal string, so no word of an ask carries a digest or fingerprint whole.
held := BackupAsk(bkey, "novox", "mail", fNew, "the kept data between "+fNew+" and "+fNew+" is not known", 0, now)
if a := mustAsk(t, held); regexp.MustCompile(`[0-9a-f]{20,}`).MatchString(a.Headline + a.Explanation + a.Details) {
t.Errorf("the ask carries a long hexadecimal string: %q", a.Explanation)
}
if BackupAnswerWords("again", 0) == BackupAnswerWords("again", 1) {
t.Errorf("two answers of the same option are one want value")
@@ -395,6 +332,7 @@ func TestTheRecordAndBackupAsksAreValid(t *testing.T) {
// ADR 0546 clauses 7 and 8: a put's ask is valid at the record ask's key; for the bus its yes approves and binds the act,
// so the view cannot answer it, and it lasts no longer than an approving ask may.
put := puts.Put{FP: fNew, Why: "the bus's user list", Hold: true}
dgst := "sha256:" + strings.Repeat("b", 64)
d := ComposedDigest{Digest: dgst, Judgement: JudgedCannot, Words: "the have names no composition"}
for _, bus := range []bool{false, true} {
a, err := PutAsk(rkey, "ace", "mail", put, d, bus, now)
@@ -439,22 +377,6 @@ func TestTheRecordAndBackupAsksAreValid(t *testing.T) {
}
}
// 1945/AC21: the condition of a module on neither list is urgent, names the module, the node and the rule holding its want back,
// under the assigner's own name keyed by node and module, and is cleared under the same key.
func TestTheNeitherConditionNamesModuleNodeAndRule(t *testing.T) {
c := NeitherCondition("g14", "i3status-rust", Holding{Rule: mwc.RuleProviders, Words: "no provider of x11-display runs healthy on g14 or at its canary"}, true)
if _, err := occ.EncodeCondition(c); err != nil {
t.Fatalf("the condition is refused: %v", err)
}
if c.State != occ.StateRaised || c.Severity != occ.SeverityUrgent || c.Subject.ID != "i3status-rust" || c.Subject.Machine != "g14" ||
!strings.Contains(c.Explanation, "x11-display") || !strings.Contains(c.Explanation, "rule 5") || c.Key != "mesh-delivery-assigner.neither.g14.i3status-rust" {
t.Errorf("condition = %+v", c)
}
if got := NeitherCondition("g14", "i3status-rust", Holding{}, false); got.State != occ.StateCleared || got.Key != c.Key {
t.Errorf("cleared = %+v", got)
}
}
// mustAsk is the router's ask an asks-state value carries.
func mustAsk(t *testing.T, a asks.Ask) oc.Ask {
t.Helper()
@@ -154,18 +154,3 @@ func (f Findings) Say(say func(oc.Condition) error) func(oc.Condition) error {
return errors.Join(errs...)
}
}
// KindActingCycle is the finding of a want held on a cycle of acting waits no rule breaks (design 47 G A-323, A-330): scope module,
// id `<node>.<module>` of the held want, naming the cycle with each edge's step; cleared by the next pass that finds it held on no
// cycle.
const KindActingCycle = "acting-cycle"
// ActingCycleFinding is the finding acting-cycle of module's want on node, held on cycle.
func ActingCycleFinding(node, module, cycle string) Observed {
return Observed{Scope: mcc.ScopeModule, ID: node + "." + module, Kind: KindActingCycle, Machine: node, Severity: "warning",
Summary: fmt.Sprintf("the want of %s on %s is held on a cycle of acting waits: %s", module, node, cycle),
Headline: fmt.Sprintf("%s on %s waits on a cycle of acting parts", module, node),
Explanation: fmt.Sprintf("Each acting part on the cycle %s waits for another's new version to run, so none moves by itself. "+
"assigner_release lets one move with the version running.", cycle),
Source: "assigner." + KindActingCycle}
}
@@ -6,13 +6,11 @@ import (
"mesh-delivery-assigner/internal/assignment"
"mesh-delivery-assigner/internal/buckets"
"sort"
"strings"
"time"
mcc "git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshconditionsclient"
mcseat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
occ "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/clients/operatorchannelclient"
"git.novox.be/novox/mesh-contracts/provisioning/go/clients/meshprovisionerclient"
"git.novox.be/novox/mesh-sdk/go/catalogue"
)
@@ -48,66 +46,15 @@ func PolicyOf(m catalogue.Manifest, chosen map[string]catalogue.PersonPolicy) (p
return catalogue.Upgrade(m, c)
}
func contains(list []string, s string) bool {
for _, v := range list {
if v == s {
return true
}
}
return false
}
// KindProvisionFailed is the assigner's finding of a provision its module's want waits for that failed (ADR 0570 §4).
const KindProvisionFailed = "provision-failed"
// ProvisionFailedKey is a failed provision's finding's key, `provider.<node>.<consumer>.<provision>[.<local>].provision-failed`.
func ProvisionFailedKey(key string) string {
return mcc.Key(mcc.ScopeProvider, key, KindProvisionFailed)
}
// ProvisionFailedFinding is the finding of a failed provision, naming its consumer, its provider and why.
func ProvisionFailedFinding(key string, p meshprovisionerclient.Provision, at time.Time) (mcseat.Finding, error) {
summary := fmt.Sprintf("%s for %s on %s failed at %s on %s: %s, so %s is not moved there until it is provided", p.Provision,
p.Consumer.Module, p.Consumer.Node, p.Provider.Module, p.Provider.Node, p.Why, p.Consumer.Module)
return encode(Observed{Scope: mcc.ScopeProvider, ID: key, Kind: KindProvisionFailed, Machine: p.Consumer.Node, Also: also(p.Provider.Node, p.Consumer.Node),
Summary: summary, Said: p.Why, Headline: clipHeadline(p.Consumer.Module + " waits for a provision that failed"),
Explanation: occ.NothingToDo + " " + summary + ". It clears once the provider provides it.",
Source: "assigner." + KindProvisionFailed}, at)
}
// encode is the observation as the assigner's finding at at.
func encode(o Observed, at time.Time) (mcseat.Finding, error) { return o.Finding(at), nil }
func also(provider, consumer string) []string {
if provider == "" || provider == consumer {
return nil
}
return []string{provider}
}
// KindProvisionMissing is the assigner's finding of a required provision that has had no key for longer than its bound.
const KindProvisionMissing = "provision-missing"
// ProvisionMissingKey is its key, `provider.<node>.<module>.<provision>.provision-missing`.
func ProvisionMissingKey(key string) string {
return mcc.Key(mcc.ScopeProvider, key, KindProvisionMissing)
}
// ProvisionMissingFinding is the finding of a required provision with no key past bound (key `<node>.<module>.<provision>`).
func ProvisionMissingFinding(key string, bound time.Duration, at time.Time) (mcseat.Finding, error) {
parts := strings.SplitN(key, ".", 3)
if len(parts) != 3 {
return mcseat.Finding{}, fmt.Errorf("%q is not <node>.<module>.<provision>", key)
}
node, module, provision := parts[0], parts[1], parts[2]
summary := fmt.Sprintf("%s on %s requires %s and mesh-provisioner has composed no key for it in %s, so %s is not moved there: "+
"no provider of it may be placed", module, node, provision, bound, module)
return encode(Observed{Scope: mcc.ScopeProvider, ID: key, Kind: KindProvisionMissing, Machine: node,
Summary: summary, Headline: clipHeadline(module + " on " + node + " lacks " + provision),
Explanation: occ.NothingToDo + " " + summary + ". It clears once the provision has its key.",
Source: "assigner." + KindProvisionMissing}, at)
}
// KindUnplaced is, from the lease write, a node that runs but no assignments names (ADR 0571 §6).
const KindUnplaced = "unplaced"
@@ -79,6 +79,23 @@ func StepPut(w PutWorld) PutNext {
if !w.Assigned {
return say(puts.Refused, "%s is not assigned to %s: a put moves a module where it stands assigned (propose its assignments first)", w.Module, w.Node)
}
if p.Step != puts.Wanted && p.Step != puts.Holding && w.Build == "" {
// Only where the builder's store holds no build of it: one it built goes the put's whole way (composition, the yes).
if r := w.Running; r != nil && !r.Stopped && r.Fingerprint != "" && r.Fingerprint == p.FP {
// The build the node runs now (design 47 G A-427): read from the node's running statement, held there with the
// composition its have names, and the builder's store is not asked for it (a part started by hand has none there).
if h := w.Have; h == nil || h.Fp != p.FP || h.Composed == "" {
return say(puts.Refused, "%s runs %s at %s, and its have names no composition at that fingerprint, so the want cannot name what runs", w.Node, w.Module, fp)
}
p.Composed = w.Have.Composed
words := fmt.Sprintf("the want of %s on %s names %s, the build it runs now (composition %s), from its running statement; the builder's store is not asked",
w.Module, w.Node, fp, short(p.Composed))
if p.Hold {
words += ", held until released"
}
return PutNext{Put: applied(w, p.Said(w.Now, puts.Wanted, words))}
}
}
switch w.Build {
case builds.BuildDone:
case builds.BuildFailed:
@@ -86,8 +103,13 @@ func StepPut(w PutWorld) PutNext {
case "":
if p.FP != w.Newest {
// The builder builds the trunk's newest fingerprint and the candidates', and takes no ask for another yet (ADR 0546
// clause 3): an older fingerprint it never built, or whose key it removed, cannot be put.
return say(puts.Refused, "the builder holds no build of %s at %s, and builds by itself only the trunk's newest (%s): put that, or a version it built", w.Module, fp, short(w.Newest))
// clause 3): an older fingerprint it never built, or whose key it removed, cannot be put; the build the node runs now
// can (A-427), and the refusal names it.
runs := "states no running build of it"
if r := w.Running; r != nil && !r.Stopped && r.Fingerprint != "" {
runs = "runs " + short(r.Fingerprint)
}
return say(puts.Refused, "the builder holds no build of %s at %s, and builds by itself only the trunk's newest (%s), and %s %s by its running statement: put that, or a version the builder built", w.Module, fp, short(w.Newest), w.Node, runs)
}
return say(puts.Build, "waits for the builder's build of %s at %s, the trunk's newest, which it builds by itself", w.Module, fp)
default:
@@ -190,9 +212,9 @@ func needsPerson(w PutWorld, d ComposedDigest) bool {
return d.Judgement == JudgedRecreates || d.Judgement == JudgedMovesData || d.Judgement == JudgedCannot
}
// PutWant is the want a put writes once it is wanted: the fingerprint and composition, marked put, and held when it holds.
// PutWant is the want a put writes once it is wanted: the fingerprint, marked put, and held when it holds.
func PutWant(p puts.Put) mwc.Want {
return mwc.Want{Fp: p.FP, Composed: p.Composed, Put: true, Hold: p.Hold, Words: "put: " + p.Why}
return mwc.Want{Fp: p.FP, Put: true, Hold: p.Hold, Words: "put: " + p.Why}
}
// PutOwns says what a put does to the node's want: owns says the rules pass over it, want the want it writes (nil: what
@@ -0,0 +1,46 @@
package assign
import (
"fmt"
"strings"
"time"
mcseat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
"git.novox.be/novox/mesh-sdk/go/views"
)
// KindAssignmentUnlisted is a module assigned to a node that no watched branch lists, left out of that node's composition
// (design 47 H-A-148, H-A-149): scope delivery, id `<node>.<module>`, severity warning.
const (
KindAssignmentUnlisted = "assignment-unlisted"
ScopeAssignmentUnlisted = "delivery"
)
// UnlistedKey is its finding's key, `delivery.<node>.<module>.assignment-unlisted`.
func UnlistedKey(node, module string) string {
return views.FindingKey(ScopeAssignmentUnlisted, KeyID(node+"."+module), KindAssignmentUnlisted)
}
// UnlistedOfKey is the node and module of an assignment-unlisted finding's key, or false for another finding's.
func UnlistedOfKey(key string) (node, module string, ok bool) {
rest, ok := strings.CutPrefix(key, ScopeAssignmentUnlisted+".")
if !ok {
return "", "", false
}
if rest, ok = strings.CutSuffix(rest, "."+KindAssignmentUnlisted); !ok {
return "", "", false
}
node, module, ok = strings.Cut(rest, ".")
return node, module, ok && node != "" && module != "" && !strings.Contains(module, ".")
}
// UnlistedFinding is the finding of module assigned to node and listed on none of its watched branches, raised by the composition
// step that leaves the assignment out (H-A-149).
func UnlistedFinding(node, module string, at time.Time) (mcseat.Finding, error) {
summary := fmt.Sprintf("%s is assigned %s, which no watched branch lists, so its composition leaves the assignment out", node, module)
return encode(Observed{Scope: ScopeAssignmentUnlisted, ID: node + "." + module, Kind: KindAssignmentUnlisted, Machine: node,
Severity: mcseat.FindingSeverityWarning, Summary: summary, Headline: clipHeadline(module + " on " + node + " is listed nowhere"),
Explanation: summary + ": a stale assignment is a fault of the assignments, not of the change judged (ADR 0578 §2). " +
"Take it off, or register the module on a watched branch.",
Source: "assigner." + KindAssignmentUnlisted}, at)
}
@@ -1,38 +0,0 @@
package assign
import (
"slices"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/graph"
)
// verbWaiting says why the module's want on node waits for a verb it invokes (novox/hq ADR 0614 §2): the first seat verb or
// module tool of Invokes (the module graph's verb edges, those it leaves out on a cycle not among them, §3) that no
// running healthy build serves. Nil Served (nothing read of what runs) waits for none, and a verb a running build serves
// already adds no wait. It holds under the provisions' rule (RuleProvisions): no reader knows a rule number of its own
// yet, so the words name the edge (graph.VerbWaitWords, which the delivery view reads).
func (m Module) verbWaiting(node string) (string, bool) {
if m.Served == nil {
return "", false
}
for _, v := range slices.Sorted(slices.Values(m.Invokes)) {
if !m.Served(v) {
return graph.VerbWaitWords(v, m.Name, node), true
}
}
return "", false
}
// busStateWaiting says why the module's want on node waits for bus state (ADR 0614 §5): its manifest asks bus state (a
// bus-state entry, as the module graph reads it) and no build whose manifest offers bus-state runs healthy on a node
// present. The provision bus-state is answered with no credential of a consumer's own, so ADR 0603 §5 counts the
// provider's own have and no provisioner key is waited for, handed or not. Nil Offering (nothing read of what runs) waits
// for none, and neither does a module that offers bus-state itself. It holds under the provisions' rule, its words naming bus state (graph.BusStateWaitWords).
func (m Module) busStateWaiting(node string) (string, bool) {
if len(m.Manifest.BusState) == 0 || m.Offering == nil || m.Offering(graph.BusState) ||
slices.Contains(m.Manifest.Offers(), graph.BusState) { // the bus module offering it waits on nobody for it
return "", false
}
return graph.BusStateWaitWords(m.Name, node), true
}
@@ -2,359 +2,79 @@ package assign
import (
"fmt"
"slices"
"strings"
"git.novox.be/novox/mesh-contracts/go/clients/nodeengineclient"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
mwc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/catalogkey"
"git.novox.be/novox/mesh-delivery/modules/mesh-grants/grantsstate"
"maps"
"mesh-delivery-assigner/internal/puts"
"slices"
"sort"
"strings"
"time"
"git.novox.be/novox/mesh-contracts/provisioning/go/clients/meshprovisionerclient"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-builder/builds/forms"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/graph"
"mesh-delivery-assigner/internal/puts"
)
// Module is what the six rules read of one module (ADR 0429 §6, ADR 0528 clause 3): its newest fingerprint F at the
// trunk (the indexer's modules), whether the builder's build of F is done, whether F is held, whether the controller
// issued its credential for F, its manifest at F, and the nodes it is assigned to.
// A want names the newest released version whose pipeline passed (design 47 H §750): for every node whose assignment places
// a module on a watched branch, the want names the version, the pipeline and the mover's rank in it, written tier by tier
// (§751). It is held for nothing else: the rules of ADR 0429 §6 (the build done, not held, the canary and step, every
// provider healthy, the grant, the composition and the reader capabilities, the provisions, the served verbs and the bus
// state), the network hold and A-428's exceptions end (H-A-55). A put owns its node's want as before (ADR 0546), and the
// operator's yes on a module of policy record is the node-engine's have and the asker's (the pass's yeses).
// Target is the build a node's want names: its fingerprint and released version, with the pipeline whose passed end released
// it and the mover's rank in that pipeline; a placement's build names no pipeline and no rank (design 47 H §750, H-A-37).
type Target struct {
Fp string
Version string
Pipeline string
Rank int64
}
// Module is what the want rule reads of one module: the nodes it is assigned to, the build each node's want names, the puts
// that own a node's want and the nodes that compose it themselves.
type Module struct {
Name string
FP string
Built bool
// BuildFailed and BuildError say a build that ended failed, with the error as the builder's `build.ended` carries it whole
// (design 47 G §575, A-162): the words of a hold under rule 1.
BuildFailed bool
BuildError string
Held bool
Granted bool
// GrantedAt says whether the controller issued the module's credential for another fingerprint than FP: the first want of a node
// that runs an older one names it (issue 1945). Nil: none.
GrantedAt func(fp string) bool
// GrantedOn says whether the controller's grant of FP names the module's accounts on a node, when the grant names any:
// a grant written for the module's other nodes says nothing of a node whose account is not issued and sealed (issue
// 1945, live on 2026-10-25 at 20:04: ace's mesh-build-go was wanted with no account on the bus). Nil: the grant alone.
GrantedOn func(node string) bool
Manifest catalogue.Manifest
// Provisions is the seat mesh-provisioner's provisions this module consumes on a node, by key (ADR 0570 §4): the want
// waits until each is provided. Nil: the seat's state is not read (not delivered yet), and nothing waits on it.
Provisions func(node string) map[string]meshprovisionerclient.Provision
// Answering is the manifests of the modules placed somewhere that provide a provision: what catalogue.Awaited
// judges a want's provisions by (issue 774). Nil: none known, and no key is waited for that is not there.
Answering func(provision string) []catalogue.Manifest
// Offered says whether any module offers a provision by name or by its own name (catalogue.Manifest.Offers) among every
// manifest the trunk holds and the modules the mesh provides itself, placed or not. Nil: not known, and no requirement
// is waited on for want of an offer.
Offered func(provision string) bool
// Invokes are the seat verbs and module tools the module graph says the module invokes and keeps as edges to the
// modules serving them, those it leaves out on a cycle not among them (ADR 0614 §2, §3): the want waits until each is
// served (Served). Nil: no graph node is read, and no want waits on a verb.
Invokes []string
// Served says whether a build serving a seat verb or module tool runs healthy, counted from its holder's have (ADR 0614
// §2, as ADR 0603 §5 counts a provider's). Nil: nothing is read of what runs, and no want waits on a verb.
Served func(invoke string) bool
// Offering says whether a build whose manifest offers a provision runs healthy on a node present, counted from the
// provider's own have (ADR 0603 §5): what a want asking bus state waits for (ADR 0614 §5). Nil: nothing is read of what
// runs, and no want waits on bus state.
Offering func(provision string) bool
Name string
Manifest catalogue.Manifest
// Chosen is a person's choice of the module's upgrade policy (the assigner's `policies`, ADR 0565 §7); nil: none.
Chosen *catalogue.PersonPolicy
Nodes []string
// Composed answers the composition of the module for a node at a fingerprint: the digest the node's own have names (a
// placed node composes its own, ADR 0571 §6), and whether it names one. Nil: none exists (ADR 0539 §1, §6).
Composed func(node, fp string) (ComposedDigest, bool)
// Target is the build node's want names: the newest version of the module released on the branch the node's placement
// names whose pipeline passed and whose tier is written (§750, §751), or the placement's build (H-A-5); false: none yet,
// and the want written stays.
Target func(node string) (Target, bool)
// Allowed says whether the operator answered yes to the record ask about the move of this module on node to the composition
// with this digest (ADR 0539 §14). Nil: none did.
Allowed func(node, digest string) bool
// Released is a hold on FP the operator released (ADR 0539 §19): FP is not held again by a health check that failed.
Released bool
// Restored says whether the operator answered "restore" to the restore ask of this data module on node: it is then set back
// as any module is, losing the writes made since (ADR 0539 §19). Nil: none did.
Restored func(node string) bool
// Kept says the operator answered "keep" to the hold ask of FP: a hold kept so is not lifted by itself.
Kept bool
// Now is when this pass reads the haves: the held record names it as when the health check was seen to fail. Zero: not said.
Now time.Time
// Puts are the puts of the module, by node (ADR 0546): while one owns a node's want (PutOwns), the rules pass over it.
// Puts are the puts of the module, by node (ADR 0546): while one owns a node's want (PutOwns), the rule passes over it.
Puts map[string]puts.Put
// Needs are the reader capabilities the manifest at FP needs (the indexer's modules value, catalogue.ManifestNeeds, ADR
// 0614 §4): a node's want moves only while that node's engine states each of them. Nil: none.
Needs []string
// FormNeeds are the reference forms the module's build at FP is written in (`form:<name>`, the builder's build key's
// needs, ADR 0618 §1): a node's want is held only while that node's engine reads none of them (ADR 0624 §2). Nil: the
// build names none, and holds nothing.
FormNeeds []string
// Self says whether node composes the module itself: the catalogue's assignments names the node (ADR 0547 §2). It is the one
// source of a want's Self: every want the rules write or keep is derived from it (selfDerived), so a want written Self while
// the node was placed does not outlive the assignments (issue 1126). Nil: no node does.
// Self says whether node composes the module itself: the catalogue's assignments names the node (ADR 0547 §2). Nil: no
// node does.
Self func(node string) bool
// KeptBuilds answers what a want at a fingerprint names of its build: its parts and its keeping node as the builder's `build.ended`
// names them, or the released version and parts of the catalog's `version-released` (design 47 G §379, §526, A-96), for a node that states the capability WantParts. Nil: none is read.
KeptBuilds func(fp string) (KeptBuild, bool)
// MachineHeld says whether the node's own network condition is open, which holds the machine as a whole: no want moves to it
// until that clears (design 47 G §706 *M's own network*). Nil: none is held.
MachineHeld func(node string) bool
// Acting are the acting edges of the assignment graph entry of this module on node that the assigner holds (composing, placing)
// and whose wait was not released by hand (design 47 G §266, §268): the want moves only once each acting part's version runs
// on the edge's node, as Nodes.Running says it. Nil: none.
Acting func(node string) []ActingEdge
}
// ActingEdge is one acting edge: Part's version Fp acts in Step on Node, before the entry moves.
type ActingEdge struct{ Node, Part, Fp, Step string }
// Runs says the part's version of the edge runs on its node, as the node-engine seat's `running` says it.
func (n Nodes) Runs(e ActingEdge) bool {
if n.Running != nil {
r, ok := n.Running[e.Node][e.Part]
return ok && !r.Stopped && r.Fingerprint == e.Fp
}
h, ok := n.Haves[e.Node][e.Part]
return ok && healthy(h, e.Fp)
}
// actingWaiting says why the module's want on node waits for an acting part's new version (§266): the first edge not run.
func (m Module) actingWaiting(node string, n Nodes) (string, bool) {
if m.Acting == nil {
return "", false
}
for _, e := range m.Acting(node) {
if !n.Runs(e) {
return fmt.Sprintf("%s on %s waits in %s for %s at %s to run on %s", m.Name, node, e.Step, e.Part, short(e.Fp), e.Node), true
}
}
return "", false
}
// WantParts is the capability a node-engine of G states (ADR 0614 §4, design 47 G §525): it reads a want's `parts` and `kept-on`.
const WantParts = "want-parts"
// KeptBuild is what a want names of a build: the digest of each of its parts by `<module>:<artifact>`, and, as the builder's
// `build.ended` says it, the build node that keeps a kept build; for a trunk build the released version the catalog's
// `version-released` says (design 47 G §379, §526, A-96).
type KeptBuild struct {
Parts map[string]string
KeptOn string
Version string
}
// withKept is w naming the kept build at its fingerprint, the parts by digest and the keeping node, only while the node's
// engine states WantParts (design 47 G §525, §526); a want of a build that is not kept, or of a node that does not state it,
// is w.
func (n Nodes) withKept(m Module, node string, w mwc.Want) mwc.Want {
if m.KeptBuilds == nil {
return w
}
k, ok := m.KeptBuilds(w.Fp)
if !ok || !slices.Contains(n.Reads[node], WantParts) {
return w
}
w.Parts, w.KeptOn, w.Version = k.Parts, k.KeptOn, k.Version
return w
// ReadsVersion says whether node's node-engine states that it reads a want by version (the word want:version of the seat
// node-engine, design 47 H §772, H-A-45); a node whose engine does not is written its want held, awaiting its hand placement
// (H-A-73). Nil: every node does.
ReadsVersion func(node string) bool
}
func (m Module) selfOn(node string) bool { return m.Self != nil && m.Self(node) }
func (m Module) composition(node, fp string) (ComposedDigest, bool) {
if m.Composed == nil {
return ComposedDigest{}, false
}
return m.Composed(node, fp)
}
// Node is what the rules read of the nodes: whether each is online (the watchman's presence) and each module's have.
// Nodes is what the pass reads of the nodes: whether each is online (the watchman's presence), each module's have and the
// node-engine seat's last `running`.
type Nodes struct {
Online map[string]bool
Haves map[string]map[string]nodeengine.HaveByNodeModuleValue
// Running is, by node and module, the last `running` the node-engine seat said (design 47 G §309): a provider runs healthy
// while the build it runs does, as this says it, whatever a newer want of it waits for (rule 5, main file *A provider
// before its consumers*). Nil: the seat's events are not heard, and the have says it.
// Running is, by node and module, the last `running` the node-engine seat said (design 47 G §309). Nil: the seat's events
// are not heard.
Running map[string]map[string]nodeengine.Running
// Providers is, by provision, the modules that provide it, with the nodes each is assigned to.
Providers map[string]map[string][]string
// Reads is, by node, the reader capabilities its node-engine states in its node record (nodeengine.NodeRecord.ManifestReads,
// ADR 0614 §4). A node with none, or none read, is read as stating the baseline (catalogue.StatedManifestReads).
// Reads is, by node, the reader capabilities its node-engine states (nodeengine.NodeRecord.ManifestReads, ADR 0614 §4).
Reads map[string][]string
}
// healthy says whether a have runs fp healthy.
func healthy(h nodeengine.HaveByNodeModuleValue, fp string) bool {
return h.Fp == fp && h.Phase == nodeengineclient.PhaseRunning && h.Health == nodeengineclient.HealthOK
}
// Failed says whether a have's health check failed once the node is done moving.
func Failed(h nodeengine.HaveByNodeModuleValue) bool { return failed(h) }
// Canary is the module's canary: the first of its nodes, by name, that is online (ADR 0435 §3; one ring, ordered by
// name, ADR 0528 clause 3). Empty when none is online.
func Canary(nodes []string, online map[string]bool) string {
sorted := slices.Sorted(slices.Values(nodes))
for _, n := range sorted {
if online[n] {
return n
}
}
return ""
}
// Holds is whether every rule holds for moving node's want for m to m.FP, and if not, the first rule that does not,
// with why (ADR 0429 §6). Rule 4, at most `step` others ahead, always holds: the mesh keeps no step, and step 0 is no
// limit (ADR 0528 clause 3). Rule 5, every provider healthy, holds no want (issue 1960): a module whose provider is down
// is wanted all the same, and said as not reached (Unreached), since a site runs while the proxy in front of it is
// down and one module never blocks another.
func Holds(m Module, node string, n Nodes) (bool, int, string) {
return holds(m, node, n, true)
}
// holds is Holds; with ordering false it leaves out the canary (3), which orders a move among nodes, and keeps those
// without which there is nothing to want: the build done, not held, the grant and the composition.
func holds(m Module, node string, n Nodes, ordering bool) (bool, int, string) {
switch {
case !m.Built:
if m.BuildFailed {
return false, mwc.RuleBuildDone, fmt.Sprintf("the build of %s at %s failed: %s", m.Name, short(m.FP), m.BuildError)
}
return false, mwc.RuleBuildDone, fmt.Sprintf("the build of %s at %s is being built", m.Name, short(m.FP))
case m.Held:
return false, mwc.RuleNotHeld, fmt.Sprintf("%s is held at %s", m.Name, short(m.FP))
case m.MachineHeld != nil && m.MachineHeld(node):
return false, mwc.RuleNotHeld, fmt.Sprintf("the condition machine.%s.network is open: no want moves to %s until its own network is healthy", node, node)
}
if ordering {
canary := Canary(m.Nodes, n.Online)
switch {
case canary == "":
return false, mwc.RuleCanary, fmt.Sprintf("none of the nodes of %s is online, so it has no canary", m.Name)
case node != canary && !n.RunsHealthy(canary, m.Name, m.FP):
return false, mwc.RuleCanary, fmt.Sprintf("the canary %s does not run %s healthy yet", canary, short(m.FP))
}
}
if !m.Granted {
return false, mwc.RuleGrant, fmt.Sprintf("the controller has not issued the credential of %s for %s", m.Name, short(m.FP))
}
if m.GrantedOn != nil && !m.GrantedOn(node) {
return false, mwc.RuleGrant, fmt.Sprintf("the controller has not issued the credential of %s on %s for %s", m.Name, node,
short(m.FP))
}
if words, lacking := m.readerLacking(node, n); lacking {
return false, mwc.RuleComposed, words
}
if _, ok := m.composition(node, m.FP); !ok {
return false, mwc.RuleComposed, fmt.Sprintf("%s has named no composition of its own for %s at %s yet", node, m.Name, short(m.FP))
}
if words, waiting := m.actingWaiting(node, n); waiting {
return false, mwc.RuleComposed, words
}
if words, waiting := m.provisionWaiting(node); waiting {
return false, mwc.RuleProvisions, words
}
if words, waiting := m.verbWaiting(node); waiting {
return false, mwc.RuleProvisions, words
}
if words, waiting := m.busStateWaiting(node); waiting {
return false, mwc.RuleProvisions, words
}
return true, 0, ""
}
// readerLacking says why the module's want on node is held for the node's engine (ADR 0614 §4): a reader capability its
// manifest needs that the engine does not state, read as the baseline when it states none, a bootstrapped seat counting as
// read by every engine (graph.MissingReads, ADR 0636 §2). It is held under rule 7 (the
// composition), since no rule of its own is numbered in this release, with words naming the capability; it moves once the
// engine states it. The node-engine's own new build is held only by a word of its own manifest no engine states.
//
// A build's reference forms hold the want only when the engine reads none of them (ADR 0624 §2): every engine reads a
// first form, so a build written in one is never held by its forms; the words name the forms it reads none of.
func (m Module) readerLacking(node string, n Nodes) (string, bool) {
missing := graph.MissingReads(m.Needs, n.Reads[node])
if len(missing) == 0 && forms.Current.Held(m.FormNeeds, n.Reads[node]) {
missing = slices.Clone(m.FormNeeds)
}
if len(missing) == 0 {
return "", false
}
return graph.ReaderWaitWords(node, missing, m.Name, short(m.FP)), true // the words the delivery view names the edge by
}
// provisionWaiting says why the module's want on node waits for a provision (ADR 0570 §4): a provision it requires that has
// no key yet, or the first of its keys that is not provided. Nil Provisions (the seat's state not on the bus) waits for none.
func (m Module) provisionWaiting(node string) (string, bool) {
if m.Provisions == nil {
return "", false
}
if missing := m.MissingProvisions(node); len(missing) > 0 {
return fmt.Sprintf("provision %s has no key yet for %s on %s", missing[0], m.Name, node), true
}
keyed := m.Provisions(node)
// Only a provision the newest manifest still requires is waited on (ADR 0603 §9): a key of an older revision's edge,
// asked or retiring for the operator's answer (ADR 0570 §5), holds nothing. A requirement catalogue.Awaited leaves out is
// not waited on when something offers it (a module's own name, a module the mesh provides itself, a provision the
// composition does not key: optional, a toolchain on the module's own machine, a login the controller makes). One that
// nothing offers is waited on (ADR 0603 §5: an unknown provider has provided nothing), so a consumer never moves ahead of
// a provider whose module the indexer has not yet taken in; it holds loudly, since the watchman raises the hold past its
// bound (ADR 0603 §8).
needed := m.Manifest.Requires
if m.Answering != nil {
needed = catalogue.Awaited(m.Manifest, m.Answering)
have := map[string]bool{}
for _, p := range keyed {
have[p.Provision] = true
}
for _, r := range slices.Sorted(slices.Values(m.Manifest.Requires)) {
if have[r] && !m.Manifest.OptionalRequires[r] && !slices.Contains(needed, r) {
needed = append(needed, r) // the provisioner keys it from the manifests, whoever is placed yet
continue
}
if m.Offered == nil || m.Manifest.OptionalRequires[r] || len(m.Answering(r)) > 0 || m.Offered(r) || slices.Contains(needed, r) {
continue
}
needed = append(needed, r)
if !have[r] {
return fmt.Sprintf("no module offers %s yet for %s on %s: an unknown provider has provided nothing, so the want waits for one, and the watchman raises it past its bound", r, m.Name, node), true
}
}
}
for _, key := range slices.Sorted(maps.Keys(keyed)) {
if p := keyed[key]; p.State != meshprovisionerclient.Provided && slices.Contains(needed, p.Provision) {
words := fmt.Sprintf("the provision %s of %s on %s is %s, not provided", key, m.Name, node, p.State)
if p.Why != "" {
words += ": " + p.Why
}
return words, true
}
}
return "", false
}
// MissingProvisions are the provisions a want of the module waits for (catalogue.Awaited, the one rule the plan
// composition and the seat mesh-provisioner key by, issue 774) that have no key on node yet, sorted; none while the
// seat's state is not read. A requirement the composition keys nothing for (a toolchain on the module's own machine, a
// login the controller still makes for a module not handed) is not waited for: on 2026-10-30 every new build of
// grafana, dnsmasq, mesh-knowledge, mesh-mail and the builders waited here for a key nobody would make.
func (m Module) MissingProvisions(node string) []string {
if m.Provisions == nil || m.Answering == nil {
return nil
}
have := map[string]bool{}
for _, p := range m.Provisions(node) {
have[p.Provision] = true
}
var out []string
for _, r := range catalogue.Awaited(m.Manifest, m.Answering) {
if !have[r] {
out = append(out, r)
}
}
return out
}
// runsHealthy says whether module runs healthy on node: the node-engine seat's last `running` of it names a build, does not say it
// stopped and does not say `healthy` false (design 47 G §520); nothing heard of it counts as not healthy.
func (n Nodes) runsHealthy(node, module string) bool {
@@ -363,312 +83,53 @@ func (n Nodes) runsHealthy(node, module string) bool {
}
// RunsHealthy says whether the build of module at fp runs healthy on node, from the node-engine seat's last `running` of it alone
// (design 47 G §520): a `running` with no `healthy`, said by a node-engine of before G, reads as healthy while it stands, and a
// module of which nothing was heard counts as not healthy. The have is never read for it.
// (design 47 G §520). The have is never read for it.
func (n Nodes) RunsHealthy(node, module, fp string) bool {
r, ok := n.Running[node][module]
return ok && n.runsHealthy(node, module) && r.Fingerprint == fp
}
// providedHealthy is rule 5 for one provision: some module providing it runs healthy on the node, or, assigned
// elsewhere only, at its canary. A provision no module provides is not a module's to judge (the mesh or the node
// offers it) and holds.
func providedHealthy(provision, node string, n Nodes) (bool, string) {
providers := n.Providers[provision]
if len(providers) == 0 {
return true, ""
}
names := make([]string, 0, len(providers))
for p := range providers {
names = append(names, p)
}
sort.Strings(names)
for _, p := range names {
nodes := providers[p]
at := node
if !slices.Contains(nodes, node) {
at = Canary(nodes, n.Online)
}
if at != "" && n.runsHealthy(at, p) {
return true, ""
}
}
return false, fmt.Sprintf("no provider of %s runs healthy on %s or at its canary", provision, node)
}
// unreached is why m on node may be wanted and not reached: the first provision it requires that no provider runs
// healthy on node or at its canary (rule 5, said and never holding a want; issue 1960); empty when all do.
func unreached(m Module, node string, n Nodes) string {
for _, provision := range m.Manifest.Requires {
if ok, why := providedHealthy(provision, node, n); !ok {
return why
}
}
return ""
}
// keepsData says whether a module holds data a set-back would lose: an own item of a class that keeps (irreplaceable,
// valuable or rebuildable; cache and none do not).
func keepsData(m catalogue.Manifest) bool {
for _, it := range m.DataItems() {
if it.Class == catalogue.ClassIrreplaceable || it.Class == catalogue.ClassValuable || it.Class == catalogue.ClassRebuildable {
return true
}
}
return false
}
// Outcome is what one module's pass decides: each node's want to write (only those that change), and a hold to write.
// Outcome is what one module's pass decides: each node's want to write (only those that change).
type Outcome struct {
Wants map[string]mwc.Want
// Held is the hold of m.FP to write, when a node's health check failed on it and it is not held yet.
Held *mwc.Held
// Lifted is the hold of m.FP lifted by itself: every node that runs the module runs m.FP healthy (issue 1906). The held
// record and its ask are taken away, and the wants move by the rules again in this pass.
Lifted bool
// NodeFailed is, by node, a failed health check of m.FP on a node while another node runs m.FP healthy: the failure is
// that node's, so m.FP is not held and nothing is set back (ADR 0557 §1, issue 1496). The pass raises its condition once.
NodeFailed map[string]NodeFailure
// Record is the moves a person must allow before the want names them: each is asked once (ADR 0539 §14).
Record []RecordNeed
// Restore is the nodes of a module holding data whose held fingerprint failed its health check there and that are not set
// back: the operator is asked whether to restore each (ADR 0539 §19).
Restore []string
// Rules is, by node, the rule holding the node back from m.FP and why.
Rules map[string]Holding
// Unreached is, by node, why the module may be wanted there and not reached: no provider of a provision it requires runs
// healthy (rule 5, issue 1960). It holds no want back; the pass says it.
Unreached map[string]string
// Neither is, by node, the nodes the module is assigned to that run it (or whose have names it), hold no want for it after this
// pass and are not held (a held module is on the held list), with the rule holding the first want back: the node's own composition does not hold a module with a fingerprint of the new form, so such a module is on
// neither list and nothing applies it on that node (issue 1945). A module with no fingerprint of the new form goes with the node's
// own composition and is never here.
Neither map[string]Holding
}
// RecordNeed is a move of a module of policy record on a node that waits for the operator's yes: the composition's digest, the
// controller's judgement of the move and its words.
type RecordNeed struct {
Node string
Digest string
Judgement Judgement
Words string
}
// Holding is a rule holding a node back, and why. The bus module is held back by the rules alone, as every module (ADR 0601 §1,
// §2): no bar of its own.
type Holding struct {
Rule int
Words string
}
// Reason is the holding in words: the rule and its words.
func (h Holding) Reason() string {
return fmt.Sprintf("rule %d: %s", h.Rule, h.Words)
}
// Wants is the pass of one module m: for each of its nodes, the want by the six rules, starting from the want written
// before (wants, by node); lastHealthy is, by node, the newest fingerprint other than m.FP the node ran healthy. A failed
// health check of m.FP on a node holds it: every node wanting m.FP is set back to its last healthy fingerprint, but a
// module holding data is not set back but asked about (Restore). A
// node that wants m but is no longer among its nodes gets its want written removed, never deleted (ADR 0408 §4).
func Wants(m Module, n Nodes, wants map[string]mwc.Want, lastHealthy map[string]string) Outcome {
out := Outcome{Wants: map[string]mwc.Want{}, Rules: map[string]Holding{}, Neither: map[string]Holding{}}
held := m.Held
if held && !m.Kept && m.FP != "" && allRunHealthy(m, n) {
out.Lifted, held = true, false
}
if !held && !out.Lifted && !m.Released && m.FP != "" {
for _, node := range slices.Sorted(slices.Values(m.Nodes)) {
h, ok := n.Haves[node][m.Name]
if !ok || h.Fp != m.FP || !failed(h) {
continue
}
if others := healthyElsewhere(m, n, node); len(others) > 0 && !failedElsewhere(m, n, node) {
// F runs healthy on another node, so its failure here is this node's, not F's: F is not held, no node is set back,
// and the failing node keeps its want (ADR 0557 §1; issue 1496: on ace a newly assigned mesh-build-node failed its
// first check and the hold moved shanks, g14 and novox, healthy on F for an hour, back). The pass raises the node's
// condition. With no online healthy witness, or with F failed on a second node, the hold and the set-back stand (ADR 0557
// §2, ADR 0429 §6).
if out.NodeFailed == nil {
out.NodeFailed = map[string]NodeFailure{}
}
out.NodeFailed[node] = NodeFailure{Others: others, Words: HeldWords(h, time.Time{})} // said once: no clock in it
continue
}
out.Held = &mwc.Held{Node: node, Words: HeldWords(h, m.Now)}
held = true
break
}
}
mm := m
mm.Held = held
// Wants is the pass of one module m: for each of its nodes, the want naming its Target, starting from the want written before
// (wants, by node). A put that owns a node's want writes the put's; a node with no target keeps the want written. A node that
// wants m but is no longer among its nodes gets its want written removed, never deleted (ADR 0408 §4).
func Wants(m Module, wants map[string]mwc.Want) Outcome {
out := Outcome{Wants: map[string]mwc.Want{}}
for _, node := range m.Nodes {
if m.FP == "" {
break
}
before, had := wants[node]
var next mwc.Want
p, put := m.Puts[node]
if !put && had && before.Put && before.Hold {
// The want is the truth (ADR 0546 clause 5): a want marked put and held stands while its put is not heard (the
// puts not open, or not yet handed after a start); only a put heard released gives it back to the rules. A put
// without hold is not kept this way: its put takes it further once heard.
p, put = puts.Put{FP: before.Fp, Composed: before.Composed, Hold: true, Why: strings.TrimPrefix(before.Words, "put: "),
Step: puts.Holding}, true
// The want is the truth (ADR 0546 clause 5): a want marked put and held stands while its put is not heard; only a put
// heard released gives it back to the rule.
p, put = puts.Put{FP: before.Fp, Hold: true, Why: strings.TrimPrefix(before.Words, "put: "), Step: puts.Holding}, true
}
if put {
if want, owns := PutOwns(p); owns {
if want != nil {
w := *want
// A held bus still takes a revision of its composition that changes only its user list (ADR 0539 §7).
if ul, ok := m.userListRevision(node, before, had, n); ok && ul.Fp == w.Fp {
w.Composed = ul.Composed
}
if !had || !mwc.SameWant(normal(before), normal(w)) {
out.Wants[node] = w
}
if want != nil && (!had || !mwc.SameWant(normal(before), normal(*want))) {
out.Wants[node] = *want
}
continue
}
}
// A revision of the bus module's composition that differs only in its user list is written at once, at the fingerprint the
// node runs, outside the rules, the record hold and the bar on a new fingerprint: a new module's credential must reach the
// bus before the module can connect (ADR 0539 §7). The controller marks it; whatever it judges of the file's mount stands.
if w, ok := m.userListRevision(node, before, had, n); ok {
if !had || !mwc.SameWant(normal(before), normal(w)) {
out.Wants[node] = w
}
t, ok := Target{}, false
if m.Target != nil {
t, ok = m.Target(node)
}
if !ok || t.Fp == "" {
continue
}
ok, rule, words := Holds(mm, node, n)
target := m.FP
if have, ran := n.Haves[node][m.Name]; !ok && (!had || before.Removed) && rule == mwc.RuleCanary {
// The canary orders a move, never the first want of a node that does not run the module (issue 1960: de-spiegel,
// link2pay and photos on novox were left with no want). A node that runs an older fingerprint of the new form,
// composed and granted, gets its first want at what it runs, and rule 3 then orders its move to F as from any want.
// A node that runs an old-form build, which no want can name, stays under the canary (issue 1945, a design limit):
// its first want names F once the canary runs F healthy. Any other node that runs it (F itself, or an older
// fingerprint with no composition or grant) gets F by the rules without which there is nothing to want.
older := ran && runs(have) && have.Fp != m.FP && strings.HasPrefix(have.Fp, meshcatalogclient.SourcePrefix2)
if older {
_, composed := m.composition(node, have.Fp)
older = composed && m.GrantedAt != nil && m.GrantedAt(have.Fp)
}
oldForm := ran && runs(have) && have.Fp != m.FP && !strings.HasPrefix(have.Fp, meshcatalogclient.SourcePrefix2)
switch {
case older:
ok, target = true, have.Fp
case oldForm:
// held back by rule 3 as written: on neither list until the canary runs F healthy
default:
ok, rule, words = holds(mm, node, n, false)
}
next := mwc.Want{Fp: t.Fp, Version: t.Version, Pipeline: t.Pipeline, Rank: t.Rank, Self: m.selfOn(node)}
if had && !before.Removed && !before.Put && before.Fp == t.Fp {
// The answers the want carries stay while its build does: a failed backup's (ADR 0539 §16), a held revert's, the yes.
next.Backup, next.Words, next.Revert, next.Yes, next.Release = before.Backup, before.Words, before.Revert, before.Yes, before.Release
}
if why := unreached(m, node, n); why != "" {
if out.Unreached == nil {
out.Unreached = map[string]string{}
}
out.Unreached[node] = why
}
if ok && target == m.FP && len(out.NodeFailed) > 0 && !(had && !before.Removed && before.Fp == m.FP) &&
n.Haves[node][m.Name].Fp != m.FP {
// While a node fails F alone, F reaches no further node: a node that neither wants nor runs F gets no new want
// naming it, and wants already written stay (ADR 0557 §2). A node that runs F with no live want gets its want at F, or
// it would be on neither list and its node-engine would give the module up (issue 1945).
ok, rule, words = false, mwc.RuleNotHeld, FailedAloneWords(m.Name, m.FP, slices.Sorted(maps.Keys(out.NodeFailed)))
}
switch {
case ok:
d, _ := m.composition(node, target)
next = n.withKept(m, node, mwc.Want{Fp: target, Composed: d.Digest})
at := m
if target != m.FP {
// the first want at the older fingerprint the node runs: held back from F by the rule, and judged as a want at it
next.Newest, next.Rule, next.Words = m.FP, int64(rule), words
at.FP = target
}
// A placed node's want names the build alone: it is the same target while the build is.
if had && !before.Removed && !before.Put && before.Fp == target && (before.Composed == d.Digest || (before.Self && m.selfOn(node))) {
next.Backup, next.Words = before.Backup, before.Words // the answer to a failed backup stays while its target stays (ADR 0539 §16)
}
running, ran := n.Haves[node][m.Name]
// A removed want is no want: a first want after it goes through the record ask as a first want does.
asked, hadLive := before, had
if before.Removed {
asked, hadLive = mwc.Want{}, false
}
if need, wait := at.mustAsk(node, asked, hadLive, ran, running.Fp, running.Composed == "", d); wait {
if need != nil {
out.Record = append(out.Record, *need)
}
continue
}
case held && had && before.Fp == m.FP:
out.Rules[node] = Holding{Rule: rule, Words: words}
last := lastHealthy[node]
switch {
case keepsData(m.Manifest) && (m.Restored == nil || !m.Restored(node)):
next = before
next.Words = fmt.Sprintf("%s holds data, so it is not set back from %s: the operator is asked whether to restore it", m.Name, short(m.FP))
out.Restore = append(out.Restore, node)
case last == "":
next = before
next.Words = fmt.Sprintf("%s is held at %s and %s ran no other fingerprint healthy to set it back to", m.Name, short(m.FP), node)
default:
d, there := m.composition(node, last)
if !there {
next = before
next.Words = fmt.Sprintf("%s is held at %s, and the composition of %s at %s is gone, so %s is not set back", m.Name, short(m.FP), m.Name, short(last), node)
break
}
next = mwc.Want{Fp: last, Composed: d.Digest, Newest: m.FP, Rule: int64(rule), Words: words}
}
default:
out.Rules[node] = Holding{Rule: rule, Words: words}
if !had || before.Removed {
// The node runs the module, or its have names it, and gets no want for it: the module is on neither list (issue 1945), and
// the pass says so. A new assignment, with no have, waits for the rules and is on no list yet by design. A held module (rule 2,
// held before or by this pass) is on the held list instead, whose hold is said and answered on its own: it is never on neither
// list (issue 1945: systemd-resolved, held on shanks by the operator, was said as urgent every hour).
h, there := n.Haves[node][m.Name]
switch {
case there && h.Phase != nodeengineclient.PhaseRemoved && !held:
out.Neither[node] = Holding{Rule: rule, Words: words}
case had && (!there || h.Phase == nodeengineclient.PhaseRemoved):
// A removed want of a node that does not run the module says why no want follows it (issue 1945), so the view's
// assigner_want answers it; it stays removed. A node with no key gets none: a removed want written where none was
// would have its node agent remove the module and stop holding its composition's resources back.
next = mwc.Want{Removed: true, Words: NoWantWords(rule, words)}
if !mwc.SameWant(normal(before), normal(next)) {
out.Wants[node] = next
}
}
continue
}
next = mwc.Want{Fp: before.Fp, Composed: before.Composed, Newest: m.FP, Rule: int64(rule), Words: words}
if before.Fp == m.FP {
// Held at F by the rules: a new revision of F's composition waits for them, as a new fingerprint does (ADR 0539 §5).
next = mwc.Want{Fp: m.FP, Composed: before.Composed}
} else if d, there := m.composition(node, before.Fp); there && d.Digest != "" && d.Digest != before.Composed {
// Held back at an earlier fingerprint whose kept composition the controller composed again with today's config
// (novox/hq ADR 0545): the want follows its new revision, so the node does not run that build with the config of
// the moment it was made (on g14 a capacity of 0 after a rollback). Asked as any move of a record module is.
at := m
at.FP = before.Fp
running, ran := n.Haves[node][m.Name]
need, wait := at.mustAsk(node, before, true, ran, running.Fp, running.Composed == "", d)
if need != nil {
out.Record = append(out.Record, *need)
}
if !wait {
next.Composed = d.Digest
}
}
}
next, write := m.selfDerived(node, before, had, next, n, &out)
if !write {
continue
if m.ReadsVersion != nil && !m.ReadsVersion(node) {
// A node-engine that cannot read a want by version is placed by hand when its machine is back (design 47 H §772).
next.Hold, next.Words, next.Backup, next.Revert = true, mwc.HoldAwaitsHandPlacement, "", ""
}
if !had || !mwc.SameWant(normal(before), normal(next)) {
out.Wants[node] = next
@@ -682,143 +143,17 @@ func Wants(m Module, n Nodes, wants map[string]mwc.Want, lastHealthy map[string]
return out
}
// selfDerived is next with its Self derived from the assignments now (Module.Self), whichever rule made it, and whether it is
// written. A placed node's want names the build alone (ADR 0547 §2). An unplaced node's want that a rule kept from the want
// written while the node was placed (held at F, held back by rule 3 or 5, a data module asked about) names the controller's
// composition of the same fingerprint, asked as any move of a record module is (ADR 0539 §14): on 2026-10-27, after the
// assignments seed's revert, g14's systemd-resolved (held) and forticlient (rule 5), and shanks's forticlient (rule 3), kept
// their Self wants, which their node agents, no longer placed, could not compose (issue 1126). With no such composition, or
// while its ask waits, the want written stays and the node's holding says why.
func (m Module) selfDerived(node string, before mwc.Want, had bool, next mwc.Want, n Nodes, out *Outcome) (mwc.Want, bool) {
switch {
case next.Removed:
return next, true
case m.selfOn(node):
next.Self, next.Composed = true, ""
return next, true
case !next.Self && next.Composed != "":
return next, true
}
next.Self, next.Yes = false, ""
d, there := m.composition(node, next.Fp)
if !there || d.Digest == "" {
out.Rules[node] = Holding{Rule: mwc.RuleComposed, Words: fmt.Sprintf("%s on %s was composed by the node while it was placed, "+
"and no composition of its own is named at %s now, so its want stays", m.Name, node, short(next.Fp))}
return next, false
}
at := m
at.FP = next.Fp
running, ran := n.Haves[node][m.Name]
if need, wait := at.mustAsk(node, before, had, ran, running.Fp, running.Composed == "", d); wait {
if need != nil && !slices.Contains(out.Record, *need) { // the branch held back at an older fingerprint may have asked it
out.Record = append(out.Record, *need)
}
return next, false
}
next.Composed = d.Digest
return next, true
}
// NoWantWords say why a node gets no want for a module: the rule that holds its first want back and why (issue 1945).
func NoWantWords(rule int, words string) string {
return fmt.Sprintf("no want: rule %d: %s", rule, words)
}
// failed says whether a have's health check failed once the node is done moving: phase running or failed (never removed, held, or
// moving). A failed health while it
// backs up, applies or checks is a step of the move, not its outcome (on novox at 15:27:36 on 2026-10-25, "health failed, phase
// applying" held the controller's canary two seconds before the new build was healthy). Every healthy read (healthy, providedHealthy,
// the world's lastHealthy) already asks for phase running.
// moving).
func failed(h nodeengine.HaveByNodeModuleValue) bool {
return h.Health == nodeengineclient.HealthFailed && (h.Phase == nodeengineclient.PhaseRunning || h.Phase == nodeengineclient.PhaseFailed)
}
// healthyElsewhere is every online node of m but node that runs m.FP healthy, by name.
func healthyElsewhere(m Module, n Nodes, node string) []string {
var out []string
for _, other := range slices.Sorted(slices.Values(m.Nodes)) {
// A witness is online: a node that sleeps keeps the have it last wrote, and a stale have is no evidence that F runs
// healthy now.
if other != node && n.Online[other] && n.RunsHealthy(other, m.Name, m.FP) {
out = append(out, other)
}
}
return out
}
// failedElsewhere says whether another node of m has a have naming m.FP failed: then the failure is not one node's alone, and
// the hold and the set-back stand at the second failure (ADR 0557 §2).
func failedElsewhere(m Module, n Nodes, node string) bool {
for _, other := range m.Nodes {
if h, ok := n.Haves[other][m.Name]; ok && other != node && h.Fp == m.FP && failed(h) {
return true
}
}
return false
}
// FailedAloneWords say why a node gets no new want naming fp: fp fails its health check on the nodes named, alone.
func FailedAloneWords(module, fp string, failing []string) string {
return fmt.Sprintf("%s at %s fails its health check on %s, so no further node moves to it until that is over", module, short(fp),
strings.Join(failing, ", "))
}
// NodeFailure is a failed health check of a module's newest fingerprint on one node while it runs healthy on Others: the have's
// health, phase and words (HeldWords without a time), and the healthy witnesses by name.
type NodeFailure struct {
Others []string
Words string
}
// runs says whether a have is of a module the node runs: running, whatever its health.
func runs(h nodeengine.HaveByNodeModuleValue) bool {
return h.Phase == nodeengineclient.PhaseRunning
}
// allRunHealthy says whether every node of m that runs the module (its have's phase is running, or failed) runs m.FP healthy, and
// at least one does: a hold whose fingerprint runs healthy wherever the module runs holds nothing back any more (issue 1906: seven
// modules stayed held on every machine after one transient failed check). A node set back to another fingerprint does not run
// m.FP, and a failed one does not run it healthy, so the hold stays; a have that is removed, held for its backup or still moving
// (backing up, applying, checking) is not counted, or it would keep the hold up for ever.
func allRunHealthy(m Module, n Nodes) bool {
ran := 0
for _, node := range m.Nodes {
h, ok := n.Haves[node][m.Name]
if !ok || (h.Phase != nodeengineclient.PhaseRunning && h.Phase != nodeengineclient.PhaseFailed) {
continue
}
if !n.RunsHealthy(node, m.Name, m.FP) {
return false
}
ran++
}
return ran > 0
}
// HeldWords are the words a hold keeps of its cause (issue 1906): the health and phase the node reported, when the assigner saw
// it, and the node's own words. The node is the held record's own field.
func HeldWords(h nodeengine.HaveByNodeModuleValue, at time.Time) string {
words := fmt.Sprintf("health %s, phase %s", h.Health, h.Phase)
if !at.IsZero() {
words += ", seen at " + at.UTC().Format(time.RFC3339)
}
if d := strings.TrimSpace(h.Detail); d != "" {
return words + ": " + d
}
return words + ": the node gave no words"
}
// LiftedWords say why a hold was lifted by itself.
func LiftedWords(module, fp string) string {
return fmt.Sprintf("every node that runs %s runs %s healthy, so the assigner lifted its hold by itself", module, short(fp))
}
// normal is a want without its version, as a decoded and a composed one are compared.
func normal(w mwc.Want) mwc.Want {
w.V = 0
return w
}
func short(fp string) string {
part, err := catalogkey.KeyPart(fp)
if err != nil || len(part) < 12 {
@@ -827,69 +162,20 @@ func short(fp string) string {
return part[:12]
}
// mustAsk says whether the move to the composition d on node waits for the operator's yes (need names the ask, ADR 0539 §14). A
// module the node never ran (it has no want and no have), a move judged neither, a module that is not of policy record and a want
// that stays are written as any want. The bus module is no exception: it moves by the rules (ADR 0601 §1), its node backing up its
// streams before it applies (§2); the assigner asks no snapshot for it.
func (m Module) mustAsk(node string, before mwc.Want, had, ran bool, running string, haveNamesNoComposition bool, d ComposedDigest) (*RecordNeed, bool) {
if (!had && !ran) || before.Removed || (before.Fp == m.FP && before.Composed == d.Digest) {
return nil, false
}
// Right after the switch no node has a readable want, and a have from the old node-engine names a fingerprint and no composition
// (ADR 0539 §9, §11): a node running this fingerprint is given its want at it with no hold when the controller judges the composition
// unchanged, equal to the declaration the node last applied (ADR 0540 §9), since the node agent then applies nothing. A composition that
// differs from it (a changed setting or secret), or that the controller could not judge, waits for the ask. A new fingerprint still waits.
if !had && ran && running == m.FP && haveNamesNoComposition && d.Judgement == JudgedUnchanged {
return nil, false
}
if !m.recorded(d) || d.Judgement == JudgedNeither || d.Judgement == JudgedUnchanged {
return nil, false
}
if m.Allowed != nil && m.Allowed(node, d.Digest) {
return nil, false
}
return &RecordNeed{Node: node, Digest: d.Digest, Judgement: d.Judgement, Words: d.Words}, true
// RecordNeed is a move of a module of policy record on a node that waits for the operator's yes: the digest the node-engine's have
// waits on, its judgement of the move and its words (ADR 0539 §14).
type RecordNeed struct {
Node string
Digest string
Judgement Judgement
Words string
}
// recorded says whether the module is of policy record: a person's choice at the assigner over the manifest's word (ADR
// 0565 §7, catalogue.Upgrade); for a module with none, as the controller holds it beside the composition's digest until the
// lease write (ADR 0539 §14); on a composition made by hand, which carries none, as the manifest derives it.
func (m Module) recorded(d ComposedDigest) bool {
if m.Chosen != nil {
policy, _, _, _ := catalogue.Upgrade(m.Manifest, m.Chosen)
return policy == catalogue.PolicyRecord
}
if d.Policy != "" {
return d.Policy == catalogue.PolicyRecord
}
policy, _, _ := catalogue.DerivedUpgrade(m.Manifest)
return policy == catalogue.PolicyRecord
}
// userListRevision is the want that names the bus module's composition at the fingerprint the node runs when that composition
// differs from the one the node runs only in the bus's user list (ComposedDigest.UserListOnly), and whether there is one. A node
// whose want names another fingerprint than the one it runs, or a module that does not provide the bus, has none.
func (m Module) userListRevision(node string, before mwc.Want, had bool, n Nodes) (mwc.Want, bool) {
if !catalogue.ProvidesBus(m.Manifest) {
return mwc.Want{}, false
}
running, ran := n.Haves[node][m.Name]
if !ran || running.Fp == "" || (had && (before.Removed || before.Fp != running.Fp)) {
return mwc.Want{}, false
}
d, ok := m.composition(node, running.Fp)
if !ok || !d.UserListOnly {
return mwc.Want{}, false
}
w := mwc.Want{Fp: running.Fp, Composed: d.Digest}
if had && before.Composed == d.Digest {
w.Backup, w.Words = before.Backup, before.Words
}
return w, true
}
// GrantNamesNode says whether a grant of module names its accounts on node (mesh-sdk's Grant.NamesNode, which a
// put reads by too).
func GrantNamesNode(g grantsstate.Grant, node, module string) bool {
return g.NamesNode(node, module)
// KeptBuild is what the assigner knows of a build: the digest of each of its parts by `<module>:<artifact>` and the build node that
// keeps it, as the builder's `build.ended` says them, and its released version as the catalog's `version-released` says it (design
// 47 G §379, A-96). A want names the version alone (design 47 H §750).
type KeptBuild struct {
Parts map[string]string
KeptOn string
Version string
}
File diff suppressed because it is too large Load Diff
@@ -53,9 +53,6 @@ type Computed struct {
// Uncomputed is each placed module whose entry could not be computed, as "<node>/<module>: why", sorted: it is said,
// never left out in silence.
Uncomputed []string
// Cycles are the cycles among the acting waits, within one step or across steps (Cycles, design 47 G §272, A-323): said, never
// left in silence.
Cycles []string
}
// placedAt is one placed module with what its entry is computed from.
@@ -74,7 +71,7 @@ type placedAt struct {
optional func(string) bool
}
type actingRule struct{ seat, step, on, bound string }
type actingRule struct{ seat, step, on string }
// Compute is the assignment graph revision of in: one entry per module placed on a node whose branch's catalog graph
// holds it, its version the build the placement names or else the catalog entry's fingerprint (design 47 lines 909-914),
@@ -128,7 +125,7 @@ func Compute(in Inputs) Computed {
p.langs[lang] = true
}
for _, r := range ce.Acts {
p.acts = append(p.acts, actingRule{seat: r.Seat, step: r.Step, on: r.On, bound: r.Bound})
p.acts = append(p.acts, actingRule{seat: r.Seat, step: r.Step, on: r.On})
}
p.provides, p.contributes = ce.Provides, ce.Contributes
p.delivering = map[string]seatdef.Definition{}
@@ -199,7 +196,7 @@ func Compute(in Inputs) Computed {
}
for _, h := range from {
t.entry.Edges = append(t.entry.Edges, meshwants.Edge{Kind: EdgeActing, Node: h.node, Module: part, Fp: h.entry.Fp,
Seat: rule.seat, Step: rule.step, Bound: rule.bound})
Seat: rule.seat, Step: rule.step})
}
}
}
@@ -217,7 +214,6 @@ func Compute(in Inputs) Computed {
rev.Entries = append(rev.Entries, meshwants.NodeEntryRef{Node: p.node, Module: p.placed.Module, Digest: d})
}
out.Revision = rev
out.Cycles = Cycles(slices.Collect(maps.Values(out.Entries)))
slices.Sort(out.Uncomputed)
return out
}
@@ -229,7 +225,7 @@ func sortEdges(edges []meshwants.Edge) {
}
func edgeKey(e meshwants.Edge) string {
return strings.Join([]string{e.Kind, e.Node, e.Module, e.Provision, e.Seat, e.Step, e.Fp, e.Bound}, "\x00")
return strings.Join([]string{e.Kind, e.Node, e.Module, e.Provision, e.Seat, e.Step, e.Fp}, "\x00")
}
// EntryDigest is the digest an entry is stored under: the same entry, the same digest.
@@ -1,248 +0,0 @@
package assigngraph
import (
"fmt"
"maps"
"slices"
"strings"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
)
// Cycles are the cycles among the acting waits (design 47 G §272, ADR 0656, A-323): an entry waits for its acting parts in the step
// an edge names, so acting parts that wait for each other, in one step or across steps, wait for ever unless a rule breaks the
// cycle. A cycle within one step is `<step>: a -> b -> a`; one across steps names each edge's step, `a -[compose]-> b -[place]-> a`;
// each by node and module, said once from its smallest member, sorted. A holder's own inputs are no edge here (the graph gives an
// acting edge only from a part to the entries it acts on, never to what the part is built from).
func Cycles(entries []meshwants.AssignmentEntry) []string {
type key struct{ step, at string }
next := map[key][]string{}
steps := map[string]bool{}
for _, e := range entries {
for _, edge := range e.Edges {
if edge.Kind != EdgeActing {
continue
}
k := key{edge.Step, e.Node + "/" + e.Module}
next[k] = append(next[k], edge.Node+"/"+edge.Module)
steps[edge.Step] = true
}
}
var out []string
for _, step := range slices.Sorted(maps.Keys(steps)) {
const (
open = iota + 1
done
)
state := map[string]int{}
var path []string
var walk func(at string)
walk = func(at string) {
state[at] = open
path = append(path, at)
for _, to := range next[key{step, at}] {
switch state[to] {
case 0:
walk(to)
case open:
from := slices.Index(path, to)
cycle := slices.Clone(path[from:])
// start at the smallest member so one cycle is said once, whichever member is met first
lowest := slices.Index(cycle, slices.Min(cycle))
cycle = append(cycle[lowest:], cycle[:lowest]...)
out = append(out, fmt.Sprintf("%s: %s -> %s", step, strings.Join(cycle, " -> "), cycle[0]))
}
}
path = path[:len(path)-1]
state[at] = done
}
starts := map[string]bool{}
for k := range next {
if k.step == step {
starts[k.at] = true
}
}
for _, at := range slices.Sorted(maps.Keys(starts)) {
if state[at] == 0 {
walk(at)
}
}
}
// Across steps (A-323): the shortest cycle through each entry over every acting edge, said when its edges name two steps or more.
for _, hops := range cyclesThrough(entries, func(_ meshwants.AssignmentEntry, e meshwants.Edge) bool { return e.Kind == EdgeActing }) {
if crossesSteps(hops) {
out = append(out, hopWords(rotated(hops)))
}
}
slices.Sort(out)
return slices.Compact(out)
}
// HeldCycles is, by `<node>/<module>`, the cycle each entry lies on among the edges holds says hold it (A-323, A-330): a want held
// on such a cycle is held for ever, since no rule breaks it. Each cycle starts at the entry and names each edge's step.
func HeldCycles(entries []meshwants.AssignmentEntry, holds func(e meshwants.AssignmentEntry, edge meshwants.Edge) bool) map[string]string {
out := map[string]string{}
for at, hops := range cyclesThrough(entries, holds) {
out[at] = hopWords(hops)
}
return out
}
// Engines is, by node, the module that holds the seat node-engine there, read from the acting edges' seat (A-330).
func Engines(entries []meshwants.AssignmentEntry) map[string]string {
out := map[string]string{}
for _, e := range entries {
for _, edge := range e.Edges {
if edge.Kind == EdgeActing && edge.Seat == nodeengine.Seat {
out[edge.Node] = edge.Module
}
}
}
return out
}
// Runner is the module that holds the seat mesh-pipeline-runner, read from the acting edges' seat as Engines reads the node-engine
// (A-334); "" when none is read.
func Runner(entries []meshwants.AssignmentEntry) string {
for _, e := range entries {
for _, edge := range e.Edges {
if edge.Kind == EdgeActing && edge.Seat == meshpipelinerunner.Seat {
return edge.Module
}
}
}
return ""
}
// hop is one edge of a cycle: from the entry at, in step, to the next hop's entry.
type hop struct{ at, step string }
// cyclesThrough is, by `<node>/<module>`, the shortest cycle through each entry over the edges keep takes, found within the
// entry's strongly connected part, each starting at the entry.
func cyclesThrough(entries []meshwants.AssignmentEntry, keep func(meshwants.AssignmentEntry, meshwants.Edge) bool) map[string][]hop {
type out struct{ to, step string }
next := map[string][]out{}
for _, e := range entries {
at := e.Node + "/" + e.Module
for _, edge := range e.Edges {
if keep(e, edge) {
next[at] = append(next[at], out{edge.Node + "/" + edge.Module, edge.Step})
}
}
}
for at := range next {
slices.SortFunc(next[at], func(a, b out) int { return strings.Compare(a.to+"\x00"+a.step, b.to+"\x00"+b.step) })
}
part := strongParts(slices.Sorted(maps.Keys(next)), func(at string) []string {
var to []string
for _, o := range next[at] {
to = append(to, o.to)
}
return to
})
found := map[string][]hop{}
for _, start := range slices.Sorted(maps.Keys(next)) {
// breadth first from start back to it, within its part
prev := map[string]hop{}
queue := []string{start}
seen := map[string]bool{}
for len(queue) > 0 && found[start] == nil {
at := queue[0]
queue = queue[1:]
for _, o := range next[at] {
if part[o.to] != part[start] {
continue
}
if o.to == start {
hops := []hop{{at, o.step}}
for cur := at; cur != start; {
h := prev[cur]
hops = append(hops, h)
cur = h.at
}
slices.Reverse(hops)
found[start] = hops
break
}
if !seen[o.to] {
seen[o.to] = true
prev[o.to] = hop{at, o.step}
queue = append(queue, o.to)
}
}
}
}
return found
}
// strongParts numbers each vertex by its strongly connected part (Tarjan).
func strongParts(vertices []string, succ func(string) []string) map[string]int {
index, low, part := map[string]int{}, map[string]int{}, map[string]int{}
on := map[string]bool{}
var stack []string
n, parts := 0, 0
var visit func(v string)
visit = func(v string) {
index[v], low[v] = n, n
n++
stack = append(stack, v)
on[v] = true
for _, w := range succ(v) {
if _, ok := index[w]; !ok {
visit(w)
low[v] = min(low[v], low[w])
} else if on[w] {
low[v] = min(low[v], index[w])
}
}
if low[v] == index[v] {
parts++
for {
w := stack[len(stack)-1]
stack = stack[:len(stack)-1]
on[w] = false
part[w] = parts
if w == v {
break
}
}
}
}
for _, v := range vertices {
if _, ok := index[v]; !ok {
visit(v)
}
}
return part
}
func crossesSteps(hops []hop) bool {
for _, h := range hops[1:] {
if h.step != hops[0].step {
return true
}
}
return false
}
// rotated is the cycle started at its smallest member, so one cycle is said once.
func rotated(hops []hop) []hop {
lowest := 0
for i, h := range hops {
if h.at < hops[lowest].at {
lowest = i
}
}
return append(slices.Clone(hops[lowest:]), hops[:lowest]...)
}
// hopWords is a cycle with each edge's step: `a -[compose]-> b -[place]-> a`.
func hopWords(hops []hop) string {
var b strings.Builder
for _, h := range hops {
fmt.Fprintf(&b, "%s -[%s]-> ", h.at, h.step)
}
return b.String() + hops[0].at
}
@@ -1,60 +0,0 @@
package assigngraph
import (
"slices"
"testing"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
)
// Design 47 G §272 (AS10), A-323: a cycle among the waits is found within one step and across steps, each edge's step named across
// steps; a chain and provisioning edges are none.
func TestACycleAmongTheWaitsWithinOrAcrossStepsIsFound(t *testing.T) {
act := func(node, module, step string) meshwants.Edge {
return meshwants.Edge{Kind: EdgeActing, Node: node, Module: module, Step: step}
}
entry := func(module string, edges ...meshwants.Edge) meshwants.AssignmentEntry {
return meshwants.AssignmentEntry{Node: "ace", Module: module, Edges: edges}
}
for _, c := range []struct {
name string
entries []meshwants.AssignmentEntry
want []string
}{
{"two parts on each other in one step", []meshwants.AssignmentEntry{entry("a", act("ace", "b", "compose")), entry("b", act("ace", "a", "compose"))},
[]string{"compose: ace/a -> ace/b -> ace/a"}},
{"three in a ring, said once", []meshwants.AssignmentEntry{entry("c", act("ace", "a", "build")), entry("a", act("ace", "b", "build")), entry("b", act("ace", "c", "build"))},
[]string{"build: ace/a -> ace/b -> ace/c -> ace/a"}},
{"the indexer taking in the checker, the checker checking the indexer", []meshwants.AssignmentEntry{entry("checker", act("ace", "indexer", "take-in")), entry("indexer", act("ace", "checker", "check"))},
[]string{"ace/checker -[take-in]-> ace/indexer -[check]-> ace/checker"}},
{"the assigner and the node-engine, across compose and place", []meshwants.AssignmentEntry{entry("assigner", act("ace", "engine", "compose")),
entry("engine", act("ace", "assigner", "place")), entry("app", act("ace", "engine", "compose"), act("ace", "assigner", "place"))},
[]string{"ace/assigner -[compose]-> ace/engine -[place]-> ace/assigner"}},
{"a chain", []meshwants.AssignmentEntry{entry("a", act("ace", "b", "compose")), entry("b", act("ace", "c", "compose")), entry("c")}, nil},
{"provisioning edges are no wait of a step", []meshwants.AssignmentEntry{entry("a", meshwants.Edge{Kind: EdgeProvisioning, Node: "ace", Module: "b"}), entry("b", meshwants.Edge{Kind: EdgeProvisioning, Node: "ace", Module: "a"})}, nil},
} {
if got := Cycles(c.entries); !slices.Equal(got, c.want) {
t.Errorf("%s: cycles %v, want %v", c.name, got, c.want)
}
}
}
// A-323, A-330: the node-engine on a node is read from the acting edges' seat, and the cycles that hold a want are those of the
// edges said to hold it, each from the entry, naming each edge's step.
func TestTheHeldCyclesAreThoseOfTheHoldingEdges(t *testing.T) {
entries := []meshwants.AssignmentEntry{
{Node: "ace", Module: "assigner", Edges: []meshwants.Edge{{Kind: EdgeActing, Node: "ace", Module: "engine", Step: "compose", Seat: "node-engine"}}},
{Node: "ace", Module: "engine", Edges: []meshwants.Edge{{Kind: EdgeActing, Node: "ace", Module: "assigner", Step: "place", Seat: "mesh-wants"}}},
}
if got := Engines(entries); len(got) != 1 || got["ace"] != "engine" {
t.Errorf("the node-engines %v, want engine on ace", got)
}
all := func(meshwants.AssignmentEntry, meshwants.Edge) bool { return true }
if got := HeldCycles(entries, all); len(got) != 2 || got["ace/engine"] != "ace/engine -[place]-> ace/assigner -[compose]-> ace/engine" {
t.Errorf("held cycles %v", got)
}
// the node-engine's want held by no acting edge: no cycle holds anything
if got := HeldCycles(entries, func(e meshwants.AssignmentEntry, _ meshwants.Edge) bool { return e.Module != "engine" }); len(got) != 0 {
t.Errorf("held cycles with the node-engine's edges holding nothing: %v", got)
}
}
@@ -86,7 +86,7 @@ func TestTheAssignmentGraphIsComputedFromItsInputsAndKept(t *testing.T) {
}
want := []meshwants.Edge{
{Kind: EdgeActing, Node: "anchor", Module: "build-go", Fp: "src2:b1", Seat: "node-build-go", Step: "build"},
{Kind: EdgeActing, Node: "anchor", Module: "node-engine", Fp: "src2:e1", Seat: "node-engine", Step: "compose", Bound: "30m"},
{Kind: EdgeActing, Node: "anchor", Module: "node-engine", Fp: "src2:e1", Seat: "node-engine", Step: "compose"}, // the edge stays; the wait's bound goes (H-A-70)
{Kind: EdgeProvisioning, Node: "anchor", Module: "postgres", Fp: "src2:p1", Provision: "database"},
}
if fmt.Sprint(webA.Edges) != fmt.Sprint(want) {
@@ -30,6 +30,29 @@ type Objects interface {
Names(ctx context.Context) ([]string, error)
}
// Described is one object as the bucket's listing says it: its name, and for an entry object the module and fingerprint put beside
// its bytes (empty for one put before them).
type Described struct {
Name, Module, Fp string
}
// Describer is an object bucket whose listing says, in one read, each entry object's module and fingerprint, so the removal of the
// revisions not current reads no object per entry (design 47 H-A-259).
type Describer interface {
// PutDescribed stores data whole under name, with module and fp beside it in the listing.
PutDescribed(ctx context.Context, name string, data []byte, module, fp string) error
// Described is every object, as the listing says it.
Described(ctx context.Context) ([]Described, error)
}
// PutEntry stores the entry object e under name, with its module and fingerprint beside it where the bucket says them.
func PutEntry(ctx context.Context, o Objects, name string, data []byte, e meshwants.AssignmentEntry) error {
if d, ok := o.(Describer); ok {
return d.PutDescribed(ctx, name, data, e.Module, e.Fp)
}
return o.Put(ctx, name, data)
}
// EntryObject is the object name of the entry of that digest (the seat's key form entry.<digest>).
func EntryObject(digest string) string { return "entry." + digest }
@@ -144,7 +167,7 @@ func writeEntries(ctx context.Context, o Objects, c Computed, rev meshwants.Assi
if err != nil {
return err
}
if err := o.Put(ctx, name, data); err != nil {
if err := PutEntry(ctx, o, name, data, e); err != nil {
return fmt.Errorf("the entry of %s/%s in %s: %w", ref.Node, ref.Module, RevisionsObjects, err)
}
held[name] = true
@@ -11,6 +11,7 @@ import (
client "git.novox.be/novox/mesh-contracts/go/clients/meshmoduleassignerclient"
seat "git.novox.be/novox/mesh-contracts/go/seats/meshmoduleassigner"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/keys"
)
@@ -356,5 +357,30 @@ func TestAssignments(t *testing.T) {
if h, _ := client.HoldersOf(keyed, "node-files", "novox"); h != nil {
t.Errorf("a node seat nobody holds there is held by %v", h)
}
// A-400: a seat no holding names is held by the first assigned module whose manifest claims it; a holding on record wins.
assigned := map[string]seat.Assignments{
"ace": {Node: "ace", Modules: []seat.PlacedModule{{Module: "mesh-delivery-assigner"}, {Module: "mesh-files"}}},
"novox": {Node: "novox", Modules: []seat.PlacedModule{{Module: "nats"}, {Module: "mesh-files"}}, Holds: []seat.Holding{{Claim: "mesh-broker", Scope: "mesh", Module: "nats"}}},
}
manifests := map[string]catalogue.Manifest{
"mesh-delivery-assigner": {Claims: []catalogue.Claim{{Name: "mesh-module-assigner", Scope: "mesh"}}},
"nats": {Claims: []catalogue.Claim{{Name: "mesh-broker", Scope: "mesh"}}},
"mesh-files": {Claims: []catalogue.Claim{{Name: "node-files"}}},
}
with, derived := SeatHoldersWithClaimants(assigned, manifests)
keyed = map[string][]byte{}
for k, v := range with {
keyed[k], _ = json.Marshal(v)
}
if h, err := client.HoldersOf(keyed, "mesh-module-assigner", ""); err != nil || len(h) != 1 || h[0].Module != "mesh-delivery-assigner" || h[0].Node != "ace" {
t.Errorf("an unheld seat's claimant is %v, %v", h, err)
}
if h, _ := client.HoldersOf(keyed, "node-files", "novox"); len(h) != 1 || h[0].Module != "mesh-files" {
t.Errorf("a node seat's claimant on novox is %v", h)
}
if h, _ := client.HoldersOf(keyed, "mesh-broker", ""); len(h) != 1 || h[0].Node != "novox" || len(derived) != 3 {
t.Errorf("a held seat is %v; derived %v", h, derived)
}
})
}
@@ -66,7 +66,7 @@ func DecodeCandidate(data []byte) (seat.CandidatesByProposalNodeValue, error) {
if err := keys.CheckVersion(data); err != nil {
return seat.CandidatesByProposalNodeValue{}, err
}
c, err := seat.DecodeCandidatesByProposalNodeValue(data)
c, _, err := seat.DecodeCandidatesByProposalNodeValue(data)
if err != nil {
return seat.CandidatesByProposalNodeValue{}, fmt.Errorf("assignments: a candidate does not fit its shape: %w", err)
}
@@ -252,3 +252,54 @@ func sortedKeys[V any](m map[string]V) []string {
sort.Strings(out)
return out
}
// SeatHoldersWithClaimants is SeatHoldersOf over the assignments with, for each seat no holding names (a seat held once:
// on no node; a seat of every node: on that node), the first module assigned to a node (nodes and modules in order) whose
// manifest claims it, as its holder (lead answer A-400, the same rule as grants' A-398; the operator, 2026-11-14: who holds
// a seat follows from the module graph and the assignments). derived lists each key so held, for its writer to say. Pure.
func SeatHoldersWithClaimants(assignments map[string]seat.Assignments, manifests map[string]catalogue.Manifest) (out map[string]seat.SeatHolders, derived []string) {
held := map[string]bool{} // "<seat>" for a seat held once, "<seat>.<node>" for a seat of every node
keyOf := func(claim, scope, node string) string {
name := claim
if s, ok := catalogue.SeatNamed(claim); ok {
name = s.Name
}
if scope == catalogue.ScopeNode {
return name + "." + node
}
return name
}
for _, n := range sortedKeys(assignments) {
for _, h := range assignments[n].Holds {
held[keyOf(h.Claim, h.Scope, n)] = true
}
}
with := map[string]seat.Assignments{}
var added []string
for _, n := range sortedKeys(assignments) {
a := assignments[n]
a.Holds = append([]seat.Holding(nil), a.Holds...)
modules := make([]string, 0, len(a.Modules))
for _, m := range a.Modules {
modules = append(modules, m.Module)
}
sort.Strings(modules)
for _, module := range modules {
m, ok := manifests[module]
if !ok {
continue
}
for _, c := range m.Claims {
k := keyOf(c.Name, c.At(), n)
if held[k] {
continue
}
held[k] = true
a.Holds = append(a.Holds, seat.Holding{Claim: c.Name, Module: module, Scope: c.At()})
added = append(added, k+" by "+module+" on "+n)
}
}
with[n] = a
}
return SeatHoldersOf(with), added
}
@@ -428,7 +428,7 @@ func DecodeProposal(data []byte) (seat.Proposal, error) {
if err := keys.CheckVersion(data); err != nil {
return seat.Proposal{}, err
}
p, err := seat.DecodeProposalsByProposalValue(data)
p, _, err := seat.DecodeProposalsByProposalValue(data)
if err != nil {
return seat.Proposal{}, fmt.Errorf("assignments: a proposal does not fit its shape: %w", err)
}
@@ -18,17 +18,14 @@ import (
const (
// WaitsState holds the waits on an outside cause, one key `<node>.<module>.<fingerprint hex>` (design 47 G §706).
WaitsState = "waits"
// DeliveredAgainState holds each ask of assigner_delivered_again, one key `<module>`, its value the version, who asked and why, and
// why it does not hold yet (design 47 G §376, A-250).
DeliveredAgainState = "delivered-again"
// DeliveryWaitsState holds each dependent's delivery wait the assigner said, one key `<module>`, its value the wait-held said
// (design 47 G §376, §498, A-246).
DeliveryWaitsState = "delivery-waits"
// PutWaitsState holds each put wait the assigner said, one key `<node>.<module>`, its value the wait's id and the put as said
// (design 47 G A-204, A-211), so a put that ends while the assigner is stopped gets its wait-ended at the next start.
PutWaitsState = "put-waits"
// InputsState holds the inputs of the composition steps, `<time>.<digest>`, which the seat mesh-wants' verb input answers (design 47 G §354).
InputsState = "inputs"
// CompositionRunsState holds the composition runs, one key `<candidate key>.<machine>` per run and its bound keys
// `bound.<run key>` and `untaken.<run key>` (design 47 G §719, §720, A-470).
CompositionRunsState = "composition-runs"
// PoliciesState is the state of the policies a person set for a module's upgrade.
PoliciesState = "policies"
)
@@ -37,16 +34,19 @@ const (
// constant of its name (design 47 G A-296, §428).
func own(state string) string { return plc.Module() + "_" + state }
func Wants() string { return own(wants.StateWants) }
func Differences() string { return own(wants.StateDifferences) }
func Asks() string { return own("asks") }
func Puts() string { return own("puts") }
func Waits() string { return own(WaitsState) }
func DeliveredAgain() string { return own(DeliveredAgainState) }
func DeliveryWaits() string { return own(DeliveryWaitsState) }
func PutWaits() string { return own(PutWaitsState) }
func Inputs() string { return own(InputsState) }
func Policies() string { return own(PoliciesState) }
func Wants() string { return own(wants.StateWants) }
func Differences() string { return own(wants.StateDifferences) }
func Asks() string { return own("asks") }
func Puts() string { return own("puts") }
func Waits() string { return own(WaitsState) }
func PutWaits() string { return own(PutWaitsState) }
func Inputs() string { return own(InputsState) }
func CompositionRuns() string { return own(CompositionRunsState) }
func Policies() string { return own(PoliciesState) }
// Taken is the bucket of the state taken (design 47 H2 §775, §777): the asks of the seat mesh-wants taken once, and their
// drops; named as mesh-sdk's process.TakenState.
func Taken() string { return own("taken") }
// AsksHistory is the revisions the bucket of asks keeps per key.
const AsksHistory = 5
@@ -67,10 +67,6 @@ const (
Graph = IndexerModule + "_graph"
ModulesRead = IndexerModule + "." + catalog.StateModules
ManifestsRead = IndexerModule + "." + catalog.StateManifests
// ProvisionerModule is the holder of the seat mesh-provisioner, named from this module's manifest (reads its provisions); Provisions
// is its state provisions.
ProvisionerModule = "mesh-provisioner"
Provisions = ProvisionerModule + "_provisions"
// TellerModule is the module whose hand the operator's answers pass: the one that holds each ask's answer, and the
// name the hand-act log records a warrant under. Held equal to the manifest's reads by its test.
TellerModule = "mesh-delivery-teller"
@@ -12,9 +12,9 @@ func TestBucketsAreTheEarlierNames(t *testing.T) {
for name, c := range map[string][2]string{
"Have": {Have, "node-engine_have"}, "ComposedRead": {ComposedRead, "mesh-host.composed"},
"Modules": {Modules, "mesh-delivery-indexer_modules"}, "Manifests": {Manifests, "mesh-delivery-indexer_manifests"},
"Answers": {Answers, "mesh-delivery-teller_answers"},
"Grants": {Grants, "mesh-grants_grants"},
"Provisions": {Provisions, "mesh-provisioner_provisions"}, "TellerModule": {TellerModule, "mesh-delivery-teller"},
"Answers": {Answers, "mesh-delivery-teller_answers"},
"Grants": {Grants, "mesh-grants_grants"},
"TellerModule": {TellerModule, "mesh-delivery-teller"},
} {
if c[0] != c[1] {
t.Errorf("%s = %q, want %q", name, c[0], c[1])
@@ -31,7 +31,8 @@ func TestTheAssignersOwnBucketsTakeTheModuleItRunsAs(t *testing.T) {
"Wants": {Wants(), "some-assigner_wants"}, "Differences": {Differences(), "some-assigner_differences"},
"Asks": {Asks(), "some-assigner_asks"}, "Puts": {Puts(), "some-assigner_puts"}, "Policies": {Policies(), "some-assigner_policies"},
"Waits": {Waits(), "some-assigner_waits"}, "Inputs": {Inputs(), "some-assigner_inputs"},
"Assignments": {plc.AssignmentsBucket(), "some-assigner_assignments"}, "SeatHolders": {plc.SeatHoldersBucket(), "some-assigner_seat-holders"},
"CompositionRuns": {CompositionRuns(), "some-assigner_composition-runs"},
"Assignments": {plc.AssignmentsBucket(), "some-assigner_assignments"}, "SeatHolders": {plc.SeatHoldersBucket(), "some-assigner_seat-holders"},
} {
if c[0] != c[1] {
t.Errorf("%s = %q, want %q", name, c[0], c[1])

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