@wtfalch/foundry 0.76.1 → 0.77.0

package/dist/plan/diff.js

@@ -1,8 +1,9 @@
 import { VERSIONS } from '../bootstrap/versions.js';
 import { NATIVE_BUILD_KEY_ENV } from '../native-build.js';
-import { APP_ENTRY_KEY, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, appsOn, companyGithubFor, heldEnvRef, kosmosOn, mainEntry, ownerMailboxRecorded, ownerMailboxes, ownerNameProblem, ownsServices, } from '../org.js';
+import { APP_ENTRY_KEY, MAIL_APP_KEY_ENV, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, appsOn, companyGithubFor, heldEnvRef, kosmosOn, mainEntry, ownerMailboxRecorded, ownerMailboxes, ownerNameProblem, ownsServices, sendsMail, signsInBoth, signsInCustomers, } from '../org.js';
 import { entryHasDatabase } from '../worker-app-config.js';
 import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CHAT_CALLS_APPLIED_SCOPE_KEY, CHAT_CALLS_TOKEN_SCOPE_KEY, CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, chatCallsApplied, chatHasUpstreams, desiredAgoraEnv, entryClientIdScopeKey, withRecordedMessagingProject, } from './agora.js';
+import { AI_OFFERS_SCOPE_KEY, aiKeyPermissions, aiOffers, planAiBouleKey } from './ai-boule-key.js';
 import { planAnalyticsBoule } from './analytics-boule.js';
 import { analyticsEnvDrift, analyticsWanted, desiredAnalyticsEnv } from './analytics.js';
 import { planAppsDbRoute } from './apps-db-route.js';
@@ -25,9 +26,12 @@ import { authEventsAppliedScopeKey, authEventsBlocked, authEventsMarker, } from
 import { CUSTOMER_GRANTS_ENV, CUSTOMER_GRANTS_WRITTEN_SCOPE_KEY, customerGrantsEntries, customerGrantsShapeMatches, customerGrantsToDrop, wantedCustomerGrants, } from './entry-customer-grants.js';
 import { planEdgeReservedLabels, planEdgeSlug, planEntryEdgeKeys } from './entry-edge-key.js';
 import { planFilesKeys } from './entry-files-key.js';
+import { planEntryJobsBouleKeys } from './entry-jobs-boule-key.js';
 import { planEntryJobs } from './entry-jobs.js';
 import { planEntryRepoKeys } from './entry-repo-key.js';
+import { planEntryReportingKeys } from './entry-reporting-key.js';
 import { BROKER_WORKSPACES_DATABASE_ENV, workspacesDatabaseRef } from './entry-workspaces.js';
+import { planFilesBouleKey } from './files-boule-key.js';
 import { gateIdRecordKey, hasWildcardGate, planGates } from './gates.js';
 import { githubSourceResourceKey, planGithubSource } from './github-source.js';
 import { appHostname, tunnelDnsHostnames } from './hostnames.js';
@@ -53,7 +57,10 @@ import { DEFAULT_ORG_PLATFORM_READINESS, } from './platform-org.js';
 import { PLATFORM_AUTH_BROKER_MAIL_KEY_REF } from './platform-providers.js';
 import { companyAppPostLogoutUris, postLogoutUpdateOwed, zitadelAppPostLogoutAppliedScopeKey, } from './post-logout-uris.js';
 import { CLOUDFLARE_TUNNEL_APPS_HOSTNAMES_SCOPE_KEY, CLOUDFLARE_TUNNEL_ENTRY_ROUTES_SCOPE_KEY, CLOUDFLARE_TUNNEL_OIKOS_HOSTNAMES_SCOPE_KEY, appLabelsAppliedScopeKey, entryAppsHostnames, entryLabelHash, entryLabelSpec, entryOikosHostnames, entryRoutes, entryRoutesMarker, } from './proxy-labels.js';
+import { planRegisteredApps } from './registered-app.js';
 import { planRemoteDatabase } from './remote-database.js';
