Compare commits

...
Author SHA1 Message Date
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
256 changed files with 6919 additions and 9655 deletions
+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"
+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 "$@"
+1 -2
View File
@@ -63,7 +63,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 +82,6 @@
"tools": [
"claude_code_status",
"claude_code_render",
"claude_code_guard",
"claude_code_pull",
"claude_code_grant",
"claude_code_add_api_key",
+9
View File
@@ -24,6 +24,15 @@
"loads": [
"disk-load"
]
},
{
"name": "diskreadings",
"kind": "package",
"language": "go",
"paths": [
"diskreadings"
],
"series": "0.1"
}
]
},
@@ -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)
@@ -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)
}
@@ -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
@@ -108,6 +109,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 {
@@ -666,6 +670,22 @@ func TestTheHolderOfTheTwoImageSeats(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
@@ -692,6 +712,23 @@ func TestTheHolderOfTheTwoImageSeats(t *testing.T) {
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))
}
// `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 ||
@@ -273,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.
@@ -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
@@ -112,6 +115,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"`
+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 (
+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;
}
+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 {
+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);
}
}
+35 -148
View File
@@ -4,8 +4,7 @@
// Emits (novox/hq ADR 0041/0042):
// module.gitea.repo.created — a repository appeared, however it was made (push, web UI, or tool)
// module.gitea.pull.merged — a pull request was merged, however it was merged (web UI, API, or tool)
// module.gitea.pull.updated — an open pull request's head moved, opened or pushed to: the mesh checks it
// before it merges (novox/hq to-be 45 §9)
// module.gitea.pull.updated — an open pull request's head moved, opened or pushed to, said from the forge's event alone
//
// module.gitea.pull.closed — a pull request closed unmerged: the delivery it was is stopped (novox/hq ADR 0239)
//
@@ -16,13 +15,8 @@
// It reads no other module's state: mesh/check, and every act of a delivery part on the forge, arrive as verbs of the seat
// git (seat.ts), asked by the forge bridge (novox/hq design 47 *The seat git*).
//
// This module is the one writer of mesh/merge-gate. It hears no build seat's event: since R4g a check's steps are asks
// on the build seats' streams, whose backlog the delivery view shows (novox/hq ADR 0525 §9; issue 1887).
//
// **A trunk's move puts every open verdict into it out of date** (novox/hq ADR 0323 §4, trunk.ts): each pass reads the
// head of every trunk an open pull request merges into, and when one moved, the merge check statuses of every open pull
// request into it go back to pending with the reason. Nothing is run for it. A verdict that lands judged against a trunk
// commit that is no longer the trunk's head is said out of date in place of its pass or failure.
// No merge check is asked, weighed or written here (design 47 H §764; H-A-28, H-A-100): a merge is one merge call of the
// seat git (mergecall.ts), its members judged by their heads and failed steps alone.
//
// Every pull request the forge holds is announced, whatever its repository: the controller holds the
// module graph and decides what is checked — a repository is never asked to opt in.
@@ -50,18 +44,18 @@ import { FORGE_CONTAINER, seatTools } from "./seat.js";
import { REGISTRATION_CHANGED_EVENT, Registrations } from "./registrations.js";
import { FailedSteps, Heads, readHeads } from "./failedsteps.js";
import { failedStepsTools } from "./tools/failedsteps.js";
import { Calls, callRetentionDays, sayUnsaid } from "./calls.js";
import { Partials } from "./partials.js";
import { callTools } from "./tools/calls.js";
import { seatPublish } from "@novox/mesh-sdk/runtime";
import { seat as GIT, events as GIT_EVENTS, type BranchMovedEvent, type PullClosedEvent, type PullMergedEvent, type PullUpdatedEvent } from "@novox/mesh-delivery-contracts-git";
import { seat as RUNNER, events as RUNNER_EVENTS, type StepEndedEvent } from "@novox/mesh-delivery-contracts-mesh-pipeline-runner";
import { run } from "./delivery.js";
import { GiteaAdmin, GiteaClient, movedSince } from "./client.js";
import { keepMainRules, mainRulesStep } from "./mainrules.js";
import { CHECK_CONTEXT, CHECK_STATUS, REPO_CHECK_CONTEXT, headKey, requiredOf, writesGate, type Announced } from "./pulls.js";
import { actOn, announceNewHeads, startPass } from "./watch.js";
import { GateWriter } from "./gate.js";
import { HOOK_PATH, HOOK_PORT, Pace, claimHead, ensureSystemHook, eventsTool, keptSecret, receiver, type ForgeEvent } from "./webhook.js";
import { keepSiblings, readSiblings, siblingsFile, weighSiblings } from "./siblings.js";
import { actOn } from "./watch.js";
import { HOOK_PATH, HOOK_PORT, Pace, ensureSystemHook, eventsTool, keptSecret, receiver, type ForgeEvent } from "./webhook.js";
import { bindInBackground, bindUntilHeld } from "./bind.js";
import { announcementOf, weighTrunks } from "./trunk.js";
import { announcementOf } from "./updated.js";
import { ReadAll, readAllTools } from "./readall.js";
import { DeliveredWrites, writeTools } from "./writes.js";
import { TOOLS_ACCOUNT, TOOLS_ORG, meshAccounts } from "./tools-account.js";
@@ -107,7 +101,7 @@ async function pollRepos(client: GiteaClient): Promise<void> {
// What has been announced is kept beside the module's state, so a restart does not announce the
// whole history again — and the first tick on a machine with no record announces nothing, because
// everything it sees then predates the watching.
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
import { join } from "node:path";
// What has been announced is no longer kept in a file (novox/hq ADR 0406 §6, §7, issue 976): an announcement carries a
// message id (announce.ts), so the same merge announced by the poll and by the forge's event, or again after a restart,
@@ -179,7 +173,6 @@ async function announceClosed(client: GiteaClient, repo: RepoOf, pull: PullOf):
throw err;
}
console.log(`[gitea] announced ${repo.full_name}#${pull.number} closed unmerged`);
await siblingMoves(client, repo.full_name, pull.number);
return true;
}
@@ -239,8 +232,6 @@ async function announceMerge(client: GiteaClient, repo: RepoOf, pull: PullOf): P
// Said, because a trigger that fires silently is indistinguishable from one that did not
// fire (novox/hq 04-ISSUES/131) — this line is how an operator knows the mesh was told.
console.log(`[gitea] announced merge ${repo.full_name}#${pull.number} (${pull.merge_commit_sha.slice(0, 8)}) into ${pull.base}`);
// Its own merge of the head that was read is no sibling's move; any other is (ADR 0382 §5).
await siblingMoves(client, repo.full_name, pull.number);
} catch (err) {
announced.delete(pull.merge_commit_sha);
throw err;
@@ -248,123 +239,12 @@ async function announceMerge(client: GiteaClient, repo: RepoOf, pull: PullOf): P
return true;
}
// **Every new head of an open pull request is announced** (novox/hq to-be 45 §9): the mesh checks it against every
// machine of its facts before it merges. What this process announced is remembered in memory only (novox/hq ADR 0406
// §6, §7, issue 976): the announcement carries a message id (announce.ts), so the poll's, the forge event's and the
// merge tool's are one to the bus. After a start, the first look announces a head only if the forge shows no merge check
// of it yet — a head with one was announced — and only what moved in the last day, so a forge's whole backlog is not
// checked at once and a restart asks no check again against a trunk that moved.
let heads: Announced = {};
let primedPulls = false;
/** **A head, announced once, whichever path saw it first** (novox/hq issue 729): the poll or the forge's event. */
async function announceHead(client: GiteaClient, repo: RepoOf, pull: OpenOf): Promise<boolean> {
const key = headKey(repo.full_name, pull.number, pull.base);
const sha = String(pull.head_sha ?? "");
const before = heads[key];
// Claimed before the first wait, so the other path finds it taken while this one is still announcing.
if (!claimHead(heads, key, sha)) return false;
try {
// The announcement the merge tool makes too when it asks a check (trunk.ts, novox/hq ADR 0323 §5).
await announce("pull.updated", await announcementOf(client, repo.owner, repo.name, repo.clone_url ?? "", pull));
} catch (err) {
if (before === undefined) delete heads[key];
else heads[key] = before;
throw err;
}
// A sibling's new head puts out of date every verdict that read the sibling at another head (ADR 0382 §5).
await siblingMoves(client, repo.full_name, pull.number);
// Said, so an operator knows the mesh was asked to check it.
console.log(`[gitea] announced ${key} at ${sha.slice(0, 8)} to be checked before it merges`);
// Pending until the verdict comes, so the pull request says a check is running rather than nothing — and
// where it is: in the build queue from now, until a build machine takes it (novox/hq issue 446). Only where the base
// still requires mesh/merge-gate (issue 1301): a main that requires mesh/check is the checker's;
// a rule that cannot be read is said pending, as before.
const rule = pull.base ? await client.appliedProtection(repo.owner, repo.name, String(pull.base)).catch(() => undefined) : undefined;
if (writesGate(requiredOf(rule))) await gates.pending(repo.owner, repo.name, sha);
return true;
/** **A pull request's new head, said as pull.updated from the forge's event alone** (design 47 H §764; H-A-100): no
* poll, no pending status and no sibling's weighing. */
async function announceUpdated(client: GiteaClient, repo: RepoOf, pull: PullOf): Promise<void> {
await announce("pull.updated", await announcementOf(client, repo.owner, repo.name, repo.clone_url ?? "", pull));
console.log(`[gitea] said ${repo.full_name}#${pull.number} at ${String(pull.head_sha ?? "").slice(0, 8)} updated`);
}
type OpenOf = Awaited<ReturnType<GiteaClient["listOpenPullsSince"]>>[number];
/** Whether the forge shows a merge check of the head, in any state: only an announced head has one. */
async function alreadyChecked(client: GiteaClient, repo: RepoOf, pull: OpenOf): Promise<boolean> {
try {
const checks = await client.headChecks(repo.owner, repo.name, String(pull.head_sha));
return CHECK_CONTEXT in checks || REPO_CHECK_CONTEXT in checks || CHECK_STATUS in checks;
} catch {
return false; // the forge cannot say: announced, and the bus's message id collapses it if it was
}
}
let lastPullLook = "";
/** The pass over every open pull request: run at the start and when the receiver listens, never on a timer (issue 1422). */
async function passPulls(client: GiteaClient): Promise<void> {
const began = new Date().toISOString();
const dayAgo = new Date(Date.now() - 24 * 3600_000).toISOString();
for (const repo of await client.listAllRepos()) {
// Every open pull request, paged (novox/hq issue 579).
const open = await client.listOpenPullsSince(repo.owner, repo.name, "");
await announceNewHeads(repo.full_name, open, heads, primedPulls, dayAgo, {
alreadyChecked: (pull) => alreadyChecked(client, repo, pull),
announceHead: (pull) => announceHead(client, repo, pull),
missed: (what) => pace.miss(what),
});
if (await trunksMoved(client, repo.owner, repo.name)) changedTrunks = true;
}
if (changedTrunks) keepTrunks();
changedTrunks = false;
primedPulls = true;
lastPullLook = began;
}
// **The trunks' heads, as this module last read them** (novox/hq ADR 0323 §4), by `owner/repo:branch`: kept beside the
// other records, so a move made while this module was away is weighed on its first pass back. With no record — the
// first pass after this rolls out — a trunk's head is taken as it is and nothing is put out of date: the verdicts
// then standing are weighed on the trunk's next move, and the merge tool compares commits whatever this holds.
const trunksRecord = process.env.MESH_GITEA_STATE_DIR ? join(process.env.MESH_GITEA_STATE_DIR, "trunks-seen.json") : null;
let trunks: Record<string, string> = {};
let changedTrunks = false;
if (trunksRecord && existsSync(trunksRecord)) {
try {
trunks = (JSON.parse(readFileSync(trunksRecord, "utf8")) as { trunks: Record<string, string> }).trunks ?? {};
} catch {
// An unreadable record is no record: the next pass takes each trunk's head as it is.
}
}
function keepTrunks(): void {
if (!trunksRecord) return;
mkdirSync(join(trunksRecord, ".."), { recursive: true });
const tmp = trunksRecord + ".tmp";
writeFileSync(tmp, JSON.stringify({ trunks }));
renameSync(tmp, trunksRecord);
}
/** Whether a trunk of one repository moved, weighed with this module's forge and its one writer (trunk.ts). */
function trunksMoved(client: GiteaClient, owner: string, name: string): Promise<boolean> {
return weighTrunks(client, gates, trunks, owner, name, () => siblingMoves(client, `${owner}/${name}`));
}
// **The siblings each open pull request's latest verdict names** (novox/hq ADR 0382 §5, siblings.ts), by member, kept beside
// the other records. A sibling's new head, close unmerged, merge, or a move of its base puts the merge check of every
// member whose verdict names it back to pending, with the reason; nothing is run for it.
const siblingsRecord = siblingsFile(process.env.MESH_GITEA_STATE_DIR);
const siblingNamed = readSiblings(siblingsRecord);
/** A sibling moved, weighed (ADR 0382 §5): never fatal to what heard it. */
async function siblingMoves(client: GiteaClient, repository: string, number?: number): Promise<void> {
try {
if (await weighSiblings(client, gates, siblingNamed, repository, number)) keepSiblings(siblingsRecord, siblingNamed);
} catch (err) {
console.error(`[gitea] whether a sibling of ${repository}${number ? "#" + number : ""} moved could not be weighed — ${err instanceof Error ? err.message : err}`);
}
}
// **This module is the one writer of a head's mesh/merge-gate** (novox/hq issue 446): the announcement's pending words,
// where the check is when a build machine takes it, and the verdict — each head's writes in one chain, the verdict last
// (gate.ts). A second writer elsewhere raced the verdict and could leave a pass reading pending.
const gates = new GateWriter({
setCommitStatus: (owner, repo, sha, status) => (gitea as GiteaClient).setCommitStatus(owner, repo, sha, status),
headChecks: (owner, repo, sha) => (gitea as GiteaClient).headChecks(owner, repo, sha),
});
/** How fast the polls look: 30 s until the forge's events are heard, five minutes while they are; and what
* gitea_events says of them (webhook.ts). */
@@ -400,27 +280,34 @@ const registrations = new Registrations((verb, input) => broker().request(verb,
// The failed steps the runner's step-ended said, and the heads that keep them (failedsteps.ts; design 47 §39, §475, §487, §135).
const heldHeads = new Heads();
let reloadHeads: () => Promise<void> = async () => {};
const failedSteps = new FailedSteps(state<unknown>("failed-steps"), (line) => console.log(`[gitea] ${line}`), (commit) => heldHeads.has(commit));
// The merge calls, each written before its first merge (calls.ts; design 47 H §766).
const calls = new Calls(state<unknown>("calls"), () => callRetentionDays(), (line) => console.log(`[gitea] ${line}`));
// At the start, every call whose merge-called is not said says it for what landed (§766).
const partials = new Partials(state<unknown>("findings"), calls, (line) => console.log(`[gitea] ${line}`));
void sayUnsaid(calls, seatPublish, (line) => console.log(`[gitea] ${line}`)).catch((err) =>
console.error(`[gitea] the merge calls not said could not be said at the start — ${err instanceof Error ? err.message : err}`));
const failedSteps = new FailedSteps(state<unknown>("failed-steps"), (line) => console.log(`[gitea] ${line}`), (commit) => heldHeads.has(commit),
undefined, state<unknown>("findings"));
// The `seen` keys past their 30 days are deleted at the start, as on each step-ended (design 47 §581).
void failedSteps.expireSeen().catch((err) => console.log(`[gitea] the seen keys past 30 days could not be deleted at the start: ${err instanceof Error ? err.message : String(err)}`));
// gitea_events is served whether or not the forge is watched: it says so (novox/hq issue 729). The seat git's verbs are
// served here, beside the one writer of a head's statuses: the seat's status takes its turn on the head's chain, after the
// announcement's pending and a trunk's move, so a recheck's pending never lands over a later verdict (issue 456).
// served here.
registerModuleTools("gitea", () => [eventsTool(pace), ...readAllTools(readAll), ...writeTools(writes), ...statusTools("gitea", "gitea_first_views", "gitea_first_view_again", followers, firstViews,
async (act) => { await broker().request("seat:mesh-hand-acts.hand-act", act); }),
...(gitea ? seatTools(gitea, { run, container: FORGE_CONTAINER, statuses: gates, registered: () => registrations.written, judge: (head) => failedSteps.judge(head) }) : []),
...(gitea ? seatTools(gitea, { run, container: FORGE_CONTAINER, registered: () => registrations.written, judge: (head) => failedSteps.judge(head),
watched: () => registrations.watched, calls, say: seatPublish, partials }) : []),
...callTools(calls, partials, seatPublish, async (act) => { await broker().request("seat:mesh-hand-acts.hand-act", act); }),
...failedStepsTools(failedSteps, async (act) => { await broker().request("seat:mesh-hand-acts.hand-act", act); })]);
/** What the forge's event asks of the announcer at once (issue 729, 1422): see watch.ts. */
const actOnEvent = (client: GiteaClient, event: ForgeEvent): Promise<void> => actOn<RepoOf, PullOf>(event, {
getRepo: (o, r) => client.getRepo(o, r),
getPull: (o, r, n) => client.getPullRequest(o, r, n) as Promise<PullOf & { state?: string; merged?: boolean }>,
announceHead: (repo, pull) => announceHead(client, repo, pull as OpenOf),
announceUpdated: (repo, pull) => announceUpdated(client, repo, pull),
announceMerge: (repo, pull) => announceMerge(client, repo, pull),
announceClosed: (repo, pull) => announceClosed(client, repo, pull),
siblingMoves: (full, n) => siblingMoves(client, full, n),
});
/**
@@ -566,7 +453,9 @@ if (gitea) {
const read = await readHeads(forge, registrations.watched, (line) => console.log(`[gitea] ${line}`));
await failedSteps.lost(heldHeads.replace(read.names, read.branches, read.pulls));
};
void bindUntilHeld(`${RUNNER}.${RUNNER_EVENTS.stepEnded}`, () => on<StepEndedEvent>(`${RUNNER}.${RUNNER_EVENTS.stepEnded}`, (event) => failedSteps.stepEnded(event.body)));
// The runner's step-ended is said on step-ended.<module>.<branch>.<commit> (the seat's definition).
const stepEnded = `${RUNNER}.${RUNNER_EVENTS.stepEnded}.*.*.*`;
void bindUntilHeld(stepEnded, () => on<StepEndedEvent>(stepEnded, (event) => failedSteps.stepEnded(event.body)));
// A branch's head is read from the forge, never taken from the event (the seat's definition of branch-moved).
void bindUntilHeld(`${GIT}.${GIT_EVENTS.branchMoved}`, () => on<BranchMovedEvent>(`${GIT}.${GIT_EVENTS.branchMoved}`, async (event) => {
const { repository, branch } = event.body;
@@ -580,9 +469,8 @@ if (gitea) {
}
void registrations.start().then(() => reloadHeads()).catch(say);
}
// Main takes no push and only the tools' account merges, in every repository, kept and not only when a token is
// minted: at the start and every ten minutes after, so a repository made later gets it too (issue 948, ADR 0398 §2).
// Only while the setting keep-main-rules is true (mainrules.ts); false, the default, leaves every repository's rule as set.
// Main's rule is put right only when the tools' account's token is minted, and only while the setting keep-main-rules is
// true (mainrules.ts); no timer keeps it (design 47 H §764, H-A-100).
// The package seats' write token (packages-account.ts): minted at the start; after that renewed only when the Go
// bundle that writes with it says the forge refused it (the finding PACKAGES_TOKEN_REFUSED), never on a timer.
try {
@@ -595,14 +483,13 @@ if (gitea) {
} catch (err) {
console.error(`[gitea] the package seats cannot write — ${err instanceof Error ? err.message : err}`);
}
tick(mainRulesStep(keepMainRules(), () => GiteaAdmin.fromEnv().ensureMainMerges("novox"), (line) => console.log(line)), 600_000);
tick(() => pollRepos(client), 60_000);
// **No timer asks the forge for pull requests or merges** (issue 1422): the forge's events announce them. One pass over
// every repository runs at the start and again once the receiver listens, so what happened while the module was away or
// not yet listening is announced; passes run one at a time, a failed one is asked again a minute later.
let passes: Promise<void> = Promise.resolve();
const pass = (): Promise<void> => (passes = passes.catch(() => {}).then(() =>
startPass(async () => { await pollMerged(client); await passPulls(client); }, { retryMs: 60_000 })));
pollMerged(client).catch((err) => console.error(`[gitea] the pass over every repository's merges failed — ${err instanceof Error ? err.message : err}`))));
void pass();
let catchUpAsked = false;
catchUp = () => {
+18 -3
View File
@@ -213,7 +213,9 @@ func (h *Holder) answer(transfer string, r parts.Received) Answer {
return Answer{Transfer: transfer, Lacks: r.Lacks, Ended: r.Ended}
}
// Publish is `publish` on seat for the proved caller: a package is one file, its digest the file's sha256.
// Publish is `publish` on seat for the proved caller: a package is one file, its digest the file's sha256. With its one
// part the file travels (design 51 *Publishing*); with none (the builder's publish again, design 47 G A-73, A-417) the
// version is said published when the forge holds it under the digest, and refused as not stored otherwise.
func (h *Holder) Publish(seat, caller string, p Publish) (Answer, error) {
if err := checkPublish(seat, p); err != nil {
return Answer{}, err
@@ -225,12 +227,25 @@ func (h *Holder) Publish(seat, caller string, p Publish) (Answer, error) {
} else if ok {
if d != p.Digest {
reason := fmt.Sprintf("%s@%s is published with %s, not %s", p.Name, p.Version, d, p.Digest)
if len(p.Parts) == 0 {
// The builder's publish again names nothing the forge holds under that digest: refused as not stored (A-490,
// A-490a), the words its republish recognises.
reason = "not stored: " + reason
return Answer{Transfer: p.Transfer, Ended: true}, errors.Join(errors.New("publish: "+reason), h.refused(Transfer{Shape: Opening{Publish: p, Seat: seat}}, reason))
}
// A one-part publish of a taken version is refused with an event only, as the registry would (the builder's "version taken").
return Answer{Transfer: p.Transfer, Ended: true}, h.refused(Transfer{Shape: Opening{Publish: p, Seat: seat}}, reason)
}
o := outcomeOf(p, "")
o.Reference = Reference(p.Name, p.Version)
return Answer{Transfer: p.Transfer, Ended: true}, h.Say(seat, EventPublished, o)
}
// A publish with a version, a digest and no parts (design 47 G A-73, A-417): what the forge holds under the version has
// been said published above; nothing else travels, so the publish is refused as not stored, naming the digest.
if len(p.Parts) == 0 {
reason := fmt.Sprintf("not stored: the forge holds no %s of %s, so version %s names nothing", p.Digest, p.Name, p.Version)
return Answer{Transfer: p.Transfer, Ended: true}, errors.Join(errors.New("publish: "+reason), h.refused(Transfer{Shape: Opening{Publish: p, Seat: seat}}, reason))
}
// The transfer's name is the caller's own (the seat's contract): none would open the seat's one nameless transfer,
// which key() still makes a valid id.
if strings.TrimSpace(p.Transfer) == "" {
@@ -377,8 +392,8 @@ func checkPublish(seat string, p Publish) error {
return fmt.Errorf("publish: %s holds packages, not a %s", seat, p.Kind)
case !strings.HasPrefix(p.Digest, "sha256:"):
return fmt.Errorf("publish: digest %q is no sha256 digest", p.Digest)
case len(p.Parts) != 1 || p.Parts[0].Digest != p.Digest:
return errors.New("publish: a package is one file, its one part the package's digest")
case len(p.Parts) > 1 || (len(p.Parts) == 1 && p.Parts[0].Digest != p.Digest):
return errors.New("publish: a package is one file, its one part the package's digest, or no part at all")
}
return nil
}
@@ -3,6 +3,7 @@ package packageseats
import (
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"strings"
"testing"
@@ -10,6 +11,7 @@ import (
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/parts"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/publishconformance"
)
type memObjects map[string][]byte
@@ -50,10 +52,21 @@ func (b builder) Recorded(_, _, _ string) (bool, string, error) { return b.ok, "
// forge is the forge's package registry: seat -> name@version -> file.
type forge struct {
files map[string]map[string][]byte
digests map[string]string // seat+name@version -> a digest held with no bytes kept
removed []string
}
func (f *forge) holdDigest(seat, name, version, d string) {
if f.digests == nil {
f.digests = map[string]string{}
}
f.digests[seat+" "+name+"@"+version] = d
}
func (f *forge) Held(seat, name, version string) (string, bool, error) {
if d, ok := f.digests[seat+" "+name+"@"+version]; ok {
return d, true, nil
}
b, ok := f.files[seat][name+"@"+version]
if !ok {
return "", false, nil
@@ -150,6 +163,85 @@ func TestTheForgeHoldsBothPackageSeats(t *testing.T) {
}
}
})
// Design 47 G A-490, A-490a: the publish contract's no-parts form, as every publish holder is held to it, per seat.
for _, seat := range []string{GoSeat, NpmSeat} {
t.Run("the publish conformance cases on "+seat, func(t *testing.T) {
publishconformance.Run(t, func(t *testing.T) publishconformance.Bed {
b := newBed(true)
return publishconformance.Bed{
Hold: func(d string) {
b.forge.holdDigest(seat, publishconformance.Name, publishconformance.Version, d)
},
Publish: func(name, version, digest string) publishconformance.Outcome {
a, err := b.h.Publish(seat, goBuild, Publish{Transfer: "t", Name: name, Version: version, Kind: KindPackage, Digest: digest})
o := publishconformance.Outcome{Ended: a.Ended, Lacks: len(a.Lacks), Err: err}
if len(b.said) > 0 {
o.Event, o.Reason = b.said[len(b.said)-1].event, b.said[len(b.said)-1].o.Reason
}
return o
}}
})
})
}
// Design 47 G A-490j: the one-part publish a build module makes while it builds, as every publish holder is held to it, per
// seat, checked through the real Reserved against the builder's answer.
for _, seat := range []string{GoSeat, NpmSeat} {
t.Run("the publish while the build runs on "+seat, func(t *testing.T) {
publishconformance.RunReserved(t, func(t *testing.T) publishconformance.ReservedBed {
b := newBed(true)
whole := []byte("a package built now")
answer := ""
b.h.Builder = Reserved{Ask: func(string, any) (json.RawMessage, error) {
if answer == "" {
return nil, errors.New("no reserved version of mesh-sdk")
}
return json.RawMessage(answer), nil
}}
return publishconformance.ReservedBed{
Reserve: func(r publishconformance.Reservation) {
d := map[publishconformance.Reservation]string{publishconformance.NoDigestYet: "", publishconformance.SameDigest: digest(whole),
publishconformance.OtherDigest: digest([]byte("another"))}[r]
answer = `{"module":"mesh-sdk","version":"0.1.19","artifacts":[{"artifact":"mesh-sdk:` + seat + `","digest":"` + d + `"}]}`
},
Hold: func() { b.forge.holdDigest(seat, "mesh-sdk", "0.1.19", digest([]byte("first"))) },
PublishWhole: func() publishconformance.Outcome {
a, err := b.h.Publish(seat, goBuild, pub("mesh-sdk", "0.1.19", whole))
if err == nil && !a.Ended {
_, err = b.h.PublishPart(seat, goBuild, "t-mesh-sdk", digest(whole), 0, true, whole)
}
o := publishconformance.Outcome{Err: err}
if len(b.said) > 0 {
o.Event, o.Reason = b.said[len(b.said)-1].event, b.said[len(b.said)-1].o.Reason
}
return o
}}
})
})
}
// Design 47 G A-73, A-417: the builder's publish again names the version and the digest and no parts.
t.Run("a publish with a digest and no parts is published when held, refused as not stored when not", func(t *testing.T) {
for _, seat := range []string{NpmSeat, GoSeat} {
b := newBed(true)
none := pub("mesh-sdk", "0.1.0", file)
none.Parts = nil
a, err := b.h.Publish(seat, goBuild, none)
if err == nil || !strings.Contains(err.Error(), "not stored") || !strings.Contains(err.Error(), digest(file)) || !a.Ended {
t.Fatalf("%s: a publish of a digest the forge lacks answered %+v, %v; want refused as not stored, naming the digest", seat, a, err)
}
if len(b.said) != 1 || b.said[0].event != EventRefused || !strings.Contains(b.said[0].o.Reason, digest(file)) || !b.findings["publish-refused mesh-sdk@0.1.0"] {
t.Errorf("%s: said %+v, findings %v; want refused with the digest and the finding raised", seat, b.said, b.findings)
}
b = newBed(true)
if _, ok := b.forge.files[seat]; !ok {
b.forge.files[seat] = map[string][]byte{}
}
b.forge.files[seat]["mesh-sdk@0.1.0"] = file
a, err = b.h.Publish(seat, goBuild, none)
if err != nil || !a.Ended || len(a.Lacks) != 0 || len(b.said) != 1 || b.said[0].event != EventPublished || b.said[0].o.Reference != "mesh-sdk@0.1.0" {
t.Errorf("%s: a held digest answered %+v, %v, said %+v; want published", seat, a, err, b.said)
}
}
})
// Tools review F4 and running review F2's kind: a seat's incoming is read per seat with the cap its binding
// carries; an open transfer is armed with its idle key, re-armed for the rest when it took a chunk since, and
// dropped with its chunks when it had none for 24 hours; a cap from the binding refuses a transfer past it.
@@ -9,7 +9,7 @@ import (
// 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 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).
@@ -34,7 +34,10 @@ func (r Reserved) Recorded(name, version, digest string) (bool, string, error) {
return false, fmt.Sprintf("%s reserved %s for %s, not %s", a.Module, a.Version, name, version), nil
}
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 (design 47 G §369, A-415, A-490j). Its record then meets what
// the holder holds: the published kept on the reservation marks the artifact, and a digest that differs fails the build.
if art.Digest == digest || art.Digest == "" {
return true, "", nil
}
}
@@ -19,6 +19,7 @@ func reservedChecksAPublishAgainstTheReservation(t *testing.T) {
}{
{name: "the reserved version and digest", answer: `{"module":"mesh-sdk","version":"0.1.19","artifacts":[{"artifact":"mesh-sdk:ts","digest":"sha256:aa"}]}`, ok: true},
{name: "another artifact of it carries the digest", answer: `{"module":"mesh-sdk","version":"0.1.19","artifacts":[{"artifact":"mesh-sdk:go"},{"artifact":"mesh-sdk:ts","digest":"sha256:aa"}]}`, ok: true},
{name: "the artifact is not built yet", answer: `{"module":"mesh-sdk","version":"0.1.19","artifacts":[{"artifact":"mesh-sdk:ts"}]}`, ok: true},
{name: "another digest", answer: `{"module":"mesh-sdk","version":"0.1.19","artifacts":[{"artifact":"mesh-sdk:ts","digest":"sha256:bb"}]}`, why: "another digest than sha256:aa"},
{name: "another version reserved", answer: `{"module":"mesh-sdk","version":"0.1.20","artifacts":[]}`, why: "reserved 0.1.20 for @novox/mesh-sdk, not 0.1.19"},
{name: "the builder refused the name", err: errors.New("no entry carries @novox/mesh-sdk"), why: "no entry carries @novox/mesh-sdk"},
+3
View File
@@ -0,0 +1,3 @@
// Package seatgit holds the whole test of the seat git as the forge module serves it (novox/hq design 47 H §774, H-A-87):
// the module's TypeScript bundle run against a bus of the test alone and a fixture forge. It has no code of its own.
package seatgit
@@ -0,0 +1,483 @@
//go:build integration
package seatgit
// The seat git whole, as the forge module serves it (novox/hq design 47 H §734 to §736, §766, §767, §774; acceptance tests
// 111, 114 and 115; H-A-61, H-A-87): the module's TypeScript bundle, built here and played over its real stdin and stdout
// as the node's tool runner plays it, its states key-value buckets of a nats-server of this test alone, its seat events
// published on that bus and read back from its stream, and the forge an httptest server.
//
// - At its start a call kept unsaid, stopped after the second of three merges, says one merge-called naming the two
// that landed, and is kept said (§766, test 111's stop case).
// - A runner's step-ended of a failed required step at a pull request's head and fingerprint is kept, and a merge call
// naming that head merges nothing and names the step (§735, test 114).
// - A call naming two pull requests in two repositories merges both, in order, and says one merge-called (§734, §736).
// - A forge that refuses the second merge gives one merge-called with the first member and `refused`, and merge-partial
// raised; a later call landing the refused member clears it (§767, test 115).
import (
"bufio"
"context"
"encoding/json"
"errors"
"fmt"
"io"
"net/http"
"net/http/httptest"
"os"
"os/exec"
"path/filepath"
"regexp"
"strings"
"sync"
"testing"
"time"
"git.novox.be/novox/mesh-sdk/go/testbus"
"github.com/nats-io/nats.go"
"github.com/nats-io/nats.go/jetstream"
)
const within = 30 * time.Second
// pull is one pull request of the fixture forge.
type pull struct {
repo, base, head string
number int
merged, refuse bool
merge string
}
// forge is the fixture forge: the pull requests by `<owner>/<name>#<number>` and every merge asked.
type forge struct {
mu sync.Mutex
pulls map[string]*pull
merges []string
paths []string
}
func (f *forge) serve(w http.ResponseWriter, r *http.Request) {
f.mu.Lock()
defer f.mu.Unlock()
f.paths = append(f.paths, r.Method+" "+r.URL.Path)
m := regexp.MustCompile(`^/api/v1/repos/([^/]+/[^/]+)/pulls/(\d+)(/merge)?$`).FindStringSubmatch(r.URL.Path)
if m != nil {
p := f.pulls[m[1]+"#"+m[2]]
if p == nil {
http.Error(w, `{"message":"not found"}`, http.StatusNotFound)
return
}
if m[3] != "" && r.Method == http.MethodPost {
f.merges = append(f.merges, m[1]+"#"+m[2])
if p.refuse {
http.Error(w, `{"message":"merge conflict"}`, http.StatusConflict)
return
}
p.merged, p.merge = true, strings.Repeat(fmt.Sprint(p.number%10), 40)
return
}
body := map[string]any{"number": p.number, "title": "t", "state": "open", "merged": p.merged,
"base": map[string]any{"ref": p.base}, "head": map[string]any{"ref": "feat", "sha": p.head}}
if p.merged {
body["state"], body["merge_commit_sha"] = "closed", p.merge
}
_ = json.NewEncoder(w).Encode(body)
return
}
if c := regexp.MustCompile(`^/api/v1/repos/[^/]+/[^/]+/git/commits/([0-9a-f]+)$`).FindStringSubmatch(r.URL.Path); c != nil {
_ = json.NewEncoder(w).Encode(map[string]any{"sha": c[1], "parents": []any{map[string]any{"sha": c[1]}}})
return
}
http.Error(w, `{"message":"the fixture forge serves no `+r.URL.Path+`"}`, http.StatusNotFound)
}
func (f *forge) merged() []string {
f.mu.Lock()
defer f.mu.Unlock()
return append([]string(nil), f.merges...)
}
func (f *forge) asked(prefix string) bool {
f.mu.Lock()
defer f.mu.Unlock()
for _, p := range f.paths {
if strings.HasPrefix(p, prefix) {
return true
}
}
return false
}
// runtime is the half of the conversation the tool runner plays for the bundle.
type runtime struct {
t *testing.T
in io.WriteCloser
js jetstream.JetStream
kvs map[string]jetstream.KeyValue
mu sync.Mutex
next int
wait map[string]chan json.RawMessage
// regs are what the seat mesh-catalog's registrations answers; subs the patterns the bundle subscribed.
regs []map[string]any
subs []string
}
func (r *runtime) subscribed(pattern string) bool {
r.mu.Lock()
defer r.mu.Unlock()
for _, s := range r.subs {
if s == pattern {
return true
}
}
return false
}
func (r *runtime) say(m map[string]any) {
m["jsonrpc"] = "2.0"
raw, _ := json.Marshal(m)
r.mu.Lock()
defer r.mu.Unlock()
_, _ = r.in.Write(append(raw, '\n'))
}
func (r *runtime) read(out io.Reader) {
sc := bufio.NewScanner(out)
sc.Buffer(make([]byte, 1<<20), 1<<24)
for sc.Scan() {
var m struct {
ID json.RawMessage `json:"id"`
Method string `json:"method"`
Params json.RawMessage `json:"params"`
Result json.RawMessage `json:"result"`
}
if json.Unmarshal(sc.Bytes(), &m) != nil {
continue
}
if m.Method == "" {
var id string
_ = json.Unmarshal(m.ID, &id)
r.mu.Lock()
ch := r.wait[id]
delete(r.wait, id)
r.mu.Unlock()
if ch != nil {
ch <- m.Result
}
continue
}
go r.answer(m.ID, m.Method, m.Params)
}
}
// answer is the tool runner's answer to one method the bundle asks.
func (r *runtime) answer(id json.RawMessage, method string, params json.RawMessage) {
var p struct {
State string `json:"state"`
Key string `json:"key"`
Value json.RawMessage `json:"value"`
Subject string `json:"subject"`
Pattern string `json:"pattern"`
Body json.RawMessage `json:"body"`
ID string `json:"id"`
}
_ = json.Unmarshal(params, &p)
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
result, err := func() (any, error) {
kv := r.kvs[p.State]
switch method {
case "mesh/subscribe":
r.mu.Lock()
r.subs = append(r.subs, p.Pattern)
r.mu.Unlock()
return map[string]any{}, nil
case "mesh/publish", "mesh/state.watch", "mesh/seat.record":
return map[string]any{}, nil
case "mesh/capabilities":
return map[string]any{"words": []string{}}, nil
case "mesh/seat.publish":
// The seat's event, published on the bus under its id, as the runtime does.
_, err := r.js.Publish(ctx, p.Subject, p.Body, jetstream.WithMsgID(p.ID))
return map[string]any{}, err
case "mesh/ask":
var a struct {
Key string `json:"key"`
}
_ = json.Unmarshal(params, &a)
switch a.Key {
case "seat:mesh-catalog.registrations":
return map[string]any{"registrations": r.regs}, nil
case "seat:mesh-hand-acts.hand-act":
return map[string]any{}, nil
}
return nil, fmt.Errorf("the runtime answers no ask %s in this test", a.Key)
case "mesh/state.get":
if kv == nil {
return nil, fmt.Errorf("the state %q is not declared", p.State)
}
e, err := kv.Get(ctx, p.Key)
if errors.Is(err, jetstream.ErrKeyNotFound) {
return nil, nil
}
if err != nil {
return nil, err
}
return map[string]any{"key": p.Key, "value": json.RawMessage(e.Value()), "revision": e.Revision()}, nil
case "mesh/state.put":
if kv == nil {
return nil, fmt.Errorf("the state %q is not declared", p.State)
}
rev, err := kv.Put(ctx, p.Key, p.Value)
return map[string]any{"revision": rev}, err
case "mesh/state.delete":
if kv == nil {
return nil, fmt.Errorf("the state %q is not declared", p.State)
}
return map[string]any{}, kv.Delete(ctx, p.Key)
case "mesh/state.keys":
if kv == nil {
return nil, fmt.Errorf("the state %q is not declared", p.State)
}
keys, err := kv.Keys(ctx)
if errors.Is(err, jetstream.ErrNoKeysFound) {
return []string{}, nil
}
return keys, err
case "mesh/state.info":
return map[string]any{"bytes": 0, "keys": 0, "max_bytes": 0}, nil
}
return nil, fmt.Errorf("the runtime offers no %s to this bundle", method)
}()
if id == nil {
return
}
if err != nil {
r.say(map[string]any{"id": id, "error": map[string]any{"code": -32000, "message": err.Error()}})
return
}
r.say(map[string]any{"id": id, "result": result})
}
// ask sends the bundle one request and answers its result.
func (r *runtime) ask(method string, params map[string]any) json.RawMessage {
r.t.Helper()
r.mu.Lock()
r.next++
id := fmt.Sprintf("rt-%d", r.next)
ch := make(chan json.RawMessage, 1)
r.wait[id] = ch
r.mu.Unlock()
r.say(map[string]any{"id": id, "method": method, "params": params})
select {
case raw := <-ch:
return raw
case <-time.After(within):
r.t.Fatalf("%s was not answered in %s", method, within)
}
return nil
}
// mergePull calls the seat's verb as a proved caller and answers its result.
func (r *runtime) mergePull(pulls ...map[string]any) map[string]any {
r.t.Helper()
raw := r.ask("tools/call", map[string]any{"name": "git.merge-pull", "_meta": map[string]any{"mesh/caller": "shanks.claude-code"},
"arguments": map[string]any{"by": "lead@shanks", "pulls": pulls}})
var res struct {
Content []struct {
Text string `json:"text"`
} `json:"content"`
}
var out map[string]any
if json.Unmarshal(raw, &res) != nil || len(res.Content) == 0 || json.Unmarshal([]byte(res.Content[0].Text), &out) != nil {
r.t.Fatalf("merge-pull answered %s", raw)
}
return out
}
func until(t *testing.T, what string, ok func() bool) {
t.Helper()
deadline := time.Now().Add(within)
for !ok() {
if time.Now().After(deadline) {
t.Fatalf("within %s: %s did not happen", within, what)
}
select {
case <-time.After(20 * time.Millisecond):
}
}
}
// said is every merge-called on the bus so far, by call.
func said(t *testing.T, js jetstream.JetStream) map[string]map[string]any {
t.Helper()
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
out := map[string]map[string]any{}
s, err := js.Stream(ctx, "SEAT_git_merge-called")
if err != nil {
t.Fatal(err)
}
info, err := s.Info(ctx)
if err != nil {
t.Fatal(err)
}
for seq := info.State.FirstSeq; seq <= info.State.LastSeq && info.State.Msgs > 0; seq++ {
m, err := s.GetMsg(ctx, seq)
if err != nil {
continue
}
var body map[string]any
_ = json.Unmarshal(m.Data, &body)
out[strings.TrimPrefix(m.Subject, "mesh.seat.git.event.merge-called.")] = body
}
return out
}
func numbers(v any) []float64 {
var out []float64
list, _ := v.([]any)
for _, m := range list {
n, _ := m.(map[string]any)["number"].(float64)
out = append(out, n)
}
return out
}
func TestTheSeatGitWholeOverARealBus(t *testing.T) {
dir, err := filepath.Abs(filepath.Join("..", ".."))
if err != nil {
t.Fatal(err)
}
if _, err := os.Stat(filepath.Join(dir, "node_modules", "@novox", "mesh-sdk")); err != nil {
t.Fatalf("the forge module's packages are not installed in %s (npm install first): %v", dir, err)
}
build := exec.Command("npm", "run", "build")
build.Dir = dir
if out, err := build.CombinedOutput(); err != nil {
t.Fatalf("the bundle does not build: %v\n%s", err, out)
}
nc, err := nats.Connect(testbus.URL(t))
if err != nil {
t.Fatal(err)
}
t.Cleanup(nc.Close)
js, _ := jetstream.New(nc)
ctx := context.Background()
// The seat's stream merge-called is kept on (the definition's keep); the template states as buckets.
if _, err := js.CreateStream(ctx, jetstream.StreamConfig{Name: "SEAT_git_merge-called", Subjects: []string{"mesh.seat.git.event.merge-called.*"}}); err != nil {
t.Fatal(err)
}
kvs := map[string]jetstream.KeyValue{}
for _, name := range []string{"bound", "announced", "findings", "first-views", "transfers", "idle", "failed-steps", "calls"} {
kv, err := js.CreateKeyValue(ctx, jetstream.KeyValueConfig{Bucket: "gitea_" + name})
if err != nil {
t.Fatal(err)
}
kvs[name] = kv
}
A, B, X := strings.Repeat("a", 40), strings.Repeat("b", 40), strings.Repeat("e", 40)
// A call stopped after the second of three merges, kept and not said (§766).
stopped, _ := json.Marshal(map[string]any{"by": "lead@shanks", "account": "shanks.claude-code", "at": "2026-11-20T03:00:00Z", "said": false,
"members": []any{
map[string]any{"repository": "novox/app", "number": 1, "branch": "main", "head": A, "state": "merged", "commit": strings.Repeat("1", 40)},
map[string]any{"repository": "novox/app", "number": 2, "branch": "main", "head": A, "state": "merged", "commit": strings.Repeat("2", 40)},
map[string]any{"repository": "novox/app", "number": 3, "branch": "main", "head": A, "state": "judged"}}})
if _, err := kvs["calls"].Put(ctx, "call.00000000000000cc", stopped); err != nil {
t.Fatal(err)
}
f := &forge{pulls: map[string]*pull{
"novox/app#5": {repo: "novox/app", base: "main", head: A, number: 5},
"novox/app#6": {repo: "novox/app", base: "main", head: X, number: 6},
"novox/app#7": {repo: "novox/app", base: "main", head: A, number: 7},
"novox/lib#9": {repo: "novox/lib", base: "main", head: B, number: 9, refuse: true},
"novox/lib#10": {repo: "novox/lib", base: "main", head: B, number: 10},
}}
srv := httptest.NewServer(http.HandlerFunc(f.serve))
t.Cleanup(srv.Close)
state := t.TempDir()
launch := `const sdk = await import("@novox/mesh-sdk/stdio"); await import("./dist/index.js"); await import("./dist/tools/index.js"); await sdk.serveRegisteredOverStdio("gitea");`
cmd := exec.Command("node", "--input-type=module", "-e", launch)
cmd.Dir = dir
cmd.Env = append(os.Environ(), "MESH_SERVED_MODULE=gitea", "MESH_MODULE=gitea", "MESH_NODE=test", "MESH_GITEA_URL="+srv.URL,
"GITEA_TOKEN=t", "MESH_GITEA_STATE_DIR="+state, "MESH_GITEA_HOOK_PORT=0", "MESH_GITEA_CONFIG_FILE="+filepath.Join(state, "config.json"))
in, _ := cmd.StdinPipe()
out, _ := cmd.StdoutPipe()
cmd.Stderr = testLog{t}
if err := cmd.Start(); err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = in.Close(); _ = cmd.Process.Kill(); _ = cmd.Wait() })
rt := &runtime{t: t, in: in, js: js, kvs: kvs, wait: map[string]chan json.RawMessage{}, regs: []map[string]any{
{"module": "app", "origin": "novox/app", "branches": []string{"main"}},
{"module": "lib", "origin": "novox/lib", "branches": []string{"main"}}}}
go rt.read(out)
// At the start the stopped call says one merge-called naming the two that landed (§766).
until(t, "the stopped call's merge-called at the start", func() bool { return said(t, js)["00000000000000cc"] != nil })
if got := numbers(said(t, js)["00000000000000cc"]["members"]); fmt.Sprint(got) != "[1 2]" {
t.Fatalf("the stopped call names %v, not the two that landed", got)
}
until(t, "the stopped call kept said", func() bool {
e, err := kvs["calls"].Get(ctx, "call.00000000000000cc")
return err == nil && strings.Contains(string(e.Value()), `"said":true`)
})
// The registrations are read, and the heads with them, before a merge is judged against them.
until(t, "the watched heads read after the registrations", func() bool { return f.asked("GET /api/v1/repos/novox/app/branches") })
// A failed required step at a head's fingerprint refuses that head (§735, test 114), heard on the module's consumer.
until(t, "the runner's step-ended followed", func() bool { return rt.subscribed("mesh-pipeline-runner.step-ended.*.*.*") })
rt.ask("mesh/event", map[string]any{"envelope": map[string]any{"key": "mesh-pipeline-runner.step-ended.app.main." + X, "node": "test",
"body": map[string]any{"v": 1, "pipeline": "main.4", "module": "app", "branch": "main", "commit": X, "fingerprint": "fp-x",
"at": "2026-11-20T03:00:00Z", "result": map[string]any{"step": "unit", "status": "required", "outcome": "failed"}}}})
refused := rt.mergePull(map[string]any{"repository": "novox/app", "number": 6, "head": X})
members, _ := refused["members"].([]any)
if len(members) != 1 || members[0].(map[string]any)["state"] != "refused" ||
!strings.Contains(fmt.Sprint(members[0].(map[string]any)["why"]), "the unit step of app failed in run main.4") {
t.Fatalf("a head at a failed required step's fingerprint answered %v", refused)
}
if got := f.merged(); len(got) != 0 {
t.Fatalf("merged %v", got)
}
// Two pull requests in two repositories merge, in order, and say one merge-called (§734, §736).
both := rt.mergePull(map[string]any{"repository": "novox/app", "number": 7, "head": A}, map[string]any{"repository": "novox/lib", "number": 10, "head": B})
call, _ := both["call"].(string)
until(t, "the merge-called of the two", func() bool { return said(t, js)[call] != nil })
if got := numbers(said(t, js)[call]["members"]); fmt.Sprint(got) != "[7 10]" || fmt.Sprint(f.merged()) != "[novox/app#7 novox/lib#10]" {
t.Fatalf("the call of two said %v, merged %v", got, f.merged())
}
// The forge refuses the second merge: merge-called with the first and refused, merge-partial raised (§767, test 115).
partial := rt.mergePull(map[string]any{"repository": "novox/app", "number": 5, "head": A}, map[string]any{"repository": "novox/lib", "number": 9, "head": B})
pc, _ := partial["call"].(string)
until(t, "the partial call's merge-called", func() bool { return said(t, js)[pc] != nil })
body := said(t, js)[pc]
if fmt.Sprint(numbers(body["members"])) != "[5]" || fmt.Sprint(numbers(body["refused"])) != "[9]" {
t.Fatalf("the partial call said %v", body)
}
key := "delivery." + pc + ".merge-partial"
if e, err := kvs["findings"].Get(ctx, key); err != nil || !strings.Contains(string(e.Value()), `"severity":"urgent"`) {
t.Fatalf("merge-partial %s is not raised: %v", key, err)
}
// A later call landing the refused member clears it.
f.mu.Lock()
f.pulls["novox/lib#9"].refuse = false
f.mu.Unlock()
rt.mergePull(map[string]any{"repository": "novox/lib", "number": 9, "head": B})
until(t, "merge-partial cleared by the later call", func() bool {
_, err := kvs["findings"].Get(ctx, key)
return errors.Is(err, jetstream.ErrKeyNotFound)
})
}
type testLog struct{ t *testing.T }
func (w testLog) Write(p []byte) (int, error) {
defer func() { _ = recover() }()
w.t.Logf("bundle: %s", strings.TrimRight(string(p), "\n"))
return len(p), nil
}
+1
View File
@@ -6,6 +6,7 @@
// checks/readable every state another manifest reads to a readable announcement.
export const KEPT: readonly { readonly name: string; readonly readable?: boolean }[] = [
{ name: "announced" },
{ name: "calls" },
{ name: "bound", readable: true },
{ name: "findings", readable: true },
{ name: "failed-steps" },
-18
View File
@@ -3,8 +3,6 @@
// False, the default, leaves every repository's branch protection as people set it at the forge.
import { readFileSync } from "node:fs";
export const LEFT_AS_SET = "[gitea] main's rules are left as set at the forge (keep-main-rules is false)";
/** The setting from the settings-merged config file the mesh delivers; absent, unreadable or not true is false. */
export function keepMainRules(env: NodeJS.ProcessEnv = process.env): boolean {
const file = env.MESH_GITEA_CONFIG_FILE;
@@ -14,19 +12,3 @@ export function keepMainRules(env: NodeJS.ProcessEnv = process.env): boolean {
return v === true || v === "true";
} catch { return false; }
}
/** The 10-minute step: puts the rules right only when kept; else says once that they are left and writes nothing. */
export function mainRulesStep(keep: boolean, put: () => Promise<string[]>, say: (line: string) => void): () => Promise<void> {
let said = false;
let touched = -1;
return async () => {
if (!keep) {
if (!said) say(LEFT_AS_SET);
said = true;
return;
}
const repos = await put();
if (repos.length !== touched) say(`[gitea] main's rule is right in ${repos.length} repositories`);
touched = repos.length;
};
}
+189
View File
@@ -0,0 +1,189 @@
// **One merge call is a delivery's start and its group** (novox/hq design 47 H §734, §735; ADR 0682 §1, §2, §13; H-A-21,
// H-A-22, H-A-47): the seat git's `merge-pull` takes `pulls`, one or more members `{repository, number, head}`, and `by`,
// the caller as who@node, recorded beside the bus account the tool runner proved for the call. Every member is judged
// before any is merged: still the pull request's head, its base a watched branch, not merged already (refused
// `already-merged` with its commit), and no run at the head's build-input fingerprint failed a `required` step (the
// module's own `failed-steps`). No branch protection is judged (ADR 0682 §13). When one member is refused, none is merged
// and the answer names every refused member and why; else the members are merged in the order the call names them. The
// verb answers once, at the call's end: `call` and each member's outcome.
import { randomBytes } from "node:crypto";
import { UNPROVEN, callerOf } from "@novox/mesh-sdk/callers";
import type { Call, MemberOutcome, MergePullAnswer } from "@novox/mesh-delivery-contracts-git";
import type { GiteaClient } from "./client.js";
import { Refused, checkName } from "./guard.js";
import type { Judged } from "./failedsteps.js";
import { keptMember, sayCall, type Calls, type Say } from "./calls.js";
import type { Partials } from "./partials.js";
/** What a merge call reaches beside the forge's API. */
export interface CallDeps {
/** Whether the first registrations were written: until then no merge is made (design 47 §95). */
registered: () => boolean;
/** The watched branches the registrations name, by their origin repository `<owner>/<name>`. */
watched: () => ReadonlyMap<string, ReadonlySet<string>>;
/** The failed `required` step that refuses a head, or null (failedsteps.ts). */
judge: (head: string) => Promise<Judged | null>;
/** A new call's id: 16 lowercase hex characters (H-A-24). */
newCall?: () => string;
/** The state calls (calls.ts): the call is written before its first merge and as each member merges (§766). */
calls?: Calls;
now?: () => Date;
/** Says a seat event on its subject under an id the bus keeps once (mesh-sdk runtime.seatPublish): merge-called (§736). */
say?: Say;
/** The findings merge-partial (partials.ts; §767). */
partials?: Partials;
}
/** The forge's API a merge call uses. */
export type CallForge = Pick<GiteaClient, "getPullRequest" | "mergePullRequest" | "commitParents">;
/** One member as the call names it, and as it was judged. */
export interface Member {
repository: string;
owner: string;
repo: string;
number: number;
head: string;
/** The pull request's base, read at judging. */
branch: string;
state: MemberOutcome["state"];
commit?: string;
why?: string;
}
const SHA = /^[0-9a-f]{40}$/;
export const CALL = /^[0-9a-f]{16}$/;
/** A new call's id. */
export const newCallId = (): string => randomBytes(8).toString("hex");
/** The members a call names, each checked, or the reason the call is refused whole. */
export function membersOf(raw: unknown): Member[] {
if (!Array.isArray(raw) || raw.length === 0) throw new Refused("pulls names one or more members {repository, number, head}");
const seen = new Set<string>();
return raw.map((p: any) => {
const parts = String(p?.repository ?? "").split("/");
if (parts.length !== 2) throw new Refused(`repository ${JSON.stringify(p?.repository)} is not <owner>/<name>`);
const owner = checkName("owner", parts[0]), repo = checkName("name", parts[1]);
const number = Number(p?.number);
if (!Number.isInteger(number) || number < 1) throw new Refused(`${JSON.stringify(p?.number)} is not a pull request's number`);
const head = String(p?.head ?? "").trim();
if (!SHA.test(head)) throw new Refused("head is a commit's full 40-hex sha");
const repository = `${owner}/${repo}`;
if (seen.has(`${repository}#${number}`)) throw new Refused(`${repository}#${number} is named twice`);
seen.add(`${repository}#${number}`);
return { repository, owner, repo, number, head, branch: "", state: "judged" as const };
});
}
/** Why a member is refused at judging, or "" when it is judged. */
async function judgeMember(forge: CallForge, deps: CallDeps, m: Member): Promise<string> {
const pull = await forge.getPullRequest(m.owner, m.repo, m.number);
m.branch = String(pull.base ?? "");
if (pull.merged) {
if (pull.merge_commit_sha) m.commit = pull.merge_commit_sha;
return `already-merged: ${m.repository}#${m.number} was merged${pull.merge_commit_sha ? ` as ${pull.merge_commit_sha}` : ""}`;
}
if (pull.state !== "open") return `${m.repository}#${m.number} is closed`;
if (pull.head_sha !== m.head) {
return `head-moved: its head is ${String(pull.head_sha).slice(0, 12)}, not the ${m.head.slice(0, 12)} the caller names`;
}
if (!deps.watched().get(m.repository)?.has(m.branch)) return `its base ${m.branch} is no watched branch`;
const failed = await deps.judge(m.head);
if (failed) {
return `the ${failed.step} step of ${failed.module} failed in run ${failed.run} at its build-input fingerprint ${failed.fingerprint}`;
}
return "";
}
/** One member merged at its head, its merge commit read back; throws when the forge refused or did not name it. */
async function mergeMember(forge: CallForge, m: Member): Promise<string> {
await forge.mergePullRequest(m.owner, m.repo, m.number, "merge", true, m.head);
const merged = await forge.getPullRequest(m.owner, m.repo, m.number);
if (!merged.merge_commit_sha) throw new Error(`${m.repository}#${m.number} WAS merged, but the forge named no merge commit`);
// The merge is done once the forge named its commit: a read-back of its parents that fails is said, never a failed act.
try {
const parents = await forge.commitParents(m.owner, m.repo, merged.merge_commit_sha);
if (parents.length === 2 && parents[1] !== m.head) {
console.error(`[gitea] ${m.repository}#${m.number} WAS merged (${merged.merge_commit_sha}), but the forge merged ` +
`${parents[1].slice(0, 12)}, not the ${m.head.slice(0, 12)} the caller names (novox/hq issue 381)`);
}
} catch (err) {
console.error(`[gitea] ${m.repository}#${m.number} was merged (${merged.merge_commit_sha}); which head it joined could not be read back — ${err instanceof Error ? err.message : err}`);
}
return merged.merge_commit_sha;
}
/** A member's outcome as the answer says it. */
export const outcomeOf = (m: Member): MemberOutcome => ({ repository: m.repository, number: m.number, state: m.state,
...(m.commit ? { commit: m.commit } : {}), ...(m.why ? { why: m.why } : {}) });
/** merge-pull: one merge call (design 47 H §734, §735). */
export async function mergeCall(forge: CallForge, args: Record<string, unknown>, deps: CallDeps): Promise<MergePullAnswer> {
const by = String(args.by ?? "").trim();
if (!/^[^\s@]+@[^\s@]+$/.test(by)) throw new Refused("by is the caller as who@node");
const account = callerOf(args);
if (account === UNPROVEN) throw new Refused("the tool runner proved no caller account for this call, so nothing is merged");
const members = membersOf(args.pulls);
// Until the first registrations are written no merge is made (design 47 §95).
if (!deps.registered()) throw new Refused("no module is registered yet: the catalog has said no registration-changed, so no merge is made until the first registrations are written");
const call = (deps.newCall ?? newCallId)();
if (!CALL.test(call)) throw new Error(`the call's id ${JSON.stringify(call)} is not 16 lowercase hex characters`);
// Every member is judged before any is merged (§735).
let refused = false;
for (const m of members) {
const why = await judgeMember(forge, deps, m);
if (why) {
m.state = "refused";
m.why = why;
refused = true;
}
}
const now = deps.now ?? (() => new Date());
// The call as kept (§766), its `at` the time of its write, then of its last merge (the event's `at`, §736).
let at = now().toISOString();
const value = (said: boolean): Call => ({ by, account, at, members: members.map(keptMember), said });
const keep = async (said: boolean) => { await deps.calls?.put(call, value(said), now()); };
// A call refused at judging merged nothing and has nothing to say.
if (refused) {
await keep(true);
return { call, members: members.map(outcomeOf) };
}
// Written before the first merge, and again as each member merges.
await keep(false);
// Then merged in the order the call names them; a member the forge refuses stops the call (§767).
for (const m of members) {
try {
m.commit = await mergeMember(forge, m);
m.state = "merged";
at = now().toISOString();
await keep(false);
} catch (err) {
m.state = "refused";
m.why = `the forge refused the merge: ${err instanceof Error ? err.message : String(err)}`;
for (const rest of members.slice(members.indexOf(m) + 1)) {
rest.state = "refused";
rest.why = `not merged: ${m.repository}#${m.number} before it was refused by the forge`;
}
await keep(false);
// Raised for the refused members, the landed ones delivered as any call's (§767).
await deps.partials?.raise({ ...value(false), call });
break;
}
}
// Once its members are merged or refused, the call says merge-called, then is kept said (§736, §766).
if (deps.say) {
try {
await sayCall({ ...value(false), call }, deps.say);
await keep(true);
} catch (err) {
console.error(`[gitea] the merge call ${call} landed and its merge-called is not said yet; it is said at the next start — ${err instanceof Error ? err.message : err}`);
}
}
// A call that landed members clears every merge-partial whose refused members are now all landed (§767).
if (members.some((m) => m.state === "merged")) {
await deps.partials?.landed().catch((err) => console.error(`[gitea] the merge-partial findings could not be judged after the call ${call} — ${err instanceof Error ? err.message : err}`));
}
return { call, members: members.map(outcomeOf) };
}
+15 -3
View File
@@ -211,9 +211,16 @@
"trusted": true,
"default": {}
},
"call-retention": {
"type": "number",
"description": "How many days the forge module keeps a merge call in its state calls (design 47 H §766): a call older than this is deleted when a new call is written, oldest first.",
"trusted": false,
"minimum": 1,
"default": 30
},
"keep-main-rules": {
"type": "boolean",
"description": "Whether the module keeps main's branch protection as the mesh wants it. True: every ten minutes, and at the start, main's rule in every repository of the organisation novox is put to no push and the tools' account alone merging, and each apply of the `repositories` value narrows the main rule of the repositories it lists, requiring no status. False (the default): the module changes no existing repository's branch protection, whoever set it at the forge, but takes away a required status it finds on a rule covering main, once (ADR 0534 §1); a repository listed in `repositories` that does not exist is still made, with its first protection.",
"description": "Whether the module keeps main's branch protection as the mesh wants it. True: when the tools' account's token is minted, main's rule in every repository of the organisation novox is put to no push and the tools' account alone merging, and each apply of the `repositories` value narrows the main rule of the repositories it lists, requiring no status. False (the default): the module changes no existing repository's branch protection, whoever set it at the forge, but takes away a required status it finds on a rule covering main, once (ADR 0534 §1); a repository listed in `repositories` that does not exist is still made, with its first protection.",
"trusted": true,
"default": false
},
@@ -358,7 +365,8 @@
"takes-config": [
"url",
"keep-main-rules",
"main-mergers"
"main-mergers",
"call-retention"
]
},
{
@@ -623,6 +631,10 @@
{
"name": "failed-steps",
"history": 1
},
{
"name": "calls",
"history": 1
}
],
"reads": [
@@ -642,7 +654,7 @@
"consumes": [
"mesh-catalog.catalog-revision",
"mesh-catalog.registration-changed",
"mesh-pipeline-runner.step-ended",
"mesh-pipeline-runner.step-ended.*.*.*",
"git.branch-moved",
"git.pull-updated",
"git.pull-closed",
+78
View File
@@ -0,0 +1,78 @@
// **A member refused after every member was judged is said and raised** (novox/hq design 47 H §767; H-A-1, H-A-18,
// H-A-81): when the forge refuses a member after all were judged, the call stops merging and the forge module raises the
// finding `merge-partial`, scope `delivery`, id the call, naming each refused member, severity urgent, resolver operator,
// in its own state `findings`, which the condition keeper reads. It clears it when a later call lands every refused member
// (read from its own `calls`), or by its tool `forge_partial_clear` with `call` and `why`, written in the hand-act log.
import type { State } from "@novox/mesh-sdk/state";
import { findingKey } from "./catalog.js";
import type { Calls, KeptCall } from "./calls.js";
export const MERGE_PARTIAL = "merge-partial";
const SCOPE = "delivery";
/** The key of a call's merge-partial in the state findings. */
export const partialKey = (call: string): string => findingKey(SCOPE, call, MERGE_PARTIAL);
/** A member's name in a finding, `<repository>#<number>`. */
const named = (m: { repository: string; number: number }) => `${m.repository}#${m.number}`;
/** The merge-partial of a call the forge refused a member of after judging, as the condition keeper reads it. */
export function partialValue(c: KeptCall, observer = "gitea"): { key: string; value: Record<string, unknown> } {
const key = partialKey(c.call);
const landed = c.members.filter((m) => m.state === "merged").map(named);
const refused = c.members.filter((m) => m.state === "refused");
const summary = `the merge call ${c.call} by ${c.by} landed ${landed.length ? landed.join(", ") : "none"} and not ` +
refused.map((m) => `${named(m)} (${m.why ?? "refused"})`).join(", ");
return { key, value: {
v: 1, key, kind: MERGE_PARTIAL, subject: { scope: SCOPE, id: c.call }, severity: "urgent", resolver: "operator", summary,
headline: `A merge call landed in part: ${refused.map(named).join(", ")} not merged`,
explanation: `The forge refused ${refused.map(named).join(", ")} after every member of the merge call ${c.call} was judged, so ` +
`the repositories stand half-merged. A later merge call that lands them clears this, or forge_partial_clear with why.`,
resolved: "", evidence: [{ at: c.at, said: summary }], source: `${observer}.${MERGE_PARTIAL}`, observer, at: c.at,
} };
}
export class Partials {
constructor(private readonly findings: State<unknown>, private readonly calls: Calls,
private readonly log: (line: string) => void = () => {}) {}
/** Raises merge-partial for a call the forge refused a member of after judging. */
async raise(c: KeptCall): Promise<void> {
const f = partialValue(c);
await this.findings.put(f.key, f.value);
this.log(`merge-partial raised: ${String(f.value.summary)}`);
}
/** The calls whose merge-partial is held, newest first. */
async held(): Promise<KeptCall[]> {
const out: KeptCall[] = [];
for (const c of await this.calls.all()) if ((await this.findings.get(partialKey(c.call)))?.value) out.push(c);
return out;
}
/** After a call landed members: every held merge-partial whose refused members a later call landed, each, is cleared.
* Answers the calls cleared. */
async landed(): Promise<string[]> {
const all = await this.calls.all(); // newest first
const cleared: string[] = [];
for (const [i, c] of all.entries()) {
if (!(await this.findings.get(partialKey(c.call)))?.value) continue;
const later = new Set(all.slice(0, i).flatMap((x) => x.members.filter((m) => m.state === "merged").map(named)));
const refused = c.members.filter((m) => m.state === "refused").map(named);
if (refused.every((r) => later.has(r))) {
await this.findings.delete(partialKey(c.call));
cleared.push(c.call);
this.log(`merge-partial of ${c.call} cleared: a later call landed ${refused.join(", ")}`);
}
}
return cleared;
}
/** Clears one call's merge-partial by hand (forge_partial_clear); answers whether one was held. */
async clear(call: string): Promise<boolean> {
const held = !!(await this.findings.get(partialKey(call)))?.value;
if (held) await this.findings.delete(partialKey(call));
return held;
}
}
+2 -92
View File
@@ -1,15 +1,5 @@
// A pull request's merge check (novox/hq to-be 45 §9): what the forge's announcer says when a pull
// request's head moves, and the status contexts the check is kept under.
//
// **Before merge, never after.** Each new head of an open pull request is announced as `pull.updated`, and the mesh
// checks it against every machine of its facts before it merges. The verdict is the checker's `mesh/check`, which this
// module writes from the checker's owed state (check.ts); the controller's `checked`, which once set the two older
// statuses, is no event any more (ADR 0571 clause 13).
//
// Pure functions here, so they are tested without a forge.
import type { GiteaPull, GiteaRepo } from "./client.js";
import { movedSince } from "./client.js";
// The status contexts the forge's protections named for a merge check, read by the account's writes (writes.ts) to take
// them off a protection: no merge check is asked, weighed or written any more (design 47 H §764; H-A-28, H-A-100).
/** The status context a merge check's gate is kept under: one per commit, the newest replacing the last. */
export const CHECK_CONTEXT = "mesh/merge-gate";
@@ -20,83 +10,3 @@ export const REPO_CHECK_CONTEXT = "mesh/repo-check";
/** The one status main requires (novox/hq ADR 0447 §1, issue 1301): the checker's verdict, written by this module from the
* checker's owed state (check.ts, ADR 0521). Its line names the head and the trunk commit it judged: "pass <head12> on <trunk12> …". */
export const CHECK_STATUS = "mesh/check";
/** The statuses a branch's rule requires, from the rule the forge applies to it: none when it is unprotected or checks
* no status; undefined when the rule could not be read. */
export function requiredOf(rule: { enable_status_check?: boolean; status_check_contexts?: string[] | null } | null | undefined): string[] | undefined {
if (rule === undefined) return undefined;
if (!rule || !rule.enable_status_check) return [];
return (rule.status_check_contexts ?? []).filter(Boolean);
}
/**
* **The controller's statuses are written only where a base still requires them** (issue 1301; ADR 0503 §3, §5): of
* mesh/merge-gate and mesh/repo-check, those the base requires — hq's mesh/repo-check alone once the forge requires
* mesh/check everywhere else, so no mesh/merge-gate stands on a head that nothing will set. A base whose rule could not
* be read keeps both, as before: a status nothing requires blocks nothing, and one that is required is never left out.
*/
export function maintained(required: string[] | undefined): string[] {
const both = [CHECK_CONTEXT, REPO_CHECK_CONTEXT];
return required === undefined ? both : both.filter((c) => required.includes(c));
}
/** Whether mesh/merge-gate is written on a head of this base (maintained). */
export function writesGate(required: string[] | undefined): boolean {
return maintained(required).includes(CHECK_CONTEXT);
}
/**
* The pending words a head's merge check is announced with (novox/hq issue 446): where the check is, and since when,
* in the time the operator reads. They stood as "the mesh is mapping this head onto its module graph" for the whole
* check — the few seconds the controller maps the head and then the queue wait and the build — and readers took the
* forge for lagging (issue 423). The controller maps and queues the check in seconds, so from the announcement it waits
* in the build queue; mesh-delivery says "building on <machine> since …" when a build machine takes it.
*/
export function pendingWords(announced: Date): string {
const two = (n: number) => String(n).padStart(2, "0");
return `waiting in the build queue since ${two(announced.getHours())}:${two(announced.getMinutes())}`;
}
/** The heads already announced, keyed by `headKey`, so a restart announces nothing twice. */
export type Announced = Record<string, string>;
/** The key a pull request's announced head is kept under: `owner/repo#number@base`. The base is in it because a pull
* request retargeted keeps its head, and a head judged into one base is not judged into another (issue 1422, de-spiegel #6). */
export function headKey(full: string, number: number, base?: string): string {
return `${full}#${number}@${base ?? ""}`;
}
/** Which open pull requests have a head not yet announced. A pull request merged or closed is not
* open and is never asked about. */
export function headsToAnnounce(full: string, pulls: GiteaPull[], announced: Announced): GiteaPull[] {
return pulls.filter((p) => p.state === "open" && !!p.head_sha && announced[headKey(full, p.number, p.base)] !== p.head_sha);
}
/** A pull request the forge found updated, by its repository: what `searchOpenPulls` answers. */
export interface PullSeen {
owner: string;
name: string;
updated_at?: string;
}
/** **The repositories a pass looks at** (novox/hq issue 347): every one that moved since the floor, every one
* holding a pull request updated since the floor — opening, reopening or retargeting a pull request moves its own
* update time and not its repository's — and every one on a sweep or the first pass. */
export function reposToLook(repos: GiteaRepo[], floor: string, pulls: PullSeen[], sweep: boolean): GiteaRepo[] {
if (sweep || !floor) return repos;
const moved = new Set(movedSince(repos, floor).map((r) => r.full_name));
const at = Date.parse(floor);
for (const p of pulls) {
if (!p.updated_at || !(Date.parse(p.updated_at) < at)) moved.add(`${p.owner}/${p.name}`);
}
return repos.filter((r) => moved.has(r.full_name));
}
export function clipped(d: string): string {
d = d.replace(/\s+/g, " ").trim();
return d.length > 140 ? d.slice(0, 139) + "…" : d;
}
/** What a group member's gate says while the group's composed check is the one that judges it: the member's own check can say
* nothing more of it, so asking that check again brings no verdict that names a trunk (novox/hq issue 1106). */
export const WAITS_FOR_COMPOSED = "waits for its group's composed check";
+22 -80
View File
@@ -9,9 +9,9 @@
// 4xx, or a refusal of this holder) the kind `refused`, a forge that failed or did not answer the kind `failed`; an empty list or an absent file is answered
// only when the forge said so.
//
// **The acts carry the caller's id** (status, comment, view, note, merge-pull): an id the pull request or the note already
// holds is answered `held` and nothing is done again; `merge-pull` merges the head the caller names, only into a base
// whose protection refuses a push, and refuses a head at whose fingerprint a run failed a `required` step (design 47 §39, §314).
// **The acts carry the caller's id** (status, comment, view, note): an id the pull request or the note already holds is
// answered `held` and nothing is done again. `merge-pull` is one merge call of one or more pull requests, every member
// judged before any is merged, no branch protection judged (mergecall.ts; design 47 H §734, §735; ADR 0682 §13).
import type { ToolDefinition } from "@novox/mesh-sdk/tools";
import {
@@ -26,6 +26,9 @@ import { containedFrom, newestByContext } from "./checks.js";
import { Refused, checkName } from "./guard.js";
import { appendNote, viewBody, viewComment, type Runner } from "./delivery.js";
import type { Judged } from "./failedsteps.js";
import { mergeCall } from "./mergecall.js";
import type { Calls, Say } from "./calls.js";
import type { Partials } from "./partials.js";
/** The verbs of the seat, in its definition's order. */
export const VERBS: readonly string[] = Object.values(GIT_VERBS);
@@ -37,22 +40,23 @@ export const TAGS_PAGE = 50;
* is the manifest's container's; no variable names it (a MESH_* word nothing sets is refused, checks/environment). */
export const FORGE_CONTAINER = "gitea";
/** The writer every status of a head takes its turn on (gate.ts): the seat's status lands after every write of the head
* already asked for, so a recheck's pending never lands over a later verdict (novox/hq issue 456). */
export interface HeadStatuses {
status(owner: string, repo: string, sha: string, status: CommitStatus): Promise<void>;
}
/** What the holder reaches beside the forge's API: git in the forge's container (the note), the head's one writer of its
* statuses, and whether the first registrations are written. */
/** What the holder reaches beside the forge's API: git in the forge's container (the note), and whether the first
* registrations are written. */
export interface SeatDeps {
run: Runner;
container: string;
statuses: HeadStatuses;
/** Whether the first registrations were written (registrations.ts): until then merge-pull refuses every merge (design 47 §95). */
registered: () => boolean;
/** The failed `required` step that refuses a head, judged from the module's own state `failed-steps` (failedsteps.ts), or null. */
judge: (head: string) => Promise<Judged | null>;
/** The watched branches the registrations name, by their origin repository (registrations.ts): a member's base is one. */
watched: () => ReadonlyMap<string, ReadonlySet<string>>;
/** The state calls (calls.ts): each merge call written before its first merge (design 47 H §766). */
calls?: Calls;
/** Says merge-called on the seat (mesh-sdk runtime.seatPublish; design 47 H §736). */
say?: Say;
/** The findings merge-partial (partials.ts; design 47 H §767). */
partials?: Partials;
}
/** A failure as the contract says it: the forge's or this holder's refusal, or a forge that failed. */
@@ -149,7 +153,7 @@ export function seatTools(gitea: GiteaClient, deps: SeatDeps): ToolDefinition[]
const pull = pullOf(full, p);
return pull.state === "open" ? { pull, merging: await mergingOf(gitea, owner, repo, p) } : { pull };
}),
verb(GIT_VERBS.branch, "The seat git's branch: a branch's head, and whether a protection rule refuses a direct push and admits only merges.",
verb(GIT_VERBS.branch, "The seat git's branch: a branch's head.",
async (args): Promise<BranchAnswer> => {
const { owner, repo, full } = repositoryOf(args.repository);
// No branch named is the repository's default branch, read from the forge, as the verb file reads it (A-399).
@@ -158,7 +162,7 @@ export function seatTools(gitea: GiteaClient, deps: SeatDeps): ToolDefinition[]
if (branch === "") throw new Error(`the forge names no default branch of ${full}`);
// The head first: a branch the forge does not hold is its 404, the kind not-found, never an unprotected branch.
const head = await gitea.branchHead(owner, repo, branch);
return { repository: full, branch, head, protected: pushRefused(await gitea.appliedProtection(owner, repo, branch)) };
return { repository: full, branch, head };
}),
verb(GIT_VERBS.openPulls, "The seat git's open-pulls: every open pull request of every repository, with the statuses its base requires and those its head has.",
async (): Promise<OpenPullsAnswer> => {
@@ -218,14 +222,14 @@ export function seatTools(gitea: GiteaClient, deps: SeatDeps): ToolDefinition[]
const combined = await gitea.combinedStatus(owner, repo, commit);
return { commit, combined: combined.state, statuses: newestByContext(combined.statuses).map(statusOf) };
}),
verb(GIT_VERBS.status, "The seat git's status: an act of the forge bridge, a commit status set in its turn after every write of the head already asked for; the same id said again sets it again to the same.",
verb(GIT_VERBS.status, "The seat git's status: an act of the forge bridge, a commit status set on a commit; the same id said again sets it again to the same.",
async (args): Promise<StatusAnswer> => {
const id = idOf(args.id);
const { owner, repo } = repositoryOf(args.repository);
const commit = commitOf("commit", args.commit);
const state = String(args.state ?? "");
if (!STATES.has(state)) throw new Refused(`state ${JSON.stringify(state)} is none of ${[...STATES].join(", ")}`);
await deps.statuses.status(owner, repo, commit, { state: state as CommitStatus["state"], context: String(args.context ?? ""),
await gitea.setCommitStatus(owner, repo, commit, { state: state as CommitStatus["state"], context: String(args.context ?? ""),
description: String(args.description ?? ""), ...(args.target ? { target_url: String(args.target) } : {}) });
return { id, performed: true };
}),
@@ -258,8 +262,8 @@ export function seatTools(gitea: GiteaClient, deps: SeatDeps): ToolDefinition[]
const said = await appendNote(deps.run, deps.container, owner, repo, commit, "mesh-plan", `${String(args.line ?? "")} [${id}]`, id);
return said.added ? { id, performed: true } : { id, held: true, performed: true };
}),
verb(GIT_VERBS.mergePull, "The seat git's merge-pull: an act of the forge bridge, a pull request merged at the head the caller names; it refuses a head at whose fingerprint a required step failed.",
async (args): Promise<MergePullAnswer> => mergePull(gitea, args, deps.registered, deps.judge)),
verb(GIT_VERBS.mergePull, "The seat git's merge-pull: one merge call, a delivery's start and its group: the pull requests named (pulls, each {repository, number, head}) and by (who@node); every member is judged before any is merged (still its head, its base a watched branch, no required step failed at its fingerprint), none merged when one is refused, then each merged in the order named; it answers the call and each member's outcome.",
async (args): Promise<MergePullAnswer> => mergeCall(gitea, args, deps)),
verb(GIT_VERBS.tag, "The seat git's tag: the git tag go/vMAJOR.MINOR.PATCH of a released version, written at the commit its build was made from; a tag that is at that commit is performed.",
async (args): Promise<TagAnswer> => {
const { owner, repo } = repositoryOf(args.repository);
@@ -275,68 +279,6 @@ export function seatTools(gitea: GiteaClient, deps: SeatDeps): ToolDefinition[]
];
}
/** Whether a protection rule refuses a direct push and admits only merges: the rule exists and takes no push. */
export function pushRefused(rule: { enable_push?: boolean } | null): boolean {
return !!rule && rule.enable_push === false;
}
function holds(comments: GiteaComment[], id: string): boolean {
return comments.some((c) => String(c.body ?? "").includes(actMarker(id)));
}
/** merge-pull (design 47 §314): only the head the caller names, only into a base that takes no push, no check judged. */
export async function mergePull(gitea: GiteaClient, args: Record<string, unknown>, registered: () => boolean,
judge: (head: string) => Promise<Judged | null>): Promise<MergePullAnswer> {
const id = idOf(args.id);
const { owner, repo, full } = repositoryOf(args.repository);
const number = numberOf(args.number);
const head = commitOf("head", args.head);
const no = (why: string, kind: NonNullable<MergePullAnswer["refused-kind"]>): MergePullAnswer =>
({ id, refused: `${full}#${number} is not merged: ${why}`, "refused-kind": kind });
// Until the first registrations are written no merge is made: the old assigner would write a want from the trunk with no
// pipeline (design 47 §95). It names what is missing.
if (!registered()) return no("no module is registered yet: the catalog has said no registration-changed, so no merge is made until the first registrations are written", "no-registrations");
const pull = await gitea.getPullRequest(owner, repo, number);
if (pull.merged) {
// Already merged at that head: performed (the act said again after its answer was lost); at another, refused.
return pull.head_sha === head ? { id, performed: true, held: true, ...(pull.merge_commit_sha ? { "merge-commit": pull.merge_commit_sha } : {}) }
: no(`it was merged at ${String(pull.head_sha).slice(0, 12)}, not the ${head.slice(0, 12)} the caller names`, "head-moved");
}
if (pull.state !== "open") return no("it is closed", "git-refused");
if (pull.head_sha !== head) {
return no(`its head is ${String(pull.head_sha).slice(0, 12)}, not the ${head.slice(0, 12)} the caller names`, "head-moved");
}
const rule = await gitea.appliedProtection(owner, repo, String(pull.base ?? ""));
if (!pushRefused(rule)) {
return no(`its base ${pull.base} is guarded by no protection rule that refuses a push`, "unprotected");
}
// The head's runs, judged from the module's own state (design 47 §39): a step that failed at its fingerprint in any run refuses it,
// naming the run, the module and the step; a head no run named merges, and the runner being down changes nothing.
const failed = await judge(head);
if (failed) {
return { id, refused: `${full}#${number} is not merged: the ${failed.step} step of ${failed.module} failed in run ${failed.run} at its build-input fingerprint ${failed.fingerprint}`,
"refused-kind": "policy-failed", run: failed.run, module: failed.module, step: failed.step };
}
try {
await gitea.mergePullRequest(owner, repo, number, "merge", true, head);
} catch (err) {
const f = failure(err);
if (f["error-kind"] === "refused") return no(`the forge refused the merge: ${f.error}`, "git-refused");
throw err;
}
const merged = await gitea.getPullRequest(owner, repo, number);
if (!merged.merge_commit_sha) throw new Error(`${full}#${number} WAS merged, but the forge named no merge commit`);
// The merge is done once the forge named its commit: a read-back that fails is said, never answered as a failed act.
let parents: string[];
try {
parents = await gitea.commitParents(owner, repo, merged.merge_commit_sha);
} catch (err) {
console.error(`[gitea] ${full}#${number} was merged (${merged.merge_commit_sha}); which head it joined could not be read back — ${err instanceof Error ? err.message : err}`);
return { id, performed: true, "merge-commit": merged.merge_commit_sha };
}
if (parents.length === 2 && parents[1] !== head) {
throw new Error(`${full}#${number} WAS merged (${merged.merge_commit_sha}), but the forge merged ${parents[1].slice(0, 12)}, ` +
`not the ${head.slice(0, 12)} the caller names (novox/hq issue 381)`);
}
return { id, performed: true, "merge-commit": merged.merge_commit_sha };
}
-298
View File
@@ -1,298 +0,0 @@
// **A delivery group's member is checked beside the other members' heads, and a sibling's move puts that verdict out of
// date** (novox/hq ADR 0382 §5, §6; issue 867).
//
// The controller's verdict (`checked`) names the siblings its check read: each as the sibling's repository, pull
// request, head, base branch and the base commit the sibling's head was merged onto. This module, the forge's holder,
// keeps them per open pull request, beside its other records, and:
//
// - on its own hearing of a sibling's new head, of its close unmerged, or of a move of its base, sets
// mesh/merge-gate and mesh/repo-check of every member whose verdict names that sibling back to pending, with the
// reason. Nothing is run for it. The one move that does not count is the sibling's own merge of the head that was
// read onto the base commit that was read (in either order of the two merges);
// - lets the merge tool refuse a verdict that read siblings unless mesh/delivery-group passed at the very heads it
// read, and every sibling head it read carries an approving review at that head (merge.ts).
//
// A verdict without siblings (a controller from before ADR 0382) is none of this: nothing is kept and nothing changes.
// Pure functions and one small file of the module's own state, so this is tested without a forge.
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
import { dirname } from "node:path";
import type { CommitStatus, GiteaPull, HeadCheck } from "./client.js";
import { Refused } from "./guard.js";
import { CHECK_CONTEXT, REPO_CHECK_CONTEXT, clipped } from "./pulls.js";
import { sameCommit, twelve, type OutOfDateWriter } from "./trunk.js";
/** The status the delivery group's owner sets on each member's head (novox/hq ADR 0239). */
export const GROUP_CONTEXT = "mesh/delivery-group";
/** One sibling a verdict read, as the controller names it (contract of ADR 0382 §4). */
export interface SiblingNamed {
repository: string;
number: number;
head: string;
base: string;
base_commit: string;
/** Set here, never by the controller: the sibling merged its head onto its base commit read, so it is no sibling's
* move any more. */
merged?: boolean;
}
/** What is kept of one member's latest verdict that read siblings: the head it was of and the siblings it named. */
export interface SiblingEntry {
head: string;
siblings: SiblingNamed[];
}
/** The records, by `owner/repo#number` of the member. */
export type SiblingRecord = Record<string, SiblingEntry>;
/** The member's key. */
export function memberKey(owner: string, repo: string, number: number): string {
return `${owner}/${repo}#${number}`.toLowerCase();
}
/** The siblings a verdict names, trimmed to what is kept; none when it names none or names one badly. */
export function siblingsOf(named: unknown): SiblingNamed[] {
if (!Array.isArray(named)) return [];
const out: SiblingNamed[] = [];
for (const s of named) {
const r = s as Record<string, unknown>;
const repository = String(r?.repository ?? ""), head = String(r?.head ?? ""), base = String(r?.base ?? "");
const number = Number(r?.number);
if (!repository || !head || !base || !Number.isInteger(number) || number <= 0) continue;
out.push({ repository, number, head, base, base_commit: String(r?.base_commit ?? "") });
}
return out;
}
/** The siblings as a status names them: "mesh-host#114@abcdef123456, …". */
export function siblingWords(siblings: SiblingNamed[]): string {
return siblings.map((s) => `${s.repository.split("/").pop()}#${s.number}@${twelve(s.head)}`).join(", ");
}
/** What a status of a verdict that read siblings carries, after the commits it judged. */
export function besideWords(siblings: SiblingNamed[]): string {
// Short, so that the verdict word and the start of its reason survive the forge's 140 characters: the first sibling
// by its pull request and 8 characters of its head, and how many more. The whole list is the holder's record and the comment's.
const first = siblings[0];
const more = siblings.length > 1 ? ` +${siblings.length - 1} more` : "";
return `beside ${first.repository.split("/").pop()}#${first.number}@${twelve(first.head).slice(0, 8)}${more}`;
}
/** The mark a status carries when the siblings could not be learned (ADR 0382 §1): said, never silent. */
export const UNKNOWN_MARK = "siblings unknown";
/** Whether a status names that its verdict read siblings (so that a record lost does not read as none). */
export function namesSiblings(description: string | undefined): boolean {
return / beside [\w.-]+#\d+@[0-9a-f]{8}\b/.test(description ?? "");
}
/** Whether a status is a verdict put out of date by a sibling's move. */
export function siblingOutOfDate(description: string | undefined): boolean {
return /^out of date: judged beside /.test(description ?? "");
}
// --- the record on disk ----------------------------------------------------------------------------------------
/** The file the holder keeps the siblings its verdicts name in, beside its other records. */
export function siblingsFile(stateDir: string | undefined): string | null {
return stateDir ? `${stateDir.replace(/\/+$/, "")}/siblings-named.json` : null;
}
export function readSiblings(file: string | null): SiblingRecord {
if (!file || !existsSync(file)) return {};
try {
return (JSON.parse(readFileSync(file, "utf8")) as { members?: SiblingRecord }).members ?? {};
} catch {
return {};
}
}
export function keepSiblings(file: string | null, record: SiblingRecord): void {
if (!file) return;
try {
mkdirSync(dirname(file), { recursive: true });
writeFileSync(file + ".tmp", JSON.stringify({ members: record }));
renameSync(file + ".tmp", file);
} catch (err) {
console.error(`[gitea] the siblings a verdict named could not be kept — ${err instanceof Error ? err.message : err}`);
}
}
// --- what a sibling's move is ---------------------------------------------------------------------------------
/** What weighing a sibling reads of the forge. */
export interface SiblingForge {
getPullRequest(owner: string, repo: string, index: number): Promise<GiteaPull>;
branchHead(owner: string, repo: string, branch: string): Promise<string>;
commitParents(owner: string, repo: string, sha: string): Promise<string[]>;
}
/** The reason a verdict that named this sibling is out of date, from what the forge holds now, or nothing; and whether
* the sibling has merged its head read onto the base commit read, which ends it as a sibling. */
export async function siblingMoved(forge: SiblingForge, s: SiblingNamed): Promise<{ reason?: string; merged?: boolean }> {
const [owner, repo] = s.repository.split("/");
const who = `${repo}#${s.number}`;
const pull = await forge.getPullRequest(owner, repo, s.number);
if (pull.merged) {
// Its own merge of the head that was read onto the base commit that was read: the head the merge joined is the head
// read, and the commit it was made onto is the base commit read. Any other merge is a move of the base.
const parents = pull.merge_commit_sha ? await forge.commitParents(owner, repo, pull.merge_commit_sha).catch(() => []) : [];
const own = sameCommit(pull.head_sha, s.head) && parents.length >= 1 && sameCommit(parents[0], s.base_commit) &&
(parents.length === 1 || sameCommit(parents[1], s.head));
if (own) return { merged: true };
return { reason: `${who} was merged otherwise than its head ${twelve(s.head)} onto ${twelve(s.base_commit)}` };
}
if (pull.state !== "open") return { reason: `${who} was closed unmerged` };
if (!sameCommit(pull.head_sha, s.head)) {
return { reason: `${who} at ${twelve(s.head)}, it is now at ${twelve(pull.head_sha)}` };
}
const base = await forge.branchHead(owner, repo, s.base);
if (!sameCommit(base, s.base_commit)) {
return { reason: `${who} merged onto ${twelve(s.base_commit)}, its ${s.base} is now ${twelve(base)}` };
}
return {};
}
/** A verdict out of date because a sibling moved, as its statuses say it (ADR 0382 §5; the wording of ADR 0323 §4). */
export function siblingOutOfDateWords(reason: string): string {
return clipped(`out of date: judged beside ${reason}; judged again on a recheck or when it is merged`);
}
/** The statuses a sibling's move puts back to pending on one member's head, from what the forge holds on it now: none
* when it has no merge check, or its gate is pending (a check on its way, or already out of date). */
export function siblingStatuses(checks: Record<string, HeadCheck>, reason: string): CommitStatus[] {
const gate = checks[CHECK_CONTEXT];
if (!gate || gate.state === "pending") return [];
const description = siblingOutOfDateWords(reason);
const out: CommitStatus[] = [{ state: "pending", context: CHECK_CONTEXT, description }];
if (checks[REPO_CHECK_CONTEXT]) out.push({ state: "pending", context: REPO_CHECK_CONTEXT, description });
return out;
}
/** What weighing a sibling's move writes with, beside the forge's reads. */
export interface SiblingWeighing extends SiblingForge {}
/**
* A sibling moved (a new head, a close, a base move, a merge): every member whose latest verdict names it has its
* merge check put back to pending with the reason. `repository` and, when the event names one, `number` say which
* sibling. A member whose head is no longer the one its verdict was of is dropped from the record: its new head is
* checked afresh. Nothing is run. Answers whether the record changed. A read that fails leaves that member for the next
* move to weigh, and is said.
*/
export async function weighSiblings(forge: SiblingWeighing, gates: OutOfDateWriter, record: SiblingRecord,
repository: string, number?: number): Promise<boolean> {
let changed = false;
const repo = repository.toLowerCase();
for (const [key, entry] of Object.entries(record)) {
const [path] = key.split("#");
const [owner, name] = path.split("/");
const memberNumber = Number(key.split("#")[1]);
// A member that is merged or no longer open has no verdict to put out of date: its entry goes (the record must not
// grow without bound, and a merged head is never re-pended by a sibling's later push). Weighed when the event is the
// member's own, or names one of its siblings.
const own = path === repo && (number === undefined || number === memberNumber);
if (own || entry.siblings.some((s) => !s.merged && s.repository.toLowerCase() === repo && (number === undefined || s.number === number))) {
try {
const member = await forge.getPullRequest(owner, name, memberNumber);
if (member.merged || member.state !== "open") {
delete record[key];
changed = true;
continue;
}
} catch (err) {
console.error(`[gitea] ${key}: whether it is still open could not be read — ${err instanceof Error ? err.message : err}`);
}
}
for (const s of entry.siblings) {
if (s.merged || s.repository.toLowerCase() !== repo || (number !== undefined && s.number !== number)) continue;
try {
const moved = await siblingMoved(forge, s);
if (moved.merged) {
s.merged = true;
changed = true;
continue;
}
if (!moved.reason) continue;
const member = await forge.getPullRequest(owner, name, memberNumber);
if (!sameCommit(member.head_sha, entry.head)) {
delete record[key];
changed = true;
break;
}
const written = await gates.outOfDate(owner, name, entry.head, (checks) => siblingStatuses(checks, moved.reason!),
member.html_url || undefined);
if (written.length) {
console.log(`[gitea] ${key}: its verdict was judged beside ${moved.reason}: out of date, nothing run (novox/hq ADR 0382)`);
}
break;
} catch (err) {
console.error(`[gitea] ${key}: whether ${s.repository}#${s.number} moved could not be weighed, so it is weighed again ` +
`on its next move — ${err instanceof Error ? err.message : err}`);
}
}
}
return changed;
}
// --- the merge tool's rule (ADR 0382 §6) ----------------------------------------------------------------------
/** What the rule reads beside the pull request being merged. */
export interface GroupForge {
headChecks(owner: string, repo: string, sha: string): Promise<Record<string, HeadCheck>>;
}
/** The heads the operator's Approve covers (novox/hq ADR 0421 §9, issue 1022), as mesh-delivery hands them to the merge
* tool: `owner/repo@<full sha>`, one per member, by repository. A malformed entry is refused, never skipped. */
export function approvedHeadsOf(given: unknown): Map<string, string> | undefined {
if (given === undefined || given === null) return undefined;
if (!Array.isArray(given)) throw new Refused("approved_heads must be a list of owner/repo@<full sha>. Nothing was merged");
const out = new Map<string, string>();
for (const entry of given) {
const m = /^([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)@([0-9a-f]{40}|[0-9a-f]{64})$/i.exec(String(entry));
if (!m) throw new Refused(`approved_heads holds ${JSON.stringify(entry)}, which is not owner/repo@<full sha>. Nothing was merged`);
out.set(m[1].toLowerCase(), m[2].toLowerCase());
}
return out;
}
/** Why a pull request's head is not one the Approve covers, in words, or nothing: its repository is not named, or names
* another head. */
export function notApproved(approved: Map<string, string>, repository: string, number: number, head: string): string | undefined {
const covered = approved.get(repository.toLowerCase());
const at = `${repository.split("/")[1]}#${number}@${twelve(head)}`;
if (covered === undefined) return `${at} is not among the heads the Approve covers`;
if (covered !== head.toLowerCase()) return `${at} is not the head the Approve covers (${twelve(covered)})`;
return undefined;
}
/**
* What stops a pull request whose verdict read siblings from merging, in words, or nothing: mesh/delivery-group must be
* a success at its own head and at every sibling head the verdict read, and every head read must be one the operator's
* Approve covers (ADR 0421 §9: the Approve is the review; the merge tool takes the approved heads from mesh-delivery).
* Every missing thing is named.
*/
export async function groupRefusal(forge: GroupForge, self: { owner: string; repo: string; number: number; head: string },
siblings: SiblingNamed[], approved: Map<string, string> | undefined): Promise<string | undefined> {
const missing: string[] = [];
const members = [{ repository: `${self.owner}/${self.repo}`, number: self.number, head: self.head },
...siblings.map((s) => ({ repository: s.repository, number: s.number, head: s.head }))];
for (const m of members) {
const [owner, repo] = m.repository.split("/");
const at = `${repo}#${m.number}@${twelve(m.head)}`;
let group: HeadCheck | undefined;
try {
group = (await forge.headChecks(owner, repo, m.head))[GROUP_CONTEXT];
} catch (err) {
missing.push(`${GROUP_CONTEXT} at ${at} could not be read (${err instanceof Error ? err.message : err})`);
continue;
}
if (group?.state !== "success") missing.push(`${GROUP_CONTEXT} is ${group?.state ?? "missing"} at ${at}`);
if (!approved) missing.push(`${at} is covered by no Approve: the merge was handed no approved heads`);
else {
const why = notApproved(approved, m.repository, m.number, m.head);
if (why) missing.push(why);
}
}
return missing.length ? missing.join("; ") : undefined;
}
-16
View File
@@ -12,22 +12,6 @@ const repo = (full: string, updated: string) => {
return { full_name: full, owner, name, private: false, html_url: "", updated_at: updated };
};
test("a pull request opened after the margin is looked at, by its own update time", async () => {
const { reposToLook } = await import("../pulls.ts");
const pushed = "2026-10-09T10:00:00Z"; // the branch pushed: the repository's update time
// The pull request opened two minutes later; the last pass was at 10:02:30, so the floor is 10:01:30.
const floor = "2026-10-09T10:01:30Z";
const repos = [repo("novox/mesh-sdk", pushed), repo("novox/hq", "2026-10-09T09:00:00Z")];
const opened = [{ owner: "novox", name: "mesh-sdk", updated_at: "2026-10-09T10:02:00Z" }];
assert.deepEqual(reposToLook(repos, floor, opened, false).map((r) => r.full_name), ["novox/mesh-sdk"],
"the repository of a pull request updated since the floor, though the repository itself did not move");
assert.deepEqual(reposToLook(repos, floor, [], false).map((r) => r.full_name), [],
"without the pull request's own time nothing is looked at — the fault");
assert.deepEqual(reposToLook(repos, floor, [], true).map((r) => r.full_name).sort(), ["novox/hq", "novox/mesh-sdk"],
"a sweep looks at every repository");
assert.deepEqual(reposToLook(repos, "", [], false).length, 2, "the first pass looks at every repository");
});
test("every open pull request is read with what its base requires and what its head has (gitea_open_pulls)", async () => {
const { GiteaClient } = await import("../client.ts");
const asked: string[] = [];
+119
View File
@@ -0,0 +1,119 @@
import assert from "node:assert/strict";
import { test } from "node:test";
import { memory } from "./memstate.ts";
// **The call is written before its first merge** (novox/hq design 47 H §766; H-A-18, H-A-47, H-A-71): the key
// call.<call> of the state calls holds by, the proved account, at, each member with its base and its state (judged before
// the first merge, merged with its commit as it merges) and said; a call past call-retention is deleted on a new call's
// write, oldest first.
const A = "a".repeat(40), B = "b".repeat(40);
test("a merge call is kept before its first merge, each member judged, then merged with its commit", async () => {
const { mergeCall } = await import("../dist/mergecall.js");
const { Calls } = await import("../dist/calls.js");
const { runAs } = await import("@novox/mesh-sdk/callers");
const { kv, st } = memory();
const calls = new Calls(st as any);
const seenAtMerge: any[] = [];
const pulls: Record<string, any> = { 5: { head: A, merged: false }, 9: { head: B, merged: false } };
const forge = {
getPullRequest: async (_o: string, r: string, n: number) => ({ number: n, state: "open", merged: pulls[n].merged, base: "main",
head_sha: pulls[n].head, ...(pulls[n].merged ? { merge_commit_sha: String(n).repeat(40) } : {}) }),
mergePullRequest: async (_o: string, _r: string, n: number) => {
seenAtMerge.push(structuredClone(kv.get("call.0123456789abcdef")));
pulls[n].merged = true;
},
commitParents: async () => [],
};
const args = { by: "lead@shanks", pulls: [{ repository: "novox/app", number: 5, head: A }, { repository: "novox/app", number: 9, head: B }] };
const at = new Date("2026-11-20T03:00:00Z");
await runAs({ "mesh/caller": "shanks.claude-code" }, args, () => mergeCall(forge as any, args, { registered: () => true,
watched: () => new Map([["novox/app", new Set(["main"])]]), judge: async () => null, newCall: () => "0123456789abcdef",
calls, now: () => at } as any));
const first = seenAtMerge[0];
assert.deepEqual([first.by, first.account, first.at, first.said], ["lead@shanks", "shanks.claude-code", at.toISOString(), false]);
assert.deepEqual(first.members.map((m: any) => [m.number, m.branch, m.head, m.state]), [[5, "main", A, "judged"], [9, "main", B, "judged"]]);
assert.deepEqual(seenAtMerge[1].members.map((m: any) => [m.state, m.commit]), [["merged", "5".repeat(40)], ["judged", undefined]]);
const kept = await calls.get("0123456789abcdef");
assert.deepEqual(kept?.members.map((m: any) => m.state), ["merged", "merged"]);
});
test("a call past call-retention is deleted on a new call's write, oldest first; a younger one is kept", async () => {
const { Calls } = await import("../dist/calls.js");
const { kv, st } = memory();
const calls = new Calls(st as any, () => 30);
const call = (at: string) => ({ by: "a@b", account: "x", at, members: [], said: true });
await calls.put("1111111111111111", call("2026-09-01T00:00:00Z"), new Date("2026-09-01T00:00:00Z"));
await calls.put("2222222222222222", call("2026-10-25T00:00:00Z"), new Date("2026-10-25T00:00:00Z"));
await calls.put("3333333333333333", call("2026-11-20T00:00:00Z"), new Date("2026-11-20T00:00:00Z"));
assert.deepEqual([...kv.keys()].sort(), ["call.2222222222222222", "call.3333333333333333"]);
assert.deepEqual((await calls.all()).map((c) => c.call), ["3333333333333333", "2222222222222222"], "newest first");
});
// **The merge call says one event** (design 47 H §736, §766; test 111's stop case): merge-called on merge-called.<call> with
// the landed members, each with its base and merge commit; a call that landed none says none; at the start a call whose
// event is not said (a stop after the second of three merges) says one naming the two that landed, and is kept said.
test("a call says one merge-called of what landed; none for a call that landed none; the start says an unsaid one", async () => {
const { mergeCall } = await import("../dist/mergecall.js");
const { Calls, sayUnsaid } = await import("../dist/calls.js");
const { runAs } = await import("@novox/mesh-sdk/callers");
const said: { subject: string; body: any; id?: string }[] = [];
const say = async (subject: string, body: unknown, id?: string) => { said.push({ subject, body, id }); };
const { st } = memory();
const calls = new Calls(st as any);
const pulls: Record<number, any> = { 5: { head: A, merged: false, state: "open" }, 9: { head: B, merged: false, state: "closed" } };
const forge = {
getPullRequest: async (_o: string, _r: string, n: number) => ({ number: n, state: pulls[n].state, merged: pulls[n].merged, base: "main",
head_sha: pulls[n].head, ...(pulls[n].merged ? { merge_commit_sha: String(n).repeat(40) } : {}) }),
mergePullRequest: async (_o: string, _r: string, n: number) => { pulls[n].merged = true; },
commitParents: async () => [],
};
const deps = (call: string) => ({ registered: () => true, watched: () => new Map([["novox/app", new Set(["main"])]]),
judge: async () => null, newCall: () => call, calls, say, now: () => new Date("2026-11-20T03:00:00Z") });
const run = (call: string, numbers: number[]) => {
const args = { by: "lead@shanks", pulls: numbers.map((n) => ({ repository: "novox/app", number: n, head: pulls[n].head })) };
return runAs({ "mesh/caller": "shanks.claude-code" }, args, () => mergeCall(forge as any, args, deps(call) as any));
};
await run("00000000000000aa", [5, 9]); // refused at judging: no event
assert.deepEqual(said, []);
await run("00000000000000bb", [5]);
assert.equal(said.length, 1);
assert.deepEqual([said[0].subject, said[0].id], ["mesh.seat.git.event.merge-called.00000000000000bb", "merge-called.00000000000000bb"]);
assert.deepEqual(said[0].body, { call: "00000000000000bb", by: "lead@shanks", account: "shanks.claude-code", at: "2026-11-20T03:00:00.000Z",
members: [{ repository: "novox/app", number: 5, branch: "main", head: A, commit: "5".repeat(40) }] });
assert.equal((await calls.get("00000000000000bb"))?.said, true);
// A stop after the second of three merges: kept, not said.
const m = (n: number, state: string) => ({ repository: "novox/app", number: n, branch: "main", head: A, state, ...(state === "merged" ? { commit: String(n).repeat(40) } : {}) });
await calls.put("00000000000000cc", { by: "lead@shanks", account: "x", at: "2026-11-20T03:01:00Z", members: [m(1, "merged"), m(2, "merged"), m(3, "judged")], said: false } as any);
said.length = 0;
assert.deepEqual(await sayUnsaid(calls, say), ["00000000000000cc"]);
assert.deepEqual(said.map((s) => s.body.members.map((x: any) => x.number)), [[1, 2]]);
assert.equal(said[0].body.refused, undefined, "a member not merged after a stop is no refused member");
assert.deepEqual(await sayUnsaid(calls, say), [], "said once");
});
// The merge calls' tools (design 47 H §766): forge_calls answers the calls newest first with each member's state, and
// forge_call_say_again says a call's merge-called again once the hand-act log took it.
test("forge_calls reads the calls newest first; forge_call_say_again says one again after the hand-act log", async () => {
const { Calls } = await import("../dist/calls.js");
const { Partials } = await import("../dist/partials.js");
const { callTools } = await import("../dist/tools/calls.js");
const { st } = memory();
const calls = new Calls(st as any);
const m = (n: number, state: string) => ({ repository: "novox/app", number: n, branch: "main", head: A, state, ...(state === "merged" ? { commit: String(n).repeat(40) } : {}) });
await calls.put("00000000000000aa", { by: "a@b", account: "x", at: "2026-11-20T01:00:00Z", members: [m(1, "merged")], said: true } as any);
await calls.put("00000000000000bb", { by: "a@b", account: "x", at: "2026-11-20T02:00:00Z", members: [m(2, "refused")], said: true } as any);
const said: any[] = [], acts: any[] = [];
const tools = callTools(calls, new Partials(memory().st as any, calls), async (subject: string, body: unknown) => { said.push([subject, body]); },
async (a) => { acts.push(a); });
const tool = (name: string) => tools.find((t) => t.name === name)!;
const read: any = await tool("forge_calls").run({});
assert.deepEqual(read.calls.map((c: any) => [c.call, c.members[0].state]), [["00000000000000bb", "refused"], ["00000000000000aa", "merged"]]);
await assert.rejects(tool("forge_call_say_again").run({ call: "00000000000000aa" }), /names the call .* and why/);
await assert.rejects(tool("forge_call_say_again").run({ call: "00000000000000ff", why: "x" }), /keeps no merge call/);
const again: any = await tool("forge_call_say_again").run({ call: "00000000000000aa", why: "the gate missed it" });
assert.deepEqual([again.said, acts[0].verb, said[0][0]], [true, "forge_call_say_again", "mesh.seat.git.event.merge-called.00000000000000aa"]);
const none: any = await tool("forge_call_say_again").run({ call: "00000000000000bb", why: "x" });
assert.equal(none.said, false, "a call that landed none says none");
});
+25 -5
View File
@@ -20,7 +20,7 @@ function memory() {
}
const ended = (commit: string, outcome: string, extra: Record<string, unknown> = {}, over: Record<string, unknown> = {}) => ({
v: 1, pipeline: `main.7.nats-${commit.slice(0, 2)}`, module: "nats", branch: "main", commit, at: "2026-11-11T12:00:00Z",
result: { step: "unit", status: "required", outcome, fingerprint: "fp-1", ...extra }, ...over }) as any;
fingerprint: "fp-1", result: { step: "unit", status: "required", outcome, ...extra }, ...over }) as any;
test("a head is refused by a required step that failed at its fingerprint in any run, until a rerun passes it", async () => {
const { kv, st } = memory();
@@ -45,12 +45,13 @@ test("a head is refused by a required step that failed at its fingerprint in any
// A later commit at the fingerprint is refused too, and a failed optional step refuses nothing.
await f.stepEnded(ended(C3, "passed"));
await judged("a later commit of the same content", C3, "run-on-request nats unit");
await f.stepEnded(ended(C3, "failed", { step: "lint", status: "optional", fingerprint: "fp-2" }));
await f.stepEnded(ended(C3, "failed", { step: "lint", status: "optional" }, { fingerprint: "fp-2" }));
await judged("a failed optional step", C3, "run-on-request nats unit");
assert.equal(kv.has(failedStepKey("nats", "fp-2", "lint")), false);
// A result that names no fingerprint is kept at the one the seat's step event carries (`fingerprint`).
await f.stepEnded(ended(C3, "failed", { step: "lint", fingerprint: undefined }, { fingerprint: "fp-3" }));
// The fingerprint is the body's alone, never the result's (G §585, H-A-93).
await f.stepEnded(ended(C3, "failed", { step: "lint", fingerprint: "fp-x" }, { fingerprint: "fp-3" }));
assert.ok(kv.has(failedStepKey("nats", "fp-3", "lint")), "the event's fingerprint is kept");
assert.equal(kv.has(failedStepKey("nats", "fp-x", "lint")), false, "the result's is never read");
// A plain pass clears nothing; a rerun that passes clears it.
await f.stepEnded(ended(C2, "passed"));
await judged("a plain pass", C2, "run-on-request nats unit");
@@ -109,7 +110,8 @@ test("a seen key past 30 days is deleted at the next step-ended, a younger one k
const now = new Date("2026-11-11T12:00:00Z");
const old = (n: number) => new Date(Date.parse("2026-10-01T00:00:00Z") - n * 60000).toISOString();
await st.put(seenKey(C1, "old"), { v: 1, commit: C1, module: "old", fingerprints: ["x"], at: old(0) });
await st.put(seenKey(C2, "young"), { v: 1, commit: C2, module: "young", fingerprints: ["x"], at: "2026-10-20T00:00:00Z" });
// Younger than 30 days both before the step-ended and before the tool's own clock, today's: kept by both.
await st.put(seenKey(C2, "young"), { v: 1, commit: C2, module: "young", fingerprints: ["x"], at: new Date(Date.now() - 86_400_000).toISOString() });
await f.stepEnded(ended(C3, "passed"));
assert.equal(kv.has(seenKey(C1, "old")), false, "past 30 days: deleted at the next step-ended");
assert.equal(kv.has(seenKey(C2, "young")), true, "younger: kept");
@@ -121,3 +123,21 @@ test("a seen key past 30 days is deleted at the next step-ended, a younger one k
const done: any = await runAs({ "mesh/caller": "operator" }, {}, () => tool.run({ why: "stale" }));
assert.deepEqual([done.deleted.length, acts[0].verb], [1, "git_seen_expire"]);
});
// step-unread (G §585, H-A-93): a step-ended of a pipeline's commit without the body's fingerprint records nothing and writes
// the finding, scope module, its subject the step's module, keyed <run>.<module>.<step>, warning, resolver operator; a later
// step-ended of that step with its fingerprint clears it.
test("a step-ended without its fingerprint writes step-unread, cleared by the step's later step-ended with it", async () => {
const { stepUnreadFinding } = await import("../failedsteps.js");
const { kv, st } = memory();
const findings = memory();
const f = new FailedSteps(st as any, () => {}, () => true, async () => ({ bytes: 0, keys: 0, max_bytes: 0 }), findings.st as any);
await f.stepEnded(ended(C1, "failed", { fingerprint: "fp-in-result" }, { fingerprint: undefined }));
const { key } = stepUnreadFinding("main.7.nats-" + C1.slice(0, 2), "nats", "unit", "");
const raised: any = findings.kv.get(key);
assert.deepEqual([raised?.kind, raised?.subject, raised?.severity, raised?.resolver], ["step-unread", { scope: "module", id: "nats" }, "warning", "operator"]);
assert.match(raised.summary, /unit of nats in run main\.7\.nats-/);
assert.equal([...kv.keys()].some((k) => !k.startsWith("seen.")), false, "no failure recorded");
await f.stepEnded(ended(C1, "failed"));
assert.equal(findings.kv.has(key), false, "cleared by the step's step-ended with its fingerprint");
});
-69
View File
@@ -1,69 +0,0 @@
import assert from "node:assert/strict";
import { test } from "node:test";
// **One writer of a head's mesh/merge-gate** (novox/hq issue 446): the announcement's pending words, a recheck's pending and
// a trunk's move, each write of a head in the order it was asked.
const SHA = "a6b08de8507c1703528277e5cefc80548dbc9bb3";
/** A forge that keeps the newest status per context, as gitea does, and whose writes take as long as a test says. */
function aForge() {
const kept: Record<string, { state: string; description: string; updated_at: string }> = {};
const written: string[] = [];
let failNext = 0;
let hold: Promise<void> | null = null;
let release = () => {};
return {
kept, written,
/** The next writes fail: a request the forge did not take. */
failWrites(n = 1) {
failNext = n;
},
/** The next writes wait until released: a request in flight. */
holdWrites() {
hold = new Promise<void>((r) => (release = r));
},
release() {
hold = null;
release();
},
async headChecks() {
return {};
},
async setCommitStatus(_o: string, _r: string, _sha: string, s: { state: string; context: string; description: string }) {
if (hold) await hold;
if (failNext > 0) {
failNext--;
throw new Error("the forge answered 502");
}
kept[s.context] = { state: s.state, description: s.description, updated_at: new Date().toISOString() };
written.push(`${s.state} ${s.description}`);
},
};
}
// **A recheck's pending goes through the one writer** (novox/hq issue 456).
const recheckAt = new Date("2026-10-11T01:30:00Z");
const checkingAgain = { state: "pending" as const, context: "mesh/merge-gate", description: "checking again: main moved on" };
const gateOf = (forge: ReturnType<typeof aForge>) =>
`${forge.kept["mesh/merge-gate"].state} ${forge.kept["mesh/merge-gate"].description}`;
test("a repository as the mesh clones it is told from another", async () => {
const { clonedAs } = await import("../gate.ts");
assert.equal(clonedAs("http://127.0.0.1:20000/novox/hq.git", "novox", "hq"), true);
assert.equal(clonedAs("http://127.0.0.1:20000/novox/mesh-hq.git", "novox", "hq"), false);
assert.equal(clonedAs("http://127.0.0.1:20000/novox/mesh-controller.git", "novox", "hq"), false);
});
test("a recheck the forge does not take fails its caller, and the next write still takes its turn", async () => {
const { GateWriter } = await import("../gate.ts");
const forge = aForge();
const gates = new GateWriter(forge, () => recheckAt);
await gates.pending("novox", "hq", SHA);
forge.failWrites();
await assert.rejects(gates.status("novox", "hq", SHA, checkingAgain));
await gates.status("novox", "hq", SHA, checkingAgain);
assert.equal(gateOf(forge), "pending checking again: main moved on");
});
+14 -74
View File
@@ -431,70 +431,20 @@ test("the two new tools are named for what mesh_search is asked, and gitea_api s
assert.ok("refused" in judgeApiCall("PATCH", "/repos/a/b/pulls/7", { base: "x" }));
});
// **merge-pull judges the head it is asked at and no check** (design 47 *The seat git*, §314): merge-pull merges the
// head it is named into a base that takes no push, whatever its statuses say, and an id said again after the merge is
// answered performed.
test("merge-pull merges the head the caller names, and refuses one at whose fingerprint a required step failed", async () => {
// The seat git's pull and status (design 47 *The seat git*): an open pull request answers what the forge would merge now,
// and two writes of one head's status land in order. merge-pull is the merge call's (merge-call.test.ts).
test("the seat's pull answers what the forge would merge now, and its status is set on the commit", async () => {
const { seatTools } = await import("../dist/seat.js");
const { runAs } = await import("@novox/mesh-sdk/callers");
const bridge = "ace.mesh-delivery-forge-bridge";
let registered = true;
let failedStep: { run: string; module: string; step: string; fingerprint: string } | null = null;
// The head's one writer of its statuses (gate.ts), over a forge whose first write is still in flight when the next is asked.
const { GateWriter } = await import("../dist/gate.js");
// The seat's status is set through the forge's client directly (design 47 H §764; H-A-100): no chain of a head's writes.
const landed: string[] = [];
let inFlight: Promise<void> | null = null, land = () => {};
const slow = {
headChecks: async () => ({}),
setCommitStatus: async (_o: string, _r: string, _sha: string, s: { state: string; description: string }) => {
if (inFlight) { const w = inFlight; inFlight = null; await w; }
landed.push(`${s.state} ${s.description}`);
},
};
const gates = new GateWriter(slow);
const seat = seatTools(Object.assign(Object.create(client), { setCommitStatus: slow.setCommitStatus }),
{ run: async () => ({ stdout: "", code: 0 }), container: "gitea", statuses: gates, registered: () => registered, judge: async () => failedStep });
const seat = seatTools(Object.assign(Object.create(client), {
setCommitStatus: async (_o: string, _r: string, _sha: string, s: { state: string; description: string }) => { landed.push(`${s.state} ${s.description}`); },
}), { run: async () => ({ stdout: "", code: 0 }), container: "gitea", registered: () => true, judge: async () => null,
watched: () => new Map() });
const call = (verb: string, args: Record<string, unknown>, caller = bridge) =>
runAs({ "mesh/caller": caller }, args, () => seat.find((t: any) => t.name === `git.${verb}`)!.run(args)) as Promise<any>;
const merge = (extra: Record<string, unknown> = {}, caller?: string) =>
call("merge-pull", { id: "act-1", repository: "novox/mesh-catalog", number: 7, head: REVIEWED, ...extra }, caller);
const rows: { name: string; set: () => void; caller?: string; extra?: Record<string, unknown>; want: RegExp | "merged" | "held"; loud?: boolean; kind?: string }[] = [
{ name: "no registration written yet", set: () => { registered = false; }, want: /no module is registered yet/, kind: "no-registrations" },
{ name: "a head that moved", set: () => { state.head = MOVED; }, want: /its head is 3c4d5e6f7a8b, not the abc1234def56/, kind: "head-moved" },
{ name: "a base no rule guards", set: () => { state.rules = []; }, want: /guarded by no protection rule/, kind: "unprotected" },
{ name: "a base whose protection was removed after the last branch-moved", set: () => { state.rules = [protectedMain()]; state.rules = []; }, want: /guarded by no protection rule/, kind: "unprotected" },
{ name: "a base that takes a push", set: () => { state.rules = [{ rule_name: "main", enable_push: true }]; }, want: /guarded by no protection rule/, kind: "unprotected" },
{ name: "a required step failed at the head's fingerprint", set: () => { failedStep = { run: "main.7.nats", module: "nats", step: "unit", fingerprint: "fp-1" }; },
want: /the unit step of nats failed in run main\.7\.nats/, kind: "policy-failed" },
{ name: "a failed check", set: () => { state.statuses = [{ context: "mesh/check", state: "failure", description: "fail" }]; }, want: "merged" },
{ name: "no status at all", set: () => { state.statuses = []; }, want: "merged" },
{ name: "a check of another trunk", set: () => { state.statuses = judgedAt(MOVED); }, want: "merged" },
{ name: "the id said again after the merge", set: () => { state.merged = true; }, want: "held" },
{ name: "a pull request merged at another head", set: () => { state.merged = true; state.head = MOVED; }, want: /merged at 3c4d5e6f7a8b, not the abc1234def56/ },
{ name: "a closed pull request", set: () => { state.prState = "closed"; }, want: /it is closed/, kind: "git-refused" },
{ name: "a fast-forward", set: () => { state.parents = [REVIEWED]; }, want: "merged" },
{ name: "the merge read back fails", set: () => { state.commitsFail = 502; }, want: "merged" },
{ name: "the forge merged another head", set: () => { state.landed = MOVED; }, want: /WAS merged .*the forge merged 3c4d5e6f7a8b, not the abc1234def56/, loud: true },
];
for (const r of rows) {
registered = true; failedStep = null; state.merged = false; state.head = REVIEWED; state.statuses = judgedAt(TRUNK); state.sent = [];
state.rules = [protectedMain()]; state.prState = "open"; state.parents = null; state.commitsFail = 0; state.landed = "";
r.set();
const got = await merge(r.extra, r.caller);
if (r.want === "merged") {
assert.equal(got.performed, true, `${r.name}: ${JSON.stringify(got)}`);
assert.equal(got["merge-commit"], state.mergeCommit, r.name);
assert.equal(state.sent.find((s) => s.path.endsWith("/pulls/7/merge"))?.body.head_commit_id, REVIEWED, r.name);
} else if (r.want === "held") {
assert.deepEqual([got.performed, got.held], [true, true], r.name);
assert.deepEqual(writes(), [], `${r.name}: nothing merged again`);
} else {
assert.match(String(got.refused ?? got.error), r.want, r.name);
if (r.kind) assert.equal(got["refused-kind"], r.kind, r.name);
if (r.kind === "policy-failed") assert.deepEqual([got.run, got.module, got.step], ["main.7.nats", "nats", "unit"], r.name);
assert.deepEqual(writes(), r.loud ? ["POST /repos/novox/mesh-catalog/pulls/7/merge"] : [], `${r.name}: what was merged`);
}
}
// A read: an open pull request answers what the forge would merge now; a forge that fails is the kind failed.
state.merged = false; state.head = REVIEWED; state.rules = [protectedMain()];
const pull = await call("pull", { repository: "novox/mesh-catalog", number: 7 });
@@ -507,17 +457,9 @@ test("merge-pull merges the head the caller names, and refuses one at whose fing
assert.deepEqual([open.pull?.head, open.pull?.state, open.merging?.protected, open.merging?.required],
[REVIEWED, "open", true, ["mesh/merge-gate", "mesh/repo-check"]], JSON.stringify(open));
assert.equal("body" in (open.pull ?? {}), false, "never its description");
// Two writes of one head out of order (issue 456): a recheck's pending still in flight when the verdict is set through the
// seat; the verdict takes its turn after it and is what the head carries.
inFlight = new Promise<void>((r) => (land = r));
const recheck = gates.pending("novox", "mesh-catalog", REVIEWED);
const verdict = call("status", { id: "act-s", repository: "novox/mesh-catalog", commit: REVIEWED, state: "success",
context: "mesh/merge-gate", description: "passed" });
await new Promise((r) => setImmediate(r));
land();
await recheck;
assert.equal((await verdict).performed, true);
assert.equal(landed.at(-1), "success passed", `the verdict lands last: ${JSON.stringify(landed)}`);
const verdict = await call("status", { id: "act-s", repository: "novox/mesh-catalog", commit: REVIEWED, state: "success",
context: "mesh/check", description: "passed" });
assert.deepEqual([verdict.performed, landed], [true, ["success passed"]]);
// A pull request the forge does not have is the kind not-found, so a caller never reads it out of the words.
const gone = await call("pull", { repository: "novox/mesh-catalog", number: 404 });
assert.deepEqual([gone.pull, gone["error-kind"]], [undefined, "not-found"], JSON.stringify(gone));
@@ -552,10 +494,10 @@ test("every read and act of the seat git answers its contract, and an error is a
};
const run = async (_f: string, args: string[]) => args.includes("show") || args.includes("--ref") && !args.includes("append")
? { stdout: noteShown, code: noteShown ? 0 : 1 } : (noteWritten++, { stdout: "", code: 0 });
const seat = seatTools(forge as any, { run: run as any, container: "gitea", statuses: { status: async () => {} }, registered: () => true, judge: async () => null });
const seat = seatTools(forge as any, { run: run as any, container: "gitea", registered: () => true, judge: async () => null, watched: () => new Map() });
const call = (verb: string, args: Record<string, unknown>, over: Record<string, unknown> = {}) => {
const t = seat.find((x: any) => x.name === `git.${verb}`)!;
const wrapped = seatTools(Object.assign(Object.create(forge), over) as any, { run: run as any, container: "gitea", statuses: { status: async () => {} }, registered: () => true, judge: async () => null });
const wrapped = seatTools(Object.assign(Object.create(forge), over) as any, { run: run as any, container: "gitea", registered: () => true, judge: async () => null, watched: () => new Map() });
return runAs({ "mesh/caller": "ace.x" }, args, () => wrapped.find((x: any) => x.name === t.name)!.run(args)) as Promise<any>;
};
const rows: [string, string, Record<string, unknown>, Record<string, unknown>, (a: any) => unknown, unknown][] = [
@@ -563,9 +505,7 @@ test("every read and act of the seat git answers its contract, and an error is a
["pull", "by merge commit", { repository: "novox/app", "merge-commit": OTHER }, {}, (a) => [a.pull.state, a.pull["merge-commit"], a.merging], ["merged", OTHER, undefined]],
["pull", "unknown", { repository: "novox/app", number: 404 }, {}, (a) => [a.pull, a["error-kind"]], [undefined, "not-found"]],
["pull", "forge down", { repository: "novox/app", number: 9 }, { getPullRequest: down }, (a) => [a.pull, a["error-kind"]], [undefined, "failed"]],
["branch", "a branch a rule guards", { repository: "novox/app", branch: "main" }, { branchHead: async () => SHA, appliedProtection: async () => ({ rule_name: "main", enable_push: false }) }, (a) => [a.head, a.protected], [SHA, true]],
["branch", "a branch no rule guards", { repository: "novox/app", branch: "scratch" }, { branchHead: async () => SHA, appliedProtection: async () => null }, (a) => [a.head, a.protected], [SHA, false]],
["branch", "a rule that takes a push", { repository: "novox/app", branch: "main" }, { branchHead: async () => SHA, appliedProtection: async () => ({ rule_name: "main", enable_push: true }) }, (a) => [a.protected], [false]],
["branch", "a branch's head, no protection read (ADR 0682 §13)", { repository: "novox/app", branch: "main" }, { branchHead: async () => SHA, appliedProtection: async () => { throw new Error("read"); } }, (a) => [a.head, a.protected, a.error], [SHA, undefined, undefined]],
["branch", "no such branch", { repository: "novox/app", branch: "nope" }, { branchHead: gone }, (a) => [a.head, a["error-kind"]], [undefined, "not-found"]],
["open-pulls", "one", {}, {}, (a) => [a.pulls.length, a.pulls[0].required], [1, ["mesh/check"]]],
["open-pulls", "forge down", {}, { openPulls: down }, (a) => [a.pulls, a["error-kind"]], [undefined, "failed"]],
+2 -2
View File
@@ -16,8 +16,8 @@ test("the states the module announces are the states its manifest declares", asy
test("the announcement has the layout mesh-sdk's go/announce reads: version 1, the module, the node, the states sorted by name", async () => {
const { statesAnnouncement } = await import("../kept.ts");
assert.deepEqual(statesAnnouncement("gitea", "ace"), { v: 1, module: "gitea", node: "ace", states: [{ name: "announced" }, { name: "bound", readable: true }, { name: "failed-steps" }, { name: "findings", readable: true }, { name: "first-views" }, { name: "idle" }, { name: "transfers" }] });
assert.deepEqual(statesAnnouncement("gitea", undefined), { v: 1, module: "gitea", states: [{ name: "announced" }, { name: "bound", readable: true }, { name: "failed-steps" }, { name: "findings", readable: true }, { name: "first-views" }, { name: "idle" }, { name: "transfers" }] });
assert.deepEqual(statesAnnouncement("gitea", "ace"), { v: 1, module: "gitea", node: "ace", states: [{ name: "announced" }, { name: "bound", readable: true }, { name: "calls" }, { name: "failed-steps" }, { name: "findings", readable: true }, { name: "first-views" }, { name: "idle" }, { name: "transfers" }] });
assert.deepEqual(statesAnnouncement("gitea", undefined), { v: 1, module: "gitea", states: [{ name: "announced" }, { name: "bound", readable: true }, { name: "calls" }, { name: "failed-steps" }, { name: "findings", readable: true }, { name: "first-views" }, { name: "idle" }, { name: "transfers" }] });
});
test("index.ts says the announcement as the event `states` before the tools are served", () => {
+10 -21
View File
@@ -2,11 +2,11 @@
// writes nothing at the forge, true puts main's rule right as before.
import { test } from "node:test";
import assert from "node:assert/strict";
import { mkdtempSync, writeFileSync } from "node:fs";
import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { keepMainRules, mainRulesStep, LEFT_AS_SET } from "../dist/mainrules.js";
import { keepMainRules } from "../dist/mainrules.js";
function env(body?: string): NodeJS.ProcessEnv {
if (body === undefined) return {};
@@ -15,6 +15,14 @@ function env(body?: string): NodeJS.ProcessEnv {
return { MESH_GITEA_CONFIG_FILE: f };
}
// No timer keeps main's rules (design 47 H §764, H-A-100): the setting's description says when it acts, and names none.
test("the setting's description names no timer", () => {
const manifest = JSON.parse(readFileSync(new URL("../module.json", import.meta.url), "utf8"));
const said: string = manifest.config["keep-main-rules"].description;
assert.match(said, /token is minted/);
assert.doesNotMatch(said, /every ten minutes|every \w+ minutes/);
});
test("the setting is false unless the config says true", () => {
assert.equal(keepMainRules(env()), false);
assert.equal(keepMainRules(env("{}")), false);
@@ -23,25 +31,6 @@ test("the setting is false unless the config says true", () => {
assert.equal(keepMainRules(env('{"keep-main-rules":true}')), true);
});
test("false: the step never writes and says once that the rules are left", async () => {
let writes = 0;
const said: string[] = [];
const step = mainRulesStep(false, async () => { writes++; return ["a"]; }, (l) => said.push(l));
await step(); await step(); await step();
assert.equal(writes, 0);
assert.deepEqual(said, [LEFT_AS_SET]);
assert.match(LEFT_AS_SET, /main's rules are left as set at the forge \(keep-main-rules is false\)/);
});
test("true: every step puts the rules right", async () => {
let writes = 0;
const said: string[] = [];
const step = mainRulesStep(true, async () => { writes++; return ["a", "b"]; }, (l) => said.push(l));
await step(); await step();
assert.equal(writes, 2);
assert.deepEqual(said, ["[gitea] main's rule is right in 2 repositories"]);
});
test("a token mint's account setup writes no protection while keep-main-rules is false, and does when true", async () => {
const { setUpToolsAccount } = await import("../dist/tools-account.js");
for (const [keep, want] of [[false, 0], [true, 1]] as const) {
+11
View File
@@ -0,0 +1,11 @@
// A state of the runtime in memory, for the tests of the merge calls (calls.ts, partials.ts).
export function memory() {
const kv = new Map<string, unknown>();
return { kv, st: {
get: async (k: string) => (kv.has(k) ? { key: k, value: structuredClone(kv.get(k)), revision: 1 } : null),
put: async (k: string, v: unknown) => { kv.set(k, structuredClone(v)); return 1; },
delete: async (k: string) => { kv.delete(k); },
keys: async () => [...kv.keys()].sort(),
watch: async () => {},
} };
}
+106
View File
@@ -0,0 +1,106 @@
import assert from "node:assert/strict";
import { test } from "node:test";
// **One merge call, every member judged before any is merged** (novox/hq design 47 H §734, §735; ADR 0682 §13; H-A-21,
// H-A-22, H-A-47): the seat git's merge-pull takes pulls and by, 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 them in the order named, and answers the call and each member's outcome once.
const A = "a".repeat(40), B = "b".repeat(40), MOVED = "c".repeat(40);
const CALL = "0123456789abcdef";
interface FakePull { base: string; head: string; state: string; merged: boolean; merge?: string; refuse?: string }
/** A forge of pull requests by `<repository>#<number>`, recording each merge asked. It has no protection API: a call that
* read a branch's protection would throw. */
function forge(pulls: Record<string, FakePull>) {
const merges: string[] = [];
const key = (o: string, r: string, n: number) => `${o}/${r}#${n}`;
return {
merges,
getPullRequest: async (o: string, r: string, n: number) => {
const p = pulls[key(o, r, n)];
if (!p) throw new Error(`Gitea API GET /repos/${o}/${r}/pulls/${n}: 404 {}`);
return { number: n, title: "", state: p.state, merged: p.merged, base: p.base, head: "b", head_sha: p.head,
...(p.merged ? { merge_commit_sha: p.merge ?? "m".repeat(40) } : {}) } as any;
},
mergePullRequest: async (o: string, r: string, n: number, _m: string, _d: boolean, head: string) => {
const p = pulls[key(o, r, n)];
merges.push(key(o, r, n));
if (p.refuse) throw new Error(`Gitea API POST /repos/${o}/${r}/pulls/${n}/merge: 409 ${p.refuse}`);
assert.equal(head, p.head);
p.merged = true;
p.merge = `${n}`.repeat(40).slice(0, 40);
},
commitParents: async (_o: string, _r: string, sha: string) => [sha, "x"],
};
}
const watched = new Map([["novox/app", new Set(["main"])], ["novox/lib", new Set(["main"])]]);
async function call(f: ReturnType<typeof forge>, args: Record<string, unknown>, over: Record<string, unknown> = {}, caller = "person.jochen") {
const { mergeCall } = await import("../dist/mergecall.js");
const { runAs } = await import("@novox/mesh-sdk/callers");
const deps = { registered: () => true, watched: () => watched, judge: async () => null, newCall: () => CALL, ...over };
return runAs({ "mesh/caller": caller }, args, () => mergeCall(f as any, args, deps as any)) as Promise<any>;
}
const two = { by: "lead@shanks", pulls: [{ repository: "novox/app", number: 5, head: A }, { repository: "novox/lib", number: 9, head: B }] };
const open = (): Record<string, FakePull> => ({ "novox/app#5": { base: "main", head: A, state: "open", merged: false },
"novox/lib#9": { base: "main", head: B, state: "open", merged: false } });
test("a merge call merges its members in the order named and answers each with its merge commit; one pull request is a list of one", async () => {
const f = forge(open());
const got = await call(f, two);
assert.equal(got.call, CALL);
assert.deepEqual(f.merges, ["novox/app#5", "novox/lib#9"]);
assert.deepEqual(got.members.map((m: any) => [m.repository, m.number, m.state, m.commit]),
[["novox/app", 5, "merged", "5".repeat(40)], ["novox/lib", 9, "merged", "9".repeat(40)]]);
const one = forge(open());
const single = await call(one, { by: "lead@shanks", pulls: [two.pulls[0]] });
assert.deepEqual([one.merges, single.members.length, single.members[0].state], [["novox/app#5"], 1, "merged"]);
});
test("a member refused at judging merges none and names every refused member and why", async () => {
const rows: { name: string; set: (p: Record<string, FakePull>) => void; over?: Record<string, unknown>; why: RegExp }[] = [
{ name: "the second member's head moved", set: (p) => { p["novox/lib#9"].head = MOVED; }, why: /head-moved: its head is cccccccccccc, not the bbbbbbbbbbbb/ },
{ name: "already merged", set: (p) => { Object.assign(p["novox/lib#9"], { merged: true, merge: "e".repeat(40) }); }, why: /already-merged: .* as e{40}/ },
{ name: "closed", set: (p) => { p["novox/lib#9"].state = "closed"; }, why: /is closed/ },
{ name: "a base no registration watches", set: (p) => { p["novox/lib#9"].base = "feat/x"; }, why: /its base feat\/x is no watched branch/ },
{ name: "a required step failed at its head's fingerprint",
set: () => {}, over: { judge: async (h: string) => (h === B ? { run: "main.7", module: "lib", step: "unit", fingerprint: "fp" } : null) },
why: /the unit step of lib failed in run main\.7 at its build-input fingerprint fp/ },
];
for (const r of rows) {
const pulls = open();
r.set(pulls);
const f = forge(pulls);
const got = await call(f, two, r.over);
assert.deepEqual(f.merges, [], `${r.name}: nothing merged`);
assert.equal(got.members[0].state, "judged", r.name);
assert.equal(got.members[1].state, "refused", r.name);
assert.match(got.members[1].why, r.why, r.name);
}
});
test("a call is refused whole with no proved caller, no by, no registration or no pull request", async () => {
const f = forge(open());
await assert.rejects(call(f, two, {}, ""), /proved no caller account/);
await assert.rejects(call(f, { pulls: two.pulls }), /by is the caller as who@node/);
await assert.rejects(call(f, two, { registered: () => false }), /no module is registered yet/);
await assert.rejects(call(f, { by: "lead@shanks", pulls: [] }), /one or more members/);
await assert.rejects(call(f, { by: "lead@shanks", pulls: [two.pulls[0], two.pulls[0]] }), /named twice/);
assert.deepEqual(f.merges, []);
});
test("the forge refusing a member after every member was judged stops the call: the landed member merged, the rest refused", async () => {
const pulls = open();
pulls["novox/lib#9"].refuse = "merge conflict";
const three = { by: "lead@shanks", pulls: [...two.pulls, { repository: "novox/app", number: 6, head: A }] };
pulls["novox/app#6"] = { base: "main", head: A, state: "open", merged: false };
const f = forge(pulls);
const got = await call(f, three);
assert.deepEqual(f.merges, ["novox/app#5", "novox/lib#9"], "the third is never asked");
assert.deepEqual(got.members.map((m: any) => m.state), ["merged", "refused", "refused"]);
assert.match(got.members[1].why, /the forge refused the merge: .*merge conflict/);
});
+67
View File
@@ -0,0 +1,67 @@
import assert from "node:assert/strict";
import { test } from "node:test";
import { memory } from "./memstate.ts";
// **A member refused after every member was judged is said and raised** (novox/hq design 47 H §767; acceptance test 115;
// H-A-81): a forge that refuses the second merge gives one merge-called with the first member and `refused`, and
// merge-partial (scope delivery, id the call, urgent, resolver operator) raised; a later call landing the refused member
// clears it, and forge_partial_clear clears one by hand after the hand-act log took it.
const A = "a".repeat(40), B = "b".repeat(40);
test("the forge refusing the second merge says what landed, raises merge-partial, and a later call landing it clears it", async () => {
const { mergeCall } = await import("../dist/mergecall.js");
const { Calls } = await import("../dist/calls.js");
const { Partials, partialKey } = await import("../dist/partials.js");
const { callTools } = await import("../dist/tools/calls.js");
const { runAs } = await import("@novox/mesh-sdk/callers");
const { st } = memory();
const findings = memory();
const calls = new Calls(st as any);
const partials = new Partials(findings.st as any, calls);
const said: any[] = [];
const pulls: Record<number, any> = { 5: { head: A, merged: false, refuse: false }, 9: { head: B, merged: false, refuse: true } };
const forge = {
getPullRequest: async (_o: string, _r: string, n: number) => ({ number: n, state: "open", merged: pulls[n].merged, base: "main",
head_sha: pulls[n].head, ...(pulls[n].merged ? { merge_commit_sha: String(n).repeat(40) } : {}) }),
mergePullRequest: async (_o: string, r: string, n: number) => {
if (pulls[n].refuse) throw new Error(`Gitea API POST /repos/novox/${r}/pulls/${n}/merge: 409 merge conflict`);
pulls[n].merged = true;
},
commitParents: async () => [],
};
let clock = Date.parse("2026-11-20T03:00:00Z");
const run = (call: string, numbers: number[]) => {
const args = { by: "lead@shanks", pulls: numbers.map((n) => ({ repository: n === 5 ? "novox/app" : "novox/lib", number: n, head: pulls[n].head })) };
return runAs({ "mesh/caller": "shanks.claude-code" }, args, () => mergeCall(forge as any, args, { registered: () => true,
watched: () => new Map([["novox/app", new Set(["main"])], ["novox/lib", new Set(["main"])]]), judge: async () => null,
newCall: () => call, calls, partials, say: async (_s: string, body: unknown) => { said.push(body); },
now: () => new Date((clock += 1000)) } as any)) as Promise<any>;
};
const got = await run("00000000000000aa", [5, 9]);
assert.deepEqual(got.members.map((m: any) => m.state), ["merged", "refused"]);
assert.equal(said.length, 1);
assert.deepEqual(said[0].members.map((m: any) => m.number), [5]);
assert.deepEqual(said[0].refused.map((m: any) => [m.repository, m.number]), [["novox/lib", 9]]);
assert.match(said[0].refused[0].why, /merge conflict/);
const raised: any = findings.kv.get(partialKey("00000000000000aa"));
assert.deepEqual([raised?.kind, raised?.subject, raised?.severity, raised?.resolver], ["merge-partial", { scope: "delivery", id: "00000000000000aa" }, "urgent", "operator"]);
assert.match(raised.summary, /landed novox\/app#5 and not novox\/lib#9/);
// A later call landing the refused member clears it.
pulls[9].refuse = false;
await run("00000000000000bb", [9]);
assert.equal(findings.kv.has(partialKey("00000000000000aa")), false, "cleared by the later call");
// By hand: written in the hand-act log first, then cleared.
pulls[9] = { head: B, merged: false, refuse: true };
pulls[5] = { head: A, merged: false, refuse: false };
await run("00000000000000cc", [5, 9]);
assert.equal(findings.kv.has(partialKey("00000000000000cc")), true);
const acts: any[] = [];
const tool = callTools(calls, partials, async () => {}, async (a) => { acts.push(a); }).find((t) => t.name === "forge_partial_clear")!;
await assert.rejects(tool.run({ call: "00000000000000cc" }), /names the call .* and why/);
const failing = callTools(calls, partials, async () => {}, async () => { throw new Error("down"); }).find((t) => t.name === "forge_partial_clear")!;
await assert.rejects(failing.run({ call: "00000000000000cc", why: "dropped" }), /not recorded, so nothing was cleared/);
assert.equal(findings.kv.has(partialKey("00000000000000cc")), true);
const done: any = await runAs({ "mesh/caller": "person.jochen" }, {}, () => tool.run({ call: "00000000000000cc", why: "the lib change is dropped" }));
assert.deepEqual([done.cleared, acts[0].verb, findings.kv.has(partialKey("00000000000000cc"))], [true, "forge_partial_clear", false]);
});
-27
View File
@@ -41,33 +41,6 @@ async function serve(count: number, heads: Record<number, string>) {
return { client, ...f };
}
test("a new head beyond the newest 20 open pull requests is announced, exactly once", async () => {
const { headsToAnnounce } = await import("../pulls.ts");
// 25 open, every head announced before; #3 — the 23rd most recently updated — got a new head.
const announced: Record<string, string> = {};
for (let n = 1; n <= 25; n++) announced[`novox/hq#${n}@main`] = sha(n, "a");
const { client, server, asked } = await serve(25, { 3: sha(3, "b") });
try {
// The fault: the newest 20 alone do not hold it.
const newest = await client.listPullRequests("novox", "hq", { state: "open", sort: "recentupdate", limit: "20" });
assert.deepEqual(headsToAnnounce("novox/hq", newest, announced), [], "the newest 20 miss #3's new head");
asked.length = 0;
const said: string[] = [];
for (let pass = 0; pass < 2; pass++) {
// The sweep, as index.ts's pollPulls asks: no floor, every page.
const open = await client.listOpenPullsSince("novox", "hq", "");
for (const p of headsToAnnounce("novox/hq", open, announced)) {
said.push(`#${p.number}@${p.head_sha}`);
announced[`novox/hq#${p.number}@${p.base}`] = String(p.head_sha);
}
}
assert.deepEqual(said, [`#3@${sha(3, "b")}`], "the new head past the newest 20, announced once over two passes");
assert.ok(asked.every((q) => q.get("state") === "open" && q.get("sort") === "recentupdate"), "asked newest first");
} finally {
server.close();
}
});
test("a pass pages until it reaches back past its floor, and no further", async () => {
// 130 open pull requests, #n updated n hours after T0: page 1 holds #130–#81, page 2 #80–#31, page 3 #30–#1.
const { client, server, asked } = await serve(130, {});
+1 -58
View File
@@ -2,32 +2,7 @@ import assert from "node:assert/strict";
import { test } from "node:test";
import { createServer } from "node:http";
// A pull request's merge check (novox/hq to-be 45 §9): each new head announced once, and the verdict set
// where the pull request shows it — an error never as a success.
test("each open pull request's new head is announced once, and nothing closed or merged", async () => {
const { headsToAnnounce } = await import("../pulls.ts");
const pulls = [
{ number: 1, title: "a", state: "open", merged: false, head_sha: "aaa", base: "main", html_url: "" },
{ number: 2, title: "b", state: "open", merged: false, head_sha: "bbb", html_url: "" },
{ number: 3, title: "c", state: "closed", merged: true, head_sha: "ccc", html_url: "" },
{ number: 4, title: "d", state: "open", merged: false, html_url: "" },
];
const announced = { "novox/mesh-catalog#1@main": "aaa", "novox/mesh-catalog#2@": "old" };
assert.deepEqual(headsToAnnounce("novox/mesh-catalog", pulls, announced).map((p) => p.number), [2],
"only a head not announced, of a pull request that is open");
});
test("a pull request retargeted keeps its head and is announced again, into its new base (de-spiegel #6)", async () => {
const { headsToAnnounce, headKey } = await import("../pulls.ts");
const was = { number: 6, title: "a", state: "open", merged: false, head_sha: "aaa", base: "old-trunk", html_url: "" };
const announced: Record<string, string> = { [headKey("novox/de-spiegel", 6, "old-trunk")]: "aaa" };
assert.deepEqual(headsToAnnounce("novox/de-spiegel", [was], announced), [], "the same head into the same base is announced once");
const retargeted = { ...was, base: "main" };
assert.deepEqual(headsToAnnounce("novox/de-spiegel", [retargeted], announced).map((p) => p.number), [6],
"the same head into a new base is judged afresh");
assert.notEqual(headKey("novox/de-spiegel", 6, "main"), headKey("novox/de-spiegel", 6, "old-trunk"));
});
// A commit status, set where the pull request shows it (the seat git's status).
test("a commit status is set on the commit, under the merge check's context", async () => {
const { GiteaClient } = await import("../client.ts");
@@ -53,35 +28,3 @@ test("a commit status is set on the commit, under the merge check's context", as
assert.equal(seen!.body.state, "failure");
assert.equal(seen!.body.context, "mesh/merge-gate");
});
// **A pending check says where it is** (novox/hq issue 446): announced, it waits in the build queue, since the time the
// operator reads — not "mapping this head onto its module graph" for the ten minutes of a controller check.
test("a head announced is pending in the build queue, since the local time it was announced", async () => {
const { pendingWords } = await import("../pulls.ts");
assert.equal(pendingWords(new Date(2026, 9, 11, 3, 8, 50)), "waiting in the build queue since 03:08");
assert.equal(pendingWords(new Date(2026, 9, 11, 14, 0, 0)), "waiting in the build queue since 14:00");
});
// Issue 1301 (ADR 0503 §3, §5): gitea writes the controller's statuses only where the base still requires them. hq's main
// requires mesh/repo-check alone, so no mesh/merge-gate is written on its heads.
test("a base's required statuses decide which of the controller's statuses are written", async () => {
const { maintained, writesGate, CHECK_STATUS } = await import("../pulls.ts");
assert.equal(CHECK_STATUS, "mesh/check");
assert.deepEqual(maintained(undefined), ["mesh/merge-gate", "mesh/repo-check"], "a rule not read: as before");
assert.deepEqual(maintained(["mesh/repo-check"]), ["mesh/repo-check"]);
assert.deepEqual(maintained(["mesh/check", "other/x"]), []);
assert.deepEqual(maintained([]), []);
assert.equal(writesGate(undefined), true);
assert.equal(writesGate(["mesh/repo-check"]), false);
assert.equal(writesGate(["mesh/check"]), false);
assert.equal(writesGate(["mesh/merge-gate", "mesh/repo-check"]), true);
});
test("a rule the forge gives with no contexts (null) requires nothing, and an unread rule is unknown", async () => {
const { requiredOf } = await import("../pulls.ts");
// The forge's BranchProtection says status_check_contexts may be null (protection.ts); requiredOf takes it as it comes.
assert.deepEqual(requiredOf({ enable_status_check: true, status_check_contexts: null }), []);
assert.deepEqual(requiredOf({ enable_status_check: true, status_check_contexts: ["mesh/check", ""] }), ["mesh/check"]);
assert.deepEqual(requiredOf(null), []);
assert.equal(requiredOf(undefined), undefined);
});
-273
View File
@@ -1,273 +0,0 @@
// **A delivery group's member is judged beside its siblings, and a sibling's move puts that verdict out of date**
// (novox/hq ADR 0382 §4-§6, issue 867): the holder keeps the siblings each verdict names; a sibling's new head, close
// unmerged or base move (other than its own merge of the head that was read) sets both statuses of every member whose
// verdict names it back to pending, and runs nothing; a member merges only with its group passed and every sibling head
// read approved.
import { test } from "node:test";
import assert from "node:assert/strict";
import { mkdtempSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { approvedHeadsOf, besideWords, groupRefusal, keepSiblings, namesSiblings, readSiblings, siblingOutOfDate, siblingsFile,
siblingsOf, siblingStatuses, weighSiblings, type SiblingRecord } from "../dist/siblings.js";
import { weighTrunks } from "../dist/trunk.js";
const h = (c: string) => c.repeat(40);
const MEMBER_HEAD = h("a"), HOST_HEAD = h("b"), HOST_BASE = h("c"), HOST_NEW = h("d"), HOST_MOVED = h("e"), MERGE = h("f");
const sibling = { repository: "novox/mesh-host", number: 114, head: HOST_HEAD, base: "main", base_commit: HOST_BASE };
const verdict = { owner: "novox", repo: "mesh-controller", number: 346, commit: MEMBER_HEAD, verdict: "pass", summary: "x", id: "build-1",
trunk: h("1").slice(0, 12), siblings: [sibling], judge_from: "sibling novox/mesh-controller#346 merge 123456789abc",
gate: { verdict: "pass", summary: "every machine composes ".repeat(10) }, "repo-check": { verdict: "pass", summary: "ok" } };
test("the siblings a verdict names are kept per member, and read back from where the holder keeps its state", () => {
const file = siblingsFile(mkdtempSync(join(tmpdir(), "gitea-siblings-")));
const record: SiblingRecord = { "novox/mesh-controller#346": { head: MEMBER_HEAD, siblings: siblingsOf([sibling]) } };
keepSiblings(file, record);
assert.deepEqual(readSiblings(file), record, "kept where the holder keeps its state");
assert.deepEqual(readSiblings(null), {});
});
// --- a sibling's move -----------------------------------------------------------------------------------------
interface World {
host: { merged: boolean; state: string; head_sha: string; merge_commit_sha?: string };
hostBase: string;
parents: string[];
member: { head_sha: string; state: string; merged: boolean };
checks: Record<string, { state: string; description?: string }>;
written: { sha: string; context: string; state: string; description: string }[];
reads: string[];
}
const world = (): World => ({ host: { merged: false, state: "open", head_sha: HOST_HEAD }, hostBase: HOST_BASE, parents: [],
member: { head_sha: MEMBER_HEAD, state: "open", merged: false },
checks: { "mesh/merge-gate": { state: "success", description: "head aaaaaaaaaaaa merged into trunk 111111111111 beside mesh-host#114@bbbbbbbb — pass: x" },
"mesh/repo-check": { state: "success", description: "pass: y" } },
written: [], reads: [] });
const forgeOf = (w: World) => ({
async getPullRequest(owner: string, repo: string, n: number) {
w.reads.push(`${owner}/${repo}#${n}`);
return repo === "mesh-host" ? { number: n, title: "", html_url: "", ...w.host } : { number: n, title: "", html_url: "", merged: false, ...w.member };
},
async branchHead(_o: string, _r: string, _b: string) { return w.hostBase; },
async commitParents() { return w.parents; },
});
const gatesOf = (w: World) => ({
async outOfDate(_o: string, _r: string, sha: string, decide: (c: any) => any[] | Promise<any[]>) {
const put = await decide(w.checks);
for (const s of put) { w.written.push({ sha, ...s }); w.checks[s.context] = { state: s.state, description: s.description }; }
return put;
},
});
const recordOf = (): SiblingRecord => ({ "novox/mesh-controller#346": { head: MEMBER_HEAD, siblings: siblingsOf([sibling]) } });
const weigh = (w: World, record: SiblingRecord, repository = "novox/mesh-host", number?: number) =>
weighSiblings(forgeOf(w) as any, gatesOf(w) as any, record, repository, number);
test("a sibling's new head puts both statuses of the member back to pending, with the reason, and runs nothing", async () => {
const w = world();
w.host.head_sha = HOST_NEW;
await weigh(w, recordOf(), "novox/mesh-host", 114);
assert.deepEqual(w.written.map((s) => [s.sha, s.context, s.state]),
[[MEMBER_HEAD, "mesh/merge-gate", "pending"], [MEMBER_HEAD, "mesh/repo-check", "pending"]]);
assert.equal(w.written[0].description,
"out of date: judged beside mesh-host#114 at bbbbbbbbbbbb, it is now at dddddddddddd; judged again on a recheck or when it is merged");
assert.ok(siblingOutOfDate(w.written[0].description));
// Already pending (out of date, or a check on its way): not written again.
w.written.length = 0;
await weigh(w, recordOf(), "novox/mesh-host", 114);
assert.deepEqual(w.written, []);
});
test("a sibling closed unmerged puts the member's verdict out of date", async () => {
const w = world();
w.host.state = "closed";
await weigh(w, recordOf(), "novox/mesh-host", 114);
assert.equal(w.written.length, 2);
assert.match(w.written[0].description, /^out of date: judged beside mesh-host#114 was closed unmerged/);
});
test("a move of the sibling's base puts it out of date, naming both commits", async () => {
const w = world();
w.hostBase = HOST_MOVED;
await weigh(w, recordOf());
assert.equal(w.written.length, 2);
assert.match(w.written[0].description, /mesh-host#114 merged onto cccccccccccc, its main is now eeeeeeeeeeee/);
});
test("the sibling's own merge of the head read onto the base read does not, in either order of the two merges", async () => {
// The sibling merges first (a merge commit of the base commit read and the head read).
const w = world();
Object.assign(w.host, { merged: true, state: "closed", merge_commit_sha: MERGE });
w.hostBase = MERGE;
w.parents = [HOST_BASE, HOST_HEAD];
const record = recordOf();
assert.equal(await weigh(w, record), true, "the record changes: the sibling is marked merged");
assert.deepEqual(w.written, []);
assert.equal(record["novox/mesh-controller#346"].siblings[0].merged, true);
// A move of that base afterwards is no sibling's move: the sibling is merged.
w.hostBase = HOST_MOVED;
await weigh(w, record);
assert.deepEqual(w.written, []);
// The member merges first: its own repository moves, which no member's verdict names as a sibling.
const m = world();
m.member.merged = true;
await weigh(m, recordOf(), "novox/mesh-controller");
assert.deepEqual(m.written, []);
// And the sibling then merges: still not a move.
Object.assign(m.host, { merged: true, state: "closed", merge_commit_sha: MERGE });
m.parents = [HOST_BASE, HOST_HEAD];
await weigh(m, recordOf());
assert.deepEqual(m.written, []);
// A squash is one parent: the base commit read.
const q = world();
Object.assign(q.host, { merged: true, state: "closed", merge_commit_sha: MERGE });
q.parents = [HOST_BASE];
await weigh(q, recordOf());
assert.deepEqual(q.written, []);
});
test("a merge of another head, or onto another base, is a move", async () => {
const other = world();
Object.assign(other.host, { merged: true, state: "closed", merge_commit_sha: MERGE, head_sha: HOST_NEW });
other.parents = [HOST_BASE, HOST_NEW];
await weigh(other, recordOf());
assert.equal(other.written.length, 2);
const onto = world();
Object.assign(onto.host, { merged: true, state: "closed", merge_commit_sha: MERGE });
onto.parents = [HOST_MOVED, HOST_HEAD];
await weigh(onto, recordOf());
assert.equal(onto.written.length, 2);
});
test("only the members whose verdict names the sibling are touched, and a member that moved on is dropped", async () => {
// Another sibling's move, or another repository's: nothing read, nothing written.
const w = world();
w.host.head_sha = HOST_NEW;
await weigh(w, recordOf(), "novox/mesh-lab");
await weigh(w, recordOf(), "novox/mesh-host", 999);
assert.deepEqual(w.written, []);
// A verdict that is none (a gate not yet judged) is left alone.
const none = world();
none.host.head_sha = HOST_NEW;
none.checks = {};
await weigh(none, recordOf());
assert.deepEqual(none.written, []);
// The member has a new head: its old verdict is no verdict; the record is dropped, nothing written to the old head.
const moved = world();
moved.host.head_sha = HOST_NEW;
moved.member.head_sha = h("9");
const record = recordOf();
assert.equal(await weigh(moved, record), true);
assert.deepEqual(moved.written, []);
assert.deepEqual(record, {});
// A repository without a repo-check gets no pending one a verdict would never set.
assert.deepEqual(siblingStatuses({ "mesh/merge-gate": { state: "success" } }, "x").map((s) => s.context), ["mesh/merge-gate"]);
});
test("a trunk that moved tells the siblings' weighing; one first seen does not", async () => {
const told: string[] = [];
const forge = { listOpenPulls: async () => [{ number: 1, title: "", state: "open", merged: false, head_sha: h("2"), base: "main", html_url: "" }],
branchHead: async () => h("3") };
const gates = { outOfDate: async () => [] };
const trunks: Record<string, string> = {};
await weighTrunks(forge as any, gates as any, trunks, "novox", "mesh-host", async (b) => { told.push(b); });
assert.deepEqual(told, [], "first seen");
trunks["novox/mesh-host:main"] = h("4");
await weighTrunks(forge as any, gates as any, trunks, "novox", "mesh-host", async (b) => { told.push(b); });
assert.deepEqual(told, ["main"]);
});
// --- the merge rule -------------------------------------------------------------------------------------------
test("the group rule names every missing thing: the group status at each head read, and each head the Approve does not cover", async () => {
const self = { owner: "novox", repo: "mesh-controller", number: 346, head: MEMBER_HEAD };
const statuses: Record<string, string> = {};
const forge = {
headChecks: async (_o: string, r: string, sha: string) => (statuses[`${r}@${sha}`] ? { "mesh/delivery-group": { state: statuses[`${r}@${sha}`] } } : {}),
};
const siblings = siblingsOf([sibling]);
const none = await groupRefusal(forge, self, siblings, undefined);
assert.match(none!, /mesh\/delivery-group is missing at mesh-controller#346@aaaaaaaaaaaa; mesh-controller#346@aaaaaaaaaaaa is covered by no Approve: the merge was handed no approved heads; mesh\/delivery-group is missing at mesh-host#114@bbbbbbbbbbbb; mesh-host#114@bbbbbbbbbbbb is covered by no Approve/);
statuses[`mesh-controller@${MEMBER_HEAD}`] = "success";
statuses[`mesh-host@${HOST_HEAD}`] = "pending";
const approved = approvedHeadsOf([`novox/mesh-controller@${MEMBER_HEAD}`])!;
assert.match((await groupRefusal(forge, self, siblings, approved))!, /^mesh\/delivery-group is pending at mesh-host#114@bbbbbbbbbbbb; mesh-host#114@bbbbbbbbbbbb is not among the heads the Approve covers$/);
statuses[`mesh-host@${HOST_HEAD}`] = "success";
assert.match((await groupRefusal(forge, self, siblings, approved))!, /^mesh-host#114@bbbbbbbbbbbb is not among the heads the Approve covers$/);
approved.set("novox/mesh-host", "c".repeat(40));
assert.match((await groupRefusal(forge, self, siblings, approved))!, /^mesh-host#114@bbbbbbbbbbbb is not the head the Approve covers \(cccccccccccc\)$/);
approved.set("novox/mesh-host", HOST_HEAD.toLowerCase());
assert.equal(await groupRefusal(forge, self, siblings, approved), undefined);
// A read that fails is named, never read as a pass.
const broken = { headChecks: async () => { throw new Error("the forge is away"); } };
assert.match((await groupRefusal(broken, self, siblings, approved))!, /could not be read \(the forge is away\)/);
assert.equal(besideWords(siblings), "beside mesh-host#114@bbbbbbbb");
});
test("a merged or closed member's entry is dropped, so a sibling's later push never re-pends its merged head", async () => {
// mesh-host#114 judged beside mesh-controller#346; #114 then merged; a push to #346 follows.
const w = world();
w.host.merged = true; // the member (mesh-host#114) is merged
w.member.head_sha = h("9"); // the sibling (mesh-controller#346) has a new head
const record: SiblingRecord = { "novox/mesh-host#114": { head: HOST_HEAD, siblings: siblingsOf([
{ repository: "novox/mesh-controller", number: 346, head: MEMBER_HEAD, base: "main", base_commit: h("2") }]) } };
assert.equal(await weigh(w, record, "novox/mesh-controller", 346), true);
assert.deepEqual(w.written, [], "the merged head is not put back to pending");
assert.deepEqual(record, {}, "and its entry is gone");
// On its own close or merge the member's entry goes too, whatever the siblings do.
const own = world();
own.host.state = "closed";
const kept = recordOf();
const mine: SiblingRecord = { "novox/mesh-host#114": { head: HOST_HEAD, siblings: kept["novox/mesh-controller#346"].siblings } };
assert.equal(await weigh(own, mine, "novox/mesh-host", 114), true);
assert.deepEqual(mine, {});
assert.deepEqual(own.written, []);
});
// --- the composed verdict names the siblings of each member (issue 1049) --------------------------------------
// Issue 1049: the 2026-10-17 23:48 group (mesh-controller #375 beside mesh-catalog #353). #375's own verdict named #353
// at its old head; #353 then got a new head, and the group's composed verdict passed for both new heads. The record still
// held the old head, so #353's own merge of the NEW head read as "merged otherwise than its head" and put #375's gate back
// to pending, and the group merged in two passes.
const composedMembers = () => [
{ owner: "novox", repo: "mesh-controller", number: 346, commit: MEMBER_HEAD, trunk: "111111111111", base: "main" },
{ owner: "novox", repo: "mesh-host", number: 114, commit: HOST_NEW, trunk: HOST_BASE.slice(0, 12), base: "main" },
];
/** The record a group's composed verdict once left: for each member, the other members at the heads and base commits it composed. */
const composedRecord = (members: ReturnType<typeof composedMembers>): SiblingRecord => Object.fromEntries(members.map((m) => [
`${m.owner}/${m.repo}#${m.number}`.toLowerCase(), { head: m.commit, siblings: members.filter((o) => o !== m).map((o) => ({
repository: `${o.owner}/${o.repo}`, number: o.number, head: o.commit, base: o.base, base_commit: o.trunk })) }]));
const staleRecord = (): SiblingRecord => ({ "novox/mesh-controller#346": { head: MEMBER_HEAD, siblings: siblingsOf([sibling]) } });
test("without the composed verdict's siblings, a sibling's own merge of its new head is a move (the pin of issue 1049)", async () => {
const w = world();
Object.assign(w.host, { merged: true, state: "closed", merge_commit_sha: MERGE, head_sha: HOST_NEW });
w.parents = [HOST_BASE, HOST_NEW];
await weigh(w, staleRecord());
assert.equal(w.written.length, 2, "the record names the old head: the merge reads as another head's");
});
test("a composed verdict names the siblings of each member at the heads and base commits it composed, so a sibling's own merge of its new head is no move (issue 1049)", async () => {
const record = composedRecord(composedMembers());
assert.deepEqual(record["novox/mesh-controller#346"], { head: MEMBER_HEAD,
siblings: [{ repository: "novox/mesh-host", number: 114, head: HOST_NEW, base: "main", base_commit: HOST_BASE.slice(0, 12) }] });
assert.deepEqual(record["novox/mesh-host#114"], { head: HOST_NEW,
siblings: [{ repository: "novox/mesh-controller", number: 346, head: MEMBER_HEAD, base: "main", base_commit: "111111111111" }] });
const w = world();
Object.assign(w.host, { merged: true, state: "closed", merge_commit_sha: MERGE, head_sha: HOST_NEW });
w.parents = [HOST_BASE, HOST_NEW];
await weigh(w, record);
assert.deepEqual(w.written, [], "its own merge of the head the composed check judged leaves the member's gate alone");
assert.equal(record["novox/mesh-controller#346"].siblings[0].merged, true);
// A merge of any other head, or onto any other base, is still a move.
const other = world();
const again = composedRecord(composedMembers());
Object.assign(other.host, { merged: true, state: "closed", merge_commit_sha: MERGE, head_sha: HOST_NEW });
other.parents = [HOST_MOVED, HOST_NEW];
await weigh(other, again);
assert.equal(other.written.length, 2);
});
+3 -3
View File
@@ -487,9 +487,9 @@ test("a glob rule covering main gives its approvals and override, not its status
assert.deepEqual(rule.merge_whitelist_usernames, [TOOLS_ACCOUNT]);
});
test("a start with the token kept still puts main's rules right: the module's start asks for it each time (issue 948, review round 1)", async () => {
const src = await readFile(new URL("../index.ts", import.meta.url), "utf8");
assert.match(src, /ensureMainMerges\("novox"\)/, "index.ts calls it outside the token's mint");
// The module's start no longer puts main's rules right every ten minutes (design 47 H §764; H-A-100): ensureMainMerges is
// the mint's alone.
test("ensureMainMerges makes a main rule gone again with no token minted", async () => {
const { GiteaAdmin } = await import("../dist/client.js");
const env = await environment();
forge.mainRules.delete("hq");
-167
View File
@@ -1,167 +0,0 @@
// **A merge check's verdict holds for the trunk commit it judged** (novox/hq ADR 0323, issue 341): both statuses name
// the head and the trunk commit; a trunk's move puts the merge check of every open pull request into that trunk — and
// of none into another — back to pending with the reason, and runs nothing; a verdict that lands judged against a trunk
// that has moved since is said out of date.
import { test } from "node:test";
import assert from "node:assert/strict";
import { checkOnItsWay, outOfDateStatuses, outOfDateWords, trunkNamed, verdictAtTrunk, weighTrunks } from "../dist/trunk.js";
import { GateWriter } from "../dist/gate.js";
const HEAD = "dfb1415aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
const TRUNK = "a2c2c35bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
const MOVED = "d28ca95ccccccccccccccccccccccccccccccccc";
test("a trunk's move puts an open head's merge check out of date, naming both commits, unless a check is on its way", () => {
const verdict = (trunk: string, state = "success") => ({
"mesh/merge-gate": { state, description: `head ${HEAD.slice(0, 12)} merged into trunk ${trunk.slice(0, 12)} — pass: x` },
"mesh/repo-check": { state, description: `head ${HEAD.slice(0, 12)} merged into trunk ${trunk.slice(0, 12)} — pass: y` } });
const put = outOfDateStatuses(verdict(TRUNK), MOVED);
assert.deepEqual(put.map((s) => [s.context, s.state]), [["mesh/merge-gate", "pending"], ["mesh/repo-check", "pending"]]);
assert.equal(put[0].description, "out of date: judged against trunk a2c2c35bbbbb, the trunk is now d28ca95ccccc; " +
"judged again on a recheck or when it is merged");
assert.equal(put[0].description, outOfDateWords(TRUNK, MOVED));
assert.equal(trunkNamed(put[0].description), "a2c2c35bbbbb", "an out-of-date status still names what it judged");
// A failure is out of date too: it judged another merge.
assert.equal(outOfDateStatuses(verdict(TRUNK, "failure"), MOVED).length, 2);
// Already judged against the trunk's head; a check on its way or already out of date; no check yet: left alone.
assert.deepEqual(outOfDateStatuses(verdict(MOVED), MOVED), []);
assert.deepEqual(outOfDateStatuses({ "mesh/merge-gate": { state: "pending", description: "building on ace since 14:02" } }, MOVED), []);
assert.deepEqual(outOfDateStatuses({ "mesh/merge-gate": { state: "pending", description: put[0].description } }, MOVED), []);
assert.deepEqual(outOfDateStatuses({}, MOVED), []);
// A head with no repository check of its own gets no pending one a verdict would never set.
assert.deepEqual(outOfDateStatuses({ "mesh/merge-gate": verdict(TRUNK)["mesh/merge-gate"] }, MOVED).map((s) => s.context),
["mesh/merge-gate"]);
// A verdict naming no trunk, of a build seat from before the rule, judged an earlier trunk.
assert.match(outOfDateStatuses({ "mesh/merge-gate": { state: "success", description: "pass: x" } }, MOVED)[0].description,
/judged against a trunk it does not name, the trunk is now d28ca95ccccc/);
assert.ok(checkOnItsWay({ state: "pending", description: "waiting in the build queue since 14:00" }));
assert.ok(checkOnItsWay({ state: "pending", description: "checking again: a person asked" }));
assert.ok(!checkOnItsWay({ state: "pending", description: put[0].description }));
assert.deepEqual(verdictAtTrunk(verdict(MOVED), MOVED), { current: true, onItsWay: false, judged: "d28ca95ccccc" });
assert.equal(verdictAtTrunk(verdict(TRUNK), MOVED).current, false);
});
/** A forge holding open pull requests into two branches, each head's statuses, and what was written. */
function aForge(pulls: { number: number; base: string; head: string }[], heads: Record<string, string>) {
const statuses = new Map<string, Record<string, { state: string; description?: string }>>();
const writes: string[] = [];
const verdict = (trunk: string) => ({
"mesh/merge-gate": { state: "success", description: `head x merged into trunk ${trunk.slice(0, 12)} — pass` },
"mesh/repo-check": { state: "success", description: `head x merged into trunk ${trunk.slice(0, 12)} — pass` } });
for (const p of pulls) statuses.set(p.head, verdict(heads[p.base]));
const forge = {
listOpenPulls: async () => pulls.map((p) => ({ number: p.number, title: "t", state: "open", merged: false, base: p.base,
head: "feat", head_sha: p.head, html_url: `http://forge/pulls/${p.number}` })),
branchHead: async (_o: string, _r: string, branch: string) => heads[branch],
setCommitStatus: async (_o: string, _r: string, sha: string, s: { context: string; state: string; description: string }) => {
writes.push(`${sha} ${s.context} ${s.state}`);
statuses.set(sha, { ...statuses.get(sha), [s.context]: { state: s.state, description: s.description } });
},
headChecks: async (_o: string, _r: string, sha: string) => statuses.get(sha) ?? {},
};
return { forge, writes, statuses };
}
test("a push to a trunk puts every open pull request into it out of date — twenty-five of them — and none into another", async () => {
const heads: Record<string, string> = { main: TRUNK, release: "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" };
const pulls = Array.from({ length: 25 }, (_, i) => ({ number: i + 1, base: "main", head: `${String(i).padStart(2, "0")}`.repeat(20) }));
pulls.push({ number: 99, base: "release", head: "9".repeat(40) });
const { forge, writes, statuses } = aForge(pulls, heads);
const gates = new GateWriter(forge);
const trunks: Record<string, string> = {};
// First sight: each trunk is taken as it is, and nothing is put out of date.
assert.equal(await weighTrunks(forge, gates, trunks, "novox", "mesh-host"), true);
assert.deepEqual(writes, []);
assert.equal(trunks["novox/mesh-host:main"], TRUNK);
// Nothing moved: nothing read past the trunks, nothing written.
assert.equal(await weighTrunks(forge, gates, trunks, "novox", "mesh-host"), false);
heads.main = MOVED;
assert.equal(await weighTrunks(forge, gates, trunks, "novox", "mesh-host"), true);
assert.equal(writes.length, 50, "both statuses of each of the 25 pull requests into main");
for (const p of pulls.filter((p) => p.base === "main")) {
const s = statuses.get(p.head)!;
assert.equal(s["mesh/merge-gate"].state, "pending");
assert.match(s["mesh/merge-gate"].description!, /judged against trunk a2c2c35bbbbb, the trunk is now d28ca95ccccc/);
assert.equal(s["mesh/repo-check"].state, "pending");
}
assert.equal(statuses.get("9".repeat(40))!["mesh/merge-gate"].state, "success", "a pull request into another branch is left");
assert.equal(trunks["novox/mesh-host:main"], MOVED);
// Weighed again, nothing more: the move was taken once, and the out-of-date statuses are left as they are.
writes.length = 0;
heads.main = "f".repeat(40);
await weighTrunks(forge, gates, trunks, "novox", "mesh-host");
assert.deepEqual(writes, [], "a check already out of date is not written again");
});
test("a trunk that cannot be read is weighed again on the next pass, never recorded half", async () => {
const heads: Record<string, string> = { main: TRUNK };
const { forge } = aForge([{ number: 1, base: "main", head: "1".repeat(40) }], heads);
const trunks: Record<string, string> = { "novox/mesh-host:main": TRUNK };
heads.main = MOVED;
const failing = { ...forge, setCommitStatus: async () => { throw new Error("the forge is away"); } };
assert.equal(await weighTrunks(failing, new GateWriter(failing), trunks, "novox", "mesh-host"), false);
assert.equal(trunks["novox/mesh-host:main"], TRUNK, "not recorded: the next pass weighs it again");
});
test("a verdict judged against a trunk newer than the pass's first read is not put out of date", async () => {
const NEWER = "ffffffffffffffffffffffffffffffffffffffff";
const heads: Record<string, string> = { main: TRUNK };
const { forge, statuses } = aForge([{ number: 1, base: "main", head: HEAD }], heads);
const trunks: Record<string, string> = { "novox/mesh-host:main": TRUNK };
// The pass reads main at MOVED; by the head's turn the trunk moved again, and the head's check answered for it.
let reads = 0;
const moving = { ...forge, branchHead: async () => (reads++ === 0 ? MOVED : NEWER) };
statuses.set(HEAD, { "mesh/merge-gate": { state: "success", description: `head x merged into trunk ${NEWER.slice(0, 12)} — pass` } });
await weighTrunks(moving, new GateWriter(moving), trunks, "novox", "mesh-host");
assert.equal(statuses.get(HEAD)!["mesh/merge-gate"].state, "success", "a fresh verdict was put out of date");
});
test("a release branch's move puts every open pull request into it out of date, as a trunk's does (ADR 0358 §5)", async () => {
// novox/hq ADR 0358 §5: for a pull request into a release branch, the release branch takes the trunk's place in ADR
// 0323 — the check merges the head onto the release branch's head and names it as the trunk commit, so the release
// branch's move puts its open verdicts out of date, and leaves those into main alone.
const release = "feat/57-config-and-provisioning";
const heads: Record<string, string> = { main: TRUNK, [release]: "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" };
const pulls = [{ number: 315, base: release, head: "3".repeat(40) }, { number: 1, base: "main", head: "1".repeat(40) }];
const { forge, statuses } = aForge(pulls, heads);
const gates = new GateWriter(forge);
const trunks: Record<string, string> = {};
await weighTrunks(forge, gates, trunks, "novox", "mesh-controller");
heads[release] = MOVED;
assert.equal(await weighTrunks(forge, gates, trunks, "novox", "mesh-controller"), true);
const s = statuses.get("3".repeat(40))!;
assert.equal(s["mesh/merge-gate"].state, "pending");
assert.match(s["mesh/merge-gate"].description!, /judged against trunk eeeeeeeeeeee, the trunk is now d28ca95ccccc/);
assert.equal(s["mesh/repo-check"].state, "pending");
assert.equal(statuses.get("1".repeat(40))!["mesh/merge-gate"].state, "success", "a pull request into main is left");
assert.equal(trunks[`novox/mesh-controller:${release}`], MOVED);
// The merge tool's rule reads the same: a verdict judged against the release branch's old head is not current.
assert.equal(verdictAtTrunk({ "mesh/merge-gate": { state: "success",
description: "head x merged into trunk eeeeeeeeeeee — pass" } }, MOVED).current, false);
});
// Issue 1301: a trunk's move puts out of date only the controller's statuses the base still requires; on hq that is
// mesh/repo-check alone, judged by its own words; on a main requiring mesh/check, none (the checker's, ADR 0447 §4).
test("a trunk's move writes only the statuses the base still requires", async () => {
const { outOfDateStatuses, trunkNamed } = await import("../trunk.ts");
const old = "1".repeat(40), now = "2".repeat(40);
const repo = { state: "success", description: `head ${"a".repeat(12)} merged into trunk ${old.slice(0, 12)} — pass: y` };
const gate = { state: "success", description: `head ${"a".repeat(12)} merged into trunk ${old.slice(0, 12)} — pass: x` };
assert.deepEqual(outOfDateStatuses({ "mesh/repo-check": repo }, now, ["mesh/repo-check"]).map((s: any) => s.context), ["mesh/repo-check"]);
assert.deepEqual(outOfDateStatuses({ "mesh/merge-gate": gate, "mesh/repo-check": repo }, now, ["mesh/repo-check"]).map((s: any) => s.context),
["mesh/repo-check"]);
assert.deepEqual(outOfDateStatuses({ "mesh/merge-gate": gate, "mesh/repo-check": repo }, now, ["mesh/check"]), []);
assert.deepEqual(outOfDateStatuses({ "mesh/merge-gate": gate, "mesh/repo-check": repo }, now).map((s: any) => s.context),
["mesh/merge-gate", "mesh/repo-check"], "a rule not read: as before");
// The checker's line names its trunk as "<head12> on <trunk12>".
assert.equal(trunkNamed(`pass ${"a".repeat(12)} on ${old.slice(0, 12)} | unit 3 run`), old.slice(0, 12));
assert.equal(trunkNamed("building on shanks since 10:00"), undefined);
});
+6 -43
View File
@@ -1,9 +1,9 @@
import assert from "node:assert/strict";
import { mock, test } from "node:test";
import { test } from "node:test";
import type { GiteaPull } from "../client.ts";
// **No poll of the forge** (issue 1422, notes 10 and 11): the forge's events announce heads and merges; a pass runs once at
// the start and when the receiver listens.
// **No poll of the forge for heads** (issue 1422; design 47 H §764, H-A-100): the forge's events say a pull request's new
// head as pull.updated, a merge and a close; nothing weighs a sibling or asks a merge check.
const edited = (base: string) => ({ name: "forge.pull-request.edited", body: { owner: "novox", repo: "hq", number: 7, base, merged: false } });
@@ -12,10 +12,9 @@ function deps() {
return { calls, d: {
getRepo: async () => ({ r: 1 }),
getPull: async () => ({ state: "open", base: "trunk" }) as any,
announceHead: async () => { calls.push("head"); },
announceUpdated: async () => { calls.push("updated"); },
announceMerge: async () => { calls.push("merge"); },
announceClosed: async () => { calls.push("closed"); },
siblingMoves: async () => { calls.push("siblings"); },
} };
}
@@ -23,51 +22,15 @@ test("an edited event announces the head into the base it now has, without a pol
const { actOn } = await import("../watch.ts");
const { calls, d } = deps();
await actOn(edited("trunk"), d);
assert.deepEqual(calls, ["head"]);
assert.deepEqual(calls, ["updated"]);
});
test("a close without a merge is announced by its event, a merged close is left to the merge event", async () => {
const { actOn } = await import("../watch.ts");
const { calls, d } = deps();
await actOn({ name: "forge.pull-request.closed", body: { owner: "novox", repo: "hq", number: 7, merged: false } }, d);
assert.deepEqual(calls, ["closed", "siblings"]);
assert.deepEqual(calls, ["closed"]);
calls.length = 0;
await actOn({ name: "forge.pull-request.closed", body: { owner: "novox", repo: "hq", number: 7, merged: true } }, d);
assert.deepEqual(calls, []);
});
test("no timer polls after the start: one pass ends and nothing is scheduled; a failed one is asked again", async () => {
const { startPass } = await import("../watch.ts");
mock.timers.enable({ apis: ["setTimeout", "setInterval"] });
try {
let runs = 0;
await startPass(async () => { runs++; }, { retryMs: 60_000, log: () => {} });
mock.timers.tick(24 * 3600_000);
assert.equal(runs, 1, "a day later the forge was not asked again");
let tries = 0;
const retried = startPass(async () => { if (++tries < 2) throw new Error("forge down"); }, { retryMs: 60_000, log: () => {} });
await Promise.resolve(); await Promise.resolve();
mock.timers.tick(60_000);
await retried;
assert.equal(tries, 2);
} finally {
mock.timers.reset();
}
});
test("a start pass announces a head nobody announced, and only remembers one the forge shows a check of", async () => {
const { announceNewHeads } = await import("../watch.ts");
const pull = (n: number, sha: string): GiteaPull => ({ number: n, state: "open", head_sha: sha, base: "main",
updated_at: new Date().toISOString() } as unknown as GiteaPull);
const announced: number[] = [], said: string[] = [];
const heads: Record<string, string> = {};
await announceNewHeads("novox/hq", [pull(1, "a".repeat(40)), pull(2, "b".repeat(40))], heads, false,
new Date(Date.now() - 24 * 3600_000).toISOString(), {
alreadyChecked: async (p) => p.number === 2,
announceHead: async (p) => { announced.push(p.number); return true; },
missed: (w) => said.push(w),
});
assert.deepEqual(announced, [1]);
assert.equal(heads["novox/hq#2@main"], "b".repeat(40), "the checked head is remembered, not announced");
assert.equal(said.length, 1);
});
+72
View File
@@ -0,0 +1,72 @@
// The tools of the forge module's merge calls (novox/hq design 47 H §766, §767): forge_calls reads the calls, newest first,
// with each member's state; forge_call_say_again says a call's merge-called again; forge_partial_clear clears a call's
// merge-partial by hand. Each act is written in the hand-act log before it is done.
import type { ToolDefinition } from "@novox/mesh-sdk/tools";
import { callerOf } from "@novox/mesh-sdk/callers";
import type { HandAct } from "@novox/mesh-sdk/views";
import type { Partials } from "../partials.js";
import { sayCall, type Calls, type Say } from "../calls.js";
const word = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
export function callTools(calls: Calls, partials: Partials, say: Say, acts: (act: HandAct) => Promise<void>): ToolDefinition[] {
return [
{
name: "forge_calls",
description: "The merge calls the forge module keeps (its state calls), newest first: each call's by, account, when, whether its merge-called " +
"was said, and each member with its base, head and state (judged, merged with its commit, or refused with why) (design 47 H §766).",
input: { type: "object", properties: { call: { type: "string", description: "only this merge call" } } },
run: async (args: Record<string, unknown>) => {
const only = word(args.call);
const all = await calls.all();
return { calls: only ? all.filter((c) => c.call === only) : all };
},
},
{
name: "forge_call_say_again",
description: "Says one merge call's merge-called again, for what it landed, with why: a gate that missed it takes the call in. " +
"Written in the hand-act log first (design 47 H §766).",
input: { type: "object", required: ["call", "why"], properties: {
call: { type: "string", description: "the merge call, 16 lowercase hex characters" },
why: { type: "string", description: "why it is said again, in plain words" } } },
run: async (args: Record<string, unknown>) => {
const call = word(args.call), why = word(args.why);
if (!/^[0-9a-f]{16}$/.test(call) || !why) throw new Error("forge_call_say_again names the call (16 lowercase hex characters) and why");
const kept = await calls.get(call);
if (!kept) throw new Error(`the forge module keeps no merge call ${call}`);
const by = callerOf(args);
try {
await acts({ what: `said the merge-called of the merge call ${call} again`, why: `${why} (${by})`, cause: "merge-called-said-again", verb: "forge_call_say_again" });
} catch (err) {
throw new Error(`the hand act was not recorded, so nothing was said: ${err instanceof Error ? err.message : String(err)}`);
}
const said = await sayCall(kept, say);
if (said && !kept.said) {
const { call: _c, ...value } = kept;
await calls.put(call, { ...value, said: true });
}
return { call, said, why, by, ...(said ? {} : { "said-none": "the call landed no member, so it says no merge-called" }) };
},
},
{
name: "forge_partial_clear",
description: "Clears the finding merge-partial of one merge call (a call the forge refused a member of after every member was judged), " +
"with why, when its refused members are not to be merged. Written in the hand-act log first (design 47 H §767).",
input: { type: "object", required: ["call", "why"], properties: {
call: { type: "string", description: "the merge call, 16 lowercase hex characters" },
why: { type: "string", description: "why it is cleared, in plain words" } } },
run: async (args: Record<string, unknown>) => {
const call = word(args.call), why = word(args.why);
if (!/^[0-9a-f]{16}$/.test(call) || !why) throw new Error("forge_partial_clear names the call (16 lowercase hex characters) and why");
const by = callerOf(args);
try {
await acts({ what: `cleared the merge-partial of the merge call ${call}`, why: `${why} (${by})`, cause: "merge-partial-cleared", verb: "forge_partial_clear" });
} catch (err) {
throw new Error(`the hand act was not recorded, so nothing was cleared: ${err instanceof Error ? err.message : String(err)}`);
}
return { call, cleared: await partials.clear(call), why, by };
},
},
];
}
-211
View File
@@ -1,211 +0,0 @@
// **A merge check's verdict holds for the trunk commit it judged** (novox/hq ADR 0323, issue 341).
//
// The build seat checks a pull request's head merged into its trunk's head at that moment — the verdict's trunk
// commit — and the verdict names both: "head 1a2b3c4d5e6f merged into trunk 7a8b9c0d1e2f", in both statuses'
// descriptions. When the trunk moves, every open pull request's verdict into it is out of date:
//
// - **the forge's holder** (index.ts) hears the move on its own — it reads each trunk's head on every pass that
// looks at the repository, never through mesh-delivery (ADR 0239 §36) — and sets mesh/merge-gate and
// mesh/repo-check on the head of every open pull request into that trunk back to pending, with the reason.
// Nothing is run for it: a recheck, a new head, or the merge tool asks the check again;
// - **the merge tool** (tools/index.ts) compares the trunk commit the head's verdict names with the trunk's head at
// the moment it is asked, merges nothing when they differ, asks the head's check once — the same announcement a
// new head makes — and never merges by itself after.
//
// Since issue 1301 (ADR 0447 §4) a main that requires mesh/check is the checker's: its line names the trunk commit it judged
// ("pass <head12> on <trunk12>"), the checker sets it out of date when the trunk moves, and the merge tool refuses a verdict
// of another trunk and asks nothing. The two statuses above are kept only where a base still requires them (a revert,
// pulls.ts maintained).
//
// Pure functions and two small files of the module's own state, so this is tested without a forge.
import type { CommitStatus, GiteaClient, GiteaPull, HeadCheck } from "./client.js";
import { CHECK_CONTEXT, WAITS_FOR_COMPOSED, maintained, requiredOf } from "./pulls.js";
/** A commit as a verdict names it: its first twelve characters. */
export function twelve(sha: string | undefined): string {
return String(sha ?? "").slice(0, 12).toLowerCase();
}
/** Whether two commits are one, however either is abbreviated (seven characters at least). */
export function sameCommit(a: string | undefined, b: string | undefined): boolean {
const x = String(a ?? "").toLowerCase(), y = String(b ?? "").toLowerCase();
if (x.length < 7 || y.length < 7) return false;
return x.length <= y.length ? y.startsWith(x) : x.startsWith(y);
}
/** What a verdict judged, as both statuses' descriptions begin (ADR 0323 §3). */
export function judgedWords(head: string, trunk: string): string {
return `head ${twelve(head)} merged into trunk ${twelve(trunk)}`;
}
/** The trunk commit a merge check's status names: the one its verdict judged ("merged into trunk …"), or, for a
* verdict put out of date, the one it had judged ("judged against trunk …"). Undefined when it names none, as a
* verdict of a build seat from before ADR 0323 does. */
export function trunkNamed(description: string | undefined): string | undefined {
const m = /(?:merged into|judged against) trunk ([0-9a-f]{7,64})\b/i.exec(description ?? "")
// The checker's mesh/check line (ADR 0447 §3): "<head12> on <trunk12>".
?? /\b[0-9a-f]{12} on ([0-9a-f]{12})\b/i.exec(description ?? "");
return m ? m[1].toLowerCase() : undefined;
}
/** A verdict out of date, as its statuses say it (ADR 0323 §4). */
export function outOfDateWords(judged: string | undefined, now: string): string {
const was = judged ? `judged against trunk ${twelve(judged)}` : "judged against a trunk it does not name";
return `out of date: ${was}, the trunk is now ${twelve(now)}; judged again on a recheck or when it is merged`;
}
/** Whether a pending gate says a check of the head is asked and not yet answered: waiting in the build queue,
* building on a machine (gate.ts), or asked again by a recheck (mesh-delivery). Such a check is not asked again. */
export function checkOnItsWay(gate: HeadCheck | undefined): boolean {
if (!gate || gate.state !== "pending") return false;
const d = gate.description ?? "";
return d.startsWith("waiting in the build queue") || d.startsWith("building on ") || d.startsWith("checking again");
}
/** Whether a gate says it waits for its group's composed check. */
export function waitsForComposed(gate: HeadCheck | undefined): boolean {
return !!gate && gate.state === "pending" && (gate.description ?? "").startsWith(WAITS_FOR_COMPOSED);
}
/**
* The statuses a trunk's move puts back to pending on one open pull request's head, from what the forge holds on it
* now: none when it has no merge check yet, when a check is pending (on its way, or already out of date — its
* verdict is weighed against the trunk when it lands), or when its verdict judged the trunk's head. Otherwise the
* gate, and the repository's own check when the head has one — a pending repo-check a verdict will not set would
* stand for ever (novox/hq issue 305's rule).
*/
export function outOfDateStatuses(checks: Record<string, HeadCheck>, trunkHead: string, required?: string[]): CommitStatus[] {
// Only the statuses the base still requires (issue 1301): the first of them the head holds judges.
const kept = maintained(required).filter((c) => checks[c]);
const judge = kept.length ? checks[kept[0]] : undefined;
if (!judge || judge.state === "pending") return [];
const judged = trunkNamed(judge.description);
if (judged && sameCommit(judged, trunkHead)) return [];
const description = outOfDateWords(judged, trunkHead);
return kept.map((context) => ({ state: "pending" as const, context, description }));
}
/** Where the merge tool stands with a head's verdict and the trunk's head (ADR 0323 §5). */
export interface VerdictAtTrunk {
/** The verdict judged the trunk's head: the required statuses decide, as before. */
current: boolean;
/** A check of the head is asked and not yet answered: nothing is asked again. */
onItsWay: boolean;
/** The trunk commit the verdict names, when it names one. */
judged?: string;
}
export function verdictAtTrunk(checks: Record<string, HeadCheck>, trunkHead: string, context = CHECK_CONTEXT): VerdictAtTrunk {
const gate = checks[context];
const judged = trunkNamed(gate?.description);
if (checkOnItsWay(gate)) return { current: false, onItsWay: true, judged };
return { current: !!gate && gate.state !== "pending" && !!judged && sameCommit(judged, trunkHead), onItsWay: false, judged };
}
/** The pending words the merge tool's ask of a check is said with: in the build queue from now, as an announced head's. */
export function askedWords(at: Date, trunkHead: string): string {
const two = (n: number) => String(n).padStart(2, "0");
return `waiting in the build queue since ${two(at.getHours())}:${two(at.getMinutes())}: asked by the merge tool ` +
`against trunk ${twelve(trunkHead)}`;
}
// --- a trunk's move, weighed --------------------------------------------------------------------------------------
/** What weighing a trunk's move reads of the forge. */
export interface TrunkForge {
listOpenPulls(owner: string, repo: string): Promise<GiteaPull[]>;
branchHead(owner: string, repo: string, branch: string): Promise<string>;
/** The rule the forge applies to a branch: which of the controller's statuses are kept there (issue 1301). Not given,
* or not read: both, as before. */
appliedProtection?(owner: string, repo: string, branch: string): Promise<{ enable_status_check?: boolean; status_check_contexts?: string[] | null } | null>;
}
/** What it writes with: the merge check's one writer (gate.ts), which decides in the head's own turn. */
export interface OutOfDateWriter {
outOfDate(owner: string, repo: string, sha: string,
decide: (checks: Record<string, HeadCheck>) => CommitStatus[] | Promise<CommitStatus[]>, target?: string): Promise<CommitStatus[]>;
}
/**
* Every trunk of one repository that an open pull request merges into, read; for one that moved since it was last read
* (`trunks`, by `owner/repo:branch`, which this keeps current), the merge check of every open pull request into it put
* out of date (ADR 0323 §4). A trunk first seen is recorded as it is and nothing is put out of date. Bounded however
* many are open: one listing of the open pull requests (paged), one read of each trunk, then per open pull request into
* a trunk that moved one read and at most two writes, one at a time. A trunk that could not be weighed whole is not
* recorded, so the next pass weighs it again. Answers whether the record changed. `moved` is told of each base that moved, for the siblings whose base it is.
*/
export async function weighTrunks(forge: TrunkForge, gates: OutOfDateWriter, trunks: Record<string, string>, owner: string,
name: string, moved?: (base: string) => Promise<void>): Promise<boolean> {
let changed = false;
try {
const open = (await forge.listOpenPulls(owner, name)).filter((p) => p.state === "open" && !!p.head_sha && !!p.base);
for (const base of new Set(open.map((p) => String(p.base)))) {
const key = `${owner}/${name}:${base}`.toLowerCase();
const head = await forge.branchHead(owner, name, base);
const before = trunks[key];
if (before && sameCommit(before, head)) continue;
if (before) {
let put = 0;
const required = forge.appliedProtection
? requiredOf(await forge.appliedProtection(owner, name, base).catch(() => undefined)) : undefined;
for (const pull of open.filter((p) => p.base === base)) {
// The trunk is read again in the head's own turn: a verdict judged against a head newer than the pass's first
// read — the trunk moved again meanwhile, and a check answered — is not put out of date.
const written = await gates.outOfDate(owner, name, String(pull.head_sha),
async (checks) => outOfDateStatuses(checks, await forge.branchHead(owner, name, base), required), pull.html_url || undefined);
if (written.length) put++;
}
console.log(`[gitea] ${owner}/${name}'s ${base} moved from ${twelve(before)} to ${twelve(head)}: ${put} open pull ` +
`request(s) into it put out of date, nothing run (novox/hq ADR 0323)`);
// A verdict that read a pull request into this trunk as a sibling is out of date by its move too (ADR 0382 §5).
if (moved) await moved(base);
}
trunks[key] = head;
changed = true;
}
} catch (err) {
console.error(`[gitea] ${owner}/${name}: whether a trunk moved could not be weighed, so it is weighed again on the next ` +
`pass — ${err instanceof Error ? err.message : err}`);
}
return changed;
}
// --- the announcement of a head, shared by the watcher and the merge tool ---------------------------------------
/** `pull.updated` for one open pull request's head: what the controller asks the build seat to check (novox/hq to-be
* 45 §9). The merge tool's ask is this same announcement (ADR 0323 §5). */
export async function announcementOf(client: GiteaClient, owner: string, name: string, cloneURL: string | undefined,
pull: GiteaPull): Promise<Record<string, unknown>> {
const files = await client.listPullFiles(owner, name, pull.number);
const head = String(pull.head_sha);
// What the controller maps the change onto the mesh's module graph with (novox/hq ADR 0237 as amended): which
// changed directories hold a module at the head — the merge's rule (issue 278). Not said when it could not be read; the controller then reads the change as
// touching everything built from the repository.
let moduleDirs: string[] | null = null;
try {
if (!files.truncated) moduleDirs = await client.moduleDirsAt(owner, name, head, files.paths);
} catch (err) {
console.error(`[gitea] ${owner}/${name}#${pull.number}: what the head holds could not be read — ${err instanceof Error ? err.message : err}`);
}
// The base branch's head as the head is announced: the trunk commit a verdict no build judges is said against
// (novox/hq ADR 0323 §3). Not said when it cannot be read; that verdict then names none.
const baseSHA = pull.base ? await client.branchHead(owner, name, String(pull.base)).catch(() => undefined) : undefined;
return {
owner,
repo: name,
number: pull.number,
...(baseSHA ? { base_sha: baseSHA } : {}),
title: pull.title,
body: pull.body,
base: pull.base,
head: pull.head,
head_sha: pull.head_sha,
clone_url: cloneURL,
html_url: pull.html_url,
paths: files.paths,
paths_truncated: files.truncated,
removed: files.removed,
...(moduleDirs ? { module_dirs: moduleDirs, module_dirs_said: true } : {}),
};
}
+42
View File
@@ -0,0 +1,42 @@
// **A pull request's new head is said as the seat git's pull.updated** (novox/hq design 47 H §764; H-A-100): from the forge's
// event of an opened, pushed, reopened or retargeted pull request alone; nothing polls for heads and no merge check is
// asked or written (the merge-check machinery went with milestone H).
import type { GiteaClient, GiteaPull } from "./client.js";
/** `pull.updated` for one open pull request's head: what the controller asks the build seat to check (novox/hq to-be
* 45 §9). The merge tool's ask is this same announcement (ADR 0323 §5). */
export async function announcementOf(client: GiteaClient, owner: string, name: string, cloneURL: string | undefined,
pull: GiteaPull): Promise<Record<string, unknown>> {
const files = await client.listPullFiles(owner, name, pull.number);
const head = String(pull.head_sha);
// What the controller maps the change onto the mesh's module graph with (novox/hq ADR 0237 as amended): which
// changed directories hold a module at the head — the merge's rule (issue 278). Not said when it could not be read; the controller then reads the change as
// touching everything built from the repository.
let moduleDirs: string[] | null = null;
try {
if (!files.truncated) moduleDirs = await client.moduleDirsAt(owner, name, head, files.paths);
} catch (err) {
console.error(`[gitea] ${owner}/${name}#${pull.number}: what the head holds could not be read — ${err instanceof Error ? err.message : err}`);
}
// The base branch's head as the head is announced: the trunk commit a verdict no build judges is said against
// (novox/hq ADR 0323 §3). Not said when it cannot be read; that verdict then names none.
const baseSHA = pull.base ? await client.branchHead(owner, name, String(pull.base)).catch(() => undefined) : undefined;
return {
owner,
repo: name,
number: pull.number,
...(baseSHA ? { base_sha: baseSHA } : {}),
title: pull.title,
body: pull.body,
base: pull.base,
head: pull.head,
head_sha: pull.head_sha,
clone_url: cloneURL,
html_url: pull.html_url,
paths: files.paths,
paths_truncated: files.truncated,
removed: files.removed,
...(moduleDirs ? { module_dirs: moduleDirs, module_dirs_said: true } : {}),
};
}
+6 -54
View File
@@ -1,29 +1,24 @@
// What the forge's events ask of the announcer, and the one pass at a start (issue 1422, notes 10 and 11). Nothing polls the
// forge: a head or merge is announced when its event is heard, and a pass over every repository runs once when the module
// starts and again when the receiver is listening, so what happened while it was down is announced too.
// forge for heads: a pull request's new head is said as pull.updated when its event is heard, a merge or a close by its
// event and by the pass over every repository's merges at the start (design 47 H §764; H-A-100).
//
// Apart from index.ts, which has side effects at import, so these are tested with the announcers injected.
import type { GiteaPull, GiteaRepo } from "./client.js";
import type { Announced } from "./pulls.js";
import { headKey, headsToAnnounce } from "./pulls.js";
import type { ForgeEvent } from "./webhook.js";
export interface ActDeps<R, P> {
getRepo(owner: string, repo: string): Promise<R>;
getPull(owner: string, repo: string, number: number): Promise<P & { state?: string; merged?: boolean }>;
announceHead(repo: R, pull: P): Promise<unknown>;
announceUpdated(repo: R, pull: P): Promise<unknown>;
announceMerge(repo: R, pull: P): Promise<unknown>;
announceClosed(repo: R, pull: P): Promise<unknown>;
siblingMoves(full: string, number: number): Promise<unknown>;
}
const HEAD_EVENTS = ["forge.pull-request.opened", "forge.pull-request.synchronized", "forge.pull-request.reopened"];
/**
* What the forge's event asks of the announcer at once: a new head is announced, a merge, a close without a merge, and a
* pull request retargeted (an edit: the head is announced into the base it now has — the base is in the head's key, so an
* edit that changed nothing about the base announces nothing).
* What the forge's event asks of the announcer at once: a new head is said, a merge, a close without a merge, and a pull
* request retargeted (an edit: the head is said into the base it now has).
*/
export async function actOn<R, P>(event: ForgeEvent, d: ActDeps<R, P>): Promise<void> {
const b = event.body as { owner?: string; repo?: string; number?: number; merged?: boolean };
@@ -37,51 +32,8 @@ export async function actOn<R, P>(event: ForgeEvent, d: ActDeps<R, P>): Promise<
const [repo, pull] = await Promise.all([d.getRepo(b.owner, b.repo), d.getPull(b.owner, b.repo, b.number)]);
if (closed) {
await d.announceClosed(repo, pull);
await d.siblingMoves(`${b.owner}/${b.repo}`, b.number);
return;
}
if (head && pull.state === "open") await d.announceHead(repo, pull);
if (head && pull.state === "open") await d.announceUpdated(repo, pull);
if (merged) await d.announceMerge(repo, pull);
}
/**
* The one pass at a start, and its retry: run now; if it fails, say so and run again after `retryMs`, until one pass has
* ended. A retry of a failed pass, never a poll: after a pass has ended nothing is scheduled.
*/
export function startPass(run: () => Promise<void>, opts: { retryMs: number; log?: (l: string) => void }): Promise<void> {
const log = opts.log ?? ((l) => console.error(`[gitea] ${l}`));
return run().catch((err) => {
log(`the pass over every repository failed, asked again in ${opts.retryMs / 1000} s — ${err instanceof Error ? err.message : err}`);
return new Promise<void>((resolve) => setTimeout(() => resolve(startPass(run, opts)), opts.retryMs));
});
}
export interface HeadDeps {
/** Whether the forge shows a merge check of the head: only an announced head has one. */
alreadyChecked(pull: GiteaPull): Promise<boolean>;
/** Announce it; true when it was this call that announced it (not an event before it). */
announceHead(pull: GiteaPull): Promise<boolean>;
/** Told of a head this pass announced that no event had. */
missed(what: string): void;
}
/**
* The heads of one repository's open pull requests a pass announces. A head is announced when it is new and fresh (moved in
* the last day); at the first pass after a start (`primed` false) one the forge shows a merge check of was announced
* already, and is only remembered.
*/
export async function announceNewHeads(full: string, open: GiteaPull[], heads: Announced, primed: boolean, dayAgo: string, d: HeadDeps): Promise<void> {
for (const pull of headsToAnnounce(full, open, heads)) {
const key = headKey(full, pull.number, pull.base);
const fresh = primed || (!!pull.updated_at && pull.updated_at > dayAgo);
if (fresh && !primed && await d.alreadyChecked(pull)) {
heads[key] = String(pull.head_sha);
continue;
}
if (fresh) {
if (await d.announceHead(pull)) d.missed(`${key} at ${String(pull.head_sha).slice(0, 8)}`);
} else heads[key] = String(pull.head_sha);
}
}
export type { GiteaRepo };
@@ -1,7 +1,7 @@
package main
// What this module keeps on the bus, announced from its code (novox/hq ADR 0495 §2 §5; issue 1790): every state it
// keeps, each readable by others, since another module reads each today (the builder, the checker and the indexer read toolchains; the builder and the checker read steps; gitea reads keys). A state of its own that it
// keeps, each readable by others, since another module reads each today (the builder and the indexer read toolchains; the builder reads steps; gitea reads keys). A state of its own that it
// did not name here is refused at the call (stdio.Keeps).
import (
@@ -57,9 +57,6 @@ func (m *Module) askSteps(steps []StepTool) steprun.AskSteps {
func (m *Module) Puller(steps []StepTool, source steprun.AskSource) *steprun.Puller {
if source == nil {
source = &steprun.SeatAsks{Language: sdkstep.AskGo, Logf: m.Say}
if m.Callers == nil {
m.Callers = steprun.SeatListCallers(sdkstep.AskGo, m.Say)
}
}
capacity := m.Capacity
// The capacity's own change wakes the puller (issue 1887): the runtime's watch of the config value as mesh-config
@@ -91,7 +88,7 @@ func (m *Module) Puller(steps []StepTool, source steprun.AskSource) *steprun.Pul
if m.SayEvent != nil {
say = steprun.SayOn(sdkstep.AskGo, m.Node, m.SayEvent)
}
return &steprun.Puller{KeepOutput: steprun.KeepOutputIn(m.Outputs), Source: source, Language: sdkstep.AskGo, Say: say, Callers: m.Callers, Node: m.Node, Put: m.Steps, PausePut: m.Pauses, Load: load, ForgetPause: m.ForgetPause, WatchPauses: m.WatchPauses, PauseKeys: m.ReadPauses.Keys,
return &steprun.Puller{KeepOutput: steprun.KeepOutputIn(m.Outputs), Source: source, Language: sdkstep.AskGo, Say: say, Prior: steprun.PriorRuns(m.ReadSteps.Get), Node: m.Node, Put: m.Steps, PausePut: m.Pauses, Load: load, ForgetPause: m.ForgetPause, WatchPauses: m.WatchPauses, PauseKeys: m.ReadPauses.Keys,
Capacity: capacity, SettingsFile: settings, WatchConfig: watch, CoresPerStep: cores, BuildHours: hours, Logf: m.Say, Has: m.Has,
Run: func(ctx context.Context, a sdkstep.StepAsk) (any, error) {
if err := m.Check(ctx); err != nil {
@@ -55,7 +55,7 @@ func TestTheModuleTakesADeliveryAskBeforeAnEarlierCheck(t *testing.T) {
// A build rides main's subject, any other kind a named asker's (design 47 G §543).
subject, _ := sdkstep.AskSubject(a.Language, a.Kind)
if a.Kind != sdkstep.AskDelivery {
subject, _ = sdkstep.AskSubjectBy(a.Language, a.Kind, "mesh-delivery-checker")
subject, _ = sdkstep.AskSubjectBy(a.Language, a.Kind, "mesh-delivery-runner")
}
if _, err := js.Publish(ctx, subject, raw); err != nil {
t.Fatal(err)
@@ -87,7 +87,7 @@ func TestTheModuleTakesADeliveryAskBeforeAnEarlierCheck(t *testing.T) {
ended := 0
states.mu.Lock()
for _, a := range []sdkstep.StepAsk{first, check} {
asker := "mesh-delivery-checker" // a named ask's step is keyed under its asker, main's under its node (§481)
asker := "mesh-delivery-runner" // a named ask's step is keyed under its asker, main's under its node (§481)
if a.Kind == sdkstep.AskDelivery {
asker = ""
}
@@ -11,15 +11,11 @@ import (
func TestPullerSaysTheSeatsEventsOnItsNodesSubject(t *testing.T) {
var subjects []string
m := &Module{Node: "ace", Capacity: func() int { return 0 },
Callers: func(kind string) ([]string, bool) { return []string{"mesh-pipeline-runner"}, kind == "step" },
SayEvent: func(subject string, _ any, _ string) error { subjects = append(subjects, subject); return nil }}
p := m.Puller(nil, steprun.NewFakeAsks())
if p.Say == nil {
t.Fatal("the puller says no event")
}
if got, ok := p.Callers("step"); !ok || len(got) != 1 {
t.Fatalf("the puller checks the callers of %v, %v, not the module's", got, ok)
}
seat, _ := sdkstep.BuildSeat(sdkstep.AskGo)
for _, event := range []string{"ask-taken", "step-progress", "step-ended"} {
if err := p.Say(event, nil, "id"); err != nil {
@@ -198,7 +198,7 @@ func TestACheckAsksDigestIsTheToolsAnswerInTheCall(t *testing.T) {
}
}
ask := m.askSteps(steps)
a := sdkstep.StepAsk{ID: sdkstep.NewID(), Kind: sdkstep.AskCheck, Language: sdkstep.AskGo, Asker: "mesh-delivery-checker",
a := sdkstep.StepAsk{ID: sdkstep.NewID(), Kind: sdkstep.AskCheck, Language: sdkstep.AskGo, Asker: "mesh-delivery-runner",
At: time.Now(), Check: &sdkstep.CheckJob{Fetch: sdkstep.Fetch{Repository: "novox/x", Commit: askCommit}, Levels: []string{sdkstep.LevelUnit}}}
out, err := steprun.RunAsk(context.Background(), ask, a)
if err != nil {
@@ -166,14 +166,15 @@ func TestAComposeAskFailsLoudly(t *testing.T) {
}
// Design 47 G §615: the module reads the manifests a compose ask names from the catalog graph's entry, by the seat's verb
// entry, and invokes no tool of the delivery indexer. 1921 (B0): a run's input is asked of the checker seat's verb input, as
// the manifest invokes it, and no state of the checker's inputs is read (ADR 0596 §2).
// entry, and invokes no tool of the delivery indexer. 1921 (B0): a run's input is asked of the seat mesh-wants' verb input, as
// the manifest invokes it, and no state of the checker's inputs is read (ADR 0596 §2); the seat mesh-delivery-checker is no
// longer invoked (design 47 H §764, H-A-57).
func TestTheModuleReadsTheCatalogEntries(t *testing.T) {
m := readManifest(t)
if !slices.Contains(m.Invokes, catalogclient.EntryVerb) || slices.ContainsFunc(m.Invokes, func(i string) bool { return strings.HasPrefix(i, "mesh-delivery-indexer") }) {
t.Errorf("invokes = %v: want %s and no tool of the indexer", m.Invokes, catalogclient.EntryVerb)
}
if !slices.Contains(m.Invokes, runInputVerb) || slices.Contains(m.Reads, "mesh-delivery-checker.inputs") {
if !slices.Contains(m.Invokes, runInputVerb) || slices.ContainsFunc(m.Invokes, func(i string) bool { return strings.HasPrefix(i, "seat:mesh-delivery-checker") }) || slices.Contains(m.Reads, "mesh-delivery-checker.inputs") {
t.Errorf("invokes = %v, reads = %v: want %s invoked and no inputs state read", m.Invokes, m.Reads, runInputVerb)
}
}
@@ -12,6 +12,7 @@ import (
"errors"
"fmt"
"os"
"path"
"path/filepath"
"regexp"
"slices"
@@ -157,7 +158,7 @@ func (m *Module) fetchInto(ctx context.Context, req sdkstep.FetchRequest, id str
return nil, err
}
if (base == "" || res.Merge != "") && len(req.Paths) > 0 {
if err := steprun.Narrow(tree, req); err != nil {
if err := narrowTree(tree, repository, req); err != nil { // with what H-A-136 adds
return nil, err
}
// Said beside the tree, so the steps that list the tree's go.mod files leave out those narrowed away.
@@ -173,7 +174,7 @@ func (m *Module) fetchInto(ctx context.Context, req sdkstep.FetchRequest, id str
// A fetch asked with a module's directory is of that Go module and what its go.mod replaces with a local path,
// never another Go module of the tree (design 47 G, A-447). Said beside the tree, so every later step lists the
// same modules.
if dirs, err = scopedDirs(tree, dir, dirs); err != nil {
if dirs, err = scopedDirs(tree, dir, req.Paths, dirs); err != nil {
return nil, err
}
if err := os.WriteFile(filepath.Join(root, scopeMark), []byte(strings.Join(dirs, "\n")), 0o600); err != nil {
@@ -687,7 +688,7 @@ func cleanDir(dir string) string {
// go.mod replaces with a local path, followed through their own replaces (design 47 G, A-447), in order. A directory
// the tree holds no go.mod for is left out. A directory holding no go.mod chooses every go.mod under it, and one that
// chooses no Go module at all is an error naming it (A-447a).
func scopedDirs(tree, dir string, all []string) ([]string, error) {
func scopedDirs(tree, dir string, paths, all []string) ([]string, error) {
have := map[string]bool{}
for _, d := range all {
have[d] = true
@@ -696,11 +697,23 @@ func scopedDirs(tree, dir string, all []string) ([]string, error) {
todo := []string{dir}
if !have[dir] {
// A directory with no go.mod of its own (a module whose Go code lies in go/, a contracts module with a go.mod per
// seat) is every go.mod under it; the tree is already narrowed to the module's paths (A-447a).
// seat) is every go.mod under it, in a narrowed tree under its named paths (A-447a): the narrowed tree also holds
// the module's generated-from directories and its repository's zero-version packages (H-A-136), which are not
// the artifact's own Go modules.
roots := []string{dir}
if len(paths) > 0 {
roots = nil
for _, p := range paths {
roots = append(roots, path.Join(dir, filepath.ToSlash(p)))
}
}
todo = nil
for _, d := range all {
if dir == "." || strings.HasPrefix(d, dir+"/") {
todo = append(todo, d)
for _, r := range roots {
if r == "." || d == r || strings.HasPrefix(d, r+"/") {
todo = append(todo, d)
break
}
}
}
}
@@ -69,7 +69,7 @@ func TestAFetchAskedWithADirectoryChoosesItsModuleAndWhatItReplacesAlone(t *test
t.Fatal(err)
}
}
got, err := scopedDirs(tree, cleanDir(c.dir), all)
got, err := scopedDirs(tree, cleanDir(c.dir), nil, all)
if c.want == nil {
if err == nil || !strings.Contains(err.Error(), c.dir) {
t.Errorf("dir %q chose %v, %v; want an error naming it", c.dir, got, err)
@@ -56,3 +56,19 @@ func TestTheStepsSayAFailedNetworkAsATransportFault(t *testing.T) {
}
})
}
// A-489b, design 47 G §24: the module's own steps can say a pipeline step's end, or
// every step ask the runner sends it is refused ("this build module says no step's end"), as the first live pipeline met.
func TestTheStepsCanSayAStepsEnd(t *testing.T) {
conformance.StepEnds(t, (&Module{Node: "kitnode"}).askSteps(nil))
}
// A-489c (A-489a): the module's puller counts the runs its steps state says started, not the bus's deliveries (an ask given back before
// it ran is no run), so the poison rule never ends an ask that never ran.
func TestThePullerCountsRunsThatStarted(t *testing.T) {
conformance.RunsCounted(t, func(read func(string) (json.RawMessage, error)) *steprun.Puller {
m := &Module{Node: "kitnode", Capacity: func() int { return 1 }}
m.ReadSteps = StateRead{Get: read}
return m.Puller(nil, steprun.NewFakeAsks())
})
}
@@ -195,6 +195,16 @@ func TestTheModuleInvokesTheArtifactSeatsVerbsAndWritesNoStore(t *testing.T) {
if !slices.Contains(m.Consumes, "mesh-conditions.findings-asked") {
t.Errorf("consumes %v lack mesh-conditions.findings-asked", m.Consumes)
}
// Design 47 G A-488a, A-488b: its runtime follows the seat list, so the module consumes the seat's two events (which makes its
// durable consumer) and invokes the verb that reads the list.
for _, ev := range []string{"mesh-catalog.seat-definition-changed", "mesh-catalog.seat-definition-removed"} {
if !slices.Contains(m.Consumes, ev) {
t.Errorf("consumes %v lack %s", m.Consumes, ev)
}
}
if !slices.Contains(m.Invokes, "seat:mesh-catalog.seat-definitions") {
t.Errorf("invokes %v lack seat:mesh-catalog.seat-definitions", m.Invokes)
}
// Not a foundation part, it asks its finding stream in requires, by the template events (design 47 G §529, A-30), and
// declares no stream of that name.
for _, st := range m.Streams {
@@ -25,9 +25,6 @@ const CheckRound = 10 * time.Minute
// Module is the Go build module's one running state: the node it runs on, its recipe, the toolchain guard and the
// states it writes (toolchains, steps).
type Module struct {
// Callers says which seats the build seat's definition lists as callers of an accepted kind (steprun.SeatListCallers when
// the module pulls through its runtime; nil in a test checks no named asker): design 47 G §543, A-163.
Callers func(kind string) ([]string, bool)
// SayEvent publishes an event of the go build seat on a seat subject (stdio.SeatPublish; nil says none, a test's): the
// puller's ask-taken, step-progress and step-ended (design 47 G §496, §602).
SayEvent func(subject string, body any, id string) error
@@ -119,7 +116,7 @@ type Module struct {
// request names each manifest it gives by digest with (compose.go, design 47 G §615); GoModCache, when set, is the Go module cache in place of Cache's (a test).
ReadEntry func(fingerprint string) (meshcat.CatalogEntry, error)
// AskInput asks a seat verb the module invokes (module.json) as the runtime calls it (stdio.Ask): the verb a run ask's
// input names, answering the input by its digest (meshdeliverycheckerclient.ReadInput).
// input names, answering the input by its digest (the seat mesh-wants' verb input).
AskInput func(key string, body any) (json.RawMessage, error)
// PlaceHead, when set, lays a run's head at a directory instead of fetching it (a test).
PlaceHead func(ctx context.Context, h sdkstep.RunHead, dir string) error
@@ -0,0 +1,251 @@
package main
import (
"io/fs"
"maps"
"os"
"path"
"path/filepath"
"slices"
"strings"
sdkstep "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/steprun"
"git.novox.be/novox/mesh-sdk/go/catalogue"
)
// narrowedKeptAtRoot are what steprun.Narrow keeps beside the named paths, read from the request's directory: the
// manifest and its lock files. A request narrowed from the repository's root (narrowTree) keeps them at the root too,
// where the asked module's build names none of them; they are removed again.
var narrowedKeptAtRoot = []string{"module.json", "go.sum", "package-lock.json"}
// narrowTree narrows the fetched tree for a build of an artifact that names its paths (ADR 0499 clause 4,
// steprun.Narrow). Beside the artifact's paths and the module's manifest, the workspace holds every generated-from
// directory an artifact of the module names, and the directory (with its go.mod) of every package of the same repository
// the artifact's go.mod requires at the zero version, found by the manifests of that repository's modules; nothing else
// (design 47 H, lead answer H-A-136). A package of another repository comes published, as before (ADR 0573 §4).
func narrowTree(tree, repository string, req sdkstep.FetchRequest) error {
dir := cleanDir(req.Dir)
if dir == "" {
return steprun.Narrow(tree, req) // refused there: named paths without the module's directory
}
extra := generatedFromDirs(tree, dir)
extra = append(extra, ownZeroPackageDirs(tree, repository, dir, req.Paths)...)
var outside []string
inside := slices.Clone(req.Paths)
for _, e := range extra {
if rel, ok := under(dir, e); ok {
if !slices.Contains(inside, rel) {
inside = append(inside, rel)
}
} else if !slices.Contains(outside, e) {
outside = append(outside, e)
}
}
if len(outside) == 0 {
r := req
r.Paths = inside
return steprun.Narrow(tree, r)
}
// A directory outside the module's own: the request is narrowed from the root, with every path the module's
// narrowing keeps named by its path from the root (the manifest and lock files only where the module has them).
all := []string{}
for _, p := range inside {
all = append(all, path.Join(dir, p))
}
for _, f := range narrowedKeptAtRoot {
if _, err := os.Lstat(filepath.Join(tree, filepath.FromSlash(path.Join(dir, f)))); err == nil {
all = append(all, path.Join(dir, f))
}
}
all = append(all, outside...)
if err := steprun.Narrow(tree, sdkstep.FetchRequest{Repository: req.Repository, Commit: req.Commit, Paths: all}); err != nil {
return err
}
for _, f := range narrowedKeptAtRoot {
if !slices.Contains(all, f) {
if err := os.RemoveAll(filepath.Join(tree, f)); err != nil {
return err
}
}
}
return nil
}
// under answers p's path relative to dir when p is dir or lies under it.
func under(dir, p string) (string, bool) {
if dir == "." {
return p, true
}
if p == dir {
return ".", true
}
if rel, ok := strings.CutPrefix(p, dir+"/"); ok {
return rel, true
}
return "", false
}
// generatedFromDirs are the generated-from directories (from the tree's root) the artifacts of the module in dir name
// (H-A-136): the seat definitions a generated package is compared against. A module at the repository's root keeps not
// its generated-from directory, which would be the whole repository, but the generator's inputs and outputs: the seats/
// directory of each generated-from directory and the paths of every artifact of the module naming generated-from, as
// the generator's check reads every generated package (H-A-137). A manifest that is absent or unreadable names none;
// the steps that read it say so.
func generatedFromDirs(tree, dir string) []string {
raw, err := os.ReadFile(filepath.Join(tree, filepath.FromSlash(dir), "module.json"))
if err != nil {
return nil
}
man, err := catalogue.Decode(raw)
if err != nil || man.Build == nil {
return nil
}
var out []string
add := func(p string) {
if p == ".." || strings.HasPrefix(p, "../") || slices.Contains(out, p) {
return
}
if _, err := os.Lstat(filepath.Join(tree, filepath.FromSlash(p))); err == nil { // steprun.Narrow refuses a path the tree lacks
out = append(out, p)
}
}
for _, a := range man.Build.Artifacts {
g := strings.TrimSpace(a.GeneratedFrom)
if g == "" {
continue
}
if dir != "." {
add(path.Join(dir, filepath.ToSlash(g)))
continue
}
add(path.Join(filepath.ToSlash(g), "seats"))
for _, p := range a.Paths {
add(path.Clean(filepath.ToSlash(p)))
}
}
return out
}
// ownZeroPackageDirs are the directories (from the tree's root) of the packages of the checked repository that a go.mod
// under the artifact's named paths requires at the zero version (H-A-136; ADR 0573 §2), transitively: the go.mod of each
// such directory is read in turn for the packages of the repository it requires at the zero version, each directory
// once (design 47 H, H-A-202, H-A-198). Each is found by the manifests of the repository's modules: a module's directory
// or the directory of one of its artifacts' paths whose go.mod declares the required module path. One no manifest leads
// to is left to the fetch's resolution, which fails naming it.
func ownZeroPackageDirs(tree, repository, dir string, paths []string) []string {
want := map[string]bool{}
addReqs := func(raw []byte) {
for _, pn := range forgePins(string(raw)) {
if pn.short == zeroShort && "novox/"+pn.repo == repository {
want[pn.module] = true
}
}
}
for _, p := range paths {
root := filepath.Join(tree, filepath.FromSlash(path.Join(dir, p)))
filepath.WalkDir(root, func(file string, e fs.DirEntry, err error) error {
if err != nil {
return nil
}
if e.IsDir() {
if n := e.Name(); n == ".git" || n == "vendor" || n == "node_modules" || n == "testdata" {
return filepath.SkipDir
}
return nil
}
if e.Name() != "go.mod" {
return nil
}
if raw, err := os.ReadFile(file); err == nil {
addReqs(raw)
}
return nil
})
}
if len(want) == 0 {
return nil
}
byModule := map[string][]string{} // a module path and the manifest-named directories whose go.mod declares it
for _, cand := range manifestDirs(tree) {
if mod := goModulePath(filepath.Join(tree, filepath.FromSlash(cand), "go.mod")); mod != "" && !slices.Contains(byModule[mod], cand) {
byModule[mod] = append(byModule[mod], cand)
}
}
var out []string
done := map[string]bool{}
for len(want) > len(done) {
for _, mod := range slices.Sorted(maps.Keys(want)) {
if done[mod] {
continue
}
done[mod] = true
for _, cand := range byModule[mod] {
if slices.Contains(out, cand) {
continue
}
out = append(out, cand)
if raw, err := os.ReadFile(filepath.Join(tree, filepath.FromSlash(cand), "go.mod")); err == nil {
addReqs(raw) // what this package requires of the repository comes along (H-A-202)
}
}
}
}
slices.Sort(out)
return out
}
// manifestDirs are the directories the manifests of the tree name, from its root: each module's directory and the
// directory of each of its artifacts' named paths.
func manifestDirs(tree string) []string {
var out []string
filepath.WalkDir(tree, func(file string, e fs.DirEntry, err error) error {
if err != nil {
return nil
}
if e.IsDir() {
if n := e.Name(); n == ".git" || n == "vendor" || n == "node_modules" || n == "testdata" {
return filepath.SkipDir
}
return nil
}
if e.Name() != "module.json" {
return nil
}
rel, err := filepath.Rel(tree, filepath.Dir(file))
if err != nil {
return nil
}
mdir := filepath.ToSlash(rel)
out = append(out, mdir)
raw, err := os.ReadFile(file)
if err != nil {
return nil
}
man, err := catalogue.Decode(raw)
if err != nil || man.Build == nil {
return nil
}
for _, a := range man.Build.Artifacts {
for _, p := range a.Paths {
out = append(out, path.Join(mdir, filepath.ToSlash(p)))
}
}
return nil
})
return out
}
// goModulePath is the module path the go.mod file declares, "" when there is none.
func goModulePath(file string) string {
raw, err := os.ReadFile(file)
if err != nil {
return ""
}
for _, line := range strings.Split(string(raw), "\n") {
if f := strings.Fields(line); len(f) == 2 && f[0] == "module" {
return strings.Trim(f[1], `"`)
}
}
return ""
}
@@ -45,6 +45,28 @@ func TestAFetchWithNamedPathsNarrowsTheWorkspace(t *testing.T) {
if strings.Join(res.Modules, ",") != "lib" {
t.Errorf("the fetch answered the modules %v, want lib alone", res.Modules)
}
// A tree shaped like mesh-delivery's: the narrowed artifact requires another module of its repository at the zero
// version: the narrowed workspace keeps its directory, found by its manifest, and the fetch resolves it there (design
// 47 H, H-A-136; live 2026-11-20, pipeline main.3).
const sdk = "git.novox.be/novox/narrowown/modules/sdk"
_, ownHead := f.repo("novox/narrowown", map[string]string{
"modules/sdk/go.mod": "module " + sdk + "\n\ngo 1.25.0\n",
"modules/sdk/module.json": `{"module":"sdk","version":"1"}`,
"modules/sdk/s.go": "package sdk\n\nconst S = 1\n",
"modules/c/module.json": `{"module":"c","version":"1"}`,
"modules/c/go/x/go.mod": "module git.novox.be/novox/narrowown/modules/c/go/x\n\ngo 1.25.0\n\nrequire " + sdk + " v0.0.0-00010101000000-000000000000\n",
"modules/c/go/x/x.go": "package x\n\nimport \"" + sdk + "\"\n\nconst X = sdk.S\n",
})
res, st = fetched(t, m, states, map[string]any{"repository": "novox/narrowown", "commit": ownHead, "dir": "modules/c", "paths": []any{"go/x"}})
if st.State != sdkstep.StepPassed {
t.Fatalf("the fetch of an artifact requiring its repository's other module ended %s: %s", st.State, st.Reason)
}
if _, err := os.Stat(filepath.Join(m.Work, res.Workspace, "tree", "modules", "sdk", "s.go")); err != nil {
t.Errorf("the narrowed workspace lacks the required package of its repository: %v", err)
}
if strings.Join(res.Modules, ",") != "modules/c/go/x" {
t.Errorf("the fetch answered the modules %v, want modules/c/go/x alone", res.Modules)
}
_, st = fetched(t, m, states, map[string]any{"repository": "novox/narrow", "commit": head, "dir": "", "paths": []any{"cmd"}})
if st.State != sdkstep.StepFailed || !strings.Contains(st.Reason, "no module directory") {
t.Errorf("paths without a directory: %s %q", st.State, st.Reason)
@@ -0,0 +1,197 @@
package main
import (
"os"
"path/filepath"
"slices"
"strings"
"testing"
sdkstep "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/seatgen"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/steprun"
)
func writeFile(t *testing.T, file, body string) {
t.Helper()
if err := os.MkdirAll(filepath.Dir(file), 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(file, []byte(body), 0o644); err != nil {
t.Fatal(err)
}
}
// Design 47 H, lead answer H-A-136 (live 2026-11-20, the first pipeline main.3): a workspace narrowed to an artifact's
// named paths also holds every generated-from directory an artifact of its module names (the seat definitions the
// generated package is compared against) and the directory, with its go.mod, of every package of the same repository the
// artifact's go.mod requires at the zero version, found by that repository's manifests; nothing else. The fetch's Go
// modules stay the artifact's own (A-447a): neither the generated-from directory's nor the sibling package's.
func TestANarrowedWorkspaceHoldsTheGeneratedFromDirectoriesAndItsRepositorysZeroVersionPackages(t *testing.T) {
const sdk = "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk"
const repo = "git.novox.be/novox/mesh-delivery"
zero := " v0.0.0-00010101000000-" + zeroShort
for _, tc := range []struct {
name, dir string
paths []string
files map[string]string
kept, gone []string
modules []string
seats []string // generated into the tree by the seat generator, its out-of-step check then finding nothing
refused string // the narrowing fails naming this
}{
{name: "a generated-from directory", dir: "modules/c", paths: []string{"go/seats/a"},
files: map[string]string{
"modules/c/module.json": `{"module":"c","build":{"artifacts":[{"name":"go-a","kind":"package","language":"go","paths":["go/seats/a"],"generated-from":"seats"},{"name":"go-b","kind":"package","language":"go","paths":["go/seats/b"],"generated-from":"seats"}]}}`,
"modules/c/seats/a.json": "{}\n",
"modules/c/go/seats/a/go.mod": "module git.novox.be/novox/mesh-delivery/modules/c/go/seats/a\n\ngo 1.26\n",
"modules/c/go/seats/b/go.mod": "module git.novox.be/novox/mesh-delivery/modules/c/go/seats/b\n\ngo 1.26\n",
"modules/c/docs/x.md": "not named\n",
"modules/d/module.json": `{"module":"d"}`,
},
kept: []string{"modules/c/module.json", "modules/c/seats/a.json", "modules/c/go/seats/a/go.mod"},
gone: []string{"modules/c/go/seats/b", "modules/c/docs", "modules/d"},
modules: []string{"modules/c/go/seats/a"}},
{name: "the module's own directory as generated-from", dir: "modules/c", paths: []string{"go/seats/a"},
files: map[string]string{
"modules/c/module.json": `{"module":"c","build":{"artifacts":[{"name":"go-a","kind":"package","language":"go","paths":["go/seats/a"],"generated-from":"."}]}}`,
"modules/c/seats/a.json": "{}\n",
"modules/c/go/seats/a/go.mod": "module git.novox.be/novox/mesh-delivery/modules/c/go/seats/a\n\ngo 1.26\n",
"modules/c/go/seats/b/go.mod": "module git.novox.be/novox/mesh-delivery/modules/c/go/seats/b\n\ngo 1.26\n",
"modules/d/module.json": `{"module":"d"}`,
},
kept: []string{"modules/c/seats/a.json", "modules/c/go/seats/b/go.mod"},
gone: []string{"modules/d"},
modules: []string{"modules/c/go/seats/a"}},
{name: "a module at the repository's root with generated-from \".\"", dir: ".", paths: []string{"go/seats/onestore"},
files: map[string]string{
"module.json": `{"module":"mesh-contracts","build":{"artifacts":[{"name":"go-onestore","kind":"package","language":"go","paths":["go/seats/onestore"],"generated-from":"."},{"name":"go-twostore","kind":"package","language":"go","paths":["go/seats/twostore"],"generated-from":"."},{"name":"ts-onestore","kind":"package","language":"typescript","paths":["ts/seats/onestore"],"generated-from":"."},{"name":"ts-twostore","kind":"package","language":"typescript","paths":["ts/seats/twostore"],"generated-from":"."},{"name":"go-other","kind":"package","language":"go","paths":["go/other"]}]}}`,
"README.md": "the repository\n",
"docs/a.md": "not named\n",
"go/other/go.mod": "module git.novox.be/novox/mesh-contracts/go/other\n\ngo 1.26\n",
"modules/x/module.json": `{"module":"x"}`,
},
seats: []string{"one-store", "two-store"},
kept: []string{"module.json", "seats/one-store/seat.json", "seats/two-store/seat.json", "go/seats/onestore/go.mod", "go/seats/twostore/contract.go", "ts/seats/twostore/package.json"},
gone: []string{"README.md", "docs", "go/other", "modules"},
modules: []string{"go/seats/onestore"}},
{name: "a package of the same repository at the zero version", dir: "modules/mesh-delivery-contracts",
paths: []string{"go/clients/meshcatalogclient"},
files: map[string]string{
"module.json": `{"module":"root"}`,
"go.sum": "root\n",
"modules/mesh-delivery-contracts/module.json": `{"module":"mesh-delivery-contracts","build":{"artifacts":[{"name":"go-meshcatalogclient","kind":"package","language":"go","paths":["go/clients/meshcatalogclient"]}]}}`,
"modules/mesh-delivery-contracts/go/clients/meshcatalogclient/go.mod": "module git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient\n\ngo 1.26\n\nrequire (\n\t" + sdk + zero + "\n\tgit.novox.be/novox/mesh-sdk/go" + zero + "\n)\n",
"modules/mesh-delivery-contracts/go/clients/meshcatalogclient/c.go": "package meshcatalogclient\n",
"modules/mesh-delivery-contracts/go/clients/other/go.mod": "module git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/other\n\ngo 1.26\n",
"modules/mesh-delivery-sdk/module.json": `{"module":"mesh-delivery-sdk","build":{"artifacts":[{"name":"go-sdk","kind":"package","language":"go"}]}}`,
"modules/mesh-delivery-sdk/go.mod": "module " + sdk + "\n\ngo 1.26\n",
"modules/mesh-delivery-sdk/steprun/s.go": "package steprun\n",
"modules/mesh-delivery-view/module.json": `{"module":"mesh-delivery-view"}`,
"modules/mesh-delivery-view/go.mod": "module git.novox.be/novox/mesh-delivery/modules/mesh-delivery-view\n\ngo 1.26\n",
},
kept: []string{"modules/mesh-delivery-contracts/module.json", "modules/mesh-delivery-contracts/go/clients/meshcatalogclient/c.go",
"modules/mesh-delivery-sdk/go.mod", "modules/mesh-delivery-sdk/steprun/s.go"},
gone: []string{"module.json", "go.sum", "modules/mesh-delivery-view", "modules/mesh-delivery-contracts/go/clients/other"},
modules: []string{"modules/mesh-delivery-contracts/go/clients/meshcatalogclient"}},
// H-A-202, H-A-198: the packages of the repository a required one requires at the zero version come along too,
// transitively (state -> builds -> client), each found by its manifest.
{name: "the repository's packages a required package requires, transitively", dir: "modules/a", paths: []string{"state"},
files: map[string]string{
"modules/a/module.json": `{"module":"a","build":{"artifacts":[{"name":"state","kind":"package","language":"go","paths":["state"]}]}}`,
"modules/a/state/go.mod": "module " + repo + "/modules/a/state\n\ngo 1.26\n\nrequire " + repo + "/modules/b/builds" + zero + "\n",
"modules/a/state/s.go": "package state\n",
"modules/b/module.json": `{"module":"b","build":{"artifacts":[{"name":"builds","kind":"package","language":"go","paths":["builds"]}]}}`,
"modules/b/builds/go.mod": "module " + repo + "/modules/b/builds\n\ngo 1.26\n\nrequire (\n\t" + repo + "/modules/c/client" + zero + "\n\tgit.novox.be/novox/mesh-sdk/go" + zero + "\n)\n",
"modules/b/builds/b.go": "package builds\n",
"modules/b/other/o.go": "package other\n",
"modules/c/module.json": `{"module":"c","build":{"artifacts":[{"name":"client","kind":"package","language":"go","paths":["client"]}]}}`,
"modules/c/client/go.mod": "module " + repo + "/modules/c/client\n\ngo 1.26\n\nrequire " + repo + "/modules/b/builds" + zero + "\n",
"modules/c/client/c.go": "package client\n",
"modules/c/other/o.go": "package other\n",
"modules/d/module.json": `{"module":"d"}`,
},
kept: []string{"modules/a/state/s.go", "modules/b/builds/b.go", "modules/c/client/c.go"},
gone: []string{"modules/b/other", "modules/c/other", "modules/d"},
modules: []string{"modules/a/state"}},
// A named path that leaves the repository is refused.
{name: "a named path that leaves the repository", dir: "mesh-grants", paths: []string{".", "../../outside"},
files: map[string]string{"mesh-grants/module.json": `{"module":"mesh-grants"}`, "mesh-grants/go.mod": "module mesh-grants\n\ngo 1.26\n"},
refused: `"../../outside" leaves`},
{name: "a named path that leaves the repository from a nested module", dir: "modules/mesh-grants", paths: []string{"../../../outside"},
files: map[string]string{"modules/mesh-grants/module.json": `{"module":"mesh-grants"}`, "modules/mesh-grants/go.mod": "module mesh-grants\n\ngo 1.26\n"},
refused: `"../../../outside" leaves`},
} {
t.Run(tc.name, func(t *testing.T) {
tree := t.TempDir()
var all []string
for f, body := range tc.files {
os.MkdirAll(filepath.Join(tree, filepath.Dir(f)), 0o755)
if err := os.WriteFile(filepath.Join(tree, f), []byte(body), 0o644); err != nil {
t.Fatal(err)
}
if filepath.Base(f) == "go.mod" {
all = append(all, filepath.Dir(f))
}
}
if len(tc.seats) > 0 {
for _, seat := range tc.seats {
writeFile(t, filepath.Join(tree, "seats", seat, "seat.json"), `{"format":1,"seat":"`+seat+`","scope":"mesh","grain":"whole","domain":"Module","decision":"ADR 1","verbs":[{"name":"query","input":{"type":"object"},"answer":{"type":"object"}}]}`)
}
g, err := seatgen.Load(tree, "git.novox.be/novox/mesh-contracts/go", "@novox/mesh-contracts")
if err != nil {
t.Fatal(err)
}
files, err := seatgen.Generate(g)
if err != nil {
t.Fatal(err)
}
for f, b := range files {
writeFile(t, filepath.Join(tree, f), string(b))
if filepath.Base(f) == "go.mod" {
all = append(all, filepath.Dir(f))
}
}
}
req := sdkstep.FetchRequest{Repository: "novox/mesh-delivery", Commit: commitSHA, Dir: tc.dir, Paths: tc.paths}
err := narrowTree(tree, req.Repository, req)
if tc.refused != "" {
if err == nil || !strings.Contains(err.Error(), tc.refused) {
t.Fatalf("the narrowing answered %v, want it refused naming %s", err, tc.refused)
}
return
}
if err != nil {
t.Fatal(err)
}
for _, k := range tc.kept {
if _, err := os.Stat(filepath.Join(tree, k)); err != nil {
t.Errorf("%s was narrowed away: %v", k, err)
}
}
for _, g := range tc.gone {
if _, err := os.Stat(filepath.Join(tree, g)); err == nil {
t.Errorf("%s is still in the workspace", g)
}
}
if len(tc.seats) > 0 {
for _, root := range []string{steprun.GeneratedRootGo, steprun.GeneratedRootTS} {
if out, err := steprun.OutOfStep(filepath.Join(tree, tc.dir), root); err != nil || len(out) != 0 {
t.Errorf("the seat generator's check in the narrowed workspace, root %s: %v %v, want nothing out of step", root, out, err)
}
}
}
var left []string
for _, d := range all {
if _, err := os.Stat(filepath.Join(tree, d, "go.mod")); err == nil {
left = append(left, d)
}
}
slices.Sort(left)
got, err := scopedDirs(tree, tc.dir, tc.paths, left)
if err != nil || strings.Join(got, ",") != strings.Join(tc.modules, ",") {
t.Errorf("the fetch's Go modules = %v (%v), want %v", got, err, tc.modules)
}
})
}
}
@@ -63,7 +63,7 @@ func TestACheckAskReachesTheTestStepPastItsPackages(t *testing.T) {
}
}
}
a := sdkstep.StepAsk{ID: sdkstep.NewID(), Kind: sdkstep.AskCheck, Language: sdkstep.AskGo, Asker: "mesh-delivery-checker",
a := sdkstep.StepAsk{ID: sdkstep.NewID(), Kind: sdkstep.AskCheck, Language: sdkstep.AskGo, Asker: "mesh-delivery-runner",
At: time.Now(), Check: &sdkstep.CheckJob{Fetch: sdkstep.Fetch{Repository: "novox/x", Commit: askCommit}, Levels: []string{sdkstep.LevelUnit}}}
out, err := steprun.RunAsk(context.Background(), m.askSteps(steps), a)
got := ""
@@ -365,9 +365,9 @@ func (m *Module) takeReplacedZeroPins(ctx context.Context, root, repository, dir
}
// takeZeroRequirements takes, for each requirement at the zero version, the version it is built against (ADR 0573 §2,
// §4: whatever go.mod names): the commit the ask names for the package; else the head of the package's repository among
// the asked versions (the check's or try's members: another package of the same repository names it); else the latest
// published version, the trunk's head. It never looks for the commit 000000000000 among the pull request heads. One
// §4: whatever go.mod names): a module of the checked repository from the fetched tree (H-A-198); any other at the pin
// the ask names for that package path, and with no pin it refuses the build, never taking another path's version or
// the latest (design 47 H, H-A-192). It never looks for the commit 000000000000 among the pull request heads. One
// taken before (dir's modfile requires or replaces it) is left as it is.
func (m *Module) takeZeroRequirements(ctx context.Context, root, repository, dir, d string, reqs []zeroRequirement, asked sdkstep.PackageVersions, pins *sync.Mutex) ([]TakenVersion, error) {
resolved := map[string]string{}
@@ -409,13 +409,13 @@ func (m *Module) takeZeroRequirements(ctx context.Context, root, repository, dir
taken = append(taken, tv)
continue
}
tv := TakenVersion{Dir: d, Package: p.module, Asked: askedFor(asked, p), Named: named}
why := "the ask names it"
// The ask's pin for this path alone: a build module given no pin refuses the build, loud, and never takes another
// path's version nor the latest (design 47 H, H-A-192).
tv := TakenVersion{Dir: d, Package: p.module, Asked: asked[p.module], Named: named}
if tv.Asked == "" {
tv.Asked, why = "latest", "the ask names no commit of its repository, so its latest published version"
} else if _, ok := asked[p.module]; !ok {
why = "the head of its repository among the asked versions"
return taken, fmt.Errorf("no pin for %s: the builder pins or waits (H-A-192)", p.module)
}
why := "the ask names it"
if err := m.takeVersion(ctx, root, dir, &tv, pins); err != nil {
return taken, fmt.Errorf("the requirement of %s at the zero version: %w", p.module, err)
}
@@ -431,20 +431,6 @@ func (m *Module) takeZeroRequirements(ctx context.Context, root, repository, dir
// namedBySaid says that a module dir replaces by the directory by names a package, and dir's go.mod does not.
func namedBySaid(by string) string { return "named by " + by + ", not by this go.mod" }
// askedFor is the commit the ask names for the package p: its own, else that of the first package of the same repository
// in order (the members' heads are by repository), else none.
func askedFor(asked sdkstep.PackageVersions, p pin) string {
if c := asked[p.module]; c != "" {
return c
}
for _, pkg := range slices.Sorted(maps.Keys(asked)) {
if pkg == forgePrefix+p.repo || strings.HasPrefix(pkg, forgePrefix+p.repo+"/") {
return asked[pkg]
}
}
return ""
}
// useOwnModules replaces, in dir's temporary modfile, every module of the fetched tree whose path lies in the repository
// repo by its directory in the tree (once), and answers the paths of those modules. A replace of a module dir does not
// require is harmless to Go; one module of a repository requires another of it at the zero version.
@@ -6,6 +6,7 @@ import (
"os"
"os/exec"
"path/filepath"
"slices"
"strings"
"sync"
"testing"
@@ -300,10 +301,10 @@ func TestARelativeReplaceStillResolvesInTheTemporaryModfile(t *testing.T) {
}
// A go.mod requirement at the zero version v0.0.0-00010101000000-000000000000 names no commit (ADR 0573 §2, §4: whatever
// go.mod names): it is taken from the commit the ask names for the package, else from the head of its repository among
// the asked versions, else from the trunk's latest published version, and never looked for as the commit 000000000000
// among the pull request heads.
func TestARequirementAtTheZeroVersionIsTakenFromTheAskOrTheTrunk(t *testing.T) {
// go.mod names): it is taken from the pin the ask names for that package path alone, and never looked for as the commit
// 000000000000 among the pull request heads. With no pin of its own the build is refused, loud, naming the path: never
// built at another package's pin of the same repository nor at the latest (design 47 H, H-A-192).
func TestARequirementAtTheZeroVersionIsTakenFromItsPinOrRefused(t *testing.T) {
t.Parallel()
const sdk = "git.novox.be/novox/mesh-sdk/go"
zeroMod := "module fixture/member\n\ngo 1.26\n\nrequire (\n\t" + sdk + " v0.0.0-00010101000000-" + zeroShort + "\n)\n"
@@ -313,6 +314,7 @@ func TestARequirementAtTheZeroVersionIsTakenFromTheAskOrTheTrunk(t *testing.T) {
packages map[string]any
download string // what go mod download -json answers
want string // the version asked of go
refused bool // the step fails, naming the path: the ask carries no pin for it (H-A-192)
head bool // the asked commit is on no trunk: only a pull request head carries it
// replaced: the directory's go.mod names no mesh package; a module it replaces by a directory of the tree requires
// it at the zero version, so go mod download passes and only a shut-off package load would look it up (1966/AC178-1)
@@ -320,18 +322,14 @@ func TestARequirementAtTheZeroVersionIsTakenFromTheAskOrTheTrunk(t *testing.T) {
}{
{name: "the ask names the package", packages: map[string]any{sdk: trunk}, want: sdk + "@" + trunk,
download: `{"Version":"v0.1.15-0.20261101000000-aaaaaaaaaaaa","Sum":"h1:zip="}`},
{name: "the ask names another package of its repository", packages: map[string]any{"git.novox.be/novox/mesh-sdk/other": trunk}, want: sdk + "@" + trunk,
download: `{"Version":"v0.1.15-0.20261101000000-aaaaaaaaaaaa","Sum":"h1:zip="}`},
{name: "the ask names the root of its repository, which no package of is published", packages: map[string]any{"git.novox.be/novox/mesh-sdk": trunk}, want: sdk + "@" + trunk,
download: `{"Version":"v0.1.15-0.20261101000000-aaaaaaaaaaaa","Sum":"h1:zip="}`},
{name: "the ask pins only another package of its repository", packages: map[string]any{"git.novox.be/novox/mesh-sdk/other": trunk}, refused: true},
{name: "the ask pins only the root of its repository", packages: map[string]any{"git.novox.be/novox/mesh-sdk": trunk}, refused: true},
{name: "the ask names the head of a pull request", packages: map[string]any{sdk: commitSHA}, want: sdk + "@" + commitSHA, head: true},
{name: "the ask names nothing of its repository", packages: map[string]any{"git.novox.be/novox/mesh-tools/go": trunk}, want: sdk + "@latest",
download: `{"Version":"v0.1.20-0.20261104000000-bbbbbbbbbbbb","Sum":"h1:zip="}`},
{name: "no ask", want: sdk + "@latest", download: `{"Version":"v0.1.20-0.20261104000000-bbbbbbbbbbbb","Sum":"h1:zip="}`},
{name: "the ask names nothing of its repository", packages: map[string]any{"git.novox.be/novox/mesh-tools/go": trunk}, refused: true},
{name: "no ask", refused: true},
{name: "named only by a module the directory replaces, the ask names it", packages: map[string]any{sdk: trunk}, want: sdk + "@" + trunk, replaced: true,
download: `{"Version":"v0.1.15-0.20261101000000-aaaaaaaaaaaa","Sum":"h1:zip="}`},
{name: "named only by a module the directory replaces, no ask", want: sdk + "@latest", replaced: true,
download: `{"Version":"v0.1.20-0.20261104000000-bbbbbbbbbbbb","Sum":"h1:zip="}`},
{name: "named only by a module the directory replaces, no ask", replaced: true, refused: true},
} {
t.Run(c.name, func(t *testing.T) {
gomod := zeroMod
@@ -374,6 +372,15 @@ func TestARequirementAtTheZeroVersionIsTakenFromTheAskOrTheTrunk(t *testing.T) {
t.Fatal(err)
}
st := states.waitEnd(t)
if c.refused {
if st.State == sdkstep.StepPassed || !strings.Contains(st.Reason, "no pin for "+sdk) {
t.Fatalf("the step ended %s (%s), want it failed naming no pin for %s", st.State, st.Reason, sdk)
}
if h.ran(" mod download -json " + sdk + "@") {
t.Errorf("go was asked for a version of %s with no pin:\n%s", sdk, strings.Join(h.f.lines(), "\n"))
}
return
}
if st.State != sdkstep.StepPassed {
t.Fatalf("the step ended %s: %s", st.State, st.Reason)
}
@@ -400,39 +407,84 @@ func TestARequirementAtTheZeroVersionIsTakenFromTheAskOrTheTrunk(t *testing.T) {
// A requirement at the zero version of a module of the checked repository itself (a nested module not yet published, which
// another module of the repository requires) is built from the fetched tree, and never asked of Go or the forge (issue 1921).
// Narrowed: a fetch of one artifact of a tree shaped like mesh-delivery's (modules/mesh-delivery-contracts/go/clients/<c>
// requiring modules/mesh-delivery-sdk at the zero version), asked with the module's directory and the artifact's paths,
// keeps the sdk's directory, found by its manifest, and resolves it there (design 47 H, H-A-136; live 2026-11-20,
// pipeline main.3: "no module of that path is in the fetched tree of novox/mesh-delivery").
func TestARequirementAtTheZeroVersionOfTheCheckedRepositorysOwnModuleIsTakenFromItsTree(t *testing.T) {
const own = "git.novox.be/novox/mesh-delivery/nested/go"
zeroMod := "module fixture/member\n\ngo 1.26\n\nrequire (\n\t" + own + " v0.0.0-00010101000000-" + zeroShort + "\n)\n"
h, states := newPinHarness(t, zeroMod, false, pullList)
base := h.m.Run
h.m.Run = func(ctx context.Context, env []string, name string, args ...string) forgekey.Ran {
line := name + " " + strings.Join(args, " ")
if name == "go" && strings.Contains(line, " mod download") && !strings.Contains(strings.Join(env, " "), "-modfile=") {
trees, _ := filepath.Glob(filepath.Join(h.m.Work, "*", "tree"))
for _, tree := range trees {
os.MkdirAll(filepath.Join(tree, "nested", "go"), 0o755)
os.WriteFile(filepath.Join(tree, "nested", "go", "go.mod"), []byte("module "+own+"\n\ngo 1.26\n"), 0o644)
for _, tc := range []struct {
name, own, ownDir, gomods string
args map[string]any
narrowed bool
}{
{name: "whole tree", own: "git.novox.be/novox/mesh-delivery/nested/go", ownDir: "nested/go", gomods: "go.mod\n",
args: map[string]any{"repository": "novox/mesh-delivery", "commit": commitSHA}},
{name: "narrowed to an artifact's paths", own: "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk",
ownDir: "modules/mesh-delivery-sdk", gomods: "modules/mesh-delivery-contracts/go/clients/meshcatalogclient/go.mod\n",
args: map[string]any{"repository": "novox/mesh-delivery", "commit": commitSHA, "dir": "modules/mesh-delivery-contracts",
"paths": []any{"go/clients/meshcatalogclient"}}, narrowed: true},
} {
t.Run(tc.name, func(t *testing.T) {
zeroMod := "module fixture/member\n\ngo 1.26\n\nrequire (\n\t" + tc.own + " v0.0.0-00010101000000-" + zeroShort + "\n)\n"
h, states := newPinHarness(t, zeroMod, false, pullList)
h.f.gomods = tc.gomods
base := h.m.Run
h.m.Run = func(ctx context.Context, env []string, name string, args ...string) forgekey.Ran {
line := name + " " + strings.Join(args, " ")
if name == "git" && strings.Contains(line, " checkout ") && tc.narrowed {
r := base(ctx, env, name, args...)
tree := args[slices.Index(args, "-C")+1]
for f, body := range map[string]string{
"modules/mesh-delivery-sdk/go.mod": "module " + tc.own + "\n\ngo 1.26\n",
"modules/mesh-delivery-sdk/module.json": `{"module":"mesh-delivery-sdk","build":{"artifacts":[{"name":"go-sdk","kind":"package","language":"go"}]}}`,
"modules/mesh-delivery-contracts/module.json": `{"module":"mesh-delivery-contracts","build":{"artifacts":[{"name":"go-meshcatalogclient","kind":"package","language":"go","paths":["go/clients/meshcatalogclient"]}]}}`,
"modules/mesh-delivery-view/go.mod": "module git.novox.be/novox/mesh-delivery/modules/mesh-delivery-view\n\ngo 1.26\n",
} {
os.MkdirAll(filepath.Join(tree, filepath.Dir(f)), 0o755)
os.WriteFile(filepath.Join(tree, f), []byte(body), 0o644)
}
return r
}
if name == "go" && strings.Contains(line, " mod download") && !strings.Contains(strings.Join(env, " "), "-modfile=") {
if !tc.narrowed {
trees, _ := filepath.Glob(filepath.Join(h.m.Work, "*", "tree"))
for _, tree := range trees {
os.MkdirAll(filepath.Join(tree, tc.ownDir), 0o755)
os.WriteFile(filepath.Join(tree, tc.ownDir, "go.mod"), []byte("module "+tc.own+"\n\ngo 1.26\n"), 0o644)
}
}
return forgekey.Ran{Status: 1, Stderr: "go: " + tc.own + "@v0.0.0-00010101000000-" + zeroShort + ": invalid version: unknown revision " + zeroShort + "\n"}
}
return base(ctx, env, name, args...)
}
return forgekey.Ran{Status: 1, Stderr: "go: " + own + "@v0.0.0-00010101000000-" + zeroShort + ": invalid version: unknown revision " + zeroShort + "\n"}
}
return base(ctx, env, name, args...)
}
if _, err := fetchTool(t, h.m)(map[string]any{"repository": "novox/mesh-delivery", "commit": commitSHA}); err != nil {
t.Fatal(err)
}
st := states.waitEnd(t)
if st.State != sdkstep.StepPassed {
t.Fatalf("the step ended %s: %s", st.State, st.Reason)
}
modfiles, _ := filepath.Glob(filepath.Join(h.m.Work, "*", "pins", "*", "go.mod"))
if len(modfiles) != 1 {
t.Fatalf("modfiles = %v", modfiles)
}
body, _ := os.ReadFile(modfiles[0])
if !strings.Contains(string(body), "replace "+own+" => "+filepath.Join(filepath.Dir(filepath.Dir(filepath.Dir(modfiles[0]))), "tree", "nested", "go")) {
t.Errorf("the module of the tree was not replaced into the modfile:\n%s", body)
}
if h.ran(" mod download -json ") || h.ran("ls-remote") {
t.Error("a module of the checked repository was asked of Go or looked for among the pull request heads")
if _, err := fetchTool(t, h.m)(tc.args); err != nil {
t.Fatal(err)
}
st := states.waitEnd(t)
if st.State != sdkstep.StepPassed {
t.Fatalf("the step ended %s: %s", st.State, st.Reason)
}
modfiles, _ := filepath.Glob(filepath.Join(h.m.Work, "*", "pins", "*", "go.mod"))
if len(modfiles) != 1 {
t.Fatalf("modfiles = %v", modfiles)
}
root := filepath.Dir(filepath.Dir(filepath.Dir(modfiles[0])))
where := filepath.Join(root, "tree", filepath.FromSlash(tc.ownDir))
if tc.narrowed {
if _, err := os.Stat(filepath.Join(root, "tree", "modules", "mesh-delivery-view")); err == nil {
t.Error("the narrowed tree holds a module the artifact does not require")
}
}
body, _ := os.ReadFile(modfiles[0])
if !strings.Contains(string(body), "replace "+tc.own+" => "+where+"\n") {
t.Errorf("the module of the repository was not replaced into the modfile by %s:\n%s", where, body)
}
if strings.Count(string(body), "replace ") != 1 {
t.Errorf("the modfile replaces more than the one other module (its own directory again?):\n%s", body)
}
if h.ran(" mod download -json ") || h.ran("ls-remote") {
t.Error("a module of the checked repository was asked of Go or looked for among the pull request heads")
}
})
}
}
+5 -10
View File
@@ -19,7 +19,7 @@ import (
"path/filepath"
"strings"
checker "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdeliverychecker"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
sdkstep "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/steprun"
)
@@ -50,22 +50,21 @@ func (m *Module) run(ctx context.Context, fetch steprun.StepFunc, a sdkstep.Step
}
// inputOf is the input a run names, asked of the seat verb the ask names (module.json invokes it) and checked against
// its digest and size: bytes that are not the input named refuse the ask. A verb marked chunks (the seat mesh-catalog's
// its digest and size: bytes that are not the input named refuse the ask. A verb marked chunks (the seats mesh-catalog's and mesh-wants'
// input, of any size) is asked by the plain seat call: the tool runner receives the chunks and hands this module the
// whole file in the member `file` (design 47 G A-237, A-249); another seat's input answers its bytes in `input`.
// whole file in the member `file` (design 47 G A-237, A-249).
func (m *Module) inputOf(in sdkstep.RunInput) ([]byte, error) {
if m.AskInput == nil {
return nil, errors.New("this module asks no seat verb for a run's input")
}
// A verb that does not answer fails the step; an answer that is not the input named refuses the ask.
raw, err := m.AskInput(in.Verb, checker.InputInput{Digest: in.Digest})
raw, err := m.AskInput(in.Verb, meshwants.InputInput{Digest: in.Digest})
if err != nil {
return nil, fmt.Errorf("asking %s for the input %s: %w", in.Verb, in.Digest, err)
}
var a struct {
Digest string `json:"digest"`
File string `json:"file"`
Input string `json:"input"`
}
if err := json.Unmarshal(raw, &a); err != nil {
return nil, steprun.Refuse("%s answered no input for %s: %v", in.Verb, in.Digest, err)
@@ -73,11 +72,7 @@ func (m *Module) inputOf(in sdkstep.RunInput) ([]byte, error) {
if a.Digest != in.Digest {
return nil, steprun.Refuse("%s answered the input %q, asked %s", in.Verb, a.Digest, in.Digest)
}
text := a.File
if text == "" {
text = a.Input
}
body, err := base64.StdEncoding.DecodeString(text)
body, err := base64.StdEncoding.DecodeString(a.File)
if err != nil {
return nil, steprun.Refuse("%s answered the input %s in no base64: %v", in.Verb, in.Digest, err)
}
@@ -16,8 +16,7 @@ import (
"github.com/nats-io/nats.go"
"github.com/nats-io/nats.go/jetstream"
checkerclient "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshdeliverycheckerclient"
checker "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdeliverychecker"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
sdkstep "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/steprun"
"git.novox.be/novox/mesh-sdk/go/testbus"
@@ -25,7 +24,7 @@ import (
// 1921/C3: a run ask put on the Go build seat's check stream is pulled by the module started whole on the real bus and
// answered on its step key <node>.<ask id>: the program, run shut off over its heads and its input (asked by digest of the
// seat verb the ask names, which a fake checker answers on the bus as the checker's verb input does), answers its last
// seat verb the ask names, which a fake assigner answers on the bus as the seat's verb input does), answers its last
// line and exit; a program cannot write under its heads, and one
// that dials the machine's network is shut off, and its key ends failed, the answer kept (design 47 G A-290).
func TestARunAskIsAnsweredOnTheBusAndItsProgramIsShutOff(t *testing.T) {
@@ -63,13 +62,13 @@ func TestARunAskIsAnsweredOnTheBusAndItsProgramIsShutOff(t *testing.T) {
}
m.PlaceHead = func(_ context.Context, h sdkstep.RunHead, dir string) error { return os.MkdirAll(dir, 0o700) }
body := `{"v":1}`
// The checker's verb input on the bus, and the module asking it as the runtime calls a seat verb it invokes.
// The wants seat's verb input on the bus, and the module asking it as the runtime calls a seat verb it invokes.
asked := make(chan string, 4)
sub, err := nc.Subscribe("mesh.seat.mesh-delivery-checker.tool.input", func(msg *nats.Msg) {
var ask checker.InputInput
sub, err := nc.Subscribe("mesh.seat.mesh-wants.tool.input", func(msg *nats.Msg) {
var ask meshwants.InputInput
_ = json.Unmarshal(msg.Data, &ask)
asked <- ask.Digest
reply, _ := json.Marshal(map[string]any{"result": checkerclient.InputAnswerOf([]byte(body))})
reply, _ := json.Marshal(map[string]any{"result": inputAnswerOf([]byte(body))})
_ = msg.Respond(reply)
})
if err != nil {
@@ -81,7 +80,7 @@ func TestARunAskIsAnsweredOnTheBusAndItsProgramIsShutOff(t *testing.T) {
return nil, errors.New("asked " + key)
}
data, _ := json.Marshal(b)
msg, err := nc.Request("mesh.seat.mesh-delivery-checker.tool.input", data, 5*time.Second)
msg, err := nc.Request("mesh.seat.mesh-wants.tool.input", data, 5*time.Second)
if err != nil {
return nil, err
}
@@ -15,8 +15,7 @@ import (
"testing"
"time"
checkerclient "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshdeliverycheckerclient"
checker "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdeliverychecker"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
sdkstep "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/composer"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/steprun"
@@ -25,17 +24,24 @@ import (
const runCommit = "5555555555555555555555555555555555555555"
// runInputVerb is the seat verb a run ask's input is served on, as the checker names it in the ask.
const runInputVerb = checkerclient.InputVerb
// runInputVerb is the seat verb a run ask's input is served on, as the ask names it.
const runInputVerb = "seat:mesh-wants.input"
// answersInput is a seat verb serving body by its digest, as the checker's verb input answers (sdkstep.RunInputAnswer).
// inputAnswerOf is the seat mesh-wants's answer of the input body as the tool runner hands it over: the digest and
// the whole file.
func inputAnswerOf(body []byte) map[string]any {
sum := sha256.Sum256(body)
return map[string]any{"digest": hex.EncodeToString(sum[:]), "chunks": 1, "file": base64.StdEncoding.EncodeToString(body)}
}
// answersInput is a seat verb serving body by its digest, as the seat mesh-wants' verb input answers.
func answersInput(body string) func(key string, b any) (json.RawMessage, error) {
return func(key string, b any) (json.RawMessage, error) {
ask, _ := b.(checker.InputInput)
ask, _ := b.(meshwants.InputInput)
if sum := sha256.Sum256([]byte(body)); key != runInputVerb || ask.Digest != hex.EncodeToString(sum[:]) {
return nil, fmt.Errorf("the checker keeps no input %s", ask.Digest)
return nil, fmt.Errorf("the assigner keeps no input %s", ask.Digest)
}
return json.Marshal(checkerclient.InputAnswerOf([]byte(body)))
return json.Marshal(inputAnswerOf([]byte(body)))
}
}
@@ -45,7 +51,7 @@ func runAskOf(t *testing.T, body string) sdkstep.StepAsk {
if err != nil {
t.Fatal(err)
}
return sdkstep.StepAsk{ID: sdkstep.NewID(), Kind: sdkstep.AskCheck, Language: sdkstep.AskGo, Asker: "mesh-delivery-checker", At: time.Now(),
return sdkstep.StepAsk{ID: sdkstep.NewID(), Kind: sdkstep.AskCheck, Language: sdkstep.AskGo, Asker: "mesh-delivery-runner", At: time.Now(),
Run: &sdkstep.RunJob{Program: sdkstep.RunProgram{Repository: "novox/mesh-delivery", Commit: runCommit, Dir: ".", Package: "./cmd/prog"},
Heads: []sdkstep.RunHead{{Repository: "novox/mesh-sdk", Commit: runCommit}, {Repository: "novox/mesh-host", Commit: runCommit}},
Input: in, Args: []string{"-seats"}}}
@@ -112,7 +118,7 @@ func TestAKeptProgramIsRunOverItsHeadsAndInput(t *testing.T) {
m.Inside, m.Run = true, StepRunner(t.TempDir())
// An input other than the one named is refused, naming it; one the verb does not answer fails the step, saying why.
m.AskInput = func(_ string, b any) (json.RawMessage, error) {
return json.Marshal(checker.InputAnswer{Digest: b.(checker.InputInput).Digest, Input: base64.StdEncoding.EncodeToString([]byte(`{"other":1}`))})
return json.Marshal(map[string]any{"digest": b.(meshwants.InputInput).Digest, "chunks": 1, "file": base64.StdEncoding.EncodeToString([]byte(`{"other":1}`))})
}
if _, err := m.run(context.Background(), fetch, a); err == nil || !strings.Contains(err.Error(), "is not the one the ask names") || !errors.As(err, new(*steprun.Refusal)) {
t.Errorf("a wrong input: %v", err)
@@ -182,22 +188,22 @@ func TestARunsInputIsAskedOfTheVerbTheAskNames(t *testing.T) {
// answersInputOn is answersInput for the seat verb wanted.
func answersInputOn(wanted, body string) func(key string, b any) (json.RawMessage, error) {
return func(key string, b any) (json.RawMessage, error) {
ask, _ := b.(checker.InputInput)
ask, _ := b.(meshwants.InputInput)
if sum := sha256.Sum256([]byte(body)); key != wanted || ask.Digest != hex.EncodeToString(sum[:]) {
return nil, fmt.Errorf("%s keeps no input %s", key, ask.Digest)
}
return json.Marshal(checkerclient.InputAnswerOf([]byte(body)))
return json.Marshal(inputAnswerOf([]byte(body)))
}
}
// Design 47 G A-237, A-249: the input of a run is of any size: the mesh-catalog seat's verb input, marked chunks, is asked by the
// Design 47 G A-237, A-249: the input of a run is of any size: the mesh-wants seat's verb input, marked chunks, is asked by the
// plain seat call and answers {digest, chunks, file}, the file whole as the tool runner received it; the bytes are checked.
func TestARunsInputOfAnySizeIsTakenFromTheChunkedVerb(t *testing.T) {
body := strings.Repeat("0123456789", 300000) // 3 MB
sum := sha256.Sum256([]byte(body))
in := sdkstep.RunInput{Verb: "seat:mesh-catalog.input", Digest: hex.EncodeToString(sum[:]), Size: len(body)}
m := &Module{AskInput: func(key string, b any) (json.RawMessage, error) {
if ask, _ := b.(checker.InputInput); key != in.Verb || ask.Digest != in.Digest {
if ask, _ := b.(meshwants.InputInput); key != in.Verb || ask.Digest != in.Digest {
return nil, fmt.Errorf("%s keeps no input %v", key, b)
}
return json.Marshal(map[string]any{"digest": in.Digest, "chunks": 6, "file": base64.StdEncoding.EncodeToString([]byte(body))})
+1 -2
View File
@@ -9,10 +9,9 @@ require (
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-builder/builds v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/containerimageregistryclient v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshdeliverycheckerclient v0.0.0-00010101000000-000000000000
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/meshcatalog v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdeliverychecker v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/nodebuildgo 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
+4 -2
View File
@@ -33,7 +33,9 @@
}
],
"consumes": [
"mesh-conditions.findings-asked"
"mesh-conditions.findings-asked",
"mesh-catalog.seat-definition-changed",
"mesh-catalog.seat-definition-removed"
],
"invokes": [
"seat:mesh-hand-acts.hand-act",
@@ -41,11 +43,11 @@
"seat:oci-artifact-registry.publish-part",
"seat:go-package-registry.publish",
"seat:go-package-registry.publish-part",
"seat:mesh-delivery-checker.input",
"seat:mesh-catalog.input",
"seat:mesh-wants.input",
"seat:mesh-module-assigner.assignments",
"seat:mesh-catalog.module",
"seat:mesh-catalog.seat-definitions",
"seat:mesh-catalog.entry"
],
"config": {
@@ -31,16 +31,24 @@ func (m *Module) askSteps(steps []StepTool) steprun.AskSteps {
Fetch: byName["build_image_fetch"], Build: byName["build_image_build"], Copy: byName["build_image_copy"],
Release: func(ws string) error { return m.spaces().Release(ws) },
Logf: m.Say,
Node: m.Node,
SayStep: m.sayStep(),
}
}
// sayStep says a step ask's end on this node's subject of the seat (design 47 G §24): an image has no lint, unit or integration
// step (§328), so none is asked of this seat, but the steps of every build module can say their ends, which the kit holds.
func (m *Module) sayStep() func(sdkstep.StepEnded) error {
if m.SayStep != nil {
return m.SayStep
}
return steprun.SayStepOn(sdkstep.AskImage, m.Node, stdio.SeatPublish)
}
// Puller is the module's pull of its seat's asks, on source (the runtime's seat pull when nil).
func (m *Module) Puller(steps []StepTool, source steprun.AskSource) *steprun.Puller {
if source == nil {
source = &steprun.SeatAsks{Language: sdkstep.AskImage, Logf: m.Say}
if m.Callers == nil {
m.Callers = steprun.SeatListCallers(sdkstep.AskImage, m.Say)
}
}
capacity := m.Capacity
// The capacity's own change wakes the puller (issue 1887): the runtime's watch of the config value as mesh-config
@@ -69,7 +77,7 @@ func (m *Module) Puller(steps []StepTool, source steprun.AskSource) *steprun.Pul
if m.SayEvent != nil {
say = steprun.SayOn(sdkstep.AskImage, m.Node, m.SayEvent)
}
return &steprun.Puller{KeepOutput: steprun.KeepOutputIn(m.Outputs), Source: source, Language: sdkstep.AskImage, Say: say, Callers: m.Callers, Node: m.Node, Put: m.Steps, PausePut: m.Pauses, Load: load, ForgetPause: m.ForgetPause, WatchPauses: m.WatchPauses, PauseKeys: m.ReadPauses.Keys,
return &steprun.Puller{KeepOutput: steprun.KeepOutputIn(m.Outputs), Source: source, Language: sdkstep.AskImage, Say: say, Prior: steprun.PriorRuns(m.ReadSteps.Get), Node: m.Node, Put: m.Steps, PausePut: m.Pauses, Load: load, ForgetPause: m.ForgetPause, WatchPauses: m.WatchPauses, PauseKeys: m.ReadPauses.Keys,
Capacity: capacity, SettingsFile: settings, WatchConfig: watch, CoresPerStep: cores, BuildHours: hours, Eligible: m.Eligible, Logf: m.Say,
Run: func(ctx context.Context, a sdkstep.StepAsk) (any, error) {
if err := m.Check(ctx); err != nil {
@@ -11,15 +11,11 @@ import (
func TestPullerSaysTheSeatsEventsOnItsNodesSubject(t *testing.T) {
var subjects []string
m := &Module{Node: "ace", Capacity: func() int { return 0 },
Callers: func(kind string) ([]string, bool) { return []string{"mesh-pipeline-runner"}, kind == "step" },
SayEvent: func(subject string, _ any, _ string) error { subjects = append(subjects, subject); return nil }}
p := m.Puller(nil, steprun.NewFakeAsks())
if p.Say == nil {
t.Fatal("the puller says no event")
}
if got, ok := p.Callers("step"); !ok || len(got) != 1 {
t.Fatalf("the puller checks the callers of %v, %v, not the module's", got, ok)
}
seat, _ := sdkstep.BuildSeat(sdkstep.AskImage)
for _, event := range []string{"ask-taken", "step-progress", "step-ended"} {
if err := p.Say(event, nil, "id"); err != nil {
@@ -24,7 +24,7 @@ func TestTheModuleInvokesTheImageSeatAndHoldsNoRegistry(t *testing.T) {
t.Fatal(err)
}
if want := []string{"seat:mesh-hand-acts.hand-act", "seat:container-image-registry.publish", "seat:container-image-registry.publish-part",
"seat:container-image-registry.mirror", "seat:mesh-module-assigner.assignments", "seat:mesh-catalog.module"}; !slices.Equal(m.Invokes, want) {
"seat:container-image-registry.mirror", "seat:mesh-module-assigner.assignments", "seat:mesh-catalog.module", "seat:mesh-catalog.seat-definitions"}; !slices.Equal(m.Invokes, want) {
t.Errorf("invokes = %v, want %v", m.Invokes, want)
}
// The seat's outcomes a copy waits on; the version comes in the ask, so version.numbered is not heard (design 47 G §413).
@@ -32,6 +32,7 @@ func TestTheModuleInvokesTheImageSeatAndHoldsNoRegistry(t *testing.T) {
for _, e := range OutcomeEvents {
consumes = append(consumes, "container-image-registry."+e)
}
consumes = append(consumes, "mesh-catalog.seat-definition-changed", "mesh-catalog.seat-definition-removed") // the seat list, A-488a
if !slices.Equal(m.Consumes, consumes) {
t.Errorf("consumes = %v, want %v", m.Consumes, consumes)
}
@@ -2,6 +2,7 @@ package main
import (
"context"
"encoding/json"
"errors"
sdkstep "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/steprun"
@@ -44,3 +45,19 @@ func TestTheStepsSayAFailedNetworkAsATransportFault(t *testing.T) {
}
})
}
// A-489b, design 47 G §24: the module's own steps can say a pipeline step's end, or
// every step ask the runner sends it is refused ("this build module says no step's end"), as the first live pipeline met.
func TestTheStepsCanSayAStepsEnd(t *testing.T) {
conformance.StepEnds(t, (&Module{Node: "kitnode"}).askSteps(nil))
}
// A-489c (A-489a): the module's puller counts the runs its steps state says started, not the bus's deliveries (an ask given back before
// it ran is no run), so the poison rule never ends an ask that never ran.
func TestThePullerCountsRunsThatStarted(t *testing.T) {
conformance.RunsCounted(t, func(read func(string) (json.RawMessage, error)) *steprun.Puller {
m := &Module{Node: "kitnode", Capacity: func() int { return 1 }}
m.ReadSteps = StateRead{Get: read}
return m.Puller(nil, steprun.NewFakeAsks())
})
}
@@ -113,6 +113,16 @@ func TestWorkAndStoreDirectoriesLieOutsideTheHome(t *testing.T) {
// and the registry's address is bound into a file of the home that the program reads.
func TestManifestKeepsItsStatesClaimsItsBuildSeatAndDeclaresItsHealthTool(t *testing.T) {
m := readManifest(t)
// Design 47 G A-488a, A-488b: its runtime follows the seat list, so the module consumes the seat's two events (which makes its
// durable consumer) and invokes the verb that reads the list.
for _, ev := range []string{"mesh-catalog.seat-definition-changed", "mesh-catalog.seat-definition-removed"} {
if !slices.Contains(m.Consumes, ev) {
t.Errorf("consumes %v lack %s", m.Consumes, ev)
}
}
if !slices.Contains(m.Invokes, "seat:mesh-catalog.seat-definitions") {
t.Errorf("invokes %v lack seat:mesh-catalog.seat-definitions", m.Invokes)
}
states := []string{}
for _, s := range m.State {
states = append(states, s.Name)
@@ -20,14 +20,13 @@ const CheckRound = 10 * time.Minute
// Module is the image build module's one running state.
type Module struct {
// Callers says which seats the build seat's definition lists as callers of an accepted kind (steprun.SeatListCallers when
// the module pulls through its runtime; nil in a test checks no named asker): design 47 G §543, A-163.
Callers func(kind string) ([]string, bool)
// Outputs is the object store of a run's answers over what step-ended carries inline (steprun.OutputsStore); nil keeps none.
Outputs steprun.OutputObjects
// SayEvent publishes an event of the image build seat on a seat subject (stdio.SeatPublish; nil says none, a test's): the
// puller's ask-taken, step-progress and step-ended (design 47 G §496, §602).
SayEvent func(subject string, body any, id string) error
// SayStep says a step ask's end (steprun.AskSteps.SayStep); the seat's publish on this node when nil (a test's own).
SayStep func(sdkstep.StepEnded) error
Node string
// RecordAct writes an act in the hand-act log of the seat mesh-hand-acts (§463, §480): a drop writes it first.
+5 -2
View File
@@ -68,11 +68,14 @@
"seat:container-image-registry.publish-part",
"seat:container-image-registry.mirror",
"seat:mesh-module-assigner.assignments",
"seat:mesh-catalog.module"
"seat:mesh-catalog.module",
"seat:mesh-catalog.seat-definitions"
],
"consumes": [
"container-image-registry.published",
"container-image-registry.refused"
"container-image-registry.refused",
"mesh-catalog.seat-definition-changed",
"mesh-catalog.seat-definition-removed"
],
"own-secrets": {
"broker": "${dir:state}/broker"
@@ -1,7 +1,7 @@
package main
// What this module keeps on the bus, announced from its code (novox/hq ADR 0495 §2 §5; issue 1790): every state it
// keeps, each readable by others, since another module reads each today (the builder, the checker and the indexer read toolchains; the builder and the checker read steps; gitea reads keys). A state of its own that it
// keeps, each readable by others, since another module reads each today (the builder and the indexer read toolchains; the builder reads steps; gitea reads keys). A state of its own that it
// did not name here is refused at the call (stdio.Keeps).
import (
@@ -41,16 +41,26 @@ func (m *Module) askSteps(steps []StepTool) steprun.AskSteps {
},
Release: func(ws string) error { return m.spaces().Release(ws) },
Logf: m.Say,
Has: m.Has,
Lint: m.lintStep,
Node: m.Node,
SayStep: m.sayStep(),
}
}
// sayStep says a pipeline step's end on this node's subject of the seat (design 47 G §24, *Asked on a work queue, ended by an
// event*): SayStep when a test sets it, else the runtime's seat publish.
func (m *Module) sayStep() func(sdkstep.StepEnded) error {
if m.SayStep != nil {
return m.SayStep
}
return steprun.SayStepOn(sdkstep.AskNode, m.Node, stdio.SeatPublish)
}
// Puller is the module's pull of its seat's asks, on source (the runtime's seat pull when nil).
func (m *Module) Puller(steps []StepTool, source steprun.AskSource) *steprun.Puller {
if source == nil {
source = &steprun.SeatAsks{Language: sdkstep.AskNode, Logf: m.Say}
if m.Callers == nil {
m.Callers = steprun.SeatListCallers(sdkstep.AskNode, m.Say)
}
}
capacity := m.Capacity
// The capacity's own change wakes the puller (issue 1887): the runtime's watch of the config value as mesh-config
@@ -79,7 +89,7 @@ func (m *Module) Puller(steps []StepTool, source steprun.AskSource) *steprun.Pul
if m.SayEvent != nil {
say = steprun.SayOn(sdkstep.AskNode, m.Node, m.SayEvent)
}
return &steprun.Puller{KeepOutput: steprun.KeepOutputIn(m.Outputs), Source: source, Language: sdkstep.AskNode, Say: say, Callers: m.Callers, Node: m.Node, Put: m.Steps, PausePut: m.Pauses, Load: load, ForgetPause: m.ForgetPause, WatchPauses: m.WatchPauses, PauseKeys: m.ReadPauses.Keys,
return &steprun.Puller{KeepOutput: steprun.KeepOutputIn(m.Outputs), Source: source, Language: sdkstep.AskNode, Say: say, Prior: steprun.PriorRuns(m.ReadSteps.Get), Node: m.Node, Put: m.Steps, PausePut: m.Pauses, Load: load, ForgetPause: m.ForgetPause, WatchPauses: m.WatchPauses, PauseKeys: m.ReadPauses.Keys,
Capacity: capacity, SettingsFile: settings, WatchConfig: watch, CoresPerStep: cores, BuildHours: hours, Logf: m.Say,
Run: func(ctx context.Context, a sdkstep.StepAsk) (any, error) {
if err := m.Prepare(ctx); err != nil {

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