@wtfalch/foundry 0.34.0 → 0.35.2

package/dist/plan/platform-diff.js

@@ -2,10 +2,12 @@ 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 { buildDriftNotes } from './build-record.js';
 import { versionChangeNeedsConfirmation } from './confirm-upgrade.js';
 import { ACCESS_PROVIDER_RECORD_KEY } from './gates.js';
 import { legacyAppHostname } from './hostnames.js';
 import { PLATFORM_MAIL_RELAY_KEY, planMailRelay } from './mail-relay.js';
+import { planOikosIngress } from './oikos-ingress.js';
 import { callsSfuAppliedFingerprint } from './platform-sfu.js';
 import { ZITADEL_ORG_DOMAIN_BLOCKED_SCOPE_KEY, signInDomainBlockedText } from './sign-in-org.js';
 import { withStepSystem } from './step-system.js';
@@ -219,15 +221,16 @@ export const PLATFORM_ARCHON_APPLIED_AUTH_ORG_SCOPE_KEY = 'archon_applied_auth_o
  */
 export const PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY = 'archon_applied_rolling_update';
 /**
- * The sign-in org Archon accepts: the platform owner company's own
- * ({@link PLATFORM_OWNER_ORG_SCOPE_KEY}), else the platform's `foundry` org for
- * a platform with no owner company declared. Undefined when neither is recorded.
+ * The owner company's sign-in hostname Archon was last registered under, and
+ * the owner's files host (`<internalUrl>|<audience>`, or `none`) its env was
+ * last written with. `planArchon` plans the step again when either differs
+ * from the owner's current ones (a marker never recorded reads as `none`).
  */
