How it is built

In plain language

The platform is built the way its own runs are recorded: every decision is written down before the code, every rule has a check that enforces it, and every claim of "it works" is a measurement. This page is for readers who want to know what the engineering culture behind the mechanisms looks like.

Decisions are records

Sixty-seven architecture decision records across the three repositories (30 substrate, 15 composition, 22 product), each with a status, a date, a decider, the context that forced it, the decision, its consequences and the alternatives considered. Contested or load-bearing decisions are frozen in an ADR before code; a frozen contract is a conformance target, and "no semantic drift between the freeze and the implementation is permitted." Superseded ADRs remain in the record with a pointer forward.

Invariants are enforced, not aspired to

Every substrate invariant names its mechanism — CI gate, deploy gate, test requirement, schema check, lint rule, infrastructure assertion, runtime guard, machine evidence — and "invariants without enforcement are not invariants." The house rule is invariant-first: the test that pins a rule ships in the same change as the rule. Constitutional changes are additive, refinement or breaking, each with an explicit disposition (ADR-0025).

Measurement over assertion

Roughly 13,700 unit tests across the three repositories (≈3,000 substrate, 175 composition, ≈10,500 product), all runnable locally with the same command CI uses.
Consumer mirror suites re-run the substrate's contract tests against the pinned published artifacts, so a version upgrade is gated by the consumer's own evidence.
Source-grep tests forbid entire classes of bypass (table scans, non-transactional writes, direct knowledge-record writes, cross-provider SDK imports).
Snapshot governance of public and runtime surfaces turns an accidental API change into a failed build.
Live-gated smokes prove provider behaviour against the real models before a capability bit is flipped; a declaration that fails live stays false.
Tests assert on code, never on prose: comments are stripped before a source scan is judged.
The user interface is accepted by measurement in real browsers at real viewport widths, with probes that select the rendered element and count lines from layout, not from arithmetic.

Release mechanics

The substrate publishes as one lockstep release from an annotated tag on main; the workflow re-runs every gate before the first artifact is pushed and publishes in dependency order, idempotently.
Artifact sets are immutable; consumers pin exact versions.
Prompt and corpus publication is content-hash idempotent: republishing identical content is a no-op, and a pointer move is a ledgered flip.
Every production write is a governed operation with a dry-run and a plan hash; the CLI and our API resolve the same registered implementation.

Honesty as a mechanism

Several rules exist specifically so the system cannot flatter itself: never synthesise a value to fill a screen (I-29); metering never blocks execution but its gaps are visible (I-16); a lead alert claims provider acceptance, not delivery; an erasure runbook lists what is retained; a declaration describes the adapter's current behaviour, not the model's theoretical capacity. The platform prefers a recorded gap to an invented number.

Sources

magpie/docs/adr/, mag-composition/docs/adr/, matterandgas-com/docs/adr/.
magpie/docs/architecture-constitution.md §1 (enforcement vocabulary).
matterandgas-com/docs/adr/0025-architectural-constitution-governance.md.
magpie/tests/unit/, mag-composition/tests/unit/, matterandgas-com/tests/unit/.