@wtfalch/foundry 0.6.0 → 0.8.0

package/dist/plan/index.d.ts

@@ -24,6 +24,8 @@ export { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, MissingMailCop
 export type { ScopeResolver, RecordedIds } from './providers-readers.js';
 export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
 export type { AgoraHostPort, AgoraHostValues } from './agora.js';
+export type { LoginHostBinding, LoginHostBindingsPort } from './login-host.js';
+export { loginHostnameFor } from './login-host.js';
 export type { MailIdentityApp, MailIdentityAudienceCheck } from './mail-identity.js';
 export { checkMailIdentityAudience } from './mail-identity.js';
 export type { MailAllowlistApp } from './mail-identity-allowlist.js';

package/dist/plan/index.js

@@ -12,6 +12,7 @@ export { createZitadelAdminMinter } from './zitadel-machine-user.js';
 export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep } from './platform-sfu.js';
 export { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, MissingMailCopyAccountsError, MissingMailCopySourceTokenError, MissingMailCopyStalwartTokenError, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';
 export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
+export { loginHostnameFor } from './login-host.js';
 export { checkMailIdentityAudience } from './mail-identity.js';
 export { checkMailAppsAllowlist } from './mail-identity-allowlist.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls } from './executor.js';

package/dist/plan/login-host.d.ts

@@ -0,0 +1,88 @@
+import type { DeclaredOrg } from '../org.js';
+/**
+ * #267: what both the planner (`diff.ts`) and the executor (`executor.ts`)
+ * need to agree on for an org's own company login host -- the hostname and
+ * the shape of zitadel-login's own routing entry -- the same split
+ * `agora.ts` already makes for Agora's own hostname and env.
+ *
+ * Decided in https://github.com/wtfalch/auth/issues/137 (William,
+ * 2026-10-01): foundry owns company sign-in setup through
+ * `@wtfalch/providers`, not `auth`'s own `scripts/namespace-provisioner.mjs`.
+ * `auth/docs/company-login-hosts.md` is the enforcement side this hostname
+ * and binding feed.
+ */
+/**
+ * `auth.<domain>` once the org has its own domain and `issuer.usesDomain` is on, `<slug>-auth.oikos.host`
+ * otherwise -- the same per-tier shape `agora.ts`'s own `agoraHostnameFor`
+ * uses for Agora, and the two tiers #267's issue names directly
+ * ("auth.<domain>" on the org's own domain, "<slug>-auth.oikos.host" for
+ * tier 1, riding the shared `*.oikos.host` wildcard tunnel the same way
+ * `<slug>-agora.oikos.host` does). `../slug.ts`'s
+ * `RESERVED_AUTH_AND_ENVIRONMENTS` already reserves the `auth` *slug* so no
+ * org's own `<slug>.oikos.host` can collide with this subdomain, the same
+ * way `AGORA_SUFFIX` reserves `-agora`.
+ */
+export declare function loginHostnameFor(org: DeclaredOrg): string;
+/**
+ * One entry in zitadel-login's own `LOGIN_HOST_BINDINGS`
+ * (`auth/docs/company-login-hosts.md`) -- a single-line JSON document naming
+ * every company-bound host, its ZITADEL organization and the client ids
+ * allowed to use it. `host` is {@link loginHostnameFor}'s own value;
+ * `organizationId` is the org's ZITADEL org id (`executor.ts`'s
+ * `zitadelIssuer` recorded it as `zitadel_org`).
+ */
+export interface LoginHostBinding {
+    host: string;
+    organizationId: string;
+    clientIds: string[];
+}
+/**
+ * Host-supplied write access to zitadel-login's own `LOGIN_HOST_BINDINGS`
+ * env (`auth/docs/company-login-hosts.md`'s own "Set `LOGIN_HOST_BINDINGS`
+ * on zitadel-login", "today set by hand"). Optional on
+ * {@link FoundryStepExecutorPorts} the same way `jobsScheduler`/`mailCopy`
+ * are, but without it the login-host step is blocked, not partly applied:
+ * isolation between orgs rests on the binding, and an app repointed at a host
+ * with no binding cannot sign in. Wiring the port means the host routes to
+ * zitadel-login (DNS and ingress), because the first apply after wiring
+ * repoints the org's bound apps.
+ */
+export interface LoginHostBindingsPort {
+    upsertBinding(binding: LoginHostBinding): Promise<void>;
+    /**
+     * #274: removes a host's entry from zitadel-login's own `LOGIN_HOST_BINDINGS`
+     * -- the old host's binding, once a host change or an org destroy has
+     * moved or removed what it pointed at. Treat "not found" as done, the same
+     * rule `executor.ts`'s `isNotFoundError` gives every other removal in this
+     * package.
+     */
+    deleteBinding(host: string): Promise<void>;
+}
+/**
+ * Scope id holding what the binding was last written with
+ * ({@link loginBindingState}). Client ids are not secrets. The planner
+ * replans the login-host step when the org's recorded client ids no longer
+ * match it, so an app created after the first apply is added to the binding
+ * on the next run.
+ */
+export declare const LOGIN_BINDING_SCOPE_KEY = "login_host_binding";
+/** The org's recorded app client ids (hosted app, cms, agora), sorted. */
+export declare function loginHostClientIds(recorded: Readonly<Record<string, string>>): string[];
+/** The host plus its sorted client ids, as recorded under {@link LOGIN_BINDING_SCOPE_KEY}. */
+export declare function loginBindingState(host: string, clientIds: readonly string[]): string;
+/**
+ * #274 fix round 2: hosts a company-login-host change (or an org destroy)
+ * tried to remove and could not yet -- some live app's own ZITADEL Login V2
+ * base URI still pointed at one of them, so removing it would have broken
+ * that app's sign-in. `zitadelLoginHost` always advances
+ * `zitadel:login-host:<key>` to the org's *current* desired host on every
+ * successful run (never leaving it on an old one), so this is the only
+ * record of a removal still owed -- lost otherwise the moment a second host
+ * change moves `previousHost` on. Comma-joined, sorted, the same shape
+ * `MAIL_ROLE_MAILBOXES_SCOPE_KEY` (`executor.ts`) holds a list in.
+ */
+export declare const LOGIN_HOST_PENDING_REMOVAL_SCOPE_KEY = "zitadel_login_host_pending_removal";
+/** The hosts {@link LOGIN_HOST_PENDING_REMOVAL_SCOPE_KEY} currently names, parsed back out. */
+export declare function pendingRemovalHosts(recorded: Readonly<Record<string, string>>): string[];
+/** {@link pendingRemovalHosts}' own serialisation, sorted so the recorded value is stable regardless of check order. */
+export declare function pendingRemovalState(hosts: readonly string[]): string;

package/dist/plan/login-host.js

@@ -0,0 +1,73 @@
+import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, } from './agora.js';
+/**
+ * #267: what both the planner (`diff.ts`) and the executor (`executor.ts`)
+ * need to agree on for an org's own company login host -- the hostname and
+ * the shape of zitadel-login's own routing entry -- the same split
+ * `agora.ts` already makes for Agora's own hostname and env.
+ *
+ * Decided in https://github.com/wtfalch/auth/issues/137 (William,
+ * 2026-10-01): foundry owns company sign-in setup through
+ * `@wtfalch/providers`, not `auth`'s own `scripts/namespace-provisioner.mjs`.
+ * `auth/docs/company-login-hosts.md` is the enforcement side this hostname
+ * and binding feed.
+ */
+/**
+ * `auth.<domain>` once the org has its own domain and `issuer.usesDomain` is on, `<slug>-auth.oikos.host`
+ * otherwise -- the same per-tier shape `agora.ts`'s own `agoraHostnameFor`
+ * uses for Agora, and the two tiers #267's issue names directly
+ * ("auth.<domain>" on the org's own domain, "<slug>-auth.oikos.host" for
+ * tier 1, riding the shared `*.oikos.host` wildcard tunnel the same way
+ * `<slug>-agora.oikos.host` does). `../slug.ts`'s
+ * `RESERVED_AUTH_AND_ENVIRONMENTS` already reserves the `auth` *slug* so no
+ * org's own `<slug>.oikos.host` can collide with this subdomain, the same
+ * way `AGORA_SUFFIX` reserves `-agora`.
+ */
+export function loginHostnameFor(org) {
+    // `issuer.usesDomain` is the issuer's opt-in into the org's domain
+    // (`org.ts`'s `IssuerConfig`): a domain alone never moves it, so a domain
+    // with `usesDomain` false stays on the tier 1 host.
+    return org.domain && org.issuer.usesDomain ? `auth.${org.domain}` : `${org.slug}-auth.oikos.host`;
+}
+/**
+ * Scope id holding what the binding was last written with
+ * ({@link loginBindingState}). Client ids are not secrets. The planner
+ * replans the login-host step when the org's recorded client ids no longer
+ * match it, so an app created after the first apply is added to the binding
+ * on the next run.
+ */
+export const LOGIN_BINDING_SCOPE_KEY = 'login_host_binding';
+/** The org's recorded app client ids (hosted app, cms, agora), sorted. */
+export function loginHostClientIds(recorded) {
+    return [
+        recorded[APP_CLIENT_ID_SCOPE_KEY],
+        recorded[CMS_CLIENT_ID_SCOPE_KEY],
+        recorded[AGORA_CLIENT_ID_SCOPE_KEY],
+    ]
+        .filter((id) => Boolean(id))
+        .sort();
+}
+/** The host plus its sorted client ids, as recorded under {@link LOGIN_BINDING_SCOPE_KEY}. */
+export function loginBindingState(host, clientIds) {
+    return `${host} ${clientIds.join(',')}`;
+}
+/**
+ * #274 fix round 2: hosts a company-login-host change (or an org destroy)
+ * tried to remove and could not yet -- some live app's own ZITADEL Login V2
+ * base URI still pointed at one of them, so removing it would have broken
+ * that app's sign-in. `zitadelLoginHost` always advances
+ * `zitadel:login-host:<key>` to the org's *current* desired host on every
+ * successful run (never leaving it on an old one), so this is the only
+ * record of a removal still owed -- lost otherwise the moment a second host
+ * change moves `previousHost` on. Comma-joined, sorted, the same shape
+ * `MAIL_ROLE_MAILBOXES_SCOPE_KEY` (`executor.ts`) holds a list in.
+ */
+export const LOGIN_HOST_PENDING_REMOVAL_SCOPE_KEY = 'zitadel_login_host_pending_removal';
+/** The hosts {@link LOGIN_HOST_PENDING_REMOVAL_SCOPE_KEY} currently names, parsed back out. */
+export function pendingRemovalHosts(recorded) {
+    const raw = recorded[LOGIN_HOST_PENDING_REMOVAL_SCOPE_KEY];
+    return raw ? raw.split(',').filter((host) => host.length > 0) : [];
+}
+/** {@link pendingRemovalHosts}' own serialisation, sorted so the recorded value is stable regardless of check order. */
+export function pendingRemovalState(hosts) {
+    return [...hosts].sort().join(',');
+}

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

