@wtfalch/foundry 0.7.1 → 0.8.0

package/dist/plan/platform-providers.js

@@ -1,10 +1,10 @@
 import { createHash, createPrivateKey, generateKeyPairSync, randomBytes, randomUUID, sign, } from 'node:crypto';
 import { isIPv4 } from 'node:net';
-import { VERSIONS } from '../bootstrap/versions.js';
+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) {
@@ -93,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;
@@ -106,6 +110,7 @@ export class FoundryPlatformStepExecutor {
     files;
     ai;
     archon;
+    backup;
     constructor(cloudflare, declaredOrgStore, options = {}) {
         this.cloudflare = cloudflare;
         this.declaredOrgStore = declaredOrgStore;
@@ -118,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 = {};
@@ -131,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;
@@ -198,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;
     }
     /**
@@ -271,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();
         }
@@ -809,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);
@@ -1520,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) {
@@ -1933,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) {
@@ -3836,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);
@@ -4339,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
@@ -4393,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.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

@@ -21,23 +21,19 @@ import type { FoundryStoreDb } from './postgres.js';
  * backfill can still be written later, where discarding the old rows
  * outright could not be undone.
  *
- * `checkRuntimeRole` defaults to `false` here, the opposite of
- * `createLedger`'s own default (#232, needs a human call -- flagged
- * `ai:needs-human`, not decided here): that check requires the connection
- * to be a real, restricted `<database>_rt` role, the one 0001's migration
- * revokes UPDATE/DELETE/TRUNCATE from by name
- * (`current_database() || '_rt'`). foundry has no such role for its own
- * database -- `FOUNDRY_DATABASE_URL` is one connection, no owner/runtime
- * split the way archon's, manage's or lokessmie's own `DATABASE_URL_OWNER`/
- * `DATABASE_URL` pair is (see #239, the same split for a *hosted* app's
- * database -- this is foundry's *own*). Leaving the default on would make
- * every real call throw `UnsafeRuntimeRoleError`, since the revoke in
- * 0001_audit.sql never ran against whatever role `FOUNDRY_DATABASE_URL`
- * actually is; the append-only guard and the chain still hold at the
- * database level regardless (0001's triggers, 0004's hashing), only the
- * extra fail-closed check on the *connection* is off. Options, not a second
- * positional argument (`CLAUDE.md` rule 7): a caller -- today only a test
- * fixture -- can pass `true` once foundry's own database gets that split.
+ * `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, options?: {
     checkRuntimeRole?: boolean;

package/dist/store/audit.js

@@ -61,29 +61,25 @@ function boundPlan(plan) {
  * backfill can still be written later, where discarding the old rows
  * outright could not be undone.
  *
- * `checkRuntimeRole` defaults to `false` here, the opposite of
- * `createLedger`'s own default (#232, needs a human call -- flagged
- * `ai:needs-human`, not decided here): that check requires the connection
- * to be a real, restricted `<database>_rt` role, the one 0001's migration
- * revokes UPDATE/DELETE/TRUNCATE from by name
- * (`current_database() || '_rt'`). foundry has no such role for its own
- * database -- `FOUNDRY_DATABASE_URL` is one connection, no owner/runtime
- * split the way archon's, manage's or lokessmie's own `DATABASE_URL_OWNER`/
- * `DATABASE_URL` pair is (see #239, the same split for a *hosted* app's
- * database -- this is foundry's *own*). Leaving the default on would make
- * every real call throw `UnsafeRuntimeRoleError`, since the revoke in
- * 0001_audit.sql never ran against whatever role `FOUNDRY_DATABASE_URL`
- * actually is; the append-only guard and the chain still hold at the
- * database level regardless (0001's triggers, 0004's hashing), only the
- * extra fail-closed check on the *connection* is off. Options, not a second
- * positional argument (`CLAUDE.md` rule 7): a caller -- today only a test
- * fixture -- can pass `true` once foundry's own database gets that split.
+ * `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 function createPostgresAuditLog(db, options = {}) {
     const ledger = createLedger({
         vocabulary: FOUNDRY_LEDGER_VOCABULARY,
         hashChain: true,
-        checkRuntimeRole: options.checkRuntimeRole ?? false,
+        checkRuntimeRole: options.checkRuntimeRole,
     });
     const targetFor = (orgId, target) => ({
         type: target === 'platform' ? 'platform' : 'org',

package/dist/store/postgres.d.ts

@@ -7,6 +7,20 @@ import type { DeclaredOrgStore, PlatformStore, RequestedChangeStore } from '../s
  * connection itself.
  */
 export type FoundryStoreDb = PgDatabase<PgQueryResultHKT, any, any>;
+/**
+ * The Postgres unique-violation constraint name, however the driver hands the
+ * error back -- directly (PGlite in this package's own tests) or wrapped in
+ * drizzle-orm's own `DrizzleQueryError`, whose `cause` carries the raw driver
+ * error (postgres-js in a host) -- or `undefined` when this is not a unique
+ * violation. Checked by Postgres error code, never by message text, since
+ * message text is not a contract. Same code-check pattern as
+ * `../runner/runner.ts`'s own `isUniqueViolation` -- kept as a local copy
+ * here rather than shared, since neither module depends on the other; this
+ * one additionally reads the constraint name (`constraint` under node-postgres and PGlite, `constraint_name` under postgres-js) so `create`/`update` can tell a slug
+ * collision from a domain collision (#131) rather than reporting both the
+ * same way.
+ */
+export declare function uniqueViolationConstraint(error: unknown): string | undefined;
 /**
  * Thrown by `create` and `update` when the store refuses a write: an id
  * that already exists, an id that does not, a slug that fails

package/dist/store/postgres.js

@@ -19,17 +19,22 @@ const NON_NEGATIVE_INTEGER = /^(0|[1-9]\d*)$/;
  * message text is not a contract. Same code-check pattern as
  * `../runner/runner.ts`'s own `isUniqueViolation` -- kept as a local copy
  * here rather than shared, since neither module depends on the other; this
- * one additionally reads `constraint` so `create`/`update` can tell a slug
+ * one additionally reads the constraint name (`constraint` under node-postgres and PGlite, `constraint_name` under postgres-js) so `create`/`update` can tell a slug
  * collision from a domain collision (#131) rather than reporting both the
  * same way.
  */
-function uniqueViolationConstraint(error) {
-    const direct = error;
-    if (direct?.code === UNIQUE_VIOLATION)
-        return direct.constraint;
-    const cause = error?.cause;
-    if (cause?.code === UNIQUE_VIOLATION)
-        return cause.constraint;
+export function uniqueViolationConstraint(error) {
+    // Walk `cause`: drizzle-orm wraps the driver error, and how deep differs by version. Bounded so a cyclic `cause` ends.
+    let current = error;
+    for (let depth = 0; depth < 5 && current !== null && typeof current === 'object'; depth += 1) {
+        const e = current;
+        if (e.code === UNIQUE_VIOLATION) {
+            // node-postgres spells it `constraint`; postgres-js spells it `constraint_name`.
+            const name = e.constraint ?? e.constraint_name;
+            return typeof name === 'string' ? name : undefined;
+        }
+        current = e.cause;
+    }
     return undefined;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",
@@ -15,6 +15,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./migrations-dir": {
+      "types": "./dist/migrations-dir.d.ts",
+      "default": "./dist/migrations-dir.js"
+    },
     "./migrations/*.sql": "./dist/migrations/*.sql",
     "./package.json": "./package.json"
   },
@@ -30,7 +34,6 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "db:provision": "node scripts/foundry-db-provision.mjs",
-    "db:migrate": "node scripts/foundry-db-migrate.mjs",
     "calls-sfu:deploy": "node scripts/calls-sfu-deploy.mjs"
   },
   "peerDependencies": {
@@ -47,8 +50,8 @@
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.8",
     "@types/node": "^22",
+    "@wtfalch/db": "0.5.2",
     "drizzle-orm": "0.45.2",
-    "postgres": "3.4.9",
     "typescript": "^5.9.0",
     "vitest": "^4.1.6"
   }

package/versions.json

@@ -2,7 +2,7 @@
   "zitadel": "v4.17.3",
   "synapse": "v1.161.0",
   "mas": "1.24.0",
-  "livekit": "latest",
+  "livekit": "v1.13.7",
   "cloudflared": "2026.9.3",
   "stalwart": "v0.16.24"
 }

