@wtfalch/foundry 0.1.0

package/dist/plan/plan-apply.js

@@ -0,0 +1,172 @@
+import { createHash } from 'node:crypto';
+import { computePlanDetail, toPlan } from './diff.js';
+import { readLiveResources } from './live.js';
+export class DeclaredOrgNotFoundError extends Error {
+    constructor(orgId) {
+        super(`no declared org ${orgId}`);
+        this.name = 'DeclaredOrgNotFoundError';
+    }
+}
+/** #10 (resolved): "an apply is refused when its plan no longer matches reality." */
+export class StalePlanError extends Error {
+    constructor(orgId) {
+        super(`the plan for org ${orgId} no longer matches live state; recompute plan() and try again (#9, #10)`);
+        this.name = 'StalePlanError';
+    }
+}
+/** #9 (resolved): "any step that destroys or migrates requires the org's name typed." */
+export class ConfirmationRequiredError extends Error {
+    constructor(orgId) {
+        super(`the plan for org ${orgId} has a step that destroys or migrates data; the org's name must be typed exactly to apply it (#9)`);
+        this.name = 'ConfirmationRequiredError';
+    }
+}
+export class NotAuthorizedError extends Error {
+    constructor(actor, orgId) {
+        super(`${actor.display} does not hold the permission to apply org ${orgId} (#9, #19)`);
+        this.name = 'NotAuthorizedError';
+    }
+}
+/**
+ * The #19 implementation of {@link PlanApply}: computes a plan against live
+ * state, and refuses to apply one that has gone stale, one that touches a
+ * destructive or migrating step without the org's name typed, or one the
+ * actor is not authorized to run.
+ */
+export class FoundryPlanApply {
+    store;
+    readers;
+    executor;
+    audit;
+    authz;
+    actor;
+    now;
+    constructor(options) {
+        this.store = options.store;
+        this.readers = options.readers;
+        this.executor = options.executor;
+        this.audit = options.audit;
+        this.authz = options.authz;
+        this.actor = options.actor;
+        this.now = options.now ?? (() => new Date());
+    }
+    async plan(id) {
+        const { plan } = await this.computeFreshPlan(id);
+        await this.audit.recordPlan({ actor: this.actor, orgId: id, plan, at: this.now() });
+        return plan;
+    }
+    async apply(plan, confirmedOrgName) {
+        const orgId = plan.orgId;
+        const authorized = await this.authz.canApply(this.actor, orgId);
+        if (!authorized) {
+            await this.refuse(plan, 'not authorized');
+            throw new NotAuthorizedError(this.actor, orgId);
+        }
+        const { org, plan: freshPlan, detail } = await this.computeFreshPlan(orgId);
+        if (!plansMatch(plan, freshPlan)) {
+            await this.refuse(plan, 'stale: live state has moved since this plan was computed');
+            throw new StalePlanError(orgId);
+        }
+        const needsConfirmation = plan.steps.some((step) => step.destroys || step.migrates);
+        if (needsConfirmation && confirmedOrgName.trim() !== org.displayName.trim()) {
+            await this.refuse(plan, "destructive or migrating step without the org's name typed correctly");
+            throw new ConfirmationRequiredError(orgId);
+        }
+        return this.runSteps(org, plan, detail);
+    }
+    async refuse(plan, reason) {
+        await this.audit.recordApply({
+            actor: this.actor,
+            orgId: plan.orgId,
+            plan,
+            outcome: 'refused',
+            reason,
+            at: this.now(),
+        });
+    }
+    async runSteps(org, plan, detail) {
+        const orgId = plan.orgId;
+        const previous = await this.store.getAppliedState(orgId);
+        const serviceIds = { ...(previous?.serviceIds ?? {}) };
+        const checkpoints = [];
+        try {
+            for (const planned of detail.plannedSteps) {
+                const result = await this.executor.execute(planned.action);
+                if (result?.resourceId)
+                    serviceIds[planned.action.kind] = result.resourceId;
+                checkpoints.push({ step: planned.step.description, completedAt: this.now().toISOString() });
+            }
+        }
+        catch (e) {
+            // #9 (resolved): "it stops at the checkpoint... there is no automatic
+            // rollback." Whatever completed stays recorded; the failure is
+            // rethrown for a human to fix and resume.
+            await this.store.putAppliedState({
+                orgId,
+                serviceIds,
+                checkpoints,
+                failedFields: previous?.failedFields ?? [],
+                lastApplied: previous?.lastApplied ?? null,
+            });
+            await this.audit.recordApply({
+                actor: this.actor,
+                orgId,
+                plan,
+                outcome: 'failed',
+                reason: e instanceof Error ? e.message : String(e),
+                at: this.now(),
+            });
+            throw e;
+        }
+        const applied = {
+            orgId,
+            serviceIds,
+            checkpoints,
+            // Carried forward, never recomputed. #18 added `failedFields` and left
+            // "whether apply throws, partially applies, or does both" to #19, but
+            // this implementation was written before the field existed and has no
+            // opinion on it: `computePlanDetail` plans only the issuer, mail and
+            // chat, so it cannot yet say which declared fields it failed to make
+            // true. Writing `[]` here would claim it had checked. #20 wires the
+            // full provisioning surface and is what computes this list.
+            failedFields: previous?.failedFields ?? [],
+            lastApplied: { at: this.now().toISOString(), declaredOrgVersion: hashOrg(org) },
+        };
+        await this.store.putAppliedState(applied);
+        await this.audit.recordApply({
+            actor: this.actor,
+            orgId,
+            plan,
+            outcome: 'applied',
+            at: this.now(),
+        });
+        return applied;
+    }
+    async computeFreshPlan(id) {
+        const org = await this.store.get(id);
+        if (!org)
+            throw new DeclaredOrgNotFoundError(id);
+        const live = await readLiveResources(id, this.readers);
+        const detail = computePlanDetail(org, live);
+        return { org, plan: toPlan(detail), detail };
+    }
+}
+/** Order-independent structural equality between two plans. */
+function plansMatch(a, b) {
+    return JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+}
+function canonical(plan) {
+    return {
+        orgId: plan.orgId,
+        steps: [...plan.steps].sort((x, y) => x.description.localeCompare(y.description)),
+        unmanaged: [...plan.unmanaged].sort((x, y) => x.description.localeCompare(y.description)),
+    };
+}
+/**
+ * A structural version of the declared org, recorded on {@link AppliedState}
+ * so a later reader can tell whether it changed since this apply —
+ * `DeclaredOrg` (org.ts) carries no version field of its own.
+ */
+function hashOrg(org) {
+    return createHash('sha256').update(JSON.stringify(org)).digest('hex');
+}

