@wtfalch/foundry 0.16.16 → 0.17.1

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

@@ -118,6 +118,23 @@ export declare const PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY = "archon_applied
  * unrecorded and the old key stays pinned.
  */
 export declare const PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY = "archon_integrations_key_synced";
+/**
+ * #467: sha256 of the exact env set the *last confirmed* Archon deploy ran
+ * with, recorded only once that deploy's `waitForHealthyVersion` passed --
+ * mirroring {@link PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY}'s own
+ * confirm-after-health-check timing, generalized from one env to all of
+ * them. `provisionPlatformArchon` clears this to `''` the moment it decides
+ * a redeploy is needed, before attempting it: a deploy that then fails (or
+ * a crash before the health check passes) must leave the attempt
+ * unconfirmed, and the env hash alone cannot tell a failed retry's intended
+ * content apart from a successful one's, since both intend the same bytes.
+ * Without this, a run that writes new envs and then fails before Archon
+ * redeploys -- `envsDiffer` comparing desired envs against the *live*
+ * store, which this run's own write already updated -- leaves a retry
+ * reading no difference at all, and the container stays on the stale
+ * values until someone redeploys by hand (#467).
+ */
+export declare const PLATFORM_ARCHON_ENVS_DEPLOYED_SCOPE_KEY = "archon_envs_deployed_hash";
 /**
  * #211 round 4: the broker app id Archon last registered its entry with.
  * `provisionPlatformArchon` reads the broker to register with from
@@ -136,6 +153,21 @@ export declare const PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY = "archon_applied_
  * has recorded it.
  */
 export declare const PLATFORM_ARCHON_APPLIED_OPERATOR_SCOPE_KEY = "archon_applied_bootstrap_operator";
+/**
+ * #475: whether the last successful Archon apply patched the app with
+ * `custom_network_aliases` and `is_consistent_container_name_enabled: false`
+ * instead of the old fixed `custom_internal_name` alone. Coolify only runs a
+ * rolling, health-checked deploy -- start the new container, wait, then stop
+ * the old one -- when the consistent-name flag is off; with it on (set by
+ * foundry's own pre-#475 applies, or by hand in the Coolify UI) every deploy
+ * stops the old container before the new one exists, which is what took
+ * Archon down for #475's incident. Absent on every platform applied before
+ * this fix landed; `planArchon` plans the step again until
+ * `provisionPlatformArchon` records it, which only happens once that run's
+ * redeploy has passed its health check -- the same confirm-after-health-check
+ * timing {@link PLATFORM_ARCHON_ENVS_DEPLOYED_SCOPE_KEY} uses.
+ */
+export declare const PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY = "archon_applied_rolling_update";
 /**
  * The owner's ZITADEL user id Archon takes as its first operator, from
  * {@link PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY}. Undefined when none is
@@ -309,6 +341,20 @@ export declare const PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY = "coolify_platform
 export declare const PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF = "platform:master:coolify-url";
 export declare const PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF = "platform:master:coolify-token";
 export declare const PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF = "platform:master:cloudflare-token";
+/**
+ * #436: a Coolify API token scoped to `read` only, for Archon's own
+ * `/backups` page (`COOLIFY_URL`/`COOLIFY_READ_TOKEN`, Archon's
+ * `src/lib/backups/coolify.ts`) -- deliberately not
+ * {@link PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF}'s root token, which a
+ * read-only status page must never hold. Coolify's token UI has no API
+ * counterpart to create one (`@wtfalch/providers`'s `CoolifyClient` doc:
+ * "Keys & Tokens -> API tokens" only), so a human creates it in Coolify's
+ * console and holds it under this ref; `provisionPlatformArchon` only reads
+ * it back, and pushes nothing until it is held. `COOLIFY_URL` needs no ref
+ * of its own: it is not secret, and {@link PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF}
+ * already holds the same panel's address.
+ */
+export declare const PLATFORM_ARCHON_COOLIFY_READ_TOKEN_REF = "platform:archon:coolify-read-token";
 /**
  * #169: `platform:<service>` for the platform's own mail server (Stalwart),
  * mirroring {@link PLATFORM_AUTH_KEY} exactly.
@@ -395,6 +441,18 @@ export declare function appEnvAppliedScopeKey(entryKey: string): string;
  * would leave a stale container that no plan notices.
  */
 export declare function dbEnvAppliedScopeKey(entryKey: string): string;
