@fougere/cli 0.2.0-alpha.2 → 0.4.0-alpha.0

package/fronds/analysis/handlers/CheckHandler.ts

@@ -1,4 +1,10 @@
-import { buildGraph, clusterEntities, crossFrondImports, resolveContracts, type ScanDiagnostic } from '@fougere/core';
+import {
+  buildGraph,
+  clusterEntities,
+  resolveEffectiveOperations,
+  type ScanDiagnostic,
+} from '@fougere/core';
+import { crossFrondImports } from '@fougere/core/node';
 import ProjectScan from '../services/ProjectScan.js';
 
 /** One thing that does not hold, in the terms of whoever has to fix it. */
@@ -8,6 +14,12 @@ export interface Finding {
   code: string;
   /** Where to go and look. */
   filePath: string;
+  /**
+   * What the finding is ABOUT — `PostHandler.whoNull(user)` — when the rule holds it
+   * as a fact rather than inside its sentence. Two ops of one handler breaking the
+   * same rule read as one repeated line without it.
+   */
+  subject?: string;
   /** What is wrong, and what it costs. One sentence. */
   message: string;
 }
@@ -18,57 +30,38 @@ export interface CheckResult {
   findings: Finding[];
 }
 
+/** Shared with `fougere graph` — one threshold, so the two never disagree. */
+const DOMAIN_SPLIT_MIN_ENTITIES = 6;
+
 /**
  * What does not hold in this app — derived from its declarations, not from tests.
  *
  * It scans rather than boots — see `ProjectScan`, which states what that costs.
  *
- * Two rules today, and the shape for the rest:
+ * It raises no operation-resolution rule of its own: those findings come from the same
+ * EffectiveOperation resolver boot consumes. The remaining findings come from their
+ * existing owners — scan diagnostics, the import reader and domain clustering. A second
+ * opinion here would report what the runtime does not serve, precisely what a checker
+ * must avoid.
  *
- *   - what the scan could not do (`ScanResult.diagnostics`) — an unreadable
- *     directory, a handler that would not parse, an `extends` it could not follow;
- *   - an operation whose parameters have no binding plan — it is served, and it
- *     receives nothing;
- *   - a relative import that resolves into another frond — a colocation constraint
- *     nothing declares, which holds until the day the other frond is not on this disk.
- *
- * A rule about an ABSENCE is only sound if the analysis attests it looked, which
- * is why the first bullet had to exist before this command could.
+ * A rule about an ABSENCE is only sound if the analysis attests it looked, which is
+ * why the scan's diagnostics had to exist before this command could.
  */
