Layers, ports and adapters

An escape-room company runs each room from one controller box. The puzzle logic lives there: which solved clue opens which door.

In the escape room	In ports and adapters
each socket on the box is labelled by what the room needs: "puzzle solved", "open door", "play sound"	ports, declared by the core, named by purpose (steps 2, 9)
a supplier's magnetic lock or keypad is wired to give "solved" the way the box defines it; the box never learns the brand	adapters plugged in from outside, dependencies pointing inward (steps 3–4)
players and the game master set things going; the box itself fires the door release and the lights	driving and driven adapters (step 7)
the technician wires every prop to its socket before the doors open	one place wires the adapters (step 8)
the countdown display sits on its own socket; in a rehearsal the designer sets it to "two minutes left" to test the ending	the clock behind a port, and a fixed time in tests (steps 13–14)
the printed riddle on the wall needs no socket	pure code stays a plain part (step 12)

In real terms: the core's files import only the core; every database, vendor, framework and clock call reaches it through a port that an adapter fills, chosen in one startup file.

Breaks down when: the technician rewires a prop in the middle of a game. In code, the startup file picks each adapter once, before the first request.

Contrasting case: a paper treasure hunt in a park has no electronics to wire; a script with no outside world to reach has nothing to put behind a port.

4.1 ExamHall EXH-2630: the grading core that needs a database and a day

EXH-2630: the grading core scored an attempt by reading the answer key through Prisma and judged lateness with the system clock:

// core/grade-attempt.ts
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

export async function gradeAttempt(examId: string, answers: Record<number, string>, deadline: Date) {
  const key = await prisma.question.findMany({ where: { examId } });
  const right = key.filter((q) => answers[q.number] === q.correct).length;
  return { score: Math.round((100 * right) / key.length), late: new Date() > deadline };
}

Its four tests ran on CI, which has no database, and on a laptop with one, on two days:

4.1 EXH-2630 as written · CI, no database: 0 of 4 on 2026-10-02, 0 of 4 on 2026-11-02 · laptop with the database: 3 of 4 on 2026-10-02 (fails: late after the deadline), 3 of 4 on 2026-11-02 (fails: on time before the deadline)
4.1 EXH-2630 inward check: 1 import leaves core/ (core/grade-attempt.ts -> @prisma/client)

Every run needed the database, and on the laptop each day failed a different test (steps 13–14). MR !2930 gives the core two ports. Adapters implement them, and main.ts wires both in:

// core/ports.ts
export interface AnswerKeys { forExam(examId: string): Promise<{ number: number; correct: string }[]>; }
export interface Clock { now(): Date; }

// core/grade-attempt.ts
import type { AnswerKeys, Clock } from './ports';

export async function gradeAttempt(keys: AnswerKeys, clock: Clock, examId: string, answers: Record<number, string>, deadline: Date) {
  const key = await keys.forExam(examId);
  const right = key.filter((q) => answers[q.number] === q.correct).length;
  return { score: Math.round((100 * right) / key.length), late: clock.now() > deadline };
}

// adapters/prisma-answer-keys.ts
import { PrismaClient } from '@prisma/client';
import type { AnswerKeys } from '../core/ports';

export class PrismaAnswerKeys implements AnswerKeys {
  private prisma = new PrismaClient();
  forExam(examId: string) { return this.prisma.question.findMany({ where: { examId } }); }
}

// adapters/system-clock.ts
import type { Clock } from '../core/ports';

export const systemClock: Clock = { now: () => new Date() };

// main.ts
import { gradeAttempt } from './core/grade-attempt';
import { PrismaAnswerKeys } from './adapters/prisma-answer-keys';
import { systemClock } from './adapters/system-clock';

const keys = new PrismaAnswerKeys();
export const grade = (examId: string, answers: Record<number, string>, deadline: Date) =>
  gradeAttempt(keys, systemClock, examId, answers, deadline);

The same four tests now pass an in-memory answer key and a fixed clock:

4.1 MR !2930 with an in-memory answer key and a fixed clock · CI, no database: 4 of 4 on 2026-10-02, 4 of 4 on 2026-11-02 · laptop with the database: 4 of 4 on 2026-10-02, 4 of 4 on 2026-11-02
4.1 MR !2930 inward check: 0 imports leave core/ · main.ts in production on 2026-10-02 (Prisma, system clock): score 75, late false

The inward check finds no import leaving core/, and the same core still grades through Prisma in production (step 4).

4.2 Proof domain, payments ledger: two ways in, one core

A ledger core posts entries through its own port. An HTTP adapter and a nightly CSV adapter both drive it:

// core/ledger.ts
export interface Entry { account: string; pence: number; ref: string; }
export interface EntryStore { add(e: Entry): void; }

export function postEntry(store: EntryStore, e: Entry) {
  if (!Number.isInteger(e.pence) || e.pence === 0) throw new Error(`bad amount on ${e.ref}`);
  store.add(e);
}

// adapters/http-entries.ts
import { postEntry, type EntryStore } from '../core/ledger';

export const handle = (store: EntryStore) => (req: { body: string }) => {
  postEntry(store, JSON.parse(req.body));
  return { status: 201 };
};

// adapters/csv-entries.ts
import { postEntry, type EntryStore } from '../core/ledger';

export function importCsv(store: EntryStore, text: string) {
  for (const line of text.trim().split('\n').slice(1)) {
    const [account, pence, ref] = line.split(',');
    postEntry(store, { account, pence: Number(pence), ref });
  }
}

4.2 HTTP adapter, 3 requests (201, 201, 201): 3 entries (acc-1 +1250 r-1, acc-2 -300 r-2, acc-1 +40 r-3)
4.2 CSV adapter, 3 lines: 3 entries, the same · inward check: 0 imports leave core/

Both drivers call the same port, and the core names neither (steps 3, 7).