@wtfalch/foundry 0.34.0 → 0.35.2

package/dist/plan/plan-apply.js

@@ -7,20 +7,24 @@ 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 { NetworkMoveBackupMissingError, UpgradeBackupMissingError, platformDatabasesForService, requireFreshBackupsForMove, requireFreshBackupsForUpgrades, } from './backup-gate.js';
+import { readLiveBuilds } from './build-record.js';
 import { unconfirmedUpgrades } from './confirm-upgrade.js';
-import { AI_KEY_UNDELIVERED_SCOPE_KEY, JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY, computePlanDetail, isPlatformOwnOrg, toPlan, } from './diff.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';
 import { FILES_ROOT_UNDELIVERED_SCOPE_KEY, entryFilesUndeliveredScopeKey, } from './entry-files-key.js';
 import { readLivePlatformResources, readLiveResources, } from './live.js';
 import { lockedHostnames } from './locked-hostnames.js';
 import { agoraIssuerHostFor, loginHostServesAgora, readLoginHostDiscovery, } from './login-host.js';
-import { OWN_MAIL_SMTP_INTERNAL_SCOPE_KEY, PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY, } from './mail-relay.js';
+import { OWN_MAIL_SMTP_INTERNAL_SCOPE_KEY, OWN_MAIL_SMTP_PORT_BASE, OWN_MAIL_SMTP_PORT_MAX, OWN_MAIL_SMTP_PORT_SCOPE_KEY, PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY, isOwnMailSmtpPort, mailRelayFingerprint, } from './mail-relay.js';
 import { findNameClashes, nameClashMessage } from './org-names.js';
+import { ownHostnames } from './own-hostnames.js';
 import { OWN_FILES_R2_UNDELIVERED_SCOPE_KEY, orgTarget } from './own-services.js';
-import { PLATFORM_ARCHON_KEY, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_KEY, appStepKey, planPlatform as computePlatformPlanDetail, toPlatformPlan, } from './platform-diff.js';
-import { DEFAULT_ORG_PLATFORM_READINESS, NO_DOMAIN_MAIL_APEX, ORG_PLATFORM_KEY_REFS, agoraHostValuesForOwn, agoraHostValuesFromPlatform, dnsBlockedReason, heldOwnKeyRefs, heldPlatformKeyRefs, orgPlatformReadinessFor, orgPlatformReadinessFrom, serviceGitRefsOf, } from './platform-org.js';
-import { PLATFORM_AUTH_BROKER_MAIL_KEY_REF } from './platform-providers.js';
+import { PLATFORM_ARCHON_KEY, PLATFORM_BACKUP_DATABASE_SCOPE_KEYS, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_KEY, appStepKey, planPlatform as computePlatformPlanDetail, toPlatformPlan, } from './platform-diff.js';
+import { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesForOwn, agoraHostValuesFromPlatform, dnsBlockedReason, heldOwnKeyRefs, heldPlatformKeyRefs, orgPlatformReadinessFor, orgPlatformReadinessFrom, ownerFilesFrom, ownerSignInFrom, platformOwnerUserIdFrom, serviceGitRefsOf, } from './platform-org.js';
+import { PLATFORM_AUTH_BROKER_MAIL_KEY_REF, PLATFORM_BACKUP_S3_STORAGE_SCOPE_KEY, } from './platform-providers.js';
+import { CLOUDFLARE_TUNNEL_ENTRY_ROUTES_SCOPE_KEY, CLOUDFLARE_TUNNEL_OIKOS_HOSTNAMES_SCOPE_KEY, } from './proxy-labels.js';
 import { liveWorkers, workerTraceScopeKeys } from './worker.js';
 /** #441: the lease scope that serializes every mutation of one company, and the one for the shared platform. */
 const companyScope = (orgId) => `company:${orgId}`;
