@wtfalch/foundry 0.7.1 → 0.8.0

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

@@ -49,6 +49,14 @@ export interface LoginHostBinding {
  */
 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
@@ -62,3 +70,19 @@ export declare const LOGIN_BINDING_SCOPE_KEY = "login_host_binding";
 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

@@ -50,3 +50,24 @@ export function loginHostClientIds(recorded) {
 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

@@ -192,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

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';
@@ -428,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)';
@@ -512,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
@@ -541,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:',
@@ -689,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 { DeclaredOrg, OrgId } from '../org.js';
-import type { Plan, UnmanagedItem } from '../plan.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
@@ -441,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
@@ -486,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

package/dist/plan/platform-diff.js

@@ -1,3 +1,5 @@
+import { VERSIONS } from '../bootstrap/versions.js';
+import { VERSION_CHANGE_KIND, } from '../plan.js';
 /**
  * The `Plan` (#19's public contract) a {@link PlatformPlanDetail} carries,
  * mirroring `diff.ts`'s `toPlan`. There is no separate platform-shaped `Plan`
@@ -12,6 +14,7 @@ export function toPlatformPlan(detail, ownerOrgId) {
         orgId: ownerOrgId,
         steps: detail.plannedSteps.map((p) => p.step),
         unmanaged: detail.unmanaged,
+        versionChanges: detail.versionChanges,
     };
 }
 function resourceKey(system, kind, key) {
@@ -25,6 +28,72 @@ function resourceKey(system, kind, key) {
  * an org's own (which is keyed by that org's id).
  */
 export 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 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 const CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY = 'calls_synapse_applied_image_tag';
+export 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 function versionChangeLine(service, from, to, note) {
+    if (!from || from === to)
+        return null;
+    return {
+        kind: VERSION_CHANGE_KIND,
+        service,
+        description: `${service}: ${from} -> ${to} (${note})`,
+    };
+}
+/**
+ * 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 function versionNotAppliedLine(service, appLive, applied, pinned) {
+    if (!appLive)
+        return null;
+    if (!applied) {
+        return {
+            kind: VERSION_CHANGE_KIND,
+            service,
+            description: `${service}: pinned ${pinned}, running tag unknown`,
+        };
+    }
+    if (applied === pinned)
+        return null;
+    return {
+        kind: VERSION_CHANGE_KIND,
+        service,
+        description: `${service}: pinned ${pinned}, running ${applied} (not applied by foundry)`,
+    };
+}
 /**
  * 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
@@ -490,6 +559,40 @@ export function planPlatform(platform, live, options = {}) {
     const archon = planArchon(platform, recordedIds, blocked.archon, authReady, drifted.archon);
     if (archon.step)
         plannedSteps.push(archon.step);
+    // #257: after every service above, so a database any of them just
+    // recorded is already visible to `recordedIds` on this same plan.
+    const backups = planBackups(byKey, claimed, recordedIds, blocked.backupExecutorMissing ?? false);
+    plannedSteps.push(...backups.steps);
+    // #251: one line per service whose recorded applied ref no longer matches
+    // what the next apply would use (or, for zitadel, what is actually live).
+    // Never pushed into `plannedSteps` -- see `VersionChangeItem`'s own doc
+    // comment (`plan.ts`) for why. Withheld exactly where that service's own
+    // step is blocked: advertising a version it cannot run yet, or cannot be
+    // read for, is premature, not informational.
+    const versionChanges = [];
+    for (const change of [
+        mail.blocked
+            ? null
+            : versionChangeLine('mail', recordedIds[PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY], platform.mail.gitRef, 'image, redeploy'),
+        archon.blocked
+            ? null
+            : versionChangeLine('archon', recordedIds[PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY], platform.archon.gitRef, 'git ref, redeploy'),
+        ai.blocked
+            ? null
+            : versionChangeLine('ai', recordedIds[PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY], platform.ai.gitRef, 'git ref, redeploy'),
+        files.blocked
+            ? null
+            : versionChangeLine('files', recordedIds[PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY], platform.files.gitRef, 'git ref, redeploy'),
+        integrations.blocked
+            ? null
+            : versionChangeLine('integrations', recordedIds[PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY], platform.integrations.gitRef, 'git ref, redeploy'),
+        auth.blocked
+            ? null
+            : versionNotAppliedLine('zitadel', Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_AUTH_KEY)]), recordedIds[PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY], VERSIONS.zitadel),
+    ]) {
+        if (change)
+            versionChanges.push(change);
+    }
     const unmanaged = live
         .filter((r) => !claimed.has(resourceKey(r.system, r.kind, r.key)))
         .map((r) => ({
@@ -516,7 +619,8 @@ export function planPlatform(platform, live, options = {}) {
         unmanaged.push({ description: ai.blocked, key: 'ai' });
     if (archon.blocked)
         unmanaged.push({ description: archon.blocked, key: 'archon' });
-    return { plannedSteps, unmanaged };
+    unmanaged.push(...backups.blocked);
+    return { plannedSteps, unmanaged, versionChanges };
 }
 /**
  * The platform's own Cloudflare zone for its shared apex (`platform.ts`'s
@@ -610,6 +714,98 @@ function planJobs(platform, byKey, claimed, observable) {
         },
     };
 }
+/**
+ * #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 const PLATFORM_BACKUP_DATABASE_SCOPE_KEYS = {
+    jobs: 'coolify_jobs_database',
+    auth: 'coolify_platform_auth_database',
+    archon: 'coolify_platform_archon_database',
+    ai: 'coolify_platform_ai_database',
+    files: 'coolify_platform_files_database',
+    integrations: 'coolify_integrations_database',
+};
+export const PLATFORM_BACKUP_SERVICE_KEYS = [
+    'jobs',
+    'auth',
+    'archon',
+    'ai',
+    'files',
+    'integrations',
+];
+/**
+ * #257: a nightly backup for each platform database foundry itself creates,
+ * one `coolify:backup:<service>` step per service -- unconditional, the
+ * same "no enabled toggle, always wanted" shape {@link planApexZone} has,
+ * since a database that exists always wants a backup whether or not its own
+ * service is currently `enabled` (platform-steps rule 2, this repo's
+ * CLAUDE.md: blocked, not failing). A service with no database recorded yet
+ * has nothing to back up, so it is reported blocked rather than planned --
+ * the same way `planJobs` blocks rather than plans with no Coolify reader --
+ * and so is every service once a database exists but `executorMissing` says
+ * the host built the platform executor without backup dependencies (the
+ * R2/S3 credentials `FoundryPlatformStepExecutorOptions.backup` carries).
+ * Once a step's own `coolify:backup:<service>` resource is live, it is
+ * claimed and never re-planned: like every other provision-only step here,
+ * there is no park branch for a backup already scheduled.
+ */
+function planBackups(byKey, claimed, recordedIds, executorMissing) {
+    const steps = [];
+    const blocked = [];
+    for (const service of PLATFORM_BACKUP_SERVICE_KEYS) {
+        const key = resourceKey('coolify', 'backup', service);
+        const live = byKey.get(key);
+        if (live) {
+            claimed.add(key);
+            continue;
+        }
+        // No database yet is not reported: unlike a Coolify reader or a backup
+        // executor missing (below), there is nothing here for a host to fix --
+        // the database arrives on its own once that service's own step is
+        // enabled and applied, and this step simply follows next time. Reporting
+        // it would make every platform with a service not yet applied carry a
+        // standing "blocked" note nobody can act on.
+        const databaseId = recordedIds[PLATFORM_BACKUP_DATABASE_SCOPE_KEYS[service]];
+        if (!databaseId)
+            continue;
+        if (executorMissing) {
+            blocked.push({
+                description: `platform:backup:${service} is blocked, not planned: the host built the platform executor without its backup dependencies`,
+                key: `backup:${service}`,
+            });
+            continue;
+        }
+        steps.push({
+            action: {
+                system: 'coolify',
+                kind: 'backup',
+                key: service,
+                desired: { databaseId },
+            },
+            step: {
+                description: `schedule a nightly R2 backup of the platform's ${service} database`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, blocked };
+}
 /**
  * The platform's shared calls SFU (#170), keyed `sfu:livekit:platform` --
  * there is exactly one, so `key` names the platform itself rather than a

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

@@ -102,6 +102,13 @@ export interface FoundryPlatformStepExecutorOptions {
      * -- optional for the same reason as {@link auth}.
      */
     archon?: PlatformArchonDeps;
+    /**
+     * #257: dependencies for every `coolify:backup:<service>` step -- optional
+     * for the same reason as `auth`; a service whose database already exists
+     * without this set has its backup step reported blocked rather than
+     * planned.
+     */
+    backup?: PlatformBackupDeps;
 }
 /**
  * The real {@link PlatformStepExecutor} for the two steps built so far:
@@ -159,6 +166,10 @@ export interface FoundryPlatformStepExecutorOptions {
  * #175 adds `coolify:app` keyed {@link PLATFORM_ARCHON_KEY}, Archon itself
  * ({@link provisionPlatformArchon}), once a host passes
  * {@link PlatformArchonDeps}.
+ *
+ * #257 adds `coolify:backup:<service>`, a nightly R2 backup of each
+ * platform database ({@link provisionPlatformBackup}), once a host passes
+ * {@link PlatformBackupDeps}.
  */
 export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor {
     private readonly cloudflare;
@@ -172,6 +183,7 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
     private readonly files?;
     private readonly ai?;
     private readonly archon?;
+    private readonly backup?;
     constructor(cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'createZone'>, declaredOrgStore: Pick<DeclaredOrgStore, 'findOrgIdForZone' | 'list'>, options?: FoundryPlatformStepExecutorOptions);
     blockedSteps(platform: DeclaredPlatform, recordedIds?: Readonly<Record<string, string>>): Promise<{
         auth?: string;
@@ -182,6 +194,7 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
         ai?: string;
         archon?: string;
         mail?: string;
+        backupExecutorMissing?: boolean;
     }>;
     /**
      * Whether Archon's live Access policy lets through anyone but the declared
@@ -580,6 +593,28 @@ export declare const INTEGRATIONS_MANAGEMENT_ISSUER = "foundry";
  * its signed request; fixed, since there is one key until rotation is built.
  */
 export declare const INTEGRATIONS_MANAGEMENT_KEY_ID = "foundry-1";
+/**
+ * #257: everything {@link provisionPlatformBackup} needs beyond
+ * {@link PlatformStepExecutionContext} -- the narrow Coolify slice for the
+ * backup calls themselves, and the R2 (or any S3-compatible) bucket every
+ * platform database's dump lands in. A person creates or confirms the
+ * bucket and these credentials by hand (the issue's own "Human steps"); this
+ * package only ever registers the bucket with Coolify and schedules the
+ * dump, never creates or reads the bucket itself.
+ */
+export interface PlatformBackupDeps {
+    coolify: Pick<CoolifyPort, 'listS3Storages' | 'createS3Storage' | 'listDatabaseBackups' | 'createDatabaseBackup'>;
+    r2: {
+        endpoint: string;
+        bucket: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+        /** R2 takes `'auto'` (`CoolifyPort.createS3Storage`'s own doc comment). Default `'auto'`. */
+        region?: string;
+    };
+    /** A cron string or one of Coolify's names (`daily`, `weekly`, ...). Default `'daily'`. */
+    frequency?: string;
+}
 /**
  * The real {@link PlatformCloudflareReader}: the platform's apex zone as
  * `planApexZone` expects to see it, and nothing else. The zone's DNS records
@@ -609,7 +644,7 @@ export declare class ProvidersPlatformCloudflareReader implements PlatformCloudf
 export declare class ProvidersPlatformCoolifyReader implements PlatformCoolifyReader {
     private readonly client;
     private readonly platformStore;
-    constructor(client: Pick<CoolifyPort, 'getApplication'>, platformStore: Pick<PlatformStore, 'getServiceIds'>);
+    constructor(client: Pick<CoolifyPort, 'getApplication' | 'listDatabaseBackups'>, platformStore: Pick<PlatformStore, 'getServiceIds'>);
     listResources(): Promise<LiveResource[]>;
 }
 export {};