@wtfalch/foundry 0.1.0 → 0.3.0

package/dist/plan/index.d.ts

@@ -2,7 +2,9 @@ export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, File
 export { readLiveResources } from './live.js';
 export type { StepAction, PlannedStep, PlanDetail } from './diff.js';
 export { computePlanDetail, toPlan } from './diff.js';
-export type { AuditActor, AuditLog, AuthzGate, StepExecutor, FoundryPlanApplyOptions, } from './plan-apply.js';
-export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, } from './plan-apply.js';
-export type { ScopeResolver } from './providers-readers.js';
-export { ProvidersCloudflareReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, } from './providers-readers.js';
+export type { AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, FoundryPlanApplyOptions, } from './plan-apply.js';
+export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, } from './plan-apply.js';
+export type { ScopeResolver, RecordedIds } from './providers-readers.js';
+export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
+export type { CoolifyPort, CloudflarePort, ZitadelPort, FilesOrgLimits, AiOrgLimits, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, } from './executor.js';
+export { FoundryStepExecutor, NotBuiltError, healthUrls } from './executor.js';

package/dist/plan/index.js

@@ -1,4 +1,5 @@
 export { readLiveResources } from './live.js';
 export { computePlanDetail, toPlan } from './diff.js';
-export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, } from './plan-apply.js';
-export { ProvidersCloudflareReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, } from './providers-readers.js';
+export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, } from './plan-apply.js';
+export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
+export { FoundryStepExecutor, NotBuiltError, healthUrls } from './executor.js';

package/dist/plan/live.d.ts

@@ -3,10 +3,14 @@ import type { OrgId } from '../org.js';
  * One resource as seen live in one of foundry's six systems.
  *
  * `key` is unique within `(system, kind)`. Per-org singleton resources