-export function archonAuthOrganizationId(recorded) {
-    const owner = recorded[PLATFORM_OWNER_ORG_SCOPE_KEY];
-    if (owner && owner !== 'none')
-        return owner;
-    return recorded[PLATFORM_ZITADEL_ORG_SCOPE_KEY] || undefined;
+export const PLATFORM_ARCHON_APPLIED_AUTH_HOSTNAME_SCOPE_KEY = 'archon_applied_auth_hostname';
+export const PLATFORM_ARCHON_APPLIED_FILES_SCOPE_KEY = 'archon_applied_files';
+/** The value {@link PLATFORM_ARCHON_APPLIED_FILES_SCOPE_KEY} records for the owner's files host. */
+export function archonFilesMarker(files) {
+    return files ? `${files.internalUrl}|${files.audience}` : 'none';
 }
 /**
  * #175: set to '1' before the step points the tunnel at `http_status:404`
@@ -609,8 +612,78 @@ export function serviceDbEnvAppliedScopeKey(service) {
 export function zitadelAppIdTokenUserinfoAppliedScopeKey(appKey) {
     return `zitadel_app_id_token_userinfo_applied.${appKey}`;
 }
-/** The ZITADEL app id of Archon's sign-in client in the platform's own ZITADEL. */
+/**
+ * Archon's own sign-in organisation, in the owner company's ZITADEL instance
+ * and apart from the organisation that holds the company's people (and Boule's
+ * sign-in). Made by the `zitadel:archon-org` step, which runs before
+ * `platform:archon`. The first six keys below are the step's own progress:
+ * each is recorded only after its call succeeded.
+ */
+export const PLATFORM_ARCHON_ORG_SCOPE_KEY = 'zitadel_platform_archon_org';
+/** The primary domain registered on Archon's sign-in organisation. */
+export const PLATFORM_ARCHON_ORG_DOMAIN_SCOPE_KEY = 'zitadel_platform_archon_org_domain';
+/** The domain the sign-in server refused to make primary; set instead of failing, reported as blocked. */
+export const PLATFORM_ARCHON_ORG_DOMAIN_BLOCKED_SCOPE_KEY = 'zitadel_platform_archon_org_domain_blocked';
+/** The Archon org id once self-registration is closed on it. */
+export const PLATFORM_ARCHON_ORG_REGISTRATION_CLOSED_SCOPE_KEY = 'zitadel_platform_archon_org_registration_closed';
+/** The Archon org id once its login policy forces a second factor. */
+export const PLATFORM_ARCHON_ORG_POLICY_SCOPE_KEY = 'zitadel_platform_archon_org_policy';
+/** The first person's user id in the Archon org (`none` when no owner is declared), recorded once the invite was mailed. */
+export const PLATFORM_ARCHON_OWNER_INVITE_SCOPE_KEY = 'zitadel_platform_archon_owner_invite';
+/** The Archon org the recorded invite was made in. */
+export const PLATFORM_ARCHON_OWNER_INVITE_ORG_SCOPE_KEY = 'zitadel_platform_archon_owner_invite_org';
+/** The name of the Archon sign-in organisation: `<owner slug>-archon`. */
+export function archonOrgName(ownerSlug) {
+    return `${ownerSlug}-archon`;
+}
+/** The primary domain of the Archon sign-in organisation: `archon.` before the owner's own sign-in domain. */
+export function archonOrgDomain(ownerSignInDomain) {
+    return `archon.${ownerSignInDomain}`;
+}
+/**
+ * The CI organisation id the last Archon apply wrote as `CI_ORGANIZATION_ID`,
+ * and the `ARCHON_FIRST_OWNER_LINK` value it wrote (empty when none).
+ * `planArchon` plans the step again when either differs from what is wanted.
+ */
+export const PLATFORM_ARCHON_APPLIED_CI_ORG_SCOPE_KEY = 'archon_applied_ci_org';
+export const PLATFORM_ARCHON_APPLIED_FIRST_OWNER_LINK_SCOPE_KEY = 'archon_applied_first_owner_link';
+/**
+ * `<archonUserId>:<ciUserId>`: the first person in both organisations, which
+ * Archon seeds its link table from. Empty when either id is not known (no
+ * owner declared, or the CI-side account not recorded yet).
+ */
+export function archonFirstOwnerLink(recordedIds, ownerSignIn) {
+    const archonUserId = recordedIds[PLATFORM_ARCHON_OWNER_INVITE_SCOPE_KEY];
+    const ciUserId = ownerSignIn?.firstOwnerUserId;
+    if (!archonUserId || archonUserId === 'none' || !ciUserId || ciUserId === 'none')
+        return '';
+    return `${archonUserId}:${ciUserId}`;
+}
+/**
+ * The one-time-PIN provider id the Archon Access app was last made with.
+ * Drift is read against it, because a plan must not ask edge to find or make
+ * the provider.
+ */
+export const PLATFORM_ARCHON_ACCESS_PIN_SCOPE_KEY = 'cloudflare_platform_archon_access_pin';
+/**
+ * The Archon org the `AUTH_APP_KEY` in Archon's env was minted for. A key
+ * minted for another org (the CI org, before the move) is replaced by a fresh
+ * one, so the key the CI-org broker entry held stops being Archon's.
+ */
+export const PLATFORM_ARCHON_APP_KEY_ORG_SCOPE_KEY = 'archon_app_key_org';
+/**
+ * `<org>|<project>|<app>` of Archon's old sign-in client while it still waits
+ * to be deleted. Set before the new client's ids overwrite the recorded ones,
+ * cleared once the old client is gone.
+ */
+export const PLATFORM_ARCHON_RETIRED_CLIENT_SCOPE_KEY = 'zitadel_platform_archon_retired_client';
+/** The ZITADEL app id of Archon's sign-in client in the owner company's ZITADEL. */
 export const PLATFORM_ARCHON_ZITADEL_APP_SCOPE_KEY = 'zitadel_platform_archon_app';
+/** The ZITADEL project id Archon's sign-in client lives in. */
+export const PLATFORM_ARCHON_ZITADEL_PROJECT_SCOPE_KEY = 'zitadel_platform_archon_project';
+/** The ZITADEL project and client ids of the Access sign-in provider, in the owner company's ZITADEL. */
+export const PLATFORM_ACCESS_ZITADEL_PROJECT_SCOPE_KEY = 'zitadel_platform_access_project';
+export const PLATFORM_ACCESS_ZITADEL_APP_SCOPE_KEY = 'zitadel_platform_access_app';
 /**
  * The ZITADEL app id of Archon's sign-in client once "user info inside the
  * ID token" was switched on for it. `planArchonIdTokenUserinfo` plans the
@@ -674,7 +747,7 @@ export function appliedAppDomains(org, recorded, entryKey) {
  * `coolifyApp` records as applied, so a declared change replans and no secret
  * is written into it.
  */
-export function resolveAppEnv(org, entry, recorded, available = { platformMailKey: false, sharedSecret: false }) {
+export function resolveAppEnv(org, entry, recorded, available = { sharedSecret: false }) {
     const sources = {
         filesOrganisationId: recorded[`files:organisation:${org.id}`],
         aiOrganisationId: recorded[`ai:organisation:${org.id}`],
@@ -686,15 +759,6 @@ export function resolveAppEnv(org, entry, recorded, available = { platformMailKe
     const unresolvedSecrets = [];
     const marker = {};
     for (const [name, declared] of Object.entries(entry.env).sort(([a], [b]) => (a < b ? -1 : 1))) {
-        if (typeof declared !== 'string' && declared.from === 'platformMailKey') {
-            if (available.platformMailKey) {
-                secrets.push({ name, source: 'platformMailKey' });
-                marker[name] = 'secret:platformMailKey';
-            }
-            else
-                unresolvedSecrets.push([name, 'platformMailKey']);
-            continue;
-        }
         if (typeof declared !== 'string' && declared.from === 'sharedSecret') {
             const label = `sharedSecret ${declared.name}`;
             if (available.sharedSecret) {
@@ -729,6 +793,13 @@ export const PLATFORM_AI_KEY = 'platform:ai';
  * public hostname. Holds whichever way the public-hostname decision goes.
  */
 export const PLATFORM_AI_INTERNAL_URL_SCOPE_KEY = 'ai_platform_internal_url';
+/**
+ * The id of the tunnel that carries the AI host's public hostname. Recorded once the tunnel, its
+ * connector and the DNS record are in place; an entry is given `AI_URL` only after it.
+ */
+export const PLATFORM_AI_TUNNEL_SCOPE_KEY = 'cloudflare_platform_ai_tunnel';
+/** The one Coolify app that runs `cloudflared` for the AI tunnel. */
+export const PLATFORM_AI_CONNECTOR_APP_SCOPE_KEY = 'coolify_platform_ai_connector_app';
 /**
  * #172: the same two-key discipline as the ZITADEL admin key above, for
  * foundry's AI management key (the bearer key `ai:organisation`, `ai:budget`
@@ -935,6 +1006,18 @@ export const PLATFORM_HC_APPLIED_GIT_REF_SCOPE_KEY = 'hc_applied_git_ref';
  * and that implementation is where the key is actually used.
  */
 export const PLATFORM_HC_API_KEY_REF = 'hc:platform:apiKey';
+/**
+ * foundry#544: the held-key ref a human puts the *outside* Healthchecks
+ * account's project API key under, read only while
+ * `platform.heartbeatsProvider` is `'hosted'` -- {@link PLATFORM_HC_API_KEY_REF}'s
+ * own ref is for the self-hosted instance only, and the two are never
+ * conflated: switching provider needs its own key held under its own ref,
+ * never the other one silently reused. Same "this package never reads the
+ * value back" rule as {@link PLATFORM_HC_API_KEY_REF}'s own doc comment --
+ * whoever implements {@link HeartbeatsPort} against the outside service is
+ * the host.
+ */
+export const PLATFORM_HEARTBEATS_HOSTED_API_KEY_REF = 'heartbeats:platform:hostedApiKey';
 /**
  * #540: the heartbeat check named after the uptime Worker (foundry#542,
  * which is what actually pings it -- blocked today on edge#26, so nothing
@@ -1134,7 +1217,7 @@ export function uptimeRecorded(recordedIds) {
  * unchanged).
  */
 export function planPlatform(platform, live, options = {}) {
-    const { jobsObservable = true, sfuBlocked = null, callsOrgSlugs, mailRoutes = [], mailPlatformDomains = [], mailRoutesBlocked = [], recordedIds = {}, blocked = {}, drifted = {}, } = options;
+    const { jobsObservable = true, sfuBlocked = null, callsOrgSlugs, mailRoutes = [], mailRoutesBlocked = [], recordedIds = {}, owner, liveBuilds = {}, blocked = {}, drifted = {}, } = options;
     const byKey = new Map(live.map((r) => [resourceKey(r.system, r.kind, r.key), r]));
     const claimed = new Set();
     const plannedSteps = [];
@@ -1169,6 +1252,15 @@ export function planPlatform(platform, live, options = {}) {
         : (service) => `the platform's ${service} is blocked, not planned: every DNS record is written through edge, and edge is neither applied nor planned (${platform.edge.enabled
             ? (edge.blocked ?? 'its step is not planned')
             : 'the platform does not enable edge'})`;
+    // The shared oikos.host ingress: after edge, whose DNS and tunnel calls it uses.
+    const oikosIngress = planOikosIngress(platform, recordedIds, {
+        // Only once edge is APPLIED: the zone check in `blockedSteps` needs edge's address, so a
+        // same-round plan would apply unchecked and throw on a missing zone.
+        edgeApplied,
+        executorBlocked: blocked.oikosIngress,
+    });
+    if (oikosIngress.step)
+        plannedSteps.push(oikosIngress.step);
     // #540: hc needs only edge's DNS, the same as mail and archon -- no
     // auth/ZITADEL client, so it is planned here rather than after `authReady`
     // further down.
@@ -1203,27 +1295,27 @@ export function planPlatform(platform, live, options = {}) {
     // mail step that gives the port up.
     const relay = planMailRelay(platform, recordedIds, {
         routes: mailRoutes,
-        platformDomains: mailPlatformDomains,
         executorBlocked: blocked.relay,
-        mailReady: mail.step !== null ||
-            (Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_MAIL_KEY)]) &&
-                mailPortsApplied(platform, recordedIds)),
     });
     if (relay.step)
         plannedSteps.push(relay.step);
     // #172: a throw halts every step after it, so this one goes late.
-    const ai = planAi(platform, recordedIds, blocked.ai);
+    const ai = planAi(platform, recordedIds, blocked.ai ?? dnsBlocked?.('AI host'));
     if (ai.step)
         plannedSteps.push(ai.step);
     // #604: after edge and sign-in, whose applied ids it reads; before Archon,
     // whose redeploy can end the run.
-    const accessProvider = planAccessProvider(platform, recordedIds, blocked.accessProvider);
+    const accessProvider = planAccessProvider(platform, recordedIds, blocked.accessProvider, owner?.signIn ?? null);
     if (accessProvider.step)
         plannedSteps.push(accessProvider.step);
+    // Archon's own sign-in organisation: before Archon, whose client, env and broker entry live in it.
+    const archonOrg = planArchonOrg(platform, recordedIds, blocked.archonOrg, blocked.archonOrgInvite, owner?.signIn ?? null);
+    if (archonOrg.step)
+        plannedSteps.push(archonOrg.step);
     // #175: last, on purpose. Archon's sign-in client lives in the sign-in
     // `planAuth` builds, and its env reads what every other service's step
     // records or delivers, so in one apply it runs after all of them.
-    const archon = planArchon(platform, recordedIds, blocked.archon ?? dnsBlocked?.('Archon'), authReady, drifted.archon, blocked.archonDeployRunning);
+    const archon = planArchon(platform, recordedIds, blocked.archon ?? dnsBlocked?.('Archon'), owner?.signIn ?? null, owner?.files ?? null, drifted.archon, blocked.archonDeployRunning, { step: archonOrg.step !== null, blocked: archonOrg.blocked });
     // The host runs inside this app: its step ends by redeploying the process
     // that runs the plan, so it goes after everything else (pushed below).
     if (archon.step && !blocked.archonRunsInsideApp)
@@ -1328,11 +1420,17 @@ export function planPlatform(platform, live, options = {}) {
         unmanaged.push({ description: ai.blocked, key: 'ai' });
     if (edge.blocked)
         unmanaged.push({ description: edge.blocked, key: 'edge' });
+    // Edge's own blocked reason, just above, already names the cause when edge is what is missing.
+    if (oikosIngress.blocked && !edge.blocked) {
+        unmanaged.push({ description: oikosIngress.blocked, key: 'oikos-ingress' });
+    }
     if (accessProvider.blocked) {
         unmanaged.push({ description: accessProvider.blocked, key: 'access-provider' });
     }
     if (hc.blocked)
         unmanaged.push({ description: hc.blocked, key: 'hc' });
+    if (archonOrg.blocked)
+        unmanaged.push({ description: archonOrg.blocked, key: 'archon-org' });
     if (archon.blocked)
         unmanaged.push({ description: archon.blocked, key: 'archon' });
     // #398: the old integrations key stays pinned until Archon holds the new
@@ -1355,7 +1453,7 @@ export function planPlatform(platform, live, options = {}) {
         plannedSteps: plannedSteps.map(withStepSystem),
         unmanaged,
         versionChanges,
-        notes: uptime.notes,
+        notes: [...uptime.notes, ...buildDriftNotes(recordedIds, liveBuilds)],
     };
 }
 /**
@@ -1492,19 +1590,13 @@ function planJobs(platform, byKey, claimed, observable, recordedIds) {
  * never a wrong step.
  */
 export const PLATFORM_BACKUP_DATABASE_SCOPE_KEYS = {
-    jobs: 'coolify_jobs_database',
-    auth: 'coolify_platform_auth_database',
     archon: 'coolify_platform_archon_database',
     ai: 'coolify_platform_ai_database',
-    files: 'coolify_platform_files_database',
     integrations: 'coolify_integrations_database',
 };
 export const PLATFORM_BACKUP_SERVICE_KEYS = [
-    'jobs',
-    'auth',
     'archon',
     'ai',
-    'files',
     'integrations',
 ];
 /**
@@ -2383,16 +2475,16 @@ function planAuthSignInPolicy(platform, recordedIds, wired) {
  * delivered (its secret cannot be shown again), or `executorBlocked` (no
  * dependencies, or edge cannot confirm Access is ready).
  */
-function planAccessProvider(platform, recordedIds, executorBlocked) {
-    if (!platform.edge.enabled || !platform.auth.enabled)
+function planAccessProvider(platform, recordedIds, executorBlocked, ownerSignIn) {
+    if (!platform.edge.enabled)
         return { step: null, blocked: null };
     if (recordedIds[ACCESS_PROVIDER_RECORD_KEY]) {
         // The secret is not stored, so a changed address cannot be re-sent: a person remakes the client.
         const appliedHostname = recordedIds[PLATFORM_ACCESS_PROVIDER_APPLIED_HOSTNAME_SCOPE_KEY];
-        if (appliedHostname && appliedHostname !== platform.auth.hostname) {
+        if (ownerSignIn && appliedHostname && appliedHostname !== ownerSignIn.hostname) {
             return {
                 step: null,
-                blocked: `the Access sign-in provider is blocked, not planned: it was applied with the sign-in hostname ${appliedHostname} and ${platform.auth.hostname} is declared now; its secret is not stored, so delete the ZITADEL client cloudflare-access, remove the recorded keys ${ACCESS_PROVIDER_RECORD_KEY}, ${PLATFORM_ACCESS_PROVIDER_APPLIED_HOSTNAME_SCOPE_KEY} and ${PLATFORM_ACCESS_PROVIDER_APPLIED_AUTH_DOMAIN_SCOPE_KEY}, then apply again`,
+                blocked: `the Access sign-in provider is blocked, not planned: it was applied with the sign-in hostname ${appliedHostname} and ${ownerSignIn.hostname} is the owner company's now; its secret is not stored, so delete the ZITADEL client cloudflare-access, remove the recorded keys ${ACCESS_PROVIDER_RECORD_KEY}, ${PLATFORM_ACCESS_PROVIDER_APPLIED_HOSTNAME_SCOPE_KEY} and ${PLATFORM_ACCESS_PROVIDER_APPLIED_AUTH_DOMAIN_SCOPE_KEY}, then apply again`,
             };
         }
         return { step: null, blocked: null };
@@ -2404,15 +2496,10 @@ function planAccessProvider(platform, recordedIds, executorBlocked) {
             blocked: `the Access sign-in provider is blocked, not planned: its ZITADEL client (${undelivered}) was made and its secret may or may not have reached edge; it cannot be shown again, so delete that client in ZITADEL and remove the recorded keys ${PLATFORM_ACCESS_PROVIDER_UNDELIVERED_SCOPE_KEY} and ${ACCESS_PROVIDER_RECORD_KEY}, then apply again to make both anew`,
         };
     }
-    const applied = Boolean(recordedIds[PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY]) &&
-        Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_AUTH_KEY)]) &&
-        // The sibling ZITADEL steps need the delivered admin key (or the instance it came from).
-        (Boolean(recordedIds[PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY]) ||
-            Boolean(recordedIds[PLATFORM_AUTH_INSTANCE_SCOPE_KEY]));
-    if (!applied) {
+    if (!ownerSignIn || !recordedIds[PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY]) {
         return {
             step: null,
-            blocked: 'the Access sign-in provider is blocked, not planned: edge and the platform sign-in are not both applied yet',
+            blocked: "the Access sign-in provider is blocked, not planned: edge and the owner company's sign-in are not both applied yet",
         };
     }
     if (executorBlocked)
@@ -2421,7 +2508,7 @@ function planAccessProvider(platform, recordedIds, executorBlocked) {
         step: {
             action: { system: 'cloudflare', kind: 'access-provider', key: 'platform', desired: {} },
             step: {
-                description: "make the platform's ZITADEL the sign-in provider in Cloudflare Access, for company gates",
+                description: "make the owner company's ZITADEL the sign-in provider in Cloudflare Access, for company gates",
                 destroys: false,
                 migrates: false,
             },
@@ -2511,9 +2598,24 @@ function planHc(platform, recordedIds, executorBlocked) {
  * with. Without this, a fresh platform's heartbeats step is ready
  * (`hcReady`) the same round `hc` is merely *planned*, long before anyone
  * has signed in to it to create that key.
+ *
+ * foundry#544: `platform.heartbeatsProvider === 'hosted'` skips the two
+ * checks above that are specific to the self-hosted server (`platform.hc.enabled`,
+ * `hcReady`) -- the outside service needs neither `hc` declared nor applied.
+ * `apiKeyMissing` still applies in both cases, but names a different ref
+ * depending on the provider (the caller, `platform-providers.ts`'s
+ * `blockedSteps`, resolves the right one before calling this). `desired`
+ * folds the provider in alongside the check names, so switching provider
+ * with the same checks otherwise desired is still a change from the last
+ * recorded marker -- the step plans again, creating every check fresh on
+ * the newly-chosen provider (`provisionPlatformHeartbeats` lists the new
+ * provider's own live checks, sees none of foundry's names yet, and creates
+ * all of them) rather than reading "nothing left to reconcile" against a
+ * marker that was true of the *other* provider.
  */
 function planHeartbeats(platform, recordedIds, hcReady, executorMissing, apiKeyMissing) {
-    if (!platform.hc.enabled) {
+    const hosted = platform.heartbeatsProvider === 'hosted';
+    if (!hosted && !platform.hc.enabled) {
         // Removing checks is not planned. The recorded marker names the checks
         // foundry's last reconcile wanted, so they are foundry's own; report
         // them rather than leave them unseen.
@@ -2525,7 +2627,7 @@ function planHeartbeats(platform, recordedIds, hcReady, executorMissing, apiKeyM
                 : null,
         };
     }
-    if (!hcReady) {
+    if (!hosted && !hcReady) {
         return {
             step: null,
             blocked: 'the heartbeat checks are blocked, not planned: platform:hc has not been applied yet',
@@ -2540,10 +2642,12 @@ function planHeartbeats(platform, recordedIds, hcReady, executorMissing, apiKeyM
     if (apiKeyMissing) {
         return {
             step: null,
-            blocked: `the heartbeat checks are blocked, not planned: no project API key is held yet for hc (${PLATFORM_HC_API_KEY_REF}); a human must sign in to hc, create the first superuser account and a project, mint that project's API key, and hold it under that ref (issue #540 "Human steps") before this step can call hc's check-creation API`,
+            blocked: hosted
+                ? `the heartbeat checks are blocked, not planned: no project API key is held yet for the outside Healthchecks account (${PLATFORM_HEARTBEATS_HOSTED_API_KEY_REF}); a human must create that account (or project), mint its API key, and hold it under that ref (issue #544 "Human steps") before this step can call its check-creation API`
+                : `the heartbeat checks are blocked, not planned: no project API key is held yet for hc (${PLATFORM_HC_API_KEY_REF}); a human must sign in to hc, create the first superuser account and a project, mint that project's API key, and hold it under that ref (issue #540 "Human steps") before this step can call hc's check-creation API`,
         };
     }
-    const desired = [...desiredHeartbeatCheckNames(recordedIds)].sort().join(',');
+    const desired = `${platform.heartbeatsProvider}:${[...desiredHeartbeatCheckNames(recordedIds)].sort().join(',')}`;
     if (recordedIds[PLATFORM_HEARTBEATS_APPLIED_SCOPE_KEY] === desired) {
         return { step: null, blocked: null };
     }
@@ -2698,7 +2802,9 @@ function planAi(platform, recordedIds, executorBlocked) {
     // already set then, so nothing is minted again.
     const applied = Boolean(recordedIds[key]);
     const drifted = recordedIds[PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY] !== platform.ai.hostname ||
-        recordedIds[PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY] !== platform.ai.gitRef;
+        recordedIds[PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY] !== platform.ai.gitRef ||
+        // The public route (tunnel, connector, DNS record) is part of the step: a host applied before it existed plans it once.
+        !recordedIds[PLATFORM_AI_TUNNEL_SCOPE_KEY];
     if (applied && !drifted)
         return { step: null, blocked: null };
     // #201: the signing pair foundry mints to authenticate its own calls to
@@ -2788,13 +2894,67 @@ function planAi(platform, recordedIds, executorBlocked) {
  * ({@link PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY}) plans the step again, as
  * {@link planAuth} does.
  */
-function planArchon(platform, recordedIds, executorBlocked, authReady, drifted, deployRunning) {
+/** Archon signs its operators in through the owner company's own sign-in; fixed text, part of the stale-plan comparison. */
+export const ARCHON_OWNER_SIGN_IN_BLOCKED = "Archon is blocked, not planned: the owner company's sign-in is not applied yet";
+/** Archon signs in from its own organisation, which the `zitadel:archon-org` step makes; fixed text, part of the stale-plan comparison. */
+export const ARCHON_ORG_BLOCKED = 'Archon is blocked, not planned: its own sign-in organisation is not applied yet';
+/**
+ * Archon's own sign-in organisation in the owner company's ZITADEL: the org,
+ * its primary domain, closed registration, the second-factor policy, and the
+ * first person's invite. One `zitadel:archon-org` step keyed
+ * {@link PLATFORM_ARCHON_KEY}, planned while any of those is not recorded
+ * against the recorded org, and always before `platform:archon`. Blocked, not
+ * planned, while the host cannot reach the instance. A refused domain is
+ * reported as a standing note (as the owner org's is) and does not hold the
+ * step; an invite that cannot be sent (no work address, no mail port) is a
+ * standing note and does not hold it either.
+ */
+function planArchonOrg(platform, recordedIds, executorBlocked, inviteBlocked, ownerSignIn) {
+    if (!platform.archon.enabled || !ownerSignIn)
+        return { step: null, blocked: null };
+    const orgId = recordedIds[PLATFORM_ARCHON_ORG_SCOPE_KEY];
+    const blockedDomain = recordedIds[PLATFORM_ARCHON_ORG_DOMAIN_BLOCKED_SCOPE_KEY];
+    const domainDone = Boolean(recordedIds[PLATFORM_ARCHON_ORG_DOMAIN_SCOPE_KEY]) || Boolean(blockedDomain);
+    const inviteRecorded = recordedIds[PLATFORM_ARCHON_OWNER_INVITE_SCOPE_KEY];
+    const inviteDone = Boolean(inviteBlocked) ||
+        inviteRecorded === 'none' ||
+        (Boolean(inviteRecorded) && recordedIds[PLATFORM_ARCHON_OWNER_INVITE_ORG_SCOPE_KEY] === orgId);
+    const standing = [
+        inviteBlocked,
+        blockedDomain && !recordedIds[PLATFORM_ARCHON_ORG_DOMAIN_SCOPE_KEY]
+            ? `Archon's sign-in domain ${blockedDomain} is blocked, not planned: the sign-in server refused to make it primary because its domain policy wants proof of ownership. Set the policy ValidateOrgDomains to false on the sign-in server, then remove the recorded key ${PLATFORM_ARCHON_ORG_DOMAIN_BLOCKED_SCOPE_KEY}`
+            : null,
+    ].filter((v) => Boolean(v));
+    const standingNote = standing.length > 0 ? standing.join('; ') : null;
+    if (orgId &&
+        domainDone &&
+        recordedIds[PLATFORM_ARCHON_ORG_REGISTRATION_CLOSED_SCOPE_KEY] === orgId &&
+        recordedIds[PLATFORM_ARCHON_ORG_POLICY_SCOPE_KEY] === orgId &&
+        inviteDone) {
+        return { step: null, blocked: standingNote };
+    }
+    if (executorBlocked)
+        return { step: null, blocked: executorBlocked };
+    return {
+        step: {
+            action: { system: 'zitadel', kind: 'archon-org', key: PLATFORM_ARCHON_KEY, desired: {} },
+            step: {
+                description: "make Archon's own sign-in organisation in the owner company's ZITADEL: close registration, force a second factor, and invite the first person",
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: standingNote,
+    };
+}
+function planArchon(platform, recordedIds, executorBlocked, ownerSignIn, ownerFiles, drifted, deployRunning, archonOrg = { step: false, blocked: null }) {
     if (!platform.archon.enabled)
         return { step: null, blocked: null };
     // A deploy the step triggered is still running: planning it again would deploy twice.
     if (deployRunning)
         return { step: null, blocked: deployRunning };
     const key = resourceKey('coolify', 'app', PLATFORM_ARCHON_KEY);
+    const archonOrgId = recordedIds[PLATFORM_ARCHON_ORG_SCOPE_KEY];
     const applied = Boolean(recordedIds[key]) &&
         Boolean(recordedIds[PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY]) &&
         recordedIds[PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY] === platform.archon.hostname &&
@@ -2803,11 +2963,20 @@ function planArchon(platform, recordedIds, executorBlocked, authReady, drifted,
         // deleted by hand, or `platform:auth` minting a fresh one) leaves
         // Archon's last registration on a broker that no longer exists, and
         // nothing else here would ever plan the step again to redo it.
-        Boolean(recordedIds[PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY]) &&
-        recordedIds[PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY] ===
-            recordedIds[PLATFORM_AUTH_BROKER_SCOPE_KEY] &&
-        recordedIds[PLATFORM_ARCHON_APPLIED_AUTH_ORG_SCOPE_KEY] ===
-            archonAuthOrganizationId(recordedIds) &&
+        ownerSignIn !== null &&
+        recordedIds[PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY] === ownerSignIn.brokerAppId &&
+        // Archon signs in from its own organisation, never the company's.
+        Boolean(archonOrgId) &&
+        recordedIds[PLATFORM_ARCHON_APPLIED_AUTH_ORG_SCOPE_KEY] === archonOrgId &&
+        recordedIds[PLATFORM_ARCHON_APPLIED_CI_ORG_SCOPE_KEY] === ownerSignIn.organisationId &&
+        (recordedIds[PLATFORM_ARCHON_APPLIED_FIRST_OWNER_LINK_SCOPE_KEY] ?? '') ===
+            archonFirstOwnerLink(recordedIds, ownerSignIn) &&
+        recordedIds[PLATFORM_ARCHON_APP_KEY_ORG_SCOPE_KEY] === archonOrgId &&
+        !recordedIds[PLATFORM_ARCHON_RETIRED_CLIENT_SCOPE_KEY] &&
+        Boolean(recordedIds[PLATFORM_ARCHON_ACCESS_PIN_SCOPE_KEY]) &&
+        recordedIds[PLATFORM_ARCHON_APPLIED_AUTH_HOSTNAME_SCOPE_KEY] === ownerSignIn.hostname &&
+        (recordedIds[PLATFORM_ARCHON_APPLIED_FILES_SCOPE_KEY] ?? 'none') ===
+            archonFilesMarker(ownerFiles) &&
         // #475: a platform applied before the rolling-update fix keeps planning
         // this step until a confirmed redeploy has cleared it. #480: this marker
         // alone does not catch the live app's settings changing back afterward
@@ -2839,17 +3008,11 @@ function planArchon(platform, recordedIds, executorBlocked, authReady, drifted,
                 recordedIds[PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY]);
     if (applied && !drifted)
         return { step: null, blocked: null };
-    if (!platform.auth.enabled) {
-        return {
-            step: null,
-            blocked: "Archon is blocked, not planned: its sign-in client lives in the platform's own sign-in, and auth is not enabled",
-        };
-    }
-    if (!authReady) {
-        return {
-            step: null,
-            blocked: "Archon is blocked, not planned: its sign-in client lives in the platform's own sign-in, which is neither applied nor planned",
-        };
+    if (!ownerSignIn)
+        return { step: null, blocked: ARCHON_OWNER_SIGN_IN_BLOCKED };
+    // The org is recorded, or its step runs earlier in this same plan.
+    if (!archonOrgId && !archonOrg.step) {
+        return { step: null, blocked: archonOrg.blocked ?? ARCHON_ORG_BLOCKED };
     }
     if (executorBlocked)
         return { step: null, blocked: executorBlocked };

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

@@ -1,6 +1,6 @@
-import { type DeclaredOrg } from '../org.js';
+import { type DeclaredOrg, type VersionPin } from '../org.js';
 import type { DeclaredPlatform } from '../platform.js';
-import type { AgoraHostValues } from './agora.js';
+import { type AgoraHostValues } from './agora.js';
 /**
  * #443: the no-domain company mail apex -- `<slug>.oikos.host`, the same
  * fixed suffix `agora.ts`'s `agoraHostnameFor`, `boule.ts`'s
@@ -76,8 +76,8 @@ export interface OrgPlatformReadiness {
     /** The AI host (#172), the same always-on shape as {@link filesReady}. */
     aiReady: boolean;
     /**
-     * The AI host's internal address, which an entry with `uses.ai` gets as
-     * `AI_URL`. `null` or absent until the platform has recorded it.
+     * The AI host's public origin (`https://<platform.ai.hostname>`), which an entry with `uses.ai`
+     * gets as `AI_URL`. `null` or absent until the platform has applied the AI host.
      */
     aiUrl?: string | null;
     /**
@@ -87,8 +87,30 @@ export interface OrgPlatformReadiness {
      * read, so "applied" has no separate check.
      */
     callsReady: boolean;
+    /** The shared oikos.host ingress (tunnel, wildcard record, rate limit) is applied. Absent reads as false. */
+    oikosIngressApplied?: boolean;
+    /**
+     * The broker app Archon last registered on (`PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY`). The
+     * owner's own sign-in counts that registration as its broker's first entry: the broker starts
+     * on it and the login client is minted once it is there. Absent or `null` when Archon has not
+     * registered.
+     */
+    archonBrokerAppId?: string | null;
+    /**
+     * The ZITADEL project and client ids the platform made in the owner company's own ZITADEL
+     * (Archon's and the Access provider's). The owner company's page counts them as the
+     * platform's, not as strangers. Absent when none is recorded.
+     */
+    platformZitadelIds?: readonly string[];
     /** The platform's own sign-in (#168), which every org's own ZITADEL org lives inside. */
     authReady: boolean;
+    /**
+     * The host of the platform's own shared sign-in when its Coolify app is still recorded
+     * (`coolify:app:platform:auth`), whether or not this build declares it. Absent on a platform
+     * built from empty. The owner company's own sign-in takes the same name on the apex, so it
+     * waits while this is set.
+     */
+    platformAuthRecordedHost?: string;
     /** `https://<platform.auth.hostname>`, the platform's own sign-in issuer; `null` until {@link authReady}. The owner invite reads its issuer here, never from Agora's host config. */
     authIssuer: string | null;
     /** The Access provider id the platform recorded (`ACCESS_PROVIDER_RECORD_KEY`), which every gate requires. `null` or absent until the platform has recorded it. */
@@ -142,7 +164,7 @@ export interface OrgPlatformReadiness {
     };
     /**
      * The platform's Lettermint key (`PLATFORM_AUTH_BROKER_MAIL_KEY_REF`) is held,
-     * so an entry env from `platformMailKey` can be filled. Absent reads as not held.
+     * so the owner company's mail can be planned. Absent reads as not held.
      */
     mailKeyHeld?: boolean;
     /** The host's held keys can `put`, so an entry env from `sharedSecret` can be filled. Absent reads as false. */
@@ -160,9 +182,9 @@ export interface OrgPlatformReadiness {
         jobs: string;
     };
     /**
-     * The platform's recorded owner invite (`PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY`): the user id the
-     * platform's files host takes as `AUTHZ_BOOTSTRAP_OPERATOR`, or `'none'` when the platform has no
-     * owner to invite. `null` or absent until recorded. An own org's files host gets the same value.
+     * The user id an own org's files host takes as `AUTHZ_BOOTSTRAP_OPERATOR`: the owner company's
+     * owner in the owner company's own ZITADEL ({@link platformOwnerUserIdFrom}), or `'none'` when
+     * the owner company has no owner to invite. `null` or absent until recorded.
      */
     platformOwnerUserId?: string | null;
 }
@@ -221,8 +243,8 @@ heldRefs?: ReadonlySet<string>,
 noKeyReader?: boolean, 
 /** #317: true when the host's executor was built with an `EdgePort` ({@link OrgPlatformReadiness.edgeReady}). */
 edgePortPresent?: boolean): OrgPlatformReadiness;
-/** The git refs the platform declares for the services an own org deploys. */
-export declare function serviceGitRefsOf(platform: DeclaredPlatform): {
+/** The git refs the platform declares for the services an own org deploys; a company's `pin` wins per part. */
+export declare function serviceGitRefsOf(platform: DeclaredPlatform, pin?: VersionPin | null): {
     auth: string;
     mail: string;
     files: string;
@@ -257,3 +279,50 @@ export declare function agoraHostValuesForOwn(org: DeclaredOrg, orgRecordedIds:
  * host-supplied `agora` port overrides it.
  */
 export declare function agoraHostValuesFromPlatform(platform: DeclaredPlatform, platformRecordedIds: Readonly<Record<string, string>>): AgoraHostValues;
+/**
+ * The owner company's own sign-in, as the platform plan reads it. `null` (the
+ * platform plan's input) until the owner's own sign-in step and its ZITADEL
+ * organisation are applied. `bearerRef` is a held-key reference, never a value.
+ */
+export interface OwnerSignIn {
+    issuerUrl: string;
+    organisationId: string;
+    brokerAppId: string;
+    bearerRef: string;
+    hostname: string;
+    /**
+     * The company's first owner in its own organisation (the CI-side half of
+     * Archon's first-owner link): the recorded user id, `'none'` when no owner
+     * is declared, absent while the owner step has recorded nothing.
+     */
+    firstOwnerUserId?: string | null;
+}
+/** The owner company's own files host, as Archon's `FILES_*` env reads it. */
+export interface OwnerFiles {
+    internalUrl: string;
+    audience: string;
+    organisationId: string;
+    managementKeyRef: string;
+}
+/** What the platform plan reads about the owner company. */
+export interface PlatformOwnerInput {
+    signIn?: OwnerSignIn | null;
+    files?: OwnerFiles | null;
+}
+/**
+ * The owner's sign-in from its declared org and the ids its own steps recorded.
+ * The host and issuer are the host the own-auth step last applied, and only
+ * while that is the declared `ownHostnames(org).auth`: a domain edit gives
+ * `null` until the step has applied the new host, so the owner's instance
+ * token is never sent to a host the step has not set up.
+ */
+export declare function ownerSignInFrom(owner: DeclaredOrg | null, recorded: Readonly<Record<string, string>>): OwnerSignIn | null;
+/**
+ * The platform's operator identity for a company's files host: the owner company's first owner,
+ * as the owner's `zitadel:owner` step recorded it in the owner company's own ZITADEL. `'none'`
+ * when the owner company declares no owner; `null` until the step has recorded the id, and
+ * when there is no owner company running its own services.
+ */
+export declare function platformOwnerUserIdFrom(owner: DeclaredOrg | null, recorded: Readonly<Record<string, string>>): string | null;
+/** The owner's files host once its own files step has applied; `null` before. */
+export declare function ownerFilesFrom(owner: DeclaredOrg | null, recorded: Readonly<Record<string, string>>): OwnerFiles | null;