@wtfalch/foundry 0.60.0 → 0.62.0

package/dist/plan/diff.js

@@ -1,10 +1,13 @@
-import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
-import { APP_ENTRY_KEY, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, heldEnvRef, mainEntry, ownerMailboxRecorded, ownerMailboxes, ownerNameProblem, ownsServices, } from '../org.js';
+import { VERSIONS } from '../bootstrap/versions.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 { 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, withRecordedMessagingProject, } from './agora.js';
-import { planBlueGreen } from './blue-green.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 { planAppsDbRoute } from './apps-db-route.js';
+import { planAppsZones } from './apps-zones.js';
+import { bgKey, planBlueGreen, } from './blue-green.js';
 import { BOULE_ARCHON_CREDENTIAL_ENV, BOULE_BRIDGE_SECRET_ENV, BOULE_BROKER_ENTRY_KEY, BOULE_CUSTOMERS_CREDENTIAL_ENV, BOULE_MAIL_TOKEN_ENV, BOULE_OWNER_SEED_SECRET_ENV, BOULE_PEER_PASSWORD_ENV, BOULE_SECRETS_RESTARTED_SCOPE_KEY, CUSTOMERS_ROOM_SCOPE_KEY, CUSTOMERS_SIGN_IN_SCOPE_KEY, CUSTOMERS_SIGN_UP_SCOPE_KEY, archonCredentialRenewDue, bouleEnvDrift, bouleMailTokenDrift, bouleMailWanted, customersOrgIdOf, customersRoomValue, desiredBouleEnv, planBouleOwners, staleCustomersEnv, wantedBouleBrokerEntry, } from './boule.js';
-import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
+import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, entryMcpProjectScopeKey, wantedBrokerEntry, } from './broker-entries.js';
+import { bouleRegistrarDrift, planBrokerRegistrar } from './broker-registrar.js';
 import { chatInternalNames, chatUpstreams } from './chat-matrix.js';
 import { planCompanyBackups } from './company-backups.js';
 import { COOKIE_DOMAIN_WAITING_REASONS, LOGIN_COOKIE_DOMAIN_SCOPE_KEY, MIN_AUTH_FOR_CLIENT_ORGS, authAtLeast, cookieDomainAllowed, cookieDomainWaitingLine, } from './cookie-domain.js';
@@ -12,34 +15,49 @@ import { DESKTOP_AUTH_HOME, planDesktopAuth } from './desktop-auth.js';
 import { planDesktopCallbacks } from './desktop-callback.js';
 import { onPlatformNetwork } from './destinations.js';
 import { planEntryAiKeys } from './entry-ai-key.js';
-import { planEdgeReservedLabels, planEntryEdgeKeys } from './entry-edge-key.js';
+import { planEntryAudit } from './entry-audit.js';
+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 { hasWildcardGate, planGates } from './gates.js';
+import { planEntryJobs } from './entry-jobs.js';
+import { planEntryRepoKeys } from './entry-repo-key.js';
+import { BROKER_WORKSPACES_DATABASE_ENV, workspacesDatabaseRef } from './entry-workspaces.js';
+import { gateIdRecordKey, hasWildcardGate, planGates } from './gates.js';
+import { githubSourceResourceKey, planGithubSource } from './github-source.js';
 import { appHostname, tunnelDnsHostnames } from './hostnames.js';
+import { planKeysRegistrar } from './keys-registrar.js';
+import { desiredKosmosEnv, kosmosEnvDrift } from './kosmos.js';
 import { APP_GONE_KIND } from './live.js';
 import { lockedHostnames } from './locked-hostnames.js';
 import { LOGIN_BINDING_SCOPE_KEY, LOGIN_CLIENT_ORGS_SCOPE_KEY, OWN_CUSTOMERS_BASE_URI_SCOPE_KEY, agoraIssuerHostFor, clientOrganizationsState, companyLoginTunnelHost, customersClientOrganizations, inAppApps, loginBindingState, loginHostClientIds, loginHostServesAgora, loginHostnameFor, ownAuthApplied, ownCustomersAppState, pendingRemovalHosts, } from './login-host.js';
+import { planMachineBypasses } from './machine-paths.js';
 import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, } from './mail-copy.js';
 import { mailStoreSwitchChange } from './mail-store.js';
 import { planMcp } from './mcp.js';
 import { hasAdoptedResources, networkMoveNeeded, planNetworkMove } from './network-move.js';
+import { planAppsAdmin } from './org-apps-admin.js';
 import { planOrgPostgresMigration } from './org-postgres-migrate.js';
 import { legacyUnmigrated, orgPostgresUndeliveredScopeKey, planOrgPostgresSteps, serviceOnServer, } from './org-postgres.js';
-import { OWN_AUTH_BLOCKED_KEY, OWN_FILES_BLOCKED_KEY, OWN_FILES_R2_BLOCKED_KEY, OWN_JOBS_BLOCKED_KEY, OWN_MAIL_BLOCKED_KEY, OWN_SFU_BLOCKED_KEY, OWN_SFU_FIREWALL_KEY, OWN_SIGNIN_DB_MOVE_BLOCKED_KEY, planOwnAuth, planOwnFiles, planOwnFilesR2, planOwnJobs, planOwnMail, planOwnSfu, planSigninDbMove, } from './own-diff.js';
+import { OWN_AUTH_BLOCKED_KEY, OWN_FILES_BLOCKED_KEY, OWN_FILES_R2_BLOCKED_KEY, OWN_JOBS_BLOCKED_KEY, OWN_JOBS_ROUTE_BLOCKED_KEY, OWN_MAIL_BLOCKED_KEY, OWN_SFU_BLOCKED_KEY, OWN_SFU_FIREWALL_KEY, OWN_SIGNIN_DB_MOVE_BLOCKED_KEY, planOwnAuth, planOwnFiles, planOwnFilesR2, planOwnJobs, planOwnJobsRoute, planOwnMail, planOwnSfu, planSigninDbMove, } from './own-diff.js';
 import { ownDnsHostnames } from './own-dns.js';
 import { ownHostnames } from './own-hostnames.js';
+import { platformMailMxHost } 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, ORG_MAIL_APPLIED_MODE_SCOPE_KEY, ORG_MAIL_APPLIED_USES_DOMAIN_SCOPE_KEY, PLATFORM_AUTH_MCP_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, appEnvAppliedScopeKey, appFolderDiffers, appSecretAvailability, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, serviceDbEnvAppliedScopeKey, versionNotAppliedLine, zitadelAppIdTokenUserinfoAppliedScopeKey, } 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 { companyAppPostLogoutUris, postLogoutUpdateOwed, zitadelAppPostLogoutAppliedScopeKey, } from './post-logout-uris.js';
-import { CLOUDFLARE_TUNNEL_ENTRY_ROUTES_SCOPE_KEY, CLOUDFLARE_TUNNEL_OIKOS_HOSTNAMES_SCOPE_KEY, appLabelsAppliedScopeKey, entryLabelHash, entryLabelSpec, entryOikosHostnames, entryRoutes, entryRoutesMarker, } from './proxy-labels.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 { planRemoteDatabase } from './remote-database.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, } from './sign-in.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';
 import { WORKER_APP_DB_BLOCKED_KEY, WORKER_APP_DB_LEGACY_NOTE_KEY, WORKER_APP_DB_SCOPE_KEYS, planWorkerAppDb, } from './worker-app-db.js';
 import { brokerKeyDelivered, planWorkerApps } from './worker-app.js';
 import { planWorkers } from './worker.js';