package/dist/plan/providers-readers.d.ts

@@ -0,0 +1,86 @@
+import type { CloudflareClient } from '@wtfalch/providers/cloudflare';
+import type { CoolifyClient } from '@wtfalch/providers/coolify';
+import type { ZitadelClient } from '@wtfalch/providers/zitadel';
+import type { OrgId } from '../org.js';
+import type { DeclaredOrgStore } from '../store.js';
+import type { CloudflareReader, CoolifyReader, LiveResource, ZitadelReader } from './live.js';
+/**
+ * Real `CoolifyReader`, `CloudflareReader` and `ZitadelReader` implementations
+ * (`live.ts:31-45`), backed by `@wtfalch/providers`' HTTP clients instead of
+ * the fakes `plan-apply.test.ts` and `diff.test.ts` use (`../test/fakes.ts`'s
+ * `FakeReader`).
+ *
+ * This is the smallest real use #20 ("provision Company Factory end to end")
+ * names, per `providers`' own integration scout
+ * (`providers/.claude/scout/2026-09-23-integration.md`, "foundry" row): "New
+ * adapter code implementing `CoolifyReader`/`CloudflareReader`/`ZitadelReader`
+ * ... over `@wtfalch/providers/{coolify,cloudflare,zitadel}`." That scout also
+ * names a `StepExecutor` half; this file deliberately covers reads only — see
+ * the Finding on #20 in this repo's phase-B report for why the write half
+ * (creating/mutating live Coolify/Cloudflare/Zitadel resources) is left for
+ * #20 itself rather than folded into this adoption PR.
+ *
+ * `packages/foundry/package.json` had zero `@wtfalch/*` dependencies before
+ * this file; `@wtfalch/providers` is its first.
+ */
+/**
+ * Resolves an estate {@link OrgId} to one provider's own scope id — a
+ * Coolify project uuid, a Cloudflare zone id, ZITADEL's own org id — or
+ * `null` before that provider has anything provisioned for this org yet.
+ *
+ * Every `@wtfalch/providers` client's `listResources` takes that provider's
+ * own scope, never foundry's `OrgId` directly (`providers/packages/providers/
+ * src/resource.ts`'s doc comment, ADR 0002: providers imports nothing from
+ * the estate, so it cannot resolve foundry's id itself — "resolving an
+ * estate org to that scope is foundry's job"). This type makes that lookup
+ * explicit and injectable per reader, rather than hard-coding one id map's
+ * key name into each reader class.
+ */
+export type ScopeResolver = (orgId: OrgId) => Promise<string | null>;
+/**
+ * A {@link ScopeResolver} backed by `AppliedState.serviceIds`
+ * (`../state.ts`: "one id per service ... keyed by that service's own name
+ * for the org") — the one place foundry records a provider's own id for an
+ * org today, through the same `DeclaredOrgStore` seam #18 built.
+ *
+ * Nothing writes a `serviceIds[serviceKey]` entry yet — that is the
+ * `StepExecutor` half of #20, not built here — so every resolver built this
+ * way returns `null` for every org until it does. That is the correct
+ * "nothing live yet" answer: a reader passed `null` returns `[]`, which
+ * `computePlanDetail` (`diff.ts`) already reads as "no live resource",
+ * exactly right for an org with no Coolify project (etc.) yet.
+ */
+export declare function storeScopeResolver(store: DeclaredOrgStore, serviceKey: string): ScopeResolver;
+/**
+ * Backed by `@wtfalch/providers/coolify`'s `CoolifyClient.listResources`: a
+ * Coolify project's environments and in-scope applications (v1 scope — see
+ * that method's own doc comment for what it leaves out).
+ */
+export declare class ProvidersCoolifyReader implements CoolifyReader {
+    private readonly client;
+    private readonly resolveScope;
+    constructor(client: CoolifyClient, resolveScope: ScopeResolver);
+    listResources(orgId: OrgId): Promise<LiveResource[]>;
+}
+/**
+ * Backed by `@wtfalch/providers/cloudflare`'s `CloudflareClient.listResources`:
+ * a zone's DNS records plus its email-routing status (v1 scope — see that
+ * method's own doc comment for what it leaves out).
+ */
+export declare class ProvidersCloudflareReader implements CloudflareReader {
+    private readonly client;
+    private readonly resolveScope;
+    constructor(client: CloudflareClient, resolveScope: ScopeResolver);
+    listResources(orgId: OrgId): Promise<LiveResource[]>;
+}
+/**
+ * Backed by `@wtfalch/providers/zitadel`'s `ZitadelClient.listResources`: one
+ * resource per project and per project grant in a ZITADEL org (v1 scope —
+ * see that method's own doc comment).
+ */
+export declare class ProvidersZitadelReader implements ZitadelReader {
+    private readonly client;
+    private readonly resolveScope;
+    constructor(client: ZitadelClient, resolveScope: ScopeResolver);
+    listResources(orgId: OrgId): Promise<LiveResource[]>;
+}