@@ -17,14 +17,19 @@ export interface AuditActor {
 /**
  * The seam onto `@wtfalch/audit`.
  *
- * #19 asks for `@wtfalch/audit` itself, but that package's `record`/`ledger`
- * (see `app-template/src/lib/authz/audit.ts`) is bound to one app's Drizzle
- * table, session model and closed `EventName`/`ActorClass` vocabulary — none
- * of which foundry's SDK package has (it has no database of its own; #18
- * owns the store). Adopting it here is more than a small change, so this is
- * the interface instead, logged as a Finding on #19 rather than a half
- * adoption. A real implementation binds `@wtfalch/audit`'s `ledger.sign` to
- * foundry's own vocabulary and table once foundry has one.
+ * #19 asked for `@wtfalch/audit` itself, but at the time that package's
+ * `record`/`ledger` were bound to one app's Drizzle table, session model and
+ * closed `EventName`/`ActorClass` vocabulary -- none of which foundry's SDK
+ * package had. This interface was the stand-in, logged as a Finding on #19
+ * rather than a half adoption.
+ *
+ * #232: `@wtfalch/audit` now supports a service with no tenant database of
+ * its own (`ledgerVocabulary`, `tenantId: null`, the org as `target`) -- see
+ * `store/audit.ts`'s `createPostgresAuditLog`, which binds `ledger.sign` to
+ * foundry's own closed vocabulary and `foundry_audit_events`' replacement,
+ * `audit_events` (`@wtfalch/audit`'s own table, through migrations
+ * 0022-0026). This interface itself is unchanged -- `bootstrap.ts` and
+ * `redactingAudit` need no change either.
  */
 export interface AuditLog {
     recordPlan(entry: {
@@ -187,6 +192,8 @@ export interface PlatformStepExecutor {
         ai?: string;
         archon?: string;
         mail?: string;
+        /** #257: see `PlanPlatformOptions.blocked.backupExecutorMissing` (`platform-diff.ts`). */
+        backupExecutorMissing?: boolean;
     }>;
     /**
      * Steps whose live state differs from the declared one in a way the recorded
@@ -281,6 +288,13 @@ export interface FoundryPlanApplyOptions {
      * step never runs (and fails) where no scheduler is deployed.
      */
     jobsScheduler?: boolean;
+    /**
+     * #267: true when the host's executor was built with a `loginHostBindings`
+     * port. Optional, and false without it: each org's login host is then
+     * reported blocked instead of planned, so nothing is trusted or repointed
+     * before zitadel-login's binding can be written.
+     */
+    loginHostBindings?: boolean;
     /**
      * #177: true when the host's executor was built with its own `filesOrganisation`
      * / `aiOrganisation` port. Without one, the org step needs the platform's
@@ -334,6 +348,7 @@ export declare class FoundryPlanApply implements PlanApply {
     private readonly actor;
     private readonly agora;
     private readonly jobsScheduler;
+    private readonly loginHostBindings;
     private readonly hostFiles;
     private readonly hostAi;
     private readonly now;

package/dist/plan/plan-apply.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { NO_AGORA_HOST_VALUES, readAgoraHost, } from './agora.js';
 import { AI_KEY_UNDELIVERED_SCOPE_KEY, JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY, computePlanDetail, toPlan, } from './diff.js';
 import { readLivePlatformResources, readLiveResources, } from './live.js';
@@ -78,6 +79,7 @@ export class FoundryPlanApply {
     actor;
     agora;
     jobsScheduler;
+    loginHostBindings;
     hostFiles;
     hostAi;
     now;
@@ -92,6 +94,7 @@ export class FoundryPlanApply {
         this.actor = options.actor;
         this.agora = options.agora;
         this.jobsScheduler = options.jobsScheduler ?? false;
+        this.loginHostBindings = options.loginHostBindings ?? false;
         this.hostFiles = options.filesOrganisation ?? false;
         this.hostAi = options.aiOrganisation ?? false;
         this.now = options.now ?? (() => new Date());
@@ -351,7 +354,7 @@ export class FoundryPlanApply {
             this.orgPlatformReadiness(),
             this.orgAgoraHost(id),
         ]);
-        const detail = computePlanDetail(org, live, applied?.serviceIds ?? {}, agoraHost, this.jobsScheduler, platformReadiness);
+        const detail = computePlanDetail(org, live, applied?.serviceIds ?? {}, agoraHost, this.jobsScheduler, platformReadiness, { loginHostBindings: this.loginHostBindings });
         return { org, plan: toPlan(detail), detail };
     }
     /**
@@ -426,6 +429,15 @@ export class FoundryPlanApply {
     async sfuBlockedReason(platform) {
         if (!platform.sfu.enabled)
             return null;
+        // #248: both images the SFU compose actually runs, checked before the
+        // connection -- a floating tag is a reason to block independent of
+        // whether a connection is held.
+        const livekitBlocked = floatingTagBlocked('LiveKit', VERSIONS.livekit, 'v1.13.7');
+        if (livekitBlocked)
+            return `the platform SFU is blocked, not planned: ${livekitBlocked}`;
+        const cloudflaredBlocked = floatingTagBlocked('cloudflared', VERSIONS.cloudflared, '2026.9.3');
+        if (cloudflaredBlocked)
+            return `the platform SFU is blocked, not planned: ${cloudflaredBlocked}`;
         const port = this.requirePlatformDeps().sfuConnection;
         if (!port) {
             return 'the platform SFU is blocked, not planned: the host supplies no SFU connection port (#170)';
@@ -510,7 +522,10 @@ const ZITADEL_ORG_SCOPE_KEY = 'zitadel_org';
 /**
  * Every resource `FoundryPlanApply.destroy` tears down, built from
  * `AppliedState.serviceIds`, in the order the goal line and this campaign's
- * report settle on: the Cloudflare tunnel first, then the Access gate (stop routing traffic to the
+ * report settle on: the org's own company login host first (#274 -- an
+ * instance-wide ZITADEL trust and a zitadel-login binding, neither depending
+ * on anything else this org owns, so nothing is lost by going first), then
+ * the Cloudflare tunnel, then the Access gate (stop routing traffic to the
  * app before tearing it down), then the org's own Coolify database and app,
  * then the org's customers ZITADEL org (plan gap A9), then every ZITADEL app
  * foundry recorded, then the ZITADEL project, then the
@@ -539,6 +554,7 @@ function destroyTargets(serviceIds) {
     // collected in this order, then every ZITADEL app (there can be several,
     // #71), then the two scope ids last.
     const ORDERED_PREFIXES = [
+        'zitadel:login-host:',
         'cloudflare:tunnel:',
         'cloudflare:access:',
         'coolify:database:',
@@ -617,12 +633,13 @@ function stepField(action) {
  *
  * Three sources, in this order:
  * - fields no planner step exists for yet, so no apply can make them true:
- *   SSO, guests and solo when turned on, a bespoke app repo, an adopted app
- *   in the `repo` form (#7's `#15` comment: "declared but refused by
- *   `apply`"), and calls or hosting on a domain the org has not recorded
- *   (#145: calls on the org's own domain now has a planner step, the same
- *   way hosting's own domain does, so it only fails for that one missing-
- *   domain reason, not unconditionally);
+ *   SSO, guests and solo when turned on, an adopted app in the `repo` form
+ *   (#7's `#15` comment: "declared but refused by `apply`"), and calls or
+ *   hosting on a domain the org has not recorded (#145: calls on the org's
+ *   own domain now has a planner step, the same way hosting's own domain
+ *   does, so it only fails for that one missing-domain reason, not
+ *   unconditionally). `bespokeAppRepo` is not one of these: `coolify:app`
+ *   reads it (#240), so it converges with that step like any other field;
  * - chat's reverse re-key, which the planner surfaces but which is not built
  *   (#7 amendment 3), so it counts as failed even when no step threw;
  * - on a failed apply, the field of every planned step from the one that
@@ -646,8 +663,6 @@ function failedFields(org, detail, completed, serviceIds) {
         failed.add('guests.enabled');
     if (org.solo.enabled)
         failed.add('solo.enabled');
-    if (org.bespokeAppRepo !== null)
-        failed.add('bespokeAppRepo');
     if (org.adoptedApp?.form === 'repo')
         failed.add('adoptedApp');
     // `planCallsService`/`planTunnel`/`planZone` all share this same domain
@@ -688,6 +703,11 @@ function canonical(plan) {
         orgId: plan.orgId,
         steps: [...plan.steps].sort((x, y) => x.description.localeCompare(y.description)),
         unmanaged: [...plan.unmanaged].sort((x, y) => x.description.localeCompare(y.description)),
+        // #251: display-only, but still part of what a plan says -- live state
+        // moving between `plan()` and `apply()` in a way that only changes a
+        // version-change line must still be caught as stale, the same as any
+        // other field here.
+        versionChanges: [...(plan.versionChanges ?? [])].sort((x, y) => x.description.localeCompare(y.description)),
     };
 }
 /**

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

@@ -1,5 +1,5 @@
-import type { OrgId } from '../org.js';
-import type { Plan, UnmanagedItem } from '../plan.js';
+import type { DeclaredOrg, OrgId } from '../org.js';
+import { type Plan, type UnmanagedItem, type VersionChangeItem } from '../plan.js';
 import type { DeclaredPlatform } from '../platform.js';
 import type { PlannedStep } from './diff.js';
 import type { LiveResource } from './live.js';
@@ -14,6 +14,8 @@ import type { LiveResource } from './live.js';
 export interface PlatformPlanDetail {
     plannedSteps: PlannedStep[];
     unmanaged: UnmanagedItem[];
+    /** #251: see {@link VersionChangeItem}. Never folded into `plannedSteps`. */
+    versionChanges: VersionChangeItem[];
 }
 /**
  * The `Plan` (#19's public contract) a {@link PlatformPlanDetail} carries,
@@ -33,6 +35,47 @@ export declare function toPlatformPlan(detail: PlatformPlanDetail, ownerOrgId: O
  * an org's own (which is keyed by that org's id).
  */
 export declare const PLATFORM_AUTH_KEY = "platform:auth";
+/**
+ * #251: the ZITADEL image tag the last successful auth run actually set
+ * live. `provisionPlatformAuth` records this only when it set the tag --
+ * today that is creation alone, `findOrCreatePlatformApp`'s own
+ * `justCreated`, since nothing yet patches `docker_registry_image_tag` on
+ * an app found already running (unlike mail, which does). Recording it on
+ * every run regardless, the way the app id itself is recorded, would make
+ * {@link versionNotAppliedLine} compare the pinned version against a value
+ * that was never actually applied.
+ */
+export declare const PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY = "auth_zitadel_applied_image_tag";
+/**
+ * #251: the Synapse/MAS image tags an org's calls Matrix stack last
+ * successful apply actually set live. `coolifyCalls` (`executor.ts`)
+ * records these only at creation, for the same reason
+ * {@link PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY} is: nothing yet
+ * patches either tag on an app `findOrCreateCallsApp` found already
+ * running.
+ */
+export declare const CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY = "calls_synapse_applied_image_tag";
+export declare const CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY = "calls_mas_applied_image_tag";
+/**
+ * One line for a service whose own step genuinely redeploys when its
+ * recorded applied ref differs from the declared or pinned one (mail,
+ * archon, ai, files, integrations) -- `from` undefined (nothing applied
+ * yet, a first-ever apply) or already equal to `to` means nothing to
+ * report.
+ */
+export declare function versionChangeLine(service: string, from: string | undefined, to: string, note: string): VersionChangeItem | null;
+/**
+ * One line for a service whose own step never patches a running app's
+ * image tag once created -- zitadel, synapse, mas. #251 round 3: a prior
+ * attempt worded this line the same as {@link versionChangeLine}'s
+ * "X -> Y (image, redeploy)", which promised a redeploy `apply` can never
+ * actually perform for these three. `appLive` false means nothing live yet
+ * to compare against (no line, the same first-apply case
+ * {@link versionChangeLine} has); a live app with no recorded `applied`
+ * value predates this tracking and is reported as `running tag unknown`
+ * rather than silently showing nothing.
+ */
+export declare function versionNotAppliedLine(service: string, appLive: boolean, applied: string | undefined, pinned: string): VersionChangeItem | null;
 /**
  * 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
@@ -268,6 +311,28 @@ export declare function platformMailMxHost(apex: string): string;
  */
 export declare const ORG_MAIL_APPLIED_APEX_SCOPE_KEY = "mail_applied_apex";
 export declare const ORG_MAIL_APPLIED_HOST_SCOPE_KEY = "mail_applied_host";
+/**
+ * #243: the org's `hosting.appEnv` values the last `coolify:app` apply pushed,
+ * recorded as one JSON object (env name to value; ids and a domain, never a
+ * secret). `planApp` plans the step again when {@link resolveAppEnv} differs
+ * from it, so a changed map reaches an app that is already live.
+ */
+export declare const APP_ENV_APPLIED_SCOPE_KEY = "app_env_applied";
+/**
+ * #239: set to '1' once an app has been restarted after its database URLs
+ * were pushed. Not a URL. Without it a crash between the push and the restart
+ * would leave a stale container that no plan notices.
+ */
+export declare const DB_ENV_APPLIED_SCOPE_KEY = "db_env_applied";
+/**
+ * The `hosting.appEnv` entries whose source has a recorded value, in env-name
+ * order, and the env names whose source has none yet. Shared by `planApp` and
+ * the executor's `pushAppEnv` so both read the same recorded ids.
+ */
+export declare function resolveAppEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>): {
+    values: Record<string, string>;
+    unresolved: Array<[string, string]>;
+};
 /**
  * #172: the resource key `planAi` plans under and `FoundryPlatformStepExecutor`
  * dispatches on, the same `platform:<service>` shape as
@@ -419,6 +484,13 @@ export interface PlanPlatformOptions {
         ai?: string;
         archon?: string;
         mail?: string;
+        /**
+         * #257: true once a service's database exists but the host built the
+         * platform executor with no backup dependencies -- every such service's
+         * `coolify:backup:<service>` step is blocked, not planned, the same
+         * "executor missing" shape {@link authExecutorMissing} has for auth.
+         */
+        backupExecutorMissing?: boolean;
     };
     /**
      * Steps whose live state differs from the declared one in a way the recorded
@@ -464,6 +536,34 @@ export declare function planPlatform(platform: DeclaredPlatform, live: LiveResou
  * it, so the planner and the executor/reader can never key it apart).
  */
 export declare const JOBS_SCHEDULER_KEY = "jobs";
+/**
+ * #257: the six platform databases foundry itself creates, each keyed by
+ * the scope id `platform-providers.ts`'s own `createPostgresDatabase` call
+ * site records once that service's database exists --
+ * `JOBS_DATABASE_SCOPE_KEY`, `PLATFORM_AUTH_DB_SCOPE_KEY`,
+ * `PLATFORM_ARCHON_DB_SCOPE_KEY`, `PLATFORM_AI_DB_SCOPE_KEY`,
+ * `PLATFORM_FILES_DB_SCOPE_KEY`, `INTEGRATIONS_DATABASE_SCOPE_KEY`. Those
+ * constants stay module-private in `platform-providers.ts`, grouped with
+ * each service's other scope keys; the string values here are a second,
+ * documented copy rather than an import, so `planBackups` below never
+ * reaches into that file and `platform-providers.ts` keeps importing *from*
+ * this one, never the other way (every other scope key constant already
+ * flows that direction). `platform-providers.test.ts`'s own
+ * `coolify:backup` suite exercises both the executor's real constants and
+ * this planner end to end, so a renamed key on either side shows up as a
+ * database the planner can no longer see -- reported blocked, per rule 2,
+ * never a wrong step.
+ */
+export declare const PLATFORM_BACKUP_DATABASE_SCOPE_KEYS: {
+    readonly jobs: "coolify_jobs_database";
+    readonly auth: "coolify_platform_auth_database";
+    readonly archon: "coolify_platform_archon_database";
+    readonly ai: "coolify_platform_ai_database";
+    readonly files: "coolify_platform_files_database";
+    readonly integrations: "coolify_integrations_database";
+};
+export type PlatformBackupServiceKey = keyof typeof PLATFORM_BACKUP_DATABASE_SCOPE_KEYS;
+export declare const PLATFORM_BACKUP_SERVICE_KEYS: readonly PlatformBackupServiceKey[];
 /**
  * #174: the resource key the integrations host is planned and recorded under,
  * `platform:integrations`, like {@link PLATFORM_AUTH_KEY}: the step is