+import { testCustomersOrgKey, withDarkWorkspaceSignIn, workspaceClientKey, } from './workspace-client.js';
+import { planTestCustomers, planWorkspaceBrokerEntries, planWorkspaceClients, workspaceSignInMarker, } from './workspace-sign-in.js';
+import { workspaceWorkerParent } from './workspace-worker.js';
+import { planWorkspaces, withWorkspaceWorkers, withoutDarkEntries, workspaceGateKey, wsKey, } from './workspace.js';
 /** The `Plan` (#19's public contract) a `PlanDetail` carries. */
 export function toPlan(detail) {
     return {
@@ -84,7 +102,17 @@ function madeByFoundry(org, r, recordedIds, recordedValues, platformNames) {
     if (r.system === 'coolify') {
         if (r.kind === 'environment')
             return true;
-        return r.kind === 'application' && r.config.name === chatInternalNames(org.slug).mas;
+        if (r.kind !== 'application')
+            return false;
+        // The in-app login app of the org's own sign-in stack; its id is not recorded, so its name says it.
+        const login = `${org.slug}-auth-login`;
+        const inAppLogin = signInLoginNames({
+            names: { authLogin: login },
+            internal: { authLogin: login },
+        });
+        if (r.config.name === inAppLogin.name)
+            return Boolean(recordedIds[`coolify:own-auth:${org.id}`]);
+        return r.config.name === chatInternalNames(org.slug).mas;
     }
     if (r.system !== 'cloudflare' || r.kind !== 'dns_record')
         return false;
@@ -122,6 +150,7 @@ const OWN_MARKER_KINDS = new Set([
     'own-files',
     'own-files-r2',
     'own-jobs',
+    'own-jobs-route',
     'own-sfu',
 ]);
 /** The kinds a provider lists a resource under before a recorded `system:kind:key` maps it to foundry's own. */
@@ -197,7 +226,10 @@ function liveResourceName(r) {
  * Company Factory end to end", which wires real readers and executors
  * against this seam.
  */
-export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AGORA_HOST_VALUES, jobsAvailable = false, platformReadiness = DEFAULT_ORG_PLATFORM_READINESS, options = {}) {
+export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost = NO_AGORA_HOST_VALUES, jobsAvailable = false, platformReadiness = DEFAULT_ORG_PLATFORM_READINESS, options = {}) {
+    // An entry that is not live has no app, address or Worker of its own: only its workspace exists (the
+    // workspace steps, the gate and the tunnel read `declaredOrg`).
+    const org = withoutDarkEntries(declaredOrg);
     const byKey = new Map(live.map((r) => [resourceKey(r.system, r.kind, r.key), r]));
     const claimed = new Set();
     const plannedSteps = [];
@@ -243,7 +275,7 @@ 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, {
+    const loginHost = planLoginHost(withDarkWorkspaceSignIn(org, declaredOrg), recordedIds, {
         authReady: platformReadiness.authReady,
         issuerPlanned: issuer.step !== null,
         bindingsWired: options.loginHostBindings ?? false,
@@ -320,7 +352,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     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, versionPin?.calls);
+    const calls = planCalls(org, byKey, claimed);
     if (calls.step)
         plannedSteps.push(calls.step);
     // An own org's media server, before the calls service that reads its addresses.
@@ -423,9 +455,14 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const customers = planCustomers(org, live, claimed, recordedIds, options.zitadelOrgMetadata ?? false);
     if (customers.step)
         plannedSteps.push(customers.step);
+    // The workspaces' own customers, before the clients and the workspace steps that read the organisation's id.
+    const testCustomers = planTestCustomers(declaredOrg, live, claimed, recordedIds, options.zitadelOrgMetadata ?? false);
+    if (testCustomers.step)
+        plannedSteps.push(testCustomers.step);
     for (const step of [
         ...planIssuerApps(org, byKey, claimed),
         ...planEntryClients(org, byKey, claimed),
+        ...planWorkspaceClients(declaredOrg, byKey, claimed),
     ]) {
         const guarded = guardApp(step);
         if (guarded)
@@ -433,14 +470,16 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     }
     // Auth ADR 0002: the MCP project and the JWT app, after the app they change
     // and before the broker entry and the Worker that read the project id.
-    const mcp = planMcp(org, recordedIds, plannedSteps, options.zitadelMcp ?? false);
+    const mcp = planMcp(org, recordedIds, plannedSteps, options.zitadelMcp ?? false, declaredOrg);
     plannedSteps.push(...mcp.steps);
     // The Access gate before the database, app, tunnel and zone (#84): on a
     // first apply the hostname is gated before anything answers on it.
     // An Access gate that cannot be planned must not leave the hostname it
     // guards routed: the tunnel (and its DNS) that exposes it waits too.
     let accessGateBlocked = false;
-    const access = planAccess(org, recordedIds, platformReadiness.accessProviderId ?? null, options.platformHostnames ?? []);
+    const access = planAccess(org, recordedIds, platformReadiness.accessProviderId ?? null, options.platformHostnames ?? [], declaredOrg);
+    for (const note of access.notes)
+        dnsBlocked.push({ description: note, key: 'cloudflare:access' });
     if (access.blocked) {
         accessGateBlocked = true;
         dnsBlocked.push({
@@ -477,11 +516,32 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     });
     if (workerAppDb.step)
         plannedSteps.push(workerAppDb.step);
+    // Before the apps: an app built from the company's own account is created through this source.
+    const githubSource = planGithubSource(org, recordedIds, platformReadiness.githubAppKeys);
+    if (githubSource.step)
+        plannedSteps.push(githubSource.step);
     const authIssuer = 'error' in agoraHost ? null : agoraHost.issuer;
     const app = planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer, platformReadiness);
     plannedSteps.push(...app.steps);
+    // The broker's workspaces database, before any broker entry that needs it: made once, when none is held or set.
+    const workspacesDatabasePlanned = declaredOrg.hosting.enabled &&
+        declaredOrg.hosting.entries.some((e) => e.uses?.auth?.workspaces) &&
+        (options.broker ?? false) &&
+        !(options.brokerWorkspacesDatabase ?? false) &&
+        (options.provisionWorkspacesDatabase ?? false);
+    if (workspacesDatabasePlanned) {
+        plannedSteps.push({
+            action: { system: 'coolify', kind: 'workspaces-database', key: org.id, desired: {} },
+            step: {
+                description: `make the database of ${org.slug}'s broker for customer workspaces and hold its URL at ${workspacesDatabaseRef(org)}`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    const brokerWorkspacesDatabase = (options.brokerWorkspacesDatabase ?? false) || workspacesDatabasePlanned;
     // After the apps: the broker entry's key is minted into each app's env.
-    const brokerEntries = planBrokerEntries(org, recordedIds, plannedSteps, options.broker ?? false);
+    const brokerEntries = planBrokerEntries(org, recordedIds, plannedSteps, options.broker ?? false, brokerWorkspacesDatabase);
     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)());
@@ -495,6 +555,10 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const edgeReservedLabels = planEdgeReservedLabels(org, recordedIds, platformReadiness, options.platformHostnames ?? []);
     if (edgeReservedLabels.step)
         plannedSteps.push(edgeReservedLabels.step);
+    // F3: the slug edge keys a company's platform hostnames on, next to the company's own edge key.
+    const edgeSlugStep = planEdgeSlug(org, recordedIds, platformReadiness);
+    if (edgeSlugStep)
+        plannedSteps.push(edgeSlugStep);
     // Blue/green (`blue-green.ts`): the apps and balancers before the tunnel routes to them, a second
     // server's connector after the tunnel exists.
     const blueGreen = planBlueGreen({
@@ -509,7 +573,49 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
             p.action.key === appStepKey(org, entryKey)),
     });
     plannedSteps.push(...blueGreen.steps.filter((x) => x.phase === 'before').map(blueGreenDraft()));
-    const tunnel = planTunnel(org, byKey, claimed, recordedIds, platformReadiness.platformApex);
+    // A workspace is made only behind its gate: recorded already, or planned earlier in this run.
+    const workspaceGateReady = (gateKey) => Boolean(recordedIds[gateIdRecordKey(org.id, gateKey)]) ||
+        plannedSteps.some((p) => p.action.system === 'cloudflare' &&
+            p.action.kind === 'gate' &&
+            p.action.key === appStepKey(org, gateKey));
+    const stepPlanned = (system, kind, key) => plannedSteps.some((p) => p.action.system === system &&
+        p.action.kind === kind &&
+        (key === undefined || p.action.key === key));
+    // A workspace's sign-in is ready when its values are recorded, or the steps that record them are planned.
+    const workspaceSignInWanted = (entry) => {
+        const marker = workspaceSignInMarker(declaredOrg, entry, recordedIds, authIssuer);
+        if (marker)
+            return marker;
+        const customers = entry.uses?.auth?.users === 'customers';
+        const orgKnown = customers
+            ? Boolean(recordedIds[testCustomersOrgKey(org.id)]) ||
+                stepPlanned('zitadel', 'customers-test')
+            : Boolean(recordedIds.zitadel_org);
+        const clientKnown = Boolean(recordedIds[entryClientIdScopeKey(workspaceClientKey(entry.key))]) ||
+            stepPlanned('zitadel', 'app', workspaceClientKey(entry.key));
+        const mcpKnown = !entry.uses?.auth?.mcp ||
+            Boolean(recordedIds[entryMcpProjectScopeKey(workspaceClientKey(entry.key))]) ||
+            stepPlanned('zitadel', 'mcp-project', `${org.id}:${workspaceClientKey(entry.key)}`);
+        return orgKnown && clientKnown && mcpKnown && authIssuer ? 'pending' : null;
+    };
+    // Blue/green's cousin: each server workspace is a stage with a host of its own, behind its gate.
+    const workspaces = planWorkspaces({
+        org: declaredOrg,
+        recordedIds,
+        servers: options.blueGreenServers,
+        gateReady: workspaceGateReady,
+        signInWanted: workspaceSignInWanted,
+        authIssuer,
+        ...(options.stageSinkDown ? { stageSinkDown: true } : {}),
+    });
+    plannedSteps.push(...workspaces.steps);
+    // After the workspace step has put the stage's own key in its env.
+    const workspaceBrokerEntries = planWorkspaceBrokerEntries(declaredOrg, recordedIds, plannedSteps, options.broker ?? false, brokerWorkspacesDatabase, (entry) => recordedIds[bgKey.stageState(entry.key)] === 'ok' ||
+        plannedSteps.some((p) => p.action.system === 'coolify' &&
+            p.action.kind === 'workspace' &&
+            p.action.desired.entry === entry.key));
+    plannedSteps.push(...workspaceBrokerEntries.steps);
+    const tunnel = planTunnel(declaredOrg, byKey, claimed, recordedIds, platformReadiness.platformApex);
     // #238: a tunnel that is being provisioned waits for an active zone; parking
     // one never does.
     // #555: provisioning writes the tunnel config, the zone lookup and DNS; a
@@ -577,10 +683,45 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         archon: options.bouleArchonCredential === true,
         directory: options.customersDirectory === true,
     }, platformReadiness.canHoldSecrets === true, (options.now ?? Date.now)());
-    const boule = planBoule(org, byKey, claimed, recordedIds, authIssuer, options.otherSlugs ?? [], options.archonUrl ?? null, platformReadiness, bouleCredentials.wants);
+    // F13: Boule's `CUSTOMER_GRANTS`, from the entries that declare `uses.customerGrants`. Every reason it
+    // says nothing yet is a plan line, never silence.
+    const customerGrants = wantedCustomerGrants(org, recordedIds, {
+        live: byKey.has(resourceKey('coolify', 'boule', org.id)),
+    });
+    const customerGrantsNotes = [...customerGrants.notes];
+    let customerGrantsShape = null;
+    if (customerGrants.shape) {
+        if (bouleCredentials.wants.customersDirectory) {
+            customerGrantsShape = customerGrants.shape;
+        }
+        else {
+            customerGrantsNotes.push(`${org.slug}'s customer grants are not planned: they need the customers directory credential, which is blocked above`);
+        }
+    }
+    // T3: a company with customers gets a registrar key at the sign-in broker; Boule is given it.
+    const registrar = planBrokerRegistrar(org, recordedIds, plannedSteps, {
+        brokerWired: options.broker ?? false,
+        canHoldSecrets: platformReadiness.canHoldSecrets === true,
+        issuerKnown: Boolean(authIssuer),
+    });
+    const boule = planBoule(org, byKey, claimed, recordedIds, authIssuer, options.otherSlugs ?? [], options.archonUrl ?? null, platformReadiness, {
+        ...bouleCredentials.wants,
+        ...(customerGrantsShape ? { customerGrants: true } : {}),
+        ...(registrar.deliver ? { registrar: true } : {}),
+        ...(registrar.keepBouleEnv ? { registrarKept: true } : {}),
+    }, customerGrantsShape);
     if (boule.step)
         plannedSteps.push(boule.step);
-    // Boule's and Agora's blue/green: after their own steps, which make the app it copies.
+    // 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);
+    const kosmosGuarded = guardApp(kosmosClient);
+    if (kosmosGuarded)
+        plannedSteps.push(kosmosGuarded);
+    const kosmos = planKosmos(org, byKey, claimed, recordedIds, authIssuer, options.otherSlugs ?? []);
+    if (kosmos.step)
+        plannedSteps.push(kosmos.step);
+    // 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.
     const bouleOwners = planBouleOwners(org, recordedIds, (byKey.get(resourceKey('coolify', 'boule', org.id))?.config.env ?? null));
@@ -598,11 +739,26 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // the same dependency `planEntryAiKeys`/`planFilesKeys` have.
     const entryEdgeKeys = planEntryEdgeKeys(org, recordedIds, plannedSteps, platformReadiness, (options.now ?? Date.now)());
     plannedSteps.push(...entryEdgeKeys.steps);
+    // F7: the signed-records registrar key, after Boule like the edge key.
+    const keysRegistrar = planKeysRegistrar(org, recordedIds, plannedSteps, { ...(options.keysRegistrarUrl !== undefined ? { url: options.keysRegistrarUrl } : {}) }, (options.now ?? Date.now)());
+    plannedSteps.push(...keysRegistrar.steps);
+    // A company on shared services registers on the scheduler the host supplies (the owner company's); a company
+    // that runs its own services never does, only on its own.
+    const schedulerUsable = (jobsAvailable && !ownsServices(org)) || platformReadiness.jobsReady;
+    // 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);
+    // 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);
     // Boule's own broker entry, after its app: the entry needs the AUTH_APP_KEY
     // that step puts in the app's env.
     const bouleBroker = planBouleBrokerEntry(org, recordedIds, plannedSteps, options.broker ?? false);
     if (bouleBroker.step)
         plannedSteps.push(bouleBroker.step);
+    // The company's registrar record in the broker, after Boule's own broker entry.
+    if (registrar.step)
+        plannedSteps.push(registrar.step);
     // #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, {
@@ -622,12 +778,20 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     });
     if (ownJobs.step)
         plannedSteps.push(ownJobs.step);
+    const ownJobsRoute = planOwnJobsRoute({
+        org,
+        recordedIds,
+        readiness: platformReadiness,
+        ownServices: options.ownServices ?? false,
+        zoneActive: ownZoneActive,
+        schedulerPlanned: ownJobs.step !== null,
+    });
+    if (ownJobsRoute.step)
+        plannedSteps.push(ownJobsRoute.step);
     // #173: register the org's own app with the platform's jobs scheduler.
     // After Agora, so a failing registration can never stop Agora from
     // provisioning (`runSteps` stops at the first failing step).
-    const jobsRegistration = planJobsRegistration(org, recordedIds, 
-    // An own org never registers with the shared scheduler the host supplies.
-    (jobsAvailable && !ownsServices(org)) || platformReadiness.jobsReady, platformReadiness.missingKeys.jobs, platformReadiness.noKeyReader, platformReadiness.jobsUrlMissing ?? false);
+    const jobsRegistration = planJobsRegistration(org, recordedIds, schedulerUsable, platformReadiness.missingKeys.jobs, platformReadiness.noKeyReader, platformReadiness.jobsUrlMissing ?? false);
     if (jobsRegistration.step)
         plannedSteps.push(jobsRegistration.step);
     const remoteDatabase = planRemoteDatabase(org, options.remoteDatabase, recordedIds);
@@ -660,7 +824,8 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     }
     // ADR 0002: Worker apps, after the Workers for the same reason: a route, record
     // or script name that is not ours throws at apply and `runSteps` stops there.
-    const workerApps = planWorkerApps(org, recordedIds, {
+    const workerOrg = withWorkspaceWorkers(org, declaredOrg);
+    const workerApps = planWorkerApps(workerOrg, recordedIds, {
         available: options.workerApps ?? false,
         ...(options.workerAppKeysUrl !== undefined ? { keysUrl: options.workerAppKeysUrl } : {}),
         ...(options.workerAppRegistryAccountId !== undefined
@@ -683,7 +848,10 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     });
     for (const step of workerApps.steps) {
         const stepEntry = step.action.key.slice(org.id.length + 1);
-        const ownZone = org.hosting.usesDomain && Boolean(org.domain);
+        // A workspace Worker lives in the platform's apps zone, not the org's own.
+        const wsEntry = workerOrg.hosting.entries.find((e) => e.key === stepEntry);
+        const wsParent = wsEntry ? workspaceWorkerParent(wsEntry) : null;
+        const ownZone = wsParent === null && org.hosting.usesDomain && Boolean(org.domain);
         const apply = step.action.desired.mode === 'apply';
         // Retire never looks a zone up; a deploy needs the org's zone, or the shared oikos.host zone.
         const hasDatabase = Boolean(org.hosting.entries.find((e) => e.key === stepEntry)?.workerApp?.database);
@@ -691,10 +859,16 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
             ? null
             : hasDatabase
                 ? edgeNeeded(platformReadiness, ['zones', 'dns', 'access', 'tunnels'])
-                : ownZone
+                : ownZone || wsParent !== null
                     ? edgeNeeded(platformReadiness, ['zones', 'dns'])
                     : edgeNeeded(platformReadiness, ['zones']);
-        if (reason) {
+        if (apply && wsParent !== null && !workspaceGateReady(workspaceGateKey(wsParent))) {
+            appBlocked.push({
+                description: `${org.slug}'s ${wsParent} workspace Worker is blocked, not planned: its Access gate is not recorded or planned yet`,
+                key: step.action.key,
+            });
+        }
+        else if (reason) {
             dnsBlocked.push(edgeBlockedItem(org, `${stepEntry} Worker app`, step.action.key, reason));
         }
         else if (apply && ownZone && zoneWaiting) {
@@ -703,7 +877,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
                 key: step.action.key,
             });
         }
-        else if (apply && !ownZone && !(options.oikosZoneReady ?? false)) {
+        else if (apply && wsParent === null && !ownZone && !(options.oikosZoneReady ?? false)) {
             zoneBlocked.push({
                 description: `${org.slug}'s ${stepEntry} Worker app is blocked, not planned: the shared oikos.host zone is not ready yet`,
                 key: step.action.key,
@@ -713,11 +887,14 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
             plannedSteps.push(step);
         }
     }
+    // `uses.audit`: registers the entry's ledger for platform sealing, after its Worker app.
+    const entryAudit = planEntryAudit(org, recordedIds, plannedSteps, platformReadiness);
+    plannedSteps.push(...entryAudit.steps);
     // Last: a repair that fails must not stop any step after it (`runSteps` stops at the first failure).
     const idTokenUserinfo = planIdTokenUserinfo(org, live, recordedIds, plannedSteps, platformReadiness.authReady, options.zitadelIdTokenUserinfo ?? false);
     if (idTokenUserinfo)
         plannedSteps.push(idTokenUserinfo);
-    const postLogoutUris = planPostLogoutUris(org, live, recordedIds, plannedSteps, platformReadiness.authReady, options.zitadelPostLogoutUris ?? false);
+    const postLogoutUris = planPostLogoutUris(declaredOrg, live, recordedIds, plannedSteps, platformReadiness.authReady, options.zitadelPostLogoutUris ?? false);
     if (postLogoutUris)
         plannedSteps.push(postLogoutUris);
     const desktopCallbacks = planDesktopCallbacks(org, live, recordedIds, plannedSteps, platformReadiness.authReady, options.zitadelRedirectUris ?? false);
@@ -725,6 +902,24 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         plannedSteps.push(desktopCallbacks);
     // #444, last: a Postgres step that fails must not stop the zone, mail, app, Agora and Boule steps of a live company.
     plannedSteps.push(...orgPostgresSteps);
+    // F4 (#925): with apps on, the apps admin role on that server and the route Hyperdrive reaches it by.
+    const appsAdmin = planAppsAdmin(org, recordedIds, plannedSteps, {
+        canHoldSecrets: platformReadiness.canHoldSecrets === true,
+        postgresPlanned: orgPostgresSteps.some((p) => p.action.system === 'coolify' && p.action.kind === 'org-postgres'),
+    });
+    plannedSteps.push(...appsAdmin.steps);
+    const appsDbRoute = planAppsDbRoute(org, recordedIds, plannedSteps, {
+        accessReady: edgeNeeded(platformReadiness, ['access', 'tunnels', 'dns', 'zones']) === null,
+        canHoldSecrets: platformReadiness.canHoldSecrets === true,
+        tunnelReady: Boolean(recordedIds[`cloudflare:tunnel:${org.id}`]) ||
+            plannedSteps.some((s) => s.action.system === 'cloudflare' && s.action.kind === 'tunnel'),
+    });
+    plannedSteps.push(...appsDbRoute.steps);
+    // FZ: the company slug and the zone ids, in the same Boule env.
+    const appsZones = planAppsZones(org, recordedIds, plannedSteps, {
+        zonesReady: edgeNeeded(platformReadiness, ['zones']) === null,
+    });
+    plannedSteps.push(...appsZones.steps);
     // After the org-postgres steps: the desktop sign-in service lives on a home they may create in this same plan.
     if (desktopAuth.step)
         plannedSteps.push(desktopAuth.step);
@@ -742,7 +937,12 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         for (const id of platformReadiness.platformZitadelIds ?? [])
             recordedValues.add(id);
     }
-    const platformNames = new Set([...(options.platformHostnames ?? []), platformReadiness.mailHost?.mailHost ?? ''].map((h) => h.toLowerCase()));
+    const platformNames = new Set([
+        ...(options.platformHostnames ?? []),
+        platformReadiness.mailHost?.mailHost ?? '',
+        // The shared mail relay's MX host, which the platform's relay step writes.
+        platformReadiness.platformApex ? platformMailMxHost(platformReadiness.platformApex) : '',
+    ].map((h) => h.toLowerCase()));
     platformNames.delete('');
     const unmanaged = live
         .filter((r) => !claimed.has(resourceKey(r.system, r.kind, r.key)))
@@ -778,14 +978,23 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     for (const description of bouleCredentials.blocked) {
         unmanaged.push({ description, key: 'coolify:boule:credentials' });
     }
+    customerGrantsNotes.forEach((description, index) => {
+        unmanaged.push({ description, key: `coolify:boule:customer-grants:${index}` });
+    });
+    registrar.blocked.forEach((description, index) => {
+        unmanaged.push({ description, key: `coolify:broker-registrar:${index}` });
+    });
     if (boule.mailBlocked) {
         unmanaged.push({ description: boule.mailBlocked, key: 'coolify:boule:mail' });
     }
+    if (kosmos.blocked)
+        unmanaged.push({ description: kosmos.blocked, key: 'coolify:kosmos' });
     // Same for an ai key minted but never delivered: planning a new mint would
     // orphan a second live key.
     if (aiKey.blocked)
         unmanaged.push({ description: aiKey.blocked, key: 'ai:key' });
     unmanaged.push(...blueGreen.unmanaged);
+    unmanaged.push(...workspaces.unmanaged);
     unmanaged.push(...filesKeys.blocked);
     unmanaged.push(...entryAiKeys.blocked);
     unmanaged.push(...edgeWorkers.blocked);
@@ -798,7 +1007,15 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     }
     unmanaged.push(...mcp.blocked);
     unmanaged.push(...customers.blocked);
+    unmanaged.push(...testCustomers.blocked);
     unmanaged.push(...entryEdgeKeys.blocked);
+    unmanaged.push(...keysRegistrar.blocked);
+    unmanaged.push(...appsAdmin.blocked);
+    unmanaged.push(...appsDbRoute.blocked);
+    unmanaged.push(...appsZones.blocked);
+    unmanaged.push(...entryJobs.blocked);
+    unmanaged.push(...entryAudit.blocked);
+    unmanaged.push(...entryRepoKeys.blocked);
     unmanaged.push(...edgeReservedLabels.blocked);
     if (ownAuth.blocked)
         unmanaged.push({ description: ownAuth.blocked, key: OWN_AUTH_BLOCKED_KEY });
@@ -807,6 +1024,9 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     }
     if (ownJobs.blocked)
         unmanaged.push({ description: ownJobs.blocked, key: OWN_JOBS_BLOCKED_KEY });
+    if (ownJobsRoute.blocked) {
+        unmanaged.push({ description: ownJobsRoute.blocked, key: OWN_JOBS_ROUTE_BLOCKED_KEY });
+    }
     if (ownMail.blocked)
         unmanaged.push({ description: ownMail.blocked, key: OWN_MAIL_BLOCKED_KEY });
     if (ownSfu.blocked)
@@ -895,8 +1115,10 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         });
     }
     // #243: an appEnv source nothing will record is reported, not silently skipped.
+    unmanaged.push(...githubSource.blocked);
     unmanaged.push(...app.blocked);
     unmanaged.push(...brokerEntries.blocked);
+    unmanaged.push(...workspaceBrokerEntries.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);
@@ -940,6 +1162,7 @@ const NEEDS_OWN_ZITADEL = new Set([
     'zitadel:owner',
     'zitadel:app',
     'zitadel:customers',
+    'zitadel:customers-test',
     'zitadel:id-token-userinfo',
     'zitadel:desktop-callback',
     'zitadel:login-host',
@@ -947,7 +1170,10 @@ const NEEDS_OWN_ZITADEL = new Set([
     'coolify:calls-service',
     'coolify:calls-chat',
     'coolify:broker-entry',
+    'coolify:workspace-broker-entry',
+    'coolify:workspaces-database',
     'coolify:boule-broker-entry',
+    'coolify:broker-registrar',
     'files:organisation',
 ]);
 /**
@@ -1555,8 +1781,8 @@ function loginHostWaiting(org, host, recordedIds, bindingsWired, issuerPlanned)
  * actually need it -- CMS's, chat's and calls' entries follow their own
  * on/off switch, the same ones this file already gates their own
  * `coolify:*` steps on (`org.ts`'s `SiteConfig.enabled`, `ChatConfig.enabled`,
- * `CallsConfig.enabled`); Boule's is unconditional, matching `org.ts`'s own
- * "every org gets one" rule; the app schema follows whether any
+ * `CallsConfig.enabled`); kosmos follows its own switch too (`KosmosApp.enabled`, foundry#949); Boule's is
+ * unconditional, matching `org.ts`'s own "every org gets one" rule; the app schema follows whether any
  * `hosting.entries` entry declares `database: true` (`coolifyDatabase`'s own
  * gate) rather than `hosting.enabled` alone, since a hosting org with no
  * database-bearing entry has nothing for this schema to hold.
@@ -1564,6 +1790,8 @@ function loginHostWaiting(org, host, recordedIds, bindingsWired, issuerPlanned)
 function orgServiceSchemaEnabled(org, schema) {
     if (schema.schema === 'cms')
         return org.site.enabled;
+    if (schema.schema === 'kosmos')
+        return kosmosOn(org);
     if (schema.schema.startsWith('chat_'))
         return org.chat.enabled;
     if (schema.schema.startsWith('calls_'))
@@ -1983,75 +2211,47 @@ function planChat(org, byKey, claimed, recordedIds, reading, issuerPlanned) {
  * matrix-authentication-service, entirely separate from chat's
  * (`plan/calls-matrix.ts`'s own top doc comment: a call guest must never gain
  * chat membership). Unlike chat, off by default: `org.ts`'s
- * `CallsConfig.enabled` doc comment. Same on/off, park-not-delete shape as
- * {@link planApp}/{@link planDatabase}/{@link planTunnel} below
- * (`planHostingToggle`, #7 corrections 1) -- turning it off parks Synapse and
- * MAS, never either database (`executor.ts`'s `coolifyCalls`).
+ * `CallsConfig.enabled` doc comment.
  *
- * #177: a first-ever provision (no live resource yet) is blocked, not
- * planned, while `platformReadiness.callsReady` is false -- an org's own
- * Matrix stack is wired to the shared calls SFU (#122/#127), so there is
- * nothing for it to authenticate calls against until the platform's own
- * `sfu:livekit` step is declared. Parking, and an already-provisioned stack,
- * are unaffected.
+ * #430: calls run transit-only now (calls#93's `CALLS_ENCRYPTION=transit`),
+ * so the calls service no longer talks to a per-org Matrix stack and this
+ * never provisions a new one, nor re-provisions a parked one -- the live
+ * resource is still claimed, so it is never reported unmanaged. An org
+ * whose stack is already live and enabled is left exactly as it is;
+ * removing it is a separate, human-confirmed step. Turning `calls.enabled`
+ * off still parks an already-live stack unchanged (`executor.ts`'s
+ * `coolifyCalls`, #7 corrections 1): data is retained, not deleted.
  */
-function planCalls(org, byKey, claimed, callsReady, synapseTag) {
+function planCalls(org, byKey, claimed) {
     const key = resourceKey('coolify', 'calls', org.id);
-    if (org.calls.enabled && !byKey.get(key) && !callsReady) {
-        return {
-            step: null,
-            blocked: ownsServices(org)
-                ? `${org.slug}'s calls Matrix stack is blocked, not planned: its own media server (coolify:own-sfu) is not applied yet`
-                : `${org.slug}'s calls Matrix stack is blocked, not planned: the platform owner's calls SFU (the platform's) is off`,
-        };
-    }
-    // #248: the two images this stack's own apply would run, checked the same
-    // way the platform's SFU checks LiveKit/cloudflared and ZITADEL checks its
-    // own tag -- a re-apply of the same declaration must not silently run a
-    // different version with no diff shown anywhere.
-    if (org.calls.enabled && !byKey.get(key)) {
-        const synapseBlocked = floatingTagBlocked('Synapse', synapseTag ?? VERSIONS.synapse, 'v1.161.0');
-        if (synapseBlocked) {
-            return {
-                step: null,
-                blocked: `${org.slug}'s calls Matrix stack is blocked, not planned: ${synapseBlocked}`,
-            };
-        }
-        const masBlocked = floatingTagBlocked('matrix-authentication-service', VERSIONS.mas, '1.24.0');
-        if (masBlocked) {
-            return {
-                step: null,
-                blocked: `${org.slug}'s calls Matrix stack is blocked, not planned: ${masBlocked}`,
-            };
-        }
-    }
+    const live = byKey.get(key);
+    if (live)
+        claimed.add(key);
+    const liveEnabled = live !== undefined && live.config.enabled !== false;
+    if (org.calls.enabled && !liveEnabled)
+        return { step: null, blocked: null };
     const toggle = planHostingToggle('coolify', 'calls', org.calls.enabled, org, byKey, claimed, () => `provision ${org.slug}'s calls Matrix stack (Synapse + matrix-authentication-service)`, () => `park ${org.slug}'s calls Matrix stack (stops serving; data is retained, not deleted -- #7 corrections 1)`);
-    // A held Synapse tag rides in the provisioning step; a parking step carries none.
-    if (toggle && synapseTag && toggle.action.desired.enabled === true) {
-        toggle.action.desired = { ...toggle.action.desired, synapseTag };
-    }
     return { step: toggle, blocked: null };
 }
 /**
  * The org's own calls service (#145, part 2 of #128) -- `wtfalch/calls`'s
- * `packages/service`, deployed alongside the calls Matrix stack {@link planCalls}
- * provisions and wired to it and to the shared LiveKit SFU (foundry#122/#127).
- * Gated on the same `org.calls.enabled` flag as the Matrix stack, not a flag
- * of its own: a calls service with no Matrix stack behind it has nothing to
- * authenticate a guest against, and a Matrix stack alone answers no browser,
- * so the two are declared as one on/off switch even though they are two
- * planner steps. Same on/off, park-not-delete shape as {@link planCalls}
- * (`planHostingToggle`, #7 corrections 1) -- turning it off parks the app,
- * never its database (`executor.ts`'s `coolifyCallsService`).
+ * `packages/service`, wired to the shared LiveKit SFU (foundry#122/#127).
+ * Same on/off shape as {@link planCalls} (`planHostingToggle`, #7
+ * corrections 1) -- turning it off parks the app, never its database
+ * (`executor.ts`'s `coolifyCallsService`).
  *
- * #177: silently plans nothing (no second blocked message) while the Matrix
- * stack it rides beside is itself blocked on `callsReady` -- {@link planCalls}
- * already reports the platform's shared SFU as missing once.
+ * #430: calls run transit-only (calls#93), so this no longer rides behind
+ * the Matrix stack {@link planCalls} used to provision -- there is none to
+ * ride behind any more -- and reports the shared SFU as missing itself
+ * (#177) rather than relying on `planCalls`'s now-removed report.
  */
 function planCallsService(org, byKey, claimed, callsReady, recordedIds, callsBlocked, tokenHost) {
     const key = resourceKey('coolify', 'calls-service', org.id);
-    if (org.calls.enabled && !byKey.get(key) && !callsReady) {
-        return { step: null, blocked: null };
+    if (org.calls.enabled && !byKey.get(key) && !callsReady && !ownsServices(org)) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s calls service is blocked, not planned: the platform owner's calls SFU (the platform's) is off`,
+        };
     }
     // An own org's service names its own media server, so it waits for it even when already provisioned.
     if (org.calls.enabled && ownsServices(org) && !callsReady) {
@@ -2867,6 +3067,137 @@ function planBouleClient(org, byKey, claimed) {
         },
     };
 }
+/**
+ * foundry#949: the fixed ZITADEL web client `kosmos`, once the company turns kosmos on. The same shape as
+ * {@link planBouleClient} and {@link planAgoraClient}; `kosmosOn(org)` is false before any client is planned.
+ */
+function planKosmosClient(org, byKey, claimed) {
+    if (!kosmosOn(org))
+        return null;
+    const key = resourceKey('zitadel', 'app', 'kosmos');
+    const live = byKey.get(key);
+    if (live)
+        claimed.add(key);
+    const desired = { appType: 'web' };
+    if (!live) {
+        return {
+            action: { system: 'zitadel', kind: 'app', key: 'kosmos', desired },
+            step: {
+                description: `provision the web ZITADEL app 'kosmos' for ${org.slug}'s kosmos sign-in`,
+                destroys: false,
+                migrates: false,
+            },
+        };
+    }
+    if (live.config.appType === 'web')
+        return null;
+    return {
+        action: {
+            system: 'zitadel',
+            kind: 'app',
+            key: 'kosmos',
+            desired: { ...desired, recreate: true },
+        },
+        step: {
+            description: `recreate ZITADEL app 'kosmos' for ${org.slug} as web (was ${String(live.config.appType)})`,
+            destroys: true,
+            migrates: false,
+        },
+    };
+}
+/**
+ * foundry#949: the org's own kosmos, a per-org singleton keyed by the org id under its own `kosmos` kind, built
+ * from https://github.com/wtfalch/kosmos's root Dockerfile (`executor.ts`'s `coolifyKosmos`), with a database of
+ * its own. Unlike Boule and Agora, kosmos is set up only once the company turns it on (`kosmosOn(org)`); while
+ * it is off, an org that never had it plans nothing, and a live app is parked (stopped, database kept), the
+ * same rule a switched-off service always follows here.
+ *
+ * Once live, a step is planned again whenever the live app's sign-in env lacks a desired key or holds a
+ * different value (`kosmos.ts`'s `desiredKosmosEnv`, the function the executor writes from). The only host
+ * value is the issuer address (the one Agora and Boule sign in at); without it kosmos is blocked, not planned,
+ * so every other step still applies.
+ */
+function planKosmos(org, byKey, claimed, recordedIds, issuer, otherSlugs) {
+    if (!kosmosOn(org)) {
+        // Switched off: park a live app (stop it, keep the database), like CMS and calls. A stopped app is
+        // already parked, so the plan reaches empty.
+        const parked = planHostingToggle('coolify', 'kosmos', false, org, byKey, claimed, () => `provision ${org.slug}'s kosmos`, () => `park ${org.slug}'s kosmos (stops serving; its database is retained, not deleted)`, org.id, (live) => !/^(exited|stopped)/.test(String(live.config.status ?? '')));
+        return { step: parked, blocked: null };
+    }
+    const key = resourceKey('coolify', 'kosmos', org.id);
+    const live = byKey.get(key);
+    if (live)
+        claimed.add(key);
+    // Never truncated: Postgres cuts an identifier at 63 bytes, and a DNS label
+    // over 63 is refused by Coolify and Cloudflare -- the same check `planBoule` makes.
+    const tooLong = [
+        [`${org.slug}-kosmos`, 'the kosmos host label and app name'],
+        [`${org.slug}_kosmos_db_rt`, 'the kosmos database role'],
+    ].filter(([name]) => name.length > 63);
+    if (tooLong.length > 0) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s kosmos is blocked, not planned: ${tooLong.map(([n, what]) => `${what} '${n}' is over 63 characters`).join(', ')}; shorten the slug`,
+        };
+    }
+    if (otherSlugs.includes(`${org.slug}-kosmos`)) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s kosmos is blocked, not planned: another declared org has the slug '${org.slug}-kosmos', which is this kosmos's hostname`,
+        };
+    }
+    if (!issuer) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s kosmos is blocked, not planned: the host supplies no issuer`,
+        };
+    }
+    const action = {
+        system: 'coolify',
+        kind: 'kosmos',
+        key: org.id,
+        desired: { issuer },
+    };
+    if (!live) {
+        return {
+            step: {
+                action,
+                step: { description: `provision ${org.slug}'s kosmos`, destroys: false, migrates: false },
+            },
+            blocked: null,
+        };
+    }
+    const liveEnv = (live.config.env ?? {});
+    const { env } = desiredKosmosEnv(org, recordedIds, issuer);
+    const drift = kosmosEnvDrift(env, liveEnv);
+    // Switched back on while the app is still stopped: the step starts it (`coolifyKosmos` starts a stopped app).
+    if (/^(exited|stopped)/.test(String(live.config.status ?? ''))) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `start ${org.slug}'s kosmos again (it was parked)`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked: null,
+        };
+    }
+    if (drift.length === 0)
+        return { step: null, blocked: null };
+    return {
+        step: {
+            action,
+            step: {
+                description: `update ${org.slug}'s kosmos config (${drift.join(', ')} missing or different)`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}
 /**
  * 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
@@ -2919,7 +3250,7 @@ function planBouleCredentials(org, recordedIds, host, canHoldSecrets, nowMs) {
  * address (the one Agora signs in at); without it the Boule is blocked, not
  * planned, so every other step still applies.
  */
-function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonUrl, readiness, credentials) {
+function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonUrl, readiness, credentials, customerGrantsShape = null) {
     const key = resourceKey('coolify', 'boule', org.id);
     const live = byKey.get(key);
     if (live)
@@ -2991,6 +3322,9 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
             platformOwner,
             archonCredential: credentials.archonCredential === true,
             customersDirectory: credentials.customersDirectory === true,
+            // Only an org that declares the flag carries the key, so every other plan is unchanged.
+            ...(credentials.customerGrants === true ? { customerGrants: true } : {}),
+            ...(credentials.registrar === true ? { registrar: true } : {}),
         },
     };
     if (!live) {
@@ -3020,6 +3354,26 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
         if (!drift.includes(key))
             drift.push(key);
     }
