# System Documentation (docs/architecture/systems/{system}.md)

Truth document. Use for: **one machine that spans packages** — exactly how it works, end to end, in one place. One file per machine, named for the machine (`docs/architecture/systems/update-engine.md`). It states the machine's model and its whole path: what enters it, every stage it passes through, what it writes, what re-drives it when it stalls, and what a reader sees at the far end.

**A system document's globs win by specificity.** Its `owns:` names the subtrees and exact files the machine is made of — `packages/studio/src/server/execution/**`, `packages/ui/src/shared/harnessVocabulary.ts` — and those are narrower than the package document's `packages/studio/**`, so the system takes them and the package keeps the residue. That is the whole mechanism: **the package document is the residual owner and the system document is the specific one**, and nothing needs to be subtracted by hand. A machine confined to one package still gets a system document if the machine is the thing worth stating; it is the *narrower glob* that makes it a system, not the package count.

**Two rules bind the globs.** Neither genre may claim a path another document claims at **equal specificity** — equal-specificity overlap is an ownership conflict to resolve before either document ships. And every glob **matches at least one file on disk** at `status: active`; projected globs are permitted only at `draft` and are confirmed when the document flips. Because a system's `owns:` list is long and hand-assembled, re-glob it whenever the machine's code moves — a stale entry here silently un-owns real code back to the package document, which does not describe it.

**How this differs from its neighbours — and the mistake this template exists to prevent.** A **feature** document covers one capability or one page a person names and owns that surface's globs. A **package** document covers one unit of distribution and owns what is left of its tree. A **system** document covers a *machine*: something with an entry, stages, state and an outcome, which a person does not open and cannot point at. **The failure mode is a system document written as a giant feature document** — a tour of screens and what each button does, at ten times a feature doc's length. The test is mechanical: if the subject can be named by an address a person navigates to, it is a feature; if it can be named only as a verb over the product's own nouns — the walk, the egress, the ingest, the settlement — it is a system. A system document says what a surface *renders from* and links to the feature document for what the surface looks like; it never describes the surface.

**Required vs optional.** Required in every system document: the **frontmatter**, the **opening statement** (what the machine is, then what this document states end to end), the **boundary paragraph** (what this document does not restate, and which document holds each part), the **machine diagram**, at least one **stage section**, **Files**, and **Related**. Everything else is optional. Do not add a section because it seems owed — a stage the machine does not have is a section that will be filled with something untrue.

System documents are long by nature, because the point is that the whole machine is in one place — roughly 300 to 1000 lines. Length is earned by stages, never by restating a neighbour: every paragraph that could have been a link to the document that owns it is the genre's characteristic waste.

```yaml
---
owns:                                              # required — the machine's subtrees and exact files; narrower than the package glob
  - packages/{pkg}/src/{machine}/**
  - packages/{pkg}/src/routes/{machine}.ts
  - packages/{other}/src/shared/{machine}Vocabulary.ts
keywords: [machine name, its nouns, its verbs]     # required — discovery terms: the machine's own vocabulary, the table and route names
status: active                                     # required — active | draft | deprecated
applies:                                           # optional — the decisions and doctrine this machine is BOUND by (obligation, not a bibliography)
  - docs/architecture/decisions/AD-0NN-{slug}.md
  - docs/architecture/common/{doctrine}.md
type: system                                       # required tooling key — genre stamp; preserve on edits, never narrate
---
```

> A system document carries no `module:` — a machine that spans packages belongs to no single
> bounded context, and labelling it with one asserts a boundary it crosses by definition.
> `last-reviewed:` is optional tooling metadata: preserve it, never narrate it.

