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.
101 lines
4.9 KiB
Markdown
101 lines
4.9 KiB
Markdown
---
|
|
layer: as-is
|
|
status: implemented
|
|
code: [hal]
|
|
updated: 2026-08-23
|
|
decisions:
|
|
- adr/0014-build-publish-and-deploy-are-three-silos.md
|
|
- adr/0013-an-artifact-is-build-output.md
|
|
- adr/0008-a-failed-step-fails-the-job.md
|
|
---
|
|
|
|
# Delivery — from a push to a running node
|
|
|
|
One trigger, three silos, and a fan-out point that is the most consequential boundary in the
|
|
mesh.
|
|
|
|
## The trigger
|
|
|
|
A push to the forge. The forge calls a webhook; the receiving module verifies its signature
|
|
and emits an event. The coordinator resolves which modules the pushed commits affect, orders
|
|
them into dependency levels, and creates a pipeline per level.
|
|
|
|
There is no second path. A manual trigger exists for a module the push detection missed, and
|
|
using it routinely is a sign the detection is wrong rather than a workflow.
|
|
|
|
Detection is the pipeline's most fragile input. It has failed for reasons that have nothing to
|
|
do with the change: a webhook truncating its commit list on a large merge, a forge address
|
|
whose port broke the module-path matching. The characteristic outcome is the bad one — **a
|
|
merge that created no pipeline, and nothing said so**.
|
|
|
|
## Three silos
|
|
|
|
Cardinality is the whole point, and the three differ
|
|
([ADR 0014](../../adr/0014-build-publish-and-deploy-are-three-silos.md)):
|
|
|
|
| Silo | Runs | Where | Does |
|
|
|---|---|---|---|
|
|
| **build** | once per module feature | the build node | compile and bundle into a self-contained output |
|
|
| **publish** | once per module feature | the build node | package that output and upload it; a package-registry feature publishes here |
|
|
| **deploy** | once per module feature **per node** | every assigned node | install, configure, start, verify |
|
|
|
|
Commands and events are addressed per feature, not per module.
|
|
|
|
Build hands over a **staged tree**, not a package. Packaging belongs to publish, so a failed
|
|
upload retries by re-packaging rather than by re-sending something stale, and build never needs
|
|
to know how each module composes its artifact. The handover is a tree in a known location,
|
|
because the build's own working directory is reference-counted and may be gone by the time a
|
|
later stage runs.
|
|
|
|
## The artifact
|
|
|
|
The artifact is **build output** — compiled and bundled with its dependency graph inlined —
|
|
never a filtered copy of source ([ADR 0013](../../adr/0013-an-artifact-is-build-output.md)).
|
|
A deploy is extract-and-run and touches no network.
|
|
|
|
The consequence is the whole cost of the decision: **anything not in the build output does not
|
|
ship.** Every file kind had to be brought into that rule separately, and each was discovered by
|
|
something silently not happening after deploy — migrations reading a source layout, provisioning
|
|
scripts reading a source layout, selection files never packaged at all.
|
|
|
|
## The fan-out, and the build node
|
|
|
|
After publish, work fans out to every assigned node. The build node is the only node that has
|
|
already passed through two silos when this happens, and that asymmetry has its own defect
|
|
class: anything advancing a node's stage must account for **both** pre-fan-out stages. Code
|
|
that knew only about the first parked the build node forever while every other node deployed
|
|
cleanly — and the recovery sweeper, which knew the same subset, reported nothing to recover.
|
|
|
|
A recovery mechanism that knows less than the thing it guards is worse than none, because it
|
|
reports success over a stall it cannot see.
|
|
|
|
## Levels
|
|
|
|
A level completes before the next begins, so a module builds against its dependencies as they
|
|
were just published. The shared library is at level zero, which means anything that breaks it
|
|
breaks the first module of every cascade.
|
|
|
|
## What green proves
|
|
|
|
**A green pipeline proves transport, not effect.** The stages report that a message was
|
|
dispatched and accepted, which is not the same as the thing being running, correct, or present.
|
|
|
|
This is the mesh's most consistent failure shape and it is not incidental to the design — it is
|
|
what the stage reporting currently measures. Documented instances include a service reported
|
|
started when the container command merely returned, an image pull failure that did not fail the
|
|
deploy, a package install that 404ed from every mirror while the job went green (see
|
|
[`04-ISSUES/001`](../../04-ISSUES/001-failed-package-install-reports-success/00-report.md)),
|
|
and a node left on old code after a failed artifact download with a version marker that had
|
|
already advanced.
|
|
|
|
A verify stage exists to close this gap. It has been built and, for a period, was never
|
|
scheduled, because the coordinator's stage list did not include it.
|
|
|
|
## What is not covered
|
|
|
|
The end-to-end harness for this pipeline has not built since the workspace was removed, and
|
|
nothing reports that nothing runs it
|
|
([`04-ISSUES/005`](../../04-ISSUES/005-pipeline-test-harness-unbuildable/00-report.md)). The
|
|
pipeline's coverage is currently assumed rather than checked — which is the same class of claim
|
|
this repository exists to make people stop making.
|