Compare commits

..
Author SHA1 Message Date
jschoubben 1a54a432cf GT1 review round 2: the record's end clears its record-too-large from the findings state
The entries whose refusal a record's end must clear were kept in process
memory, so after a restart a refusal of an entry never written (an act's
first write, a mover's) was never cleared. A record-too-large finding now
names its record as its subject (its id stays the refused entry), and the
record's end clears every held one whose subject is the record, read from
the gate's own findings state; the in-memory map goes. A finding raised
before this change names its entry as its subject and clears when that
entry is next written within 64 KiB.

Review finding: record-too-large cleared at the record's end only from
process memory (movers.go:228-233, Records.refused).

Builds: design 47 H2 §809, H-A-455 (3), H-A-460
2026-11-22 03:10:24 +01:00
jschoubben 758a8ad653 GT1: each owed act is a ledger entry of its own; every ledger write is measured
An act the gate owes the forge is now the entry act/<branch.source.act.id>
(type act, index acts on its record's key in the manifest), removed when
the forge bridge performed it; the head entry holds the record's fields
alone, and the record's acts are joined from their entries when read.
The record type keeps no act operation: a head written before this change
is read for its fields and the acts embedded in it are ignored (they are
notes and views of the few records in flight at the delivery; losing them
changes nothing the operator relies on). A view act's text is the record's
summary, the head's fields and a count of movers per outcome, so it fits
64 KiB for any record; gate_record still shows the whole record. The
64 KiB refusal measures every write, the head's, a mover's and an act's,
raising record-too-large, which the record's end clears for every entry
of it. The gate's whole test gains the step: 126 movers write 127 entries
plus their acts, none over 64 KiB, the head counting 126 and holding no
act; a take-in said again with a why past 64 KiB raises record-too-large
and the record's end clears it.

Builds: design 47 H2 §809, H-A-385, H-A-391, H-A-453 (3), H-A-455, H-A-457, H-A-459
2026-11-22 02:58:39 +01:00
jschoubben 3dd92f1c4b C4 whole: the forge holds one token for the account after the bundle's own mint
The seat git's whole test configures no token: the bundle mints the tools'
account's token at the fixture forge with the admin's login, writes it
through the vault seat's two-step own-put (sealed to the call's key) and
reads it through get (sealed to the process's key), both answered by the
test, with the mint's lease watched as the runtime delivers it. After the
mint the forge holds exactly one token for the account, mesh-tools-1, the
one the vault keeps at generation 1; the old fixed-name token is gone.

Builds: design 47 H2 §808 (whole: the forge holds one token for the account after), H-A-422, H-A-430 (1), H-A-439, H-A-453 (3)
2026-11-22 02:49:12 +01:00
jschoubben 4150402020 SC1 whole: the self-check's whole test raises and clears over-budget from the gate's times
The review found §810's probe proven only at the unit level (H-A-453 (3)): the whole test now enables the budget
probe, answers gate_times with a core delivery 11 minutes from its merge call, reads over-budget for core naming its
record and longest phase, and a core delivery within its budget at the next run clears it.

Builds: design 47 H2 §810, H-A-453 (3)
2026-11-22 02:37:08 +01:00
jschoubben 2b06ab31d7 M1: the forge module declares tweetnacl, which its test bus imports
test/fakebus.ts imports tweetnacl to seal as the vault does; it came only through mesh-sdk's own dependency, so the
forge module's tests named nothing they import (the review's finding; H-A-453). Pinned as mesh-sdk pins it, an
external package as the rule allows.

Builds: design 47 H2 §808, §822; H-A-407, H-A-453
2026-11-22 02:36:15 +01:00
jschoubben 739fb6bf47 M1: the forge module's caps stand above their live fills
Read on novox at 2026-11-22 01:35 UTC through the bus module's nats_streams
(the review's finding on H-A-437; H-A-453):

  gitea bound          16703 bytes, 28 msgs    cap 8 MiB
  gitea announced         98 bytes, 1 msg      cap 8 MiB
  gitea findings      565816 bytes, 2013 msgs  cap 8 MiB
  gitea first-views      369 bytes, 1 msg      cap 8 MiB
  gitea transfers     396894 bytes, 2015 msgs  cap 8 MiB
  gitea idle          376879 bytes, 1041 msgs  cap 8 MiB
  gitea failed-steps  255007 bytes, 754 msgs   cap 8 MiB
  gitea calls          36362 bytes, 93 msgs    cap 8 MiB
  gitea taken         no bucket on the bus yet  cap 8 MiB
  gitea-findings log       0 bytes, 0 msgs     cap 8 MiB

Each fill is below a quarter of 8 MiB (2 MiB), the largest 565,816 bytes, so
each cap stays at 8 MiB; none is raised.

Builds: design 47 H2 §812; H-A-411 (2), H-A-437, H-A-453
2026-11-22 02:35:31 +01:00
jschoubben 5dc8cb343b GT2 whole: the gate's whole test ends a record and reads its delivery time and class
The review found §810's whole criterion proven only at the unit level (H-A-453 (3)): the whole test now ends its
record through the wants seat's wanted and pipeline-wanted and the node-engine seat's running, over the real bus, and
reads the head's delivery-time and class core from a core mover's catalog entry.

Builds: design 47 H2 §810, H-A-453 (3)
2026-11-22 02:34:05 +01:00
jschoubben 98da0e0b68 M1 check-needs: a package outside every Go artifact's from takes the manifest's own check-needs
The forge module's internal/seatgit whole test needs the Node build seat, and no Go artifact's from holds it, so
nothing named its need and the Go build seat ran it on a node without the Node toolchain. The manifest now says the
need at its top level, read by the Go build module for such packages; gitea declares node-build-node
(review round 1, mesh-catalog, finding on §800; H-A-453 (2)).

Builds: design 47 H2 §800, H-A-453 (2)
2026-11-22 02:27:36 +01:00
jschoubben 30a3e665e0 GT: an owed act ended not-needed is ended, never said as a refusal
A pull request closed unmerged is a fact of the forge, not a fault of the
act, so the gate no longer keeps a refusal for an act the forge bridge
ends not-needed: the record's acts and gate_record show it ended with
that outcome, and delivery_status says no refusal of it. Every other
outcome other than performed is still said as a refusal.

Builds: design 47 H2 §807; H-A-432 (2), H-A-444
2026-11-22 02:06:45 +01:00
jschoubben 4500d98ca6 Merge feat/47-H2-c into feat/47-H2
The side branch's manifest rows, gate, forge, packet-filter and
package-manager changes join the build modules' share; no file was
touched by both.

Builds: design 47 H2 (the merged commits' own Builds: lines)
2026-11-22 01:56:19 +01:00
jschoubben 2785c69d95 GT: an act the forge bridge ends not-needed is ended in its record
The forge bridge ends an act whose pull request closed unmerged with the
outcome not-needed. The gate keeps it in the record's acts as ended, as it
keeps performed and could not be performed, and no longer counts it as
owed. The gate's code takes any outcome forgemsg reads, so the change is
forgemsg's outcome list at mesh-delivery feat/47-H2-a. The row in the
owed-acts test fails where forgemsg refuses not-needed.

Builds: design 47 H2 §807; H-A-432 (2)
2026-11-22 01:54:05 +01:00
jschoubben 280adcce68 C4: the vault keeps the forge token with the scopes it was minted with
The file beside the token that kept its scopes went with C4, and with it
the re-mint of a token carrying a scope beyond the tools' (write:admin).
The value written through own-put now holds the token and its scopes; a
token minted with other scopes, or a value naming none, is minted again
unasked and the one it replaces deleted at the forge. The Go bundles read
the token out of that value. The lost test is back as a row of the scope
test in test/token.test.ts.

Builds: design 47 H2 §808; H-A-439
2026-11-22 01:52:24 +01:00
jschoubben 22b92b827d BM publish version: the build modules' bundle asks name the ask's version, as the SDK now refuses one without
A bundle publishes under the version its ask reserved, and the delivery SDK's
publish refuses an empty one loudly; the tests' bundle asks carry a version, a
bundle asked with none is shown refused, and an archive still publishes by its
digest alone.

Builds: design 47 H2 H-A-373, H-A-373 addendum
2026-11-22 01:50:30 +01:00
jschoubben ed14a10006 GT: each act the gate owes names its delivery record
The gate's owed event carries record, the delivery record's source
revision <branch>.<source> (the record's key), said and kept in the
record's acts alike, so the forge bridge keeps it with the act and
bridge_owed_again finds a record's acts in its own state. Built against
the seat mesh-delivery's Owed.record on mesh-delivery feat/47-H2-a.

Builds: design 47 H2 §807; H-A-432 (1)
2026-11-22 01:48:18 +01:00
jschoubben 575fe56243 M1: the gate's and artifact-store-tools' caps stand above their live fills
Read on novox at 2026-11-22 (the seat mesh-broker's show; the gate's
old-section state source through the bus module's nats_streams, since the
bus module made no entry for it):

  mesh-delivery-gate heads      582 bytes, 5 keys     cap 8 MiB
  mesh-delivery-gate findings   24905 bytes, 27 keys  cap 8 MiB
  mesh-delivery-gate source     70166 bytes, 68 msgs  cap 8 MiB
  artifact-store-tools findings 8199 bytes, 8 keys    cap 8 MiB

Each fill is below a quarter of 8 MiB (2 MiB), so each cap M1 wrote stays
at 8 MiB; none is raised.

Builds: design 47 H2 §812; H-A-411 (2), H-A-437
2026-11-22 01:46:45 +01:00
jschoubben 3ec18c9cd2 M1: nftables' setting allowances-max is marked runtime
The packet filter holder's tools read allowances-max themselves (config at
tools/index.ts); no file places it, so the manifest says "runtime": true
and the judge's placed-nowhere rule holds it as read by the module's code.

Builds: design 47 H2 H-A-430 (4)
2026-11-22 01:45:28 +01:00
jschoubben 872ed19648 M1: every module's findings stream holds 8 MiB, not only the delivery modules'
The eleven other modules that bind finding-events (claude-code, mesh-healers,
mesh-knowledge, mesh-provisioner, mesh-recovery, mesh-self-check,
mesh-watcher, minio, nfs-server, restic, zfs) set max-mib 8 for 7 days, as
the delivery modules' already do, so the indexer's finding-events rule (I6)
judges every manifest alike.

Builds: design 47 H2 §783; H-A-411 (1), H-A-430 (3)
2026-11-22 01:44:03 +01:00
jschoubben 39ed20c5bc C4: the forge module's tokens live in the vault, one process mints at a time
Two processes that minted at once left the forge two tokens by one name, and a token kept in a file in the
runtime state is a plain state. Both accounts' tokens (mesh-tools, mesh-packages) are now the module's own
secrets in the vault, written through the seat mesh-vault's own-put and read through its get, sealed to the
reading process's key. A refused or expired (token-ttl) token is minted again only by the holder of the lease
mint in the state token-lease (mint-lease); each mint is named <account>-<generation>, and the token it
replaces is deleted by id only after own-put landed. The Go bundles read their tokens through get at start
and at secret-changed; the MESH_GITEA_*_TOKEN_FILE words go. forge_token_lease reads the lease and each
token's age, never the token.

Builds: design 47 H2 §808, §822; H-A-407, H-A-422, H-A-426, H-A-430 (1)
2026-11-22 01:41:30 +01:00
jschoubben d3d9ff5183 M1: the build modules and the registry say their class and name every store's cap; detected-steps is pruned
Each of the four is core. Every state that named no cap names one, from its
live fill read 2026-11-22 01:4x CET (mesh-broker show, nats_streams on novox):
mesh-build-go steps 16.0 MiB (16,783,695 bytes) -> 128 MiB; mesh-build-node
steps 2.35 MiB (2,463,833 bytes) -> 16 MiB; every other state under 2 MiB ->
8 MiB (largest: distribution holds 1,844,287 bytes, mesh-build-go
detected-steps 868,554, distribution transfers 846,359, findings 668,161, idle
401,736, mesh-build-go pauses 254,366). The Go build module's finding-events is
8 MiB for 7 days. The objects stores already name their caps; none keeps a log.
The Go and Node build modules prune their state detected-steps (each key an
artifact's steps as detected, detected again when gone) at their own writes,
past prune-mark 70 % down to prune-target 50 %, and serve
<module>_state_prune_now and <module>_state_keep; no other state of the four is
prunable (each is truth: running steps, pauses, keys, toolchains, findings,
holds, transfers, windows, mirrors, taken asks).

Builds: design 47 H2 §812, §820; H-A-411 (1), (2), (3), H-A-437
2026-11-22 01:39:49 +01:00
jschoubben 1697b7041c BM4: each build module keeps a run's test output in its outputs objects
The Go build module's level answers its text in output (test2json's Output
lines), the Node build module's what its commands wrote; the delivery SDK's step
run keeps it as <node>.<ask> in the module's outputs objects, which each module
asks for in requires (1 GiB, kept 7 days) and reads through the verb output at
form 2. Each module's kit test runs the SDK's SeatVerbs.

Builds: design 47 H2 §791, §820; H-A-412 (1), H-A-412 second addendum (a), H-A-421, H-A-434
2026-11-22 01:32:40 +01:00
jschoubben 46990669de BM4: the bus module's keeper keeps an objects store's objects for its max-age-days
The objects template takes max-age-days (absent keeps an object for good): the
keeper plans it as the object store's max age, which the bus applies as the
store's TTL, so a build module's outputs objects go at their seven days.

Builds: design 47 H2 §820 (outputs: 7 days, the store's max-age), §791; H-A-434
2026-11-22 01:32:03 +01:00
jschoubben e335e859d5 BM3: the Node build module installs a module's npm tree and publishes it as <module>:node-modules
An install ask's body runs npm ci from the lock with no install script and no
link, packs the tree alone under modules/<module>/node_modules, publishes it to
the artifact store as the archive <module>:node-modules under the ask's version
and answers its reference, which the step's end carries. The package.json npm
ci needs is written from the lock's root entry, a lock without one refused. The
integration level's setup bound in code goes: half of the level's bound, which
each level's script gets as MESH_TEST_LEVEL_BOUND.

Builds: design 47 H2 §800; H-A-399 (2), H-A-403, H-A-427
2026-11-22 01:24:44 +01:00
jschoubben 1d8839640e BM4b: the build modules keep an oversized end in steps-objects, read by the verb answer
The delivery SDK replaced the output chunks with the verb answer over the
steps state's objects and output at form 2: each build module keeps an end
over the steps state's value with KeepAnswerIn, serves AnswerTool and
OutputTool over its steps state, and its steps name their outputs objects.

Builds: design 47 H2 §791, H-A-412 addendum, H-A-412 second addendum (b), H-A-399 (1)
2026-11-22 01:19:00 +01:00
jschoubben 9afbd35759 NP1: the NFS server and package manager modules' tests fold into one test per file, within 50 as the check counts
The check counts every test the integration level runs, untagged ones in: the NFS server
module held 51 and the package manager module 121, over the budget of 50. Each folded file's
tests run in order as rows of one test that keeps the first one's name and logs each case
before it runs; the root helper's test sockets are numbered per call, as one test now holds
several listeners, and the case that skips without pacman-conf runs last. Counts now 48 and 42.

Builds: design 47 H2 §819; H-A-349 DQ-14
2026-11-22 01:18:06 +01:00
jschoubben 7519191861 BM5: the steps read tools list an ask's steps under its asker, so they are never empty while asks run
Each build module's steps read tool listed only `<node>.<id>` keys and so
skipped every ask's step, kept as `<asker>.<node>.<id>`: it now reads every key
of its node, newest id first. The Go build module's test of capacity 0 also
holds the seat's current at form 2: no ask taken, why not capacity 0, then
paused.

Builds: design 47 H2 §801; H-A-399 (1)
2026-11-22 01:10:54 +01:00
jschoubben c63b4ae31d BM2: a test that cannot run says NOT RUN; the level's bound and the install archive reach the tests
The Go build module's level result carries not-run (the SDK reader's NOT RUN
skips), its tests get MESH_TEST_LEVEL_BOUND, the level's bound, from which
mesh-sdk's helpers take the setup bound; a test call naming an install archive
reads it from the artifact store by its reference and unpacks it into the
workspace's tree before go test. check-needs is read from the module's
manifest, on the Go artifact whose path holds the package, and the marker
file goes: the Node build module's manifest declares it on its bundle.

Builds: design 47 H2 §800; H-A-294, H-A-350 DMC-6, H-A-368, H-A-399 (1) (2) (3)
2026-11-22 01:07:45 +01:00
jschoubben a6132b32f6 C6: a source-only check's step-ended is heard on its escaped subject part
The manifest validator takes no # in consumes, and a key part escapes its
dots (mesh-sdk keys.EscapeName), so the forge module keeps hearing
step-ended.*.*.*: a source-only check's module source.<owner>.<name> is one
escaped subject part, and its body names it whole. The whole test says it so.

Builds: design 47 H2 §815; H-A-408
2026-11-22 01:07:28 +01:00
jschoubben bff5e98b30 C6: merge-pull refuses a source-only head whose check failed, naming the step
The runner's step-ended of a source-only check names the registration's key
source.<owner>.<name> as its module and the commit's root tree hash as its
fingerprint, so its subject holds more parts than a module's: the forge
module hears every subject under step-ended and judges it as a module's.
The seat's whole test refuses an hq pull request whose unit step failed.

Builds: design 47 H2 §815; H-A-408
2026-11-22 01:05:16 +01:00
jschoubben 74dd8af699 M1: the gate prunes its state heads toward its cap at its own writes
heads is written through the SDK's pruned state, which judges the fill each
put answers and past prune-mark (70 %) prunes the oldest keys to
prune-target (50 %); the gate serves mesh-delivery-gate_state_prune_now and
mesh-delivery-gate_state_keep, each written in the hand-act log.

Builds: design 47 H2 §812; H-A-380, H-A-386, H-A-411 (3)
2026-11-22 01:03:06 +01:00
jschoubben ac4ed46359 M1: every manifest says its class; the delivery modules' stores name their caps
A module that claims a seat is core, one that claims none a leaf (141
manifests; the build modules and the registry are the other developer's).
The forge module's, the gate's and the sweep's states each name 8 MiB, and
their findings stream 8 MiB for 7 days.

Builds: design 47 H2 §810, §812, §783, §820; H-A-394 (1), H-A-411 (1), (2), H-A-378
2026-11-22 01:01:26 +01:00
jschoubben 0cb4090096 C2: the environment check takes a declared setting's word as the node-engine's
The forge module reads ask-taken-bound from MESH_CONFIG_ASK_TAKEN_BOUND, the
word the node-engine composes for every setting a manifest declares; the
check takes MESH_CONFIG_<KEY> of each declared config key as set, and an
undeclared one as set by nothing.

Builds: design 47 H2 §775, §781; H-A-370, H-A-400 (2)
2026-11-22 00:58:29 +01:00
jschoubben ee5e7f232f P1: the packet filter holder reads a port's scope from its derived rule's comment
A derived accept rule's one comment says derived <modules> <protocol>/<port>
scope <any|private-network|local-network>, its module list cut with a count
past 128 bytes; allow without a source is refused for a port whose derived
rules name no scope any, read from the comments, never from a rule's shape.

Builds: design 47 H2 §813 (4); H-A-357, H-A-384 (1), H-A-349 DQ-11
2026-11-22 00:55:14 +01:00
jschoubben 6b17965d98 C5: forge_merged lists a repository's merged pull requests by number
From..to inclusive, each read from the forge one by one, with its merge
commit, when it was merged and the merge call that made it when a kept call
names it merged; at most 768 KB, capped with the next number as the cursor.

Builds: design 47 H2 §812, §811; H-A-402
2026-11-22 00:52:01 +01:00
jschoubben b93253e698 C2: the forge module takes an act of the seat git once by its ask id
Each act (status, comment, view, note, merge-pull, tag) carrying an ask id is
taken in the state taken, key git.<ask>, for the setting ask-taken-bound
(10m, read from MESH_CONFIG_ASK_TAKEN_BOUND): a repeat while the act runs
joins it; after it ended, the repeat answers what the forge holds of the act,
read afresh (a merge call's pull requests merged with their merge commits),
and the act is never done twice. An act that performed nothing drops its
key, so the kept call's repeat acts.

Builds: design 47 H2 §775, §820; H-A-381, H-A-400, H-A-359a
2026-11-22 00:51:01 +01:00
jschoubben 681de09f04 RG2: the registry's list pages by module and cursor; the sweep reads it page by page
oci-artifact-registry's list filters by name or module while it reads and
answers at most 768 KB a page with capped, total and the cursor next, in
order of the names; container-image-registry's answers whole as its form
says. The registry takes a removal for retention whoever asks it: the
refusal "not the sweep's" and its read of the sweep seat's holder go. The
sweep reads the list from its cursor until no page is left.

Builds: design 47 H2 §813 (7), §811, §779; H-A-350 DMC-10, H-A-399
2026-11-22 00:49:42 +01:00
jschoubben 54fe0dd7cc C1: the forge module says away when the forge or its store is away
A 401, 502, 503 or connection fault is judged by the forge's own
unauthenticated version read: the read failing, or naming the store
unavailable, answers the kind away with part and words, which every caller
reads as a transport fault; the read passing, a 401 (the fresh token refused
too) is the forge refusing the mesh's admin account, never worded as an
account to create.

Builds: design 47 H2 §776; H-A-350 DMC-2, H-A-354
2026-11-22 00:45:38 +01:00
jschoubben cb5de6fd31 MR1: the recovery module's whole test waits its start by the setup bound
The module's start is the test's setup: its two waits on the bus take
testbus.SetupBound (half of MESH_TEST_LEVEL_BOUND) and say a starved setup
in the one line testbus.Starved writes; its 30 s values go.

Builds: design 47 H2 §800; H-A-327, H-A-368
2026-11-22 00:43:38 +01:00
jschoubben 4e381c323b C3: the seat git's tags name each tag's commit, at the seat's form 2
tags answers items {tag, commit} read from the forge's own tag list, a tag
the forge names no commit for being an error, never a tag without one; tag
writes <directory>/vMAJOR.MINOR.PATCH, the form the Go toolchain's direct
fallback reads, go/v<version> among them.

Builds: design 47 H2 §796, §780; H-A-350 DMC-3; mesh-delivery D5 d2d3ebbf
2026-11-22 00:42:37 +01:00
jschoubben 5d2d0bade8 SC1: the self-check raises over-budget from the gate's times
gate_times answers per class its newest delivery (last) with whether it was
over its budget; the self-check's probe D-budget reads gate_times and raises
over-budget with the class as its id, naming the source revision and its
longest phase, and a newest delivery within its budget clears it.

Builds: design 47 H2 §810; H-A-396
2026-11-22 00:37:03 +01:00
jschoubben 872a02b378 RG1: a repeated publish ask reads the store's held version in its new form
The merge of main's H-A-387/H-A-393 fix gave Store.Held a reference and the
digest another publish holds; a repeat answers ended when the reference is set.

Builds: design 47 H2 §775; H-A-381
2026-11-22 00:33:39 +01:00
jschoubben 83012ad97b Merge remote-tracking branch 'origin/main' into feat/47-H2 2026-11-22 00:31:45 +01:00
jschoubben 607a1d76ea GT2: a delivery record keeps its delivery time; gate_times judges it
The head entry keeps merge-called from its opening and the pipeline's phases
from its end; a record whose every mover runs ends with delivery-time (from
merge-called to the last running of its movers) and class (core when a mover's
catalog entry, read once at its entry's opening, says core). gate_times answers
each class's budget (budget-core 10m, budget-leaf 3m), the last seven days'
median and worst, and every delivery over its budget with its longest phase.

Builds: design 47 H2 §810, §785; H-A-394
2026-11-22 00:30:48 +01:00
jschoubben 41610e903f BM1: the build modules give a step met away again by again-delays
Each build module declares again-delays (15s,60s) and gives its puller the
delays steprun.AgainDelays reads from it; a publish's no responders is a
transport fault by steprun.PublishFault with no seat call to learn why, so
the modules no longer invoke the assigner's assignments.

Builds: design 47 H2 §799; H-A-350 DMC-7, H-A-390
2026-11-22 00:27:04 +01:00
mesh-tools e3fff86f1a Merge pull request 'The artifact registry takes a publish whose reservation names no digest yet, and refuses a version it holds at another digest (H-A-387, H-A-393)' (#734) from fix/47-H1-registry-takes-unreserved into main 2026-11-21 23:24:04 +00:00
jschoubben eac56f9990 GT1: the gate's whole test over a real bus reads the mover's entry
The test bus serves the ledger's query the movers index answers, and the
take-in's mover is looked for in its own entry, the head counting it.

Builds: design 47 H2 §809; H-A-391
2026-11-22 00:22:05 +01:00
jschoubben e866a64be3 GT4: the gate watches a source-only registration's branch as any
The gate reads the registrations page by page from the cursor each page
answers, so a source-only registration (no module) past the first page is
watched as any branch; its merge's take-in with no movers ends the record
nothing to deliver as before.

Builds: design 47 H2 §815, §806, §779
2026-11-22 00:21:06 +01:00
jschoubben 6f744d6602 GT1: the gate's ledger keeps one entry per module and revision
A record's head entry record/<branch.source> keeps the record-wide fields and
the count of its movers; each mover, the catalog half's too, has its entry
mover/<branch.source.module> with its pipeline, version and step outcomes per
node, found through the index movers on its record's key. An entry over
64 KiB is refused with record-too-large, cleared when written within it or
at the record's end; the ledger is capped at 1 GiB.

Builds: design 47 H2 §809, §820; H-A-385, H-A-391
2026-11-22 00:19:16 +01:00
jschoubben 7765947476 The artifact registry refuses a held version published at another digest (H-A-393)
While the reserved digest is still empty, a second publish of the same
version with another digest passed the reservation check and the store's
Put moved the version's tag. Publish now refuses it in its held branch,
before the reservation is asked, naming both digests, with the publish's
finding and refused said as any refusal; the same digest is taken as before.
The store's Held answers the digest it holds at the version when it differs.

Builds: design 47 H H-A-393, design 47 G A-490j
2026-11-22 00:18:20 +01:00
jschoubben 410451a2a2 GT3: the gate's deliveries filters while it reads and pages at 768 KB
deliveries takes module, outcome, since and the cursor next beside state,
repository and group, applies them while it reads, and answers at most
768 KB a page with capped, total and the next page's opaque cursor.

Builds: design 47 H2 §811, §779
2026-11-22 00:14:55 +01:00
jschoubben 69940d1019 The artifact registry takes a publish whose reservation names no digest yet (H-A-387)
The builder records a build's digests only at its end, while the Go build
module publishes during the build step with the reserved version (H-A-373),
so the distribution holder's strict digest check refused every archive-only
publish with "reserved ... for another digest". Recorded now takes an
artifact whose reserved digest is empty, as A-490j decided for every holder,
still refuses a different recorded digest, and its refusal names the case:
the digest reserved and the one published, or no reservation of the version.

Builds: design 47 H H-A-387, design 47 G A-490j
2026-11-22 00:14:30 +01:00
jschoubben 34f55bdf79 RG1: the bounded steps' finding test joins their one test function
Builds: design 47 H2 §819
2026-11-22 00:06:07 +01:00
jschoubben babcd1bb31 RG1: the registry takes a publish ask once by its id
A publish carrying an ask id is kept in the state taken for ask-taken-bound
(10m): a repeat while the act runs joins it, a repeat after it ended answers
the act's state read afresh (the transfer's lacking parts, a held version
ended, a transfer gone refused), never publishing twice.

Builds: design 47 H2 §775, §820; H-A-359, H-A-381
2026-11-22 00:05:58 +01:00
jschoubben d545299a71 RG3: the registry purges a deleted chunk's leftovers
Every delete of a chunk in the incoming object store is followed by the
runtime's purge of what it left (busstate.Objects.Purge), so the store's kept
descriptions equal its live objects; a failed purge is said.

Builds: design 47 H2 §813 (8); H-A-227, H-A-366
2026-11-22 00:02:56 +01:00
jschoubben 086745edd5 Merge remote-tracking branch 'origin/main' into feat/47-H2 2026-11-21 23:53:45 +01:00
mesh-tools 7030e1420c Merge pull request 'The Go build module fetches an archive-only lane of a module without Go code; every publish of the Go and Node build modules names the ask's version (H-A-371, H-A-372, H-A-373)' (#733) from fix/47-H1-go-fetch-archive-only into main 2026-11-21 22:49:52 +00:00
jschoubben b5c05b326a Go build module: a bundle's and an archive's publish carry the version the ask reserved
Every bundle and archive was published with an empty version, a by-digest
publish, so the builder marked none against its reservation: the same kind
as the Node build module's bundles.

Builds: design 47 H H-A-373
2026-11-21 23:45:30 +01:00
jschoubben ebf4d9896b Node build module: a bundle's publish carries the version the ask reserved
Every bundle was published with an empty version, a by-digest publish, so
the builder never saw package-published and the bundle was not marked
against its reservation.

Builds: design 47 H H-A-372
2026-11-21 23:38:37 +01:00
jschoubben 02371b32de Go build module: a module directory that chooses no Go module is an empty scope
The builder sends a module's directory with every lane, and an archive is
packed by the Go build seat, so the fetch's refusal of a directory without
go.mod left every archive-only module without Go code unbuildable. Such a
directory is now an empty scope (the empty scope file written); a Go bundle
or package without go.mod still fails at its build step, naming it.

Builds: design 47 H H-A-371
2026-11-21 23:37:51 +01:00
jschoubben 0bc03bba35 §780 readers: take the form the tolerant seat decoders answer
mesh-contracts' K1 regenerated every seat package to answer (value, form, error); the catalog's four
callers take the form.

Builds: design 47 H2 §780; H-A-350 DMC-4
2026-11-21 23:20:11 +01:00
jschoubben 0206ec825e VA1: the vault takes a module's own secret through own-put and answers it through get
The forge module needs a place for its token that only its own processes read: own-put keeps it as
module/<module>/<name>, named by the caller's account, its newest generation only.

Builds: design 47 H2 §822, §808; H-A-345, H-A-349 DQ-7, H-A-360
2026-11-21 23:14:43 +01:00
jschoubben 1cbe0b1294 N1: nats_connections carries each connection's five busiest subscriptions
Also fixes the trunk race in the request test: the watch hands its handler over a channel.

Builds: design 47 H2 §813 (5); H-A-356
2026-11-21 23:07:54 +01:00
jschoubben 51c27203de N3: the keeper's approve-level bend names the research that ends it
Builds: design 47 H2 §813 (11)
2026-11-21 23:06:52 +01:00
jschoubben 1ad170705e N2: the keeper withdraws a refused drop's or recreate's ask on operator-channel
A refused request leaves nothing for the operator to answer, so its ask is cancelled in the same pass.

Builds: design 47 H2 §813 (6)
2026-11-21 23:06:43 +01:00
jschoubben c5a593eb05 N1: the bus module's nats_consumers lists consumers by delivered-rate or created
The flow per consumer is measured within one call, so a busy bus says with what.

Builds: design 47 H2 §813 (5), §819
2026-11-21 23:04:31 +01:00
mesh-tools 32e1ed6c55 Merge pull request 'The Node build module's integration tests supply the SDK the skipped fetch would place (design 47 G §571)' (#732) from fix/47-H1-build-node-tests-under-load into main 2026-11-21 21:44:31 +00:00
mesh-tools d7b23f50b4 Merge pull request 'Packet filter control verbs: the nftables holder serves the verbs, keeps allowances in its state and arms expiries (ADR 0683)' (#731) from feat/packet-filter-allow into main 2026-11-21 21:36:38 +00:00
jschoubben 6527ebd077 mesh-build-node: the real-toolchain tests' fixture holds the SDK where the fetch places it
Since the toolchain lock pins no SDK (design 47 G §571), only the fetch puts
@novox/mesh-sdk in a module's node_modules. The three tests that build with
the real tsc and esbuild skip the fetch, so they read the SDK from an older
installed toolchain that still carried one. Once a build node installed the
current lock (shanks 19:26, then g14), they failed with TS2307 (main.137,
main.155). The fixture now lays a minimal SDK of its own where the fetch
would, so the tests no longer depend on which toolchains a node still keeps.

Builds: design 47 G §571
2026-11-21 22:25:38 +01:00
jschoubben 31abcad907 nftables: test that a start waits for the watch's expiry; refuse a stale node-engine package
Review round 2 (1): the start's wait for the expiries the watch handed over
had no test that failed without it; the start test gains a store whose
deletes wait, and without the wait the key is said expired twice. The note:
a node-engine package naming no verb converged refuses the start loudly
instead of asking seat:node-engine.undefined.

Builds: design 33 control-verbs §10, §11, §14; design 47 H H-A-312
2026-11-21 22:05:47 +01:00
jschoubben f589b5af5c nftables: hold the verbs until the start ends; until with seconds; the seat's own forms
Review round 1 (1)-(3): an until without seconds was accepted, which the
node-engine's RFC 3339 read refuses, withholding every later compose; the
verbs answered before started was said and before the watch's expiries
ended; and the holder kept its own copies of the seat's names, key forms
and value forms, which had drifted from H-A-324. The holder now takes them
from the seat's generated package, the tools' inputs are checked against
its input types, and every seat verb waits for the start's end.

Builds: design 33 control-verbs §2, §3, §11, §12, §14; design 47 H H-A-324, H-A-330
2026-11-21 21:42:45 +01:00
jschoubben 38ea9ce25c nftables: allow names the outward link a kept allowance opens
An allowance with no interface never opens an outward link; one named in
interfaces does, and allow now says so: a kept allowance whose interface is
in the outward links of the converged answer asked for the call answers
with outward, that link. The holder reads no shape of the loaded table to
tell an outward link from the tunnel; the event carries no outward.

Builds: design 33 control-verbs §4, §14; design 47 H H-A-324, H-A-325
2026-11-21 21:19:03 +01:00
jschoubben 09d5758343 nftables: ask converged through the node-engine seat's generated package
The holder's ask of the node-engine's converged takes the seat's name, the
verb's name and the answer's form from the node-engine seat's TypeScript
package, as the holder says its own event through its seat's package.

Builds: design 33 control-verbs §10, §12; design 47 H H-A-316, H-A-321
2026-11-21 21:04:16 +01:00
jschoubben 83482a4513 nftables: allowances per machine, refused unproven or adopted, written in the hand-act log
The security and seams reviews of the packet filter's control verbs: the
allowances state is one bucket per machine whose keys carry the node, so a
holder lists and writes its own node's only; allow and disallow refuse an
unproven caller, an adopted node and a converged that does not answer within
10 s, and are written in the hand-act log before the state is; allow refuses a
port the loaded mesh table accepts from given sources only unless a source is
given, and more than the setting allowances-max; allowed answers none on an
adopted node and asks converged again while none answered; rules marks loaded
only on an equal at and lists loaded allowance comments nobody keeps. The event
is said through the seat's generated package; the claim says it, so emits
stays without it.

Builds: design 33 control-verbs §1-§11, §14; ADR 0683; design 47 H H-A-314 (3), (5), (6), H-A-315 (1)-(3), (5), (7), H-A-316, H-A-317, H-A-318, H-A-319
2026-11-21 20:52:34 +01:00
jschoubben 7bd1e74086 nftables: serve allow, disallow and allowed, keeping allowances as its own state
The operator, 2026-11-21 20:35: a firewall module has tools to control the
firewall beside the provisioning from declarations. The holder keeps one
allowance per protocol, port and interface in its state allowances, says every
change as allowances-changed, removes an allowance at its until by a timer on
its own state (and every expired one at its start, before started), and rules
marks each allowance loaded by its comment in the mesh's table. It writes no
rule: the node-engine renders the allowances.

Builds: ADR 0683; design 33 control-verbs §1-§7, §9; design 47 H H-A-304..310, H-A-312 (2)
2026-11-21 20:40:35 +01:00
mesh-tools 553bfb0ccf Merge pull request 'The forge's whole-seat test ends NOT RUN when its npm tooling is missing (H-A-294)' (#730) from fix/47-H1-gitea-whole-test-not-run into main 2026-11-21 18:30:10 +00:00
mesh-tools 3c27ea7a11 Merge pull request 'The zfs keeper test's race, and a non-root peer whose write is cut is told only root (A-37)' (#729) from fix/47-H1-zfs-keeper-test into main 2026-11-21 18:29:59 +00:00
jschoubben e2571a6468 gitea: the seat git's whole test says NOT RUN where node, npm or its npm packages are missing
The Go integration level fetches the forge module's tree without node_modules and
without network, so TestTheSeatGitWholeOverARealBus failed every pipeline carrying
the forge. It now checks its needs first and skips by name, as the Node build
module's realMachine does; with its needs present it runs whole as before.

Issue 1960 (H1).
Builds: design 47 H H-A-294
2026-11-21 19:26:31 +01:00
jschoubben 94bcc14a82 zfs: the keeper's socket test no longer races, and a refused peer is told so
The test switched the peer's uid in a plain variable the keeper's serving
goroutines read, a data race that fails it under -race; it is an atomic now.
A peer the keeper refuses could also get "broken pipe" instead of the
refusal, when the keeper closed before the request was written: the client
now reads the refusal that waits on the socket. A request larger than the
socket's buffer makes that case happen every time.

Builds: A-37 (only root opens the keeper's socket; a non-root peer is told so); design 47 H section 10 rows 165 and 167 (hq branch design/47-H1-answers-59, 81fa1ee4)
2026-11-21 19:26:14 +01:00
mesh-tools 461868b9fe Merge pull request 'Design 47 H1: a trunk build places every mesh package it names; the bus module's whole test waits for a fill pass (H-A-267)' (#728) from fix/47-H1-catalog-trunk-packages-and-nats-test into main 2026-11-21 14:49:34 +00:00
jschoubben 4fb3ab6df5 mesh-build-node: say a placed release outside the package file's range (H-A-276)
The latest release is placed whatever the range a package.json names
(ADR 0573 §2); one outside that range is now said in the journal, for
the SDK and every other mesh package, so a module built against a
release its range excludes is visible. A range of a form not read is
said as such.

Builds: design 47 H H-A-267, H-A-276
2026-11-21 15:47:46 +01:00
jschoubben a5976cf299 mesh-build-node: hold the member's-build precedence over the registry in a test (H-A-267)
A fetch naming a member's build of a mesh package the registry lacks
lays the build and waits on nothing; without the skip in
placeMeshPackages it waits for the registry's release.

Builds: design 47 H H-A-267
2026-11-21 15:45:10 +01:00
jschoubben 820840076f nats: the whole test waits for the first fill pass, not a first view's answer (H-A-268)
The keeper never marks a first view listing no module as answered
(A-367), so the subtest waited for what cannot come and hid every later
subtest. It waits for the first fill pass and takes it as the first.

Builds: design 47 H H-A-268
2026-11-21 15:37:46 +01:00
jschoubben 83802dc4a6 mesh-build-node: place every mesh package a module names at its latest release (H-A-267)
A trunk build put only the SDK into a module's node_modules; any other
@novox/mesh-* package its package.json names was left out of the install
and only a group or a member's build brought it, so the forge module's
build failed with "Cannot find module" for its contracts package. Each
such package is now placed at the latest release the registry holds, as
the SDK is; a group's packed package or a member's build still takes
precedence.

Builds: design 47 H H-A-267
2026-11-21 15:35:26 +01:00
mesh-tools efc8c52e68 Merge pull request 'Design 47 H1: the artifact sweep runs one pending pass from a followed view of the builds (H-A-250)' (#727) from fix/47-H1-artifact-sweep-one-pass into main 2026-11-21 11:08:08 +00:00
jschoubben 72872b045a Design 47 H1: a build's end comes from the builder's log; an unread end or view holds the pass loudly (H-A-258, H-A-260)
A done build whose history read failed was left out of the view for the whole process, so later passes judged from an
incomplete keep set, and every build cost one history read. A build's end is now taken from the build-ended entries of
the builder's log the pass already reads once, and only a build the log lacks is read from its history. While any done
key's end is unread, or the view is not yet taken in, no pass judges: it ends with the finding artifact-builds-unread,
written once and cleared by the next pass that judges. Every change heard while a watch's handover is gathered now goes
into that handover, so a build finished between the handover and its taking in is not lost by the swap (H-A-257).

Builds: design 47 H §H-A-255 (1), §H-A-257, §H-A-258, §H-A-260
2026-11-21 12:06:18 +01:00
jschoubben 603d4c7557 Design 47 H1: a watch of the builds asked again replaces the followed view whole (H-A-257)
A watch asked again after an error handed over the current values on top of the old view, so a key deleted while no
watch ran stayed in the keep set. Each handover is now gathered apart and replaces the view whole once it is in, and
the ends of keys it no longer holds are forgotten.

Builds: design 47 H §H-A-255 (1), §H-A-257
2026-11-21 12:01:58 +01:00
jschoubben 8d1c0d7d1d Design 47 H1: the artifact sweep judges from a followed view of the builds, not pages (H-A-255)
A page read costs the whole bucket per page, so the builder's builds are now a followed view: the watch's first view
at start, then its updates, kept in memory with each build's end read once from its history. A pass reads nothing of
the builds on the bus and judges nothing before the first view is in, so it never sweeps against an empty keep set.

Builds: design 47 H §H-A-250 (2), §H-A-255 (1)
2026-11-21 11:59:56 +01:00
jschoubben c01a816385 Design 47 H1: the artifact sweep runs one pending pass from one paged read, and stops on an unread list (H-A-250)
A finished build or a want change started a sweep and an observation each, every one reading the builder's builds key
by key and asking the registry's list again, queued behind one lock: a third of the night's bus flood. Now an event
marks the one pending pass, a pass running when marked runs once more, the builds are read in pages of the state with
each build's end from the page, and a list the registry seats cannot answer ends the pass with artifact-list-unread,
written once and cleared by a pass that reads it.

Builds: design 47 H §H-A-250 (1), (2), (3)
2026-11-21 11:54:46 +01:00
mesh-tools eb443cfc24 Merge pull request 'Design 47 H1: the bus module's warrant asks at approve level until a channel carries destroy; the router names the hold (H-A-237)' (#726) from fix/47-H1-nats-warrant-approve into main 2026-11-21 10:28:07 +00:00
jschoubben 7c6cf18532 Design 47 H1: a held destroy-level ask says its level; an offer with no channel named says so
The router held the bus module's destroy-level asks with the bare words
"no channel can carry it now", so the asker could not tell why. holdWhy
now names the destroy level and that no channel carries a destroy answer
yet. The bus module's tool says "offered, channel not yet named" for an
open record with no tickets, never "offered on :".

Builds: design 47 H H-A-237 (3), H-A-239 (2)
2026-11-21 11:26:19 +01:00
jschoubben a8f2316d08 Design 47 H1: the keeper's warrant asks at approve level; the tool says the router's standing
The bus module's drop and rebuild asks were at the destroy level, which no
channel carries yet, so the router held every one unshown until it expired
while the tool answered "the operator is asked". The ask is now at the
approve level for the caller's expires_minutes (5 to 1430, default 60,
refused outside), the keeper accepts an approve-level choice for these two
acts and bounds a request by its ask's own expiry, and the tool makes one
read of the router's record after the publish and says offered, held or
refused as it finds it; the request read shows that standing too.

Builds: design 47 H H-A-237 (1) (2), H-A-239 (1) (2)
2026-11-21 11:17:58 +01:00
mesh-tools af004a8ef6 Merge pull request 'Design 47 H1, proof 1 (second run): one line in feh' (#725) from proof/47-H1-feh-2 into main 2026-11-21 10:08:05 +00:00
jschoubben e1974b770e Design 47 H1, proof 1 (second run): one line in feh
Design lines: H §5 step 7. The first run's pipeline failed on the validate ask before the assigner fix.
2026-11-21 11:07:41 +01:00
mesh-tools c9beea9a38 Merge pull request 'Design 47 H1: the forge answers not-found for a missing directory in a trees listing (H-A-232)' (#724) from fix/47-H1-gitea-trees-not-found into main 2026-11-21 02:09:21 +00:00
jschoubben 74488f3e66 Design 47 H1: the seat git answers a listing's missing directory not-found (H-A-232)
A directory of a trees listing's files the commit does not hold was
thrown as a plain error and answered with the kind failed, so the
indexer took it for a forge that failed, never ran its one-directory
fallback (issue 1585), and published nothing of the repository.
commitTrees throws DirectoryNotInTree for it, and the seat's failure
answers it with the kind not-found, the error naming the directory.

Builds: design 47 H H-A-232 (2), H-A-234; issue 1585
2026-11-21 02:59:05 +01:00
mesh-tools 49cc5b3d7d Merge pull request 'Design 47 H1: the bus module counts every manifest's old-section entries as asked for (H-A-229)' (#723) from fix/47-H1-nats-old-sections into main 2026-11-21 01:33:10 +00:00
jschoubben 08ec25e367 Design 47 H1: a kept old-section entry keeps only the objects the keeper made; a kept state stays in the cap sum
Review round 1. keepOld took the old plan's objects whole, so a state's `<state>-objects` store
the grants part made beside a bucket the keeper made alone would have been compared, grown and,
on a recreate, deleted by the keeper: it now keeps only the old plan's objects the made record
already holds. CapSum skipped every kept entry as counted in the old sections' caps, which count
objects, logs and streams but never a state: it now skips only a kept objects, log or stream
entry, so a kept state's bucket stays in the sum.

At the delivery the plan digest changes once for every module with old sections (most modules,
since state counts): each plans again once, quietly, as its entries are compared with what the
bus holds and nothing is created or said where they agree.

Builds: design 47 H H-A-229, H-A-230, H-A-231; G §547
2026-11-21 02:32:01 +01:00
jschoubben ec305f08e6 Design 47 H1: the bus module counts every manifest's old-section entries as asked for (H-A-229)
The keeper read only a manifest's new-form asks, so the entries it had made for the artifact
registry and the forge, now declared in their old sections, stood as orphans with live data: a
rebuild refused, a drop offered. The keeper now reads every manifest's old sections (state,
objects, logs, streams) by the SDK's naming per section, as the grants part composes them. An
entry it made under one of those bus names is no orphan, is compared and grown to the declared
cap and rebuilt on request; it creates none of them and says no created for one, and counts a
kept one's cap once, in the old sections' sum.

Builds: design 47 H H-A-229, H-A-230, H-A-231
2026-11-21 02:26:20 +01:00
mesh-tools c050f23860 Merge pull request 'Design 47 H1, proof 1: one comment in feh, delivered by its pipeline' (#722) from proof/47-H1-feh into main 2026-11-21 00:43:52 +00:00
jschoubben ae9bb17e0f feh: name H1's proof 1 in the wallpaper file, the single-module change its pipeline delivers
A one-line comment in ~/.fehbg (the files archive) moves feh's fingerprint and
is readable on every machine that holds feh once it is delivered, with no hand act.

Design 47 H §5 runbook step 7: "Prove it. One single-module change (a comment in
a module with lint, unit and composition steps only), merged to main through a
merge call (merge-pull, design 47 H §734), followed from take-in.taken through
pipeline-ended to the node-engine's running and the gate's ended record, with no
hand act".
G §370: "The version reaches every artifact's build": the delivered files
archive carries the version the pipeline gave it.

Builds: design 47 H §5 step 7, G §370
2026-11-21 01:39:08 +01:00
mesh-tools be6eb0358f Merge pull request 'Design 47 H1: the Go build module takes a same-repository requirement from the tree at any version and reads the repository from the fetch (H-A-202, H-A-198, H-A-204)' (#721) from fix/47-H1-build-go-same-repo into main 2026-11-20 23:52:00 +00:00
jschoubben e1d2af8d6e mesh-build-go: build a same-repository requirement from the tree at any version (H item 6)
A requirement of the checked repository at a real version was fetched from the Go seat while the
indexer's fingerprint takes the tree, so the build and its key disagreed; and "same repository" was
read from the owner name novox/ written into the code. The fetch now takes every requirement of its
own repository from the fetched tree before anything is downloaded, at whatever version go.mod
names, keeps those directories in the narrowed tree, and judges "same repository" by the fetch's
repository as the ask names it.

Builds: design 47 H S31, S3, L8 (H-pins-spec-and-gaps section 8 item 6); H-A-204, H-A-202, H-A-198
2026-11-20 23:22:53 +01:00
mesh-tools 34a884ffcc Merge pull request 'Design 47 H1: disk-load declares its readings package, the gate accepts asks at 0.3, the Go build module refuses a build with no pin and keeps the same-repository tree (H-A-186, H-A-188, H-A-192, H-A-202)' (#720) from fix/47-H1-catalog-h1-owed into main 2026-11-20 21:39:11 +00:00
jschoubben b889075e21 H-A-202: the narrowed tree keeps the repository's packages a required package requires, transitively
A package artifact's go.mod may require a package of its repository that
requires another of it at the zero version; the narrowing kept only the
first level, so the build of the second found no module of that path. The
entry's paths keep the manifest's form; the Go build module reads each kept
package's go.mod in turn, each directory once, and keeps what it requires.

Builds: design 47 H H-A-202, H-A-198
2026-11-20 22:28:28 +01:00
jschoubben 3fd2e58072 H-A-192: the Go build module refuses a requirement with no pin of its own
Given no pin, the module took the version of another package of the same
repository, or the latest, and built against versions never published. A
requirement of another repository is now taken at the pin the ask names for
its own path, else the build fails naming the path; a same-repository
requirement is still built from the fetched tree.

Builds: design 47 H H-A-192, H-A-198, G §370
2026-11-20 22:20:12 +01:00
jschoubben dc507ec9ff H-A-186, H-A-188: declare diskreadings as a package artifact; the gate accepts asks at 0.3
disk-load's Go package diskreadings is imported by mesh-grants, whose build
waits for a publish no release made: an imported mesh package is a declared
artifact of its module, so every release publishes it. The gate imports the
assigner's asks, published in the assigner's series 0.3, so it names that
series in its packages.

Builds: design 47 H H-A-186, H-A-188, H-A-198, G §370
2026-11-20 22:13:25 +01:00
mesh-tools 3c402d766c Merge pull request 'Design 47 H1: proof 2, a two-module change along a dependency edge delivered by its pipeline (H §5 step 7)' (#719) from proof/47-H1-two-modules-2 into main 2026-11-20 17:55:45 +00:00
jschoubben 7de86ff471 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:28 +01:00
mesh-tools e8924b9f5d Merge pull request 'Design 47 H1: proof 1, a single-module change delivered by its pipeline (H §5 step 7)' (#718) from proof/47-H1-single-module into main 2026-11-20 16:00:06 +00:00
jschoubben 2cd3f20cb2 Design 47 H1: proof 1, a single-module change delivered by its pipeline (H §5 step 7) 2026-11-20 16:59:41 +01:00
mesh-tools e01c21f19e Merge pull request 'distribution: versions on the artifact seat answers the blob a reference names (A-430a, design 51)' (#717) from fix/47-H1-engine-archive-digest into main 2026-11-20 15:21:37 +00:00
jschoubben b68de8f186 distribution: test versions' digest per seat; say why a version has none
Review round 1: versionsAnswer's choice of digest per seat had no test.
TestTheVerbsSpeakTheSeatsContract now holds it, with a store whose blob
and manifest digests differ. OCI.Blob refuses a manifest that keeps no
single blob, naming its layers, and versions says that in the journal:
the contract's answer has no field for why.

Notes for H2: OCI.Held (oci.go) compares the tag's manifest digest with
a bundle's or an archive's blob digest, the same kind as this fault;
versions answers kind "" since the tool reads a kind its input does not
take.

Builds: design 47 G A-430a (G-22-lead-answers-2), design 51 *One contract*
2026-11-20 16:20:00 +01:00
mesh-tools 05955b6349 Merge pull request 'mesh-build-node: narrow a step's workspace as H-A-136 and H-A-137 say; a narrowed-out package is no module of the step' (#716) from fix/47-H1-mesh-contracts-publish into main 2026-11-20 15:12:43 +00:00
jschoubben 6f4e85c656 distribution: versions on the artifact seat answers the blob a reference names
The node-engine resolves a want's version to an archive's digest through
oci-artifact-registry's verb versions and fetches /blobs/<digest> by it.
The holder answered the tag's manifest digest, so shanks asked
claude-code/files' manifest as a blob and got 404 (claude-code 0.1.17).
On the artifact seat versions now answers the manifest's one blob, the
digest the reference and the event published carry; the image seat
keeps the manifest digest.

Builds: design 47 G A-430a (G-22-lead-answers-2), design 51 *One contract* (the seats' events carry the digest), the seat's contract Artifact and Listed.artifact
2026-11-20 16:12:27 +01:00
jschoubben f4cd0e89fd mesh-build-node-narrowed-packages: narrow a step's workspace as H-A-136 and H-A-137 say
Review round 1. The node build module runs the seat generator's check at its unit level
(steprun.OutOfStep), so its narrowed workspace keeps what H-A-136 and H-A-137 name: every
generated-from directory of the module, and for a root module the seats/ directory and the
paths of every artifact naming generated-from. Narrowed bare, a step of one mesh-contracts
package named the generated files left out as out of step. The fetch and the steps verb now
narrow the same way, and the steps verb reads its narrowed tree as the levels do.

narrowTree and generatedFromDirs are copied from mesh-build-go without its Go part, not moved
into mesh-delivery-sdk's steprun: the move is a change to two more repositories and a group
delivery for some sixty lines, in a fix that unblocks the build steps now; the copy says so.
packageDir and narrowedAway share one path helper.

Builds: design 47 H H-A-136, H-A-137 (hq design/47-H1-answers-59), ADR 0499 clause 4
2026-11-20 16:10:08 +01:00
jschoubben 0b834bbca7 mesh-build-node-narrowed-packages: a package narrowed out of a step's workspace is no module of it
A step of one TypeScript package of a module with several (mesh-contracts' root:
ts-meshbroker beside ts-meshrecovery, pipeline main.3 of 2026-11-20) fetches a workspace
narrowed to that package's path. The fetch and the lint and test levels read every package
artifact of the manifest, and one whose path the narrowing left out fell back to the
module's directory, which holds no lock: every TypeScript step of mesh-contracts ended
"could not run: the package in . has no package-lock.json". Such a package is now left
out of the fetch's install and of the levels' targets; an unnarrowed tree is read as before.

Builds: design 47 H H-A-136 (a step's workspace holds the artifact's paths; nothing else is fetched), ADR 0499 clause 4
2026-11-20 16:01:19 +01:00
mesh-tools a0e86fc696 Merge pull request 'mesh-vault, claude-code: consume binding.changed.<consumer>, so binding moves are heard (H-A-142)' (#715) from fix/vault-hears-binding-changed into main 2026-11-20 14:18:18 +00:00
jschoubben 51a83ed3a8 mesh-vault, claude-code: consume binding.changed.<consumer>, so binding moves are heard
The licence manager says each binding change as binding.changed.<consumer>
(mesh.mod.claude-licence-manager.event.binding.changed.<consumer>), but both
manifests consumed claude-licence-manager.binding.changed, which the grants part
composes into the exact filter mesh.mod.claude-licence-manager.event.binding.changed:
the bus consumer never handed either module one change, and the vault kept only its
first view (2026-11-20: g14 refused a switched licence's token until the first view
was asked again by hand). The consumed pattern now names the further part, `*`.

Builds: design 47 G A-134; design 39 bus-and-switch §17, §19, §22
2026-11-20 15:09:45 +01:00
mesh-tools eb4e964fbf Merge pull request 'claude-code: a login not handed gives way to a newer lease of its own account (H-A-140)' (#714) from fix/licence-file-the-cli-accepts into main 2026-11-20 13:49:50 +00:00
jschoubben 121125aa50 claude-code: the latest login wins over a login not handed to the manager
A login not handed is kept only against a lease that does not succeed it; a lease
of the same account that succeeds it replaces it, said as login superseded. A login
to another account is kept until the manager adopts it.

Builds: ADR 0206, ADR 0209, design 39 §6, H-A-138 (hq design/47-H1-answers-59 175ed320), H-A-139 (hq design/47-H1-answers-59 e359911e), H-A-140 (hq design/47-H1-answers-59 b75d1386)
2026-11-20 14:47:49 +01:00
mesh-tools 947a68d274 Merge pull request 'claude-code: a login is succeeded by its own refresh, not only by a newer lineage (H-A-139)' (#713) from fix/licence-file-the-cli-accepts into main 2026-11-20 13:27:19 +00:00
jschoubben 0934292f47 claude-code: a login is succeeded by its own refresh, not only by a newer lineage
The manager's refresh keeps the licence's refresh-token expiry, so a grant of the
same lineage with a later access expiry replaces the login; a grant with no
mark, an older lineage or no later access expiry is the older lease and is kept.

Builds: ADR 0206, ADR 0209, design 39 §3 §6, design 14, H-A-138 (hq design/47-H1-answers-59 175ed320), H-A-139 (hq design/47-H1-answers-59 e359911e)
2026-11-20 14:25:47 +01:00
mesh-tools 1b706ca0b1 Merge pull request 'claude-code: the node side never writes a lease over a login the manager was not handed, and only a newer lineage over a handed one' (#712) from fix/licence-file-the-cli-accepts into main 2026-11-20 13:24:15 +00:00
jschoubben a8a0cfeb8f claude-code: a login handed is replaced only by a grant of a newer lineage
One reason, login kept, on both paths, with a journal line; the not-handed
return skips the binding's generation on purpose.

Builds: ADR 0206, ADR 0209, design 39 §3 §6, design 14, H-A-138 (hq design/47-H1-answers-59 175ed320)
2026-11-20 14:21:47 +01:00
jschoubben a7459c6e4f claude-code: never write a lease over a login the manager was not handed
A login made on a node (while the tool runner was stopped, or before the
manager asked claude_code_grant for it) was overwritten by the next apply
of the binding's older grant: Apply took any refresh token in the file as
one already handed, and forced the write. The person's login was lost and
the session asked for a login again.

The node side now keeps the fingerprint of the login claude_code_grant last
sealed (state login-handed, never the token). Apply leaves a file whose
login is not that one untouched (applied false, reason login-not-adopted);
its report makes it the manager's candidate, and the successor the manager
hands back replaces it, as before without a refresh token.

Builds: ADR 0206, ADR 0209; design 39 §6 (the latest login wins, a login
moves its node); design 14 (a node never holds a refresh token).
2026-11-20 14:02:37 +01:00
mesh-tools 677c149022 Merge pull request 'The claude-code module renders no shell guard; the wait-list hooks stay (the operator, 2026-11-20)' (#711) from fix/claude-code-no-shell-guard into main 2026-11-20 12:56:56 +00:00
mesh-tools 144bfd5626 Merge pull request 'The Go build module's step workspace holds the generated-from directories and the same-repository zero-version packages (design 47 H, H-A-136, H-A-137)' (#710) from fix/47-H1-zero-version-tree into main 2026-11-20 12:56:52 +00:00
jschoubben 1ae83499ba claude-code: drop the machines data only the guard read
With the guard gone nothing reads the machines' names, domains and
addresses: remove Machine, the name lookup and the ten-minute timer that
resolved them again, so the tools' table is read only when a followed
state changes. Also remove the now unused cut helper.
2026-11-20 13:15:52 +01:00
jschoubben f57ae96e55 claude-code: remove the guard on the agent's shell
The operator asked for the shell guard to go (2026-11-20): the plugin no
longer carries a PreToolUse hook or guard.json, the binary no longer has
a guard verb, and the claude_code_guard tool, its record and the
refusal-ranked order of the instead-of table are gone. The SessionStart
and Stop hooks of the wait list stay, run by the same binary at the same
path, which is also the home-fs helper's. The rendered rule against ssh
to a mesh machine stays as the session's own and no longer claims a
guard enforces it; claude-agent no longer passes the guard's override.
2026-11-20 13:06:55 +01:00
jschoubben 30f274bcb0 mesh-build-go: a narrowed root module keeps its seats/ and every generated package
A module at the repository's root naming generated-from "." (mesh-contracts)
kept nothing of it: the narrowing kept "." alone, which prunes everything,
so the seat generator's check of go-meshconfig still found every file out
of step. Such a module now keeps the seats/ directory the generator reads
and the paths of every artifact naming generated-from; nothing else of the
root.

Builds: design 47 H H-A-137
2026-11-20 13:03:05 +01:00
jschoubben c52907a346 mesh-build-go: a narrowed workspace keeps generated-from and same-repository zero-version packages
The first pipeline of the clean state (main.3) failed every build of a
mesh-delivery-contracts client: the fetch narrowed the tree to the
artifact's paths (ADR 0499 clause 4), which removed
modules/mesh-delivery-sdk, so its requirement at the zero version found
"no module of that path in the fetched tree". The same narrowing left the
seat generator's out-of-step check without its seat definitions.

The narrowed workspace now also holds every generated-from directory an
artifact of the module names and the directory of every package of the
same repository the artifact's go.mod requires at the zero version, found
by the repository's manifests; the root's manifest and lock files are not
kept when narrowing from the root. The fetch's own Go modules stay those
under the artifact's paths (A-447a), not the added directories.

Builds: design 47 H H-A-136; design 47 G-22 A-447a

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 12:41:16 +01:00
mesh-tools 8b91552f59 Merge pull request 'Design 47 H1: the gate (merge-pull is the start), gitea, build modules, bus tools; retired parts removed' (#709) from feat/47-H1-gate-forge into main 2026-11-20 07:15:15 +00:00
jschoubben 6ecadf294e GATE-R2: the retired checker no longer reads the gate's state source
Builds: design 47 H §764

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 06:35:44 +01:00
jschoubben ae8b0c65bc NATS-R2: nats_consumer_remove judges durables by every accepted module
The refusal read the keeper's state asked, which holds only a module that
asks for kept data, so a running module keeping no bus data would lose its
live durables. It now reads the keeper's state plans, one key per module of
a watched branch's newest revision; the keeper no longer deletes a plan key
when a module's asked key goes, so plans stays that accepted set.

Builds: design 47 H H-A-126, H-A-127, H-A-128; design 47 G §538

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 06:35:44 +01:00
jschoubben 1568877f35 nats-tools: a durable beginning <node>_<module>_ is the module's too
Builds: design 47 H H-A-128

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 06:22:51 +01:00
jschoubben 04eda6130d mesh-cli: nox checks goes; the seat mesh-delivery no longer serves checks
Builds: design 47 H §764 (the checker and its verbs retire)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 06:20:40 +01:00
jschoubben 959e8d6d30 nats-tools: nats_consumer_remove judges a consumer by its name and records the hand act
An accepted module's durable (<node>_<module>) is refused on any stream; any
other durable is an orphan and goes, why its warrant, recorded through
mesh-hand-acts. It no longer refuses every consumer of a kept-data stream.

Builds: design 47 H H-A-126, H-A-127

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 06:20:30 +01:00
jschoubben 01543d9121 gate: gate_record_end takes an all form for the clean state
Every open record ends after one hand act naming how many; the answer says
what it ended, counted.

Builds: design 47 H H-A-121 (2), §765 (the gate's open records go at the clean state)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 06:12:40 +01:00
jschoubben 8c8b4367f1 mesh-mail-reader: its callers list goes; every verb answers every caller
Every account may call every verb; what protects the mail is what the verbs
answer (ADR 0459 §2), not who may call them.

Builds: design 47 H §764 (every callers list, §752); H-A-122

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 06:10:56 +01:00
jschoubben c775aab29a gitea, mesh-issues: no timer said for main's rules; the checker is no owner
Review round 1, notes: keep-main-rules acts at the token's mint alone since the
ten-minute step went (H-A-100), and the issue tracker's owners named the
checker's path, which a search for the checker must not find (§764).

Builds: design 47 H §764 (the forge module's ten-minute timer; the checker whole); H-A-100

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 06:06:57 +01:00
jschoubben df79ab8769 mesh-knowledge: the overview's delivery block and the progress verb's groups lines go
Review round 1, Must 3: the groups and group-ended are retired; the overview
showed the deliveries, another module's state, which the status view owns.
The overview keeps two sources (the tracker, the asks), consumes no merge,
transition or pipeline's end, and the progress verb asks no groups.

Builds: design 47 H §764 (the gate's verb groups; the runner's group-ended); H-A-28; H-A-125

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 06:04:16 +01:00
jschoubben 5b06dd7e43 messenger: the operator channel's holder keeps no held-back asks and serves no ask-again
Review round 1, Must 5: the seat lost held-back and ask-again (mesh-contracts
9db2e1d); the holder still offered held-back asks of before, refused choices
on them, listed them in asks and served ask-again.

Builds: design 47 H §764 (The operator channel's limit); H-A-57

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:57:16 +01:00
jschoubben c99ad77633 mesh-cli: nox try and nox groups go with the checker and the groups
Review round 1, Must 4: both called verbs no part serves.

Builds: design 47 H §764 (the checker whole; the gate's verb groups)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:54:54 +01:00
jschoubben 401289afac mesh-conditions: the hold reads a want's fingerprint alone
Review round 1, Must 2: the want's composed digest left mesh-sdk's motion.Want
(H-A-78); the hold read it and no longer built.

Builds: design 47 H H-A-78 (1)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:52:52 +01:00
jschoubben a6a6135f74 gate: drop the require of the checker's seat contract, which is gone
Review round 1, Must 1: commit 11a22fdf removed the checker's seat package;
the require left the gate unbuildable against the H1 heads.

Builds: design 47 H §764 (the checker whole goes); H-A-57

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 05:52:00 +01:00
jschoubben c91ab3acfa build modules: the checker seat's invoke, its client and its fixtures go; a run's input is asked of the seat mesh-wants
The kinds check and recheck stay in H1 (H-A-117).

Builds: design 47 H §764 (the checker (H1)); lead answers H-A-57, H-A-117

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:59:05 +01:00
jschoubben ba0330c205 mesh-cli: nox head take calls gate_head_take; indexer_take_in is gone
Builds: design 47 H §742, lead answer H-A-105

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:14:18 +01:00
jschoubben 15458aeb61 FORGE-6: the seat git's whole test runs the forge module's bundle on a real bus
A Go integration test builds the TypeScript bundle and plays its tool
runner over stdin and stdout against a bus of its own and a fixture
forge: a call stopped after two of three merges says one merge-called at
the start; a failed required step refuses its head; two pull requests in
two repositories merge and say one merge-called; a forge refusing the
second merge says what landed and raises merge-partial, cleared by a
later call.

Builds: design 47 H §774 (forge module: tests 111, 114, 115), §734, §735, §736, §766, §767; H-A-61, H-A-87 (1)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:58:00 +01:00
jschoubben 815be6bdce FORGE-6: the forge module's merge-check machinery and its polls go
announceHead with its mesh/merge-gate pending, the weighing of trunk and
sibling moves (passPulls, trunksMoved, siblingMoves, GateWriter) and their
files on disk, the pass's pull-passing half with its 60 s retry, and the
10-minute keep-main-rules step go. A pull request's new head is said as
pull.updated from the forge's event alone; the seat's status writes
through the client; pollRepos, pollMerged and readAllAtStart stay.

Builds: design 47 H §764 (the forge module: the merge-check machinery, its poll and timer), §762; H-A-28, H-A-100

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:54:09 +01:00
jschoubben f85f639afe FORGE-1: failed-steps reads the body's fingerprint; a step-ended without it writes step-unread
The forge module keeps a step's failure at the step-ended body's
fingerprint alone, consumes step-ended on its <module>.<branch>.<commit>
subject, and writes step-unread (scope module, keyed <run>.<module>.<step>,
warning, resolver operator) for a step-ended without its fingerprint,
cleared by the step's later step-ended with it.

Builds: design 47 H §735 (failed-steps from step-ended); G §585; H-A-18, H-A-47 (FORGE-1 builds step-unread), H-A-93

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:49:12 +01:00
jschoubben 0400d7bbe7 FORGE-5: forge_calls reads the merge calls; forge_call_say_again says one again
forge_calls answers the kept calls newest first with each member's base,
head and state; forge_call_say_again, with call and why, says a call's
merge-called again once the hand-act log took it.

Builds: design 47 H §766 (its tools); H-A-18

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:47:41 +01:00
jschoubben 3ba309c5e4 FORGE-4: a member the forge refuses after judging raises merge-partial
The call stops merging, says merge-called with what landed and refused,
and raises merge-partial (scope delivery, id the call, urgent, resolver
operator) in the module's findings; a later call landing every refused
member clears it, and forge_partial_clear clears one by hand after the
hand-act log took it.

Builds: design 47 H §767; H-A-1, H-A-18, H-A-81

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:46:59 +01:00
jschoubben 7f5f285b60 FORGE-3: a merge call says one merge-called, and the start says an unsaid one
Once its members are merged or refused the call says merge-called on
merge-called.<call> with its landed members (base and merge commit) and
its refused ones, and is kept said; a call that landed none says none. At
the start every call not said says it for what landed.

Builds: design 47 H §736, §766 (said again at the start); H-A-18, H-A-47 (said), H-A-71 (2)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:45:27 +01:00
jschoubben f0bf4578a9 FORGE-2: the merge call is written in the state calls before its first merge
The key call.<call> holds by, the proved account, at, each member with
its base and state (judged, then merged with its commit as it merges, or
refused with why) and said; a call past call-retention (a setting, 30
days) is deleted on a new call's write, oldest first, with no timer.

Builds: design 47 H §766 (the state calls, call-retention); H-A-18, H-A-47 (said, deletion on each new call's write), H-A-71 (2)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:44:20 +01:00
jschoubben 40dc5fe11d FORGE-1: merge-pull is one merge call, every member judged before any is merged
merge-pull takes pulls and by, refuses a call with no proved caller,
judges each member (its head, its base a watched branch, not merged
already, no required step failed at its fingerprint) and no branch
protection, merges none when one is refused, else merges in the order
named and answers the call and each member's outcome once. The seat's
branch answers no protection. The seen-expiry test no longer depends on
today's date.

Builds: design 47 H §734, §735, §764 (the single-pull form; merge-pull's protection judgement); ADR 0682 §13; H-A-21, H-A-22, H-A-24, H-A-47

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:42:00 +01:00
jschoubben 82d5688477 GATE-9: the gate's whole test holds the heads and the seed; the source key read as written
The source key is read with the escaping it is written with, so a merge
call's head on a branch holding a dot is no untaken head. The whole test
raises head-untaken for a head held past the bound, takes a merge call on
release/1.2, holds a push no call delivered, and holds nothing after the seed.

Builds: design 47 H §774 (gate: tests 110, 111), §737, §740, §742, §768; H-A-87 (2)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:35:43 +01:00
jschoubben 57984e9b98 GATE-5: the delivery record follows its pipeline to the machines
The record a merge call opened takes the runner's pipeline-started,
pipeline-ended, wait-held and wait-ended, the assigner's wanted and
pipeline-wanted and the node-engine seat's running, read by its key, and
ends on pipeline-wanted (running: every tier runs; tier-late: failed) or
failed on a pipeline that did not pass.

Builds: design 47 H §738 (G §141 to §147); H-A-29, H-A-75, H-A-89 (1) to (5)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:33:56 +01:00
jschoubben 2f471edc0f GATE-6, GATE-7: gofmt over the watchdog and its tools
The repository's gofmt check refused heads.go, headtools.go and main.go
as written; a stale comment of the stalled conditions goes with them.

Builds: design 47 H §740, §742

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:22:22 +01:00
jschoubben 6cde12bf2f BUILD-1: the build modules wire no asker judgement of the step runner
The three build modules no longer give the step runner a callers reader
of the seat list (steprun.SeatListCallers and Puller.Callers go): no seat
definition names callers and every account may call every verb.

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

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:19:16 +01:00
jschoubben e534f667da GATE-7: gate_heads reads the untaken heads; gate_head_take takes one in by hand
gate_heads reads the state heads with each head's since and finding;
gate_head_take, recorded in the hand-act log first, names the held head a
source revision as a merge call does, with a call of its own, its record
marked by hand with who and when and its member <repository>@<commit 12>,
and the finding clears.

Builds: design 47 H §742; H-A-24 (hand, by and the time in the trace), H-A-48 (a hand take's member <repository>@<commit 12>)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:18:27 +01:00
jschoubben 4f10af81b0 GATE-6: the watchdog holds a head no merge call delivered and raises head-untaken
The gate consumes the forge bridge's head-moved, keeps in its template
state heads each head source.<branch> does not name, and raises
head-untaken (scope delivery, id <repository>.<branch>, warning, the
operator its resolver) once untaken-bound passes, on its one deadline
timer; a later source revision naming the head lets it go and clears the
finding. The stalled conditions, their state and the operator-channel
use go: the watchman's record-open is the one signal.

Builds: design 47 H §740; H-A-27 (head-moved's form, forgemsg), H-A-48 (the stalled conditions go; untaken-bound on the gate's one timer), H-A-81 (warning, resolver operator, no owner)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:17:42 +01:00
jschoubben 6d398264db GATE-8: gate_source_seed seeds every watched branch's first source revision
For every watched branch the registrations name, one source revision at
each registered repository's head read through git.branch, start true, a
call of its own, source-moved said and no record opened; recorded in the
hand-act log first, the counts answered. It refuses to run while a key of
the earlier form is held, naming it (the source bucket is dropped first).

Builds: design 47 H §768; H-A-15, H-A-47 (the seed opens no record; the start pass writes through its path), H-A-76 (Q-G2: numbers from 1, refuses an earlier-form key)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:14:00 +01:00
jschoubben e44a2d140d GATE-4, GATE-5: a merge call names one source revision per branch and opens its record
The gate consumes the seat git's merge-called and, per watched branch its
members name, writes source.<branch> once by compare-and-set keyed by the
call, numbered one above the branch's newest; opens that revision's record
keyed <branch>.<source> with the call, by and account in its trace; says
record-opened on record-opened.<call> and source-moved on
source-moved.<branch>.<source>. The take-in.taken writes its movers into
the record read by its key, and a take-in with no mover ends it as nothing
to deliver. The verb groups, the record's pins and pins-stated, forge-made
and the emitted transition go. One commit for both subtasks: the record's
opening is the handler's second half and neither compiles alone against
the contracts.

Builds: design 47 H §737, §738 (a take-in with no movers ends its record), §749 (the pins are the indexer's), §764 (the gate: the source moved on take-in.taken, the verb groups); H-A-13, H-A-19, H-A-24, H-A-25, H-A-28, H-A-29, H-A-33, H-A-47 (the start writes through the seed's path, no record), H-A-48 (pins, pins-stated, transition, members <repository>@<number>), H-A-76 (Q-G1: the say-again carries the value's heads, start false)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:12:57 +01:00
jschoubben f9857ab712 CALLERS-2: the vault's secret-ask and retire callers lists go; its enrolment check stays
Every account may call every verb from H1, so secret-ask answers every caller the runtime
proved and retire every caller whose warrant holds; the manifest's two lists, the config
retire-callers and its file go. The enrolment verbs keep their one list, now a small type
of the vault's own since mesh-sdk's Callers goes.

Builds: design 47 H §752 (ADR 0682 §10's exception for the enrolment caller, H-A-11); H-A-41, H-A-66

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:51:02 +01:00
jschoubben 0cafb62d0e CALLERS-1: claude-code and mesh-recovery keep no callers list for the seat list
mesh-sdk's callers set goes in H1, so the seat list's two tools of claude-code answer
every caller, and mesh-recovery's seat list part is made with its prefix alone.

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

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:51:02 +01:00
jschoubben d7dada57aa CONFIG-1: mesh-config judges retirements on catalog-revision; #708 onto main
#708's six commits are taken onto main (the pull request path and A-490l's sweep go).
manifest-accepted goes in H1, so a retiring value is judged for every module a
catalog-revision names changed, and the resync tool's words no longer name the
indexer's config candidates, which retire too.

Builds: design 47 H §763 (G §654), §764 (mesh-config: its pull request path and A-490l's pull sweep; the indexer's manifest-accepted and config candidates); H-A-49, H-A-61

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:42:16 +01:00
jschoubben a1bc613702 mesh-config: a rename window written after start rearms the deadline timer (issue 1982; ADR 0681 §1; A-490l)
The timer was rearmed on a write of proposals or retiring only, so a rename window opened after start, with nothing else
waiting on a time, left it blocked and its seven-day held finding never came; a window opened under a later armed deadline
came late. The condition is now armsDeadline (proposals, retiring, renames), and a test shows a written window rearms it.
The comment on Proposal.Pull cites ADR 0681 §5.

Builds: ADR 0681 §1; lead answer A-490l (hq main, 03-DESIGN/01-to-be/47-milestones/G-22-lead-answers-2.md: the held finding comes in a quiet mesh too).

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:38:45 +01:00
jschoubben abcbeed115 mesh-config: one deadline timer for the earliest real deadline, its floor a setting (issue 1982; ADR 0681 §1; A-490l)
The one timer left is set for the earliest of three deadlines: a waiting proposal's end, an unanswered retirement's second
ask, and a rename window's seven-day held finding, which is now judged at its deadline (JudgeHeldWindows) so it comes in a
quiet mesh too. Its floor is the module's setting deadline-floor-seconds (default 60), not a constant.

Tests: an integration test counts asks by key and fails on any `seat:git.*` over the whole run (ADR 0681, How it is checked,
clause 1); a unit test shows an approved proposal records a hand act naming no pull request; another that a stored proposal
naming a pull request is refused on approval, saying why.

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:38:45 +01:00
jschoubben 673d1db95a mesh-config: drop the require of the removed meshconfigclient (issue 1982)
The generated client held only the held values' keys and decoder, which the seat no longer has.

Builds: ADR 0681 §1, §6 (the seat keeps no held value, so its generated client goes).

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:38:45 +01:00
jschoubben c7f54357ad mesh-cli: config no longer passes pull (issue 1982; ADR 0681 §1)
mesh-config's verb takes no pull request argument any more, so `nox config` offers none.

Builds: ADR 0681 §1 (the verb `config` takes no `pull`).

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:38:45 +01:00
jschoubben a30852939c mesh-config: remove the pull request path (issue 1982; ADR 0681 §1, §3, §5, §6)
The mesh knows no pull request (design 47 G, G-1 §38-39). Removed:
- the states `pulls` and `kept` and all code that reads or writes them (pulls.go, the held values a proposal holds, the
  listing of held values), SweepPulls, settlePull, HeardPull and the forge call;
- the consumes of git.pull-merged and git.pull-closed, the invoke of seat:git.pull;
- the config verb's `pull`, `head`, `declares` and `pulls` arguments and its actions `pull-declares` and `held`;
- the indexer's config candidates, which only that path used: the consume of mesh-delivery-indexer.views.config-candidates
  and the invoke of indexer_read_config_candidates (the indexer's state goes in the same group).
A stored proposal that names a pull request is judged not one this module makes, so nothing is set on it.

Builds: ADR 0681 §1 (no pulls or kept, no git events, no seat:git.pull, no `pull` argument, no pull-declares or held), §3, §5, §6;
lead answer A-490l (a stored proposal naming a pull request is refused on its approval).

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:38:45 +01:00
jschoubben 9cfda8d6c7 mesh-config: read its own states from a watched copy and wake only on an input (issue 1982)
mesh-config sent about 262 requests a second and received about 1,540 since its start: every sources() call (a
resolution pass, and a `delivered`, `manifest-reads-changed` or `manifest-accepted` event, each of which read the sources
whether or not a window or a retirement was open) read every key of its own states by one get each (pulls 1,176 keys,
resolved 447, declared 168, values 101...: about 1,200 requests for an event, 2,800 for a pass), serialised by one lock, so
a delivery's burst of events kept it asking the bus back to back.

- The module's own states are read from mesh-sdk's WatchedStates (one watch per state, its own writes taken into the copy)
  instead of a get per key (ownstates.go, main.go runtimeStore).
- An event judges what it names: `delivered` and `manifest-reads-changed` read no source when no rename window is open,
  `manifest-accepted` reads none when every row is already marked or read again (renames.go windowOpen, retiring.go).
- Open windows and retirements are judged again after each pass, since an entry that answers after the judgement was
  made moves the pass, not the event; the slow reads had hidden that race.
- No timer polls: the five-minute resolution and sweep of every pull request on the forge, and the minute's read of the
  router's record, are gone. The sweep and Decide run once at start (an event said while the module was down is not said
  again), then on git.pull-merged/-closed and operator-channel.decided.mesh-config; an ask ended with no choice also
  takes the retirements from the router's record. One timer is left, a deadline: for the earliest waiting proposal
  (ProposalLasts + 1 h) or unanswered retirement (HeldFinding), set again when either is written (NextDeadline).

Wake-ups kept, each by its record: `delivered` and `manifest-reads-changed` close a rename window (design 32 *A config
value renamed*, ADR 0609 §4); `manifest-accepted` judges one module's retirements (design 32 *A value no longer read*);
`git.pull-merged` and `-closed` settle one pull request's held values (ADR 0502 §7); `decided.mesh-config` takes one ask's
warrant (ADR 0259); a changed view (assignment, want, predefined list, config candidate, catalog revision, entry) moves a
resolution that writes only what moved (ADR 0565 §3).

Builds: ADR 0681 §1 (no polling of the forge: the five-minute look ends); ADR 0580 §1; ADR 0426 §3; design 32 (*A config value renamed*, *A value no longer read*);
lead answer A-490l (hq main, 03-DESIGN/01-to-be/47-milestones/G-22-lead-answers-2.md) for the wake-ups and the one deadline timer.

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:38:45 +01:00
jschoubben a943b6a7db GATE-3: one path moves the source: the take-in and the bridge's merged message no longer do
From H1 only a merge call names a source revision, so the gate stops moving source on
take-in.taken and on the forge bridge's merged message, and the start's comparison with
the forge's heads, gate_source_follow, its finding source-uncompared and the forge-made
record opener nobody calls go with them.

Builds: design 47 H §737 (moveSource leaves the take-in.taken handler; ForgeMerged, moveHead, gate_source_follow go), §764 (the gate: the source per merged message, the start's comparison with the forge's heads, the source moved on take-in.taken; forge-made per H-A-25)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:38:01 +01:00
jschoubben d901c6c19d GATE-2: the gate's groups from branch names and its pull request states go
A merge call is the delivery's group from H1, so the gate no longer keeps deliveries
and groups from the seat git's pull events, reads no open pull request at its start,
and answers deliveries and show from the records alone. The verb groups stays,
answered from the records, until the seat mesh-delivery's definition drops it.

Builds: design 47 H §764 (the gate: the groups from a branch name, its states deliveries and groups, its consumption of pull-updated, pull-merged and pull-closed, its start reconciliation); H-A-28

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:36:11 +01:00
jschoubben 30d1527e6a GATE-1: the gate's switch, its carried approval and its old states go
The switch to the records ran once at G's delivery; from H1 one model holds, so the
switch, the carried Approve and its finding, the states merges and the old owed, the
ledger's switch key and the checker client nobody imports leave the gate.

Builds: design 47 H §764 (the gate: the switch and the carried approval, the states merges, owed, asks, pulls, turns); H-A-28

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:33:51 +01:00
mesh-tools f82338e8ff Merge pull request 'mesh-build-node: its steps say a step's end, lint is the type-check; every build module runs the step-ends and runs-counted kit cases (A-489b, A-489c)' (#706) from fix/build-node-step-ends into main 2026-11-19 21:40:25 +00:00
mesh-tools c28fd39d23 Merge pull request 'gitea: the package seats take a publish with a digest and no parts as tag-or-refuse (A-490, A-490a)' (#707) from fix/gitea-publish-by-digest into main 2026-11-19 21:40:03 +00:00
jschoubben ac2cd3749c Registry holders: the distribution holder keeps trunk's check; the package holders run the kit's held-under-another-digest case on both seats (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:35 +01:00
jschoubben 4bdcedd0f0 Registry holders take a one-part publish made while the build runs: a reserved artifact with no digest yet accepts it (A-490j)
Builds: design 47 G A-490j, §381, A-415

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 21:34:20 +01:00
jschoubben f85199f624 gitea: the not-stored refusal for another digest applies to the no-parts publish only; the one-part publish keeps trunk's refusal
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 13d43a7de0 gitea: a no-parts publish of a version held under another digest is refused as not stored, named by its digest; conformance runs on both package seats
The builder's republish recognises a refusal by the words not stored.
Builds: design 47 G A-490, A-490a

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 17:04:55 +01:00
jschoubben 5dfb357333 gitea: the package seats take a publish with a digest and no parts (held says published, else refused not stored)
The builder's publish again sends version and digest and no parts; the package seats refused it as not one part.
Both registry holders now run the publish conformance cases.

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 83accdbb4e build modules: cite A-489c on the runs-counted kit tests and failurekit's refusal
Builds: design 47 G §24; lead answer A-489c

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 15:45:49 +01:00
jschoubben 7c64c17e65 build modules: every one runs the runs-counted kit case; failurekit refuses one that does not (A-489a)
Builds: design 47 G §24; lead answers A-489a, A-489b

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 15:42:44 +01:00
jschoubben 0a446c7572 build modules: cite A-489b on the step-ends kit case, its check and the node's need
Builds: design 47 G §24; lead answer A-489b

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 15:38:16 +01:00
jschoubben e1521a2ecf build modules: every one runs the step-ends kit case; failurekit refuses one that does not; image and go count runs that started
mesh-build-image's steps now carry Node and SayStep (an image has no step, §328, but the kit holds all three). Prior wired in go and image.

Builds: design 47 G §24, §328

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 15:25:38 +01:00
jschoubben 3a94021766 mesh-build-node: its steps say a step's end, lint is the type-check, it has its own need
A pipeline step ask (the sdk's lib lint and unit steps) was refused with 'this build module says no step's end': its
AskSteps set no SayStep, Node, Lint or Has. They are set as mesh-build-go sets them; lint runs tsc --noEmit over each TypeScript
package; Puller.Prior counts only runs that started toward poison.

Builds: design 47 G §328 (Lint per language), §22, §24, §25

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 15:25:38 +01:00
mesh-tools 282758456c Merge pull request 'The build modules declare what their seat-list reader uses (A-488a, A-488b)' (#705) from fix/build-node-consumes into main 2026-11-19 12:51:11 +00:00
jschoubben 0e9f916806 The three build modules consume the seat list's events and invoke its verb
mesh-build-go and mesh-build-image follow the seat list as mesh-build-node does, so each consumes mesh-catalog.seat-definition-changed and
-removed, and all three invoke seat:mesh-catalog.seat-definitions, which the reader calls.

Builds: design 47 G A-488a, A-488b (hq 57c14047)
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 13:49:07 +01:00
jschoubben daa5d3ea5f mesh-build-node consumes the seat list's events, so its runtime's consumer exists
Its runtime follows the seat list (seatlist.Start subscribes to mesh-catalog.seat-definition-changed and -removed); with no consumes
there was no consumer shanks_mesh-build-node_tools, the seat list was never read and the asks of a named asker were given back.

Builds: design 47 G A-488a (hq 25df48ad)
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 13:41:12 +01:00
mesh-tools be993cb2c5 Merge pull request 'restic: its secrets belong to the account its processes run as (ADR 0680)' (#703) from fix/restic-secrets-owner into main 2026-11-18 01:18:35 +00:00
jschoubben cd3b8fe8e9 restic: its secrets belong to the account its processes run as
Its processes run as the operator account, so its own secrets are owned by it (design 20 "Whose a process's own secrets are").

Builds: ADR 0680 §1, §4; design 20 "Whose a process's own secrets are"
2026-11-18 01:21:54 +01:00
mesh-tools f0c21ca033 Merge pull request 'feh: the second single-module proof (one comment line)' (#702) from proof/feh-two into main 2026-11-17 19:49:31 +00:00
jschoubben c6ec42bc2e feh: mark the wallpaper file with the second single-module proof
The single-module proof of design 47 G (the operator, 2026-11-17), after pack49:
one change to one leaf module, followed to delivered on g14 and shanks with no hand act.
2026-11-17 20:49:20 +01:00
mesh-tools f65d789052 Merge pull request 'feh: the wallpaper file is replaced at every delivery (single-module proof)' (#701) from proof/feh-one-line into main 2026-11-17 16:02:47 +00:00
jschoubben 62b8251b99 feh: say the wallpaper file is replaced at every delivery, the glossary's word
The single-module proof of design 47 G (the operator, 2026-11-17): one change to one module,
followed through its pipeline to delivered on g14 and shanks.
2026-11-17 17:01:16 +01:00
mesh-tools 90c88fc7b5 Merge pull request 'A-471: the build modules' tests expect the language version in a toolchain report' (#700) from fix/a471-toolchain-language-version into main 2026-11-17 14:56:47 +00:00
jschoubben 740c218139 A-471: mesh-build-go start test expects the language version
Builds: design 47 G A-471 (G-22-lead-answers-2.md)
2026-11-17 15:53:05 +01:00
jschoubben 1481465ec7 A-471: the build modules' tests expect the language version in a toolchain report
The toolchain a build module reports (guard key and toolchain-reported event) names the
language version alone (mesh-delivery-sdk steprun Guard); the build module's own
Toolchain func keeps the installed text. Delivered with or after the sdk change.

Builds: design 47 G A-471 (G-22-lead-answers-2.md)
2026-11-17 15:53:05 +01:00
mesh-tools d2b8f64c94 Merge pull request 'G-24 tests on main: mesh-build-go keeps no step-code bridge, uses a stand-in composer, and runs within its level bounds' (#699) from fix/g24-tests-on-main into main 2026-11-17 14:35:32 +00:00
jschoubben eed95cd63b mesh-build-go: the integration level runs its slowest independent tests side by side, inside its 60 s bound
The level took 67 s locally and 74 s in the pipeline, over IntegrationRun's 60 s. The eight slowest tests share no state and run in
parallel: 31 s locally with the fixture's store and bus. The real-store test makes its work directory under the test temp
directory, not /tmp.

Builds: ADR 0445 §3 (the integration level's 60 s bound)
2026-11-17 15:31:00 +01:00
jschoubben 84106a9338 mesh-build-go: the compose ask's test builds a stand-in composer from its own testdata, reading no other repository
A pipeline's test step places no repository beside the tree and a module's tests read nothing outside their module (lead answer
A-474), so the test no longer needs MESH_CHECK_BESIDE or the node-engine's tree: it fetches a small program of the composer's
contract (testdata/composer) and still proves the build once, the kept composer on the second ask, and the verdict by case.

Builds: design 47 G lead answer A-474 (principles 10 and 9)
2026-11-17 15:31:00 +01:00
jschoubben 9ed13cd9dc mesh-build-go: the empty buildstep bridge goes (G's indexer runs), and the unit level runs its digest tests side by side
The bridge kept a directory for the pre-G indexer's package publishing; its own commit says it goes once G's indexer runs, and
the test of the delivery SDK's step code refuses it. The unit level took 6.3 s over its bound of 5 s in the take-in's pipeline:
the digest tests ran their go commands one after another; the marker table is a subtest per case in a fixture of its own, the
list half a test of its own, and the six slowest independent tests run in parallel (4.6 s locally).

Builds: design 47 G §464, §680 (the build modules keep no copy of the delivery SDK step code); ADR 0445 §3 (the unit level's 5 s bound)
2026-11-17 15:31:00 +01:00
mesh-tools d76c3588e3 Merge pull request 'gate: the start comparison ends only when every head was compared (A-464e)' (#698) from fix/47-G-start-compare into main 2026-11-17 08:22:03 +00:00
jschoubben 377d42f5ea gate: the start comparison ends only when every head was compared (A-464e)
Builds: design 47 G-22 A-464e, A-464
2026-11-17 09:03:29 +01:00
mesh-tools 9ade421e12 Merge pull request 'gate: the source of a watched branch follows every merge, forward only (A-464..A-464d)' (#697) from fix/47-G-untaken-merge into main 2026-11-17 01:13:07 +00:00
jschoubben 46f3dc8cd7 gate: take-in.taken moves a head only forward too (A-464d)
Also corrects the manifest test's comment, which said the gate does not hear merged (A-464).

Builds: design 47 G-22 A-464d, A-464
2026-11-17 02:10:36 +01:00
jschoubben 7da6dd20a1 gate: a head moves only forward and only when it changes (A-464c)
Builds: design 47 G-22 A-464c, A-464
2026-11-17 02:02:07 +01:00
jschoubben c87cf1ace5 gate: the source of a watched branch follows every merge into it (A-464, A-464b)
The forge bridge's merged moves the repository's head and says source-moved; at its start each head is compared with the forge's branch head; gate_source_follow does it for one repository by hand.

Builds: design 47 G-22 A-464, A-464b
2026-11-17 01:59:09 +01:00
mesh-tools 3f3f6789dd Merge pull request 'nats: the tools bundle answers initialize again' (#696) from fix/nats-starts-again into main 2026-11-16 21:29:12 +00:00
jschoubben 8b5cc8be8d nats: the tools bundle answers initialize again (keep days read when asked)
bundleKeepDays read the config value snapshot-keep-days while allTools
listed the tools, before stdio.Serve; a config read waits for the runtime's
channel, which opens only once the bundle serves, so the bundle never
answered initialize and node-tools served none of its tools (novox
2026-11-16 22:21 and 22:26, after the first build from main since A-112).
The setting is now read when nats_snapshots is called.
2026-11-16 22:28:40 +01:00
mesh-tools 7c6aed9d69 Merge pull request 'nats: a tool purges a stream's messages below a sequence' (#695) from fix/nats-stream-purge into main 2026-11-16 21:07:49 +00:00
jschoubben 4f9f307eaf nats: a tool purges a stream's messages below a sequence
A build seat's work queue (SEAT_NODE_BUILD_GO) held about 370 asks of
pipelines nobody waits for, ahead of the one pipeline wanted, and no tool
could empty it short of removing the stream. nats_stream_purge removes the
messages below a given sequence, keeping the rest, the stream and its
consumers; it needs why, reads first, offers dry_run, refuses a purge past
the stream's end and the module-kept data nats_drop owns, and says
stream-purged as its audit event, like the three removal tools.
2026-11-16 22:07:18 +01:00
mesh-tools e87c6cd3b6 Merge pull request 'mesh-build-go: an asked version brings the requirements and sums of its go.mod into the modfile' (#694) from fix/build-go-asked-versions-every-dir into main 2026-11-16 20:10:03 +00:00
jschoubben 73c2286ec9 mesh-build-go: an asked version brings the requirements and sums of its go.mod into the modfile
Kind: a version written into a workspace's modfile without what that version's graph needs, judged against files the build does not use.

Builds: design 47 G (ADR 0573 §2, §4, as written in versions.go: asked versions hold whatever go.mod names)
2026-11-16 21:06:17 +01:00
mesh-tools 3be2f79921 Merge pull request 'mesh-hand-acts: a thirteenth change through its own pipeline' (#693) from probe/thirteenth-pipeline-hand-acts into main 2026-11-16 15:42:06 +00:00
jschoubben cf5ea429a2 mesh-hand-acts: a thirteenth change through its own pipeline 2026-11-16 16:37:58 +01:00
mesh-tools 1419dcef7d Merge pull request 'mesh-hand-acts: a twelfth change through its own pipeline' (#692) from probe/twelfth-pipeline-hand-acts into main 2026-11-16 14:44:00 +00:00
jschoubben 8c96a02a01 mesh-hand-acts: a twelfth change through its own pipeline 2026-11-16 15:43:38 +01:00
mesh-tools 03cc8eac90 Merge pull request 'Design 47 G start: catalog fixes placed by hand and the Go build per module (A-447)' (#691) from fix/47-G-start-merge into main 2026-11-16 14:15:15 +00:00
jschoubben f31d6c645d Merge commit 'cdf16870' into fix/47-G-start-merge 2026-11-16 15:11:01 +01:00
jschoubben bbc9eb7c93 Merge remote-tracking branch 'origin/main' into fix/47-G-start-merge 2026-11-16 15:11:01 +01:00
mesh-tools 1310c28102 Merge pull request 'mesh-hand-acts: an eleventh change through its own pipeline' (#690) from probe/eleventh-pipeline-hand-acts into main 2026-11-16 14:02:55 +00:00
jschoubben affffa9c23 mesh-hand-acts: an eleventh change through its own pipeline 2026-11-16 14:58:00 +01:00
mesh-tools 94f3cde557 Merge pull request 'mesh-hand-acts: a tenth change through its own pipeline' (#689) from probe/tenth-pipeline-hand-acts into main 2026-11-16 13:46:58 +00:00
jschoubben 6962da2f98 mesh-hand-acts: a tenth change through its own pipeline 2026-11-16 14:46:48 +01:00
mesh-tools 0aee792af6 Merge pull request 'mesh-hand-acts: a ninth change through its own pipeline' (#688) from probe/ninth-pipeline-hand-acts into main 2026-11-16 13:32:32 +00:00
jschoubben 86367f65b2 mesh-hand-acts: a ninth change through its own pipeline 2026-11-16 14:32:22 +01:00
mesh-tools 932e5c4e4b Merge pull request 'mesh-hand-acts: an eighth change through its own pipeline' (#687) from probe/eighth-pipeline-hand-acts into main 2026-11-16 13:21:00 +00:00
jschoubben 930c0fb783 mesh-hand-acts: an eighth change through its own pipeline 2026-11-16 14:20:51 +01:00
mesh-tools 79bd15884d Merge pull request 'mesh-hand-acts: a seventh change through its own pipeline' (#686) from probe/seventh-pipeline-hand-acts into main 2026-11-16 13:14:34 +00:00
jschoubben 13a0277f8c mesh-hand-acts: a seventh change through its own pipeline 2026-11-16 14:14:21 +01:00
mesh-tools fcdf21d615 Merge pull request 'mesh-hand-acts: a sixth change through its own pipeline' (#685) from probe/sixth-pipeline-hand-acts into main 2026-11-16 13:10:33 +00:00
jschoubben d6b75616f5 mesh-hand-acts: a sixth change through its own pipeline 2026-11-16 14:10:25 +01:00
mesh-tools 096668a14a Merge pull request 'mesh-hand-acts: a fifth change through its own pipeline' (#684) from probe/fifth-pipeline-hand-acts into main 2026-11-16 12:50:56 +00:00
jschoubben 2b1bc1d302 mesh-hand-acts: a fifth change through its own pipeline 2026-11-16 13:50:47 +01:00
mesh-tools a55241c30b Merge pull request 'mesh-hand-acts: a fourth change through its own pipeline' (#683) from probe/fourth-pipeline-hand-acts into main 2026-11-16 12:21:38 +00:00
jschoubben e1ee303a1c mesh-hand-acts: a fourth change through its own pipeline 2026-11-16 13:21:29 +01:00
mesh-tools c9f8e6e8cd Merge pull request 'mesh-hand-acts: a third change through its own pipeline, each step asked for this module's directory' (#682) from probe/third-pipeline-hand-acts into main 2026-11-16 11:24:27 +00:00
jschoubben 0afca54a0f mesh-hand-acts: a third change through its own pipeline, each step asked for this module's directory 2026-11-16 12:24:18 +01:00
mesh-tools 8bb73eb61f Merge pull request 'mesh-hand-acts: a second change through its own pipeline, each step on this module alone' (#681) from probe/second-pipeline-hand-acts into main 2026-11-16 11:13:39 +00:00
jschoubben 229c887999 mesh-hand-acts: a second change through its own pipeline, each step on this module alone 2026-11-16 12:13:31 +01:00
jschoubben cdf168706b Go steps test a module's own directories alone, not what its go.mod replaces from outside (A-447c)
Builds: design 47 G (G-22 lead answers 2) A-447c
2026-11-16 11:42:56 +01:00
jschoubben ae78fb039f Go fetch with no dir fetches the tree whole again, for the checker until G removes it (A-447e)
Builds: design 47 G (G-22 lead answers 2) A-447e
2026-11-16 11:40:18 +01:00
jschoubben 928de07c43 Go build module: a step for a module compares its own module.json's generated files alone (A-447c)
Builds: design 47 G (G-22 lead answers 2) A-447c
2026-11-16 11:37:23 +01:00
jschoubben 666be37916 Go fetch is refused with no dir, naming its asker; the checking program's fetch names its directory (A-447b)
Builds: design 47 G (G-22 lead answers 2) A-447b
2026-11-16 11:34:17 +01:00
jschoubben ccab80d726 Go fetch with dir: a directory with no go.mod chooses every go.mod under it; none chosen fails naming it (A-447a)
Builds: design 47 G (G-22 lead answers 2) A-447a
2026-11-16 11:16:16 +01:00
jschoubben 1168376930 Go build module: a fetch asked with dir chooses that module and its local replaces alone (A-447)
Builds: design 47 G (G-22 lead answers 2) A-447
2026-11-16 11:09:26 +01:00
mesh-tools 2679399d60 Merge pull request 'mesh-hand-acts: the first change delivered through its own pipeline' (#680) from probe/first-pipeline-hand-acts into main 2026-11-16 09:17:04 +00:00
jschoubben ce30601b0c mesh-hand-acts: say in its header that its changes are delivered through its own pipeline (the first to run one end to end) 2026-11-16 10:16:53 +01:00
jschoubben d2c1a24a24 nats: the bus keeper no longer reads the seat mesh-catalog's states before the first views (reverts ed536102)
A-379 replaced A-376 for the start, and the seat mesh-catalog offers neither the states modules and manifests as views
nor verbs of those names, so the validator refused the manifest's two consumes and two invokes.

Builds: design 47 G A-379, A-445 (G-22-lead-answers-2.md)
2026-11-16 09:51:48 +01:00
jschoubben 88ff34e855 distribution: a step given up at its bound is said given up, and its call's end is said later
Builds: design 47 G A-443, A-443a
2026-11-16 09:46:12 +01:00
jschoubben 76195e421f mesh-delivery-gate: the start pass runs once, asking again only while the registrations cannot be read
Builds: design 47 G A-442, A-401
2026-11-16 09:41:45 +01:00
jschoubben 59704456c3 messenger: offer every ask when it is raised; hold none back for room
The operator channel kept at most three asks of one asker offered and held its oldest back behind newer ones, so asks
waited unseen (the pipeline's proposal behind two mailu asks). It keeps no count any more and holds nothing back: every
ask is offered when it is raised, and lapses at its expiry or ends at its answer. An ask held back before the change is
offered again at the router's next tick; ask-again offers one so and holds nothing back in its place.

Builds: design 47 G A-424
2026-11-15 15:52:48 +01:00
jschoubben 4a99f7044e distribution: a publish with a version and no parts tags the digest the store holds
The builder's publish again of mesh-delivery-pipeline 0.1.6 sends the version and the digest with no parts, as A-73
has it; the build stored the bundle untagged, and the holder answered 'publish: no parts' unless the tag existed
already. The holder now checks the digest against the store under the name (the artifact store, A-50), asks the
builder's reservation, tags it with the version and says published; a digest it holds none of is refused as not
stored, naming the digest.

Builds: design 47 G A-417, A-73, A-50, §588
2026-11-15 02:39:28 +01:00
jschoubben 7d17441a9a gofmt 2026-11-15 01:38:29 +01:00
jschoubben c006538064 Distribution: the incoming-full finding is said off the publish's path
Builds: design 47 G (publish path of oci-artifact-registry; no design line covers it)
2026-11-15 01:38:27 +01:00
jschoubben bfc877209f Distribution: each bus step of a publish bounded at 10 s and logged by name
Builds: design 47 G (publish path of oci-artifact-registry; no design line covers the bounds or log lines)
2026-11-15 01:30:05 +01:00
jschoubben 99f3e23492 Distribution: each wait of a publish logged with its time; the window's learning no longer holds the answer
Builds: design 47 G (publish path of oci-artifact-registry; no design line covers the log lines)
2026-11-15 01:20:04 +01:00
jschoubben e8204a9c27 Gate: the start pass asks again until no repository is left out (A-401)
The forge's git verbs may serve after the gate does; one pass with every head read refused wrote nothing and was never retried.

Builds: design 47 G A-401
2026-11-14 22:34:54 +01:00
jschoubben 89397466aa Gate: source-moved for started heads names no group; tests for the registration-changed branch and the start pass (A-401, A-404)
Builds: design 47 G A-401, A-404
2026-11-14 22:16:30 +01:00
jschoubben 28f616e379 Gate: a held source key gets the registered repositories it lacks, heads unchanged (A-403)
Builds: design 47 G A-403, A-401, A-34
2026-11-14 22:09:06 +01:00
jschoubben 8ea8ef9768 Gate: a watched branch starts from the forge, as a clone does; tool gate_source_start (A-401)
At its start and on each registration-changed of the seat mesh-catalog, the gate writes source.<branch> for every watched
branch the registrations name that no source key holds, each registered repository at its head from the seat git's verb
branch, group empty, then says source-moved; a repository whose head cannot be read is left out and said; a held key is
never rewritten. gate_source_start (branch, why) does it by hand through the hand-act log. The manifest consumes
registration-changed and invokes seat:git.branch and seat:mesh-catalog.registrations.

Builds: design 47 G A-401, §430, §15, A-34
2026-11-14 22:08:22 +01:00
jschoubben fb24d384a2 Build seat: says each toolchain-reported it said, not only the ones it could not 2026-11-14 19:00:01 +01:00
jschoubben 5236c2aa72 gitea: the seat git's branch with no branch named answers the repository's default branch (A-399)
The seed and a registration with no branches read the default branch through the seat git (design 47 G-1 §104) by
calling branch with an empty branch; gitea refused it as no branch for a path, and the seed stopped on novox 2026-11-14.
2026-11-14 14:57:27 +01:00
jschoubben 5df0fb64f5 mesh-build-go: a finding writer that cannot start is said, and the module serves on (A-394)
Live on shanks the bundle exited 39 times on 'an ordered consumer of mesh-conditions.findings-asked: context deadline exceeded', so the seat node-build-go never answered steps and the seed waited.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-14 11:52:23 +01:00
jschoubben ed536102ac A-376: the bus keeper makes the catalog half's own holder before the first views
Before the catalog half's first views are in (a read refused, or none-yet), the keeper reads the manifest on the trunk of the
holder of the seat mesh-catalog from the seat's states modules and manifests (the holder from the seat that places modules)
and makes its kept data as any module's, each entry said as ever; every other module waits as A-367 says.

Builds: design 47 G A-376 (G-22-lead-answers-2.md)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 23:11:57 +01:00
jschoubben a98b6ba77e S6: the bus keeper treats a none-yet catalog half as not yet viewed
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
PlanCatalog plans nothing, deletes no plans key and orphans no entry while the
catalog half lists no module before any was seen; the first revision with
entries plans as before.

Builds: design 47 G A-367 (G-22-lead-answers-2.md), W22/Q4 of start-waits.md

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 20:48:04 +01:00
mesh-tools b1125c02cf Merge pull request 'Bridge for G's take-in: an empty modules/mesh-build-go/buildstep package' (#678) from fix/47-G-bridge into main 2026-11-13 13:40:27 +00:00
jschoubben a4bc3d95ed Bridge for G's take-in: an empty modules/mesh-build-go/buildstep package
mesh/delivery merged: source.main moved to novox/mesh-catalog@b1125c02cfe6
mesh/delivery-group group fix/47-G-bridge merged: every member is merged
mesh/check checking a4bc3d95edef on b1125c02cfe6 | novox/mesh-catalog#678 in group fix/47-G-bridge
The running pre-G indexer publishes mesh-catalog's packages only while every package directory it published before is
in the tree; G removed this one, so mesh-catalog's packages are never published (2026-11-13). An empty package keeps
the directory; it goes once G's indexer runs.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 14:34:40 +01:00
mesh-tools 6ba73d4e2a Merge pull request 'Milestone 47 G: mesh-catalog's part of the one release' (#677) from feat/47-G-join12 into main 2026-11-13 13:08:20 +00:00
556 changed files with 17752 additions and 10704 deletions
+12
View File
@@ -77,6 +77,7 @@ func Check(root string) (map[string]map[string][]string, error) {
}
set := map[string]bool{}
setBy(manifest, set)
settingWords(manifest, set)
reads := map[string]map[string]bool{}
consts := map[string]map[string]string{} // directory -> constant -> word
var goFiles []string
@@ -180,6 +181,17 @@ func setBy(v any, set map[string]bool) {
}
}
// settingWords collects the words the node-engine composes for every setting the manifest's `config` declares,
// MESH_CONFIG_<KEY>, the key upper-cased with '-' and '.' as '_', into the module's processes and its tool runner slice
// alike (design 47 H2 §781; H-A-370, H-A-400 (2)).
func settingWords(v any, set map[string]bool) {
m, _ := v.(map[string]any)
config, _ := m["config"].(map[string]any)
for key := range config {
set["MESH_CONFIG_"+strings.NewReplacer("-", "_", ".", "_").Replace(strings.ToUpper(key))] = true
}
}
// Listed is the list's `<module> <WORD>` lines; a line starting with # and a blank line are not entries.
func Listed(path string) (map[string]bool, error) {
f, err := os.Open(path)
+13 -11
View File
@@ -32,13 +32,14 @@ func module(t *testing.T, root, name, manifest string, files map[string]string)
// not; tests, node_modules and dist are not read.
func TestAWordReadThatNothingSetsIsFound(t *testing.T) {
root := t.TempDir()
module(t, root, "reader", `{"module":"reader","build":{"artifacts":[{"name":"tools","env":{"MESH_SET":"x"}}]},`+
module(t, root, "reader", `{"module":"reader","config":{"ask-taken-bound":{"type":"string"}},"build":{"artifacts":[{"name":"tools","env":{"MESH_SET":"x"}}]},`+
`"resources":[{"id":"p","type":"process","environment":{"variables":{"MESH_VARIABLE":"y"}}}]}`, map[string]string{
"cmd/a/main.go": `package main; const reach = "MESH_REACH"; var _ = os.Getenv(reach); var _ = os.Getenv("MESH_SET")`,
"cmd/a/other.go": `package main; var _, _ = os.LookupEnv("MESH_LITERAL"); var _ = os.Getenv("MESH_MODULE")`,
"cmd/a/write.go": `package main; var _ = []string{"MESH_WRITTEN_FOR_A_CHILD=1"}`,
"cmd/a/a_test.go": `package main; var _ = os.Getenv("MESH_IN_A_TEST")`,
"client.ts": `const a = process.env.MESH_TS ?? "d"; const b = env["MESH_BRACKET"]; const c = env.MESH_VARIABLE;`,
"cmd/a/main.go": `package main; const reach = "MESH_REACH"; var _ = os.Getenv(reach); var _ = os.Getenv("MESH_SET")`,
"cmd/a/other.go": `package main; var _, _ = os.LookupEnv("MESH_LITERAL"); var _ = os.Getenv("MESH_MODULE")`,
"cmd/a/write.go": `package main; var _ = []string{"MESH_WRITTEN_FOR_A_CHILD=1"}`,
"cmd/a/a_test.go": `package main; var _ = os.Getenv("MESH_IN_A_TEST")`,
// 47 H2 §781, H-A-370: a declared setting's word, which the node-engine composes; one undeclared is set by nothing.
"client.ts": `const a = process.env.MESH_TS ?? "d"; const b = env["MESH_BRACKET"]; const c = env.MESH_VARIABLE; const d = env.MESH_CONFIG_ASK_TAKEN_BOUND; const e = env.MESH_CONFIG_UNDECLARED;`,
"files/env": "MESH_FROM_FILE=${config:x}\n",
"index.ts": `const f = env.MESH_FROM_FILE;`,
"test/x.test.ts": `env.MESH_IN_A_TEST_DIR`,
@@ -50,16 +51,17 @@ func TestAWordReadThatNothingSetsIsFound(t *testing.T) {
t.Fatal(err)
}
want := map[string]map[string][]string{"reader": {
"MESH_REACH": {"cmd/a/main.go"},
"MESH_LITERAL": {"cmd/a/other.go"},
"MESH_TS": {"client.ts"},
"MESH_BRACKET": {"client.ts"},
"MESH_REACH": {"cmd/a/main.go"},
"MESH_LITERAL": {"cmd/a/other.go"},
"MESH_TS": {"client.ts"},
"MESH_BRACKET": {"client.ts"},
"MESH_CONFIG_UNDECLARED": {"client.ts"},
}}
if !reflect.DeepEqual(got, want) {
t.Fatalf("found %v, want %v", got, want)
}
refused, stale := Judge(got, map[string]bool{"reader MESH_REACH": true, "reader MESH_GONE": true})
if !reflect.DeepEqual(refused, []string{"reader MESH_BRACKET", "reader MESH_LITERAL", "reader MESH_TS"}) ||
if !reflect.DeepEqual(refused, []string{"reader MESH_BRACKET", "reader MESH_CONFIG_UNDECLARED", "reader MESH_LITERAL", "reader MESH_TS"}) ||
!reflect.DeepEqual(stale, []string{"reader MESH_GONE"}) {
t.Errorf("refused %v, stale %v", refused, stale)
}
+20 -1
View File
@@ -5,7 +5,7 @@
// exempt from that, and said so. Every build module, test step or not, must also hold a test that calls
// conformance.LeftRunning with its own start sweep, so a step a previous process left running is ended at its start
// (issue 1890), and one that calls conformance.Passing, so a step whose network did not answer is said as a transport fault
// (issue 1748). Its manifest asks the capability seat-settle-delay (ADR 0664 §5).
// (issue 1748), and one that calls conformance.StepEnds, so its steps can say a pipeline step's end (design 47 G §24). Its manifest asks the capability seat-settle-delay (ADR 0664 §5).
package failurekit
import (
@@ -91,6 +91,25 @@ func Judge(root string) ([]Judged, error) {
refused = append(refused, fmt.Sprintf("it claims %s, and no test of it calls conformance.LeftRunning "+
"(mesh-build-go buildstep/conformance): run the kit's left-running case with the module's own start sweep (issue 1890)", seat))
}
// A-489b: every build module is asked pipeline steps, so every one runs the case that its steps can say a step's end: without a
// SayStep every step ask is refused live ("this build module says no step's end"), as mesh-build-node's was.
ends, err := runsTheKit(dir, "conformance.StepEnds(")
if err != nil {
return nil, err
}
counts, err := runsTheKit(dir, "conformance.RunsCounted(")
if err != nil {
return nil, err
}
if !counts {
// A-489c
refused = append(refused, fmt.Sprintf("it claims %s, and no test of it calls conformance.RunsCounted "+
"(mesh-delivery-sdk steprun/conformance): run the kit's case that its puller counts the runs that started, not the bus's deliveries (A-489a)", seat))
}
if !ends {
refused = append(refused, fmt.Sprintf("it claims %s, and no test of it calls conformance.StepEnds "+
"(mesh-delivery-sdk steprun/conformance): run the kit's step-ends case with the module's own steps (design 47 G §24)", seat))
}
// Every build module meets the network (a fetch, a download, an install, a publish), so every one runs the passing case: its
// steps say a network that did not answer as a transport fault the bus gives the ask again for (ADR 0664, issue 1748).
says, err := runsTheKit(dir, "conformance.Passing(")
+7 -3
View File
@@ -13,7 +13,7 @@ import (
func TestABuildModuleWithATestStepMustRunTheKit(t *testing.T) {
root := t.TempDir()
const imp = "package main\n\nimport \"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/steprun/conformance\"\n\n"
const sweep = "func TestSweep(t *testing.T) { conformance.LeftRunning(t, nil) }\nfunc TestPassing(t *testing.T) { conformance.Passing(t, nil, nil) }\n"
const sweep = "func TestSweep(t *testing.T) { conformance.LeftRunning(t, nil) }\nfunc TestPassing(t *testing.T) { conformance.Passing(t, nil, nil) }\nfunc TestEnds(t *testing.T) { conformance.StepEnds(t, steprun.AskSteps{}) }\nfunc TestCounted(t *testing.T) { conformance.RunsCounted(t, nil) }\n"
kit := imp + "func TestKit(t *testing.T) { conformance.Run(t, conformance.GoTest, nil) }\n" + sweep
for path, body := range map[string]string{
"modules/a/module.json": `{"claims":[{"name":"node-build-a"}],"tools":["build_a_fetch","build_a_test"]}`,
@@ -30,6 +30,10 @@ func TestABuildModuleWithATestStepMustRunTheKit(t *testing.T) {
"modules/h/cmd/h/kit_test.go": imp + "func TestSweep(t *testing.T) { conformance.LeftRunning(t, nil) }\n",
"modules/i/module.json": `{"claims":[{"name":"node-build-i"}],"capabilities":["other"],"tools":["build_i_build"]}`, // the whole kit, and no seat-settle-delay
"modules/i/cmd/i/kit_test.go": imp + sweep,
"modules/j/module.json": `{"claims":[{"name":"node-build-j"}],"capabilities":["seat-settle-delay"],"tools":["build_j_build"]}`, // the rest of the kit, and no step-ends case
"modules/j/cmd/j/kit_test.go": imp + "func TestSweep(t *testing.T) { conformance.LeftRunning(t, nil) }\nfunc TestPassing(t *testing.T) { conformance.Passing(t, nil, nil) }\nfunc TestCounted(t *testing.T) { conformance.RunsCounted(t, nil) }\n",
"modules/k/module.json": `{"claims":[{"name":"node-build-k"}],"capabilities":["seat-settle-delay"],"tools":["build_k_build"]}`, // no runs-counted case
"modules/k/cmd/k/kit_test.go": imp + "func TestSweep(t *testing.T) { conformance.LeftRunning(t, nil) }\nfunc TestPassing(t *testing.T) { conformance.Passing(t, nil, nil) }\nfunc TestEnds(t *testing.T) { conformance.StepEnds(t, steprun.AskSteps{}) }\n",
"modules/e/module.json": `{"claims":[{"name":"node-build-e"}],"tools":["build_e_test"]}`,
"modules/e/cmd/e/kit.go": kit, // not a test file
} {
@@ -45,9 +49,9 @@ func TestABuildModuleWithATestStepMustRunTheKit(t *testing.T) {
if err != nil {
t.Fatal(err)
}
want := map[string]string{"a": "refused", "b": "passes", "c": "exempt", "e": "refused", "f": "refused", "g": "refused", "h": "refused", "i": "refused"}
want := map[string]string{"a": "refused", "b": "passes", "c": "exempt", "e": "refused", "f": "refused", "g": "refused", "h": "refused", "i": "refused", "j": "refused", "k": "refused"}
if len(got) != len(want) {
t.Fatalf("judged %+v, want a, b, c, e, f, g, h and i", got)
t.Fatalf("judged %+v, want a, b, c, e, f, g, h, i, j and k", got)
}
for _, j := range got {
is := "passes"
+1
View File
@@ -1,6 +1,7 @@
{
"module": "adwaita",
"version": "0.1",
"class": "leaf",
"moved": true,
"capabilities": [
"package-manager"
+13
View File
@@ -119,3 +119,16 @@ removed for `retention` on its seat (`release`, `remove`). It reads a reference
and `<seat>/<module>/<artifact>@<digest>`, as one artifact, and says artifacts-gone in the form the build named it. A
call a seat refuses stops the sweep and writes the finding `sweep-refused` in the module's findings; the next sweep no
seat refuses clears it (`sweepseats.go`).
### One pending pass
A finished build or a changed want marks the one pending pass (design 47 H, H-A-250); a pass running when one is marked
runs once more when it ends, however many events marked it. The builder's builds are a followed view: the watch's first view
at start, then its updates, kept in memory (H-A-255), each build's end taken from the builder's log's build-ended entries the
pass reads once, and only for a build the log lacks from its key's history (H-A-258); a watch asked again after an error replaces the view whole with its handover (H-A-257). A pass reads nothing
of them on the bus, judges nothing before the first view is in, and sweeps and observes S25
from that one judgement. A list the registry
seats cannot answer ends the pass with the finding `artifact-list-unread`, written once; nothing asks the list again
until the next event, and a pass that reads it clears the finding. A pass that cannot judge the builds (the view not yet taken in, or a
done build's end unread) ends the same way with the finding `artifact-builds-unread` (H-A-260) (`holder.go`,
`sweepseats.go`).
@@ -116,12 +116,16 @@ func (runtimeBus) Publish(subject string, body any) error {
return stdio.SeatPublish(subject, body, "")
}
// follow watches the builder's done keys and the wants: a build's end sweeps and
// observes again; a want changed observes again. Event-driven: nothing reads them on a timer.
// follow watches the builder's done keys and the wants: the builds are a followed view, the watch's first view then its
// updates kept in memory (design 47 H, H-A-255); a build's end or a want changed marks the one pending pass (H-A-250 (1)),
// which sweeps and observes from the views. Event-driven: nothing reads them on a timer.
func follow(h *Holder, v *views.Reader) {
<-stdio.Served()
watch := func(state string, handle func(stdio.StateChange) error) {
for {
if state == BuildsRead {
h.Watching() // each handover, the first or one asked again, replaces the view whole (H-A-257)
}
if err := stdio.State(state).Watch("", handle); err == nil {
return
} else {
@@ -130,12 +134,8 @@ func follow(h *Holder, v *views.Reader) {
time.Sleep(10 * time.Second)
}
}
observe := func() {
if err := h.Observe(context.Background()); err != nil {
h.logf("image-missing could not be observed: %v", err)
}
}
watch(BuildsRead, func(c stdio.StateChange) error {
h.Heard(c)
if c.Current || c.Op != stdio.OpPut {
return nil
}
@@ -143,10 +143,12 @@ func follow(h *Holder, v *views.Reader) {
State string `json:"state"`
}
if json.Unmarshal(c.Value, &b) == nil && b.State == "done" {
go func() { h.AfterBuild(c.Key); observe() }()
h.Wanted("after the build " + c.Key)
}
return nil
})
// The watch hands every current value over before it returns: the first view is in.
h.TakenIn()
// The wants are the assigner's: the first view then its events (ADR 0615). What Watch hands over before it returns
// is the first view, not a change.
var current atomic.Bool
@@ -154,7 +156,7 @@ func follow(h *Holder, v *views.Reader) {
for {
err := v.Watch(WantsRead, func(string, []byte, bool) {
if !current.Load() {
go observe()
h.Wanted("a want changed")
}
})
if err == nil {
@@ -164,5 +166,5 @@ func follow(h *Holder, v *views.Reader) {
time.Sleep(10 * time.Second)
}
current.Store(false)
observe()
h.Wanted("the first view of the wants")
}
@@ -38,6 +38,10 @@ import (
"git.novox.be/novox/mesh-sdk/go/views"
)
// ErrBuildsUnread is a judgement refused because the builds cannot be judged: the followed view not yet taken in, or a
// done key's end unread (H-A-258, H-A-260).
var ErrBuildsUnread = errors.New("the builder's builds cannot be judged")
// What the holder reads and keeps.
const (
WantsRead = assignerModule + ".wants"
@@ -95,8 +99,19 @@ type Holder struct {
sweep sync.Mutex // one sweep at a time
mu sync.Mutex
fmu sync.Mutex // one pass of Observe at a time
ended map[string]time.Time // a done key's end, read once from its history
// pmu guards the pending pass (H-A-250 (1)): running while a pass runs, wanted when an event marked it since.
pmu sync.Mutex
running bool
wanted bool
wantedBy string
fmu sync.Mutex // one pass of Observe at a time
ended map[string]time.Time // a done key's end, read once from its history
// done is the followed view of the builder's builds (design 47 H, H-A-255): the done builds by key, taken in from the
// watch's first view and its updates (Heard); taken says the first view is in. A pass judges from it, reading nothing.
done map[string]Build
taken bool
// next is the handover a watch asked (again) is giving, which replaces done whole once it is in (H-A-257).
next map[string]Build
}
// Build is one done build of a module, as its key holds it, with when it ended.
@@ -108,39 +123,81 @@ type Build struct {
Manifest string
}
// Builds is every done build the builder's keys hold, each with its end.
// Builds is every done build of the followed view, by key, read from memory, never from the bus (design 47 H, H-A-250
// (2), H-A-255): each with the end known for it, zero where none is known yet (withEnds gives it). Before the view's first
// view is taken in there is none to judge from, and it says so, so no pass sweeps against an empty keep set.
func (h *Holder) Builds() ([]Build, error) {
keys, err := h.Bus.Keys(BuildsRead)
if err != nil {
return nil, fmt.Errorf("the builder's builds: %w", err)
h.mu.Lock()
defer h.mu.Unlock()
if !h.taken {
return nil, fmt.Errorf("%w: they are not taken in yet, their first view has not come", ErrBuildsUnread)
}
var out []Build
for _, k := range keys {
module, fp, err := builds.ParseBuilderBuildKey(k)
if err != nil {
continue
}
raw, found, err := h.Bus.Get(BuildsRead, k)
if err != nil {
return nil, fmt.Errorf("the builder's build %s: %w", k, err)
}
if !found {
continue
}
b, err := builds.DecodeBuilderBuild(raw)
if err != nil || b.State != builds.BuildDone {
continue
}
at, err := h.endOf(k)
if err != nil {
return nil, err
}
out = append(out, Build{Module: module, FP: fp, Key: k, At: at, Artifacts: b.Artifacts, Manifest: b.Manifest})
out := make([]Build, 0, len(h.done))
for _, b := range h.done {
b.At = h.ended[b.Key]
out = append(out, b)
}
sort.Slice(out, func(a, b int) bool { return out[a].Key < out[b].Key })
return out, nil
}
// endOf is when a done key was last written done, read once from its history: a done key is not written again.
// Heard takes one change of the builder's builds into the followed view: a done value is kept, anything else drops the
// key. Its end is not read here: withEnds takes it from the builder's log at the next pass (H-A-258); a key written done
// anew forgets the end it had. While a watch's handover is gathered (Watching), every change goes into it, current or
// not, so nothing heard before TakenIn is lost by the swap (H-A-257).
func (h *Holder) Heard(c stdio.StateChange) {
module, fp, err := builds.ParseBuilderBuildKey(c.Key)
if err != nil {
return
}
var b builds.BuilderBuild
if c.Op == stdio.OpPut {
b, err = builds.DecodeBuilderBuild(c.Value)
}
h.mu.Lock()
defer h.mu.Unlock()
if !c.Current {
delete(h.ended, c.Key) // written anew or gone: an end it had is no longer its
}
if h.next == nil && h.done == nil {
h.done = map[string]Build{}
}
into := h.done
if h.next != nil {
into = h.next
}
if c.Op != stdio.OpPut || err != nil || b.State != builds.BuildDone {
delete(into, c.Key)
return
}
into[c.Key] = Build{Module: module, FP: fp, Key: c.Key, Artifacts: b.Artifacts, Manifest: b.Manifest}
}
// Watching says a watch of the builds is asked, first or again after an error: its handover of current values is
// gathered apart and replaces the view whole at TakenIn, so a key deleted while no watch ran leaves it (H-A-257).
func (h *Holder) Watching() {
h.mu.Lock()
h.next = map[string]Build{}
h.mu.Unlock()
}
// TakenIn says the watch's handover is in: every current value was Heard. It replaces the view whole, and forgets the
// end of every key it no longer holds.
func (h *Holder) TakenIn() {
h.mu.Lock()
defer h.mu.Unlock()
if h.next != nil {
h.done, h.next = h.next, nil
for k := range h.ended {
if _, kept := h.done[k]; !kept {
delete(h.ended, k)
}
}
}
h.taken = true
}
// endOf is when a done key was last written done, read from its history and kept: for a build the builder's log lacks.
func (h *Holder) endOf(key string) (time.Time, error) {
h.mu.Lock()
at, known := h.ended[key]
@@ -320,6 +377,8 @@ type judged struct {
mirrors map[string]*Ref
// mirrorsHeld says why no copy is eligible now, when one is not: a kept build whose bases the log does not name.
mirrorsHeld string
// unread is why the registry seats' list could not be read, nil when it was (or none is read).
unread error
}
func (h *Holder) judge(ctx context.Context) (*judged, error) {
@@ -327,6 +386,15 @@ func (h *Holder) judge(ctx context.Context) (*judged, error) {
if err != nil {
return nil, err
}
// The builder's log, read once: what each build stood on, and each build's end (H-A-258).
against, ends, logErr := h.logged()
if logErr != nil {
h.logf("the builder's log could not be read, so every copy is kept as unrecorded and each end is read from its history: %v", logErr)
against, ends = nil, nil
}
if builds, err = h.withEnds(builds, ends); err != nil {
return nil, err
}
wants, err := h.Wants()
if err != nil {
return nil, err
@@ -335,15 +403,10 @@ func (h *Holder) judge(ctx context.Context) (*judged, error) {
if h.Listed != nil {
if j.view, err = h.Listed(ctx); err != nil {
h.logf("the store's listing could not be read, so nothing is said gone: %v", err)
j.view = nil
j.view, j.unread = nil, err
}
}
if j.view != nil {
against, err := h.against()
if err != nil {
h.logf("the builder's log could not be read, so every copy is kept as unrecorded: %v", err)
against = nil
}
j.mirrors, j.mirrorsHeld = Mirrors(j.view, builds, keptBuilds(builds, wants), against)
for r, m := range j.mirrors {
if len(m.Builds) > 0 {
@@ -354,13 +417,47 @@ func (h *Holder) judge(ctx context.Context) (*judged, error) {
return j, nil
}
// against is what each build the builder's log says ended stood on, by build key: the bases' references.
func (h *Holder) against() (map[string][]string, error) {
// withEnds gives each build its end: the one known, else the builder's log's build-ended entry, else its key's history,
// each kept once read (H-A-258). A done key whose end can be read from neither stays unread, and then nothing is judged:
// never from a view missing a build.
func (h *Holder) withEnds(built []Build, ends map[string]time.Time) ([]Build, error) {
var unread []string
var why error
for i := range built {
if !built[i].At.IsZero() {
continue
}
if at, logged := ends[built[i].Key]; logged {
h.mu.Lock()
if h.ended == nil {
h.ended = map[string]time.Time{}
}
h.ended[built[i].Key] = at
h.mu.Unlock()
built[i].At = at
continue
}
at, err := h.endOf(built[i].Key)
if err != nil {
unread, why = append(unread, built[i].Key), err
continue
}
built[i].At = at
}
if len(unread) > 0 {
return nil, fmt.Errorf("%w: the end of %d done builds could not be read (%s first), so nothing is judged: %v", ErrBuildsUnread, len(unread), unread[0], why)
}
return built, nil
}
// logged is what each build the builder's log says ended stood on, by build key (the bases' references), and when it
// ended: one read of the log.
func (h *Holder) logged() (map[string][]string, map[string]time.Time, error) {
entries, err := h.Bus.LogSince(builds.BuildLogRead, h.now().Add(-builds.BuilderLogDays*24*time.Hour))
if err != nil {
return nil, err
return nil, nil, err
}
out := map[string][]string{}
out, ends := map[string][]string{}, map[string]time.Time{}
for _, raw := range entries {
e, err := builds.DecodeBuildLogEntry(raw.Value)
if err != nil || e.Event != builds.BuildEndedEvent {
@@ -371,8 +468,11 @@ func (h *Holder) against() (map[string][]string, error) {
continue
}
out[key] = e.Against
if e.At.After(ends[key]) {
ends[key] = e.At
}
}
return out, nil
return out, ends, nil
}
// Mirrors judges each copy in the store's mirror repositories (upstream/<host>/<path>, <module>/on-<argument>; ADR
@@ -514,6 +614,11 @@ func (h *Holder) Sweep(ctx context.Context, s Sweeping) (*CollectAnswer, error)
if err != nil {
return nil, err
}
return h.sweepFrom(ctx, j, s)
}
// sweepFrom is a sweep from a judgement already read; the caller holds h.sweep.
func (h *Holder) sweepFrom(ctx context.Context, j *judged, s Sweeping) (*CollectAnswer, error) {
a := &CollectAnswer{DryRun: s.DryRun, WouldLetGo: []string{}, LetGo: []string{}}
var keptArchives, eligible []string
for _, r := range j.sorted() {
@@ -658,15 +763,73 @@ func namedBy(b Build, r string) string {
return r
}
// AfterBuild is the sweep at a build's end.
func (h *Holder) AfterBuild(key string) {
a, err := h.Sweep(context.Background(), Sweeping{Most: MostPerSweep, By: "after the build " + key})
// Wanted marks the pass wanted (design 47 H, H-A-250 (1)): a finished build or a want change asks it, by naming what
// asked. With no pass running one starts; a pass running when it is marked runs once more when it ends, however many
// events marked it, never once per event.
func (h *Holder) Wanted(by string) {
if h.mark(by) {
go h.passes(by)
}
}
// mark sets the pending mark, and says whether no pass ran, so the caller starts one.
func (h *Holder) mark(by string) bool {
h.pmu.Lock()
defer h.pmu.Unlock()
if h.running {
h.wanted, h.wantedBy = true, by
return false
}
h.running = true
return true
}
// passes runs the pass, then once more for as long as an event marked it during the one that ran.
func (h *Holder) passes(by string) {
for {
h.Pass(context.Background(), by)
h.pmu.Lock()
if !h.wanted {
h.running = false
h.pmu.Unlock()
return
}
h.wanted, by = false, h.wantedBy
h.pmu.Unlock()
}
}
// Pass is one pass of the seat: the keep set judged from one read of the builds, the wants and the store's list, then
// the sweep and S25's observation from that one judgement. A list the registry seats cannot answer ends the pass with
// the finding artifact-list-unread, asked again only at the next event (H-A-250 (3)); a list read again clears it.
func (h *Holder) Pass(ctx context.Context, by string) {
h.sweep.Lock()
j, err := h.judge(ctx)
if err != nil {
h.logf("the sweep after %s: %v", key, err)
h.sweep.Unlock()
h.logf("the pass %s: %v", by, err)
if errors.Is(err, ErrBuildsUnread) {
h.unreadFinding(BuildsUnread, err) // H-A-260
}
return
}
if len(a.LetGo) > 0 || a.Stopped != "" || a.Missing > 0 {
h.logf("the sweep after %s let go of %d (%d left, %d missing): %s", key, len(a.LetGo), a.Left, a.Missing, a.Stopped)
h.readAgain(BuildsUnread)
if j.unread != nil {
h.sweep.Unlock()
h.unreadFinding(ListUnread, j.unread)
return
}
h.readAgain(ListUnread)
a, err := h.sweepFrom(ctx, j, Sweeping{Most: MostPerSweep, By: by})
h.sweep.Unlock()
switch {
case err != nil:
h.logf("the sweep %s: %v", by, err)
case len(a.LetGo) > 0 || a.Stopped != "" || a.Missing > 0:
h.logf("the sweep %s let go of %d (%d left, %d missing): %s", by, len(a.LetGo), a.Left, a.Missing, a.Stopped)
}
if err := h.observeFrom(ctx, j); err != nil {
h.logf("image-missing could not be observed: %v", err)
}
}
@@ -857,10 +1020,16 @@ func inStoreAt(image, address string) string {
// want's machine, written once and cleared once it no longer holds. Nothing is said without a listing. What stands is what
// the held writer holds (design 47 G A-32, A-38), so a restart neither drops nor rewrites it.
func (h *Holder) Observe(ctx context.Context) error {
now, err := h.observed(ctx)
j, err := h.judge(ctx)
if err != nil {
return err
}
return h.observeFrom(ctx, j)
}
// observeFrom is Observe from a judgement already read.
func (h *Holder) observeFrom(ctx context.Context, j *judged) error {
now := h.observed(j)
if now == nil {
return nil
}
@@ -899,13 +1068,9 @@ type Findings interface {
}
// observed is S25's findings now by key, nil without a listing.
func (h *Holder) observed(ctx context.Context) (map[string]meshconditions.Finding, error) {
j, err := h.judge(ctx)
if err != nil {
return nil, err
}
func (h *Holder) observed(j *judged) map[string]meshconditions.Finding {
if j.view == nil {
return nil, nil
return nil
}
address := ""
if d, err := h.Door(); err == nil {
@@ -944,7 +1109,7 @@ func (h *Holder) observed(ctx context.Context) (map[string]meshconditions.Findin
break
}
}
return now, nil
return now
}
// imageMissing is S25's finding, in the controller's words (cmd/mesh-controller/image_missing.go watchMissingImages); its id
@@ -11,6 +11,7 @@ package main
import (
"context"
"encoding/json"
"fmt"
"strings"
"sync"
"testing"
@@ -200,6 +201,15 @@ func TestTheSeatSweepsAtABuildsEndOnARealBusWithNoLease(t *testing.T) {
}
h := &Holder{Bus: findingsAt{realBus: bus}, Findings: findingsThrough{findingsAt{realBus: bus}}, Door: mem.Door, Listed: mem.Listed, Seats: ask, Now: time.Now, Logf: t.Logf}
h.Acts = meshhandactsclient.Recorder{Ask: ask}
// The followed view of the builds: the six on the bus handed over as the watch's first view does.
h.Watching()
if keys, err := bus.Keys(BuildsRead); err == nil {
for _, k := range keys {
raw, _, _ := bus.Get(BuildsRead, k)
h.Heard(stdio.StateChange{State: BuildsRead, Key: k, Op: stdio.OpPut, Value: raw, Current: true})
}
}
h.TakenIn()
// A build's end heard from the builds bucket, as follow hands it over.
kv, _ := bus.kv(BuildsRead)
@@ -215,7 +225,8 @@ func TestTheSeatSweepsAtABuildsEndOnARealBusWithNoLease(t *testing.T) {
}
select {
case e := <-w.Updates():
h.AfterBuild(e.Key())
h.Heard(stdio.StateChange{State: BuildsRead, Key: e.Key(), Op: stdio.OpPut, Value: e.Value()})
h.Pass(ctx, "after the build "+e.Key())
case <-ctx.Done():
t.Fatal("the build's end was not heard")
}
@@ -234,26 +245,82 @@ func TestTheSeatSweepsAtABuildsEndOnARealBusWithNoLease(t *testing.T) {
}
time.Sleep(20 * time.Millisecond)
}
mu.Lock()
defer mu.Unlock()
if len(acts) != 3 || !strings.Contains(acts[0], archiveRef("letta", 2)) || !strings.Contains(acts[1], imageRef("letta", 2)) ||
!strings.Contains(acts[2], mirror(1)) {
t.Fatalf("the hand acts recorded are %v; the store was asked %v", acts, door.asked)
}
if len(gone) != 1 || !strings.Contains(gone[0], `"fingerprint":"`+fp(2)+`"`) {
t.Fatalf("artifacts-gone said %v", gone)
}
func() {
mu.Lock()
defer mu.Unlock()
if len(acts) != 3 || !strings.Contains(acts[0], archiveRef("letta", 2)) || !strings.Contains(acts[1], imageRef("letta", 2)) ||
!strings.Contains(acts[2], mirror(1)) {
t.Fatalf("the hand acts recorded are %v; the store was asked %v", acts, door.asked)
}
if len(gone) != 1 || !strings.Contains(gone[0], `"fingerprint":"`+fp(2)+`"`) {
t.Fatalf("artifacts-gone said %v", gone)
}
// S25 through the real findings bucket: letta's wanted image missing from the store is a finding there.
view, _ := mem.Listed(ctx)
repo, digest, _ := splitReference(imageRef("letta", 1))
delete(view.L.Repos[repo].Revisions, digest)
if err := h.Observe(ctx); err != nil {
t.Fatal(err)
}
if keys, _ := bus.Keys("artifact-store-tools." + FindingsState); len(keys) != 1 || keys[0] != "module.letta.ace.image-missing" {
t.Fatalf("the findings are %v", keys)
}
// S25 through the real findings bucket: letta's wanted image missing from the store is a finding there.
view, _ := mem.Listed(ctx)
repo, digest, _ := splitReference(imageRef("letta", 1))
delete(view.L.Repos[repo].Revisions, digest)
if err := h.Observe(ctx); err != nil {
t.Fatal(err)
}
if keys, _ := bus.Keys("artifact-store-tools." + FindingsState); len(keys) != 1 || keys[0] != "module.letta.ace.image-missing" {
t.Fatalf("the findings are %v", keys)
}
}()
// Design 47 H2 §813 (7): a pass reads oci-artifact-registry's list page by page, each at most 768 KB, over 20,000
// artifacts, so its view holds every one.
t.Run("a pass reads 20,000 artifacts page by page", func(t *testing.T) {
const many, pageBytes = 20000, 768 << 10
repos := make([]map[string]any, many)
for i := range repos {
repos[i] = map[string]any{"name": fmt.Sprintf("m%05d/bundle", i), "manifests": []map[string]any{{
"digest": fmt.Sprintf("sha256:%064x", i), "artifact": fmt.Sprintf("sha256:%064x", many+i), "size": 100}}}
}
pages := 0
sub, err := nc.Subscribe("mesh.seat.oci-artifact-registry.tool.list.paged", func(m *nats.Msg) {
var in struct{ Next string }
_ = json.Unmarshal(m.Data, &in)
page, size, next := []map[string]any{}, 0, ""
for _, r := range repos {
if r["name"].(string) <= in.Next {
continue
}
raw, _ := json.Marshal(r)
if size+len(raw)+1 > pageBytes-1024 { // its comma, and room for the answer's other fields
next = page[len(page)-1]["name"].(string)
break
}
size += len(raw) + 1
page = append(page, r)
}
pages++
out, _ := json.Marshal(map[string]any{"repositories": page, "next": next, "capped": next != "", "total": many})
_ = m.Respond(out)
})
if err != nil {
t.Fatal(err)
}
defer func() { _ = sub.Unsubscribe() }()
store := &Store{Ask: func(key string, body any) (json.RawMessage, error) {
if key != "seat:oci-artifact-registry.list" {
return ask(key, body)
}
raw, _ := json.Marshal(body)
m, err := nc.Request("mesh.seat.oci-artifact-registry.tool.list.paged", raw, 5*time.Second)
if err != nil {
return nil, err
}
if len(m.Data) > pageBytes {
t.Errorf("a page of %d bytes", len(m.Data))
}
return m.Data, nil
}}
got, err := store.ListOf("oci-artifact-registry", "")
if err != nil || len(got) != many || got[many-1].Name != "m19999/bundle" || pages < 2 {
t.Fatalf("read %d repositories in %d pages: %v", len(got), pages, err)
}
})
}
// findingsAt reads and writes the holder's own findings in its bucket, artifact-store-tools_findings.
@@ -34,6 +34,17 @@ type memBus struct {
history map[string][]stdio.StateRevision
log []stdio.LogEntry
published []string
// historyErr fails the history read of a key.
historyErr map[string]error
// calls counts each read by "<verb> <state>": a pass reads nothing of the builds, judged from the followed view.
calls map[string]int
}
func (b *memBus) count(verb, state string) {
if b.calls == nil {
b.calls = map[string]int{}
}
b.calls[verb+" "+state]++
}
func (b *memBus) LogSince(read string, at time.Time) ([]stdio.LogEntry, error) {
@@ -49,6 +60,7 @@ func (b *memBus) LogSince(read string, at time.Time) ([]stdio.LogEntry, error) {
func (b *memBus) Keys(state string) ([]string, error) {
b.mu.Lock()
defer b.mu.Unlock()
b.count("keys", state)
var out []string
for k := range b.states[state] {
out = append(out, k)
@@ -60,11 +72,18 @@ func (b *memBus) Keys(state string) ([]string, error) {
func (b *memBus) Get(state, key string) ([]byte, bool, error) {
b.mu.Lock()
defer b.mu.Unlock()
b.count("get", state)
v, ok := b.states[state][key]
return v, ok, nil
}
func (b *memBus) History(state, key string) ([]stdio.StateRevision, error) {
b.mu.Lock()
defer b.mu.Unlock()
b.count("history", state)
if err := b.historyErr[key]; err != nil {
return nil, err
}
return b.history[state+" "+key], nil
}
@@ -229,7 +248,7 @@ func aMesh(t *testing.T) (*Holder, *memBus, *memDoor, *[]string) {
want, _ := json.Marshal(meshwants.WantsByWantNodeModuleValue{V: 1, Fp: fp(1), Self: true})
_ = b.Put(WantsRead, "want.ace.letta", json.RawMessage(want))
var acts []string
h := &Holder{Bus: b, Findings: findingsThrough{b}, Door: func() (Door, error) { return door, nil }, Seats: door.seat,
h := &Holder{Logf: t.Logf, Bus: b, Findings: findingsThrough{b}, Door: func() (Door, error) { return door, nil }, Seats: door.seat,
Listed: func(context.Context) (*View, error) { return &View{L: listing}, nil },
Now: func() time.Time { return day.Add(48 * time.Hour) },
Acts: meshhandactsclient.Recorder{Ask: func(key string, body any) (json.RawMessage, error) {
@@ -237,9 +256,49 @@ func aMesh(t *testing.T) (*Holder, *memBus, *memDoor, *[]string) {
acts = append(acts, key+" "+string(raw))
return json.RawMessage(`{}`), nil
}}}
takeIn(h, b)
return h, b, door, &acts
}
// takeIn hands the builds over as the watch's first view does, then forgets the reads that took: a pass's are counted.
func takeIn(h *Holder, b *memBus) {
handOver(h, b)
h.TakenIn()
b.calls = nil
}
// handOver is a watch's handover of every current value, not yet taken in.
func handOver(h *Holder, b *memBus) {
h.Watching()
keys, _ := b.Keys(BuildsRead)
for _, k := range keys {
raw, _, _ := b.Get(BuildsRead, k)
h.Heard(stdio.StateChange{State: BuildsRead, Key: k, Op: stdio.OpPut, Value: raw, Current: true})
}
}
// keyOf is letta's n-th build's key.
func keyOf(n int) string { k, _ := builds.BuilderBuildKey("letta", fp(n)); return k }
// viewKeys are the keys the followed view holds.
func viewKeys(t *testing.T, h *Holder) []string {
t.Helper()
h.mu.Lock()
defer h.mu.Unlock()
var out []string
for k := range h.done {
out = append(out, k)
}
sort.Strings(out)
return out
}
// putBuild writes a build's key and hands it over as the watch's update does.
func putBuild(h *Holder, b *memBus, key string, raw []byte) {
_ = b.Put(BuildsRead, key, json.RawMessage(raw))
h.Heard(stdio.StateChange{State: BuildsRead, Key: key, Op: stdio.OpPut, Value: raw})
}
// ADR 0571 clause 2, 1126/A4/AC2: the keep set from the store's listing, the wants and the five newest builds; with no
// lease key, a build's end and a confirmed collect let go of the eligible within the bound, leave an index for a
// confirmed collect, record each deletion as a hand act and say artifacts-gone.
@@ -312,7 +371,7 @@ func TestTheSeatKeepsTheFiveNewestAndTheWantedAndSweepsWithNoLease(t *testing.T)
raw, _ := builds.EncodeBuilderBuild(builds.BuilderBuild{State: builds.BuildDone, Manifest: strings.Repeat("d", 64), Artifacts: []builds.BuiltArtifact{
{Name: "image", Kind: "image", Digest: digestOf(imageRef("letta", n)), Reference: artifactref.SeatReference(reg.Seat, "letta", "image", digestOf(imageRef("letta", n)))},
{Name: "files", Kind: "archive", Digest: digestOf(archiveRef("letta", n)), Reference: artifactref.SeatReference(ociseat.Seat, "letta", "files", digestOf(archiveRef("letta", n)))}}})
_ = b.Put(BuildsRead, key, json.RawMessage(raw))
putBuild(h, b, key, raw)
}
}
if c.refuse != "" {
@@ -323,7 +382,7 @@ func TestTheSeatKeepsTheFiveNewestAndTheWantedAndSweepsWithNoLease(t *testing.T)
}
switch c.how {
case "build":
h.AfterBuild("letta.x")
h.Pass(context.Background(), "after the build letta.x")
var gone []string
for _, x := range door.asked {
if r, ok := strings.CutPrefix(x, "let go "); ok {
@@ -420,6 +479,7 @@ func TestAWantedImageTheStoreLacksIsAFindingAndImagesNamesWantsAndHaves(t *testi
view.L.Repos[repo].Revisions[digest] = true
// A restart: a holder made afresh holds no finding of its own, and clears what the writer holds (design 47 G A-32, A-38).
h = &Holder{Bus: h.Bus, Findings: h.Findings, Door: h.Door, Listed: h.Listed, Seats: h.Seats, Now: h.Now, Acts: h.Acts, Logf: h.Logf}
takeIn(h, b)
if err := h.Observe(context.Background()); err != nil {
t.Fatal(err)
}
@@ -482,3 +542,154 @@ func (f findingsThrough) Held() []meshconditions.Finding {
func (f findingsThrough) Clear(_ context.Context, scope, id, kind, _ string) error {
return f.bus.Delete(FindingsState, views.FindingKey(scope, id, kind))
}
// writesCounted counts the findings written through the test's writer.
type writesCounted struct {
findingsThrough
writes *int
}
func (w writesCounted) Write(ctx context.Context, f meshconditions.Finding) error {
*w.writes++
return w.findingsThrough.Write(ctx, f)
}
// Design 47 H, H-A-250: the starts fold into one pending pass, a pass reads the builds in one page, and a list the
// registry seats cannot answer ends the pass with artifact-list-unread, written once and asked again only at an event.
func TestOnePendingPassReadsTheBuildsOnceAndEndsOnAnUnreadList(t *testing.T) {
t.Run("three events during a pass run exactly one more", func(t *testing.T) {
h, _, _, _ := aMesh(t)
listed, inner := 0, h.Listed
h.Listed = func(ctx context.Context) (*View, error) {
listed++
if listed == 1 {
for _, by := range []string{"after the build a", "after the build b", "a want changed"} {
h.Wanted(by) // a pass runs: each only marks it
}
}
return inner(ctx)
}
if !h.mark("after the build letta.x") {
t.Fatal("no pass ran, and the mark did not start one")
}
h.passes("after the build letta.x")
if listed != 2 {
t.Fatalf("three events during a pass ran %d passes, want 2", listed)
}
if h.running || h.wanted {
t.Fatalf("after the passes running is %v and wanted %v", h.running, h.wanted)
}
})
t.Run("a pass reads nothing of the builds and their ends come from the log", func(t *testing.T) {
h, b, door, _ := aMesh(t)
handOver(h, b) // a fresh take-in, counted: no history read for a build the log holds (H-A-258)
h.TakenIn()
h.Pass(context.Background(), "after the build letta.x")
if n := b.calls["keys "+BuildsRead] - 1 + b.calls["get "+BuildsRead] - 7 + b.calls["history "+BuildsRead]; n != 0 {
t.Fatalf("a take-in and a pass read the builds by %v", b.calls)
}
if !slices.Contains(door.asked, "let go "+imageRef("letta", 2)) {
t.Fatalf("the pass swept nothing: %v", door.asked)
}
// Only a build the log lacks is read from its history, once.
h, b, _, _ = aMesh(t)
b.log = append(b.log[:2:2], b.log[3:]...) // letta's 3rd
h.Pass(context.Background(), "a")
h.Pass(context.Background(), "b")
if b.calls["history "+BuildsRead] != 1 {
t.Fatalf("two passes read the builds' history %d times, want once for the build the log lacks", b.calls["history "+BuildsRead])
}
})
t.Run("no pass judges before the first view, and says so", func(t *testing.T) {
h, b, door, _ := aMesh(t)
h.taken = false
h.Pass(context.Background(), "after the build letta.x")
_, found, _ := b.Get(FindingsState, views.FindingKey("module", Module, BuildsUnread))
if len(door.asked) != 0 || !found {
t.Fatalf("a pass before the builds were taken in asked %v; artifact-builds-unread is written: %v", door.asked, found)
}
})
t.Run("an unread end holds every pass until it is read", func(t *testing.T) {
h, b, door, _ := aMesh(t)
writes := 0
h.Findings = writesCounted{findingsThrough{b}, &writes}
b.log = append(b.log[:2:2], b.log[3:]...) // letta's 3rd: the log lacks it, and its history fails
b.historyErr = map[string]error{keyOf(3): errors.New("no responders")}
h.Pass(context.Background(), "a")
h.Pass(context.Background(), "b")
key := views.FindingKey("module", Module, BuildsUnread)
if _, found, _ := b.Get(FindingsState, key); !found || writes != 1 || len(door.asked) != 0 {
t.Fatalf("with an end unread the passes asked %v; the finding is written %v, %d times", door.asked, found, writes)
}
b.historyErr = nil
h.Pass(context.Background(), "c")
if _, found, _ := b.Get(FindingsState, key); found || !slices.Contains(door.asked, "let go "+imageRef("letta", 2)) {
t.Fatalf("once the end was read the pass asked %v and left the finding: %v", door.asked, found)
}
})
t.Run("a change heard during the handover is in the view it gives", func(t *testing.T) {
h, b, _, _ := aMesh(t)
handOver(h, b)
raw, _, _ := b.Get(BuildsRead, keyOf(1))
h.Heard(stdio.StateChange{State: BuildsRead, Key: keyOf(8), Op: stdio.OpPut, Value: raw}) // after the handover, before TakenIn
h.Heard(stdio.StateChange{State: BuildsRead, Key: keyOf(3), Op: stdio.OpDelete})
h.TakenIn()
got := viewKeys(t, h)
if !slices.Contains(got, keyOf(8)) || slices.Contains(got, keyOf(3)) {
t.Fatalf("the view after the handover holds %v", got)
}
})
t.Run("a key deleted or no longer done leaves the view; one written done again takes its new end", func(t *testing.T) {
h, b, _, _ := aMesh(t)
h.Pass(context.Background(), "a") // every end known
building, _ := builds.EncodeBuilderBuild(builds.BuilderBuild{State: "building"})
h.Heard(stdio.StateChange{State: BuildsRead, Key: keyOf(3), Op: stdio.OpDelete})
h.Heard(stdio.StateChange{State: BuildsRead, Key: keyOf(4), Op: stdio.OpPut, Value: building})
if got := viewKeys(t, h); slices.Contains(got, keyOf(3)) || slices.Contains(got, keyOf(4)) {
t.Fatalf("the view holds %v", got)
}
later := b.log[len(b.log)-1].At.Add(time.Hour)
e := builds.BuildLogEntry{Event: builds.BuildEndedEvent, Module: "letta", FP: fp(5), Repository: "novox/x", Commit: "c", Node: "ace", At: later, Outcome: "done"}
entry, _ := builds.EncodeBuildLogEntry(e)
b.log = append(b.log, stdio.LogEntry{Sequence: 99, Key: "letta", Value: entry, At: later})
raw, _, _ := b.Get(BuildsRead, keyOf(5))
h.Heard(stdio.StateChange{State: BuildsRead, Key: keyOf(5), Op: stdio.OpPut, Value: raw})
h.Pass(context.Background(), "b")
if got, _ := h.Builds(); !slices.ContainsFunc(got, func(x Build) bool { return x.Key == keyOf(5) && x.At.Equal(later) }) {
t.Fatalf("letta's 5th written done again does not end at %v: %+v", later, got)
}
})
t.Run("a watch asked again replaces the view whole", func(t *testing.T) {
h, b, _, _ := aMesh(t)
gone, _ := builds.BuilderBuildKey("letta", fp(3))
_ = b.Delete(BuildsRead, gone) // deleted while no watch ran: no change of it is heard
takeIn(h, b)
got, err := h.Builds()
if err != nil || len(got) != 6 || slices.ContainsFunc(got, func(x Build) bool { return x.Key == gone }) {
t.Fatalf("after the watch was asked again the view holds %d builds (%v), %s among them", len(got), err, gone)
}
})
t.Run("a list unread ends the pass with its finding once", func(t *testing.T) {
h, b, door, _ := aMesh(t)
writes, listed, inner := 0, 0, h.Listed
h.Findings = writesCounted{findingsThrough{b}, &writes}
h.Listed = func(context.Context) (*View, error) {
listed++
return nil, errors.New("the answer exceeds the bus's one megabyte")
}
h.Pass(context.Background(), "after the build a")
h.Pass(context.Background(), "a want changed")
key := views.FindingKey("module", Module, ListUnread)
if raw, found, _ := b.Get(FindingsState, key); !found || writes != 1 || !strings.Contains(string(raw), "one megabyte") {
t.Fatalf("the finding is %s (found %v), written %d times", raw, found, writes)
}
if listed != 2 || len(door.asked) != 0 || len(b.published) != 0 {
t.Fatalf("two passes listed %d times, asked %v and said %v", listed, door.asked, b.published)
}
h.Listed = inner
h.Pass(context.Background(), "after the build b")
if _, found, _ := b.Get(FindingsState, key); found || len(door.asked) == 0 {
t.Fatalf("a pass that read the list left the finding (%v) or swept nothing (%v)", found, door.asked)
}
})
}
@@ -79,20 +79,46 @@ type Store struct {
Ask func(key string, body any) (json.RawMessage, error)
}
// ListOf asks seat's list, of one repository or, with name empty, of every one.
// ListOf asks seat's list, of one repository or, with name empty, of every one. oci-artifact-registry's list is read page by
// page from its cursor until it answers none (design 47 H2 §813 (7), §779); container-image-registry's answers whole.
func (s *Store) ListOf(seat, name string) ([]reg.Repository, error) {
if s == nil || s.Ask == nil {
return nil, fmt.Errorf("this process reaches no registry seat")
}
raw, err := s.Ask("seat:"+seat+"."+reg.VerbList, reg.ListInput{Name: name})
if err != nil {
return nil, fmt.Errorf("%s's list: %w", seat, err)
if seat != ociseat.Seat {
raw, err := s.Ask("seat:"+seat+"."+reg.VerbList, reg.ListInput{Name: name})
if err != nil {
return nil, fmt.Errorf("%s's list: %w", seat, err)
}
var a reg.ListAnswer
if err := json.Unmarshal(raw, &a); err != nil {
return nil, fmt.Errorf("%s's answer to list: %w", seat, err)
}
return a.Repositories, nil
}
var a reg.ListAnswer
if err := json.Unmarshal(raw, &a); err != nil {
return nil, fmt.Errorf("%s's answer to list: %w", seat, err)
var out []reg.Repository
seen := map[string]bool{}
for in := (ociseat.ListInput{Name: name}); ; {
raw, err := s.Ask("seat:"+seat+"."+reg.VerbList, in)
if err != nil {
return nil, fmt.Errorf("%s's list: %w", seat, err)
}
var a struct {
Repositories []reg.Repository `json:"repositories"`
Next string `json:"next"`
}
if err := json.Unmarshal(raw, &a); err != nil {
return nil, fmt.Errorf("%s's answer to list: %w", seat, err)
}
out = append(out, a.Repositories...)
if a.Next == "" {
return out, nil
}
if seen[a.Next] {
return nil, fmt.Errorf("%s's list answered the cursor %q twice", seat, a.Next)
}
seen[a.Next], in.Next = true, a.Next
}
return a.Repositories, nil
}
// View reads the store now, through both seats.
@@ -32,7 +32,7 @@ func main() {
h.Acts = meshhandactsclient.Recorder{Ask: stdio.Ask}
// The module's one held writer (design 47 G §689, A-16, A-29, A-32): the holder's findings and the reader's go through it.
w, err := views.NewStdioHeldWriter(views.WriterConfig[meshconditions.Finding, meshconditions.FindingCleared, meshconditions.FindingsStated, meshconditions.FindingsAskedEvent]{
Asked: meshconditions.SubjectFindingsAsked, Module: Module, State: stdio.State("findings"), Kinds: []string{ImageMissing, SweepRefused}})
Asked: meshconditions.SubjectFindingsAsked, Module: Module, State: stdio.State("findings"), Kinds: []string{ImageMissing, SweepRefused, ListUnread, BuildsUnread}})
if err != nil {
logf("%v", err)
os.Exit(1)
@@ -92,7 +92,20 @@ func (f *fakeStore) ask(t *testing.T) func(string, any) (json.RawMessage, error)
repos = append(repos, reg.Repository{Name: name, Manifests: ms})
}
}
return json.Marshal(reg.ListAnswer{Repositories: repos})
if seat != "oci-artifact-registry" {
return json.Marshal(reg.ListAnswer{Repositories: repos})
}
// oci-artifact-registry pages (design 47 H2 §813 (7)): one repository a page, after the one its cursor names.
var page struct{ Next string }
_ = json.Unmarshal(raw, &page)
for len(repos) > 0 && repos[0].Name <= page.Next {
repos = repos[1:]
}
next := ""
if len(repos) > 1 {
repos, next = repos[:1], repos[0].Name
}
return json.Marshal(map[string]any{"repositories": repos, "next": next, "capped": next != ""})
}
}
@@ -27,6 +27,9 @@ import (
// SweepRefused is the sweep's finding: a seat refused a hold or a remove the sweep asked.
const SweepRefused = "sweep-refused"
// ListUnread is the pass's finding: the registry seats' list could not be read, so the pass ended (design 47 H, H-A-250 (3)).
const ListUnread = "artifact-list-unread"
// canonical is a kept reference in the older form, `artifact-store://<path>`, whichever form it came in; another is as
// it was.
func canonical(reference string) string {
@@ -140,6 +143,53 @@ func (h *Holder) sweepClean() {
}
}
// BuildsUnread is the pass's finding: the builder's builds could not be judged, so the pass ended (design 47 H, H-A-260).
const BuildsUnread = "artifact-builds-unread"
// unreadFinding writes a pass's finding of what it could not read (ListUnread, BuildsUnread) once: a pass that fails the
// same way while the writer holds it writes nothing more. Nothing asks again until the next event marks a pass.
func (h *Holder) unreadFinding(kind string, err error) {
for _, was := range h.Findings.Held() {
if was.Kind == kind {
return
}
}
at := h.now().UTC()
f := meshconditions.Finding{Scope: "module", ID: keys.EscapeName(Module), Kind: kind,
Subject: meshconditions.Subject{Scope: "module", ID: keys.EscapeName(Module)},
Severity: meshconditions.FindingSeverityWarning, Resolver: "operator",
Summary: "the artifact sweep stopped: the registry seats' list could not be read (the evidence names why)",
Headline: "The artifact sweep cannot read the store's list",
Explanation: "The sweep judges what to keep against the store's list, which it asks the registry seats. The list " +
"could not be read, so the sweep removed nothing and observed nothing; what it kept stays kept.",
Needs: "read the registry seat holder's journal for why its list failed; the next finished build or want change asks again.",
Evidence: []meshconditions.Evidence{{At: at, Said: err.Error()}},
Source: "CAT-AS1", Observer: Module, At: at}
if kind == BuildsUnread {
f.Summary = "the artifact sweep stopped: the builder's builds could not be judged (the evidence names why)"
f.Headline = "The artifact sweep cannot judge the builds"
f.Explanation = "The sweep keeps each module's newest builds and every wanted one, judged from the builder's builds " +
"and when each ended. Those could not all be read, so the sweep removed nothing and observed nothing; what " +
"it kept stays kept."
f.Needs = "read this module's journal for which build's end is unread; the next finished build or want change asks again."
}
if werr := h.Findings.Write(context.Background(), f); werr != nil {
h.logf("the pass's finding %s (%v) could not be written: %v", kind, err, werr)
}
}
// readAgain clears a pass's finding of kind, when the held writer holds it, once a pass read what it could not.
func (h *Holder) readAgain(kind string) {
for _, was := range h.Findings.Held() {
if was.Kind != kind {
continue
}
if err := h.Findings.Clear(context.Background(), was.Scope, was.ID, was.Kind, "a pass read it again"); err != nil {
h.logf("the pass's finding %s could not be cleared: %v", kind, err)
}
}
}
// keptWhy is why a kept reference is held, as the seat's hold takes it.
func keptWhy(r *Ref) string {
if r == nil || len(r.Why) == 0 {
+6 -2
View File
@@ -1,6 +1,7 @@
{
"module": "artifact-store-tools",
"version": "0.1",
"class": "core",
"packages": {
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-builder/builds": "0.1"
},
@@ -111,7 +112,10 @@
{
"name": "findings",
"storage": "key-value",
"template": "state"
"template": "state",
"options": {
"max-mib": 8
}
},
{
"name": "finding-events",
@@ -124,7 +128,7 @@
"findings-stated.*"
],
"max-age-days": 7,
"max-mib": 16
"max-mib": 8
}
}
]
+1
View File
@@ -1,6 +1,7 @@
{
"module": "asus-zephyrus-g14",
"version": "0.1",
"class": "leaf",
"moved": true,
"templates": "templates",
"capabilities": [
+1
View File
@@ -1,6 +1,7 @@
{
"module": "audit-logger",
"version": "0.1",
"class": "leaf",
"slug": "audit",
"consumes": [
"**"
+1
View File
@@ -1,6 +1,7 @@
{
"module": "avahi",
"version": "0.1",
"class": "leaf",
"capabilities": [
"package-manager",
"service-manager"
+1
View File
@@ -1,6 +1,7 @@
{
"module": "baserow",
"version": "0.1",
"class": "leaf",
"capabilities": [
"container-runtime"
],
+1
View File
@@ -1,6 +1,7 @@
{
"module": "blueman",
"version": "0.1",
"class": "leaf",
"capabilities": [
"package-manager"
],
+1
View File
@@ -1,6 +1,7 @@
{
"module": "bluetooth",
"version": "0.1",
"class": "leaf",
"capabilities": [
"package-manager",
"service-manager"
+1
View File
@@ -1,6 +1,7 @@
{
"module": "brother",
"version": "0.1",
"class": "core",
"requires": [
{
"name": "s3-bucket",
+1
View File
@@ -1,6 +1,7 @@
{
"module": "buildah",
"version": "0.1",
"class": "leaf",
"capabilities": [
"package-manager",
"user-namespaces"
+1
View File
@@ -1,6 +1,7 @@
{
"module": "ca-trust",
"version": "0.1",
"class": "core",
"slug": "catrust",
"capabilities": [
"service-manager"
+7 -32
View File
@@ -28,8 +28,7 @@ And, for where the agent runs as an account of its own (hq ADR 0266):
rule and can read no secret the mesh placed for another account. A way found is this module's condition,
and the controller's self-check says it urgently.
- `/usr/local/bin/claude-agent`, root's, `0755`: starts the agent as that account — `claude` itself when run
as it, otherwise `sudo -iu <account> claude` through the operator's own sudo, carrying the guard's
override only when it is set in the operator's shell.
as it, otherwise `sudo -iu <account> claude` through the operator's own sudo.
- `/etc/claude-code/agent-account`, root's, `0644`: the name of that account, the machine fact
`agent-account`, for the shell to read — the controller fills no machine fact into shell code.
- **`claude` in the operator's interactive zsh is `claude-agent`** where the machine names an agent account:
@@ -48,7 +47,7 @@ whenever the node's tool runtime collects the module's tools:
| `managed-mcp.json` | the tool servers every session loads: the mesh's console as `mesh` (with a `timeout` of 660000 ms, mesh_wait's longest wait and a minute, so the agent's one-minute default does not cut a wait, issue 1871), and the servers set in this module's `mcp_servers` setting. **Exclusive**: a server not listed here does not load — not one added with `claude mcp add`, not a project's `.mcp.json`, not a plugin's |
| `managed-settings.json` | the keys set in this module's `managed_settings` setting — at the controller's terminal alone (hq issue 340) — under the mesh's own keys: the repositories' attribution convention, the claude.ai connectors kept beside the managed servers, the key-helper while the node holds an API-key licence, git's credential file while the node holds the forge's read credential (below), and the two that name the `nox-mesh` marketplace and enable its plugin, and `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` (660000) in `env` beside the operator's own, the mesh's key winning |
| `CLAUDE.md` | how a session on this mesh works, this node's name and role, the conventions, the **"instead of" table** — then the instruction sections registered for every node and for this one |
| `marketplace/` | the `nox-mesh` plugin (hq ADR 0216): the skills, subagents, commands and output styles registered for every node and for this one, offered in a session as `nox-mesh:<name>` — and the **guard on the agent's shell** (`guard/`), the mesh's own hook and the plugin's only one (hq issue 340). Replaced whole, staged beside and swapped in |
| `marketplace/` | the `nox-mesh` plugin (hq ADR 0216): the skills, subagents, commands and output styles registered for every node and for this one, offered in a session as `nox-mesh:<name>` — and this module's binary (`guard/guard`, its path kept so the home-fs helper's path does not move) run by the mesh's own SessionStart and Stop hooks, the plugin's only hooks (hq issue 340, ADR 0489). No PreToolUse hook: the guard on the agent's shell is removed (the operator, 2026-11-20). Replaced whole, staged beside and swapped in |
Under the operator's home: `~/.claude/.credentials.json`, only when the licence manager hands this node a
subscription token; and what is registered at the **home** scope for this node — a skill, subagent,
@@ -126,31 +125,15 @@ The agent kept reaching for `ssh <machine> journalctl` while the service manager
answered this is not placed) — at start, every ten minutes and on `claude_code_render`, keeps it in its
state (`mesh-tools.json`), and renders it into `CLAUDE.md` as one row per seat or module: `<node>/<seat>.` and
each verb with the commands it replaces. Generated, never written by hand: a verb that gains `replaces` is in
the next render. Ordered by what the guard here refused most, then the machines' seats, the modules, the
the next render. Ordered by the machines' seats, the modules, the
mesh's seats; at most sixteen rows, the rest one `mesh_search` away.
- **The guard.** A PreToolUse hook on every tool, judging `Bash`, `Edit`, `Write`, `MultiEdit` and `NotebookEdit` and letting the rest through (but see the account rule below): this module's own
binary (`claude-code guard`), copied root's into the plugin with what it judges with (`guard.json`: the
machines by name, domain and address, and the replaced commands), run by its path under `/etc/claude-code` so
the session cannot change it. It refuses `ssh`, `scp`, `sftp`, `rsync`, `mosh` and `autossh` to a mesh machine
(any `*.internal` name, a machine's name or a name under its domains, one of its addresses, as `ssh -G` reads
the destination; a jump through one too), writing `/etc/hosts` or `/etc/resolv.conf`, and `HOSTALIASES` —
naming the verb that does the job on that machine when one says it replaces the command, and otherwise that a
missing tool is created in the module that owns it, never worked around. **Stated, not silent:** an ssh login
as `git` is the forge's account, which runs nothing but git, and passes; a git remote is never an ssh command
line anyway.
- **The operator's override**: `MESH_GUARD_OVERRIDE=<why>`, exported in the operator's own shell before the
session starts. It is read from the session's environment as the kernel kept it at exec
(`/proc/<pid>/environ` of the agent's process), so nothing a session does — a command's `export`, a
settings `env` key — can set it, and a command naming it is refused outright. Every override and every
refusal is a line in the module's `guard.log`; an override that cannot be recorded is not honoured.
`claude_code_guard` shows the rules, the data and the record.
It is a guard against the habit, not a sandbox: a command written to hide what it runs can hide it, and the
record is how a habit that found a way round is seen.
The rule under the table (never `ssh` to a mesh machine, never edit `/etc/hosts` or set `HOSTALIASES` for a
mesh name) is the session's own: nothing on the agent's shell enforces it since the guard was removed (the
operator, 2026-11-20).
## Tools
`claude_code_status`, `claude_code_render`, `claude_code_guard`, `claude_code_pull` (asks the vault for this node's
`claude_code_status`, `claude_code_render`, `claude_code_pull` (asks the vault for this node's
licence token now), `claude_code_grant` (for the licence manager), `claude_code_mcp_list`, `claude_code_mcp_unregister` (this node by default; `nodes: "all"` or a list for
more).
@@ -339,14 +322,6 @@ applied only while the agent's account holds it — and what this module placed
goes: the access-token-only credentials file (one holding a refresh token is a login the person made, and
stays, said), the home-scope items unless changed by hand, the key kept in the state.
**The guard there refuses every tool call of a session that does not run as the agent's account** —
shell, file edits, reads and the mesh's tools alike — and no override lifts it: the operator's account may become root, and an
agent started in it by habit must do nothing. Its record goes to the machine's journal
(`journalctl -t mesh-claude-code-guard`), which the session's account may add to and not change;
`claude_code_guard` reads it there, keeping only the lines the journal says the guard's own binary wrote. That
is not proof: the account can run the guard's binary itself and add lines in the guard's words. What it
cannot do is remove one.
**An API key is taken only from the agent's own home.** `claude_code_add_api_key` reads a file and removes it,
and the runtime runs as the operator: a path anywhere would hand whoever calls it the runtime's credential or
the operator's keys. So the file must lie under the home of the account the agent runs as, reached through no
@@ -1,8 +1,7 @@
package main
// Where the agent runs as an account of its own (novox/hq ADR 0266): the home touched through the helper, the
// licence that follows the account, what goes from the operator's home, and the guard that refuses a session
// running as anyone else.
// licence that follows the account, and what goes from the operator's home.
import (
"bufio"
@@ -11,7 +10,6 @@ import (
"errors"
"io"
"io/fs"
"net"
"os"
"path/filepath"
"strings"
@@ -333,82 +331,6 @@ func TestNothingGoesWhereTheAgentRunsAsTheOperator(t *testing.T) {
}
}
// ---- the guard --------------------------------------------------------------------------------------------
func TestASessionNotRunningAsTheAgentsAccountDoesNothing(t *testing.T) {
g := Guard{Data: GuardData{Node: "anchor", Agent: "agent"}}
echo := HookInput{ToolName: "Bash", ToolInput: map[string]any{"command": "echo hello"}}
v := g.JudgeAs("operator", echo)
if !v.Refuse || v.Rule != "account" || v.Overridable || !strings.Contains(v.Message, "claude-agent") {
t.Fatalf("a session as the operator is refused whatever it runs, with no override: %+v", v)
}
if v := g.JudgeAs("operator", HookInput{ToolName: "Write", ToolInput: map[string]any{"file_path": "/tmp/x"}}); !v.Refuse {
t.Fatal("a file edit too")
}
if v := g.JudgeAs("agent", echo); v.Refuse {
t.Fatalf("the agent's own account runs as before: %+v", v)
}
if v := (Guard{Data: GuardData{Node: "laptop"}}).JudgeAs("operator", echo); v.Refuse {
t.Fatal("where agents run as the operator, the operator's session runs as before")
}
}
func TestWhereTheAgentHasItsOwnAccountTheRecordIsTheJournal(t *testing.T) {
p, _ := node(t, "anchor")
if d := GuardDataOf(p, nil); d.Agent != "" || strings.HasPrefix(d.Log, JournalRecord) {
t.Fatalf("as the operator: the module's own file; got %+v", d)
}
p.Agent, p.Operator = "agent", "operator"
d := GuardDataOf(p, nil)
if d.Agent != "agent" || d.Log != JournalRecord+GuardJournalID {
t.Fatalf("as an account of its own: the journal, and the account named; got %+v", d)
}
socket := filepath.Join(t.TempDir(), "journal")
conn, err := net.ListenUnixgram("unixgram", &net.UnixAddr{Name: socket, Net: "unixgram"})
if err != nil {
t.Skipf("no unix datagram socket here: %v", err)
}
defer conn.Close()
was := journalSocket
journalSocket = socket
t.Cleanup(func() { journalSocket = was })
if err := RecordGuard(d.Log, GuardEntry{Decision: "refused", Rule: "account", Tool: "Bash", Command: "a\nb"}); err != nil {
t.Fatal(err)
}
buf := make([]byte, 4096)
n, _, err := conn.ReadFrom(buf)
if err != nil {
t.Fatal(err)
}
lines := strings.Split(strings.TrimSuffix(string(buf[:n]), "\n"), "\n")
if len(lines) != 3 || lines[0] != "SYSLOG_IDENTIFIER="+GuardJournalID || !strings.HasPrefix(lines[2], "MESSAGE={") {
t.Fatalf("one line per field, the entry as one line of JSON: %q", lines)
}
readWas := readJournal
t.Cleanup(func() { readJournal = readWas })
readJournal = func(id string, last int) ([]byte, error) {
if id != GuardJournalID {
t.Fatalf("read %s", id)
}
msg, _ := json.Marshal(strings.TrimPrefix(lines[2], "MESSAGE="))
forged, _ := json.Marshal(`{"decision":"overridden","rule":"ssh","tool":"Bash","command":"forged"}`)
return []byte(`{"MESSAGE":` + string(msg) + `,"_EXE":"` + HelperPath() + `"}` + "\n" +
`{"MESSAGE":` + string(forged) + `,"_EXE":"/usr/bin/logger"}` + "\n"), nil
}
if got := ReadGuardLog(d.Log, 10); len(got) != 1 || got[0].Rule != "account" || got[0].Command != "a\nb" {
t.Fatalf("the record reads back from the journal: %+v", got)
}
if err := RecordGuard(JournalRecord+"x", GuardEntry{}); err != nil && !strings.Contains(err.Error(), "journal") {
t.Fatal(err)
}
journalSocket = filepath.Join(t.TempDir(), "absent")
if err := RecordGuard(d.Log, GuardEntry{}); err == nil {
t.Fatal("a journal that cannot be reached is an error, so an override is not honoured unrecorded")
}
}
// ---- an API key is taken only from the agent's own home ---------------------------------------------------
func TestAnAPIKeyFileOutsideTheAgentsHomeIsRefusedAndKept(t *testing.T) {
@@ -439,21 +361,6 @@ func TestAnAPIKeyFileOutsideTheAgentsHomeIsRefusedAndKept(t *testing.T) {
}
}
func TestTheGuardIsAskedAboutEveryToolAndRefusesEachForAnotherAccount(t *testing.T) {
if GuardMatcher != "*" {
t.Fatalf("the guard is asked about every tool, got %q", GuardMatcher)
}
g := Guard{Data: GuardData{Node: "anchor", Agent: "agent"}}
for _, tool := range []string{"Read", "Grep", "WebFetch", "mcp__mesh__mesh_call", "Task"} {
if v := g.JudgeAs("operator", HookInput{ToolName: tool}); !v.Refuse {
t.Fatalf("%s as another account is refused", tool)
}
if v := g.JudgeAs("agent", HookInput{ToolName: tool}); v.Refuse {
t.Fatalf("%s as the agent's account passes", tool)
}
}
}
func TestAMoveWritesTheAccountFileBesideTheToken(t *testing.T) {
p, w := node(t, "anchor")
writeFile(t, p.binding(), `{"licence":"personal","kind":"subscription","generation":4}`)
@@ -11,6 +11,7 @@ import (
"testing"
"time"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/views"
)
@@ -358,18 +359,128 @@ func TestAnAppliedBindingSaysWhyAndWho(t *testing.T) {
}
}
func TestTheTokenANodeIsHandedReplacesALoginsGrantAndLeavesNoRefreshToken(t *testing.T) {
p, w := node(t, "laptop")
writeFile(t, p.credentials(), `{"claudeAiOauth":{"accessToken":"at-old","refreshToken":"rt-spent","expiresAt":`+
strings.TrimSpace(string(mustJSON(now+7_200_000)))+`}}`)
var asked []string
out, err := Pull(p, seat(t, "personal", "at-new", 1, &asked), writer(w))
if err != nil || out["applied"] != true {
t.Fatalf("%v %v", out, err)
}
c := creds(t, p)
if c["accessToken"] != "at-new" || c["refreshToken"] != nil || HoldingsOf(p).Refresh.Present {
t.Fatalf("%v", c)
// ADR 0206, ADR 0209, design 39 §6 "the latest login wins": a login in the file that was never handed to the manager
// is newer than every lease, made while the tool runner was stopped (the start's first view) or while it runs (a
// binding or the vault's change heard before the manager asked claude_code_grant). No path writes over it; once
// claude_code_grant handed it, its successor replaces it and leaves no refresh token, and a file holding no login is
// restored as before.
func TestALoginNotHandedIsNeverWrittenOverAndItsSuccessorReplacesIt(t *testing.T) {
login := `{"claudeAiOauth":{"accessToken":"at-login","refreshToken":"rt-login","expiresAt":` +
strings.TrimSpace(string(mustJSON(now+7_200_000))) + `,"refreshTokenExpiresAt":9000},"other":1}`
lease := `{"claudeAiOauth":{"accessToken":"at-lease","expiresAt":1},"other":1}`
for _, c := range []struct {
name, file string
handed bool
offeredRTE int64 // the refresh token expiry the grant offered carries, 0 for none
offeredExp int64 // its access expiry, 0 for an hour from now
heard func(p Paths, ask Ask, w WriteManaged) (string, error)
want string // the access token the file holds after
account string // the email address the agent's account file names, "" for none
reason string // what the journal line says, "" for nothing
}{
{"the start's first view, a login made while stopped", login, false, 0, 0, func(p Paths, ask Ask, w WriteManaged) (string, error) {
return FirstBinding(p, ask, w)
}, "at-login", "", ""},
{"binding.changed heard while it runs, before the grant was asked", login, false, 0, 0, func(p Paths, ask Ask, w WriteManaged) (string, error) {
return OnBindingChanged(p, []byte(`{"consumer":"laptop","licence":"personal","key":"personal","kind":"subscription","generation":9}`), ask, w)
}, "at-login", "", ""},
{"the vault's change heard while it runs, before the grant was asked", login, false, 0, 0, func(p Paths, ask Ask, w WriteManaged) (string, error) {
return OnSecretChanged(p, []byte(`{"name":"licence.personal.access","generation":5}`), ask, w)
}, "at-login", "", ""},
{"a login handed, met by its refresh: same lineage, later access expiry (H-A-139)", login, true, 9000, now + 3*7_200_000, func(p Paths, ask Ask, w WriteManaged) (string, error) {
return OnBindingChanged(p, []byte(`{"consumer":"laptop","licence":"personal","key":"personal","kind":"subscription","generation":9}`), ask, w)
}, "at-new", "", ""},
{"a login handed, met by a newer lineage (H-A-138)", login, true, 200_000_000, 0, func(p Paths, ask Ask, w WriteManaged) (string, error) {
return OnBindingChanged(p, []byte(`{"consumer":"laptop","licence":"personal","key":"personal","kind":"subscription","generation":9}`), ask, w)
}, "at-new", "", ""},
{"a login handed, met by the same lineage with an earlier access expiry (H-A-139)", login, true, 9000, 0, func(p Paths, ask Ask, w WriteManaged) (string, error) {
return OnBindingChanged(p, []byte(`{"consumer":"laptop","licence":"personal","key":"personal","kind":"subscription","generation":9}`), ask, w)
}, "at-login", "", ""},
{"a login handed, met by the same lineage with an equal access expiry (H-A-139)", login, true, 9000, now + 7_200_000, func(p Paths, ask Ask, w WriteManaged) (string, error) {
return OnBindingChanged(p, []byte(`{"consumer":"laptop","licence":"personal","key":"personal","kind":"subscription","generation":9}`), ask, w)
}, "at-login", "", ""},
{"a login handed, met by an older lineage (H-A-138)", login, true, -100_000_000, now + 3*7_200_000, func(p Paths, ask Ask, w WriteManaged) (string, error) {
return OnBindingChanged(p, []byte(`{"consumer":"laptop","licence":"personal","key":"personal","kind":"subscription","generation":9}`), ask, w)
}, "at-login", "", ""},
{"a login handed, met by a lease with no lineage mark (H-A-138)", login, true, 0, now + 3*7_200_000, func(p Paths, ask Ask, w WriteManaged) (string, error) {
return OnBindingChanged(p, []byte(`{"consumer":"laptop","licence":"personal","key":"personal","kind":"subscription","generation":9}`), ask, w)
}, "at-login", "", ""},
{"not handed, the same account, a lease that succeeds it: the latest login wins (H-A-140)", login, false, 9000, now + 3*7_200_000, func(p Paths, ask Ask, w WriteManaged) (string, error) {
return OnBindingChanged(p, []byte(`{"consumer":"laptop","licence":"personal","key":"personal","kind":"subscription","generation":9}`), ask, w)
}, "at-new", "personal", "login superseded"},
{"not handed, the same account, a lease older than it (H-A-140)", login, false, 9000, 0, func(p Paths, ask Ask, w WriteManaged) (string, error) {
return OnBindingChanged(p, []byte(`{"consumer":"laptop","licence":"personal","key":"personal","kind":"subscription","generation":9}`), ask, w)
}, "at-login", "personal", ""},
{"not handed, another account, a newer lease (H-A-140)", login, false, 200_000_000, now + 3*7_200_000, func(p Paths, ask Ask, w WriteManaged) (string, error) {
return OnBindingChanged(p, []byte(`{"consumer":"laptop","licence":"personal","key":"personal","kind":"subscription","generation":9}`), ask, w)
}, "at-login", "someone@example.org", ""},
{"a file holding the lease, older than the one handed", lease, false, 0, 0, func(p Paths, ask Ask, w WriteManaged) (string, error) {
return FirstBinding(p, ask, w)
}, "at-new", "", ""},
} {
t.Run(c.name, func(t *testing.T) {
p, w := node(t, "laptop")
writeFile(t, p.binding(), `{"licence":"personal","key":"personal","kind":"subscription","generation":2}`+"\n")
writeFile(t, p.credentials(), c.file)
if c.account != "" {
writeFile(t, p.account(), `{"oauthAccount":{"accountUuid":"u-1","emailAddress":"`+c.account+`"}}`)
}
if c.handed {
manager, _ := GenerateKeyPair()
if a, err := GrantFor(p, manager.PublicKey); err != nil || a.Sealed == nil {
t.Fatalf("the grant: %+v %v", a, err)
}
}
var asked []string
current := seat(t, "personal", "at-new", 9, &asked)
ask := func(address string, args any) (json.RawMessage, error) {
if address == SeatVerb("bindings") {
return json.RawMessage(`[{"consumer":"laptop","licence":"personal","key":"personal","kind":"subscription","generation":9}]`), nil
}
if address == VaultGet && (c.offeredRTE != 0 || c.offeredExp != 0) {
exp := c.offeredExp
if exp == 0 {
exp = now + 3_600_000
}
g := Grant{AccessToken: "at-new", ExpiresAt: exp}
if c.offeredRTE != 0 {
g.RefreshTokenExpiresAt = &c.offeredRTE
}
gj, _ := json.Marshal(g)
box, err := Seal(string(gj), args.(map[string]any)["public_key"].(string))
if err != nil {
t.Fatal(err)
}
return json.Marshal(map[string]any{"name": args.(map[string]any)["name"], "generation": 1, "sealed": box})
}
return current(address, args)
}
before, _ := os.ReadFile(p.credentials())
line, err := c.heard(p, ask, writer(w))
if err != nil {
t.Fatal(err)
}
if !strings.Contains(line, c.reason) {
t.Fatalf("the line %s lacks %q", line, c.reason)
}
got := creds(t, p)
if got["accessToken"] != c.want {
t.Fatalf("the file holds %v, want %s", got["accessToken"], c.want)
}
after, _ := os.ReadFile(p.credentials())
if c.want == "at-login" {
if string(after) != string(before) || !HoldingsOf(p).Refresh.Present {
t.Fatalf("a login not handed was changed: %s", after)
}
return
}
// Restored: no refresh token survives (design 14, design 36 §5), the CLI's other keys stay.
var whole map[string]any
_ = json.Unmarshal(after, &whole)
if got["refreshToken"] != nil || HoldingsOf(p).Refresh.Present || whole["other"] == nil {
t.Fatalf("restored %s", after)
}
})
}
}
@@ -618,7 +729,10 @@ func TestTheFirstViewOfTheBindingIsApplied(t *testing.T) {
Reads []string
}
_ = json.Unmarshal(raw, &m)
if !slices.Contains(m.Consumes, BindingChanged) || !slices.Contains(m.Consumes, SecretChanged) ||
// The manager says each change as binding.changed.<consumer> (design 47 G A-134), and the bus consumer this module's
// consumes is composed into hands it only what an entry names, so an entry naming binding.changed alone hears none.
hears := slices.ContainsFunc(m.Consumes, func(c string) bool { return stdio.TopicMatches(c, BindingChanged+".g14") })
if !hears || !slices.Contains(m.Consumes, SecretChanged) ||
!slices.Contains(m.Invokes, SeatVerb("bindings")) || !slices.Contains(m.Invokes, VaultGet) || len(m.Reads) != 0 {
t.Fatalf("the manifest consumes %v, invokes %v, reads %v", m.Consumes, m.Invokes, m.Reads)
}
+13 -29
View File
@@ -472,40 +472,27 @@ type PluginFile struct {
From string `json:",omitempty"`
}
// GuardDir is where the guard on the agent's shell lives in the plugin (novox/hq ADR 0245): its binary and
// what it is given. Outside hooks/, so no registered hook's name can be it.
// GuardDir is where this module's binary lives in the plugin, run by the SessionStart and Stop hooks and as the
// home-fs helper (novox/hq ADR 0266). Outside hooks/, so no registered hook's name can be it. Its path is kept so the
// helper's does not move; the guard on the agent's shell that once ran from it is removed (the operator,
// 2026-11-20).
const GuardDir = "guard"
// GuardFiles are the guard as the plugin carries it: the binary to copy, what it judges with, and — the same
// binary again — the waits directory the SessionStart and Stop hooks are given (novox/hq ADR 0489, issues
// 1744, 1743). Empty WaitsDir places no such hook.
type GuardFiles struct {
// HookFiles are what the plugin carries to run its hooks: the binary to copy and the waits directory the
// SessionStart and Stop hooks are given (novox/hq ADR 0489, issues 1744, 1743). Empty WaitsDir places no hook.
type HookFiles struct {
Exe string
Data GuardData
WaitsDir string
}
// GuardMatcher is what the guard is asked about: every tool. Its own rules judge the shell and the agent's file
// edits and let every other tool through; the rule of the account agents run as (novox/hq ADR 0266) refuses
// every tool of a session running as another, reading and the mesh's tools included, so that session can do
// nothing at all.
const GuardMatcher = "*"
// GuardCommand is the hook's command line: by its path under the managed directory, root's — never the
// copy the agent may keep of a plugin, which the session could change.
func GuardCommand() string {
dir := filepath.Join(ManagedDir, MarketplaceDir, "plugins", Plugin, GuardDir)
return `"` + filepath.Join(dir, "guard") + `" guard "` + filepath.Join(dir, "guard.json") + `"`
}
// SessionStartCommand is the plugin's SessionStart hook: the guard's own binary, told the session's open
// SessionStartCommand is the plugin's SessionStart hook: this module's binary, told the session's open
// waits live under waitsDir (novox/hq ADR 0489 §3, issue 1744).
func SessionStartCommand(waitsDir string) string {
dir := filepath.Join(ManagedDir, MarketplaceDir, "plugins", Plugin, GuardDir)
return `"` + filepath.Join(dir, "guard") + `" session-start "` + waitsDir + `"`
}
// StopCommand is the plugin's Stop hook: the guard's own binary, refusing to end the turn while a wait under
// StopCommand is the plugin's Stop hook: this module's binary, refusing to end the turn while a wait under
// waitsDir is open and unwatched, or past its bound and untold (novox/hq ADR 0489 §3-§6, issue 1743).
func StopCommand(waitsDir string) string {
dir := filepath.Join(ManagedDir, MarketplaceDir, "plugins", Plugin, GuardDir)
@@ -516,9 +503,9 @@ func StopCommand(waitsDir string) string {
// over a mesh item of the same kind and name: the node's wins.
func Marketplace(c Config) map[string]PluginFile { return MarketplaceWith(c, nil) }
// MarketplaceWith is the marketplace with the guard on the agent's shell, when there is one to place: its
// hook first, before any registered one.
func MarketplaceWith(c Config, guard *GuardFiles) map[string]PluginFile {
// MarketplaceWith is the marketplace with the binary the plugin's hooks run, when there is one to place, and its
// SessionStart and Stop hooks. No PreToolUse hook: the plugin judges no tool call.
func MarketplaceWith(c Config, guard *HookFiles) map[string]PluginFile {
root := "plugins/" + Plugin + "/"
out := map[string]PluginFile{
".claude-plugin/marketplace.json": {Content: jsonFile(map[string]any{
@@ -547,9 +534,6 @@ func MarketplaceWith(c Config, guard *GuardFiles) map[string]PluginFile {
hooks := map[string][]any{}
if guard != nil && guard.Exe != "" {
out[root+GuardDir+"/guard"] = PluginFile{From: guard.Exe, Executable: true}
out[root+GuardDir+"/guard.json"] = PluginFile{Content: jsonFile(guard.Data)}
hooks["PreToolUse"] = append(hooks["PreToolUse"], map[string]any{"matcher": GuardMatcher,
"hooks": []any{map[string]any{"type": "command", "command": GuardCommand(), "timeout": 15}}})
if guard.WaitsDir != "" {
// A session's wait list (novox/hq ADR 0489): the SessionStart hook names the session's id and its open
// waits (issue 1744); the Stop hook keeps the turn open while one is unwatched or untold (issue 1743).
@@ -574,7 +558,7 @@ func MarketplaceWith(c Config, guard *GuardFiles) map[string]PluginFile {
out[root+"output-styles/"+it.Name+".md"] = PluginFile{Content: it.Files[it.Name+".md"]}
}
// A hook is never rendered from a registration (novox/hq issue 340): the plugin's hooks are the mesh's own
// guard alone, and any other is the operator's, in the managed settings set at the controller's terminal.
// SessionStart and Stop hooks alone, and any other is the operator's, in the managed settings set at the controller's terminal.
}
if len(hooks) > 0 {
out[root+"hooks/hooks.json"] = PluginFile{Content: jsonFile(map[string]any{"hooks": hooks})}
@@ -281,7 +281,7 @@ func TestTheManifestListsEveryToolServed(t *testing.T) {
// notice goes out on the operator channel's notify (design 47 G GR8).
if !slices.Equal(m.Invokes, []string{"seat:mesh-hand-acts.warranted", "seat:mesh-hand-acts.hand-act", "seat:mesh-catalog.seat-definitions", RevisionVerb, RegistrationsVerb, SourceVerb, AssignmentsTool, SeatVerb("bindings"), SeatVerb("current"), VaultGet, "seat:operator-channel.notify"}) ||
len(m.Reads) != 0 ||
!slices.Equal(m.Consumes, []string{"mesh-catalog.catalog-revision", "mesh-catalog.registration-changed", "mesh-delivery.source-moved", "mesh-delivery-assigner.views.assignments", "mesh-catalog.seat-definition-changed", "mesh-catalog.seat-definition-removed", "mesh-conditions.findings-asked", HoldingsAsked, BindingChanged, SecretChanged}) {
!slices.Equal(m.Consumes, []string{"mesh-catalog.catalog-revision", "mesh-catalog.registration-changed", "mesh-delivery.source-moved", "mesh-delivery-assigner.views.assignments", "mesh-catalog.seat-definition-changed", "mesh-catalog.seat-definition-removed", "mesh-conditions.findings-asked", HoldingsAsked, BindingChanged + ".*", SecretChanged}) {
t.Errorf("invokes = %v, reads = %v, consumes = %v", m.Invokes, m.Reads, m.Consumes)
}
if src, _ := os.ReadFile("proposals.go"); !strings.Contains(string(src), `"seat:mesh-hand-acts.warranted"`) ||
@@ -122,6 +122,36 @@ func HoldsLogin(c Credentials) bool {
return rt != ""
}
// LoginKept is the reason a grant is not written over a login (H-A-138).
const LoginKept = "login kept"
// Succeeds says the offered grant replaces the login the file holds (H-A-138, H-A-139): its lineage is newer
// (its refresh token's expiry later than the login's, beyond one generation), or it is of the same lineage
// (sameGeneration) and its access token expires later than the login's, which only the manager's refresh of
// that login yields. No lineage mark, an older lineage, or the same lineage with no later access expiry is the
// older lease.
func Succeeds(login Credentials, offered Grant) bool {
if offered.RefreshTokenExpiresAt == nil {
return false
}
held := GrantOf(login)
if held == nil || held.RefreshTokenExpiresAt == nil {
return true
}
if sameGeneration(held.RefreshTokenExpiresAt, offered.RefreshTokenExpiresAt) {
return offered.ExpiresAt > held.ExpiresAt
}
return *offered.RefreshTokenExpiresAt > *held.RefreshTokenExpiresAt
}
// LoginNotHanded says the file holds a login that was never handed to the manager: handed is the fingerprint
// of the refresh token claude_code_grant last sealed, "" when none was. Such a login is newer than anything the
// manager holds, so no grant may overwrite it before the manager adopts it (ADR 0206, ADR 0209).
func LoginNotHanded(c Credentials, handed string) bool {
rt := RefreshTokenOf(c)
return rt != "" && Fingerprint(rt) != handed
}
// RefreshTokenOf is the refresh token a login left, or "".
func RefreshTokenOf(c Credentials) string {
rt, _ := c.oauth()["refreshToken"].(string)
@@ -1,811 +0,0 @@
package main
// The guard on the agent's shell (novox/hq ADR 0245): a PreToolUse hook every session on a machine of the
// mesh runs before a shell command or a file edit, delivered in the module's plugin.
//
// It refuses three work-arounds, each with the mesh tool that does the job when one says it replaces the
// command, and otherwise with the rule that a missing tool is created, never worked around:
//
// 1. **ssh to a mesh machine** — `ssh`, `scp`, `sftp`, `rsync`, `mosh` or `autossh` to a machine's name, a
// name under its domains, any `*.internal` name, or one of its addresses; a jump through one too. The
// destination is read as ssh itself reads it (`ssh -G`), so an alias in ~/.ssh/config is no way round.
// **Stated, not silent**: an ssh login as `git` is the forge's account, which runs git and nothing
// else — so `git push` over ssh, and `ssh -T git@<forge>`, reach no machine and pass. A git remote is
// never an ssh command line anyway.
// 2. **writing /etc/hosts or /etc/resolv.conf** — by redirect, tee, sed -i, an editor, cp/mv/install onto
// it, or the agent's own Edit and Write tools: a mesh name is the mesh's resolvers' (ADR 0194), and a
// machine's hosts file is its node-hostname seat's.
// 3. **HOSTALIASES**, named anywhere in a command line.
//
// And it refuses any command that names the operator's override, so the agent never sets it (guard_run.go).
//
// The matching is on the command line as a shell would split it — quotes, separators, `$(…)`, `bash -c` —
// and wrappers such as sudo, env and timeout are looked through. It is a guard against the habit of reaching
// for ssh, not a sandbox: a command built to hide what it runs can hide it, and the record of what was
// refused (the module's `guard.log`, read by `claude_code_guard`) is how a habit that found a way round is seen.
import (
"fmt"
"net"
"net/url"
"path"
"path/filepath"
"sort"
"strings"
)
// GuardData is what the hook is given: this machine, the mesh's machines, what replaces what, and where
// its record is kept. Written beside the hook on every render, root's, so the session cannot change it.
type GuardData struct {
Node string `json:"node"`
Machines []Machine `json:"machines"`
Replacements []Replacement `json:"replacements"`
Log string `json:"log"`
// Agent is the account every session here must run as, where the machine names an agent account of its
// own (novox/hq ADR 0266); empty where agents run as the operator.
Agent string `json:"agent,omitempty"`
}
// HookInput is what the agent hands a PreToolUse hook.
type HookInput struct {
ToolName string `json:"tool_name"`
ToolInput map[string]any `json:"tool_input"`
Cwd string `json:"cwd"`
SessionID string `json:"session_id"`
}
// Verdict is the guard's answer.
type Verdict struct {
Refuse bool `json:"refuse"`
Rule string `json:"rule,omitempty"` // ssh | hosts-file | hostaliases | override-named | account
Machine string `json:"machine,omitempty"`
Message string `json:"message,omitempty"`
// Overridable is false for a refusal no override lifts: the agent naming the override itself.
Overridable bool `json:"-"`
// Calls are the tools the refusal named, by address without a machine: what the instructions' table
// puts first, the tools the agent most reached round.
Calls []string `json:"calls,omitempty"`
}
// OverrideVar is the operator's override: set in the operator's own shell before the session starts,
// with why as its value. Read from the session's own environment as it was started, never from what a
// command or a setting put there (guard_run.go).
const OverrideVar = "MESH_GUARD_OVERRIDE"
// ForgeUser is the forge's ssh account: it runs git, never a shell (stated in ADR 0245).
const ForgeUser = "git"
// protectedFiles are the files a session never writes for a mesh name.
var protectedFiles = map[string]bool{"/etc/hosts": true, "/etc/resolv.conf": true}
// SSHView is how ssh itself reads a destination with these options: the host it connects to, the user,
// and the jumps. Empty host when ssh could not say.
type SSHView func(options []string, destination string) (host, user string, jumps []string)
// Guard judges what a session is about to do.
type Guard struct {
Data GuardData
// SSH reads a destination as ssh does (`ssh -G`); nil reads it from the command line alone.
SSH SSHView
// Resolve is a name's addresses, for a name that is none of the mesh's but may point at a machine.
Resolve func(string) []string
}
// JudgeAs is the verdict on one tool call of a session running as an account. **On a machine whose agents run
// as an account of their own, a session running as any other does nothing** (novox/hq ADR 0266): the
// operator's account there may become root without a person, and an agent started in it by habit would carry
// that into every command. Refused whatever the command, and no override lifts it — the operator's own shell is
// how the operator acts as themselves.
func (g Guard) JudgeAs(account string, in HookInput) Verdict {
if g.Data.Agent != "" && account != g.Data.Agent {
return Verdict{Refuse: true, Rule: "account", Message: fmt.Sprintf("Refused: on %s agents run as %s, an "+
"account that cannot become root without a person, and this session runs as %s (novox/hq ADR 0266). "+
"No tool it calls here is let through. End it, and start the agent with `claude-agent`, which runs it as "+
"%s; what needs the operator's own rights is the operator's to run in their own shell.",
orThisMachine(g.Data.Node), g.Data.Agent, account, g.Data.Agent)}
}
return g.Judge(in)
}
func orThisMachine(node string) string {
if node == "" {
return "this machine"
}
return node
}
// Judge is the verdict on one tool call.
func (g Guard) Judge(in HookInput) Verdict {
switch in.ToolName {
case "Bash":
command, _ := in.ToolInput["command"].(string)
return g.judgeLine(command, 0)
case "Edit", "Write", "MultiEdit", "NotebookEdit":
for _, key := range []string{"file_path", "notebook_path"} {
if p, _ := in.ToolInput[key].(string); p != "" && protectedFiles[filepath.Clean(p)] {
return g.hostsFile(filepath.Clean(p), in.ToolName+" "+filepath.Clean(p))
}
}
}
return Verdict{}
}
func (g Guard) judgeLine(line string, depth int) Verdict {
if depth > 4 {
return Verdict{}
}
if strings.Contains(line, OverrideVar) {
return Verdict{Refuse: true, Rule: "override-named", Message: fmt.Sprintf(
"Refused by the mesh's guard (novox/hq ADR 0245): this command names %s, the operator's override. "+
"It is the operator's alone, set in their own shell before a session starts; a session never sets, "+
"reads or passes it.", OverrideVar)}
}
if strings.Contains(line, "HOSTALIASES") {
return g.refuseLocal("hostaliases", "HOSTALIASES", "setting HOSTALIASES")
}
for _, words := range simpleCommands(line) {
if v := g.judgeCommand(words, depth); v.Refuse {
return v
}
// What a word runs in its own shell: `$(…)` and backticks inside a quoted word.
for _, w := range words {
for _, inner := range substitutions(w) {
if v := g.judgeLine(inner, depth+1); v.Refuse {
return v
}
}
}
}
return Verdict{}
}
// wrappers run the command after them; each with the options that take a value.
var wrappers = map[string]string{
"sudo": "ugCDhpTrt", "doas": "uC", "env": "uSC", "timeout": "sk", "nohup": "", "nice": "n", "ionice": "cnpP",
"command": "", "exec": "a", "time": "fo", "stdbuf": "ioe", "xargs": "aEdIiLlnPs", "setsid": "", "unbuffer": "",
"chronic": "", "flock": "wE", "torsocks": "", "proxychains": "f", "proxychains4": "f", "caffeinate": "",
}
// shells run their -c argument as a command line.
var shells = map[string]bool{"sh": true, "bash": true, "zsh": true, "dash": true, "ksh": true, "fish": true, "eval": true}
func (g Guard) judgeCommand(words []string, depth int) Verdict {
words = unwrap(words)
if len(words) == 0 {
return Verdict{}
}
name := path.Base(words[0])
args := words[1:]
if shells[name] {
if name == "eval" {
return g.judgeLine(strings.Join(args, " "), depth+1)
}
for i, a := range args {
if strings.HasPrefix(a, "-") && !strings.HasPrefix(a, "--") && strings.Contains(a, "c") && i+1 < len(args) {
return g.judgeLine(args[i+1], depth+1)
}
}
}
switch name {
case "ssh", "autossh", "mosh", "slogin":
return g.judgeSSH(name, args, strings.Join(words, " "))
case "scp", "sftp", "rsync":
return g.judgeCopy(name, args, strings.Join(words, " "))
}
if target := writesProtected(name, args); target != "" {
return g.hostsFile(target, strings.Join(words, " "))
}
return Verdict{}
}
// unwrap takes off what only runs the command: assignments before it, and wrappers with their options.
func unwrap(words []string) []string {
for len(words) > 0 {
w := words[0]
switch {
case w == "!" || w == "{" || w == "}" || w == "then" || w == "do" || w == "else" || w == "if" || w == "while" ||
w == "until" || w == "elif":
words = words[1:]
case isAssignment(w):
words = words[1:]
default:
opts, wrapper := wrappers[path.Base(w)]
if !wrapper {
return words
}
base := path.Base(w)
words = words[1:]
for len(words) > 0 {
a := words[0]
if a == "--" {
words = words[1:]
break
}
if base == "env" && isAssignment(a) {
words = words[1:]
continue
}
if !strings.HasPrefix(a, "-") || a == "-" {
break
}
words = words[1:]
if strings.HasPrefix(a, "--") {
continue
}
if f := a[len(a)-1:]; strings.Contains(opts, f) && len(words) > 0 {
words = words[1:]
}
}
// timeout's duration, nice's adjustment as a word: a number before the command.
if (base == "timeout") && len(words) > 0 {
words = words[1:]
}
}
}
return words
}
func isAssignment(w string) bool {
i := strings.Index(w, "=")
if i <= 0 {
return false
}
for _, r := range w[:i] {
if !(r == '_' || r >= 'A' && r <= 'Z' || r >= 'a' && r <= 'z' || r >= '0' && r <= '9') {
return false
}
}
return true
}
// sshOptionsWithValue are ssh's single-letter options that take a value.
const sshOptionsWithValue = "BbcDEeFIiJLlmOoPpQRSWw"
func (g Guard) judgeSSH(name string, args []string, line string) Verdict {
var options, jumps []string
user := ""
dest, rest := "", []string(nil)
for i := 0; i < len(args); i++ {
a := args[i]
if a == "--" {
if i+1 < len(args) {
dest, rest = args[i+1], args[i+2:]
}
break
}
if name == "autossh" && strings.HasPrefix(a, "-M") {
if a == "-M" {
i++ // autossh's own: the monitoring port
}
continue
}
if strings.HasPrefix(a, "-") && len(a) > 1 {
options = append(options, a)
if name == "mosh" || strings.HasPrefix(a, "--") {
continue // mosh's own options are long, each with its value after `=`
}
for j := 1; j < len(a); j++ {
if !strings.ContainsRune(sshOptionsWithValue, rune(a[j])) {
continue
}
value := a[j+1:]
if value == "" && i+1 < len(args) {
i++
value = args[i]
options = append(options, value)
}
switch a[j] {
case 'J':
jumps = append(jumps, strings.Split(value, ",")...)
case 'l':
user = value
case 'o':
k, v, _ := strings.Cut(value, "=")
switch strings.ToLower(strings.TrimSpace(k)) {
case "proxyjump":
jumps = append(jumps, strings.Split(v, ",")...)
case "user":
user = strings.TrimSpace(v)
}
}
break
}
continue
}
dest, rest = a, args[i+1:]
break
}
if dest == "" {
return Verdict{}
}
host, destUser := hostOf(dest)
if destUser != "" {
user = destUser
}
if g.SSH != nil && name != "mosh" {
if h, u, j := g.SSH(options, dest); h != "" {
host, user = h, u
jumps = append(jumps, j...)
}
}
remote := strings.Join(rest, " ")
for _, jump := range jumps {
jh, ju := hostOf(jump)
if machine, ok := g.meshHost(jh); ok && ju != ForgeUser {
return g.refuseSSH(machine, jh, remote, line)
}
}
if user == ForgeUser {
return Verdict{} // the forge's account: git and nothing else (stated in ADR 0245)
}
if machine, ok := g.meshHost(host); ok {
return g.refuseSSH(machine, host, remote, line)
}
return Verdict{}
}
// judgeCopy reads scp's, sftp's and rsync's remote paths, `[user@]host:path` or `scp://[user@]host/…`.
func (g Guard) judgeCopy(name string, args []string, line string) Verdict {
for i := 0; i < len(args); i++ {
a := args[i]
if strings.HasPrefix(a, "-") {
if name != "rsync" && len(a) == 2 && strings.ContainsRune("cFiJloPSXBRD", rune(a[1])) {
i++
}
if name == "rsync" && (a == "-e" || a == "--rsh") {
i++
}
continue
}
var host, user string
if strings.Contains(a, "://") {
host, user = hostOf(a)
} else if colon := strings.Index(a, ":"); colon > 0 && !strings.Contains(a[:colon], "/") {
host, user = hostOf(a[:colon])
} else if name == "sftp" {
host, user = hostOf(a)
} else {
continue
}
if user == ForgeUser {
continue
}
if g.SSH != nil {
if h, u, _ := g.SSH(nil, host); h != "" {
host = h
if u == ForgeUser && user == "" {
continue
}
}
}
if machine, ok := g.meshHost(host); ok {
return g.refuseSSH(machine, host, "", line)
}
}
return Verdict{}
}
// hostOf reads `[user@]host[:port]`, `ssh://[user@]host[:port]/…` or `[v6]`.
func hostOf(dest string) (host, user string) {
if strings.Contains(dest, "://") {
if u, err := url.Parse(dest); err == nil {
return strings.ToLower(u.Hostname()), u.User.Username()
}
}
if at := strings.LastIndex(dest, "@"); at >= 0 {
user, dest = dest[:at], dest[at+1:]
}
if strings.HasPrefix(dest, "[") {
if end := strings.Index(dest, "]"); end > 0 {
return strings.ToLower(dest[1:end]), user
}
}
if h, _, err := net.SplitHostPort(dest); err == nil && strings.Count(dest, ":") == 1 {
dest = h
}
return strings.TrimSuffix(strings.ToLower(dest), "."), user
}
// meshHost says whether a host is one of the mesh's machines, and which when it can tell.
func (g Guard) meshHost(host string) (string, bool) {
host = strings.TrimSuffix(strings.ToLower(strings.Trim(host, "[]")), ".")
if host == "" {
return "", false
}
if ip := net.ParseIP(host); ip != nil {
for _, m := range g.Data.Machines {
for _, a := range m.Addresses {
if b := net.ParseIP(a); b != nil && b.Equal(ip) {
return m.Name, true
}
}
}
return "", false
}
for _, m := range g.Data.Machines {
if host == strings.ToLower(m.Name) {
return m.Name, true
}
for _, d := range m.Domains {
if host == d || strings.HasSuffix(host, "."+d) {
return m.Name, true
}
}
}
if strings.HasSuffix(host, InternalSuffix) {
return "", true
}
if g.Resolve != nil && !strings.Contains(host, "/") {
for _, a := range g.Resolve(host) {
if m, ok := g.meshHost(a); ok && net.ParseIP(a) != nil {
return m, true
}
}
}
return "", false
}
// writesProtected is the protected file a command writes, or "".
func writesProtected(name string, args []string) string {
protected := func(a string) string {
a = strings.Trim(a, `"'`)
if strings.HasPrefix(a, "of=") {
a = a[3:]
}
if protectedFiles[filepath.Clean(a)] {
return filepath.Clean(a)
}
return ""
}
// A redirect onto it, from any command.
for i, a := range args {
if (a == ">" || a == ">>") && i+1 < len(args) {
if p := protected(args[i+1]); p != "" {
return p
}
}
}
operands := func() []string {
var out []string
for i := 0; i < len(args); i++ {
if args[i] == ">" || args[i] == ">>" || args[i] == "<" {
i++
continue
}
out = append(out, args[i])
}
return out
}()
switch name {
case "tee", "vi", "vim", "nvim", "nano", "emacs", "ed", "ex", "micro", "hx", "helix", "kak", "gedit", "code",
"truncate", "chattr", "chmod", "chown", "rm", "unlink", "shred", "dd", "sponge", "visudo", "vipw":
for _, a := range operands {
if p := protected(a); p != "" {
return p
}
}
case "sed", "perl", "ruby", "awk", "gawk":
inPlace := false
for _, a := range operands {
switch {
case name == "awk" || name == "gawk":
inPlace = inPlace || a == "inplace"
case strings.HasPrefix(a, "--in-place"):
inPlace = true
case strings.HasPrefix(a, "-") && !strings.HasPrefix(a, "--") && strings.Contains(a, "i"):
inPlace = true
}
}
if inPlace {
for _, a := range operands {
if p := protected(a); p != "" {
return p
}
}
}
case "cp", "mv", "install", "ln", "rsync":
var files []string
for _, a := range operands {
if !strings.HasPrefix(a, "-") {
files = append(files, a)
}
}
if len(files) > 1 {
if p := protected(files[len(files)-1]); p != "" {
return p
}
}
}
return ""
}
// replacementsFor are the mesh's tools that replace a command, the most specific first, each address once.
func (g Guard) replacementsFor(command string) []string {
have := commandWordsOf(command)
type found struct {
address string
weight int
replace string
}
var all []found
for _, r := range g.Data.Replacements {
best := 0
which := ""
for _, c := range r.Replaces {
want := commandWordsOf(c)
if inOrderWords(want, have) && len(want) > best {
best, which = len(want), c
}
}
if best > 0 {
all = append(all, found{r.Address, best, which})
}
}
sort.SliceStable(all, func(i, j int) bool { return all[i].weight > all[j].weight })
var out []string
for _, f := range all {
out = append(out, f.address+"\x00"+f.replace)
}
return out
}
// callFor is how an address is called for a machine.
func (g Guard) callFor(address, machine string) string {
for _, r := range g.Data.Replacements {
if r.Address != address || !r.NodeScoped {
continue
}
on := machine
if !r.Seat && len(r.On) > 0 && !containsString(r.On, machine) {
on = r.On[0]
}
if on == "" {
on = "<node>"
}
return on + "/" + address
}
return address
}
func containsString(xs []string, s string) bool {
for _, x := range xs {
if x == s {
return true
}
}
return false
}
// exact is the replacement that names this exact command, or "".
func (g Guard) exact(command string) string {
for _, r := range g.Data.Replacements {
for _, c := range r.Replaces {
if c == command {
return r.Address
}
}
}
return ""
}
const missingTool = "No mesh tool says it replaces this. Do not work around it: a missing tool is created in the module " +
"that owns the thing, on the seat it occupies — say what is missing to the operator. First make sure with " +
"`mesh_search` and the command's own words."
func (g Guard) refuseSSH(machine, host, remote, line string) Verdict {
who := machine
if who == "" {
who = host + " (a mesh name)"
}
var b strings.Builder
var named []string
fmt.Fprintf(&b, "Refused by the mesh's guard (novox/hq ADR 0245): `%s` reaches %s round the mesh's tools.\n", cut(line, 160), who)
switch {
case strings.TrimSpace(remote) == "":
target := machine
if target == "" {
target = "<machine>"
}
fmt.Fprintf(&b, "What a machine serves is `mesh_machine %s`; `mesh_search` with what you meant to run finds its tool.\n", target)
default:
calls := g.replacementsFor(remote)
if len(calls) == 0 {
b.WriteString(missingTool + "\n")
break
}
b.WriteString("Call instead, through `mesh_call`:\n")
for i, c := range calls {
if i == 3 {
break
}
address, replaces, _ := strings.Cut(c, "\x00")
named = append(named, address)
fmt.Fprintf(&b, " %s — replaces `%s`\n", g.callFor(address, machine), replaces)
}
}
return Verdict{Refuse: true, Rule: "ssh", Machine: machine, Message: strings.TrimRight(b.String(), "\n"), Overridable: true,
Calls: named}
}
func (g Guard) refuseLocal(rule, replaced, what string) Verdict {
var b strings.Builder
fmt.Fprintf(&b, "Refused by the mesh's guard (novox/hq ADR 0245): %s is a work-around for a mesh name. "+
"A mesh name is the mesh's resolvers' to answer, and a machine's own lines in /etc/hosts are its node-hostname seat's.\n", what)
var named []string
if address := g.exact(replaced); address != "" {
named = append(named, address)
fmt.Fprintf(&b, "Call instead, through `mesh_call`: %s — replaces `%s`", g.callFor(address, g.Data.Node), replaced)
} else {
b.WriteString(missingTool)
}
return Verdict{Refuse: true, Rule: rule, Machine: g.Data.Node, Message: b.String(), Overridable: true, Calls: named}
}
func (g Guard) hostsFile(file, line string) Verdict {
replaced := "edit " + file
return g.refuseLocal("hosts-file", replaced, fmt.Sprintf("writing %s (`%s`)", file, cut(line, 120)))
}
func cut(s string, n int) string {
s = strings.Join(strings.Fields(s), " ")
if r := []rune(s); len(r) > n {
return string(r[:n-1]) + "…"
}
return s
}
// commandWordsOf are a command line's words as matched against a replaced command (the mesh MCP server's search rule):
// lower-cased, a program by path reduced to its name, sudo left out.
func commandWordsOf(line string) []string {
var out []string
for i, w := range strings.Fields(strings.ToLower(line)) {
if i == 0 || strings.HasPrefix(w, "/") {
w = path.Base(w)
}
if w == "sudo" {
continue
}
out = append(out, w)
}
return out
}
func inOrderWords(want, have []string) bool {
i := 0
for _, h := range have {
if i < len(want) && h == want[i] {
i++
}
}
return len(want) > 0 && i == len(want)
}
// ---- the shell's words ------------------------------------------------------------------------------
// simpleCommands splits a command line as a shell would into its simple commands' words: quotes
// removed, `;`, `&`, `|`, `&&`, `||`, newlines, parentheses and backticks between commands, `$(` opening
// one; `>` and `>>` kept as words of their own, before what they redirect to.
func simpleCommands(line string) [][]string {
var out [][]string
var words []string
var cur strings.Builder
inWord := false
flushWord := func() {
if inWord {
words = append(words, cur.String())
cur.Reset()
inWord = false
}
}
flushCommand := func() {
flushWord()
if len(words) > 0 {
out = append(out, words)
}
words = nil
}
r := []rune(line)
for i := 0; i < len(r); i++ {
c := r[i]
switch {
case c == '\\' && i+1 < len(r):
i++
if r[i] != '\n' {
cur.WriteRune(r[i])
inWord = true
}
case c == '\'':
inWord = true
for i++; i < len(r) && r[i] != '\''; i++ {
cur.WriteRune(r[i])
}
case c == '"':
inWord = true
for i++; i < len(r) && r[i] != '"'; i++ {
if r[i] == '\\' && i+1 < len(r) && strings.ContainsRune("\"\\$`", r[i+1]) {
i++
}
cur.WriteRune(r[i])
}
case c == '$' && i+1 < len(r) && r[i+1] == '(':
flushCommand()
i++
case c == ';' || c == '&' || c == '|' || c == '\n' || c == '(' || c == ')' || c == '`':
flushCommand()
case c == '>' || c == '<':
// A file descriptor before it (`2>`) is not a word.
if inWord && isDigits(cur.String()) {
cur.Reset()
inWord = false
}
flushWord()
op := string(c)
if c == '>' && i+1 < len(r) && r[i+1] == '>' {
op = ">>"
i++
}
if i+1 < len(r) && (r[i+1] == '&' || r[i+1] == '|') {
i++
}
words = append(words, op)
case c == ' ' || c == '\t':
flushWord()
case c == '#' && !inWord:
for i < len(r) && r[i] != '\n' {
i++
}
flushCommand()
default:
cur.WriteRune(c)
inWord = true
}
}
flushCommand()
return out
}
func isDigits(s string) bool {
if s == "" {
return false
}
for _, r := range s {
if r < '0' || r > '9' {
return false
}
}
return true
}
// substitutions are the command lines a quoted word runs in a shell of its own: `$(…)` and `…`.
func substitutions(word string) []string {
var out []string
for {
i := strings.Index(word, "$(")
if i < 0 {
break
}
rest := word[i+2:]
depth, end := 1, len(rest)
for j, c := range rest {
if c == '(' {
depth++
} else if c == ')' {
depth--
if depth == 0 {
end = j
break
}
}
}
out = append(out, rest[:end])
if end >= len(rest) {
break
}
word = rest[end+1:]
}
parts := strings.Split(word, "`")
for i := 1; i < len(parts); i += 2 {
out = append(out, parts[i])
}
return out
}
@@ -1,315 +0,0 @@
package main
// The guard as the hook runs it (novox/hq ADR 0245): `claude-code guard <guard.json>`, the tool call on
// standard input, exit 2 with the reason on standard error to refuse — the agent reads it — and 0 to let it be.
//
// **The operator's override.** `MESH_GUARD_OVERRIDE=<why>` lets one session through a refusal — never the
// refusal of a command naming the override itself — and only:
//
// - **from the session's environment as it was started**: read from /proc/<pid>/environ of the agent's own
// process, which is fixed at exec. A command's `export`, an `env` key in a settings file, a variable the
// session sets for its tools — none of them reaches it. A nested session the agent starts with the
// variable is refused before it starts: the command names the override;
// - **recorded**: every override is a line in the module's guard.log — or, where the agent runs as an account
// of its own, in the machine's journal (novox/hq ADR 0266) — with why, the command and the machine; an
// override that cannot be recorded is not honoured. Refusals are recorded the same way.
//
// A guard that fails — a fault in this code — exits 1, which the agent shows and does not block on: a guard
// that refused every command would stop the session the operator needs to repair it.
import (
"bytes"
"context"
"encoding/json"
"fmt"
"io"
"net"
"os"
"os/exec"
"os/user"
"path/filepath"
"strconv"
"strings"
"time"
)
// procRoot and parentPID are where the session's process is found; a test points them at its own.
var (
procRoot = "/proc"
parentPID = os.Getppid
)
// GuardLogMax is the size the guard's record grows to before it is kept once as guard.log.1.
const GuardLogMax = 1 << 20
// GuardEntry is one line of the guard's record.
type GuardEntry struct {
At string `json:"at"`
Node string `json:"node,omitempty"`
Decision string `json:"decision"` // refused | overridden
Rule string `json:"rule"`
Machine string `json:"machine,omitempty"`
Tool string `json:"tool"`
Command string `json:"command"`
Why string `json:"why,omitempty"`
// Tools are the tools the refusal named instead.
Tools []string `json:"tools,omitempty"`
Session string `json:"session,omitempty"`
}
// JournalRecord is the guard's record where the agent runs as an account of its own (novox/hq ADR 0266): the
// session's account cannot enter the module's state, and must not be able to rewrite what it was refused, so
// each line goes to the machine's journal, which the account may add to and not change. The record's
// location is then this prefix and the journal's identifier.
const JournalRecord = "journal:"
// GuardJournalID is the identifier the guard's lines carry in the journal.
const GuardJournalID = "mesh-claude-code-guard"
// journalSocket is where the journal takes a line; a test points it at its own.
var journalSocket = "/run/systemd/journal/socket"
// RecordGuard appends one line to the record.
func RecordGuard(path string, e GuardEntry) error {
if path == "" {
return fmt.Errorf("no record is kept here")
}
if id, ok := strings.CutPrefix(path, JournalRecord); ok {
return recordInJournal(id, e)
}
if info, err := os.Stat(path); err == nil && info.Size() > GuardLogMax {
_ = os.Rename(path, path+".1")
}
f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o600)
if err != nil {
return err
}
raw, _ := json.Marshal(e)
if _, err := f.Write(append(raw, '\n')); err != nil {
f.Close()
return err
}
return f.Close()
}
// recordInJournal says one line to the journal by its native protocol: the entry as JSON in MESSAGE, one line,
// so nothing in a command can add a field of its own.
func recordInJournal(id string, e GuardEntry) error {
raw, err := json.Marshal(e)
if err != nil {
return err
}
conn, err := net.Dial("unixgram", journalSocket)
if err != nil {
return fmt.Errorf("the journal cannot be reached: %w", err)
}
defer conn.Close()
_, err = conn.Write([]byte("SYSLOG_IDENTIFIER=" + id + "\nPRIORITY=5\nMESSAGE=" + string(raw) + "\n"))
return err
}
// readJournal is the journal's last lines of the guard's record, read as root through the runtime account's
// sudo where this process is not root: what other accounts said is not the runtime account's to read. As JSON,
// with the field the journal itself sets for the program that wrote the line (_EXE), which no writer chooses —
// and matched on it in the query itself, so lines another program wrote under the guard's identifier cannot
// push the guard's own past the last ones read.
var readJournal = func(id string, last int) ([]byte, error) {
args := []string{"journalctl", "-q", "--no-pager", "-o", "json", "--output-fields=MESSAGE,_EXE", "-t", id,
"_EXE=" + HelperPath(), "-n", strconv.Itoa(last)}
if os.Geteuid() != 0 {
args = append([]string{"sudo", "-n"}, args...)
}
cmd := exec.Command(args[0], args[1:]...)
cmd.Env = append(os.Environ(), "LC_ALL=C", "LANG=C")
return cmd.Output()
}
// guardsOwnLines keeps, of the journal's JSON lines, the messages the guard's own binary wrote (novox/hq ADR
// 0266). The agent's account may add to the journal under any identifier — `logger -t` — and the journal
// says which program wrote each line; a line another program wrote under the guard's identifier is not the
// guard's record. The agent can still run the guard's binary itself, so the record is the guard's words, not
// proof that each refusal happened in a session: what it cannot do is remove one.
func guardsOwnLines(raw []byte, exe string) []byte {
var out []byte
for _, line := range bytes.Split(raw, []byte("\n")) {
var f struct {
Message any `json:"MESSAGE"`
Exe string `json:"_EXE"`
}
if json.Unmarshal(line, &f) != nil || f.Exe != exe {
continue
}
if m, ok := f.Message.(string); ok {
out = append(append(out, m...), '\n')
}
}
return out
}
// ReadGuardLog is the record's last lines, newest last.
func ReadGuardLog(path string, last int) []GuardEntry {
read := os.ReadFile
if id, ok := strings.CutPrefix(path, JournalRecord); ok {
read = func(string) ([]byte, error) {
raw, err := readJournal(id, last)
return guardsOwnLines(raw, HelperPath()), err
}
}
raw, err := read(path)
if err != nil {
return []GuardEntry{}
}
lines := strings.Split(strings.TrimSpace(string(raw)), "\n")
if len(lines) > last {
lines = lines[len(lines)-last:]
}
out := []GuardEntry{}
for _, l := range lines {
var e GuardEntry
if json.Unmarshal([]byte(l), &e) == nil {
out = append(out, e)
}
}
return out
}
// sshDashG reads a destination as ssh does: `ssh -G` prints the configuration it would use and connects
// to nothing, so an alias, a HostName and a ProxyJump in ~/.ssh/config are what is judged.
func sshDashG(options []string, destination string) (host, user string, jumps []string) {
if _, err := exec.LookPath("ssh"); err != nil {
return "", "", nil
}
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
args := append([]string{"-G"}, options...)
args = append(args, "--", destination)
out, err := exec.CommandContext(ctx, "ssh", args...).Output()
if err != nil {
return "", "", nil
}
for _, line := range strings.Split(string(out), "\n") {
k, v, ok := strings.Cut(strings.TrimSpace(line), " ")
if !ok {
continue
}
switch k {
case "hostname":
host = strings.ToLower(v)
case "user":
user = v
case "proxyjump":
if v != "none" {
jumps = append(jumps, strings.Split(v, ",")...)
}
}
}
return host, user, jumps
}
func quickLookup(name string) []string {
ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()
addrs, _ := net.DefaultResolver.LookupHost(ctx, name)
return addrs
}
// sessionEnvironment is the environment the agent's own process was started with: the nearest ancestor
// that is the agent, read from what the kernel kept at its exec.
func sessionEnvironment(proc string, pid int) map[string]string {
for i := 0; i < 32 && pid > 1; i++ {
cmdline, _ := os.ReadFile(filepath.Join(proc, strconv.Itoa(pid), "cmdline"))
if isAgent(cmdline) {
raw, err := os.ReadFile(filepath.Join(proc, strconv.Itoa(pid), "environ"))
if err != nil {
return nil
}
env := map[string]string{}
for _, kv := range bytes.Split(raw, []byte{0}) {
if k, v, ok := strings.Cut(string(kv), "="); ok {
env[k] = v
}
}
return env
}
stat, err := os.ReadFile(filepath.Join(proc, strconv.Itoa(pid), "stat"))
if err != nil {
return nil
}
// The parent is the fourth field, after the command's name in parentheses (which may hold spaces).
closing := bytes.LastIndexByte(stat, ')')
fields := strings.Fields(string(stat[closing+1:]))
if len(fields) < 2 {
return nil
}
pid, _ = strconv.Atoi(fields[1])
}
return nil
}
// isAgent says whether a process's command line is the agent's: its native binary, or its package run by node.
func isAgent(cmdline []byte) bool {
args := strings.Split(strings.TrimRight(string(cmdline), "\x00"), "\x00")
if len(args) == 0 || args[0] == "" {
return false
}
if filepath.Base(args[0]) == "claude" {
return true
}
if b := filepath.Base(args[0]); (b == "node" || b == "bun") && len(args) > 1 {
return filepath.Base(args[1]) == "claude" || strings.Contains(args[1], "@anthropic-ai/claude-code")
}
return false
}
// currentAccount is the account the session runs as; a test sets its own.
var currentAccount = func() string {
if u, err := user.Current(); err == nil {
return u.Username
}
return "uid " + strconv.Itoa(os.Getuid())
}
// runGuard is the hook: the tool call in, the verdict out as the exit code.
func runGuard(dataPath string, stdin io.Reader, stderr io.Writer) (code int) {
defer func() {
if r := recover(); r != nil {
fmt.Fprintf(stderr, "the mesh's guard failed and judged nothing: %v\n", r)
code = 1
}
}()
var in HookInput
if err := json.NewDecoder(stdin).Decode(&in); err != nil {
fmt.Fprintf(stderr, "the mesh's guard could not read the tool call: %v\n", err)
return 1
}
var data GuardData
if raw, err := os.ReadFile(dataPath); err == nil {
_ = json.Unmarshal(raw, &data)
}
g := Guard{Data: data, SSH: sshDashG, Resolve: quickLookup}
v := g.JudgeAs(currentAccount(), in)
if !v.Refuse {
return 0
}
command, _ := in.ToolInput["command"].(string)
if command == "" {
command, _ = in.ToolInput["file_path"].(string)
}
entry := GuardEntry{At: time.Now().UTC().Format(time.RFC3339), Node: data.Node, Decision: "refused", Rule: v.Rule,
Machine: v.Machine, Tool: in.ToolName, Command: cut(command, 400), Session: in.SessionID, Tools: v.Calls}
if v.Overridable {
if why := strings.TrimSpace(sessionEnvironment(procRoot, parentPID())[OverrideVar]); why != "" {
entry.Decision, entry.Why = "overridden", cut(why, 200)
if err := RecordGuard(data.Log, entry); err == nil {
return 0
} else {
v.Message += fmt.Sprintf("\nThe operator's override is set, and could not be recorded (%v): an override "+
"that is not recorded is not honoured.", err)
entry.Decision, entry.Why = "refused", ""
}
}
}
_ = RecordGuard(data.Log, entry)
fmt.Fprintln(stderr, v.Message)
return 2
}
@@ -1,328 +0,0 @@
package main
import (
"bytes"
"encoding/json"
"os"
"path/filepath"
"strconv"
"strings"
"testing"
"git.novox.be/novox/mesh-sdk/go/seatdef"
)
// meshForTheGuard is a mesh of two machines and the verbs that replace what an agent runs over ssh, as the
// seats' contract and the modules' manifests say them.
func meshForTheGuard() GuardData {
defined := []seatdef.Definition{
{Seat: "mesh-module-assigner", Scope: "mesh", Verbs: []seatdef.Verb{
{Name: "assignments", Description: "Read assignments: one node's key.", Replaces: []string{"hostnamectl", "uptime"}}}},
{Seat: "node-service-manager", Scope: "node", Verbs: []seatdef.Verb{
{Name: "status", Description: "One unit as the service manager sees it now: its states.", Replaces: []string{"systemctl status", "systemctl is-active"}},
{Name: "restart", Description: "Restart one unit.", Replaces: []string{"systemctl restart"}},
{Name: "journal", Description: "The last lines of one unit's journal.", Replaces: []string{"journalctl"}}}},
{Seat: "node-hostname", Scope: "node", Verbs: []seatdef.Verb{
{Name: "add", Description: "Add one address and its names to the operator's lines of /etc/hosts.", Replaces: []string{"edit /etc/hosts", "HOSTALIASES"}}}},
}
modules := []ModuleTools{{Module: "docker", On: []string{"anchor"}, Replaces: map[string][]string{"docker_logs": {"docker logs"}, "docker_list": {"docker ps"}}},
{Module: "systemd", On: []string{"anchor", "laptop"}}}
return GuardData{Node: "laptop", Replacements: ReplacementsOf(defined, modules), Machines: []Machine{
{Name: "anchor", Domains: []string{"anchor" + InternalSuffix, "anchor.example"}, Addresses: []string{"192.0.2.10", "10.10.0.1"}},
{Name: "laptop", Domains: []string{"laptop" + InternalSuffix}, Addresses: []string{"10.10.0.4"}},
}}
}
// noSSH reads a destination from the command line alone; aliases reads one alias as ssh's configuration would.
func aliases(options []string, destination string) (string, string, []string) {
host, user := hostOf(destination)
switch host {
case "a":
return "anchor.example", "operator", nil
case "via-anchor":
return "203.0.113.5", "operator", []string{"anchor"}
case "forge":
return "git.anchor" + InternalSuffix, "git", nil
}
if user == "" {
user = "operator"
}
for i, o := range options {
if o == "-l" && i+1 < len(options) {
user = options[i+1]
}
}
return host, user, nil
}
func guard() Guard {
return Guard{Data: meshForTheGuard(), SSH: aliases, Resolve: func(name string) []string {
if name == "nas.lan" {
return []string{"192.0.2.10"}
}
return nil
}}
}
func bash(command string) HookInput {
return HookInput{ToolName: "Bash", ToolInput: map[string]any{"command": command}}
}
// **ssh to a mesh machine is refused**, by every name and address it has and however the shell spells it,
// and the refusal names the verb that does the job on that machine (novox/hq ADR 0245).
func TestSSHToAMeshMachineIsRefusedNamingTheTool(t *testing.T) {
g := guard()
for command, want := range map[string]string{
"ssh anchor journalctl -u mesh-config -n 50": "anchor/node-service-manager.journal",
"ssh anchor 'sudo journalctl -fu sshd'": "anchor/node-service-manager.journal",
"ssh -p 22 root@anchor.example systemctl status nats": "anchor/node-service-manager.status",
"ssh anchor.internal systemctl restart nats": "anchor/node-service-manager.restart",
"ssh -o StrictHostKeyChecking=no 10.10.0.1 docker ps -a": "anchor/docker.docker_list",
"ssh anchor docker logs --tail 100 nats": "anchor/docker.docker_logs",
"ssh laptop docker logs x": "anchor/docker.docker_logs",
"ssh a uptime": "mesh-module-assigner.assignments",
"cd /tmp && ssh anchor journalctl": "anchor/node-service-manager.journal",
"sudo -u root ssh anchor journalctl": "anchor/node-service-manager.journal",
"timeout 10 ssh anchor journalctl": "anchor/node-service-manager.journal",
"env LANG=C ssh anchor journalctl": "anchor/node-service-manager.journal",
"bash -c 'ssh anchor journalctl -u x'": "anchor/node-service-manager.journal",
`echo "$(ssh anchor journalctl -n 5)" | tail`: "anchor/node-service-manager.journal",
"for n in anchor laptop; do ssh $n uptime; done; ssh anchor uptime": "mesh-module-assigner.assignments",
"ssh -J anchor 203.0.113.9 journalctl": "anchor/node-service-manager.journal",
"ssh via-anchor journalctl": "anchor/node-service-manager.journal",
"ssh nas.lan journalctl": "anchor/node-service-manager.journal",
"ssh ssh://anchor:2222 journalctl": "anchor/node-service-manager.journal",
} {
v := g.Judge(bash(command))
if !v.Refuse || v.Rule != "ssh" {
t.Errorf("%q was not refused: %+v", command, v)
continue
}
if !strings.Contains(v.Message, want) {
t.Errorf("%q: the refusal does not name %s:\n%s", command, want, v.Message)
}
}
}
// What no tool replaces is refused all the same, saying a tool is created, never worked around; a shell
// on a machine is pointed at what the machine serves; copying a file off one is refused too.
func TestSSHWithNoToolForItSaysCreateOne(t *testing.T) {
g := guard()
for command, want := range map[string]string{
"ssh anchor cat /var/lib/thing/state.json": "a missing tool is created in the module",
"ssh anchor": "mesh_machine anchor",
"ssh build.internal ls": "a missing tool is created",
"scp anchor:/etc/nats/nats.conf /tmp/": "mesh_machine anchor",
"rsync -av root@10.10.0.4:/srv/ ./srv/": "mesh_machine laptop",
"sftp anchor.example": "mesh_machine anchor",
"mosh anchor": "mesh_machine anchor",
"autossh -M 0 -N -L 5432:localhost:5432 anchor": "mesh_machine anchor",
} {
v := g.Judge(bash(command))
if !v.Refuse {
t.Errorf("%q was not refused", command)
continue
}
if !strings.Contains(v.Message, want) {
t.Errorf("%q: want %q in:\n%s", command, want, v.Message)
}
}
}
// **What is not a work-around passes**: git over ssh to the forge above all, and ssh beyond the mesh, and
// every command that merely mentions ssh or a machine.
func TestWhatIsNotAWorkAroundPasses(t *testing.T) {
g := guard()
for _, command := range []string{
"git push -u origin feat/x",
"git clone ssh://git@git.anchor.internal:222/novox/hq.git",
"git fetch ssh://git@git.anchor.internal:222/novox/hq.git main",
`GIT_SSH_COMMAND="ssh -i ~/.ssh/forge -o IdentitiesOnly=yes" git push origin HEAD`,
"git -c core.sshCommand='ssh -p 222' pull",
"ssh -T git@git.anchor.internal -p 222",
"ssh forge",
"scp git@git.anchor.internal:novox/hq.git .",
"ssh github.com",
"ssh -T git@github.com",
"ssh user@203.0.113.7 uptime",
"ssh -V",
"ssh-keygen -t ed25519 -f ~/.ssh/x",
"ssh-add -l",
"man ssh",
"grep -r 'ssh anchor' docs/",
`git commit -m "Stop running ssh anchor journalctl"`,
"echo anchor && journalctl --user -n 5",
"cat /etc/hosts",
"getent hosts anchor.internal",
"cp /etc/hosts /tmp/hosts.copy",
"sed -n 1,5p /etc/hosts",
"curl -s http://anchor.internal:8080/health",
"go test ./...",
} {
if v := g.Judge(bash(command)); v.Refuse {
t.Errorf("%q was refused:\n%s", command, v.Message)
}
}
if v := g.Judge(HookInput{ToolName: "Read", ToolInput: map[string]any{"file_path": "/etc/hosts"}}); v.Refuse {
t.Errorf("reading /etc/hosts was refused")
}
if v := g.Judge(HookInput{ToolName: "Write", ToolInput: map[string]any{"file_path": "/tmp/hosts"}}); v.Refuse {
t.Errorf("writing a file named hosts elsewhere was refused")
}
}
// **The local work-arounds for a mesh name are refused** with the machine's own hosts verb: writing
// /etc/hosts by any means, the agent's own Edit and Write included, and HOSTALIASES.
func TestTheLocalWorkAroundsForAMeshNameAreRefused(t *testing.T) {
g := guard()
for _, command := range []string{
"echo '10.10.0.1 anchor' | sudo tee -a /etc/hosts",
"sudo sh -c 'echo 10.10.0.1 anchor >> /etc/hosts'",
"echo x >>/etc/hosts",
"sudo sed -i 's/old/new/' /etc/hosts",
"sudo sed -Ei.bak 's/a/b/' /etc/hosts",
"sudo vim /etc/hosts",
"sudo cp /tmp/hosts /etc/hosts",
"sudo install -m 644 hosts /etc/hosts",
"HOSTALIASES=~/.hosts curl http://anchor/",
"export HOSTALIASES=/tmp/aliases",
} {
v := g.Judge(bash(command))
if !v.Refuse {
t.Errorf("%q was not refused", command)
continue
}
if !strings.Contains(v.Message, "laptop/node-hostname.add") {
t.Errorf("%q: the refusal does not name this machine's hosts verb:\n%s", command, v.Message)
}
}
for _, tool := range []string{"Edit", "Write", "MultiEdit"} {
v := g.Judge(HookInput{ToolName: tool, ToolInput: map[string]any{"file_path": "/etc/../etc/hosts"}})
if !v.Refuse || !strings.Contains(v.Message, "node-hostname.add") {
t.Errorf("%s of /etc/hosts was not refused with the verb: %+v", tool, v)
}
}
// The resolver file has no verb that replaces writing it: the refusal says to create one.
v := g.Judge(bash("echo nameserver 192.0.2.53 | sudo tee /etc/resolv.conf"))
if !v.Refuse || !strings.Contains(v.Message, "a missing tool is created") {
t.Errorf("writing the resolver file: %+v", v)
}
}
// The agent never names the operator's override, and no override lifts that refusal.
func TestACommandNamingTheOverrideIsRefused(t *testing.T) {
g := guard()
for _, command := range []string{
"export " + OverrideVar + "=because",
OverrideVar + "=x claude -p 'ssh anchor uptime'",
"env " + OverrideVar + "=1 bash",
} {
v := g.Judge(bash(command))
if !v.Refuse || v.Rule != "override-named" || v.Overridable {
t.Errorf("%q: %+v", command, v)
}
}
}
// Without the mesh's answer — a controller not asked yet — the mesh's own names are still refused.
func TestWithoutTheMeshsAnswerItsNamesAreStillRefused(t *testing.T) {
g := Guard{}
if v := g.Judge(bash("ssh anchor.internal journalctl")); !v.Refuse || !strings.Contains(v.Message, "a missing tool is created") {
t.Errorf("an internal name without data: %+v", v)
}
if v := g.Judge(bash("echo x | sudo tee -a /etc/hosts")); !v.Refuse {
t.Errorf("the hosts file without data: %+v", v)
}
}
// fakeProc lays out a process tree: the agent started with env, a shell under it, the hook under that.
func fakeProc(t *testing.T, agentEnv []string) (root string, hookParent int) {
t.Helper()
root = t.TempDir()
write := func(pid, ppid int, cmdline []string, env []string) {
dir := filepath.Join(root, strconv.Itoa(pid))
_ = os.MkdirAll(dir, 0o755)
_ = os.WriteFile(filepath.Join(dir, "cmdline"), []byte(strings.Join(cmdline, "\x00")+"\x00"), 0o644)
_ = os.WriteFile(filepath.Join(dir, "environ"), []byte(strings.Join(env, "\x00")), 0o644)
_ = os.WriteFile(filepath.Join(dir, "stat"), []byte(strconv.Itoa(pid)+" (some (odd) name) S "+strconv.Itoa(ppid)+" 1 1"), 0o644)
}
write(100, 1, []string{"/opt/claude-code/bin/claude", "--resume"}, agentEnv)
write(200, 100, []string{"/bin/sh", "-c", "hook"}, []string{OverrideVar + "=set-by-the-session"})
return root, 200
}
// **The override is the operator's, from the session as it was started, and recorded** — and a value a
// command or a setting put in the session's later environment is not it.
func TestTheOverrideIsTheOperatorsAndRecorded(t *testing.T) {
data := meshForTheGuard()
data.Log = filepath.Join(t.TempDir(), "guard.log")
path := filepath.Join(t.TempDir(), "guard.json")
raw, _ := json.Marshal(data)
_ = os.WriteFile(path, raw, 0o644)
was, wasPID := procRoot, parentPID
t.Cleanup(func() { procRoot, parentPID = was, wasPID })
run := func(command string) (int, string) {
var stderr bytes.Buffer
in, _ := json.Marshal(bash(command))
return runGuard(path, bytes.NewReader(in), &stderr), stderr.String()
}
// Not set where the session started: the later shell's value is not the operator's.
root, hook := fakeProc(t, []string{"HOME=/home/operator"})
procRoot, parentPID = root, func() int { return hook }
if code, says := run("ssh anchor journalctl"); code != 2 || !strings.Contains(says, "anchor/node-service-manager.journal") {
t.Fatalf("refused with %d: %s", code, says)
}
// Set by the operator before the session: let through, with why on record.
root, hook = fakeProc(t, []string{"HOME=/home/operator", OverrideVar + "=reading the broker's log by hand while the systemd module is down"})
procRoot, parentPID = root, func() int { return hook }
if code, says := run("ssh anchor journalctl -u nats"); code != 0 {
t.Fatalf("the operator's override was not honoured: %d %s", code, says)
}
// Never for a command naming the override itself.
if code, _ := run("export " + OverrideVar + "=x"); code != 2 {
t.Fatalf("a command naming the override passed under it: %d", code)
}
record := ReadGuardLog(data.Log, 10)
if len(record) != 3 || record[0].Decision != "refused" || record[1].Decision != "overridden" ||
!strings.Contains(record[1].Why, "systemd module is down") || record[1].Machine != "anchor" || record[2].Rule != "override-named" {
t.Fatalf("the record: %+v", record)
}
// An override that cannot be recorded is not honoured.
data.Log = filepath.Join(t.TempDir(), "no", "such", "dir", "guard.log")
raw, _ = json.Marshal(data)
_ = os.WriteFile(path, raw, 0o644)
if code, says := run("ssh anchor journalctl"); code != 2 || !strings.Contains(says, "could not be recorded") {
t.Fatalf("an override not recorded was honoured: %d %s", code, says)
}
}
// What passes is not recorded, and a guard that cannot read the call says so and blocks nothing.
func TestTheHookExitsAsTheAgentReadsIt(t *testing.T) {
path := filepath.Join(t.TempDir(), "guard.json")
_ = os.WriteFile(path, []byte(`{}`), 0o644)
var stderr bytes.Buffer
in, _ := json.Marshal(bash("git push"))
if code := runGuard(path, bytes.NewReader(in), &stderr); code != 0 || stderr.Len() != 0 {
t.Errorf("git push: %d %q", code, stderr.String())
}
if code := runGuard(path, strings.NewReader("not json"), &stderr); code != 1 {
t.Errorf("an unreadable call: %d", code)
}
}
func TestTheAgentsProcessIsKnown(t *testing.T) {
for cmdline, want := range map[string]bool{
"/opt/claude-code/bin/claude\x00--resume\x00": true,
"claude\x00": true,
"node\x00/usr/lib/node_modules/@anthropic-ai/claude-code/cli.js\x00": true,
"/usr/bin/node\x00/home/x/.local/bin/claude\x00": true,
"/bin/zsh\x00": false,
"node\x00server.js\x00": false,
"/usr/bin/claude-code-tools\x00": false,
} {
if isAgent([]byte(cmdline)) != want {
t.Errorf("%q: want %v", cmdline, want)
}
}
}
@@ -63,7 +63,7 @@ func FilesFor(p Paths) *Files {
return &Files{Home: filepath.Clean(p.Home), Account: p.Agent, Helper: &Helper{Account: p.Agent, Exe: HelperPath()}}
}
// HelperPath is the helper's binary: the guard's copy of this module's binary in the plugin, root's and
// HelperPath is the helper's binary: the plugin's copy of this module's binary in the plugin, root's and
// readable by every account, so the agent's account runs exactly what the mesh placed.
func HelperPath() string {
return filepath.Join(ManagedDir, MarketplaceDir, "plugins", Plugin, GuardDir, "guard")
@@ -4,12 +4,10 @@ package main
// address, not this shell command — generated on every render from what each seat verb and module tool
// says it replaces, so it cannot drift from the tools the mesh has.
//
// Short: a row per seat or module, its top what this machine's agent reached round most — the tools the
// guard named most often in its record.
// Short: a row per seat or module, the machines' seats first.
import (
"fmt"
"sort"
"strings"
)
@@ -31,17 +29,15 @@ func code(s string) string { return "`" + strings.ReplaceAll(s, "`", "'") + "`"
// insteadGroup is one row: a seat or a module, and its verbs that replace a command.
type insteadGroup struct {
prefix string // `<node>/node-service-manager.` or `mesh-controller.`
verbs []Replacement
refused int
prefix string // `<node>/node-service-manager.` or `mesh-controller.`
verbs []Replacement
}
// InsteadOf is the section, or "" when the mesh said nothing replaces anything — an older controller,
// or one not yet asked.
//
// One row per seat or module, every verb of it that replaces a command in the row, so a verb is never cut
// for being late in its seat's list; the rows the guard here named most come first, then the machines'
// seats, the modules' tools and the mesh's own seats in the records' order.
// for being late in its seat's list; the machines' seats first, the modules' tools and the mesh's own seats in the records' order.
func InsteadOf(m *MeshTools) string {
if m == nil || len(m.Replacements) == 0 {
return ""
@@ -64,13 +60,8 @@ func InsteadOf(m *MeshTools) string {
groups = append(groups, g)
}
g.verbs = append(g.verbs, r)
g.refused += m.Refused[r.Address]
}
}
sort.SliceStable(groups, func(i, j int) bool { return groups[i].refused > groups[j].refused })
for _, g := range groups {
sort.SliceStable(g.verbs, func(i, j int) bool { return m.Refused[g.verbs[i].Address] > m.Refused[g.verbs[j].Address] })
}
more := 0
if len(groups) > InsteadOfRows {
more = len(groups) - InsteadOfRows
@@ -97,7 +88,7 @@ func InsteadOf(m *MeshTools) string {
fmt.Fprintf(&b, "\n%d more seats and modules: `mesh_search` with the command finds the tool for it.\n", more)
}
b.WriteString("\n- **Never `ssh` to a mesh machine**, and never edit `/etc/hosts` or set `HOSTALIASES` for a mesh\n" +
" name: the guard on this session's shell refuses it and names the tool. Where no tool covers what you\n" +
" name: call the tool the table names instead. Where no tool covers what you\n" +
" need, none is worked around: say so, and the tool is created in the module that owns it, on its seat.\n")
return b.String()
}
@@ -5,6 +5,7 @@ import (
"encoding/json"
"errors"
"os"
"path/filepath"
"reflect"
"slices"
"strings"
@@ -98,16 +99,10 @@ func aCatalog() fakeCatalog {
return f
}
func resolving(name string) []string {
return map[string][]string{"anchor": {"10.10.0.1"}, "anchor.internal": {"10.10.0.1"}, "anchor.example": {"192.0.2.10"},
"laptop": {"127.0.0.1", "10.10.0.4"}}[name]
}
// Issue 1126 B13: what the mesh says of its tools and machines is read from the bus whole, never asked of the
// controller: the seats' verbs, the placed modules' own tools, every machine with its domains and addresses — a
// loopback address never one of them.
// controller: the seats' verbs and the placed modules' own tools.
func TestTheMeshsToolsAreReadFromTheBus(t *testing.T) {
m, err := ReadMeshToolsFrom(aMesh(t), aCatalog(), someSeats(), resolving)
m, err := ReadMeshToolsFrom(aMesh(t), aCatalog(), someSeats())
if err != nil {
t.Fatal(err)
}
@@ -118,12 +113,21 @@ func TestTheMeshsToolsAreReadFromTheBus(t *testing.T) {
if got := strings.Join(addresses, ","); got != "mesh-module-assigner.assignments,node-service-manager.status,node-service-manager.journal,docker.docker_logs" {
t.Errorf("replacements: %s", got)
}
t.Run("the again tool answers the operator and the healers only", func(t *testing.T) {
// An operator's session through the mesh MCP server is proved as its machine's tool runner (issue 627, issue 1966).
for caller, refused := range map[string]bool{"person.jochen": false, "shanks.node-tools": false, "shanks.mesh-healers": false,
"shanks.mesh-config": true} {
if err := seatlist.Refusal("claude_code_seat_list_again", seatListAgainCallers, caller); (err != nil) != refused {
t.Errorf("%s: refused=%v, err %v", caller, refused, err)
t.Run("the again tool answers every caller", func(t *testing.T) {
// H-A-66 (design 47 H §752): no holder keeps a callers list; the seat list's tools answer every caller.
files, _ := filepath.Glob("*.go")
for _, f := range files {
if strings.HasSuffix(f, "_test.go") {
continue
}
raw, err := os.ReadFile(f)
if err != nil {
t.Fatal(err)
}
for _, gone := range []string{"AnyPerson", "seatListAgainCallers", "seatlist.Refusal"} {
if strings.Contains(string(raw), gone) {
t.Errorf("%s still names %s", f, gone)
}
}
}
})
@@ -144,7 +148,7 @@ func TestTheMeshsToolsAreReadFromTheBus(t *testing.T) {
case <-time.After(10 * time.Second):
t.Fatalf("the seat list was not read: %+v", seatList.Status())
}
got, err := ReadMeshToolsFrom(aMesh(t), aCatalog(), definedSeats(), resolving)
got, err := ReadMeshToolsFrom(aMesh(t), aCatalog(), definedSeats())
var addrs []string
for _, r := range got.Replacements {
addrs = append(addrs, r.Address)
@@ -154,10 +158,6 @@ func TestTheMeshsToolsAreReadFromTheBus(t *testing.T) {
t.Fatalf("replacements from the bus: %v, %v", addrs, err)
}
})
if len(m.Machines) != 2 || strings.Join(m.Machines[0].Domains, ",") != "anchor.internal,anchor.example" ||
strings.Join(m.Machines[0].Addresses, ",") != "10.10.0.1,192.0.2.10" || strings.Join(m.Machines[1].Addresses, ",") != "10.10.0.4" {
t.Errorf("machines: %+v", m.Machines)
}
if m.Replacements[3].Does != "logs" || !m.Replacements[2].NodeScoped || m.Replacements[0].NodeScoped {
t.Errorf("the rows: %+v", m.Replacements)
}
@@ -166,7 +166,7 @@ func TestTheMeshsToolsAreReadFromTheBus(t *testing.T) {
// **The table is generated, not written** (novox/hq ADR 0245): what the records say a verb replaces is a row,
// the machines' seats first, and nothing is rendered where the records say nothing.
func TestTheInsteadOfTableIsGeneratedFromTheRecords(t *testing.T) {
m, _ := ReadMeshToolsFrom(aMesh(t), aCatalog(), someSeats(), resolving)
m, _ := ReadMeshToolsFrom(aMesh(t), aCatalog(), someSeats())
table := InsteadOf(&m)
for _, want := range []string{
"| `<node>/node-service-manager.` | `status` — `systemctl status`, `systemctl is-active` · `journal` — `journalctl` |",
@@ -182,14 +182,11 @@ func TestTheInsteadOfTableIsGeneratedFromTheRecords(t *testing.T) {
strings.Index(table, "docker.") > strings.Index(table, "`mesh-module-assigner.`") {
t.Errorf("not the machines' seats, then modules, then the mesh's:\n%s", table)
}
// What the guard here named most comes first: its row, and in its row its verb.
m.Refused = map[string]int{"node-service-manager.journal": 3, "mesh-module-assigner.assignments": 1}
ranked := InsteadOf(&m)
if !strings.Contains(ranked, "| `<node>/node-service-manager.` | `journal` — `journalctl` · `status`") ||
strings.Index(ranked, "`mesh-module-assigner.`") > strings.Index(ranked, "`<node>/docker.`") {
t.Errorf("not ranked by the guard's record:\n%s", ranked)
// No guard on the session's shell: the rule is the session's own, and the text claims no guard (the operator,
// 2026-11-20).
if strings.Contains(table, "guard") || !strings.Contains(table, "call the tool the table names instead") {
t.Errorf("the rule names a guard, or not the tool to call:\n%s", table)
}
m.Refused = nil
if InsteadOf(nil) != "" || InsteadOf(&MeshTools{}) != "" {
t.Error("a table from nothing")
}
@@ -216,21 +213,17 @@ func TestTheInsteadOfTableIsGeneratedFromTheRecords(t *testing.T) {
// Asked again with the same answer, nothing is written and nothing renders.
func TestTheMeshsToolsAreKeptOnlyWhenTheyChange(t *testing.T) {
p := Paths{State: t.TempDir()}
m, _ := ReadMeshToolsFrom(aMesh(t), aCatalog(), someSeats(), resolving)
m, _ := ReadMeshToolsFrom(aMesh(t), aCatalog(), someSeats())
if !KeepMeshTools(p, m) {
t.Fatal("the first answer was not kept")
}
if KeepMeshTools(p, m) {
t.Fatal("the same answer was kept again")
}
m.Machines = m.Machines[:1]
if !KeepMeshTools(p, m) || len(ReadMeshTools(p).Machines) != 1 {
m.Replacements = m.Replacements[:1]
if !KeepMeshTools(p, m) || len(ReadMeshTools(p).Replacements) != 1 {
t.Fatal("a changed answer was not kept")
}
d := GuardDataOf(Paths{State: p.State, Node: "laptop"}, ReadMeshTools(p))
if d.Node != "laptop" || len(d.Replacements) != 4 || !strings.HasSuffix(d.Log, "guard.log") {
t.Errorf("the guard's data: %+v", d)
}
}
// Where a module runs is read from the seat mesh-module-assigner's assignments (issue 1126 B13), never the controller's answer.
@@ -267,20 +260,20 @@ func TestTheMeshIsReadFromTheOwnersFirstViews(t *testing.T) {
t.Fatal(err)
}
}
want, err := ReadMeshToolsFrom(bus, aCatalog(), someSeats(), resolving)
want, err := ReadMeshToolsFrom(bus, aCatalog(), someSeats())
if err != nil {
t.Fatal(err)
}
got, err := ReadMeshToolsFrom(viewStates{r}, aCatalog(), someSeats(), resolving)
got, err := ReadMeshToolsFrom(viewStates{r}, aCatalog(), someSeats())
if err != nil || !reflect.DeepEqual(got, want) || len(got.Replacements) == 0 {
t.Fatalf("from the views: %+v, %v\nfrom the state: %+v", got, err, want)
}
// A reader not yet answered says so, and reads nothing.
// A catalog half with no first view says so, and reads no module as absent.
if _, err := ReadMeshToolsFrom(bus, fakeCatalog{notYet: errors.New("the catalog half has no first view of main yet")}, someSeats(), resolving); err == nil || !strings.Contains(err.Error(), "no first view") {
if _, err := ReadMeshToolsFrom(bus, fakeCatalog{notYet: errors.New("the catalog half has no first view of main yet")}, someSeats()); err == nil || !strings.Contains(err.Error(), "no first view") {
t.Fatalf("an unanswered catalog half: %v", err)
}
if _, err := ReadMeshToolsFrom(viewStates{newMeshViews()}, aCatalog(), someSeats(), resolving); err == nil || !strings.Contains(err.Error(), "no first view") {
if _, err := ReadMeshToolsFrom(viewStates{newMeshViews()}, aCatalog(), someSeats()); err == nil || !strings.Contains(err.Error(), "no first view") {
t.Fatalf("an unanswered first view: %v", err)
}
}
@@ -288,7 +281,7 @@ func TestTheMeshIsReadFromTheOwnersFirstViews(t *testing.T) {
// Issue 1126 B13 AC1 (ADR 0590): over the seats the mesh defines, the rendered instructions, their table among them,
// name no address of the controller, which is not placed: each job is named by the seat that owns it now.
func TestTheRenderedInstructionsNameNoControllerAddress(t *testing.T) {
m, err := ReadMeshToolsFrom(aMesh(t), aCatalog(), someSeats(), resolving)
m, err := ReadMeshToolsFrom(aMesh(t), aCatalog(), someSeats())
if err != nil {
t.Fatal(err)
}
+7 -26
View File
@@ -339,10 +339,10 @@ func tools(p Paths, servers ServerState, view *ServerView, config ConfigState, c
Description: "Claude Code on this machine as the mesh configured it: the licence it holds and when its token expires, what it reports holding, the managed files, the MCP servers registered here. Fingerprints only, never a token.",
Run: func(map[string]any) (any, error) { return status(p), nil }},
{Name: "claude_code_render",
Description: "Write Claude Code's managed directory now, from the mesh's facts, this module's settings and the servers registered here — after reading the bus again for what each tool replaces and which machines the mesh has (the instructions' table and the shell's guard).",
Description: "Write Claude Code's managed directory now, from the mesh's facts, this module's settings and the servers registered here — after reading the bus again for what each tool replaces (the instructions' table).",
Run: func(map[string]any) (any, error) {
answer := map[string]any{}
if m, err := ReadMeshToolsFrom(viewStates{meshViews}, meshCatalog, definedSeats(), lookup); err != nil {
if m, err := ReadMeshToolsFrom(viewStates{meshViews}, meshCatalog, definedSeats()); err != nil {
answer["asked"] = "the bus could not be read in full (" + err.Error() + "); what was kept is rendered"
} else {
KeepMeshTools(p, m)
@@ -351,16 +351,6 @@ func tools(p Paths, servers ServerState, view *ServerView, config ConfigState, c
answer["rendered"] = out
return answer, err
}},
{Name: "claude_code_guard",
Description: "The guard on the agent's shell on this machine (novox/hq ADR 0245): what it refuses — ssh to a mesh machine, writing /etc/hosts or /etc/resolv.conf, HOSTALIASES — the machines and the replaced commands it judges with, the \"instead of\" table rendered into the agent's instructions, and its record of what it refused and what the operator's override let through, newest last.",
Input: map[string]any{"last": map[string]any{"type": "integer", "description": "how many lines of the record (default 50)"}},
Run: func(a map[string]any) (any, error) {
last := 50
if n, ok := a["last"].(float64); ok && n > 0 {
last = int(n)
}
return GuardStatus(p, last), nil
}},
{Name: "claude_code_pull",
Description: "Ask the licence manager which licence this node holds and the vault for its access token now, and apply it, rather than waiting for its binding or the token to change.",
Run: func(map[string]any) (any, error) { return Pull(p, ask, writeManaged) }},
@@ -452,10 +442,6 @@ func persist(what string, attempt func() error, done func(refusals int)) {
}
func main() {
// The guard on the agent's shell (novox/hq ADR 0245): this binary, run by the agent's hook.
if len(os.Args) == 3 && os.Args[1] == "guard" {
os.Exit(runGuard(os.Args[2], os.Stdin, os.Stderr))
}
// The plugin's SessionStart hook (novox/hq ADR 0489 §1, issue 1744): names the session's id and its open waits.
if len(os.Args) == 3 && os.Args[1] == "session-start" {
os.Exit(runSessionStart(os.Args[2], os.Stdin, os.Stdout))
@@ -734,17 +720,12 @@ func refusals(n int) string {
return fmt.Sprintf(" (after %d refusal(s))", n)
}
// seatListAgainCallers may read the seat list again: every operator's session and the healers (ADR 0636 §7). A call through
// the mesh MCP server is proved only as its machine's tool runner (<node>.node-tools, issue 627), so node-tools stands for
// an operator's session until a session is proved (issue 1966).
var seatListAgainCallers = []string{stdio.AnyPerson, "node-tools", "mesh-healers"}
// seatListTools are the seat list reader's two tools: what the list holds and what it waits for, and a read now. The
// reader starts once the runtime serves, after the tools are listed, so each tool finds it when it is called.
// seatListTools are the seat list reader's two tools: what the list holds and what it waits for, and a read now, each
// answering every caller (design 47 H §752, H-A-66). The reader starts once the runtime serves, after the tools are
// listed, so each tool finds it when it is called.
func seatListTools() []stdio.Tool {
names := []string{"claude_code_seat_list", "claude_code_seat_list_again"}
callers := seatListAgainCallers
shape := seatlist.Tools(&seatlist.Reader{}, names[0], names[1], callers)
shape := seatlist.Tools(&seatlist.Reader{}, names[0], names[1])
for i := range shape {
run := i
shape[i].Run = func(args map[string]any) (any, error) {
@@ -754,7 +735,7 @@ func seatListTools() []stdio.Tool {
if r == nil {
return nil, errors.New("the seat list reader has not started yet: the runtime has not served this module")
}
return seatlist.Tools(r, names[0], names[1], callers)[run].Run(args)
return seatlist.Tools(r, names[0], names[1])[run].Run(args)
}
}
return shape
+18 -126
View File
@@ -1,22 +1,19 @@
package main
// What the mesh says about its own tools and machines, as the agent's instructions and the guard on its
// shell need it (novox/hq ADR 0245): every seat verb and module tool that says what shell command it
// replaces, and the mesh's machines by every name and address a session could reach one by.
// What the mesh says about its own tools, as the agent's instructions need it (novox/hq ADR 0245): every seat verb
// and module tool that says what shell command it replaces.
//
// Read from the bus at start and every few minutes (issue 1126 B13; the controller that answered this before is
// Read from the bus at start and whenever a followed state changes (issue 1126 B13; the controller that answered this before is
// not placed, novox/hq ADR 0590): the seats' verbs from the seats' contract (mesh-contracts), the modules'
// own tools from the manifests the indexer keeps (`mesh-delivery-indexer.modules` and `.manifests`), and the
// machines and where each module runs from the seat mesh-module-assigner's `assignments`. Kept in the module's state so
// own tools from the manifests the indexer keeps (`mesh-delivery-indexer.modules` and `.manifests`), and where
// each module runs from the seat mesh-module-assigner's `assignments`. Kept in the module's state so
// a render never waits for the bus, and rendered whenever it changes. Nothing here is written by hand: a verb
// that gains a `replaces` is in the next render's table and the guard's next refusal.
// that gains a `replaces` is in the next render's table.
import (
"context"
"encoding/json"
"errors"
"fmt"
"net"
"os"
"path/filepath"
"sort"
@@ -45,39 +42,13 @@ type Replacement struct {
On []string `json:"on,omitempty"`
}
// Machine is one of the mesh's machines and the names and addresses it is reached by.
type Machine struct {
Name string `json:"name"`
Domains []string `json:"domains,omitempty"`
Addresses []string `json:"addresses,omitempty"`
}
// MeshTools is what the bus said, as kept in the module's state.
type MeshTools struct {
Replacements []Replacement `json:"replacements"`
Machines []Machine `json:"machines"`
// Asked is when the bus was last read whole.
Asked string `json:"asked,omitempty"`
// Refused is how often the guard here named each tool instead of a work-around, from its record: the
// table's order. Never kept — read from the record at each render.
Refused map[string]int `json:"-"`
}
// RefusedCounts are how often the guard's record named each tool, over its last lines.
func RefusedCounts(log string) map[string]int {
out := map[string]int{}
for _, e := range ReadGuardLog(log, 2000) {
for _, t := range e.Tools {
out[t]++
}
}
return out
}
// InternalSuffix is the mesh's own names' domain: every machine and service is `<name>.internal`
// (novox/hq ADR 0194), and a session reaches none of them by ssh.
const InternalSuffix = ".internal"
func (p Paths) meshTools() string { return filepath.Join(p.State, "mesh-tools.json") }
// ReadMeshTools is what was kept, or nil.
@@ -234,17 +205,8 @@ func ReplacementsOf(defined []seatdef.Definition, modules []ModuleTools) []Repla
return out
}
// lookup resolves one name, briefly: a name that does not resolve here is no address.
func lookup(name string) []string {
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
addrs, _ := net.DefaultResolver.LookupHost(ctx, name)
return addrs
}
// ReadMeshToolsFrom reads the bus now: the seats' verbs, the placed modules' own tools, and every node assignments names
// with its domains and addresses. A part that cannot be read is left out and said in the error; what was read is kept.
func ReadMeshToolsFrom(st States, cat CatalogHalf, defined []seatdef.Definition, resolve func(string) []string) (MeshTools, error) {
// ReadMeshToolsFrom reads the bus now: the seats' verbs and the placed modules' own tools. A part that cannot be read is left out and said in the error; what was read is kept.
func ReadMeshToolsFrom(st States, cat CatalogHalf, defined []seatdef.Definition) (MeshTools, error) {
var m MeshTools
placed, err := assignments(st)
if err != nil {
@@ -253,24 +215,6 @@ func ReadMeshToolsFrom(st States, cat CatalogHalf, defined []seatdef.Definition,
}
modules, merr := modulesTools(cat, runsOn(placed))
m.Replacements = ReplacementsOf(defined, modules)
for node, p := range placed {
machine := Machine{Name: node, Domains: []string{node + InternalSuffix}}
if d := strings.ToLower(strings.TrimSpace(p.Decided.PublicDomain)); d != "" {
machine.Domains = append(machine.Domains, d)
}
seen := map[string]bool{}
for _, name := range append([]string{node}, machine.Domains...) {
for _, a := range resolve(name) {
if !seen[a] && !net.ParseIP(a).IsLoopback() {
seen[a] = true
machine.Addresses = append(machine.Addresses, a)
}
}
}
sort.Strings(machine.Addresses)
m.Machines = append(m.Machines, machine)
}
sort.Slice(m.Machines, func(i, j int) bool { return m.Machines[i].Name < m.Machines[j].Name })
return m, merr
}
@@ -295,22 +239,9 @@ func KeepMeshTools(p Paths, m MeshTools) bool {
return os.Rename(tmp, p.meshTools()) == nil
}
// GuardDataOf is what the guard judges with on this machine.
func GuardDataOf(p Paths, m *MeshTools) GuardData {
d := GuardData{Node: p.Node, Log: filepath.Join(p.State, "guard.log"), Machines: []Machine{}, Replacements: []Replacement{}}
if p.Confined() {
// The session's account cannot write the module's state, and must not rewrite its own record (ADR 0266).
d.Agent, d.Log = p.Agent, JournalRecord+GuardJournalID
}
if m != nil {
d.Machines, d.Replacements = m.Machines, m.Replacements
}
return d
}
// guardFiles is the guard to place: this module's own executable and what it judges with. None where the
// hookFiles is what the plugin's hooks run: this module's own executable and the waits directory. None where the
// executable cannot be named — then no hook is written, rather than one that cannot run.
func guardFiles(p Paths, m *MeshTools) *GuardFiles {
func hookFiles(p Paths) *HookFiles {
exe, err := os.Executable()
if err != nil {
return nil
@@ -318,18 +249,13 @@ func guardFiles(p Paths, m *MeshTools) *GuardFiles {
if resolved, err := filepath.EvalSymlinks(exe); err == nil {
exe = resolved
}
return &GuardFiles{Exe: exe, Data: GuardDataOf(p, m), WaitsDir: WaitsDirPath(p)}
return &HookFiles{Exe: exe, WaitsDir: WaitsDirPath(p)}
}
// MeshToolsEvery is how often the machines' addresses are resolved again; the tools and the assignments are read again
// when their followed states change (a views event), not on this timer.
const MeshToolsEvery = 10 * time.Minute
// MeshToolsFirst is how long the first read waits for the first views to be answered.
const MeshToolsFirst = 2 * time.Minute
// refreshMeshTools reads the pictures once the first views are answered, and again whenever one changes (and the
// machines' addresses every few minutes), and renders when what it said changed.
// refreshMeshTools reads the pictures once the first views are answered, and again whenever one changes, and renders when what it said changed.
func refreshMeshTools(p Paths) {
select {
case <-meshViews.Ready():
@@ -338,60 +264,26 @@ func refreshMeshTools(p Paths) {
}
startSeatList(seatlist.StdioBus())
for {
m, err := ReadMeshToolsFrom(viewStates{meshViews}, meshCatalog, definedSeats(), lookup)
m, err := ReadMeshToolsFrom(viewStates{meshViews}, meshCatalog, definedSeats())
if err != nil {
say("reading what each tool replaces and which machines the mesh has: %v", err)
say("reading what each tool replaces: %v", err)
}
if (err == nil || len(m.Replacements) > 0) && KeepMeshTools(p, m) {
if _, err := RenderNow(p, writeManaged); err != nil {
say("rendering what the bus said of the tools: %v", err)
} else {
say("the mesh's tools changed: %d replace a command, %d machines; rendered", len(m.Replacements), len(m.Machines))
say("the mesh's tools changed: %d replace a command; rendered", len(m.Replacements))
}
}
<-meshChanged
time.Sleep(2 * time.Second) // a burst of events is one read
select {
case <-meshChanged:
time.Sleep(2 * time.Second) // a burst of events is one read
select {
case <-meshChanged:
default:
}
case <-time.After(MeshToolsEvery):
default:
}
}
}
// GuardStatus is what claude_code_guard answers.
func GuardStatus(p Paths, last int) map[string]any {
m := ReadMeshTools(p)
d := GuardDataOf(p, m)
asked := "never: the bus has not been read whole yet"
if m != nil {
asked = m.Asked
}
return map[string]any{
"refuses": []string{
"ssh, scp, sftp, rsync, mosh or autossh to a mesh machine: its name, a name under its domains, any *" + InternalSuffix +
" name or one of its addresses, read as ssh reads it (ssh -G); a jump through one too. An ssh login as `" +
ForgeUser + "` is the forge's account and passes",
"writing /etc/hosts or /etc/resolv.conf, by the shell or the agent's Edit and Write",
"HOSTALIASES, named anywhere in a command",
"any command naming " + OverrideVar,
"where the machine names an agent account of its own (novox/hq ADR 0266): every command and file edit of a " +
"session that does not run as it, whatever it is, and no override lifts it",
},
"agent_account": map[bool]string{true: p.Agent, false: "none of its own: agents run as the operator's account"}[p.Confined()],
"override": OverrideVar + "=<why>, set in the operator's own shell before the session starts; read from the session's " +
"environment as it was started, recorded with why, and not honoured when it cannot be recorded",
"hook": GuardCommand(),
"asked": asked,
"machines": d.Machines,
"replacements": d.Replacements,
"instead_of": InsteadOf(m),
"record": ReadGuardLog(d.Log, last),
}
}
// seatList is the seat list this module holds: the definitions of the seats, read from the seat mesh-catalog and
// followed on its events (novox/hq ADR 0635 §1, ADR 0636), the foundation's bootstrapped ones until it answers.
var seatList *seatlist.Reader
+52 -8
View File
@@ -24,6 +24,7 @@ import (
"encoding/json"
"errors"
"fmt"
"log"
"os"
"path/filepath"
"regexp"
@@ -84,8 +85,8 @@ func PathsFrom(env func(string) string) (Paths, bool) {
Agent: env("MESH_AGENT_ACCOUNT"), Operator: env("MESH_OPERATOR_ACCOUNT"),
AgentHome: env("MESH_AGENT_HOME"), OperatorHome: env("MESH_OPERATOR_HOME")}
if (p.Home == "") != (p.Agent == "") {
// Half of the agent's account is not "the operator's": taken so, the agent's account rule of the guard
// would be off and its home never written, and nothing would say so. Not launched, said (main).
// Half of the agent's account is not "the operator's": taken so, the agent's
// home would never be written, and nothing would say so. Not launched, said (main).
return p, false
}
if p.Home == "" {
@@ -143,6 +144,7 @@ func HomeScopeRefused(p Paths, target string) string {
func (p Paths) credentials() string { return filepath.Join(p.Home, ".claude", ".credentials.json") }
func (p Paths) account() string { return filepath.Join(p.Home, ".claude.json") }
func (p Paths) binding() string { return filepath.Join(p.State, "licence.json") }
func (p Paths) handed() string { return filepath.Join(p.State, "login-handed") }
func (p Paths) apiKey() string { return filepath.Join(p.keyDir(), "api-key") }
func (p Paths) helper() string { return filepath.Join(p.keyDir(), "api-key-helper") }
@@ -256,11 +258,8 @@ func RenderNow(p Paths, write WriteManaged) ([]string, error) {
config.Approved = ApprovedHere(approved, p.Node)
}
mesh := ReadMeshTools(p)
if mesh != nil {
mesh.Refused = RefusedCounts(GuardDataOf(p, mesh).Log)
}
files := RenderWithMesh(facts, settings, binding, p.helperCommand(), Registered(p), config, mesh)
tree, _ := json.Marshal(MarketplaceWith(config, guardFiles(p, mesh)))
tree, _ := json.Marshal(MarketplaceWith(config, hookFiles(p)))
files[MarketplaceDir+"/"] = string(tree)
names := make([]string, 0, len(files))
for n := range files {
@@ -418,9 +417,26 @@ func GrantFor(p Paths, managerPublicKey string) (GrantAnswer, error) {
if err != nil {
return GrantAnswer{}, err
}
// Which login was handed: only its successor may replace it (ADR 0206, ADR 0209). The fingerprint, never
// the token.
if err := fsys.MkdirAll(p.State, 0o700); err != nil {
return GrantAnswer{}, err
}
if err := fsys.WriteFile(p.handed(), []byte(Fingerprint(rt)+"\n"), 0o600); err != nil {
return GrantAnswer{}, err
}
return GrantAnswer{Sealed: &box, Identity: ReadIdentity(p.account()), Fingerprint: Fingerprint(rt)}, nil
}
// readHanded is the fingerprint of the login last handed to the manager, or "".
func readHanded(p Paths) string {
raw, err := fsys.ReadFile(p.handed())
if err != nil {
return ""
}
return strings.TrimSpace(string(raw))
}
// Pull asks the seat which licence this node holds, then the vault for that licence's access secret, sealed to this
// module's key, and applies it (§19).
func Pull(p Paths, ask Ask, write WriteManaged) (map[string]any, error) {
@@ -609,9 +625,37 @@ func Apply(p Paths, c Current, sealed SealedBox, write WriteManaged) (map[string
return nil, err
}
local := ReadCredentials(p.credentials())
// A login waiting here was handed to the manager first (ADR 0206): what comes back is its successor,
// and the refresh token in the file is the one the manager just spent.
// A login made here that the manager has not adopted yet stays whole: the grant handed is the old
// lineage's, and writing it would spend the person's login unseen (ADR 0206, ADR 0209). The manager
// asks claude_code_grant for it on this node's report; its successor then comes as a newer generation.
// This return skips the binding's generation below on purpose: later binding events pull again until
// the manager adopts the login.
// The latest login wins (design 39 §6): a lease of the same account that succeeds the login (H-A-139) —
// the manager adopted a later login to that account from another node — replaces it, said as "login
// superseded"; a login to another account than the lease's licence is always kept (H-A-140, hq
// design/47-H1-answers-59 b75d1386).
superseded := false
if LoginNotHanded(local, readHanded(p)) {
id := ReadIdentity(p.account())
if id == nil || id.EmailAddress == "" || id.EmailAddress != c.Licence || !Succeeds(local, g) {
log.Printf("login kept: the login in the credentials file was not handed to the manager yet (licence %s)", c.Licence)
return map[string]any{"applied": false, "licence": c.Licence, "reason": LoginKept}, nil
}
superseded = true
log.Printf("login superseded: a later login to the account of licence %s was adopted by the manager (generation %d)", c.Licence, c.Generation)
}
// A login handed to the manager is replaced only by a grant of a newer lineage (its refresh token's
// expiry later than the login's, or the same lineage with a later access expiry, as the manager's refresh yields it): a lease older than the login is never
// written, so the manager's failed refresh is a finding on the manager, never a lost login here
// (H-A-138, hq design/47-H1-answers-59 175ed320; H-A-139, e359911e).
if HoldsLogin(local) && !Succeeds(local, g) {
log.Printf("login kept: the grant offered for licence %s does not succeed the login in the credentials file", c.Licence)
return map[string]any{"applied": false, "licence": c.Licence, "reason": LoginKept}, nil
}
d := DecideApply(GrantOf(local), g, switched || HoldsLogin(local))
if d.Apply && superseded {
out["reason"] = "login superseded"
}
if d.Apply {
next := WithGrant(local, g)
if switched {
@@ -114,7 +114,7 @@ func TestSessionStartRejectsAnUnsafeSessionID(t *testing.T) {
}
// 1744/AC4 is checked together with 1743/AC7 in terminal_only_test.go's
// TestThePluginsOnlyHooksAreTheGuardTheSessionStartHookAndTheStopHook.
// TestThePluginsOnlyHooksAreTheSessionStartHookAndTheStopHook.
// ADR 0490 §2: every session start lists every name on this node with an open wait, from the node-wide
// index, with the exact adopt call to make if it is yours — read directly, never by calling back into this
@@ -320,9 +320,9 @@ func TestWaitBlocksStopAdvisesMeshWaitOnItsEventOtherwiseAWatcher(t *testing.T)
}
}
// 1743/AC7's rendering half (hooks.json holds the guard's PreToolUse entry and the Stop entry) is checked
// 1743/AC7's rendering half (hooks.json holds the Stop entry) is checked
// together with 1744/AC4 in terminal_only_test.go's
// TestThePluginsOnlyHooksAreTheGuardTheSessionStartHookAndTheStopHook. claude_code_hook_register still
// TestThePluginsOnlyHooksAreTheSessionStartHookAndTheStopHook. claude_code_hook_register still
// refuses a Stop hook (or any other) at every scope.
func TestHookRegisterStillRefusesEveryHook(t *testing.T) {
p, _ := node(t, "laptop")
@@ -261,12 +261,13 @@ func TestTheOperatorsManagedSettingsAreWhatSessionsObey(t *testing.T) {
}
}
// The plugin's only hooks are the guard, the session-start hook and the Stop hook (novox/hq ADR 0245, ADR
// 0489) — never a hook a registration named, whatever the configuration given holds (novox/hq issue 340).
func TestThePluginsOnlyHooksAreTheGuardTheSessionStartHookAndTheStopHook(t *testing.T) {
// The plugin's only hooks are the session-start hook and the Stop hook (novox/hq ADR 0489) — no guard on the
// shell (the operator, 2026-11-20), and never a hook a registration named, whatever the configuration given holds
// (novox/hq issue 340).
func TestThePluginsOnlyHooksAreTheSessionStartHookAndTheStopHook(t *testing.T) {
c := Config{Mesh: []Item{{Kind: KindHook, Name: "planted", Scope: ScopeMesh, Event: "PreToolUse", Matcher: "Bash",
Command: "${HOOK_DIR}/x.sh", Files: map[string]string{"x.sh": "#!/bin/sh\n"}}}}
plugin := MarketplaceWith(c, &GuardFiles{Exe: "/bin/true", WaitsDir: "/home/agent/.claude/nox-mesh/waits"})
plugin := MarketplaceWith(c, &HookFiles{Exe: "/bin/true", WaitsDir: "/home/agent/.claude/nox-mesh/waits"})
root := "plugins/" + Plugin + "/"
var hooks struct {
Hooks map[string][]struct {
@@ -279,9 +280,14 @@ func TestThePluginsOnlyHooksAreTheGuardTheSessionStartHookAndTheStopHook(t *test
if err := json.Unmarshal([]byte(plugin[root+"hooks/hooks.json"].Content), &hooks); err != nil {
t.Fatal(err)
}
if len(hooks.Hooks) != 3 || len(hooks.Hooks["PreToolUse"]) != 1 || hooks.Hooks["PreToolUse"][0].Matcher != GuardMatcher ||
hooks.Hooks["PreToolUse"][0].Hooks[0].Command != GuardCommand() {
t.Fatalf("the guard's hook: %s", plugin[root+"hooks/hooks.json"].Content)
if len(hooks.Hooks) != 2 || hooks.Hooks["PreToolUse"] != nil {
t.Fatalf("a hook beside the session-start and Stop hooks: %s", plugin[root+"hooks/hooks.json"].Content)
}
if plugin[root+GuardDir+"/guard"].From != "/bin/true" {
t.Fatalf("the binary the hooks run is not placed: %+v", plugin[root+GuardDir+"/guard"])
}
if _, ok := plugin[root+GuardDir+"/guard.json"]; ok {
t.Fatal("the guard's data is placed")
}
if len(hooks.Hooks["SessionStart"]) != 1 || hooks.Hooks["SessionStart"][0].Matcher != "startup|resume|clear|compact" ||
hooks.Hooks["SessionStart"][0].Hooks[0].Command != SessionStartCommand("/home/agent/.claude/nox-mesh/waits") {
+1 -1
View File
@@ -20,7 +20,7 @@ package main
// Every file lives under the agent's home (the manifest's `agent-home` resource), which this process —
// launched as the operator's account (novox/hq ADR 0193) — cannot itself write when the node names an agent
// account of its own (novox/hq ADR 0266): every write below goes through `fsys` (homefs.go), which already
// carries such a write through the sudo helper the guard's binary also serves, exactly as grant.go's
// carries such a write through the sudo helper this module's binary serves, exactly as grant.go's
// WriteCredentials does for the agent's own credentials file. Where the node has no agent account of its
// own, fsys is the plain filesystem and the write reaches the operator's own home directly.
+1 -5
View File
@@ -5,9 +5,5 @@ agent='${machine:agent-account}'
if [ "$(id -un)" = "$agent" ]; then
exec claude "$@"
fi
# Another account, the operator's, becomes the agent's through its own sudo: the person is the authority. The
# operator's override of the guard travels only when it is set in this shell, as it would reach claude.
if [ -n "$MESH_GUARD_OVERRIDE" ]; then
exec sudo -iu "$agent" env MESH_GUARD_OVERRIDE="$MESH_GUARD_OVERRIDE" claude "$@"
fi
# Another account, the operator's, becomes the agent's through its own sudo: the person is the authority.
exec sudo -iu "$agent" claude "$@"
+3 -3
View File
@@ -1,6 +1,7 @@
{
"module": "claude-code",
"version": "0.1",
"class": "leaf",
"moved": true,
"slug": "agent",
"capabilities": [
@@ -23,7 +24,7 @@
"findings-stated.*"
],
"max-age-days": 7,
"max-mib": 16
"max-mib": 8
}
},
{
@@ -63,7 +64,7 @@
"mesh-catalog.seat-definition-removed",
"mesh-conditions.findings-asked",
"claude-licence-manager.holdings.asked",
"claude-licence-manager.binding.changed",
"claude-licence-manager.binding.changed.*",
"mesh-vault.secret-changed"
],
"state": [
@@ -82,7 +83,6 @@
"tools": [
"claude_code_status",
"claude_code_render",
"claude_code_guard",
"claude_code_pull",
"claude_code_grant",
"claude_code_add_api_key",
@@ -1,6 +1,7 @@
{
"module": "claude-licence-manager",
"version": "0.1",
"class": "core",
"slug": "licmgr",
"runs-as": "claude-licence-manager",
"requires": [
+1
View File
@@ -1,6 +1,7 @@
{
"module": "clipmenu",
"version": "0.1",
"class": "core",
"moved": true,
"capabilities": [
"package-manager"
+1
View File
@@ -1,6 +1,7 @@
{
"module": "confluence",
"version": "0.1",
"class": "leaf",
"slug": "confl",
"own-secrets": {
"token": "${dir:state}/token"
+1
View File
@@ -1,6 +1,7 @@
{
"module": "cups",
"version": "0.1",
"class": "leaf",
"capabilities": [
"package-manager",
"service-manager"
+1
View File
@@ -1,6 +1,7 @@
{
"module": "dbus",
"version": "0.1",
"class": "core",
"capabilities": [
"package-manager",
"service-manager"
+1
View File
@@ -1,6 +1,7 @@
{
"module": "desk-channel",
"version": "0.1",
"class": "core",
"slug": "desk",
"runs-as": "desk-channel",
"claims": [
+1
View File
@@ -1,6 +1,7 @@
{
"module": "dev-tools",
"version": "0.1",
"class": "leaf",
"capabilities": [
"package-manager"
],
+10
View File
@@ -1,6 +1,7 @@
{
"module": "disk-load",
"version": "0.1",
"class": "leaf",
"tools": [
"disk_load",
"disk_top",
@@ -24,6 +25,15 @@
"loads": [
"disk-load"
]
},
{
"name": "diskreadings",
"kind": "package",
"language": "go",
"paths": [
"diskreadings"
],
"series": "0.1"
}
]
},
@@ -0,0 +1,136 @@
package main
import (
"fmt"
"time"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/parts"
"distribution/internal/holder"
)
// stepBound bounds each bus operation of a publish well under the tool runner's 30 s call bound, so a hang is an error
// naming its step and the publish answers with it.
const stepBound = 10 * time.Second
// step runs f, logs its start and its end with its time, and gives up on it after bound: the error names the step. A step
// given up on is not cancelled (the SDK's bus calls take no context): its call ends at the SDK's own bound of the ask, and
// the log says, by the step's name, that it was given up and later when the call behind it ended and how (A-443, A-443a).
func step[T any](bound time.Duration, what string, f func() (T, error)) (T, error) {
type res struct {
v T
err error
}
start := time.Now()
logf("step %s starts", what)
ch := make(chan res, 1)
go func() { v, err := f(); ch <- res{v, err} }()
select {
case r := <-ch:
logf("step %s ended after %s (%v)", what, time.Since(start).Round(time.Millisecond), r.err)
return r.v, r.err
case <-time.After(bound):
var zero T
err := fmt.Errorf("%s did not answer within %s", what, bound)
logf("step %s: %v; given up, its call is left to end at the SDK's own bound", what, err)
go func() {
r := <-ch
logf("step %s, given up after %s: its call ended after %s (%v)", what, bound, time.Since(start).Round(time.Millisecond), r.err)
}()
return zero, err
}
}
func stepErr(bound time.Duration, what string, f func() error) error {
_, err := step(bound, what, func() (struct{}, error) { return struct{}{}, f() })
return err
}
// boundedObjects is the incoming object store with each operation bounded and logged. Purge is the store's purge of a
// deleted object's chunks (busstate.Objects.Purge): every delete of a chunk is followed by it, so what a delete left
// behind is dropped and the store's kept descriptions equal its live objects (design 47 H2 §813 (8); H-A-227, H-A-366).
type boundedObjects struct {
parts.Objects
Purge func(name string) error
}
func (b boundedObjects) Used() (uint64, error) {
return step(stepBound, "the incoming object store's fill (objects)", b.Objects.Used)
}
func (b boundedObjects) Put(name string, data []byte) error {
return stepErr(stepBound, "the put of a chunk in the incoming object store (objects)", func() error { return b.Objects.Put(name, data) })
}
func (b boundedObjects) Get(name string) ([]byte, error) {
return step(stepBound, "the get of a chunk from the incoming object store (objects)", func() ([]byte, error) { return b.Objects.Get(name) })
}
func (b boundedObjects) Delete(name string) error {
err := stepErr(stepBound, "the delete of a chunk in the incoming object store (objects)", func() error { return b.Objects.Delete(name) })
if b.Purge == nil {
return err
}
perr := stepErr(stepBound, "the purge of a deleted chunk's leftovers in the incoming object store (objects)", func() error { return b.Purge(name) })
if err != nil {
return err
}
return perr
}
// boundedTransfers is the transfers state with its reads and writes bounded and logged.
type boundedTransfers struct {
parts.Transfers[holder.Opening]
}
func (b boundedTransfers) Get(id string) (parts.Transfer[holder.Opening], bool, error) {
type r struct {
t parts.Transfer[holder.Opening]
ok bool
}
x, err := step(stepBound, "the read of the transfer in the transfers state", func() (r, error) {
t, ok, err := b.Transfers.Get(id)
return r{t, ok}, err
})
return x.t, x.ok, err
}
func (b boundedTransfers) Put(t parts.Transfer[holder.Opening]) error {
return stepErr(stepBound, "the write of the transfer in the transfers state", func() error { return b.Transfers.Put(t) })
}
func (b boundedTransfers) Delete(id string) error {
return stepErr(stepBound, "the delete of the transfer in the transfers state", func() error { return b.Transfers.Delete(id) })
}
// boundedCap is the incoming cap read from its binding, bounded and logged.
func boundedCap(c func() (uint64, error)) func() (uint64, error) {
return func() (uint64, error) {
return step(stepBound, "the read of incoming's cap from its binding (objects)", c)
}
}
// boundedArm is the idle key's write, bounded and logged.
func boundedArm(a func(string, time.Duration) error) func(string, time.Duration) error {
return func(id string, ttl time.Duration) error {
return stepErr(stepBound, "the write of the idle key in the idle state", func() error { return a(id, ttl) })
}
}
// boundedFinding is the findings writer's say moved off the publish's path: the receiver says the incoming fill on every
// open, and a publish never waits for it. One worker says them in order, each bounded and logged; one said while the worker
// is full is dropped and logged (the next open says the fill again).
func boundedFinding(f holder.Finding) holder.Finding {
type said struct {
kind, subject, words string
raised bool
}
queue := make(chan said, 64)
go func() {
for s := range queue {
_ = stepErr(stepBound, "the finding "+s.kind+" of "+s.subject, func() error { f(s.kind, s.subject, s.words, s.raised); return nil })
}
}()
return func(kind, subject, words string, raised bool) {
select {
case queue <- said{kind, subject, words, raised}:
default:
logf("the finding %s of %s is not said now: the writer is behind, the next open says it again", kind, subject)
}
}
}
@@ -0,0 +1,106 @@
package main
import (
"fmt"
"strings"
"sync"
"testing"
"time"
)
// The incoming store's steps (design 47 H2 §819: one test function for the bounded steps).
func TestTheBoundedSteps(t *testing.T) {
t.Run("a hung step answers with its name", hungStepAnswersWithItsName)
t.Run("a given-up step says when its call ended", givenUpStepSaysWhenItsCallEnded)
t.Run("a deleted chunk is purged", deletedChunkIsPurged)
t.Run("a finding is said off the path", findingIsSaidOffThePath)
}
// A bus operation that never answers becomes an error naming its step, within the bound.
func hungStepAnswersWithItsName(t *testing.T) {
block := make(chan struct{})
defer close(block)
_, err := step(10*time.Millisecond, "the write of the idle key", func() (int, error) { <-block; return 0, nil })
if err == nil || !strings.Contains(err.Error(), "the write of the idle key did not answer within") {
t.Fatalf("err = %v", err)
}
if v, err := step(time.Second, "x", func() (int, error) { return 7, nil }); v != 7 || err != nil {
t.Fatalf("%d %v", v, err)
}
}
// A step given up on is said given up by name, and the log says later when the call behind it ended and how (A-443a).
func givenUpStepSaysWhenItsCallEnded(t *testing.T) {
var mu sync.Mutex
var lines []string
ended := make(chan struct{})
w := func(f string, a ...any) {
l := fmt.Sprintf(f, a...)
mu.Lock()
lines = append(lines, l)
mu.Unlock()
if strings.Contains(l, "the put of a chunk") && strings.Contains(l, "its call ended after") {
close(ended)
}
}
old := logTo.Swap(&w)
defer logTo.Store(old)
release := make(chan struct{})
if _, err := step(10*time.Millisecond, "the put of a chunk", func() (int, error) { <-release; return 0, fmt.Errorf("bus closed") }); err == nil {
t.Fatal("not given up")
}
close(release)
<-ended
mu.Lock()
all := strings.Join(lines, "\n")
mu.Unlock()
if !strings.Contains(all, "given up") || !strings.Contains(all, "bus closed") {
t.Fatalf("log: %s", all)
}
}
// The finding is said off the caller's path: a writer that never answers does not hold the call that says it.
func findingIsSaidOffThePath(t *testing.T) {
block := make(chan struct{})
defer close(block)
say := boundedFinding(func(string, string, string, bool) { <-block })
done := make(chan struct{})
go func() {
say("incoming-full", "incoming", "w", false)
say("incoming-full", "incoming", "w", false)
close(done)
}()
select {
case <-done:
case <-time.After(5 * time.Second):
t.Fatal("the call was held by the finding")
}
}
// fakeObjects is an object store that counts deletes.
type fakeObjects struct{ deleted []string }
func (f *fakeObjects) Put(string, []byte) error { return nil }
func (f *fakeObjects) Get(string) ([]byte, error) { return nil, nil }
func (f *fakeObjects) Delete(name string) error { f.deleted = append(f.deleted, name); return nil }
func (f *fakeObjects) Used() (uint64, error) { return 0, nil }
// Every delete of a chunk purges what it left behind, so the store's kept descriptions equal its live objects (design 47
// H2 §813 (8)); a purge's failure is said, never swallowed.
func deletedChunkIsPurged(t *testing.T) {
f := &fakeObjects{}
var purged []string
b := boundedObjects{f, func(name string) error { purged = append(purged, name); return nil }}
for i := range 1000 {
if err := b.Delete(fmt.Sprintf("chunk.%d", i)); err != nil {
t.Fatal(err)
}
}
if len(f.deleted) != 1000 || len(purged) != 1000 || purged[999] != "chunk.999" {
t.Fatalf("deleted %d, purged %d", len(f.deleted), len(purged))
}
b.Purge = func(string) error { return fmt.Errorf("no responders") }
if err := b.Delete("chunk.x"); err == nil || !strings.Contains(err.Error(), "no responders") {
t.Fatalf("a failed purge answered %v", err)
}
}
@@ -40,11 +40,15 @@ func partAnswer(in reg.PublishPartInput, a holder.PublishAnswer) reg.PublishPart
return reg.PublishPartAnswer{Transfer: in.Transfer, Part: in.Part, Received: in.Sequence + 1, Complete: a.Ended}
}
// versionsAnswer is `versions`: each version with the digest the store holds under it.
// versionsAnswer is `versions`: each version with the digest its reference names (holder.Verbs.VersionDigest).
func versionsAnswer(v *holder.Verbs, kind string, a holder.VersionsAnswer) reg.VersionsAnswer {
out := reg.VersionsAnswer{Name: a.Name, Versions: []reg.Artifact{}}
for _, ver := range a.Versions {
d, _ := v.Catalog.Digest(a.Name, ver)
d, err := v.VersionDigest(a.Seat, a.Name, ver)
if err != nil {
// The contract's answer has no field for why; the version is answered with no digest and the reason said here.
logf("versions: %s %s on %s answers no digest: %v", a.Name, ver, a.Seat, err)
}
out.Versions = append(out.Versions, reg.Artifact{Name: a.Name, Version: ver, Digest: d, Kind: kind})
}
return out
@@ -12,6 +12,12 @@ import (
"distribution/internal/holder"
)
// twoDigests is a store whose every version's manifest digest and blob differ.
type twoDigests struct{ holder.Catalog }
func (twoDigests) Digest(string, string) (string, error) { return "sha256:manifest", nil }
func (twoDigests) Blob(string, string) (string, error) { return "sha256:blob", nil }
func jsonFields(v any) map[string]bool {
out := map[string]bool{}
t := reflect.TypeOf(v)
@@ -30,7 +36,7 @@ func TestTheVerbsSpeakTheSeatsContract(t *testing.T) {
reg.VerbVersions: reg.VersionsInput{}, reg.VerbRemove: reg.RemoveInput{}, reg.VerbHold: reg.HoldInput{},
reg.VerbRelease: reg.ReleaseInput{}, reg.VerbMirror: reg.MirrorInput{}, reg.VerbTags: reg.TagsInput{}}
seen := 0
for _, tool := range tools(&holder.Verbs{}, kept[holder.Window]{}) {
for _, tool := range tools(&holder.Verbs{}, kept[holder.Window]{}, nil) {
seat, verb, ok := strings.Cut(tool.Name, ".")
in, isVerb := inputs[verb]
if !ok || !isVerb || (seat != holder.ImageSeat && seat != holder.ArtifactSeat) {
@@ -59,6 +65,14 @@ func TestTheVerbsSpeakTheSeatsContract(t *testing.T) {
if a := publishAnswer(holder.PublishAnswer{Transfer: "t", Missing: []string{"sha256:bb"}}); !reflect.DeepEqual(a.Lacks, []string{"sha256:bb"}) || a.Held {
t.Errorf("publish answers %+v", a)
}
// versions answers the digest a reference names (design 47 G A-430a): the blob on the artifact seat, the manifest on the image seat.
cat := twoDigests{}
for _, c := range []struct{ seat, want string }{{holder.ArtifactSeat, "sha256:blob"}, {holder.ImageSeat, "sha256:manifest"}} {
got := versionsAnswer(&holder.Verbs{Catalog: cat}, "", holder.VersionsAnswer{Seat: c.seat, Name: "m/files", Versions: []string{"0.1.7"}})
if len(got.Versions) != 1 || got.Versions[0].Digest != c.want || got.Versions[0].Version != "0.1.7" {
t.Errorf("versions on %s answers %+v, want digest %s", c.seat, got.Versions, c.want)
}
}
if r, err := partOf(reg.PublishPartInput{Transfer: "t", Part: "sha256:bb", Data: "aGk=", Last: true}); err != nil || string(r.Data) != "hi" || r.Digest != "sha256:bb" {
t.Errorf("publish-part read %+v, %v", r, err)
}
@@ -16,20 +16,30 @@ import (
"os"
"strings"
"sync"
"sync/atomic"
"time"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
meshconditions "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
reg "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/containerimageregistry"
oci "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/ociartifactregistry"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/parts"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/seatlist"
"git.novox.be/novox/mesh-sdk/go/busstate"
"git.novox.be/novox/mesh-sdk/go/views"
"distribution/internal/holder"
)
func logf(format string, a ...any) { fmt.Fprintf(os.Stderr, "[distribution-tools] "+format+"\n", a...) }
// logTo is where logf writes; a test replaces it (atomically: a step given up on logs from its own goroutine).
var logTo atomic.Pointer[func(string, ...any)]
func init() {
w := func(format string, a ...any) { fmt.Fprintf(os.Stderr, "[distribution-tools] "+format+"\n", a...) }
logTo.Store(&w)
}
func logf(format string, a ...any) { (*logTo.Load())(format, a...) }
// kept is one state of distribution's, through the runtime.
type kept[T any] struct {
@@ -234,7 +244,7 @@ func arg[T any](args map[string]any) (T, error) {
func str(args map[string]any, k string) string { s, _ := args[k].(string); return strings.TrimSpace(s) }
// tools are distribution's tools over v.
func tools(v *holder.Verbs, windows kept[holder.Window]) []stdio.Tool {
func tools(v *holder.Verbs, windows kept[holder.Window], taken *asks) []stdio.Tool {
obj := func(props map[string]any, req ...string) map[string]any {
return map[string]any{"type": "object", "required": req, "properties": props}
}
@@ -249,10 +259,23 @@ func tools(v *holder.Verbs, windows kept[holder.Window]) []stdio.Tool {
if err != nil {
return nil, err
}
a, err := v.Publish(seat, stdio.CallerOf(args), publishOf(in))
caller := stdio.CallerOf(args)
start := time.Now()
logf("%s.publish received from %s: %s %s (%s, %d parts)", seat, caller, in.Name, in.Version, in.Kind, len(in.Parts))
r := publishOf(in)
a, err := taken.once(seat, stdio.AskIDOf(args), func() (holder.PublishAnswer, error) { return v.Publish(seat, caller, r) },
func() (holder.PublishAnswer, error) { return v.Repeat(seat, caller, r) })
if err == nil {
learnPublishing(windows, stdio.CallerOf(args))
// The window's learning asks the delivery view (up to 60 s, past the runner's 30 s call bound),
// so it never holds the answer.
go func() {
t := time.Now()
logf("learning the publishing build of %s starts (mesh-delivery-view.node_haves)", caller)
learnPublishing(windows, caller)
logf("learning the publishing build of %s ended after %s", caller, time.Since(t).Round(time.Millisecond))
}()
}
logf("%s.publish from %s answered after %s (error: %v)", seat, caller, time.Since(start).Round(time.Millisecond), err)
return publishAnswer(a), err
}},
stdio.Tool{Name: seat + "." + holder.VerbPublishPart, Description: "Send one chunk (at most 1 MiB) of one part of an open transfer, from the caller that opened it.",
@@ -291,15 +314,7 @@ func tools(v *holder.Verbs, windows kept[holder.Window]) []stdio.Tool {
}
return reg.RemoveAnswer{Removed: got.Removed, Kept: got.Kept, Reason: got.Reason, Tags: got.Tags, Artifact: &reg.Artifact{Name: in.Name, Version: in.Version, Tag: in.Tag, Digest: in.Digest}}, nil
}},
stdio.Tool{Name: seat + "." + holder.VerbList, Description: "What the store holds of one repository, or of every repository the seat holds: each manifest's digest, whether it is an index and the manifests it names, the tags naming it, its size and whether it is held (ADR 0632 §3). Read from the store's own files; changes nothing.",
Input: obj(map[string]any{"name": s("<module>/<artifact>; every repository when not given")}),
Run: func(args map[string]any) (any, error) {
repos, err := v.List(context.Background(), seat, stdio.CallerOf(args), str(args, "name"))
if err != nil {
return nil, err
}
return reg.ListAnswer{Repositories: repos}, nil
}},
listTool(v, seat),
stdio.Tool{Name: seat + "." + holder.VerbHold, Description: "Keep one untagged bundle, archive or copied base from retention (the artifact sweep alone); says held.",
Input: obj(map[string]any{"name": s("name"), "digest": s("sha256:…"), "reason": s("which of the sweep's rules keeps it")}, "name", "digest", "reason"),
Run: func(args map[string]any) (any, error) {
@@ -468,11 +483,11 @@ func main() {
}()
base, _ := url.Parse("http://127.0.0.1:5001")
store := &holder.OCI{Base: base, Upstream: &holder.Upstream{}}
h := &holder.Holder{Objects: parts.BusObjects(holder.IncomingObjects), Builder: holder.Reserved{Ask: stdio.Ask}, Store: store, Say: say, Finding: findings.Say,
Transfers: parts.BusTransfers[holder.Opening](holder.TransfersState), Cap: parts.BusCap(holder.IncomingObjects), Record: recordAct, Idle: parts.BusArm(holder.IdleState)}
h := &holder.Holder{Logf: logf, Objects: boundedObjects{parts.BusObjects(holder.IncomingObjects), busstate.ObjectsOf(holder.IncomingObjects).Purge}, Builder: holder.Reserved{Ask: stdio.Ask}, Store: store, Say: say, Finding: boundedFinding(findings.Say),
Transfers: boundedTransfers{parts.BusTransfers[holder.Opening](holder.TransfersState)}, Cap: boundedCap(parts.BusCap(holder.IncomingObjects)), Record: recordAct, Idle: boundedArm(parts.BusArm(holder.IdleState))}
files := &holder.Files{Container: or(os.Getenv("MESH_REGISTRY_CONTAINER"), "mesh-registry"), Run: holder.ExecRunner, UID: os.Getuid()}
v := &holder.Verbs{Holder: h, Catalog: store, Holds: kept[holder.Hold]{state: "holds", key: holder.Hold.Key}, Mirrors: mirrors{},
Files: files, SweepHolder: func() (string, error) { return seatlist.HolderOf(stdio.Ask, holder.SweepSeat) }}
Files: files}
go followMirrors(v)
go parts.FollowIdle(holder.IdleState, parts.IDs(h.Transfers), h.Expired, func(id string, dropped bool, err error) {
if err != nil {
@@ -482,7 +497,13 @@ func main() {
logf("transfer %s had no part for %s: dropped with its parts", id, holder.TransferIdle)
})
windows := kept[holder.Window]{state: "windows", key: func(w holder.Window) string { return w.Name }}
if err := stdio.Serve("", tools(v, windows)); err != nil {
bound, err := stdio.SettingDuration(askTakenBound, askTakenDefault)
if err != nil {
logf("the setting %s: %v", askTakenBound, err)
os.Exit(1)
}
taken := &asks{take: stdio.State(stdio.TakenState).TakeOnce, bound: bound}
if err := stdio.Serve("", tools(v, windows, taken)); err != nil {
logf("%v", err)
os.Exit(1)
}
@@ -494,3 +515,41 @@ func or(v, d string) string {
}
return v
}
// listTool is the seat's verb list. On oci-artifact-registry it filters by name or module while it reads and pages at 768 KB
// by the cursor next (design 47 H2 §779, §811, §813 (7)); on container-image-registry, whose form takes no cursor, it answers
// whole.
func listTool(v *holder.Verbs, seat string) stdio.Tool {
s := func(d string) map[string]any { return map[string]any{"type": "string", "description": d} }
description := "What the store holds of one repository, or of every repository the seat holds: each manifest's digest, whether it is an index and the manifests it names, the tags naming it, its size and whether it is held (ADR 0632 §3). Read from the store's own files; changes nothing."
props := map[string]any{"name": s("<module>/<artifact>; every repository when not given")}
if seat == holder.ArtifactSeat {
description += " Filtered by name or module while it reads and paged by the cursor next, at most 768 KB a page, capped saying the rest is read from next."
props["module"] = s("only the repositories of this module, <module>/*")
props["next"] = s("the cursor the previous page answered; absent for the first page")
}
return stdio.Tool{Name: seat + "." + holder.VerbList, Description: description, Input: map[string]any{"type": "object", "properties": props},
Run: func(args map[string]any) (any, error) {
if seat != holder.ArtifactSeat {
page, err := v.List(context.Background(), seat, stdio.CallerOf(args), holder.ListQuery{Name: str(args, "name")})
if err != nil {
return nil, err
}
return reg.ListAnswer{Repositories: page.Repositories}, nil
}
in, err := arg[oci.ListInput](args)
if err != nil {
return nil, err
}
page, err := v.List(context.Background(), seat, stdio.CallerOf(args), holder.ListQuery{Name: in.Name, Module: in.Module, Next: in.Next, PageBytes: holder.ListPageBytes})
if err != nil {
return nil, err
}
out := oci.ListAnswer{Form: oci.Form, Repositories: []oci.Repository{}, Capped: page.Capped, Next: page.Next, Total: int64(page.Total)}
raw, _ := json.Marshal(page.Repositories)
if err := json.Unmarshal(raw, &out.Repositories); err != nil {
return nil, err
}
return out, nil
}}
}
@@ -0,0 +1,75 @@
package main
import (
"fmt"
"sync"
"time"
"distribution/internal/holder"
)
// askTakenBound is the setting the taken key of a publish ask lives (design 47 H2 §775, H-A-381 (2)): the holder never
// receives the caller's bound, so it keeps an ask's id this long, the largest caller's bound by default.
const askTakenBound = "ask-taken-bound"
// askTakenDefault is ask-taken-bound's default, the runner's ask-unanswered-bound (H-A-381 (2)).
const askTakenDefault = 10 * time.Minute
// asks takes each publish ask once by its id (design 47 H2 §775; ADR 0668 §2; H-A-381): the first call with an id is
// kept in the state taken and acts; a repeat while that act runs joins it and gets its answer; a repeat after it ended
// answers the act's state read afresh (holder.Repeat), never acting twice. No answer is kept in taken. A call that
// carries no ask id is no kept call, and acts as it did before.
type asks struct {
take func(seat, ask string, bound time.Duration) (bool, error)
bound time.Duration
mu sync.Mutex
running map[string]*flight
// joined, when set, is told each repeat that joins a running act (a test's hook).
joined func()
}
// flight is one act of a taken ask while it runs, which a repeat joins.
type flight struct {
done chan struct{}
a holder.PublishAnswer
err error
}
func (k *asks) once(seat, ask string, act, repeat func() (holder.PublishAnswer, error)) (holder.PublishAnswer, error) {
if ask == "" || k == nil || k.take == nil {
return act()
}
key := seat + "." + ask
k.mu.Lock()
if f, ok := k.running[key]; ok {
k.mu.Unlock()
if k.joined != nil {
k.joined()
}
<-f.done
return f.a, f.err
}
if k.running == nil {
k.running = map[string]*flight{}
}
f := &flight{done: make(chan struct{})}
k.running[key] = f
k.mu.Unlock()
defer func() {
k.mu.Lock()
delete(k.running, key)
k.mu.Unlock()
close(f.done)
}()
took, err := k.take(seat, ask, k.bound)
switch {
case err != nil:
f.err = fmt.Errorf("publish: the ask %s of %s cannot be taken: %w", ask, seat, err)
case took:
f.a, f.err = act()
default:
logf("%s.publish: the ask %s was taken before; it answers the act's state, acting not again", seat, ask)
f.a, f.err = repeat()
}
return f.a, f.err
}
@@ -0,0 +1,63 @@
package main
import (
"errors"
"sync"
"sync/atomic"
"testing"
"time"
"distribution/internal/holder"
)
// A publish ask given twice acts once (design 47 H2 §775; H-A-381): a repeat while the act runs joins it and gets its
// answer, a repeat after it ended answers the act's state, a call with no ask id acts as before, a take that fails is said.
func TestAPublishAskIsTakenOnce(t *testing.T) {
taken := map[string]bool{}
var mu sync.Mutex
k := &asks{bound: time.Minute, take: func(seat, ask string, bound time.Duration) (bool, error) {
mu.Lock()
defer mu.Unlock()
if ask == "broken" {
return false, errors.New("no responders")
}
if bound != time.Minute || taken[seat+"."+ask] {
return false, nil
}
taken[seat+"."+ask] = true
return true, nil
}}
var acts, repeats atomic.Int32
release, started, joined := make(chan struct{}), make(chan struct{}, 1), make(chan struct{}, 1)
k.joined = func() { joined <- struct{}{} }
act := func() (holder.PublishAnswer, error) {
acts.Add(1)
started <- struct{}{}
<-release
return holder.PublishAnswer{Transfer: "t", Missing: []string{"d"}}, nil
}
repeat := func() (holder.PublishAnswer, error) { repeats.Add(1); return holder.PublishAnswer{Transfer: "t"}, nil }
answers := make(chan holder.PublishAnswer, 2)
go func() { a, _ := k.once(holder.ArtifactSeat, "a1", act, repeat); answers <- a }()
<-started
go func() { a, _ := k.once(holder.ArtifactSeat, "a1", act, repeat); answers <- a }()
<-joined
close(release)
for range 2 {
if a := <-answers; len(a.Missing) != 1 {
t.Errorf("an answer of the running act = %+v", a)
}
}
if a, _ := k.once(holder.ArtifactSeat, "a1", act, repeat); acts.Load() != 1 || repeats.Load() != 1 || a.Transfer != "t" {
t.Errorf("acts %d, repeats %d after a repeat of an ended act", acts.Load(), repeats.Load())
}
release = make(chan struct{})
close(release)
act2 := func() (holder.PublishAnswer, error) { acts.Add(1); return holder.PublishAnswer{}, nil }
if _, err := k.once(holder.ArtifactSeat, "", act2, repeat); err != nil || acts.Load() != 2 {
t.Errorf("a call with no ask id: acts %d, %v", acts.Load(), err)
}
if _, err := k.once(holder.ArtifactSeat, "broken", act2, repeat); err == nil || acts.Load() != 2 {
t.Errorf("a failed take: acts %d, %v", acts.Load(), err)
}
}
+1 -1
View File
@@ -10,6 +10,7 @@ require (
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/containerimageregistry v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshbuilds v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/ociartifactregistry v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-sdk/go v0.0.0-00010101000000-000000000000
github.com/nats-io/nats.go v1.54.0
@@ -31,7 +32,6 @@ require (
require (
git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshhandacts 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
)
require git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery v0.0.0-00010101000000-000000000000 // indirect
@@ -18,6 +18,7 @@ import (
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
artifactref "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/containerimageregistryclient/reference"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/publishconformance"
)
type memObjects map[string][]byte
@@ -61,8 +62,9 @@ func (b fakeBuilder) Recorded(string, string, string) (bool, string, error) {
}
type fakeStore struct {
has map[string]bool
put []map[string][]byte
has map[string]bool
held map[string]string // name@version to the digest the store holds there
put []map[string][]byte
}
func (s *fakeStore) Has(_, d string) (bool, error) { return s.has[d], nil }
@@ -70,7 +72,17 @@ func (s *fakeStore) Put(t PublishRequest, parts map[string][]byte) (string, erro
s.put = append(s.put, parts)
return t.Name + "@" + t.Digest, nil
}
func (s *fakeStore) Held(string, string, string) (string, bool, error) { return "", false, nil }
func (s *fakeStore) Held(name, version, digest string) (string, string, error) {
switch d := s.held[name+"@"+version]; d {
case "":
return "", "", nil
case digest:
return name + "@" + d, "", nil
default:
return "", d, nil
}
}
func (s *fakeStore) Holds(r PublishRequest) (bool, error) { return s.has[r.Digest], nil }
type said struct {
seat, event string
@@ -107,6 +119,9 @@ func (c *fakeCatalog) Versions(name string) ([]string, error) {
func (c *fakeCatalog) Digest(name, version string) (string, error) {
return c.tags[name+":"+version], nil
}
func (c *fakeCatalog) Blob(name, version string) (string, error) {
return c.tags[name+":"+version], nil
}
// Remove deletes by the digest, as the store does: every tag naming the digest goes with it.
func (c *fakeCatalog) Remove(name, version string) error {
@@ -201,8 +216,7 @@ func newBed(builderOK bool) *bed {
return nil
},
Finding: func(kind, subject, _ string, raised bool) { b.findings[kind+" "+subject] = raised }}
b.v = &Verbs{Holder: b.h, Catalog: b.cat, Holds: memHolds{}, Mirrors: memMirrors{},
SweepHolder: func() (string, error) { return "artifact-store-tools", nil }}
b.v = &Verbs{Holder: b.h, Catalog: b.cat, Holds: memHolds{}, Mirrors: memMirrors{}}
return b
}
@@ -231,6 +245,40 @@ func TestTheHolderOfTheTwoImageSeats(t *testing.T) {
return PublishRequest{Transfer: id, Name: "m/program", Version: "0.1.4", Kind: KindBundle, Digest: part.Digest, Parts: []Part{part}}
}
t.Run("a publish says each of its waits with its time", func(t *testing.T) {
b := newBed(true)
var lines []string
b.h.Logf = func(f string, a ...any) { lines = append(lines, fmt.Sprintf(f, a...)) }
if _, err := b.h.Publish(ArtifactSeat, builder, req("tl")); err != nil {
t.Fatal(err)
}
all := strings.Join(lines, "\n")
for _, want := range []string{"the store's read of what it holds (the program's registry) starts", "(the program's registry) ended after", "the opening of the transfer on the bus"} {
if !strings.Contains(all, want) {
t.Errorf("no log line %q in:\n%s", want, all)
}
}
})
// A publish ask taken before answers the act's state read afresh and never publishes again (design 47 H2 §775;
// H-A-381): an open transfer its lacking parts, a transfer gone with nothing held a refusal naming it.
t.Run("a repeated ask answers the act's state", func(t *testing.T) {
b := newBed(true)
if _, err := b.h.Repeat(ArtifactSeat, builder, req("tr")); err == nil || !strings.Contains(err.Error(), "transfer tr is gone") {
t.Errorf("a repeat of an act that never happened answered %v", err)
}
if _, err := b.h.Publish(ArtifactSeat, builder, req("tr")); err != nil {
t.Fatal(err)
}
opened := len(b.h.Transfers.(memTransfers))
if a, err := b.h.Repeat(ArtifactSeat, builder, req("tr")); err != nil || !reflect.DeepEqual(a.Missing, []string{part.Digest}) {
t.Errorf("a repeat of an open transfer = %+v, %v", a, err)
}
if len(b.h.Transfers.(memTransfers)) != opened || len(b.said) != 0 {
t.Errorf("a repeat acted: transfers %d, said %+v", len(b.h.Transfers.(memTransfers)), b.said)
}
})
t.Run("a transfer in parts, cut and resumed, hashed, numbered by the builder, published", func(t *testing.T) {
b := newBed(true)
a, err := b.h.Publish(ArtifactSeat, builder, req("t1"))
@@ -297,6 +345,16 @@ func TestTheHolderOfTheTwoImageSeats(t *testing.T) {
_, err := b.h.Publish(ArtifactSeat, builder, req("t"))
return err
}, "the builder did not reserve it"},
{"a version the store holds at another digest", func(b *bed) error {
b.store.held = map[string]string{"m/program@0.1.4": "sha256:bb"}
r := req("t")
r.Digest = "sha256:aa"
_, err := b.h.Publish(ArtifactSeat, builder, r) // the reservation names no digest yet: the bed's builder says yes
if !b.findings["publish-refused m/program@0.1.4"] || len(b.store.put) != 0 {
return errors.New("not refused loudly, or stored")
}
return err
}, "the store holds m/program@0.1.4 at digest sha256:bb, not sha256:aa"},
{"an image on the artifact seat", func(b *bed) error {
r := req("t")
r.Kind = KindImage
@@ -307,10 +365,6 @@ func TestTheHolderOfTheTwoImageSeats(t *testing.T) {
_, err := b.v.Remove(ArtifactSeat, "novox.mesh-delivery-builder", RemoveRequest{Name: "m/program", Version: "0.1.4", Reason: "branch ended"})
return err
}, "has no tag"},
{"a retention removal from another caller than the sweep", func(b *bed) error {
_, err := b.v.Remove(ArtifactSeat, "novox.mesh-delivery-builder", RemoveRequest{Name: "m/program", Digest: part.Digest, Reason: ReasonRetention})
return err
}, "artifact sweep's alone"},
{"a retention removal of a held archive", func(b *bed) error {
_ = b.v.HoldOne(ArtifactSeat, "novox.artifact-store-tools", HoldRequest{Name: "m/a", Kind: KindArchive, Digest: part.Digest})
_, err := b.v.Remove(ArtifactSeat, "novox.artifact-store-tools", RemoveRequest{Name: "m/a", Digest: part.Digest, Reason: ReasonRetention})
@@ -319,16 +373,6 @@ func TestTheHolderOfTheTwoImageSeats(t *testing.T) {
{"a hold of an image", func(b *bed) error {
return b.v.HoldOne(ImageSeat, "novox.artifact-store-tools", HoldRequest{Name: "m/i", Kind: KindImage, Digest: part.Digest})
}, "never held"},
{"a retention removal by the module that held the sweep seat before", func(b *bed) error {
b.v.SweepHolder = func() (string, error) { return "artifact-sweeper", nil } // the seat's holder as the seat says it now
_, err := b.v.Remove(ArtifactSeat, "novox.artifact-store-tools", RemoveRequest{Name: "m/program", Digest: part.Digest, Reason: ReasonRetention})
return err
}, "artifact sweep's alone"},
{"a retention removal while the sweep's holder cannot be read", func(b *bed) error {
b.v.SweepHolder = func() (string, error) { return "", errors.New("the seat's holders are not answered") }
_, err := b.v.Remove(ArtifactSeat, "novox.artifact-store-tools", RemoveRequest{Name: "m/program", Digest: part.Digest, Reason: ReasonRetention})
return err
}, "cannot be read"},
{"a release in distribution's own name", func(b *bed) error {
_, err := b.v.Release(ArtifactSeat, "novox.distribution", HoldRequest{Name: "m/a", Digest: part.Digest})
return err
@@ -431,7 +475,8 @@ func TestTheHolderOfTheTwoImageSeats(t *testing.T) {
t.Run("the sweep's removal, hold and release", func(t *testing.T) {
b := newBed(true)
sweep := "novox.artifact-store-tools"
if _, err := b.v.Remove(ArtifactSeat, sweep, RemoveRequest{Name: "m/a", Digest: part.Digest, Kind: KindArchive, Reason: ReasonRetention}); err != nil {
// A removal for retention is taken whoever asks it; the seat's holders are not read (design 47 H2 §813 (7)).
if _, err := b.v.Remove(ArtifactSeat, "novox.artifact-sweeper", RemoveRequest{Name: "m/a", Digest: part.Digest, Kind: KindArchive, Reason: ReasonRetention}); err != nil {
t.Fatal(err)
}
if err := b.v.HoldOne(ArtifactSeat, sweep, HoldRequest{Name: "m/b", Kind: KindArchive, Digest: part.Digest}); err != nil {
@@ -448,7 +493,7 @@ func TestTheHolderOfTheTwoImageSeats(t *testing.T) {
for _, s := range b.said {
events = append(events, s.event+" "+s.body.By)
}
if want := []string{"removed " + sweep, "held " + sweep, "released person.jochen"}; !reflect.DeepEqual(events, want) {
if want := []string{"removed novox.artifact-sweeper", "held " + sweep, "released person.jochen"}; !reflect.DeepEqual(events, want) {
t.Errorf("said %v, want %v", events, want)
}
b.cat.tags["m/p:0.1.5-feat-x.1"] = part.Digest
@@ -650,30 +695,70 @@ func TestTheHolderOfTheTwoImageSeats(t *testing.T) {
}
}
})
t.Run("a late publish names a held bundle with no size: tagged at the store's size, nothing sent", func(t *testing.T) {
// Design 47 G A-490: the publish contract's no-parts form, as every publish holder is held to it.
t.Run("the publish conformance cases", func(t *testing.T) {
publishconformance.Run(t, func(t *testing.T) publishconformance.Bed {
b := newBed(true)
return publishconformance.Bed{
Hold: func(d string) { b.store.has[d] = true },
Publish: func(name, version, digest string) publishconformance.Outcome {
got, err := b.h.Publish(ArtifactSeat, builder, PublishRequest{Name: name, Version: version, Kind: KindBundle, Digest: digest, Transfer: "t"})
o := publishconformance.Outcome{Ended: got.Ended, Lacks: len(got.Missing), Err: err}
if len(b.said) > 0 {
o.Event, o.Reason = b.said[len(b.said)-1].event, b.said[len(b.said)-1].body.Reason
}
return o
}}
})
})
t.Run("a publish with a version and no parts tags the held digest at the store's size; one not held is not stored", func(t *testing.T) {
// Design 47 G A-417, A-73, A-50: the build stored the bundle untagged; the builder's publish of its version with that
// digest and no parts tags it and says published, nothing sent; a digest the store holds none of is refused as not
// stored, naming the digest.
store := newFakeRegistry()
sts := httptest.NewServer(store)
defer sts.Close()
base, _ := url.Parse(sts.URL)
o := &OCI{Base: base}
b := newBed(true)
b.h.Store = &OCI{Base: base}
blob := []byte(strings.Repeat("b", 4321))
store.blobs["m/tools@"+digestOf(blob)] = blob
ref, err := o.Put(PublishRequest{Name: "m/tools", Version: "0.1.4", Kind: KindBundle, Digest: digestOf(blob),
Parts: []Part{{Digest: digestOf(blob)}}}, map[string][]byte{})
if err != nil || ref != "m/tools@"+digestOf(blob) {
t.Fatalf("Put = %q, %v", ref, err)
got, err := b.h.Publish(ArtifactSeat, "x.mesh-delivery-builder", PublishRequest{Name: "m/tools", Version: "0.1.4", Kind: KindBundle, Digest: digestOf(blob),
Transfer: "republish-m-0-1-4-tools"})
if err != nil || !got.Ended || len(b.said) != 1 || b.said[0].event != EventPublished || b.said[0].body.Reference != SeatReference(ArtifactSeat, "m/tools@"+digestOf(blob)) {
t.Fatalf("Publish = %+v, %v; said %+v", got, err, b.said)
}
var man struct {
Layers []struct {
Size int64 `json:"size"`
Digest string `json:"digest"`
Size int64 `json:"size"`
} `json:"layers"`
}
if err := json.Unmarshal(store.manifests["m/tools:0.1.4"], &man); err != nil || len(man.Layers) != 1 || man.Layers[0].Size != int64(len(blob)) {
if err := json.Unmarshal(store.manifests["m/tools:0.1.4"], &man); err != nil || len(man.Layers) != 1 || man.Layers[0].Size != int64(len(blob)) || man.Layers[0].Digest != digestOf(blob) {
t.Errorf("the version's manifest %s, want one layer of %d bytes", store.manifests["m/tools:0.1.4"], len(blob))
}
if _, err := o.Put(PublishRequest{Name: "m/tools", Version: "0.1.5", Kind: KindBundle, Digest: "sha256:" + strings.Repeat("e", 64),
Parts: []Part{{Digest: "sha256:" + strings.Repeat("e", 64)}}}, map[string][]byte{}); err == nil {
t.Error("a digest the store does not hold was tagged")
// `versions` answers the digest the version's reference names and its published carries (design 47 G A-430a): on the
// artifact seat the blob, which the node-engine fetches as /blobs/<digest>, never the manifest's own digest.
v := &Verbs{Holder: b.h, Catalog: &OCI{Base: base}}
for _, c := range []struct{ seat, version, want string }{
{ArtifactSeat, "0.1.4", digestOf(blob)},
{ImageSeat, "0.1.4", digestOf(store.manifests["m/tools:0.1.4"])},
{ArtifactSeat, "0.1.9", ""},
} {
if got, err := v.VersionDigest(c.seat, "m/tools", c.version); err != nil || got != c.want {
t.Errorf("VersionDigest(%s, m/tools, %s) = %q, %v, want %q", c.seat, c.version, got, err, c.want)
}
}
// A manifest that keeps no single blob answers no digest and says why.
store.manifests["m/tools:0.2.0"] = []byte(`{"schemaVersion":2,"mediaType":"application/vnd.oci.image.manifest.v1+json","config":{"mediaType":"application/vnd.oci.image.config.v1+json","digest":"sha256:c"},"layers":[{"digest":"sha256:a"},{"digest":"sha256:b"}]}`)
if got, err := v.VersionDigest(ArtifactSeat, "m/tools", "0.2.0"); got != "" || err == nil || !strings.Contains(err.Error(), "2 layers") {
t.Errorf("VersionDigest of a manifest of two layers = %q, %v, want no digest and why", got, err)
}
gone := "sha256:" + strings.Repeat("e", 64)
_, err = b.h.Publish(ArtifactSeat, "x.mesh-delivery-builder", PublishRequest{Name: "m/tools", Version: "0.1.5", Kind: KindBundle, Digest: gone, Transfer: "republish-m-0-1-5-tools"})
if err == nil || !strings.Contains(err.Error(), "not stored: ") || !strings.Contains(err.Error(), gone) || store.manifests["m/tools:0.1.5"] != nil ||
len(b.said) != 2 || b.said[1].event != EventRefused || !b.findings["publish-refused m/tools@0.1.5"] {
t.Errorf("a digest not held: %v; said %+v; findings %v", err, b.said, b.findings)
}
})
t.Run("mirror answers at once and says the copy's end on the seat's events", func(t *testing.T) {
@@ -844,10 +929,24 @@ func TestTheHolderOfTheTwoImageSeats(t *testing.T) {
Name string `json:"name"`
Port int `json:"port"`
} `json:"listens"`
Class string `json:"class"`
State []struct {
Name string `json:"name"`
MaxMiB int `json:"max-mib"`
} `json:"state"`
}
if err := json.Unmarshal(raw, &m); err != nil {
t.Fatal(err)
}
// Design 47 H2 H-A-411 (2): a core module, and every state names its cap, 8 MiB.
if m.Class != "core" {
t.Errorf("class %q, want core", m.Class)
}
for _, st := range m.State {
if st.MaxMiB != 8 {
t.Errorf("the state %s names max-mib %d, want 8", st.Name, st.MaxMiB)
}
}
// The reservation is asked through the seat mesh-builds, so the manifest takes no package of the builder (design 47 §381).
if len(m.Packages) != 0 {
t.Errorf("packages %v: want none", m.Packages)
+75 -15
View File
@@ -9,9 +9,12 @@ package holder
import (
"context"
"encoding/base64"
"encoding/json"
"errors"
"fmt"
"sort"
"strings"
reg "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/containerimageregistry"
)
@@ -25,27 +28,52 @@ type StoreFiles interface {
Manifests(ctx context.Context, l *Listing) (map[string]*Manifest, map[string]string)
}
// List is `list` on seat: the repositories it holds, or name alone; a repository the seat holds nothing of is not named,
// and name not held is an empty answer. A manifest whose content cannot be read fails the answer, by name: a listing
// missing one would read as the store not holding it.
func (v *Verbs) List(ctx context.Context, seat, caller, name string) ([]reg.Repository, error) {
// ListPageBytes is the most a page of oci-artifact-registry's list answers (design 47 H2 §811): 768 KB.
const ListPageBytes = 768 << 10
// ListQuery is what a list is asked: Name or Module (`<module>/*`) filter the repositories while the files are read, Next
// is the cursor a page answered, and PageBytes the most a page answers, 0 for the whole answer at once (the seat
// container-image-registry's list, whose form takes no cursor).
type ListQuery struct {
Name, Module, Next string
PageBytes int
}
// ListPage is one page of a list: its repositories in order of their names, Total the repositories the filters hold in
// all, and Next the cursor of the next page, empty at the end; Capped says the page stopped at PageBytes.
type ListPage struct {
Repositories []reg.Repository
Capped bool
Total int
Next string
}
// List is `list` on seat: the repositories it holds, or those q's filters name; a repository the seat holds nothing of is
// not named, and a name not held is an empty answer. A paged list continues after the repository its cursor names, in
// order of the names (design 47 H2 §779, §811, §813 (7)). A manifest whose content cannot be read fails the answer, by
// name: a listing missing one would read as the store not holding it.
func (v *Verbs) List(ctx context.Context, seat, caller string, q ListQuery) (ListPage, error) {
if seat != ImageSeat && seat != ArtifactSeat {
return nil, fmt.Errorf("list: %s is no seat of distribution's", seat)
return ListPage{}, fmt.Errorf("list: %s is no seat of distribution's", seat)
}
if v.Files == nil {
return nil, errors.New("list: this process reads no store files")
return ListPage{}, errors.New("list: this process reads no store files")
}
after, err := listCursor(q.Next)
if err != nil {
return ListPage{}, err
}
l, err := v.Files.List(ctx)
if err != nil {
return nil, fmt.Errorf("list: the store's files cannot be listed: %w", err)
return ListPage{}, fmt.Errorf("list: the store's files cannot be listed: %w", err)
}
if name != "" {
r, held := l.Repos[name]
l = &Listing{Blobs: l.Blobs, Repos: map[string]*Repo{}}
if held {
l.Repos[name] = r
kept := &Listing{Blobs: l.Blobs, Repos: map[string]*Repo{}}
for name, r := range l.Repos {
if (q.Name == "" || name == q.Name) && (q.Module == "" || strings.HasPrefix(name, q.Module+"/")) {
kept.Repos[name] = r
}
}
l = kept
docs, unread := v.Files.Manifests(ctx, l)
if len(unread) > 0 {
keys := make([]string, 0, len(unread))
@@ -53,11 +81,11 @@ func (v *Verbs) List(ctx context.Context, seat, caller, name string) ([]reg.Repo
keys = append(keys, k)
}
sort.Strings(keys)
return nil, fmt.Errorf("list: %d manifests cannot be read, the first %s: %s", len(keys), keys[0], unread[keys[0]])
return ListPage{}, fmt.Errorf("list: %d manifests cannot be read, the first %s: %s", len(keys), keys[0], unread[keys[0]])
}
holds, err := v.Holds.List()
if err != nil {
return nil, fmt.Errorf("list: the holds cannot be read: %w", err)
return ListPage{}, fmt.Errorf("list: the holds cannot be read: %w", err)
}
held := map[string]bool{}
for _, h := range holds {
@@ -102,5 +130,37 @@ func (v *Verbs) List(ctx context.Context, seat, caller, name string) ([]reg.Repo
out = append(out, reg.Repository{Name: repo, Manifests: manifests})
}
}
return out, nil
page := ListPage{Repositories: []reg.Repository{}, Total: len(out)}
size := 0
for _, r := range out {
if r.Name <= after {
continue
}
if q.PageBytes > 0 {
raw, _ := json.Marshal(r)
if size+len(raw) > q.PageBytes {
if len(page.Repositories) == 0 {
return ListPage{}, fmt.Errorf("list: the repository %s alone is over a page's %d bytes (%d)", r.Name, q.PageBytes, len(raw))
}
page.Capped = true
page.Next = base64.RawURLEncoding.EncodeToString([]byte(page.Repositories[len(page.Repositories)-1].Name))
break
}
size += len(raw)
}
page.Repositories = append(page.Repositories, r)
}
return page, nil
}
// listCursor is the repository a page's cursor continues after, "" for the first page; a cursor no page answered is refused.
func listCursor(next string) (string, error) {
if next == "" {
return "", nil
}
name, err := base64.RawURLEncoding.DecodeString(next)
if err != nil || len(name) == 0 {
return "", fmt.Errorf("list: %q is no cursor a page of list answered", next)
}
return string(name), nil
}
@@ -2,6 +2,7 @@ package holder
import (
"context"
"encoding/json"
"fmt"
"reflect"
"strings"
@@ -132,7 +133,8 @@ func TestListAnswersTheStoreThroughTheSeat(t *testing.T) {
t.Fatal(err)
}
ctx := context.Background()
images, err := b.v.List(ctx, ImageSeat, "mesh-anyone", "")
page, err := b.v.List(ctx, ImageSeat, "mesh-anyone", ListQuery{})
images := page.Repositories
if err != nil {
t.Fatal(err)
}
@@ -155,7 +157,8 @@ func TestListAnswersTheStoreThroughTheSeat(t *testing.T) {
if !reflect.DeepEqual(images, want) {
t.Errorf("the image seat lists %+v\nwant %+v", images, want)
}
artifacts, err := b.v.List(ctx, ArtifactSeat, "mesh-anyone", "")
page, err = b.v.List(ctx, ArtifactSeat, "mesh-anyone", ListQuery{})
artifacts := page.Repositories
if err != nil {
t.Fatal(err)
}
@@ -166,16 +169,42 @@ func TestListAnswersTheStoreThroughTheSeat(t *testing.T) {
if !reflect.DeepEqual(artifacts, wantA) {
t.Errorf("the artifact seat lists %+v\nwant %+v", artifacts, wantA)
}
if one, err := b.v.List(ctx, ImageSeat, "mesh-anyone", "app/tools"); err != nil || len(one) != 0 {
if one, err := b.v.List(ctx, ImageSeat, "mesh-anyone", ListQuery{Name: "app/tools"}); err != nil || len(one.Repositories) != 0 {
t.Errorf("the image seat's list of a bundle's repository: %+v, %v", one, err)
}
if one, err := b.v.List(ctx, ArtifactSeat, "mesh-anyone", "mesh/facts"); err != nil || len(one) != 1 || one[0].Name != "mesh/facts" {
if one, err := b.v.List(ctx, ArtifactSeat, "mesh-anyone", ListQuery{Name: "mesh/facts"}); err != nil || len(one.Repositories) != 1 || one.Repositories[0].Name != "mesh/facts" {
t.Errorf("one repository: %+v, %v", one, err)
}
// Design 47 H2 §813 (7), §811, §779: the artifact seat's list filters by module while it reads, and pages by its cursor in
// order of the names, each page within its bytes, saying capped and the total the filters hold.
if mod, err := b.v.List(ctx, ArtifactSeat, "mesh-anyone", ListQuery{Module: "app", PageBytes: ListPageBytes}); err != nil ||
!reflect.DeepEqual(mod, ListPage{Repositories: wantA[:1], Total: 1}) {
t.Errorf("the module app's repositories: %+v, %v", mod, err)
}
first, _ := json.Marshal(wantA[0])
second, _ := json.Marshal(wantA[1])
var paged []reg.Repository
q := ListQuery{PageBytes: max(len(first), len(second))} // one repository a page
for pages := 0; ; pages++ {
p, err := b.v.List(ctx, ArtifactSeat, "mesh-anyone", q)
if err != nil || p.Total != 2 || p.Capped != (p.Next != "") || pages > 2 {
t.Fatalf("page %d: %+v, %v", pages, p, err)
}
paged = append(paged, p.Repositories...)
if q.Next = p.Next; q.Next == "" {
break
}
}
if !reflect.DeepEqual(paged, wantA) {
t.Errorf("the pages hold %+v, want %+v", paged, wantA)
}
if _, err := b.v.List(ctx, ArtifactSeat, "mesh-anyone", ListQuery{Next: "!"}); err == nil {
t.Error("a cursor no page answered was taken")
}
// A manifest whose content cannot be read fails the answer: a listing without it would read as the store not holding it.
delete(f.manifests, dg("m-old"))
b.v.Files = &Files{Container: "mesh-registry", Run: f.run(t)} // what was read is kept: a fresh reader reads again
if _, err := b.v.List(ctx, ImageSeat, "mesh-anyone", ""); err == nil || !strings.Contains(err.Error(), "cannot be read") {
if _, err := b.v.List(ctx, ImageSeat, "mesh-anyone", ListQuery{}); err == nil || !strings.Contains(err.Error(), "cannot be read") {
t.Errorf("an unreadable manifest: %v", err)
}
// The files' listing: a repository with slashes read, a cut or stray one refused.
+46 -4
View File
@@ -208,15 +208,34 @@ func (o *OCI) layerSize(t PublishRequest, parts map[string][]byte) (int64, error
}
// Held is the reference of name at version when the store holds digest under it.
func (o *OCI) Held(name, version, digest string) (string, bool, error) {
func (o *OCI) Held(name, version, digest string) (string, string, error) {
d, err := o.Digest(name, version)
if err != nil || d == "" {
return "", false, err
return "", "", err
}
if d != digest {
return "", false, nil
return "", d, nil
}
return name + "@" + d, true, nil
return name + "@" + d, "", nil
}
// Holds is whether the store holds what r's digest names under r's name: an image's manifest by its digest, or a bundle's
// or an archive's blob.
func (o *OCI) Holds(r PublishRequest) (bool, error) {
if r.Kind != KindImage && r.Kind != KindUpstream {
return o.Has(r.Name, r.Digest)
}
resp, _, err := o.do(http.MethodHead, "/v2/"+r.Name+"/manifests/"+r.Digest, "", nil, accepted...)
if err != nil {
return false, err
}
switch resp.StatusCode {
case http.StatusOK:
return true, nil
case http.StatusNotFound:
return false, nil
}
return false, fmt.Errorf("the store answered %d for the manifest %s of %s", resp.StatusCode, r.Digest, r.Name)
}
// Versions are name's tags.
@@ -254,6 +273,29 @@ func (o *OCI) Digest(name, version string) (string, error) {
return resp.Header.Get("Docker-Content-Digest"), nil
}
// Blob is the one blob the manifest name holds at version keeps (Manifest.Holder's shape): a bundle's or an archive's,
// what its reference names. Empty when none is held at version; an error naming why when the manifest keeps no single blob.
func (o *OCI) Blob(name, version string) (string, error) {
resp, b, err := o.do(http.MethodGet, "/v2/"+name+"/manifests/"+version, "", nil, mediaManifest)
if err != nil {
return "", err
}
if resp.StatusCode == http.StatusNotFound {
return "", nil
}
if resp.StatusCode != http.StatusOK {
return "", fmt.Errorf("the store answered %d for %s:%s", resp.StatusCode, name, version)
}
m, err := ParseManifest(b)
if err != nil {
return "", fmt.Errorf("the manifest of %s:%s cannot be read: %w", name, version, err)
}
if !m.Holder() {
return "", fmt.Errorf("the manifest of %s:%s keeps %d layers under a %q configuration, not one blob", name, version, len(m.Layers), m.ConfigMedia)
}
return m.Layers[0], nil
}
// ErrNoTagAlone is a store that cannot delete a tag alone. registry 2.8.3, the store's pinned image, is one: its
// DeleteManifest (distribution v2.8.3 registry/handlers/manifests.go) ignores a tag reference and deletes the empty
// digest, whose check fails, answered 400 DIGEST_INVALID; registry 3 untags alone.
@@ -3,13 +3,14 @@ package holder
import (
"encoding/json"
"fmt"
"strings"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshbuilds"
)
// Reserved is the holder's check of a publish against the builder's reservation (novox/hq design 47 §381, §478, §504): it asks the
// seat mesh-builds' verb reserved with the publish's name and version, a package's name in its ecosystem, and accepts the publish
// only when that version is the one reserved and an artifact of it has the publish's digest. It reads no catalog and a publish gains
// only when that version is the one reserved and an artifact of it has the publish's digest or none recorded yet (A-490j). It reads no catalog and a publish gains
// no field. It is the Builder the holder's Check asks.
type Reserved struct {
// Ask is the runtime's request and reply over the bus (mesh-sdk stdio.Ask).
@@ -31,12 +32,20 @@ func (r Reserved) Recorded(name, version, digest string) (bool, string, error) {
return false, "", fmt.Errorf("%s answered no reservation for %s@%s: %s", Address, name, version, raw)
}
if a.Version != version {
return false, fmt.Sprintf("%s reserved %s for %s, not %s", a.Module, a.Version, name, version), nil
return false, fmt.Sprintf("%s has no reservation of version %s of %s (it reserved %s)", a.Module, version, name, a.Version), nil
}
var reserved []string
for _, art := range a.Artifacts {
if art.Digest == digest {
// An artifact whose build has not recorded its digest yet takes the publish: the builder records a build's digests only when
// the build ends, while the build module publishes during it with the reserved version (design 47 G §369, A-415, A-490j,
// H-A-387). A digest the build then records that differs from what the holder holds fails the build.
if art.Digest == digest || art.Digest == "" {
return true, "", nil
}
reserved = append(reserved, art.Digest)
}
return false, fmt.Sprintf("%s reserved %s@%s for another digest than %s", a.Module, name, version, digest), nil
if len(reserved) == 0 {
return false, fmt.Sprintf("%s reserved %s@%s with no artifact, so no digest takes %s", a.Module, name, version, digest), nil
}
return false, fmt.Sprintf("%s reserved %s@%s for digest %s, not %s", a.Module, name, version, strings.Join(reserved, ", "), digest), nil
}
@@ -19,8 +19,10 @@ func reservedChecksAPublishAgainstTheReservation(t *testing.T) {
}{
{name: "the reserved version and digest", answer: `{"module":"mesh-image","version":"0.1.7","artifacts":[{"artifact":"mesh-image:image","digest":"sha256:aa"}]}`, ok: true},
{name: "another artifact of it carries the digest", answer: `{"module":"mesh-image","version":"0.1.7","artifacts":[{"artifact":"mesh-image:aux"},{"artifact":"mesh-image:image","digest":"sha256:aa"}]}`, ok: true},
{name: "another digest", answer: `{"module":"mesh-image","version":"0.1.7","artifacts":[{"artifact":"mesh-image:image","digest":"sha256:bb"}]}`, why: "another digest than sha256:aa"},
{name: "another version reserved", answer: `{"module":"mesh-image","version":"0.1.8","artifacts":[]}`, why: "reserved 0.1.8 for registry/mesh-image, not 0.1.7"},
{name: "no digest recorded yet", answer: `{"module":"mesh-image","version":"0.1.7","artifacts":[{"artifact":"mesh-image:image"}]}`, ok: true},
{name: "another digest", answer: `{"module":"mesh-image","version":"0.1.7","artifacts":[{"artifact":"mesh-image:image","digest":"sha256:bb"}]}`, why: "reserved registry/mesh-image@0.1.7 for digest sha256:bb, not sha256:aa"},
{name: "no artifact reserved", answer: `{"module":"mesh-image","version":"0.1.7","artifacts":[]}`, why: "with no artifact, so no digest takes sha256:aa"},
{name: "another version reserved", answer: `{"module":"mesh-image","version":"0.1.8","artifacts":[]}`, why: "no reservation of version 0.1.7 of registry/mesh-image (it reserved 0.1.8)"},
{name: "the builder refused the name", err: errors.New("no entry carries registry/mesh-image"), why: "no entry carries registry/mesh-image"},
{name: "an answer that is none", answer: `{"error":"x"}`, why: "answered no reservation"},
} {
@@ -19,9 +19,6 @@ const (
OldSeat = "mesh-artifact-store"
)
// SweepSeat is the seat of the artifact sweep, whose holder alone removes an untagged version for retention.
const SweepSeat = "mesh-artifact-sweep"
// The verbs of the seats (design 26 *A seat's definition*; design 51 *One contract*).
const (
VerbPublish = "publish"
@@ -141,8 +141,12 @@ type Store interface {
// Put stores a publish's parts under its name and version and answers the reference's path (SeatReference).
Put(r PublishRequest, parts map[string][]byte) (reference string, err error)
// Held is the reference's path of name at version when the store already holds digest under it: a rebuild of a held
// fingerprint answers it and stores nothing.
Held(name, version, digest string) (reference string, ok bool, err error)
// fingerprint answers it and stores nothing. When the store holds the version at another digest, other names that digest
// and reference is empty; neither is set when the store holds no such version.
Held(name, version, digest string) (reference, other string, err error)
// Holds says whether the store holds what a publish's digest names under its name: an image's manifest, or a bundle's or
// an archive's blob. The store is the artifact store (A-50): `artifact-store://<name>/blobs/<digest>` is that blob.
Holds(r PublishRequest) (bool, error)
}
// SeatReference is a reference in the form the seat answers (novox/hq ADR 0605 §9): the seat's name, then the path the
@@ -173,6 +177,20 @@ type Holder struct {
// Idle writes a transfer's idle key with its own time to live, once (parts.BusArm over IdleState); the receiver
// arms it on each open that leaves a transfer open. Nil arms nothing.
Idle func(id string, ttl time.Duration) error
// Logf says each wait of a publish with its time (stderr in the bundle); nil says nothing.
Logf func(string, ...any)
}
// timed runs f and logs its name and time when the holder logs.
func (h *Holder) timed(what string, f func() error) error {
if h.Logf == nil {
return f()
}
start := time.Now()
h.Logf("publish: %s starts", what)
err := f()
h.Logf("publish: %s ended after %s (%v)", what, time.Since(start).Round(time.Millisecond), err)
return err
}
func (h *Holder) now() time.Time {
@@ -249,23 +267,91 @@ func (h *Holder) Publish(seat, caller string, r PublishRequest) (PublishAnswer,
}
// A rebuild of a held fingerprint answers the held version and stores nothing.
if r.Version != "" {
if ref, ok, err := h.Store.Held(r.Name, r.Version, r.Digest); err != nil {
var ref, other string
err := h.timed("the store's read of what it holds (the program's registry)", func() (err error) {
ref, other, err = h.Store.Held(r.Name, r.Version, r.Digest)
return err
})
if err != nil {
return PublishAnswer{}, fmt.Errorf("publish: the store cannot say whether it holds %s@%s: %w", r.Name, r.Version, err)
} else if ok {
return PublishAnswer{Transfer: r.Transfer, Ended: true}, h.Say(seat, EventPublished, h.eventOf(seat, r, SeatReference(seat, ref), ""))
} else if other != "" {
// A second publish of a held version with another digest is refused before the reservation is asked, as the forge
// holds the first (A-490j, H-A-393): while the reserved digest is still empty it would pass, and the store's Put
// would move the version's tag.
return h.refusePublish(seat, r, fmt.Sprintf("the store holds %s@%s at digest %s, not %s", r.Name, r.Version, other, r.Digest))
} else if ref != "" {
return PublishAnswer{Transfer: r.Transfer, Ended: true}, h.timed("the published event on the seat", func() error {
return h.Say(seat, EventPublished, h.eventOf(seat, r, SeatReference(seat, ref), ""))
})
}
}
if r.Version != "" && len(r.Parts) == 0 {
return h.tagHeld(seat, r)
}
wants := make([]parts.Want, 0, len(r.Parts))
for _, p := range r.Parts {
wants = append(wants, parts.Want{Digest: p.Digest, Size: p.Size})
}
got, err := h.receiver().Open(r.Transfer, caller, wants, Opening{PublishRequest: r, Seat: seat})
var got parts.Received
err := h.timed("the opening of the transfer on the bus (objects, transfer state, idle key)", func() (err error) {
got, err = h.receiver().Open(r.Transfer, caller, wants, Opening{PublishRequest: r, Seat: seat})
return err
})
if err != nil {
return answerOf(got), fmt.Errorf("publish: %w", err)
}
return answerOf(got), nil
}
// refusePublish ends a publish refused before anything is stored: its finding raised, refused said on the seat, the reason
// answered.
func (h *Holder) refusePublish(seat string, r PublishRequest, reason string) (PublishAnswer, error) {
h.Finding("publish-refused", r.Name+"@"+r.Version, reason, true)
if err := h.Say(seat, EventRefused, h.eventOf(seat, r, "", reason)); err != nil {
return PublishAnswer{}, fmt.Errorf("publish: %s, and the refused is not said: %w", reason, err)
}
return PublishAnswer{Transfer: r.Transfer, Ended: true}, errors.New("publish: " + reason)
}
// tagHeld is a publish with a version, a digest and no parts (design 47 G A-417, A-73, A-50): what the store holds of that
// digest under the name (the build's untagged publish, the artifact store's blob) is checked against the builder's reservation
// and tagged with the version, and published is said; when the store holds none of it, the publish is refused as not stored,
// naming the digest. Nothing travels.
func (h *Holder) tagHeld(seat string, r PublishRequest) (PublishAnswer, error) {
var held bool
err := h.timed("the store's read of the digest it holds (the program's registry)", func() (err error) {
held, err = h.Store.Holds(r)
return err
})
if err != nil {
return PublishAnswer{}, fmt.Errorf("publish: the store cannot say whether it holds %s of %s: %w", r.Digest, r.Name, err)
}
refuse := func(reason string) (PublishAnswer, error) { return h.refusePublish(seat, r, reason) }
if !held {
return refuse(fmt.Sprintf("not stored: the store holds no %s of %s, so version %s names nothing", r.Digest, r.Name, r.Version))
}
ok, why, err := h.Builder.Recorded(r.Name, r.Version, r.Digest)
if err != nil {
return PublishAnswer{}, fmt.Errorf("publish: the reservation could not be read, so nothing is tagged: %w", err)
}
if !ok {
return refuse("the builder did not reserve it: " + why)
}
tag := r
tag.Parts = []Part{{Digest: r.Digest}}
var path string
if err := h.timed("the store's tag of the held digest (the program's registry)", func() (err error) {
path, err = h.Store.Put(tag, map[string][]byte{})
return err
}); err != nil {
return refuse("the store did not tag it: " + err.Error())
}
h.Finding("publish-refused", r.Name+"@"+r.Version, "", false)
return PublishAnswer{Transfer: r.Transfer, Ended: true}, h.timed("the published event on the seat", func() error {
return h.Say(seat, EventPublished, h.eventOf(seat, r, SeatReference(seat, path), ""))
})
}
// PublishPart is `publish-part`: one chunk, from the caller that opened the transfer alone.
func (h *Holder) PublishPart(seat, caller string, r PartRequest) (PublishAnswer, error) {
got, err := h.receiver().Take(r.Transfer, caller, r.Digest, r.Sequence, r.Last, r.Data, func(t Transfer) error {
@@ -320,6 +406,38 @@ func (h *Holder) DropIdle() ([]string, error) { return h.receiver().DropIdle() }
// already gone. It answers whether it dropped the transfer.
func (h *Holder) Expired(id string) (bool, error) { return h.receiver().Expired(id) }
// Repeat is `publish` given again with an ask id the holder already took and whose first act ended (design 47 H2 §775;
// H-A-381): it never publishes twice and keeps no answer, but answers the act's state as it stands, read afresh, which is
// what the act answers when done: a version the store holds ended, an open transfer the parts it lacks; a transfer that
// is gone, with nothing held, says the act never happened, and is refused naming it.
func (h *Holder) Repeat(seat, caller string, r PublishRequest) (PublishAnswer, error) {
if err := checkPublish(seat, r); err != nil {
return PublishAnswer{}, err
}
if r.Version != "" {
var ref string
err := h.timed("the store's read of what it holds (the program's registry)", func() (err error) {
ref, _, err = h.Store.Held(r.Name, r.Version, r.Digest)
return err
})
if err != nil {
return PublishAnswer{}, fmt.Errorf("publish: the store cannot say whether it holds %s@%s: %w", r.Name, r.Version, err)
} else if ref != "" {
return PublishAnswer{Transfer: r.Transfer, Ended: true}, nil
}
}
t, found, err := h.Transfers.Get(r.Transfer)
switch {
case err != nil:
return PublishAnswer{}, fmt.Errorf("publish: the transfer %s of a repeated ask cannot be read: %w", r.Transfer, err)
case !found:
return PublishAnswer{}, fmt.Errorf("publish: refused: the ask was taken before, and transfer %s is gone with nothing of %s held: the act did not happen", r.Transfer, r.Name)
case t.Opener != caller:
return PublishAnswer{}, fmt.Errorf("publish: refused for %s: transfer %s was opened by another caller", caller, r.Transfer)
}
return PublishAnswer{Transfer: t.ID, Missing: t.Lacks()}, nil
}
func checkPublish(seat string, r PublishRequest) error {
switch {
case !slices.Contains(Seats, seat):
+16 -11
View File
@@ -19,6 +19,9 @@ type Catalog interface {
Versions(name string) ([]string, error)
// Digest is the digest name holds at version, empty when none.
Digest(name, version string) (string, error)
// Blob is the one blob the manifest name holds at version keeps, for a bundle or an archive: the digest its reference
// names and its published event carries. Empty when none is held; an error when the manifest keeps no single blob.
Blob(name, version string) (string, error)
// Remove deletes name at version by its manifest's digest, every tag naming that digest with it; the store's
// collector frees its blobs.
Remove(name, version string) error
@@ -85,9 +88,6 @@ type Verbs struct {
Mirrors Mirrors
// Files are the store's own files, which list reads (ADR 0632 §3).
Files StoreFiles
// SweepHolder is the module holding the seat `mesh-artifact-sweep`, as the seat's holders say it now (design 47 G §7, §428);
// a removal for retention is that module's alone.
SweepHolder func() (string, error)
}
// VersionsAnswer is `versions`: the versions the seat holds of name.
@@ -112,6 +112,16 @@ func (v *Verbs) Versions(seat, caller, name string) (VersionsAnswer, error) {
return VersionsAnswer{Seat: seat, Name: name, Versions: got}, nil
}
// VersionDigest is the digest `versions` answers for name at version on seat: the one an artifact's reference names and
// its event `published` carries (the contract's Artifact), so a node-engine fetches the bytes by it (design 47 G A-430a):
// on the artifact seat a bundle's or an archive's blob, on the image seat the image's manifest. Empty when none is held.
func (v *Verbs) VersionDigest(seat, name, version string) (string, error) {
if seat == ArtifactSeat {
return v.Catalog.Blob(name, version)
}
return v.Catalog.Digest(name, version)
}
// RemoveRequest is `remove`: a tagged version, or with the reason retention an untagged one by its digest.
type RemoveRequest struct {
Name string `json:"name"`
@@ -137,7 +147,7 @@ type Removal struct {
const ReasonSharedDigest = reg.RemoveAnswerReasonSharedDigest
// Remove is `remove`: the builder removes a tagged version; the artifact sweep's holder an untagged bundle, archive or
// copied base with the reason retention, which a hold keeps. Every removal says `removed` with its reason.
// copied base with the reason retention, which a hold keeps, its caller not judged (design 47 H2 §813 (7)). Every removal says `removed` with its reason.
func (v *Verbs) Remove(seat, caller string, r RemoveRequest) (Removal, error) {
if strings.TrimSpace(r.Name) == "" || strings.TrimSpace(r.Reason) == "" {
return Removal{}, errors.New("remove: a name and a reason are required")
@@ -145,13 +155,8 @@ func (v *Verbs) Remove(seat, caller string, r RemoveRequest) (Removal, error) {
ev := Event{Name: r.Name, Version: r.Version, Kind: r.Kind, Digest: r.Digest, Holder: Self, Reason: r.Reason, By: caller}
switch {
case r.Reason == ReasonRetention:
sweep, err := v.SweepHolder()
if err != nil {
return Removal{}, fmt.Errorf("remove: the holder of %s cannot be read, so nothing is removed for retention: %w", SweepSeat, err)
}
if CallerModule(caller) != sweep {
return Removal{}, fmt.Errorf("remove: refused for %s: a removal for retention is the artifact sweep's alone", caller)
}
// The removal for retention the holder of mesh-artifact-sweep asks; its caller is not judged, as every account may call
// every verb (design 47 H2 §813 (7)).
if r.Digest == "" {
return Removal{}, errors.New("remove: a removal for retention names the digest")
}
+38 -7
View File
@@ -1,6 +1,7 @@
{
"module": "distribution",
"version": "0.1",
"class": "core",
"provides": [
{
"name": "artifact-store",
@@ -249,14 +250,44 @@
}
],
"state": [
"transfers",
{
"name": "transfers",
"max-mib": 8
},
{
"name": "idle",
"key-ttl": true
"key-ttl": true,
"max-mib": 8
},
"holds",
"windows",
"mirrors",
"findings"
]
{
"name": "holds",
"max-mib": 8
},
{
"name": "windows",
"max-mib": 8
},
{
"name": "mirrors",
"max-mib": 8
},
{
"name": "findings",
"max-mib": 8
},
{
"name": "taken",
"key-ttl": true,
"max-mib": 8
}
],
"config": {
"ask-taken-bound": {
"type": "string",
"description": "How long the registry keeps the id of a publish ask it took, as a duration such as 10m (design 47 H2 §775): a publish given again with that id within it acts not again but answers the transfer as it stands. The largest caller's bound, the pipeline runner's ask-unanswered-bound, by default.",
"trusted": false,
"runtime": true,
"default": "10m"
}
}
}
+1
View File
@@ -1,6 +1,7 @@
{
"module": "dmenu",
"version": "0.1",
"class": "leaf",
"capabilities": [
"package-manager"
],
+1
View File
@@ -1,6 +1,7 @@
{
"module": "dnsmasq",
"version": "0.1",
"class": "core",
"upgrade": {
"policy": "record",
"why": "the mesh's resolver: a build that breaks it can stop a machine resolving the bus, and then neither the gate's rollback nor a push reaches it (hq ADR 0236, issue 260)"
+1
View File
@@ -1,6 +1,7 @@
{
"module": "docker-compose",
"version": "0.1",
"class": "leaf",
"capabilities": [
"package-manager"
],
+1
View File
@@ -1,6 +1,7 @@
{
"module": "docker",
"version": "0.1",
"class": "core",
"capabilities": [
"package-manager",
"service-manager",
+1
View File
@@ -1,6 +1,7 @@
{
"module": "dunst",
"version": "0.1",
"class": "core",
"moved": true,
"capabilities": [
"package-manager"
+1
View File
@@ -1,6 +1,7 @@
{
"module": "fail2ban",
"version": "0.1",
"class": "core",
"capabilities": [
"firewall"
],
+1
View File
@@ -1,5 +1,6 @@
// feh's Go tools bundle (novox/hq ADR 0188, ADR 0193, ADR 0208): the wallpaper's tools, served by the
// node's runtime as the operator account.
// Design 47 H1, proof 1: this comment is the single-module change its pipeline delivers.
package main
import (
+2 -2
View File
@@ -1,6 +1,6 @@
#!/bin/sh
# The wallpaper (module feh, novox/hq ADR 0208). Owned by the mesh: replaced at every push. The
# The wallpaper (module feh, novox/hq ADR 0208). Owned by the mesh: replaced at every delivery. The
# session's start runs it, and so may anything that wants the declared wallpaper back. The image is
# the module's own, in ~/.local/share/feh/wallpapers. feh_set changes the wallpaper for a session
# without touching this file.
# without touching this file (design 47 H1, proof 1 (second run): delivered by its pipeline, 2026-11-21).
feh --no-fehbg --bg-fill "$HOME/.local/share/feh/wallpapers/default.jpg"
+1
View File
@@ -1,6 +1,7 @@
{
"module": "feh",
"version": "0.1",
"class": "leaf",
"moved": true,
"capabilities": [
"package-manager"
+1
View File
@@ -1,6 +1,7 @@
{
"module": "flatpak",
"version": "0.1",
"class": "leaf",
"capabilities": [
"package-manager"
],
+1
View File
@@ -1,6 +1,7 @@
{
"module": "fonts",
"version": "0.1",
"class": "leaf",
"capabilities": [
"package-manager"
],
+1
View File
@@ -1,6 +1,7 @@
{
"module": "forticlient",
"version": "0.1",
"class": "leaf",
"upgrade": {
"policy": "record",
"why": "its adapter routes the company's domains on the machine a person works on: a build that breaks it cuts the person off from work names until a person pushes the next (hq ADR 0236, ADR 0247)"
+6 -4
View File
@@ -100,7 +100,8 @@ search that reaches the call's deadline stops there and answers what it found, w
It reaches the forge through the same HTTP client as the package-registry bundle (`internal/forgehttp`), as the
tools' own account (novox/hq ADR 0365 §2, issue 469): the token the TypeScript bundle mints for `mesh-tools` and
keeps (`MESH_GITEA_TOKEN_FILE`), sent only when its scopes line names that account, never the admin login. One tool
keeps in the vault as the module's own (`module/gitea/mesh-tools`, design 47 H2 §808), read through the vault seat's
`get` at start and at each `secret-changed` naming it, never the admin login. One tool
call takes at most 50 seconds.
`go test ./cmd/forge` runs it against a fake forge: the files of one commit created, updated and deleted on
a new branch from its base; an existing branch committed on; the default branch, a protected branch and
@@ -247,9 +248,10 @@ version already gone counts as deleted.
Over the forge's HTTP interface on the machine (`MESH_GITEA_URL`), never as the admin account (design 51: each
holder keeps its write side as an own secret beside a read-only tool token). It **reads** as the tools' account,
with the token the TypeScript bundle keeps for it (`MESH_GITEA_TOKEN_FILE`, scopes including `read:package`), and
**writes** (a publish, a remove, retention's deletion) as the packages account `mesh-packages`
(`MESH_GITEA_PACKAGES_USER`), with its own token (`MESH_GITEA_PACKAGES_TOKEN_FILE`, the one scope `write:package`).
with the token the TypeScript bundle keeps for it in the vault (`module/gitea/mesh-tools`, scopes including
`read:package`), and **writes** (a publish, a remove, retention's deletion) as the packages account `mesh-packages`
(`MESH_GITEA_PACKAGES_USER`), with its own token (`module/gitea/mesh-packages`, the one scope `write:package`), both
read through the vault seat's `get` at start and at each `secret-changed` (design 47 H2 §808).
That account is plain, a member of the team `mesh-packages` that writes the organisation's packages and nothing else;
the watcher makes it with the administrator's login and mints and keeps its token at its start (`packages-account.ts`).
No timer looks at it after that: when the forge refuses a write (401) this bundle raises the finding
+111
View File
@@ -0,0 +1,111 @@
// **The call is written before its first merge** (novox/hq design 47 H §766; H-A-18, H-A-47, H-A-71): before it merges
// anything, the forge module writes the call's key `call.<call>` in its own template state `calls` (the seat git's
// definition declares it): `by`, the bus account the tool runner proved, `at`, the members, each with its base `branch`
// and `state` judged, merged with its commit, or refused with why, and `said`, whether its `merge-called` was said. Each
// member is updated as it merges. A call is kept `call-retention` (a setting, default 30 days), then deleted by the forge
// module on each new call's write, oldest first, with no timer (H-A-47).
import { readFileSync } from "node:fs";
import type { State } from "@novox/mesh-sdk/state";
import {
callsByCallCallKey, mergeCalledSubject, parseCallsByCallCallKey, type Call, type CallMember, type MergeCalledEvent,
} from "@novox/mesh-delivery-contracts-git";
/** call-retention's default, in days (§766). */
export const CALL_RETENTION_DAYS = 30;
/** call-retention as the module's config file says it, in days; the default when it says none (mainrules.ts' form). */
export function callRetentionDays(env: NodeJS.ProcessEnv = process.env): number {
const file = env.MESH_GITEA_CONFIG_FILE;
if (!file) return CALL_RETENTION_DAYS;
try {
const v = Number((JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>)["call-retention"]);
return Number.isInteger(v) && v >= 1 ? v : CALL_RETENTION_DAYS;
} catch { return CALL_RETENTION_DAYS; }
}
/** One kept call with its id. */
export interface KeptCall extends Call {
call: string;
}
/** The state `calls`: one key per merge call. */
export class Calls {
constructor(private readonly st: State<unknown>, private readonly retentionDays: () => number = () => CALL_RETENTION_DAYS,
private readonly log: (line: string) => void = () => {}) {}
/** Every call kept, newest first. */
async all(): Promise<KeptCall[]> {
const out: KeptCall[] = [];
for (const key of await this.st.keys()) {
const parsed = parseCallsByCallCallKey(key);
if (!parsed) continue;
const e = await this.st.get(key);
if (e?.value) out.push({ ...(e.value as Call), call: parsed.call });
}
return out.sort((a, b) => (a.at < b.at ? 1 : a.at > b.at ? -1 : a.call < b.call ? 1 : -1));
}
/** One call, or undefined. */
async get(call: string): Promise<KeptCall | undefined> {
const e = await this.st.get(callsByCallCallKey(call));
return e?.value ? { ...(e.value as Call), call } : undefined;
}
/** Writes a call. A new call (none kept under its key) first deletes the calls past call-retention, oldest first. */
async put(call: string, value: Call, now: Date = new Date()): Promise<void> {
if (!(await this.st.get(callsByCallCallKey(call)))?.value) await this.expire(now);
await this.st.put(callsByCallCallKey(call), value);
}
/** Deletes the calls whose `at` is past call-retention before now, oldest first; answers the calls deleted. */
async expire(now: Date): Promise<string[]> {
const before = now.getTime() - this.retentionDays() * 86_400_000;
const old = (await this.all()).filter((c) => (Date.parse(c.at) || 0) < before).reverse();
for (const c of old) await this.st.delete(callsByCallCallKey(c.call));
if (old.length) this.log(`${old.length} merge calls past ${this.retentionDays()} days deleted: ${old.map((c) => c.call).join(", ")}`);
return old.map((c) => c.call);
}
}
/** A kept member of a call. */
export const keptMember = (m: { repository: string; number: number; branch: string; head: string; state: CallMember["state"];
commit?: string; why?: string }): CallMember => ({ repository: m.repository, number: m.number, branch: m.branch, head: m.head,
state: m.state, ...(m.commit ? { commit: m.commit } : {}), ...(m.why ? { why: m.why } : {}) });
/** Says a seat event on its subject, under an id the bus keeps once. */
export type Say = (subject: string, body: unknown, id?: string) => Promise<void>;
/** The merge-called of a kept call (design 47 H §736, §767): its landed members, each with its base and merge commit, and its
* refused ones; undefined for a call that landed no member, which says none. */
export function mergeCalledOf(c: KeptCall): MergeCalledEvent | undefined {
const landed = c.members.filter((m) => m.state === "merged" && m.commit);
if (landed.length === 0) return undefined;
// A member judged and not merged (a stop mid-call) is in neither: its head is an untaken head (§740).
const refused = c.members.filter((m) => m.state === "refused");
return { call: c.call, by: c.by, account: c.account, at: c.at,
members: landed.map((m) => ({ repository: m.repository, number: m.number, branch: m.branch, head: m.head, commit: m.commit! })),
...(refused.length ? { refused: refused.map((m) => ({ repository: m.repository, number: m.number, why: m.why ?? "not merged" })) } : {}) };
}
/** Says a call's merge-called, when it landed a member; answers whether it said one. */
export async function sayCall(c: KeptCall, say: Say): Promise<boolean> {
const body = mergeCalledOf(c);
if (!body) return false;
await say(mergeCalledSubject(c.call), body, `merge-called.${c.call}`);
return true;
}
/** At the start (§766): every call whose event is not said says merge-called for what landed, and is kept said, so a stop
* between the last merge and the event loses nothing it recorded. Answers the calls said. */
export async function sayUnsaid(calls: Calls, say: Say, log: (line: string) => void = () => {}): Promise<string[]> {
const said: string[] = [];
for (const c of await calls.all()) {
if (c.said) continue;
if (await sayCall(c, say)) said.push(c.call);
const { call, ...value } = c;
await calls.put(call, { ...value, said: true });
}
if (said.length) log(`merge-called said again at the start for ${said.join(", ")}`);
return said;
}
+43 -3
View File
@@ -182,7 +182,19 @@ export const FORGE_REQUEST_TIMEOUT_MS = 20_000;
/** The most a tool's answer carries of one file: the bus's message bound is 1 MiB and a file travels as text (issue 1577). */
export const MAX_FILE_BYTES = 512 * 1024;
/** A directory of a listing's `files` the commit does not hold: the seat git answers it with the kind not-found, the error
* naming the directory (seat.ts failure; novox/hq design 47 H H-A-232). */
export class DirectoryNotInTree extends Error {
constructor(message: string) {
super(message);
this.name = "DirectoryNotInTree";
}
}
/** One request to the forge, cut at the limit and failing loud naming the request. */
/** What a forge's answer says when its store does not answer (design 47 H2 §776). */
const STORE_UNAVAILABLE = /database|\bdb\b|store/i;
async function timedFetch(url: string, init: RequestInit, label: string, timeoutMs: number): Promise<Response> {
try {
return await fetch(url, { ...init, signal: init.signal ? AbortSignal.any([init.signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs) });
@@ -267,6 +279,28 @@ export class GiteaClient {
return this.request<T>(path, options);
}
/**
* The forge's own version read, unauthenticated (GET /api/v1/version): whether the forge answers at all, and whether
* it names its store unavailable (design 47 H2 §776). What the seat git reads before it says a 401, a 502, a 503 or a
* connection fault is the forge's refusal or the forge away; never throws.
*/
async forgeVersion(): Promise<{ ok: true; version: string } | { ok: false; words: string; store: boolean }> {
const label = "GET /version";
try {
const res = await timedFetch(`${this.baseUrl}/api/v1/version`, { headers: { Accept: "application/json" } }, label, this.requestTimeoutMs);
const text = await res.text();
const store = STORE_UNAVAILABLE.test(text);
if (!res.ok) return { ok: false, words: `the forge's version read answered ${res.status} ${text}`.trim(), store };
let version = "";
try { version = String(JSON.parse(text)?.version ?? ""); } catch { /* no version said */ }
if (store) return { ok: false, words: `the forge's version read names its store unavailable: ${text}`, store };
if (!version) return { ok: false, words: `the forge's version read named no version: ${text}`, store };
return { ok: true, version };
} catch (err) {
return { ok: false, words: `the forge's version read: ${err instanceof Error ? err.message : String(err)}`, store: false };
}
}
// ---- Repositories ----
/** Every repository this token can see, one page. `/user/repos` is only what the token's own
@@ -490,11 +524,17 @@ export class GiteaClient {
}
/** One page of a repository's tags, newest first, by name: what the seat git's `tags` answers. */
async tags(owner: string, repo: string, page: number, limit: number): Promise<string[]> {
async tags(owner: string, repo: string, page: number, limit: number): Promise<{ tag: string; commit: string }[]> {
if (!Number.isInteger(page) || page < 1) throw new Error(`${page} is not a page, from 1`);
const list = await this.request<any[]>(`${repoPath(owner, repo)}/tags?page=${page}&limit=${limit}`);
if (!Array.isArray(list)) throw new Error(`the forge answered no list of the tags of ${owner}/${repo}`);
return list.map((t) => String(t?.name ?? "")).filter((n) => n !== "");
// Each tag with the commit it names (design 47 H2 §796): a tag the forge names no commit for is no answer, never a
// tag without its commit.
return list.filter((t) => String(t?.name ?? "") !== "").map((t) => {
const tag = String(t.name), commit = String(t?.commit?.sha ?? "");
if (!/^[0-9a-f]{40}$/.test(commit)) throw new Error(`the forge named no commit for ${owner}/${repo}'s tag ${tag}`);
return { tag, commit };
});
}
/** The commit a tag names, or null when the repository has no such tag (the forge's 404 only). */
@@ -634,7 +674,7 @@ export class GiteaClient {
// is whole (a cut one failed above), so a directory absent from it is absent at the commit.
filesOf = {};
for (const dir of files) {
if (dir !== "" && dirOf.get(dir) === undefined) throw new Error(`the directory ${dir} is not in ${owner}/${repo} at ${sha}`);
if (dir !== "" && dirOf.get(dir) === undefined) throw new DirectoryNotInTree(`the directory ${dir} is not in ${owner}/${repo} at ${sha}`);
const prefix = dir === "" ? "" : `${dir}/`;
const blobs: Record<string, string> = {};
for (const e of entries) {
+40 -22
View File
@@ -1,35 +1,54 @@
package main
// The commit and the reads act as the tools' own account (novox/hq ADR 0365 §2, issue 469): the token the module
// keeps for `mesh-tools`, never the admin login. That account is no repository's administrator, so the forge
// keeps for `mesh-tools` in the vault (design 47 H2 §808), never the admin login. That account is no repository's administrator, so the forge
// refuses it the protection rules (403, as gitea's reqAdmin does); the commit then judges an existing branch by the
// protection the forge says it applies, and leaves a branch not made yet to the forge's own judgement.
import (
"context"
"encoding/json"
"fmt"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"strings"
"testing"
"git.novox.be/novox/mesh-sdk/go/seal"
"gitea/internal/forgehttp"
)
const toolsToken = "tools-token-never-shown"
// asTools serves the fake forge to a bundle holding the tools' token: only that token is taken, the rules are
// refused as to a non-administrator, and the branches named protected say so as the forge does.
func asTools(t *testing.T, f *fakeForge, protected map[string]string, scopes string) (*Forge, *[]string) {
dir := t.TempDir()
file := filepath.Join(dir, "token")
if err := os.WriteFile(file, []byte(toolsToken+"\n"), 0o600); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(file+".scopes", []byte(scopes+"\n"), 0o600); err != nil {
// vaultHolding is the vault seat's get answering account's token sealed to the key it is asked with; "" holds none.
func vaultHolding(t *testing.T, account, token string) *forgehttp.VaultToken {
t.Helper()
v, err := forgehttp.NewVaultToken(account, func(address string, args any) (json.RawMessage, error) {
a := args.(map[string]any)
if address != forgehttp.VaultGet || a["name"] != forgehttp.VaultName(account) {
return nil, fmt.Errorf("asked %s for %v", address, a["name"])
}
if token == "" {
return nil, fmt.Errorf("the vault holds no secret named %s", a["name"])
}
// The value the minter writes: the token and the scopes it was minted with (H-A-439).
value, _ := json.Marshal(map[string]any{"token": token, "scopes": []string{"write:repository", "write:issue", "read:user", "read:package"}})
box, err := seal.Seal(string(value), a["public_key"].(string))
if err != nil {
return nil, err
}
return json.Marshal(map[string]any{"name": a["name"], "generation": 1, "sealed": box})
})
if err != nil {
t.Fatal(err)
}
return v
}
// asTools serves the fake forge to a bundle holding the token the vault hands: only the tools' token is taken, the
// rules are refused as to a non-administrator, and the branches named protected say so as the forge does.
func asTools(t *testing.T, f *fakeForge, protected map[string]string, held string) (*Forge, *[]string) {
var seen []string
const repo = "/api/v1/repos/acme/app"
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -52,12 +71,12 @@ func asTools(t *testing.T, f *fakeForge, protected map[string]string, scopes str
f.handle(w, r)
}))
t.Cleanup(srv.Close)
return &Forge{Client: forgehttp.Client{URL: srv.URL, TokenFile: file, Account: "mesh-tools"}}, &seen
return &Forge{Client: forgehttp.Client{URL: srv.URL, Token: vaultHolding(t, "mesh-tools", held), Account: "mesh-tools"}}, &seen
}
func TestTheToolsAccountCommitsOnANewBranchWithItsTokenThoughTheRulesAreNotItsToRead(t *testing.T) {
f := newFake(t)
forge, _ := asTools(t, f, nil, "read:user,write:issue,write:repository for mesh-tools")
forge, _ := asTools(t, f, nil, toolsToken)
got, err := commit(context.Background(), forge, ask(t, map[string]any{"branch": "fix/365",
"files": filesArg(map[string]any{"path": "x", "content": "x"})}))
if err != nil {
@@ -75,7 +94,7 @@ func TestTheToolsAccountIsRefusedAProtectedBranchTheForgeSaysItGuardsAndTheDefau
if rule != "" {
protected[branch] = rule
}
forge, _ := asTools(t, f, protected, "read:user,write:issue,write:repository for mesh-tools")
forge, _ := asTools(t, f, protected, toolsToken)
_, err := commit(context.Background(), forge, ask(t, map[string]any{"branch": branch,
"files": filesArg(map[string]any{"path": "x", "content": "x"})}))
if err == nil || !strings.Contains(err.Error(), "refused") || !strings.Contains(err.Error(), "ADR 0266") {
@@ -90,13 +109,13 @@ func TestTheToolsAccountIsRefusedAProtectedBranchTheForgeSaysItGuardsAndTheDefau
}
}
func TestATokenKeptForTheAdministratorIsNeverSent(t *testing.T) {
func TestNoTokenIsSentWhileTheVaultHoldsNoneForTheAccount(t *testing.T) {
f := newFake(t)
// What the module kept before ADR 0365: the admin's token, its scopes line naming no account.
forge, seen := asTools(t, f, nil, "read:user,write:issue,write:repository")
// Design 47 H2 §808: the token is read through the vault seat's get; while the module has minted none, nothing goes.
forge, seen := asTools(t, f, nil, "")
_, err := commit(context.Background(), forge, ask(t, map[string]any{"branch": "fix/365",
"files": filesArg(map[string]any{"path": "x", "content": "x"})}))
if err == nil || !strings.Contains(err.Error(), "not mesh-tools's") {
if err == nil || !strings.Contains(err.Error(), "not kept yet") {
t.Fatalf("%v", err)
}
if len(*seen) != 0 {
@@ -104,9 +123,8 @@ func TestATokenKeptForTheAdministratorIsNeverSent(t *testing.T) {
}
}
func TestTheBundleHandedATokenFileNeedsNoAdminLogin(t *testing.T) {
func TestTheBundleReadsItsTokenFromTheVaultAndNeedsNoAdminLogin(t *testing.T) {
t.Setenv("MESH_GITEA_URL", "http://127.0.0.1:3000")
t.Setenv("MESH_GITEA_TOKEN_FILE", "/state/token")
t.Setenv("MESH_GITEA_TOOLS_USER", "")
t.Setenv("MESH_GITEA_ADMIN_USER", "")
t.Setenv("MESH_GITEA_ADMIN_PASSWORD_FILE", "")
@@ -114,7 +132,7 @@ func TestTheBundleHandedATokenFileNeedsNoAdminLogin(t *testing.T) {
if err != nil {
t.Fatal(err)
}
if f.TokenFile != "/state/token" || f.Account != "mesh-tools" || f.User != "" || f.PasswordFile != "" {
if f.Token == nil || f.Token.Account != "mesh-tools" || f.Account != "mesh-tools" || f.User != "" || f.PasswordFile != "" {
t.Fatalf("%+v", f.Client)
}
}
+4 -1
View File
@@ -21,7 +21,10 @@ type Forge struct {
// ForgeFromEnv is the forge as the manifest hands it to this bundle.
func ForgeFromEnv() (*Forge, error) {
c, missing := forgehttp.FromEnv()
c, missing, err := forgehttp.ToolsFromEnv()
if err != nil {
return nil, err
}
if len(missing) > 0 {
return nil, fmt.Errorf("the forge cannot be reached: %s not set by the manifest", strings.Join(missing, ", "))
}
+8 -2
View File
@@ -691,8 +691,8 @@ func TestToolsAreTheOnesTheReadmeNamesAndTheManifestBuilds(t *testing.T) {
// The tools' own account, never the admin login (novox/hq ADR 0365 §2); the package registry's bundle also writes
// as the packages account (design 51: the write side an own secret beside a read-only tool token).
wants := map[string][]string{
"cmd/forge": {"MESH_GITEA_URL", "MESH_GITEA_TOOLS_USER", "MESH_GITEA_TOKEN_FILE"},
"cmd/package-registry": {"MESH_GITEA_URL", "MESH_GITEA_TOOLS_USER", "MESH_GITEA_TOKEN_FILE", "MESH_GITEA_PACKAGES_USER", "MESH_GITEA_PACKAGES_TOKEN_FILE"},
"cmd/forge": {"MESH_GITEA_URL", "MESH_GITEA_TOOLS_USER"},
"cmd/package-registry": {"MESH_GITEA_URL", "MESH_GITEA_TOOLS_USER", "MESH_GITEA_PACKAGES_USER"},
}
for _, a := range m.Build.Artifacts {
want, ok := wants[a.From]
@@ -713,6 +713,12 @@ func TestToolsAreTheOnesTheReadmeNamesAndTheManifestBuilds(t *testing.T) {
t.Errorf("%s is given %s: it acts as an account of its own, not the administrator", a.From, k)
}
}
// Design 47 H2 §808, H-A-422 (1): the token is read through the vault seat's get, never from a file.
for _, k := range []string{"MESH_GITEA_TOKEN_FILE", "MESH_GITEA_PACKAGES_TOKEN_FILE"} {
if a.Env[k] != "" {
t.Errorf("%s is given %s: its token is read from the vault", a.From, k)
}
}
}
for from := range wants {
t.Errorf("the manifest builds no %s bundle", from)
+12
View File
@@ -14,6 +14,8 @@ import (
"strings"
stdio "git.novox.be/novox/mesh-sdk/go"
"gitea/internal/forgehttp"
)
// ToolNames are the tools this bundle serves. The module's manifest lists no `tools` (see the package-registry
@@ -21,6 +23,16 @@ import (
var ToolNames = []string{"gitea_commit", "gitea_commits", "gitea_compare", "gitea_pull_reviews", "gitea_list_dir", "gitea_search_code"}
func main() {
// The tools' account's token, read from the vault at start and at each secret-changed naming it (design 47 H2 §808).
go func() {
account := os.Getenv("MESH_GITEA_TOOLS_USER")
if account == "" {
account = forgehttp.ToolsAccount
}
if err := forgehttp.Follow(func(f string, a ...any) { fmt.Fprintf(os.Stderr, f+"\n", a...) }, account); err != nil {
fmt.Fprintln(os.Stderr, "the vault's changes of the forge token are not heard:", err)
}
}()
if err := stdio.Serve("", Tools(ForgeFromEnv)); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
+9 -3
View File
@@ -78,8 +78,14 @@ func (f *Forge) As(typ string) *Forge {
// ForgeFromEnv is the forge as the manifest hands it to this bundle.
func ForgeFromEnv() (*Forge, error) {
c, missing := forgehttp.FromEnv()
w, writeMissing := forgehttp.WriterFromEnv()
c, missing, err := forgehttp.ToolsFromEnv()
if err != nil {
return nil, err
}
w, writeMissing, err := forgehttp.WriterFromEnv()
if err != nil {
return nil, err
}
for _, m := range writeMissing {
if m != "MESH_GITEA_URL" {
missing = append(missing, m)
@@ -168,7 +174,7 @@ func (f *Forge) DistTags(ctx context.Context, name string) (map[string]string, e
// write is the registry's write side, refused when the manifest handed none.
func (f *Forge) write() (*forgehttp.Client, error) {
if f.Writer == nil {
return nil, errors.New("the package registry's write side is not handed to this bundle (MESH_GITEA_PACKAGES_TOKEN_FILE); nothing was written")
return nil, errors.New("the package registry's write side is not handed to this bundle (the packages account's token); nothing was written")
}
return f.Writer, nil
}
@@ -17,6 +17,7 @@ import (
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/views"
"gitea/internal/forgehttp"
"gitea/internal/packageseats"
)
@@ -49,6 +50,19 @@ func main() {
os.Exit(1)
}
}()
// Both accounts' tokens, read from the vault at start and at each secret-changed naming one (design 47 H2 §808).
go func() {
tools, packages := os.Getenv("MESH_GITEA_TOOLS_USER"), os.Getenv("MESH_GITEA_PACKAGES_USER")
if tools == "" {
tools = forgehttp.ToolsAccount
}
if packages == "" {
packages = forgehttp.PackagesAccount
}
if err := forgehttp.Follow(func(f string, a ...any) { fmt.Fprintf(os.Stderr, f+"\n", a...) }, tools, packages); err != nil {
fmt.Fprintln(os.Stderr, "the vault's changes of the forge tokens are not heard:", err)
}
}()
forge := func() (*Forge, error) { return ForgeFromEnv() }
holder := func() (*packageseats.Holder, error) { return busHolder(forge) }
go followIdle(holder)
@@ -480,22 +480,24 @@ func TestToolsAreTheOnesTheReadmeNamesAndSayWhatTheyDo(t *testing.T) {
Objects any `json:"objects"`
State any `json:"state"`
}{m.Objects, m.State})
for _, want := range []string{`"name":"incoming"`, `"transfers"`, `"key-ttl":true,"name":"idle"`} {
// Each with its cap (design 47 H2 §812, H-A-411 (2)).
for _, want := range []string{`"name":"incoming"`, `"name":"transfers"`, `"key-ttl":true,"max-mib":8,"name":"idle"`} {
if !strings.Contains(string(req), want) {
t.Errorf("the manifest does not keep %s in its old sections (%s)", want, req)
}
}
// findings is one local name in one form (novox/hq ADR 0595 §11): the old section state, which the TypeScript bundle
// announces readable for the condition keeper (kept.ts), never also under requires.
if strings.Contains(string(req), `"name":"findings"`) {
t.Errorf("findings is required as well as kept in state: %s", req)
if required, _ := json.Marshal(m.Requires); strings.Contains(string(required), `"name":"findings"`) {
t.Errorf("findings is required as well as kept in state: %s", required)
}
// transfers keeps for good: a lifetime of its own would drop a transfer's key and leave its chunks in incoming.
if strings.Contains(string(req), `"name":"transfers","options"`) {
t.Errorf("transfers has options (a lifetime): %s", req)
}
// The retention asks the builder's versions; the forge's other bundles ask the catalog half and record a re-read.
if strings.Join(m.Invokes, ",") != "seat:mesh-catalog.revision,seat:mesh-catalog.registrations,seat:mesh-hand-acts.hand-act,seat:mesh-builds.reserved" {
// The forge module's tokens through the vault seat: own-put by the minter, get by every process (design 47 H2 §808).
if strings.Join(m.Invokes, ",") != "seat:mesh-catalog.revision,seat:mesh-catalog.registrations,seat:mesh-hand-acts.hand-act,seat:mesh-builds.reserved,seat:mesh-vault.own-put,seat:mesh-vault.get" {
t.Errorf("the manifest invokes %v", m.Invokes)
}
if len(m.Tools) != 0 {
@@ -505,7 +507,7 @@ func TestToolsAreTheOnesTheReadmeNamesAndSayWhatTheyDo(t *testing.T) {
for _, a := range m.Build.Artifacts {
if a.From == "cmd/package-registry" {
found = true
for _, k := range []string{"MESH_GITEA_URL", "MESH_GITEA_TOKEN_FILE", "MESH_GITEA_PACKAGES_TOKEN_FILE", "MESH_NPM_OWNER"} {
for _, k := range []string{"MESH_GITEA_URL", "MESH_NPM_OWNER"} {
if a.Env[k] == "" {
t.Errorf("the bundle is not given %s", k)
}
+1 -1
View File
@@ -291,7 +291,7 @@ func verbTools[PI, PA, PPI, PPA, VI, VA, RI, RA any](seat string, holder func()
}
return []stdio.Tool{
{Name: seat + "." + packageseats.VerbPublish, Input: obj,
Description: "Open a transfer of a package's one file (ADR 0611): its name, the builder's version, kind package, its sha256 digest and the file as its one part; answers the part the forge lacks. A version held with that digest answers held and says published.",
Description: "Open a transfer of a package's one file (ADR 0611): its name, the builder's version, kind package, its sha256 digest and the file as its one part; answers the part the forge lacks. A version held with that digest answers held and says published; with no part at all (the builder's publish again) nothing moves: held says published, else refused as not stored, naming the digest (design 47 G A-490).",
Run: run(func(h *packageseats.Holder, args map[string]any) (any, error) {
in, err := as[PI](args)
if err != nil {
@@ -9,17 +9,17 @@ import (
"encoding/base64"
"encoding/hex"
"encoding/json"
"fmt"
"io"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"strings"
"sync"
"testing"
"time"
keyparts "git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/seal"
"git.novox.be/novox/mesh-sdk/go/views"
"gitea/internal/forgehttp"
@@ -116,15 +116,10 @@ func TestThePackageSeatsStoreIntoTheForge(t *testing.T) {
g := &registry{uploaded: map[string][]byte{}, held: map[string][]byte{}}
srv := httptest.NewServer(http.HandlerFunc(g.handle))
defer srv.Close()
dir := t.TempDir()
kept := func(name, token, line string) string {
file := filepath.Join(dir, name)
_ = os.WriteFile(file, []byte(token+"\n"), 0o600)
_ = os.WriteFile(file+".scopes", []byte(line+"\n"), 0o600)
return file
}
reader := forgehttp.Client{URL: srv.URL, TokenFile: kept("token", "reader", "read:package,read:user for mesh-tools"), Account: "mesh-tools"}
writer := forgehttp.Client{URL: srv.URL, TokenFile: kept("packages-token", "writer", "write:package for mesh-packages"), Account: "mesh-packages"}
vault := map[string]string{"mesh-tools": "reader", "mesh-packages": "writer"}
writerToken := vaultHolding(t, "mesh-packages", vault)
reader := forgehttp.Client{URL: srv.URL, Token: vaultHolding(t, "mesh-tools", vault), Account: "mesh-tools"}
writer := forgehttp.Client{URL: srv.URL, Token: writerToken, Account: "mesh-packages"}
forge := &Forge{Client: reader, Writer: &writer, Owner: "acme"}
if _, err := (seatStore{forge: func() (*Forge, error) { return &Forge{Client: reader, Owner: "acme"}, nil }}).Put(packageseats.GoSeat, packageseats.Publish{}, nil); err == nil ||
!strings.Contains(err.Error(), "write side") {
@@ -138,12 +133,22 @@ func TestThePackageSeatsStoreIntoTheForge(t *testing.T) {
if k := views.FindingKey("seat", keyparts.EscapeName(packageseats.Self)+".write", PackagesTokenRefused); k != PackagesTokenRefusedKey {
t.Errorf("the refusal's key is %s, the watcher watches %s", k, PackagesTokenRefusedKey)
}
_ = os.WriteFile(writer.TokenFile, []byte("stale\n"), 0o600)
vault["mesh-packages"] = "stale"
if read, err := writerToken.Changed([]byte(`{"name":"module/gitea/mesh-packages","generation":2}`)); !read || err != nil {
t.Fatalf("the secret-changed of the packages token was not read again: %v %v", read, err)
}
if _, err := s.Put(packageseats.GoSeat, packageseats.Publish{Version: "0.1.15"}, moduleZip(t, "git.example/acme/sdk@v0.1.15")); err == nil ||
len(refused) != 1 || !refused[0] {
t.Errorf("a write the forge refused with 401 raised no finding: %v %v", err, refused)
}
_ = os.WriteFile(writer.TokenFile, []byte("writer\n"), 0o600)
vault["mesh-packages"] = "writer"
// Design 47 H2 §808: a secret-changed naming another secret reads nothing; the one naming this token reads it again.
if read, _ := writerToken.Changed([]byte(`{"name":"module/gitea/mesh-tools","generation":3}`)); read {
t.Error("a secret-changed of the tools' token read the packages token again")
}
if read, err := writerToken.Changed([]byte(`{"name":"module/gitea/mesh-packages","generation":3}`)); !read || err != nil {
t.Fatalf("the secret-changed of the packages token was not read again: %v %v", read, err)
}
tgz := tarball(t, `{"name":"@acme/contracts","version":"0.1.15-feat-x.2","main":"index.js"}`)
p := packageseats.Publish{Name: "@acme/contracts", Version: "0.1.15-feat-x.2", Tag: "feat-x", Kind: packageseats.KindPackage, Digest: "sha256:" + sha(tgz)}
@@ -197,3 +202,30 @@ func TestThePackageSeatsStoreIntoTheForge(t *testing.T) {
t.Errorf("a write the forge took after the refusal did not clear it: %v", refused)
}
}
// vaultHolding is the vault seat's get answering account's token from held, sealed to the key it is asked with; an
// account held has no entry is a secret the vault holds none of.
func vaultHolding(t *testing.T, account string, held map[string]string) *forgehttp.VaultToken {
t.Helper()
v, err := forgehttp.NewVaultToken(account, func(address string, args any) (json.RawMessage, error) {
a := args.(map[string]any)
if address != forgehttp.VaultGet || a["name"] != forgehttp.VaultName(account) {
return nil, fmt.Errorf("asked %s for %v", address, a["name"])
}
token, ok := held[account]
if !ok {
return nil, fmt.Errorf("the vault holds no secret named %s", a["name"])
}
// The value the minter writes: the token and the scopes it was minted with (H-A-439).
value, _ := json.Marshal(map[string]any{"token": token, "scopes": []string{"write:repository", "write:issue", "read:user", "read:package"}})
box, err := seal.Seal(string(value), a["public_key"].(string))
if err != nil {
return nil, err
}
return json.Marshal(map[string]any{"name": a["name"], "generation": 1, "sealed": box})
})
if err != nil {
t.Fatal(err)
}
return v
}
@@ -40,6 +40,7 @@ import (
"github.com/nats-io/nats.go/jetstream"
"git.novox.be/novox/mesh-sdk/go/buscalls"
"git.novox.be/novox/mesh-sdk/go/seal"
"git.novox.be/novox/mesh-sdk/go/testbus"
"gitea/internal/packageseats"
@@ -65,6 +66,7 @@ type player struct {
answers map[string]chan wire
puts map[string][]byte // the put sessions open, by call
gets map[string][]byte // the get sessions open, by call
vault map[string]string // the vault's secrets the seat's get hands, by name (design 47 H2 §808)
}
func (p *player) send(m map[string]any) {
@@ -130,6 +132,21 @@ func (p *player) handle(m wire) {
break
}
p.answer(m.ID, map[string]any{"module": "m", "version": q.Version, "artifacts": []map[string]any{{"artifact": "m:a", "digest": d}}}, nil)
case m.Method == "mesh/ask" && a.Key == "seat:mesh-vault.get":
var q struct {
Name string `json:"name"`
PublicKey string `json:"public_key"`
}
_ = json.Unmarshal(a.Body, &q)
token, ok := p.vault[q.Name]
if !ok {
p.answer(m.ID, nil, errors.New("the vault holds no secret named "+q.Name))
break
}
// The value the minter writes: the token and the scopes it was minted with (H-A-439).
value, _ := json.Marshal(map[string]any{"token": token, "scopes": []string{"write:repository", "write:issue", "read:user", "read:package"}})
box, err := seal.Seal(string(value), q.PublicKey)
p.answer(m.ID, map[string]any{"name": q.Name, "generation": 1, "sealed": box}, err)
case m.Method == "mesh/seat.publish":
p.answer(m.ID, map[string]any{}, p.nc.Publish(a.Subject, a.Body))
case m.Method == "mesh/capabilities":
@@ -378,17 +395,9 @@ func TestThePackageSeatsWhole(t *testing.T) {
}
}))
t.Cleanup(srv.Close)
dir := t.TempDir()
kept := func(name, token, line string) string {
file := filepath.Join(dir, name)
_ = os.WriteFile(file, []byte(token+"\n"), 0o600)
_ = os.WriteFile(file+".scopes", []byte(line+"\n"), 0o600)
return file
}
cmd := exec.CommandContext(ctx, bin)
cmd.Env = append(os.Environ(), "MESH_NODE=novox", "MESH_GITEA_URL="+srv.URL, "MESH_NPM_OWNER=acme", "MESH_GITEA_TOOLS_USER=mesh-tools",
"MESH_GITEA_TOKEN_FILE="+kept("token", "reader", "read:package,read:user,write:issue,write:repository for mesh-tools"),
"MESH_GITEA_PACKAGES_TOKEN_FILE="+kept("packages-token", "writer", "write:package for mesh-packages"))
"MESH_GITEA_PACKAGES_USER=mesh-packages")
cmd.Stderr = os.Stderr
in, _ := cmd.StdinPipe()
out, _ := cmd.StdoutPipe()
@@ -400,6 +409,7 @@ func TestThePackageSeatsWhole(t *testing.T) {
zipped := bigZip(t, "git.example/acme/sdk@v0.1.15")
digest := "sha256:" + sha(zipped)
p := &player{ctx: ctx, t: t, nc: nc, js: js, in: in, answers: map[string]chan wire{},
vault: map[string]string{"module/gitea/mesh-tools": "reader", "module/gitea/mesh-packages": "writer"},
numbered: map[string]string{"git.example/acme/sdk@0.1.15": digest}}
go p.serve(out)
p.send(map[string]any{"id": "init", "method": "initialize", "params": map[string]any{}})
-4
View File
@@ -36,10 +36,6 @@ func runSync() int {
missing = append(missing, k)
}
}
if forge.TokenFile != "" {
// The tools' account cannot make or protect a repository, and must not (ADR 0428 §8).
missing = append(missing, "the setup login (MESH_GITEA_TOKEN_FILE is set instead)")
}
if len(missing) > 0 {
fmt.Fprintf(os.Stderr, "repositories: %v not set by the manifest; nothing was changed\n", missing)
return 1
+9
View File
@@ -68,6 +68,15 @@ export async function appendNote(runner: Runner, container: string, owner: strin
return { added: true, lines: lines.length + 1 };
}
/** Whether a commit's note holds a line carrying the act's id, read without writing (design 47 H2 §775: a repeat of a
* taken ask answers what its act did). */
export async function noteHolds(runner: Runner, container: string, owner: string, repo: string, commit: string,
notesRef: string, id: string): Promise<boolean> {
const shown = await runner("docker", noteArgs(container, owner, repo, commit, notesRef));
if (shown.code !== 0 && shown.code !== 1) throw new Error(`the note on ${commit.slice(0, 8)} could not be read (git exited ${shown.code})`);
return shown.code === 0 && shown.stdout.split("\n").some((l) => l.includes(`[${id}]`));
}
/** The marker that makes one comment of a pull request the delivery's view. */
export const VIEW_MARKER = "<!-- mesh-delivery:view -->";
+46 -3
View File
@@ -19,6 +19,7 @@ import {
failedStepsByModuleFingerprintStepKey as failedKey, type FailedStep, type PullClosedEvent, type PullMergedEvent, type PullUpdatedEvent,
} from "@novox/mesh-delivery-contracts-git";
import type { StepEndedEvent } from "@novox/mesh-delivery-contracts-mesh-pipeline-runner";
import { findingKey } from "./catalog.js";
/** The key prefix of the commits' fingerprints (§487). */
export const SEEN = "seen.";
@@ -58,6 +59,22 @@ const safe = (s: string): string => s.replace(/[^A-Za-z0-9_=/-]/g, "_");
export const seenKey = (commit: string, module: string): string => `${SEEN}${commit}.${safe(module)}`;
export const failedStepKey = (module: string, fingerprint: string, step: string): string => failedKey(safe(module), safe(fingerprint), safe(step));
/** The finding of a step-ended the forge module could not record (G §585). */
export const STEP_UNREAD = "step-unread";
/** step-unread of one step of one run (H-A-93): its key in the state findings and its value. */
export function stepUnreadFinding(run: string, module: string, step: string, at: string): { key: string; value: Record<string, any> } {
const key = findingKey("module", `${run}.${module}.${step}`, STEP_UNREAD);
const summary = `the step-ended of ${step} of ${module} in run ${run} names no build-input fingerprint, so a failure of it cannot be recorded`;
return { key, value: {
v: 1, key, kind: STEP_UNREAD, subject: { scope: "module", id: module }, severity: "warning", resolver: "operator", summary,
headline: `A step the forge module could not read: ${step} of ${module}`,
explanation: `merge-pull judges a head by the failed required steps at its fingerprint; this step-ended of run ${run} carries no fingerprint, ` +
"so the forge module could not keep it. A later step-ended of the step with its fingerprint clears this.",
resolved: "", evidence: [{ at, said: summary }], source: `gitea.${STEP_UNREAD}`, observer: "gitea", at,
} };
}
export class FailedSteps {
/** Every act runs after the one before it, so a step-ended and a head's loss never interleave their reads and writes. */
private chain: Promise<unknown> = Promise.resolve();
@@ -66,7 +83,9 @@ export class FailedSteps {
/** Whether a commit is now a watched branch's head or an open pull request's head. */
private readonly current: (commit: string) => boolean = () => false,
/** The state's fill against its caps: the bundle's state call (§623). */
private readonly fillOf: () => Promise<StateFill> = askFill) {}
private readonly fillOf: () => Promise<StateFill> = askFill,
/** The module's state findings, where step-unread is written (G §585, H-A-93); none writes no finding. */
private readonly findings?: State<unknown>) {}
private turn<T>(act: () => Promise<T>): Promise<T> {
const r = this.chain.then(act, act);
@@ -98,9 +117,13 @@ export class FailedSteps {
private record(ev: StepEndedEvent): Promise<void> {
const r = ev?.result;
const fingerprint = r?.fingerprint || ev?.fingerprint || "";
if (!r || !SHA.test(String(ev.commit ?? "")) || !fingerprint || !ev.module) return Promise.resolve();
// The fingerprint is the body's, the build-input fingerprint the runner fills in every step-ended; no field of the step's
// result is read for it (G §585, H-A-93).
const fingerprint = ev?.fingerprint || "";
if (!r || !SHA.test(String(ev.commit ?? "")) || !ev.module) return Promise.resolve();
if (!fingerprint) return this.turn(() => this.unread(ev, true));
return this.turn(async () => {
await this.unread(ev, false);
const at = ev.at ?? new Date().toISOString();
const sk = seenKey(ev.commit, ev.module);
const held = (await this.st.get(sk))?.value as Seen | undefined;
@@ -137,6 +160,26 @@ export class FailedSteps {
});
}
/**
* step-unread (G §585, H-A-93): a step-ended without its fingerprint writes the finding, scope module, its subject the step's
* module, keyed `<run>.<module>.<step>`, naming the run, the module and the step, severity warning, resolver operator; a
* later step-ended of that step with its fingerprint clears it, so a failure that could not be recorded is seen.
*/
private async unread(ev: StepEndedEvent, raise: boolean): Promise<void> {
if (!this.findings) return;
const step = String(ev.result?.step ?? ""), run = String(ev.pipeline ?? "");
const { key, value } = stepUnreadFinding(run, ev.module, step, String(ev.at ?? new Date().toISOString()));
if (!raise) {
if ((await this.findings.get(key))?.value) {
await this.findings.delete(key);
this.log(`${ev.module} ${step} of ${run} is read with its fingerprint: step-unread cleared`);
}
return;
}
await this.findings.put(key, value);
this.log(String(value.summary));
}
/** The failed `required` step that refuses this head, or null: a head with a `seen` key is judged by it, one with none merges (§487). */
judge(head: string): Promise<Judged | null> {
return this.turn(async () => {
-103
View File
@@ -1,103 +0,0 @@
// **One writer of a head's mesh/merge-gate** (novox/hq issue 446).
//
// A pending check says where it is: "waiting in the build queue since …" when the head is announced. The forge keeps only
// the newest status of a context, so two writers cannot order their writes; this module is the one writer of
// mesh/merge-gate, and every write of one head's gate goes through one chain, in the order it was asked. A recheck's
// pending (novox/hq issue 456) and a trunk's move (ADR 0323 §4) take their turns on the same chain. No verdict is written
// here any more: the controller's `checked` is no event (ADR 0571 clause 13), and main requires the checker's mesh/check.
import { CHECK_CONTEXT, pendingWords } from "./pulls.js";
import type { CommitStatus, HeadCheck } from "./client.js";
/** What the gate writer needs of the forge: a status set, and a head's statuses as the forge holds them. */
export interface GateForge {
setCommitStatus(owner: string, repo: string, sha: string, status: CommitStatus): Promise<void>;
/** The head's statuses by context, the newest of each, with their words (novox/hq ADR 0323). */
headChecks(owner: string, repo: string, sha: string): Promise<Record<string, HeadCheck>>;
}
/** Whether a repository as the mesh clones it (`http://forge/novox/hq.git`) is owner/repo. */
export function clonedAs(url: string | undefined, owner: string, repo: string): boolean {
const u = (url ?? "").trim().toLowerCase().replace(/\.git$/, "");
const full = `${owner}/${repo}`.toLowerCase();
return u === full || u.endsWith("/" + full);
}
interface Head {
/** The chain the head's writes take their turns on. */
chain: Promise<void>;
}
export class GateWriter {
private heads = new Map<string, Head>();
private forge: GateForge;
private now: () => Date;
constructor(forge: GateForge, now: () => Date = () => new Date()) {
this.forge = forge;
this.now = now;
}
private head(owner: string, repo: string, sha: string): Head {
const key = `${owner}/${repo}@${sha}`.toLowerCase();
let h = this.heads.get(key);
if (!h) {
h = { chain: Promise.resolve() };
this.heads.set(key, h);
// Kept for the heads still in play; the oldest go first, past what any forge holds open at once.
if (this.heads.size > 2000) this.heads.delete(this.heads.keys().next().value as string);
}
return h;
}
/** One turn on the head's chain; a turn that fails never stops the next. Its failure is the caller's. */
private turn(h: Head, fn: () => Promise<void>): Promise<void> {
const run = h.chain.then(fn);
h.chain = run.catch(() => {});
return run;
}
/** A turn whose failure is said here: a pending word not written is not worth the event again. */
private said(h: Head, what: string, fn: () => Promise<void>): Promise<void> {
return this.turn(h, fn).catch((err) => {
console.error(`[gitea] ${what} — ${err instanceof Error ? err.message : err}`);
});
}
/** The head announced: it waits in the build queue from now. A new check of the head, so no verdict yet. */
pending(owner: string, repo: string, sha: string): Promise<void> {
const h = this.head(owner, repo, sha);
const at = this.now();
return this.said(h, `${owner}/${repo}@${sha.slice(0, 8)}: could not say a check is pending`, () =>
this.forge.setCommitStatus(owner, repo, sha, { state: "pending", context: CHECK_CONTEXT, description: pendingWords(at) }));
}
/**
* A status the seat git's `status` verb sets (seat.ts), a recheck's pending among them (novox/hq issue 456): it takes
* its turn after every write of the head already asked for, so it lands over them, and a later write lands over it. A
* write that fails fails the caller.
*/
status(owner: string, repo: string, sha: string, status: CommitStatus): Promise<void> {
return this.turn(this.head(owner, repo, sha), () => this.forge.setCommitStatus(owner, repo, sha, status));
}
/**
* **A trunk's move puts the head's verdict out of date** (novox/hq ADR 0323 §4): its merge check statuses are put back
* to pending, with the reason, in their turn after every write of the head already asked for — a verdict in flight
* lands first. What is written is decided in the turn, from the statuses the forge holds then (`decide`, trunk.ts's
* outOfDateStatuses): a check on its way, or a verdict already judged against the trunk's head, is left as it is. It
* opens no check — nothing is asked — so a verdict of a check asked before it keeps its weight. Answers what it wrote;
* a write that fails fails the caller, and the move is weighed again on the next pass.
*/
outOfDate(owner: string, repo: string, sha: string,
decide: (checks: Record<string, HeadCheck>) => CommitStatus[] | Promise<CommitStatus[]>, target?: string): Promise<CommitStatus[]> {
const h = this.head(owner, repo, sha);
const written: CommitStatus[] = [];
return this.turn(h, async () => {
for (const s of await decide(await this.forge.headChecks(owner, repo, sha))) {
await this.forge.setCommitStatus(owner, repo, sha, target ? { ...s, target_url: target } : s);
written.push(s);
}
}).then(() => written);
}
}

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