+    // F13: the grants entry says what the flagged entries say (credentials by presence only). Taken away only
+    // once no entry declares the flag and foundry wrote it; held credentials of dropped entries are forgotten.
+    if (customerGrantsShape) {
+        if (!customerGrantsShapeMatches(liveEnv[CUSTOMER_GRANTS_ENV], customerGrantsShape)) {
+            drift.push(CUSTOMER_GRANTS_ENV);
+        }
+    }
+    else if (customerGrantsEntries(org).length === 0 &&
+        recordedIds[CUSTOMER_GRANTS_WRITTEN_SCOPE_KEY] &&
+        liveEnv[CUSTOMER_GRANTS_ENV] !== undefined) {
+        drift.push(CUSTOMER_GRANTS_ENV);
+    }
+    if (customerGrantsToDrop(org, recordedIds).length > 0 && !drift.includes(CUSTOMER_GRANTS_ENV)) {
+        drift.push(CUSTOMER_GRANTS_ENV);
+    }
+    // T3: the registrar key by presence and by which mint Boule got; taken away once customers are off.
+    for (const key of bouleRegistrarDrift(org, recordedIds, liveEnv, credentials.registrar === true, credentials.registrarKept === true)) {
+        if (!drift.includes(key))
+            drift.push(key);
+    }
     // The token is compared, never planned with its value.
     if (mailOn &&
         bouleMailTokenDrift(liveEnv[BOULE_MAIL_TOKEN_ENV], live.config.appMailToken)) {
@@ -3191,7 +3545,7 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
     // 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 === mainEntry(org.hosting)?.key) {
+    if (entryKey === mainEntry(org.hosting)?.key || entry?.uses?.mail) {
         const mailDomain = recordedIds[MAIL_DOMAIN_SCOPE_KEY];
         const platformApex = readiness.platformApex;
         const platformLettermintProjectId = readiness.platformLettermintProjectId;
@@ -3519,11 +3873,53 @@ function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer, re
         if (org.hosting.entries.some((e) => e.key === key && e.workerApp))
             continue;
         const app = planApp(org, key, byKey, claimed, recordedIds, plannedSteps, authIssuer, readiness);
+        // An app built from the company's own account is created through its GitHub source: with no source
+        // recorded or planned, a new app waits (blocked, not planned) instead of failing at create.
+        const sourceEntry = org.hosting.entries.find((e) => e.key === key);
+        if (app.step &&
+            app.step.action.desired.enabled !== false &&
+            sourceEntry &&
+            companyGithubFor(org.hosting, sourceEntry.repo) &&
+            !recordedIds[githubSourceResourceKey(org.id)] &&
+            !recordedIds[`coolify:app:${appStepKey(org, key)}`] &&
+            !plannedSteps.some((p) => p.action.system === 'coolify' && p.action.kind === 'github-source')) {
+            blocked.push({
+                description: `${org.slug}'s app for entry '${key}' is blocked, not planned: it is built from the company's GitHub account and its GitHub source is not made yet`,
+                key: 'github-source',
+            });
+            blocked.push(...app.blocked);
+            continue;
+        }
+        // The entry's workspaces key is made and held by this step; a store that cannot put leaves the step failing every run.
+        if (app.step &&
+            app.step.action.desired.enabled !== false &&
+            org.hosting.entries.some((e) => e.key === key && e.uses?.auth?.workspaces) &&
+            readiness.canHoldSecrets !== true) {
+            blocked.push({
+                description: `${org.slug}'s app for entry '${key}' is blocked, not planned: its workspaces key needs a held-key store that can put, and the host has none`,
+                key: `coolify:app:${key}:workspaces-key`,
+            });
+            blocked.push(...app.blocked);
+            continue;
+        }
+        // The entry's customer-grants credential is made and held by this step; a store that cannot put leaves it failing every run.
+        if (app.step &&
+            app.step.action.desired.enabled !== false &&
+            org.hosting.entries.some((e) => e.key === key && e.uses?.customerGrants) &&
+            readiness.canHoldSecrets !== true) {
+            blocked.push({
+                description: `${org.slug}'s app for entry '${key}' is blocked, not planned: its customer grants credential needs a held-key store that can put, and the host has none`,
+                key: `coolify:app:${key}:customer-grants`,
+            });
+            blocked.push(...app.blocked);
+            continue;
+        }
         // The executor pushes the issuer the plan read, the way Agora gets its host values.
         // The same availability the plan's marker used: the executor records its
         // marker from this, never from its own port, so the two cannot disagree.
         const usesSecrets = org.hosting.entries.some((e) => e.key === key &&
-            Object.values(e.env).some((v) => typeof v !== 'string' && (v.from === 'sharedSecret' || v.from === 'heldSecret')));
+            (e.uses?.customerGrants === true ||
+                Object.values(e.env).some((v) => typeof v !== 'string' && (v.from === 'sharedSecret' || v.from === 'heldSecret'))));
         if (usesSecrets && app.step && app.step.action.desired.enabled !== false) {
             const entry = org.hosting.entries.find((e) => e.key === key);
             app.step.action.desired = {
@@ -3538,15 +3934,16 @@ 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 `isMainEntry(entry)` gate). Unlike
+        // #491: only the `app` entry's step and an entry with `uses.mail` run
+        // `ensureAppLettermintMail` (`executor.ts`'s own 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 === mainKey && app.step && app.step.action.desired.enabled !== false) {
+        const sendsMail = key === mainKey || org.hosting.entries.some((e) => e.key === key && e.uses?.mail);
+        if (sendsMail && app.step && app.step.action.desired.enabled !== false) {
             app.step.action.desired = {
                 ...app.step.action.desired,
                 platformApex: readiness.platformApex,
@@ -3558,17 +3955,53 @@ function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer, re
         // edge: blocked, not planned, while edge is not applied.
         const appReason = edgeNeeded(readiness, ['zones', 'dns']);
         if (appReason &&
-            key === mainKey &&
+            sendsMail &&
             app.step &&
             app.step.action.desired.enabled !== false &&
             recordedIds[MAIL_DOMAIN_SCOPE_KEY]) {
-            blocked.push(edgeBlockedItem(org, 'app', 'coolify:app', appReason));
+            blocked.push(edgeBlockedItem(org, key === mainKey ? 'app' : `${key} app`, key === mainKey ? 'coolify:app' : `coolify:app:${key}`, appReason));
             blocked.push(...app.blocked);
             continue;
         }
+        // A workspace entry's live app is made from the commit its workspace runs: none is made before one is known.
+        const goLive = org.hosting.entries.find((e) => e.key === key && e.workspace !== undefined && e.workerApp === undefined);
+        if (goLive &&
+            app.step &&
+            app.step.action.desired.enabled !== false &&
+            !recordedIds[`coolify:app:${appStepKey(org, key)}`]) {
+            const commit = goLive.liveCommit ?? recordedIds[wsKey.commit(key)];
+            if (!commit) {
+                blocked.push({
+                    description: `${org.slug}'s app for entry '${key}' is blocked, not planned: its workspace has not deployed a commit yet, and the live app is made from that commit`,
+                    key: `workspace:${key}:golive`,
+                });
+                blocked.push(...app.blocked);
+                continue;
+            }
+            app.step.action.desired = { ...app.step.action.desired, workspaceCommit: commit };
+            app.step.step.description = `${app.step.step.description} from the commit its workspace runs (${commit.slice(0, 12)})`;
+        }
         if (app.step)
             steps.push(app.step);
         blocked.push(...app.blocked);
+        // A promote: the live app exists and runs another commit than the entry's `liveCommit`.
+        if (goLive?.liveCommit !== undefined &&
+            recordedIds[`coolify:app:${appStepKey(org, key)}`] &&
+            recordedIds[wsKey.liveCommit(key)] !== goLive.liveCommit) {
+            steps.push({
+                action: {
+                    system: 'coolify',
+                    kind: 'promote',
+                    key: appStepKey(org, key),
+                    desired: { entry: key, commit: goLive.liveCommit },
+                },
+                step: {
+                    description: `put ${org.slug}'s live app for entry '${key}' on commit ${goLive.liveCommit.slice(0, 12)} and deploy it`,
+                    destroys: false,
+                    migrates: false,
+                },
+            });
+        }
     }
     return { steps, blocked };
 }
@@ -3713,6 +4146,8 @@ function planTunnel(org, byKey, claimed, recordedIds, platformApex) {
         (org.site.enabled && Boolean(org.domain)) ||
         (org.calls.enabled && org.calls.usesDomain && Boolean(org.domain)) ||
         Boolean(org.domain) ||
+        // F4 (#925): apps on, the tunnel carries the route to the company's Postgres server for Hyperdrive.
+        appsOn(org) ||
         // A company without a domain still gets a tunnel of its own for an entry at `<slug>.oikos.host`.
         entryRoutes(org, recordedIds).length > 0;
     const toggled = planHostingToggle('cloudflare', 'tunnel', desired, org, byKey, claimed, () => `provision a Cloudflare tunnel for ${org.slug}'s app`, () => `park ${org.slug}'s Cloudflare tunnel (configuration is retained, not deleted -- #7 corrections 1)`, org.id, 
@@ -3764,10 +4199,13 @@ function planTunnel(org, byKey, claimed, recordedIds, platformApex) {
             sortedNames(tunnelDnsHostnames(org, org.domain, loginHost));
     // The entry names in the platform's oikos.host zone are recorded apart from the company's own zone.
     const oikosStale = (recordedIds[CLOUDFLARE_TUNNEL_OIKOS_HOSTNAMES_SCOPE_KEY] ?? '') !==
-        entryOikosHostnames(org).join(',');
+        entryOikosHostnames(org, recordedIds).join(',');
+    const appsStale = (recordedIds[CLOUDFLARE_TUNNEL_APPS_HOSTNAMES_SCOPE_KEY] ?? '') !==
+        entryAppsHostnames(org, recordedIds).join(',');
     const dnsStale = (org.domain !== null && recordedIds[CLOUDFLARE_TUNNEL_DNS_DOMAIN_SCOPE_KEY] !== org.domain) ||
         edgeChanged ||
-        oikosStale;
+        oikosStale ||
+        appsStale;
     // An entry's hostname goes straight to its container, so a changed port, key or name, or an ingress
     // written before entries were routed that way, needs the ingress written again. Nothing recorded
     // equals no routes.
@@ -3962,7 +4400,7 @@ function planEntryClients(org, byKey, claimed) {
  * record blocks it (rule 2). A foreign broker entry the last write found
  * invalid is listed as a warning: the broker drops it, foundry keeps it.
  */
-export function planBrokerEntries(org, recordedIds, plannedSteps, brokerWired) {
+export function planBrokerEntries(org, recordedIds, plannedSteps, brokerWired, brokerWorkspacesDatabase) {
     const steps = [];
     const blocked = [];
     for (const entry of org.hosting.entries) {
@@ -3985,6 +4423,14 @@ export function planBrokerEntries(org, recordedIds, plannedSteps, brokerWired) {
             });
             continue;
         }
+        // The broker does not start once an entry declares workspaces without its database, and then no one signs in.
+        if (auth.workspaces && !brokerWorkspacesDatabase) {
+            blocked.push({
+                description: `${at} is blocked, not planned: the broker has no ${BROKER_WORKSPACES_DATABASE_ENV}; hold the connection string of its workspaces database at ${workspacesDatabaseRef(org)}, then apply again`,
+                key,
+            });
+            continue;
+        }
         // Auth ADR 0002: a broker given an `mcp` entry before it holds its database and secret exits at boot.
         // A company's own sign-in step sets them and records it; a shared org's broker is the platform's, whose
         // marker this plan cannot see, so `writeBrokerEntry` refuses there until the platform step has run.
@@ -4205,10 +4651,12 @@ const signInMetadataBlocked = (org) => ({
  * gates (`planGates`) come first. Under a `'*'` gate, a bypass on each name
  * foundry owns comes before them, so no owned name is ever gated.
  */
-function planAccess(org, recordedIds, providerId, platformHostnames) {
-    const { steps: gates, blocked } = planGates(org, recordedIds, providerId);
+function planAccess(org, recordedIds, providerId, platformHostnames, declaredOrg = org) {
+    const { steps: gates, blocked } = planGates(org, recordedIds, providerId, declaredOrg);
+    // F11: a machine path of a gated entry is let through its gate, and a removed one is closed again.
+    const machine = planMachineBypasses(org, recordedIds, declaredOrg);
     if (!org.hosting.enabled)
-        return { steps: gates, blocked };
+        return { steps: [...gates, ...machine.steps], blocked, notes: machine.notes };
     const owned = (hasWildcardGate(org) ? [...lockedHostnames(org, platformHostnames)].sort() : [])
         .filter((hostname) => !recordedIds[resourceKey('cloudflare', 'access', appStepKey(org, hostname))])
         .map((hostname) => ({
@@ -4239,7 +4687,7 @@ function planAccess(org, recordedIds, providerId, platformHostnames) {
             migrates: false,
         },
     }));
-    return { steps: [...owned, ...gates, ...rules], blocked };
+    return { steps: [...owned, ...gates, ...machine.steps, ...rules], blocked, notes: machine.notes };
 }
 /** The plan description for one `hosting.access` rule, by kind (#246). */
 function accessRuleDescription(org, rule) {