```
# {The machine}

{One paragraph that defines the machine in its own first sentence — bold the term being defined —
then says what this document states, in the order the body states it. The enumeration is the
contract: a reader who wants one stage finds it by reading this sentence. Where the machine's
purpose is easier stated as an outcome, lead with `**Goal:**` and one sentence instead.}

{One paragraph: the boundary. What this document does **not** restate, and which document holds
each part — the neighbouring systems, the package documents whose residue this sits inside, the
feature documents that render from it, the common-plane doctrine it obeys, the decision records
behind its shape. Name each with a link and the subject it holds. This paragraph is what keeps the
document from growing into its neighbours.}

```text
{The machine diagram. One fenced block, drawn as the thing flows — entry at the top or left,
each stage a box or a labelled arrow, the durable writes named, the re-drive path shown returning.
Label the arrows with what crosses them, not with verbs. This is the picture a reader holds while
reading the rest, so it carries the machine's real names — routes, tables, classes, files — and
not generic boxes.}
```

{Optional, and worth its line whenever the body names paths: "Every path below is relative to
`packages/{pkg}/src/{dir}/` unless it names another package."}

{Optional: a reading order for a long document — "§ X is the data; § Y is the code that reads it;
§ Z is what re-drives it" — where the section list is not self-evidently a sequence.}

## The shape

{Optional. Where the machine has parts a reader must hold at once before any stage makes sense,
name them in one table before the stages begin.}

| Part | Where | What it holds |
| --- | --- | --- |
| {Entry} | `routes/{x}.ts` | {thin, tenancy first} |
| {Ledger} | `{machine}/ledger.ts` | {the durable row} |

## {Stage sections — one per stage, in the order the machine runs them}

{The body, and the only genre where the section order is decided for you: the machine's own order.
Entry, then each stage, then what is written durably, then what re-drives a stalled one, then what
reads the result. Name each section for its stage in the product's own vocabulary. Within a
section, state the mechanism and its reason: what the code does, what it refuses, and why it
refuses that rather than something else. Tables for rosters (routes, columns, frames, states,
bindings); prose for a rule and the defect it prevents. Never paste an implementation — a
signature, a state list, a wire shape, a table's columns.}

## Tests

{Optional. What proves this machine, and what each suite pins — a `Suite | Pins` table. Include it
where the machine has a suite of its own; omit the heading where the coverage lives in the package
documents' suites.}

## Files

| Path | Role |
| --- | --- |
| `packages/{pkg}/src/{machine}/{file}.ts` | {what it holds, by name — the exports a reader is looking for} |

{One row per file this document owns — the roster is the `owns:` list, made readable. Close with
the inverse: "Read here, owned elsewhere:" naming the paths the body describes but another document
claims, each with the document that claims it. That closing line is what stops a system document
from quietly annexing the code it reads.}

## Related

- [AD-0NN — {the ruling}](../decisions/AD-0NN-{slug}.md) — {the decision behind this shape, the options weighed}
- [`{neighbour}.md`]({neighbour}.md) — {the machine on the other side of this seam}
- [`{feature}.md`](../../features/{feature}.md) — {what a person sees of this machine}
- [`{doctrine}.md`](../common/{doctrine}.md) — {the cross-cutting contract this machine answers to}
```

### The boundary paragraph is the genre's load-bearing section

Systems overlap: they share tables, call each other, and render into the same surfaces. Without a
paragraph that names the seams, two system documents describe the same stage from two angles and
drift apart on the first change — and a reader has no way to tell which is authoritative. So the
boundary paragraph is not a courtesy list of related reading; it is the statement of what this
document is *not*, written specifically enough that a later editor can tell where to put a fact.
Write it as a list of subjects with their owners — "the coordinator's tables, alarm and drive claim
are `harness.md`; a run's ledger row and settlement are `generation-runs.md`" — never as bare
links.

### Marking what is decided and unbuilt

Where the machine has a stage that is decided and not built — a predicate that selects but never
acts, a column that is written and never read, a door with no caller — wrap the prose in a marker
so the gap is machine-findable and its evidence travels with it:

```
<!-- UNBUILT:START — {what is decided, where it is decided (an AD § or an owner ruling), and the
source evidence that it is not built: the function with no caller, the route that is not mounted,
the value written and never read} -->
{the prose describing the unbuilt stage, and what runs in its place}
<!-- UNBUILT:END -->
```

**State what runs instead.** A machine with a hole in it still works somehow, and the workaround is
the fact a reader needs. **A design decided *against* carries no marker** — a marker means the work
is owed and absent, so using one for a rejected design turns the register of debt into a register
of opinions.

### `status: draft` on a system

A system document is `draft` when the **machine as a whole** does not run — the code is on disk and
nothing reaches it. Say so in the first section, in plain words, with the evidence: which halves
exist, which do not, and what a reader who invokes it actually observes. A scoped gap in a working
machine is not a draft: the document stays `active` and takes an UNBUILT marker at the stage that
has the hole.