@wtfalch/foundry 0.4.0 → 0.6.0

package/dist/plan/platform-diff.d.ts

@@ -0,0 +1,487 @@
+import type { OrgId } from '../org.js';
+import type { Plan, UnmanagedItem } from '../plan.js';
+import type { DeclaredPlatform } from '../platform.js';
+import type { PlannedStep } from './diff.js';
+import type { LiveResource } from './live.js';
+/**
+ * The platform's own diff result, the {@link DeclaredPlatform} counterpart to
+ * `diff.ts`'s `PlanDetail` -- everything the same, minus the `orgId` an org's
+ * plan carries, since a platform is one singleton record, not one per org
+ * (`platform.ts`'s own doc comment). {@link toPlatformPlan} below turns this
+ * into the public `Plan` (`../plan.ts`) `FoundryPlanApply.planPlatform`
+ * returns.
+ */
+export interface PlatformPlanDetail {
+    plannedSteps: PlannedStep[];
+    unmanaged: UnmanagedItem[];
+}
+/**
+ * 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 declare function toPlatformPlan(detail: PlatformPlanDetail, ownerOrgId: OrgId): Plan;
+/**
+ * #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 declare 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 declare 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 declare const PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY = "archon_applied_hostname";
+export declare 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 declare 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 declare const PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY = "archon_gate_closed";
+export declare const PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY = "zitadel_platform_admin_user_id";
+export declare 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 declare const PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY = "zitadel_platform_login_client_user_id";
+export declare const PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY = "zitadel_platform_login_client_user_undelivered";
+/**
+ * #216 round 4/5: what {@link PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY}
+ * records once delivery succeeds -- the minted machine user's id, the exact
+ * PAT id that was handed to the login app and the broker, and (round 5) a
+ * sha256 of the exact token value, never the value itself.
+ */
+export interface PlatformAuthLoginClientRecord {
+    readonly userId: string;
+    readonly patId: string;
+    readonly tokenHash: string;
+}
+/**
+ * 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 declare function parseLoginClientRecord(raw: string | undefined): PlatformAuthLoginClientRecord | null;
+/**
+ * #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 declare 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 declare const PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY = "coolify_platform_auth_broker_deployed";
+/**
+ * #211 round 5: what {@link PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY} records
+ * once a deploy succeeds -- the broker app id that was deployed, and a sha256
+ * of the exact `AUTH_APPS` value that was live at that deploy, never the
+ * value itself (`platform-providers.ts`'s `hashAuthApps`: a secret must never
+ * reach a recorded scope id). Round 2-4 recorded a plain broker-id string
+ * there, which could only ever mean "deployed at least once" -- it could not
+ * tell a broker recreated under a new app id, or a crash between writing
+ * `AUTH_APPS` and deploying, from one still fully applied. This record is
+ * what lets `brokerDeployNeeded` (`platform-providers.ts`) and {@link planAuth}
+ * below answer both, from one mechanism instead of two ad hoc booleans.
+ */
+export interface BrokerDeployRecord {
+    readonly brokerAppId: string;
+    readonly authAppsHash: string;
+}
+/**
+ * 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 declare function parseBrokerDeployRecord(raw: string | undefined): BrokerDeployRecord | null;
+/**
+ * #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 declare 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 declare 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 declare 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 declare const PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF = "platform:master:coolify-url";
+export declare const PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF = "platform:master:coolify-token";
+export declare 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 declare 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 declare const PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY = "stalwart_platform_admin_key_delivered";
+export declare 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 declare const PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY = "mail_applied_hostname";
+export declare 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 declare 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 declare function platformMailMxHost(apex: string): string;
+/**
+ * #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 declare const ORG_MAIL_APPLIED_APEX_SCOPE_KEY = "mail_applied_apex";
+export declare 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 declare 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 declare 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 declare const PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY = "ai_platform_management_key_id";
+export declare 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 declare 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 declare const PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY = "ai_platform_signing_key_undelivered";
+export declare 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 declare 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 declare const PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY = "ai_platform_applied_hostname";
+export declare 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 declare 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 declare 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 declare 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 declare const PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY = "files_internal_url";
+export declare 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 declare const PLATFORM_FILES_INTROSPECTION_SCOPE_KEY = "zitadel_platform_files_introspection_app";
+export declare const PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY = "zitadel_platform_files_introspection_undelivered";
+export declare const PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY = "files_management_key_id";
+export declare 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 declare const PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY = "files_applied_hostname";
+export declare const PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY = "files_applied_git_ref";
+/**
+ * Options for {@link planPlatform}, replacing four positional arguments that
+ * shifted on every merge that added a platform service (#186, #187, #188) --
+ * see https://github.com/wtfalch/foundry/pull/188#issuecomment-5895935971,
+ * the merge comment that named this shape (#189).
+ */
+export interface PlanPlatformOptions {
+    /** Whether the host supplies a Coolify reader for the platform (default `true`). */
+    jobsObservable?: boolean;
+    /** Why the shared SFU is blocked, or `null` when it is not (default `null`). */
+    sfuBlocked?: string | null;
+    /** The platform's recorded resource/scope ids (default `{}`). */
+    recordedIds?: Readonly<Record<string, string>>;
+    /** Per-step block reasons the executor reports (default `{}`). */
+    blocked?: {
+        auth?: string;
+        /**
+         * #211 round 6: set once the auth block is "the host built the platform
+         * executor without its auth dependencies" -- distinct from `auth` itself,
+         * which also covers "the broker exists but cannot deploy yet" (#209/#210
+         * still pending). `planAuth` must withhold the step for the former
+         * whatever the recorded ids say; it must not for the latter.
+         */
+        authExecutorMissing?: boolean;
+        /**
+         * #216 round 5: the broker's required inputs other than
+         * `ZITADEL_SERVICE_USER_TOKEN` that are still missing (a subset of what
+         * `auth`'s own text already names, filtered) -- {@link planAuth} reads
+         * this to say, accurately, whether a needed login-client re-mint can
+         * actually happen on the next apply or is itself waiting on one of
+         * these. Default `[]`.
+         */
+        authOtherInputsMissing?: string[];
+        files?: string;
+        integrations?: string;
+        ai?: string;
+        archon?: string;
+        mail?: string;
+    };
+    /**
+     * Steps whose live state differs from the declared one in a way the recorded
+     * ids cannot show (default `{}`). `archon`: the Cloudflare Access policy's
+     * include list is not the declared one. `auth` (#216 round 4): the
+     * login-client PAT recorded under
+     * {@link PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY} is no longer the sole
+     * live PAT on that ZITADEL machine user.
+     */
+    drifted?: {
+        archon?: boolean;
+        auth?: boolean;
+    };
+}
+/**
+ * #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 declare function planPlatform(platform: DeclaredPlatform, live: LiveResource[], options?: PlanPlatformOptions): PlatformPlanDetail;
+/**
+ * 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 declare const JOBS_SCHEDULER_KEY = "jobs";
+/**
+ * #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 declare 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 declare const PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY = "integrations_management_key_undelivered";
+export declare 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 declare const PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY = "integrations_applied_hostname";
+export declare const PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY = "integrations_applied_gitref";