---
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`.