package/dist/migrate.d.ts

@@ -1,38 +0,0 @@
-/** This package's own migrations -- `../migrations` from `src/`, `./migrations` once built to `dist/` (`package.json`'s `build` script copies the `.sql` files there alongside `migrate.js`). */
-export declare const MIGRATIONS_DIR: string;
-/**
- * The one capability `migrate` needs from a driver: run SQL text (one
- * statement or several) and run a callback inside a transaction. Deliberately
- * not a drizzle `PgDatabase` or a concrete driver type -- drizzle's own
- * `.execute()` routes a multi-statement string through a single prepared
- * query on PGlite, which rejects it, so a migration file's raw text has to
- * reach the driver's own multi-statement path (`postgres`'s `.unsafe()`,
- * PGlite's `.exec()`) instead. Same "narrow port, no concrete client type"
- * shape `plan/executor.ts`'s `CoolifyPort` uses, for the same reason: a real
- * driver satisfies this structurally, with a few lines of adapter at the
- * call site (see `scripts/foundry-db-migrate.mjs` and `migrate.test.ts`).
- */
-export interface MigrateSql {
-    /** Run SQL text and discard any result -- the tracking table's own DDL, and each migration file's contents. */
-    exec(text: string): Promise<void>;
-    /**
-     * Run one literal SELECT and return its rows. Only ever called here with
-     * fixed text this module builds itself (the tracking table's name, and a
-     * migration filename already checked against `/^\d{4}_.+\.sql$/`), so
-     * there is no external input to inject.
-     */
-    query<T = Record<string, unknown>>(text: string): Promise<T[]>;
-    /** Run `fn` inside one transaction, handing it a `MigrateSql` scoped to it; rolled back if `fn` throws. */
-    transaction<T>(fn: (tx: MigrateSql) => Promise<T>): Promise<T>;
-}
-export interface MigrationResult {
-    /** Names of the migration files applied this run, in filename order -- empty when the database was already current. */
-    applied: string[];
-}
-/**
- * Applies every migration file in `dir` (default: this package's own
- * `../migrations`) not yet recorded in `foundry_schema_migrations`, in
- * filename order, one transaction per file. Safe to call repeatedly: a file
- * already recorded is never re-read, let alone re-run.
- */
-export declare function migrate(sql: MigrateSql, dir?: string): Promise<MigrationResult>;

