@wtfalch/foundry 0.16.15 → 0.17.0

package/dist/plan/executor.js

@@ -1,19 +1,21 @@
 import { randomBytes } from 'node:crypto';
 import { URL } from 'node:url';
 import { CALLS_SFU_PRIVATE_URL, CALLS_SFU_PUBLIC_URL } from '../calls-sfu.js';
-import { APP_ENTRY_KEY, appEntry, filesCollectionEnvName, ownerMailboxRecorded, ownerMailboxes, } from '../org.js';
-import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_NAME_SCOPE_KEY, CALLS_SERVICE_PORT, CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY, CHAT_SERVICE_URL_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, ZITADEL_MESSAGING_PROJECT_SCOPE_KEY, ZITADEL_ORG_SCOPE_KEY, agoraHostnameFor, callsIntrospectionAppName, callsServiceHasName, callsServiceInternalName, callsTokenEnvMarker, callsTokenEnvMovedMessage, desiredAgoraEnv, entryClientIdScopeKey, } from './agora.js';
+import { APP_ENTRY_KEY, appEntry, filesCollectionEnvName, ownerMailboxRecorded, ownerMailboxes, sharedSecretRef, } from '../org.js';
+import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_NAME_SCOPE_KEY, CALLS_SERVICE_PORT, CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY, CHAT_SERVICE_URL_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, ZITADEL_MESSAGING_PROJECT_SCOPE_KEY, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostnameFor, callsIntrospectionAppName, callsServiceHasName, callsServiceInternalName, callsTokenEnvMarker, callsTokenEnvMovedMessage, desiredAgoraEnv, entryClientIdScopeKey, } from './agora.js';
 import { BOULE_BROKER_ENTRY_KEY, BOULE_CLIENT_ID_SCOPE_KEY, BOULE_DATABASE_SCOPE_KEY, bouleEnvDrift, bouleHostnameFor, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, writeBrokerEntry, } from './broker-entries.js';
 import { MAS_IMAGE, MAS_TAG, SYNAPSE_IMAGE, SYNAPSE_TAG, callsMasConfigYaml, callsServerName, callsSynapseHomeserverYaml, mintCallsMatrixSecrets, parseCallsDbUrl, } from './calls-matrix.js';
 import { CHAT_REPO, CHAT_SERVICE_DOCKERFILE, CHAT_SERVICE_PORT, CHAT_SYNAPSE_DOCKERFILE, CHAT_SYNAPSE_PORT, chatInternalNames, chatMasConfigYaml, chatServiceEnvs, chatSynapseHomeserverYaml, chatUpstreams, } from './chat-matrix.js';
 import { ensureCloudflaredConnector } from './cloudflared-connector.js';
+import { CORE_FILES_COLLECTION_NAME, FILES_CORE_COLLECTION_SCOPE_KEY, ZITADEL_FILES_PROJECT_SCOPE_KEY, } from './core-files.js';
 import { AI_ENTRY_RENEW_WINDOW_DAYS, entryAiAppliedScopeKey, entryAiClampedScopeKey, entryAiExpiresScopeKey, entryAiPendingExpiresScopeKey, entryAiRetiredScopeKey, entryAiUndeliveredScopeKey, entryAiUnrevokedScopeKey, entryAiWebhookPendingScopeKey, entryAiWrittenScopeKey, parseIdList, } from './entry-ai-key.js';
 import { FILES_AGORA_KEY_SCOPE_KEY, FILES_AGORA_UNDELIVERED_SCOPE_KEY, FILES_KEY_DAYS, FILES_KEY_RENEW_WINDOW_DAYS, FILES_ORG_OWNER_SCOPE_KEY, FILES_ROOT_EXPIRES_SCOPE_KEY, FILES_ROOT_PREVIOUS_SCOPE_KEY, FILES_ROOT_UNDELIVERED_SCOPE_KEY, FILES_ROOT_UNREVOKED_SCOPE_KEY, entryFilesAppliedScopeKey, entryFilesExpiresScopeKey, entryFilesMinterScopeKey, entryFilesPendingExpiresScopeKey, entryFilesRetiredScopeKey, entryFilesUndeliveredScopeKey, entryFilesUnrevokedScopeKey, entryFilesWrittenScopeKey, filesOwnerUserId, parseIdList as parseFilesIdList, } from './entry-files-key.js';
 import { appHostname, coolifyDomains, entryHostnames, tunnelDnsHostnames, tunnelIngressHostnames, } from './hostnames.js';
 import { LOGIN_BINDING_SCOPE_KEY, LOGIN_HOST_PENDING_REMOVAL_SCOPE_KEY, loginBindingState, loginHostClientIds, pendingRemovalHosts, pendingRemovalState, } from './login-host.js';
 import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';
 import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, appDomainsAppliedScopeKey, appEnvAppliedScopeKey, appNameFor, appSettingsAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, } from './platform-diff.js';
