@wtfalch/foundry 0.30.0 → 0.32.0

package/dist/apply.d.ts

@@ -1,5 +1,6 @@
 import type { OrgId } from './org.js';
 import type { Plan } from './plan.js';
+import type { FoundryApplyOptions } from './plan/plan-apply.js';
 import type { AppliedState } from './state.js';
 /** One destroy step starting, finishing or failing; `index` counts from 1 up to `total`. */
 export interface DestroyProgress {
@@ -30,8 +31,12 @@ export interface PlanApply {
      * required whenever `plan` contains a step with `destroys` or `migrates`
      * true (#9). Implementations must refuse to apply when the live state a
      * fresh plan would compute no longer matches this `plan` (#9, #10).
+     * @param options `confirmUpgrade` names the services whose version change
+     * is confirmed. Implementations must refuse, before any step runs, a plan
+     * whose `versionChanges` holds a `needsConfirmation` line for a service
+     * `confirmUpgrade` does not name exactly.
      */
-    apply(plan: Plan, confirmedOrgName: string): Promise<AppliedState>;
+    apply(plan: Plan, confirmedOrgName: string, options?: FoundryApplyOptions): Promise<AppliedState>;
     /**
      * Deletes every resource foundry created and recorded for `id`, then the
      * declared org itself.

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export { REQUESTABLE_FIELDS, classifyChange, RequestedChangeError } from './requ
 export type { SlugRejectionReason, SlugRejection } from './slug.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
 export type { Checkpoint, LastApplied, AppliedState, DestroyRecord, DestroyStepRecord, } from './state.js';
-export type { PlanStep, UnmanagedItem, Plan } from './plan.js';
+export type { PlanStep, UnmanagedItem, Plan, VersionChangeItem } from './plan.js';
 export type { AppliedVersion, AppliedVersionsStore, DeclaredOrgStore, HeldLease, MutationLease, PlatformStore, RequestedChangeStore, StaleUpdate, UpdateOptions, } from './store.js';
 export { StaleLeaseError } from './store.js';
 export type { PlanApply, DestroyProgress } from './apply.js';
@@ -18,11 +18,11 @@ export { createPostgresAppliedVersionsStore, createPostgresDeclaredOrgStore, cre
 export { createPostgresAuditLog } from './store/audit.js';
 export type { FoundryStoreDb } from './store/postgres.js';
 export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, type AuditEventRow, type DeclaredOrgRow, type NewDeclaredOrgRow, type AppliedStateRow, type NewAppliedStateRow, type AppliedVersionRow, type NewAppliedVersionRow, type DeclaredPlatformRow, type NewDeclaredPlatformRow, type RequestedChangeRow, type NewRequestedChangeRow, } from './store/schema.js';
-export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, PlatformCloudflareReader, PlatformCoolifyReader, PlatformLiveReaders, StepAction, PlannedStep, StepSystem, PlanDetail, OrgPostgresPlan, PlatformPlanDetail, AdoptCandidate, AdoptInput, AdoptPlan, AdoptSnapshot, AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, } from './plan/index.js';
+export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, PlatformCloudflareReader, PlatformCoolifyReader, PlatformLiveReaders, StepAction, PlannedStep, StepSystem, PlanDetail, OrgPostgresPlan, PlatformPlanDetail, AdoptCandidate, AdoptInput, AdoptPlan, AdoptSnapshot, AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, FoundryApplyOptions, UnconfirmedUpgrade, } from './plan/index.js';
 export { AdoptRefusedError } from './plan/index.js';
 export { createEdgeAccess, createEdgeDns, edgeDnsRecordOwners, createEdgeRateLimits, createEdgeTunnels, createEdgeWorkers, createEdgeZones, } from './plan/index.js';
 export type { AccessAppSummary, AccessDecision, AccessPolicyRule, AccessPort, DnsPort, EdgePlatformAccess, EdgePlatformDns, EdgePlatformRateLimits, EdgePlatformWorkers, EdgePlatformZones, EdgeZonesOptions, ZonePort, EdgeRateLimitsOptions, RateLimitPort, RateLimitRuleInput, EdgeWorkersOptions, EdgePlatformTunnels, TunnelPort, } from './plan/index.js';
-export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, PLATFORM_SFU_APPLIED_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
+export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, PLATFORM_SFU_APPLIED_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, UpgradeConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
 export type { HeldKeyResolver, OrgPlatformReadiness } from './plan/index.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './plan/index.js';
 export type { PlatformOrgClientFactories } from './plan/index.js';

package/dist/index.js

@@ -13,7 +13,7 @@ export { createPostgresAuditLog } from './store/audit.js';
 export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, } from './store/schema.js';
 export { AdoptRefusedError } from './plan/index.js';
 export { createEdgeAccess, createEdgeDns, edgeDnsRecordOwners, createEdgeRateLimits, createEdgeTunnels, createEdgeWorkers, createEdgeZones, } from './plan/index.js';
-export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, PLATFORM_SFU_APPLIED_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
+export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, PLATFORM_SFU_APPLIED_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, UpgradeConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './plan/index.js';
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';

package/dist/org.d.ts

@@ -288,7 +288,12 @@ export declare const APP_ENTRY_KEY = "app";
 export interface HostingEntry {
     /** A DNS label, unique per org. It goes into step ids and scope keys, so it never holds `:` or `.`. */
     key: string;
-    /** The repo under `wtfalch` the app builds from. `null` is the shared standard app (`executor.ts`'s `DEFAULT_APP_REPO`). */
+    /**
+     * The repo under `wtfalch` the app builds from. `null` is the shape
+     * migration 0029 wrote for every org with no `bespokeAppRepo`; there is no
+     * shared default app any more (#447), so `plan/diff.ts`'s `planApp` blocks
+     * it at plan time instead of provisioning it.
+     */
     repo: string | null;
     /** The app's folder in `repo`. `null` is the repo root. */
     folder: string | null;

package/dist/org.js

@@ -502,8 +502,8 @@ const WORKER_SHA256 = /^[0-9a-f]{64}$/;
 const WORKER_NAME_FIXED_LENGTH = 8 + 1 + '-edge'.length;
 const WORKER_NAME_MAX_LENGTH = 63;
 /**
- * `worker`: the entry's own repo (never the shared standard app -- entries
- * with `repo: null` have no Worker source of their own), an `https://`
+ * `worker`: the entry's own repo (entries with `repo: null` have no Worker
+ * source of their own), an `https://`
  * artifact URL with a lowercase-hex sha256 (never a bare path or relative
  * file -- estate DECISIONS.md, 2026-10-04, rules out any checkout or
  * bundling inside foundry), a route whose zone is the org's own domain
@@ -519,7 +519,7 @@ function validateEntryWorker(entry, hosting, domain) {
     if (!hosting.enabled)
         return `${at} requires hosting.enabled`;
     if (entry.repo === null) {
-        return `${at} needs its own repo (repo: null is the shared standard app, not a Worker source)`;
+        return `${at} needs its own repo (repo: null is not a Worker source)`;
     }
     if (entry.key.length > WORKER_NAME_MAX_LENGTH - WORKER_NAME_FIXED_LENGTH) {
         return `${at} entry key is too long: the deployed Worker's name (an 8-character org hash, the key, and "-edge") must fit Cloudflare's ${WORKER_NAME_MAX_LENGTH}-character limit`;

package/dist/plan/confirm-upgrade.d.ts

@@ -0,0 +1,17 @@
+import type { VersionChangeItem } from '../plan.js';
+export interface UnconfirmedUpgrade {
+    service: string;
+    from?: string;
+    to?: string;
+}
+/**
+ * Whether a change of `service` from `from` to `to` needs a confirmation:
+ * any change on a stateful service, otherwise a major or minor difference.
+ * A git ref or branch name has no major or minor, so it never counts as a jump.
+ */
+export declare function versionChangeNeedsConfirmation(service: string, from: string, to: string): boolean;
+/**
+ * The lines that need a confirmation `confirmUpgrade` does not give. A name
+ * must match `VersionChangeItem.service` exactly; no value confirms all.
+ */
+export declare function unconfirmedUpgrades(versionChanges: readonly VersionChangeItem[] | undefined, confirmUpgrade: readonly string[] | undefined): UnconfirmedUpgrade[];

package/dist/plan/confirm-upgrade.js

@@ -0,0 +1,47 @@
+/**
+ * The `VersionChangeItem.service` names whose data the service migrates on
+ * first boot with a new image, so going back to the old image may not undo
+ * it. Stalwart is reported as `mail`, the name of its plan step. Postgres
+ * has no version-change line yet; its name is here for when it gets one.
+ */
+const STATEFUL_VERSION_CHANGE_SERVICES = new Set([
+    'zitadel',
+    'mail',
+    'synapse',
+    'mas',
+    'postgres',
+]);
+function majorMinor(version) {
+    const match = /^v?(\d+)\.(\d+)\.\d+/.exec(version.trim());
+    return match ? `${match[1]}.${match[2]}` : null;
+}
+/**
+ * Whether a change of `service` from `from` to `to` needs a confirmation:
+ * any change on a stateful service, otherwise a major or minor difference.
+ * A git ref or branch name has no major or minor, so it never counts as a jump.
+ */
+export function versionChangeNeedsConfirmation(service, from, to) {
+    if (from === to)
+        return false;
+    if (STATEFUL_VERSION_CHANGE_SERVICES.has(service))
+        return true;
+    const a = majorMinor(from);
+    const b = majorMinor(to);
+    return a !== null && b !== null && a !== b;
+}
+/**
+ * The lines that need a confirmation `confirmUpgrade` does not give. A name
+ * must match `VersionChangeItem.service` exactly; no value confirms all.
+ */
+export function unconfirmedUpgrades(versionChanges, confirmUpgrade) {
+    const confirmed = new Set(confirmUpgrade ?? []);
+    const seen = new Set();
+    const result = [];
+    for (const line of versionChanges ?? []) {
+        if (!line.needsConfirmation || confirmed.has(line.service) || seen.has(line.service))
+            continue;
+        seen.add(line.service);
+        result.push({ service: line.service, from: line.from, to: line.to });
+    }
+    return result;
+}

package/dist/plan/diff.js

@@ -2323,10 +2323,17 @@ function planHostingToggle(system, kind, desiredEnabled, org, byKey, claimed, de
         step: { description: describeProvision(), destroys: false, migrates: false },
     };
 }
+/**
+ * The git source of the retired shared default app (`apps/hestia`, deleted in
+ * #447). {@link planApp} uses it only to recognise a live app still built
+ * from it, which it deletes instead of parking: nothing can redeploy it.
+ */
+const RETIRED_DEFAULT_APP_REPO = 'wtfalch/foundry';
 /**
  * The org's own app on Coolify (`org.ts`'s `HostingConfig.enabled`, #71), a
  * per-org singleton resource modeled on {@link planSite}: park, not delete,
- * on the way off (#7 corrections 1).
+ * on the way off (#7 corrections 1) -- except a live app built from
+ * {@link RETIRED_DEFAULT_APP_REPO}, which is deleted (#447).
  *
  * #75: every app foundry deploys also carries a durable log directory (a
  * persistent volume mounted at `/app/logs`, `LOG_DIR` in its env) so a
@@ -2411,10 +2418,49 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
             });
         }
     }
-    const toggled = planHostingToggle('coolify', 'app', entry !== undefined, org, byKey, claimed, () => `provision ${org.slug}'s ${label}`, () => `park ${org.slug}'s ${label} (stops serving; app data is retained, not deleted -- #7 corrections 1)`, stepKey);
+    // #447: no shared default app any more. Migration 0029 wrote `repo: null`
+    // for every org without a bespoke app and nothing rewrites that data, so
+    // the entry stays declared but is blocked here and never provisioned.
+    const noRepo = entry !== undefined && entry.repo === null;
+    if (noRepo) {
+        blocked.push({
+            description: `${org.slug}'s ${label} repo is blocked, not planned: there is no shared default app any more (#447)`,
+            key: blockedKey('repo'),
+        });
+    }
+    const toggled = planHostingToggle('coolify', 'app', entry !== undefined && !noRepo, org, byKey, claimed, () => `provision ${org.slug}'s ${label}`, () => `park ${org.slug}'s ${label} (stops serving; app data is retained, not deleted -- #7 corrections 1)`, stepKey);
+    // #447: only the live app's own `git_repository` decides, never the
+    // declared entry (a `repo: null` entry can sit over a bespoke app, which is
+    // parked as before). Only the `app` key ever held the default app, and an
+    // entry that declares a repo is never a candidate. The reader does not
+    // surface the Dockerfile location, so the repo is the whole match. Checked
+    // whether or not the app is already parked, so a parked leftover is not
+    // stranded.
+    if (entryKey === APP_ENTRY_KEY && (entry === undefined || noRepo)) {
+        const liveApp = byKey.get(resourceKey('coolify', 'app', stepKey));
+        if (liveApp?.config.git_repository === RETIRED_DEFAULT_APP_REPO) {
+            claimed.add(resourceKey('coolify', 'app', stepKey));
+            return {
+                step: {
+                    action: {
+                        system: 'coolify',
+                        kind: 'app',
+                        key: stepKey,
+                        desired: { enabled: false, delete: true },
+                    },
+                    step: {
+                        description: `delete ${org.slug}'s ${label}: it still builds from the retired shared default app, which no longer exists to redeploy from (#447)`,
+                        destroys: true,
+                        migrates: false,
+                    },
+                },
+                blocked,
+            };
+        }
+    }
     if (toggled)
         return { step: toggled, blocked };
-    if (!entry)
+    if (!entry || noRepo)
         return { step: null, blocked };
     const live = byKey.get(resourceKey('coolify', 'app', stepKey));
     if (!live)

package/dist/plan/executor.js

@@ -230,24 +230,6 @@ const RATE_LIMIT_RULE_DESCRIPTION = 'foundry: rate limit sign-in paths';
  */
 const RATE_LIMIT_FREE_PLAN_PERIOD_SECONDS = 10;
 const RATE_LIMIT_REQUESTS_PER_PERIOD = 10;
-/**
- * The shared standard app a level-1 org with no `bespokeAppRepo` gets
- * deployed (gap P1, `.plans/2026-09-26-level-1-org-map.md`): one repo, the
- * same for every such org, decided by William 2026-09-26. `coolifyApp` below
- * names it as the git source in exactly the shape `bespokeAppRepo` itself
- * uses (`org.ts`'s `DeclaredOrg.bespokeAppRepo: string | null`) whenever an
- * org declares none of its own — the repo may not exist yet at decision
- * time, and Coolify's own GitHub App create call is what will fail loudly
- * against it, the same as any other repo name that does not exist.
- *
- * Hestia moved into this repo's own `apps/hestia` (estate DECISIONS.md,
- * 2026-09-28; the hestia repo archives once this move lands), so the
- * standard app now builds from foundry's own repo, told apart from
- * `packages/foundry` by `dockerfile_location` — the same one-repo,
- * multiple-apps shape `cmsSite`/`CMS_APP_DOCKERFILE` already use below.
- */
-const DEFAULT_APP_REPO = 'wtfalch/foundry';
-const DEFAULT_APP_DOCKERFILE = '/apps/hestia/Dockerfile';
 /**
  * The shared repo `cmsSite` builds its cms admin app from, always, and its
  * site app from by default (https://github.com/wtfalch/cms) -- the
@@ -275,7 +257,7 @@ const CMS_APP_PORT = 3000;
  * #164: the repo `coolifyAgora` builds the org's Agora from
  * (https://github.com/wtfalch/agora) -- the issue's own "How" names this
  * exact Dockerfile, and it is the only build strategy any app this file
- * provisions ever uses ({@link DEFAULT_APP_DOCKERFILE}/{@link CMS_APP_DOCKERFILE}/
+ * provisions ever uses ({@link CMS_APP_DOCKERFILE}/
  * `CALLS_SERVICE_DOCKERFILE` below are all `dockerfile_location` into a
  * `createGithubAppApplication` build-from-repo call, never a registry
  * image): "Coolify builds each org's Agora from the agora repo" is not a
@@ -1868,7 +1850,19 @@ export class FoundryStepExecutor {
         const recordedAppId = context.recordedIds()[`coolify:app:${action.key}`];
         if (action.desired.enabled === false) {
             if (!recordedAppId) {
-                throw new Error(`coolify:app for ${org.slug}: no live app recorded, nothing to park`);
+                throw new Error(`coolify:app for ${org.slug}: no live app recorded, nothing to ${action.desired.delete === true ? 'delete' : 'park'}`);
+            }
+            // `planApp` sets `delete` only on the retired default app. A 404 counts
+            // as deleted, so a retry after a crash past the Coolify delete succeeds.
+            if (action.desired.delete === true) {
+                try {
+                    await this.ports.coolify.deleteApplication(recordedAppId);
+                }
+                catch (error) {
+                    if (!isNotFoundError(error))
+                        throw error;
+                }
+                return {};
             }
             await this.ports.coolify.raw('POST', `/applications/${recordedAppId}/stop`);
             return { resourceId: recordedAppId };
@@ -1876,10 +1870,12 @@ export class FoundryStepExecutor {
         const entry = org.hosting.entries.find((e) => appStepKey(org, e.key) === action.key);
         if (!entry)
             throw new Error(`coolify:app for ${org.slug}: no hosting entry for ${action.key}`);
-        // A level-1 org with no bespoke app of its own gets the shared standard
-        // app instead (gap P1, `.plans/2026-09-26-level-1-org-map.md`): an entry
-        // with no `repo`.
-        const appRepo = entry.repo ?? DEFAULT_APP_REPO;
+        // `planApp` blocks a `repo: null` entry at plan time; reaching here with
+        // one means a stale or hand-built plan.
+        if (entry.repo === null) {
+            throw new Error(`coolify:app for ${org.slug}: entry '${entry.key}' has no repo`);
+        }
+        const appRepo = entry.repo;
         const projectUuid = await this.ensureCoolifyProject(org, context);
         const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
         // The recorded id first; the name when nothing is recorded, or when the
@@ -1953,9 +1949,6 @@ export class FoundryStepExecutor {
                 // copies `base_directory`, and reads `publish_directory` only for a
                 // built app.
                 base_directory: entry.folder === null ? undefined : `/${entry.folder}`,
-                // Only the shared standard app builds from this repo; a bespoke
-                // app's Dockerfile is at its own repo's root.
-                dockerfile_location: entry.repo ? undefined : DEFAULT_APP_DOCKERFILE,
             });
             appId = created.uuid;
             // Create sent every setting, so nothing is left to patch.

package/dist/plan/index.d.ts

@@ -12,8 +12,9 @@ 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 type { AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, FoundryApplyOptions, } from './plan-apply.js';
+export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, UpgradeConfirmationRequiredError, planNeedsConfirmation, } from './plan-apply.js';
+export type { UnconfirmedUpgrade } from './confirm-upgrade.js';
 export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, filesPublicHostsValue, filesShareDomains, } from './platform-providers.js';
 export type { PlatformAuthDeps, PlatformAuthSmtp, PlatformAuthRuntime, PlatformFilesDeps, PlatformFilesRuntime, PlatformEdgeDeps, PlatformDnsFactory, PlatformAccessFactory, PlatformAccessPort, PlatformTunnelsFactory, PlatformEdgeRuntime, } from './platform-providers.js';
 export type { PlatformMailDeps, PlatformMailAdminPort, PlatformMailRuntime, } from './platform-providers.js';

package/dist/plan/index.js

@@ -5,7 +5,7 @@ export { planPlatform, toPlatformPlan, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDUL
 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 { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, UpgradeConfirmationRequiredError, planNeedsConfirmation, } from './plan-apply.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';

package/dist/plan/plan-apply.d.ts

@@ -7,6 +7,7 @@ import type { AppliedState } from '../state.js';
 import { type AppliedVersionsStore, type DeclaredOrgStore, type PlatformStore } from '../store.js';
 import { type AdoptCandidate, type AdoptInput, type AdoptPlan } from './adopt.js';
 import { type AgoraHostPort } from './agora.js';
+import { type UnconfirmedUpgrade } from './confirm-upgrade.js';
 import { type StepAction } from './diff.js';
 import { type LiveReaders, type LiveResource, type PlatformLiveReaders } from './live.js';
 import { type EdgePortName, type HeldKeyResolver } from './platform-org.js';
@@ -313,6 +314,15 @@ export declare class StalePlanError extends Error {
 export declare class ConfirmationRequiredError extends Error {
     constructor(orgId: OrgId);
 }
+/**
+ * A plan holds a version change that needs confirmation
+ * (`VersionChangeItem.needsConfirmation`) and `confirmUpgrade` does not name
+ * its service exactly. `upgrades` lists every such service with its versions.
+ */
+export declare class UpgradeConfirmationRequiredError extends Error {
+    readonly upgrades: readonly UnconfirmedUpgrade[];
+    constructor(upgrades: readonly UnconfirmedUpgrade[]);
+}
 export declare class NotAuthorizedError extends Error {
     constructor(actor: AuditActor, orgId: OrgId);
 }
@@ -336,6 +346,11 @@ export declare class PlatformStalePlanError extends Error {
 export declare class PlatformConfirmationRequiredError extends Error {
     constructor();
 }
+/** The third argument of `apply` and `applyPlatform`. */
+export interface FoundryApplyOptions {
+    /** Service names (`VersionChangeItem.service`), matched exactly, whose version change the operator confirmed. */
+    confirmUpgrade?: readonly string[];
+}
 export interface FoundryPlanApplyOptions {
     store: DeclaredOrgStore;
     readers: LiveReaders;
@@ -518,7 +533,7 @@ export declare class FoundryPlanApply implements PlanApply {
      */
     release(id: OrgId, entryKey: string): Promise<AppliedState>;
     private computeAdopt;
-    apply(plan: Plan, confirmedOrgName: string): Promise<AppliedState>;
+    apply(plan: Plan, confirmedOrgName: string, options?: FoundryApplyOptions): Promise<AppliedState>;
     /**
      * After an org apply: gives the platform files runner a changed share-domain
      * set (its Coolify `domains` and `FILES_PUBLIC_HOSTS`, derived from the
@@ -543,7 +558,7 @@ export declare class FoundryPlanApply implements PlanApply {
      * shape of their own. `confirmedName` must be the literal word `platform`
      * rather than a declared name -- `DeclaredPlatform` has none.
      */
-    applyPlatform(plan: Plan, confirmedName: string): Promise<{
+    applyPlatform(plan: Plan, confirmedName: string, options?: FoundryApplyOptions): Promise<{
         serviceIds: Record<string, string>;
     }>;
     /**

package/dist/plan/plan-apply.js

@@ -6,6 +6,7 @@ import { AlreadyRunningError, StepFailedError } from '../runner/errors.js';
 import { StaleLeaseError, } from '../store.js';
 import { AdoptRefusedError, adoptCandidates, adoptedKeysUnreadable, adoptedScopeKey, parseAdoptSnapshot, planAdoptFrom, } from './adopt.js';
 import { NO_AGORA_HOST_VALUES, readAgoraHost, } from './agora.js';
+import { unconfirmedUpgrades } from './confirm-upgrade.js';
 import { AI_KEY_UNDELIVERED_SCOPE_KEY, JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY, computePlanDetail, toPlan, } from './diff.js';
 import { entryAiUndeliveredScopeKey } from './entry-ai-key.js';
 import { BOULE_EDGE_ENTRY_KEY, entryEdgeRetiredScopeKey, entryEdgeUndeliveredScopeKey, } from './entry-edge-key.js';
@@ -53,6 +54,21 @@ export class ConfirmationRequiredError extends Error {
         this.name = 'ConfirmationRequiredError';
     }
 }
+/**
+ * A plan holds a version change that needs confirmation
+ * (`VersionChangeItem.needsConfirmation`) and `confirmUpgrade` does not name
+ * its service exactly. `upgrades` lists every such service with its versions.
+ */
+export class UpgradeConfirmationRequiredError extends Error {
+    upgrades;
+    constructor(upgrades) {
+        super(`the plan changes versions that must be confirmed by service name: ${upgrades
+            .map((u) => `${u.service} ${u.from ?? 'unknown'} -> ${u.to ?? 'unknown'}`)
+            .join(', ')}; pass confirmUpgrade naming each one`);
+        this.upgrades = upgrades;
+        this.name = 'UpgradeConfirmationRequiredError';
+    }
+}
 export class NotAuthorizedError extends Error {
     constructor(actor, orgId) {
         super(`${actor.display} does not hold the permission to apply org ${orgId} (#9, #19)`);
@@ -341,7 +357,7 @@ export class FoundryPlanApply {
             previous,
         };
     }
-    async apply(plan, confirmedOrgName) {
+    async apply(plan, confirmedOrgName, options = {}) {
         const orgId = plan.orgId;
         const authorized = await this.authz.canApply(this.actor, orgId);
         if (!authorized) {
@@ -354,6 +370,11 @@ export class FoundryPlanApply {
                 await this.refuse(plan, 'stale: live state has moved since this plan was computed');
                 throw new StalePlanError(orgId);
             }
+            const unconfirmed = unconfirmedUpgrades(freshPlan.versionChanges, options.confirmUpgrade);
+            if (unconfirmed.length > 0) {
+                await this.refuse(plan, `version change without confirmUpgrade naming: ${unconfirmed.map((u) => u.service).join(', ')}`);
+                throw new UpgradeConfirmationRequiredError(unconfirmed);
+            }
             if (planNeedsConfirmation(plan.steps) &&
                 confirmedOrgName.trim() !== org.displayName.trim()) {
                 await this.refuse(plan, "destructive or migrating step without the org's name typed correctly");
@@ -426,7 +447,7 @@ export class FoundryPlanApply {
      * shape of their own. `confirmedName` must be the literal word `platform`
      * rather than a declared name -- `DeclaredPlatform` has none.
      */
-    async applyPlatform(plan, confirmedName) {
+    async applyPlatform(plan, confirmedName, options = {}) {
         const { store, executor } = this.requirePlatformDeps();
         const declared = await store.get();
         if (!declared)
@@ -449,6 +470,11 @@ export class FoundryPlanApply {
                 await this.refusePlatform(plan, platform.ownerOrgId, 'stale: live state has moved since this plan was computed');
                 throw new PlatformStalePlanError();
             }
+            const unconfirmed = unconfirmedUpgrades(freshPlan.versionChanges, options.confirmUpgrade);
+            if (unconfirmed.length > 0) {
+                await this.refusePlatform(plan, platform.ownerOrgId, `version change without confirmUpgrade naming: ${unconfirmed.map((u) => u.service).join(', ')}`);
+                throw new UpgradeConfirmationRequiredError(unconfirmed);
+            }
             if (planNeedsConfirmation(plan.steps) && confirmedName.trim() !== 'platform') {
                 await this.refusePlatform(plan, platform.ownerOrgId, "destructive or migrating step without 'platform' typed correctly");
                 throw new PlatformConfirmationRequiredError();
@@ -803,6 +829,10 @@ export class FoundryPlanApply {
                     const { system, kind, key } = planned.action;
                     serviceIds[`${system}:${kind}:${key}`] = result.resourceId;
                 }
+                else if (planned.action.desired.delete === true) {
+                    const { system, kind, key } = planned.action;
+                    delete serviceIds[`${system}:${kind}:${key}`];
+                }
                 checkpoints.push({ step: planned.step.description, completedAt: this.now().toISOString() });
             }
         }

package/dist/plan/platform-diff.d.ts

@@ -216,6 +216,8 @@ export declare const PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY = "zitadel_platform_ow
 export declare const PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY = "zitadel_platform_reserved_admin_username";
 /** #394: recorded once the platform's own ZITADEL org has self-registration forced off. */
 export declare const PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY = "zitadel_platform_registration_closed";
+/** The platform's own ZITADEL org (`foundry`, the one `provisionPlatformAuth` mints its admin user in). */
+export declare const PLATFORM_ZITADEL_ORG_SCOPE_KEY = "zitadel_platform_org";
 export declare const PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY = "zitadel_platform_admin_user_id";
 export declare const PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY = "zitadel_platform_admin_user_undelivered";
 /** #283: the created instance's id, recorded once its owner token is delivered. */
@@ -403,6 +405,15 @@ export declare const PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY = "stalwart_platf
  */
 export declare const PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY = "mail_applied_hostname";
 export declare const PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY = "mail_applied_git_ref";
+/**
+ * #661: recorded with {@link PLATFORM_MAIL_ROUTE_WANTED} once the mail
+ * server's settings write included the rule that delivers hosted recipients
+ * locally (`@wtfalch/email` 0.20.0). A platform applied before it lacks the id,
+ * so `planMail` plans the step once more; that run redeploys nothing, mints
+ * no key and creates nothing in the sign-in server.
+ */
+export declare const PLATFORM_MAIL_ROUTE_SCOPE_KEY = "mail_route_applied";
+export declare const PLATFORM_MAIL_ROUTE_WANTED = "local-first";
 /**
  * #177: where the mail server answers on the Coolify network
  * (`http://<custom_internal_name>:<port>`), recorded by the step the same way
@@ -1029,6 +1040,12 @@ export interface PlanPlatformOptions {
          * repair step is not planned.
          */
         archonIdTokenUserinfo?: boolean;
+        /**
+         * The executor has the platform's sign-in dependencies and a ZITADEL
+         * client for its instance. Not a block: without it the sign-in policy
+         * step is not planned.
+         */
+        authSignInPolicy?: boolean;
     };
     /**
      * Steps whose live state differs from the declared one in a way the recorded

package/dist/plan/platform-diff.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { VERSIONS } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY } from '../org.js';
 import { VERSION_CHANGE_KIND, } from '../plan.js';
+import { versionChangeNeedsConfirmation } from './confirm-upgrade.js';
 import { ACCESS_PROVIDER_RECORD_KEY } from './gates.js';
 import { legacyAppHostname } from './hostnames.js';
 import { callsSfuAppliedFingerprint } from './platform-sfu.js';
@@ -78,6 +79,9 @@ export function versionChangeLine(service, from, to, note) {
         kind: VERSION_CHANGE_KIND,
         service,
         description: `${service}: ${from} -> ${to} (${note})`,
+        from,
+        to,
+        needsConfirmation: versionChangeNeedsConfirmation(service, from, to),
     };
 }
 /**
@@ -99,6 +103,8 @@ export function versionNotAppliedLine(service, appLive, applied, pinned) {
             kind: VERSION_CHANGE_KIND,
             service,
             description: `${service}: pinned ${pinned}, running tag unknown`,
+            to: pinned,
+            needsConfirmation: false,
         };
     }
     if (applied === pinned)
@@ -107,6 +113,10 @@ export function versionNotAppliedLine(service, appLive, applied, pinned) {
         kind: VERSION_CHANGE_KIND,
         service,
         description: `${service}: pinned ${pinned}, running ${applied} (not applied by foundry)`,
+        from: applied,
+        to: pinned,
+        // #254: no apply acts on this line, so there is no upgrade to confirm.
+        needsConfirmation: false,
     };
 }
 /**
@@ -243,6 +253,8 @@ export const PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY = 'zitadel_platform_owner_invi
 export const PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY = 'zitadel_platform_reserved_admin_username';
 /** #394: recorded once the platform's own ZITADEL org has self-registration forced off. */
 export const PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY = 'zitadel_platform_registration_closed';
+/** The platform's own ZITADEL org (`foundry`, the one `provisionPlatformAuth` mints its admin user in). */
+export const PLATFORM_ZITADEL_ORG_SCOPE_KEY = 'zitadel_platform_org';
 export const PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY = 'zitadel_platform_admin_user_id';
 export const PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY = 'zitadel_platform_admin_user_undelivered';
 /** #283: the created instance's id, recorded once its owner token is delivered. */
@@ -441,6 +453,15 @@ export const PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY = 'stalwart_platform_admi
  */
 export const PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY = 'mail_applied_hostname';
 export const PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY = 'mail_applied_git_ref';
+/**
+ * #661: recorded with {@link PLATFORM_MAIL_ROUTE_WANTED} once the mail
+ * server's settings write included the rule that delivers hosted recipients
+ * locally (`@wtfalch/email` 0.20.0). A platform applied before it lacks the id,
+ * so `planMail` plans the step once more; that run redeploys nothing, mints
+ * no key and creates nothing in the sign-in server.
+ */
+export const PLATFORM_MAIL_ROUTE_SCOPE_KEY = 'mail_route_applied';
+export const PLATFORM_MAIL_ROUTE_WANTED = 'local-first';
 /**
  * #177: where the mail server answers on the Coolify network
  * (`http://<custom_internal_name>:<port>`), recorded by the step the same way
@@ -1174,6 +1195,10 @@ export function planPlatform(platform, live, options = {}) {
     const idTokenUserinfo = planArchonIdTokenUserinfo(platform, recordedIds, blocked.archonIdTokenUserinfo ?? false);
     if (idTokenUserinfo)
         plannedSteps.push(idTokenUserinfo);
+    // #669: after the ID token repair too, which is proven; a policy call that fails every time holds up nothing.
+    const signInPolicy = planAuthSignInPolicy(platform, recordedIds, blocked.authSignInPolicy ?? false);
+    if (signInPolicy)
+        plannedSteps.push(signInPolicy);
     // #251: one line per service whose recorded applied ref no longer matches
     // what the next apply would use (or, for zitadel, what is actually live).
     // Never pushed into `plannedSteps` -- see `VersionChangeItem`'s own doc
@@ -1717,10 +1742,7 @@ function planAuth(platform, recordedIds, executorBlocked, executorMissing, authD
         Boolean(recordedIds[PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY]) &&
         // The ZITADEL run options reach the container only through the auth
         // step's redeploy, so a platform recorded before them still plans it.
-        recordedIds[PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY] === AUTH_ZITADEL_RUN_OPTIONS &&
-        // #394: a platform applied before these existed plans the step again.
-        Boolean(recordedIds[PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY]) &&
-        Boolean(recordedIds[PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY])) {
+        recordedIds[PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY] === AUTH_ZITADEL_RUN_OPTIONS) {
         return { step: null, blocked: null };
     }
     // The admin key was minted but never reached the host. ZITADEL shows a
@@ -1856,9 +1878,16 @@ function planMail(platform, recordedIds, executorBlocked, authReady) {
         recordedIds[PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY] === platform.mail.gitRef &&
         // #177: a mail step applied before this key existed never recorded it, and
         // org steps read it for Agora's mail upstream. Missing means unapplied.
-        recordedIds[PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY]) {
+        recordedIds[PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY] &&
+        recordedIds[PLATFORM_MAIL_ROUTE_SCOPE_KEY] === PLATFORM_MAIL_ROUTE_WANTED) {
         return { step: null, blocked: null };
     }
+    // Only the route is missing: say so, the app is not redeployed.
+    const onlyRouteMissing = recordedIds[key] &&
+        recordedIds[PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY] &&
+        recordedIds[PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY] === platform.mail.hostname &&
+        recordedIds[PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY] === platform.mail.gitRef &&
+        recordedIds[PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY];
     // Stalwart's `x:ApiKey/set` shows a secret once. An id was minted but never
     // reached the host: report it, plan nothing, the same rule {@link planAuth}
     // follows for ZITADEL's own admin key.
@@ -1886,7 +1915,9 @@ function planMail(platform, recordedIds, executorBlocked, authReady) {
                 desired: { hostname: platform.mail.hostname, gitRef: platform.mail.gitRef },
             },
             step: {
-                description: `provision mail (Stalwart) at ${platform.mail.hostname}`,
+                description: onlyRouteMissing
+                    ? `write the mail server's local-delivery route at ${platform.mail.hostname}`
+                    : `provision mail (Stalwart) at ${platform.mail.hostname}`,
                 destroys: false,
                 migrates: false,
             },
@@ -2231,6 +2262,31 @@ function planArchonIdTokenUserinfo(platform, recordedIds, wired) {
         },
     };
 }
+/**
+ * #394, #669: the platform's sign-in org reserves the username `admin` and
+ * switches self-registration off. One `zitadel:sign-in-policy` step keyed
+ * {@link PLATFORM_AUTH_KEY}, planned while either recorded key is missing and
+ * the sign-in's ZITADEL org is recorded. Not planned before that, and not
+ * blocked: nothing is owed until the sign-in exists.
+ */
+function planAuthSignInPolicy(platform, recordedIds, wired) {
+    if (!wired || !platform.auth.enabled)
+        return null;
+    if (!recordedIds[PLATFORM_ZITADEL_ORG_SCOPE_KEY])
+        return null;
+    if (recordedIds[PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY] &&
+        recordedIds[PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY]) {
+        return null;
+    }
+    return {
+        action: { system: 'zitadel', kind: 'sign-in-policy', key: PLATFORM_AUTH_KEY, desired: {} },
+        step: {
+            description: "reserve the username 'admin' and switch self-registration off on the platform's sign-in org",
+            destroys: false,
+            migrates: false,
+        },
+    };
+}
 /**
  * #604: the platform's ZITADEL as a sign-in provider in Cloudflare Access: a
  * ZITADEL client for Cloudflare, then edge's `ensureProvider`. One

package/dist/plan/platform-providers.d.ts

@@ -10,7 +10,7 @@ import type { TunnelPort } from './edge-tunnels.js';
 import type { CloudflarePort, CoolifyPort, FoundryStepExecutorPorts, ZitadelPort } from './executor.js';
 import type { LiveResource, PlatformCloudflareReader, PlatformCoolifyReader } from './live.js';
 import type { PlatformDriftedSteps, PlatformStepExecutionContext, PlatformStepExecutor } from './plan-apply.js';
-import { type BrokerDeployRecord } from './platform-diff.js';
+import { type BrokerDeployRecord, PLATFORM_ZITADEL_ORG_SCOPE_KEY } from './platform-diff.js';
 import { type CallsSfuPlatformDeps } from './platform-sfu.js';
 import { type PlatformUptimeDeps } from './uptime-worker.js';
 /**
@@ -336,6 +336,7 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
         archonRunsInsideApp?: boolean;
         archonDeployRunning?: string;
         archonIdTokenUserinfo?: boolean;
+        authSignInPolicy?: boolean;
     }>;
     /**
      * foundry#542: why the uptime Worker cannot run yet, which optional secrets
@@ -603,8 +604,7 @@ export interface PlatformArchonRuntime {
  * org (`foundry:<orgId>`), with the platform's step key in the org id's place.
  */
 export declare const PLATFORM_ARCHON_ACCESS_APP_NAME = "foundry:platform:archon";
-/** The platform's own ZITADEL org (`foundry`, the one `provisionPlatformAuth` mints its admin user in). */
-export declare const PLATFORM_ZITADEL_ORG_SCOPE_KEY = "zitadel_platform_org";
+export { PLATFORM_ZITADEL_ORG_SCOPE_KEY };
 /** Archon's OIDC client id: public, not a secret, so a plain scope id. */
 export declare const PLATFORM_ARCHON_CLIENT_ID_SCOPE_KEY = "zitadel_platform_archon_client_id";
 /**
@@ -1246,4 +1246,3 @@ export declare function filesPublicHostsValue(publicHosts: string | undefined, s
  * from the declared orgs, for its apply and its drift check alike.
  */
 export declare function filesShareDomains(orgs: readonly DeclaredOrg[]): string[];
-export {};

package/dist/plan/platform-providers.js

@@ -9,7 +9,7 @@ import { ACCESS_POLICY_NAME, getDatabaseStarted, isNotFoundError, isRunningOrSta
 import { ACCESS_PROVIDER_RECORD_KEY, GATE_CLAIM_NAME } from './gates.js';
 import { healthCheckSettings } from './health-check-settings.js';
 import { coolifyDomains, coolifyTunnelDomains, filesShareHostname } from './hostnames.js';
-import { AUTH_ZITADEL_RUN_OPTIONS, JOBS_DEPLOY_PENDING_SCOPE_KEY, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_ACCESS_PROVIDER_APPLIED_AUTH_DOMAIN_SCOPE_KEY, PLATFORM_ACCESS_PROVIDER_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ACCESS_PROVIDER_UNDELIVERED_SCOPE_KEY, PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY, PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_KEY, PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_OPERATOR_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY, PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, PLATFORM_ARCHON_COOLIFY_READ_TOKEN_REF, PLATFORM_ARCHON_DEPLOYMENT_SCOPE_KEY, PLATFORM_ARCHON_ENVS_DEPLOYED_SCOPE_KEY, PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_ID_TOKEN_USERINFO_APPLIED_SCOPE_KEY, PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY, PLATFORM_ARCHON_KEY, PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF, PLATFORM_ARCHON_UPTIME_TOKEN_SYNCED_SCOPE_KEY, PLATFORM_ARCHON_ZITADEL_APP_SCOPE_KEY, PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY, PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY, PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY, PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY, PLATFORM_AUTH_SMTP_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY, PLATFORM_BACKUP_DATABASE_SCOPE_KEYS, PLATFORM_BACKUP_SERVICE_KEYS, PLATFORM_EDGE_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_EDGE_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_PLATFORM_KEY_SET_SCOPE_KEY, PLATFORM_EDGE_PLATFORM_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_HC_API_KEY_REF, PLATFORM_HC_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_HC_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_HC_KEY, PLATFORM_HEARTBEATS_APPLIED_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY, PLATFORM_INTEGRATIONS_KEY_ID_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_ROTATION_PREVIOUS_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_ROTATION_REQUESTED_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_ROTATION_UNDELIVERED_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_INTEGRATIONS_RUNNER_KEYRING_DEPLOYED_SCOPE_KEY, PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY, PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_SFU_APPLIED_SCOPE_KEY, PLATFORM_UPTIME_ACCESS_CLIENT_ID_REF, PLATFORM_UPTIME_ACCESS_CLIENT_SECRET_REF, PLATFORM_UPTIME_ACCESS_TOKEN_ID_SCOPE_KEY, PLATFORM_UPTIME_ACCESS_TOKEN_NAME, PLATFORM_UPTIME_ACCESS_UNDELIVERED_SCOPE_KEY, PLATFORM_UPTIME_HEARTBEAT_CHECK_NAME, PLATFORM_UPTIME_KEY, PLATFORM_UPTIME_REMOVED_SCOPE_KEY, PLATFORM_UPTIME_SCRIPT_NAME, PLATFORM_UPTIME_TOKEN_ID_SCOPE_KEY, PLATFORM_UPTIME_TOKEN_REF, archonBootstrapOperator, desiredHeartbeatCheckNames, heartbeatCheckUrlRef, parseBrokerDeployRecord, parseLoginClientRecord, platformBackupHeartbeatCheckName, platformMailMxHost, uptimeAccessTokenConflict, uptimeRecorded, uptimeVarsDigest, } from './platform-diff.js';
+import { AUTH_ZITADEL_RUN_OPTIONS, JOBS_DEPLOY_PENDING_SCOPE_KEY, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_ACCESS_PROVIDER_APPLIED_AUTH_DOMAIN_SCOPE_KEY, PLATFORM_ACCESS_PROVIDER_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ACCESS_PROVIDER_UNDELIVERED_SCOPE_KEY, PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY, PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_KEY, PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_OPERATOR_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY, PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, PLATFORM_ARCHON_COOLIFY_READ_TOKEN_REF, PLATFORM_ARCHON_DEPLOYMENT_SCOPE_KEY, PLATFORM_ARCHON_ENVS_DEPLOYED_SCOPE_KEY, PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_ID_TOKEN_USERINFO_APPLIED_SCOPE_KEY, PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY, PLATFORM_ARCHON_KEY, PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF, PLATFORM_ARCHON_UPTIME_TOKEN_SYNCED_SCOPE_KEY, PLATFORM_ARCHON_ZITADEL_APP_SCOPE_KEY, PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY, PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY, PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY, PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY, PLATFORM_AUTH_SMTP_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY, PLATFORM_BACKUP_DATABASE_SCOPE_KEYS, PLATFORM_BACKUP_SERVICE_KEYS, PLATFORM_EDGE_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_EDGE_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_PLATFORM_KEY_SET_SCOPE_KEY, PLATFORM_EDGE_PLATFORM_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_HC_API_KEY_REF, PLATFORM_HC_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_HC_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_HC_KEY, PLATFORM_HEARTBEATS_APPLIED_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY, PLATFORM_INTEGRATIONS_KEY_ID_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_ROTATION_PREVIOUS_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_ROTATION_REQUESTED_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_ROTATION_UNDELIVERED_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_INTEGRATIONS_RUNNER_KEYRING_DEPLOYED_SCOPE_KEY, PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY, PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ROUTE_SCOPE_KEY, PLATFORM_MAIL_ROUTE_WANTED, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_SFU_APPLIED_SCOPE_KEY, PLATFORM_UPTIME_ACCESS_CLIENT_ID_REF, PLATFORM_UPTIME_ACCESS_CLIENT_SECRET_REF, PLATFORM_UPTIME_ACCESS_TOKEN_ID_SCOPE_KEY, PLATFORM_UPTIME_ACCESS_TOKEN_NAME, PLATFORM_UPTIME_ACCESS_UNDELIVERED_SCOPE_KEY, PLATFORM_UPTIME_HEARTBEAT_CHECK_NAME, PLATFORM_UPTIME_KEY, PLATFORM_UPTIME_REMOVED_SCOPE_KEY, PLATFORM_UPTIME_SCRIPT_NAME, PLATFORM_UPTIME_TOKEN_ID_SCOPE_KEY, PLATFORM_UPTIME_TOKEN_REF, PLATFORM_ZITADEL_ORG_SCOPE_KEY, archonBootstrapOperator, desiredHeartbeatCheckNames, heartbeatCheckUrlRef, parseBrokerDeployRecord, parseLoginClientRecord, platformBackupHeartbeatCheckName, platformMailMxHost, uptimeAccessTokenConflict, uptimeRecorded, uptimeVarsDigest, } from './platform-diff.js';
 import { applyCallsSfuPlatformStep, callsSfuAppliedFingerprint, } from './platform-sfu.js';
 import { heldUptimeValues, provisionPlatformUptime, } from './uptime-worker.js';
 import { CreateInstanceError, createZitadelInstance, generateSystemApiKeypair, instanceWithoutBearerMessage, systemApiUsersEnv, } from './zitadel-system-api.js';
@@ -365,6 +365,16 @@ export class FoundryPlatformStepExecutor {
                 console.error(`platform:archon: could not reach the platform's ZITADEL client to plan the ID token repair: ${e instanceof Error ? e.message : String(e)}`);
             }
         }
+        // Not a block: without the auth dependencies and a ZITADEL client for the instance the sign-in policy step is not planned.
+        if (this.auth && platform.auth.enabled && recordedIds[PLATFORM_ZITADEL_ORG_SCOPE_KEY]) {
+            try {
+                this.auth.zitadelForInstance?.(`https://${platform.auth.hostname}`);
+                blocked.authSignInPolicy = true;
+            }
+            catch (e) {
+                console.error(`platform:auth: could not reach the platform's ZITADEL client to plan the sign-in policy: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
         // Not a block: tells the planner to order Archon's step last (`PlanPlatformOptions.blocked.archonRunsInsideApp`).
         if (this.archon?.runsInsideApp) {
             blocked.archonRunsInsideApp = true;
@@ -608,6 +618,14 @@ export class FoundryPlatformStepExecutor {
             }
             return switchOnArchonIdTokenUserinfo(context, this.archon);
         }
+        if (action.system === 'zitadel' &&
+            action.kind === 'sign-in-policy' &&
+            action.key === PLATFORM_AUTH_KEY) {
+            if (!this.auth) {
+                throw new Error('platform:auth needs FoundryPlatformStepExecutor to be constructed with its auth dependencies (#168)');
+            }
+            return applyPlatformSignInPolicy(context, this.auth);
+        }
         if (action.system === 'cloudflare' && action.kind === 'access-provider') {
             if (!this.accessProvider) {
                 throw new Error('cloudflare:access-provider needs FoundryPlatformStepExecutor to be constructed with its Access provider dependencies (#604)');
@@ -1820,29 +1838,47 @@ async function provisionPlatformAuth(context, deps, owners = []) {
             }
         }
     }
-    // ---- reserved username and closed registration, once each (#394) ----------
-    // Outside the blocks above so a platform applied before this existed gets
-    // it on its next apply; `planAuth` plans the step until both keys exist.
-    // Last, so a failure here holds up neither the SMTP provider nor the invite.
-    const policyRecorded = context.recordedIds();
-    if (!policyRecorded[PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY] ||
-        !policyRecorded[PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY]) {
-        const policyZitadel = deps.zitadelForInstance?.(`https://${hostname}`) ?? deps.zitadel;
-        let policyOrgId = policyRecorded[PLATFORM_ZITADEL_ORG_SCOPE_KEY];
-        if (!policyOrgId) {
-            policyOrgId = (await policyZitadel.findOrCreateOrg(PLATFORM_AUTH_ORG_NAME)).org.id;
-            await record(PLATFORM_ZITADEL_ORG_SCOPE_KEY, policyOrgId);
+    return { resourceId: zitadelAppId };
+}
+/**
+ * Reserves the username `admin` and switches self-registration off in the
+ * platform's sign-in org (`zitadel:sign-in-policy` keyed {@link PLATFORM_AUTH_KEY}).
+ * Each call records its own key right after it succeeds, so a failure in the
+ * second leaves the first recorded and throws; the next plan names the step
+ * again. The error names the org only, never the cause.
+ */
+async function applyPlatformSignInPolicy(context, deps) {
+    const { platform } = context;
+    const recorded = context.recordedIds();
+    const orgId = recorded[PLATFORM_ZITADEL_ORG_SCOPE_KEY];
+    if (!orgId) {
+        throw new Error("platform:auth: the sign-in's ZITADEL org is not recorded yet -- cannot reserve the admin username or close registration");
+    }
+    const zitadel = deps.zitadelForInstance?.(`https://${platform.auth.hostname}`) ?? deps.zitadel;
+    const record = async (key, value) => {
+        context.recordScopeId(key, value);
+        await context.persist?.();
+    };
+    if (!recorded[PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY]) {
+        let userId;
+        try {
+            ({ userId } = await zitadel.reserveUserName(orgId, PLATFORM_AUTH_RESERVED_USERNAME));
         }
-        if (!policyRecorded[PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY]) {
-            const { userId } = await policyZitadel.reserveUserName(policyOrgId, PLATFORM_AUTH_RESERVED_USERNAME);
-            await record(PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY, userId);
+        catch {
+            throw new Error(`platform:auth: reserving the username '${PLATFORM_AUTH_RESERVED_USERNAME}' failed in ZITADEL org ${orgId}`);
         }
-        if (!policyRecorded[PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY]) {
-            await policyZitadel.closeSelfRegistration(policyOrgId);
-            await record(PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY, 'closed');
+        await record(PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY, userId);
+    }
+    if (!recorded[PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY]) {
+        try {
+            await zitadel.closeSelfRegistration(orgId);
         }
+        catch {
+            throw new Error(`platform:auth: closing self-registration failed in ZITADEL org ${orgId}`);
+        }
+        await record(PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY, 'closed');
     }
-    return { resourceId: zitadelAppId };
+    return {};
 }
 /** Lettermint's SMTP relay, as ZITADEL's SMTP provider wants it: `host:port`, STARTTLS. */
 const PLATFORM_AUTH_SMTP_HOST = 'smtp.lettermint.co:587';
@@ -2326,7 +2362,10 @@ async function provisionPlatformMail(context, deps) {
     const { project } = await zitadel.findOrCreateProject(org.id, PLATFORM_MAIL_ZITADEL_PROJECT_NAME);
     const recordedProjectId = recorded[PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY];
     const adminKeyRecorded = Boolean(recorded[PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY]);
-    if (adminKeyRecorded && recordedProjectId !== project.id) {
+    // #661: a platform applied before the local-delivery route existed gets it
+    // here, over the same recovery-admin credential, and mints nothing.
+    const routeRecorded = recorded[PLATFORM_MAIL_ROUTE_SCOPE_KEY] === PLATFORM_MAIL_ROUTE_WANTED;
+    if (adminKeyRecorded && (recordedProjectId !== project.id || !routeRecorded)) {
         // #346 round 3: the OIDC-directory write below (next block) runs only
         // once, while the admin key is unrecorded -- so once it is recorded, a
         // changed project id (the project was deleted and recreated, ZITADEL was
@@ -2366,6 +2405,7 @@ async function provisionPlatformMail(context, deps) {
                 },
             });
             await record(PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, project.id);
+            await record(PLATFORM_MAIL_ROUTE_SCOPE_KEY, PLATFORM_MAIL_ROUTE_WANTED);
         }
         catch (error) {
             throw redactedMailError(error, [password]);
@@ -2405,6 +2445,7 @@ async function provisionPlatformMail(context, deps) {
                     oidc: { issuerUrl: issuer, audience: project.id },
                 },
             });
+            await record(PLATFORM_MAIL_ROUTE_SCOPE_KEY, PLATFORM_MAIL_ROUTE_WANTED);
             // Recorded and persisted before the secret leaves this function: if
             // delivery fails for good, the next plan reports the lost key rather
             // than skipping or minting again.
@@ -2718,9 +2759,8 @@ const PLATFORM_ARCHON_PROJECT_SCOPE_KEY = 'coolify_project_platform_archon';
 const PLATFORM_ARCHON_DB_SCOPE_KEY = 'coolify_platform_archon_database';
 const PLATFORM_ARCHON_TUNNEL_SCOPE_KEY = 'cloudflare_platform_archon_tunnel';
 const PLATFORM_ARCHON_ACCESS_SCOPE_KEY = 'cloudflare_platform_archon_access_app';
-/** The platform's own ZITADEL org (`foundry`, the one `provisionPlatformAuth` mints its admin user in). */
-export const PLATFORM_ZITADEL_ORG_SCOPE_KEY = 'zitadel_platform_org';
 const PLATFORM_ARCHON_ZITADEL_PROJECT_SCOPE_KEY = 'zitadel_platform_archon_project';
+export { PLATFORM_ZITADEL_ORG_SCOPE_KEY };
 /** The hostname the sign-in client's redirect URIs were made for; a change makes a new client. */
 const PLATFORM_ARCHON_CLIENT_HOSTNAME_SCOPE_KEY = 'zitadel_platform_archon_client_hostname';
 /** Archon's OIDC client id: public, not a secret, so a plain scope id. */

package/dist/plan/version-status.d.ts

@@ -21,8 +21,7 @@ import type { VersionChangeItem } from '../plan.js';
  * `coolifyApplicationUuid` is the id `plan/diff.ts`'s `appStepKey` keys an
  * org's hosting entry under in `AppliedState.serviceIds`
  * (`` `coolify:app:${appStepKey(org, entry.key)}` ``, `org.ts`); `repo` is
- * `HostingEntry.repo`, falling back to whatever default an app with none
- * declared resolves to (`plan/executor.ts`'s own `DEFAULT_APP_REPO`).
+ * `HostingEntry.repo`.
  */
 export interface OrgAppVersionRef {
     orgId: OrgId;

package/dist/plan.d.ts

@@ -99,4 +99,16 @@ export interface VersionChangeItem {
     /** The service this line is about, e.g. 'mail', 'archon', 'zitadel'. */
     service: string;
     description: string;
+    /** The version running or last applied; absent when that is unknown. */
+    from?: string;
+    /** The version the declaration or the foundry pin now asks for. */
+    to?: string;
+    /**
+     * True when `apply` and `applyPlatform` refuse the plan until
+     * `confirmUpgrade` names {@link service}: any change on a stateful service
+     * (`plan/confirm-upgrade.ts`), or a major or minor jump on any service. An
+     * unknown running version is never a change, so it is false. So is a line
+     * `apply` does not act on ("not applied by foundry").
+     */
+    needsConfirmation: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",
@@ -45,7 +45,7 @@
     "@wtfalch/audit": "0.6.0",
     "@wtfalch/auth": "0.16.0",
     "@wtfalch/edge": "0.12.0",
-    "@wtfalch/email": "^0.17.0",
+    "@wtfalch/email": "^0.20.0",
     "@wtfalch/providers": "0.7.5",
     "ssh2": "1.17.0",
     "zod": "4.6.5"