jschoubben
702efca6bb
HQ held only the to-be. Every reader had to already know the system the decisions were about, and an as-is claim had nowhere to live except inside an intention. Adds 02-DESIGN/00-as-is — eleven documents written from the implementation and the operational record, not from intent, including the parts nobody would choose again. The two existing designs move under 01-to-be. Layers are declared in frontmatter and never mix: a design that ships does not move, its as-is counterpart is written, and both stand. Back-fills adr/0001-0014 for decisions taken in implementation and never recorded — the broker, the module abstraction, the mesh database, managed files, provisioning, migrations, the workspace removal, failing loudly, the constitution, application placement, linking, the employee model, the artifact, the three silos. Each marked reconstructed, dated from the history, and citing the evidence it was recovered from. The two existing records renumber to 0015 and 0016 so the ledger runs oldest first; 0017 extends 0015 to modules outside the core, principle only — the domain list is deliberately not invented here. how-we-build.md becomes the source of the mesh constitution, with a sync playbook, so the enforced copy stops being the only one that is true. Process becomes explicit: five playbooks, eight thin skills that defer to them, a repository map, and AGENTS.md with CLAUDE.md as its include. The five Observations become 04-ISSUES 001-005 where they can be owned and closed. 006 is new and uncomfortable: HQ is not indexed into the knowledge base. That claim is what decision 27 rests on, it was never checked, and the README now says so instead of repeating it. Also corrects the ADR index into something generated, the "02-DESIGN is empty" claim, the VISION.md pointer that did not survive the repo split, and a note asserting the symlink rule was contradicted — it was a misreading; the rule forbids hand-made links, the installer links by design.
64 lines
3.0 KiB
Markdown
64 lines
3.0 KiB
Markdown
---
|
|
status: accepted
|
|
date: 2026-08-04
|
|
deciders: jochen
|
|
reconstructed: 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
|
|
|
|
1. **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.
|
|
2. **Ship source plus its resolved dependency tree.** Rejected: large, slow, and it ships the
|
|
dependency resolution's platform assumptions along with it.
|
|
3. **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](0008-a-failed-step-fails-the-job.md).
|
|
|
|
## 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`.
|