@fougere/testing 0.9.2-alpha.0 → 0.10.0-alpha.0

package/src/{comparison.ts → DoorContractCase.ts}

@@ -4,9 +4,11 @@ import { Invocation } from '@fougere/core/contract';
 import { serveRest, serveRpc, tableOf } from '@fougere/app';
 import { lowerFirst, type SchemaView } from '@fougere/schema';
 import { listQuery, findQuery, mutationFor, at } from './gql.js';
-import { sampleInput, type SampleOptions } from './sample.js';
+import { sampleInput } from './sample.js';
+import type { DoorOptions } from './DoorOptions.js';
+import type { DoorInput } from './DoorInput.js';
 
-/** The rows a door hands back, with its own envelope taken off. */
+/** The rows a facade hands back, with its own envelope taken off. */
 function rowsOf(value: unknown): unknown {
   if (Array.isArray(value)) return [...value];
   const page = value as { items?: unknown } | null;
@@ -23,21 +25,13 @@ function written(value: unknown, sent: Record<string, unknown>): unknown {
   return wire(Object.fromEntries(Object.keys(sent).map((key) => [key, row[key]])));
 }
 
-export interface DoorOptions extends SampleOptions {
-  given?: Record<string, unknown>;
-  /** The audience, when the app serves named surfaces. */
-  surface?: string;
-}
-
-interface Doors {
+interface Facades {
   local: (op: string, call?: DoorInput) => Promise<unknown>;
   rpc: (op: string, call?: DoorInput) => Promise<unknown>;
   rest: (op: string, call?: DoorInput) => Promise<unknown>;
   graphql: (op: string, call?: DoorInput) => Promise<unknown>;
 }
 
-export interface DoorInput { id?: string; input?: Record<string, unknown> }
-
 export interface DoorContractCase {
   /** What this case proves — becomes the test name. */
   name: string;
@@ -48,17 +42,17 @@ export interface DoorContractCase {
   expected: unknown;
 }
 
-/** One entity, four doors, the same answers. */
+/** One entity, four facades, the same answers. */
 export function checkDoors(app: App, entity: SchemaView, options: DoorOptions = {}): void {
   const name = lowerFirst(entity.name ?? '');
-  const doors = doorsOf(app, entity, name, options.surface);
+  const facades = facadesOf(app, entity, name, options.surface);
   const inputOf = () => sampleInput(entity, options.given ?? {}, options);
 
-  describe(`${entity.name} — the doors agree`, () => {
+  describe(`${entity.name} — the facades agree`, () => {
     it('on create, over what the caller sent', async () => {
       const sent = inputOf();
       const answers = await Promise.all(
-        (['local', 'rpc', 'rest', 'graphql'] as const).map((door) => doors[door]('create', { input: sent })),
+        (['local', 'rpc', 'rest', 'graphql'] as const).map((facade) => facades[facade]('create', { input: sent })),
       );
 
       const [local, ...others] = answers.map((answer) => written(answer, sent));
@@ -68,33 +62,33 @@ export function checkDoors(app: App, entity: SchemaView, options: DoorOptions =
     });
 
     it('on list', async () => {
-      await doors.local('create', { input: inputOf() });
+      await facades.local('create', { input: inputOf() });
 
-      const local = wire(rowsOf(await doors.local('list')));
+      const local = wire(rowsOf(await facades.local('list')));
       expect(Array.isArray(local) && local.length > 0, 'nothing to compare').toBe(true);
 
-      expect(wire(rowsOf(await doors.rpc('list'))), 'rpc ≠ local').toEqual(local);
-      expect(wire(rowsOf(await doors.rest('list'))), 'rest ≠ local').toEqual(local);
-      expect(wire(rowsOf(await doors.graphql('list'))), 'graphql ≠ local').toEqual(local);
+      expect(wire(rowsOf(await facades.rpc('list'))), 'rpc ≠ local').toEqual(local);
+      expect(wire(rowsOf(await facades.rest('list'))), 'rest ≠ local').toEqual(local);
+      expect(wire(rowsOf(await facades.graphql('list'))), 'graphql ≠ local').toEqual(local);
     });
 
     it('on findById', async () => {
-      const row = await doors.local('create', { input: inputOf() }) as { id: string };
+      const row = await facades.local('create', { input: inputOf() }) as { id: string };
 
-      const local = wire(await doors.local('findById', { id: row.id }));
+      const local = wire(await facades.local('findById', { id: row.id }));
 
-      expect(wire(await doors.rpc('findById', { id: row.id })), 'rpc ≠ local').toEqual(local);
-      expect(wire(await doors.rest('findById', { id: row.id })), 'rest ≠ local').toEqual(local);
-      expect(wire(await doors.graphql('findById', { id: row.id })), 'graphql ≠ local').toEqual(local);
+      expect(wire(await facades.rpc('findById', { id: row.id })), 'rpc ≠ local').toEqual(local);
+      expect(wire(await facades.rest('findById', { id: row.id })), 'rest ≠ local').toEqual(local);
+      expect(wire(await facades.graphql('findById', { id: row.id })), 'graphql ≠ local').toEqual(local);
     });
 
     it('on update, over what the caller sent', async () => {
-      const rows = await Promise.all([1, 2, 3, 4].map(() => doors.local('create', { input: inputOf() }))) as { id: string }[];
+      const rows = await Promise.all([1, 2, 3, 4].map(() => facades.local('create', { input: inputOf() }))) as { id: string }[];
       const patch = inputOf();
 
       const answers = await Promise.all(
         (['local', 'rpc', 'rest', 'graphql'] as const)
-          .map((door, index) => doors[door]('update', { id: rows[index].id, input: patch })),
+          .map((facade, index) => facades[facade]('update', { id: rows[index].id, input: patch })),
       );
 
       const [local, ...others] = answers.map((answer) => written(answer, patch));
@@ -104,32 +98,32 @@ export function checkDoors(app: App, entity: SchemaView, options: DoorOptions =
     });
 
     it('on delete', async () => {
-      const rows = await Promise.all([1, 2, 3, 4].map(() => doors.local('create', { input: inputOf() }))) as { id: string }[];
+      const rows = await Promise.all([1, 2, 3, 4].map(() => facades.local('create', { input: inputOf() }))) as { id: string }[];
 
       const answers = await Promise.all(
-        (['local', 'rpc', 'rest', 'graphql'] as const).map((door, index) => doors[door]('delete', { id: rows[index].id })),
+        (['local', 'rpc', 'rest', 'graphql'] as const).map((facade, index) => facades[facade]('delete', { id: rows[index].id })),
       );
 
       // REST answers a deletion with no content at all, which is the protocol saying yes.
       const onTheWire = answers.map((answer) => (answer === undefined || answer === null ? true : wire(answer)));
-      expect(new Set(onTheWire).size, `the doors disagree: ${JSON.stringify(onTheWire)}`).toBe(1);
+      expect(new Set(onTheWire).size, `the facades disagree: ${JSON.stringify(onTheWire)}`).toBe(1);
     });
 
     it('on a refusal', async () => {
-      // A refusal is where the doors diverge most, and where each is most tempted to
+      // A refusal is where the facades diverge most, and where each is most tempted to
       // answer in its own words. What must match is that it WAS refused.
       const bad = { ...inputOf(), __unknown__: 'x' };
       const refusals = await Promise.all(
-        (['local', 'rpc', 'rest', 'graphql'] as const).map((door) => refused(() => doors[door]('create', { input: bad }))),
+        (['local', 'rpc', 'rest', 'graphql'] as const).map((facade) => refused(() => facades[facade]('create', { input: bad }))),
       );
 
       expect(refusals[0], 'local accepted a body outside the contract').toBe(true);
-      expect(refusals, `the doors disagree: ${JSON.stringify(refusals)}`).toEqual([true, true, true, true]);
+      expect(refusals, `the facades disagree: ${JSON.stringify(refusals)}`).toEqual([true, true, true, true]);
     });
   });
 }
 
-/** Run one hand-written invocation contract through every door. */
+/** Run one hand-written invocation contract through every facade. */
 export function checkDoorContract(
   app: App,
   entity: SchemaView,
@@ -137,13 +131,13 @@ export function checkDoorContract(
   options: Pick<DoorOptions, 'surface'> = {},
 ): void {
   const name = lowerFirst(entity.name ?? '');
-  const doors = doorsOf(app, entity, name, options.surface);
+  const facades = facadesOf(app, entity, name, options.surface);
   const names = ['local', 'rpc', 'rest', 'graphql'] as const;
 
-  describe(`${entity.name} — its invocation contract crosses every door`, () => {
+  describe(`${entity.name} — its invocation contract crosses every facade`, () => {
     for (const one of cases) {
       it(one.name, async () => {
-        const answers = await Promise.all(names.map((door) => doors[door](one.operation, one.input)));
+        const answers = await Promise.all(names.map((facade) => facades[facade](one.operation, one.input)));
         for (const [index, answer] of answers.entries()) {
           expect(wire(answer), `${names[index]} disagrees with the canonical invocation`).toEqual(wire(one.expected));
         }
@@ -156,8 +150,8 @@ async function refused(call: () => Promise<unknown>): Promise<boolean> {
   try { await call(); return false; } catch { return true; }
 }
 
-/** The four doors, each reduced to `(op, input) => answer` so the tests above read alike. */
-function doorsOf(app: App, entity: SchemaView, name: string, surface?: string): Doors {
+/** The four facades, each reduced to `(op, input) => answer` so the tests above read alike. */
+function facadesOf(app: App, entity: SchemaView, name: string, surface?: string): Facades {
   const run = createLocalRunner(app, surface);
   const state: Record<string, unknown> = {};
 
@@ -181,7 +175,7 @@ function doorsOf(app: App, entity: SchemaView, name: string, surface?: string):
     },
 
     rest: async (op, call) => {
-      // The route the REST door itself would match, read from its own table — rebuilding
+      // The route the REST facade itself would match, read from its own table — rebuilding
       // the path here would be a second opinion on where an entity lives.
       const route = tableOf(app).find((one) => one.entityName === name && one.operationName === op);
       if (!route) throw new Error(`[checkDoors] REST serves no ${name}.${op}`);

package/src/DoorInput.ts

@@ -0,0 +1 @@
+export interface DoorInput { id?: string; input?: Record<string, unknown> }

package/src/DoorOptions.ts

@@ -0,0 +1,7 @@
+import { type SampleOptions } from './sample.js';
+
+export interface DoorOptions extends SampleOptions {
+  given?: Record<string, unknown>;
+  /** The audience, when the app serves named surfaces. */
+  surface?: string;
+}

package/src/all.ts

@@ -1,14 +1,16 @@
 import { describe, it, expect } from 'vitest';
 import type { App } from '@fougere/core';
 import type { SchemaView } from '@fougere/schema';
-import { checkContract, checkOutput, type CheckOptions } from './doors.js';
-import { checkDoors, type DoorOptions } from './comparison.js';
+import { type CheckOptions } from './facades/CheckOptions.js';
+import { checkContract, checkOutput } from './facades/Verdict.js';
+import { checkDoors } from './DoorContractCase.js';
+import { type DoorOptions } from './DoorOptions.js';
 
 export interface CheckAllOptions extends DoorOptions, CheckOptions {
   /** Entities to leave out, by name — one whose rows a test cannot seed, typically. */
   except?: string[];
-  /** Skip the four-door comparison. The contract and the leak are still checked. */
-  doors?: boolean;
+  /** Skip the four-facade comparison. The contract and the leak are still checked. */
+  facades?: boolean;
 }
 
 /** Every entity the app SERVES, with its handler. */
@@ -37,6 +39,6 @@ export function checkAll(app: App, options: CheckAllOptions = {}): void {
   for (const { entity } of served) {
     checkContract(app, entity, options);
     checkOutput(app, entity, options);
-    if (options.doors !== false) checkDoors(app, entity, options);
+    if (options.facades !== false) checkDoors(app, entity, options);
   }
 }

package/src/{app.ts → app/TestApp.ts}

@@ -2,33 +2,11 @@ import { type App } from '@fougere/core';
 import { boot } from '@fougere/compiler';
 import { createContainer } from '@fougere/container';
 import { resolveStorage, type DbConfig } from '@fougere/defaults';
-import { installStubs, type Port, type Stub } from './stub.js';
-import { scopeOfRun } from './scope.js';
+import { installStubs, type Stub } from '../stub/Stub.js';
+import type { Port } from '../stub/Port.js';
+import { scopeOfRun } from '../scope.js';
 import { lowerFirst } from '@fougere/schema';
-
-export interface TestAppOptions {
-  /** The project to scan. */
-  root?: string;
-  /** Boot only these fronds, by name. Deduced from the position when absent. */
-  fronds?: string[];
-  /**
-   * The running test file, for hosts other than vitest. Vitest is read automatically
-   * through `expect.getState()`; anything else hands its own path in.
-   */
-  testPath?: string;
-  /** Where the rows go. */
-  db?: string;
-  /**
-   * Follow `remotes:` from the config. False by default — a test that meant to exercise
-   * one frond should not silently reach for a process that is not running.
-   */
-  topology?: boolean;
-  /**
-   * Ports answered by a double instead of their realization. A double carries every
-   * method the port declares and returns nothing until the test says what it returns.
-   */
-  stub?: Port[];
-}
+import type { TestAppOptions } from './TestAppOptions.js';
 
 /** An app, plus the doubles standing in front of its ports and the facts it announced. */
 export interface TestApp extends App {

package/src/app/TestAppOptions.ts

@@ -0,0 +1,25 @@
+import type { Port } from '../stub/Port.js';
+
+export interface TestAppOptions {
+  /** The project to scan. */
+  root?: string;
+  /** Boot only these fronds, by name. Deduced from the position when absent. */
+  fronds?: string[];
+  /**
+   * The running test file, for hosts other than vitest. Vitest is read automatically
+   * through `expect.getState()`; anything else hands its own path in.
+   */
+  testPath?: string;
+  /** Where the rows go. */
+  db?: string;
+  /**
+   * Follow `remotes:` from the config. False by default — a test that meant to exercise
+   * one frond should not silently reach for a process that is not running.
+   */
+  topology?: boolean;
+  /**
+   * Ports answered by a double instead of their realization. A double carries every
+   * method the port declares and returns nothing until the test says what it returns.
+   */
+  stub?: Port[];
+}

package/src/facades/CheckOptions.ts

@@ -0,0 +1,6 @@
+import { type SampleOptions } from '../sample.js';
+
+export interface CheckOptions extends SampleOptions {
+  /** Values the generator cannot invent — the id of a row a `ref()` points at. */
+  given?: Record<string, unknown>;
+}

package/src/{doors.ts → facades/Verdict.ts}

@@ -3,16 +3,17 @@ import { createLocalRunner, validationErrorsOf, type App } from '@fougere/core';
 import { Invocation } from '@fougere/core/contract';
 import { lowerFirst, Visibility, type SchemaView, type ValidationError } from '@fougere/schema';
 import { Cases } from '@fougere/schema';
-import { derivedCases } from './derive.js';
-import { sampleInput, replaySeed, type SampleOptions } from './sample.js';
+import { derivedCases } from '../derive.js';
+import { sampleInput, replaySeed } from '../sample.js';
+import type { CheckOptions } from './CheckOptions.js';
 
-/** The one shape both the local validator and a door already speak. */
+/** The one shape both the local validator and a facade already speak. */
 export interface Verdict {
   success: boolean;
   errors?: ValidationError[];
 }
 
-/** What a door answers, in the shape a verdict is compared in. */
+/** What a facade answers, in the shape a verdict is compared in. */
 export async function verdictOf(call: () => Promise<unknown>): Promise<Verdict> {
   try {
     await call();
@@ -29,11 +30,6 @@ function opsFor(entity: SchemaView): { create: string; update: string; name: str
   return { name, create: 'create', update: 'update' };
 }
 
-export interface CheckOptions extends SampleOptions {
-  /** Values the generator cannot invent — the id of a row a `ref()` points at. */
-  given?: Record<string, unknown>;
-}
-
 /** The declared contract, posed to the façade that will receive it. */
 export function checkContract(app: App, entity: SchemaView, options: CheckOptions = {}): void {
   const { name, create, update } = opsFor(entity);

package/src/index.ts

@@ -1,15 +1,15 @@
 export { sampleInput } from './sample.js';
 // The derivation itself lives with the axes it reads.
 export { Cases, type ValidationCase } from '@fougere/schema';
-export { testApp } from './app.js';
-export { checkContract, checkOutput, verdictOf, type Verdict } from './doors.js';
-export { stubOf, type Port, type Stub } from './stub.js';
+export { testApp } from './app/TestApp.js';
+export { checkContract, checkOutput, verdictOf, type Verdict } from './facades/Verdict.js';
+export { type Port } from './stub/Port.js';
+export { stubOf, type Stub } from './stub/Stub.js';
 export { frondOf, type Scope } from './scope.js';
-export { loadScript } from './load.js';
-export {
-  checkDoorContract,
-  checkDoors,
-} from './comparison.js';
+export { loadScript, reachableOps } from './load.js';
+export { statementsOf } from './statements.js';
+export { spansOf } from './spans.js';
+export { checkDoorContract, checkDoors } from './DoorContractCase.js';
 export { at } from './gql.js';
 export { driftOf, agrees, explain, type CardDrift } from './remotes.js';
 export { checkAll } from './all.js';

package/src/load.ts

@@ -1,11 +1,25 @@
 import { frameCall } from '@fougere/transport-http';
-import type { App } from '@fougere/core';
+import { resolveEffectiveOperations } from '@fougere/core';
+import type { FrondDescriptor } from '@fougere/core/descriptor';
+
+/**
+ * What a load script is read from: the fronds, and nothing else.
+ *
+ * An `App` satisfies it, and so does a scan — which is what lets `fougere load` answer without
+ * booting the project it describes. A boot runs migrations and seeds, so a command that wrote a
+ * scenario would also write to the target's database.
+ */
+interface Serving {
+  fronds: readonly FrondDescriptor[];
+}
 import type { SchemaView } from '@fougere/schema';
 import { sampleInput } from './sample.js';
 
 export interface LoadOptions {
-  /** Where the calls go. The RPC door of a running app. */
-  door?: string;
+  /** Where the calls go. The RPC facade of a running app. */
+  facade?: string;
+  /** The topology statement, so an op that crosses a process is given the time to. */
+  remotes?: Record<string, string>;
   /** Values the generator cannot invent, by entity name — the id a `ref()` points at. */
   given?: Record<string, Record<string, unknown>>;
 }
@@ -13,21 +27,31 @@ export interface LoadOptions {
 interface Reachable {
   method: string;
   input: unknown;
+  /** How many times this op's work crosses a process — what its budget is a function of. */
+  hops: number;
 }
 
 /** Every operation the app answers, with a body for those that take one. */
-export function reachableOps(app: App, given: LoadOptions['given'] = {}): Reachable[] {
+export function reachableOps(
+  app: Serving,
+  given: LoadOptions['given'] = {},
+  remotes: Record<string, string> = {},
+): Reachable[] {
+  const { operations } = resolveEffectiveOperations(app.fronds, { remotes });
+  const hops = new Map(operations.map((op) => [`${op.handler.address}.${op.name}`, op.reach.hops]));
   const found: Reachable[] = [];
   for (const frond of app.fronds) {
     for (const handler of frond.handlers) {
-      // A named surface is a restricted door; the load of an app is what its default
-      // door answers, so a surface would count the same operation twice.
+      // A named surface is a restricted facade; the load of an app is what its default
+      // facade answers, so a surface would count the same operation twice.
       if (handler.surface) continue;
       for (const [op, contract] of handler.operations ?? []) {
         const schema = contract.input as SchemaView | undefined;
+        const method = `${handler.address}.${op}`;
         found.push({
-          method: `${handler.address}.${op}`,
+          method,
           input: schema ? sampleInput(schema, given[handler.address] ?? {}) : undefined,
+          hops: hops.get(method) ?? 0,
         });
       }
     }
@@ -36,9 +60,9 @@ export function reachableOps(app: App, given: LoadOptions['given'] = {}): Reacha
 }
 
 /** A k6 scenario, written from what the app answers. */
-export function loadScript(app: App, options: LoadOptions = {}): string {
-  const door = options.door ?? 'http://127.0.0.1:3000/_fougere/call';
-  const ops = reachableOps(app, options.given);
+export function loadScript(app: Serving, options: LoadOptions = {}): string {
+  const facade = options.facade ?? 'http://127.0.0.1:3000/_fougere/call';
+  const ops = reachableOps(app, options.given, options.remotes ?? {});
   // The shape, from the one function that states it. `body` is replaced per iteration.
   const envelope = frameCall({ entity: 'ENTITY', op: 'OP' }, { params: {}, query: {}, input: undefined, state: {} } as never, 0);
   // What the envelope carries that an iteration does not fill in itself. Keeping
@@ -51,11 +75,17 @@ export function loadScript(app: App, options: LoadOptions = {}): string {
 import http from 'k6/http';
 import { check } from 'k6';
 
-const DOOR = ${JSON.stringify(door)};
+const DOOR = ${JSON.stringify(facade)};
 
 // Every operation the app serves. A weight of 0 takes one out, visibly.
 const OPS = ${JSON.stringify(ops.map((op) => ({ ...op, weight: 1 })), null, 2)};
 
+// Yours: how long an op may take here, and what one process boundary is allowed to add. Two
+// numbers instead of one, because an op that crosses nothing and an op that crosses twice were
+// never the same subject — hops above is read from the code, these two are facts about your
+// network.
+const BUDGET = { base: 300, perHop: 200 };
+
 export const options = {
   // Yours: a flat rate draws flat lines and there is nothing to read in them.
   stages: [
@@ -63,8 +93,17 @@ export const options = {
     { duration: '45s', target: 5 },
     { duration: '30s', target: 0 },
   ],
-  // Yours: what counts as too slow is a fact about your users.
-  thresholds: { http_req_failed: ['rate<0.01'], http_req_duration: ['p(95)<500'] },
+  // Yours: the shape of the run.
+  // Derived from BUDGET and each op's hops — an op that crosses two processes is not held to
+  // the same figure as one that never leaves. k6 reads a threshold per tag, and every call
+  // below is tagged with the op it made.
+  thresholds: {
+    http_req_failed: ['rate<0.01'],
+    ...Object.fromEntries(OPS.map((op) => [
+      \`http_req_duration{op:\${op.method}}\`,
+      [\`p(95)<\${BUDGET.base + op.hops * BUDGET.perHop}\`],
+    ])),
+  },
 };
 
 const TOTAL = OPS.reduce((sum, op) => sum + op.weight, 0);

package/src/spans.ts

@@ -0,0 +1,66 @@
+import type { App } from '@fougere/core';
+import type { FinishedSpan } from '@fougere/observability';
+
+/** One tracer per app: `app.use` has no undo, so a second call would stack a middleware. */
+const installed = new WeakMap<App, FinishedSpan[][]>();
+
+/**
+ * The steps one call opened — the operation, then whatever ran under it.
+ *
+ * The dual of [statementsOf]: that one counts what a call asked the database, this one holds
+ * the shape of the call itself. What it is FOR is a test about structure rather than speed —
+ * an op that delegates reports almost no self time, whatever the machine it runs on:
+ *
+ * ```ts
+ * const [op] = await spansOf(app, () => facade.list());
+ * expect(op.selfMs).toBeLessThan(0.1 * op.ms);   // it delegates, it does not work
+ * ```
+ *
+ * A threshold in milliseconds tests the machine. A ratio tests the code.
+ */
+export async function spansOf(app: App, run: () => Promise<unknown>): Promise<FinishedSpan[]> {
+  const collecting = await tracerOf(app);
+  const spans: FinishedSpan[] = [];
+  collecting.push(spans);
+
+  try {
+    await run();
+  } finally {
+    collecting.splice(collecting.indexOf(spans), 1);
+  }
+
+  return spans;
+}
+
+async function tracerOf(app: App): Promise<FinishedSpan[][]> {
+  const held = installed.get(app);
+  if (held) return held;
+
+  const { statementsUnder, tracing } = await observability();
+  const collecting: FinishedSpan[][] = [];
+  installed.set(app, collecting);
+  // A test IS the diagnosis, so it asks for the detail a process running continuously does not.
+  const tracer = tracing(
+    [(span) => { for (const into of collecting) into.push(span); }],
+    { spanPerStatement: true },
+  );
+  app.use(tracer.middleware);
+  // Both halves, or `selfMs` would read as if the handler did the waiting itself. The
+  // subscription lives as long as the test process: `app.use` has no undo either, and one
+  // app per file is what a test file has.
+  await statementsUnder(tracer);
+
+  return collecting;
+}
+
+/** Optional, and dynamic for the reason `@fougere/calls` states: this package depends on none. */
+async function observability(): Promise<typeof import('@fougere/observability')> {
+  try {
+    return await import('@fougere/observability');
+  } catch {
+    throw new Error(
+      '[spansOf] reading what a call cost needs @fougere/observability — install it, '
+      + 'or there is no span to read.',
+    );
+  }
+}

package/src/statements.ts

@@ -0,0 +1,41 @@
+import type { QueryEvent } from '@fougere/adapter-sql';
+
+/**
+ * Every statement a call ran, in order.
+ *
+ * `testApp` boots on real SQLite, so this is what the handler actually asked the database —
+ * one per row is the shape of an N+1, and it is a number a test can refuse. A computed field
+ * that reads is the case: the façade hands the presenter the whole PAGE, so one query is
+ * possible, and nothing refuses `Promise.all(rows.map(…))` inside the field body.
+ *
+ * It REFUSES when `@fougere/adapter-sql` is absent, where the tracer degrades quietly: zero
+ * is what a passing assertion looks like, so an app observing nothing would turn this into a
+ * test that cannot fail.
+ *
+ * What it counts is the PROCESS, not the call — everything running while the block runs.
+ */
+export async function statementsOf(run: () => Promise<unknown>): Promise<QueryEvent[]> {
+  const { onQuery } = await sql();
+  const ran: QueryEvent[] = [];
+  const stop = onQuery((event) => ran.push(event));
+
+  try {
+    await run();
+  } finally {
+    stop();
+  }
+
+  return ran;
+}
+
+/** Optional, and dynamic for the reason `@fougere/calls` states: this package depends on none. */
+async function sql(): Promise<typeof import('@fougere/adapter-sql')> {
+  try {
+    return await import('@fougere/adapter-sql');
+  } catch {
+    throw new Error(
+      '[statementsOf] counting statements needs @fougere/adapter-sql — install it, '
+      + 'or the count is zero whatever the handler ran.',
+    );
+  }
+}

package/src/stub/Port.ts

@@ -0,0 +1,2 @@
+/** Anything a provider can be declared as: a class the container knows how to build. */
+export type Port = abstract new (...args: never[]) => unknown;

package/src/{stub.ts → stub/Stub.ts}

@@ -1,9 +1,7 @@
 import { vi, type Mock } from 'vitest';
 import type { Container } from '@fougere/container';
 import type { App } from '@fougere/core';
-
-/** Anything a provider can be declared as: a class the container knows how to build. */
-export type Port = abstract new (...args: never[]) => unknown;
+import type { Port } from './Port.js';
 
 /** The double handed in place of a port — one spy per method the port declares. */
 export type Stub<T> = { [K in keyof T]: T[K] extends (...args: never[]) => unknown ? Mock : T[K] };

package/src/{sync.ts → sync/SyncDrift.ts}

@@ -1,16 +1,8 @@
-import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { Card, type Change, type SchemaDescriptor, type SchemaView } from '@fougere/schema';
 import type { IdentityCard } from '@fougere/core';
-
-/** One entry of `.fougere/remotes.json`, written by `fougere sync`. */
-export interface SyncedRemote {
-  name: string;
-  url: string;
-  /** Where the synced classes were written. */
-  path: string;
-}
+import type { SyncedRemote } from './SyncedRemote.js';
 
 /** What separates a consumer's synced copy from what the producer serves today. */
 export interface SyncDrift {
@@ -21,18 +13,6 @@ export interface SyncDrift {
   moved: { entity: string; changes: Change[] }[];
 }
 
-/** The remotes a project synced, read from the file `fougere sync` writes. */
-export async function syncedRemotes(root: string): Promise<SyncedRemote[]> {
-  try {
-    const raw = await readFile(join(root, '.fougere', 'remotes.json'), 'utf8');
-    const parsed = JSON.parse(raw) as Record<string, { url: string; path: string }>;
-    return Object.entries(parsed).map(([name, one]) => ({ name, ...one }));
-  } catch {
-    // No file is the ordinary case: an app with no remote synced nothing.
-    return [];
-  }
-}
-
 /** The shapes a consumer holds for one remote frond. */
 export async function heldShapes(remote: SyncedRemote): Promise<Map<string, SchemaDescriptor>> {
   const cards = new Map<string, SchemaDescriptor>();
@@ -47,12 +27,12 @@ export async function heldShapes(remote: SyncedRemote): Promise<Map<string, Sche
   return cards;
 }
 
-/** The shapes a card announces, by the name a door carries. */
+/** The shapes a card announces, by the name a facade carries. */
 function servedShapes(card: IdentityCard, frond: string): Map<string, unknown> {
   const served = new Map<string, unknown>();
   for (const one of card.fronds) {
     if (one.name !== frond) continue;
-    for (const door of one.doors) if (door.schema) served.set(door.schema.title ?? door.name, door.schema);
+    for (const facade of one.facades) if (facade.schema) served.set(facade.schema.title ?? facade.name, facade.schema);
   }
   return served;
 }