package/dist/plan/providers-readers.js

@@ -0,0 +1,83 @@
+/**
+ * A {@link ScopeResolver} backed by `AppliedState.serviceIds`
+ * (`../state.ts`: "one id per service ... keyed by that service's own name
+ * for the org") — the one place foundry records a provider's own id for an
+ * org today, through the same `DeclaredOrgStore` seam #18 built.
+ *
+ * Nothing writes a `serviceIds[serviceKey]` entry yet — that is the
+ * `StepExecutor` half of #20, not built here — so every resolver built this
+ * way returns `null` for every org until it does. That is the correct
+ * "nothing live yet" answer: a reader passed `null` returns `[]`, which
+ * `computePlanDetail` (`diff.ts`) already reads as "no live resource",
+ * exactly right for an org with no Coolify project (etc.) yet.
+ */
+export function storeScopeResolver(store, serviceKey) {
+    return async (orgId) => {
+        const applied = await store.getAppliedState(orgId);
+        // `|| null`, not `??`: an empty string is not a usable scope id either,
+        // and no provider mints one, so there is nothing to lose by treating it
+        // the same as "not set yet".
+        return applied?.serviceIds[serviceKey] || null;
+    };
+}
+/** `@wtfalch/providers`' own `LiveResource` (`resource.ts`) has no `system` field — foundry's adds it at this boundary. */
+function toFoundryResources(system, resources) {
+    return resources.map((r) => ({ system, kind: r.kind, key: r.key, config: r.config }));
+}
+/**
+ * Backed by `@wtfalch/providers/coolify`'s `CoolifyClient.listResources`: a
+ * Coolify project's environments and in-scope applications (v1 scope — see
+ * that method's own doc comment for what it leaves out).
+ */
+export class ProvidersCoolifyReader {
+    client;
+    resolveScope;
+    constructor(client, resolveScope) {
+        this.client = client;
+        this.resolveScope = resolveScope;
+    }
+    async listResources(orgId) {
+        const projectUuid = await this.resolveScope(orgId);
+        if (!projectUuid)
+            return [];
+        return toFoundryResources('coolify', await this.client.listResources(projectUuid));
+    }
+}
+/**
+ * Backed by `@wtfalch/providers/cloudflare`'s `CloudflareClient.listResources`:
+ * a zone's DNS records plus its email-routing status (v1 scope — see that
+ * method's own doc comment for what it leaves out).
+ */
+export class ProvidersCloudflareReader {
+    client;
+    resolveScope;
+    constructor(client, resolveScope) {
+        this.client = client;
+        this.resolveScope = resolveScope;
+    }
+    async listResources(orgId) {
+        const zoneId = await this.resolveScope(orgId);
+        if (!zoneId)
+            return [];
+        return toFoundryResources('cloudflare', await this.client.listResources(zoneId));
+    }
+}
+/**
+ * Backed by `@wtfalch/providers/zitadel`'s `ZitadelClient.listResources`: one
+ * resource per project and per project grant in a ZITADEL org (v1 scope —
+ * see that method's own doc comment).
+ */
+export class ProvidersZitadelReader {
+    client;
+    resolveScope;
+    constructor(client, resolveScope) {
+        this.client = client;
+        this.resolveScope = resolveScope;
+    }
+    async listResources(orgId) {
+        const zitadelOrgId = await this.resolveScope(orgId);
+        if (!zitadelOrgId)
+            return [];
+        return toFoundryResources('zitadel', await this.client.listResources(zitadelOrgId));
+    }
+}