+import { planReportingBoule } from './reporting-boule.js';
+import { REPORTING_MAIL_TOKEN_ENV, desiredReportingEnv, reportingEnvDrift, reportingWanted, } from './reporting.js';
 import { ZITADEL_ORG_DOMAIN_BLOCKED_SCOPE_KEY, ZITADEL_ORG_DOMAIN_SCOPE_KEY, ZITADEL_ORG_REGISTRATION_CLOSED_SCOPE_KEY, signInDomainBlockedText, signInOrgDomain, } from './sign-in-org.js';
 import { SIGN_IN_BASE_PATH, SIGN_IN_IMAGE_TAG_SUFFIX, SIGN_IN_IN_APP_SCOPE_KEY, SIGN_IN_LOGIN_APP_SCOPE_KEY, SIGN_IN_LOGIN_INTERNAL_NAME, SIGN_IN_RATE_LIMIT_SCOPE_KEY, SIGN_IN_TRUSTED_SCOPE_KEY, inAppSignIn, inAppStatePairs, inAppTargets, signInLoginNames, } from './sign-in.js';
 import { withStepSystem } from './step-system.js';
@@ -446,13 +453,14 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
     const filesOrganisation = planFilesOrganisation(org, byKey, claimed, platformReadiness.filesReady, platformReadiness.missingKeys.files, platformReadiness.noKeyReader, ownsServices(org) && !recordedIds[`coolify:own-files:${org.id}`]);
     if (filesOrganisation.step)
         plannedSteps.push(filesOrganisation.step);
-    const aiOrganisation = planAiOrganisation(org, byKey, claimed, platformReadiness.aiReady, platformReadiness.missingKeys.ai, platformReadiness.noKeyReader);
+    const aiBouleReads = options.aiBouleReads ?? false;
+    const aiOrganisation = planAiOrganisation(org, byKey, claimed, platformReadiness.aiReady, platformReadiness.missingKeys.ai, platformReadiness.noKeyReader, recordedIds, aiBouleReads);
     if (aiOrganisation.step)
         plannedSteps.push(aiOrganisation.step);
     const aiBudget = planAiBudget(org, byKey, claimed, platformReadiness.aiReady, platformReadiness.missingKeys.ai, platformReadiness.noKeyReader);
     if (aiBudget.step)
         plannedSteps.push(aiBudget.step);
-    const aiKey = planAiKey(org, recordedIds, platformReadiness.aiReady);
+    const aiKey = planAiKey(org, recordedIds, platformReadiness.aiReady, aiBouleReads);
     if (aiKey.step)
         plannedSteps.push(aiKey.step);
     // Before `planSite`'s own step (#139): `cmsSite`'s executor reads this
@@ -609,12 +617,14 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
         const marker = workspaceSignInMarker(declaredOrg, entry, recordedIds, authIssuer);
         if (marker)
             return marker;
-        const customers = entry.uses?.auth?.users === 'customers';
+        const customers = signsInCustomers(entry.uses?.auth);
         const orgKnown = customers
             ? Boolean(recordedIds[testCustomersOrgKey(org.id)]) ||
                 stepPlanned('zitadel', 'customers-test')
             : Boolean(recordedIds.zitadel_org);
-        const clientKnown = Boolean(recordedIds[entryClientIdScopeKey(workspaceClientKey(entry.key))]) ||
+        // ADR 0003: the broker makes the clients of a workspace both sign in to, once the stage exists.
+        const clientKnown = signsInBoth(entry.uses?.auth) ||
+            Boolean(recordedIds[entryClientIdScopeKey(workspaceClientKey(entry.key))]) ||
             stepPlanned('zitadel', 'app', workspaceClientKey(entry.key));
         const mcpKnown = !entry.uses?.auth?.mcp ||
             Boolean(recordedIds[entryMcpProjectScopeKey(workspaceClientKey(entry.key))]) ||
@@ -737,6 +747,12 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
     }, customerGrantsShape);
     if (boule.step)
         plannedSteps.push(boule.step);
