ADR 0267: an artifact is rebuilt only when its build source changes, and a module moves only along build dependencies on artifacts #232

Merged
mesh-admin merged 2 commits from decision/0267-a-module-moves-when-its-build-source-changes into main 2026-10-08 21:13:14 +00:00
Contributor

A decision record for the operator to accept. Status proposed.

The rule (the operator's, 2026-10-08). A change moves exactly the artifacts whose build source it touches, and, transitively, every module with a build dependency on a changed artifact, as the catalogue's module graph states it. Nothing else moves a module: sharing a repository is not a dependency. One build may produce many artifacts of any kind, each with its own build source. A dependency points at an artifact. An artifact whose build source did not change is not rebuilt as a new digest and not sent.

Why. Issue 338 (hq #231): every controller merge planned the controller, the build seat's holder and the route proxy in three gated tiers, about 15 minutes instead of 4 to 5, because the planner adds a module that reads a repository as a context on any merge to it (the packages edge), and the fingerprint hashes the context's whole tree.

What changes.

  • ADR 0267 (new, proposed), topic building it.
  • ADR 0162 decision 1 superseded in part (the packages kind and the same-tier code dependency); ADR 0238 decision 3 superseded in part (the whole repository for a root build, and a repository a recipe names). Each gets a dated Superseded in part note marked proposed; ADR 0236 gets a mechanism changed note (fingerprint per artifact). No other text of the old records changed.
  • Glossary: new entry build source, in Change and delivery, saying it narrows the older use (the repository a module is built from, ADR 0015/0111). No retired word applies.

How it is checked. The record's table points at mesh-controller #167's planner tests (planner_rules_test.go, planner_records_test.go; the rows tagged issue 338 flip) and names the new checks: per-artifact edges, a dependent dropped when its base rebuilds to the same digest, a Go build source equal to go list -deps, a catalogue check refusing a whole-repository build source, a declared-path build that reads outside its paths failing, and building twice giving one digest.

Local run: records, index, cycle and words all pass (merge-check.sh, with MESH_CATALOG_DIR set to a fresh catalogue checkout).

Do not merge before the operator accepts it; accepting flips status: to accepted and drops the proposed wording from the three notes.

A decision record for the operator to accept. Status `proposed`. **The rule (the operator's, 2026-10-08).** A change moves exactly the artifacts whose build source it touches, and, transitively, every module with a build dependency on a changed artifact, as the catalogue's module graph states it. Nothing else moves a module: sharing a repository is not a dependency. One build may produce many artifacts of any kind, each with its own build source. A dependency points at an artifact. An artifact whose build source did not change is not rebuilt as a new digest and not sent. **Why.** Issue 338 (hq #231): every controller merge planned the controller, the build seat's holder and the route proxy in three gated tiers, about 15 minutes instead of 4 to 5, because the planner adds a module that reads a repository as a context on any merge to it (the `packages` edge), and the fingerprint hashes the context's whole tree. **What changes.** - ADR 0267 (new, proposed), topic *building it*. - ADR 0162 decision 1 superseded in part (the `packages` kind and the same-tier *code* dependency); ADR 0238 decision 3 superseded in part (the whole repository for a root build, and a repository a recipe names). Each gets a dated *Superseded in part* note marked proposed; ADR 0236 gets a *mechanism changed* note (fingerprint per artifact). No other text of the old records changed. - Glossary: new entry **build source**, in Change and delivery, saying it narrows the older use (the repository a module is built from, ADR 0015/0111). No retired word applies. **How it is checked.** The record's table points at mesh-controller #167's planner tests (`planner_rules_test.go`, `planner_records_test.go`; the rows tagged issue 338 flip) and names the new checks: per-artifact edges, a dependent dropped when its base rebuilds to the same digest, a Go build source equal to `go list -deps`, a catalogue check refusing a whole-repository build source, a declared-path build that reads outside its paths failing, and building twice giving one digest. Local run: records, index, cycle and words all pass (`merge-check.sh`, with `MESH_CATALOG_DIR` set to a fresh catalogue checkout). Do not merge before the operator accepts it; accepting flips `status:` to `accepted` and drops the *proposed* wording from the three notes.
mesh-admin added 1 commit 2026-10-08 21:06:04 +00:00
ADR 0267 (proposed): an artifact is rebuilt only when its build source changes
mesh/merge-gate pass: the change touches no module of the mesh's graph
mesh/repo-check pass: its merge-check.sh passed
mesh/delivery superseded: a newer head of the same pull request
7d3f4407a7
A merge to a shared repository moved every module that read it, in a gated
tier each (issue 338). The operator's rule maps a change onto the artifacts
whose build source it touches and adds only modules with a build dependency
on a changed artifact; sharing a repository is no dependency. Supersedes in
part ADR 0162 decision 1 (the packages kind) and ADR 0238 decision 3 (whole
repository and context reads); adds build source to the glossary.
Author
Contributor

Delivery novox/hq@d2fe9bc870dc — delivered since 2026-10-08T21:13:44Z

Delivery plan — builds nothing: the change touches no module of the mesh's graph

Transitions

  • 2026-10-08 21:11 (new) → proposed (announced): novox/hq#232's head announced
  • 2026-10-08 21:12 proposed → checked (checked): the verdict names this commit
  • 2026-10-08 21:12 checked → ready (accepted): the gate passed or warned, and the repository's own check did not fail
  • 2026-10-08 21:13 ready → published (merged): on the trunk its modules follow: merged there, and its walk opened — or nothing for a walk to move
  • 2026-10-08 21:13 published → delivered (done): nothing for a walk to move

The commit's note under refs/notes/mesh-plan keeps every transition: git log --notes=mesh-plan.

<!-- mesh-delivery:view --> **Delivery** `novox/hq@d2fe9bc870dc` — **delivered** since 2026-10-08T21:13:44Z **Delivery plan** — builds nothing: the change touches no module of the mesh's graph **Transitions** - 2026-10-08 21:11 (new) → proposed (announced): novox/hq#232's head announced - 2026-10-08 21:12 proposed → checked (checked): the verdict names this commit - 2026-10-08 21:12 checked → ready (accepted): the gate passed or warned, and the repository's own check did not fail - 2026-10-08 21:13 ready → published (merged): on the trunk its modules follow: merged there, and its walk opened — or nothing for a walk to move - 2026-10-08 21:13 published → delivered (done): nothing for a walk to move The commit's note under `refs/notes/mesh-plan` keeps every transition: `git log --notes=mesh-plan`.
jschoubben added 1 commit 2026-10-08 21:11:37 +00:00
Accept ADR 0267: the operator's word of 2026-10-08
mesh/delivery delivered
mesh/merge-gate pass: the change touches no module of the mesh's graph
mesh/repo-check pass: its merge-check.sh passed
d2fe9bc870
Set its status to accepted and state the notes on ADR 0162, 0238 and 0236
as decided.
mesh-admin changed title from ADR 0267 (proposed): an artifact is rebuilt only when its build source changes, and a module moves only along build dependencies on artifacts to ADR 0267: an artifact is rebuilt only when its build source changes, and a module moves only along build dependencies on artifacts 2026-10-08 21:13:11 +00:00
mesh-admin merged commit e2de8811a3 into main 2026-10-08 21:13:14 +00:00
mesh-admin deleted branch decision/0267-a-module-moves-when-its-build-source-changes 2026-10-08 21:13:14 +00:00
Sign in to join this conversation.
No Reviewers
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: novox/hq#232