+import { PLATFORM_AUTH_BROKER_MAIL_KEY_REF } from './platform-providers.js';
 import { appLabelsAppliedScopeKey, entryLabelHash, entryLabelSpec, entryProxyLabels, sameLabelSets, } from './proxy-labels.js';
 /**
  * #274 fix round 4: bridges `@wtfalch/providers`' real `ZitadelClient.
@@ -209,14 +211,16 @@ const RATE_LIMIT_REQUESTS_PER_PERIOD = 10;
 const DEFAULT_APP_REPO = 'wtfalch/foundry';
 const DEFAULT_APP_DOCKERFILE = '/apps/hestia/Dockerfile';
 /**
- * The one repo `cmsSite` builds both of its apps from
- * (https://github.com/wtfalch/cms) -- the 2026-09-25 decision this campaign
- * implements (`.plans/2026-09-25-org-sites.md`, that repo): foundry never
- * calls a cms admin API for the org's site, it provisions two ordinary
- * Coolify applications from this one repo, told apart by
- * `dockerfile_location`. `CMS_APP_DOCKERFILE` is the repo's own root
- * `Dockerfile` (`apps/host`, single-org mode); `CMS_SITE_APP_DOCKERFILE`
- * is `apps/site`'s own Dockerfile (the reference renderer).
+ * The shared repo `cmsSite` builds its cms admin app from, always, and its
+ * site app from by default (https://github.com/wtfalch/cms) -- the
+ * 2026-09-25 decision this campaign implements
+ * (`.plans/2026-09-25-org-sites.md`, that repo): foundry never calls a cms
+ * admin API for the org's site, it provisions two ordinary Coolify
+ * applications, told apart by `dockerfile_location`. `CMS_APP_DOCKERFILE`
+ * is the repo's own root `Dockerfile` (`apps/host`, single-org mode);
+ * `CMS_SITE_APP_DOCKERFILE` is `apps/site`'s own Dockerfile (the reference
+ * renderer). An org with `site.repo` set (#245) builds its site app from
+ * that repo instead, the sample skin otherwise ships to every org.
  */
 const CMS_REPO = 'wtfalch/cms';
 const CMS_APP_DOCKERFILE = '/Dockerfile';
@@ -276,6 +280,8 @@ const LOG_DIR = '/app/logs';
  */
 const CMS_APP_SCOPE_KEY = 'coolify_cms_app';
 const SITE_APP_SCOPE_KEY = 'coolify_site_app';
