@wtfalch/foundry 0.16.3 → 0.16.5

package/dist/org.js

@@ -82,6 +82,10 @@ export function validateHosting(hosting, names) {
         if (app.name === 'agora') {
             return `issuerApps '${app.name}' is reserved for the always-on Agora client every org gets`;
         }
+        // #161: the same for the always-on Boule client.
+        if (app.name === 'boule') {
+            return `issuerApps '${app.name}' is reserved for the always-on Boule client every org gets`;
+        }
     }
     if (hosting.enabled && !appEntry(hosting)) {
         return `hosting.enabled requires an entry keyed '${APP_ENTRY_KEY}'`;
@@ -256,6 +260,7 @@ function validateEntryAuth(entry, hosting, domain) {
         return `${at} needs an exact hostname to sign in at`;
     }
     if (entry.key === 'agora' ||
+        entry.key === 'boule' ||
         entry.key === 'cms' ||
         hosting.issuerApps.some((app) => app.name === entry.key)) {
         return `${at} client name '${entry.key}' is already held by another ZITADEL client`;

package/dist/plan/boule.d.ts

@@ -0,0 +1,67 @@
+import type { DeclaredOrg } from '../org.js';
+import type { BrokerEntryInput, BrokerEntryWant } from './broker-entries.js';
+/**
+ * #161 (Boule part): what both the planner (`diff.ts`) and the executor
+ * (`executor.ts`) need to agree on for an org's Boule -- the hostname, the
+ * recorded ids and the env vars those produce -- so the plan can compare the
+ * live app with exactly what the executor would write. The same split as
+ * `agora.ts`, for the same reason.
+ */
+/**
+ * The fixed `boule` ZITADEL web client's `clientId`, recorded by
+ * `executor.ts`'s `zitadelApp` and read by `coolifyBoule` for
+ * `AUTH_CLIENT_ID`. Public, not a secret, so a flat scope id like
+ * `agora_client_id`.
+ */
+export declare const BOULE_CLIENT_ID_SCOPE_KEY = "boule_client_id";
+/**
+ * The Boule database's Coolify uuid. It has no `system:kind:key` slot of its
+ * own (the step's one auto-recorded `resourceId` is the app), so it is a flat
+ * scope id, like the cms and calls databases.
+ */
+export declare const BOULE_DATABASE_SCOPE_KEY = "coolify_boule_database";
+/**
+ * `boule.<domain>` when the org has a domain, `<slug>-boule.oikos.host`
+ * otherwise (the tier rule of boule#128 and foundry#147; `../slug.ts`'s
+ * `BOULE_SUFFIX` reserves the collision). A subdomain, not a path: an org's
+ * Boule is its own deploy, a separate origin and a separate application at the
+ * issuer.
+ */
+export declare function bouleHostnameFor(org: DeclaredOrg): string;
+/** The env names `desiredBouleEnv` can write, so the live reader knows which to read back. */
+export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER", "AUTH_ORGANIZATION_ID", "AUTH_CLIENT_ID", "BOULE_ORG_NAME", "AUTHZ_BOOTSTRAP_OPERATOR"];
+/**
+ * The env vars an org's Boule app should carry, and every input still missing
+ * to build them. Callers that write must refuse on a non-empty `missing`: a
+ * Boule with a blank client id fails every sign-in. `issuer` is the host's
+ * issuer address (`AgoraHostValues.issuer`), the same one Agora signs in at.
+ *
+ * `AUTHZ_BOOTSTRAP_OPERATOR` is the declared first owner's ZITADEL user id
+ * (the subject Boule's `bootstrapOperator` compares with the signed-in user's
+ * id, never an email), present once `zitadel:owner` has recorded it. It is not
+ * `missing` while absent: Boule runs without an operator until then.
+ *
+ * Not here, and written by the executor instead: the database URLs
+ * (`DATABASE_URL_OWNER`, `DATABASE_URL`, minted once) and `AUTH_COOKIE_SECRET`
+ * (generated once, never rotated).
+ */
+export declare function desiredBouleEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, issuer: string | null): {
+    env: Record<string, string>;
+    missing: string[];
+};
+/** The `AUTH_APPS` name of an org's Boule broker entry, and the scope key suffix it records under. */
+export declare const BOULE_BROKER_ENTRY_KEY = "boule";
+export declare function bouleBrokerEntryName(org: DeclaredOrg): string;
+/**
+ * What the org's Boule broker entry must say (the same shape a hosting entry
+ * with `uses.auth` gets, `broker-entries.ts`'s `wantedBrokerEntry`): staff
+ * sign in, no sign-up, the one origin of the Boule hostname. Or the inputs
+ * still missing, each with the step that records it.
+ */
+export declare function wantedBouleBrokerEntry(org: DeclaredOrg, recorded: Readonly<Record<string, string>>): {
+    want: BrokerEntryWant;
+} | {
+    missing: BrokerEntryInput[];
+};
+/** The desired env keys the live app lacks or holds a different value for. Extra live keys are ignored. */
+export declare function bouleEnvDrift(desired: Readonly<Record<string, string>>, live: Readonly<Record<string, string>>): string[];

package/dist/plan/boule.js

@@ -0,0 +1,126 @@
+import { ZITADEL_ORG_SCOPE_KEY } from './agora.js';
+/**
+ * #161 (Boule part): what both the planner (`diff.ts`) and the executor
+ * (`executor.ts`) need to agree on for an org's Boule -- the hostname, the
+ * recorded ids and the env vars those produce -- so the plan can compare the
+ * live app with exactly what the executor would write. The same split as
+ * `agora.ts`, for the same reason.
+ */
+/**
+ * The fixed `boule` ZITADEL web client's `clientId`, recorded by
+ * `executor.ts`'s `zitadelApp` and read by `coolifyBoule` for
+ * `AUTH_CLIENT_ID`. Public, not a secret, so a flat scope id like
+ * `agora_client_id`.
+ */
+export const BOULE_CLIENT_ID_SCOPE_KEY = 'boule_client_id';
+/**
+ * The Boule database's Coolify uuid. It has no `system:kind:key` slot of its
+ * own (the step's one auto-recorded `resourceId` is the app), so it is a flat
+ * scope id, like the cms and calls databases.
+ */
+export const BOULE_DATABASE_SCOPE_KEY = 'coolify_boule_database';
+/**
+ * `boule.<domain>` when the org has a domain, `<slug>-boule.oikos.host`
+ * otherwise (the tier rule of boule#128 and foundry#147; `../slug.ts`'s
+ * `BOULE_SUFFIX` reserves the collision). A subdomain, not a path: an org's
+ * Boule is its own deploy, a separate origin and a separate application at the
+ * issuer.
+ */
+export function bouleHostnameFor(org) {
+    return org.domain ? `boule.${org.domain}` : `${org.slug}-boule.oikos.host`;
+}
+/** The env names `desiredBouleEnv` can write, so the live reader knows which to read back. */
+export const BOULE_MANAGED_ENV_KEYS = [
+    'APP_URL',
+    'AUTH_ISSUER',
+    'AUTH_ORGANIZATION_ID',
+    'AUTH_CLIENT_ID',
+    'BOULE_ORG_NAME',
+    'AUTHZ_BOOTSTRAP_OPERATOR',
+];
+/**
+ * The env vars an org's Boule app should carry, and every input still missing
+ * to build them. Callers that write must refuse on a non-empty `missing`: a
+ * Boule with a blank client id fails every sign-in. `issuer` is the host's
+ * issuer address (`AgoraHostValues.issuer`), the same one Agora signs in at.
+ *
+ * `AUTHZ_BOOTSTRAP_OPERATOR` is the declared first owner's ZITADEL user id
+ * (the subject Boule's `bootstrapOperator` compares with the signed-in user's
+ * id, never an email), present once `zitadel:owner` has recorded it. It is not
+ * `missing` while absent: Boule runs without an operator until then.
+ *
+ * Not here, and written by the executor instead: the database URLs
+ * (`DATABASE_URL_OWNER`, `DATABASE_URL`, minted once) and `AUTH_COOKIE_SECRET`
+ * (generated once, never rotated).
+ */
+export function desiredBouleEnv(org, recorded, issuer) {
+    const zitadelOrgId = recorded[ZITADEL_ORG_SCOPE_KEY];
+    const clientId = recorded[BOULE_CLIENT_ID_SCOPE_KEY];
+    const missing = [];
+    if (!issuer)
+        missing.push('issuer');
+    if (!zitadelOrgId)
+        missing.push('zitadelOrgId');
+    if (!clientId)
+        missing.push('clientId');
+    const env = {
+        APP_URL: `https://${bouleHostnameFor(org)}`,
+        BOULE_ORG_NAME: org.displayName,
+    };
+    if (issuer)
+        env.AUTH_ISSUER = issuer;
+    if (zitadelOrgId)
+        env.AUTH_ORGANIZATION_ID = zitadelOrgId;
+    if (clientId)
+        env.AUTH_CLIENT_ID = clientId;
+    const owner = org.owners[0];
+    const ownerUserId = owner
+        ? recorded[`zitadel:owner:${org.id}:${owner.email.toLowerCase()}`]
+        : undefined;
+    if (ownerUserId)
+        env.AUTHZ_BOOTSTRAP_OPERATOR = ownerUserId;
+    return { env, missing };
+}
+/** The `AUTH_APPS` name of an org's Boule broker entry, and the scope key suffix it records under. */
+export const BOULE_BROKER_ENTRY_KEY = 'boule';
+export function bouleBrokerEntryName(org) {
+    return `${org.slug}-boule`;
+}
+/**
+ * What the org's Boule broker entry must say (the same shape a hosting entry
+ * with `uses.auth` gets, `broker-entries.ts`'s `wantedBrokerEntry`): staff
+ * sign in, no sign-up, the one origin of the Boule hostname. Or the inputs
+ * still missing, each with the step that records it.
+ */
+export function wantedBouleBrokerEntry(org, recorded) {
+    const organizationId = recorded[ZITADEL_ORG_SCOPE_KEY];
+    const clientId = recorded[BOULE_CLIENT_ID_SCOPE_KEY];
+    const mailDomain = recorded.mail_domain;
+    const missing = [];
+    if (!organizationId) {
+        missing.push({ what: "the org's ZITADEL org id", producedBy: ['zitadel', 'issuer'] });
+    }
+    if (!clientId)
+        missing.push({ what: 'its sign-in client id', producedBy: ['zitadel', 'app'] });
+    if (!mailDomain)
+        missing.push({ what: 'the org mail domain', producedBy: ['coolify', 'mail'] });
+    if (!organizationId || !clientId || !mailDomain)
+        return { missing };
+    return {
+        want: {
+            name: bouleBrokerEntryName(org),
+            organizationId,
+            clientId,
+            origins: [`https://${bouleHostnameFor(org)}`],
+            from: `${org.mail.noReplyLocalPart || 'noreply'}@${mailDomain}`,
+            registration: false,
+            replaces: null,
+        },
+    };
+}
+/** The desired env keys the live app lacks or holds a different value for. Extra live keys are ignored. */
+export function bouleEnvDrift(desired, live) {
+    return Object.entries(desired)
+        .filter(([key, value]) => live[key] !== value)
+        .map(([key]) => key);
+}

package/dist/plan/diff.d.ts

@@ -36,6 +36,8 @@ export interface PlanOrgOptions {
     loginHostBindings?: boolean;
     /** F5: the executor was built with a `broker` port. */
     broker?: boolean;
+    /** #161: the slugs of the other declared orgs, so a Boule whose hostname another org's slug would take is blocked. */
+    otherSlugs?: readonly string[];
     /** F6a, F6b: the clock `planEntryAiKeys` and `planFilesKeys` read for the renewal window. Default `Date.now`. */
     now?: () => number;
 }

package/dist/plan/diff.js

@@ -1,6 +1,7 @@
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY, ownerMailboxRecorded, ownerMailboxes } from '../org.js';
 import { CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraHostMissing, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
+import { BOULE_BROKER_ENTRY_KEY, bouleEnvDrift, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
 import { planEntryAiKeys } from './entry-ai-key.js';
 import { planFilesKeys } from './entry-files-key.js';
@@ -235,6 +236,20 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const agora = planAgora(org, byKey, claimed, recordedIds, agoraHost);
     if (agora.step)
         plannedSteps.push(agora.step);
+    // #161 (Boule part): every org's own Boule -- always on, no toggle, the same
+    // shape as Agora and planned right after it. Its fixed ZITADEL client first,
+    // for the same reason: `coolifyBoule` reads that step's recorded client id.
+    const bouleClient = planBouleClient(org, byKey, claimed);
+    if (bouleClient)
+        plannedSteps.push(bouleClient);
+    const boule = planBoule(org, byKey, claimed, recordedIds, authIssuer, options.otherSlugs ?? []);
+    if (boule.step)
+        plannedSteps.push(boule.step);
+    // Boule's own broker entry, after its app: the entry needs the AUTH_APP_KEY
+    // that step puts in the app's env.
+    const bouleBroker = planBouleBrokerEntry(org, recordedIds, plannedSteps, options.broker ?? false);
+    if (bouleBroker.step)
+        plannedSteps.push(bouleBroker.step);
     // #173: register the org's own app with the platform's jobs scheduler.
     // After Agora, so a failing registration can never stop Agora from
     // provisioning (`runSteps` stops at the first failing step).
@@ -253,6 +268,8 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // item list, so it rides along with the unmanaged items.
     if (agora.blocked)
         unmanaged.push({ description: agora.blocked, key: 'coolify:agora' });
+    if (boule.blocked)
+        unmanaged.push({ description: boule.blocked, key: 'coolify:boule' });
     // Same for an ai key minted but never delivered: planning a new mint would
     // orphan a second live key.
     if (aiKey.blocked)
@@ -307,6 +324,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // #243: an appEnv source nothing will record is reported, not silently skipped.
     unmanaged.push(...app.blocked);
     unmanaged.push(...brokerEntries.blocked);
+    unmanaged.push(...bouleBroker.blocked);
     return { orgId: org.id, plannedSteps, unmanaged, versionChanges };
 }
 /**
@@ -1434,6 +1452,114 @@ function planAgora(org, byKey, claimed, recordedIds, reading) {
         blocked: null,
     };
 }
+/**
+ * #161 (Boule part): every org gets one fixed ZITADEL web client named
+ * `boule`, so its Boule (https://github.com/wtfalch/boule) can sign anyone in.
+ * The same shape as {@link planAgoraClient}: provision when missing, recreate
+ * when the live `appType` differs, nothing otherwise.
+ */
+function planBouleClient(org, byKey, claimed) {
+    const key = resourceKey('zitadel', 'app', 'boule');
+    const live = byKey.get(key);
+    if (live)
+        claimed.add(key);
+    const desired = { appType: 'web' };
+    if (!live) {
+        return {
+            action: { system: 'zitadel', kind: 'app', key: 'boule', desired },
+            step: {
+                description: `provision the web ZITADEL app 'boule' for ${org.slug}'s Boule sign-in`,
+                destroys: false,
+                migrates: false,
+            },
+        };
+    }
+    if (live.config.appType === 'web')
+        return null;
+    return {
+        action: { system: 'zitadel', kind: 'app', key: 'boule', desired },
+        step: {
+            description: `recreate ZITADEL app 'boule' for ${org.slug} as web (was ${String(live.config.appType)})`,
+            destroys: true,
+            migrates: false,
+        },
+    };
+}
+/**
+ * #161 (Boule part): the org's own Boule, a per-org singleton keyed by the org
+ * id under its own `boule` kind, a separate Coolify application from the org's
+ * hosted app and from Agora. Built from https://github.com/wtfalch/boule's
+ * root Dockerfile (`executor.ts`'s `coolifyBoule`), with a database of its
+ * own, never toggled by any declared field and never parked or deleted.
+ *
+ * Once live, a step is planned again whenever the live app's sign-in env lacks
+ * a desired key or holds a different value (`boule.ts`'s `desiredBouleEnv`,
+ * the function the executor writes from). The only host value is the issuer
+ * address (the one Agora signs in at); without it the Boule is blocked, not
+ * planned, so every other step still applies.
+ */
+function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs) {
+    const key = resourceKey('coolify', 'boule', org.id);
+    const live = byKey.get(key);
+    if (live)
+        claimed.add(key);
+    // Never truncated: Postgres cuts an identifier at 63 bytes and Boule finds
+    // its runtime role as `<current_database()>_rt`, so a cut name breaks the
+    // match; a DNS label over 63 is refused by Coolify and Cloudflare.
+    const tooLong = [
+        [`${org.slug}-boule`, 'the Boule host label and app name'],
+        [`${org.slug}_boule_db_rt`, 'the Boule database role'],
+    ].filter(([name]) => name.length > 63);
+    if (tooLong.length > 0) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s Boule is blocked, not planned: ${tooLong.map(([n, what]) => `${what} '${n}' is over 63 characters`).join(', ')}; shorten the slug`,
+        };
+    }
+    if (otherSlugs.includes(`${org.slug}-boule`)) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s Boule is blocked, not planned: another declared org has the slug '${org.slug}-boule', which is this Boule's hostname`,
+        };
+    }
+    if (!issuer) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s Boule is blocked, not planned: the host supplies no issuer`,
+        };
+    }
+    const action = {
+        system: 'coolify',
+        kind: 'boule',
+        key: org.id,
+        desired: { issuer },
+    };
+    if (!live) {
+        return {
+            step: {
+                action,
+                step: { description: `provision ${org.slug}'s Boule`, destroys: false, migrates: false },
+            },
+            blocked: null,
+        };
+    }
+    const liveEnv = (live.config.env ?? {});
+    const { env } = desiredBouleEnv(org, recordedIds, issuer);
+    const drift = bouleEnvDrift(env, liveEnv);
+    if (drift.length === 0)
+        return { step: null, blocked: null };
+    return {
+        step: {
+            action,
+            step: {
+                description: `update ${org.slug}'s Boule config (${drift.join(', ')} missing or different)`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}
 /**
  * The shared on/off shape behind {@link planApp}, {@link planDatabase} and
  * {@link planTunnel} (#71): a per-org singleton resource, keyed by the org
@@ -2094,6 +2220,70 @@ function planBrokerEntries(org, recordedIds, plannedSteps, brokerWired) {
     }
     return { steps, blocked };
 }
+/**
+ * #161: the org's Boule broker entry (`<slug>-boule`), planned like a hosting
+ * entry's ({@link planBrokerEntries}): blocked while the host has not wired
+ * the broker port, or while an input is neither recorded nor produced by a
+ * step in this plan; nothing once the recorded marker matches what it would
+ * write. Silent while no Boule app exists or is planned (a blocked Boule
+ * already says why).
+ */
+function planBouleBrokerEntry(org, recordedIds, plannedSteps, brokerWired) {
+    const at = `${org.slug}'s Boule broker entry`;
+    const key = 'coolify:boule-broker-entry';
+    const blocked = [];
+    const warnings = recordedIds[brokerEntryWarningsScopeKey(BOULE_BROKER_ENTRY_KEY)];
+    for (const name of warnings ? JSON.parse(warnings) : []) {
+        blocked.push({
+            description: `warning: the broker's AUTH_APPS entry '${name}' is invalid and the broker drops it; foundry leaves it as it is`,
+            key: `${key}:invalid:${name}`,
+        });
+    }
+    const hasApp = Boolean(recordedIds[`coolify:boule:${org.id}`]) ||
+        plannedSteps.some((p) => p.action.system === 'coolify' && p.action.kind === 'boule');
+    if (!hasApp)
+        return { step: null, blocked };
+    if (!brokerWired) {
+        blocked.push({
+            description: `${at} is blocked, not planned: the host has not wired the broker port`,
+            key,
+        });
+        return { step: null, blocked };
+    }
+    const wanted = wantedBouleBrokerEntry(org, recordedIds);
+    if ('want' in wanted) {
+        if (recordedIds[brokerEntryAppliedScopeKey(BOULE_BROKER_ENTRY_KEY)] ===
+            JSON.stringify(wanted.want)) {
+            return { step: null, blocked };
+        }
+    }
+    else {
+        const unplanned = wanted.missing.filter(({ producedBy: [system, kind] }) => !plannedSteps.some((p) => p.action.system === system && p.action.kind === kind));
+        if (unplanned.length > 0) {
+            // With mail off nothing records a mail domain, so the Boule app is up
+            // while nobody can sign in to it: say so rather than "not recorded yet".
+            const noMail = org.mail.mode === 'off' && unplanned.some((m) => m.producedBy[1] === 'mail');
+            blocked.push({
+                description: noMail
+                    ? `${at} is blocked, not planned: ${org.slug}'s Boule is deployed but sign-in is down until the org's mail records a domain`
+                    : `${at} is blocked, not planned: ${unplanned.map((m) => m.what).join(', ')} not recorded yet`,
+                key,
+            });
+            return { step: null, blocked };
+        }
+    }
+    return {
+        step: {
+            action: { system: 'coolify', kind: 'boule-broker-entry', key: org.id, desired: {} },
+            step: {
+                description: `write ${at} beside the others`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked,
+    };
+}
 /**
  * Plan gap A9: an org's customers sign in through a second ZITADEL org with
  * self-registration on, granted the org's app project. Planned once an entry

package/dist/plan/executor.d.ts

@@ -237,6 +237,8 @@ export interface CoolifyPort {
         name?: string;
         description?: string;
         instant_deploy?: boolean;
+        /** Extra `docker run` options (`--entrypoint "..."` becomes the compose entrypoint). */
+        custom_docker_run_options?: string;
         /**
          * `host:container`, comma separated -- publishes host ports directly
          * (`@wtfalch/providers`' `CoolifyClient.createDockerImageApplication`
@@ -1377,6 +1379,14 @@ export declare function getDatabaseStarted(coolify: {
     internal_db_url?: string;
     status?: string;
 }>;
+/** Timing for the wait in {@link getDatabaseStarted}; a test swaps `sleep` and `now` for a fake clock. */
+export declare const databaseStartWait: {
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+    pollMs: number;
+    timeoutMs: number;
+    graceMs: number;
+};
 export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer {
     private readonly ports;
     constructor(ports: FoundryStepExecutorPorts);
@@ -1603,6 +1613,14 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * broker would drop.
      */
     private coolifyBrokerEntry;
+    /**
+     * #161: the org's Boule broker entry, `<slug>-boule`, written the way a
+     * hosting entry's is: with the `AUTH_APP_KEY` `coolifyBoule` put in the
+     * Boule app's env.
+     */
+    private bouleBrokerEntry;
+    /** The shared tail of both broker-entry steps: read the app's key, write the entry, record what was written. */
+    private writeAppBrokerEntry;
     /**
      * `null` once the app already has one -- `AUTH_COOKIE_SECRET` is generated
      * only the first time (task brief), never regenerated or overwritten, so a
@@ -1996,6 +2014,30 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * not the host values).
      */
     private coolifyAgora;
+    /**
+     * `plan/diff.ts`'s `planBoule`: provisions the org's own Boule
+     * (https://github.com/wtfalch/boule) as one more Coolify application, from
+     * that repo's root Dockerfile ({@link BOULE_REPO}), with a database of its
+     * own, and pushes its env. The same shape as {@link coolifyAgora}. There is
+     * no park branch: Boule is always on.
+     *
+     * The sign-in env comes from `plan/boule.ts`'s `desiredBouleEnv`, the same
+     * function the plan compares the live app against. The step never writes a
+     * partial set: when the issuer (carried in the step), the org's ZITADEL org
+     * id or the Boule client id is missing it throws naming each one, before it
+     * creates anything.
+     *
+     * The database is `<slug>-boule-db`, split like the cms app's (#117, #239):
+     * the superuser URL as `DATABASE_URL_OWNER` (Boule's boot script migrates
+     * with it, then unsets it) and a `<dbName>_rt` role's URL as `DATABASE_URL`,
+     * minted once and never rotated. `AUTH_COOKIE_SECRET` is generated once the
+     * same way. A running app is restarted when its sign-in env or database URLs
+     * changed, since a container reads its env only at start.
+     *
+     * `AUTH_APP_KEY` is minted once here; its broker entry is the next step
+     * (`bouleBrokerEntry`).
+     */
+    private coolifyBoule;
     /**
      * `plan/diff.ts`'s `planJobsRegistration`: registers the org's own app with
      * the platform's jobs scheduler (`JobsSchedulerPort.registerProject`, the

package/dist/plan/executor.js

@@ -3,6 +3,7 @@ import { URL } from 'node:url';
 import { CALLS_SFU_PRIVATE_URL, CALLS_SFU_PUBLIC_URL } from '../calls-sfu.js';
 import { APP_ENTRY_KEY, appEntry, filesCollectionEnvName, ownerMailboxRecorded, ownerMailboxes, } from '../org.js';
 import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_NAME_SCOPE_KEY, CALLS_SERVICE_PORT, CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY, CHAT_SERVICE_URL_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, ZITADEL_MESSAGING_PROJECT_SCOPE_KEY, ZITADEL_ORG_SCOPE_KEY, agoraHostnameFor, callsIntrospectionAppName, callsServiceHasName, callsServiceInternalName, callsTokenEnvMarker, callsTokenEnvMovedMessage, desiredAgoraEnv, entryClientIdScopeKey, } from './agora.js';
+import { BOULE_BROKER_ENTRY_KEY, BOULE_CLIENT_ID_SCOPE_KEY, BOULE_DATABASE_SCOPE_KEY, bouleEnvDrift, bouleHostnameFor, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, writeBrokerEntry, } from './broker-entries.js';
 import { MAS_IMAGE, MAS_TAG, SYNAPSE_IMAGE, SYNAPSE_TAG, callsMasConfigYaml, callsServerName, callsSynapseHomeserverYaml, mintCallsMatrixSecrets, parseCallsDbUrl, } from './calls-matrix.js';
 import { CHAT_REPO, CHAT_SERVICE_DOCKERFILE, CHAT_SERVICE_PORT, CHAT_SYNAPSE_DOCKERFILE, CHAT_SYNAPSE_PORT, chatInternalNames, chatMasConfigYaml, chatServiceEnvs, chatSynapseHomeserverYaml, chatUpstreams, } from './chat-matrix.js';
@@ -226,6 +227,16 @@ const CMS_SITE_APP_DOCKERFILE = '/apps/site/Dockerfile';
  */
 const AGORA_REPO = 'wtfalch/agora';
 const AGORA_APP_DOCKERFILE = '/apps/agora/Dockerfile';
+/**
+ * #161 (Boule part): the repo `coolifyBoule` builds the org's Boule from
+ * (https://github.com/wtfalch/boule), by the same convention as
+ * {@link AGORA_REPO}: Coolify's github-app build from the repo, never a
+ * registry image. Boule's own Dockerfile is at the repository root, serves on
+ * 3000 (`EXPOSE 3000`) and runs `scripts/migrate-and-start.sh`, which applies
+ * its migrations as the owner and then serves as the `<database>_rt` role.
+ */
+const BOULE_REPO = 'wtfalch/boule';
+const BOULE_APP_DOCKERFILE = '/Dockerfile';
 /**
  * Every app foundry deploys keeps its own logs across a redeploy, so a
  * database outage does not also erase the only other copy of the evidence
@@ -559,12 +570,35 @@ export function isRunningOrStarting(status) {
  * instead of `getDatabase`. Returns what `getDatabase` returned.
  */
 export async function getDatabaseStarted(coolify, dbId) {
-    const db = await coolify.getDatabase(dbId);
-    if (db.status !== undefined && !db.status.startsWith('running')) {
-        await coolify.raw('POST', `/databases/${dbId}/start`);
+    let db = await coolify.getDatabase(dbId);
+    if (db.status === undefined || db.status.startsWith('running'))
+        return db;
+    await coolify.raw('POST', `/databases/${dbId}/start`);
+    // Coolify reports `running` before Postgres accepts connections, and the app
+    // deployed next (a migrate step) connects at once. Wait for `running*`, then
+    // a fixed grace. A database already running returned above and never waits.
+    const { sleep, now, pollMs, timeoutMs, graceMs } = databaseStartWait;
+    const deadline = now() + timeoutMs;
+    for (;;) {
+        await sleep(pollMs);
+        db = await coolify.getDatabase(dbId);
+        if (db.status?.startsWith('running'))
+            break;
+        if (now() >= deadline) {
+            throw new Error(`Database ${dbId} did not reach "running" within ${timeoutMs / 1000}s (last status: ${db.status ?? 'unknown'}). Retry the apply.`);
+        }
     }
+    await sleep(graceMs);
     return db;
 }
+/** Timing for the wait in {@link getDatabaseStarted}; a test swaps `sleep` and `now` for a fake clock. */
+export const databaseStartWait = {
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    now: () => Date.now(),
+    pollMs: 2000,
+    timeoutMs: 120_000,
+    graceMs: 5000,
+};
 // ---------------------------------------------------------------------------
 // Executor
 // ---------------------------------------------------------------------------
@@ -632,6 +666,10 @@ export class FoundryStepExecutor {
                 return this.cmsSite(action, org, context);
             case 'coolify:agora':
                 return this.coolifyAgora(action, org, context);
+            case 'coolify:boule':
+                return this.coolifyBoule(action, org, context);
+            case 'coolify:boule-broker-entry':
+                return this.bouleBrokerEntry(org, context);
             case 'jobs:registration':
                 return this.jobsRegistration(action, org, context);
             default:
@@ -1052,11 +1090,17 @@ export class FoundryStepExecutor {
         // `OIDC_AUTH_METHOD_TYPE_NONE`, no secret), which is what Agora's browser
         // SPA needs. Providers cannot create ZITADEL's `USER_AGENT` app kind.
         const isAgoraClient = action.key === 'agora';
+        // #161: the fixed `boule` client signs people into the org's Boule at its
+        // own hostname, on the standard `/auth/callback` path (Boule is built on
+        // `@wtfalch/auth` like every other web app here).
+        const isBouleClient = action.key === 'boule';
         const hostname = isCmsClient
             ? cmsHostnameFor(org)
             : isAgoraClient
                 ? agoraHostnameFor(org)
-                : appHostname(org);
+                : isBouleClient
+                    ? bouleHostnameFor(org)
+                    : appHostname(org);
         // Native apps sign in via device code, with no redirect of their own
         // (auth/scripts/provision.mjs:475-497, prior art cited in the decisions
         // file) -- empty arrays rather than a web app's callback/logout URLs.
@@ -1099,9 +1143,11 @@ export class FoundryStepExecutor {
                 ? CMS_CLIENT_ID_SCOPE_KEY
                 : isAgoraClient
                     ? AGORA_CLIENT_ID_SCOPE_KEY
-                    : authEntry
-                        ? entryClientIdScopeKey(action.key)
-                        : APP_CLIENT_ID_SCOPE_KEY, created.clientId);
+                    : isBouleClient
+                        ? BOULE_CLIENT_ID_SCOPE_KEY
+                        : authEntry
+                            ? entryClientIdScopeKey(action.key)
+                            : APP_CLIENT_ID_SCOPE_KEY, created.clientId);
         }
         return { resourceId: created.appId };
     }
@@ -1635,20 +1681,46 @@ export class FoundryStepExecutor {
         if (!appId) {
             throw new Error(`coolify:broker-entry for ${org.slug}: app ${action.key} is not recorded yet`);
         }
+        await this.writeAppBrokerEntry(org, broker, entry.key, wanted.want, appId, context);
+        return {};
+    }
+    /**
+     * #161: the org's Boule broker entry, `<slug>-boule`, written the way a
+     * hosting entry's is: with the `AUTH_APP_KEY` `coolifyBoule` put in the
+     * Boule app's env.
+     */
+    async bouleBrokerEntry(org, context) {
+        const broker = this.ports.broker;
+        if (!broker) {
+            throw new Error(`coolify:boule-broker-entry for ${org.slug}: the broker port is not wired`);
+        }
+        const recorded = context.recordedIds();
+        const wanted = wantedBouleBrokerEntry(org, recorded);
+        if ('missing' in wanted) {
+            throw new Error(`coolify:boule-broker-entry for ${org.slug}: ${wanted.missing.map((m) => m.what).join(', ')} not recorded yet`);
+        }
+        const appId = recorded[`coolify:boule:${org.id}`];
+        if (!appId) {
+            throw new Error(`coolify:boule-broker-entry for ${org.slug}: the Boule app is not recorded yet`);
+        }
+        await this.writeAppBrokerEntry(org, broker, BOULE_BROKER_ENTRY_KEY, wanted.want, appId, context);
+        return {};
+    }
+    /** The shared tail of both broker-entry steps: read the app's key, write the entry, record what was written. */
+    async writeAppBrokerEntry(org, broker, entryKey, want, appId, context) {
         const appKey = (await this.ports.coolify.listEnvs(appId)).find((e) => e.key === 'AUTH_APP_KEY' && !e.is_preview)?.value;
         if (!appKey || appKey.length < 32) {
             throw new Error(`coolify:broker-entry for ${org.slug}: app ${appId} has no AUTH_APP_KEY yet`);
         }
-        const previousRaw = recorded[brokerEntryAppliedScopeKey(entry.key)];
+        const previousRaw = context.recordedIds()[brokerEntryAppliedScopeKey(entryKey)];
         const result = await writeBrokerEntry(broker, {
-            want: wanted.want,
+            want,
             appKey,
             previous: previousRaw ? JSON.parse(previousRaw) : null,
         });
-        context.recordScopeId(brokerEntryWarningsScopeKey(entry.key), JSON.stringify(result.invalidForeign));
+        context.recordScopeId(brokerEntryWarningsScopeKey(entryKey), JSON.stringify(result.invalidForeign));
         // Last: a run that failed above plans the step again.
-        context.recordScopeId(brokerEntryAppliedScopeKey(entry.key), JSON.stringify(wanted.want));
-        return {};
+        context.recordScopeId(brokerEntryAppliedScopeKey(entryKey), JSON.stringify(want));
     }
     /**
      * `null` once the app already has one -- `AUTH_COOKIE_SECRET` is generated
@@ -2958,6 +3030,84 @@ export class FoundryStepExecutor {
         await this.ports.coolify.bulkUpsertEnvs(app.appId, Object.entries(env).map(([key, value]) => ({ key, value })));
         return { resourceId: app.appId };
     }
+    // ---- boule (#161) --------------------------------------------------------
+    /**
+     * `plan/diff.ts`'s `planBoule`: provisions the org's own Boule
+     * (https://github.com/wtfalch/boule) as one more Coolify application, from
+     * that repo's root Dockerfile ({@link BOULE_REPO}), with a database of its
+     * own, and pushes its env. The same shape as {@link coolifyAgora}. There is
+     * no park branch: Boule is always on.
+     *
+     * The sign-in env comes from `plan/boule.ts`'s `desiredBouleEnv`, the same
+     * function the plan compares the live app against. The step never writes a
+     * partial set: when the issuer (carried in the step), the org's ZITADEL org
+     * id or the Boule client id is missing it throws naming each one, before it
+     * creates anything.
+     *
+     * The database is `<slug>-boule-db`, split like the cms app's (#117, #239):
+     * the superuser URL as `DATABASE_URL_OWNER` (Boule's boot script migrates
+     * with it, then unsets it) and a `<dbName>_rt` role's URL as `DATABASE_URL`,
+     * minted once and never rotated. `AUTH_COOKIE_SECRET` is generated once the
+     * same way. A running app is restarted when its sign-in env or database URLs
+     * changed, since a container reads its env only at start.
+     *
+     * `AUTH_APP_KEY` is minted once here; its broker entry is the next step
+     * (`bouleBrokerEntry`).
+     */
+    async coolifyBoule(action, org, context) {
+        // The issuer the plan read, carried in the step: the env written is the
+        // env the plan showed.
+        const issuer = action.desired.issuer ?? null;
+        const { env, missing } = desiredBouleEnv(org, context.recordedIds(), issuer);
+        if (missing.length > 0) {
+            throw new Error(`Boule for ${org.slug} cannot be configured: missing ${missing.join(', ')}. Nothing was written.`);
+        }
+        const projectUuid = await this.ensureCoolifyProject(org, context);
+        const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
+        const name = `${org.slug}-boule`;
+        const dbName = `${org.slug}-boule-db`.replace(/-/g, '_');
+        const dbId = await this.ensureCallsDatabase(context, projectUuid, environment, `${org.slug}-boule-db`, dbName, BOULE_DATABASE_SCOPE_KEY);
+        context.recordScopeId(BOULE_DATABASE_SCOPE_KEY, dbId);
+        const server = await this.resolveServer();
+        const githubApp = await this.ports.coolify.requireGithubApp();
+        const app = await this.findOrCreateCallsApp(name, environment.id, () => this.ports.coolify.createGithubAppApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            github_app_uuid: githubApp.uuid,
+            git_repository: BOULE_REPO,
+            git_branch: 'main',
+            build_pack: 'dockerfile',
+            name,
+            domains: coolifyDomains([bouleHostnameFor(org)]),
+            dockerfile_location: BOULE_APP_DOCKERFILE,
+        }));
+        // Every app foundry deploys keeps its own logs (#75), reused as-is here.
+        await this.ensureLogVolume(app.appId, org, app.existed);
+        const liveEnv = new Map((await this.ports.coolify.listEnvs(app.appId))
+            .filter((e) => !e.is_preview)
+            .map((e) => [e.key, e.value]));
+        const envChanged = bouleEnvDrift(env, Object.fromEntries(liveEnv)).length > 0;
+        const envs = Object.entries(env).map(([key, value]) => ({ key, value }));
+        const cookieSecret = await this.ensureAuthCookieSecret(app.appId);
+        if (cookieSecret)
+            envs.push({ key: 'AUTH_COOKIE_SECRET', value: cookieSecret });
+        // The key the sign-in service knows this app by: minted once, then it
+        // lives in this env and in the broker entry `bouleBrokerEntry` writes.
+        const appKey = await this.ensureAuthAppKey(app.appId);
+        if (appKey)
+            envs.push({ key: 'AUTH_APP_KEY', value: appKey });
+        await this.ports.coolify.bulkUpsertEnvs(app.appId, envs);
+        const dbPush = await this.pushDatabaseUrl(app.appId, dbId, dbName);
+        if (!dbPush.pushed) {
+            throw new Error(`Boule for ${org.slug}: its database has no internal_db_url yet -- retry this apply once Coolify reports one`);
+        }
+        if (app.existed && (envChanged || cookieSecret !== null || appKey !== null || dbPush.changed)) {
+            await this.ports.coolify.restart(app.appId);
+        }
+        return { resourceId: app.appId };
+    }
     // ---- jobs (#173) ---------------------------------------------------------
     /**
      * `plan/diff.ts`'s `planJobsRegistration`: registers the org's own app with

package/dist/plan/hostnames.d.ts

@@ -28,8 +28,8 @@ export declare function coolifyDomains(names: readonly string[]): string;
 export declare function legacyAppHostname(org: DeclaredOrg): string;
 /**
  * The hostnames `cloudflareTunnel` routes to Coolify's proxy (#115, #145,
- * #164): a site's two names, every entry's names, an own-domain calls name and
- * Agora's, then the wildcard last. An org that does not host keeps the single
+ * #164): a site's two names, every entry's names, an own-domain calls name,
+ * Agora's and Boule's, then the wildcard last. An org that does not host keeps the single
  * name it always had.
  */
 export declare function tunnelIngressHostnames(org: DeclaredOrg): string[];

package/dist/plan/hostnames.js

@@ -1,5 +1,6 @@
 import { APP_ENTRY_KEY } from '../org.js';
 import { agoraHostnameFor } from './agora.js';
+import { bouleHostnameFor } from './boule.js';
 /**
  * The full names an entry is served at. With `hosting.usesDomain` off, or no
  * domain, `hostnames` is not read: the `app` entry is at `<slug>.oikos.host`
@@ -48,8 +49,8 @@ export function legacyAppHostname(org) {
 }
 /**
  * The hostnames `cloudflareTunnel` routes to Coolify's proxy (#115, #145,
- * #164): a site's two names, every entry's names, an own-domain calls name and
- * Agora's, then the wildcard last. An org that does not host keeps the single
+ * #164): a site's two names, every entry's names, an own-domain calls name,
+ * Agora's and Boule's, then the wildcard last. An org that does not host keeps the single
  * name it always had.
  */
 export function tunnelIngressHostnames(org) {
@@ -67,6 +68,8 @@ export function tunnelIngressHostnames(org) {
     // #164: Agora always moves onto `agora.<domain>` once `org.domain` is set.
     if (org.domain) {
         hostnames.push(agoraHostnameFor(org));
+        // #161: and Boule moves onto `boule.<domain>` the same way.
+        hostnames.push(bouleHostnameFor(org));
     }
     // The wildcard goes last: Cloudflare takes the first ingress rule that
     // matches, so every exact name above must come before `*.<domain>`.

package/dist/plan/locked-hostnames.d.ts

@@ -1,7 +1,7 @@
 import type { DeclaredOrg } from '../org.js';
 /**
  * The names under the org's domain that foundry owns, so no hosting entry may
- * take one: Agora, the cms studio when the site is on, calls when it uses the
+ * take one: Agora, Boule, the cms studio when the site is on, calls when it uses the
  * domain, the sign-in host when the issuer does, and every platform service
  * hostname that falls under the domain. Empty for an org with no domain.
  */

package/dist/plan/locked-hostnames.js

@@ -1,8 +1,9 @@
 import { agoraHostnameFor } from './agora.js';
+import { bouleHostnameFor } from './boule.js';
 import { loginHostnameFor } from './login-host.js';
 /**
  * The names under the org's domain that foundry owns, so no hosting entry may
- * take one: Agora, the cms studio when the site is on, calls when it uses the
+ * take one: Agora, Boule, the cms studio when the site is on, calls when it uses the
  * domain, the sign-in host when the issuer does, and every platform service
  * hostname that falls under the domain. Empty for an org with no domain.
  */
@@ -12,6 +13,7 @@ export function lockedHostnames(org, platformHostnames) {
     if (!domain)
         return locked;
     locked.add(agoraHostnameFor(org));
+    locked.add(bouleHostnameFor(org));
     if (org.site.enabled)
         locked.add(`cms.${domain}`);
     if (org.calls.enabled && org.calls.usesDomain)

package/dist/plan/plan-apply.js

@@ -371,9 +371,11 @@ export class FoundryPlanApply {
             this.orgPlatformReadiness(),
             this.orgAgoraHost(id),
         ]);
+        const otherSlugs = (await this.store.list()).filter((o) => o.id !== id).map((o) => o.slug);
         const detail = computePlanDetail(org, live, applied?.serviceIds ?? {}, agoraHost, this.jobsScheduler, platformReadiness, {
             loginHostBindings: this.loginHostBindings,
             broker: this.broker,
+            otherSlugs,
             now: () => this.now().getTime(),
         });
         const invalid = await this.invalidHosting(org);

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

@@ -46,6 +46,15 @@ export declare const PLATFORM_AUTH_KEY = "platform:auth";
  * that was never actually applied.
  */
 export declare const PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY = "auth_zitadel_applied_image_tag";
+/**
+ * The image has `Entrypoint /app/zitadel` and no `Cmd`, so without this it
+ * runs zitadel with no subcommand, exits, and restarts forever. Coolify turns
+ * `--entrypoint` in `custom_docker_run_options` into the compose `entrypoint`
+ * (its PATCH takes this field; it refuses `dockerfile`).
+ */
+export declare const AUTH_ZITADEL_RUN_OPTIONS = "--entrypoint \"/app/zitadel start-from-init --masterkeyFromEnv --tlsMode external\"";
+/** The run options last applied to the ZITADEL app (value: the options string), so a changed value forces one redeploy. */
+export declare const PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY = "zitadel_platform_auth_run_options_applied";
 /**
  * #251: the Synapse/MAS image tags an org's calls Matrix stack last
  * successful apply actually set live. `coolifyCalls` (`executor.ts`)

package/dist/plan/platform-diff.js

@@ -41,6 +41,15 @@ export const PLATFORM_AUTH_KEY = 'platform:auth';
  * that was never actually applied.
  */
 export const PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY = 'auth_zitadel_applied_image_tag';
+/**
+ * The image has `Entrypoint /app/zitadel` and no `Cmd`, so without this it
+ * runs zitadel with no subcommand, exits, and restarts forever. Coolify turns
+ * `--entrypoint` in `custom_docker_run_options` into the compose `entrypoint`
+ * (its PATCH takes this field; it refuses `dockerfile`).
+ */
+export const AUTH_ZITADEL_RUN_OPTIONS = '--entrypoint "/app/zitadel start-from-init --masterkeyFromEnv --tlsMode external"';
+/** The run options last applied to the ZITADEL app (value: the options string), so a changed value forces one redeploy. */
+export const PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY = 'zitadel_platform_auth_run_options_applied';
 /**
  * #251: the Synapse/MAS image tags an org's calls Matrix stack last
  * successful apply actually set live. `coolifyCalls` (`executor.ts`)
@@ -753,8 +762,15 @@ function planJobs(platform, byKey, claimed, observable) {
         claimed.add(key);
     if (!platform.jobs.enabled)
         return { step: null, blocked: null };
-    if (live)
-        return { step: null, blocked: null };
+    if (live) {
+        // The step also starts the scheduler's database (0.16.3), so a live app
+        // whose database the reader saw stopped plans it again. A status the
+        // reader could not read is absent, and plans nothing.
+        const databaseStatus = live.config.databaseStatus;
+        if (typeof databaseStatus !== 'string' || databaseStatus.startsWith('running')) {
+            return { step: null, blocked: null };
+        }
+    }
     // No Coolify reader means the host wired no Coolify at all for the
     // platform: the step's executor would throw every apply, and the scheduler
     // could never be seen live, so it would re-plan forever. A fixed text: it
@@ -1103,7 +1119,10 @@ function planAuth(platform, recordedIds, executorBlocked, executorMissing, authD
         connectorApplied &&
         brokerApplied &&
         brokerDeployed &&
-        loginClientApplied) {
+        loginClientApplied &&
+        // The ZITADEL run options reach the container only through the auth
+        // step's redeploy, so a platform recorded before them still plans it.
+        recordedIds[PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY] === AUTH_ZITADEL_RUN_OPTIONS) {
         return { step: null, blocked: null };
     }
     // The admin key was minted but never reached the host. ZITADEL shows a

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

@@ -513,6 +513,20 @@ export interface PlatformAiDeps {
     heldKeys?: {
         resolve(ref: string): Promise<string | null>;
     };
+    /**
+     * The `@wtfalch/keys` settings the AI host reads (`KEYS_WORKER_URL`,
+     * `KEYS_CREDENTIAL`, `KEYS_VERIFY_KEYS`: the worker's origin, this host's
+     * own worker-signed caller credential, and the worker's Ed25519 public
+     * key(s), comma-separated base64url, current first). ai's
+     * `POST /v1/platform/keys` refuses every call unless all three are set, so
+     * the step sets them on the host and the worker, and the executor reports
+     * the step blocked while this is unset. Never recorded or logged.
+     */
+    keys?: {
+        workerUrl: string;
+        credential: string;
+        verifyKeys: string;
+    };
     /** Injected for tests. Absent, {@link provisionPlatformAi} builds the real {@link createAiManagementKeyMinter} from the signing key it mints. */
     managementKeyMinter?: AiManagementKeyMinter;
     /** Injected for tests, e.g. against a fake ai host. Defaults to the global `fetch`. */
@@ -770,7 +784,7 @@ export declare class ProvidersPlatformCloudflareReader implements PlatformCloudf
 export declare class ProvidersPlatformCoolifyReader implements PlatformCoolifyReader {
     private readonly client;
     private readonly platformStore;
-    constructor(client: Pick<CoolifyPort, 'getApplication' | 'listDatabaseBackups'>, platformStore: Pick<PlatformStore, 'getServiceIds'>);
+    constructor(client: Pick<CoolifyPort, 'getApplication' | 'getDatabase' | 'listDatabaseBackups'>, platformStore: Pick<PlatformStore, 'getServiceIds'>);
     listResources(): Promise<LiveResource[]>;
 }
 export {};

package/dist/plan/platform-providers.js

@@ -6,7 +6,7 @@ import { redactSecrets } from '../calls-sfu-deploy-support.js';
 import { ensureCloudflaredConnector } from './cloudflared-connector.js';
 import { ACCESS_POLICY_NAME, getDatabaseStarted, isNotFoundError, isRunningOrStarting, } from './executor.js';
 import { coolifyDomains } from './hostnames.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_INSTANCE_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_UNDELIVERED_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, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, parseBrokerDeployRecord, parseLoginClientRecord, platformMailMxHost, } from './platform-diff.js';
+import { AUTH_ZITADEL_RUN_OPTIONS, 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_INSTANCE_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_UNDELIVERED_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_AUTH_ZITADEL_RUN_OPTIONS_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, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, parseBrokerDeployRecord, parseLoginClientRecord, platformMailMxHost, } from './platform-diff.js';
 import { applyCallsSfuPlatformStep } from './platform-sfu.js';
 import { CreateInstanceError, createZitadelInstance, generateSystemApiKeypair, instanceWithoutBearerMessage, systemApiUsersEnv, } from './zitadel-system-api.js';
 /** The key `runPlatformSteps` records the apex zone's id under (`system:kind:key`). */
@@ -184,6 +184,10 @@ export class FoundryPlatformStepExecutor {
             blocked.ai =
                 "the platform's AI host is blocked, not planned: the host built the platform executor without its ai dependencies";
         }
+        else if (platform.ai.enabled && !aiKeys(this.ai)) {
+            blocked.ai =
+                "the platform's AI host is blocked, not planned: the host supplies no keys worker URL, credential and verify keys (KEYS_WORKER_URL, KEYS_CREDENTIAL, KEYS_VERIFY_KEYS), and without them ai's POST /v1/platform/keys refuses every call, so foundry's management key could never be minted";
+        }
         else if (platform.ai.enabled &&
             !this.ai?.managementKeyMinter &&
             !this.ai?.heldKeys &&
@@ -871,6 +875,7 @@ async function provisionPlatformAuth(context, deps) {
             docker_registry_image_name: AUTH_ZITADEL_IMAGE,
             docker_registry_image_tag: AUTH_ZITADEL_IMAGE_TAG,
             ports_exposes: AUTH_ZITADEL_PORT,
+            custom_docker_run_options: AUTH_ZITADEL_RUN_OPTIONS,
             name: PLATFORM_AUTH_ZITADEL_APP_NAME,
             description: `ZITADEL for the platform's own sign-in (#168, ${AUTH_ZITADEL_IMAGE}:${AUTH_ZITADEL_IMAGE_TAG})`,
             instant_deploy: false,
@@ -882,9 +887,14 @@ async function provisionPlatformAuth(context, deps) {
     // create must not leave the app unnamed for good, and the tunnel addresses
     // the app by this name. (The port cannot read the current name back, and
     // setting the same value again is harmless.)
+    // The run options go in the same patch, so an app made before they existed
+    // gets them too.
     await deps.coolify.updateApplication(zitadelAppId, {
         custom_internal_name: PLATFORM_AUTH_ZITADEL_INTERNAL_NAME,
+        custom_docker_run_options: AUTH_ZITADEL_RUN_OPTIONS,
     });
+    // The container only takes new run options at its next deploy.
+    const zitadelRunOptionsNew = recorded[PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY] !== AUTH_ZITADEL_RUN_OPTIONS;
     // #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.
@@ -1012,9 +1022,12 @@ async function provisionPlatformAuth(context, deps) {
     await deps.coolify.bulkUpsertEnvs(brokerAppId, brokerEnvs);
     // Deploy an app that was just created, is not running (a throw after the
     // create left it never deployed, or it stopped), or whose envs changed.
-    if (zitadelApp.justCreated || !zitadelApp.running || zitadelEnvsChanged) {
+    if (zitadelApp.justCreated || !zitadelApp.running || zitadelEnvsChanged || zitadelRunOptionsNew) {
         await deps.coolify.deploy(zitadelAppId);
         await record(PLATFORM_AUTH_ZITADEL_DEPLOYED_SCOPE_KEY, zitadelAppId);
+        // Only now: the options are live once the deploy went out. A throw between
+        // the PATCH and here leaves the marker unset, so the next run deploys.
+        await record(PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY, AUTH_ZITADEL_RUN_OPTIONS);
     }
     if (loginApp.justCreated || !loginApp.running || loginEnvsChanged) {
         await deps.coolify.deploy(loginAppId);
@@ -3219,9 +3232,13 @@ const PLATFORM_AI_WORKER_DEFAULTS = [
  *   rotates it yet, so the platform loses its AI management key after 90 days.
  * - Deploys are decided from the recorded "pending" mark and the app's own
  *   status, not from a deployment's age: the port cannot read one.
- * - Provider keys (`KEYS_WORKER_URL`, `KEYS_CREDENTIAL`, `KEYS_VERIFY_KEYS`)
- *   and sign-in (`AUTH_*`) are not set: until an operator supplies them the
- *   host answers `503 not_configured` for provider work, as its README says.
+ * - Sign-in (`AUTH_*`) is not set: until an operator supplies it the host
+ *   answers `503 not_configured` for sign-in, as its README says.
+ * - `KEYS_WORKER_URL`, `KEYS_CREDENTIAL` and `KEYS_VERIFY_KEYS` come from
+ *   {@link PlatformAiDeps.keys} and are set on the host and the worker. They
+ *   gate more than provider work: ai builds the issuer behind
+ *   `POST /v1/platform/keys` only when all three are set, so without them
+ *   foundry's own management key can never be minted.
  */
 async function provisionPlatformAi(context, deps) {
     const { platform } = context;
@@ -3231,6 +3248,15 @@ async function provisionPlatformAi(context, deps) {
     const runtime = deps.runtime ?? {};
     const sleep = runtime.sleep ?? defaultSleep;
     const { coolify } = deps;
+    const keys = aiKeys(deps);
+    if (!keys) {
+        throw new Error("platform:ai needs the keys worker URL, credential and verify keys in its ai dependencies (KEYS_WORKER_URL, KEYS_CREDENTIAL, KEYS_VERIFY_KEYS); ai refuses to mint foundry's management key without them");
+    }
+    const keysEnvs = [
+        { key: 'KEYS_WORKER_URL', value: keys.workerUrl },
+        { key: 'KEYS_CREDENTIAL', value: keys.credential },
+        { key: 'KEYS_VERIFY_KEYS', value: keys.verifyKeys },
+    ];
     const record = async (key, id) => {
         context.recordScopeId(key, id);
         await context.persist?.();
@@ -3315,10 +3341,12 @@ async function provisionPlatformAi(context, deps) {
     const runnerEnvs = [
         { key: 'DATABASE_URL', value: runtimeUrl },
         { key: 'APP_URL', value: `https://${hostname}` },
+        ...keysEnvs,
         ...(await missingEnvs(coolify, runner.appId, PLATFORM_AI_RUNNER_DEFAULTS)),
     ];
     const workerEnvs = [
         { key: 'DATABASE_URL', value: runtimeUrl },
+        ...keysEnvs,
         ...(await missingEnvs(coolify, worker.appId, PLATFORM_AI_WORKER_DEFAULTS)),
     ];
     // Whether anything the containers run on differs from what they last
@@ -4118,6 +4146,10 @@ async function provisionPlatformFiles(context, deps) {
     await record(PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, gitRef);
     return { resourceId: runnerApp.appId };
 }
+function aiKeys(deps) {
+    const keys = deps?.keys;
+    return keys?.workerUrl && keys.credential && keys.verifyKeys ? keys : null;
+}
 function filesKeys(deps) {
     const keys = deps?.keys;
     return keys?.workerUrl && keys.credential ? keys : null;
@@ -5029,11 +5061,27 @@ export class ProvidersPlatformCoolifyReader {
         if (recordedAppId) {
             try {
                 const app = await this.client.getApplication(recordedAppId);
+                // The scheduler's database status, so `planJobs` can see a stopped
+                // one. Left out when it cannot be read: unknown is not "stopped".
+                let databaseStatus;
+                const databaseId = recorded[JOBS_DATABASE_SCOPE_KEY];
+                if (databaseId) {
+                    try {
+                        databaseStatus = (await this.client.getDatabase(databaseId)).status;
+                    }
+                    catch {
+                        databaseStatus = undefined;
+                    }
+                }
                 resources.push({
                     system: 'coolify',
                     kind: 'jobs',
                     key: JOBS_SCHEDULER_KEY,
-                    config: { uuid: app.uuid, status: app.status },
+                    config: {
+                        uuid: app.uuid,
+                        status: app.status,
+                        ...(databaseStatus !== undefined && { databaseStatus }),
+                    },
                 });
             }
             catch {

package/dist/plan/providers-readers.js

@@ -1,3 +1,4 @@
+import { BOULE_MANAGED_ENV_KEYS } from './boule.js';
 /**
  * A {@link ScopeResolver} backed by `AppliedState.serviceIds` (`../state.ts`)
  * — the one place foundry records a provider's own id for an org today,
@@ -191,6 +192,24 @@ async function withAgoraEnvConfig(client, resource, recorded) {
     }
     return { ...resource, config: { ...resource.config, env } };
 }
+/**
+ * #161: the org's own recorded Boule app's live sign-in env vars, as
+ * `config.env`, so `diff.ts`'s `planBoule` can compare them with what
+ * `executor.ts` would write. Gated and failing exactly like
+ * {@link withAgoraEnvConfig}.
+ */
+async function withBouleEnvConfig(client, resource, recorded) {
+    if (resource.kind !== 'application' || !recorded[resource.key]?.startsWith('boule:')) {
+        return resource;
+    }
+    const managed = BOULE_MANAGED_ENV_KEYS;
+    const env = {};
+    for (const e of await client.listEnvs(resource.key)) {
+        if (!e.is_preview && managed.includes(e.key))
+            env[e.key] = e.value;
+    }
+    return { ...resource, config: { ...resource.config, env } };
+}
 /** `@wtfalch/providers`' own `LiveResource` (`resource.ts`) has no `system` field — foundry's adds it at this boundary. */
 function toFoundryResources(system, resources) {
     return resources.map((r) => ({ system, kind: r.kind, key: r.key, config: r.config }));
@@ -221,7 +240,8 @@ export class ProvidersCoolifyReader {
         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);
+        const withBouleConfig = await Promise.all(withAgoraConfig.map((r) => withBouleEnvConfig(this.client, r, recorded)));
+        return applyRecordedIds(withBouleConfig, recorded);
     }
 }
 /**

package/dist/slug.js

@@ -128,6 +128,13 @@ const CALLS_SUFFIX = /-calls$/;
  * taken, not just one that turns a feature on.
  */
 const AGORA_SUFFIX = /-agora$/;
+/**
+ * `<something>-boule` — a level-1 org's own Boule hostname
+ * (`<slug>-boule.oikos.host`, foundry#161). Every org gets a Boule, so like
+ * {@link AGORA_SUFFIX} this collides with every org's own hostname, not only
+ * one that opts in.
+ */
+const BOULE_SUFFIX = /-boule$/;
 /**
  * Validates a candidate org slug against every rule #28 decided. Returns
  * `null` when the slug is acceptable, or a {@link SlugRejection} naming
@@ -151,10 +158,11 @@ export function validateSlug(slug) {
     if (STAGE_SUFFIX.test(slug) ||
         PR_SUFFIX.test(slug) ||
         CALLS_SUFFIX.test(slug) ||
-        AGORA_SUFFIX.test(slug)) {
+        AGORA_SUFFIX.test(slug) ||
+        BOULE_SUFFIX.test(slug)) {
         return {
             reason: 'environment-suffix',
-            message: `slug '${slug}' ends with an environment suffix ('-stage', '-pr-<digits>', '-calls' or '-agora') reserved for another org's own hostname (#28, #145, #164) — 'acme-calls' is only legal as acme's calls hostname, 'acme-agora' only as acme's Agora hostname, never as an org slug in its own right`,
+            message: `slug '${slug}' ends with an environment suffix ('-stage', '-pr-<digits>', '-calls', '-agora' or '-boule') reserved for another org's own hostname (#28, #145, #164, #161) — 'acme-calls' is only legal as acme's calls hostname, 'acme-agora' only as acme's Agora hostname, 'acme-boule' only as acme's Boule hostname, never as an org slug in its own right`,
         };
     }
     return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.16.3",
+  "version": "0.16.5",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",