@wtfalch/foundry 0.4.0 → 0.6.0

package/dist/plan/platform-diff.js

@@ -0,0 +1,1220 @@
+/**
+ * The `Plan` (#19's public contract) a {@link PlatformPlanDetail} carries,
+ * mirroring `diff.ts`'s `toPlan`. There is no separate platform-shaped `Plan`
+ * type: `orgId` is stamped with the platform's own `ownerOrgId` -- Company
+ * Included's own {@link OrgId}, the org whose money and access the platform's
+ * resources are billed and owned by (`platform.ts`'s `DeclaredPlatform.ownerOrgId`
+ * doc comment) -- so `AuditLog`/`AuthzGate` (`plan-apply.ts`), both keyed by
+ * `OrgId`, need no platform-specific shape of their own either.
+ */
+export function toPlatformPlan(detail, ownerOrgId) {
+    return {
+        orgId: ownerOrgId,
+        steps: detail.plannedSteps.map((p) => p.step),
+        unmanaged: detail.unmanaged,
+    };
+}
+function resourceKey(system, kind, key) {
+    return `${system}:${kind}:${key}`;
+}
+/**
+ * #168: the resource key `planAuth` plans under and `FoundryPlatformStepExecutor`
+ * (`platform-providers.ts`) dispatches on -- `platform:<service>`, exactly the
+ * shape `planPlatform`'s own doc comment above already named as the eventual
+ * convention, so a platform service's `coolify:app` step never collides with
+ * an org's own (which is keyed by that org's id).
+ */
+export const PLATFORM_AUTH_KEY = 'platform:auth';
+/**
+ * Scope keys (colon-free, so never mistaken for a `system:kind:key` resource
+ * id) for foundry's ZITADEL admin machine user. The delivered key is the guard
+ * that skips the mint, recorded only once the token reached the host. The
+ * undelivered key is recorded first, the moment the user is minted: an id
+ * under it with no delivered key means the one-time token was lost, and the
+ * planner reports that instead of minting again.
+ */
+/**
+ * #175: the resource key `planArchon` plans under and
+ * `FoundryPlatformStepExecutor` (`platform-providers.ts`) dispatches on --
+ * the same `platform:<service>` shape as {@link PLATFORM_AUTH_KEY}.
+ */
+export const PLATFORM_ARCHON_KEY = 'platform:archon';
+/**
+ * #175: the hostname and `gitRef` the last successful Archon run applied.
+ * `planArchon` plans the step again when either differs from the declared
+ * value; a re-run patches `git_branch`, `APP_URL` and the sign-in client and
+ * redeploys, and mints nothing.
+ */
+export const PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY = 'archon_applied_hostname';
+export const PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY = 'archon_applied_git_ref';
+/**
+ * #211 round 4: the broker app id Archon last registered its entry with.
+ * `provisionPlatformArchon` reads the broker to register with from
+ * {@link PLATFORM_AUTH_BROKER_SCOPE_KEY} alone, so a broker recreated under a
+ * new app id (the old one deleted by hand, or `platform:auth` minting a fresh
+ * one) leaves Archon "applied" against a broker that no longer holds its
+ * entry. `planArchon` plans the step again whenever this differs from the
+ * currently recorded {@link PLATFORM_AUTH_BROKER_SCOPE_KEY}, the same way a
+ * changed hostname or `gitRef` does.
+ */
+export const PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY = 'archon_applied_broker_app';
+/**
+ * #175: set to '1' before the step points the tunnel at `http_status:404`
+ * (Access app rebuild), cleared to '' once the real ingress is written back.
+ * While it is non-empty `planArchon` plans the step, so a run that failed in
+ * between is repaired by the next one.
+ */
+export const PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY = 'archon_gate_closed';
+export const PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY = 'zitadel_platform_admin_user_id';
+export const PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY = 'zitadel_platform_admin_user_undelivered';
+/**
+ * #216 (building on #209/#215): the `IAM_LOGIN_CLIENT` machine user minted
+ * for the login app and the broker, mirroring
+ * {@link PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY}/
+ * {@link PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY} in shape -- a recorded
+ * id once delivered, an undelivered id recorded first, the moment the user
+ * is minted.
+ *
+ * Unlike the admin pair, an undelivered login-client key never blocks
+ * {@link planAuth} from planning the step again -- #216 round 2: `planAuth`
+ * below does read it, but only to surface a non-blocking note (alongside a
+ * planned step, the way #211 round 3's broker-deploy block already is)
+ * rather than to hold the step back. Revoking a stale login-client PAT
+ * destroys nothing -- unlike the admin user's, whose loss the admin pair's
+ * own "delete that user by hand" message exists for because nothing else
+ * here re-derives the ZITADEL masterkey a lost admin PAT might have been the
+ * only record of -- so `mintLoginClientMachineUser` (`zitadel-machine-user.ts`)
+ * always lists and deletes every PAT the user already holds before minting a
+ * fresh one. That is what lets `provisionPlatformAuth` simply re-mint on the
+ * next run, with no manual step, which is #216's whole fix for the bug PR
+ * #215 shipped with: PR #215 mirrored the admin pair's forever-blocking
+ * behaviour for this key too, which meant one failed Coolify call lost the
+ * login-client token for good.
+ *
+ * #216 round 4: the value recorded here is JSON ({@link
+ * PlatformAuthLoginClientRecord}, parsed back by
+ * {@link parseLoginClientRecord}), not the bare user id round 2-3 wrote --
+ * the user id alone can never tell a healthy delivery from one a concurrent
+ * apply has since clobbered, because `mintLoginClientMachineUser` reuses the
+ * same user on every mint. The PAT id travels alongside it so {@link
+ * planAuth} can ask ZITADEL, on every plan, whether that exact PAT is still
+ * the sole live one.
+ *
+ * #216 round 5: that alone is still not enough -- a recorded PAT can be the
+ * sole live one in ZITADEL while Coolify holds a *different*, already-dead
+ * token, when two concurrent applies interleave their own writes and
+ * records in the right (wrong) order (see `authLoginClientDrifted`'s own
+ * doc comment in `platform-providers.ts` for the exact ordering). So the
+ * record also carries `tokenHash`, a sha256 of the exact token that was
+ * delivered -- never the token itself -- which `authLoginClientDrifted`
+ * compares against what is actually live in both apps' Coolify envs.
+ */
+export const PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY = 'zitadel_platform_login_client_user_id';
+export const PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY = 'zitadel_platform_login_client_user_undelivered';
+/**
+ * Parses a {@link PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY} scope id back
+ * into a {@link PlatformAuthLoginClientRecord}. `null` for anything that is
+ * not one -- absent, the pre-round-4 plain user-id string, the round 2-4
+ * `{userId, patId}` shape with no `tokenHash`, or corrupt JSON -- the same
+ * "malformed reads as unapplied, never throws" rule
+ * {@link parseBrokerDeployRecord} follows and for the same reason: this is a
+ * planning read, not a validation boundary. A pre-round-5 record reading as
+ * unapplied is the intended migration: the next apply's fresh mint recomputes
+ * it in the new shape, the same way a pre-round-4 plain-string record already
+ * did.
+ */
+export function parseLoginClientRecord(raw) {
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    const candidate = parsed;
+    if (typeof candidate.userId !== 'string' || !candidate.userId)
+        return null;
+    if (typeof candidate.patId !== 'string' || !candidate.patId)
+        return null;
+    if (typeof candidate.tokenHash !== 'string' || !candidate.tokenHash)
+        return null;
+    return { userId: candidate.userId, patId: candidate.patId, tokenHash: candidate.tokenHash };
+}
+/**
+ * #204/#211: the sign-in broker app `provisionPlatformAuth` creates alongside
+ * ZITADEL and the login app. Defined here, not in `platform-providers.ts`
+ * (which imports it), because `planAuth` below needs it too -- a recorded
+ * `coolify:app:platform:auth` key with no recorded broker id is a platform
+ * provisioned before #204 shipped, and must still plan the step again so the
+ * broker gets created rather than being read as fully applied.
+ */
+export const PLATFORM_AUTH_BROKER_SCOPE_KEY = 'coolify_platform_auth_broker_app';
+/**
+ * #211: recorded once the broker has actually been deployed -- distinct from
+ * {@link PLATFORM_AUTH_BROKER_SCOPE_KEY} (the app exists) precisely because
+ * the app can exist for a while before it is ever deployed (see
+ * `missingBrokerInputs` in `platform-providers.ts`). Defined here, not there,
+ * for the same reason as {@link PLATFORM_AUTH_BROKER_SCOPE_KEY}: `planAuth`
+ * below needs it too, so a broker that is created but not yet deployed still
+ * plans the step again instead of reading as fully applied for good.
+ */
+export const PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY = 'coolify_platform_auth_broker_deployed';
+/**
+ * Parses a {@link PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY} scope id back into
+ * a {@link BrokerDeployRecord}. `null` for anything that is not one --
+ * absent, the pre-round-5 plain broker-id string, or corrupt JSON -- because
+ * this is a planning read, not a validation boundary: a malformed record
+ * must read as "not deployed" so the step plans (and overwrites it) again,
+ * never throw and take the rest of the plan down with it. Exported here
+ * rather than defined in `platform-providers.ts` for the same reason
+ * {@link PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY} itself was moved here in
+ * round 2 -- {@link planAuth} below needs it too, without a circular import.
+ */
+export function parseBrokerDeployRecord(raw) {
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    const candidate = parsed;
+    if (typeof candidate.brokerAppId !== 'string' || !candidate.brokerAppId)
+        return null;
+    if (typeof candidate.authAppsHash !== 'string' || !candidate.authAppsHash)
+        return null;
+    return { brokerAppId: candidate.brokerAppId, authAppsHash: candidate.authAppsHash };
+}
+/**
+ * #197: the `cloudflared` connector app `provisionPlatformAuth` runs for its
+ * own tunnel. Consulted by `planAuth` below so that a tunnel recorded with no
+ * connector recorded is not treated as fully applied -- the same rule that
+ * lets an instance provisioned before #197 shipped pick up a connector on its
+ * next apply, without minting anything again.
+ */
+export const PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY = 'coolify_platform_auth_connector_app';
+/** #197: the same connector scope id for the mail step's own tunnel, read by `planMail`. */
+export const PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY = 'coolify_platform_mail_connector_app';
+/** #197: the same connector scope id for the Archon step's own tunnel, read by `planArchon`. */
+export const PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY = 'coolify_platform_archon_connector_app';
+/**
+ * #213: the three held-key refs, under tenant `platform`, Archon's own
+ * onboarding reads before it can start (archon#101 round 3, archon#104).
+ * `planArchon`'s step puts each one, once, before Archon's app deploys; an
+ * entry already held is left alone, never overwritten
+ * (`putArchonMasterKeys` in `platform-providers.ts`). The Coolify URL and
+ * token are values this package already deploys with; the Cloudflare
+ * parent token ("API Tokens Write", so Archon can mint its own scoped
+ * child tokens from it) is a human-created credential the host supplies --
+ * neither Coolify nor Cloudflare lets either be minted over an API (#213
+ * "Human steps").
+ */
+export const PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF = 'platform:master:coolify-url';
+export const PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF = 'platform:master:coolify-token';
+export const PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF = 'platform:master:cloudflare-token';
+/**
+ * #169: `platform:<service>` for the platform's own mail server (Stalwart),
+ * mirroring {@link PLATFORM_AUTH_KEY} exactly.
+ */
+export const PLATFORM_MAIL_KEY = 'platform:mail';
+/**
+ * Scope keys for Stalwart's admin API key, mirroring
+ * {@link PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY}/{@link PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY}
+ * -- except `createApiKey` (`@wtfalch/email/postmaster`'s `StalwartClient`)
+ * returns only the minted secret, never an id, so there is no id to record
+ * the way ZITADEL's `userId` is. `PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION`
+ * (`platform-providers.ts`) is recorded instead -- the fixed description the
+ * key is minted under, which is what a human revokes it by in Stalwart's own
+ * admin UI once it is lost.
+ */
+export const PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY = 'stalwart_platform_admin_key_delivered';
+export const PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY = 'stalwart_platform_admin_key_undelivered';
+/**
+ * #169: the hostname and `gitRef` (the Stalwart image tag) the last successful
+ * mail run applied. `planMail` plans the step again when either differs from
+ * the declared value; a re-run patches the image tag and
+ * `STALWART_PUBLIC_URL`, redeploys, and mints nothing.
+ */
+export const PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY = 'mail_applied_hostname';
+export const PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY = 'mail_applied_git_ref';
+/**
+ * #177: where the mail server answers on the Coolify network
+ * (`http://<custom_internal_name>:<port>`), recorded by the step the same way
+ * {@link PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY}/{@link PLATFORM_AI_INTERNAL_URL_SCOPE_KEY}
+ * already are -- what an org's own `coolify:mail`/`coolify:agora` steps read
+ * for `AGORA_MAIL_UPSTREAM` (`platform-org.ts`'s `agoraHostValuesFromPlatform`)
+ * instead of a literal a host used to have to supply. Not a secret: Stalwart's
+ * own internal address, never its admin credential.
+ */
+export const PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY = 'mail_internal_url';
+/**
+ * #177: the one host the platform's mail server takes SMTP/MX on, and so the
+ * `mailHost` every org's own mail step writes. `provisionPlatformMail` (the
+ * DNS record and the server) and `platform-org.ts` (each org's mail step)
+ * both call this, so the two cannot name different hosts. Not
+ * `platform.mail.hostname`, which is the web (JMAP/admin) host.
+ */
+export function platformMailMxHost(apex) {
+    return `mx.${apex}`;
+}
+/**
+ * #177: the platform apex and mail host an org's `coolify:mail` step last
+ * wrote, recorded in that org's applied state. `diff.ts`'s `planMail` plans
+ * the step again when either differs from the platform's current values, so a
+ * later platform address change reaches orgs that are already applied.
+ */
+export const ORG_MAIL_APPLIED_APEX_SCOPE_KEY = 'mail_applied_apex';
+export const ORG_MAIL_APPLIED_HOST_SCOPE_KEY = 'mail_applied_host';
+/**
+ * #172: the resource key `planAi` plans under and `FoundryPlatformStepExecutor`
+ * dispatches on, the same `platform:<service>` shape as
+ * {@link PLATFORM_AUTH_KEY}. The step's own recorded resource id (the ai
+ * host's runner app) lands at `coolify:app:platform:ai`.
+ */
+export const PLATFORM_AI_KEY = 'platform:ai';
+/**
+ * #172: where the ai host answers on the Coolify network
+ * (`http://<custom_internal_name>:<port>`), recorded by the step so a host
+ * building `AiOrganisationPort` (`executor.ts`) can reach it without a
+ * public hostname. Holds whichever way the public-hostname decision goes.
+ */
+export const PLATFORM_AI_INTERNAL_URL_SCOPE_KEY = 'ai_platform_internal_url';
+/**
+ * #172: the same two-key discipline as the ZITADEL admin key above, for
+ * foundry's AI management key (the bearer key `ai:organisation`, `ai:budget`
+ * and `ai:key` use). The undelivered key holds the credential id the moment
+ * it is minted; the delivered key is recorded only once the secret reached
+ * the host, and is what skips the mint on a later run.
+ */
+export const PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY = 'ai_platform_management_key_id';
+export const PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY = 'ai_platform_management_key_undelivered';
+/**
+ * #201: set when ai's `POST /v1/platform/keys` reports its `archon` key
+ * already exists but returns no secret -- a mint this record never learned
+ * about (most likely the crash window {@link PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY}'s
+ * own comment describes: the secret returned once and was never recorded).
+ * ai shows a credential's secret only at mint time, so it cannot be
+ * recovered; the planner reports this instead of minting under another
+ * name. A person revokes the live `archon` key in ai and removes this
+ * recorded key to let the step mint a fresh one.
+ */
+export const PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY = 'ai_platform_management_key_conflict';
+/**
+ * #201: the same two-key discipline as {@link PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY}
+ * and {@link PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY}, for the Ed25519 pair
+ * foundry mints to sign its calls to ai's `POST /v1/platform/keys`. The
+ * undelivered key is recorded the moment the pair is minted; the set key,
+ * only once the private half was delivered and the public half pinned on
+ * the runner as `MANAGEMENT_PUBLIC_KEYS`.
+ */
+export const PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY = 'ai_platform_signing_key_undelivered';
+export const PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY = 'ai_platform_signing_key_set';
+/**
+ * #172: ai's platform (operator) tenant id, which the management key belongs
+ * to -- what ai's own README calls `AI_ORGANISATION_ID`. Not a secret.
+ */
+export const PLATFORM_AI_ORGANISATION_SCOPE_KEY = 'ai_platform_organisation_id';
+/**
+ * #172: the hostname and gitRef the last apply finished with. A declared
+ * value that differs plans the step again (without minting again, the
+ * management key's own guard stays set).
+ */
+export const PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY = 'ai_platform_applied_hostname';
+export const PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY = 'ai_platform_applied_gitref';
+/**
+ * #172: set (with the migrate job's last status) when the migrate job did
+ * not turn healthy in time. The planner reports it as blocked and plans
+ * nothing, so an unhealthy migration is not retried and timed out on every
+ * apply. A person fixes the job and removes this recorded key.
+ */
+export const PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY = 'ai_platform_migrate_blocked';
+/**
+ * #172: set before an env or branch change is written and cleared once the
+ * deploys that carry it finished, so a run that fails halfway (a migrate
+ * that throws) is repaired by the next one.
+ */
+export const PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY = 'ai_platform_deploy_pending';
+/**
+ * #171: the resource key `planFiles` plans under and `FoundryPlatformStepExecutor`
+ * dispatches on, the {@link PLATFORM_AUTH_KEY} shape for the files host.
+ * `runPlatformSteps` records the files runner app's uuid under
+ * `coolify:app:platform:files` once the step succeeds, which is what stops
+ * `planFiles` planning it again.
+ */
+export const PLATFORM_FILES_KEY = 'platform:files';
+/**
+ * #171: scope keys (colon-free) the files step records in the applied
+ * platform.
+ *
+ * - {@link PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY}: the files host's address on
+ *   the Coolify network (`http://<custom_internal_name>:3000`), the value an
+ *   Agora's `AGORA_FILES_UPSTREAM` (and a host's `FilesOrganisationPort`
+ *   client) is read from. Not a secret. The host has no public address.
+ * - {@link PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY}: the files ZITADEL
+ *   project's id in the platform's own sign-in, which is the person-token
+ *   audience (`AUTH_PERSON_TOKEN_AUDIENCE`) an Agora requests as an extra
+ *   scope (`urn:zitadel:iam:org:project:id:<id>:aud`).
+ */
+export const PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY = 'files_internal_url';
+export const PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY = 'zitadel_platform_files_project';
+/**
+ * #171: scope keys (colon-free) for the files host's two one-time secrets,
+ * the {@link PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY} pattern twice. Each
+ * `*_UNDELIVERED_*` key is recorded and persisted the moment its secret is
+ * minted, before delivery. Each guard is recorded only once the secret was
+ * delivered AND written to the runner's env. An undelivered id with no guard
+ * means the secret is lost: the planner reports it and never mints again.
+ * None of these holds a secret.
+ */
+export const PLATFORM_FILES_INTROSPECTION_SCOPE_KEY = 'zitadel_platform_files_introspection_app';
+export const PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY = 'zitadel_platform_files_introspection_undelivered';
+export const PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY = 'files_management_key_id';
+export const PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY = 'files_management_key_undelivered';
+/**
+ * #171: the hostname and `gitRef` the last successful files run applied.
+ * `planFiles` plans the step again when either differs from the declared
+ * value; a re-run updates `git_branch` and the runner env and redeploys,
+ * and mints nothing (the guards above hold).
+ */
+export const PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY = 'files_applied_hostname';
+export const PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY = 'files_applied_git_ref';
+/**
+ * #167: the platform's own diff engine, mirroring `diff.ts`'s
+ * `computePlanDetail` for the one shared {@link DeclaredPlatform} record
+ * (#166) rather than one `DeclaredOrg` per call. It reuses the same step
+ * kinds an org plans against (`coolify:app`, `coolify:database`,
+ * `cloudflare:tunnel`, `cloudflare:zone`, `zitadel:app`), keyed under the
+ * platform's own resources rather than an org id -- a platform service's
+ * eventual `coolify:app` step, for one example, is keyed `platform:<service>`
+ * (`platform.ts`'s `PlatformServiceKey`) rather than an `OrgId`, once that
+ * step exists.
+ *
+ * Scope for #167: the frame plus one step, {@link planApexZone}. #173 adds
+ * {@link planJobs}, #170 adds {@link planSfu}, #168 adds {@link planAuth},
+ * #169 adds {@link planMail}, #174 adds {@link planIntegrations}, #171 adds
+ * {@link planFiles}, #172 adds {@link planAi} and #175 adds
+ * {@link planArchon}, the same way #19 shipped org plan/apply against
+ * three singletons before #27, #71, #80 and the rest added the remaining
+ * twelve. Until then, a live resource under one of those eventual keys is
+ * reported unmanaged rather than silently ignored (#10's rule, carried over
+ * unchanged).
+ */
+export function planPlatform(platform, live, options = {}) {
+    const { jobsObservable = true, sfuBlocked = null, recordedIds = {}, blocked = {}, drifted = {}, } = options;
+    const byKey = new Map(live.map((r) => [resourceKey(r.system, r.kind, r.key), r]));
+    const claimed = new Set();
+    const plannedSteps = [];
+    const zone = planApexZone(platform, byKey, claimed);
+    if (zone)
+        plannedSteps.push(zone);
+    // #173: the jobs scheduler, second of the eight services this frame leaves
+    // open (this file's own doc comment above).
+    const jobs = planJobs(platform, byKey, claimed, jobsObservable);
+    if (jobs.step)
+        plannedSteps.push(jobs.step);
+    // A blocked SFU is reported in `unmanaged`, not planned: a step the
+    // executor must refuse would halt every step after it (`diff.ts` does the
+    // same for a blocked Agora).
+    const sfu = platform.sfu.enabled && sfuBlocked ? null : planSfu(platform);
+    if (sfu)
+        plannedSteps.push(sfu);
+    const auth = planAuth(platform, recordedIds, blocked.auth, blocked.authExecutorMissing ?? false, drifted.auth ?? false, blocked.authOtherInputsMissing ?? []);
+    if (auth.step)
+        plannedSteps.push(auth.step);
+    // #174: the integrations host. Planned after auth; neither step reads the
+    // other's recorded ids today, so the order is only for a readable plan.
+    const integrations = planIntegrations(platform, recordedIds, blocked.integrations);
+    if (integrations.step)
+        plannedSteps.push(integrations.step);
+    // #171: after auth, so a first apply builds the sign-in the files step
+    // creates its ZITADEL project in before that step runs.
+    const authReady = auth.step !== null || Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_AUTH_KEY)]);
+    const files = planFiles(platform, recordedIds, blocked.files, authReady);
+    if (files.step)
+        plannedSteps.push(files.step);
+    // #169: the platform's own mail server. After auth, because its OIDC
+    // directory is built against the platform's sign-in.
+    const mail = planMail(platform, recordedIds, blocked.mail, authReady);
+    if (mail.step)
+        plannedSteps.push(mail.step);
+    // #172: a throw halts every step after it, so this one goes late.
+    const ai = planAi(platform, recordedIds, blocked.ai);
+    if (ai.step)
+        plannedSteps.push(ai.step);
+    // #175: last, on purpose. Archon's sign-in client lives in the sign-in
+    // `planAuth` builds, and its env reads what every other service's step
+    // records or delivers, so in one apply it runs after all of them.
+    const archon = planArchon(platform, recordedIds, blocked.archon, authReady, drifted.archon);
+    if (archon.step)
+        plannedSteps.push(archon.step);
+    const unmanaged = live
+        .filter((r) => !claimed.has(resourceKey(r.system, r.kind, r.key)))
+        .map((r) => ({
+        description: `${r.system} ${r.kind} "${r.key}" is live but not named by the declared platform`,
+    }));
+    // A blocked jobs scheduler is reported here, not planned: a step that
+    // throws every apply, or that can never be seen live and so re-plans
+    // forever, is worse than none.
+    if (jobs.blocked)
+        unmanaged.push({ description: jobs.blocked, key: 'jobs' });
+    if (platform.sfu.enabled && sfuBlocked) {
+        unmanaged.push({ description: sfuBlocked, key: 'sfu' });
+    }
+    // Blocked, not planned: reported with the unmanaged items, like a blocked Agora.
+    if (auth.blocked)
+        unmanaged.push({ description: auth.blocked, key: 'auth' });
+    if (mail.blocked)
+        unmanaged.push({ description: mail.blocked, key: 'mail' });
+    if (integrations.blocked)
+        unmanaged.push({ description: integrations.blocked, key: 'integrations' });
+    if (files.blocked)
+        unmanaged.push({ description: files.blocked, key: 'files' });
+    if (ai.blocked)
+        unmanaged.push({ description: ai.blocked, key: 'ai' });
+    if (archon.blocked)
+        unmanaged.push({ description: archon.blocked, key: 'archon' });
+    return { plannedSteps, unmanaged };
+}
+/**
+ * The platform's own Cloudflare zone for its shared apex (`platform.ts`'s
+ * `DeclaredPlatform.apex`) -- modeled on `diff.ts`'s `planZone`, keyed by the
+ * domain itself rather than an org id, for the same reason: a Cloudflare
+ * zone belongs to a domain, not whoever declares it. Provision-only, like
+ * that planner: there is no `usesDomain` toggle to turn off here (the
+ * platform's apex is not optional the way an org's own domain is), so this
+ * step is never destructive and a live zone is never parked -- it only ever
+ * needs creating once, which is exactly #167's "so the empty
+ * companyincluded.com zone is managed."
+ */
+function planApexZone(platform, byKey, claimed) {
+    const key = resourceKey('cloudflare', 'zone', platform.apex);
+    const live = byKey.get(key);
+    if (live) {
+        claimed.add(key);
+        return null;
+    }
+    const action = {
+        system: 'cloudflare',
+        kind: 'zone',
+        key: platform.apex,
+        desired: { domain: platform.apex },
+    };
+    return {
+        action,
+        step: {
+            description: `provision a Cloudflare zone for ${platform.apex}`,
+            destroys: false,
+            migrates: false,
+        },
+    };
+}
+/**
+ * The one Coolify application (and key) every recorded jobs-scheduler
+ * resource, and its `coolify:jobs` step, is keyed under -- there is exactly
+ * one scheduler for the whole platform, so this is a fixed constant rather
+ * than something derived from `platform` (`platform-providers.ts`'s
+ * `FoundryPlatformStepExecutor`/`ProvidersPlatformCoolifyReader` both import
+ * it, so the planner and the executor/reader can never key it apart).
+ */
+export const JOBS_SCHEDULER_KEY = 'jobs';
+/**
+ * #173: the jobs scheduler (https://github.com/wtfalch/jobs) itself, as a
+ * platform-level Coolify application with its own database -- provision-only,
+ * like {@link planApexZone}: there is no park branch yet (`platform.ts`'s
+ * `PlatformService.enabled` going from true to false plans nothing, the same
+ * scope note {@link planApexZone}'s own doc comment leaves for a future
+ * issue), and once live it is never replanned -- a hostname or `gitRef`
+ * change is a manual redeploy today, not a diffed field, matching #167's own
+ * "the frame plus one step" scope for this campaign.
+ *
+ * Not planned at all while `platform.jobs.enabled` is false -- an org step
+ * (`diff.ts`'s eventual `jobs:registration`) has nothing to register against
+ * before this exists.
+ */
+function planJobs(platform, byKey, claimed, observable) {
+    const key = resourceKey('coolify', 'jobs', JOBS_SCHEDULER_KEY);
+    const live = byKey.get(key);
+    if (live)
+        claimed.add(key);
+    if (!platform.jobs.enabled)
+        return { step: null, blocked: null };
+    if (live)
+        return { step: null, blocked: null };
+    // No Coolify reader means the host wired no Coolify at all for the
+    // platform: the step's executor would throw every apply, and the scheduler
+    // could never be seen live, so it would re-plan forever. A fixed text: it
+    // is part of the stale-plan comparison.
+    if (!observable) {
+        return {
+            step: null,
+            blocked: 'the jobs scheduler is blocked, not planned: the host supplies no Coolify reader for the platform',
+        };
+    }
+    return {
+        blocked: null,
+        step: {
+            action: {
+                system: 'coolify',
+                kind: 'jobs',
+                key: JOBS_SCHEDULER_KEY,
+                desired: { hostname: platform.jobs.hostname, gitRef: platform.jobs.gitRef },
+            },
+            step: {
+                description: `provision the jobs scheduler at ${platform.jobs.hostname}`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+    };
+}
+/**
+ * The platform's shared calls SFU (#170), keyed `sfu:livekit:platform` --
+ * there is exactly one, so `key` names the platform itself rather than a
+ * domain or an org id, the way `LiveResource`'s own doc comment explains for
+ * this system. Unlike {@link planApexZone}, this step is never matched
+ * against a live resource: there is no cheap way to read the SFU VM's own
+ * state over SSH during planning (`LiveResource`'s doc comment on the `sfu`
+ * system), so the step is planned whenever `platform.sfu.enabled` is true,
+ * full stop. That is safe rather than wasteful: `applyCallsSfu`
+ * (`calls-sfu.ts`'s own top doc comment) is built to be re-run, so an apply
+ * that runs this step again writes the same files and runs the same
+ * idempotent `docker compose`/`ufw` commands, changing nothing on a VM
+ * already caught up.
+ */
+function planSfu(platform) {
+    if (!platform.sfu.enabled)
+        return null;
+    const action = {
+        system: 'sfu',
+        kind: 'livekit',
+        key: 'platform',
+        desired: { enabled: true },
+    };
+    return {
+        action,
+        step: {
+            description: 'apply the shared calls SFU (LiveKit + cloudflared) over SSH',
+            destroys: false,
+            migrates: false,
+        },
+    };
+}
+/**
+ * #168: the platform's own sign-in (ZITADEL), built fresh rather than
+ * adopted (#165) -- a Coolify Postgres, a ZITADEL app and a zitadel-login
+ * app, reached through a Cloudflare tunnel at `platform.auth.hostname`, plus
+ * (once the instance is up) minting foundry's own ZITADEL machine user with
+ * the admin role. All of that is one step, `coolify:app` keyed
+ * {@link PLATFORM_AUTH_KEY} -- mirroring `diff.ts`'s `coolifyCalls`, which
+ * bundles two apps and two databases into its own single `coolify:calls`
+ * step the same way, rather than four separate ones.
+ *
+ * Idempotent on the *recorded* resource id
+ * (`recordedIds[resourceKey('coolify','app',PLATFORM_AUTH_KEY)]`), not a live
+ * resource -- the same choice `diff.ts`'s `planOwner` makes and explains: no
+ * reader reports this step's Coolify/Cloudflare resources yet (`planPlatform`'s
+ * own doc comment: "every other service ... is left for its own issue to
+ * plan"), so a live check here would never see them and would replan this
+ * step, and its one-time machine-user mint, forever. This also means a
+ * second `planPlatform()` call plans nothing further once the first apply's
+ * `runPlatformSteps` has recorded that key -- so a second `applyPlatform`
+ * never even calls the executor for this step, let alone mints again (#168
+ * "Done when").
+ *
+ * Off by default like every {@link PlatformService} (`platform.ts`'s
+ * `basePlatform` fixture: every service starts `enabled: false`); this
+ * planner never parks or updates what it already provisioned -- v1's scope,
+ * matching #167's own apex-zone step, is "provision once."
+ *
+ * #197: the resource id alone is not "fully applied" any more. A tunnel with
+ * no `cloudflared` connector answers every platform hostname with a
+ * Cloudflare error, so a recorded app with no recorded connector
+ * ({@link PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY}) still plans the step again
+ * -- `provisionPlatformAuth` re-runs idempotently against everything it
+ * already built and only adds the connector, so this never mints or
+ * redeploys what a prior run already finished.
+ *
+ * #211: the same holds for the broker ({@link PLATFORM_AUTH_BROKER_SCOPE_KEY}).
+ * A platform applied before #204 shipped the broker recorded the app and the
+ * connector and never the broker, so without this check it would read as
+ * fully applied and Archon would never find a broker to register with.
+ *
+ * #211 round 2: a recorded broker id is not the same as a *deployed* broker
+ * ({@link PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY}) -- `provisionPlatformAuth`
+ * creates and records the app before it has `ZITADEL_SERVICE_USER_TOKEN`/
+ * `RESEND_API_TOKEN` to deploy it with (#209, #210). So this still plans the
+ * step again while the broker sits undeployed: `executorBlocked` (from
+ * `authBrokerBlockedReason`) reports it blocked, by name, for as long as the
+ * inputs stay missing, and the moment they arrive the same replanned step
+ * deploys it -- no apply is left blocked for good once its inputs exist.
+ *
+ * #211 round 5: "deployed" ({@link PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY})
+ * is read back through {@link parseBrokerDeployRecord}, not `Boolean(...)`,
+ * and only counts while the record's `brokerAppId` matches the currently
+ * recorded {@link PLATFORM_AUTH_BROKER_SCOPE_KEY} -- a broker recreated under
+ * a new app id (the old one deleted by hand, or a fresh mint) leaves the old
+ * record pointing at an app that no longer exists, and a plain `Boolean`
+ * check (round 2-4) could never see that. This function has no live Coolify
+ * access, so it cannot also compare the record's `authAppsHash` against a
+ * live `AUTH_APPS` -- that half of the same rule (`brokerDeployNeeded` in
+ * `platform-providers.ts`) only runs inside the two `provision*` functions,
+ * which do have one. A malformed record parses to `null` and is treated the
+ * same as none recorded -- see {@link parseBrokerDeployRecord}'s own doc
+ * comment.
+ *
+ * #211 round 3: `executorBlocked` must not hold back the step itself once
+ * the broker exists (`brokerApplied`). `authBrokerBlockedReason` only ever
+ * returns non-null once a broker app id is recorded, so `executorBlocked &&
+ * brokerApplied` can only mean "broker created, not yet deployed" -- never
+ * "no executor". Blocking the whole step on that would deadlock: #209 mints
+ * the broker's own token as part of running this step, and a step that is
+ * never planned never runs. So this still plans the step -- surfacing
+ * `executorBlocked` in `blocked` for visibility, not to stop planning.
+ *
+ * #211 round 6: round 3's `!brokerApplied` guard assumed "no executor" and
+ * "broker not yet created" always coincide. They don't: a broker recorded on
+ * an earlier apply, then run again against a host built without its auth
+ * dependencies (`this.auth` undefined in `PlatformProvidersExecutor`), has
+ * `brokerApplied === true` and `executorBlocked` set to the no-deps message,
+ * so round 3's check let the step through and apply threw on the missing
+ * executor. `executorMissing` is that case's own signal
+ * ({@link PlanPlatformOptions.blocked}'s `authExecutorMissing`) and holds the
+ * step back unconditionally -- there is no executor to run it with, whatever
+ * `recordedIds` says.
+ *
+ * #216: a platform with every one of the above applied but no recorded
+ * {@link PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY} is not fully applied
+ * either -- the same "provisioned before this shipped" case
+ * {@link PLATFORM_AUTH_BROKER_SCOPE_KEY} already covers, here for a platform
+ * applied before #216's login-client mint existed at all.
+ * `provisionPlatformAuth` re-runs idempotently against everything it already
+ * built and only mints and delivers the login-client token, so this never
+ * redoes what a prior run already finished. Unlike the admin key, an
+ * undelivered login-client key never blocks this check -- see
+ * {@link PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY}'s own doc comment
+ * for why -- though it is still read, below, for a non-blocking note.
+ *
+ * #216 round 4: a *recorded* login-client key is also not enough on its own
+ * -- `authDrifted` (the host's own `driftedSteps`, reading ZITADEL's live
+ * PATs for the recorded user) means the PAT this platform's two apps were
+ * handed is no longer the sole live one: a concurrent apply's own mint
+ * revoked or replaced it, or minted an extra one alongside it. Round 2 and
+ * round 3 both tried to catch that from inside the same run that delivered
+ * the token (checking once after every write, then checking again before
+ * every write) and both left a window a slow concurrent write could still
+ * land in. This closes it from the other end instead: every plan re-checks
+ * the live state no matter which run last touched it, so whichever run's
+ * write actually won is caught on the very next plan, not raced against
+ * from inside the run that might lose.
+ *
+ * #216 round 5: `otherInputsMissing` keeps the note below honest when a
+ * re-mint is needed (undelivered or drifted) but cannot actually happen yet
+ * -- `provisionPlatformAuth` only mints and delivers once the broker's
+ * inputs *other than* `ZITADEL_SERVICE_USER_TOKEN` are all present
+ * (deferred, not blocked -- see that function's own doc comment), so a note
+ * promising "this apply re-mints" while one of those is still missing would
+ * be wrong the moment it is read.
+ */
+function planAuth(platform, recordedIds, executorBlocked, executorMissing, authDrifted, otherInputsMissing = []) {
+    if (!platform.auth.enabled)
+        return { step: null, blocked: null };
+    const key = resourceKey('coolify', 'app', PLATFORM_AUTH_KEY);
+    const connectorApplied = Boolean(recordedIds[PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY]);
+    // #211: a recorded app and connector with no recorded broker id is a
+    // platform provisioned before #204 shipped the broker, or a run that threw
+    // before the broker's own id was recorded -- still not fully applied, the
+    // same rule `connectorApplied` already follows for #197's connector.
+    const brokerApplied = Boolean(recordedIds[PLATFORM_AUTH_BROKER_SCOPE_KEY]);
+    // #211 round 2: also require the broker to be deployed, not merely created.
+    // #211 round 5: and only while the deploy record still names the broker
+    // that is currently recorded -- see this function's own doc comment.
+    const brokerDeployRecord = parseBrokerDeployRecord(recordedIds[PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY]);
+    const brokerDeployed = brokerDeployRecord !== null &&
+        brokerDeployRecord.brokerAppId === recordedIds[PLATFORM_AUTH_BROKER_SCOPE_KEY];
+    // #216 round 4: parsed back, not just `Boolean(...)` -- see this
+    // function's own doc comment and {@link parseLoginClientRecord}.
+    const loginClientRecord = parseLoginClientRecord(recordedIds[PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY]);
+    // #216 round 4: a recorded record whose PAT has since drifted (revoked,
+    // replaced, or joined by an extra live PAT) reads as unapplied, same as
+    // none recorded at all -- see this function's own doc comment.
+    const loginClientApplied = loginClientRecord !== null && !authDrifted;
+    // #216 round 2: read for a non-blocking note only -- see
+    // {@link PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY}'s own doc
+    // comment for why this never holds the step back the way the admin key's
+    // own `undelivered` check below does.
+    const loginClientUndelivered = recordedIds[PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY];
+    if (recordedIds[key] &&
+        connectorApplied &&
+        brokerApplied &&
+        brokerDeployed &&
+        loginClientApplied) {
+        return { step: null, blocked: null };
+    }
+    // The admin key was minted but never reached the host. ZITADEL shows a
+    // token once, so it is lost: minting another would hide that, and skipping
+    // would leave foundry without its admin key. Report it, plan nothing.
+    const undelivered = recordedIds[PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY];
+    if (undelivered && !recordedIds[PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY]) {
+        return {
+            step: null,
+            blocked: `the platform's sign-in is blocked, not planned: the admin key of ZITADEL machine user ${undelivered} was minted but never delivered and cannot be shown again; delete that user in ZITADEL and remove the recorded key ${PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY} to mint a new one`,
+        };
+    }
+    // #211 round 6: the executor itself is unusable on this host -- nothing to
+    // plan, whatever the broker's recorded state says.
+    if (executorMissing)
+        return { step: null, blocked: executorBlocked ?? null };
+    // #211 round 3: a blocked reason with no broker yet created also means the
+    // executor is unusable (no auth dependencies) -- nothing to plan.
+    // A blocked reason with the broker already created means only its deploy
+    // is held back; plan the step anyway so it can keep retrying and, once
+    // #209/#210 land, deploy on the very next apply.
+    if (executorBlocked && !brokerApplied)
+        return { step: null, blocked: executorBlocked };
+    return {
+        step: {
+            action: {
+                system: 'coolify',
+                kind: 'app',
+                key: PLATFORM_AUTH_KEY,
+                desired: { hostname: platform.auth.hostname, gitRef: platform.auth.gitRef },
+            },
+            step: {
+                description: `provision the platform's own sign-in (ZITADEL, the login app and the sign-in broker) at ${platform.auth.hostname}`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        // #211 round 3: still surface a broker-deploy block for visibility even
+        // though the step above is planned -- see the doc comment above. #216
+        // round 2: when nothing executor-side is blocked, surface an in-flight
+        // (or abandoned) login-client mint the same way -- informational only,
+        // never a reason to skip planning. #216 round 4: same treatment for a
+        // drifted (already-delivered, now stale) login-client token. #216 round
+        // 5: and only claim "this apply re-mints" when `otherInputsMissing` is
+        // actually empty -- see this function's own doc comment.
+        blocked: executorBlocked ??
+            loginClientNeedsMintNote(loginClientUndelivered, loginClientApplied, authDrifted, loginClientRecord, otherInputsMissing),
+    };
+}
+/**
+ * #216 round 5: the note {@link planAuth} surfaces when the login-client key
+ * needs a re-mint it cannot yet perform, split out of `planAuth`'s own return
+ * statement so the "needs minting" question and the "can it actually mint
+ * right now" question are each answered in one place.
+ */
+function loginClientNeedsMintNote(loginClientUndelivered, loginClientApplied, authDrifted, loginClientRecord, otherInputsMissing) {
+    const undeliveredNeedsMint = Boolean(loginClientUndelivered) && !loginClientApplied;
+    let subject = null;
+    if (undeliveredNeedsMint) {
+        subject = `the login-client key of ZITADEL machine user ${loginClientUndelivered} was minted but not yet confirmed delivered`;
+    }
+    else if (authDrifted && loginClientRecord) {
+        subject = `the login-client token delivered for ZITADEL machine user ${loginClientRecord.userId} is no longer the sole live token on that user, likely revoked or replaced by a concurrent apply`;
+    }
+    if (subject === null)
+        return null;
+    if (otherInputsMissing.length > 0) {
+        return `${subject}; this apply cannot re-mint and redeliver it yet -- the platform's sign-in broker still needs ${otherInputsMissing.join(' and ')} first`;
+    }
+    const action = undeliveredNeedsMint
+        ? 'this apply re-mints (revoking it) and retries'
+        : 'this apply re-mints and redelivers';
+    return `${subject}; ${action} -- no manual step needed`;
+}
+/**
+ * #169: the platform's own mail server (Stalwart), built fresh -- Stalwart on
+ * Coolify with its own storage, reached at `platform.mail.hostname` for
+ * web/JMAP/management and at `mx.<apex>` for SMTP, then (once the instance is
+ * up) the OIDC directory against the platform's own sign-in and foundry's
+ * admin API key, minted once. One `coolify:app` step, mirroring
+ * {@link planAuth} exactly -- see `platform-providers.ts`'s
+ * `provisionPlatformMail` for what it actually does and its own documented
+ * gaps.
+ *
+ * `platform.mail.gitRef` carries the Stalwart image tag rather than a git
+ * ref (`platform.ts`'s `PlatformService.gitRef` doc comment: "the release it
+ * runs" -- true of an image tag too, and Stalwart has no repo of its own to
+ * build from), so `validatePlatform`'s existing "gitRef must not be empty
+ * once enabled" rule already covers it with no change there.
+ *
+ * Idempotent on the recorded resource id plus the applied hostname and
+ * `gitRef`, for the reason {@link planAuth} gives: no reader reports this
+ * step's Coolify/Cloudflare resources yet. A changed hostname or image tag
+ * plans the step again (a redeploy, no new key). Blocked, not planned, while
+ * the platform's sign-in is neither applied nor planned.
+ *
+ * #197: a recorded app with no recorded `cloudflared` connector
+ * ({@link PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY}) plans the step again, as
+ * {@link planAuth} does.
+ */
+function planMail(platform, recordedIds, executorBlocked, authReady) {
+    if (!platform.mail.enabled)
+        return { step: null, blocked: null };
+    const key = resourceKey('coolify', 'app', PLATFORM_MAIL_KEY);
+    if (recordedIds[key] &&
+        recordedIds[PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY] &&
+        recordedIds[PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY] === platform.mail.hostname &&
+        recordedIds[PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY] === platform.mail.gitRef &&
+        // #177: a mail step applied before this key existed never recorded it, and
+        // org steps read it for Agora's mail upstream. Missing means unapplied.
+        recordedIds[PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY]) {
+        return { step: null, blocked: null };
+    }
+    // Stalwart's `x:ApiKey/set` shows a secret once. An id was minted but never
+    // reached the host: report it, plan nothing, the same rule {@link planAuth}
+    // follows for ZITADEL's own admin key.
+    const undelivered = recordedIds[PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY];
+    if (undelivered && !recordedIds[PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY]) {
+        return {
+            step: null,
+            blocked: `the platform's mail server is blocked, not planned: an admin API key ("${undelivered}") was minted but never delivered and cannot be shown again; revoke that key in Stalwart and remove the recorded key ${PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY} to mint a new one`,
+        };
+    }
+    if (executorBlocked)
+        return { step: null, blocked: executorBlocked };
+    if (!authReady) {
+        return {
+            step: null,
+            blocked: "the platform's mail server is blocked, not planned: its OIDC directory uses the platform's own sign-in, which is neither applied nor planned",
+        };
+    }
+    return {
+        step: {
+            action: {
+                system: 'coolify',
+                kind: 'app',
+                key: PLATFORM_MAIL_KEY,
+                desired: { hostname: platform.mail.hostname, gitRef: platform.mail.gitRef },
+            },
+            step: {
+                description: `provision mail (Stalwart) at ${platform.mail.hostname}`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}
+/**
+ * #174: the resource key the integrations host is planned and recorded under,
+ * `platform:integrations`, like {@link PLATFORM_AUTH_KEY}: the step is
+ * `coolify:app` keyed by it, and the id `runPlatformSteps` records is
+ * `coolify:app:platform:integrations`. The planner and the executor
+ * (`platform-providers.ts`) both import this one value.
+ */
+export const PLATFORM_INTEGRATIONS_KEY = 'platform:integrations';
+/**
+ * Scope keys (colon-free) for the integrations host's Ed25519 management key.
+ * The undelivered key is recorded first, the moment the pair is minted. The
+ * set key is the guard, recorded only after the private half was delivered
+ * and the public half written to the runner. An id under the undelivered key
+ * with no guard means the pair may be lost or half-applied, and the planner
+ * reports that instead of minting again.
+ */
+export const PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY = 'integrations_management_key_undelivered';
+export const PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY = 'integrations_management_key_set';
+/** The hostname and gitRef the last successful apply put live; a difference from the declared ones plans the step again. */
+export const PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY = 'integrations_applied_hostname';
+export const PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY = 'integrations_applied_gitref';
+/**
+ * #174: the integrations host (https://github.com/wtfalch/integrations) -- its
+ * migrate job, web app and queue worker, their shared database, and its
+ * Ed25519 management key, minted once. One step, `coolify:app` keyed
+ * {@link PLATFORM_INTEGRATIONS_KEY}, bundling every part the way
+ * {@link planAuth} bundles its database, two apps and tunnel.
+ *
+ * Idempotent on the *recorded* resource id, like {@link planAuth} and for the
+ * same reason: no platform reader reports these Coolify apps. Unlike auth, a
+ * declared `hostname` or `gitRef` that differs from the applied one (recorded
+ * as scope ids) plans the step again; the step then patches the apps and
+ * redeploys, and never mints the key again.
+ *
+ * Blocked, not planned: an undelivered key, and an executor that cannot run
+ * the step (no integrations dependencies, or no `@wtfalch/keys` values for
+ * the host).
+ */
+function planIntegrations(platform, recordedIds, executorBlocked) {
+    if (!platform.integrations.enabled)
+        return { step: null, blocked: null };
+    const { hostname, gitRef } = platform.integrations;
+    const applied = Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_INTEGRATIONS_KEY)]) &&
+        recordedIds[PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY] === hostname &&
+        recordedIds[PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY] === gitRef;
+    if (applied)
+        return { step: null, blocked: null };
+    const undelivered = recordedIds[PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY];
+    if (undelivered && !recordedIds[PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY]) {
+        return {
+            step: null,
+            blocked: `the integrations host is blocked, not planned: its management key ${undelivered} was minted but not confirmed delivered and pinned, and the private half cannot be recovered; check the held key and the runner's MANAGEMENT_PUBLIC_KEYS, then remove the recorded key ${PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY} to mint a new one`,
+        };
+    }
+    if (executorBlocked)
+        return { step: null, blocked: executorBlocked };
+    return {
+        step: {
+            action: {
+                system: 'coolify',
+                kind: 'app',
+                key: PLATFORM_INTEGRATIONS_KEY,
+                desired: { hostname, gitRef },
+            },
+            step: {
+                description: `provision the integrations host at ${hostname}`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}
+/**
+ * #171: the files host (https://github.com/wtfalch/files) -- its database, a
+ * one-shot `files-migrate` app and the `files` runner, all on Coolify's
+ * internal network with no public address, plus the files ZITADEL project and
+ * introspection client in the platform's own sign-in, and foundry's own
+ * management key. One `coolify:app` step keyed {@link PLATFORM_FILES_KEY},
+ * the same bundling {@link planAuth} does.
+ *
+ * Idempotent on the recorded runner app id plus the applied hostname and
+ * `gitRef`, for the reason {@link planAuth} gives: no platform reader reports
+ * these resources, so a live check would replan the step forever. A changed
+ * hostname or `gitRef` plans the step again (a redeploy, no new secrets).
+ *
+ * Blocked, not planned, while the platform's sign-in is neither recorded nor
+ * planned in this same plan: the step creates its ZITADEL project and client
+ * there, so it would throw on every apply.
+ */
+function planFiles(platform, recordedIds, executorBlocked, authReady) {
+    if (!platform.files.enabled)
+        return { step: null, blocked: null };
+    // A secret minted but never delivered and written is lost (the private key
+    // is never kept; ZITADEL shows a client secret once). Minting another would
+    // hide that, so report it and plan nothing.
+    for (const [undeliveredKey, guardKey, what] of [
+        [
+            PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY,
+            PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY,
+            'the files management key',
+        ],
+        [
+            PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY,
+            PLATFORM_FILES_INTROSPECTION_SCOPE_KEY,
+            "the files host's introspection client secret",
+        ],
+    ]) {
+        const undelivered = recordedIds[undeliveredKey];
+        if (undelivered && !recordedIds[guardKey]) {
+            return {
+                step: null,
+                blocked: `the files host is blocked, not planned: ${what} (${undelivered}) was minted but never delivered to the host and cannot be shown again; remove the recorded key ${undeliveredKey} (and delete the ZITADEL client for the introspection secret) to mint a new one`,
+            };
+        }
+    }
+    if (recordedIds[resourceKey('coolify', 'app', PLATFORM_FILES_KEY)] &&
+        recordedIds[PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY] === platform.files.hostname &&
+        recordedIds[PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY] === platform.files.gitRef) {
+        return { step: null, blocked: null };
+    }
+    if (executorBlocked)
+        return { step: null, blocked: executorBlocked };
+    if (!authReady) {
+        return {
+            step: null,
+            blocked: "the files host is blocked, not planned: its ZITADEL project and introspection client live in the platform's own sign-in, which is neither applied nor planned",
+        };
+    }
+    return {
+        step: {
+            action: {
+                system: 'coolify',
+                kind: 'app',
+                key: PLATFORM_FILES_KEY,
+                desired: { hostname: platform.files.hostname, gitRef: platform.files.gitRef },
+            },
+            step: {
+                description: "provision the files host on Coolify's internal network, with its ZITADEL project and foundry's management key",
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}
+/**
+ * #172: the platform's AI host (https://github.com/wtfalch/ai) -- a Coolify
+ * Postgres plus three apps built from that repo's root Dockerfile, one per
+ * build target (`migration`, `runner`, `worker`), and foundry's own AI
+ * management key. One `coolify:app` step keyed {@link PLATFORM_AI_KEY}, the
+ * same bundling {@link planAuth} uses.
+ *
+ * Idempotent on the recorded resource id, like {@link planAuth} and for the
+ * same reason: no reader reports these resources. The executor returns that
+ * id only after the management key was delivered, so the step keeps being
+ * planned until it has been.
+ *
+ * `desired.hostname` is `platform.ai.hostname` as declared. Whether ai gets a
+ * public route there (and Access in front) or stays on the Coolify network
+ * only is an open decision (#172 "Decide"); nothing here wires a tunnel, DNS
+ * record or Access app, so either choice can be added later on top.
+ */
+function planAi(platform, recordedIds, executorBlocked) {
+    if (!platform.ai.enabled)
+        return { step: null, blocked: null };
+    const key = resourceKey('coolify', 'app', PLATFORM_AI_KEY);
+    // A finished apply recorded the resource id (only once the key was
+    // delivered). It is planned again only when the declared hostname or gitRef
+    // is not the one that apply finished with; the management key's guard is
+    // already set then, so nothing is minted again.
+    const applied = Boolean(recordedIds[key]);
+    const drifted = recordedIds[PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY] !== platform.ai.hostname ||
+        recordedIds[PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY] !== platform.ai.gitRef;
+    if (applied && !drifted)
+        return { step: null, blocked: null };
+    // #201: the signing pair foundry mints to authenticate its own calls to
+    // ai's platform/keys route. Minted but not confirmed delivered and pinned:
+    // the private half cannot be recovered, so report it rather than mint
+    // another (the same reason the management key check below never mints
+    // twice).
+    const signingUndelivered = recordedIds[PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY];
+    if (signingUndelivered && !recordedIds[PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY]) {
+        return {
+            step: null,
+            blocked: `the platform's AI host is blocked, not planned: its signing key ${signingUndelivered} was minted but not confirmed delivered and pinned, and the private half cannot be recovered; check the held key and the runner's MANAGEMENT_PUBLIC_KEYS, then remove the recorded key ${PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY} to mint a new one`,
+        };
+    }
+    // Minted but never delivered: ai shows a key's secret once, so it is lost.
+    // Minting another would hide that; report it and plan nothing.
+    const undelivered = recordedIds[PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY];
+    if (undelivered && !recordedIds[PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY]) {
+        return {
+            step: null,
+            blocked: `the platform's AI host is blocked, not planned: AI management key ${undelivered} was minted but never delivered and cannot be shown again; revoke it in ai (keys:revoke --id ${undelivered}) and remove the recorded key ${PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY} to mint a new one`,
+        };
+    }
+    // #201: ai reported its 'archon' key already exists with no secret to
+    // show -- a mint this record never learned about. Never minted under
+    // another name; a person must revoke the live key first.
+    const conflict = recordedIds[PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY];
+    if (conflict) {
+        return {
+            step: null,
+            blocked: `the platform's AI host is blocked, not planned: ai already holds a management key named 'archon' (${conflict}) that was never recorded delivered, so its secret cannot be shown again; revoke it in ai and remove the recorded key ${PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY} to mint a new one`,
+        };
+    }
+    const migrateBlocked = recordedIds[PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY];
+    if (migrateBlocked) {
+        return {
+            step: null,
+            blocked: `the platform's AI host is blocked, not planned: the migrate job did not turn healthy (${migrateBlocked}); fix it from its logs in Coolify, then remove the recorded key ${PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY}`,
+        };
+    }
+    if (executorBlocked)
+        return { step: null, blocked: executorBlocked };
+    return {
+        step: {
+            action: {
+                system: 'coolify',
+                kind: 'app',
+                key: PLATFORM_AI_KEY,
+                desired: { hostname: platform.ai.hostname, gitRef: platform.ai.gitRef },
+            },
+            step: {
+                description: applied
+                    ? `apply the platform's AI host at ${platform.ai.hostname} on ${platform.ai.gitRef} (migrate job, host and worker)`
+                    : `provision the platform's AI host for ${platform.ai.hostname} (migrate job, host and worker) and mint foundry's AI management key`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}
+/**
+ * #175: Archon (https://github.com/wtfalch/archon), the one shared console,
+ * built fresh at `platform.archon.hostname` (`archon.<apex>`) rather than the
+ * hand-deployed `operator.wtfalch.dev` it replaces (#165). One step,
+ * `coolify:app` keyed {@link PLATFORM_ARCHON_KEY}, covers the app, its
+ * database, its Cloudflare tunnel, Access app and DNS record, and its sign-in
+ * client in the platform's own ZITADEL -- the same bundling {@link planAuth}
+ * does, for the same reason.
+ *
+ * Idempotent on the recorded resource id plus the applied hostname and
+ * `gitRef`, for the reason {@link planAuth} gives: no platform reader reports
+ * these resources, so a live check would replan the step forever. A changed
+ * hostname or `gitRef` plans the step again, and so does `drifted` (the Access
+ * policy's include list is not the declared one). A re-run mints nothing.
+ *
+ * Blocked, not planned, while the platform's sign-in is neither recorded nor
+ * planned in this same plan: Archon's sign-in client is created inside it, so
+ * the step could only throw.
+ *
+ * #213: also puts {@link PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF},
+ * {@link PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF} and
+ * {@link PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF} as held keys, before
+ * the app deploys -- `putArchonMasterKeys` in `platform-providers.ts`.
+ *
+ * #197: a recorded app with no recorded `cloudflared` connector
+ * ({@link PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY}) plans the step again, as
+ * {@link planAuth} does.
+ */
+function planArchon(platform, recordedIds, executorBlocked, authReady, drifted) {
+    if (!platform.archon.enabled)
+        return { step: null, blocked: null };
+    const key = resourceKey('coolify', 'app', PLATFORM_ARCHON_KEY);
+    const applied = Boolean(recordedIds[key]) &&
+        Boolean(recordedIds[PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY]) &&
+        recordedIds[PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY] === platform.archon.hostname &&
+        recordedIds[PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY] === platform.archon.gitRef &&
+        // #211 round 4: a broker recreated under a new app id (the old one
+        // deleted by hand, or `platform:auth` minting a fresh one) leaves
+        // Archon's last registration on a broker that no longer exists, and
+        // nothing else here would ever plan the step again to redo it.
+        Boolean(recordedIds[PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY]) &&
+        recordedIds[PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY] ===
+            recordedIds[PLATFORM_AUTH_BROKER_SCOPE_KEY] &&
+        !recordedIds[PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY];
+    if (applied && !drifted)
+        return { step: null, blocked: null };
+    if (!platform.auth.enabled) {
+        return {
+            step: null,
+            blocked: "Archon is blocked, not planned: its sign-in client lives in the platform's own sign-in, and auth is not enabled",
+        };
+    }
+    if (!authReady) {
+        return {
+            step: null,
+            blocked: "Archon is blocked, not planned: its sign-in client lives in the platform's own sign-in, which is neither applied nor planned",
+        };
+    }
+    if (executorBlocked)
+        return { step: null, blocked: executorBlocked };
+    return {
+        step: {
+            action: {
+                system: 'coolify',
+                kind: 'app',
+                key: PLATFORM_ARCHON_KEY,
+                desired: { hostname: platform.archon.hostname, gitRef: platform.archon.gitRef },
+            },
+            step: {
+                description: `provision Archon at ${platform.archon.hostname}, putting its master keys ` +
+                    `(${PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF}, ${PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF}, ` +
+                    `${PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF}) as held keys if they are not held yet`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}