The Engine

Before any fusion, you need the host. Alembic is a plan-execution engine for agent swarms: it takes a goal, an executable plan, and a validation contract, then runs units of work across many models — routing by cost, proving each step, gating before it ships. This lesson is its shape: six layers, one load-bearing contract, four invariants, and the funnel that turns raw sources into Learnings.

Counts are source-verified. The map records 19 workspace packages + 1 app; the test suite was at 415 when the map was written and grew to ~565 after @alembic/hermes landed — the same 565 the case study in Lesson 6 runs.

The six layers

Alembic is layered top-to-bottom, and the layering is real: the import graph has no upward edges and no cycles. Each layer may only depend on the ones below it. Read it from the bottom — the foundation is the vocabulary, the top is where humans and tools plug in.

Glue that sits across the layers. A handful of packages orchestrate across L2–L4 and are best read as their own tier: @alembic/mission (compiles missions → run specs), @alembic/vm (executes alembic.plan.ts by injecting the h.* hooks), @alembic/coda (the four run-closing gates), @alembic/forge (the Forge front-end + Scope Gate), and @alembic/planf3 (plan HTML).

The narrow waist — one contract that never throws

Here is the single most important idea in the codebase. Every model invocation in the entire system flows through one function shape: an async call that never throws and returns a discriminated union keyed on ok. Success and failure are both ordinary return values — there is no second, exceptional path to reason about.

// packages/contracts/src/model.ts — the waist (shape)
interface ModelAdapter {
  run(input: ModelRunInput): Promise<ModelRunResult>;   // NEVER throws (the invariant)
}
// ModelRunResult is a discriminated union on `ok`:
ModelRunSuccess = { ok: true;  text; usage?; costUsd?; durationMs; modelId; ... }
ModelRunFailure = { ok: false; error: { code; message; retryable }; durationMs; ... }
ModelRunResult  = z.discriminatedUnion('ok', [ Success, Failure ])

Source: packages/contracts/src/model.ts:30-151. Governed by ADR-0009 ("narrow waist — run never throws").

"Never throws" is not a comment you hope holds — it is structurally enforced by a single reusable spine, runWithGuards. Each adapter implements only an inner attempt(); the spine wraps it, in order, with: (1) Zod validation of the input at the boundary, (2) a try/catch that converts any escaped throw into a typed ModelRunFailure, (3) an optional circuit-breaker gate, and (4) retry backoff driven by each result's retryable flag — with a final outer try/catch "as a last safety net to preserve the invariant."

A second, lighter Result<T, E> union (also keyed on ok, with value/error arms) exists for non-model fallible work — file IO, parsing, subprocess wrapping. It deliberately mirrors the model waist so both read identically at call sites. That discipline is Lesson 5.

The four invariants — exactly four

The architecture rests on four properties (not more — the map enumerates exactly these). Each is asserted in source, and most are governed by an ADR.

The funnel — a 4-tier distillation

Alembic's reason for existing is the funnel: it turns a raw corpus into two value-chains — a business opportunity graph and a Learnings store. It does this in four cost tiers, cheap-first, so that most of the work costs nothing and only the strongest signals ever reach a paid model.

Three safety invariants the funnel must never regress: PII before egress (a private-channel signal is redacted before the model call and re-checked before any write), budget fail-closed (every paid call is wrapped in a fail-closed BudgetGuard.check — a projected breach blocks the call and the tier degrades rather than overspending), and append-only (results flow to content-addressed, schema-validated, append-only stores; source reads stay read-only).

Common confusions