@wtfalch/foundry 0.6.0 → 0.8.0

package/dist/plan/platform-providers.js

@@ -1,9 +1,10 @@
 import { createHash, createPrivateKey, generateKeyPairSync, randomBytes, randomUUID, sign, } from 'node:crypto';
 import { isIPv4 } from 'node:net';
+import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { redactSecrets } from '../calls-sfu-deploy-support.js';
 import { ensureCloudflaredConnector } from './cloudflared-connector.js';
 import { ACCESS_POLICY_NAME, isNotFoundError, isRunningOrStarting } from './executor.js';
-import { JOBS_SCHEDULER_KEY, PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY, PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_KEY, PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_KEY, PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF, PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY, PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY, PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY, PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, parseBrokerDeployRecord, parseLoginClientRecord, platformMailMxHost, } from './platform-diff.js';
+import { JOBS_SCHEDULER_KEY, PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY, PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_KEY, PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_KEY, PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF, PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY, PLATFORM_BACKUP_DATABASE_SCOPE_KEYS, PLATFORM_BACKUP_SERVICE_KEYS, PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY, PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY, PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, parseBrokerDeployRecord, parseLoginClientRecord, platformMailMxHost, } from './platform-diff.js';
 import { applyCallsSfuPlatformStep } from './platform-sfu.js';
 /** The key `runPlatformSteps` records the apex zone's id under (`system:kind:key`). */
 function apexZoneKey(apex) {
@@ -92,6 +93,10 @@ const JOBS_SCHEDULER_REPO = 'wtfalch/jobs';
  * #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 class FoundryPlatformStepExecutor {
     cloudflare;
@@ -105,6 +110,7 @@ export class FoundryPlatformStepExecutor {
     files;
     ai;
     archon;
+    backup;
     constructor(cloudflare, declaredOrgStore, options = {}) {
         this.cloudflare = cloudflare;
         this.declaredOrgStore = declaredOrgStore;
@@ -117,6 +123,7 @@ export class FoundryPlatformStepExecutor {
         this.files = options.files;
         this.ai = options.ai;
         this.archon = options.archon;
+        this.backup = options.backup;
     }
     async blockedSteps(platform, recordedIds = {}) {
         const blocked = {};
@@ -130,8 +137,19 @@ export class FoundryPlatformStepExecutor {
         }
         else if (platform.auth.enabled && this.auth) {
             const { reason: authBlocked, otherInputsMissing } = await authBrokerBlockedReason(this.auth, recordedIds);
-            if (authBlocked)
+            if (authBlocked) {
                 blocked.auth = authBlocked;
+            }
+            else {
+                // #248: the same "block, not throw" rule mail's own tag check
+                // follows. `VERSIONS.zitadel` is a real pin today, so this never
+                // fires in practice -- it is here so a future bump that lands a
+                // floating tag is caught the same way mail's would be.
+                const zitadelTagBlocked = floatingTagBlocked('ZITADEL', VERSIONS.zitadel, 'v4.17.3');
+                if (zitadelTagBlocked) {
+                    blocked.auth = `the platform's sign-in is blocked, not planned: ${zitadelTagBlocked}`;
+                }
+            }
             // #216 round 5: see `PlanPlatformOptions.blocked.authOtherInputsMissing`.
             if (otherInputsMissing.length > 0)
                 blocked.authOtherInputsMissing = otherInputsMissing;
@@ -197,6 +215,14 @@ export class FoundryPlatformStepExecutor {
                 }
             }
         }
+        // Only once a database actually exists to back up -- the same
+        // "nothing to report yet" rule `planBackups` (`platform-diff.ts`)
+        // itself follows for "no database", so an otherwise-unrelated platform
+        // with no backup deps wired carries no standing blocked note.
+        if (!this.backup &&
+            PLATFORM_BACKUP_SERVICE_KEYS.some((service) => Boolean(recordedIds[PLATFORM_BACKUP_DATABASE_SCOPE_KEYS[service]]))) {
+            blocked.backupExecutorMissing = true;
+        }
         return blocked;
     }
     /**
@@ -270,6 +296,12 @@ export class FoundryPlatformStepExecutor {
         if (action.system === 'coolify' && action.kind === 'jobs') {
             return this.coolifyJobs(action, context);
         }
+        if (action.system === 'coolify' && action.kind === 'backup') {
+            if (!this.backup) {
+                throw new Error(`platform:backup:${action.key} needs FoundryPlatformStepExecutor to be constructed with its backup dependencies (#257)`);
+            }
+            return provisionPlatformBackup(action, context, this.backup);
+        }
         if (action.system === 'sfu' && action.kind === 'livekit') {
             return this.executeSfu();
         }
@@ -439,9 +471,9 @@ const PLATFORM_AUTH_BROKER_INTERNAL_NAME = 'platform-auth-broker';
 const PLATFORM_AUTH_TUNNEL_NAME = 'platform-auth-tunnel';
 /** #197: the one Coolify app that runs `cloudflared` for {@link PLATFORM_AUTH_TUNNEL_NAME}. */
 const PLATFORM_AUTH_CLOUDFLARED_APP_NAME = 'platform-auth-cloudflared';
-/** `wtfalch/auth`'s `docker-compose.yml`: `image: ghcr.io/zitadel/zitadel:${ZITADEL_VERSION:-v4.17.3}`. */
+/** `wtfalch/auth`'s `docker-compose.yml`: `image: ghcr.io/zitadel/zitadel:${ZITADEL_VERSION:-v4.17.3}`. Pinned in `versions.json` (#247). */
 const AUTH_ZITADEL_IMAGE = 'ghcr.io/zitadel/zitadel';
-const AUTH_ZITADEL_IMAGE_TAG = 'v4.17.3';
+const AUTH_ZITADEL_IMAGE_TAG = VERSIONS.zitadel;
 /** `wtfalch/auth`'s own `login/Dockerfile` -- `docs/deploy.md`'s "One compose service, four containers... Two images are built from this repository: the proxy... and the login". */
 const AUTH_REPO = 'wtfalch/auth';
 const AUTH_LOGIN_DOCKERFILE = 'login/Dockerfile';
@@ -808,6 +840,15 @@ async function provisionPlatformAuth(context, deps) {
     await deps.coolify.updateApplication(zitadelAppId, {
         custom_internal_name: PLATFORM_AUTH_ZITADEL_INTERNAL_NAME,
     });
+    // #251: only on create, never unconditionally -- nothing here patches
+    // `docker_registry_image_tag` on an app `findOrCreatePlatformApp` found
+    // already running, so that is the only moment this tag is actually live.
+    // Recording it every run, the way the app id above is, would make
+    // `versionNotAppliedLine` compare a bumped `VERSIONS.zitadel` against a
+    // value that was never applied to the running app.
+    if (zitadelApp.justCreated) {
+        await record(PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY, AUTH_ZITADEL_IMAGE_TAG);
+    }
     // ---- the zitadel-login app -----------------------------------------------
     const loginApp = await findOrCreatePlatformApp(deps.coolify, PLATFORM_AUTH_LOGIN_APP_NAME, environment, async () => {
         const server = await resolvePlatformServer(deps.coolify);
@@ -1519,12 +1560,17 @@ async function provisionPlatformMail(context, deps) {
     await record(PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY, imageTag);
     return { resourceId: appId };
 }
-/** Why the Stalwart image tag cannot be used, or `null`. A floating tag cannot be re-pulled by comparing tags. */
+/**
+ * Why the Stalwart image tag cannot be used, or `null`. #248: a thin wrapper
+ * over the estate-wide {@link floatingTagBlocked} -- the mail step's own
+ * message, naming `gitRef` since that is the declared field this tag
+ * actually comes from.
+ */
 function mailImageTagBlocked(tag) {
-    if (tag.trim() === '' || tag.trim().toLowerCase() === 'latest') {
-        return `the platform's mail server is blocked, not planned: the Stalwart image tag "${tag}" floats; declare a pinned release (for example v0.16.24) as the mail gitRef`;
-    }
-    return null;
+    const reason = floatingTagBlocked('Stalwart', tag, 'v0.16.24');
+    return reason
+        ? `the platform's mail server is blocked, not planned: ${reason} as the mail gitRef`
+        : null;
 }
 /** Why the server's address cannot be the MX A record's content, or `null`. */
 function mailServerIpBlocked(ip) {
@@ -1848,19 +1894,32 @@ async function provisionPlatformArchon(context, deps) {
         await record(PLATFORM_ARCHON_PROJECT_SCOPE_KEY, projectUuid);
     }
     const { environment } = await deps.coolify.findOrCreateEnvironment(projectUuid, 'production');
+    // #265: a database already named `platform-archon-db` (the hand-deployed
+    // one) is adopted, never built a second time. One of that name in another
+    // environment is refused: adopting or duplicating it would split the data.
     let dbId = recorded[PLATFORM_ARCHON_DB_SCOPE_KEY];
     if (!dbId) {
-        const server = await resolvePlatformServer(deps.coolify);
-        const created = await deps.coolify.createPostgresDatabase({
-            project_uuid: projectUuid,
-            server_uuid: server.uuid,
-            environment_name: environment.name,
-            environment_uuid: environment.uuid,
-            name: PLATFORM_ARCHON_DB_NAME,
-            postgres_db: ARCHON_POSTGRES_DB,
-            postgres_user: ARCHON_POSTGRES_DB,
-        });
-        dbId = created.uuid;
+        const named = (await deps.coolify.listDatabases()).filter((d) => d.name === PLATFORM_ARCHON_DB_NAME);
+        const found = named.find((d) => d.environment_id === environment.id);
+        if (!found && named.length > 0) {
+            throw new Error(`platform:archon: a database named ${PLATFORM_ARCHON_DB_NAME} exists outside the ${PLATFORM_ARCHON_PROJECT} project's production environment; refusing to adopt or duplicate it. Move or rename it in Coolify and apply again`);
+        }
+        if (found) {
+            dbId = found.uuid;
+        }
+        else {
+            const server = await resolvePlatformServer(deps.coolify);
+            const created = await deps.coolify.createPostgresDatabase({
+                project_uuid: projectUuid,
+                server_uuid: server.uuid,
+                environment_name: environment.name,
+                environment_uuid: environment.uuid,
+                name: PLATFORM_ARCHON_DB_NAME,
+                postgres_db: ARCHON_POSTGRES_DB,
+                postgres_user: ARCHON_POSTGRES_DB,
+            });
+            dbId = created.uuid;
+        }
         await record(PLATFORM_ARCHON_DB_SCOPE_KEY, dbId);
     }
     const db = await deps.coolify.getDatabase(dbId);
@@ -1869,6 +1928,12 @@ async function provisionPlatformArchon(context, deps) {
     }
     // ---- the app ----------------------------------------------------------------
     const app = await findOrCreatePlatformApp(deps.coolify, PLATFORM_ARCHON_APP_NAME, environment, async () => {
+        // #265: the lookup above is scoped to this environment, so a same-named
+        // app elsewhere is invisible to it. Making another one would give two
+        // `platform-archon` apps; refuse instead.
+        if (await deps.coolify.findApplicationByName(PLATFORM_ARCHON_APP_NAME)) {
+            throw new Error(`platform:archon: an application named ${PLATFORM_ARCHON_APP_NAME} exists outside the ${PLATFORM_ARCHON_PROJECT} project's production environment; refusing to create a second one. Move or rename it in Coolify and apply again`);
+        }
         const server = await resolvePlatformServer(deps.coolify);
         const githubApp = await deps.coolify.requireGithubApp();
         return deps.coolify.createGithubAppApplication({
@@ -1913,7 +1978,7 @@ async function provisionPlatformArchon(context, deps) {
         // response was lost, or one made for another hostname: its client id
         // cannot be read back (`listApps` does not carry it), so it is deleted and
         // made again, as `zitadelApp` does.
-        const orphan = (await zitadel.listApps(org.id, project.id)).find((a) => a.name === PLATFORM_ARCHON_ZITADEL_APP &&
+        const orphan = (await zitadel.listApps(org.id, project.id)).apps.find((a) => a.name === PLATFORM_ARCHON_ZITADEL_APP &&
             a.appType === 'web' &&
             a.state !== 'APP_STATE_REMOVED');
         if (orphan) {
@@ -1944,9 +2009,20 @@ async function provisionPlatformArchon(context, deps) {
         { key: 'AUTH_ISSUER', value: issuer },
         { key: 'AUTH_ORGANIZATION_ID', value: org.id },
         { key: 'AUTH_CLIENT_ID', value: clientId },
-        { key: 'DATABASE_URL_OWNER', value: db.internal_db_url },
-        { key: 'REPORTING_SITE', value: 'archon' },
     ];
+    // #265: an owner URL or reporting site already on the app is kept as it is.
+    // The owner URL must name the adopted database's host, or the app's two
+    // database URLs would point at different databases.
+    const liveOwnerUrl = await currentEnvValue(deps.coolify, appId, 'DATABASE_URL_OWNER');
+    if (liveOwnerUrl) {
+        assertSameDatabaseHost('DATABASE_URL_OWNER', liveOwnerUrl, db.internal_db_url);
+    }
+    else {
+        envs.push({ key: 'DATABASE_URL_OWNER', value: db.internal_db_url });
+    }
+    if (!(await currentEnvValue(deps.coolify, appId, 'REPORTING_SITE'))) {
+        envs.push({ key: 'REPORTING_SITE', value: 'archon' });
+    }
     const cookieSecret = await ensureGeneratedEnv(deps.coolify, appId, 'AUTH_COOKIE_SECRET', () => randomBytes(32).toString('base64'));
     if (cookieSecret)
         envs.push({ key: 'AUTH_COOKIE_SECRET', value: cookieSecret });
@@ -2591,10 +2667,34 @@ async function collectArchonServiceInputs(platform, deps, recorded) {
  * `base64url` fits `db-runtime-role.sh`'s password alphabet
  * (`A-Za-z0-9_.~-`).
  */
+/**
+ * #265: throws when `liveUrl` points at another host than the adopted
+ * database. Names both hosts and nothing else: a URL carries a credential, and
+ * Node's parse error echoes its whole input.
+ */
+function assertSameDatabaseHost(key, liveUrl, dbInternalUrl) {
+    const hostOf = (url) => {
+        try {
+            return new URL(url).host;
+        }
+        catch {
+            return null;
+        }
+    };
+    const liveHost = hostOf(liveUrl);
+    const dbHost = hostOf(dbInternalUrl);
+    if (liveHost !== dbHost) {
+        throw new Error(`platform:archon: ${key} on the app points at host ${liveHost ?? '(unparseable)'}, but the adopted database ${PLATFORM_ARCHON_DB_NAME} is at host ${dbHost ?? '(unparseable)'}; refusing to leave the app's database URLs on different databases`);
+    }
+}
 async function ensureArchonRuntimeUrl(coolify, appId, dbInternalUrl) {
     const envs = await coolify.listEnvs(appId);
-    if (envs.some((e) => e.key === 'DATABASE_URL' && !e.is_preview))
+    const live = envs.find((e) => e.key === 'DATABASE_URL' && !e.is_preview);
+    if (live) {
+        // #265: kept as it is, but it must name the adopted database's host.
+        assertSameDatabaseHost('DATABASE_URL', live.value, dbInternalUrl);
         return null;
+    }
     let host;
     let pathname;
     let search;
@@ -3781,7 +3881,7 @@ async function provisionPlatformFiles(context, deps) {
         // An app by this name here has no recorded secret (no undelivered id, or
         // the throw above would have fired): a crash between the create and the
         // record. Nothing was delivered, so it is deleted and made again.
-        const stale = (await zitadel.listApps(org.id, project.id)).filter((app) => app.name === FILES_INTROSPECTION_APP_NAME && app.state !== 'APP_STATE_REMOVED');
+        const stale = (await zitadel.listApps(org.id, project.id)).apps.filter((app) => app.name === FILES_INTROSPECTION_APP_NAME && app.state !== 'APP_STATE_REMOVED');
         for (const app of stale) {
             try {
                 await zitadel.deleteApp(org.id, project.id, app.id);
@@ -4284,6 +4384,61 @@ async function waitForIntegrationsMigration(coolify, appId, runtime, sleep) {
         await sleep(interval);
     }
 }
+/** The name every platform database's backup is registered against -- one shared R2 bucket, one storage entry. */
+const PLATFORM_BACKUP_S3_STORAGE_NAME = 'platform-backups';
+/** The uuid `provisionPlatformBackup` records once {@link PLATFORM_BACKUP_S3_STORAGE_NAME} is registered on Coolify, so a later apply never re-registers it. */
+const PLATFORM_BACKUP_S3_STORAGE_SCOPE_KEY = 'coolify_platform_backup_s3_storage';
+/** Coolify's own name for "once a day" -- `createDatabaseBackup`'s `frequency`. */
+const PLATFORM_BACKUP_DEFAULT_FREQUENCY = 'daily';
+/**
+ * #257: schedules a nightly R2 backup of one platform database --
+ * `planBackups` (`platform-diff.ts`) plans this step once per service, each
+ * carrying that service's own database id as `action.desired.databaseId`
+ * (recorded by that service's own `coolify:app` step; never minted here).
+ * The R2 bucket is registered as a Coolify S3 storage once, by name, and
+ * its uuid recorded under {@link PLATFORM_BACKUP_S3_STORAGE_SCOPE_KEY} so
+ * every service's own backup step -- and a rerun of this one -- reuses it
+ * rather than registering a second storage entry under the same name.
+ * `createDatabaseBackup` itself is the idempotency boundary for the
+ * schedule: an existing enabled, `save_s3` schedule is left alone rather
+ * than replaced, since Coolify has no "upsert" for this call and a second
+ * schedule would dump the same database twice a night.
+ */
+async function provisionPlatformBackup(action, context, deps) {
+    const { coolify, r2 } = deps;
+    const databaseId = action.desired.databaseId;
+    const recorded = context.recordedIds();
+    let storageUuid = recorded[PLATFORM_BACKUP_S3_STORAGE_SCOPE_KEY];
+    if (!storageUuid) {
+        const found = (await coolify.listS3Storages()).find((storage) => storage.name === PLATFORM_BACKUP_S3_STORAGE_NAME);
+        if (found) {
+            storageUuid = found.uuid;
+        }
+        else {
+            const created = await coolify.createS3Storage({
+                name: PLATFORM_BACKUP_S3_STORAGE_NAME,
+                endpoint: r2.endpoint,
+                bucket: r2.bucket,
+                region: r2.region ?? 'auto',
+                key: r2.accessKeyId,
+                secret: r2.secretAccessKey,
+                is_usable: true,
+            });
+            storageUuid = created.uuid;
+        }
+        context.recordScopeId(PLATFORM_BACKUP_S3_STORAGE_SCOPE_KEY, storageUuid);
+    }
+    const existing = (await coolify.listDatabaseBackups(databaseId)).find((backup) => backup.enabled && backup.save_s3);
+    if (!existing) {
+        await coolify.createDatabaseBackup(databaseId, {
+            frequency: deps.frequency ?? PLATFORM_BACKUP_DEFAULT_FREQUENCY,
+            enabled: true,
+            save_s3: true,
+            s3_storage_uuid: storageUuid,
+        });
+    }
+    return undefined;
+}
 /**
  * The real {@link PlatformCloudflareReader}: the platform's apex zone as
  * `planApexZone` expects to see it, and nothing else. The zone's DNS records
@@ -4338,23 +4493,55 @@ export class ProvidersPlatformCoolifyReader {
         this.platformStore = platformStore;
     }
     async listResources() {
-        const recordedId = (await this.platformStore.getServiceIds())[JOBS_APP_KEY];
-        if (!recordedId)
-            return [];
-        try {
-            const app = await this.client.getApplication(recordedId);
-            return [
-                {
+        const recorded = await this.platformStore.getServiceIds();
+        const resources = [];
+        const recordedAppId = recorded[JOBS_APP_KEY];
+        if (recordedAppId) {
+            try {
+                const app = await this.client.getApplication(recordedAppId);
+                resources.push({
                     system: 'coolify',
                     kind: 'jobs',
                     key: JOBS_SCHEDULER_KEY,
                     config: { uuid: app.uuid, status: app.status },
-                },
-            ];
+                });
+            }
+            catch {
+                // A recorded id Coolify no longer has reads as not-live (see this
+                // class's own doc comment); the scheduler, not every other resource
+                // this reader checks.
+            }
         }
-        catch {
-            return [];
+        // #257: one backup-schedule resource per service whose database is
+        // recorded, found the only way a schedule can be: listed off that
+        // database itself, since Coolify names no schedule of its own.
+        for (const service of PLATFORM_BACKUP_SERVICE_KEYS) {
+            const databaseId = recorded[PLATFORM_BACKUP_DATABASE_SCOPE_KEYS[service]];
+            if (!databaseId)
+                continue;
+            try {
+                const backups = await this.client.listDatabaseBackups(databaseId);
+                const scheduled = backups.find((backup) => backup.enabled && backup.save_s3);
+                if (scheduled) {
+                    resources.push({
+                        system: 'coolify',
+                        kind: 'backup',
+                        key: service,
+                        config: { uuid: scheduled.uuid, frequency: scheduled.frequency },
+                    });
+                }
+            }
+            catch {
+                // A Coolify error (or a recorded database id Coolify no longer has)
+                // reads as not-live, the same as the jobs app above -- `databaseId`
+                // is still recorded, so `planBackups` plans the step again rather
+                // than reporting it blocked; `provisionPlatformBackup`'s own
+                // `listDatabaseBackups` check (run again there) is what keeps a
+                // transient failure here from scheduling a second backup once the
+                // first one did succeed.
+            }
         }
+        return resources;
     }
 }
 /**

package/dist/plan/providers-readers.js

@@ -130,6 +130,47 @@ async function withLogVolumeConfig(client, resource, recorded) {
         return resource;
     }
 }
+/**
+ * #239: whether a recorded database has an internal connection URL, as
+ * `config.hasInternalUrl` (a boolean, never the URL), so `planApp` can report
+ * a database it cannot push from as blocked. A failed read leaves it absent.
+ */
+async function withDatabaseUrlConfig(client, resource, recorded) {
+    if (resource.kind !== 'database' || !recorded[resource.key]?.startsWith('database:')) {
+        return resource;
+    }
+    try {
+        const db = await client.getDatabase(resource.key);
+        return {
+            ...resource,
+            config: { ...resource.config, hasInternalUrl: Boolean(db.internal_db_url) },
+        };
+    }
+    catch {
+        return resource;
+    }
+}
+/**
+ * #239: the live env var NAMES (never values) of the org's own recorded app,
+ * as `config.envNames`, so `diff.ts`'s `planApp` can notice an app that
+ * lacks `DATABASE_URL_OWNER`. Failure is swallowed like
+ * {@link withLogVolumeConfig}: `envNames` stays absent and the planner reads
+ * that as nothing checked.
+ */
+async function withEnvNamesConfig(client, resource, recorded) {
+    if (resource.kind !== 'application' || !recorded[resource.key]?.startsWith('app:')) {
+        return resource;
+    }
+    try {
+        const envNames = (await client.listEnvs(resource.key))
+            .filter((e) => !e.is_preview)
+            .map((e) => e.key);
+        return { ...resource, config: { ...resource.config, envNames } };
+    }
+    catch {
+        return resource;
+    }
+}
 /**
  * #164: the org's own recorded Agora app's live `AGORA_*` env vars, as
  * `config.env`, so `diff.ts`'s `planAgora` can compare them with what
@@ -177,7 +218,9 @@ export class ProvidersCoolifyReader {
             this.resolveRecordedIds(orgId),
         ]);
         const withLogConfig = await Promise.all(toFoundryResources('coolify', resources).map((r) => withLogVolumeConfig(this.client, r, recorded)));
-        const withAgoraConfig = await Promise.all(withLogConfig.map((r) => withAgoraEnvConfig(this.client, r, recorded)));
+        const withEnvNames = await Promise.all(withLogConfig.map((r) => withEnvNamesConfig(this.client, r, recorded)));
+        const withDbUrl = await Promise.all(withEnvNames.map((r) => withDatabaseUrlConfig(this.client, r, recorded)));
+        const withAgoraConfig = await Promise.all(withDbUrl.map((r) => withAgoraEnvConfig(this.client, r, recorded)));
         return applyRecordedIds(withAgoraConfig, recorded);
     }
 }

package/dist/plan.d.ts

@@ -53,4 +53,47 @@ export interface Plan {
     orgId: OrgId;
     steps: PlanStep[];
     unmanaged: UnmanagedItem[];
+    /**
+     * #251: see {@link VersionChangeItem}. Optional so a `Plan` built before
+     * this field existed, or a test fixture that predates it, still satisfies
+     * this type with none.
+     */
+    versionChanges?: VersionChangeItem[];
+}
+/**
+ * The action kind a {@link VersionChangeItem} carries -- a distinct, typed
+ * value so Archon can key off it to render and later gate these lines
+ * (wtfalch/archon#133), and so it is never mistaken for a `StepAction.kind`
+ * (`plan/diff.ts`) any `StepExecutor` dispatches on.
+ *
+ * #251 round 3: an earlier attempt planned these as ordinary `PlanStep`s in
+ * `Plan.steps`. That made a plan holding only version-change lines for
+ * zitadel/synapse/mas (whose own step never re-applies a running app's
+ * image tag -- see {@link VersionChangeItem}) never read as empty, which is
+ * the condition `bootstrap/drive.ts` loops on, and `apply` tried to run a
+ * step for those services that does nothing. Version-change lines are
+ * carried on their own `Plan.versionChanges` field instead, never on
+ * `steps`, so they are display-only everywhere a `Plan` is read.
+ */
+export declare const VERSION_CHANGE_KIND = "version-change";
+/**
+ * One informational line reporting a service whose version has drifted --
+ * either from what the next apply would actually put live (mail, archon,
+ * ai, files, integrations: each already redeploys when its own recorded
+ * applied ref differs from the declared one), or, for a service whose own
+ * step never patches a running app's image tag once created (zitadel,
+ * synapse, mas), from what is actually live. #251: the data to show this
+ * already existed per-service with no line anywhere saying a foundry
+ * release bumping a pinned version, or an operator changing a declared
+ * `gitRef`, had changed what the next apply would do -- or, for the second
+ * group, that it would do nothing at all.
+ *
+ * Never a {@link PlanStep}: it creates or changes nothing live, and is never
+ * passed to a `StepExecutor`.
+ */
+export interface VersionChangeItem {
+    kind: typeof VERSION_CHANGE_KIND;
+    /** The service this line is about, e.g. 'mail', 'archon', 'zitadel'. */
+    service: string;
+    description: string;
 }

package/dist/plan.js

@@ -1 +1,16 @@
-export {};
+/**
+ * The action kind a {@link VersionChangeItem} carries -- a distinct, typed
+ * value so Archon can key off it to render and later gate these lines
+ * (wtfalch/archon#133), and so it is never mistaken for a `StepAction.kind`
+ * (`plan/diff.ts`) any `StepExecutor` dispatches on.
+ *
+ * #251 round 3: an earlier attempt planned these as ordinary `PlanStep`s in
+ * `Plan.steps`. That made a plan holding only version-change lines for
+ * zitadel/synapse/mas (whose own step never re-applies a running app's
+ * image tag -- see {@link VersionChangeItem}) never read as empty, which is
+ * the condition `bootstrap/drive.ts` loops on, and `apply` tried to run a
+ * step for those services that does nothing. Version-change lines are
+ * carried on their own `Plan.versionChanges` field instead, never on
+ * `steps`, so they are display-only everywhere a `Plan` is read.
+ */
+export const VERSION_CHANGE_KIND = 'version-change';

package/dist/store/audit.d.ts

@@ -1,8 +1,40 @@
 import type { AuditLog } from '../plan/plan-apply.js';
 import type { FoundryStoreDb } from './postgres.js';
 /**
- * foundry's own {@link AuditLog}, one row per plan, apply or destroy in
- * `foundry_audit_events` (#85). The CLI uses it before any archon exists; an
- * attached archon reads the same table. It only inserts.
+ * foundry's own {@link AuditLog}, backed by `@wtfalch/audit`'s ledger
+ * (#232) instead of the hand-rolled `foundry_audit_events` table
+ * (`migrations/0012_audit.sql`) this replaces. Every row: `tenantId: null`
+ * (foundry has no tenant of its own -- the org a plan is *for* is the
+ * `target`, not a tenant), `hashChain` on so a changed or deleted row is
+ * detectable (`verifyChain`), through migrations 0024-0028
+ * (`src/migrations/`, copied from `@wtfalch/audit` 0.6.0's own
+ * `migrations/0001-0005`, the same files its own `audit-migrations` CLI
+ * would copy into a host that has a `drizzle/` journal -- foundry does not,
+ * so they are hand-placed at the next free numbers instead).
+ *
+ * The `AuditLog` interface this satisfies is unchanged (`plan-apply.ts`),
+ * so `bootstrap.ts` and `redactingAudit` need no change either.
+ *
+ * Decide (#232, open): whether `foundry_audit_events`' existing rows are
+ * copied into the ledger or left as a closed, separate trail. Left as-is
+ * here -- the simpler default, and the one that forecloses nothing: a
+ * backfill can still be written later, where discarding the old rows
+ * outright could not be undone.
+ *
+ * `checkRuntimeRole` defaults to `true`, `createLedger`'s own default. The
+ * connection must be a restricted role: not a superuser, no BYPASSRLS, and no
+ * UPDATE, DELETE or TRUNCATE on `audit_events`. A call through the owner
+ * connection throws `UnsafeRuntimeRoleError`. The check reads attributes of
+ * the connected role, not its name.
+ *
+ * The host provides that role. After it migrates with the owner URL, it calls
+ * `ensureRuntimeRole` from `@wtfalch/db/runtime-role` with
+ * `appendOnly: ['audit_events']` and the four audit functions in `grants`
+ * (README, "Foundry's own Postgres"), then connects the server as the runtime
+ * role. A test fixture without that split (PGlite's one user is a superuser)
+ * passes `checkRuntimeRole: false`. Options, not a second positional argument
+ * (`CLAUDE.md` rule 7).
  */
-export declare function createPostgresAuditLog(db: FoundryStoreDb): AuditLog;
+export declare function createPostgresAuditLog(db: FoundryStoreDb, options?: {
+    checkRuntimeRole?: boolean;
+}): AuditLog;