+/** #445: the one Coolify server every resource of this org lands on, chosen once and recorded. */
+const COOLIFY_SERVER_SCOPE_KEY = 'coolify_server';
 /**
  * #117: the cms app's own Postgres database (`<org.slug>-cms-db`), found or
  * created inside `cmsSite` the same way `coolifyDatabase` does for the org's
@@ -658,8 +664,6 @@ export class FoundryStepExecutor {
                 return action.key.includes(':')
                     ? this.filesEntryKey(action, org, context)
                     : this.filesRootKey(action, org, context);
-            case 'files:storage':
-                return this.filesStorage(action, org);
             case 'ai:organisation':
                 return this.aiOrganisation(action, org);
             case 'ai:budget':
@@ -861,11 +865,16 @@ export class FoundryStepExecutor {
         if (!zitadelOrgId) {
             throw new Error(`zitadel:owner for ${org.slug}: no ZITADEL org recorded yet -- the issuer must be provisioned first`);
         }
+        // ZITADEL's default invite link (`/ui/v2/login/verify`) 404s; the platform's login app, which
+        // every org's users sign in through on this instance, serves `/verify` at the root.
+        const authIssuer = action.desired.authIssuer;
         const { userId } = await this.ports.zitadel.inviteOrgOwner(zitadelOrgId, {
             givenName: action.desired.givenName,
             familyName: action.desired.familyName,
             email: action.desired.email,
-        });
+        }, authIssuer
+            ? `${authIssuer}/verify?userId={{.UserID}}&code={{.Code}}&organization={{.OrgID}}&invite=true`
+            : undefined);
         // An owner invited after chat was built never reaches `coolifyChat`
         // again, so the role is granted here once the messaging project exists.
         const messagingProjectId = context.recordedIds()[ZITADEL_MESSAGING_PROJECT_SCOPE_KEY];
@@ -977,6 +986,7 @@ export class FoundryStepExecutor {
                 .map((key) => key.slice(ENTRY_CLIENT_ID_SCOPE_PREFIX.length)),
             ...(recorded[CMS_CLIENT_ID_SCOPE_KEY] ? ['cms'] : []),
             ...(recorded[AGORA_CLIENT_ID_SCOPE_KEY] ? ['agora'] : []),
+            ...(recorded[BOULE_CLIENT_ID_SCOPE_KEY] ? ['boule'] : []),
         ].map((name) => recorded[`zitadel:app:${name}`]));
         const projectId = recorded.zitadel_project;
         // No project yet means no apps yet: vacuously safe to decide from (fix
@@ -1250,11 +1260,37 @@ export class FoundryStepExecutor {
         context.recordScopeId('coolify_project', projectUuid);
         return projectUuid;
     }
-    async resolveServer() {
+    /**
+     * #445: one company lands on one Coolify server. The first call for an
+     * org picks a usable, reachable server and records it
+     * ({@link COOLIFY_SERVER_SCOPE_KEY}); every later call -- this apply, or a
+     * later one -- reads that recording back and returns the same server,
+     * regardless of what the pool's order or health looks like by then. A
+     * recorded server that has gone unusable or unreachable is reported
+     * blocked (never silently replaced with a second host, which would split
+     * the org's resources across servers and break their internal container
+     * URLs); a recorded server no longer registered at all is the same.
+     * Deliberately no fallback to `servers[0]` when nothing is usable: an
+     * unusable server picked blind is not a server anyone's resources could
+     * actually be created on.
+     */
+    async resolveServer(org, context) {
         const servers = await this.ports.coolify.listServers();
-        const server = servers.find((s) => s.is_usable && s.is_reachable) ?? servers[0];
+        const recorded = context.recordedIds()[COOLIFY_SERVER_SCOPE_KEY];
+        if (recorded) {
+            const server = servers.find((s) => s.uuid === recorded);
+            if (!server) {
+                throw new Error(`${org.slug}'s recorded Coolify server ${recorded} is no longer registered on this instance`);
+            }
+            if (!(server.is_usable && server.is_reachable)) {
+                throw new Error(`${org.slug}'s recorded Coolify server ${recorded} is not usable/reachable right now; it is not moved to a second server`);
+            }
+            return server;
+        }
+        const server = servers.find((s) => s.is_usable && s.is_reachable);
         if (!server)
             throw new Error('no usable Coolify server is registered on this instance');
+        context.recordScopeId(COOLIFY_SERVER_SCOPE_KEY, server.uuid);
         return server;
     }
     async coolifyApp(action, org, context) {
@@ -1320,7 +1356,7 @@ export class FoundryStepExecutor {
             haveNames = appliedAppDomains(org, context.recordedIds(), entry.key);
         }
         else {
-            const server = await this.resolveServer();
+            const server = await this.resolveServer(org, context);
             const githubApp = await this.ports.coolify.requireGithubApp();
             const created = await this.ports.coolify.createGithubAppApplication({
                 project_uuid: projectUuid,
@@ -1424,7 +1460,13 @@ export class FoundryStepExecutor {
         // The app receives whatever it needs to sign in (gap P2). Unconditional,
         // unlike the database push above: every app has a hostname, and an
         // upsert of the same value on a later apply is a no-op, not a change.
-        const appEnv = await this.pushAppEnv(appId, org, entry, context, action.desired.authIssuer ?? null);
+        const appEnv = await this.pushAppEnv(appId, org, entry, context, action.desired.authIssuer ?? null, 
+        // What the plan decided is available (diff.ts `planApps`), so the marker
+        // recorded below is the one the plan compares against. Absent: none.
+        action.desired.secretSources ?? {
+            platformMailKey: false,
+            sharedSecret: false,
+        });
         // Rule 4 (#239, #243): a container reads its env only at start, so an app
         // that was already there is restarted, once, when its database URLs or its
         // declared appEnv changed.
@@ -1517,7 +1559,7 @@ export class FoundryStepExecutor {
                 dbId = found.uuid;
             }
             else {
-                const server = await this.resolveServer();
+                const server = await this.resolveServer(org, context);
                 const dbName = org.slug.replace(/-/g, '_');
                 const created = await this.ports.coolify.createPostgresDatabase({
                     project_uuid: projectUuid,
@@ -1633,7 +1675,7 @@ export class FoundryStepExecutor {
      * that call runs only once the `app` entry's `database` is declared and
      * provisioned, where this one is unconditional (#239).
      */
-    async pushAppEnv(appId, org, entry, context, authIssuer) {
+    async pushAppEnv(appId, org, entry, context, authIssuer, secretSources) {
         const recorded = context.recordedIds();
         const envs = [
             // Only the `app` entry has a public name; the others are internal.
@@ -1691,14 +1733,44 @@ export class FoundryStepExecutor {
         // minted here; a source with no value yet (its own step has not run,
         // or has not run for this apply) is simply omitted, the same way every
         // other optional entry above is.
-        const appEnv = resolveAppEnv(org, entry, recorded).values;
+        // The secret sources (`sharedSecret`, `platformMailKey`) are filled here
+        // only, straight into `envs`: never recorded, returned or logged.
+        const heldKeys = this.ports.heldKeys;
+        // Availability is the plan's (`secretSources`). If the plan said a key is
+        // held and this port cannot read it, the host wired the two differently:
+        // fail by ref, never push a marker for an env that was not written.
+        let mailKey = null;
+        if (secretSources.platformMailKey) {
+            try {
+                mailKey = (await heldKeys?.resolve(PLATFORM_AUTH_BROKER_MAIL_KEY_REF)) || null;
+            }
+            catch {
+                // reported below, by ref
+            }
+            if (mailKey === null) {
+                throw new Error(`coolify:app for ${org.slug}: the plan found ${PLATFORM_AUTH_BROKER_MAIL_KEY_REF} held but the executor's heldKeys cannot read it`);
+            }
+        }
+        if (secretSources.sharedSecret && typeof heldKeys?.put !== 'function') {
+            throw new Error(`coolify:app for ${org.slug}: the plan found held keys that can put but the executor's heldKeys cannot`);
+        }
+        const resolved = resolveAppEnv(org, entry, recorded, secretSources);
+        const appEnv = resolved.values;
         for (const [key, value] of Object.entries(appEnv))
             envs.push({ key, value });
+        for (const { name, source } of resolved.secrets) {
+            envs.push({
+                key: name,
+                value: source === 'platformMailKey'
+                    ? mailKey
+                    : await this.ensureSharedSecret(org, source.name, recorded),
+            });
+        }
         await this.ports.coolify.bulkUpsertEnvs(appId, envs);
         // `coolifyApp` records `applied` once the restart succeeded, so `planApp`
         // replans this step when the declared map changes (rule 3). Ids and a
         // domain, never a secret.
-        const applied = JSON.stringify(appEnv);
+        const applied = JSON.stringify(resolved.marker);
         // The sign-in values, recorded by `coolifyApp` the same way; the key is
         // never part of them.
         const authApplied = JSON.stringify(authEnv);
@@ -1710,6 +1782,28 @@ export class FoundryStepExecutor {
             authApplied,
         };
     }
+    /**
+     * The org's shared secret `name`: read from the held keys, else generated
+     * and held first, so a crash after the `put` and before the env write
+     * hands the same value out on the next apply. Only called when `put` exists.
+     * An error here names the ref, never a value.
+     */
+    async ensureSharedSecret(org, name, recorded) {
+        const heldKeys = this.ports.heldKeys;
+        const ref = sharedSecretRef(org.id, name);
+        const held = await heldKeys?.resolve(ref);
+        if (held)
+            return held;
+        // Another entry (or this one) already got a value. Generating again would
+        // split them, so a lost value needs a person, not a new mint.
+        const label = `"secret:sharedSecret:${name}"`;
+        if (Object.entries(recorded).some(([key, value]) => key.startsWith('app_env_applied.') && value.includes(label))) {
+            throw new Error(`coolify:app for ${org.slug}: shared secret ${name} was delivered but is no longer held (ref ${ref}); restore the held value, or clear it from every entry's env and applied marker to mint a new one`);
+        }
+        const value = randomBytes(32).toString('base64url');
+        await heldKeys?.put?.(ref, value);
+        return value;
+    }
     /**
      * F5: the app's `AUTH_APP_KEY`, minted once and only when the app has none
      * of at least 32 characters (the broker refuses a shorter one). `null` once
@@ -2097,16 +2191,22 @@ export class FoundryStepExecutor {
         const projectUuid = await this.ensureCoolifyProject(org, context);
         const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
         const site = await this.findOrCreateCmsApp({
+            org,
+            context,
             projectUuid,
             environment,
             name: `${org.slug}-site`,
+            repo: org.site.repo ?? CMS_REPO,
             dockerfileLocation: CMS_SITE_APP_DOCKERFILE,
             domain,
         });
         const cms = await this.findOrCreateCmsApp({
+            org,
+            context,
             projectUuid,
             environment,
             name: `${org.slug}-cms`,
+            repo: CMS_REPO,
             dockerfileLocation: CMS_APP_DOCKERFILE,
             domain: cmsHostnameFor(org),
         });
@@ -2217,7 +2317,7 @@ export class FoundryStepExecutor {
         const found = (await this.ports.coolify.listDatabases()).find((d) => d.name === name && d.environment_id === environment.id);
         if (found)
             return found.uuid;
-        const server = await this.resolveServer();
+        const server = await this.resolveServer(org, context);
         const dbName = name.replace(/-/g, '_');
         const created = await this.ports.coolify.createPostgresDatabase({
             project_uuid: projectUuid,
@@ -2304,6 +2404,10 @@ export class FoundryStepExecutor {
      * `coolifyApp`'s own analogous gap (it never restarted a found-but-stopped
      * app either) has since closed the same way, inline in that method (#130);
      * this method is `cmsSite`'s only caller.
+     *
+     * `repo` (#245) lets the site app build from an org's own skin repo
+     * (`org.site.repo`) instead of the shared `CMS_REPO`; `cmsSite` always
+     * passes `CMS_REPO` for the cms admin app, which is never org-specific.
      */
     async findOrCreateCmsApp(input) {
         const existing = await this.ports.coolify.findApplicationByName(input.name, {
@@ -2316,7 +2420,7 @@ export class FoundryStepExecutor {
             }
             return { appId: existing.uuid, existed: true };
         }
-        const server = await this.resolveServer();
+        const server = await this.resolveServer(input.org, input.context);
         const githubApp = await this.ports.coolify.requireGithubApp();
         const created = await this.ports.coolify.createGithubAppApplication({
             project_uuid: input.projectUuid,
@@ -2324,7 +2428,7 @@ export class FoundryStepExecutor {
             environment_name: input.environment.name,
             environment_uuid: input.environment.uuid,
             github_app_uuid: githubApp.uuid,
-            git_repository: CMS_REPO,
+            git_repository: input.repo,
             git_branch: 'main',
             build_pack: 'dockerfile',
             name: input.name,
@@ -2362,16 +2466,16 @@ export class FoundryStepExecutor {
         }
         const projectUuid = await this.ensureCoolifyProject(org, context);
         const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
-        const server = await this.resolveServer();
+        const server = await this.resolveServer(org, context);
         const names = {
             synapse: `${org.slug}-calls-synapse`,
             mas: `${org.slug}-calls-mas`,
             synapseDb: `${org.slug}-calls-synapse-db`,
             masDb: `${org.slug}-calls-mas-db`,
         };
-        const synapseDbId = await this.ensureCallsDatabase(context, projectUuid, environment, names.synapseDb, 'synapse', CALLS_SYNAPSE_DB_SCOPE_KEY, CALLS_SYNAPSE_DB_INITDB_ARGS);
+        const synapseDbId = await this.ensureCallsDatabase(org, context, projectUuid, environment, names.synapseDb, 'synapse', CALLS_SYNAPSE_DB_SCOPE_KEY, CALLS_SYNAPSE_DB_INITDB_ARGS);
         context.recordScopeId(CALLS_SYNAPSE_DB_SCOPE_KEY, synapseDbId);
-        const masDbId = await this.ensureCallsDatabase(context, projectUuid, environment, names.masDb, 'mas', CALLS_MAS_DB_SCOPE_KEY);
+        const masDbId = await this.ensureCallsDatabase(org, context, projectUuid, environment, names.masDb, 'mas', CALLS_MAS_DB_SCOPE_KEY);
         context.recordScopeId(CALLS_MAS_DB_SCOPE_KEY, masDbId);
         const [synapseDbRow, masDbRow] = await Promise.all([
             getDatabaseStarted(this.ports.coolify, synapseDbId),
@@ -2525,14 +2629,14 @@ export class FoundryStepExecutor {
      * database, whose {@link CALLS_SERVICE_DB_SCOPE_KEY} has no
      * `system:kind:key` slot of its own for the same reason.
      */
-    async ensureCallsDatabase(context, projectUuid, environment, name, postgresDb, scopeKey, postgresInitdbArgs) {
+    async ensureCallsDatabase(org, context, projectUuid, environment, name, postgresDb, scopeKey, postgresInitdbArgs) {
         const existing = context.recordedIds()[scopeKey];
         if (existing)
             return existing;
         const found = (await this.ports.coolify.listDatabases()).find((d) => d.name === name && d.environment_id === environment.id);
         if (found)
             return found.uuid;
-        const server = await this.resolveServer();
+        const server = await this.resolveServer(org, context);
         const created = await this.ports.coolify.createPostgresDatabase({
             project_uuid: projectUuid,
             server_uuid: server.uuid,
@@ -2658,13 +2762,13 @@ export class FoundryStepExecutor {
         await this.ensureChatAdmins(org, zitadelOrgId, project.id, recorded);
         const projectUuid = await this.ensureCoolifyProject(org, context);
         const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
-        const server = await this.resolveServer();
+        const server = await this.resolveServer(org, context);
         const names = chatInternalNames(org.slug);
-        const synapseDbId = await this.ensureCallsDatabase(context, projectUuid, environment, names.synapseDb, 'synapse', CHAT_SYNAPSE_DB_SCOPE_KEY, CALLS_SYNAPSE_DB_INITDB_ARGS);
+        const synapseDbId = await this.ensureCallsDatabase(org, context, projectUuid, environment, names.synapseDb, 'synapse', CHAT_SYNAPSE_DB_SCOPE_KEY, CALLS_SYNAPSE_DB_INITDB_ARGS);
         context.recordScopeId(CHAT_SYNAPSE_DB_SCOPE_KEY, synapseDbId);
-        const masDbId = await this.ensureCallsDatabase(context, projectUuid, environment, names.masDb, 'mas', CHAT_MAS_DB_SCOPE_KEY);
+        const masDbId = await this.ensureCallsDatabase(org, context, projectUuid, environment, names.masDb, 'mas', CHAT_MAS_DB_SCOPE_KEY);
         context.recordScopeId(CHAT_MAS_DB_SCOPE_KEY, masDbId);
-        const serviceDbId = await this.ensureCallsDatabase(context, projectUuid, environment, names.serviceDb, 'chat', CHAT_SERVICE_DB_SCOPE_KEY);
+        const serviceDbId = await this.ensureCallsDatabase(org, context, projectUuid, environment, names.serviceDb, 'chat', CHAT_SERVICE_DB_SCOPE_KEY);
         context.recordScopeId(CHAT_SERVICE_DB_SCOPE_KEY, serviceDbId);
         const [synapseDbRow, masDbRow, serviceDbRow] = await Promise.all([
             getDatabaseStarted(this.ports.coolify, synapseDbId),
@@ -2840,13 +2944,13 @@ export class FoundryStepExecutor {
         const synapseHost = `${org.slug}-calls-synapse`;
         const masHost = `${org.slug}-calls-mas`;
         const dbName = `${name}-db`;
-        const dbId = await this.ensureCallsDatabase(context, projectUuid, environment, dbName, dbName.replace(/-/g, '_'), CALLS_SERVICE_DB_SCOPE_KEY);
+        const dbId = await this.ensureCallsDatabase(org, context, projectUuid, environment, dbName, dbName.replace(/-/g, '_'), CALLS_SERVICE_DB_SCOPE_KEY);
         context.recordScopeId(CALLS_SERVICE_DB_SCOPE_KEY, dbId);
         const db = await getDatabaseStarted(this.ports.coolify, dbId);
         if (!db.internal_db_url) {
             throw new Error(`coolify:calls-service for ${org.slug}: its database has no internal_db_url yet -- retry this apply once Coolify reports one`);
         }
-        const server = await this.resolveServer();
+        const server = await this.resolveServer(org, context);
         const githubApp = await this.ports.coolify.requireGithubApp();
         const app = await this.findOrCreateCallsApp(name, environment.id, () => this.ports.coolify.createGithubAppApplication({
             project_uuid: projectUuid,
@@ -3059,6 +3163,19 @@ export class FoundryStepExecutor {
      * pushed once calls are on and this org's calls service app carries its
      * internal name (`desiredAgoraEnv` reads that marker from the recorded ids,
      * not the host values).
+     *
+     * #442: a found-but-already-running app's container binds env only at
+     * start, so writing it alone leaves that process on its old config --
+     * restarted (never redeployed: no new image, so `restart` is the same
+     * primitive `ensureLogVolume`'s own restart uses) whenever the live env
+     * actually differs, or whenever the last restart this step confirmed
+     * ({@link AGORA_ACTIVATED_ENV_SCOPE_KEY}) is not this exact env (an org
+     * applied before this existed, whose live env already matched desired
+     * with nothing ever confirmed running it). A brand new app has nothing
+     * running yet to restart. The activation marker is recorded last, after
+     * the restart (if any) returns without throwing, so a failed restart
+     * leaves it stale and the next plan replans this step even though
+     * Coolify's own env store already matches desired.
      */
     async coolifyAgora(action, org, context) {
         // The host values the plan read, carried in the step: never read again
@@ -3074,7 +3191,7 @@ export class FoundryStepExecutor {
         const projectUuid = await this.ensureCoolifyProject(org, context);
         const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
         const name = `${org.slug}-agora`;
-        const server = await this.resolveServer();
+        const server = await this.resolveServer(org, context);
         const githubApp = await this.ports.coolify.requireGithubApp();
         const app = await this.findOrCreateCallsApp(name, environment.id, () => this.ports.coolify.createGithubAppApplication({
             project_uuid: projectUuid,
@@ -3091,7 +3208,20 @@ export class FoundryStepExecutor {
         }));
         // Every app foundry deploys keeps its own logs (#75), reused as-is here.
         await this.ensureLogVolume(app.appId, org, app.existed);
+        // #442: read before overwriting -- `bulkUpsertEnvs` below always leaves
+        // Coolify's own env store matching `env`, which is why that store alone
+        // can no longer tell a changed value from one already live.
+        const liveEnv = new Map((await this.ports.coolify.listEnvs(app.appId))
+            .filter((e) => !e.is_preview)
+            .map((e) => [e.key, e.value]));
+        const envChanged = agoraEnvDrift(env, Object.fromEntries(liveEnv)).length > 0;
         await this.ports.coolify.bulkUpsertEnvs(app.appId, Object.entries(env).map(([key, value]) => ({ key, value })));
+        const revision = agoraEnvRevision(env);
+        const alreadyActivated = context.recordedIds()[AGORA_ACTIVATED_ENV_SCOPE_KEY] === revision;
+        if (app.existed && (envChanged || !alreadyActivated)) {
+            await this.ports.coolify.restart(app.appId);
+        }
+        context.recordScopeId(AGORA_ACTIVATED_ENV_SCOPE_KEY, revision);
         return { resourceId: app.appId };
     }
     // ---- boule (#161) --------------------------------------------------------
@@ -3131,9 +3261,9 @@ export class FoundryStepExecutor {
         const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
         const name = `${org.slug}-boule`;
         const dbName = `${org.slug}-boule-db`.replace(/-/g, '_');
-        const dbId = await this.ensureCallsDatabase(context, projectUuid, environment, `${org.slug}-boule-db`, dbName, BOULE_DATABASE_SCOPE_KEY);
+        const dbId = await this.ensureCallsDatabase(org, context, projectUuid, environment, `${org.slug}-boule-db`, dbName, BOULE_DATABASE_SCOPE_KEY);
         context.recordScopeId(BOULE_DATABASE_SCOPE_KEY, dbId);
-        const server = await this.resolveServer();
+        const server = await this.resolveServer(org, context);
         const githubApp = await this.ports.coolify.requireGithubApp();
         const app = await this.findOrCreateCallsApp(name, environment.id, () => this.ports.coolify.createGithubAppApplication({
             project_uuid: projectUuid,
@@ -3345,7 +3475,7 @@ export class FoundryStepExecutor {
             appName: `${org.slug}-cloudflared`,
             projectUuid,
             environment,
-            resolveServer: () => this.resolveServer(),
+            resolveServer: () => this.resolveServer(org, context),
             recordedConnectorAppId: context.recordedIds()[CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY] ?? null,
             recordAppId: async (appId) => {
                 context.recordScopeId(CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY, appId);
@@ -3965,30 +4095,45 @@ export class FoundryStepExecutor {
     }
     // ---- files / ai --------------------------------------------------------
     /**
-     * #80: provisions the org's own organisation on Files, before
-     * {@link filesStorage} can set its spend limit. `provisionOrganisation` is
-     * safely repeatable on its own (`FilesOrganisationPort`'s doc comment), so
-     * this is called every time regardless of whether it already ran --
-     * idempotent by find-or-create, not by checking `recordedIds` first.
+     * #80: provisions the org's own organisation on Files.
+     * `provisionOrganisation` is safely repeatable on its own
+     * (`FilesOrganisationPort`'s doc comment), so this is called every time
+     * regardless of whether it already ran -- idempotent by find-or-create,
+     * not by checking `recordedIds` first.
+     *
+     * F6b: `action.desired.shareHost` (`diff.ts`'s `planFilesOrganisation`) is
+     * passed through every time, even though `entry-files-key.ts` reports the
+     * route itself as blocked until the platform's files host can serve
+     * `share.<domain>` -- this is the one place the name reaches files at all,
+     * so files can act on it the moment its own route exists.
      *
      * #273: also ensures the org's Agora origin is on the files host's CORS
      * allowlist (`FilesOrganisationPort.ensureAllowedOrigin`), the same
      * repeat-is-a-no-op shape as `provisionOrganisation` itself -- every org
      * gets an Agora (#164), so `diff.ts`'s `planFilesOrganisation` always sets
      * `desired.agoraOrigin`.
+     *
+     * #437: the owner member/name, the core ZITADEL files project and the core
+     * collection (`core-files.ts`) are no longer conditioned on a hosting entry
+     * declaring `uses.files` -- the core bundle (Agora's own uploads) needs
+     * all three just as much as a bespoke entry does, and withholding them
+     * until one existed is why a plain Agora/Boule org never got a usable
+     * Files setup at all. Both the project and the collection are idempotent
+     * by name, so a re-run that already created either finds it instead.
      */
     async filesOrganisation(action, org, context) {
         const files = await this.filesPort();
-        // F6b: an org whose entries use files needs an owner member in its files
-        // organisation, which its own key is minted below. Only a new
-        // organisation takes one, so it is passed when the owner is known now.
-        const owner = org.hosting.entries.some((e) => e.uses?.files)
-            ? filesOwnerUserId(org, context.recordedIds())
-            : undefined;
+        const recorded = context.recordedIds();
+        // F6b: an organisation takes an owner member and name only while it is
+        // being created, so it is passed whenever the owner is known now --
+        // every org, not only one with a hosting entry declaring `uses.files`
+        // (#437).
+        const owner = filesOwnerUserId(org, recorded);
         const provisioned = await files.provisionOrganisation({
             organisationId: org.id,
             ceilingBytes: action.desired.ceilingBytes ?? null,
             ceilingMicros: action.desired.ceilingMicros ?? null,
+            shareHost: action.desired.shareHost ?? null,
             ...(owner ? { name: org.displayName, owner } : {}),
         });
         const agoraOrigin = action.desired.agoraOrigin;
@@ -4000,6 +4145,22 @@ export class FoundryStepExecutor {
         if (provisioned.agoraKey) {
             await this.deliverFilesAgoraKey(files, org, provisioned.agoraKey, context);
         }
+        // #437: the audience Agora requests to read/browse Files
+        // (`agoras.ts`'s `filesProjectId`), the same `urn:zitadel:iam:org:
+        // project:id:<id>:aud` shape `messagingProjectId` already uses. Retried
+        // on a later apply, same as the owner above, while the org's ZITADEL
+        // org id is not recorded yet (`zitadel:issuer` has not run).
+        const zitadelOrgId = recorded[ZITADEL_ORG_SCOPE_KEY];
+        if (zitadelOrgId) {
+            const { project } = await this.ports.zitadel.findOrCreateProject(zitadelOrgId, `${org.slug}-files`);
+            context.recordScopeId(ZITADEL_FILES_PROJECT_SCOPE_KEY, project.id);
+        }
+        // #437: the one collection every file Agora itself uploads goes into
+        // (`agoras.ts`'s `filesCollectionId`) -- Files has no route to list an
+        // organisation's collections and an ordinary member cannot create one,
+        // so it has to exist before Agora ever tries.
+        const collection = await files.ensureCollection(org.id, CORE_FILES_COLLECTION_NAME);
+        context.recordScopeId(FILES_CORE_COLLECTION_SCOPE_KEY, collection.id);
         return { resourceId: provisioned.organisationId };
     }
     /**
@@ -4036,12 +4197,6 @@ export class FoundryStepExecutor {
             context.recordScopeId(FILES_AGORA_UNDELIVERED_SCOPE_KEY, '');
         throw new Error(`${at}: Agora's key ${key.id} could not be delivered after ${AI_KEY_DELIVERY_ATTEMPTS} attempts (${cause}); ${revoked ? 'it was revoked again' : 'revoke it in files'}`);
     }
-    async filesStorage(action, org) {
-        const files = await this.filesPort();
-        await files.setQuota(org.id, action.desired.limitBytes ?? null);
-        await files.setBudget(org.id, action.desired.limitMicros ?? null);
-        return { resourceId: org.id };
-    }
     /**
      * #80: provisions the org's own organisation on AI and switches its AI use
      * on, before {@link aiBudget} can set its own spend limit. Both
@@ -4429,6 +4584,7 @@ export class FoundryStepExecutor {
             const envs = [
                 { key: 'FILES_URL', value: d.filesUrl },
                 { key: 'FILES_ORGANISATION_ID', value: org.id },
+                ...(d.shareOrigin ? [{ key: 'FILES_SHARE_ORIGIN', value: d.shareOrigin }] : []),
             ];
             for (const name of d.collections) {
                 let collection;
@@ -4495,6 +4651,7 @@ export class FoundryStepExecutor {
             permissions: d.permissions,
             collections: d.collections,
             filesUrl: d.filesUrl,
+            ...(d.shareOrigin ? { shareOrigin: d.shareOrigin } : {}),
         }));
         if (expiresAt && previousKeyId && previousKeyId !== resourceId) {
             await this.revokeFilesEntryKey(files, org, entryKey, previousKeyId, context);

package/dist/plan/hostnames.d.ts

@@ -26,6 +26,12 @@ export declare function appHostname(org: DeclaredOrg): string;
 export declare function coolifyDomains(names: readonly string[]): string;
 /** What `domains` held on an `app` entry's Coolify app before entries had hostnames. */
 export declare function legacyAppHostname(org: DeclaredOrg): string;
+/**
+ * `share.<domain>` when hosting is on and an entry declares
+ * `uses.files.shareHost`, else `null`. The files service answers public
+ * shares there; foundry never puts it behind Access.
+ */
+export declare function filesShareHostname(org: DeclaredOrg): string | null;
 /**
  * The hostnames `cloudflareTunnel` routes to Coolify's proxy (#115, #145,
  * #164): a site's two names, every entry's names, an own-domain calls name,

package/dist/plan/hostnames.js

@@ -47,6 +47,16 @@ export function coolifyDomains(names) {
 export function legacyAppHostname(org) {
     return org.hosting.usesDomain && org.domain ? org.domain : `${org.slug}.oikos.host`;
 }
+/**
+ * `share.<domain>` when hosting is on and an entry declares
+ * `uses.files.shareHost`, else `null`. The files service answers public
+ * shares there; foundry never puts it behind Access.
+ */
+export function filesShareHostname(org) {
+    if (!org.hosting.enabled || !org.domain)
+        return null;
+    return org.hosting.entries.some((e) => e.uses?.files?.shareHost) ? `share.${org.domain}` : null;
+}
 /**
  * The hostnames `cloudflareTunnel` routes to Coolify's proxy (#115, #145,
  * #164): a site's two names, every entry's names, an own-domain calls name,
@@ -71,6 +81,9 @@ export function tunnelIngressHostnames(org) {
         // #161: and Boule moves onto `boule.<domain>` the same way.
         hostnames.push(bouleHostnameFor(org));
     }
+    const share = filesShareHostname(org);
+    if (share)
+        hostnames.push(share);
     // The wildcard goes last: Cloudflare takes the first ingress rule that
     // matches, so every exact name above must come before `*.<domain>`.
     const wildcard = wildcardHostname(org);

package/dist/plan/index.d.ts

@@ -2,15 +2,19 @@ export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, File
 export { readLiveResources, readLivePlatformResources } from './live.js';
 export type { StepAction, PlannedStep, PlanDetail } from './diff.js';
 export { computePlanDetail, toPlan } from './diff.js';
+export type { StepSystem } from './step-system.js';
+export { stepSystemOf } from './step-system.js';
 export type { PlatformPlanDetail } from './platform-diff.js';
 export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, } from './platform-diff.js';
 export type { HeldKeyResolver, OrgPlatformReadiness } from './platform-org.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './platform-org.js';
 export type { PlatformOrgClientFactories } from './platform-org-ports.js';
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './platform-org-ports.js';
+export type { AdoptCandidate, AdoptInput, AdoptPlan, AdoptSnapshot } from './adopt.js';
+export { AdoptRefusedError } from './adopt.js';
 export type { AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, } from './plan-apply.js';
 export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan-apply.js';
-export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './platform-providers.js';
+export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, filesPublicHostsValue, filesShareDomains, } from './platform-providers.js';
 export type { PlatformAuthDeps, PlatformAuthRuntime, PlatformFilesDeps, PlatformFilesRuntime, } from './platform-providers.js';
 export type { PlatformMailDeps, PlatformMailAdminPort, PlatformMailRuntime, } from './platform-providers.js';
 export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, PLATFORM_AUTH_INSTANCE_BEARER_REF, } from './platform-providers.js';

package/dist/plan/index.js

@@ -1,10 +1,12 @@
 export { readLiveResources, readLivePlatformResources } from './live.js';
 export { computePlanDetail, toPlan } from './diff.js';
+export { stepSystemOf } from './step-system.js';
 export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, } from './platform-diff.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './platform-org.js';
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './platform-org-ports.js';
+export { AdoptRefusedError } from './adopt.js';
 export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan-apply.js';
-export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './platform-providers.js';
+export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, filesPublicHostsValue, filesShareDomains, } from './platform-providers.js';
 // #171: how a host signs files management requests with the delivered key.
 export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, PLATFORM_AUTH_INSTANCE_BEARER_REF, } from './platform-providers.js';
 export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManagementKeyExistsError, createAiManagementKeyMinter, PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, } from './platform-providers.js';