@wtfalch/foundry 0.28.0 → 0.30.0

package/dist/plan/chat-matrix.js

@@ -29,6 +29,22 @@ export function chatUpstreams(orgSlug) {
         mas: `http://${names.mas}:${CHAT_MAS_PORT}`,
     };
 }
+/**
+ * Internal names for the org's re-keyed homeserver pair (#463, design note
+ * `docs/chat-rekey-design.md` Option 1): a second Synapse and MAS,
+ * provisioned beside the original pair under `chatInternalNames` so both
+ * ends of the copy are live at once. The chat service and its own database
+ * are never re-created — same app, repointed once the copy is done and the
+ * original pair is parked.
+ */
+export function chatRekeyedInternalNames(orgSlug) {
+    return {
+        synapse: `${orgSlug}-chat-synapse-2`,
+        mas: `${orgSlug}-chat-mas-2`,
+        synapseDb: `${orgSlug}-chat-synapse-2-db`,
+        masDb: `${orgSlug}-chat-mas-2-db`,
+    };
+}
 /**
  * Never resolved by DNS and never federates; the identifier Synapse, MAS and
  * the chat service agree on. A level-1 org's chat lives on this name until a
@@ -38,18 +54,33 @@ export function chatUpstreams(orgSlug) {
 export function chatServerName(orgSlug) {
     return `chat-${orgSlug}.internal`;
 }
-/** The Matrix user the chat service acts as (`chat/apps/chat-service/src/workspace.ts`). */
-export function chatAdminUser(orgSlug) {
-    return `@chat-admin:${chatServerName(orgSlug)}`;
+/**
+ * The Matrix user the chat service acts as
+ * (`chat/apps/chat-service/src/workspace.ts`). `serverName` defaults to the
+ * org's level-1 `chatServerName`; a re-key (#463) passes the new one so the
+ * gate module's `admin_user` matches the homeserver it is loaded into.
+ */
+export function chatAdminUser(orgSlug, serverName = chatServerName(orgSlug)) {
+    return `@chat-admin:${serverName}`;
 }
 const q = (value) => JSON.stringify(value);
+const SERVER_NAME_PATTERN = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/;
+/** A re-key's `server_name` is a lowercase DNS name with at least two labels; anything else would be written into both configs. */
+export function assertChatServerName(serverName) {
+    if (serverName.length > 253 || !SERVER_NAME_PATTERN.test(serverName)) {
+        throw new Error('chat server_name must be a lowercase domain name');
+    }
+}
 /** `homeserver.yaml`: federation off, presence on (stable Synapse features only -- no MSC3026 `busy`, foundry#41), MAS for auth, the chat gate module on. */
 export function chatSynapseHomeserverYaml(input) {
+    const serverName = input.serverName ?? chatServerName(input.orgSlug);
+    if (input.serverName !== undefined)
+        assertChatServerName(serverName);
     return [
         '# Generated by @wtfalch/foundry (executor.ts, coolify:chat). Do not edit',
         '# by hand; re-run apply instead -- it will not rotate secrets that exist.',
         '',
-        `server_name: ${q(chatServerName(input.orgSlug))}`,
+        `server_name: ${q(serverName)}`,
         'pid_file: /data/homeserver.pid',
         'report_stats: false',
         '',
@@ -106,13 +137,16 @@ export function chatSynapseHomeserverYaml(input) {
         'modules:',
         '  - module: wtfalch_chat_gate.ChatGate',
         '    config:',
-        `      admin_user: ${q(chatAdminUser(input.orgSlug))}`,
+        `      admin_user: ${q(chatAdminUser(input.orgSlug, serverName))}`,
         '      allow_encrypted_channels: false',
         '',
     ].join('\n');
 }
 /** MAS `config.yaml`: password login and registration off; the chat service is the one client, with admin. */
 export function chatMasConfigYaml(input) {
+    const serverName = input.serverName ?? chatServerName(input.orgSlug);
+    if (input.serverName !== undefined)
+        assertChatServerName(serverName);
     const indentKey = (pem, spaces) => pem
         .trimEnd()
         .split('\n')
@@ -150,7 +184,7 @@ export function chatMasConfigYaml(input) {
         '',
         'matrix:',
         '  kind: synapse',
-        `  homeserver: ${q(chatServerName(input.orgSlug))}`,
+        `  homeserver: ${q(serverName)}`,
         `  endpoint: ${q(`http://${input.synapseHost}:${CHAT_SYNAPSE_PORT}`)}`,
         `  secret: ${q(input.sharedSecret)}`,
         '',

package/dist/plan/diff.d.ts

@@ -1,4 +1,4 @@
-import type { DeclaredOrg, OrgId } from '../org.js';
+import type { DeclaredOrg, OrgId, OrgServiceSchema } from '../org.js';
 import type { Plan, PlanStep, UnmanagedItem, VersionChangeItem } from '../plan.js';
 import { type AgoraHostReading } from './agora.js';
 import type { LiveResource } from './live.js';
@@ -64,6 +64,8 @@ export interface PlanDetail {
     unmanaged: UnmanagedItem[];
     /** #251: see `VersionChangeItem` (`../plan.ts`). Never folded into `plannedSteps`. */
     versionChanges: VersionChangeItem[];
+    /** #444a: see {@link OrgPostgresPlan}. Never folded into `plannedSteps`, for the same reason `versionChanges` above is not. */
+    orgPostgres: OrgPostgresPlan;
 }
 /** The `Plan` (#19's public contract) a `PlanDetail` carries. */
 export declare function toPlan(detail: PlanDetail): Plan;
@@ -110,7 +112,12 @@ export declare function toPlan(detail: PlanDetail): Plan;
  * app-creating step below: {@link planLoginHost}, the org's own company
  * login host -- also idempotent on the *recorded* resource id, since
  * `live` has no notion of a ZITADEL trusted domain or a login binding
- * either. Everything
+ * either. #444a adds one more fact, in a different shape from every other
+ * addition here: {@link planOrgPostgres}, the org's one shared Postgres
+ * server plus whichever of `org.ts`'s `ORG_SERVICE_SCHEMAS` (nine today)
+ * this org actually runs and has not yet recorded -- idempotent on the
+ * *recorded* resource id like {@link planOwners}, but never folded into
+ * `plannedSteps`: its own {@link OrgPostgresPlan} field says why. Everything
  * else in `live` that none of these eighteen singletons and however many
  * declared issuer apps claim is unmanaged. The full field-by-field provisioning surface (SSO,
  * guests, calls on the org's own domain, adopted/bespoke apps, the actual
@@ -128,6 +135,42 @@ export declare function computePlanDetail(org: DeclaredOrg, live: LiveResource[]
  * its login host equal to the shared ZITADEL instance's own.
  */
 export declare function isPlatformOwnOrg(org: DeclaredOrg, platformApex: string | null): boolean;
+/**
+ * What {@link planOrgPostgres} reports about the org's one shared Postgres
+ * server and its fixed schema topology (#444a, "manifest-and-plan-only"):
+ * missing only, nothing applied. Deliberately **not** folded into
+ * `plannedSteps` -- the same reason {@link VersionChangeItem} (`../plan.ts`)
+ * never is, restated in `computePlanDetail`'s own doc comment below, but
+ * sharper here: `plan-apply.ts`'s `runSteps` executes every
+ * `detail.plannedSteps` entry through `StepExecutor.execute`, which
+ * switches on `` `${system}:${kind}` `` and throws on anything it has no
+ * case for. `plan/executor.ts` is untouched this slice (444a's own
+ * acceptance line), so a `'coolify:postgres-server'`/`'coolify:postgres-
+ * schema'` entry in `plannedSteps` would not sit there harmlessly the way
+ * an unapplied field does -- the next real `apply()` would reach it and
+ * throw `FoundryStepExecutor has no dispatch for coolify:postgres-server`,
+ * for every org, immediately. This field is how 444a reports the same
+ * "missing" fact to a caller of `computePlanDetail` directly without that
+ * happening; wiring it into the public `Plan` (`toPlan` below) and into
+ * real `plannedSteps` entries is 444b's job, once `plan/executor.ts` has a
+ * dispatch for them.
+ */
+export interface OrgPostgresPlan {
+    /** True until the org's one shared Postgres server is recorded under {@link ORG_POSTGRES_SERVER_SCOPE_KEY}. */
+    serverMissing: boolean;
+    /**
+     * Every `org.ts` {@link ORG_SERVICE_SCHEMAS} entry this org actually runs
+     * and has not yet recorded under its own `scopeKey`, in that constant's
+     * own order -- see {@link orgServiceSchemaEnabled} for which entries that
+     * is. Boule's is always included, the same way `ORG_SERVICE_SCHEMAS`
+     * itself always carries it; CMS's, chat's and calls' sit behind their own
+     * feature switch, and the app schema behind whether any hosting entry
+     * declares a database. A schema this org does not run yet is never
+     * reported missing, even though {@link ORG_SERVICE_SCHEMAS} still names
+     * it as part of the full topology.
+     */
+    missingSchemas: readonly OrgServiceSchema[];
+}
 /** Restated from `executor.ts`, the same rule: the id of an ai key minted but not delivered. */
 export declare const AI_KEY_UNDELIVERED_SCOPE_KEY = "ai_key_undelivered";
 /** Restated from `executor.ts`, the same rule: the id of a jobs project registered but not delivered. */

package/dist/plan/diff.js

@@ -1,9 +1,9 @@
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
-import { APP_ENTRY_KEY, ownerMailboxRecorded, ownerMailboxes } from '../org.js';
-import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
-import { BOULE_BROKER_ENTRY_KEY, bouleEnvDrift, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
+import { APP_ENTRY_KEY, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, ownerMailboxRecorded, ownerMailboxes, } from '../org.js';
+import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CHAT_CALLS_APPLIED_SCOPE_KEY, CHAT_CALLS_TOKEN_SCOPE_KEY, CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, chatCallsApplied, chatHasUpstreams, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
+import { BOULE_BROKER_ENTRY_KEY, BOULE_MAIL_TOKEN_ENV, bouleEnvDrift, bouleMailTokenDrift, bouleMailWanted, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
-import { chatInternalNames } from './chat-matrix.js';
+import { chatInternalNames, chatUpstreams } from './chat-matrix.js';
 import { planEntryAiKeys } from './entry-ai-key.js';
 import { planEdgeReservedLabels, planEntryEdgeKeys } from './entry-edge-key.js';
 import { planFilesKeys } from './entry-files-key.js';
@@ -145,7 +145,12 @@ function liveResourceName(r) {
  * app-creating step below: {@link planLoginHost}, the org's own company
  * login host -- also idempotent on the *recorded* resource id, since
  * `live` has no notion of a ZITADEL trusted domain or a login binding
- * either. Everything
+ * either. #444a adds one more fact, in a different shape from every other
+ * addition here: {@link planOrgPostgres}, the org's one shared Postgres
+ * server plus whichever of `org.ts`'s `ORG_SERVICE_SCHEMAS` (nine today)
+ * this org actually runs and has not yet recorded -- idempotent on the
+ * *recorded* resource id like {@link planOwners}, but never folded into
+ * `plannedSteps`: its own {@link OrgPostgresPlan} field says why. Everything
  * else in `live` that none of these eighteen singletons and however many
  * declared issuer apps claim is unmanaged. The full field-by-field provisioning surface (SSO,
  * guests, calls on the org's own domain, adopted/bespoke apps, the actual
@@ -164,7 +169,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const issuer = planIssuer(org, byKey, claimed, platformReadiness.authReady, isPlatformOrg);
     if (issuer.step)
         plannedSteps.push(issuer.step);
-    plannedSteps.push(...planOwners(org, recordedIds, platformReadiness.authReady, 'error' in agoraHost ? null : agoraHost.issuer));
+    plannedSteps.push(...planOwners(org, recordedIds, platformReadiness.authReady, platformReadiness.authIssuer));
     // #267: after the ZITADEL org step, before any app's own issuer
     // application. Apps created later in this run are not in the binding yet;
     // the next run replans this step and repoints them.
@@ -176,6 +181,11 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     platformAuthHostnameFrom('error' in agoraHost ? null : agoraHost.issuer), isPlatformOrg);
     if (loginHost.step)
         plannedSteps.push(loginHost.step);
+    // #444a: the org's one shared Postgres server and its fixed schema
+    // topology -- dependent on nothing else planned here, but its own
+    // `OrgPostgresPlan`, never `plannedSteps` ({@link OrgPostgresPlan}'s own
+    // doc comment says why).
+    const orgPostgres = planOrgPostgres(org, recordedIds);
     // Planned ahead of everything that needs the zone live (#238); its own step
     // is pushed just below, before mail.
     const zone = planZone(org, byKey, claimed);
@@ -230,6 +240,10 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         : callsTokenHostFrom(withRecordedMessagingProject(agoraHost, recordedIds)));
     if (callsService.step)
         plannedSteps.push(callsService.step);
+    // After both apps it writes to: chat's token and the calls service's chat address.
+    const callsChat = planCallsChat(org, recordedIds, chat.step !== null || callsService.step !== null, chat.blocked !== null || calls.blocked !== null || callsService.blocked !== null);
+    if (callsChat.step)
+        plannedSteps.push(callsChat.step);
     // #251: same mechanism as the platform's own version-change lines -- see
     // `planPlatform`'s own block in `platform-diff.ts`. Synapse and MAS never
     // patch a running app's image tag once created, so this is
@@ -398,7 +412,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const bouleGuarded = guardApp(bouleClient);
     if (bouleGuarded)
         plannedSteps.push(bouleGuarded);
-    const boule = planBoule(org, byKey, claimed, recordedIds, authIssuer, options.otherSlugs ?? [], options.archonUrl ?? null);
+    const boule = planBoule(org, byKey, claimed, recordedIds, authIssuer, options.otherSlugs ?? [], options.archonUrl ?? null, platformReadiness);
     if (boule.step)
         plannedSteps.push(boule.step);
     // After the apps and Boule -- an edge key needs its app recorded or planned,
@@ -468,6 +482,9 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         unmanaged.push({ description: agora.blocked, key: 'coolify:agora' });
     if (boule.blocked)
         unmanaged.push({ description: boule.blocked, key: 'coolify:boule' });
+    if (boule.mailBlocked) {
+        unmanaged.push({ description: boule.mailBlocked, key: 'coolify:boule:mail' });
+    }
     // Same for an ai key minted but never delivered: planning a new mint would
     // orphan a second live key.
     if (aiKey.blocked)
@@ -504,6 +521,9 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         unmanaged.push({ description: calls.blocked, key: 'coolify:calls' });
     if (chat.blocked)
         unmanaged.push({ description: chat.blocked, key: 'coolify:chat' });
+    if (callsChat.blocked) {
+        unmanaged.push({ description: callsChat.blocked, key: 'coolify:calls-chat' });
+    }
     if (callsService.blocked) {
         unmanaged.push({ description: callsService.blocked, key: 'coolify:calls-service' });
     }
@@ -538,6 +558,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         plannedSteps: plannedSteps.map(withStepSystem),
         unmanaged,
         versionChanges,
+        orgPostgres,
     };
 }
 /**
@@ -638,12 +659,20 @@ function planIssuer(org, byKey, claimed, authReady, isPlatformOrg = false) {
         };
     }
     claimed.add(key);
+    // #517: both sides on the domain says nothing about which domain. The live
+    // issuer's recorded host differing from the declared domain's login host is
+    // a domain change, and moves the issuer too.
+    const liveHost = typeof live.config.host === 'string' ? live.config.host : null;
+    const domainMoved = Boolean(live.config.usesDomain) &&
+        desiredUsesDomain &&
+        Boolean(org.domain) &&
+        liveHost !== null &&
+        liveHost !== loginHostnameFor(org);
     // The platform's own org already signs in on the shared host: no move. A
-    // live issuer that does not say (the reader never does: foundry v1 never
-    // moves one) is not read as a different one either.
+    // live issuer that does not say is not read as a different one either.
     if (isPlatformOrg ||
         live.config.usesDomain === undefined ||
-        Boolean(live.config.usesDomain) === desiredUsesDomain) {
+        (Boolean(live.config.usesDomain) === desiredUsesDomain && !domainMoved)) {
         return { step: null, blocked: null };
     }
     const domain = org.domain ?? 'the org domain';
@@ -922,6 +951,50 @@ function loginHostWaiting(org, host, recordedIds, bindingsWired, issuerPlanned)
     }
     return null;
 }
+/**
+ * Whether `org` runs the service {@link schema} belongs to, so
+ * {@link planOrgPostgres} reports a schema missing only once the org would
+ * actually need it -- CMS's, chat's and calls' entries follow their own
+ * on/off switch, the same ones this file already gates their own
+ * `coolify:*` steps on (`org.ts`'s `SiteConfig.enabled`, `ChatConfig.enabled`,
+ * `CallsConfig.enabled`); Boule's is unconditional, matching `org.ts`'s own
+ * "every org gets one" rule; the app schema follows whether any
+ * `hosting.entries` entry declares `database: true` (`coolifyDatabase`'s own
+ * gate) rather than `hosting.enabled` alone, since a hosting org with no
+ * database-bearing entry has nothing for this schema to hold.
+ */
+function orgServiceSchemaEnabled(org, schema) {
+    if (schema.schema === 'cms')
+        return org.site.enabled;
+    if (schema.schema.startsWith('chat_'))
+        return org.chat.enabled;
+    if (schema.schema.startsWith('calls_'))
+        return org.calls.enabled;
+    if (schema.schema === 'app')
+        return org.hosting.entries.some((entry) => entry.database);
+    return true;
+}
+/**
+ * #444a: reports the org's one shared Postgres server as missing until
+ * `recordedIds` says otherwise, and its fixed schema topology as missing for
+ * whichever schemas this org actually runs and has not yet recorded (see
+ * {@link orgServiceSchemaEnabled}) -- see {@link OrgPostgresPlan}'s own doc
+ * comment for why this is a `PlanDetail` field rather than `plannedSteps`
+ * entries. Nothing here is ever blocked (rule 2 does not apply: unlike chat
+ * or calls, the server and its schemas need no issuer, no ZITADEL org and no
+ * platform readiness to exist), and the server being missing never gates a
+ * schema being reported missing too -- a fresh org with every feature on
+ * reports both the same way #444a's own acceptance line asks for ("a fresh
+ * org plans one server and N schemas"), since nothing here actually depends
+ * on the server existing yet; that ordering is 444b's concern, once
+ * `plan/executor.ts` has something to run.
+ */
+function planOrgPostgres(org, recordedIds) {
+    return {
+        serverMissing: !recordedIds[ORG_POSTGRES_SERVER_SCOPE_KEY],
+        missingSchemas: ORG_SERVICE_SCHEMAS.filter((schema) => orgServiceSchemaEnabled(org, schema) && !recordedIds[schema.scopeKey]),
+    };
+}
 /** #230: restated from `executor.ts`'s `MAIL_ROLE_MAILBOXES_SCOPE_KEY`, same rule: comma-joined local parts already created. */
 const MAIL_ROLE_MAILBOXES_SCOPE_KEY = 'mail_role_mailboxes';
 /** Restated from `executor.ts`, the same rule: the app id of the org tunnel's cloudflared connector. */
@@ -1257,13 +1330,22 @@ function planChat(org, byKey, claimed, recordedIds, reading, issuerPlanned) {
         }
         return none;
     }
-    const domain = org.domain ?? 'its domain';
     if (!liveUsesDomain && desiredUsesDomain) {
+        // #463: `usesDomain` is never fired by `domain` alone (#7 amendment 1),
+        // but it can still be turned on with no domain recorded -- the step
+        // itself has nowhere to re-key onto, so this is blocked rather than
+        // planned (rule 2), not left for `coolifyChatRekey` to throw on.
+        if (!org.domain) {
+            return {
+                step: null,
+                blocked: `${org.slug}'s chat is blocked, not planned: usesDomain is on but the org has no domain to re-key onto`,
+            };
+        }
         return {
             step: {
                 action: { system: 'coolify', kind: 'chat', key: org.id, desired: { usesDomain: true } },
                 step: {
-                    description: `re-key ${org.slug}'s chat onto ${domain}, copying rooms and messages so history reads continuous`,
+                    description: `re-key ${org.slug}'s chat onto ${org.domain}, copying rooms and messages so history reads continuous`,
                     destroys: true,
                     migrates: true,
                 },
@@ -1428,6 +1510,79 @@ function planCallsService(org, byKey, claimed, callsReady, recordedIds, callsBlo
     }
     return { step: null, blocked: null };
 }
+/**
+ * The token that lets the org's calls service ask its chat who is in a room
+ * (`executor.ts`'s `coolifyCallsChat`). Chat off: nothing, unless the calls
+ * service still carries the address, which is then removed so it does not
+ * point at a chat that is gone. Both on: planned until the token is delivered
+ * and both apps run with it, also for an org whose chat and calls service
+ * already exist. An undelivered token is reported, never minted again (rule 1).
+ * Silent while chat or the calls service is itself planned or blocked: they
+ * report their own.
+ */
+function planCallsChat(org, recordedIds, upstreamPlanned, upstreamBlocked) {
+    const none = { step: null, blocked: null };
+    if (!org.calls.enabled)
+        return none;
+    const action = (desired) => ({
+        system: 'coolify',
+        kind: 'calls-chat',
+        key: org.id,
+        desired,
+    });
+    const callsServiceId = recordedIds[`coolify:calls-service:${org.id}`];
+    if (!org.chat.enabled) {
+        if (!callsServiceId || !recordedIds[CHAT_CALLS_APPLIED_SCOPE_KEY])
+            return none;
+        return {
+            step: {
+                action: action({ remove: true }),
+                step: {
+                    description: `remove the chat address and token from ${org.slug}'s calls service (chat is off) and restart it`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked: null,
+        };
+    }
+    const tokenId = recordedIds[CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY];
+    if (tokenId && !recordedIds[CHAT_CALLS_TOKEN_SCOPE_KEY]) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s calls-to-chat token is blocked, not planned: token ${tokenId} was minted but never written to both apps; remove the recorded key ${CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY} to write it again (chat-service's copy is reused, none is minted)`,
+        };
+    }
+    const guard = recordedIds[CHAT_CALLS_TOKEN_SCOPE_KEY];
+    if (guard &&
+        recordedIds[CHAT_CALLS_APPLIED_SCOPE_KEY] ===
+            chatCallsApplied(guard, chatUpstreams(org.slug).chat)) {
+        return none;
+    }
+    const ready = chatHasUpstreams(org, recordedIds) &&
+        callsServiceId &&
+        callsServiceHasName(org, recordedIds) &&
+        recordedIds[CALLS_SERVICE_DEPLOYED_SCOPE_KEY];
+    if (!ready && upstreamBlocked)
+        return none;
+    if (!ready && !upstreamPlanned) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s calls-to-chat token is blocked, not planned: chat or the calls service is not provisioned yet (apply them first)`,
+        };
+    }
+    return {
+        step: {
+            action: action({}),
+            step: {
+                description: `give ${org.slug}'s chat service and calls service one internal token, point the calls service at chat, and redeploy both`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}
 /**
  * Deduped `ai.*` permissions offered to every organisation by default
  * (Decision, this campaign's report): the minimum set that lets an org
@@ -2027,7 +2182,7 @@ function planBouleClient(org, byKey, claimed) {
  * 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, archonUrl) {
+function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonUrl, readiness) {
     const key = resourceKey('coolify', 'boule', org.id);
     const live = byKey.get(key);
     if (live)
@@ -2042,26 +2197,59 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
     if (tooLong.length > 0) {
         return {
             step: null,
+            mailBlocked: 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,
+            mailBlocked: 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,
+            mailBlocked: null,
             blocked: `${org.slug}'s Boule is blocked, not planned: the host supplies no issuer`,
         };
     }
+    // Mail env, only for a hosted-mail org whose domain is recorded. Blocked,
+    // not failing: while the platform cannot yet supply the token, Boule is
+    // planned without mail and keeps showing the invite link.
+    const mailWanted = bouleMailWanted(org, recordedIds);
+    const mailDomain = recordedIds.mail_domain?.toLowerCase();
+    const isApexOrg = Boolean(mailDomain && readiness.platformApex && mailDomain === readiness.platformApex.toLowerCase());
+    let mailBlockedReason = null;
+    if (mailWanted && isApexOrg) {
+        if (!readiness.platformLettermintProjectId) {
+            mailBlockedReason = 'platform.mail.lettermintProjectId is not declared yet';
+        }
+        else if (readiness.mailKeyHeld !== true) {
+            mailBlockedReason = `the platform's Lettermint key is not held yet (held-key ref ${PLATFORM_AUTH_BROKER_MAIL_KEY_REF})`;
+        }
+    }
+    else if (mailWanted) {
+        mailBlockedReason = edgeNeeded(readiness, ['zones', 'dns']);
+    }
+    const mailBlocked = mailBlockedReason
+        ? `${org.slug}'s Boule mail is blocked, not planned: ${mailBlockedReason}`
+        : null;
+    const mailOn = mailWanted && !mailBlocked;
     const action = {
         system: 'coolify',
         kind: 'boule',
         key: org.id,
-        desired: { issuer, archonUrl },
+        // The platform values go in like the app step's: the executor writes
+        // what the plan showed and refuses a plan that carries no `platformApex`.
+        desired: {
+            issuer,
+            archonUrl,
+            platformApex: readiness.platformApex,
+            platformLettermintProjectId: readiness.platformLettermintProjectId,
+            mailBlocked: mailBlocked !== null,
+        },
     };
     if (!live) {
         return {
@@ -2070,13 +2258,19 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
                 step: { description: `provision ${org.slug}'s Boule`, destroys: false, migrates: false },
             },
             blocked: null,
+            mailBlocked,
         };
     }
     const liveEnv = (live.config.env ?? {});
-    const { env } = desiredBouleEnv(org, recordedIds, issuer, archonUrl);
+    const { env } = desiredBouleEnv(org, recordedIds, issuer, archonUrl, mailOn);
     const drift = bouleEnvDrift(env, liveEnv);
+    // The token is compared, never planned with its value.
+    if (mailOn &&
+        bouleMailTokenDrift(liveEnv[BOULE_MAIL_TOKEN_ENV], live.config.appMailToken)) {
+        drift.push(BOULE_MAIL_TOKEN_ENV);
+    }
     if (drift.length === 0)
-        return { step: null, blocked: null };
+        return { step: null, blocked: null, mailBlocked };
     return {
         step: {
             action,
@@ -2087,6 +2281,7 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
             },
         },
         blocked: null,
+        mailBlocked,
     };
 }
 /**