jschoubben
c0b35652d0
papa-hq reads 01 research -> 03 decision -> 02 design. The order is a scar, not a choice: 02-DESIGN existed from its initial commit, and when adr/ was finally promoted on 2026-07-13 it took the next free number rather than its place in the sequence. By then design was too settled to renumber. hal-hq was three commits old, so it is not. adr/ becomes 02-DECISIONS and 02-DESIGN becomes 03-DESIGN, and following the folder numbers now walks the process in the order it happens: research produces a decision, the decision authorises a design. 00-GENESIS becomes 00-META, matching papa's rename from the same restructure. Every path reference rewritten across documents, frontmatter, playbooks and skills. All links resolve; all 58 frontmatter blocks parse and their path fields still point at files that exist.
3.0 KiB
status, date, deciders, reconstructed
| status | date | deciders | reconstructed |
|---|---|---|---|
| accepted | 2026-08-04 | jochen | true |
13. An artifact is build output, never a source tree
Reconstructed after the fact from the evidence cited below.
Context
A module is built once and deployed to every node assigned to it. What travels between those two events is the artifact.
For a long time the artifact was a filtered copy of the module's source directory. Deploying it therefore meant resolving and installing its dependencies on the target node — which requires the target to reach a package registry, at deploy time, for every node, every deploy. A node with no route to the registry could not deploy code that had already been built successfully.
Considered options
- Ship source, install dependencies on the target. Rejected — it is what existed. Deploy becomes a network operation with a failure mode per node, and the code that runs is assembled independently on each one.
- Ship source plus its resolved dependency tree. Rejected: large, slow, and it ships the dependency resolution's platform assumptions along with it.
- Ship a self-contained build output; a failed bundle fails the build. Chosen.
Decision
The artifact is the module's build output directory — compiled and bundled, with its dependency graph inlined. Deploy is extract-and-run and touches no network.
A build that cannot produce a self-contained output fails. It does not fall back to shipping a dependency tree, because a fallback that works is a fallback that is never fixed — an application of ADR 0008.
Consequences
- A node can deploy without reaching a registry. What was built is what runs, identically, on every node.
- Deploys are faster and their failure modes are local.
- Everything not in the build output does not ship. This is the decision's whole cost, and it was paid several times before it was understood: migrations that read the source layout, provisioning scripts that read the source layout, selection files never packaged at all. Each worked in development, where the source is present, and silently did nothing after deploy.
- Any file a module needs at runtime must be deliberately placed into the build output. The
rule "the artifact is
dist/" has to be applied to every file kind, not just compiled code, and that generalisation was the expensive part. - Bundling has its own failure modes that a compiler will not catch — a bundler can exit successfully and produce output that cannot load.
References
build: bundle artifacts so a deploy is extract-and-run(#673), 2026-08-04.- The consequences, in order:
Provision migrations and seeds read the source layout, not the artifact(#699),Local migrations read the source layout too(#700), both 2026-08-07. - Knowledge base:
pipeline/artifacts-are-build-output,pipeline/bundling,troubleshooting/shell-migrations-never-packaged,troubleshooting/flavors-never-packaged,troubleshooting/esbuild-silent-tla-breakage.