@wtfalch/foundry 0.17.0 → 0.17.1

package/dist/plan/diff.js

@@ -3,12 +3,14 @@ import { APP_ENTRY_KEY, ownerMailboxRecorded, ownerMailboxes } from '../org.js';
 import { AGORA_ACTIVATED_ENV_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_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 { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
+import { planEdgeWorkers } from './edge-worker.js';
 import { planEntryAiKeys } from './entry-ai-key.js';
 import { planFilesKeys } from './entry-files-key.js';
+import { planEntryNamesKeys, planNamesReservedLabels } from './entry-names-key.js';
 import { appHostname, entryHostnames, tunnelDnsHostnames } from './hostnames.js';
 import { LOGIN_BINDING_SCOPE_KEY, loginBindingState, loginHostClientIds, loginHostnameFor, pendingRemovalHosts, } from './login-host.js';
 import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, } from './mail-copy.js';
-import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, appEnvAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, versionNotAppliedLine, } from './platform-diff.js';
+import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, appEnvAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, serviceDbEnvAppliedScopeKey, versionNotAppliedLine, } from './platform-diff.js';
 import { DEFAULT_ORG_PLATFORM_READINESS } from './platform-org.js';
 import { PLATFORM_AUTH_BROKER_MAIL_KEY_REF } from './platform-providers.js';
 import { appLabelsAppliedScopeKey, entryLabelHash, entryLabelSpec } from './proxy-labels.js';
@@ -87,7 +89,12 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // #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.
-    const loginHost = planLoginHost(org, recordedIds, platformReadiness.authReady, issuer.step !== null, options.loginHostBindings ?? false);
+    const loginHost = planLoginHost(org, recordedIds, platformReadiness.authReady, issuer.step !== null, options.loginHostBindings ?? false, 
+    // #488: `agoraHost.issuer` is the shared ZITADEL instance's own issuer
+    // URL (`https://<platform.auth.hostname>`), the same value every org's
+    // sign-in already reads through `planOwners` above -- no separate port
+    // or plumbing needed to know the platform's own auth hostname.
+    platformAuthHostnameFrom('error' in agoraHost ? null : agoraHost.issuer));
     if (loginHost.step)
         plannedSteps.push(loginHost.step);
     // Planned ahead of everything that needs the zone live (#238); its own step
@@ -95,7 +102,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const zone = planZone(org, byKey, claimed);
     const zoneWaiting = zone.blocked !== null;
     const zoneBlocked = [];