@@ -160,6 +164,7 @@ export class FoundryPlanApply {
     now;
     leaseTtlMs;
     appliedVersions;
+    backupGate;
     platformDeps;
     runner;
     constructor(options) {
@@ -187,6 +192,7 @@ export class FoundryPlanApply {
         this.now = options.now ?? (() => new Date());
         this.leaseTtlMs = options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
         this.appliedVersions = options.appliedVersions;
+        this.backupGate = options.backupGate;
         this.platformDeps = options.platform;
         this.runner = options.runner;
     }
@@ -360,6 +366,7 @@ export class FoundryPlanApply {
         const reader = this.readers.coolify;
         const live = project && reader.listProject ? await reader.listProject(project) : null;
         const claimedElsewhere = [];
+        const platformRecorded = new Set(Object.values((await this.platformDeps?.store.getServiceIds()) ?? {}));
         for (const [what, uuid] of [
             ['application', input.applicationUuid],
             ['database', input.databaseUuid],
@@ -367,6 +374,10 @@ export class FoundryPlanApply {
         ]) {
             if (!uuid)
                 continue;
+            if (platformRecorded.has(uuid)) {
+                claimedElsewhere.push(`${what} ${uuid} is recorded by the platform`);
+                continue;
+            }
             const owner = await this.store.findOtherOrgRecordingCoolifyId(uuid, id);
             if (owner)
                 claimedElsewhere.push(`${what} ${uuid} is already recorded by org ${owner}`);
@@ -394,12 +405,50 @@ export class FoundryPlanApply {
                 await this.refuse(plan, `version change without confirmUpgrade naming: ${unconfirmed.map((u) => u.service).join(', ')}`);
                 throw new UpgradeConfirmationRequiredError(unconfirmed);
             }
+            // F6: before step one. No override.
+            let backupId = null;
+            if (this.backupGate) {
+                try {
+                    ({ backupId } = await requireFreshBackupsForUpgrades(freshPlan, options.confirmUpgrade, {
+                        coolify: this.backupGate.coolify,
+                        orgId,
+                        recordedIds: (await this.store.getAppliedState(orgId))?.serviceIds ?? {},
+                        now: () => this.now().getTime(),
+                    }));
+                }
+                catch (e) {
+                    if (e instanceof UpgradeBackupMissingError) {
+                        await this.refuse(plan, `upgrade of ${e.service} without a fresh backup`);
+                    }
+                    throw e;
+                }
+            }
+            // A move to the company's own network deletes its databases: a fresh dump of each first.
+            if (detail.plannedSteps.some((s) => s.action.system === 'coolify' && s.action.kind === 'network')) {
+                try {
+                    if (!this.backupGate)
+                        throw new NetworkMoveBackupMissingError('no-gate');
+                    await requireFreshBackupsForMove({
+                        coolify: this.backupGate.coolify,
+                        projectUuid: (await this.store.getAppliedState(orgId))?.serviceIds
+                            ?.coolify_project,
+                        ownsMail: ownsServices(org) && org.mail.mode !== 'off',
+                        now: () => this.now().getTime(),
+                    });
+                }
+                catch (e) {
+                    if (e instanceof NetworkMoveBackupMissingError) {
+                        await this.refuse(plan, 'network move without a fresh backup');
+                    }
+                    throw e;
+                }
+            }
             if (planNeedsConfirmation(plan.steps) &&
                 confirmedOrgName.trim() !== org.displayName.trim()) {
                 await this.refuse(plan, "destructive or migrating step without the org's name typed correctly");
                 throw new ConfirmationRequiredError(orgId);
             }
-            const applied = await this.runSteps(org, plan, detail, fence);
+            const applied = await this.runSteps(org, plan, detail, fence, backupId);
             await this.refreshPlatformFilesShare();
             return applied;
         }));
@@ -494,6 +543,27 @@ export class FoundryPlanApply {
                 await this.refusePlatform(plan, platform.ownerOrgId, `version change without confirmUpgrade naming: ${unconfirmed.map((u) => u.service).join(', ')}`);
                 throw new UpgradeConfirmationRequiredError(unconfirmed);
             }
+            // F6: before step one. No override. The platform records no applied versions, so no backup id is kept.
+            if (this.backupGate) {
+                try {
+                    await requireFreshBackupsForUpgrades(freshPlan, options.confirmUpgrade, {
+                        coolify: this.backupGate.coolify,
+                        orgId: platform.ownerOrgId,
+                        recordedIds: await this.requirePlatformDeps().store.getServiceIds(),
+                        now: () => this.now().getTime(),
+                        scope: {
+                            keys: PLATFORM_BACKUP_DATABASE_SCOPE_KEYS,
+                            forService: platformDatabasesForService,
+                        },
+                    });
+                }
+                catch (e) {
+                    if (e instanceof UpgradeBackupMissingError) {
+                        await this.refusePlatform(plan, platform.ownerOrgId, `upgrade of ${e.service} without a fresh backup`);
+                    }
+                    throw e;
+                }
+            }
             if (planNeedsConfirmation(plan.steps) && confirmedName.trim() !== 'platform') {
                 await this.refusePlatform(plan, platform.ownerOrgId, "destructive or migrating step without 'platform' typed correctly");
                 throw new PlatformConfirmationRequiredError();
@@ -587,6 +657,11 @@ export class FoundryPlanApply {
                         // gone" itself.
                         await this.destroyer.destroy(target, { org, recordedIds: { ...serviceIds } });
                         delete serviceIds[destroyServiceIdKey(target)];
+                        if (target.system === 'cloudflare' && target.kind === 'tunnel') {
+                            // The tunnel is gone, so what was written into it is too.
+                            delete serviceIds[CLOUDFLARE_TUNNEL_ENTRY_ROUTES_SCOPE_KEY];
+                            delete serviceIds[CLOUDFLARE_TUNNEL_OIKOS_HOSTNAMES_SCOPE_KEY];
+                        }
                         if (target.system === 'cloudflare' && target.kind === 'worker') {
                             // #318: its partial-deploy traces too, or a retry after a later
                             // step fails would read this Worker as live again.
@@ -807,15 +882,17 @@ export class FoundryPlanApply {
             at: this.now(),
         });
     }
-    async runSteps(org, plan, detail, fence) {
+    async runSteps(org, plan, detail, fence, backupId = null) {
         const orgId = plan.orgId;
         const previous = await this.store.getAppliedState(orgId);
         const serviceIds = { ...(previous?.serviceIds ?? {}) };
         const checkpoints = [];
         // Backed by the very `serviceIds` map this method persists once, at the
         // end — see `StepExecutionContext`'s doc comment for why.
+        const ownerCompany = (await this.platformDeps?.store.get())?.ownerOrgId === orgId;
         const context = {
             org,
+            ownerCompany,
             recordedIds: () => ({ ...serviceIds }),
             now: () => this.now().getTime(),
             recordScopeId: (key, id) => {
@@ -902,6 +979,7 @@ export class FoundryPlanApply {
             service: orgId,
             ref: lastApplied.declaredOrgVersion,
             appliedAt: lastApplied.at,
+            backupId,
         });
         await this.audit.recordApply({
             actor: this.actor,
@@ -942,7 +1020,7 @@ export class FoundryPlanApply {
         const platformHostnames = await this.platformServiceHostnames();
         const recorded = applied?.serviceIds ?? {};
         // Read only for an org Agora may switch and whose login host is applied.
-        const issuerHost = agoraIssuerHostFor(org, isPlatformOwnOrg(org, platformReadiness.platformOwnerOrgId)).host;
+        const issuerHost = agoraIssuerHostFor(org).host;
         const loginHostServesDiscovery = issuerHost !== null && loginHostServesAgora(issuerHost, org, recorded)
             ? await readLoginHostDiscovery(this.loginHostDiscovery, issuerHost)
             : false;
@@ -952,7 +1030,9 @@ export class FoundryPlanApply {
             loginHostBindings: this.loginHostBindings,
             loginHostServesDiscovery,
             zitadelIdTokenUserinfo: this.zitadelIdTokenUserinfo,
-            broker: this.broker,
+            broker: ownsServices(org) && this.hostOwnServices && this.executor.ownBrokerPort
+                ? await this.executor.ownBrokerPort(org, recorded)
+                : this.broker,
             edgeWorkers: this.edgeWorkers,
             ownerInviteMail: this.ownerInviteMail,
             otherSlugs,
@@ -960,17 +1040,39 @@ export class FoundryPlanApply {
             archonUrl,
             platformHostnames,
             ownServices: this.hostOwnServices,
+            // The `oikos.host` zone, its wildcard and its tunnel are the platform's `platform:oikos-ingress` step.
+            oikosZoneReady: platformReadiness.oikosIngressApplied === true,
             ownMailKeyHeld: await this.ownMailKeyHeld(org),
             ownMailKeyMintable: this.executor.ownMailKeyMintable?.() ?? false,
+            ...(this.backupGate
+                ? {
+                    backupStorageUuid: (await this.platformDeps?.store.getServiceIds())?.[PLATFORM_BACKUP_S3_STORAGE_SCOPE_KEY] || null,
+                }
+                : {}),
             ownJobsTokenHeld: resumable.jobs,
             ownSfuKeysHeld: resumable.sfu,
-            ...(ownsServices(org) ? { mailRelayApplied: await this.mailRelayApplied() } : {}),
+            ...(ownsServices(org)
+                ? {
+                    mailRelayApplied: await this.mailRelayApplied(),
+                    ownMailSmtpPort: await this.ownMailSmtpPort(org),
+                    mailRelayRoute: await this.mailRelayHoldsRoute(org),
+                }
+                : {}),
             sfuPortsOpen,
             ownFilesDeps: this.executor.ownFilesDeps?.(),
             ...(ownsServices(org) && this.executor.ownFilesR2Ports
                 ? { ownFilesR2Ports: await this.executor.ownFilesR2Ports(org, recorded) }
                 : {}),
         });
+        if (!ownsServices(org)) {
+            // No company runs the shared services; each runs its own.
+            detail.plannedSteps = [];
+            detail.versionChanges = [];
+            detail.unmanaged.push({
+                description: `${org.slug} has no services.own: the shared services are removed, so a company runs its own. Set services.own.`,
+                key: 'services:shared-removed',
+            });
+        }
         if (ownsServices(org) && !this.hostOwnServices) {
             detail.unmanaged.push({
                 description: `${org.slug} runs its own services, and this host has no ownServices port`,
@@ -1046,7 +1148,9 @@ export class FoundryPlanApply {
         const held = this.platformDeps?.heldKeys;
         const platform = await this.platformDeps?.store.get();
         const readiness = orgPlatformReadinessFor(org, base, orgRecordedIds, held ? await heldOwnKeyRefs(held, org) : new Set());
-        return platform ? { ...readiness, serviceGitRefs: serviceGitRefsOf(platform) } : readiness;
+        return platform
+            ? { ...readiness, serviceGitRefs: serviceGitRefsOf(platform, org.versionPin) }
+            : readiness;
     }
     /** An own org's Lettermint key is held. A resolver that throws counts as not held. */
     async ownMailKeyHeld(org) {
@@ -1064,6 +1168,27 @@ export class FoundryPlanApply {
         const heldRefs = await heldOwnKeyRefs(held, org);
         return { jobs: heldRefs.has(refs.jobsAdminToken), sfu: heldRefs.has(refs.livekitKeys) };
     }
+    /**
+     * The host port an own org's Stalwart publishes for the relay: the one it already has recorded, else
+     * the lowest port in the range no other org has recorded. Two plans made at the same moment could pick
+     * the same port; the second Stalwart then fails to bind it and the step fails, with nothing recorded.
+     */
+    async ownMailSmtpPort(org) {
+        const own = (await this.store.getAppliedState(org.id))?.serviceIds?.[OWN_MAIL_SMTP_PORT_SCOPE_KEY];
+        if (own && isOwnMailSmtpPort(Number(own)))
+            return Number(own);
+        const taken = new Set();
+        for (const other of await this.store.list()) {
+            const port = (await this.store.getAppliedState(other.id))?.serviceIds?.[OWN_MAIL_SMTP_PORT_SCOPE_KEY];
+            if (port)
+                taken.add(Number(port));
+        }
+        for (let port = OWN_MAIL_SMTP_PORT_BASE; port <= OWN_MAIL_SMTP_PORT_MAX; port += 1) {
+            if (!taken.has(port))
+                return port;
+        }
+        return OWN_MAIL_SMTP_PORT_MAX + 1;
+    }
     /** The relay is declared and has recorded the routes it last applied: port 25 reaches the mail servers. */
     async mailRelayApplied() {
         const platform = await this.platformDeps?.store.get();
@@ -1072,6 +1197,21 @@ export class FoundryPlanApply {
         const recorded = await this.platformDeps?.store.getServiceIds();
         return Boolean(recorded?.[PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY]);
     }
+    /**
+     * The relay's last applied routes (a fingerprint, recorded when it deploys) are the routes the
+     * orgs' recorded SMTP addresses give now, and one of them is this org's mail domain.
+     */
+    async mailRelayHoldsRoute(org) {
+        const platform = await this.platformDeps?.store.get();
+        if (!platform?.mail.relay)
+            return false;
+        const { mailRoutes } = await this.mailRelayInputs();
+        const domain = ownHostnames(org).mailDomain.toLowerCase();
+        if (!mailRoutes.some((r) => r.domain.toLowerCase() === domain))
+            return false;
+        const recorded = await this.platformDeps?.store.getServiceIds();
+        return recorded?.[PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY] === mailRelayFingerprint(mailRoutes);
+    }
     async sharedPlatformReadiness() {
         if (!this.platformDeps)
             return DEFAULT_ORG_PLATFORM_READINESS;
@@ -1097,8 +1237,13 @@ export class FoundryPlanApply {
         catch {
             // not held
         }
+        const ownerOrg = await this.store.get(platform.ownerOrgId);
+        const ownerRecorded = ownerOrg
+            ? (await this.store.getAppliedState(ownerOrg.id))?.serviceIds
+            : {};
         return {
             ...readiness,
+            platformOwnerUserId: platformOwnerUserIdFrom(ownerOrg, ownerRecorded ?? {}),
             mailKeyHeld,
             canHoldSecrets: typeof heldKeys?.put === 'function',
             dnsBlocked: dnsBlockedReason(platform, recorded),
@@ -1166,52 +1311,55 @@ export class FoundryPlanApply {
         const callsOrgSlugs = (await this.store.list())
             .filter((org) => org.calls.enabled)
             .map((org) => org.slug);
-        const mailRelay = platform.mail.relay === true ? await this.mailRelayInputs(platform) : null;
+        const mailRelay = platform.mail.relay === true ? await this.mailRelayInputs() : null;
+        const owner = await this.platformOwnerInput(platform);
         const detail = computePlatformPlanDetail(platform, live, {
+            owner,
             jobsObservable: readers.coolify !== undefined,
             sfuBlocked,
             callsOrgSlugs,
             ...(mailRelay ?? {}),
             recordedIds: serviceIds,
-            blocked: (await executor.blockedSteps?.(platform, serviceIds)) ?? {},
-            drifted: (await executor.driftedSteps?.(platform, serviceIds)) ?? {},
+            liveBuilds: await readLiveBuilds(readers.coolify, serviceIds),
+            blocked: (await executor.blockedSteps?.(platform, serviceIds, owner)) ?? {},
+            drifted: (await executor.driftedSteps?.(platform, serviceIds, owner)) ?? {},
         });
         return { platform, plan: toPlatformPlan(detail, platform.ownerOrgId), detail };
     }
+    /** The owner company's own sign-in and files host, read from its applied ids; `null` members until applied. */
+    async platformOwnerInput(platform) {
+        const owner = await this.store.get(platform.ownerOrgId);
+        if (!owner)
+            return { signIn: null, files: null };
+        const recorded = (await this.store.getAppliedState(owner.id))?.serviceIds ?? {};
+        return { signIn: ownerSignInFrom(owner, recorded), files: ownerFilesFrom(owner, recorded) };
+    }
     /**
      * What the shared mail relay needs from the orgs. A route exists for an org
      * that owns its services, serves mail on its own domain and has recorded its
      * mail server's SMTP address (`mail_smtp_internal`, written by the company
-     * mail step). Every other org with mail on its own domain, the platform
-     * apex and the shared no-domain apex are platform domains: the platform's Stalwart receives them. An org
-     * that owns its services but has no mail server yet appears in neither list,
-     * so the relay refuses its mail until the server exists.
+     * mail step), on its mail domain: its own domain, or `<slug>.oikos.host`.
+     * There is no platform mail server: a domain with no route is refused. An org
+     * that owns its services but has no mail server yet has no route, so the
+     * relay refuses its mail until the server exists.
      */
-    async mailRelayInputs(platform) {
+    async mailRelayInputs() {
         const candidates = [];
-        const mailPlatformDomains = [platform.apex];
         for (const org of await this.store.list()) {
             if (org.mail.mode === 'off')
                 continue;
-            // Mail without the org's own domain is served on the shared no-domain apex.
-            if (!org.domain || !org.mail.usesDomain) {
-                if (!mailPlatformDomains.includes(NO_DOMAIN_MAIL_APEX)) {
-                    mailPlatformDomains.push(NO_DOMAIN_MAIL_APEX);
-                }
-                continue;
-            }
-            if (!ownsServices(org)) {
-                mailPlatformDomains.push(org.domain);
+            if (!ownsServices(org))
                 continue;
-            }
             const recorded = (await this.store.getAppliedState(org.id))?.serviceIds ?? {};
             const target = recorded[OWN_MAIL_SMTP_INTERNAL_SCOPE_KEY];
             if (recorded.coolify_platform_mail_app && target) {
-                candidates.push({ slug: org.slug, route: { domain: org.domain, target } });
+                candidates.push({
+                    slug: org.slug,
+                    route: { domain: ownHostnames(org).mailDomain, target },
+                });
             }
         }
-        // A domain the platform serves, or two companies claim, gets no route; the other routes stay.
-        const platformSet = new Set(mailPlatformDomains.map((d) => d.toLowerCase()));
+        // A domain two companies claim gets no route; the other routes stay.
         const claims = new Map();
         for (const { route } of candidates) {
             const domain = route.domain.toLowerCase();
@@ -1221,17 +1369,14 @@ export class FoundryPlanApply {
         const mailRoutesBlocked = [];
         for (const { slug, route } of candidates) {
             const domain = route.domain.toLowerCase();
-            if (platformSet.has(domain)) {
-                mailRoutesBlocked.push(`${slug}'s mail route for ${route.domain} is blocked, not planned: ${route.domain} is a platform mail domain`);
-            }
-            else if ((claims.get(domain) ?? 0) > 1) {
+            if ((claims.get(domain) ?? 0) > 1) {
                 mailRoutesBlocked.push(`${slug}'s mail route for ${route.domain} is blocked, not planned: another company claims ${route.domain}`);
             }
             else {
                 mailRoutes.push(route);
             }
         }
-        return { mailRoutes, mailPlatformDomains, mailRoutesBlocked };
+        return { mailRoutes, mailRoutesBlocked };
     }
     async sfuBlockedReason(platform) {
         if (!platform.sfu.enabled)
@@ -1272,6 +1417,7 @@ export class FoundryPlanApply {
         const serviceIds = { ...(await store.getServiceIds()) };
         const context = {
             platform,
+            owner: await this.platformOwnerInput(platform),
             recordedIds: () => ({ ...serviceIds }),
             recordScopeId: (key, id) => {
                 serviceIds[key] = id;

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

@@ -4,6 +4,7 @@ import type { DeclaredPlatform } from '../platform.js';
 import type { PlannedStep } from './diff.js';
 import type { LiveResource } from './live.js';
 import { type MailRoute, PLATFORM_MAIL_RELAY_KEY } from './mail-relay.js';
+import type { OwnerFiles, OwnerSignIn, PlatformOwnerInput } from './platform-org.js';
 /**
  * The platform's own diff result, the {@link DeclaredPlatform} counterpart to
  * `diff.ts`'s `PlanDetail` -- everything the same, minus the `orgId` an org's
@@ -185,11 +186,15 @@ export declare const PLATFORM_ARCHON_APPLIED_AUTH_ORG_SCOPE_KEY = "archon_applie
  */
 export declare 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 declare function archonAuthOrganizationId(recorded: Readonly<Record<string, string>>): string | undefined;
+export declare const PLATFORM_ARCHON_APPLIED_AUTH_HOSTNAME_SCOPE_KEY = "archon_applied_auth_hostname";
+export declare 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 declare function archonFilesMarker(files: OwnerFiles | null | undefined): string;
 /**
  * #175: set to '1' before the step points the tunnel at `http_status:404`
  * (Access app rebuild), cleared to '' once the real ingress is written back.
@@ -537,8 +542,68 @@ export declare function serviceDbEnvAppliedScopeKey(service: 'chat' | 'calls-ser
  * made again under a new id, is repaired once.
  */
 export declare function zitadelAppIdTokenUserinfoAppliedScopeKey(appKey: string): string;
-/** 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 declare const PLATFORM_ARCHON_ORG_SCOPE_KEY = "zitadel_platform_archon_org";
+/** The primary domain registered on Archon's sign-in organisation. */
+export declare 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 declare 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 declare 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 declare 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 declare const PLATFORM_ARCHON_OWNER_INVITE_SCOPE_KEY = "zitadel_platform_archon_owner_invite";
+/** The Archon org the recorded invite was made in. */
+export declare 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 declare function archonOrgName(ownerSlug: string): string;
+/** The primary domain of the Archon sign-in organisation: `archon.` before the owner's own sign-in domain. */
+export declare function archonOrgDomain(ownerSignInDomain: string): string;
+/**
+ * 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 declare const PLATFORM_ARCHON_APPLIED_CI_ORG_SCOPE_KEY = "archon_applied_ci_org";
+export declare 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 declare function archonFirstOwnerLink(recordedIds: Readonly<Record<string, string>>, ownerSignIn: OwnerSignIn | null): string;
+/**
+ * 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 declare 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 declare 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 declare 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 declare const PLATFORM_ARCHON_ZITADEL_APP_SCOPE_KEY = "zitadel_platform_archon_app";
+/** The ZITADEL project id Archon's sign-in client lives in. */
+export declare 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 declare const PLATFORM_ACCESS_ZITADEL_PROJECT_SCOPE_KEY = "zitadel_platform_access_project";
+export declare 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
@@ -587,9 +652,8 @@ export declare function appDomainsAppliedScopeKey(entryKey: string): string;
  * unknown, bare before 4b2380f and `https://` after it.
  */
 export declare function appliedAppDomains(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, entryKey: string): string[];
-/** Whether the secret sources can be filled right now: the mail key is held, and a new shared secret can be held. */
+/** Whether the secret sources can be filled right now: a new shared secret can be held. */
 export interface AppSecretAvailability {
-    platformMailKey: boolean;
     sharedSecret: boolean;
 }
 /**
@@ -608,7 +672,7 @@ export declare function resolveAppEnv(org: DeclaredOrg, entry: HostingEntry, rec
     unresolved: Array<[string, string]>;
     secrets: Array<{
         name: string;
-        source: 'platformMailKey' | EnvSharedSecret;
+        source: EnvSharedSecret;
     }>;
     unresolvedSecrets: Array<[string, string]>;
     marker: Record<string, string>;
@@ -627,6 +691,13 @@ export declare const PLATFORM_AI_KEY = "platform:ai";
  * public hostname. Holds whichever way the public-hostname decision goes.
  */
 export declare 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 declare const PLATFORM_AI_TUNNEL_SCOPE_KEY = "cloudflare_platform_ai_tunnel";
+/** The one Coolify app that runs `cloudflared` for the AI tunnel. */
+export declare 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`
@@ -833,6 +904,18 @@ export declare const PLATFORM_HC_APPLIED_GIT_REF_SCOPE_KEY = "hc_applied_git_ref
  * and that implementation is where the key is actually used.
  */
 export declare 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 declare 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
@@ -989,16 +1072,14 @@ export interface PlanPlatformOptions {
      * `platform.mail.relay` is true (default `[]`).
      */
     mailRoutes?: readonly MailRoute[];
-    /**
-     * The domains the platform's own Stalwart serves; the relay hands them to
-     * it and refuses any domain in neither list. Used only when
-     * `platform.mail.relay` is true (default `[]`).
-     */
-    mailPlatformDomains?: readonly string[];
     /** One line per company route left out of `mailRoutes`; each is reported blocked and the relay still plans without it. */
     mailRoutesBlocked?: readonly string[];
+    /** The owner company's own sign-in and files host; Archon and the Access provider read them (default: neither applied). */
+    owner?: PlatformOwnerInput;
     /** The platform's recorded resource/scope ids (default `{}`). */
     recordedIds?: Readonly<Record<string, string>>;
+    /** The commit each recorded app runs now, by app name; a differing one gives a `build-drift:<name>` note (default `{}`). */
+    liveBuilds?: Readonly<Record<string, string>>;
     /** Per-step block reasons the executor reports (default `{}`). */
     blocked?: {
         auth?: string;
@@ -1032,6 +1113,8 @@ export interface PlanPlatformOptions {
         edge?: string;
         /** #604: why the Access sign-in provider cannot be made yet (no dependencies, or edge cannot confirm Access is ready), or absent. */
         accessProvider?: string;
+        /** Why the shared oikos.host ingress cannot be made (no dependencies, or its zone is not on edge's account), or absent. */
+        oikosIngress?: string;
         /**
          * #257: true once a service's database exists but the host built the
          * platform executor with no backup dependencies -- every such service's
@@ -1095,6 +1178,10 @@ export interface PlanPlatformOptions {
          * step is not planned.
          */
         authSignInPolicy?: boolean;
+        /** Why Archon's own sign-in organisation cannot be made (no dependencies, no ZITADEL client for the instance), or absent. */
+        archonOrg?: string;
+        /** Why the first person cannot be invited into Archon's organisation yet (no work address, no mail port). The rest of the step still plans. */
+        archonOrgInvite?: string;
     };
     /**
      * Steps whose live state differs from the declared one in a way the recorded
@@ -1189,11 +1276,8 @@ export declare const JOBS_INTERNAL_URL_SCOPE_KEY = "jobs_internal_url";
  * never a wrong step.
  */
 export declare const PLATFORM_BACKUP_DATABASE_SCOPE_KEYS: {
-    readonly jobs: "coolify_jobs_database";
-    readonly auth: "coolify_platform_auth_database";
     readonly archon: "coolify_platform_archon_database";
     readonly ai: "coolify_platform_ai_database";
-    readonly files: "coolify_platform_files_database";
     readonly integrations: "coolify_integrations_database";
 };
 export type PlatformBackupServiceKey = keyof typeof PLATFORM_BACKUP_DATABASE_SCOPE_KEYS;
@@ -1265,3 +1349,35 @@ export declare const PLATFORM_INTEGRATIONS_KEY_ROTATION_PREVIOUS_SCOPE_KEY = "in
  * `''`) as soon as the mint is recorded, so one request is one rotation.
  */
 export declare const PLATFORM_INTEGRATIONS_KEY_ROTATION_REQUESTED_SCOPE_KEY = "integrations_management_key_rotation_requested";
+/**
+ * #175: Archon (https://github.com/wtfalch/archon), the one shared console,
+ * built fresh at `platform.archon.hostname` (`archon.<apex>`) rather than the
+ * hand-deployed `operator` app it replaces (#165). One step,
+ * `coolify:app` keyed {@link PLATFORM_ARCHON_KEY}, covers the app, its
+ * database, its Cloudflare tunnel, Access app and DNS record, and its sign-in
+ * client in the platform's own ZITADEL -- the same bundling {@link planAuth}
+ * does, for the same reason.
+ *
+ * Idempotent on the recorded resource id plus the applied hostname and
+ * `gitRef`, for the reason {@link planAuth} gives: no platform reader reports
+ * these resources, so a live check would replan the step forever. A changed
+ * hostname or `gitRef` plans the step again, and so does `drifted` (the Access
+ * policy's include list is not the declared one). A re-run mints nothing.
+ *
+ * Blocked, not planned, while the platform's sign-in is neither recorded nor
+ * planned in this same plan: Archon's sign-in client is created inside it, so
+ * the step could only throw.
+ *
+ * #213: also puts {@link PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF},
+ * {@link PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF} and
+ * {@link PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF} as held keys, before
+ * the app deploys -- `putArchonMasterKeys` in `platform-providers.ts`.
+ *
+ * #197: a recorded app with no recorded `cloudflared` connector
+ * ({@link PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY}) plans the step again, as
+ * {@link planAuth} does.
+ */
+/** Archon signs its operators in through the owner company's own sign-in; fixed text, part of the stale-plan comparison. */
+export declare 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 declare const ARCHON_ORG_BLOCKED = "Archon is blocked, not planned: its own sign-in organisation is not applied yet";