@wtfalch/foundry 0.1.0 → 0.3.0

package/dist/plan/executor.d.ts

@@ -0,0 +1,823 @@
+import type { OrgMailOptions, OrgMailOrg, OrgMailResult } from '@wtfalch/email/postmaster';
+import type { DeclaredOrg, HostingBuildPack, OrgId } from '../org.js';
+import type { StepAction } from './diff.js';
+import type { DestroyTarget, StepDestroyer, StepExecutionContext, StepExecutor } from './plan-apply.js';
+/**
+ * The real {@link StepExecutor} (#20 "provision Company Factory end to
+ * end"): makes each {@link StepAction} `diff.ts` plans true against a real
+ * Coolify, Cloudflare and ZITADEL, plus per-org organisations, spend limits
+ * and (for AI) offers on Files and AI (#80). Scope and design are exactly
+ * what `.claude/decisions-2026-09-24-executor.md`'s "Executor decisions"
+ * section settled, referenced by name at each dispatch branch below.
+ *
+ * Built entirely from narrow ports (interfaces), never a concrete
+ * `@wtfalch/providers` client: this package holds no credential and never
+ * will (executor decisions: "the executor is constructed with narrow ports
+ * ... a host [archon] supplies real clients. How the host gets provider
+ * tokens from the keys Worker is the host's job, not this campaign's").
+ * Every port method here is named and shaped to match a real method on
+ * `@wtfalch/providers`' `CoolifyClient`/`CloudflareClient`/`ZitadelClient`
+ * (checked against `providers` `origin/main`, 2026-09-24), or on
+ * `@wtfalch/files`'/`@wtfalch/ai`'s own SDK clients (#80, checked against
+ * each repo's own `main`, 2026-09-25), so a real client satisfies the port
+ * structurally, with no adapter needed — see each port's own doc comment for
+ * the one real method it does not yet have.
+ */
+/**
+ * The Coolify calls this executor makes, shaped to match
+ * `@wtfalch/providers/coolify`'s `CoolifyClient` method-for-method — a real
+ * `CoolifyClient` instance satisfies this port with no adapter.
+ *
+ * There is no single `findOrCreateProject`/stop/start on `CoolifyClient`
+ * today (unlike ZITADEL's `findOrCreateOrg`/`findOrCreateProject`, which
+ * already exist): `findProjectByName` + `createProject` compose into
+ * "find or create" inside this executor instead of the port, and `raw` —
+ * `CoolifyClient`'s own documented escape hatch for "use — or add — a typed
+ * method instead" — carries the stop/start calls Coolify's REST API has
+ * (`POST /applications/{uuid}/stop`, `POST /databases/{uuid}/stop`) that
+ * `CoolifyClient` has not wrapped yet. Logged as a Decision in this
+ * campaign's report rather than inventing port methods (`findOrCreateProject`,
+ * `stop`, `start`) no real client could structurally satisfy.
+ */
+export interface CoolifyPort {
+    findProjectByName(name: string): Promise<{
+        uuid: string;
+        name: string;
+    } | null>;
+    createProject(name: string, description?: string): Promise<{
+        uuid: string;
+    }>;
+    findOrCreateEnvironment(projectUuid: string, name: string): Promise<{
+        environment: {
+            id: number;
+            uuid: string;
+            name: string;
+        };
+        created: boolean;
+    }>;
+    listServers(): Promise<Array<{
+        uuid: string;
+        is_usable: boolean;
+        is_reachable: boolean;
+    }>>;
+    requireGithubApp(preferredUuid?: string): Promise<{
+        uuid: string;
+        name: string;
+    }>;
+    findApplicationByName(name: string, scope?: {
+        environmentIds: number[];
+    }): Promise<{
+        uuid: string;
+    } | null>;
+    /**
+     * One application's own live status (`` `running:healthy`, `exited:unhealthy`
+     * `` -- `@wtfalch/providers`' `CoolifyApplication.status` doc comment) --
+     * `findOrCreateCmsApp`'s own check of whether an app it found by name
+     * (rather than just created) needs starting again (#116 review round 3,
+     * Finding 1).
+     */
+    getApplication(uuid: string): Promise<{
+        uuid: string;
+        status?: string;
+    }>;
+    createGithubAppApplication(input: {
+        project_uuid: string;
+        server_uuid: string;
+        environment_name: string;
+        environment_uuid: string;
+        github_app_uuid: string;
+        git_repository: string;
+        git_branch: string;
+        build_pack: HostingBuildPack;
+        name?: string;
+        domains?: string;
+        /** Selects which of two Dockerfiles in one repo to build (`cmsSite`'s own site/cms apps). */
+        dockerfile_location?: string;
+    }): Promise<{
+        uuid: string;
+    }>;
+    createPostgresDatabase(input: {
+        project_uuid: string;
+        server_uuid: string;
+        environment_name: string;
+        environment_uuid: string;
+        name: string;
+        postgres_db: string;
+        postgres_user: string;
+    }): Promise<{
+        uuid: string;
+        internal_db_url: string;
+    }>;
+    /**
+     * Coolify's own record of a database, re-read here (rather than trusted
+     * from `createPostgresDatabase`'s return value) so the app's env is wired
+     * from the database's live state whether this run just created it or found
+     * it already there (`coolifyApp`/`coolifyDatabase` below, hosting-wiring
+     * campaign; `cmsSite`'s own cms database, #117). `internal_db_url` is
+     * `postgres://user:password@host/db` — a
+     * live credential, present in the raw Coolify API response and reachable
+     * only from inside the Coolify Docker network (`@wtfalch/providers`'
+     * `CoolifyClient.createPostgresDatabase` doc comment).
+     */
+    getDatabase(uuid: string): Promise<{
+        uuid: string;
+        internal_db_url?: string;
+    }>;
+    /**
+     * Every database Coolify holds. `coolifyDatabase` finds its own by name and
+     * environment, so a crash between create and persist does not make a second
+     * one on the next apply. Only `uuid`, `name` and `environment_id` are read;
+     * the raw response also carries `internal_db_url`, which is never used here.
+     */
+    listDatabases(): Promise<Array<{
+        uuid: string;
+        name: string;
+        environment_id?: number;
+    }>>;
+    /**
+     * Upsert environment variables on an application in one call — used here to
+     * push the database's `internal_db_url` in as the app's `DATABASE_URL`
+     * (hosting-wiring campaign), and, for the cms app, its `DATABASE_URL_OWNER`
+     * plus a freshly minted `DATABASE_URL` runtime-role credential (#117). Each
+     * value is a live credential: it must reach this call and nothing else —
+     * never a step's return value, `serviceIds` (hence the store), an audit
+     * record, a log or a thrown error. See `coolifyApp`'s `pushDatabaseUrl` and
+     * `cmsSite`'s `ensureCmsRuntimeUrl`.
+     */
+    bulkUpsertEnvs(applicationUuid: string, envs: Array<{
+        key: string;
+        value: string;
+        buildTime?: boolean;
+        literal?: boolean;
+        multiline?: boolean;
+    }>): Promise<unknown>;
+    /**
+     * Every environment variable currently on the application — read before
+     * generating `AUTH_COOKIE_SECRET` (`ensureAuthCookieSecret`, level-1
+     * app-env campaign) so that value is only ever generated once, never
+     * overwritten. Every key comes back twice (a production row and an
+     * `is_preview` duplicate, `@wtfalch/providers`' `CoolifyClient.listEnvs`
+     * doc comment), so a caller checking "does this key already exist" filters
+     * `is_preview === false` the same way a deployed-config reader must.
+     */
+    listEnvs(applicationUuid: string): Promise<Array<{
+        key: string;
+        value: string;
+        is_preview: boolean;
+    }>>;
+    /** Escape hatch (`CoolifyClient.raw`) — used for stop/start, which have no typed method yet. */
+    raw(method: string, path: string, body?: unknown): Promise<unknown>;
+    /**
+     * Persistent (named volume) and file storages already attached to an
+     * application (#75) — `ensureLogVolume` reads this before creating one, so
+     * a re-run never mounts a second volume at the same path.
+     */
+    listStorages(applicationUuid: string): Promise<{
+        persistent_storages?: Array<{
+            uuid: string;
+            name?: string;
+            mount_path: string;
+        }>;
+        file_storages?: Array<{
+            uuid: string;
+            mount_path: string;
+        }>;
+    }>;
+    /** Mounts a named volume on an application (#75) — `ensureLogVolume`'s create path. */
+    createPersistentStorage(applicationUuid: string, input: {
+        name: string;
+        mount_path: string;
+    }): Promise<unknown>;
+    /**
+     * Restarts the running container without a rebuild (#75) — `ensureLogVolume`
+     * calls this after mounting a volume on an app that was already running,
+     * since Coolify only binds a newly created storage into the container at
+     * its next start.
+     */
+    restart(applicationUuid: string): Promise<unknown>;
+    /** `FoundryPlanApply.destroy`'s teardown of the org's own app. */
+    deleteApplication(uuid: string): Promise<unknown>;
+    /** `FoundryPlanApply.destroy`'s teardown of the org's own database. */
+    deleteDatabase(uuid: string): Promise<unknown>;
+}
+/**
+ * The Cloudflare calls this executor makes, shaped to match
+ * `@wtfalch/providers/cloudflare`'s `CloudflareClient` method-for-method.
+ */
+export interface CloudflarePort {
+    findZoneByApex(domain: string): Promise<{
+        id: string;
+        name: string;
+    } | undefined>;
+    createZone(name: string): Promise<{
+        id: string;
+        name: string;
+    }>;
+    findTunnelByName(name: string): Promise<{
+        id: string;
+        name: string;
+    } | undefined>;
+    createTunnel(name: string): Promise<{
+        id: string;
+        name: string;
+    }>;
+    putTunnelConfig(tunnelId: string, config: unknown): Promise<unknown>;
+    /** `FoundryPlanApply.destroy`'s teardown of the org's own Cloudflare tunnel. */
+    deleteTunnel(tunnelId: string): Promise<void>;
+    /** `cloudflareAccess` finds the org's Access app by domain before creating one (#84). */
+    listAccessApps(): Promise<Array<{
+        id: string;
+        name: string;
+        domain: string;
+    }>>;
+    createAccessApp(app: {
+        name: string;
+        domain: string;
+        type: string;
+    }): Promise<{
+        id: string;
+    }>;
+    listAccessPolicies(appId: string): Promise<Array<{
+        id: string;
+        name: string;
+    }>>;
+    createAccessPolicy(appId: string, policy: {
+        name: string;
+        decision: string;
+        include: unknown[];
+    }): Promise<{
+        id: string;
+    }>;
+    deleteAccessApp(appId: string): Promise<void>;
+    /**
+     * `FoundryPlanApply.destroy`'s teardown of any DNS record foundry created
+     * for the org. Nothing in this executor creates or records one yet (Finding,
+     * this campaign's report: no `cloudflare:dns` resource kind exists in
+     * `diff.ts`/`executor.ts` today), so `destroy` has no dispatch target for
+     * it either -- this port method exists ready for whichever step starts
+     * creating one.
+     */
+    deleteDnsRecord(zoneId: string, recordId: string): Promise<void>;
+    /** `coolify:mail`'s lookup of an existing MX/TXT record before upserting it, filtered by type so a stale record of a different type is never mistaken for a match. */
+    findDnsRecord(zoneId: string, name: string, type?: string): Promise<Array<{
+        id: string;
+        type: string;
+        content: string;
+        name: string;
+    }>>;
+    createDnsRecord(zoneId: string, rec: {
+        type: string;
+        name: string;
+        content: string;
+        proxied?: boolean;
+        ttl?: number;
+    }): Promise<{
+        id: string;
+        name: string;
+        content: string;
+    }>;
+    updateDnsRecord(zoneId: string, recordId: string, rec: {
+        type: string;
+        name: string;
+        content: string;
+        proxied?: boolean;
+        ttl?: number;
+    }): Promise<{
+        id: string;
+        name: string;
+        content: string;
+    }>;
+    /**
+     * Escape hatch (mirrors `CoolifyPort.raw`'s own precedent above) --
+     * `@wtfalch/providers` 0.5.0's `CloudflareClient` has no typed method for
+     * Health Checks or zone rulesets/rate-limiting rules
+     * (https://github.com/wtfalch/foundry/issues/43), only this public,
+     * generic `request<T>(method, path, body?, missingOkay?)`, which
+     * this port names directly rather than inventing a narrower method no real
+     * client could structurally satisfy. `cloudflareRateLimit` below is its one
+     * caller today. `missingOkay` makes a 404 resolve to `undefined` instead of
+     * throwing, matching `CloudflareClient`'s own real behavior exactly.
+     */
+    request<T>(method: string, path: string, body?: unknown, missingOkay?: boolean): Promise<T>;
+}
+/**
+ * The Stalwart calls this executor makes for one org's mail, shaped to match
+ * `@wtfalch/email/postmaster`'s `applyOrgMail`/`parkOrgMail` method-for-method
+ * with the `StalwartClient` bound, the same way {@link CloudflarePort} mirrors
+ * `CloudflareClient`.
+ */
+export interface MailPort {
+    applyOrgMail(org: OrgMailOrg, options: OrgMailOptions): Promise<OrgMailResult>;
+    parkOrgMail(org: OrgMailOrg, options: OrgMailOptions): Promise<void>;
+}
+/**
+ * The ZITADEL calls this executor makes. `findOrCreateOrg`/`findOrCreateProject`
+ * already exist on `@wtfalch/providers/zitadel`'s `ZitadelClient` (returning
+ * `{org|project, created}`, not the bare `{id}` this campaign's brief
+ * sketched — matched to the real shape here, logged as a Decision).
+ * `createOidcApp`/`createApiApp`/`deleteApp` do not exist yet — "being added
+ * to providers in parallel" (task brief) — so this port states the shapes
+ * they need to land with; a `ZitadelClient` that gains exactly these three
+ * methods satisfies this port with no adapter.
+ */
+export interface ZitadelPort {
+    findOrCreateOrg(name: string): Promise<{
+        org: {
+            id: string;
+            name: string;
+        };
+        created: boolean;
+    }>;
+    findOrCreateProject(orgId: string, name: string): Promise<{
+        project: {
+            id: string;
+            name: string;
+        };
+        created: boolean;
+    }>;
+    createOidcApp(orgId: string, projectId: string, input: {
+        name: string;
+        appType: 'web' | 'native';
+        redirectUris: string[];
+        postLogoutRedirectUris: string[];
+    }): Promise<{
+        appId: string;
+        clientId: string;
+    }>;
+    /**
+     * Returns `clientSecret` alongside `appId`/`clientId` — ZITADEL mints it
+     * once, on creation, and never shows it again (`providers`' `ZitadelClient.
+     * createApiApp`, commit 1d0fec2). The executor hands it straight to
+     * {@link FoundryStepExecutorPorts.deliverSecret} and never returns, stores
+     * or logs it itself (see that port's doc comment).
+     */
+    createApiApp(orgId: string, projectId: string, input: {
+        name: string;
+    }): Promise<{
+        appId: string;
+        clientId: string;
+        clientSecret: string;
+    }>;
+    deleteApp(orgId: string, projectId: string, appId: string): Promise<void>;
+    /**
+     * The org-owner flow (goal line): find-or-create the human user by email in
+     * the org, then have ZITADEL email them an invite to set up a passkey.
+     * Idempotent on the user; the invite itself is not (a re-run always sends a
+     * fresh code) — `plan/diff.ts`'s `planOwner` is what makes a *re-run of
+     * foundry's own apply* idempotent, by planning nothing once the returned
+     * `userId` is recorded. Returns only ids, matching `createApiApp`'s own
+     * rule for anything invite/credential-shaped: the email itself is a
+     * parameter here, never part of the return value.
+     */
+    inviteOrgOwner(orgId: string, owner: {
+        givenName: string;
+        familyName: string;
+        email: string;
+    }): Promise<{
+        userId: string;
+        created: boolean;
+    }>;
+    /** Lets anyone sign up to the org (plan gap A9). Idempotent. */
+    allowSelfRegistration(orgId: string): Promise<{
+        changed: boolean;
+    }>;
+    /** Grants another ZITADEL org access to a project (plan gap A9). Idempotent. */
+    findOrCreateProjectGrant(orgId: string, projectId: string, grantedOrgId: string): Promise<{
+        created: boolean;
+    }>;
+    /** `FoundryPlanApply.destroy`'s teardown of the org's ZITADEL project, once every app inside it is gone. */
+    deleteProject(orgId: string, projectId: string): Promise<void>;
+    /** `FoundryPlanApply.destroy`'s last step: removes the whole ZITADEL org and everything foundry made inside it. */
+    deleteOrg(orgId: string): Promise<void>;
+}
+/**
+ * One org's spend limit on Files, matching `files/packages/sdk/src/client.ts:154-166`'s
+ * `setQuota`/`setBudget` (the caller's own organisation, resolved from its
+ * signed request — no organisation id parameter, hence a factory per org
+ * rather than one flat port).
+ */
+export interface FilesOrgLimits {
+    setQuota(limitBytes: string | null): Promise<unknown>;
+    setBudget(limitMicros: string | null): Promise<unknown>;
+}
+/**
+ * One org's budget on AI, matching `ai/packages/sdk/src/client.ts:94-101`'s
+ * `updateBudget` (`UpdateBudget` from `ai/packages/sdk/src/types.ts:134-137`).
+ */
+export interface AiOrgLimits {
+    updateBudget(input: {
+        keyId: string | null;
+        limitMicros: string;
+    }): Promise<unknown>;
+}
+/**
+ * Provisions one org's organisation on Files (#80), matching
+ * `files/packages/sdk/src/client.ts:136-145`'s
+ * `createFilesManagementClient().provisionOrganisation`
+ * (`ProvisionOrganisationInput`/`ProvisionOrganisationResult`,
+ * `files/packages/sdk/src/types.ts:146-156`). Flat, not a factory, like
+ * {@link ZitadelPort}: `organisationId` is an explicit call argument here,
+ * unlike {@link FilesOrgLimits}'s tenant-scoped calls, which resolve the
+ * caller's own organisation from its signed request instead.
+ *
+ * Finding (this campaign's report): unlike {@link AiOrganisationPort}'s bearer
+ * credential, `createFilesManagementClient`'s whole transport is "a signed
+ * human proof or an issued management key" (`files/packages/sdk/src/
+ * client.ts:117-119`) — concretely an Ed25519-signed `x-wtfalch-management`
+ * request (`files/apps/host/src/lib/authz/service-assertion.ts`'s
+ * `signManagementRequest`/`AssertionTrust`). A host can construct this without
+ * any human session: it only needs the Ed25519 private key (`SigningIdentity`)
+ * an operator's `MANAGEMENT_PUBLIC_KEYS`/`MANAGEMENT_ISSUER` pins — the same
+ * signer {@link FilesOrgLimits} needs for `setQuota`/`setBudget`, since the
+ * `organisation` field inside the signed claim selects the org per call, so
+ * one shared keypair signs for every org rather than needing a secret per
+ * org.
+ */
+export interface FilesOrganisationPort {
+    provisionOrganisation(input: {
+        organisationId: string;
+        ceilingBytes: string | null;
+        ceilingMicros: string | null;
+        shareHost?: string | null;
+    }): Promise<{
+        organisationId: string;
+        ceilingBytes: string | null;
+        ceilingMicros: string | null;
+        usedBytes: string;
+        reservedBytes: string;
+        spentMicros: string;
+        suspended: boolean;
+        shareHost: string | null;
+        created: boolean;
+    }>;
+}
+/**
+ * Provisions one org's organisation on AI and switches its AI use on (#80),
+ * matching `ai/packages/sdk/src/client.ts:98-108`'s `provisionOrganisation`/
+ * `setOrganisationOffers` (`ProvisionOrganisation`/`ProvisionOrganisationResult`,
+ * `SetOrganisationOffers`/`OrganisationOffersView`,
+ * `ai/packages/sdk/src/types.ts:121-143`). Flat, not a factory, for the same
+ * reason as {@link FilesOrganisationPort}.
+ *
+ * Finding (this campaign's report): AI's machine credential is a plain bearer
+ * key — archon's own `AI_MANAGEMENT_KEY`, minted by
+ * `ai/apps/host/scripts/authz/bootstrap-archon.ts`'s `keys:issue-archon` with
+ * `ARCHON_AI_PERMISSIONS` (`ai.organisations:provision`,
+ * `ai.organisations:offer`, `ai.budgets:update`, among others) copied onto
+ * it — used directly with `createAiClient`, unlike Files' signed-assertion
+ * transport above.
+ */
+export interface AiOrganisationPort {
+    provisionOrganisation(input: {
+        organisationId: string;
+        limitMicros: string | null;
+    }): Promise<{
+        organisationId: string;
+        limitMicros: string | null;
+        created: boolean;
+    }>;
+    setOrganisationOffers(organisationId: string, offers: string[]): Promise<{
+        organisationId: string;
+        offers: string[];
+    }>;
+}
+export interface FoundryStepExecutorPorts {
+    coolify: CoolifyPort;
+    cloudflare: CloudflarePort;
+    zitadel: ZitadelPort;
+    mail: MailPort;
+    /** A factory, not a flat client: Files/AI are org-scoped credentials the host resolves per org. */
+    filesLimitsFor: (orgId: OrgId) => FilesOrgLimits;
+    aiLimitsFor: (orgId: OrgId) => AiOrgLimits;
+    /** Flat, not a factory: `organisationId` is an explicit argument on both ports (see each port's own doc comment). */
+    filesOrganisation: FilesOrganisationPort;
+    aiOrganisation: AiOrganisationPort;
+    /**
+     * Hands a just-minted, one-time secret (today: an API app's
+     * `clientSecret`) to the host, immediately after the provider returns it
+     * and before the step that created it returns. This package "holds no
+     * credential and never will" (this file's own top doc comment), so a
+     * secret is never a step's return value, never goes into `serviceIds` (the
+     * store, hence the DB), and is never logged or interpolated into a thrown
+     * error -- this is its one way out of the executor. `ref` names what the
+     * secret belongs to (e.g. `zitadel:app:<org.slug>:<key>`); routing it
+     * anywhere durable (a keys Worker, a secret store) is the host's job, the
+     * same division `executor.ts`'s top comment draws for provider tokens
+     * themselves.
+     */
+    deliverSecret(ref: string, secret: string): Promise<void>;
+}
+/**
+ * Thrown by name for a step this executor deliberately does not implement:
+ * chat (no admin API exists yet), plus moving the issuer onto or off the
+ * org's domain (built, but not in v1 — domain verification and passkey
+ * invalidation need their own design). Never carries a token, secret or key
+ * (task brief: "errors carry the step and the provider's status only").
+ */
+export declare class NotBuiltError extends Error {
+    constructor(step: string, detail: string);
+}
+/**
+ * The health URLs an outside prober should call for this org (#43): one per
+ * app foundry runs for it. A hosting org's app answers at its own hostname,
+ * and a site org's site app and cms app both serve `/api/health`
+ * (https://github.com/wtfalch/cms/tree/main/apps). An org that runs neither
+ * has nothing to probe. Exported so archon, which owns uptime, never repeats
+ * this file's hostname rules.
+ */
+export declare function healthUrls(org: DeclaredOrg): string[];
+export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer {
+    private readonly ports;
+    constructor(ports: FoundryStepExecutorPorts);
+    execute(action: StepAction, context: StepExecutionContext): Promise<{
+        resourceId?: string;
+    } | undefined>;
+    /**
+     * `plan/diff.ts`'s `planAccess` (#84): puts the org's app hostname behind a
+     * Cloudflare Access app that lets only `hosting.accessEmails` through.
+     * foundry names its Access app `foundry:<orgId>` and reuses only an app with
+     * that name, so a re-run after a crash does not duplicate it. It refuses,
+     * rather than adopt, when another Access app already holds the hostname:
+     * destroy would later delete it. It also refuses when its own app carries
+     * any policy but foundry's, since that policy could let others in.
+     */
+    private cloudflareAccess;
+    /**
+     * `plan/diff.ts`'s `planRateLimit` (#43): one Cloudflare rate limiting
+     * rule, scoped to `SIGN_IN_PATH_EXPRESSION`, on the org's own Cloudflare
+     * zone -- only ever called for an own-domain org (`planRateLimit`'s own
+     * gate), so `org.domain` is set and that zone is the org's alone, never
+     * shared with another org the way `oikos.host` is.
+     *
+     * Rate limiting rules attach to a zone's `http_ratelimit` phase entry
+     * point ruleset, one `GET`/`PUT` pair per zone (`@wtfalch/providers` 0.5.0
+     * has no typed method for either -- `CloudflarePort.request`'s own doc
+     * comment) -- so "find by name" here means reading that one ruleset's
+     * `rules[]` and matching `RATE_LIMIT_RULE_DESCRIPTION`, the same shape
+     * `cloudflareAccess` above finds its own Access app by name. The Free
+     * plan allows exactly one rule per zone, so a rule already there under a
+     * different description is refused, never adopted or replaced, mirroring
+     * `cloudflareAccess`'s own refusal when a foreign Access app already
+     * holds the hostname.
+     */
+    private cloudflareRateLimit;
+    private zitadelIssuer;
+    /**
+     * `plan/diff.ts`'s `planOwner`: invites the org's owner into its ZITADEL
+     * org by email. Never logs, returns or throws the email itself -- only the
+     * invited user id, handed back as `resourceId` so `runSteps` records it
+     * under `zitadel:owner:<orgId>`, which is exactly what makes the next
+     * `plan()` call idempotent (`planOwner` plans nothing once that key is
+     * recorded).
+     */
+    private zitadelOwner;
+    /**
+     * `plan/diff.ts`'s `planCustomers` (plan gap A9): the org's customers sign
+     * in through a second ZITADEL org, `<slug> customers`, with
+     * self-registration on and a grant to the org's app project. Staff stay in
+     * the org's own invite-only ZITADEL org. The space keeps the name apart from
+     * every issuer org, which is named by a slug and a slug has no spaces. Every call here is idempotent, so
+     * a re-run after a crash finishes the job.
+     */
+    private zitadelCustomers;
+    private zitadelApp;
+    private ensureZitadelProject;
+    private ensureCoolifyProject;
+    private resolveServer;
+    private coolifyApp;
+    /**
+     * #75: mounts a persistent volume at {@link LOG_DIR} on the app, unless one
+     * is already there. Found by `mount_path`, not a recorded id — no
+     * `serviceIds` entry exists for a storage the way one does for the app or
+     * database itself, and Coolify's own listing is cheap enough to check
+     * first every time, the same way `coolifyDatabase` finds its database by
+     * name before creating one. Never called from the `enabled === false`
+     * (park) branch above, so parking an app never touches its volume either.
+     *
+     * Mounting a volume on an application already running does not attach it
+     * to the live container -- Coolify only binds a storage in at the
+     * container's next start (Finding, refuted against the first version of
+     * this method: it created the storage and let a passing `listStorages`
+     * read report `hasLogVolume: true` on the very next plan, with the
+     * container itself still writing nowhere). `wasAlreadyRunning` tells this
+     * method whether `appId` names an app `coolifyApp` found already there
+     * (restart it once the volume is created) or one it just created fresh
+     * (already about to get its first deploy/start from
+     * `createGithubAppApplication`'s own instant-deploy path, so a restart
+     * here would only be a redundant extra one).
+     */
+    private ensureLogVolume;
+    private coolifyDatabase;
+    /**
+     * Pushes the database's connection string into the app's environment as
+     * `DATABASE_URL` -- never also as `DATABASE_URL_OWNER` (Decision, this
+     * campaign's report). Archon's own boot script
+     * (`archon/scripts/migrate-and-start.sh`) treats a bare `DATABASE_URL` with
+     * no `DATABASE_URL_OWNER` as "before the split": it migrates and serves as
+     * the one role it has, which is exactly what a database Coolify just
+     * created (one superuser role, no separate runtime role yet) is. Setting
+     * both to the *same* superuser URL would instead take the split branch --
+     * `db-role-guard.sh` then refuses to boot, since `DATABASE_URL_OWNER` being
+     * set means it expects `DATABASE_URL` to connect as a distinct,
+     * non-superuser runtime role (`<database>_rt`), which nothing here creates.
+     * Minting that role's own password and URL is a provisioning step of its
+     * own, not built here (Finding, this campaign's report).
+     *
+     * The connection string is a live credential
+     * (`postgres://user:password@host/db`): it is read from
+     * `CoolifyPort.getDatabase` and handed straight to `bulkUpsertEnvs` and
+     * nowhere else in this class -- never returned, never recorded in
+     * `serviceIds` (hence never in the store or an audit record), never logged,
+     * never interpolated into a thrown error.
+     */
+    private pushDatabaseUrl;
+    /**
+     * Pushes what the org's app needs to sign a user in through ZITADEL (gap
+     * P2, `.plans/2026-09-26-level-1-org-map.md`) -- a second `bulkUpsertEnvs`
+     * call rather than folding into `pushDatabaseUrl`'s, since this one runs
+     * unconditionally (`coolifyApp`) where that one runs only once
+     * `hosting.database` is declared and provisioned.
+     *
+     * `APP_URL` and `LOG_DIR` (#75) are pushed unconditionally; every other
+     * value is pushed only once its own source step has actually recorded it
+     * (`context.recordedIds()`) -- on a first-ever apply,
+     * run one step at a time in `diff.ts`'s `computePlanDetail` order, that is
+     * `zitadel:issuer` (`AUTH_ORGANIZATION_ID`), `zitadel:owner`
+     * (`OWNER_USER_ID`, gap P3) and every `zitadel:app` step
+     * (`AUTH_CLIENT_ID`), all ordered before `coolify:app` for exactly this
+     * reason. AUTH_APP_KEY (waits on an auth broker registration API) and
+     * DATABASE_URL_OWNER (a runtime-role split not built yet, `pushDatabaseUrl`'s
+     * own doc comment) are out of scope here (task brief).
+     */
+    private pushAppEnv;
+    /**
+     * `null` once the app already has one -- `AUTH_COOKIE_SECRET` is generated
+     * only the first time (task brief), never regenerated or overwritten, so a
+     * later apply's `bulkUpsertEnvs` call simply omits the key rather than
+     * upsert a fresh value over it.
+     */
+    private ensureAuthCookieSecret;
+    /**
+     * `plan/diff.ts`'s `planSite` (#116, slicing #99's "provision the cms app,
+     * database and site app per org"): the 2026-09-25 decision
+     * (https://github.com/wtfalch/cms/blob/main/.plans/2026-09-25-org-sites.md)
+     * means foundry never calls a cms admin API for the org's site -- it
+     * provisions two ordinary Coolify applications from the one
+     * https://github.com/wtfalch/cms repo, the same way `coolifyApp` above
+     * provisions the org's own hosted app: a site app (`apps/site`, the
+     * reference renderer) at `org.domain`, built from
+     * `CMS_SITE_APP_DOCKERFILE`, and a cms app (`apps/host`, single-org mode,
+     * https://github.com/wtfalch/cms/blob/main/docs/adr/0013-one-cms-per-org.md)
+     * at {@link cmsHostnameFor}, built from the repo's own root
+     * `CMS_APP_DOCKERFILE` -- one repo, two applications, told apart by
+     * `dockerfile_location`.
+     *
+     * `action.key` is `org.id` (`planSite`'s own singleton key), so `execute`'s
+     * own auto-record has only one `resourceId` slot for this step
+     * (`cms:site:<orgId>`) -- returned here as the cms app's id, the resource
+     * this step is named for. The site app's id has no such slot, so both ids
+     * are also recorded as scope ids ({@link CMS_APP_SCOPE_KEY}/
+     * {@link SITE_APP_SCOPE_KEY}), read back by the park branch below on a
+     * later apply, when nothing gets provisioned to return one -- read
+     * independently of each other there, since a crash partway through a
+     * first-ever provision can leave only one of the two actually recorded.
+     *
+     * #117: this step also finds or creates the cms app's own Postgres
+     * database ({@link ensureCmsDatabase}) and pushes its owner and runtime
+     * connection strings ({@link ensureCmsRuntimeUrl}) onto the cms app, in the
+     * same `bulkUpsertEnvs` call as `APP_URL`/`CMS_ORGANISATION_ID`/
+     * `CMS_SITE_URL` below. The database's id is recorded as a third flat scope
+     * id ({@link CMS_DATABASE_SCOPE_KEY}), for the same reason the two app ids
+     * are: no `system:kind:key` slot of its own. Never touched from the park
+     * branch above -- parking stops the two apps only, same as #116's own
+     * destroy note; this step never parks or destroys the database.
+     */
+    private cmsSite;
+    /**
+     * `cmsSite`'s own find-or-create of a Postgres database for the cms app,
+     * modeled on `coolifyDatabase` above: `ensureCoolifyProject` (already run
+     * by `cmsSite` before this is called) and `findOrCreateEnvironment` give
+     * the project/environment this reuses, then `listDatabases` finds one
+     * already created by name before `createPostgresDatabase` makes one.
+     * Named `<org.slug>-cms-db`, distinct from `coolifyDatabase`'s own
+     * `<org.slug>-db`, so the two never collide in the same project for an org
+     * that has both.
+     *
+     * `context.recordedIds()` is checked first, the same short-circuit
+     * `coolifyDatabase` itself does not have (that step's own `resourceId` slot
+     * already covers it) -- here it is load-bearing, since this database has
+     * no `system:kind:key` slot of its own ({@link CMS_DATABASE_SCOPE_KEY}'s
+     * doc comment) and `cms:site` runs on every apply once `org.site.enabled`,
+     * not just the first.
+     *
+     * Destroying this database is out of scope here (#117, same as #116's own
+     * destroy note for the cms/site apps).
+     */
+    private ensureCmsDatabase;
+    /**
+     * `null` once the cms app already has a `DATABASE_URL` -- never rotated,
+     * the same rule `ensureAuthCookieSecret` follows for `AUTH_COOKIE_SECRET`,
+     * and for the same kind of reason: `@wtfalch/cms`'s own
+     * `apps/host/scripts/migrate.mjs` (`ensureRuntimeRole`) creates or updates
+     * the live `cms_rt` Postgres role from exactly the username/password this
+     * method mints, once, at container boot -- overwriting `DATABASE_URL` on a
+     * later apply would leave that already-created role's real password out of
+     * sync with whatever foundry hands the app next.
+     *
+     * The password is minted with `randomBytes` (the same import
+     * `ensureAuthCookieSecret` already uses) and encoded `base64url` -- `+`/`/`
+     * swapped for `-`/`_`, no `=` padding -- so it is already URL-safe in a
+     * `postgres://` URL's userinfo segment with no further percent-encoding
+     * needed. `dbInternalUrl` (`getDatabase`'s own `internal_db_url`) is parsed
+     * with `URL` for its host, path and query string; its own superuser
+     * username and password are discarded -- this mints a distinct, restricted
+     * role's own credential, never reuses the superuser's. The query string
+     * (`search`) is kept as-is and appended unchanged (#117 review round 2):
+     * a parameter there (e.g. `?sslmode=require`) is a connection requirement
+     * Coolify itself put on this database, not something specific to the
+     * superuser role, so the migration (`DATABASE_URL_OWNER`) and runtime
+     * (`DATABASE_URL`) connections must carry the same one.
+     *
+     * The password is a live credential: built here and handed straight to
+     * `cmsSite`'s own `bulkUpsertEnvs` call and nowhere else in this class --
+     * never returned, recorded, logged, or interpolated into a thrown error
+     * (the same rule `pushDatabaseUrl`'s doc comment states). That rule is why
+     * `URL`'s own parse failure is caught below rather than left to propagate:
+     * nothing here states or controls the superuser password's alphabet
+     * (Coolify's own, unlike the `cms_rt` one minted just below it), and
+     * Node's `TypeError [ERR_INVALID_URL]` on an unescaped `/`, `#` or `?` in
+     * it carries the *whole* input -- credential included -- on its own
+     * `.input` property (never in `.message`, but still reachable by a logger
+     * that inspects the error object, not just its message). Caught and
+     * turned into "skip `DATABASE_URL` for this apply" instead: `cmsSite`
+     * still pushes `DATABASE_URL_OWNER` and its other envs, and a later apply
+     * retries this once `listEnvs` still shows no `DATABASE_URL`.
+     */
+    private ensureCmsRuntimeUrl;
+    /**
+     * `cmsSite`'s own find-by-name-then-create flow for one of its two
+     * applications -- the same shape `coolifyApp` above inlines for its own,
+     * single, application, extracted here since `cmsSite` needs it twice in
+     * one step. Both of `cmsSite`'s apps share `CMS_REPO`'s own default branch
+     * (`main`) -- there is no per-org `gitBranch`/`buildPack` for this repo
+     * the way `org.hosting` carries for the org's *own* app, since the cms
+     * site is not that app.
+     *
+     * An app found by name (rather than just created) is started back up if
+     * it is not already running or on its way there (#116 review round 3,
+     * Finding 1): parking (`cmsSite`'s own `enabled: false` branch) stops both
+     * apps without deleting them, so re-enabling finds them here, still
+     * stopped, and `ProvidersCmsReader` would otherwise keep reporting
+     * `enabled: false` forever -- the plan never converging back to on.
+     * `coolifyApp`'s own analogous gap (it never restarted a found-but-stopped
+     * app either) has since closed the same way, inline in that method (#130);
+     * this method is `cmsSite`'s only caller.
+     */
+    private findOrCreateCmsApp;
+    private cloudflareTunnel;
+    private cloudflareZone;
+    /**
+     * `plan/diff.ts`'s `planMail`: gives an org mail, moves it between modes,
+     * or parks it on the one shared Stalwart instance (`this.ports.mail`,
+     * `@wtfalch/email/postmaster`'s `applyOrgMail`/`parkOrgMail` bound), then
+     * publishes whatever DNS records the call returns.
+     */
+    private coolifyMail;
+    /**
+     * Upserts each DNS record `applyOrgMail` says foundry must publish, found
+     * by an exact name+type match (`CloudflarePort.findDnsRecord`'s own doc
+     * comment) so update never mistakes a stale record of a different type for
+     * a match. A `DKIM` record can be absent on the first call, since Stalwart
+     * mints the key on a background task; the next apply publishes it.
+     */
+    private publishMailDnsRecords;
+    /**
+     * #80: provisions the org's own organisation on Files, before
+     * {@link filesStorage} can set its spend limit. `provisionOrganisation` is
+     * safely repeatable on its own (`FilesOrganisationPort`'s doc comment), so
+     * this is called every time regardless of whether it already ran --
+     * idempotent by find-or-create, not by checking `recordedIds` first.
+     */
+    private filesOrganisation;
+    private filesStorage;
+    /**
+     * #80: provisions the org's own organisation on AI and switches its AI use
+     * on, before {@link aiBudget} can set its own spend limit. Both
+     * `provisionOrganisation` and `setOrganisationOffers` are safely repeatable
+     * on their own (`AiOrganisationPort`'s doc comment), so both are called
+     * every time regardless of whether they already ran.
+     */
+    private aiOrganisation;
+    private aiBudget;
+    /**
+     * {@link StepDestroyer.destroy}: deletes the one resource
+     * `FoundryPlanApply.destroy` names. A provider 404 (already gone) counts as
+     * deleted -- `isNotFoundError` below -- since a destroy retried after a
+     * partial failure must find an already-deleted resource a no-op, not a new
+     * error.
+     */
+    destroy(target: DestroyTarget, context: {
+        readonly org: DeclaredOrg;
+        readonly recordedIds: Readonly<Record<string, string>>;
+    }): Promise<void>;
+}