+/**
+ * #456: the same marker as {@link dbEnvAppliedScopeKey}, for the chat and
+ * calls-service sibling platform services' own owner/runtime database split
+ * -- in its own `service_db_env_applied.` namespace, never
+ * `dbEnvAppliedScopeKey`'s `db_env_applied.`. Those two services are not
+ * hosting entries, but `dbEnvAppliedScopeKey`'s `entryKey` is an arbitrary
+ * caller-chosen string with no reserved words (`validateHostingEntry` only
+ * requires a DNS label), so a hosting entry a company declares with the key
+ * `chat` or `calls-service` would otherwise read or clear the sibling
+ * service's own marker, and vice versa.
+ */
+export declare function serviceDbEnvAppliedScopeKey(service: 'chat' | 'calls-service'): string;
 /**
  * The settings `coolifyApp` owns on an entry's app (`folder`, `port`,
  * `autoDeploy`) as the JSON the marker below holds. `coolifyApp` records it
@@ -563,6 +621,50 @@ export declare const PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY = "files_ma
  */
 export declare const PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY = "files_applied_hostname";
 export declare const PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY = "files_applied_git_ref";
+/**
+ * #478: the resource key `planNames` plans under and
+ * `FoundryPlatformStepExecutor` dispatches on -- the {@link PLATFORM_FILES_KEY}
+ * shape for the names host (https://github.com/wtfalch/names). `runPlatformSteps`
+ * records the app's uuid under `coolify:app:platform:names` once the step
+ * succeeds, which is what stops `planNames` planning it again.
+ */
+export declare const PLATFORM_NAMES_KEY = "platform:names";
+/**
+ * #478: the held-key ref the names platform secret's full value is
+ * delivered under, once, by {@link FoundryStepExecutorPorts.deliverSecret} --
+ * never the host's app env, which gets only its SHA-256 hash
+ * (`NAMES_PLATFORM_KEY_HASH`). Archon's own `NamesPort` reads the full
+ * secret back from this ref to call names' `mintKey`/`revokeKey`/
+ * `setReservedLabels`.
+ */
+export declare const PLATFORM_NAMES_KEY_REF = "names:platform:key";
+/**
+ * #478: the held-key ref for names' own Cloudflare API token (tunnel edit +
+ * DNS edit on one account) -- the issue's own "never Archon's token": this
+ * is a narrower, names-only credential a human provisions and holds
+ * separately from whatever broader token `PlatformNamesDeps.cloudflare`
+ * uses to stand the host itself up on Coolify.
+ */
+export declare const PLATFORM_NAMES_CLOUDFLARE_TOKEN_REF = "cloudflare:names:apiToken";
+/**
+ * #478: scope keys (colon-free) for the names platform key, the
+ * {@link PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY} pattern once:
+ * the undelivered id is recorded and persisted the moment the secret is
+ * minted, before delivery; the guard is recorded only once it was delivered
+ * AND its hash written to the runner's env. An undelivered id with no guard
+ * means the secret is lost (never kept past that point): the planner
+ * reports it and never mints again. Neither key holds the secret itself.
+ */
+export declare const PLATFORM_NAMES_PLATFORM_KEY_UNDELIVERED_SCOPE_KEY = "names_platform_key_undelivered";
+export declare const PLATFORM_NAMES_PLATFORM_KEY_SET_SCOPE_KEY = "names_platform_key_set";
+/**
+ * #478: the hostname and `gitRef` the last successful names run applied.
+ * `planNames` plans the step again when either differs from the declared
+ * value; a re-run updates `git_branch` and the runner env and redeploys,
+ * and mints no new platform key (the guards above hold).
+ */
+export declare const PLATFORM_NAMES_APPLIED_HOSTNAME_SCOPE_KEY = "names_applied_hostname";
+export declare const PLATFORM_NAMES_APPLIED_GIT_REF_SCOPE_KEY = "names_applied_git_ref";
 /**
  * Options for {@link planPlatform}, replacing four positional arguments that
  * shifted on every merge that added a platform service (#186, #187, #188) --
@@ -601,6 +703,8 @@ export interface PlanPlatformOptions {
         ai?: string;
         archon?: string;
         mail?: string;
+        /** #478: why the names host is blocked, or absent when it is not. */
+        names?: string;
         /**
          * #257: true once a service's database exists but the host built the
          * platform executor with no backup dependencies -- every such service's
@@ -652,7 +756,8 @@ export interface PlanPlatformOptions {
  * Scope for #167: the frame plus one step, {@link planApexZone}. #173 adds
  * {@link planJobs}, #170 adds {@link planSfu}, #168 adds {@link planAuth},
  * #169 adds {@link planMail}, #174 adds {@link planIntegrations}, #171 adds
- * {@link planFiles}, #172 adds {@link planAi} and #175 adds
+ * {@link planFiles}, #172 adds {@link planAi}, #478 adds {@link planNames}
+ * and #175 adds
  * {@link planArchon}, the same way #19 shipped org plan/apply against
  * three singletons before #27, #71, #80 and the rest added the remaining
  * twelve. Until then, a live resource under one of those eventual keys is

package/dist/plan/platform-diff.js

@@ -2,6 +2,7 @@ import { VERSIONS } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY } from '../org.js';
 import { VERSION_CHANGE_KIND, } from '../plan.js';
 import { legacyAppHostname } from './hostnames.js';
+import { withStepSystem } from './step-system.js';
 /**
  * The `Plan` (#19's public contract) a {@link PlatformPlanDetail} carries,
  * mirroring `diff.ts`'s `toPlan`. There is no separate platform-shaped `Plan`
@@ -138,6 +139,23 @@ export const PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY = 'archon_applied_git_ref
  * unrecorded and the old key stays pinned.
  */
 export const PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY = 'archon_integrations_key_synced';