package/dist/plan.d.ts

@@ -0,0 +1,50 @@
+import type { OrgId } from './org.js';
+/**
+ * One step of a {@link Plan}.
+ *
+ * Decided in #9 (resolved): "any step that destroys or migrates requires
+ * the org's name typed" before `apply` runs it. `destroys` and `migrates`
+ * are independent — a migration can move live data without deleting
+ * anything, but both are gated the same way at apply time.
+ */
+export interface PlanStep {
+    description: string;
+    /**
+     * True when this step deletes or replaces data the org cannot get back
+     * without foundry's own backup: a chat re-key, an issuer move, a mail
+     * domain removal (parked, not deleted, per #7 corrections 1, but still
+     * disruptive enough to gate). Requires the org's name typed (#9).
+     */
+    destroys: boolean;
+    /**
+     * True when this step moves live data between systems rather than only
+     * creating or updating config — a chat re-key copying rooms and messages,
+     * a mail level transition (#7 "Transitions"). Every transition is legal
+     * in both directions; which ones foundry builds first is scope for #13,
+     * not a property of this type.
+     */
+    migrates: boolean;
+}
+/**
+ * A live-scope item the declared org does not name.
+ *
+ * Decided in #10 (resolved): "foundry manages only what the declared org
+ * names; anything else in scope is reported as unmanaged and never
+ * deleted." A {@link Plan} lists these for visibility; it never turns one
+ * into a {@link PlanStep}.
+ */
+export interface UnmanagedItem {
+    description: string;
+}
+/**
+ * The diff between a {@link DeclaredOrg} and live reality, computed by the
+ * `plan` half of {@link PlanApply} and shown before any apply runs.
+ *
+ * Decided in #9 (resolved): "foundry computes the diff between the declared
+ * org and reality, shows it, and an apply runs exactly that plan."
+ */
+export interface Plan {
+    orgId: OrgId;
+    steps: PlanStep[];
+    unmanaged: UnmanagedItem[];
+}