package/dist/migrate.js

@@ -1,47 +0,0 @@
-import { readFileSync, readdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-// #R2 (map gap: foundry's own Postgres, two commands): a tracked, idempotent
-// migration runner. `./test/db.ts` and `./runner/test/db.ts` already read
-// and sort this same directory to build one concatenated blob for a fresh
-// PGlite -- fine for a test fixture that always starts empty, wrong for a
-// real host that must apply only what a `foundry_schema_migrations` table
-// does not yet list. `migrationFiles` below is that same discovery, reused
-// rather than re-implemented, kept per-file instead of concatenated.
-const here = dirname(fileURLToPath(import.meta.url));
-/** This package's own migrations -- `../migrations` from `src/`, `./migrations` once built to `dist/` (`package.json`'s `build` script copies the `.sql` files there alongside `migrate.js`). */
-export const MIGRATIONS_DIR = join(here, 'migrations');
-const TRACKING_TABLE = 'foundry_schema_migrations';
-function migrationFiles(dir) {
-    return readdirSync(dir)
-        .filter((f) => /^\d{4}_.+\.sql$/.test(f))
-        .sort()
-        .map((name) => ({ name, path: join(dir, name) }));
-}
-/**
- * Applies every migration file in `dir` (default: this package's own
- * `../migrations`) not yet recorded in `foundry_schema_migrations`, in
- * filename order, one transaction per file. Safe to call repeatedly: a file
- * already recorded is never re-read, let alone re-run.
- */
-export async function migrate(sql, dir = MIGRATIONS_DIR) {
-    await sql.exec(`create table if not exists ${TRACKING_TABLE} (name text primary key, applied_at timestamptz not null default now())`);
-    const appliedRows = await sql.query(`select name from ${TRACKING_TABLE}`);
-    const applied = new Set(appliedRows.map((row) => row.name));
-    const pending = migrationFiles(dir).filter((file) => !applied.has(file.name));
-    const done = [];
-    for (const file of pending) {
-        const text = readFileSync(file.path, 'utf8');
-        await sql.transaction(async (tx) => {
-            await tx.exec(text);
-            // `file.name` is drawn from `migrationFiles`' own regex-filtered
-            // `readdirSync`, never from outside this module -- see `MigrateSql`'s
-            // doc comment. Quotes are still escaped, so an oddly-named future
-            // migration file cannot break the statement.
-            const escaped = file.name.replace(/'/g, "''");
-            await tx.exec(`insert into ${TRACKING_TABLE} (name) values ('${escaped}')`);
-        });
-        done.push(file.name);
-    }
-    return { applied: done };
-}