- * (issuer, mail, chat, storage's spend limit, AI's budget, the cms site —
- * see `diff.ts`) are keyed by the {@link OrgId} itself; anything else foundry can see in
- * that system's account/org is keyed however that system names it, so it can
- * still be matched, or left
+ * (issuer, mail, chat, storage's spend limit, AI's budget, the cms site, the
+ * org's own app, its database, its Cloudflare tunnel — see `diff.ts`) are
+ * keyed by the {@link OrgId} itself. Two resources key by something else
+ * instead (#71): the Cloudflare zone is keyed by the domain name, since a
+ * zone belongs to a domain rather than an org, and each declared ZITADEL
+ * issuer app is keyed by its own declared name, since an org can declare
+ * more than one. Anything else foundry can see in that system's account/org
+ * is keyed however that system names it, so it can still be matched, or left
  * {@link https://github.com/wtfalch/foundry/issues/10 unmanaged}, by
  * `computePlanDetail`.
  */

package/dist/plan/plan-apply.d.ts

@@ -1,10 +1,10 @@
 import type { PlanApply } from '../apply.js';
-import type { OrgId } from '../org.js';
+import type { DeclaredOrg, OrgId } from '../org.js';
 import type { Plan } from '../plan.js';
 import type { AppliedState } from '../state.js';
 import type { DeclaredOrgStore } from '../store.js';
 import { type StepAction } from './diff.js';
-import { type LiveReaders } from './live.js';
+import { type LiveReaders, type LiveResource } from './live.js';
 /** Who did it, for `@wtfalch/audit`'s "who, when, the plan, the result" (#9, #19). */
 export interface AuditActor {
     readonly id: string;
@@ -37,6 +37,14 @@ export interface AuditLog {
         reason?: string;
         at: Date;
     }): Promise<void>;
+    /** `FoundryPlanApply.destroy`'s own record -- no `Plan` involved, so this is its own entry shape rather than a reuse of `recordApply`'s. */
+    recordDestroy(entry: {
+        actor: AuditActor;
+        orgId: OrgId;
+        outcome: 'destroyed' | 'refused' | 'failed';
+        reason?: string;
+        at: Date;
+    }): Promise<void>;
 }
 /**
  * The seam onto `@wtfalch/authz`, gating `apply` only — `plan` is a read
@@ -47,18 +55,101 @@ export interface AuditLog {
  */
 export interface AuthzGate {
     canApply(actor: AuditActor, orgId: OrgId): Promise<boolean>;
+    /**
+     * Gates `destroy` -- deleting every resource foundry made for an org, then
+     * the org itself, is a stronger action than applying config, so it is its
+     * own permission rather than reusing `canApply`.
+     */
+    canDestroy(actor: AuditActor, orgId: OrgId): Promise<boolean>;
+}
+/**
+ * What {@link StepExecutor.execute} needs beyond the {@link StepAction}
+ * itself to act: the declared org (a real executor names its own live
+ * resources after `org.slug`/`org.bespokeAppRepo`/etc., not just the bare
+ * ids a `StepAction` carries) and read/write access to this org's *scope*
+ * ids — a Coolify project uuid, the org's own ZITADEL org/project id, a
+ * Cloudflare zone id — the ids one step's executor resolves or creates that a
+ * later step (or a later apply) needs again (executor decisions,
+ * `.claude/decisions-2026-09-24-executor.md`: "Scope ids: a Coolify project
+ * per org (`serviceIds['coolify_project']`) ... Created resources are
+ * recorded under `system:kind:key`").
+ *
+ * Decision (executor.ts, #20): rather than backing `recordScopeId` with its
+ * own direct `DeclaredOrgStore.putAppliedState` call, `recordedIds`/
+ * `recordScopeId` below are backed by the very `serviceIds` map `runSteps`
+ * already accumulates and persists once, atomically, at the end of a run. A
+ * direct store write from inside `execute` would race that final write:
+ * `runSteps` captures `previous?.serviceIds` once before the loop starts, so
+ * its own end-of-loop `store.putAppliedState` would silently clobber
+ * anything an executor wrote to the store mid-loop. Routing scope ids
+ * through the same in-memory map both writes to removes the race entirely,
+ * and also means `recordedIds` sees a resource id `runSteps` itself recorded
+ * for an *earlier* step in this same run (e.g. the ZITADEL org provisioned
+ * by an `issuer` step, needed by a later `app` step) without any extra
+ * plumbing.
+ */
+export interface StepExecutionContext {
+    readonly org: DeclaredOrg;
+    /**
+     * Every id foundry has recorded for this org so far — both `system:kind:key`
+     * resource ids (`runSteps` records these itself from `execute`'s own return
+     * value) and flat provider *scope* ids a step recorded via
+     * {@link recordScopeId}. A snapshot at the moment it's called, but since
+     * `runSteps` runs one step at a time and mutates the same underlying map
+     * this reads from, it always reflects everything recorded so far in this
+     * run, plus whatever a previous apply already persisted.
+     */
+    recordedIds(): Readonly<Record<string, string>>;
+    /**
+     * Records a provider *scope* id — `coolify_project`, `zitadel_org`,
+     * `zitadel_project`, `cloudflare_zone` — alongside whatever `system:kind:key`
+     * resource id `execute`'s own return value records. `key` must carry no
+     * `:`, the same rule `state.ts`'s `AppliedState.serviceIds` documents, so a
+     * scope key can never collide with the `system:kind:key` form.
+     */
+    recordScopeId(key: string, id: string): void;
 }
 /**
  * Makes one {@link StepAction} true against a real system. No implementation
  * ships in this package — #19's job is the seam and the refusal rules,
  * proven against fakes; a real executor (calling Coolify/Zitadel/Cloudflare)
- * is #20's "provision Company Factory end to end".
+ * is #20's "provision Company Factory end to end" (`executor.ts`'s
+ * `FoundryStepExecutor`).
  */
 export interface StepExecutor {
-    execute(action: StepAction): Promise<{
+    execute(action: StepAction, context: StepExecutionContext): Promise<{
         resourceId?: string;
     } | undefined>;
 }
+/**
+ * One resource `FoundryPlanApply.destroy` has decided to tear down: an entry
+ * from `AppliedState.serviceIds` (`resourceKey`'s `system:kind:key` form, or
+ * one of the two ZITADEL scope keys, `zitadel_project`/`zitadel_org`),
+ * resolved back to the provider id it was recorded under.
+ */
+export interface DestroyTarget {
+    system: LiveResource['system'];
+    kind: string;
+    /** The foundry key this was recorded under: an org id, a declared issuer app's name, or the scope key itself for `kind: 'project' | 'org'`. */
+    key: string;
+    /** The provider's own id -- exactly what `AppliedState.serviceIds` holds under this resource's key. */
+    id: string;
+}
+/**
+ * Deletes one resource {@link DestroyTarget} names. The teardown half of
+ * {@link StepExecutor}: where `execute` makes a `StepAction` true, `destroy`
+ * undoes exactly the one resource it is given, one at a time, in the order
+ * `FoundryPlanApply.destroy` calls it. A provider 404 (already gone) counts
+ * as deleted, never an error -- a destroy interrupted after a resource was
+ * deleted but before its `serviceIds` entry was removed must not fail the
+ * same way twice on retry.
+ */
+export interface StepDestroyer {
+    destroy(target: DestroyTarget, context: {
+        readonly org: DeclaredOrg;
+        readonly recordedIds: Readonly<Record<string, string>>;
+    }): Promise<void>;
+}
 export declare class DeclaredOrgNotFoundError extends Error {
     constructor(orgId: OrgId);
 }
@@ -73,10 +164,15 @@ export declare class ConfirmationRequiredError extends Error {
 export declare class NotAuthorizedError extends Error {
     constructor(actor: AuditActor, orgId: OrgId);
 }
+/** The goal line's own gate: only a test org can be destroyed. */
+export declare class NotATestOrgError extends Error {
+    constructor(orgId: OrgId);
+}
 export interface FoundryPlanApplyOptions {
     store: DeclaredOrgStore;
     readers: LiveReaders;
     executor: StepExecutor;
+    destroyer: StepDestroyer;
     audit: AuditLog;
     authz: AuthzGate;
     /** The operator running this plan/apply — every audit row's "who" (#9, #19). */
@@ -94,6 +190,7 @@ export declare class FoundryPlanApply implements PlanApply {
     private readonly store;
     private readonly readers;
     private readonly executor;
+    private readonly destroyer;
     private readonly audit;
     private readonly authz;
     private readonly actor;
@@ -101,7 +198,20 @@ export declare class FoundryPlanApply implements PlanApply {
     constructor(options: FoundryPlanApplyOptions);
     plan(id: OrgId): Promise<Plan>;
     apply(plan: Plan, confirmedOrgName: string): Promise<AppliedState>;
+    /**
+     * Deletes every resource foundry recorded for `id`, in reverse creation
+     * order, then the declared org and its applied state themselves (goal
+     * line). Refused unless the stored `DeclaredOrg` has `test: true` and
+     * unless `confirmedOrgName` matches the org's `displayName` -- the same
+     * confirmation `apply` requires for a destructive step (#9), required here
+     * unconditionally since destroying an org is the most destructive step
+     * there is. A failure partway through stops and rethrows, leaving the
+     * declared org in place with whatever remains recorded in its applied
+     * state, so a retried `destroy` only tears down what's left.
+     */
+    destroy(id: OrgId, confirmedOrgName: string): Promise<void>;
     private refuse;
+    private refuseDestroy;
     private runSteps;
     private computeFreshPlan;
 }

package/dist/plan/plan-apply.js

@@ -27,6 +27,13 @@ export class NotAuthorizedError extends Error {
         this.name = 'NotAuthorizedError';
     }
 }
+/** The goal line's own gate: only a test org can be destroyed. */
+export class NotATestOrgError extends Error {
+    constructor(orgId) {
+        super(`org ${orgId} is not marked test; only a test org can be destroyed`);
+        this.name = 'NotATestOrgError';
+    }
+}
 /**
  * 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
@@ -37,6 +44,7 @@ export class FoundryPlanApply {
     store;
     readers;
     executor;
+    destroyer;
     audit;
     authz;
     actor;
@@ -45,6 +53,7 @@ export class FoundryPlanApply {
         this.store = options.store;
         this.readers = options.readers;
         this.executor = options.executor;
+        this.destroyer = options.destroyer;
         this.audit = options.audit;
         this.authz = options.authz;
         this.actor = options.actor;
@@ -74,6 +83,71 @@ export class FoundryPlanApply {
         }
         return this.runSteps(org, plan, detail);
     }
+    /**
+     * Deletes every resource foundry recorded for `id`, in reverse creation
+     * order, then the declared org and its applied state themselves (goal
+     * line). Refused unless the stored `DeclaredOrg` has `test: true` and
+     * unless `confirmedOrgName` matches the org's `displayName` -- the same
+     * confirmation `apply` requires for a destructive step (#9), required here
+     * unconditionally since destroying an org is the most destructive step
+     * there is. A failure partway through stops and rethrows, leaving the
+     * declared org in place with whatever remains recorded in its applied
+     * state, so a retried `destroy` only tears down what's left.
+     */
+    async destroy(id, confirmedOrgName) {
+        const authorized = await this.authz.canDestroy(this.actor, id);
+        if (!authorized) {
+            await this.refuseDestroy(id, 'not authorized');
+            throw new NotAuthorizedError(this.actor, id);
+        }
+        const org = await this.store.get(id);
+        if (!org)
+            throw new DeclaredOrgNotFoundError(id);
+        if (!org.test) {
+            await this.refuseDestroy(id, 'org is not marked test; only a test org can be destroyed');
+            throw new NotATestOrgError(id);
+        }
+        if (confirmedOrgName.trim() !== org.displayName.trim()) {
+            await this.refuseDestroy(id, "org's name not typed correctly");
+            throw new ConfirmationRequiredError(id);
+        }
+        const state = await this.store.getAppliedState(id);
+        const serviceIds = { ...(state?.serviceIds ?? {}) };
+        const targets = destroyTargets(serviceIds);
+        try {
+            for (const target of targets) {
+                // A provider 404 counts as deleted -- `StepDestroyer.destroy`'s own
+                // doc comment -- so nothing here needs to special-case "already
+                // gone" itself.
+                await this.destroyer.destroy(target, { org, recordedIds: { ...serviceIds } });
+                delete serviceIds[destroyServiceIdKey(target)];
+                await this.store.putAppliedState({
+                    orgId: id,
+                    serviceIds,
+                    checkpoints: state?.checkpoints ?? [],
+                    failedFields: state?.failedFields ?? [],
+                    lastApplied: state?.lastApplied ?? null,
+                });
+            }
+            await this.store.delete(id);
+        }
+        catch (e) {
+            await this.audit.recordDestroy({
+                actor: this.actor,
+                orgId: id,
+                outcome: 'failed',
+                reason: e instanceof Error ? e.message : String(e),
+                at: this.now(),
+            });
+            throw e;
+        }
+        await this.audit.recordDestroy({
+            actor: this.actor,
+            orgId: id,
+            outcome: 'destroyed',
+            at: this.now(),
+        });
+    }
     async refuse(plan, reason) {
         await this.audit.recordApply({
             actor: this.actor,
@@ -84,16 +158,41 @@ export class FoundryPlanApply {
             at: this.now(),
         });
     }
+    async refuseDestroy(orgId, reason) {
+        await this.audit.recordDestroy({
+            actor: this.actor,
+            orgId,
+            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 = [];
+        // Backed by the very `serviceIds` map this method persists once, at the
+        // end — see `StepExecutionContext`'s doc comment for why.
+        const context = {
+            org,
+            recordedIds: () => ({ ...serviceIds }),
+            recordScopeId: (key, id) => {
+                serviceIds[key] = id;
+            },
+        };
         try {
             for (const planned of detail.plannedSteps) {
-                const result = await this.executor.execute(planned.action);
-                if (result?.resourceId)
-                    serviceIds[planned.action.kind] = result.resourceId;
+                const result = await this.executor.execute(planned.action, context);
+                // `system:kind:key`, not just `kind`: two steps can share a `kind`
+                // (an org's several declared ZITADEL apps, #71) and would otherwise
+                // overwrite each other's id. `providers-readers.ts`'s
+                // `storeRecordedIds` reads this same key back to match a plan's live
+                // resources to what foundry itself created here.
+                if (result?.resourceId) {
+                    const { system, kind, key } = planned.action;
+                    serviceIds[`${system}:${kind}:${key}`] = result.resourceId;
+                }
                 checkpoints.push({ step: planned.step.description, completedAt: this.now().toISOString() });
             }
         }
@@ -105,7 +204,7 @@ export class FoundryPlanApply {
                 orgId,
                 serviceIds,
                 checkpoints,
-                failedFields: previous?.failedFields ?? [],
+                failedFields: failedFields(org, detail, checkpoints.length),
                 lastApplied: previous?.lastApplied ?? null,
             });
             await this.audit.recordApply({
@@ -122,14 +221,7 @@ export class FoundryPlanApply {
             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 ?? [],
+            failedFields: failedFields(org, detail, detail.plannedSteps.length),
             lastApplied: { at: this.now().toISOString(), declaredOrgVersion: hashOrg(org) },
         };
         await this.store.putAppliedState(applied);
@@ -146,11 +238,171 @@ export class FoundryPlanApply {
         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);
+        const [live, applied] = await Promise.all([
+            readLiveResources(id, this.readers),
+            this.store.getAppliedState(id),
+        ]);
+        const detail = computePlanDetail(org, live, applied?.serviceIds ?? {});
         return { org, plan: toPlan(detail), detail };
     }
 }
+/** `AppliedState.serviceIds`' two flat ZITADEL scope keys (`executor.ts`'s `ensureZitadelProject`/`zitadelIssuer`) -- no `:`, unlike a resource key. */
+const ZITADEL_PROJECT_SCOPE_KEY = 'zitadel_project';
+const ZITADEL_ORG_SCOPE_KEY = 'zitadel_org';
+/**
+ * Every resource `FoundryPlanApply.destroy` tears down, built from
+ * `AppliedState.serviceIds`, in the order the goal line and this campaign's
+ * report settle on: the Cloudflare tunnel first, then the Access gate (stop routing traffic to the
+ * app before tearing it down), then the org's own Coolify database and app,
+ * then the org's customers ZITADEL org (plan gap A9), then every ZITADEL app
+ * foundry recorded, then the ZITADEL project, then the
+ * ZITADEL org itself -- the one resource every other one in this org lives
+ * inside, so it goes last.
+ *
+ * ZITADEL apps are read directly from `serviceIds` (any key with the
+ * `zitadel:app:` prefix), not from the declared org's current
+ * `hosting.issuerApps` -- destroy tears down everything foundry actually
+ * recorded for this org, including an app since removed from the declared
+ * list (drift `diff.ts`'s own `planIssuerApps` doc comment already
+ * acknowledges: "removing an app from `issuerApps` entirely produces no step
+ * at all").
+ *
+ * The Cloudflare zone and the Coolify project are deliberately absent: no
+ * zone-delete or Coolify-project-delete method was named for this campaign
+ * (Finding, this campaign's report), so destroy leaves both in place. The
+ * Cloudflare rate limiting rule (#43, `diff.ts`'s `planRateLimit`) is absent
+ * for the same reason: it lives inside the same zone's ruleset, no rule-
+ * delete method exists on `CloudflarePort` (`executor.ts`), and the zone it
+ * belongs to is already left in place -- deleting only the rule and not the
+ * zone is a decision left for whoever wires teardown in, not made here.
+ */
+function destroyTargets(serviceIds) {
+    // Reverse-teardown order: everything under one of these prefixes is
+    // collected in this order, then every ZITADEL app (there can be several,
+    // #71), then the two scope ids last.
+    const ORDERED_PREFIXES = [
+        'cloudflare:tunnel:',
+        'cloudflare:access:',
+        'coolify:database:',
+        'coolify:app:',
+        'zitadel:customers:',
+    ];
+    const targets = [];
+    for (const prefix of ORDERED_PREFIXES) {
+        for (const [resourceKey, id] of Object.entries(serviceIds)) {
+            if (!resourceKey.startsWith(prefix))
+                continue;
+            const [system, kind] = prefix.split(':');
+            targets.push({ system, kind, key: resourceKey.slice(prefix.length), id });
+        }
+    }
+    for (const [resourceKey, id] of Object.entries(serviceIds)) {
+        if (!resourceKey.startsWith('zitadel:app:'))
+            continue;
+        targets.push({
+            system: 'zitadel',
+            kind: 'app',
+            key: resourceKey.slice('zitadel:app:'.length),
+            id,
+        });
+    }
+    for (const [kind, scopeKey] of [
+        ['project', ZITADEL_PROJECT_SCOPE_KEY],
+        ['org', ZITADEL_ORG_SCOPE_KEY],
+    ]) {
+        const id = serviceIds[scopeKey];
+        if (id)
+            targets.push({ system: 'zitadel', kind, key: scopeKey, id });
+    }
+    return targets;
+}
+/** The `AppliedState.serviceIds` key a completed {@link DestroyTarget} should be removed from. */
+function destroyServiceIdKey(target) {
+    if (target.kind === 'project' || target.kind === 'org')
+        return target.key;
+    return `${target.system}:${target.kind}:${target.key}`;
+}
+/**
+ * The declared field each planned step makes true, keyed `system:kind` as
+ * `diff.ts` plans it. A kind not listed here falls back to `system.kind`, so
+ * a new planner step still names something rather than vanishing.
+ */
+const STEP_FIELDS = {
+    'zitadel:issuer': 'issuer.usesDomain',
+    'zitadel:owner': 'owner',
+    'zitadel:customers': 'hosting.issuerApps',
+    'coolify:mail': 'mail',
+    'coolify:chat': 'chat.usesDomain',
+    'files:storage': 'storage',
+    'ai:budget': 'ai',
+    'cms:site': 'site',
+    'coolify:app': 'hosting.enabled',
+    'coolify:database': 'hosting.database',
+    'cloudflare:tunnel': 'hosting.tunnel',
+    'cloudflare:zone': 'hosting.usesDomain',
+    'cloudflare:access': 'hosting.accessEmails',
+    'cloudflare:ratelimit': 'hosting.usesDomain',
+};
+function stepField(action) {
+    // An org declares several issuer apps, each keyed by its name (#71).
+    if (action.system === 'zitadel' && action.kind === 'app') {
+        return `hosting.issuerApps.${action.key}`;
+    }
+    return STEP_FIELDS[`${action.system}:${action.kind}`] ?? `${action.system}.${action.kind}`;
+}
+/**
+ * #25: the declared fields this apply could not make true, written fresh on
+ * every apply rather than carried forward.
+ *
+ * Three sources, in this order:
+ * - fields no planner step exists for yet, so no apply can make them true:
+ *   SSO, guests and solo when turned on, calls on the org's domain, a
+ *   bespoke app repo, an adopted app in the `repo` form (#7's `#15` comment:
+ *   "declared but refused by `apply`"), and hosting on a domain the org has
+ *   not recorded;
+ * - chat's reverse re-key, which the planner surfaces but which is not built
+ *   (#7 amendment 3), so it counts as failed even when no step threw;
+ * - on a failed apply, the field of every planned step from the one that
+ *   threw onwards (`completed` is how many steps finished).
+ */
+function failedFields(org, detail, completed) {
+    const failed = new Set();
+    if (org.sso.enabled)
+        failed.add('sso.enabled');
+    if (org.guests.enabled)
+        failed.add('guests.enabled');
+    if (org.solo.enabled)
+        failed.add('solo.enabled');
+    if (org.bespokeAppRepo !== null)
+        failed.add('bespokeAppRepo');
+    if (org.adoptedApp?.form === 'repo')
+        failed.add('adoptedApp');
+    if (org.calls.usesDomain)
+        failed.add('calls.usesDomain');
+    // `planZone` plans nothing without a domain to put the zone on.
+    if (org.hosting.usesDomain && org.domain === null)
+        failed.add('hosting.usesDomain');
+    // `planTunnel` shares that same domain requirement (#71, map gap N3): a
+    // declared `usesDomain: true` with no recorded domain plans no tunnel
+    // step either. A domainless org (`usesDomain: false`) is not a failure --
+    // it is the level-1 case N3 decided gets no per-org tunnel at all.
+    if (org.hosting.tunnel && org.hosting.usesDomain && org.domain === null) {
+        failed.add('hosting.tunnel');
+    }
+    for (const { action, step } of detail.plannedSteps) {
+        // Provisioning chat also desires `usesDomain: false`; only the reverse
+        // re-key is a destructive step with that value.
+        const reverseReKey = action.system === 'coolify' &&
+            action.kind === 'chat' &&
+            action.desired.usesDomain === false &&
+            step.destroys;
+        if (reverseReKey)
+            failed.add(stepField(action));
+    }
+    for (const { action } of detail.plannedSteps.slice(completed))
+        failed.add(stepField(action));
+    return [...failed];
+}
 /** Order-independent structural equality between two plans. */
 function plansMatch(a, b) {
     return JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));