@wtfalch/foundry 0.17.0 → 0.18.0

package/dist/plan/diff.js

@@ -4,15 +4,17 @@ import { AGORA_ACTIVATED_ENV_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INT
 import { BOULE_BROKER_ENTRY_KEY, bouleEnvDrift, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
 import { planEntryAiKeys } from './entry-ai-key.js';
+import { planEdgeReservedLabels, planEntryEdgeKeys } from './entry-edge-key.js';
 import { planFilesKeys } from './entry-files-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';
 import { withStepSystem } from './step-system.js';
+import { planWorkers } from './worker.js';
 /** The `Plan` (#19's public contract) a `PlanDetail` carries. */
 export function toPlan(detail) {
     return {
@@ -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 edge.
+    const edgeReservedLabels = planEdgeReservedLabels(org, recordedIds, platformReadiness, options.platformHostnames ?? []);
+    if (edgeReservedLabels.step)
+        plannedSteps.push(edgeReservedLabels.step);
+    // After the apps -- a edge key needs the entry's app recorded, the same
+    // dependency `planEntryAiKeys`/`planFilesKeys` have.
+    const entryEdgeKeys = planEntryEdgeKeys(org, recordedIds, plannedSteps, platformReadiness, (options.now ?? Date.now)());
+    plannedSteps.push(...entryEdgeKeys.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 worker 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 = planWorkers(org, recordedIds, options.edgeWorkers ?? false, options.platformHostnames ?? []);
+    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)} 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(...entryEdgeKeys.blocked);
+    unmanaged.push(...edgeReservedLabels.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);
@@ -2001,10 +2214,10 @@ function planTunnel(org, byKey, claimed, recordedIds) {
     // differ from the names now declared. An org that never recorded a list
     // has nothing to compare, so only the domain check above applies to it.
     const published = recordedIds[CLOUDFLARE_TUNNEL_DNS_HOSTNAMES_SCOPE_KEY];
-    const namesChanged = published !== undefined &&
+    const edgeChanged = published !== undefined &&
         org.domain !== null &&
         sortedNames(published.split(',')) !== sortedNames(tunnelDnsHostnames(org, org.domain));
-    const dnsStale = recordedIds[CLOUDFLARE_TUNNEL_DNS_DOMAIN_SCOPE_KEY] !== org.domain || namesChanged;
+    const dnsStale = recordedIds[CLOUDFLARE_TUNNEL_DNS_DOMAIN_SCOPE_KEY] !== org.domain || edgeChanged;
     if (!connectorMissing && !dnsStale)
         return null;
     return {

package/dist/plan/entry-edge-key.d.ts

@@ -0,0 +1,79 @@
+import type { DeclaredOrg, HostingEntry } from '../org.js';
+import type { DraftStep } from './diff.js';
+import type { OrgPlatformReadiness } from './platform-org.js';
+/**
+ * F7 (#317): one edge key per entry with `uses.edge`, minted directly
+ * below the org with the edge service (`EdgePort.mintKey({
+ * organisationId, ... })` -- no org-level root key the way files/ai have
+ * one, since the edge service takes the org id itself). `EDGE_URL` and
+ * `EDGE_API_KEY` go to the entry's env and nowhere else. A edge key has no
+ * declared renewal window in the issue, so unlike `planEntryAiKeys`/
+ * `planFilesKeys` this mints once and never renews.
+ *
+ * `EDGE_*` is written in this step, after the app's own `coolify:app`
+ * create (which never knows the key yet), so the app's first boot has
+ * neither and its first deploy restarts once this step's env write lands --
+ * the same one-extra-restart shape `planEntryAiKeys`'s `AI_*`/
+ * `planFilesKeys`'s `FILES_*` already have, not a names-specific gap.
+ *
+ * A domain change after mint is not detected (#317 re-review): the key is
+ * bound to the domain passed at mint time, but nothing here records that
+ * domain to compare against a later `org.domain`, so an org that changes
+ * domains keeps a edge key still bound to the old one. Not built --
+ * resolving it needs a manual revoke-and-re-mint (drop `uses.edge`, apply,
+ * re-add it) until this is.
+ */
+export declare const entryEdgeUndeliveredScopeKey: (entryKey: string) => string;
+/** The id of a key that was live when its entry stopped declaring `uses.edge`, once handled. */
+export declare const entryEdgeRetiredScopeKey: (entryKey: string) => string;
+export declare const ENTRY_EDGE_KEY_DELIVERY_ATTEMPTS = 3;
+/** How long an entry's edge key lives. The issue names no renewal window, so this mints once and never renews. */
+export declare const EDGE_ENTRY_KEY_DAYS = 365;
+/** The ISO time a delivered key's mint succeeded -- the only trace of its age, since there is no renewal to track against. */
+export declare const entryEdgeMintedAtScopeKey: (entryKey: string) => string;
+/** A key with fewer days left than this is surfaced as a blocked warning row (#317 review): still live, but nothing here renews it. */
+export declare const EDGE_ENTRY_KEY_WARN_WINDOW_DAYS = 30;
+/** The reserved labels last sent to the edge service, as that sorted list's own JSON. */
+export declare const EDGE_RESERVED_LABELS_APPLIED_SCOPE_KEY = "edge_reserved_labels_applied";
+export declare const entryEdgeKeyName: (org: DeclaredOrg, entry: HostingEntry) => string;
+/**
+ * Every label under `org.domain` that foundry provisions or the platform
+ * uses, so edge never lets a company claim one: the hostnames foundry routes
+ * (`tunnelIngressHostnames`: entries, site, cms, calls, Agora, Boule, share),
+ * the names it locks (`lockedHostnames`: also the sign-in host and the
+ * platform's service hostnames), each entry's own labels, the mail labels
+ * and `www`. The entry's `*` is the space users claim in, so it reserves
+ * nothing, and neither does the bare domain.
+ *
+ * An org without a domain has no hostnames edge sees (`uses.edge` needs a
+ * domain), so it reserves `www` only.
+ */
+export declare function edgeReservedLabels(org: DeclaredOrg, platformHostnames?: readonly string[]): string[];
+type Blocked = Array<{
+    description: string;
+    key: string;
+}>;
+/**
+ * One step per entry whose edge key is missing, plus one retire step per
+ * entry whose `uses.edge` was removed but still has a recorded key.
+ * Blocked, not planned (rule 2), while the platform has no edge service
+ * wired, the entry's app is not recorded, or a previous mint's delivery
+ * failed.
+ */
+export declare function planEntryEdgeKeys(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], readiness: OrgPlatformReadiness, now?: number): {
+    steps: DraftStep[];
+    blocked: Blocked;
+};
+/**
+ * The reserved-labels step: resent whenever the org's own label set
+ * (`edgeReservedLabels`) differs from what was last sent. While the org
+ * uses edge at all (at least one entry with `uses.edge`) that set is
+ * `edgeReservedLabels(org)`; once the last entry drops `uses.edge`, this
+ * clears whatever was last sent (an empty list) rather than leaving it
+ * stuck in names forever -- a one-time step, same as any other change.
+ */
+export declare function planEdgeReservedLabels(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, readiness: OrgPlatformReadiness, platformHostnames?: readonly string[]): {
+    step: DraftStep | null;
+    blocked: Blocked;
+};
+export {};