@wtfalch/foundry 0.2.0 → 0.4.0

package/dist/plan/executor.d.ts

@@ -1,4 +1,6 @@
+import type { OrgMailOptions, OrgMailOrg, OrgMailResult } from '@wtfalch/email/postmaster';
 import type { DeclaredOrg, HostingBuildPack, OrgId } from '../org.js';
+import type { DeclaredOrgStore } from '../store.js';
 import type { StepAction } from './diff.js';
 import type { DestroyTarget, StepDestroyer, StepExecutionContext, StepExecutor } from './plan-apply.js';
 /**
@@ -68,6 +70,17 @@ export interface CoolifyPort {
     }): 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;
@@ -79,6 +92,8 @@ export interface CoolifyPort {
         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;
     }>;
@@ -90,6 +105,7 @@ export interface CoolifyPort {
         name: string;
         postgres_db: string;
         postgres_user: string;
+        postgres_initdb_args?: string;
     }): Promise<{
         uuid: string;
         internal_db_url: string;
@@ -99,7 +115,8 @@ export interface CoolifyPort {
      * 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). `internal_db_url` is `postgres://user:password@host/db` — a
+     * 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).
@@ -122,10 +139,12 @@ export interface CoolifyPort {
     /**
      * 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). The 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`.
+     * (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;
@@ -134,12 +153,122 @@ export interface CoolifyPort {
         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>;
+    /**
+     * An application that runs a published image as-is (#128, `coolifyCalls`'s
+     * own Postgres) — matches `@wtfalch/providers`' `CoolifyClient.
+     * createDockerImageApplication` method-for-method.
+     */
+    createDockerImageApplication(input: {
+        project_uuid: string;
+        server_uuid: string;
+        environment_name: string;
+        environment_uuid: string;
+        docker_registry_image_name: string;
+        docker_registry_image_tag: string;
+        ports_exposes: string;
+        name?: string;
+        description?: string;
+        instant_deploy?: boolean;
+    }): Promise<{
+        uuid: string;
+    }>;
+    /**
+     * An application built from an inline Dockerfile (#128, `coolifyCalls`'s own
+     * Synapse and MAS — neither's published image takes the module/command this
+     * stack needs from a plain image application) — matches `CoolifyClient.
+     * createDockerfileApplication` method-for-method.
+     */
+    createDockerfileApplication(input: {
+        project_uuid: string;
+        server_uuid: string;
+        environment_name: string;
+        environment_uuid: string;
+        dockerfile: string;
+        name?: string;
+        description?: string;
+        instant_deploy?: boolean;
+    }): Promise<{
+        uuid: string;
+    }>;
+    /**
+     * A single file mounted into the container (#128) — how `homeserver.yaml`
+     * and MAS's `config.yaml` reach a Docker-image application with no git
+     * repository of its own to carry them. Matches `CoolifyClient.
+     * createFileStorage` method-for-method.
+     */
+    createFileStorage(applicationUuid: string, input: {
+        mount_path: string;
+        content: string;
+    }): Promise<unknown>;
+    /** Updates an existing file storage's content in place. Matches `CoolifyClient.updateFileStorage`. */
+    updateFileStorage(applicationUuid: string, storageUuid: string, content: string): Promise<unknown>;
+    /**
+     * A generic application PATCH (#128) — `coolifyCalls` uses this to give
+     * Postgres/Synapse/MAS a fixed `custom_internal_name` so the other two can
+     * address each other by a name that never changes across a re-run, instead
+     * of guessing at Coolify's own container-naming scheme. Matches
+     * `CoolifyClient.updateApplication` method-for-method.
+     */
+    updateApplication(uuid: string, patch: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Queues a deployment (#128) — `coolifyCalls` calls this after writing a
+     * fresh Synapse/MAS config file, since a file-storage write alone does not
+     * reach the running container until its next deploy (issue #128's "a
+     * running app is redeployed when its config changed"). Fire-and-forget,
+     * like `restart` above: this executor does not poll a deployment to
+     * completion anywhere else, and `coolifyCalls` only calls this when the
+     * config it just wrote was actually freshly minted. Matches `CoolifyClient.
+     * deploy` method-for-method.
+     */
+    deploy(uuid: string, force?: boolean): Promise<unknown>;
 }
 /**
  * The Cloudflare calls this executor makes, shaped to match
@@ -165,6 +294,31 @@ export interface CloudflarePort {
     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,
@@ -174,6 +328,154 @@ export interface CloudflarePort {
      * 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>;
+}
+/**
+ * One DNS record a Resend domain's own response names it must publish --
+ * `record` is Resend's own label (`SPF`, `DKIM`, `DMARC`, `MX`), which
+ * {@link ResendPort.createDomain}/{@link ResendPort.getDomain} return
+ * alongside `type`/`name`/`value` for `coolifyMail` to act on, the same shape
+ * https://resend.com/docs/api-reference/domains/create-domain documents.
+ */
+export interface ResendDnsRecordSpec {
+    readonly record: 'SPF' | 'DKIM' | 'DMARC' | 'MX' | string;
+    readonly name: string;
+    readonly type: 'TXT' | 'CNAME' | 'MX';
+    readonly value: string;
+    readonly priority?: number;
+}
+export interface ResendDomain {
+    readonly id: string;
+    readonly name: string;
+    readonly status: string;
+    readonly records?: readonly ResendDnsRecordSpec[];
+}
+/**
+ * The Resend calls this executor makes to verify an org's mail domain (#138)
+ * and mint its app's sending key (#140 rework) -- the shared Stalwart relays
+ * every outbound message through Resend
+ * (https://github.com/wtfalch/email/blob/main/packages/email/src/postmaster/objects.ts#L149-L168),
+ * which refuses mail from a domain Resend has not verified. `@wtfalch/providers`
+ * has no Resend client yet, unlike Coolify/Cloudflare/ZITADEL above, so this
+ * port names Resend's own REST shapes directly
+ * (https://resend.com/docs/api-reference/domains/create-domain,
+ * https://resend.com/docs/api-reference/api-keys/create-api-key,
+ * https://resend.com/docs/api-reference/api-keys/list-api-keys,
+ * https://resend.com/docs/api-reference/api-keys/delete-api-key) -- the same
+ * prior art `wtfalch/app-template`'s `bootstrap/steps/resend-email.ts` already
+ * proved against a live account. The relay's own `<slug>-relay` key
+ * (`.plans/2026-09-27-org-mail-resend-design.md`) is a separate change, filed
+ * as https://github.com/wtfalch/foundry/issues/149 and out of scope here.
+ */
+export interface ResendPort {
+    /** An exact name match, never a listing scan `coolifyMail` has to page itself. */
+    findDomain(name: string): Promise<{
+        id: string;
+        name: string;
+        status: string;
+    } | undefined>;
+    createDomain(name: string): Promise<ResendDomain>;
+    /** Re-reads a domain already found by {@link findDomain}, for its current status and DNS records. */
+    getDomain(id: string): Promise<ResendDomain>;
+    /**
+     * Asks Resend to re-check DNS now. `coolifyMail` never polls or waits on
+     * this -- the task brief: "do not block the plan on DNS propagation:
+     * record the status, and let the next apply re-check it (idempotent, like
+     * `applyOrgMail`)".
+     */
+    verifyDomain(id: string): Promise<{
+        status: string;
+    }>;
+    /**
+     * Every key in the account, `id`+`name` only -- Resend never returns a
+     * key's token except at creation, so this is how the mint rule
+     * (`.plans/2026-09-27-org-mail-resend-design.md` "One rule for minting")
+     * tells whether the app's key is healthy before deciding to mint. `ensureAppResendKey`'s own doc comment below
+     * spells the rule out.
+     */
+    listApiKeys(): Promise<Array<{
+        id: string;
+        name: string;
+    }>>;
+    /** Sending-only, scoped to one domain -- the app step's `<slug>-app@<domainId>` (`ensureAppResendKey`), minted under the mint rule. */
+    createApiKey(input: {
+        name: string;
+        permission: 'sending_access';
+        domainId: string;
+    }): Promise<{
+        id: string;
+        token: string;
+    }>;
+    /** Deletes one key by id -- the mint rule's own cleanup of an orphan, a duplicate, or a key for a mail domain the org no longer uses. */
+    deleteApiKey(id: string): Promise<void>;
+}
+/**
+ * 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 shared calls SFU's own LiveKit API credentials (#122, #127), resolved
+ * by the host from wherever `scripts/calls-sfu-deploy.mjs`'s own
+ * `CallsSfuConfig` delivered them (#145) -- this package never mints or
+ * invents a LiveKit key/secret pair itself, the same "the executor is
+ * constructed with narrow ports ... a host [archon] supplies real clients"
+ * rule this file's own top doc comment states for every provider credential.
+ * `resolveCredentials` returns `null` when the SFU has not been configured
+ * yet, the same "nothing recorded" signal a bare `CoolifyPort.listEnvs` gives
+ * `ensureCallsMatrixSecrets` -- just for a secret this package never held in
+ * the first place, so there is nowhere here to read it back from itself.
+ */
+export interface CallsSfuPort {
+    resolveCredentials(): Promise<{
+        apiKey: string;
+        apiSecret: string;
+    } | null>;
 }
 /**
  * The ZITADEL calls this executor makes. `findOrCreateOrg`/`findOrCreateProject`
@@ -224,6 +526,23 @@ export interface ZitadelPort {
         clientSecret: string;
     }>;
     deleteApp(orgId: string, projectId: string, appId: string): Promise<void>;
+    /**
+     * `zitadelApp`'s kind-change path reads this to find an app a prior,
+     * lost-response create already made under the new name, before calling
+     * `createOidcApp`/`createApiApp` again and orphaning that one under the
+     * same name. Matches `@wtfalch/providers/zitadel`'s `ZitadelClient.
+     * listApps` return shape exactly, so that client satisfies this port with
+     * no adapter -- it does not carry `clientId`/`clientSecret` (that provider
+     * method never parses either, and a secret is minted once, on creation,
+     * never handed back again), which is why the reuse path below cannot
+     * re-deliver either one.
+     */
+    listApps(orgId: string, projectId: string): Promise<Array<{
+        id: string;
+        name: string;
+        appType: 'web' | 'native' | 'api';
+        state: string;
+    }>>;
     /**
      * 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.
@@ -350,6 +669,10 @@ export interface FoundryStepExecutorPorts {
     coolify: CoolifyPort;
     cloudflare: CloudflarePort;
     zitadel: ZitadelPort;
+    mail: MailPort;
+    resend: ResendPort;
+    /** The shared calls SFU's own LiveKit credentials (#145) -- see {@link CallsSfuPort}'s own doc comment. */
+    callsSfu: CallsSfuPort;
     /** 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;
@@ -370,28 +693,69 @@ export interface FoundryStepExecutorPorts {
      * themselves.
      */
     deliverSecret(ref: string, secret: string): Promise<void>;
+    /**
+     * Read access to the declared-org store, narrowed to the one query
+     * `cloudflareZone` needs for its cross-org refusal check (#131) -- see that
+     * method's own doc comment for why a zone needs this where
+     * `cloudflareAccess` reads Cloudflare's own live state instead. A real host
+     * passes the same store instance it constructs `FoundryPlanApply` with.
+     */
+    declaredOrgStore: Pick<DeclaredOrgStore, 'findOrgIdForZone'>;
 }
 /**
  * Thrown by name for a step this executor deliberately does not implement:
- * mail and chat (no admin API exists yet in either service) and the cms
- * site (same), 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").
+ * 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);
 }
-/** `coolify:app` needs source code to build from; `DeclaredOrg.bespokeAppRepo` is the only source this executor knows (#71, #20). */
-export declare class MissingBespokeAppRepoError extends Error {
-    constructor(slug: 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
@@ -412,10 +776,42 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      */
     private zitadelCustomers;
     private zitadelApp;
+    /**
+     * The app an earlier attempt's recreate already made under the same
+     * name, whose response this executor never saw -- deleted before the
+     * create so no duplicate is left behind. Matches on name and the
+     * desired kind, and skips a removed app -- ZITADEL's
+     * search can return one that has since been deleted (`isNotFoundError`'s
+     * own doc comment covers why a delete can be retried into a 404), and
+     * that is not the survivor this is looking for.
+     */
+    private findRecreatedApp;
     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
@@ -440,8 +836,349 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * 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;
+    /**
+     * #140 rework: the hosted app's own Resend sending key, pushed as
+     * `RESEND_API_KEY` straight into the app's env, the one place its token
+     * ever lives (Resend shows a key's token once, at creation). A no-op until
+     * `coolify:mail` has recorded a {@link RESEND_DOMAIN_ID_SCOPE_KEY} for this
+     * org; the next apply fills it in once `coolify:mail` runs first
+     * (`diff.ts`'s `computePlanDetail` order).
+     *
+     * The key is named `<slug>-app@<resendDomainId>`, so a key limited to a
+     * mail domain the org no longer uses (a `usesDomain` flip moves it between
+     * `org.domain` and `<slug>.<apex>`) never passes for the current one.
+     * `RESEND_API_KEY_ID` sits beside the token in the env -- an id, not a
+     * secret -- so the env can say which key its token belongs to.
+     *
+     * The mint rule (`.plans/2026-09-27-org-mail-resend-design.md` "One rule
+     * for minting"): healthy when the env holds a token and its
+     * `RESEND_API_KEY_ID` is the one key Resend lists under the current name.
+     * Otherwise one fresh key is minted and written to the env first, and only
+     * then is every other `<slug>-app@` key deleted -- a lost mint response, a
+     * duplicate, a hand-made key, and a previous domain's key all end the same
+     * way. An app that was already running is restarted before that delete,
+     * since a container reads its env only at start (`running`, the same
+     * reason {@link ensureLogVolume} restarts one). The restart is not
+     * awaited to completion, so the old container can briefly outlive its key.
+     *
+     * `MAIL_FROM` is upserted every time: it depends only on the mail domain
+     * `coolify:mail` resolved (`RESEND_MAIL_DOMAIN_SCOPE_KEY`).
+     *
+     * The token goes straight to `bulkUpsertEnvs` and nowhere else: never
+     * returned, never recorded in `serviceIds` (`recordScopeId`'s own doc
+     * comment), never logged, never interpolated into a thrown error -- the
+     * same discipline `pushDatabaseUrl`'s doc comment states for a database's
+     * own connection string.
+     */
+    private ensureAppResendKey;
+    /**
+     * `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;
+    /**
+     * `plan/diff.ts`'s `planCalls`: the org's own calls Matrix stack, entirely
+     * separate from chat's (`calls-matrix.ts`'s own top doc comment) -- two
+     * Coolify-managed Postgres databases, a Synapse app and an MAS app, no
+     * public hostname of its own (neither app is reachable from outside
+     * Coolify's own Docker network) -- `coolifyCallsService` below (#145, part 2
+     * of #128) is the one that gets a public hostname, since it is the one a
+     * browser actually talks to. Park stops Synapse and MAS only, the same
+     * park-not-delete rule `coolifyApp`/`cmsSite` already follow (#7
+     * corrections 1) -- their databases are never touched from that branch, the
+     * same way `cmsSite`'s own database never is.
+     */
+    private coolifyCalls;
+    /**
+     * `coolifyCalls`'s own find-or-create for Synapse/MAS, restarting a
+     * found-but-stopped app (#116 review round 3, Finding 1's same fix). Reused
+     * by `coolifyCallsService` (#145) for the calls service app itself -- the
+     * same find-by-name-then-start-or-create shape applies unchanged.
+     */
+    private findOrCreateCallsApp;
+    /**
+     * `coolifyCalls`'s own database find-or-create, modeled on
+     * `ensureCmsDatabase`: `context.recordedIds()` is checked first since
+     * neither database has a `system:kind:key` slot of its own (this step's one
+     * auto-recorded `resourceId` is the MAS app, not either database --
+     * {@link CALLS_SYNAPSE_SCOPE_KEY}'s own doc comment), then `listDatabases`
+     * finds one already created by name before `createPostgresDatabase` makes
+     * one. Reused by `coolifyCallsService` (#145) for the calls service's own
+     * database, whose {@link CALLS_SERVICE_DB_SCOPE_KEY} has no
+     * `system:kind:key` slot of its own for the same reason.
+     */
+    private ensureCallsDatabase;
+    /**
+     * Reads back {@link CALLS_SECRET_ENV_KEYS} from the MAS app's own envs
+     * before minting fresh ones -- this stack's only memory across a re-run
+     * (`calls-matrix.ts`'s `CallsMatrixSecrets` doc comment). `changed: true`
+     * only when nothing usable was found: a partial set (a crash mid-mint) is
+     * still treated as "mint fresh", since MAS's shared secret and Synapse's
+     * copy of it must always agree.
+     */
+    private ensureCallsMatrixSecrets;
+    /**
+     * Upserts a file storage's content, creating it if the application has none
+     * at that mount path yet -- there is no way to read a file storage's
+     * current content back from Coolify to diff it, the same limit
+     * `archon/bootstrap/steps/chat-instance.ts`'s own `ensureFileStorage` notes,
+     * so an existing one is always re-written.
+     */
+    private ensureCallsFileStorage;
+    /**
+     * `plan/diff.ts`'s `planCallsService`: the org's own calls service --
+     * `wtfalch/calls`'s `packages/service`, wired to the calls Matrix stack
+     * {@link coolifyCalls} provisions and the shared LiveKit SFU (#122/#127).
+     * Static config checks run first, before any Coolify call (#128's own
+     * carried-over PR 344 review fix, restated in #145's own issue body): the
+     * calls Matrix stack must already be recorded, its MAS app must already
+     * carry its client id/secret, and the shared SFU's LiveKit credentials must
+     * already be resolvable -- none of the three is minted or guessed here.
+     * Park stops the app only, the same park-not-delete rule
+     * {@link coolifyCalls}/{@link coolifyApp} already follow (#7 corrections
+     * 1); its own database is never touched from that branch.
+     */
+    private coolifyCallsService;
+    /**
+     * Reads back the calls Matrix stack's MAS client id/secret from the MAS
+     * app's own envs ({@link CALLS_SECRET_ENV_KEYS}) -- never mints: minting
+     * either is {@link ensureCallsMatrixSecrets}'s own job, and a missing value
+     * here means that stack has not finished provisioning yet, not something
+     * this step can fix on its own.
+     */
+    private readCallsMasClientCredentials;
+    /**
+     * `null` once the calls service app already has a `CALLS_BINDING_SECRET` --
+     * never rotated, the same rule {@link ensureAuthCookieSecret} follows for
+     * `AUTH_COOKIE_SECRET`: it wraps the provider-token ciphertext already
+     * stored under any binding minted so far
+     * (`calls/packages/service/src/config.mjs`'s own doc comment on
+     * `CALLS_BINDING_SECRET`), so overwriting it would strand every binding
+     * minted under the old value. 32 raw bytes, hex-encoded -- the exact shape
+     * `config.mjs`'s own regex requires.
+     */
+    private ensureCallsBindingSecret;
     private cloudflareTunnel;
+    /**
+     * `plan/diff.ts`'s `planZone`: finds or creates the Cloudflare zone for the
+     * org's own domain. Refuses to adopt a zone the store already records
+     * under a *different* org's applied state (#131), the same
+     * do-not-adopt-a-foreign-resource rule `cloudflareAccess` above enforces --
+     * but where that method tells "foundry's own" from "foreign" by reading
+     * Cloudflare's own Access-app name live, a Cloudflare zone carries no
+     * org-identifying field of its own, so this asks the store instead. That
+     * matters because two different, DB-unique `domain` values (`org.ts`'s
+     * `validateDomain` plus its unique index) can still resolve to the same
+     * Cloudflare zone -- a zone is keyed by apex, and one org's domain can be a
+     * subdomain of another org's -- which is exactly the shared-zone,
+     * shared-hostname collision this ticket exists to refuse. An org re-running
+     * its own already-recorded zone is unaffected: the store then names this
+     * same org as the owner.
+     */
     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, then registers the same
+     * mail domain with Resend (#138) -- the shared Stalwart relays every
+     * outbound message through Resend, and Resend refuses mail from a domain
+     * it has not verified. No step here ever deletes the app's Resend key:
+     * `diff.ts`'s `planMail` plans nothing for mode `'off'`, so turning mail
+     * off leaves the key live, like every other resource foundry stops
+     * managing (#10). Switching the mail domain replaces the key instead
+     * (`ensureAppResendKey`).
+     */
+    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. Returns
+     * the zone id so `registerResendDomain` publishes Resend's own records on
+     * the same zone without a second lookup.
+     */
+    private publishMailDnsRecords;
+    /**
+     * #138: registers `domain` with Resend -- the custom domain, or
+     * `<slug>.<apex>` for a level-1 org, exactly what `publishMailDnsRecords`
+     * just published the Stalwart records for. Idempotent by name, the same way
+     * `applyOrgMail` itself is: found by `findDomain` rather than any id this
+     * class recorded, so a crash between here and the next apply just repeats
+     * the same find-or-create. Never blocks on DNS propagation (task brief):
+     * `verifyDomain` asks Resend to re-check once, and its returned status is
+     * neither polled nor awaited -- an unverified domain here is exactly what
+     * the next apply corrects.
+     *
+     * #140 rework: mints no key of its own any more. It records the domain's
+     * own id and the resolved mail domain as scope ids so `ensureAppResendKey`
+     * (`coolifyApp`) can mint the app's own `<slug>-app@<domainId>` key once the app
+     * exists, without this step or the app step calling Resend to look the
+     * domain back up.
+     */
+    private registerResendDomain;
+    /**
+     * Upserts each DNS record Resend's domain names, the same find-then-upsert
+     * `publishMailDnsRecords` above uses for Stalwart's own records -- except
+     * SPF is merged into whatever record that call just published rather than
+     * created a second time (RFC 7208 treats two `v=spf1` TXT records on one
+     * name as a permerror and silently breaks SPF for every sender on the
+     * domain), and an existing `_dmarc` record is never overwritten. Prior art:
+     * `wtfalch/app-template`'s `bootstrap/steps/resend-email.ts`.
+     */
+    private publishResendDnsRecords;
+    /**
+     * Inserts Resend's `include:` token into whatever SPF record
+     * `publishMailDnsRecords` already published for this name, instead of
+     * creating a second `v=spf1` TXT record -- the classic foot-gun that makes
+     * every receiver treat SPF as a permerror and skip it entirely.
+     */
+    private mergeResendSpfRecord;
+    /**
+     * Never overwrites an existing `_dmarc` record -- a stricter policy an org
+     * already set (`p=quarantine`/`p=reject`) should not be relaxed back to
+     * Resend's own `p=none` default.
+     */
+    private ensureResendDmarcRecord;
     /**
      * #80: provisions the org's own organisation on Files, before
      * {@link filesStorage} can set its spend limit. `provisionOrganisation` is