Thirty lessons that teach a real system: how the Alembic engine is built, what was reverse-engineered out of the Hermes Agent, which capabilities were fused (and which were deliberately ignored), and the closed self-improving loop that resulted — plus the ports discipline that holds it together, a real engineering war story, a deep dive into each shipped @alembic/hermes subsystem, a full pass over the engine the fusion plugs into and the method behind it, and finally two hands-on labs plus advanced topics and a capstone. Every claim here is drawn from the project's own maps, ADRs, and shipped source; sources are cited at the foot of each lesson.
Language: English · Português (PT-BR) →
@alembic/hermes subsystem one at a time, with verbatim source. Engine & method (14–21) covers the engine those subsystems plug into — the narrow waist, the funnel, the four invariants, the gate pipeline, council/verifier, the swarm — and the discipline that produced it all: the reverse-engineering method and the CLONE/ADAPT/MERGE/IGNORE fusion framework. Finally Labs & advanced (22–30) puts it to work: two hands-on labs (build a subsystem, wire the learning pass), advanced topics (the ADR trail, test-safety engineering, security, tiers/budget, determinism, the extension recipe), and a capstone that assembles the whole machine. Each lesson is a single self-contained HTML file — no network, no build — with a diagram, an interactive quiz, and a sources footer. Toggle light/dark with the button above.
Alembic's six-layer model (L-1 contracts up to L4 clients), the narrow waist — a Result-shaped model contract that never throws — and the T0→T3 distill funnel that turns raw sources into Learnings.
What the Hermes Agent is, its tool catalog reverse-engineered tool-by-tool, and the closed learning loop (§1.10) that became the keystone of the fusion.
The CLONE / ADAPT / MERGE / IGNORE decision for every capability — why the learning loop is the keystone, why the MCP client is parked, and why delegation is IGNORE since the swarm already exists.
Frozen-snapshot memory + a propose→Validator-gate→dispose learning pass (ADR-0018) + the curator lifecycle. Why it is gated, not auto-apply (ADR-0006).
FsPort, adapter, Clock and idFactory injected; Result + Zod + never-throws at every boundary. Why (testability, determinism, store-agnosticism — ADR-0009) with real code from the shipped subsystems.
The incident (16 orphaned workers, ~1550% CPU), the two causes, the two-layer fix (hardened config + a process-group-killing test wrapper), and how it was verified.
Seven references, one per @alembic/hermes subsystem. Lessons 1–6 are the narrative; these go deeper — public API, key types/Zod schemas, the core logic in real code, the invariants (Result/never-throws, ports injected, no Date.now()/Math.random()), and what the tests cover.
MEMORY.md/USER.md, add/replace/remove by unique substring, the § delimiter, char limits 2200/1375, and snapshot-vs-live state.
reviewAndLearn: the gated passpropose→gate→apply, the ReviewGate port, scoreThresholdGate(0.7), the applied/rejected/failed buckets, and fail-closed control flow.
runCuratorThe Clock port, active→stale→archived, never-delete, the pinned/agent-only gates, and the +Infinity never-active anchor.
Promise + resolver registry + timeout, monotonicIdFactory, question/response Zod with cross-field validation, the leave-pending rule.
WebBackend + Compressor ports, createFetchBackend over global fetch (no dep), maxResults clamp, defense in depth.
list=metadata / view=body, CRUD, path-safety, and the dependency-free scalar frontmatter parser.
TranscriptionBackend/VisionBackend ports, fetch backends, Zod at the boundary, and why the local ML path is IGNORED.
Eight lessons on the Alembic engine itself (the contract, the data funnel, the invariants, the gates, the decision engine, the swarm) and the reverse-engineering + fusion method that produced this whole project. Lessons 1–6 are the narrative and 7–13 the subsystems; these go to the foundations the subsystems rest on.
ModelRunResult discriminated on ok (never throws), and runWithGuards — Zod-in → try/catch → circuit-breaker → retry → outer safety net.
The 4-tier ETL (T0 $0 → T1 ~$0 → T2 metered → T3 council+verifier), the verified-GO gate, and the three safety invariants (PII, budget, append-only).
run-never-throws · adapter/store-agnostic · content-addressed IDs & deterministic run-dir · dissent preserved by the Verifier. Four, not six.
Scope → Council → Proof → Validator → Publish, each fail-closed — and where the learning loop's ReviewGate fits the same family.
DebateEngine (serial phases / parallel members), 0–10 scoring, the read-only maker-checker Verifier, and the N-lens panel as the T3+ emission gate.
orchestrator → lead → worker, dependency-gated queue, depth-bound (MAX_DEPTH=2), git-worktree isolation, T4 park, crash-safe resume.
How the two maps were built: the code wins, honest depth tiers, Proof-Gate everything, builder ≠ validator. The discipline behind the fusion.
CLONE / ADAPT / MERGE / IGNORE walked end-to-end — two questions, a 2×2, and four worked verdicts (learning loop, MCP, delegate, neutts).
Nine lessons to put the theory to work: two hands-on labs that build real subsystems from the engine's own patterns, six advanced deep-dives into the decisions and disciplines that hold it together, and a capstone that assembles the whole machine end to end. Each lab has a "your turn" exercise; the capstone has a cross-cutting quiz.
Hands-on: write a tiny NoteStore from scratch — injected FsPort, Zod at the boundary, Result + never-throws, bounded — mirroring how memory/skills were built. With a "your turn" exercise.
Hands-on: wire reviewAndLearn from three injected ports (proposer + ReviewGate + MemoryStore); watch a turn split into applied/rejected/failed, and force each bucket.
The decisions that shaped the fusion: ADR-0001 (engine not product), 0005 (human gate), 0006 (validator emission gate), 0009 (narrow waist), 0018 (the gated loop) — and how they constrain each other.
Deep on the vitest-orphan fix: process groups, detached:true, kill(-pgid), the safe-test.mjs wrapper, the hardened vitest.config.ts, and the post-run sweep. Extends Lesson 06.
ADR-0011: PII redaction before egress, fail-closed everywhere, the path-traversal guard, Zod at the boundary, CL4R1T4S isolation, and content-addressed provenance.
The Tier ladder T0–T4 + the LOCAL marker, the 11-entry model registry, pickCheapestForTier, and the fail-closed BudgetGuard where a non-positive cap means free-tier-only.
Content-addressed run IDs (runIdFor), the deterministic run-dir, the plan-VM ban on Date.now()/Math.random(), and the injected Clock/id-factory seam that keeps replay honest.
The recipe: how to add a new @alembic/hermes subsystem — ports-and-injection, Result+Zod, no new dep, per-package vitest.config.ts, test:safe. A checklist a future agent follows.
The full picture: the distill→learn→sediment→prune loop, what shipped (7 subsystems, ~565 tests), the parked frontier (MCP client, corpus, design/GTM), and a cross-cutting capstone quiz.
@alembic/hermes subsystems — its API, its invariants, and its tests · trace a model call through the narrow waist and a corpus through the four-tier funnel · name the four invariants and the five gates · run the CLONE/ADAPT/MERGE/IGNORE decision on any capability yourself · build a ports-and-injection subsystem and a Validator-gated learning pass with your own hands · walk the ADR trail that constrained the design · reason about tiers, cost, determinism, and security from first principles · and follow the recipe to add a new subsystem of your own. Each lesson ends with a short quiz so you can check yourself.