+/**
+ * #467: sha256 of the exact env set the *last confirmed* Archon deploy ran
+ * with, recorded only once that deploy's `waitForHealthyVersion` passed --
+ * mirroring {@link PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY}'s own
+ * confirm-after-health-check timing, generalized from one env to all of
+ * them. `provisionPlatformArchon` clears this to `''` the moment it decides
+ * a redeploy is needed, before attempting it: a deploy that then fails (or
+ * a crash before the health check passes) must leave the attempt
+ * unconfirmed, and the env hash alone cannot tell a failed retry's intended
+ * content apart from a successful one's, since both intend the same bytes.
+ * Without this, a run that writes new envs and then fails before Archon
+ * redeploys -- `envsDiffer` comparing desired envs against the *live*
+ * store, which this run's own write already updated -- leaves a retry
+ * reading no difference at all, and the container stays on the stale
+ * values until someone redeploys by hand (#467).
+ */
+export const PLATFORM_ARCHON_ENVS_DEPLOYED_SCOPE_KEY = 'archon_envs_deployed_hash';
 /**
  * #211 round 4: the broker app id Archon last registered its entry with.
  * `provisionPlatformArchon` reads the broker to register with from
@@ -156,6 +174,21 @@ export const PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY = 'archon_applied_broker_a
  * has recorded it.
  */
 export const PLATFORM_ARCHON_APPLIED_OPERATOR_SCOPE_KEY = 'archon_applied_bootstrap_operator';