+    // foundry#1121: Boule's files key, after Boule and after the org's own files key it is minted below.
+    const filesBouleKey = planFilesBouleKey(org, recordedIds, plannedSteps, platformReadiness, (options.now ?? Date.now)());
+    plannedSteps.push(...filesBouleKey.steps);
+    // foundry#1122: Boule's ai key, after Boule and after the org's own ai key it is minted below.
+    const aiBouleKey = planAiBouleKey(org, recordedIds, plannedSteps, platformReadiness, (options.now ?? Date.now)(), aiBouleReads);
+    plannedSteps.push(...aiBouleKey.steps);
     // foundry#949: the company's kosmos, only once it turns it on. Its fixed ZITADEL client first, the same
     // reason Boule's and Agora's do: `coolifyKosmos` reads this step's recorded client id.
     const kosmosClient = planKosmosClient(org, byKey, claimed);
@@ -754,6 +770,14 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
     plannedSteps.push(...planAnalyticsBoule(org, recordedIds, plannedSteps));
     const entryAnalyticsKeys = planEntryAnalyticsKeys(org, recordedIds, plannedSteps, options.analyticsPort ?? false);
     plannedSteps.push(...entryAnalyticsKeys.steps);
+    // The company's reporting backend, the same way: only while an entry's `uses.reporting` or Boule's apps
+    // use it, never parked once made, and before the site keys and Boule's env, which need its operator key.
+    const reporting = planReportingBackend(org, byKey, claimed, recordedIds, options.otherSlugs ?? [], platformReadiness);
+    if (reporting.step)
+        plannedSteps.push(reporting.step);
+    plannedSteps.push(...planReportingBoule(org, recordedIds, plannedSteps));
+    const entryReportingKeys = planEntryReportingKeys(org, recordedIds, plannedSteps, options.reportingPort ?? false);
+    plannedSteps.push(...entryReportingKeys.steps);
     // Boule's, Agora's and kosmos's blue/green: after their own steps, which make the app it copies.
     plannedSteps.push(...blueGreen.steps.filter((x) => x.phase === 'last').map(blueGreenDraft()));
     // Boule owners, after the Boule step: needs the app deployed and the seeding secret in its env.
@@ -781,6 +805,9 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
     // A `uses.jobs` entry registers with the scheduler after its app, whose env the step writes.
     const entryJobs = planEntryJobs(org, recordedIds, plannedSteps, platformReadiness, schedulerUsable);
     plannedSteps.push(...entryJobs.steps);
+    // foundry#1119: Boule's key for each entry's project, after the project and after Boule.
+    const entryJobsBouleKeys = planEntryJobsBouleKeys(org, recordedIds, plannedSteps, platformReadiness, options.jobsProjectKeys ?? false);
+    plannedSteps.push(...entryJobsBouleKeys.steps);
     // F12: a deploy key for an entry's own repo, after its app (whose env the step writes).
     const entryRepoKeys = planEntryRepoKeys(org, recordedIds, plannedSteps, platformReadiness);
     plannedSteps.push(...entryRepoKeys.steps);
@@ -792,6 +819,12 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
     // The company's registrar record in the broker, after Boule's own broker entry.
     if (registrar.step)
         plannedSteps.push(registrar.step);
