Design 47 H: the pin rule as a specification with its gap table (H1)
This commit is contained in:
@@ -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
|
||||
(`<repository>/modules/<m>/go/clients/<c>`), 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 <path> 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 <path>", 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.<branch>.<module>`, 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<version>` (`internal/versions/tag.go` `GoTagOf`), never `<package dir>/v<version>`. 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<version>` once per module, whatever paths its Go packages have. | none of this part's lines; H-A-183 names `<package dir>/v<version>` 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>/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.
|
||||
Reference in New Issue
Block a user