+/**
+ * #475: whether the last successful Archon apply patched the app with
+ * `custom_network_aliases` and `is_consistent_container_name_enabled: false`
+ * instead of the old fixed `custom_internal_name` alone. Coolify only runs a
+ * rolling, health-checked deploy -- start the new container, wait, then stop
+ * the old one -- when the consistent-name flag is off; with it on (set by
+ * foundry's own pre-#475 applies, or by hand in the Coolify UI) every deploy
+ * stops the old container before the new one exists, which is what took
+ * Archon down for #475's incident. Absent on every platform applied before
+ * this fix landed; `planArchon` plans the step again until
+ * `provisionPlatformArchon` records it, which only happens once that run's
+ * redeploy has passed its health check -- the same confirm-after-health-check
+ * timing {@link PLATFORM_ARCHON_ENVS_DEPLOYED_SCOPE_KEY} uses.
+ */
+export const PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY = 'archon_applied_rolling_update';
 /**
  * The owner's ZITADEL user id Archon takes as its first operator, from
  * {@link PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY}. Undefined when none is
@@ -343,6 +376,20 @@ export const PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY = 'coolify_platform_archon_
 export const PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF = 'platform:master:coolify-url';
 export const PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF = 'platform:master:coolify-token';
 export const PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF = 'platform:master:cloudflare-token';
+/**
+ * #436: a Coolify API token scoped to `read` only, for Archon's own
+ * `/backups` page (`COOLIFY_URL`/`COOLIFY_READ_TOKEN`, Archon's
+ * `src/lib/backups/coolify.ts`) -- deliberately not
+ * {@link PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF}'s root token, which a
+ * read-only status page must never hold. Coolify's token UI has no API
+ * counterpart to create one (`@wtfalch/providers`'s `CoolifyClient` doc:
+ * "Keys & Tokens -> API tokens" only), so a human creates it in Coolify's
+ * console and holds it under this ref; `provisionPlatformArchon` only reads
+ * it back, and pushes nothing until it is held. `COOLIFY_URL` needs no ref
+ * of its own: it is not secret, and {@link PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF}
+ * already holds the same panel's address.
+ */
+export const PLATFORM_ARCHON_COOLIFY_READ_TOKEN_REF = 'platform:archon:coolify-read-token';
 /**
  * #169: `platform:<service>` for the platform's own mail server (Stalwart),
  * mirroring {@link PLATFORM_AUTH_KEY} exactly.
@@ -439,6 +486,20 @@ export function appEnvAppliedScopeKey(entryKey) {
 export function dbEnvAppliedScopeKey(entryKey) {
     return `db_env_applied.${entryKey}`;
 }
+/**
+ * #456: the same marker as {@link dbEnvAppliedScopeKey}, for the chat and
+ * calls-service sibling platform services' own owner/runtime database split
+ * -- in its own `service_db_env_applied.` namespace, never
+ * `dbEnvAppliedScopeKey`'s `db_env_applied.`. Those two services are not
+ * hosting entries, but `dbEnvAppliedScopeKey`'s `entryKey` is an arbitrary
+ * caller-chosen string with no reserved words (`validateHostingEntry` only
+ * requires a DNS label), so a hosting entry a company declares with the key
+ * `chat` or `calls-service` would otherwise read or clear the sibling
+ * service's own marker, and vice versa.
+ */
+export function serviceDbEnvAppliedScopeKey(service) {
+    return `service_db_env_applied.${service}`;
+}
 export function appSettingsOf(entry) {
     return { folder: entry.folder, port: entry.port, autoDeploy: entry.autoDeploy };
 }
@@ -636,6 +697,50 @@ export const PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY = 'files_management
  */
 export const PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY = 'files_applied_hostname';
 export const PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY = 'files_applied_git_ref';