-/** Shared with `fougere graph` — one threshold, so the two never disagree. */
-const DOMAIN_SPLIT_MIN_ENTITIES = 6;
-
 export default class CheckHandler {
   constructor(private projectScan: ProjectScan) {}
 
   /** Report what does not hold in a Fougere app, without booting it. */
   async execute(input: { root?: string }): Promise<CheckResult> {
-    const { fronds, diagnostics } = await this.projectScan.at(input.root);
-    const findings: Finding[] = diagnostics.map(asFinding);
-    let handlers = 0;
-
-    for (const frond of fronds) {
-      const collectorEntityNames = new Set(frond.collectors.map((c) => c.entityName));
-      for (const handler of frond.handlers) {
-        handlers++;
-        // The same merge the façade performs — asked for, not redone. A second
-        // opinion here would report a contract the runtime does not serve.
-        const contracts = resolveContracts(handler, frond.operationsOverrides, collectorEntityNames);
-
-        for (const [op, contract] of contracts) {
-          const params = contract.signature?.params.length ?? 0;
-          if (params > 0 && !contract.binding) {
-            findings.push({
-              severity: 'blocking',
-              code: 'operation-unbound',
-              filePath: handler.filePath,
-              message: `${handler.ctor.name}.${op} declares ${params} parameter(s) and has no `
-                + `binding plan — it is served, and it receives none of them.`,
-            });
-          }
-        }
-      }
-    }
+    const { fronds, diagnostics, config } = await this.projectScan.at(input.root);
+    // This is the same pure resolution the boot consumes. No app lifecycle, database,
+    // migration, seed or adapter mount is needed for a global semantic check.
+    const model = resolveEffectiveOperations(fronds, {
+      diagnostics,
+      remotes: config.remotes,
+      adapters: config.adapters,
+    });
+    const findings: Finding[] = model.diagnostics.map(asFinding);
+    const handlers = fronds.reduce((count, frond) => count + frond.handlers.length, 0);
 
     /**
      * Entity groups with no `ref()` between them, in one frond. Reported as a FACT, not a
@@ -113,5 +106,11 @@ export default class CheckHandler {
 
 /** A scan diagnostic IS a finding — same vocabulary, so the renderer has one shape. */
 function asFinding(d: ScanDiagnostic): Finding {
-  return { severity: d.severity, code: d.code, filePath: d.filePath, message: d.message };
+  return {
+    severity: d.severity,
+    code: d.code,
+    filePath: d.filePath,
+    subject: d.subject,
+    message: d.message,
+  };
 }

package/fronds/analysis/handlers/ExplainHandler.ts

@@ -0,0 +1,254 @@
+import {
+  resolveEffectiveOperations,
+  type EffectiveOperation,
+  type OperationContract,
+} from '@fougere/core';
+import { relative } from 'node:path';
+import ProjectScan from '../services/ProjectScan.js';
+import { ANONYMOUS_SCHEMA_NAME, lowerFirst, type SchemaView } from '@fougere/schema';
+
+type Cardinality = NonNullable<OperationContract['cardinality']>;
+type Binding = EffectiveOperation['binding'][number];
+
+export type ExplainedBinding =
+  | { kind: 'collector'; typeName: string }
+  | { kind: 'fact'; factName: string }
+  | { kind: 'param'; name: string; coerce?: 'number' | 'boolean' }
+  | { kind: 'body' }
+  | { kind: 'context' }
+  | { kind: 'query' };
+
+export interface ExplainedParameter {
+  name: string;
+  type: string | null;
+  optional: boolean;
+  nullable: boolean;
+  undefinable: boolean;
+  binding: ExplainedBinding | null;
+}
+
+export interface ExplainedCollector {
+  typeName: string;
+  class: string;
+  file: string;
+}
+
+/** Stable, JSON-shaped projection of core's canonical EffectiveOperation. */
+export interface ExplainResult {
+  operation: string;
+  handler: {
+    class: string;
+    address: string;
+    method: string;
+    file: string | null;
+  };
+  kind: 'query' | 'command';
+  description: string | null;
+  input: string | null;
+  output: { type: string; cardinality: Cardinality | null } | null;
+  parameters: ExplainedParameter[];
+  collectors: ExplainedCollector[];
+  contexts: string[];
+  semantics: EffectiveOperation['semantics'];
+  exposure: {
+    surfaces: string[];
+    adapters: string[];
+  };
+  placement: {
+    frond: string;
+    runtime: 'local' | 'remote';
+    remote: string | null;
+  };
+}
+
+/** What this project serves, when no single operation was named. */
+export interface ExplainListing {
+  fronds: {
+    name: string;
+    runtime: 'local' | 'remote';
+    remote: string | null;
+    operations: number;
+  }[];
+  operations: string[];
+}
+
+interface Selector {
+  frond?: string;
+  surface?: string;
+  address: string;
+  op: string;
+}
+
+/** Read one operation directly from the model boot and check also consume. */
+export default class ExplainHandler {
+  constructor(private projectScan: ProjectScan) {}
+
+  /** The names this project serves — the list `explain` used to spell in a refusal only. */
+  async list(input: { root?: string }): Promise<ExplainListing> {
+    const { scan, model } = await this.modelOf(input.root);
+    const remotes = scan.config.remotes ?? {};
+    const counted = new Map<string, number>();
+    for (const operation of model.operations) {
+      const frond = operation.placement.frond;
+      counted.set(frond, (counted.get(frond) ?? 0) + 1);
+    }
+
+    return {
+      fronds: scan.fronds.map((frond) => ({
+        name: frond.name,
+        runtime: remotes[frond.name] ? 'remote' as const : 'local' as const,
+        remote: remotes[frond.name] ?? null,
+        operations: counted.get(frond.name) ?? 0,
+      })).sort((a, b) => a.name.localeCompare(b.name)),
+      operations: model.operations.map((operation) => operation.id).sort(),
+    };
+  }
+
+  private async modelOf(root?: string) {
+    const scan = await this.projectScan.at(root);
+    return {
+      scan,
+      model: resolveEffectiveOperations(scan.fronds, {
+        diagnostics: scan.diagnostics,
+        remotes: scan.config.remotes,
+        adapters: scan.config.adapters,
+      }),
+    };
+  }
+
+  /** Print the contract one operation will be served under. */
+  async execute(input: { operation?: string; root?: string; json?: boolean }): Promise<ExplainResult> {
+    const requested = input.operation?.trim();
+    if (!requested) throw new Error('Usage: fougere explain <Operation> [--json] [--root <directory>]');
+
+    const selector = parseSelector(requested);
+    const { scan, model } = await this.modelOf(input.root);
+    const candidates = model.operations.filter((operation) => matches(operation, selector));
+
+    if (candidates.length === 0) {
+      const failed = model.resolutionDiagnostics.find((diagnostic) =>
+        diagnostic.subject?.toLowerCase().includes(`.${selector.op.toLowerCase()}`)
+        && diagnostic.subject.toLowerCase().includes(selector.address.toLowerCase()));
+      if (failed) throw new Error(`[${failed.code}] ${failed.message}`);
+
+      const available = model.operations.map((operation) => operation.id).sort();
+      throw new Error(
+        `Unknown operation '${requested}'. `
+        + (available.length > 0
+          ? `Available operations: ${available.join(', ')}.`
+          : 'This project exposes no resolved operation.'),
+      );
+    }
+
+    if (candidates.length > 1) {
+      throw new Error(
+        `Ambiguous operation '${requested}'. Matches: `
+        + `${candidates.map((operation) => operation.id).sort().join(', ')}. `
+        + 'Use one of these qualified names.',
+      );
+    }
+
+    const selected = candidates[0]!;
+    const invalid = model.resolutionDiagnostics.find((diagnostic) =>
+      diagnostic.subject?.startsWith(`${selected.handler.className}.${selected.name}`));
+    if (invalid) throw new Error(`[${invalid.code}] ${invalid.message}`);
+
+    return project(selected, scan.root);
+  }
+}
+
+function project(operation: EffectiveOperation, root: string): ExplainResult {
+  return {
+    operation: operation.operation,
+    handler: {
+      class: operation.implementation.className,
+      address: operation.handler.address,
+      method: operation.implementation.method,
+      file: operation.implementation.filePath
+        ? relative(root, operation.implementation.filePath)
+        : null,
+    },
+    kind: operation.kind,
+    description: operation.description ?? null,
+    input: inputTypeOf(operation),
+    output: outputOf(operation),
+    parameters: operation.parameters.map((parameter) => ({
+      name: parameter.name,
+      type: parameter.type,
+      optional: parameter.optional,
+      nullable: parameter.nullable,
+      undefinable: parameter.undefinable,
+      binding: bindingOf(parameter.binding),
+    })),
+    collectors: operation.collectors.map((collector) => ({
+      typeName: collector.typeName,
+      class: collector.className,
+      file: relative(root, collector.filePath),
+    })),
+    contexts: operation.contexts,
+    semantics: operation.semantics,
+    exposure: operation.exposure,
+    placement: {
+      frond: operation.placement.frond,
+      runtime: operation.placement.runtime,
+      remote: operation.placement.remote ?? null,
+    },
+  };
+}
+
+function parseSelector(value: string): Selector {
+  const dot = value.lastIndexOf('.');
+  if (dot <= 0 || dot === value.length - 1) {
+    throw new Error(`Invalid operation '${value}'. Expected '<Handler>.<method>', for example 'Post.publish'.`);
+  }
+
+  const path = value.slice(0, dot).split('/').filter(Boolean);
+  if (path.length === 0 || path.length > 3) {
+    throw new Error(`Invalid operation '${value}'. Expected 'Post.publish', 'blog/Post.publish', or 'blog/public/Post.publish'.`);
+  }
+
+  const qualifiers = path.slice(0, -1);
+  return {
+    ...(qualifiers[0] ? { frond: qualifiers[0] } : {}),
+    ...(qualifiers[1] ? { surface: qualifiers[1] } : {}),
+    address: addressOf(path.at(-1)!),
+    op: value.slice(dot + 1),
+  };
+}
+
+function matches(operation: EffectiveOperation, selector: Selector): boolean {
+  return operation.handler.address.toLowerCase() === selector.address.toLowerCase()
+    && operation.name === selector.op
+    && (!selector.frond || operation.placement.frond === selector.frond)
+    && (!selector.surface || operation.exposure.surfaces.includes(selector.surface));
+}
+
+function addressOf(value: string): string {
+  const base = value.endsWith('Handler') ? value.slice(0, -'Handler'.length) : value;
+  return lowerFirst(base);
+}
+
+function inputTypeOf(operation: EffectiveOperation): string | null {
+  const body = operation.parameters.find((parameter) => parameter.binding.source.kind === 'body');
+  return body?.type ?? schemaName(operation.input) ?? null;
+}
+
+function outputOf(operation: EffectiveOperation): ExplainResult['output'] {
+  const type = schemaName(operation.output) ?? parsedOutput(operation.signature?.returnType?.raw);
+  return type ? { type, cardinality: operation.cardinality ?? null } : null;
+}
+
+function schemaName(schema: SchemaView | undefined): string | undefined {
+  if (!schema) return undefined;
+  if (schema.name && schema.name !== ANONYMOUS_SCHEMA_NAME) return schema.name;
+  return schema.derivation?.sourceName;
+}
+
+function parsedOutput(raw: string | undefined): string | undefined {
+  if (!raw) return undefined;
+  return raw.startsWith('Promise<') && raw.endsWith('>') ? raw.slice(8, -1) : raw;
+}
+
+function bindingOf(binding: Binding): ExplainedBinding {
+  return { ...binding.source } as ExplainedBinding;
+}

package/fronds/analysis/handlers/FreezeHandler.ts

@@ -0,0 +1,176 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Bundle, lowerFirst, type SchemaBundle, type SchemaView, type SetDiff } from '@fougere/schema';
+import ProjectScan from '../services/ProjectScan.js';
+import { VERSIONS, chainOf } from '../versions.js';
+import type Freeze from '../entities/Freeze.js';
+
+export interface FreezeInspection {
+  version: string;
+  /** The version this one follows, or absent when it is the first. */
+  previous?: string;
+  entities: string[];
+  /** What the step contains — absent when there is nothing before to step from. */
+  step?: SetDiff;
+  /** Per entity, the pairs the calculation refuses to decide. Empty means it was written. */
+  ambiguous: Record<string, { removed: string; added: string }[]>;
+  /** Whether anything reached the disk — false while a question stands. */
+  written: boolean;
+}
+
+/**
+ * Freezing a version — the artefact three readers share.
+ *
+ * A snapshot alone loses the INTENT (a field gone plus a field appeared cannot be told
+ * from a rename), and a step alone corrupts in silence. Both are written, and replaying
+ * the step over the previous snapshot must reproduce this one — which is what catches a
+ * missing step or a hand-edited file.
+ *
+ * Nothing is written while an ambiguity stands: the only information the code does not
+ * hold is what the person who made the change meant, and this is the one place asking
+ * for it is justified.
+ */
+export default class FreezeHandler {
+  constructor(private projectScan: ProjectScan) {}
+
+  /**
+   * Record this version — or report what stops it, having written nothing.
+   *
+   * One op and not two: it is idempotent while it refuses, so a caller settles the
+   * ambiguities and calls again with `renamed`. Splitting it would let a caller write
+   * a version it never inspected.
+   */
+  async execute(input: Freeze & { renamed?: Record<string, Record<string, string>> }): Promise<FreezeInspection> {
+    const fronds = await this.read(input);
+    const version = input.version;
+    const entities = fronds.flatMap(({ bundle }) => Object.keys(bundle.$defs ?? {}));
+    // Two entrances, one map: what the entities declare, and what a caller answered.
+    // The answer wins — it is the later word on a question the declaration left open.
+    const renamed = settled(fronds.map(({ declared }) => declared), input.renamed ?? {});
+
+    // Every frond is inspected before ANY of them writes: a question standing in one
+    // frond must not leave the others recorded, or a second run cuts half a version.
+    const inspected = fronds.map(({ path, bundle, previous }) => ({
+      path,
+      bundle,
+      previous,
+      step: previous
+        ? Bundle.fromDescriptor(previous.bundle).diff(Bundle.fromDescriptor(bundle), { renamed })
+        : undefined,
+    }));
+
+    const ambiguous: FreezeInspection['ambiguous'] = {};
+    for (const { step } of inspected) {
+      for (const [name, answer] of Object.entries(step?.entities ?? {})) {
+        if (answer.ambiguous.length > 0) ambiguous[name] = answer.ambiguous;
+      }
+    }
+    // Nothing on disk while a question stands. The only information the code does not
+    // hold is what the person who made the change meant.
+    if (Object.keys(ambiguous).length > 0) {
+      return { version, previous: previousName(inspected), entities, step: merge(inspected), ambiguous, written: false };
+    }
+
+    for (const { path, bundle, previous, step } of inspected) {
+      await this.record(path, version, bundle);
+      if (!previous || !step) continue;
+      // `previous` is recorded rather than re-derived: the chain is a fact of the moment
+      // this version was cut, and a later sort of directory names is not that fact.
+      await writeFile(
+        join(path, VERSIONS, version, 'from.json'),
+        `${JSON.stringify({ previous: previous.name, renamed, ...step }, null, 2)}\n`,
+      );
+    }
+
+    return { version, previous: previousName(inspected), entities, step: merge(inspected), ambiguous: {}, written: true };
+  }
+
+  private async record(root: string, version: string, bundle: SchemaBundle): Promise<void> {
+    const directory = join(root, VERSIONS, version);
+    await mkdir(directory, { recursive: true });
+    await writeFile(join(directory, 'shape.json'), `${JSON.stringify(bundle, null, 2)}\n`);
+  }
+
+  /**
+   * Today's shapes and the version before them, one entry per frond.
+   *
+   * `Fronds.schemas()` is deliberately flat — a fact heard in one frond is declared in
+   * another — so the per-frond map is built here, where the question IS per frond.
+   */
+  private async read(input: Freeze) {
+    const scan = await this.projectScan.at(input.root ?? undefined);
+    return Promise.all(
+      scan.fronds
+        .filter((frond) => frond.entities.length > 0)
+        .map(async (frond) => ({
+          path: frond.source.path,
+          bundle: Bundle.fromSchemas(
+            Object.fromEntries(frond.entities.map((e) => [e.name, e.entityClass])),
+          ).descriptor,
+          declared: declaredRenames(frond.entities),
+          previous: await previousOf(frond.source.path, input.version),
+        })),
+    );
+  }
+}
+
+type Inspected = { previous?: { name: string }; step?: SetDiff };
+
+/**
+ * What the entities state about themselves — `previous` says what a field WAS, while
+ * `Bundle.diff` reads old to new, so the pair is turned around here and nowhere else.
+ */
+function declaredRenames(
+  entities: readonly { name: string; entityClass: unknown }[],
+): Record<string, Record<string, string>> {
+  const out: Record<string, Record<string, string>> = {};
+  for (const { name, entityClass } of entities) {
+    const previous = (entityClass as SchemaView).previous;
+    // Keyed as `Bundle.fromSchemas` keys `$defs`, which is what `Bundle.diff` reads. Spelling the
+    // convention a second way here is the defect this repo has already recorded twice.
+    const key = lowerFirst(name);
+    if (previous) out[key] = Object.fromEntries(Object.entries(previous).map(([now, was]) => [was, now]));
+  }
+  return out;
+}
+
+/** Every source of an answer, folded per entity — later sources win field by field. */
+function settled(
+  sources: readonly Record<string, Record<string, string>>[],
+  answers: Record<string, Record<string, string>>,
+): Record<string, Record<string, string>> {
+  const out: Record<string, Record<string, string>> = {};
+  for (const source of [...sources, answers]) {
+    for (const [entity, pairs] of Object.entries(source)) out[entity] = { ...out[entity], ...pairs };
+  }
+  return out;
+}
+
+/** The version every frond steps from. They are cut together, so they agree. */
+function previousName(inspected: readonly Inspected[]): string | undefined {
+  return inspected.find(({ previous }) => previous)?.previous?.name;
+}
+
+/**
+ * One report out of several fronds — entity names are unique across a scan, so the
+ * union loses nothing. Writing stays per frond; only the telling is gathered.
+ */
+function merge(inspected: readonly Inspected[]): SetDiff | undefined {
+  const steps = inspected.map(({ step }) => step).filter((step): step is SetDiff => Boolean(step));
+  if (steps.length === 0) return undefined;
+  return {
+    entities: Object.assign({}, ...steps.map((step) => step.entities)),
+    entitiesAdded: steps.flatMap((step) => step.entitiesAdded),
+    entitiesRemoved: steps.flatMap((step) => step.entitiesRemoved),
+  };
+}
+
+/** The version this one steps from: the tip of the chain, the links read rather than sorted. */
+async function previousOf(root: string, version: string): Promise<{ name: string; bundle: SchemaBundle } | undefined> {
+  const chain = (await chainOf(root)).filter((cut) => cut.name !== version);
+  const last = chain.at(-1)?.name;
+  if (!last) return undefined;
+
+  const raw = await readFile(join(root, VERSIONS, last, 'shape.json'), 'utf8').catch(() => undefined);
+  return raw ? { name: last, bundle: JSON.parse(raw) as SchemaBundle } : undefined;
+}

package/fronds/analysis/handlers/MigrateHandler.ts

@@ -0,0 +1,97 @@
+import { loadConfig } from '@fougere/core/node';
+import { resolveStorage } from '@fougere/defaults';
+import { actualState, desiredTables, planStep, collapseChain, applyStep, type Plan, type StepChange } from '@fougere/adapter-sql';
+import type { SetDiff } from '@fougere/schema';
+import ProjectScan from '../services/ProjectScan.js';
+import { chainOf } from '../versions.js';
+import type Migrate from '../entities/Migrate.js';
+
+export interface MigrationPlan {
+  /** Versions whose step was read, oldest first. */
+  chain: string[];
+  changes: StepChange[];
+  refusals: Plan['refusals'];
+  /** The statements actually run — empty unless `apply` was asked for. */
+  ran: string[];
+}
+
+/**
+ * Catching the database up with the frozen chain.
+ *
+ * Every step is replayed in order and what has already happened is SKIPPED, read off the
+ * columns themselves rather than a ledger of applied migrations. That is what makes the
+ * chain safe to replay whole: nothing here has to know which version the database sits
+ * at, and a column renamed by hand is seen rather than contradicted.
+ *
+ * The additive pass is not repeated here — a boot already creates missing tables and
+ * columns. What this adds is the half that touches live data, and only what a human
+ * declared at `fougere freeze`.
+ */
+export default class MigrateHandler {
+  constructor(private projectScan: ProjectScan) {}
+
+  /** Realise the frozen steps this database has not caught up with. */
+  async execute(input: Migrate): Promise<MigrationPlan> {
+    const scan = await this.projectScan.at(input.root ?? undefined);
+    const perFrond = await Promise.all(scan.fronds.map((frond) => stepsOf(frond.source.path)));
+    const steps = perFrond.flat();
+    if (steps.length === 0) return { chain: [], changes: [], refusals: [], ran: [] };
+
+    const config = await loadConfig(scan.root);
+    const storage = resolveStorage(config.db ?? {});
+    if (!storage.db) {
+      return {
+        chain: versionsOf(steps),
+        changes: [],
+        refusals: [{ entity: '*', field: '*', reason: 'no `db` in fougere.config.ts — nothing to migrate' }],
+        ran: [],
+      };
+    }
+
+    const tables = desiredTables(scan as never);
+    // Each frond's chain is composed on its own — its versions are its own line — and the
+    // results are gathered by SOURCE, because an engine is what a statement runs against.
+    const composed = collapseChain(perFrond.map((chain) => collapseChain(chain.map(({ step }) => step))));
+    const sourceOf = storage.sourceOf ?? (() => 'db');
+
+    const changes: StepChange[] = [];
+    const refusals: Plan['refusals'] = [];
+    const ran: string[] = [];
+    for (const source of storage.sources?.() ?? ['db']) {
+      const db = (source === 'db' ? storage.db : storage.dbOf?.(source)) as Parameters<typeof actualState>[0];
+      if (!db) continue;
+
+      const mine = onSource(composed, source, sourceOf);
+      if (Object.keys(mine.entities).length === 0) continue;
+
+      const plan = planStep(mine, tables, { actual: await actualState(db) });
+      changes.push(...plan.changes);
+      refusals.push(...plan.refusals);
+      // Held back: a refusal anywhere stops every engine, for the reason it stops every
+      // statement — half a chain is worse across two engines than within one.
+      if (input.apply && refusals.length === 0) ran.push(...(await applyStep(plan, db)));
+    }
+
+    return { chain: versionsOf(steps), changes, refusals, ran: refusals.length > 0 ? [] : ran };
+  }
+}
+
+/** The versions read, oldest first and each named once however many fronds cut it. */
+function versionsOf(steps: readonly { version: string }[]): string[] {
+  return [...new Set(steps.map(({ version }) => version))].sort((a, b) => a.localeCompare(b, 'en', { numeric: true }));
+}
+
+/** The part of a step whose entities live on one engine. */
+function onSource(step: SetDiff, source: string, sourceOf: (entity: string) => string): SetDiff {
+  return {
+    ...step,
+    entities: Object.fromEntries(Object.entries(step.entities).filter(([entity]) => sourceOf(entity) === source)),
+  };
+}
+
+/** Every recorded step, oldest first — the chain composes, so it is replayed whole. */
+async function stepsOf(frondPath: string): Promise<{ version: string; step: SetDiff }[]> {
+  const chain = await chainOf(frondPath);
+  // The first version has a shape and no step — there was nothing before it to move from.
+  return chain.flatMap(({ name, step }) => (step ? [{ version: name, step }] : []));
+}