-    const mail = planMail(org, byKey, claimed, recordedIds, platformReadiness.mailHost);
+    const mail = planMail(org, byKey, claimed, recordedIds, platformReadiness.mailHost, platformReadiness.platformApex, platformReadiness.platformLettermintProjectId);
     // #238: own-domain mail publishes DNS records into the zone, so it waits for
     // an active zone -- blocked, not planned (rule 2).
     if (mail.step && zoneWaiting && org.mail.usesDomain && org.domain) {
@@ -197,6 +204,16 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // F6b: after the owner, the apps and the files organisation it needs.
     const filesKeys = planFilesKeys(org, recordedIds, plannedSteps, platformReadiness, (options.now ?? Date.now)());
     plannedSteps.push(...filesKeys.steps);
+    // F7 (#317): reserved labels before any entry's own key, so a label is
+    // never claimable by a customer in the gap between an entry's key going
+    // live and its siblings' labels reaching names.
+    const namesReservedLabels = planNamesReservedLabels(org, recordedIds, platformReadiness);
+    if (namesReservedLabels.step)
+        plannedSteps.push(namesReservedLabels.step);
+    // After the apps -- a names key needs the entry's app recorded, the same
+    // dependency `planEntryAiKeys`/`planFilesKeys` have.
+    const entryNamesKeys = planEntryNamesKeys(org, recordedIds, plannedSteps, platformReadiness, (options.now ?? Date.now)());
+    plannedSteps.push(...entryNamesKeys.steps);
     const tunnel = planTunnel(org, byKey, claimed, recordedIds);
     // #238: a tunnel that is being provisioned waits for an active zone; parking
     // one never does.
@@ -254,6 +271,26 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const jobsRegistration = planJobsRegistration(org, recordedIds, jobsAvailable || platformReadiness.jobsReady, platformReadiness.missingKeys.jobs, platformReadiness.noKeyReader);
     if (jobsRegistration.step)
         plannedSteps.push(jobsRegistration.step);
+    // F8 (#318), after Agora and Boule, not right after the zone: a route
+    // already bound by a hand-made entry, another entry's route, a taken
+    // script name, or no Workers token all throw at apply, and `runSteps`
+    // stops at the first failure -- planned this early, a failing edge step
+    // stopped Agora (and everything after it) from provisioning at all
+    // (#318 re-review). `cloudflareWorker` still resolves the zone by apex
+    // domain the same way `planRateLimit` does, so a deploy (never a
+    // retire, which needs no new zone) still waits for it.
+    const edgeWorkers = planEdgeWorkers(org, recordedIds, options.edgeWorkers ?? false);
+    for (const step of edgeWorkers.steps) {
+        if (zoneWaiting && step.action.desired.mode === 'apply') {
+            zoneBlocked.push({
+                description: `${org.slug}'s ${step.action.key.slice(org.id.length + 1)} edge Worker is blocked, not planned: the zone for ${org.domain} is not active yet`,
+                key: step.action.key,
+            });
+        }
+        else {
+            plannedSteps.push(step);
+        }
+    }
     // #10 (resolved): "foundry manages only what the declared org names";
     // anything left unclaimed is listed, never proposed for deletion.
     const unmanaged = live
@@ -274,6 +311,9 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         unmanaged.push({ description: aiKey.blocked, key: 'ai:key' });
     unmanaged.push(...filesKeys.blocked);
     unmanaged.push(...entryAiKeys.blocked);
+    unmanaged.push(...edgeWorkers.blocked);
+    unmanaged.push(...entryNamesKeys.blocked);
+    unmanaged.push(...namesReservedLabels.blocked);
     // Same for a jobs registration that cannot run (no scheduler wired) or must
     // not run again (minted, never delivered).
     if (jobsRegistration.blocked) {
@@ -471,6 +511,24 @@ function planOwners(org, recordedIds, authReady, authIssuer) {
     });
     return steps;
 }