+/**
+ * #478: the resource key `planNames` plans under and
+ * `FoundryPlatformStepExecutor` dispatches on -- the {@link PLATFORM_FILES_KEY}
+ * shape for the names host (https://github.com/wtfalch/names). `runPlatformSteps`
+ * records the app's uuid under `coolify:app:platform:names` once the step
+ * succeeds, which is what stops `planNames` planning it again.
+ */
+export const PLATFORM_NAMES_KEY = 'platform:names';
+/**
+ * #478: the held-key ref the names platform secret's full value is
+ * delivered under, once, by {@link FoundryStepExecutorPorts.deliverSecret} --
+ * never the host's app env, which gets only its SHA-256 hash
+ * (`NAMES_PLATFORM_KEY_HASH`). Archon's own `NamesPort` reads the full
+ * secret back from this ref to call names' `mintKey`/`revokeKey`/
+ * `setReservedLabels`.
+ */
+export const PLATFORM_NAMES_KEY_REF = 'names:platform:key';
+/**
+ * #478: the held-key ref for names' own Cloudflare API token (tunnel edit +
+ * DNS edit on one account) -- the issue's own "never Archon's token": this
+ * is a narrower, names-only credential a human provisions and holds
+ * separately from whatever broader token `PlatformNamesDeps.cloudflare`
+ * uses to stand the host itself up on Coolify.
+ */
+export const PLATFORM_NAMES_CLOUDFLARE_TOKEN_REF = 'cloudflare:names:apiToken';
+/**
+ * #478: scope keys (colon-free) for the names platform key, the
+ * {@link PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY} pattern once:
+ * the undelivered id is recorded and persisted the moment the secret is
+ * minted, before delivery; the guard is recorded only once it was delivered
+ * AND its hash written to the runner's env. An undelivered id with no guard
+ * means the secret is lost (never kept past that point): the planner
+ * reports it and never mints again. Neither key holds the secret itself.
+ */
+export const PLATFORM_NAMES_PLATFORM_KEY_UNDELIVERED_SCOPE_KEY = 'names_platform_key_undelivered';
+export const PLATFORM_NAMES_PLATFORM_KEY_SET_SCOPE_KEY = 'names_platform_key_set';
+/**
+ * #478: the hostname and `gitRef` the last successful names run applied.
+ * `planNames` plans the step again when either differs from the declared
+ * value; a re-run updates `git_branch` and the runner env and redeploys,
+ * and mints no new platform key (the guards above hold).
+ */
+export const PLATFORM_NAMES_APPLIED_HOSTNAME_SCOPE_KEY = 'names_applied_hostname';
+export const PLATFORM_NAMES_APPLIED_GIT_REF_SCOPE_KEY = 'names_applied_git_ref';
 /**
  * #167: the platform's own diff engine, mirroring `diff.ts`'s
  * `computePlanDetail` for the one shared {@link DeclaredPlatform} record
@@ -650,7 +755,8 @@ export const PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY = 'files_applied_git_ref';
  * Scope for #167: the frame plus one step, {@link planApexZone}. #173 adds
  * {@link planJobs}, #170 adds {@link planSfu}, #168 adds {@link planAuth},
  * #169 adds {@link planMail}, #174 adds {@link planIntegrations}, #171 adds
- * {@link planFiles}, #172 adds {@link planAi} and #175 adds
+ * {@link planFiles}, #172 adds {@link planAi}, #478 adds {@link planNames}
+ * and #175 adds
  * {@link planArchon}, the same way #19 shipped org plan/apply against
  * three singletons before #27, #71, #80 and the rest added the remaining
  * twelve. Until then, a live resource under one of those eventual keys is
@@ -699,6 +805,10 @@ export function planPlatform(platform, live, options = {}) {
     const ai = planAi(platform, recordedIds, blocked.ai);
     if (ai.step)
         plannedSteps.push(ai.step);
+    // #478: independent of auth and files -- the names host needs neither.
+    const names = planNames(platform, recordedIds, blocked.names);
+    if (names.step)
+        plannedSteps.push(names.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.
@@ -732,6 +842,9 @@ export function planPlatform(platform, live, options = {}) {
         integrations.blocked
             ? null
             : versionChangeLine('integrations', recordedIds[PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY], platform.integrations.gitRef, 'git ref, redeploy'),
+        names.blocked
+            ? null
+            : versionChangeLine('names', recordedIds[PLATFORM_NAMES_APPLIED_GIT_REF_SCOPE_KEY], platform.names.gitRef, 'git ref, redeploy'),
         auth.blocked
             ? null
             : versionNotAppliedLine('zitadel', Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_AUTH_KEY)]), recordedIds[PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY], VERSIONS.zitadel),
@@ -763,6 +876,8 @@ export function planPlatform(platform, live, options = {}) {
         unmanaged.push({ description: files.blocked, key: 'files' });
     if (ai.blocked)
         unmanaged.push({ description: ai.blocked, key: 'ai' });
+    if (names.blocked)
+        unmanaged.push({ description: names.blocked, key: 'names' });
     if (archon.blocked)
         unmanaged.push({ description: archon.blocked, key: 'archon' });
     // #398: the old integrations key stays pinned until Archon holds the new
@@ -777,7 +892,7 @@ export function planPlatform(platform, live, options = {}) {
         });
     }
     unmanaged.push(...backups.blocked);
-    return { plannedSteps, unmanaged, versionChanges };
+    return { plannedSteps: plannedSteps.map(withStepSystem), unmanaged, versionChanges };
 }
 /**
  * The platform's own Cloudflare zone for its shared apex (`platform.ts`'s
@@ -1631,6 +1746,62 @@ function planFiles(platform, recordedIds, executorBlocked, authReady, drifted) {
         blocked: null,
     };
 }
+/**
+ * #478: the names host (https://github.com/wtfalch/names) -- its database
+ * (owner and runtime roles), its one Coolify app (no separate migrate app:
+ * the Dockerfile migrates inside the runner's own entrypoint, see
+ * `provisionPlatformNames`'s own doc comment), foundry's own platform key
+ * (minted once, its hash alone written to the runner) and a Cloudflare
+ * tunnel + DNS record at `platform.names.hostname`. One `coolify:app` step
+ * keyed {@link PLATFORM_NAMES_KEY}, the {@link planFiles} bundling shape,
+ * public like {@link planMail}/{@link planAuth} rather than internal-only
+ * like {@link planFiles}/{@link planAi}.
+ *
+ * Idempotent on the recorded app id plus the applied hostname and `gitRef`,
+ * for {@link planAuth}'s own reason: no platform reader reports this
+ * Coolify app. A changed hostname or `gitRef` plans the step again (a
+ * redeploy, no new secret).
+ *
+ * Blocked, not planned: a platform key minted but never delivered (lost,
+ * `ServiceError`-free the way {@link planFiles}'s own management-key check
+ * is), or `executorBlocked` -- the host built no names dependencies, or
+ * (CLAUDE.md's "Human steps") no Cloudflare API token is held yet under
+ * {@link PLATFORM_NAMES_CLOUDFLARE_TOKEN_REF}.
+ */
+function planNames(platform, recordedIds, executorBlocked) {
+    if (!platform.names.enabled)
+        return { step: null, blocked: null };
+    const undelivered = recordedIds[PLATFORM_NAMES_PLATFORM_KEY_UNDELIVERED_SCOPE_KEY];
+    if (undelivered && !recordedIds[PLATFORM_NAMES_PLATFORM_KEY_SET_SCOPE_KEY]) {
+        return {
+            step: null,
+            blocked: `the names host is blocked, not planned: its platform key (${undelivered}) was minted but never delivered and cannot be shown again; remove the recorded key ${PLATFORM_NAMES_PLATFORM_KEY_UNDELIVERED_SCOPE_KEY} to mint a new one`,
+        };
+    }
+    const applied = Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_NAMES_KEY)]) &&
+        recordedIds[PLATFORM_NAMES_APPLIED_HOSTNAME_SCOPE_KEY] === platform.names.hostname &&
+        recordedIds[PLATFORM_NAMES_APPLIED_GIT_REF_SCOPE_KEY] === platform.names.gitRef;
+    if (applied)
+        return { step: null, blocked: null };
+    if (executorBlocked)
+        return { step: null, blocked: executorBlocked };
+    return {
+        step: {
+            action: {
+                system: 'coolify',
+                kind: 'app',
+                key: PLATFORM_NAMES_KEY,
+                desired: { hostname: platform.names.hostname, gitRef: platform.names.gitRef },
+            },
+            step: {
+                description: `provision the names host at ${platform.names.hostname}, with its own database and foundry's platform key`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}
 /**
  * #172: the platform's AI host (https://github.com/wtfalch/ai) -- a Coolify
  * Postgres plus three apps built from that repo's root Dockerfile, one per
@@ -1765,6 +1936,15 @@ function planArchon(platform, recordedIds, executorBlocked, authReady, drifted)
             recordedIds[PLATFORM_AUTH_BROKER_SCOPE_KEY] &&
         (recordedIds[PLATFORM_ARCHON_APPLIED_OPERATOR_SCOPE_KEY] ?? 'none') ===
             (archonBootstrapOperator(recordedIds) ?? 'none') &&
+        // #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
+        // (the consistent-name flag turned on, the alias removed, the health
+        // check disabled) -- `driftedSteps`' `archonRollingUpdateDrifted` catches
+        // that by re-reading the live app, and sets `drifted` below, which plans
+        // the step again the same way an already-`applied` step does for any
+        // other drift reason.
+        recordedIds[PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY] === '1' &&
         !recordedIds[PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY] &&
         // #398: a rotated integrations key id Archon's env was not yet written
         // with (see PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY). Absent

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

@@ -1,5 +1,21 @@
 import type { DeclaredPlatform } from '../platform.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
+ * `bouleHostnameFor` and `hostnames.ts`'s own `<slug>.oikos.host` already
+ * use for a level-1 org's hostnames. `OrgPlatformReadiness.mailHost.apex`
+ * used to be `platform.apex` (the platform's own brand apex, e.g.
+ * `companyincluded.com`), which gave a domainless org `slug@companyincluded.com`
+ * instead of the settled `slug@oikos.host` contract
+ * (`@wtfalch/email`'s `org-mail.ts`'s `resolveDomain` is the only reader of
+ * this `apex`, for a level-1 org alone -- a with-domain org returns
+ * `org.domain` and never looks at it). `mailHost` itself (the MX server's own
+ * hostname, `platformMailMxHost(platform.apex)`) is unaffected: the shared
+ * mail server stays the platform's own, whichever apex a mailbox's address
+ * uses.
+ */
+export declare const NO_DOMAIN_MAIL_APEX = "oikos.host";
 /**
  * https://github.com/wtfalch/foundry/issues/177: what an org step needs to
  * know about the platform it runs on -- whether each shared service it
@@ -30,6 +46,21 @@ export interface OrgPlatformReadiness {
         apex: string;
         mailHost: string;
     } | null;
+    /**
+     * #491 (review round 2): `DeclaredPlatform.apex` itself (not `mailHost.apex`
+     * above, which is the fixed domainless-org fallback, {@link
+     * NO_DOMAIN_MAIL_APEX}) -- `null` only when no platform is declared at all.
+     * Deliberately *not* folded into `mailHost` or gated on mail being enabled
+     * or applied: an org's `coolify:app` step needs to recognise the platform's
+     * own org (its mail domain equals this) even while the platform's mail
+     * server is off or not yet applied -- the first review round gated this on
+     * `mailHost` instead, which let `ensureAppLettermintMail` take the
+     * unprotected path the moment platform mail went from applied back to off
+     * while `MAIL_DOMAIN_SCOPE_KEY` was still recorded as the apex.
+     */
+    platformApex: string | null;
+    /** `DeclaredPlatform.mail.lettermintProjectId`, `null` when undeclared or when no platform is declared. See {@link platformApex}'s own doc comment for why this is unconditional too. */
+    platformLettermintProjectId: string | null;
     /** The files host (#171). Files is always on for every org (#80), so `false` always blocks rather than only mattering when a flag is set. */
     filesReady: boolean;
     /**
@@ -56,6 +87,17 @@ export interface OrgPlatformReadiness {
     authReady: boolean;
     /** The jobs scheduler (#173) is enabled, applied, and its admin token is held. */
     jobsReady: boolean;
+    /**
+     * #317 (F7) and #478: the names service is declared `enabled`, its own
+     * `coolify:app` deploy step has applied (`provisionPlatformNames`), and
+     * the host's executor was built with a `NamesPort` -- the same
+     * `filesReady`/`aiReady` "declared and applied" shape now that #478 built
+     * the deploy step #317 shipped ahead of (this field's own doc comment
+     * used to say there was none; N1 is no longer deployed by hand).
+     */
+    namesReady: boolean;
+    /** `https://<platform.names.hostname>`, which an entry with `uses.names` gets as `NAMES_URL`. `null` until `namesReady`. */
+    namesUrl?: string | null;
     /**
      * The ref of a platform key an applied service needs that is not held yet,
      * `null` when it is held or when the service is not applied. A ref only,
@@ -123,7 +165,9 @@ export declare function orgPlatformReadinessFrom(platform: DeclaredPlatform, pla
  */
 heldRefs?: ReadonlySet<string>, 
 /** True when the host wired no held-keys reader ({@link OrgPlatformReadiness.noKeyReader}). */
-noKeyReader?: boolean): OrgPlatformReadiness;
+noKeyReader?: boolean, 
+/** #317: true when the host's executor was built with a `NamesPort` ({@link OrgPlatformReadiness.namesReady}). */
+namesPortPresent?: boolean): OrgPlatformReadiness;
 /**
  * #177: {@link AgoraHostValues} derived from the same platform state, rather
  * than requiring a bespoke host-supplied `AgoraHostPort` for values the

package/dist/plan/platform-org.js

@@ -1,5 +1,21 @@
-import { JOBS_SCHEDULER_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, platformMailMxHost, } from './platform-diff.js';
+import { JOBS_SCHEDULER_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_NAMES_KEY, platformMailMxHost, } from './platform-diff.js';
 import { FILES_MANAGEMENT_KEY_REF, JOBS_ADMIN_TOKEN_REF, PLATFORM_AI_MANAGEMENT_KEY_REF, } from './platform-providers.js';
+/**
+ * #443: the no-domain company mail apex -- `<slug>.oikos.host`, the same
+ * fixed suffix `agora.ts`'s `agoraHostnameFor`, `boule.ts`'s
+ * `bouleHostnameFor` and `hostnames.ts`'s own `<slug>.oikos.host` already
+ * use for a level-1 org's hostnames. `OrgPlatformReadiness.mailHost.apex`
+ * used to be `platform.apex` (the platform's own brand apex, e.g.
+ * `companyincluded.com`), which gave a domainless org `slug@companyincluded.com`
+ * instead of the settled `slug@oikos.host` contract
+ * (`@wtfalch/email`'s `org-mail.ts`'s `resolveDomain` is the only reader of
+ * this `apex`, for a level-1 org alone -- a with-domain org returns
+ * `org.domain` and never looks at it). `mailHost` itself (the MX server's own
+ * hostname, `platformMailMxHost(platform.apex)`) is unaffected: the shared
+ * mail server stays the platform's own, whichever apex a mailbox's address
+ * uses.
+ */
+export const NO_DOMAIN_MAIL_APEX = 'oikos.host';
 /**
  * What an org's plan reads when no platform is declared: nothing is ready, so
  * every org step that depends on a platform service is blocked (#177). A host
@@ -9,11 +25,14 @@ import { FILES_MANAGEMENT_KEY_REF, JOBS_ADMIN_TOKEN_REF, PLATFORM_AI_MANAGEMENT_
  */
 export const DEFAULT_ORG_PLATFORM_READINESS = {
     mailHost: null,
+    platformApex: null,
+    platformLettermintProjectId: null,
     filesReady: false,
     aiReady: false,
     callsReady: false,
     authReady: false,
     jobsReady: false,
+    namesReady: false,
     missingKeys: { files: null, ai: null, jobs: null },
 };
 /** The held-key refs an org step needs from the platform, one per service. */
