From 98f04757fda0879fa544ed0bcd4d3ad9c22cf6f9 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 20 Nov 2026 23:15:37 +0100 Subject: [PATCH] Design 47 H: the pin rule as a specification with its gap table (H1) --- .../47-milestones/H-pins-spec-and-gaps.md | 347 ++++++++++++++++++ 1 file changed, 347 insertions(+) create mode 100644 03-DESIGN/01-to-be/47-milestones/H-pins-spec-and-gaps.md diff --git a/03-DESIGN/01-to-be/47-milestones/H-pins-spec-and-gaps.md b/03-DESIGN/01-to-be/47-milestones/H-pins-spec-and-gaps.md new file mode 100644 index 00000000..9ad3f968 --- /dev/null +++ b/03-DESIGN/01-to-be/47-milestones/H-pins-spec-and-gaps.md @@ -0,0 +1,347 @@ +--- +layer: to-be +status: in-progress +design: 47 +milestone: H +updated: 2026-11-20 +decisions: + - "ADR 0499" + - "ADR 0573" + - "ADR 0682" +--- +# 47, milestone H — the pin rule: its specification and its gaps + +The rule by which a catalog entry pins the mesh packages a module's build resolves, written whole from the lead's +answers H-A-147, 151, 154, 155, 156, 157, 161, 162, 165, 167, 168, 170, 172, 173, 183, 184, 185, 186, 188, 192, 194, +198, 201, 202, 203, 204, 205 and 206 ([H-lead-answers.md](H-lead-answers.md)), G §370 +([G-7-answers.md](G-7-answers.md)), ADR 0499 §1 to §4 and ADR 0573 §2 and §4 (the knowledge base), then held against +the code as it stands after the evening's three fix branches. + +A word first. The glossary's **pin** is a person's choice of provider for a consumer (Provisioning). This file, as the +lead's answers do, uses "pin" for the version a catalog entry names for a mesh package its module's build resolves. +That is a second sense the glossary does not hold; the proposed word is **package pin** (a catalog entry's version of +one mesh package its module's build resolves, its key the package's Go module path), to be added in its own pull +request. Until then "pin" below means the package pin, and "revision pin" means a record keeping a catalog revision +(the indexer's state `pins`). + +## The code read + +| Part | Repository | Read at | +|---|---|---| +| The indexer (seat `mesh-catalog`) | mesh-delivery, module mesh-delivery-indexer | main `b9cc9747` plus branch `fix/47-H1-indexer-repin` at `94202fb6` (commits `0418a2b9`, `94202fb6`); the tool commit said to be in progress was not in the branch's worktree (clean at `94202fb6`) | +| The pipeline runner (seat `mesh-pipeline-runner`) | mesh-delivery, module mesh-delivery-pipeline | branch `fix/47-H1-runner-step-pins` at `e3fed775` (commits `a926a40e`, `e3fed775`) over main `b9cc9747` | +| The builder (seat `mesh-builds`) | mesh-delivery, module mesh-delivery-builder | branch `fix/47-H1-builder-revision-picture` at `0fcc614e` (one commit over main; its worktree clean) | +| The Go build module (seat `node-build-go`) | mesh-catalog, module mesh-build-go | main `34a884ff` | +| The delivery SDK's build step and step runner | mesh-delivery, module mesh-delivery-sdk, packages `buildstep`, `steprun` | main `b9cc9747` | + +Every fact below names its file and function, read with `git show` at those heads; no line numbers (they move). + +## 1. The specification + +### What an entry pins + +- **S1** An entry's `packages` names every mesh package its module's Go build requires, read from the `require` lines of + the go.mod files at the take-in, at any version, the zero version and `// indirect` included, with no build needed + (H-A-157, H-A-201). +- **S2** The set is transitive across the module graph the go.mod files give, not only the module's direct requirements + (H-A-201). +- **S3** A requirement of the module's own repository is never pinned: it is built from the tree (H-A-198, H-A-201, + H-A-202), whether or not that package is also published. +- **S4** A pin's key is the package's Go module path as go.mod requires it, a nested module's whole path included + (`/modules//go/clients/`), never a root path or a module's name (H-A-183: "the package path"). +- **S5** A pin's version is the newest version the registry seat published for that package path, as the registry's + published events name it (path and version); never a module's release number, never a commit (H-A-161, H-A-183; + G §370: a Go package's version is its tag). +- **S6** The pin stays within the series the module accepts: the one its manifest names in `packages`, the default + where it names none, whether or not a series value holds contents; a publish in another series pins nothing and moves + nothing (H-A-184, H-A-185). A package artifact's series is its module's version series (H-A-188). +- **S7** The pin is always the newest release in that series; an older version never stands over a newer release + (H-A-167). +- **S8** A requirement of another repository with no published version in its series is named with an empty version, + never left out (H-A-161, H-A-204). +- **S9** A pin is written `vMAJOR.MINOR.PATCH` everywhere it is carried (G §370's tag form; the step contract's + semantic-version form), and only an empty version stands for "none yet". +- **S10** A Go package path another module imports is a declared package artifact of its module; the catalog's check + refuses a manifest whose Go module imports a mesh package path no module declares (H-A-186). + +### When an entry is computed and pinned again + +- **S11** The entry and its pins are computed at the take-in of every watched branch, for every module the take-in + holds (H-A-157; H §743). +- **S12** A package's publish pins again every kept entry, of any repository and whether or not its module changed, + that names the path with no version or an older one in its accepted series (H-A-165, H-A-204). +- **S13** The pins move on the event, never waiting for a merge or a hand act (H-A-165). +- **S14** A pin that moves moves the importer's fingerprint; the importer becomes a mover, and the builder builds a new + key against the release (H-A-167; ADR 0573 §3). +- **S15** A failed re-pin is not acknowledged, so the publish is delivered again (H-A-167). +- **S16** The indexer answers one entry's `packages` and paths at a revision through a tool, without the whole revision + (H-A-204; tools-are-how-a-module-is-spoken-to). + +### What the fingerprint takes in + +- **S17** Every form's fingerprint (the version line's and the import form's) takes the module's pins, sorted; a + fingerprint with no pin stays as it was (H-A-167, H-A-172; ADR 0573 §2). +- **S18** The objects of every same-repository module directory the build derives from the go.mod files enter the tree + input, a line per directory, for every form, without being written into the entry; the entry's `paths` keep the + manifest's form (H-A-199 as H-A-202 amends it). +- **S19** A module whose every artifact names its paths takes its tree input from the manifest and those paths (ADR + 0499 §2). +- **S20** A build's reported imports refine the go.mod's set and never replace it with an empty one while go.mod names + a mesh package (H-A-157). + +### Who carries the pins into which ask + +- **S21** The builder takes a build's pins from the catalog entry alone and never computes one (H-A-192). +- **S22** The builder's own build ask of a lane (the trunk build it puts on the build seat's stream) carries the same + pins (ADR 0573 §2: the build writes those versions into its workspace; H-A-192). +- **S23** The runner puts the entry's pins into every step ask's fetch (lint, unit, integration), the same pins the + builder gives the build (H-A-203). +- **S24** A run on request's build step ask names no source revision (H-A-162). + +### What waits + +- **S25** A build step ask names its branch and source revision; when the builder's picture does not hold that revision + yet, the ask waits for the picture to take it in, woken by the state's change events and by each revision the view + takes in, up to `revision-wait-minutes` (1 to 60, default 2), then fails loud naming the revision and the branch; a + build with no version is never made (H-A-155, H-A-156, H-A-162). +- **S26** The builder's picture holds every kept revision: a revision below the newest it heard is read by number + through the catalog seat's `revision`; only one above the newest is waited for (H-A-205). +- **S27** A build whose entry names a package with an empty pin first asks the package registry seat's `versions` once + for that path and takes the newest in the accepted series; else it waits for the registry's published of that path + and series, up to `package-wait-minutes` (1 to 120, default 10), and pins the version that event carries; past the + bound it fails "package has no released version" (H-A-165, H-A-192, H-A-194). +- **S28** The runner asks a Go artifact's lint, unit and integration steps only when every pin of its entry has a + version; until then the steps stand as "waits on the publish of ", and end as the build ends when the bound + passes; the publish pins the entry again and moves the mover to its new fingerprint, whose pipeline runs them + (H-A-206). + +### What refuses + +- **S29** The Go build module refuses, loud, a requirement of another repository the ask gives no pin for (H-A-192). +- **S30** It never takes another path's version, a sibling's version or the latest for it (H-A-192, H-A-201). +- **S31** It builds a same-repository requirement from the fetched tree, transitively through those modules' own + go.mod files, and keeps those directories in the narrowed tree (H-A-198, H-A-202; ADR 0499 §4: a build sees only its + named paths). +- **S32** A version a repository's go.mod names is read as the oldest it accepts, and nothing more; nobody fixes a + version by hand (ADR 0573 §2). + +### What keeps the revision an entry lives in + +- **S33** The take-in pins the branch's newest kept revision for the same pipeline record as its own, and writes that + revision's number as the field `base` on the revision it writes, absent on a branch's first take-in; both are freed + with the pipeline (H-A-147, H-A-151, H-A-154). +- **S34** A passed pipeline pins, under `release..`, the revision of each mover that released a version; + a newer pipeline's `pipeline-wanted` with outcome running frees it from the revisions below only where the newer + revision holds that module's release record (H-A-168, H-A-170, H-A-173). + +### From the records, not judged here + +- **S35** A delivery group's check builds its members against the group's own heads (ADR 0573 §4). Milestone H's runs + on request replace the earlier model's group check; whether §4 still asks anything of the pin rule is a question for + the lead, not this table. + +## 2. The gap table + +Sizes: S one function (under an hour), M one module's part (a day), L the part's shape (more than a day). + +| Line | Status | Where | What the code does instead | Size | +|---|---|---|---|---| +| S1 | built | mesh-delivery-indexer: `cmd/.../named.go` (the go.mod read, `fingerprint.MeshRequiresOf`); `internal/index/package_trees.go` `otherRequired`; `internal/index/versions.go` `releasedPins` (branch indexer-repin, its `required` argument) | | | +| S2 | built otherwise | `internal/index/package_trees.go` `sameRepositoryRequired`, `otherRequired` | The reading follows only same-repository modules' go.mod files; a pinned package's own requirements (another repository's go.mod) are never read, so a transitive requirement is pinned only where the module's own go.mod lists it as `// indirect` (a tidied go.mod). | M | +| S3 | built | `releasedPins` (skips `trunk.SameRepository`); `fingerprint.OtherPackages` | The indexer never pins a same-repository package, published or not. The Go build module's side is S31. | | +| S4 | built | indexer `HearVersion` (`GoModule` from the registry's published `Module`), `releasedPins` (`s.GoModule == p`); builder `PackagePublished` (keyed by the published `Name`); mesh-build-go `takeZeroRequirements` (`asked[p.module]`) | The key is the full Go module path on every side. Live: the registry holds `.../modules/mesh-grants/busgrants` at 0.1.48 under its nested path (the indexer's `indexer_package_users`). | | +| S5 | built | `releasedPins` (branch); `fingerprint.WithPins` | The entry's pins are registry versions. The fingerprint's version line still takes commits (leftover L1). | | +| S6 | built | `releasedPins` (`m.AcceptedSeries(s.Name)`); builder `awaitPublished` (`man.AcceptedSeries(p)`) | The rule that a package artifact's series is its module's version series (H-A-188) lives in the catalog's check, outside these modules: not judged. | | +| S7 | built | `releasedPins` (the highest in the series) | | | +| S8 | built | `releasedPins` with `required` (branch indexer-repin `0418a2b9`) | The empty version is refused by a run on request's candidate: `internal/index/candidate_values.go` `checkCandidateModule` runs `sdkstep.PackageVersions.Check`, which accepts only a commit or a semantic version, on `runcandidates.go`'s values copied from the module's `Packages`. A run of a module with a package not yet published fails. | S | +| S9 | built | indexer `releasedPins` (`"v"+`), series kept without it (`HearVersion`); builder `publishedPin` (`"v"+`), `PackagePublished` (trims it); runner `stepAsk` (copies); sdk `buildstep` `PackageVersions.Check` (needs `v`); mesh-build-go `takeVersion` (`path@v…`) | One form throughout. The empty version is the one exception S8 names. | | +| S10 | not judged | the catalog's check (mesh-catalog's manifest check), not one of the modules held here | | | +| S11 | built otherwise | indexer `takeInSource` (`takein_source.go`), `recomputeLocked` (`toolchains.go`) | On the first watched branch every module is computed. On another branch the take-in recomputes only the moved repositories' modules and those whose pins name a package of a moved repository; every other entry is carried from that branch's newest revision with the pins it had. | M | +| S12 | built otherwise | `cmd/.../series.go` `heardVersion` (a registry's published runs `Recompute` of every module); `versions.go` `releaseVersion` calls `repin`; `toolchains.go` `Repin` (branch: by pins and by kept requirements) | Two paths move the pins, both in the first watched branch's view only (`ix.Modules`). A kept catalog revision is never rewritten, and another branch's entries are not pinned again. | M | +| S13 | built otherwise | as S12; `catalog_revisions.go` `keepBranchEntries` is called only from `takeInSource` | The view moves on the event, but an entry anyone reads (the builder, the runner, the node-engine through the revision) changes only when the next take-in of that branch writes a revision, which only a merge on that branch makes. | L | +| S14 | missing | `internal/index/movers.go` `moversOf` | A mover is a module of a moved repository whose fingerprint changed, or a module whose pins name a package a mover publishes. A module whose fingerprint moved by a re-pin is neither, so no pipeline builds or tests it. The builder's picture builds the new fingerprint on its own once a later revision carries it (leftover L5), outside any pipeline, with no test step and no want. | L | +| S15 | contradicts (one of two paths) | `cmd/.../series.go` `heardVersion` | The version-released path returns the re-pin's error, so the package-published is not acknowledged (built). The registry-published path logs a failed `Recompute` and acknowledges the event, so that re-pin is lost until the next publish. | S | +| S16 | missing | indexer tools (branch indexer-repin holds none) | The seat verb `mesh-catalog.entry` answers one whole entry by fingerprint, not at a revision. The tool H-A-204 asks is the commit still in progress. | S | +| S17 | built | `versions.go` `pinnedOf`; `fingerprint.WithPins`; `form.go` `formOf` (import form `stands` kept only while its built pins equal the new ones) | | | +| S18 | built | `package_trees.go` `derivedDirs`, `derivedTree` (main `b9cc9747`, merged #296) | | | +| S19 | built | `fingerprint.NamedTree` | | | +| S20 | built | `form.go` `refined` | | | +| S21 | built | builder `internal/build/step.go` `buildEntry` (entry by fingerprint through `mesh-catalog.entry`, then `awaitPublished`) | | | +| S22 | built | builder `internal/build/run.go` `runLane` (`awaitPublished`, `ask.Packages`) | Its `delete(ask.Packages, fb.Package)` loop runs over `req.Builds`, which nothing sets (leftover L6). | | +| S23 | built | runner `internal/pipeline/place.go` `stepAsk` (branch runner-step-pins `a926a40e`) | Empty pins are left out, so a step waits for them (S28). | | +| S24 | built | runner `place.go` `place` (source 0 for a run) | | | +| S25 | built | builder `internal/build/revisionwait.go` `awaitRevision`, `PictureHeld`; `module.json` `revision-wait-minutes` | | | +| S26 | built | builder `revisionwait.go` `keptRevisionHolds`; `cmd/.../keptrevision.go` `keptRevisionVia` (branch builder-revision-picture) | The kept revision is judged by its source and its fingerprints; the pins used are then the entry read by fingerprint (S21). | | +| S27 | built | builder `revisionwait.go` `awaitPublished`, `PackagePublished`; `cmd/.../versions.go` `publishedVersionsVia`; `cmd/.../seats.go` (the published heard); `module.json` `package-wait-minutes` | | | +| S28 | built otherwise | runner `place.go` (`unpinnedPackage`, `PinWait`, `endPinHeld`); `steps.go` `OnStepEndedShared`, `endPipeline` (branch runner-step-pins `e3fed775`) | A failed build ends the waiting steps with its outcome (built). When the build passes, `endPinHeld` ends none and nothing asks them: a waiting required step holds `endPipeline`, so the pipeline never ends and holds its place in the queue. The line counts on S14 (a new pipeline at the re-pinned fingerprint), which is missing. | M | +| S29 | built | mesh-build-go `cmd/mesh-build-go/pins.go` `takeZeroRequirements` ("no pin for … the builder pins or waits") | | | +| S30 | built | as S29; `versions.go` `takeRequirementsOf` leaves forge modules to their own rule | | | +| S31 | built otherwise | mesh-build-go `pins.go` `takeZeroRequirements`, `useOwnModules`; `narrow.go` `ownZeroPackageDirs` | Only a same-repository requirement at the zero version comes from the tree. One at a real version is fetched at that version through the Go seat, while the indexer's fingerprint takes the tree's objects (S18): the build and its key disagree. The repository test is the literal owner prefix `"novox/"+p.repo`, a value written into the code. | S | +| S32 | built | mesh-build-go `versions.go` `takeVersion` (a newer go.mod version is built, and said) | | | +| S33 | built | indexer `catalog_revisions.go` `keepBranchEntries` (`rev.Base`, the newest pinned in the same write); `pins.go` `HeardPins`, `unpinElsewhere` | | | +| S34 | built | indexer `pins.go` `HeardPins` (a release record only for a mover with a version), `HeardPipelineWanted` (running only; the newer revision's own release record) | | | +| S35 | not judged | | The question of whether ADR 0573 §4 still binds after the runs on request is the lead's. | | + +Counts: 35 lines; built 24, built otherwise 6, contradicts 1, missing 2, not judged 2. + +### The six points the lead asked about + +1. **The pin key's form.** On the branches every side keys by the full Go module path: the indexer from go.mod and the + registry's published `Module`, the builder from the published `Name`, the Go build module by `p.module`. A nested + path is pinned when the registry published that path (H-A-186's artifacts). The builder writes one git tag per + release, `go/v` (`internal/versions/tag.go` `GoTagOf`), never `/v`. The fetch asks the + Go seat first, so the tag is not on the path, but if the seat misses and the fetch falls through to the forge's git, + a nested path's `@v0.1.x` is an unknown revision (leftover L9). I think the refusals of nested paths seen earlier + came from the pins of H-A-161 (the module's release number) and the undeclared artifacts H-A-186 names. Both are + fixed on main and on the branches; the running indexer predates them (section 3). +2. **Reported imports against the go.mod graph.** `formOf` takes the import form when a build reported imports, and + `fingerprint.Resolve` gives versions only for the holders of what was imported. Since `0418a2b9`, `releasedPins` + adds every requirement the go.mod graph names (`required`), so the entry's pin set no longer shrinks to the imports. + The `stands` case keeps `prev.Packages` only while those equal the new pins (`pinnedOf`), so a moved pin moves the + fingerprint (S17). +3. **The recompute of unchanged modules of other repositories** (`recomputeLocked`, the held-stands guard). At a + take-in naming repository R, a module of another repository is recomputed only when its new pins name a package of + R (`importsOf`). Since `0418a2b9` that set includes requirements with an empty pin, so an importer of R's package is + recomputed. Any other module keeps its held value. A publish recomputes every module of the first watched branch's + view (`Recompute` on the registry's published) or the modules naming the released module's packages (`Repin`). + Other watched branches are not reached (S11, S12). +4. **The lane path's trunk asks.** `runLane` waits in `awaitPublished` and copies the filled pins into `ask.Packages` + for a Go fetch with any pin (S22). The lane runs both for a step ask and for the builder's own picture-driven builds + (L5). +5. **A same-repository requirement that is also published.** The indexer never pins it. The Go build module builds it + from the tree only when go.mod names it at the zero version; at a real version it is fetched from the Go seat at + that version (S31). +6. **The "v" prefix.** It is one form across the indexer, builder, runner, step contract and Go build module (S9). The + empty version is the one value the step contract refuses, which breaks runs on request (S8). + +## 3. The leftovers + +| What | Where | What it does | Line it contradicts | +|---|---|---|---| +| L1 The version line's commit form | indexer `form.go` `lineVersions` (`fingerprint.HeldVersionsOf`, the gate's heads for an unpublished package, G A-365); `fingerprint.VersionLine` | The fingerprint takes, for each other-repository package, the held module's commit or the branch head's commit. A merge of a package's repository moves every importer's fingerprint before anything is published. | S5 in spirit (H-A-161: never a commit). The pins themselves are versions. | +| L2 The accepted series' contents read at the published commit | indexer `series.go` `HearVersion` (`packagesAt`), `acceptedSeries` (DLV-I6) | Reads the published version's package digests through the forge for the import form, keeps a commit form where it cannot. | none (ADR 0593 §2's import form), but a second source of package versions beside the pins | +| L3 A whole recompute on every registry publish | indexer `cmd/.../series.go` `heardVersion` | `Recompute` of every module on each published version, beside the targeted `Repin` on version-released. | none; it duplicates S12's path, and acknowledges on failure (S15) | +| L4 The requirements state from go.sum | indexer `requirements.go` (`indexer_requirements`, `keepRequirements`, `RequiredOf`) | Keeps per package the highest version each consumer's go.sum names, for the builder's floor. Under the zero version go.sum names none (H-A-157). | none directly; H-A-157 says go.sum is never read for package edges, and H-A-159 removed the builder's own numbering it served | +| L5 The builder's picture-driven builds | builder `internal/build/run.go` (the picture's take calls `consider`), `Reconsider`, `Sweep`; `numbers.go` `PackageNamed` | Builds every fingerprint a watched branch's picture takes in, outside any step ask. It is the only path by which a re-pinned fingerprint is ever built today. | none of this part's lines (the earlier model's "the builder builds every fingerprint of the catalog half"); a builder that builds what no pipeline asked is a question for the lead | +| L6 Dead pin deletion | builder `run.go` `runLane` (`for _, fb := range req.Builds`) | Deletes from the pins the packages `builds` names, over a list nothing fills. | none | +| L7 Commit pins and pull-request heads | mesh-build-go `versions.go` `takeVersion` (a commit resolved to a pseudo-version, else `placePin` from `refs/pull/*/head`), README "A pin on a pull request's head" | Accepts a 40-hex commit as a pin and places a pull request's head beside the workspace. | S5 (H-A-161: never a commit) for a delivery build; it served ADR 0573 §4's group heads | +| L8 The literal owner prefix | mesh-build-go `pins.go` `takeZeroRequirements`, `narrow.go` `ownZeroPackageDirs` (`"novox/"+repo`) | Decides "same repository" by a written owner name. | principle 11 | +| L9 One Go tag per release | builder `internal/versions/tag.go` `GoTagOf`, `reserve.go` | Tags `go/v` once per module, whatever paths its Go packages have. | none of this part's lines; H-A-183 names `/v` as what the forge's Go seat looks for | +| L10 The candidate check on pins | indexer `candidate_values.go` `checkCandidateModule`; sdk `buildstep` `PackageVersions.Check` | Refuses an empty version. | S8 | + +## 4. Live against main + +Read through the mesh at 23:00 to 23:10 CET with read tools only (`mesh-delivery-view.node_haves`, +`mesh-catalog.entry`, `mesh-delivery-indexer.indexer_package_users`). Machines are named by role; the mapping is a +guess (section 7). + +**The indexer** + +| Machine | Build that runs | Main's or by hand | What main and the branches have that it lacks | +|---|---|---|---| +| the control-node | fingerprint `src2:9ac151c2…`, its entry at commit `f00d3467` (main, 2026-11-20 17:35 UTC) | the entry is main's commit; whether a pipeline or a hand placed it the tools do not say | 8 commits of main on the module: H-A-183, 184, 185 (the pin by path and series), H-A-186, H-A-200, H-A-201, H-A-202; and both commits of branch indexer-repin. Live, the entries of the indexer and the runner still carry 40-hex commits as pins, and the busgrants user `nats` shows no pin though 0.1.48 is published. | + +**The pipeline runner** + +| Machine | Build that runs | Main's or by hand | What main and the branch have that it lacks | +|---|---|---|---| +| the control-node | `src2:adf598f2…`, entry commit `9598b92c` (main, 17:37 UTC) | the entry is main's commit | H-A-187, H-A-189, H-A-190, H-A-191 (steps per mover); branch runner-step-pins (H-A-203, H-A-206) | + +**The builder** + +| Machine | Build that runs | Main's or by hand | What main and the branch have that it lacks | +|---|---|---|---| +| the workstation | `src2:48cabb7e…`, held: "entry-missing … src2:f34620ec…" since 17:49 CET | no kept entry names `48cabb7e`, so I take it for a build placed by hand or from before the clean state | not readable: no entry gives its commit | +| the control-node | removed ("the applied declaration no longer holds the module") | | | + +**The Go build module** + +| Machine | Build that runs | Main's or by hand | What main has that it lacks | +|---|---|---|---| +| the control-node, a build node | `src2:ae502407…`, phase failed: "the want … names no digest for mesh-build-go:files, mesh-build-go:tools" | no kept entry names it: placed by hand or from before the clean state | not readable | +| the workstation, the laptop | `src2:c69b0f1c…`, the same failure | the same | not readable | + +The delivery SDK is a package, not a running module; nothing of it runs on its own. + +## 5. The tests + +Counted as `func Test` per file; a file whose header carries `//go:build integration` counts as integration. Table +rows inside one function count once. + +| Module (head) | Unit | Integration | Starts the module whole against a bus and a store | What the tests would not catch of the gaps | +|---|---|---|---|---| +| indexer (indexer-repin) | 163 | 6 | yes, `TestIndexerWhole` (`takein_integration_test.go`) | It covers revision pins (S33, S34), not pins of packages: no whole test publishes a package and reads the entry pinned again, the re-pinned module made a mover (S14), another branch's entries (S11, S12) or an acknowledgement after a failed re-pin (S15). Unit tests `TestAnEntryNamesEveryRequirementPinnedOrWaiting` and `TestAReleaseRepinsAnEntryNamingItsPackageWithNoPin` (branch) prove S8 and S12 in the view only. | +| builder (builder-revision-picture) | 154 | 18 | yes, `integration_test.go` runs `run` | Nothing ties the lane's pins to an entry with an empty pin across a restart; the branch's unit test proves S26. | +| runner (runner-step-pins) | 91 | 4 | yes, `run_integration_test.go` runs `run` | No test builds a mover whose pin-held steps outlive a passed build (S28); the branch's `testruns_integration_test.go` checks the pins in the fetch (S23). | +| Go build module (main) | 217 | 18 | I found none that runs the module's `run` (guess; section 7) | Nothing fetches a same-repository requirement at a real version (S31) or a transitive other-repository requirement not in the go.mod (S2). | +| delivery SDK `steprun` + `buildstep` (main) | 113 (of the module's 150) | 13 (all in `steprun`) | not applicable (a package) | Nothing runs `PackageVersions.Check` on an empty version from a candidate (S8). | + +All five are inside the budget of 500 unit and 50 integration tests per module. + +## 6. Fix in place or write again + +**The indexer.** Fix in place. 14 of its 21 lines here are built. The pin's computation (S1 to S9, S17 to S20) and the +revision pins (S33, S34) follow the design. Its shape breaks in one place: a re-pin reaches only the in-memory view of +the first watched branch, and nothing turns a moved fingerprint into a catalog revision and a mover (S12 to S14, L). +That is a design question before it is code. A revision is numbered by its source (H-A-32), and a publish has no +source, so the design must say what takes in a re-pin (a take-in the publish itself starts, or a revision of its own +form). The rest are S: the acknowledgement (S15), the empty pin in a run's candidate (S8), the tool (S16). + +**The builder.** Fix in place. Its four lines (S21, S22, S25 to S27) are built on the branch, in the design's shape +(events and a bound, the versions verb read before the wait). Its open question is L5: it builds every fingerprint its +picture takes in, outside any pipeline. Today that is the only path that builds a re-pinned key, so it must not be +removed before S14 is built. + +**The pipeline runner.** Fix in place. S23 and S24 are built, and S28 is built but for one case: a pin-held step whose +build passed is never asked and never ended (M). It needs a design line for that case, for example asking the steps +with the pins the build resolved, which its step end would have to carry, or ending them "not asked" in favour of the +re-pinned mover's pipeline once S14 exists. + +**The Go build module.** Fix in place. S29, S30 and S32 are built; S31 holds only at the zero version and on a +literal owner name (S each). L7, the commit and pull-request-head pins, is the earlier model's and can go once no ask +names a commit. + +**The delivery SDK.** Fix in place: one change, the candidate check's treatment of an empty pin (S8), shared with the +indexer. + +## 7. What I could not read, and what I guessed + +- I could not send the lead an interim status mid-run: this agent has no messaging tool but its final report. +- **The tool commit of branch indexer-repin** was not in its worktree (clean at `94202fb6`), so S16 is judged missing. + Check: `git log fix/47-H1-indexer-repin` once it lands. +- **The builder's and the Go build module's running builds** have no kept entry (`mesh-catalog.entry` answers "no + entry of fingerprint … is kept"), so their commits are unknown. That they were placed by hand is a guess. Check: the + node-engine's composition of those modules on each machine (`/node-engine.composition`). +- **Whether a pipeline or a hand placed the indexer and the runner** is not said by the tools I used; their entries' + commits are main's. +- **The role of each machine** is a guess from the mesh's instructions (the control-node, the workstation, the laptop, + a build node). Check: `mesh-controller.nodes`. +- **The Go build module's whole test:** I searched its tests for a call of `run` and found none. A test that starts it + another way may exist. Check: read its `*_integration_test.go` files. +- **S2 in practice:** whether every mesh go.mod lists its transitive mesh requirements as `// indirect` I did not read. + Check: `go mod tidy` is a lint step, or read a module's go.mod at main. +- **The cause of the earlier nested-path refusals** (point 1) is a guess from the lead's answers, not from a record of + those builds. Check: `records_search` with the refused build's words. +- Line numbers are not given, by this agent's way of working (they move with every commit); each fact names its file + and function. + +## 8. The shortest list of changes still missing after the three branches + +1. **A re-pin becomes a revision and a mover** (S12, S13, S14). Owner: the indexer (its take-in), after a design + line from the lead or the design writer on what takes a re-pin in, since a revision is numbered by its source + (H-A-32). It also covers every watched branch, not only the first (S11). Size L. +2. **A pin-held step whose build passed** is asked with the pins the build resolved, or ended for the re-pinned + mover's pipeline (S28). Owner: the runner, with a design line. Size M. +3. **A failed re-pin on the registry's published is not acknowledged** (S15). Owner: the indexer, `heardVersion`. + Size S. +4. **An empty pin passes a run on request's candidate** (S8, L10). Owner: the indexer's `checkCandidateModule`, or the + SDK's `PackageVersions.Check` with an "empty allowed" form for entries. Size S. +5. **The tool answering one entry's pins and paths at a revision** (S16). Owner: the indexer. Size S (in progress). +6. **A same-repository requirement at a real version comes from the tree**, and "same repository" is read from a + setting or the fetch, not the literal owner (S31, L8). Owner: the Go build module. Size S. +7. **Transitive other-repository requirements** are pinned from the pinned packages' own go.mod files, or a check + refuses an untidied go.mod (S2). Owner: the indexer, or the catalog's check. Size M; needed only if a go.mod is + found that does not list them. + +L1 (the commit form in the fingerprint's version line) is left in place until item 1 lands, since today a +package's merge moving its importers' fingerprints is what makes them code dependents in that pipeline at all.