+    // ADR 0003: after the registrar, the apps and the workspaces: the entries both sign in to are registered.
+    const registeredApps = planRegisteredApps(declaredOrg, recordedIds, plannedSteps, {
+        registrarApi: options.registrarApi ?? false,
+        authIssuer,
+    });
+    plannedSteps.push(...registeredApps.steps);
     // #440: Agora's desktop sign-in backend, after Agora and Boule: its readiness probe goes through Agora's proxy, and
     // Agora writes the upstream only once the service ran healthy (so a first apply needs a second to turn it on).
     const desktopAuth = planDesktopAuth(org, recordedIds, {
@@ -1039,6 +1072,12 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
     if (analytics.blocked)
         unmanaged.push({ description: analytics.blocked, key: 'coolify:analytics' });
     unmanaged.push(...entryAnalyticsKeys.blocked);
+    if (reporting.blocked)
+        unmanaged.push({ description: reporting.blocked, key: 'coolify:reporting' });
+    if (reporting.mailBlocked) {
+        unmanaged.push({ description: reporting.mailBlocked, key: 'coolify:reporting:mail' });
+    }
+    unmanaged.push(...entryReportingKeys.blocked);
     // Same for an ai key minted but never delivered: planning a new mint would
     // orphan a second live key.
     if (aiKey.blocked)
@@ -1046,7 +1085,9 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
     unmanaged.push(...blueGreen.unmanaged);
     unmanaged.push(...workspaces.unmanaged);
     unmanaged.push(...filesKeys.blocked);
+    unmanaged.push(...filesBouleKey.blocked);
     unmanaged.push(...entryAiKeys.blocked);
+    unmanaged.push(...aiBouleKey.blocked);
     unmanaged.push(...edgeWorkers.blocked);
     unmanaged.push(...workerApps.blocked);
     if (appsDb.blocked) {
@@ -1067,6 +1108,7 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
     unmanaged.push(...appsDbRoute.blocked);
     unmanaged.push(...appsZones.blocked);
     unmanaged.push(...entryJobs.blocked);
+    unmanaged.push(...entryJobsBouleKeys.blocked);
     unmanaged.push(...authEventsBlocked(org, recordedIds));
     unmanaged.push(...entryAudit.blocked);
     unmanaged.push(...entryRepoKeys.blocked);
@@ -1173,6 +1215,7 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
     unmanaged.push(...app.blocked);
     unmanaged.push(...brokerEntries.blocked);
     unmanaged.push(...workspaceBrokerEntries.blocked);
+    unmanaged.push(...registeredApps.blocked);
     unmanaged.push(...bouleBroker.blocked);
     // F6: last, so every database step above runs before the backup of its database.
     const backups = planCompanyBackups(org, recordedIds, options.backupStorageUuid);
@@ -2475,7 +2518,6 @@ function planCallsChat(org, recordedIds, upstreamPlanned, upstreamBlocked) {
  * organisation bring its own provider credentials (BYOK) -- a separate,
  * 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,
@@ -2619,12 +2661,37 @@ ownFilesPending = false) {
  * #177: blocked, not planned, while `aiReady` is false -- the platform's own
  * AI host (#172) is off or not yet applied.
  */
-function planAiOrganisation(org, byKey, claimed, aiReady, missingKeyRef, noKeyReader = false) {
+function planAiOrganisation(org, byKey, claimed, aiReady, missingKeyRef, noKeyReader = false, recordedIds = {}, bouleReads = false) {
     const key = resourceKey('ai', 'organisation', org.id);
     const live = byKey.get(key);
+    const offers = aiOffers(bouleReads);
     if (live) {
         claimed.add(key);
-        return { step: null, blocked: null };
+        // foundry#1122: once ai offers Boule's reads, an organisation offered fewer is offered them (both calls
+        // are repeatable). Without the host's word nothing changes.
+        if (!bouleReads || !aiReady || recordedIds[AI_OFFERS_SCOPE_KEY] === JSON.stringify(offers)) {
+            return { step: null, blocked: null };
+        }
+        return {
+            step: {
+                action: {
+                    system: 'ai',
+                    kind: 'organisation',
+                    key: org.id,
+                    desired: {
+                        provision: true,
+                        limitMicros: effectiveAiLimitMicros(org.ai.limitMicros),
+                        offers,
+                    },
+                },
+                step: {
+                    description: `offer ${org.slug}'s AI organisation the read permissions Boule's AI page needs`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked: null,
+        };
     }
     if (!aiReady) {
         return {
@@ -2641,7 +2708,7 @@ function planAiOrganisation(org, byKey, claimed, aiReady, missingKeyRef, noKeyRe
                 desired: {
                     provision: true,
                     limitMicros: effectiveAiLimitMicros(org.ai.limitMicros),
-                    offers: [...AI_DEFAULT_OFFERS],
+                    offers,
                 },
             },
             step: {
@@ -2725,17 +2792,24 @@ function planAiBudget(org, byKey, claimed, aiReady, missingKeyRef, noKeyReader =
  * organisation to mint a key inside yet, and {@link planAiOrganisation}
  * already reports the platform's AI host as missing once.
  */
-function planAiKey(org, recordedIds, aiReady) {
+function planAiKey(org, recordedIds, aiReady, bouleReads = false) {
     const key = resourceKey('ai', 'key', org.id);
-    if (recordedIds[key])
+    const permissions = aiOffers(bouleReads);
+    // foundry#1122: a delivered key that holds fewer than the organisation now offers is minted again with them,
+    // so Boule's key can be minted below it. Without the host's word a delivered key plans nothing.
+    const widen = Boolean(recordedIds[key]) &&
+        bouleReads &&
+        aiKeyPermissions(recordedIds) !== JSON.stringify(permissions);
+    if (recordedIds[key] && !widen)
         return { step: null, blocked: null }; // delivered -- a re-run plans nothing.
     if (!aiReady)
         return { step: null, blocked: null };
     // Minted but never delivered (`executor.ts`'s `aiKey`): nobody holds the
     // secret and ai has no per-key revoke yet, so a new mint would only add
-    // another orphan. Reported, not planned.
+    // another orphan. Reported, not planned. (The delivered key's own id stays
+    // recorded as undelivered; it blocks nothing.)
     const undelivered = recordedIds[AI_KEY_UNDELIVERED_SCOPE_KEY];
-    if (undelivered) {
+    if (undelivered && undelivered !== recordedIds[key]) {
         return {
             step: null,
             blocked: `${org.slug}'s ai key ${undelivered} was minted but not delivered and must be revoked in ai before a new one is minted (https://github.com/wtfalch/ai/issues/138)`,
@@ -2751,11 +2825,14 @@ function planAiKey(org, recordedIds, aiReady) {
                 desired: {
                     name: `${org.slug}-app`,
                     expiresDays: 365,
-                    permissions: [...AI_DEFAULT_OFFERS],
+                    permissions,
+                    ...(widen ? { mode: 'widen' } : {}),
                 },
             },
             step: {
-                description: `mint ${org.slug}'s own ai key`,
+                description: widen
+                    ? `mint ${org.slug}'s own ai key again with the read permissions Boule's key needs; the old one stays live until it expires`
+                    : `mint ${org.slug}'s own ai key`,
                 destroys: false,
                 migrates: false,
             },
@@ -3332,6 +3409,120 @@ function planAnalyticsBackend(org, byKey, claimed, recordedIds, otherSlugs) {
         blocked: null,
     };
 }
+/**
+ * The company's reporting backend, the same shape as `planAnalyticsBackend`: a per-org singleton keyed by the
+ * org id under its own `reporting` kind, built from https://github.com/wtfalch/reporting's root Dockerfile
+ * (`executor.ts`'s `coolifyReporting`) with a database of its own. Planned only while `reportingWanted(org)`; once live it is kept and never parked. A live
+ * app is planned again when its `APP_URL` or `AUTH_ORGANIZATION_ID` is missing or different. It needs no
+ * sign-in client and no issuer; only the company's sign-in organisation id (recorded by an earlier step).
+ *
+ * Mail (reporting#103, foundry#1128), on the same terms as Boule's: a hosted-mail company whose domain is
+ * recorded gives the backend `MAIL_FROM` (`reportingMailFrom`) and its `<slug>-app` Lettermint token, as a
+ * consumer of the shared mint rule. Blocked, not failing, while the platform cannot supply the token: the
+ * backend is planned without mail and the reason is its own line. The token is compared by presence
+ * (`config.mailTokenHeld`), never by value, and a reader that did not say reads as holding it, so a backend
+ * that lacks either is planned once and converges.
+ */
+function planReportingBackend(org, byKey, claimed, recordedIds, otherSlugs, readiness = DEFAULT_ORG_PLATFORM_READINESS) {
+    const key = resourceKey('coolify', 'reporting', org.id);
+    const live = byKey.get(key);
+    if (live)
+        claimed.add(key);
+    if (!reportingWanted(org))
+        return { step: null, blocked: null, mailBlocked: null };
+    const tooLong = [
+        [`${org.slug}-reporting`, 'the reporting host label and app name'],
+        [`${org.slug}_reporting_db_rt`, 'the reporting database role'],
+    ].filter(([name]) => name.length > 63);
+    if (tooLong.length > 0) {
+        return {
+            step: null,
+            mailBlocked: null,
+            blocked: `${org.slug}'s reporting backend is blocked, not planned: ${tooLong.map(([n, what]) => `${what} '${n}' is over 63 characters`).join(', ')}; shorten the slug`,
+        };
+    }
+    if (otherSlugs.includes(`${org.slug}-reporting`)) {
+        return {
+            step: null,
+            mailBlocked: null,
+            blocked: `${org.slug}'s reporting backend is blocked, not planned: another declared org has the slug '${org.slug}-reporting', which is this backend's hostname`,
+        };
+    }
+    const mailDomain = recordedIds[MAIL_DOMAIN_SCOPE_KEY]?.toLowerCase();
+    const mailWanted = bouleMailWanted(org, recordedIds) && Boolean(mailDomain);
+    const isApexOrg = Boolean(mailDomain && readiness.platformApex && mailDomain === readiness.platformApex.toLowerCase());
+    let mailBlockedReason = null;
+    if (mailWanted && isApexOrg) {
+        if (!readiness.platformLettermintProjectId) {
+            mailBlockedReason = 'platform.mail.lettermintProjectId is not declared yet';
+        }
+        else if (readiness.mailKeyHeld !== true) {
+            mailBlockedReason = `the platform's Lettermint key is not held yet (held-key ref ${PLATFORM_AUTH_BROKER_MAIL_KEY_REF})`;
+        }
+    }
+    else if (mailWanted) {
+        mailBlockedReason = edgeNeeded(readiness, ['zones', 'dns']);
+    }
+    const mailBlocked = mailBlockedReason
+        ? `${org.slug}'s reporting backend mail is blocked, not planned: ${mailBlockedReason}`
+        : null;
+    const mailOn = mailWanted && !mailBlocked;
+    // `coolifyReporting` writes nothing without the sign-in organisation, so the step waits for it here.
+    const { env, missing } = desiredReportingEnv(org, recordedIds, mailOn ? (recordedIds[MAIL_DOMAIN_SCOPE_KEY] ?? null) : null);
+    if (missing.length > 0) {
+        return {
+            step: null,
+            mailBlocked: null,
+            blocked: `${org.slug}'s reporting backend is blocked, not planned: the company's sign-in organisation is not recorded yet`,
+        };
+    }
+    const action = {
+        system: 'coolify',
+        kind: 'reporting',
+        key: org.id,
+        // Only a backend that gets mail carries the mail fields, so every other plan is unchanged. The platform
+        // values go in like Boule's: the executor writes what the plan showed.
+        desired: mailOn
+            ? {
+                mail: true,
+                platformApex: readiness.platformApex ?? null,
+                platformLettermintProjectId: readiness.platformLettermintProjectId ?? null,
+            }
+            : {},
+    };
+    if (!live) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `provision ${org.slug}'s reporting backend`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked: null,
+            mailBlocked,
+        };
+    }
+    const drift = reportingEnvDrift(env, (live.config.env ?? {}));
+    // The token by presence only; a reader that did not say reads as holding it.
+    if (mailOn && live.config.mailTokenHeld === false)
+        drift.push(REPORTING_MAIL_TOKEN_ENV);
+    if (drift.length === 0)
+        return { step: null, blocked: null, mailBlocked };
+    return {
+        step: {
+            action,
+            step: {
+                description: `update ${org.slug}'s reporting backend config (${drift.join(', ')} missing or different)`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+        mailBlocked,
+    };
+}
 /**
  * C3: which credentials the org's Boule is given, and why one is not. Archon's credential goes to every
  * Boule the host can mint it for; the customers directory credential only while `customers.enabled`. Each
@@ -3883,6 +4074,26 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
             blocked,
         };
     }
+    // Rule 4, from live state: an entry that sends mail and whose app has no
+    // `MAIL_APP_KEY` yet gets it pushed once (`pushAppEnv` writes it on every
+    // run). Its value is the entry key, so the name alone says it is there. A
+    // reader that did not list env names reads as compliant, as above.
+    if (entry &&
+        sendsMail(entry) &&
+        Array.isArray(envNames) &&
+        !envNames.includes(MAIL_APP_KEY_ENV)) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `give ${org.slug}'s ${label} its ${MAIL_APP_KEY_ENV} (the key its mail is tagged with) and restart it`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked,
+        };
+    }
     // #243 (rule 3): a changed entry `env` reaches an app that is already
     // live. `pushAppEnv` records what it pushed, so this plans the same step
     // again, with a redeploy, only once the resolved map differs from that.
@@ -4551,7 +4762,8 @@ function planIssuerApps(org, byKey, claimed) {
 function planEntryClients(org, byKey, claimed) {
     const steps = [];
     for (const entry of org.hosting.entries) {
-        if (!entry.uses?.auth)
+        // ADR 0003: the broker makes the clients of an entry both sign in to when it is registered.
+        if (!entry.uses?.auth || signsInBoth(entry.uses.auth))
             continue;
         const key = resourceKey('zitadel', 'app', entry.key);
         if (byKey.has(key)) {
@@ -4582,7 +4794,8 @@ export function planBrokerEntries(org, recordedIds, plannedSteps, brokerWired, b
     const blocked = [];
     for (const entry of org.hosting.entries) {
         const auth = entry.uses?.auth;
-        if (!auth)
+        // An entry both sign in to is registered (`registered-app.ts`), not an `AUTH_APPS` entry.
+        if (!auth || signsInBoth(auth))
             continue;
         const at = `${org.slug}'s ${entry.key} broker entry`;
         const key = `coolify:broker-entry:${entry.key}`;
@@ -4739,7 +4952,7 @@ function planBouleBrokerEntry(org, recordedIds, plannedSteps, brokerWired) {
 function planCustomers(org, live, claimed, recordedIds, metadataWired, policyAvailable = true) {
     const signUp = org.customers?.signUp === true;
     const wanted = org.customers?.enabled === true ||
-        org.hosting.entries.some((entry) => entry.uses?.auth?.users === 'customers');
+        org.hosting.entries.some((entry) => signsInCustomers(entry.uses?.auth));
     // The sign-in page reads this from the customers organisation: any entry with an emailed code turns it on.
     const wantedSignIn = wanted && org.hosting.entries.some((entry) => entry.uses?.auth?.signIn === 'email-code')
         ? 'email-code'

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

@@ -11,8 +11,11 @@ import type { OrgPlatformReadiness } from './platform-org.js';
 export declare const FILES_KEY_DAYS = 365;
 /** A key with fewer days left than this is renewed. */
 export declare const FILES_KEY_RENEW_WINDOW_DAYS = 30;
-/** What the org's own key holds: it mints and revokes, and holds what its entries may hold. */
-export declare const FILES_ROOT_PERMISSIONS: readonly ["credentials:create", "credentials:revoke", "files.collections:read", "files.files:read", "files.files:download", "files.files:upload", "files.files:replace", "files.files:delete"];
+/**
+ * What the org's own key holds: it mints and revokes, and holds what its entries and Boule's key may hold
+ * (foundry#1121: `files.usage:read`, `files.shares:read` and `files.files:share` for Boule's Files page).
+ */
+export declare const FILES_ROOT_PERMISSIONS: readonly ["credentials:create", "credentials:revoke", "files.collections:read", "files.files:read", "files.files:download", "files.files:upload", "files.files:replace", "files.files:delete", "files.usage:read", "files.shares:read", "files.files:share"];
 /**
  * Flat scope ids (no `:`). The org's own key: the id minted last (it blocks
  * only while it differs from the recorded key, which means it was never
@@ -20,6 +23,12 @@ export declare const FILES_ROOT_PERMISSIONS: readonly ["credentials:create", "cr
  */
 export declare const FILES_ROOT_UNDELIVERED_SCOPE_KEY = "files_key_undelivered";
 export declare const FILES_ROOT_EXPIRES_SCOPE_KEY = "files_key_expires";
+/**
+ * foundry#1121: the permissions the recorded org key was minted with, as JSON. A key minted before this was
+ * recorded, or with fewer permissions than {@link FILES_ROOT_PERMISSIONS}, is renewed: a key below it can
+ * hold only what it holds.
+ */
+export declare const FILES_ROOT_PERMISSIONS_SCOPE_KEY = "files_key_permissions";
 /** Ids of org keys replaced by a renewal, as a JSON array, revoked once every entry holds a key below the new one. */
 export declare const FILES_ROOT_PREVIOUS_SCOPE_KEY = "files_key_previous";
 /** Ids of replaced org keys whose revoke failed, as a JSON array. They expire on their own; the plan lists each. */
@@ -47,6 +56,26 @@ export declare const entryFilesRetiredScopeKey: (entryKey: string) => string;
 export declare const entryFilesUnrevokedScopeKey: (entryKey: string) => string;
 export declare const ENTRY_FILES_UNREVOKED_PREFIX = "files_entry_unrevoked_";
 export declare const ENTRY_FILES_UNDELIVERED_PREFIX = "files_entry_undelivered_";
+/** foundry#1121 (`files-boule-key.ts`). Boule's key is minted, not held yet: its id, never the key. */
+export declare const FILES_BOULE_UNDELIVERED_SCOPE_KEY = "files_boule_key_undelivered";
+/** The id of Boule's key once it is held. */
+export declare const FILES_BOULE_KEY_SCOPE_KEY = "files_boule_key";
+/** The id of the org's own files key Boule's key was minted below. */
+export declare const FILES_BOULE_MINTER_SCOPE_KEY = "files_boule_key_minter";
+/** Ids of Boule keys a renewal replaced, as a JSON array, revoked once the new one is in Boule's env. */
+export declare const FILES_BOULE_PREVIOUS_SCOPE_KEY = "files_boule_key_previous";
+/** Per entry: label to collection name in files, every name the entry ever had. */
+export declare const entryFilesCollectionsScopeKey: (entryKey: string) => string;
+/** The name a new collection of an entry gets in files. */
+export declare const entryCollectionName: (entryKey: string, label: string) => string;
+/**
+ * Every collection name the entry has had, label to name: the recorded map, or, before one is recorded, each
+ * label of the entry's last applied files marker under its own name (the name files was given before
+ * collections were named per app).
+ */
+export declare function knownCollectionNames(entryKey: string, recordedIds: Readonly<Record<string, string>>): Record<string, string>;
+/** The files name of each collection the entry declares now, label to name, in the declared order. */
+export declare function entryCollectionNames(entry: Pick<HostingEntry, 'key' | 'uses'>, recordedIds: Readonly<Record<string, string>>): Record<string, string>;
 export declare function parseIdList(raw: string | undefined): string[];
 export declare const filesRootKeyName: (org: DeclaredOrg) => string;
 export declare const entryFilesKeyName: (org: DeclaredOrg, entry: HostingEntry) => string;
@@ -58,8 +87,15 @@ export interface EntryFilesWant {
     filesUrl: string;
     /** `https://share.<domain>`, set only when the entry declares `shareHost`. */
     shareOrigin?: string;
+    /** foundry#1121: each collection's name in files, label to name (`files-boule-key.ts`). */
+    collectionNames: Record<string, string>;
 }
-export declare function wantedEntryFiles(entry: HostingEntry, filesUrl: string, shareHostname?: string | null): EntryFilesWant;
+export declare function wantedEntryFiles(entry: HostingEntry, filesUrl: string, shareHostname?: string | null, recordedIds?: Readonly<Record<string, string>>): EntryFilesWant;
+/**
+ * foundry#1121: Boule's files key, when it has one, is below `rootKeyId` and delivered, so revoking the org
+ * key it replaced revokes nothing Boule still uses.
+ */
+export declare function bouleKeyBelow(recordedIds: Readonly<Record<string, string>>, rootKeyId: string | undefined): boolean;
 export type EntryFilesMode = 'mint' | 'renew' | 'settings' | 'finish' | 'retire';
 type Blocked = Array<{
     description: string;