@@ -60,11 +79,14 @@ export function orgPlatformReadinessFrom(platform, platformRecordedIds,
  */
 heldRefs, 
 /** True when the host wired no held-keys reader ({@link OrgPlatformReadiness.noKeyReader}). */
-noKeyReader = false) {
+noKeyReader = false, 
+/** #317: true when the host's executor was built with a `NamesPort` ({@link OrgPlatformReadiness.namesReady}). */
+namesPortPresent = false) {
     const mailApplied = platform.mail.enabled && coolifyAppApplied(platformRecordedIds, PLATFORM_MAIL_KEY);
     const filesApplied = platform.files.enabled && coolifyAppApplied(platformRecordedIds, PLATFORM_FILES_KEY);
     const aiApplied = platform.ai.enabled && coolifyAppApplied(platformRecordedIds, PLATFORM_AI_KEY);
     const jobsApplied = platform.jobs.enabled && Boolean(platformRecordedIds[`coolify:jobs:${JOBS_SCHEDULER_KEY}`]);
+    const namesApplied = platform.names.enabled && coolifyAppApplied(platformRecordedIds, PLATFORM_NAMES_KEY);
     const missing = (applied, ref) => applied && heldRefs !== undefined && !heldRefs.has(ref) ? ref : null;
     const missingKeys = {
         files: missing(filesApplied, ORG_PLATFORM_KEY_REFS.files),
@@ -73,8 +95,15 @@ noKeyReader = false) {
     };
     return {
         mailHost: mailApplied
-            ? { apex: platform.apex, mailHost: platformMailMxHost(platform.apex) }
+            ? { apex: NO_DOMAIN_MAIL_APEX, mailHost: platformMailMxHost(platform.apex) }
             : null,
+        // #491 (review round 2): unconditional -- `platform` here is always a
+        // real declared platform (this function's own doc comment: "the platform
+        // is either declared ... or this is never called"), so its apex and its
+        // mail.lettermintProjectId are facts regardless of whether mail itself is
+        // enabled or applied.
+        platformApex: platform.apex,
+        platformLettermintProjectId: platform.mail.lettermintProjectId ?? null,
         filesReady: filesApplied && missingKeys.files === null,
         filesUrl: filesApplied
             ? (platformRecordedIds[PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY] ?? null)
@@ -84,6 +113,8 @@ noKeyReader = false) {
         callsReady: platform.sfu.enabled,
         authReady: platform.auth.enabled && coolifyAppApplied(platformRecordedIds, PLATFORM_AUTH_KEY),
         jobsReady: jobsApplied && missingKeys.jobs === null,
+        namesReady: namesApplied && namesPortPresent,
+        namesUrl: namesApplied && namesPortPresent ? `https://${platform.names.hostname}` : null,
         missingKeys,
         ...(noKeyReader ? { noKeyReader } : {}),
     };