package/dist/plan.js

@@ -0,0 +1 @@
+export {};

package/dist/runner/db.d.ts

@@ -0,0 +1,8 @@
+import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+/**
+ * The host's own drizzle handle, or a transaction open on it: postgres-js
+ * in a host, PGlite in this package's own tests. The runner's queries use
+ * nothing driver-specific, the same shape `@wtfalch/keys`' `HeldKeysDb`
+ * uses.
+ */
+export type RunnerDb = PgDatabase<PgQueryResultHKT, any, any>;

package/dist/runner/db.js

@@ -0,0 +1 @@
+export {};

package/dist/runner/errors.d.ts

@@ -0,0 +1,37 @@
+import type { RunRecord } from './types.js';
+/**
+ * Thrown by {@link JobRunner.enqueueApply} when the named org already has a
+ * run that has not succeeded -- the database's lock (#9, resolved: a row,
+ * never a lockfile) refusing a second apply and saying why.
+ */
+export declare class AlreadyRunningError extends Error {
+    readonly orgId: string;
+    readonly existingRun: RunRecord;
+    constructor(orgId: string, existingRun: RunRecord);
+}
+/** Thrown by {@link JobRunner.runSteps} when the named run does not exist. */
+export declare class RunNotFoundError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+/**
+ * Thrown by {@link JobRunner.runSteps} when the caller's step list does not
+ * match the run's own `stepIds` -- guards a resume against being handed a
+ * different plan than the one that was locked in at enqueue time.
+ */
+export declare class StepMismatchError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+/**
+ * Thrown by {@link JobRunner.runSteps} when a step's own `run()` threw. The
+ * run's row already records the failure (#17: "records which step
+ * failed") before this is thrown -- this is only the caller-facing signal
+ * that the run stopped.
+ */
+export declare class StepFailedError extends Error {
+    readonly runId: string;
+    readonly step: string;
+    constructor(runId: string, step: string, cause: unknown);
+}
+export declare function errorMessage(error: unknown): string;

package/dist/runner/errors.js

