@wtfalch/foundry 0.15.0 → 0.16.1

package/dist/plan/diff.js

@@ -1,12 +1,15 @@
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
-import { APP_ENTRY_KEY } from '../org.js';
-import { CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraHostMissing, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, desiredAgoraEnv, } from './agora.js';
+import { APP_ENTRY_KEY, ownerMailboxRecorded, ownerMailboxes } from '../org.js';
+import { CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraHostMissing, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
+import { planEntryAiKeys } from './entry-ai-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 { DEFAULT_ORG_PLATFORM_READINESS } from './platform-org.js';
+import { appLabelsAppliedScopeKey, entryLabelHash, entryLabelSpec } from './proxy-labels.js';
 /** The `Plan` (#19's public contract) a `PlanDetail` carries. */
 export function toPlan(detail) {
     return {
@@ -40,7 +43,7 @@ function resourceKey(system, kind, key) {
  * `planAiOrganisation`, each planned before its own system's limit step
  * ({@link planStorage}, {@link planAiBudget}) so an org has somewhere for a
  * limit to land, and AI use is switched on, before either limit is ever set.
- * `planOwner` below adds one more singleton, in a different shape from the
+ * `planOwners` below adds one more singleton, in a different shape from the
  * rest: the org's owner, invited by ZITADEL email, idempotent on the
  * *recorded* resource id (`recordedIds`, sourced from
  * `AppliedState.serviceIds`) rather than a live resource, since a human user
@@ -57,9 +60,9 @@ function resourceKey(system, kind, key) {
  * 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
+ * resource id like {@link planOwners} rather than a live resource, since
  * nothing in `live` can report a scheduler registration (no reader exists for
- * it). #267 adds one more, right after {@link planOwner} and before every
+ * it). #267 adds one more, right after {@link planOwners} and before every
  * app-creating step below: {@link planLoginHost}, the org's own company
  * login host -- also idempotent on the *recorded* resource id, since
  * `live` has no notion of a ZITADEL trusted domain or a login binding
@@ -78,9 +81,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     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);
+    plannedSteps.push(...planOwners(org, recordedIds, platformReadiness.authReady));
     // #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.
@@ -107,16 +108,16 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const mailCopy = planMailCopy(org, byKey, recordedIds);
     if (mailCopy)
         plannedSteps.push(mailCopy);
-    const chat = planChat(org, byKey, claimed);
-    if (chat)
-        plannedSteps.push(chat);
+    const chat = planChat(org, byKey, claimed, recordedIds, agoraHost, issuer.step !== null);
+    if (chat.step)
+        plannedSteps.push(chat.step);
     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`.
+    // ordering `planOwners` relies on for `zitadel:issuer`.
     const callsService = planCallsService(org, byKey, claimed, platformReadiness.callsReady, recordedIds, calls.blocked !== null, 'error' in agoraHost ? null : callsTokenHostFrom(agoraHost));
     if (callsService.step)
         plannedSteps.push(callsService.step);
@@ -191,6 +192,12 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // After the apps: the broker entry's key is minted into each app's env.
     const brokerEntries = planBrokerEntries(org, recordedIds, plannedSteps, options.broker ?? false);
     plannedSteps.push(...brokerEntries.steps);
+    // F6a: after the apps and the org's own ai key, which it mints below.
+    const entryAiKeys = planEntryAiKeys(org, recordedIds, plannedSteps, platformReadiness, (options.now ?? Date.now)());
+    plannedSteps.push(...entryAiKeys.steps);
+    // 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);
     const tunnel = planTunnel(org, byKey, claimed, recordedIds);
     // #238: a tunnel that is being provisioned waits for an active zone; parking
     // one never does.
@@ -250,6 +257,8 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // orphan a second live key.
     if (aiKey.blocked)
         unmanaged.push({ description: aiKey.blocked, key: 'ai:key' });
+    unmanaged.push(...filesKeys.blocked);
+    unmanaged.push(...entryAiKeys.blocked);
     // Same for a jobs registration that cannot run (no scheduler wired) or must
     // not run again (minted, never delivered).
     if (jobsRegistration.blocked) {
@@ -275,6 +284,8 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     }
     if (calls.blocked)
         unmanaged.push({ description: calls.blocked, key: 'coolify:calls' });
+    if (chat.blocked)
+        unmanaged.push({ description: chat.blocked, key: 'coolify:chat' });
     if (callsService.blocked) {
         unmanaged.push({ description: callsService.blocked, key: 'coolify:calls-service' });
     }
@@ -377,11 +388,11 @@ function planIssuer(org, byKey, claimed, authReady) {
     };
 }
 /**
- * The org's owner, invited by ZITADEL email once the org's ZITADEL org
+ * The org's owners, one step each, each invited by ZITADEL email once the org's ZITADEL org
  * exists (goal line: "the org's owner is invited by ZITADEL email and sets a
  * passkey — no password passes through foundry"). A per-org singleton like
  * every other planner here, but idempotent on a different signal: the
- * *recorded* resource id (`recordedIds['zitadel:owner:<orgId>']`, written by
+ * *recorded* resource id (`recordedIds['zitadel:owner:<orgId>:<email>']`, email lowercased, written by
  * `plan-apply.ts`'s `runSteps` from this step's own `resourceId` — the
  * invited user id) rather than a live resource. `ZitadelReader.listResources`
  * (`@wtfalch/providers`' `ZitadelClient.listResources`) reads projects and
@@ -404,45 +415,51 @@ function planIssuer(org, byKey, claimed, authReady) {
  * nothing here puts it anywhere beyond what audit already records for the
  * org.
  */
-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.
+function planOwners(org, recordedIds, authReady) {
     // #177: nothing to invite into yet -- `planIssuer` already reports the
-    // platform's sign-in as blocked, so this step stays silent rather than
+    // platform's sign-in as blocked, so these steps stay silent rather than
     // repeating it.
     if (!authReady)
-        return null;
-    return {
-        action: {
-            system: 'zitadel',
-            kind: 'owner',
-            key: org.id,
-            desired: {
-                email: org.owner.email,
-                givenName: org.owner.givenName,
-                familyName: org.owner.familyName,
+        return [];
+    const steps = [];
+    org.owners.forEach((owner, index) => {
+        // Every owner is keyed by its lowercased email (as `validateOwners` compares
+        // it), so reordering the list never moves a key onto another person.
+        const key = `${org.id}:${owner.email.toLowerCase()}`;
+        if (recordedIds[resourceKey('zitadel', 'owner', key)])
+            return; // already invited.
+        steps.push({
+            action: {
+                system: 'zitadel',
+                kind: 'owner',
+                key,
+                desired: {
+                    email: owner.email,
+                    givenName: owner.givenName,
+                    familyName: owner.familyName,
+                },
             },
-        },
-        step: {
-            description: `invite ${org.slug}'s owner by email`,
-            destroys: false,
-            migrates: false,
-        },
-    };
+            step: {
+                description: index === 0
+                    ? `invite ${org.slug}'s owner by email`
+                    : `invite ${org.slug}'s owner ${index + 1} by email`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    });
+    return steps;
 }
 /**
  * #267: the org's own company login host (`login-host.ts`'s
  * `loginHostnameFor`) -- `auth.<domain>` once the org has one,
  * `<slug>-auth.oikos.host` for tier 1. Idempotent on the *recorded*
- * resource id, the same shape `planOwner` above uses and for the same
+ * resource id, the same shape `planOwners` above uses and for the same
  * reason: `ZitadelReader.listResources` has no notion of a trusted domain
  * or a login binding, so there is nothing in `live` this step could ever
  * claim or compare against.
  *
- * Unlike `planOwner`, a re-run is not simply "already done or not": the
+ * Unlike `planOwners`, a re-run is not simply "already done or not": the
  * recorded value is compared against {@link loginHostnameFor}'s own value
  * for *this* apply, so an org moving from tier 1 onto its own domain (or
  * losing one) replans this step rather than staying silent forever once
@@ -455,8 +472,8 @@ function planOwner(org, recordedIds, authReady) {
  * there is no "undelivered"
  * guard to check the way `planJobsRegistration`'s own does.
  *
- * Ordered right after `planOwner` (not after mail, chat, or any hosting
- * step), for the same reason `planOwner`'s own doc comment gives: on a
+ * Ordered right after `planOwners` (not after mail, chat, or any hosting
+ * step), for the same reason `planOwners`'s own doc comment gives: on a
  * first-ever apply the ZITADEL org this step's executor needs
  * (`context.recordedIds().zitadel_org`) has already been recorded by the
  * issuer step two steps before it in the same run, and this step itself
@@ -482,7 +499,7 @@ function planLoginHost(org, recordedIds, authReady, issuerPlanned, bindingsWired
     }
     // #177: nothing to add a trusted domain to yet -- `planIssuer` already
     // reports the platform's sign-in as blocked, so this step stays silent
-    // rather than repeating it, the same rule `planOwner` follows.
+    // rather than repeating it, the same rule `planOwners` follows.
     if (!authReady)
         return none;
     // Isolation between orgs rests on zitadel-login's binding, and repointing
@@ -519,13 +536,6 @@ function planLoginHost(org, recordedIds, authReady, issuerPlanned, bindingsWired
         blocked: null,
     };
 }
-/**
- * #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';
 /** #230: restated from `executor.ts`'s `MAIL_ROLE_MAILBOXES_SCOPE_KEY`, same rule: comma-joined local parts already created. */
 const MAIL_ROLE_MAILBOXES_SCOPE_KEY = 'mail_role_mailboxes';
 /** Restated from `executor.ts`, the same rule: the app id of the org tunnel's cloudflared connector. */
