Extending the fusion: the recipe for a new subsystem

You've read seven shipped subsystems and built two of your own in the labs. Now distill it into a checklist a future agent can follow to add an eighth @alembic/hermes subsystem without rediscovering the conventions. The recipe is not arbitrary taste — every step traces to an invariant or an ADR you've already met. Follow it and your subsystem will look like it was always there; skip a step and CI or a reviewer will catch you, because the rules are enforced, not suggested.

The recipe at a glance

Step 1–2 — ports and schemas first

Start with types.ts. Define what a valid input is (Zod) and what the subsystem depends on (port interfaces). The shipped subsystems do exactly this — e.g. the web subsystem's WebBackend + Compressor ports, the learning loop's ReviewProposer + ReviewGate ports. Ports are types, never concrete classes:

// packages/hermes/src/<name>/types.ts
import { z } from 'zod';

export const requestSchema = z.object({ /* … bounded fields … */ });
export type Request = z.infer<typeof requestSchema>;

// A port = an injected capability, never a concrete import:
export type Backend = (req: Request) =>
  Promise<import('@alembic/contracts').Result<Response, Error>>;   // never throws

Step 3–4 — Result everywhere, no globals

The implementation file is functions or a class over those ports. Every fallible path returns Result; IO is wrapped in tryCatchAsync; time/randomness come from an injected Clock/id factory, never a global (Lesson 28). This is the exact skeleton from Lab 1 — it's not a toy, it's the production pattern at minimum size.

// packages/hermes/src/<name>/<name>.ts
import { ok, err, tryCatchAsync, type Result } from '@alembic/contracts';
import { requestSchema, type Backend } from './types.js';

export const doThing = async (
  input: unknown, deps: { backend: Backend; now: () => number },
): Promise<Result<Response, Error>> => {
  const parsed = requestSchema.safeParse(input);          // ② boundary Zod
  if (!parsed.success) return err(new Error(parsed.error.message));
  return deps.backend(parsed.data);                        // ③ Result through, ④ no globals
};

Step 5 — the dependency question

Before adding a package, ask: can a global already in the runtime do it? The web and media subsystems answered yes — they use global fetch via a thin createFetchBackend rather than adding an HTTP client (Lesson 11). The skills subsystem wrote its own dependency-free scalar frontmatter parser rather than pulling YAML (Lesson 12). The rule: "Do not add new dependencies without justification." A new dep is a supply-chain surface and a clean-room risk — earn it or avoid it.

Step 6 — wire the test safety

Each package carries its own vitest.config.ts (the hermes package has one). Match the hardened root config — bounded timeouts and pool:'forks' — and always run the suite through the process-group wrapper, never bare vitest:

# run the whole suite safely (Lesson 25):
pnpm test:safe            # bounded run in its own group → kill the group + sweep
# or one package:
pnpm --filter @alembic/hermes test

Step 7–8 — export, document, verify

Re-export every public symbol from src/index.ts with a header comment naming the CLONE/ADAPT/IGNORE provenance and the source map sections (read any subsystem's block in index.ts — they all do this). Then run the baseline and confirm the count moved the right way:

# the build/test baseline every change must keep green (CLAUDE.md):
pnpm -r typecheck && pnpm -r build && pnpm -w test

The discipline closes here: "Every new feature needs tests; total test count should increase or stay flat." A subsystem with no tests, or one that drops the count, is not done.

Common confusions