@@ -0,0 +1,57 @@
+/**
+ * Thrown by {@link JobRunner.enqueueApply} when the named org already has a
+ * run that has not succeeded -- the database's lock (#9, resolved: a row,
+ * never a lockfile) refusing a second apply and saying why.
+ */
+export class AlreadyRunningError extends Error {
+    orgId;
+    existingRun;
+    constructor(orgId, existingRun) {
+        super(`org ${orgId} already has an apply run in progress (run ${existingRun.id}, ` +
+            `${existingRun.status}); refusing a second apply until it succeeds`);
+        this.name = 'AlreadyRunningError';
+        this.orgId = orgId;
+        this.existingRun = existingRun;
+    }
+}
+/** Thrown by {@link JobRunner.runSteps} when the named run does not exist. */
+export class RunNotFoundError extends Error {
+    runId;
+    constructor(runId) {
+        super(`no such run: ${runId}`);
+        this.name = 'RunNotFoundError';
+        this.runId = runId;
+    }
+}
+/**
+ * Thrown by {@link JobRunner.runSteps} when the caller's step list does not
+ * match the run's own `stepIds` -- guards a resume against being handed a
+ * different plan than the one that was locked in at enqueue time.
+ */
+export class StepMismatchError extends Error {
+    runId;
+    constructor(runId) {
+        super(`run ${runId}: supplied steps do not match the run's planned steps`);
+        this.name = 'StepMismatchError';
+        this.runId = runId;
+    }
+}
+/**
+ * Thrown by {@link JobRunner.runSteps} when a step's own `run()` threw. The
+ * run's row already records the failure (#17: "records which step
+ * failed") before this is thrown -- this is only the caller-facing signal
+ * that the run stopped.
+ */
+export class StepFailedError extends Error {
+    runId;
+    step;
+    constructor(runId, step, cause) {
+        super(`run ${runId}: step ${step} failed: ${errorMessage(cause)}`, { cause });
+        this.name = 'StepFailedError';
+        this.runId = runId;
+        this.step = step;
+    }
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/runner/index.d.ts

@@ -0,0 +1,4 @@
+export type { RunnerDb } from './db.js';
+export { AlreadyRunningError, RunNotFoundError, StepFailedError, StepMismatchError, } from './errors.js';
+export { createJobRunner } from './runner.js';
+export type { CreateJobRunnerOptions, JobRunner, RunFailure, RunRecord, RunStatus, RunStepsOptions, RunnerStep, } from './types.js';

package/dist/runner/index.js

@@ -0,0 +1,2 @@
+export { AlreadyRunningError, RunNotFoundError, StepFailedError, StepMismatchError, } from './errors.js';
+export { createJobRunner } from './runner.js';

package/dist/runner/runner.d.ts

@@ -0,0 +1,6 @@
+import type { CreateJobRunnerOptions, JobRunner } from './types.js';
+/**
+ * Creates the job runner (#17). `db` is the host's own drizzle handle,
+ * already migrated with `migrations/0001_foundry_runs.sql`.
+ */
+export declare function createJobRunner(options: CreateJobRunnerOptions): JobRunner;

package/dist/runner/runner.js

@@ -0,0 +1,137 @@
+import { randomUUID } from 'node:crypto';
+import { and, eq, ne } from 'drizzle-orm';
+import { AlreadyRunningError, RunNotFoundError, StepFailedError, StepMismatchError, errorMessage, } from './errors.js';
+import { foundryRuns } from './schema.js';
+const UNIQUE_VIOLATION = '23505';
+/**
+ * True for a Postgres unique-violation, however the driver hands it back --
+ * directly (PGlite in this package's own tests) or wrapped in drizzle-orm's
+ * own `DrizzleQueryError`, whose `cause` carries the raw driver error
+ * (postgres-js in a host). Checked by Postgres error code, never by message
+ * text, since message text is not a contract.
+ */
+function isUniqueViolation(error) {
+    const code = error?.code;
+    if (code === UNIQUE_VIOLATION)
+        return true;
+    const cause = error?.cause;
+    return cause?.code === UNIQUE_VIOLATION;
+}
+function toRunRecord(row) {
+    return {
+        id: row.id,
+        orgId: row.orgId,
+        status: row.status,
+        stepIds: row.stepIds,
+        checkpoints: row.checkpoints,
+        failure: row.failure ?? null,
+        createdAt: row.createdAt.toISOString(),
+        updatedAt: row.updatedAt.toISOString(),
+    };
+}
+/** Same order, same ids -- the guard {@link JobRunner.runSteps} applies before running anything. */
+function stepsMatch(stepIds, steps) {
+    return stepIds.length === steps.length && stepIds.every((id, index) => steps[index]?.id === id);
+}
+/**
+ * Creates the job runner (#17). `db` is the host's own drizzle handle,
+ * already migrated with `migrations/0001_foundry_runs.sql`.
+ */
+export function createJobRunner(options) {
+    const { db } = options;
+    const now = options.now ?? (() => new Date());
+    async function getRun(runId) {
+        const [row] = await db.select().from(foundryRuns).where(eq(foundryRuns.id, runId));
+        return row ? toRunRecord(row) : null;
+    }
+    async function currentRun(orgId) {
+        const [row] = await db
+            .select()
+            .from(foundryRuns)
+            .where(and(eq(foundryRuns.orgId, orgId), ne(foundryRuns.status, 'succeeded')));
+        return row ? toRunRecord(row) : null;
+    }
+    async function enqueueApply(orgId, steps) {
+        const stepIds = steps.map((step) => step.id);
+        if (new Set(stepIds).size !== stepIds.length)
+            throw new Error('runner steps must have unique ids');
+        const id = randomUUID();
+        try {
+            await db
+                .insert(foundryRuns)
+                .values({ id, orgId, status: 'running', stepIds, checkpoints: [], failure: null });
+        }
+        catch (error) {
+            if (isUniqueViolation(error)) {
+                const existing = await currentRun(orgId);
+                if (existing)
+                    throw new AlreadyRunningError(orgId, existing);
+            }
+            throw error;
+        }
+        return { runId: id };
+    }
+    async function runSteps(runId, steps, stepOptions = {}) {
+        const run = await getRun(runId);
+        if (!run)
+            throw new RunNotFoundError(runId);
+        if (run.status === 'succeeded')
+            return run;
+        if (!stepsMatch(run.stepIds, steps))
+            throw new StepMismatchError(runId);
+        if (run.status === 'failed')
+            // Resuming a failed run (#9: "a human fixes the cause and resumes
+            // from that checkpoint") clears the stale failure record -- it
+            // described the last attempt, not this one.
+            await db
+                .update(foundryRuns)
+                .set({ status: 'running', failure: null, updatedAt: now() })
+                .where(eq(foundryRuns.id, runId));
+        const stepById = new Map(steps.map((step) => [step.id, step]));
+        const checkpoints = [...run.checkpoints];
+        const done = new Set(checkpoints.map((c) => c.step));
+        for (const stepId of run.stepIds) {
+            if (done.has(stepId))
+                continue;
+            if (stepOptions.signal?.aborted)
+                break;
+            // stepsMatch already proved every run.stepIds entry has a matching step.
+            const step = stepById.get(stepId);
+            try {
+                await step.run();
+            }
+            catch (error) {
+                const failure = { step: stepId, message: errorMessage(error), at: now().toISOString() };
+                await db
+                    .update(foundryRuns)
+                    .set({ status: 'failed', failure, updatedAt: now() })
+                    .where(eq(foundryRuns.id, runId));
+                throw new StepFailedError(runId, stepId, error);
+            }
+            checkpoints.push({ step: stepId, completedAt: now().toISOString() });
+            await db
+                .update(foundryRuns)
+                .set({ checkpoints: [...checkpoints], updatedAt: now() })
+                .where(eq(foundryRuns.id, runId));
+        }
+        if (checkpoints.length < run.stepIds.length) {
+            // Stopped early (the signal fired before every step ran) -- leave the
+            // row exactly as its last checkpoint left it; this is the state a
+            // real kill would also leave, and the next call resumes it the same
+            // way regardless of which one happened.
+            const current = await getRun(runId);
+            if (!current)
+                throw new RunNotFoundError(runId);
+            return current;
+        }
+        await db
+            .update(foundryRuns)
+            .set({ status: 'succeeded', updatedAt: now() })
+            .where(eq(foundryRuns.id, runId));
+        const finished = await getRun(runId);
+        if (!finished)
+            throw new RunNotFoundError(runId);
+        return finished;
+    }
+    return { enqueueApply, runSteps, getRun, currentRun };
+}