@@ -583,13 +593,17 @@ function planMail(org, byKey, claimed, recordedIds, mailHost) {
     // (`mailboxBlocked`), the same "blocked, not planned" pattern a blocked
     // Agora already follows (PR 180) -- the rest of this step, and every
     // other step in the org's plan, is unaffected.
-    const mailboxAlreadyGiven = Boolean(recordedIds[MAIL_OWNER_MAILBOX_SCOPE_KEY]);
-    const hasOwner = Boolean(org.owner);
-    const ownerMailboxAddress = org.mail.ownerMailboxAddress ?? null;
-    const mailboxBlocked = hasOwner && !mailboxAlreadyGiven && !ownerMailboxAddress
+    // One mailbox per owner (`ownerMailboxes`): the first owner's address falls
+    // back to `mail.ownerMailboxAddress`; another owner with no `mailboxAddress`
+    // simply gets none. Only the first owner's missing address is reported
+    // blocked, as before.
+    const ownerBoxes = ownerMailboxes(org);
+    const mailboxesOwed = ownerBoxes.filter((b) => b.address !== null && !ownerMailboxRecorded(b, recordedIds)).length;
+    const firstBox = ownerBoxes[0];
+    const mailboxBlocked = firstBox && !ownerMailboxRecorded(firstBox, recordedIds) && firstBox.address === null
         ? `${org.slug}'s owner mailbox is blocked, not planned: mail.ownerMailboxAddress is not declared`
         : null;
-    const mailboxOwed = hasOwner && !mailboxAlreadyGiven && ownerMailboxAddress !== null;
+    const mailboxOwed = mailboxesOwed > 0;
     // #230: declared role mailboxes not yet recorded as created. Names only
     // ever count here, never appear in a description, same as the owner's address.
     // Recorded per address, so a changed mail domain owes its own set. A hosted
@@ -597,7 +611,9 @@ function planMail(org, byKey, claimed, recordedIds, mailHost) {
     const createdRoles = new Set((recordedIds[MAIL_ROLE_MAILBOXES_SCOPE_KEY] ?? '').split(','));
     const roleDomain = (org.mail.usesDomain && org.domain) || recordedIds[MAIL_DOMAIN_SCOPE_KEY];
     const rolesOwed = (org.mail.roleMailboxes ?? []).filter((r) => !roleDomain || !createdRoles.has(`${r}@${roleDomain}`.toLowerCase())).length;
-    const ownerNote = mailboxOwed ? `give ${org.slug}'s owner a mailbox` : '';
+    const ownerNote = mailboxOwed
+        ? `give ${org.slug}'s ${mailboxesOwed > 1 ? `${mailboxesOwed} owners a mailbox each` : 'owner a mailbox'}`
+        : '';
     const roleNote = rolesOwed > 0 ? `create ${rolesOwed} role mailbox(es) for ${org.slug}` : '';
     const mailboxWork = [ownerNote, roleNote].filter(Boolean).join(' and ');
     const mailboxNote = mailboxWork ? ` and ${mailboxWork}` : '';
@@ -714,45 +730,68 @@ function planMailCopy(org, byKey, recordedIds) {
         },
     };
 }
