@wtfalch/foundry 0.17.0 → 0.17.1

package/dist/plan/platform-diff.js

@@ -139,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
@@ -157,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
@@ -454,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 };
 }
@@ -651,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
@@ -665,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
@@ -714,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.
@@ -747,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),
@@ -778,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
@@ -1646,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
@@ -1780,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

@@ -46,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;
     /**
@@ -72,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,
@@ -139,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,4 +1,4 @@
-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
@@ -25,11 +25,14 @@ export const NO_DOMAIN_MAIL_APEX = 'oikos.host';
  */
 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. */
@@ -76,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),
@@ -91,6 +97,13 @@ noKeyReader = false) {
         mailHost: mailApplied
             ? { 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)
@@ -100,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 } : {}),
     };

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

@@ -131,6 +131,12 @@ export interface FoundryPlatformStepExecutorOptions {
      * `platform.ai.enabled` without it gets the step reported as blocked.
      */
     ai?: PlatformAiDeps;
+    /**
+     * #478: dependencies for `coolify:app` keyed {@link PLATFORM_NAMES_KEY} --
+     * optional for the same reason as `auth`; a host that declares
+     * `platform.names.enabled` without it gets the step reported as blocked.
+     */
+    names?: PlatformNamesDeps;
     /**
      * #175: dependencies for `coolify:app` keyed {@link PLATFORM_ARCHON_KEY}
      * -- optional for the same reason as {@link auth}.
@@ -197,6 +203,9 @@ export interface FoundryPlatformStepExecutorOptions {
  * #172 adds `coolify:app` keyed {@link PLATFORM_AI_KEY}, the platform's AI
  * host ({@link provisionPlatformAi}), once a host passes {@link PlatformAiDeps}.
  *
+ * #478 adds `coolify:app` keyed {@link PLATFORM_NAMES_KEY}, the names host
+ * ({@link provisionPlatformNames}), once a host passes {@link PlatformNamesDeps}.
+ *
  * #175 adds `coolify:app` keyed {@link PLATFORM_ARCHON_KEY}, Archon itself
  * ({@link provisionPlatformArchon}), once a host passes
  * {@link PlatformArchonDeps}.
@@ -216,6 +225,7 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
     private readonly integrations?;
     private readonly files?;
     private readonly ai?;
+    private readonly names?;
     private readonly archon?;
     private readonly backup?;
     constructor(cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'createZone'>, declaredOrgStore: Pick<DeclaredOrgStore, 'findOrgIdForZone' | 'list' | 'get'>, options?: FoundryPlatformStepExecutorOptions);
@@ -226,6 +236,7 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
         files?: string;
         integrations?: string;
         ai?: string;
+        names?: string;
         archon?: string;
         mail?: string;
         backupExecutorMissing?: boolean;
@@ -811,6 +822,39 @@ export declare const FILES_MANAGEMENT_KEY_ID = "foundry-1";
 export declare const FILES_MANAGEMENT_KEY_REF = "files:platform:managementKey";
 /** The ref the files host's introspection client secret is delivered under. */
 export declare const FILES_INTROSPECTION_SECRET_REF = "zitadel:platform:files:introspection";
+export interface PlatformNamesRuntime {
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** Tries at handing the platform key to the host (default 3). */
+    deliverAttempts?: number;
+    readyTimeoutMs?: number;
+    readyIntervalMs?: number;
+}
+export interface PlatformNamesDeps {
+    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'createDockerfileApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy' | 'deployAndWait' | 'raw'>;
+    cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'findTunnelByName' | 'createTunnel' | 'putTunnelConfig' | 'getTunnelToken' | 'findDnsRecord' | 'createDnsRecord' | 'updateDnsRecord'>;
+    deliverSecret: FoundryStepExecutorPorts['deliverSecret'];
+    /**
+     * Reads the names service's own Cloudflare API token back, held under
+     * {@link PLATFORM_NAMES_CLOUDFLARE_TOKEN_REF} -- a human step (the issue's
+     * own "Human steps"), never minted here: foundry has no Cloudflare
+     * account of its own to carve that token out of. Absent, or with nothing
+     * held under that ref yet, is reported blocked by `blockedSteps`
+     * ({@link namesBlockedReason}), never planned to throw.
+     */
+    heldKeys?: {
+        resolve(ref: string): Promise<string | null>;
+    };
+    /**
+     * The Cloudflare account id the token above is scoped to. Not a secret --
+     * a plain config value beside the credential it travels with, the same
+     * way {@link PlatformFilesDeps.r2}'s bucket name is.
+     */
+    cloudflareAccountId?: string;
+    /** Clock, sleep and fetch for the readiness wait and delivery retries; real ones by default. */
+    runtime?: PlatformNamesRuntime;
+}
 /**
  * #174: everything {@link provisionPlatformIntegrations} needs beyond
  * {@link PlatformStepExecutionContext} -- a bundle, like