+/**
+ * #488: the bare hostname out of an issuer URL (`https://<hostname>`, the
+ * only shape {@link agoraHostValuesFromPlatform} or a host-supplied
+ * `AgoraHostPort` ever hands back), or `null` when there is no issuer to
+ * read one from. What {@link loginHostnameFor} compares the org's own
+ * computed `auth.<domain>` against, so the platform's own org never plans
+ * its login host equal to the shared ZITADEL instance's own.
+ */
+function platformAuthHostnameFrom(issuer) {
+    if (!issuer)
+        return null;
+    try {
+        return new URL(issuer).hostname;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * #267: the org's own company login host (`login-host.ts`'s
  * `loginHostnameFor`) -- `auth.<domain>` once the org has one,
@@ -501,11 +559,22 @@ function planOwners(org, recordedIds, authReady, authIssuer) {
  * runs well before `planIssuerApps`/`planCmsClient`/`planAgoraClient`
  * create any app under the org's project -- #267's own "before any app's
  * issuer application".
+ *
+ * `platformAuthHostname` (#488) is threaded through to {@link
+ * loginHostnameFor} so the platform's own org, declared with-domain on the
+ * platform's own domain, never plans the shared ZITADEL instance's own login
+ * host as its own -- `auth.companyincluded.com` colliding with itself.
  */
-function planLoginHost(org, recordedIds, authReady, issuerPlanned, bindingsWired) {
+function planLoginHost(org, recordedIds, authReady, issuerPlanned, bindingsWired, platformAuthHostname) {
     const none = { step: null, blocked: null };
     const key = resourceKey('zitadel', 'login-host', org.id);
-    const host = loginHostnameFor(org);
+    const host = loginHostnameFor(org, platformAuthHostname);
+    // #488: the guard in `loginHostnameFor` fired -- the org's own domain host
+    // would have been the platform's shared ZITADEL instance host.
+    const sharedInstanceHost = Boolean(org.domain) &&
+        org.issuer.usesDomain &&
+        `auth.${org.domain}` === platformAuthHostname &&
+        host !== `auth.${org.domain}`;
     // Already applied -- a re-run plans nothing unless the host changed, an app
     // client id appeared since the binding was last written (#267, rule 4), or
     // an earlier host change still has a removal owed (#274 fix round 2):
@@ -549,7 +618,9 @@ function planLoginHost(org, recordedIds, authReady, issuerPlanned, bindingsWired
                 desired: { host },
             },
             step: {
-                description: `set ${org.slug}'s login host to ${host}`,
+                description: sharedInstanceHost
+                    ? `set ${org.slug}'s login host to ${host}: its domain host (auth.${org.domain}) is the platform's own shared ZITADEL instance host, so it stays on oikos.host`
+                    : `set ${org.slug}'s login host to ${host}`,
                 destroys: false,
                 migrates: false,
             },
@@ -577,9 +648,14 @@ export const JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY = 'jobs_registration_undeli
  * 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.
+ * them itself from a literal or a second lookup. #491: `platformApex` and
+ * `platformLettermintProjectId` go into `desired` the same way, so the
+ * executor can recognise the platform's own org without needing the whole
+ * `DeclaredPlatform`.
  */
-function planMail(org, byKey, claimed, recordedIds, mailHost) {
+function planMail(org, byKey, claimed, recordedIds, mailHost, 
+/** #491 (review round 2): read off `platformReadiness` directly, not off `mailHost` -- see `OrgPlatformReadiness.platformApex`'s own doc comment for why. */
+platformApex, platformLettermintProjectId) {
     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);
@@ -599,11 +675,32 @@ function planMail(org, byKey, claimed, recordedIds, mailHost) {
             mailboxBlocked: null,
         };
     }
+    // #491: this org's own declared domain is the platform's apex (Company
+    // Included on companyincluded.com, today) -- it shares the platform's
+    // existing Lettermint project rather than minting a `<slug>-app` one of
+    // its own, and `executor.ts` must never touch Lettermint for it until an
+    // operator has said which project that is. Blocked whole, not planned
+    // half-ready: "Blocked, not failing" (foundry's own CLAUDE.md).
+    const resolvedMailDomain = org.mail.usesDomain ? org.domain : null;
+    const isPlatformApexOrg = Boolean(resolvedMailDomain &&
+        platformApex &&
+        resolvedMailDomain.toLowerCase() === platformApex.toLowerCase());
+    if (isPlatformApexOrg && !platformLettermintProjectId) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s mail is blocked, not planned: its domain ${resolvedMailDomain} is the platform's own apex, and platform.mail.lettermintProjectId is not declared yet (#491)`,
+            mailboxBlocked: null,
+        };
+    }
     const desired = {
         mode: org.mail.mode,
         usesDomain: org.mail.usesDomain,
         apex: mailHost.apex,
         mailHost: mailHost.mailHost,
+        // #491: non-null whenever `mailHost` is -- both require a declared
+        // platform (`orgPlatformReadinessFrom`'s own doc comment).
+        platformApex,
+        platformLettermintProjectId,
     };
     // #162 (decided 2026-09-29): an owner's mailbox is minted inside the same
     // `coolify:mail` step, after `applyOrgMail` -- so as long as one is still
@@ -799,8 +896,35 @@ function planChat(org, byKey, claimed, recordedIds, reading, issuerPlanned) {
         };
     }
     const liveUsesDomain = Boolean(live.config.usesDomain);
-    if (liveUsesDomain === desiredUsesDomain)
+    if (liveUsesDomain === desiredUsesDomain) {
+        // #456: a live chat app made before the owner/runtime database split
+        // (#239) otherwise never gets another `coolify:chat` step at all --
+        // nothing else here ever differs for it again -- and its service keeps
+        // running on the bare superuser `DATABASE_URL` its own startup script
+        // now refuses. `coolifyChat` throws on any other action against an
+        // already-live chat (re-keying is not built, #7 amendment 3), so this
+        // step carries a distinct flag telling the executor to push only the
+        // split, never to replay the full provision.
+        if (!recordedIds[serviceDbEnvAppliedScopeKey('chat')]) {
+            return {
+                step: {
+                    action: {
+                        system: 'coolify',
+                        kind: 'chat',
+                        key: org.id,
+                        desired: { usesDomain: liveUsesDomain, refreshDatabaseSplit: true },
+                    },
+                    step: {
+                        description: `give ${org.slug}'s chat service its owner and runtime database URLs and redeploy it (#239, #456)`,
+                        destroys: false,
+                        migrates: false,
+                    },
+                },
+                blocked: null,
+            };
+        }
         return none;
+    }
     const domain = org.domain ?? 'its domain';
     if (!liveUsesDomain && desiredUsesDomain) {
         return {
@@ -933,17 +1057,19 @@ function planCallsService(org, byKey, claimed, callsReady, recordedIds, callsBlo
         : step;
     if (toggle)
         return { step: withHost(toggle), blocked: null };
-    // A live, enabled app made before the internal name or the token env
-    // existed has no step from the toggle. Run the step again until the
-    // executor has recorded both markers, but only while it can succeed: the
-    // SFU ready and the Matrix stack not blocked.
+    // A live, enabled app made before the internal name, the token env or the
+    // owner/runtime database split (#239, #456) existed has no step from the
+    // toggle. Run the step again until the executor has recorded every marker,
+    // but only while it can succeed: the SFU ready and the Matrix stack not
+    // blocked.
     const missingName = !callsServiceHasName(org, recordedIds);
     const missingTokenEnv = !callsServiceHasTokenEnv(tokenHost, recordedIds);
+    const missingDbSplit = !recordedIds[serviceDbEnvAppliedScopeKey('calls-service')];
     if (org.calls.enabled &&
         callsReady &&
         !callsBlocked &&
         byKey.has(key) &&
-        (missingName || missingTokenEnv)) {
+        (missingName || missingTokenEnv || missingDbSplit)) {
         return {
             step: withHost({
                 action: {
@@ -955,7 +1081,9 @@ function planCallsService(org, byKey, claimed, callsReady, recordedIds, callsBlo
                 step: {
                     description: missingName
                         ? `set the calls service's internal name for ${org.slug}`
-                        : `set the calls service's ZITADEL token env for ${org.slug}`,
+                        : missingTokenEnv
+                            ? `set the calls service's ZITADEL token env for ${org.slug}`
+                            : `give the calls service's owner and runtime database URLs for ${org.slug} and redeploy it (#239, #456)`,
                     destroys: false,
                     migrates: false,
                 },
@@ -976,6 +1104,32 @@ function planCallsService(org, byKey, claimed, callsReady, recordedIds, callsBlo
  * explicit opt-in this default deliberately leaves out.
  */
 const AI_DEFAULT_OFFERS = ['ai.offerings:invoke', 'ai.runs:create'];
+/**
+ * #484: the spend cap foundry applies when an org declares no AI limit
+ * (`org.ai.limitMicros === null`) -- Archon creates every company that way,
+ * and AI's own `updateBudget` has no uncapped representation
+ * (`UpdateBudget.limitMicros` is a required string), so a null limit used to
+ * throw `ai:budget` out of every apply. William's Decision, 2026-10-05: 100
+ * EUR, in `ai`'s own USD-micros unit (`usdToMicros`,
+ * `ai/packages/service/src/money.ts`), billing to revisit the number later.
+ * 100 EUR at the ECB reference rate for 2 October 2026 (1.1225 USD/EUR, the
+ * most recent published rate as of the decision) is 112.25 USD = 112,250,000
+ * micros. A declared numeric limit always wins over this default --
+ * {@link effectiveAiLimitMicros} is the one place that substitutes it.
+ */
+export const DEFAULT_AI_LIMIT_MICROS = '112250000';
+/**
+ * #484: the limit foundry actually plans and applies for an org -- its own
+ * declared `ai.limitMicros` when it declares one, else {@link DEFAULT_AI_LIMIT_MICROS}.
+ * Both {@link planAiOrganisation} and {@link planAiBudget} fill
+ * `action.desired.limitMicros` through this one function, so a company with
+ * no declared limit gets the same 100 EUR cap whichever step sets it, and
+ * never reaches `executor.ts`'s `aiBudget` with a null `desired.limitMicros`
+ * for `updateBudget` to choke on.
+ */
+function effectiveAiLimitMicros(limitMicros) {
+    return limitMicros ?? DEFAULT_AI_LIMIT_MICROS;
+}
 /**
  * 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.
@@ -1073,9 +1227,14 @@ function planFilesOrganisation(org, byKey, claimed, filesReady, missingKeyRef, n
  * regardless), so the only planned state is "not provisioned yet".
  * `AI_DEFAULT_OFFERS` is this campaign's Decision for what "AI use is
  * switched on" means by default; `limitMicros` seeds the organisation's
- * 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.
+ * first budget row with the org's own declared limit, or
+ * {@link DEFAULT_AI_LIMIT_MICROS} when it declares none (#484) --
+ * {@link effectiveAiLimitMicros} either way, the same value
+ * {@link planAiBudget} independently plans from `live` -- so a brand new
+ * org's first plan always carries both steps (same shape as any other
+ * declared limit, `ai:organisation` before `ai:budget`), and once that one
+ * apply run has pushed both, a later plan finds no further drift to
+ * replan.
  *
  * #177: blocked, not planned, while `aiReady` is false -- the platform's own
  * AI host (#172) is off or not yet applied.
@@ -1101,12 +1260,14 @@ function planAiOrganisation(org, byKey, claimed, aiReady, missingKeyRef, noKeyRe
                 key: org.id,
                 desired: {
                     provision: true,
-                    limitMicros: org.ai.limitMicros,
+                    limitMicros: effectiveAiLimitMicros(org.ai.limitMicros),
                     offers: [...AI_DEFAULT_OFFERS],
                 },
             },
             step: {
-                description: `provision ${org.slug}'s own organisation on AI and switch AI use on`,
+                description: org.ai.limitMicros === null
+                    ? `provision ${org.slug}'s own organisation on AI and switch AI use on, capped at the default of ${DEFAULT_AI_LIMIT_MICROS} micros (no limit declared)`
+                    : `provision ${org.slug}'s own organisation on AI and switch AI use on`,
                 destroys: false,
                 migrates: false,
             },
@@ -1118,8 +1279,16 @@ function planAiOrganisation(org, byKey, claimed, aiReady, missingKeyRef, noKeyRe
  * #27: the org's own spend limit on AI, a per-org singleton resource in the
  * same singleton shape as issuer/mail/chat above. Planned after {@link planAiOrganisation}
  * (#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.
+ * same `org.ai.limitMicros` (or {@link DEFAULT_AI_LIMIT_MICROS}, #484) --
+ * this planner only fires again once that row's live value has drifted from
+ * what is declared (or defaulted).
+ *
+ * #484: `desired.limitMicros` goes through {@link effectiveAiLimitMicros},
+ * never the bare `org.ai.limitMicros` -- `executor.ts`'s `aiBudget` calls
+ * AI's `updateBudget`, whose `limitMicros` is a required string with no
+ * uncapped representation, so a step that reached it with `null` always
+ * threw. The description names the default explicitly when it is the one in
+ * effect, so an operator reading the plan sees which cap applies.
  *
  * #177: silently plans nothing while there is no organisation to size a
  * budget on yet and `aiReady` is false -- {@link planAiOrganisation} already
@@ -1132,7 +1301,8 @@ function planAiBudget(org, byKey, claimed, aiReady, missingKeyRef, noKeyReader =
         claimed.add(key);
     if (!aiReady && !live)
         return { step: null, blocked: null };
-    const desired = { limitMicros: org.ai.limitMicros };
+    const isDefault = org.ai.limitMicros === null;
+    const desired = { limitMicros: effectiveAiLimitMicros(org.ai.limitMicros) };
     const liveLimitMicros = live ? (live.config.limitMicros ?? null) : null;
     if (liveLimitMicros === desired.limitMicros)
         return { step: null, blocked: null };
@@ -1147,7 +1317,9 @@ function planAiBudget(org, byKey, claimed, aiReady, missingKeyRef, noKeyReader =
         step: {
             action: { system: 'ai', kind: 'budget', key: org.id, desired },
             step: {
-                description: `set ${org.slug}'s AI budget limit to ${desired.limitMicros ?? 'uncapped'} micros`,
+                description: isDefault
+                    ? `set ${org.slug}'s AI budget limit to the default of ${desired.limitMicros} micros (no limit declared)`
+                    : `set ${org.slug}'s AI budget limit to ${desired.limitMicros} micros`,
                 destroys: false,
                 migrates: false,
             },
@@ -1657,6 +1829,32 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
             key: blockedKey(`env:${name}`),
         })))
         : [];
+    // #491: the `app` entry's own Lettermint work (`executor.ts`'s
+    // `ensureAppLettermintMail`) reads `MAIL_DOMAIN_SCOPE_KEY` directly, which
+    // can already be recorded from before this org's domain became the
+    // platform's apex -- so this is checked here too, independently of
+    // whether `coolify:mail` itself is blocked this run (`planMail` above).
+    // Reported, not fatal: the rest of this entry's own plan is unaffected.
+    // Review round 2: reads `readiness.platformApex` directly, not
+    // `readiness.mailHost?.platformApex` -- the platform's own apex is a fact
+    // independent of whether its mail server happens to be enabled or applied
+    // right now, and gating this on `mailHost` let a platform-apex org with an
+    // already-recorded domain take the unprotected path the moment platform
+    // mail went back to off.
+    if (entryKey === APP_ENTRY_KEY) {
+        const mailDomain = recordedIds[MAIL_DOMAIN_SCOPE_KEY];
+        const platformApex = readiness.platformApex;
+        const platformLettermintProjectId = readiness.platformLettermintProjectId;
+        if (mailDomain &&
+            platformApex &&
+            mailDomain.toLowerCase() === platformApex.toLowerCase() &&
+            !platformLettermintProjectId) {
+            blocked.push({
+                description: `${org.slug}'s app Lettermint mail is blocked, not planned: its mail domain is the platform's own apex, and platform.mail.lettermintProjectId is not declared yet (#491)`,
+                key: blockedKey('lettermint-project'),
+            });
+        }
+    }
     const toggled = planHostingToggle('coolify', 'app', entry !== undefined, org, byKey, claimed, () => `provision ${org.slug}'s ${label}`, () => `park ${org.slug}'s ${label} (stops serving; app data is retained, not deleted -- #7 corrections 1)`, stepKey);
     if (toggled)
         return { step: toggled, blocked };
@@ -1859,6 +2057,21 @@ function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer, re
             if (signsIn)
                 app.step.action.desired = { ...app.step.action.desired, authIssuer };
         }
+        // #491: only the `app` entry's own step runs `ensureAppLettermintMail`
+        // (`executor.ts`'s own `entry.key === APP_ENTRY_KEY` gate). Unlike
+        // `secretSources`/`authIssuer` above, these two are set unconditionally
+        // -- `null` when no platform is declared, never omitted -- because
+        // `executor.ts` treats the key being *absent* as a stale plan predating
+        // this field and refuses to run (review round 2, finding 3): an omitted
+        // key here would read identically to a stale plan and silently fall
+        // back to the unprotected pre-#491 path instead.
+        if (key === APP_ENTRY_KEY && app.step && app.step.action.desired.enabled !== false) {
+            app.step.action.desired = {
+                ...app.step.action.desired,
+                platformApex: readiness.platformApex,
+                platformLettermintProjectId: readiness.platformLettermintProjectId,
+            };
+        }
         if (app.step)
             steps.push(app.step);
         blocked.push(...app.blocked);

package/dist/plan/edge-worker.d.ts

@@ -0,0 +1,114 @@
+import type { DeclaredOrg, EdgeConfig, HostingEntry } from '../org.js';
+import type { DraftStep } from './diff.js';
+/**
+ * F8 (#318): one plain Cloudflare Worker per hosting entry that declares
+ * `edge`, deployed from a built artifact that entry's own repo publishes
+ * (estate DECISIONS.md, 2026-10-04: foundry fetches and verifies it, never
+ * checks it out or bundles it). Unlike `planEntryAiKeys`/`planFilesKeys`,
+ * there is no renewal window -- a Worker script has no expiry -- so a step
+ * is planned again only while the entry's own declared config (`route`,
+ * `bindings` or, crucially, `artifactSha256`) differs from what was last
+ * applied (recorded as that config's JSON, `edgeAppliedScopeKey`):
+ * `artifactSha256` is itself the declared signal that the built bytes
+ * changed, so a rebuild under an unchanged URL still redeploys as soon as
+ * the entry declares the new digest. "Blocked, not failing" (CLAUDE.md): a
+ * host whose executor carries no `WorkersPort` reports every entry's step
+ * (apply or retire) as blocked, not planned to a step that would throw.
+ */
+export declare const entryEdgeAppliedScopeKey: (entryKey: string) => string;
+export declare const entryEdgeRouteIdScopeKey: (entryKey: string) => string;
+/** The route pattern the recorded route id above was created for -- read to find and delete the *old* route when the declared route pattern changes. */
+export declare const entryEdgeRoutePatternScopeKey: (entryKey: string) => string;
+/**
+ * The script name retired, once a retire step completes. `runSteps` only
+ * ever writes a step's main recorded id from a *truthy* `resourceId`
+ * (`plan-apply.ts`), and retire returns none -- so the main
+ * `cloudflare:worker:<key>` id is never cleared by returning from the step,
+ * and without this marker the "gone" scan below would plan the same retire
+ * forever. Compared against that still-live id, the same convergence
+ * `entryAiRetiredScopeKey`/`entryFilesRetiredScopeKey`/
+ * `entryNamesRetiredScopeKey` already give their own entry keys.
+ */
+export declare const entryEdgeRetiredScopeKey: (entryKey: string) => string;
+/** The script name being uploaded, recorded (and persisted) *before* the upload call -- so a crash mid-upload or a failed route create still leaves a trail to the script rather than orphaning it, and a retry reads the script as foundry's own instead of tripping the `scriptExists` overwrite guard. Cleared once the step records success. */
+export declare const entryEdgeUploadedScopeKey: (entryKey: string) => string;
+/** The zone the recorded route id lives in, as {@link EdgeRouteZone} JSON -- so retire and destroy delete it on *that* zone even after `org.domain` changes or goes null. */
+export declare const entryEdgeRouteZoneScopeKey: (entryKey: string) => string;
+/** A route about to be created, as {@link EdgeRoutePending} JSON, recorded and persisted before `createRoute` -- so a crash or failed persist right after Cloudflare creates it still leaves retire and destroy something to find it by (`findRoute`). Cleared once the route id is recorded. */
+export declare const entryEdgeRoutePendingScopeKey: (entryKey: string) => string;
+export interface EdgeRouteZone {
+    id: string;
+    apex: string;
+}
+export interface EdgeRoutePending extends EdgeRouteZone {
+    pattern: string;
+    script: string;
+}
+/** The per-entry scope keys that mark something deployed or half-deployed, or that a retire already handled it -- cleared together once org destroy has torn the Worker down (#318 re-review: the retired marker was left out, so it stayed recorded as a stale leftover after the org itself was gone). */
+export declare const edgeWorkerTraceScopeKeys: (entryKey: string) => string[];
+/**
+ * Every entry key of `orgId` with something foundry deployed still live,
+ * mapped to the script name recorded for it (`''` if only a route trace is
+ * left). Read by the planner's gone-scan and by org destroy alike, so the two
+ * agree on what is live: the main `cloudflare:worker:<org>:<entry>` id
+ * (unless the retired marker matches it), or any partial-deploy trace -- the
+ * uploaded name, a recorded route id, or a pending route -- regardless of
+ * the retired marker, since an apply clears that marker before it leaves any
+ * of these (#318 re-review).
+ */
+export declare function liveEdgeWorkers(orgId: string, recordedIds: Readonly<Record<string, string>>): Map<string, string>;
+/** The first 8 hex characters of org.id's own sha256 -- see {@link edgeWorkerName}'s doc comment. */
+export declare const EDGE_WORKER_ORG_HASH_LENGTH = 8;
+/** Cloudflare's own limit on a Worker script name. */
+export declare const EDGE_WORKER_NAME_MAX_LENGTH = 63;
+/**
+ * `${8-hex-char hash of org.id}-${entry.key}-edge`, not `${org.slug}-...`
+ * (#318 re-review): a slug and an entry key both allow hyphens, so org
+ * `a-b` entry `c` and org `a` entry `b-c` produced the identical name
+ * `a-b-c-edge` on the one shared Cloudflare account -- `scriptExists` only
+ * caught the second of the two to apply, and two concurrent applies could
+ * both pass it. `org.id` is a UUID with no ambiguity of its own, but using
+ * it in full would make the fixed part of the name longer than most of the
+ * 63-character budget this port's `EDGE_WORKER_NAME_MAX_LENGTH` gives it,
+ * so only a short hash of it is used -- `validateEntryEdge` (`org.ts`)
+ * checks the resulting name never exceeds that limit.
+ */
+export declare const edgeWorkerName: (org: DeclaredOrg, entry: HostingEntry) => string;
+/**
+ * Foundry's own fixed compatibility date for every Worker it deploys -- not
+ * a per-entry declared value, so it is not part of {@link EdgeWorkerWant}
+ * and never triggers a re-plan on its own; bumping it is a foundry release,
+ * like {@link RATE_LIMIT_FREE_PLAN_PERIOD_SECONDS} is a fixed Cloudflare
+ * Free plan value rather than something an org declares.
+ */
+export declare const EDGE_WORKER_COMPATIBILITY_DATE = "2026-09-12";
+export type EdgeWorkerMode = 'apply' | 'retire';
+export interface EdgeWorkerWant {
+    name: string;
+    artifactUrl: string;
+    artifactSha256: string;
+    route: string;
+    bindings: EdgeConfig['bindings'];
+}
+export declare function wantedEdgeWorker(org: DeclaredOrg, entry: HostingEntry): EdgeWorkerWant;
+type Blocked = Array<{
+    description: string;
+    key: string;
+}>;
+/**
+ * One step per entry whose `edge` config is new or changed, plus one retire
+ * step per entry whose Worker is recorded but no longer declared -- either
+ * because the entry dropped `edge` or because the entry itself is gone, the
+ * same "gone" scan `planEntryAiKeys`/`planFilesKeys`/`planEntryNamesKeys`
+ * run over their own recorded keys, so removing a whole entry still cleans
+ * up its Worker. `workersAvailable` is the host's own
+ * `FoundryPlanApplyOptions.edgeWorkers` (mirrors `jobsAvailable`): without
+ * it, every entry's step -- apply or retire -- is reported blocked rather
+ * than planned to fail at apply. The caller (`diff.ts`) gates the *apply*
+ * steps further, on an active zone, the same way it gates `planRateLimit`.
+ */
+export declare function planEdgeWorkers(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, workersAvailable: boolean): {
+    steps: DraftStep[];
+    blocked: Blocked;
+};
+export {};