@wtfalch/foundry 0.4.0 → 0.5.0

package/dist/plan/diff.js

@@ -1,3 +1,6 @@
+import { NO_AGORA_HOST_VALUES, agoraEnvDrift, agoraHostMissing, desiredAgoraEnv, } from './agora.js';
+import { ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, } from './platform-diff.js';
+import { DEFAULT_ORG_PLATFORM_READINESS } from './platform-org.js';
 /** The `Plan` (#19's public contract) a `PlanDetail` carries. */
 export function toPlan(detail) {
     return {
@@ -38,52 +41,66 @@ function resourceKey(system, kind, key) {
  * by default unlike chat's own: {@link planCalls}, the org's own calls
  * Matrix stack (`org.ts`'s `CallsConfig.enabled`). #145 adds one more,
  * planned right after it and gated on the same flag: {@link planCallsService},
- * the calls service itself (`wtfalch/calls`'s `packages/service`). Everything
- * else in `live` that none of these fifteen singletons and however many
+ * the calls service itself (`wtfalch/calls`'s `packages/service`). #164 adds
+ * two more, unconditionally -- no `DeclaredOrg` field gates either, since
+ * every org's own Agora is always on: {@link planAgoraClient}, a fixed
+ * ZITADEL web client named `agora` (modeled on {@link planCmsClient}), and
+ * {@link planAgora}, the Agora itself as a Coolify app (modeled on
+ * {@link planSite}, minus the park branch -- foundry never deletes an
+ * Agora). #173 adds one more, gated on `org.hosting.enabled` like
+ * {@link planApp} itself: {@link planJobsRegistration}, registering the org's
+ * app with the platform's jobs scheduler, idempotent on the *recorded*
+ * resource id like {@link planOwner} rather than a live resource, since
+ * nothing in `live` can report a scheduler registration (no reader exists for
+ * it). 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
  * Zitadel/Coolify/Cloudflare/Files/AI/cms shapes) is #20's "provision
  * Company Factory end to end", which wires real readers and executors
  * against this seam.
  */
-export function computePlanDetail(org, live, recordedIds = {}) {
+export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AGORA_HOST_VALUES, jobsAvailable = false, platformReadiness = DEFAULT_ORG_PLATFORM_READINESS) {
     const byKey = new Map(live.map((r) => [resourceKey(r.system, r.kind, r.key), r]));
     const claimed = new Set();
     const plannedSteps = [];
-    const issuer = planIssuer(org, byKey, claimed);
-    if (issuer)
-        plannedSteps.push(issuer);
-    const owner = planOwner(org, recordedIds);
+    const issuer = planIssuer(org, byKey, claimed, platformReadiness.authReady);
+    if (issuer.step)
+        plannedSteps.push(issuer.step);
+    const owner = planOwner(org, recordedIds, platformReadiness.authReady);
     if (owner)
         plannedSteps.push(owner);
-    const mail = planMail(org, byKey, claimed);
-    if (mail)
-        plannedSteps.push(mail);
+    const mail = planMail(org, byKey, claimed, recordedIds, platformReadiness.mailHost);
+    if (mail.step)
+        plannedSteps.push(mail.step);
     const chat = planChat(org, byKey, claimed);
     if (chat)
         plannedSteps.push(chat);
-    const calls = planCalls(org, byKey, claimed);
-    if (calls)
-        plannedSteps.push(calls);
+    const calls = planCalls(org, byKey, claimed, platformReadiness.callsReady);
+    if (calls.step)
+        plannedSteps.push(calls.step);
     // Right after the Matrix stack (#145): its own executor
     // (`executor.ts`'s `coolifyCallsService`) reads the Synapse/MAS addresses
     // and MAS client credentials `coolifyCalls` just recorded, the same
     // ordering `planOwner` relies on for `zitadel:issuer`.
-    const callsService = planCallsService(org, byKey, claimed);
-    if (callsService)
-        plannedSteps.push(callsService);
-    const filesOrganisation = planFilesOrganisation(org, byKey, claimed);
-    if (filesOrganisation)
-        plannedSteps.push(filesOrganisation);
-    const storage = planStorage(org, byKey, claimed);
-    if (storage)
-        plannedSteps.push(storage);
-    const aiOrganisation = planAiOrganisation(org, byKey, claimed);
-    if (aiOrganisation)
-        plannedSteps.push(aiOrganisation);
-    const aiBudget = planAiBudget(org, byKey, claimed);
-    if (aiBudget)
-        plannedSteps.push(aiBudget);
+    const callsService = planCallsService(org, byKey, claimed, platformReadiness.callsReady);
+    if (callsService.step)
+        plannedSteps.push(callsService.step);
+    const filesOrganisation = planFilesOrganisation(org, byKey, claimed, platformReadiness.filesReady, platformReadiness.missingKeys.files, platformReadiness.noKeyReader);
+    if (filesOrganisation.step)
+        plannedSteps.push(filesOrganisation.step);
+    const storage = planStorage(org, byKey, claimed, platformReadiness.filesReady, platformReadiness.missingKeys.files, platformReadiness.noKeyReader);
+    if (storage.step)
+        plannedSteps.push(storage.step);
+    const aiOrganisation = planAiOrganisation(org, byKey, claimed, platformReadiness.aiReady, platformReadiness.missingKeys.ai, platformReadiness.noKeyReader);
+    if (aiOrganisation.step)
+        plannedSteps.push(aiOrganisation.step);
+    const aiBudget = planAiBudget(org, byKey, claimed, platformReadiness.aiReady, platformReadiness.missingKeys.ai, platformReadiness.noKeyReader);
+    if (aiBudget.step)
+        plannedSteps.push(aiBudget.step);
+    const aiKey = planAiKey(org, recordedIds, platformReadiness.aiReady);
+    if (aiKey.step)
+        plannedSteps.push(aiKey.step);
     // Before `planSite`'s own step (#139): `cmsSite`'s executor reads this
     // step's recorded client id, the same way `coolifyApp` runs after the
     // hosted app's own `zitadel:app` steps.
@@ -134,6 +151,22 @@ export function computePlanDetail(org, live, recordedIds = {}) {
     const customers = planCustomers(org, live, claimed, recordedIds);
     if (customers)
         plannedSteps.push(customers);
+    // #164: every org's own Agora -- always on, no toggle. Last, so nothing
+    // else in the org waits on it: `runSteps` stops at the first failing step.
+    // Its fixed ZITADEL client before the Coolify app it signs into:
+    // `coolifyAgora` reads this step's recorded client id.
+    const agoraClient = planAgoraClient(org, byKey, claimed);
+    if (agoraClient)
+        plannedSteps.push(agoraClient);
+    const agora = planAgora(org, byKey, claimed, recordedIds, agoraHost);
+    if (agora.step)
+        plannedSteps.push(agora.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).
+    const jobsRegistration = planJobsRegistration(org, recordedIds, jobsAvailable || platformReadiness.jobsReady, platformReadiness.missingKeys.jobs, platformReadiness.noKeyReader);
+    if (jobsRegistration.step)
+        plannedSteps.push(jobsRegistration.step);
     // #10 (resolved): "foundry manages only what the declared org names";
     // anything left unclaimed is listed, never proposed for deletion.
     const unmanaged = live
@@ -141,6 +174,41 @@ export function computePlanDetail(org, live, recordedIds = {}) {
         .map((r) => ({
         description: `${r.system} ${r.kind} "${r.key}" is live but not named by the declared org`,
     }));
+    // A blocked Agora is reported here, not planned: a step the executor must
+    // refuse would halt every step after it. This is the plan's one non-step
+    // item list, so it rides along with the unmanaged items.
+    if (agora.blocked)
+        unmanaged.push({ description: agora.blocked, key: 'coolify:agora' });
+    // Same for an ai key minted but never delivered: planning a new mint would
+    // orphan a second live key.
+    if (aiKey.blocked)
+        unmanaged.push({ description: aiKey.blocked, key: 'ai:key' });
+    // Same for a jobs registration that cannot run (no scheduler wired) or must
+    // not run again (minted, never delivered).
+    if (jobsRegistration.blocked) {
+        unmanaged.push({ description: jobsRegistration.blocked, key: 'jobs:registration' });
+    }
+    // #177: an org step whose own shared platform service is off or not yet
+    // applied is blocked here, not planned -- the same rule, now driven by
+    // `platformReadiness` instead of a host-supplied port. Each is reported at
+    // most once even though a dependent step (owner, calls-service, storage,
+    // budget, key) would otherwise also have nothing to act on.
+    if (issuer.blocked)
+        unmanaged.push({ description: issuer.blocked, key: 'zitadel:issuer' });
+    if (mail.blocked)
+        unmanaged.push({ description: mail.blocked, key: 'coolify:mail' });
+    if (calls.blocked)
+        unmanaged.push({ description: calls.blocked, key: 'coolify:calls' });
+    if (filesOrganisation.blocked) {
+        unmanaged.push({ description: filesOrganisation.blocked, key: 'files:organisation' });
+    }
+    if (aiOrganisation.blocked) {
+        unmanaged.push({ description: aiOrganisation.blocked, key: 'ai:organisation' });
+    }
+    if (storage.blocked)
+        unmanaged.push({ description: storage.blocked, key: 'files:storage' });
+    if (aiBudget.blocked)
+        unmanaged.push({ description: aiBudget.blocked, key: 'ai:budget' });
     return { orgId: org.id, plannedSteps, unmanaged };
 }
 /**
@@ -158,48 +226,67 @@ export function computePlanDetail(org, live, recordedIds = {}) {
  * (#7 corrections 2) and is not built in v1 (decisions file, same section:
  * "domain verification and passkey invalidation need their own design"), so
  * `executor.ts` throws `NotBuiltError` on it rather than run it.
+ *
+ * #177: every org's ZITADEL org lives inside the platform's own shared
+ * sign-in (#168), so a first-ever provision (no live issuer yet) is blocked,
+ * not planned, while `platformReadiness.authReady` is false -- the same rule
+ * every platform-dependent org step in this file now follows. An issuer that
+ * already exists live is unaffected: its own domain-move logic runs
+ * regardless, since that never re-provisions the ZITADEL org itself.
  */
-function planIssuer(org, byKey, claimed) {
+function planIssuer(org, byKey, claimed, authReady) {
     const key = resourceKey('zitadel', 'issuer', org.id);
     const live = byKey.get(key);
     const desiredUsesDomain = org.issuer.usesDomain;
     if (!live) {
+        if (!authReady) {
+            return {
+                step: null,
+                blocked: `${org.slug}'s ZITADEL org is blocked, not planned: the platform's sign-in is off or not yet applied`,
+            };
+        }
         return {
-            action: {
-                system: 'zitadel',
-                kind: 'issuer',
-                key: org.id,
-                desired: { provision: true, usesDomain: desiredUsesDomain },
-            },
             step: {
-                description: `provision ${org.slug}'s own ZITADEL org`,
-                destroys: false,
-                migrates: false,
+                action: {
+                    system: 'zitadel',
+                    kind: 'issuer',
+                    key: org.id,
+                    desired: { provision: true, usesDomain: desiredUsesDomain },
+                },
+                step: {
+                    description: `provision ${org.slug}'s own ZITADEL org`,
+                    destroys: false,
+                    migrates: false,
+                },
             },
+            blocked: null,
         };
     }
     claimed.add(key);
     const liveUsesDomain = Boolean(live.config.usesDomain);
     if (liveUsesDomain === desiredUsesDomain)
-        return null;
+        return { step: null, blocked: null };
     const domain = org.domain ?? 'the org domain';
     return {
-        action: {
-            system: 'zitadel',
-            kind: 'issuer',
-            key: org.id,
-            desired: { usesDomain: desiredUsesDomain },
-        },
         step: {
-            description: desiredUsesDomain
-                ? `move the issuer onto ${domain}, invalidating every passkey in the org`
-                : `move the issuer off ${domain} back onto the shared issuer, invalidating every passkey in the org`,
-            // Any issuer move invalidates every passkey in the org (#7 corrections
-            // 2, #19 "Done when"). It never moves data between systems, so it is
-            // never `migrates`.
-            destroys: true,
-            migrates: false,
+            action: {
+                system: 'zitadel',
+                kind: 'issuer',
+                key: org.id,
+                desired: { usesDomain: desiredUsesDomain },
+            },
+            step: {
+                description: desiredUsesDomain
+                    ? `move the issuer onto ${domain}, invalidating every passkey in the org`
+                    : `move the issuer off ${domain} back onto the shared issuer, invalidating every passkey in the org`,
+                // Any issuer move invalidates every passkey in the org (#7 corrections
+                // 2, #19 "Done when"). It never moves data between systems, so it is
+                // never `migrates`.
+                destroys: true,
+                migrates: false,
+            },
         },
+        blocked: null,
     };
 }
 /**
@@ -230,12 +317,17 @@ function planIssuer(org, byKey, claimed) {
  * nothing here puts it anywhere beyond what audit already records for the
  * org.
  */
-function planOwner(org, recordedIds) {
+function planOwner(org, recordedIds, authReady) {
     if (!org.owner)
         return null;
     const key = resourceKey('zitadel', 'owner', org.id);
     if (recordedIds[key])
         return null; // already invited -- a re-run plans nothing.
+    // #177: nothing to invite into yet -- `planIssuer` already reports the
+    // platform's sign-in as blocked, so this step stays silent rather than
+    // repeating it.
+    if (!authReady)
+        return null;
     return {
         action: {
             system: 'zitadel',
@@ -254,7 +346,27 @@ function planOwner(org, recordedIds) {
         },
     };
 }
-function planMail(org, byKey, claimed) {
+/**
+ * #162: the flat scope id `executor.ts`'s `ensureOwnerMailbox` records once
+ * it has given the org's owner a mailbox (`MAIL_OWNER_MAILBOX_SCOPE_KEY`
+ * there) — restated here rather than imported, the same rule this file's own
+ * `LOG_DIR` precedent follows for a value shared with `executor.ts`.
+ */
+const MAIL_OWNER_MAILBOX_SCOPE_KEY = 'mail_owner_mailbox';
+/** Restated from `executor.ts`, the same rule: the id of an ai key minted but not delivered. */
+export 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. */
+export const JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY = 'jobs_registration_undelivered';
+/**
+ * #177: `mailHost` is `platformReadiness.mailHost` -- the platform's own
+ * `apex`/`mail.hostname` once its mail server is enabled and applied, `null`
+ * otherwise. `executor.ts`'s `coolifyMail` reads `apex`/`mailHost` straight
+ * off this step's own `desired`, the same "the executor writes exactly these
+ * host values, so what the plan showed is what gets applied" rule
+ * `planAgora` already follows for its own host values -- never rebuilding
+ * them itself from a literal or a second lookup.
+ */
+function planMail(org, byKey, claimed, recordedIds, mailHost) {
     const key = resourceKey('coolify', 'mail', org.id);
     const live = byKey.get(key);
     // `off` means mail is not foundry's concern here (org.ts's MailMode doc);
@@ -264,45 +376,90 @@ function planMail(org, byKey, claimed) {
     // after having it would silently hide its own leftover mail resource from
     // the unmanaged list.
     if (org.mail.mode === 'off')
-        return null;
+        return { step: null, blocked: null };
     if (live)
         claimed.add(key);
-    const desired = { mode: org.mail.mode, usesDomain: org.mail.usesDomain };
+    if (!mailHost) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s mail is blocked, not planned: the platform's mail server is off or not yet applied`,
+        };
+    }
+    const desired = {
+        mode: org.mail.mode,
+        usesDomain: org.mail.usesDomain,
+        apex: mailHost.apex,
+        mailHost: mailHost.mailHost,
+    };
+    // #162: an owner's mailbox is minted inside the same `coolify:mail` step,
+    // after `applyOrgMail` -- so as long as one is still owed, this step must
+    // keep showing up even once mode/usesDomain themselves have nothing left
+    // to change, or the operator would apply and never see it happen.
+    const mailboxOwed = Boolean(org.owner) && !recordedIds[MAIL_OWNER_MAILBOX_SCOPE_KEY];
+    const mailboxNote = mailboxOwed ? ` and give ${org.slug}'s owner a mailbox` : '';
     if (!live) {
         return {
-            action: { system: 'coolify', kind: 'mail', key: org.id, desired },
             step: {
-                description: `provision mail (${org.mail.mode}) for ${org.slug}`,
-                destroys: false,
-                migrates: false,
+                action: { system: 'coolify', kind: 'mail', key: org.id, desired },
+                step: {
+                    description: `provision mail (${org.mail.mode}) for ${org.slug}${mailboxNote}`,
+                    destroys: false,
+                    migrates: false,
+                },
             },
+            blocked: null,
         };
     }
     const liveMode = live.config.mode;
     const liveUsesDomain = Boolean(live.config.usesDomain);
-    if (liveMode === desired.mode && liveUsesDomain === desired.usesDomain)
-        return null;
+    if (liveMode === desired.mode && liveUsesDomain === desired.usesDomain) {
+        // #177: the platform's apex or mail host moved since this step last wrote
+        // them (or it never recorded them). Re-applying is idempotent.
+        const addressMoved = recordedIds[ORG_MAIL_APPLIED_APEX_SCOPE_KEY] !== mailHost.apex ||
+            recordedIds[ORG_MAIL_APPLIED_HOST_SCOPE_KEY] !== mailHost.mailHost;
+        if (!mailboxOwed && !addressMoved)
+            return { step: null, blocked: null };
+        return {
+            step: {
+                action: { system: 'coolify', kind: 'mail', key: org.id, desired },
+                step: {
+                    description: addressMoved
+                        ? `re-apply ${org.slug}'s mail on the platform's mail host ${mailHost.mailHost}${mailboxNote}`
+                        : `give ${org.slug}'s owner a mailbox`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked: null,
+        };
+    }
     if (liveUsesDomain && !desired.usesDomain) {
         // #7 corrections 1: parked, not deleted — mailboxes and messages stay —
         // but still disruptive enough to gate like a destructive step.
         return {
-            action: { system: 'coolify', kind: 'mail', key: org.id, desired },
             step: {
-                description: `park ${org.slug}'s mail domain (stops receiving; mailboxes and messages are retained, not deleted — #7 corrections 1)`,
-                destroys: true,
-                migrates: false,
+                action: { system: 'coolify', kind: 'mail', key: org.id, desired },
+                step: {
+                    description: `park ${org.slug}'s mail domain (stops receiving; mailboxes and messages are retained, not deleted — #7 corrections 1)`,
+                    destroys: true,
+                    migrates: false,
+                },
             },
+            blocked: null,
         };
     }
     // A mode transition (#7 "Transitions") or turning a domain on is a
     // one-time copy, never a deletion.
     return {
-        action: { system: 'coolify', kind: 'mail', key: org.id, desired },
         step: {
-            description: `move ${org.slug}'s mail from ${String(liveMode)} to ${desired.mode}`,
-            destroys: false,
-            migrates: true,
+            action: { system: 'coolify', kind: 'mail', key: org.id, desired },
+            step: {
+                description: `move ${org.slug}'s mail from ${String(liveMode)} to ${desired.mode}${mailboxNote}`,
+                destroys: false,
+                migrates: true,
+            },
         },
+        blocked: null,
     };
 }
 function planChat(org, byKey, claimed) {
@@ -364,9 +521,26 @@ function planChat(org, byKey, claimed) {
  * {@link planApp}/{@link planDatabase}/{@link planTunnel} below
  * (`planHostingToggle`, #7 corrections 1) -- turning it off parks Synapse and
  * MAS, never either database (`executor.ts`'s `coolifyCalls`).
+ *
+ * #177: a first-ever provision (no live resource yet) is blocked, not
+ * planned, while `platformReadiness.callsReady` is false -- an org's own
+ * Matrix stack is wired to the shared calls SFU (#122/#127), so there is
+ * nothing for it to authenticate calls against until the platform's own
+ * `sfu:livekit` step is declared. Parking, and an already-provisioned stack,
+ * are unaffected.
  */
-function planCalls(org, byKey, claimed) {
-    return planHostingToggle('coolify', 'calls', org.calls.enabled, org, byKey, claimed, () => `provision ${org.slug}'s calls Matrix stack (Synapse + matrix-authentication-service)`, () => `park ${org.slug}'s calls Matrix stack (stops serving; data is retained, not deleted -- #7 corrections 1)`);
+function planCalls(org, byKey, claimed, callsReady) {
+    const key = resourceKey('coolify', 'calls', org.id);
+    if (org.calls.enabled && !byKey.get(key) && !callsReady) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s calls Matrix stack is blocked, not planned: the platform's shared calls SFU is off`,
+        };
+    }
+    return {
+        step: planHostingToggle('coolify', 'calls', org.calls.enabled, org, byKey, claimed, () => `provision ${org.slug}'s calls Matrix stack (Synapse + matrix-authentication-service)`, () => `park ${org.slug}'s calls Matrix stack (stops serving; data is retained, not deleted -- #7 corrections 1)`),
+        blocked: null,
+    };
 }
 /**
  * The org's own calls service (#145, part 2 of #128) -- `wtfalch/calls`'s
@@ -379,9 +553,20 @@ function planCalls(org, byKey, claimed) {
  * planner steps. Same on/off, park-not-delete shape as {@link planCalls}
  * (`planHostingToggle`, #7 corrections 1) -- turning it off parks the app,
  * never its database (`executor.ts`'s `coolifyCallsService`).
+ *
+ * #177: silently plans nothing (no second blocked message) while the Matrix
+ * stack it rides beside is itself blocked on `callsReady` -- {@link planCalls}
+ * already reports the platform's shared SFU as missing once.
  */
-function planCallsService(org, byKey, claimed) {
-    return planHostingToggle('coolify', 'calls-service', org.calls.enabled, org, byKey, claimed, () => `provision ${org.slug}'s calls service`, () => `park ${org.slug}'s calls service (stops serving; data is retained, not deleted -- #7 corrections 1)`);
+function planCallsService(org, byKey, claimed, callsReady) {
+    const key = resourceKey('coolify', 'calls-service', org.id);
+    if (org.calls.enabled && !byKey.get(key) && !callsReady) {
+        return { step: null, blocked: null };
+    }
+    return {
+        step: planHostingToggle('coolify', 'calls-service', org.calls.enabled, org, byKey, claimed, () => `provision ${org.slug}'s calls service`, () => `park ${org.slug}'s calls service (stops serving; data is retained, not deleted -- #7 corrections 1)`),
+        blocked: null,
+    };
 }
 /**
  * Deduped `ai.*` permissions offered to every organisation by default
@@ -394,6 +579,19 @@ function planCallsService(org, byKey, claimed) {
  * explicit opt-in this default deliberately leaves out.
  */
 const AI_DEFAULT_OFFERS = ['ai.offerings:invoke', 'ai.runs:create'];
+/**
+ * Why an org step on a shared platform service is blocked: a key that is not
+ * held, no held-keys reader given at all, or the service off or not applied.
+ * Fixed text (part of the stale-plan comparison); a ref only, never a value.
+ */
+function notReadyReason(service, keyName, missingKeyRef, noKeyReader) {
+    if (missingKeyRef && noKeyReader) {
+        return `the host gave no held-keys reader and no ${service} port, so the platform's ${keyName} ${missingKeyRef} cannot be checked`;
+    }
+    return missingKeyRef
+        ? `the platform's ${keyName} ${missingKeyRef} is not held yet`
+        : `the platform's ${service} host is off or not yet applied`;
+}
 /**
  * #80: every org's own organisation on Files, a per-org singleton resource
  * planned before {@link planStorage} -- `setQuota`/`setBudget` 404 against an
@@ -407,26 +605,39 @@ const AI_DEFAULT_OFFERS = ['ai.offerings:invoke', 'ai.runs:create'];
  * concern (`org.ts`'s `StorageConfig` doc: "a separate, operator-driven hard
  * cap this field has no opinion on"), so provisioning always asks for an
  * uncapped ceiling -- Decision, this campaign's report.
+ *
+ * #177: blocked, not planned, while `filesReady` is false -- the platform's
+ * own files host (#171) is off or not yet applied, so there is nothing here
+ * for `FilesOrganisationPort.provisionOrganisation` to reach.
  */
-function planFilesOrganisation(org, byKey, claimed) {
+function planFilesOrganisation(org, byKey, claimed, filesReady, missingKeyRef, noKeyReader = false) {
     const key = resourceKey('files', 'organisation', org.id);
     const live = byKey.get(key);
     if (live) {
         claimed.add(key);
-        return null;
+        return { step: null, blocked: null };
+    }
+    if (!filesReady) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s Files organisation is blocked, not planned: ${notReadyReason('files', 'files management key', missingKeyRef, noKeyReader)}`,
+        };
     }
     return {
-        action: {
-            system: 'files',
-            kind: 'organisation',
-            key: org.id,
-            desired: { provision: true, ceilingBytes: null, ceilingMicros: null },
-        },
         step: {
-            description: `provision ${org.slug}'s own organisation on Files`,
-            destroys: false,
-            migrates: false,
+            action: {
+                system: 'files',
+                kind: 'organisation',
+                key: org.id,
+                desired: { provision: true, ceilingBytes: null, ceilingMicros: null },
+            },
+            step: {
+                description: `provision ${org.slug}'s own organisation on Files`,
+                destroys: false,
+                migrates: false,
+            },
         },
+        blocked: null,
     };
 }
 /**
@@ -443,30 +654,42 @@ function planFilesOrganisation(org, byKey, claimed) {
  * first budget row with whatever the org already declares (including
  * `null` for uncapped), so a brand new org never needs a follow-up
  * {@link planAiBudget} step just to reach its own declared default.
+ *
+ * #177: blocked, not planned, while `aiReady` is false -- the platform's own
+ * AI host (#172) is off or not yet applied.
  */
-function planAiOrganisation(org, byKey, claimed) {
+function planAiOrganisation(org, byKey, claimed, aiReady, missingKeyRef, noKeyReader = false) {
     const key = resourceKey('ai', 'organisation', org.id);
     const live = byKey.get(key);
     if (live) {
         claimed.add(key);
-        return null;
+        return { step: null, blocked: null };
+    }
+    if (!aiReady) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s AI organisation is blocked, not planned: ${notReadyReason('AI', 'AI management key', missingKeyRef, noKeyReader)}`,
+        };
     }
     return {
-        action: {
-            system: 'ai',
-            kind: 'organisation',
-            key: org.id,
-            desired: {
-                provision: true,
-                limitMicros: org.ai.limitMicros,
-                offers: [...AI_DEFAULT_OFFERS],
-            },
-        },
         step: {
-            description: `provision ${org.slug}'s own organisation on AI and switch AI use on`,
-            destroys: false,
-            migrates: false,
+            action: {
+                system: 'ai',
+                kind: 'organisation',
+                key: org.id,
+                desired: {
+                    provision: true,
+                    limitMicros: org.ai.limitMicros,
+                    offers: [...AI_DEFAULT_OFFERS],
+                },
+            },
+            step: {
+                description: `provision ${org.slug}'s own organisation on AI and switch AI use on`,
+                destroys: false,
+                migrates: false,
+            },
         },
+        blocked: null,
     };
 }
 /**
@@ -476,23 +699,40 @@ function planAiOrganisation(org, byKey, claimed) {
  * reversible"). A missing live resource reads as uncapped (`null`), the same
  * value a freshly-declared org's `storage` starts at, so a brand new org with
  * no limits declared produces no step.
+ *
+ * #177: silently plans nothing while there is no organisation to size a limit
+ * on yet and `filesReady` is false -- {@link planFilesOrganisation} already
+ * reports the platform's files host as missing once.
  */
-function planStorage(org, byKey, claimed) {
+function planStorage(org, byKey, claimed, filesReady, missingKeyRef, noKeyReader = false) {
     const key = resourceKey('files', 'storage', org.id);
     const live = byKey.get(key);
     if (live)
         claimed.add(key);
+    if (!filesReady && !live)
+        return { step: null, blocked: null };
     const desired = { limitBytes: org.storage.limitBytes, limitMicros: org.storage.limitMicros };
     const liveLimitBytes = live ? (live.config.limitBytes ?? null) : null;
     const liveLimitMicros = live ? (live.config.limitMicros ?? null) : null;
-    if (liveLimitBytes === desired.limitBytes && liveLimitMicros === desired.limitMicros)
-        return null;
+    if (liveLimitBytes === desired.limitBytes && liveLimitMicros === desired.limitMicros) {
+        return { step: null, blocked: null };
+    }
+    // A live resource with drift needs the platform's key to change; blocked, not planned to throw at apply.
+    if (!filesReady) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s storage limit change is blocked, not planned: ${notReadyReason('files', 'files management key', missingKeyRef, noKeyReader)}`,
+        };
+    }
     return {
-        action: { system: 'files', kind: 'storage', key: org.id, desired },
+        blocked: null,
         step: {
-            description: `set ${org.slug}'s storage limit to ${desired.limitBytes ?? 'uncapped'} bytes / ${desired.limitMicros ?? 'uncapped'} micros`,
-            destroys: false,
-            migrates: false,
+            action: { system: 'files', kind: 'storage', key: org.id, desired },
+            step: {
+                description: `set ${org.slug}'s storage limit to ${desired.limitBytes ?? 'uncapped'} bytes / ${desired.limitMicros ?? 'uncapped'} micros`,
+                destroys: false,
+                migrates: false,
+            },
         },
     };
 }
@@ -502,22 +742,93 @@ function planStorage(org, byKey, claimed) {
  * (#80), which already seeds a brand new org's first budget row from this
  * same `org.ai.limitMicros` -- this planner only fires again once that row's
  * live value has drifted from what is declared.
+ *
+ * #177: silently plans nothing while there is no organisation to size a
+ * budget on yet and `aiReady` is false -- {@link planAiOrganisation} already
+ * reports the platform's AI host as missing once.
  */
-function planAiBudget(org, byKey, claimed) {
+function planAiBudget(org, byKey, claimed, aiReady, missingKeyRef, noKeyReader = false) {
     const key = resourceKey('ai', 'budget', org.id);
     const live = byKey.get(key);
     if (live)
         claimed.add(key);
+    if (!aiReady && !live)
+        return { step: null, blocked: null };
     const desired = { limitMicros: org.ai.limitMicros };
     const liveLimitMicros = live ? (live.config.limitMicros ?? null) : null;
     if (liveLimitMicros === desired.limitMicros)
-        return null;
+        return { step: null, blocked: null };
+    if (!aiReady) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s AI budget change is blocked, not planned: ${notReadyReason('AI', 'AI management key', missingKeyRef, noKeyReader)}`,
+        };
+    }
     return {
-        action: { system: 'ai', kind: 'budget', key: org.id, desired },
+        blocked: null,
         step: {
-            description: `set ${org.slug}'s AI budget limit to ${desired.limitMicros ?? 'uncapped'} micros`,
-            destroys: false,
-            migrates: false,
+            action: { system: 'ai', kind: 'budget', key: org.id, desired },
+            step: {
+                description: `set ${org.slug}'s AI budget limit to ${desired.limitMicros ?? 'uncapped'} micros`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+    };
+}
+/**
+ * #80 step 3: the org's own ai key, minted once its organisation is
+ * provisioned and offered ({@link planAiOrganisation}). Idempotent on the
+ * *recorded* resource id (`recordedIds['ai:key:<orgId>']`), the same shape
+ * {@link planOwner} uses and for the same reason: ai's `issueOrganisationKey`
+ * (`wtfalch/ai#108`/`#113`) shows a key's secret exactly once and offers no
+ * way to list or look up an already-minted key by name, so there is nothing
+ * in `live` an existing key could ever appear as. `permissions` mirrors
+ * {@link AI_DEFAULT_OFFERS} -- the key can only do what the org's own offers
+ * already allow, so the two only ever widen together.
+ *
+ * Not built here: rotating the key before its `expiresDays` runs out. #80
+ * only asks for "give every org... a working ai key"; renewal is its own
+ * follow-up once a real org has carried one for a while.
+ *
+ * #177: silently plans nothing while `aiReady` is false -- there is no
+ * organisation to mint a key inside yet, and {@link planAiOrganisation}
+ * already reports the platform's AI host as missing once.
+ */
+function planAiKey(org, recordedIds, aiReady) {
+    const key = resourceKey('ai', 'key', org.id);
+    if (recordedIds[key])
+        return { step: null, blocked: null }; // delivered -- a re-run plans nothing.
+    if (!aiReady)
+        return { step: null, blocked: null };
+    // Minted but never delivered (`executor.ts`'s `aiKey`): nobody holds the
+    // secret and ai has no per-key revoke yet, so a new mint would only add
+    // another orphan. Reported, not planned.
+    const undelivered = recordedIds[AI_KEY_UNDELIVERED_SCOPE_KEY];
+    if (undelivered) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s ai key ${undelivered} was minted but not delivered and must be revoked in ai before a new one is minted (https://github.com/wtfalch/ai/issues/138)`,
+        };
+    }
+    return {
+        blocked: null,
+        step: {
+            action: {
+                system: 'ai',
+                kind: 'key',
+                key: org.id,
+                desired: {
+                    name: `${org.slug}-app`,
+                    expiresDays: 365,
+                    permissions: [...AI_DEFAULT_OFFERS],
+                },
+            },
+            step: {
+                description: `mint ${org.slug}'s own ai key`,
+                destroys: false,
+                migrates: false,
+            },
         },
     };
 }
@@ -624,6 +935,129 @@ function planSite(org, byKey, claimed) {
         },
     };
 }
+/**
+ * https://github.com/wtfalch/foundry/issues/164 (per William,
+ * https://github.com/wtfalch/foundry/issues/161#issuecomment-5890087180:
+ * "every company gets its own Agora, always on"): every org gets one fixed
+ * ZITADEL web client named `agora`, so its Agora workspace
+ * (https://github.com/wtfalch/agora) can sign anyone in -- automatically,
+ * with no new field on `DeclaredOrg` (unlike {@link planCmsClient}'s own
+ * `cms` client, which only exists once `org.site.enabled` is true). Modeled
+ * on {@link planIssuerApps}'s/{@link planCmsClient}'s single-app shape:
+ * provision when missing, recreate when the live `appType` differs, nothing
+ * otherwise. There is no park for this client either, for the same reason
+ * `planIssuerApps`'s own doc comment gives -- ZITADEL has no notion of a
+ * disabled-but-retained OIDC client.
+ */
+function planAgoraClient(org, byKey, claimed) {
+    const key = resourceKey('zitadel', 'app', 'agora');
+    const live = byKey.get(key);
+    if (live)
+        claimed.add(key);
+    const desired = { appType: 'web' };
+    if (!live) {
+        return {
+            action: { system: 'zitadel', kind: 'app', key: 'agora', desired },
+            step: {
+                description: `provision the web ZITADEL app 'agora' for ${org.slug}'s Agora sign-in`,
+                destroys: false,
+                migrates: false,
+            },
+        };
+    }
+    if (live.config.appType === 'web')
+        return null;
+    return {
+        action: { system: 'zitadel', kind: 'app', key: 'agora', desired },
+        step: {
+            description: `recreate ZITADEL app 'agora' for ${org.slug} as web (was ${String(live.config.appType)})`,
+            destroys: true,
+            migrates: false,
+        },
+    };
+}
+/**
+ * #164: the org's own Agora, a per-org singleton resource keyed by the org
+ * id like {@link planMail}/{@link planSite}, but under its own `agora` kind
+ * rather than `app` -- it is a separate Coolify application from the org's
+ * own hosted app ({@link planApp}, `org.hosting.enabled`), provisioned from
+ * https://github.com/wtfalch/agora's `apps/agora/Dockerfile`
+ * (`executor.ts`'s `coolifyAgora`), never toggled by any declared field.
+ *
+ * Once the app is live this still plans an update whenever the live app's
+ * Agora env (`config.env`, read by `providers-readers.ts`) lacks a desired
+ * key or holds a different value, using `agora.ts`'s `desiredAgoraEnv`, the
+ * same function the executor writes from. There is no park branch: foundry
+ * never deletes an Agora.
+ *
+ * The host supplies the issuer and the mail/messaging project ids
+ * (`agora.ts`'s `AgoraHostPort`). While it lacks any (or has no port, or the
+ * port throws), no step is planned at all: the blocked Agora comes back as a
+ * message naming each missing value, which `computePlanDetail` lists with the
+ * plan's non-step items, so every other step still applies.
+ */
+function planAgora(org, byKey, claimed, recordedIds, reading) {
+    const key = resourceKey('coolify', 'agora', org.id);
+    const live = byKey.get(key);
+    if (live)
+        claimed.add(key);
+    const error = 'error' in reading ? reading.error : null;
+    const host = 'error' in reading ? NO_AGORA_HOST_VALUES : reading;
+    const missing = agoraHostMissing(host);
+    if (missing.length > 0) {
+        // A fixed text, never the port's own message: this line is part of the
+        // stale-plan comparison, and an error that varies per call would refuse
+        // every apply as stale.
+        const why = error ? ' (reading them failed)' : '';
+        return {
+            step: null,
+            blocked: `${org.slug}'s Agora is blocked, not planned: the host supplies no ${missing.join(', ')}${why}`,
+        };
+    }
+    // The executor writes exactly these host values, so what the plan showed
+    // is what gets applied; the ids only the apply itself records are read at
+    // run time.
+    const action = {
+        system: 'coolify',
+        kind: 'agora',
+        key: org.id,
+        desired: { host },
+    };
+    if (!live) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `provision ${org.slug}'s Agora`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked: null,
+        };
+    }
+    const liveEnv = (live.config.env ?? {});
+    const { env } = desiredAgoraEnv(org, recordedIds, host);
+    const drift = agoraEnvDrift(env, liveEnv);
+    // The ZITADEL ids may be unrecorded (so `env` has no AGORA_CONFIG to
+    // compare); a live app with no AGORA_CONFIG at all still needs one.
+    if (liveEnv.AGORA_CONFIG === undefined && !drift.includes('AGORA_CONFIG')) {
+        drift.push('AGORA_CONFIG');
+    }
+    if (drift.length === 0)
+        return { step: null, blocked: null };
+    return {
+        step: {
+            action,
+            step: {
+                description: `update ${org.slug}'s Agora 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
@@ -704,6 +1138,72 @@ function planApp(org, byKey, claimed) {
         },
     };
 }
+/**
+ * #173: register the org's own app with the platform's jobs scheduler
+ * (https://github.com/wtfalch/jobs's admin API, jobs#62), so the scheduler
+ * knows where to deliver that org's schedules. Idempotent on the *recorded*
+ * resource id, the same shape {@link planOwner} uses for inviting a human
+ * owner by email: nothing in `live` can report "is this org registered" (no
+ * reader exists for the scheduler's own admin API), and the admin API's own
+ * `POST /admin/projects` is itself idempotent by `(name, baseUrl)` -- a
+ * repeat call returns `200` with just the project id, never a fresh secret --
+ * but this plan-level gate means a re-plan after a successful apply proposes
+ * nothing at all, rather than relying on the executor to notice the repeat
+ * every time.
+ *
+ * Only planned once the org has its own app to register
+ * (`org.hosting.enabled`) -- an org with no hosted app has no `baseUrl` for
+ * the scheduler to deliver to. The hostname is derived the same way
+ * {@link planSite}'s own `hostname` local does: `DeclaredOrg.domain` once
+ * `hosting.usesDomain` is true, `<slug>.oikos.host` otherwise.
+ */
+function planJobsRegistration(org, recordedIds, jobsAvailable, missingKeyRef = null, noKeyReader = false) {
+    if (!org.hosting.enabled)
+        return { step: null, blocked: null };
+    const key = resourceKey('jobs', 'registration', org.id);
+    if (recordedIds[key])
+        return { step: null, blocked: null }; // already registered -- a re-run plans nothing.
+    // Registered but the credentials never reached the host (`executor.ts`'s
+    // `jobsRegistration`): the scheduler shows them once and a repeat call
+    // returns only the id, so planning the step again would record success with
+    // no sync key. Reported, not planned.
+    const undelivered = recordedIds[JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY];
+    if (undelivered) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s jobs registration ${undelivered} was registered but its credentials were not delivered; deregister it in the scheduler (DELETE /admin/projects/${org.slug}) and clear the recorded id before registering again`,
+        };
+    }
+    // The host says whether its executor has a scheduler to register with. A
+    // fixed text: it is part of the stale-plan comparison.
+    if (!jobsAvailable) {
+        return {
+            step: null,
+            blocked: !missingKeyRef
+                ? `${org.slug}'s jobs registration is blocked, not planned: the host supplies no jobs scheduler`
+                : `${org.slug}'s jobs registration is blocked, not planned: ${noKeyReader
+                    ? `the host gave no held-keys reader and no jobs scheduler port, so the platform's jobs admin token ${missingKeyRef} cannot be checked`
+                    : `the platform's jobs admin token ${missingKeyRef} is not held yet`}`,
+        };
+    }
+    const hostname = org.hosting.usesDomain && org.domain ? org.domain : `${org.slug}.oikos.host`;
+    return {
+        blocked: null,
+        step: {
+            action: {
+                system: 'jobs',
+                kind: 'registration',
+                key: org.id,
+                desired: { name: org.slug, baseUrl: `https://${hostname}` },
+            },
+            step: {
+                description: `register ${org.slug}'s app with the jobs scheduler`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+    };
+}
 /**
  * A Postgres database beside the org's app (`org.ts`'s
  * `HostingConfig.database`, #71) -- `validateHosting` requires
@@ -736,11 +1236,19 @@ function planDatabase(org, byKey, claimed) {
  * needs a tunnel too, for the same reason a site does -- an org that wants
  * `calls.<domain>` but declares no other own-domain feature must still get
  * one provisioned, not silently have nowhere for that hostname to route.
+ *
+ * #164: Agora needs a tunnel for the same reason, the moment `org.domain` is
+ * set. Agora is always on (William, 2026-09-29), so every org with a domain
+ * needs routing for `agora.<domain>` even with hosting and site off -- there
+ * is no `usesDomain` flag of its own to gate this on. A level-1 org (no
+ * domain) plans no per-org tunnel for Agora: `<slug>-agora.oikos.host` rides
+ * the shared `*.oikos.host` wildcard tunnel (`scripts/shared-ingress.mjs`).
  */
 function planTunnel(org, byKey, claimed) {
     const desired = (org.hosting.tunnel && org.hosting.usesDomain && Boolean(org.domain)) ||
         (org.site.enabled && Boolean(org.domain)) ||
-        (org.calls.enabled && org.calls.usesDomain && Boolean(org.domain));
+        (org.calls.enabled && org.calls.usesDomain && Boolean(org.domain)) ||
+        Boolean(org.domain);
     return planHostingToggle('cloudflare', 'tunnel', desired, org, byKey, claimed, () => `provision a Cloudflare tunnel for ${org.slug}'s app`, () => `park ${org.slug}'s Cloudflare tunnel (configuration is retained, not deleted -- #7 corrections 1)`);
 }
 /**
@@ -762,9 +1270,16 @@ function planTunnel(org, byKey, claimed) {
  * #145: an own-domain calls service (`org.ts`'s `CallsConfig.usesDomain`)
  * needs a zone for the same reason, whether or not the org also has hosting
  * or a site on its domain.
+ *
+ * #164: Agora needs a zone for the same reason, the moment `org.domain` is
+ * set -- Agora is always on, so every org with a domain wants its zone even
+ * with hosting and site off (see {@link planTunnel}).
  */
 function planZone(org, byKey, claimed) {
-    const usesDomain = org.hosting.usesDomain || org.site.enabled || (org.calls.enabled && org.calls.usesDomain);
+    const usesDomain = org.hosting.usesDomain ||
+        org.site.enabled ||
+        (org.calls.enabled && org.calls.usesDomain) ||
+        Boolean(org.domain);
     if (!usesDomain || !org.domain)
         return null;
     const key = resourceKey('cloudflare', 'zone', org.domain);