-function planChat(org, byKey, claimed) {
-    // Chat off (not in v1): plan nothing, and leave any live chat unclaimed so
-    // it is reported in `unmanaged` and never adopted or destroyed.
+function planChat(org, byKey, claimed, recordedIds, reading, issuerPlanned) {
+    const none = { step: null, blocked: null };
+    // Chat off: plan nothing, and leave any live chat unclaimed so it is
+    // reported in `unmanaged` and never adopted or destroyed.
     if (!org.chat.enabled)
-        return null;
+        return none;
     const key = resourceKey('coolify', 'chat', org.id);
     const live = byKey.get(key);
     if (live)
         claimed.add(key);
     const desiredUsesDomain = org.chat.usesDomain;
     if (!live) {
+        // Chat verifies ZITADEL tokens, so it needs the issuer URL and the org's
+        // ZITADEL org (rule 2: blocked, not a step that throws). The ZITADEL org
+        // may be created by the issuer step earlier in this very plan.
+        const issuer = 'error' in reading ? null : reading.issuer;
+        if (!issuer) {
+            return {
+                step: null,
+                blocked: `${org.slug}'s chat is blocked, not planned: the host supplies no issuer`,
+            };
+        }
+        if (!recordedIds[ZITADEL_ORG_SCOPE_KEY] && !issuerPlanned) {
+            return {
+                step: null,
+                blocked: `${org.slug}'s chat is blocked, not planned: the org has no ZITADEL org yet`,
+            };
+        }
         // Chat is provisioned at level 1 on a wtfalch `server_name` regardless
         // of `usesDomain` (#7 "Chat").
         return {
-            action: {
-                system: 'coolify',
-                kind: 'chat',
-                key: org.id,
-                desired: { usesDomain: desiredUsesDomain },
-            },
             step: {
-                description: `provision chat for ${org.slug} on a wtfalch server_name`,
-                destroys: false,
-                migrates: false,
+                action: {
+                    system: 'coolify',
+                    kind: 'chat',
+                    key: org.id,
+                    desired: { usesDomain: desiredUsesDomain, issuer },
+                },
+                step: {
+                    description: `provision chat for ${org.slug} on a wtfalch server_name`,
+                    destroys: false,
+                    migrates: false,
+                },
             },
+            blocked: null,
         };
     }
     const liveUsesDomain = Boolean(live.config.usesDomain);
     if (liveUsesDomain === desiredUsesDomain)
-        return null;
+        return none;
     const domain = org.domain ?? 'its domain';
     if (!liveUsesDomain && desiredUsesDomain) {
         return {
-            action: { system: 'coolify', kind: 'chat', key: org.id, desired: { usesDomain: true } },
             step: {
-                description: `re-key ${org.slug}'s chat onto ${domain}, copying rooms and messages so history reads continuous`,
-                destroys: true,
-                migrates: true,
+                action: { system: 'coolify', kind: 'chat', key: org.id, desired: { usesDomain: true } },
+                step: {
+                    description: `re-key ${org.slug}'s chat onto ${domain}, copying rooms and messages so history reads continuous`,
+                    destroys: true,
+                    migrates: true,
+                },
             },
+            blocked: null,
         };
     }
     // The reverse (usesDomain true -> false): legal in the schema, but the
@@ -760,12 +799,15 @@ function planChat(org, byKey, claimed) {
     // visibility; whoever wires a real StepExecutor (#20) must fail loudly on
     // it rather than run it, exactly as #7 amendment 3 requires.
     return {
-        action: { system: 'coolify', kind: 'chat', key: org.id, desired: { usesDomain: false } },
         step: {
-            description: `reverse ${org.slug}'s chat re-key back onto its original server_name — not yet built (#7 amendment 3)`,
-            destroys: true,
-            migrates: true,
+            action: { system: 'coolify', kind: 'chat', key: org.id, desired: { usesDomain: false } },
+            step: {
+                description: `reverse ${org.slug}'s chat re-key back onto its original server_name — not yet built (#7 amendment 3)`,
+                destroys: true,
+                migrates: true,
+            },
         },
+        blocked: null,
     };
 }
 /**
@@ -1114,7 +1156,7 @@ function planAiBudget(org, byKey, claimed, aiReady, missingKeyRef, noKeyReader =
  * #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`
+ * {@link planOwners} 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
@@ -1336,7 +1378,7 @@ function planAgora(org, byKey, claimed, recordedIds, reading) {
     if (live)
         claimed.add(key);
     const error = 'error' in reading ? reading.error : null;
-    const host = 'error' in reading ? NO_AGORA_HOST_VALUES : reading;
+    const host = withRecordedMessagingProject('error' in reading ? NO_AGORA_HOST_VALUES : reading, recordedIds);
     const missing = agoraHostMissing(host);
     if (missing.length > 0) {
         // A fixed text, never the port's own message: this line is part of the
@@ -1593,6 +1635,24 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
             blocked,
         };
     }
+    // A `*` entry's proxy labels reach an app that is already live: the label
+    // set is patched and the app redeployed once its hash differs from the one
+    // `coolifyApp` recorded.
+    const appliedLabels = recordedIds[appLabelsAppliedScopeKey(entryKey)];
+    const labelSpec = entryLabelSpec(org, entry, appliedLabels !== undefined);
+    if (labelSpec && entryLabelHash(labelSpec) !== appliedLabels) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `apply ${org.slug}'s ${label} proxy labels and redeploy the app`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked,
+        };
+    }
     // A changed `folder`, `port` or `autoDeploy` reaches an app that is already live.
     const want = appSettingsOf(entry);
     const have = appliedAppSettings(recordedIds, entryKey);
@@ -1663,7 +1723,7 @@ function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer) {
  * #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
+ * resource id, the same shape {@link planOwners} 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
@@ -2038,7 +2098,7 @@ function planBrokerEntries(org, recordedIds, plannedSteps, brokerWired) {
  * Plan gap A9: an org's customers sign in through a second ZITADEL org with
  * self-registration on, granted the org's app project. Planned once an entry
  * signs in its customers (`uses.auth.users: 'customers'`).
- * Idempotent on the recorded customers org id, like `planOwner`. Once
+ * Idempotent on the recorded customers org id, like `planOwners`. Once
  * recorded, the live project grant to that org is claimed so it is not
  * listed as unmanaged.
  */
@@ -2068,7 +2128,7 @@ function planCustomers(org, live, claimed, recordedIds) {
 /**
  * #84: a Cloudflare Access gate on the org's app hostname, letting only
  * each entry's `accessEmails` through. Idempotent on the recorded Access app id,
- * like `planOwner`: Cloudflare's live listing has no Access apps. A later
+ * like `planOwners`: Cloudflare's live listing has no Access apps. A later
  * change to the email list is not reconciled yet.
  */
 function planAccess(org, recordedIds) {

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

@@ -0,0 +1,58 @@
+import { type DeclaredOrg, type HostingEntry } from '../org.js';
+import type { PlannedStep } from './diff.js';
+import type { OrgPlatformReadiness } from './platform-org.js';
+/**
+ * F6a: one ai key per entry with `uses.ai`, minted below the org's own ai key
+ * (`ai:key:<orgId>`), delivered into that entry's env and nowhere else.
+ */
+/** How long an entry's key lives. ai refuses more than 365 and anything past its minter's own expiry. */
+export declare const AI_ENTRY_KEY_DAYS = 365;
+/** A key with fewer days left than this is renewed. */
+export declare const AI_ENTRY_RENEW_WINDOW_DAYS = 30;
+/** Flat scope ids (no `:`) per entry. Entry keys hold neither `:` nor `.`. */
+export declare const entryAiUndeliveredScopeKey: (entryKey: string) => string;
+/** The ISO time the entry's live key expires. */
+export declare const entryAiExpiresScopeKey: (entryKey: string) => string;
+/** What the last apply wrote: permissions, offerings, webhook address, ai address. Never a secret. */
+export declare const entryAiAppliedScopeKey: (entryKey: string) => string;
+/** Set before the webhook is registered and cleared once its secret is in the env. */
+export declare const entryAiWebhookPendingScopeKey: (entryKey: string) => string;
+/** The id of the key whose env write finished, before the app restart that completes the step. */
+export declare const entryAiWrittenScopeKey: (entryKey: string) => string;
+/** The expiry ai returned for the key above. */
+export declare const entryAiPendingExpiresScopeKey: (entryKey: string) => string;
+/** `{ expiresAt, minter }` of a key ai clamped under the renewal window; renewing it again under the same minter only repeats. */
+export declare const entryAiClampedScopeKey: (entryKey: string) => string;
+/** The id of a key that was live when its entry stopped declaring `uses.ai`, once handled. */
+export declare const entryAiRetiredScopeKey: (entryKey: string) => string;
+/**
+ * REVOKE SEAM (ai#157, A1b, not built): the ids of keys left live because
+ * `AiOrganisationPort.revokeKey` is absent or failed, as a JSON array. They
+ * expire on their own; the plan lists each.
+ */
+export declare const entryAiUnrevokedScopeKey: (entryKey: string) => string;
+export declare const ENTRY_AI_UNREVOKED_PREFIX = "ai_key_unrevoked_";
+export declare function parseIdList(raw: string | undefined): string[];
+export declare const entryAiKeyName: (org: DeclaredOrg, entry: HostingEntry) => string;
+export interface EntryAiWant {
+    permissions: string[];
+    offerings: string[];
+    /** `https://<first hostname><webhookPath>`, or null without `webhookPath`. */
+    webhook: string | null;
+    aiUrl: string;
+}
+export declare function wantedEntryAi(org: DeclaredOrg, entry: HostingEntry, aiUrl: string): EntryAiWant;
+export type EntryAiMode = 'mint' | 'renew' | 'settings' | 'finish' | 'retire';
+/**
+ * One step per entry whose key is missing, near expiry or whose declared
+ * settings changed. Blocked, not planned (rule 2), while the org's key, the
+ * entry's app or the ai address is not recorded, or after a mint whose
+ * delivery failed: a second mint would leave two live keys.
+ */
+export declare function planEntryAiKeys(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly PlannedStep[], readiness: OrgPlatformReadiness, now: number): {
+    steps: PlannedStep[];
+    blocked: Array<{
+        description: string;
+        key: string;
+    }>;
+};