The four invariants that hold the engine together

Alembic's architecture rests on exactly four properties — not six, not "best practices," but four named invariants each asserted in source and most governed by an ADR. They are the rules every package keeps, the reason the system is testable, replayable, and trustworthy. Knowing them is knowing the engine's spine. Source: docs/alembic-complete-map.md §2, verified against the cited files.

The four, at a glance

① run() never throws; the result is a uniform discriminated union

You met this in lesson 14. It is enforced structurally by runWithGuards (adapter-core.ts:118) and verified live — the handoff records a real 429 surfacing as a typed failure. The orchestration core re-establishes the same boundary one layer up with runDebateSafe/runSwarmSafe (harness/src/core.ts:313-334), so a throw inside a council or swarm step also becomes a value. Governed by ADR-0009.

② Engines are adapter-agnostic AND store-agnostic

The pure kernels take only readonly views and injected side-effects. The DebateEngine, scoring, and verifier take an injected AdapterRegistry (council/src/debate.ts:71-83). The ETL layer routes all IO through an injectable FsPort — "every function here is testable in-memory." And the funnel takes an injected adapter registry, so swapping in an offline registry makes the whole run $0 and hermetic (funnel.ts:79-81).

// the pattern, everywhere: dependencies arrive as arguments, never imports of concretes
runDebate({ board, pack, adapters, requestId });   // adapters injected → test with fakes
runT0Pipeline(corpusDir, { fs });                   // FsPort injected → run in-memory
runFunnel(corpusDir, { adapters: offlineRegistry }); // offline registry → $0, hermetic

This is lesson 5 (ports & injection) elevated to an architectural law: no engine reaches out to a concrete adapter, filesystem, or store. That is exactly what makes the 400-plus-test suite run fast, in-memory, with no network — and what let the @alembic/hermes subsystems (lessons 7–13) be tested without opening a single socket.

③ Content-addressed IDs + deterministic run-dir layout

A run's id is the SHA-256-style content hash of its spec: runIdFor(spec) (swarm/src/orchestrator.ts:168). Change any spec field and you get a new run directory — runs are replayable because identical inputs converge on the same id and the same place on disk:

// run dirs: <baseDir>/runs/<runId> · append-only events.jsonl + checkpoint.json
// stores are content-addressed by SHA-256 over canonical (key-sorted) JSON →
// re-appending identical content is a no-op, so re-runs converge instead of duplicating

This is why plan modules (alembic.plan.ts) must be deterministic — Date.now(), new Date(), and Math.random() are rejected by the VM. Non-determinism would change the spec hash on every run and break replay, so the engine refuses to load a plan that contains it (lesson 17 covers the gate that enforces this on plans).

④ Dissent is preserved/forced by the Verifier, not merely by a prompt

This is the subtlest, and the one most teams get wrong. Many "councils" add a prompt that says "play devil's advocate" and call it adversarial. Alembic does not trust a prompt to produce dissent — it makes dissent structural:

• The maker-checker Verifier is read-only by architecture: it accepts only readonly views, exposes no adapter or mutation surface, and proves atomic claims with deterministic oracles over the structured evidence, never over the maker's prose (council/src/verifier.ts:19-99).
• "Contrarian-last" is enforced at board-load — contrarian_not_last is a hard load error (council/src/board.ts:142-149) — and realized as real sequencing by the engine (serial phases, parallel members).

Common confusions