@wtfalch/foundry 0.6.0 → 0.8.0

package/dist/plan/executor.d.ts

@@ -2,6 +2,7 @@ import type { OrgMailOptions, OrgMailOrg, OrgMailResult } from '@wtfalch/email/p
 import type { DeclaredOrg, HostingBuildPack } from '../org.js';
 import type { DeclaredOrgStore } from '../store.js';
 import type { StepAction } from './diff.js';
+import { type LoginHostBindingsPort } from './login-host.js';
 import { type MailCopyPort } from './mail-copy.js';
 import type { DestroyTarget, StepDestroyer, StepExecutionContext, StepExecutor } from './plan-apply.js';
 /**
@@ -140,13 +141,14 @@ export interface CoolifyPort {
     }>>;
     /**
      * Upsert environment variables on an application in one call — used here to
-     * push the database's `internal_db_url` in as the app's `DATABASE_URL`
-     * (hosting-wiring campaign), and, for the cms app, its `DATABASE_URL_OWNER`
-     * plus a freshly minted `DATABASE_URL` runtime-role credential (#117). Each
-     * value is a live credential: it must reach this call and nothing else —
-     * never a step's return value, `serviceIds` (hence the store), an audit
-     * record, a log or a thrown error. See `coolifyApp`'s `pushDatabaseUrl` and
-     * `cmsSite`'s `ensureCmsRuntimeUrl`.
+     * push the org's own app's `DATABASE_URL_OWNER` plus a freshly minted
+     * `DATABASE_URL` runtime-role credential (hosting-wiring campaign, split
+     * per #239 the same way #117 already splits the cms app's), and likewise
+     * for the cms app itself. Each value is a live credential: it must reach
+     * this call and nothing else — never a step's return value, `serviceIds`
+     * (hence the store), an audit record, a log or a thrown error. See
+     * `coolifyApp`'s `pushDatabaseUrl`/`ensureAppRuntimeUrl` and `cmsSite`'s
+     * `ensureCmsRuntimeUrl`.
      */
     bulkUpsertEnvs(applicationUuid: string, envs: Array<{
         key: string;
@@ -280,6 +282,59 @@ export interface CoolifyPort {
      * deploy` method-for-method.
      */
     deploy(uuid: string, force?: boolean): Promise<unknown>;
+    /**
+     * #257: every S3-compatible storage registered for the team -- matches
+     * `CoolifyClient.listS3Storages` method-for-method. `provisionPlatformBackup`
+     * (`platform-providers.ts`) uses this to find the platform's shared R2
+     * bucket by name before registering a second one.
+     */
+    listS3Storages(): Promise<Array<{
+        uuid: string;
+        name: string;
+        bucket: string;
+        endpoint: string;
+        is_usable?: boolean;
+    }>>;
+    /**
+     * #257: registers a bucket as a Coolify team S3 storage -- matches
+     * `CoolifyClient.createS3Storage` method-for-method.
+     */
+    createS3Storage(input: {
+        name: string;
+        description?: string;
+        endpoint: string;
+        bucket: string;
+        region: string;
+        key: string;
+        secret: string;
+        is_usable?: boolean;
+    }): Promise<{
+        uuid: string;
+    }>;
+    /**
+     * #257: the scheduled backups of one database -- matches
+     * `CoolifyClient.listDatabaseBackups` method-for-method.
+     * `provisionPlatformBackup` reads this to decide whether a database
+     * already has an enabled, `save_s3` schedule before creating a second one.
+     */
+    listDatabaseBackups(databaseUuid: string): Promise<Array<{
+        uuid: string;
+        frequency: string;
+        enabled: boolean;
+        save_s3: boolean;
+    }>>;
+    /**
+     * #257: schedules dumps of a database to the registered S3 storage --
+     * matches `CoolifyClient.createDatabaseBackup` method-for-method.
+     */
+    createDatabaseBackup(databaseUuid: string, input: {
+        frequency: string;
+        enabled?: boolean;
+        save_s3?: boolean;
+        s3_storage_uuid?: string;
+    }): Promise<{
+        uuid: string;
+    }>;
 }
 /**
  * The Cloudflare calls this executor makes, shaped to match
@@ -342,11 +397,8 @@ export interface CloudflarePort {
     deleteAccessApp(appId: string): Promise<void>;
     /**
      * `FoundryPlanApply.destroy`'s teardown of any DNS record foundry created
-     * for the org. Nothing in this executor creates or records one yet (Finding,
-     * this campaign's report: no `cloudflare:dns` resource kind exists in
-     * `diff.ts`/`executor.ts` today), so `destroy` has no dispatch target for
-     * it either -- this port method exists ready for whichever step starts
-     * creating one.
+     * for the org -- `destroy`'s `cloudflare:tunnel` case uses it to remove
+     * every CNAME {@link publishTunnelDnsRecords} published (#236).
      */
     deleteDnsRecord(zoneId: string, recordId: string): Promise<void>;
     /** `coolify:mail`'s lookup of an existing MX/TXT record before upserting it, filtered by type so a stale record of a different type is never mistaken for a match. */
@@ -356,6 +408,27 @@ export interface CloudflarePort {
         content: string;
         name: string;
     }>>;
+    /**
+     * #236: `destroy`'s `cloudflare:tunnel` case and
+     * {@link FoundryStepExecutor.deleteStaleTunnelDnsRecords} each fall back to
+     * this for a domain recorded before
+     * {@link CLOUDFLARE_TUNNEL_DNS_HOSTNAMES_SCOPE_KEY} existed, with no
+     * hostname list to look up instead -- the one case left that must still
+     * see every CNAME in the zone, not one matched by name. Round 3: this is
+     * no longer either caller's normal path, since the real adapter
+     * (`@wtfalch/providers`' `cloudflare.ts`) asks for one page of 100 and
+     * never walks `result_info.total_pages`, so a zone with more records than
+     * that would silently lose everything past the first page.
+     */
+    listDnsRecords(zoneId: string, opts?: {
+        type?: string;
+        name?: string;
+    }): Promise<Array<{
+        id: string;
+        type: string;
+        content: string;
+        name: string;
+    }>>;
     createDnsRecord(zoneId: string, rec: {
         type: string;
         name: string;
@@ -618,22 +691,56 @@ export interface ZitadelPort {
     }>;
     deleteApp(orgId: string, projectId: string, appId: string): Promise<void>;
     /**
-     * `zitadelApp`'s kind-change path reads this to find an app a prior,
+     * `zitadelApp`'s kind-change path reads `apps` to find an app a prior,
      * lost-response create already made under the new name, before calling
      * `createOidcApp`/`createApiApp` again and orphaning that one under the
-     * same name. Matches `@wtfalch/providers/zitadel`'s `ZitadelClient.
-     * listApps` return shape exactly, so that client satisfies this port with
-     * no adapter -- it does not carry `clientId`/`clientSecret` (that provider
+     * same name -- it does not carry `clientId`/`clientSecret` (that provider
      * method never parses either, and a secret is minted once, on creation,
      * never handed back again), which is why the reuse path below cannot
      * re-deliver either one.
-     */
-    listApps(orgId: string, projectId: string): Promise<Array<{
-        id: string;
-        name: string;
-        appType: 'web' | 'native' | 'api';
-        state: string;
-    }>>;
+     *
+     * `loginBaseUri` and `complete` are `zitadelLoginHost`'s own #274
+     * additions, neither satisfied by the real (unpublished-ahead-of-pin)
+     * `@wtfalch/providers` `ZitadelClient.listApps` yet -- {@link
+     * adaptZitadelListApps} below is the adapter for both until a tracked
+     * change lands (https://github.com/wtfalch/providers/issues/29):
+     *
+     * - `loginBaseUri`: each app's current ZITADEL Login V2 base URI, used to
+     *   decide whether a host a company-login-host change left behind is
+     *   still in use -- rather than guessing from which apps this step itself
+     *   repointed. Three states, not two (#274 fix round 4): a `string` is
+     *   the URI itself; `null` means this call *read* the app and it has
+     *   never had one set -- common, and never a reason to keep a host
+     *   pending; `undefined` means this call could not read the field at all
+     *   (every app, through {@link adaptZitadelListApps}, until the tracked
+     *   change above lands) and is the only one of the three
+     *   `zitadelLoginHost` fails a pending host closed over. Collapsing
+     *   "confirmed unset" into "unreadable" would never let a host clear once
+     *   an app with no login flow of its own existed, forever, even after the
+     *   tracked change lands and genuinely-unset apps start reporting `null`.
+     *   The real client's own `_search` response parsing (`appFrom`)
+     *   deliberately reads only enough of each app to classify its kind,
+     *   "everything else... ignored on purpose".
+     * - `complete`: whether this call read every one of ZITADEL's own result
+     *   pages, not only the first -- the real client's `_search` call sends
+     *   no `query.offset`/`limit` yet, so {@link adaptZitadelListApps} reports
+     *   `false` until that lands. #274 fix round 3: a result count alone can
+     *   never answer this (any threshold guessed at the boundary between
+     *   "every app fit on one page" and "the page was cut off" is
+     *   indistinguishable from the server's own page size, which nothing here
+     *   is told), so `zitadelLoginHost` treats `complete: false` as "cannot
+     *   safely tell" rather than trusting however many apps did come back.
+     */
+    listApps(orgId: string, projectId: string): Promise<{
+        apps: Array<{
+            id: string;
+            name: string;
+            appType: 'web' | 'native' | 'api';
+            state: string;
+            loginBaseUri?: string | null;
+        }>;
+        complete: boolean;
+    }>;
     /**
      * The org-owner flow (goal line): find-or-create the human user by email in
      * the org, then have ZITADEL email them an invite to set up a passkey.
@@ -766,6 +873,65 @@ export interface ZitadelPort {
      * reports no longer live is never attempted at all.
      */
     listLoginClientPats(orgId: string, userId: string): Promise<string[]>;
+    /**
+     * #267: adds the org's own company login host to the ZITADEL instance's
+     * trusted domains (`@wtfalch/providers`' `ZitadelClient.ensureTrustedDomain`)
+     * -- the functionally critical half of `zitadelLoginHost` below, per
+     * `auth/docs/company-login-hosts.md`'s enforcement section: "the issuer
+     * refuses a public host that is not one of the instance's trusted
+     * domains." Idempotent: lists first, adds only if not already trusted.
+     */
+    ensureTrustedDomain(domain: string): Promise<{
+        added: boolean;
+    }>;
+    /**
+     * #274: removes a host from the ZITADEL instance's trusted domains
+     * (`@wtfalch/providers`' `ZitadelClient.deleteTrustedDomain`) -- the old
+     * host a company login host change or an org destroy leaves behind, which
+     * {@link ensureTrustedDomain} only ever adds to, never removes from. No
+     * idempotency wrapper on the real client's own side (matching `deleteApp`/
+     * `deleteOrg`/`deleteProject`): a host already gone throws the same
+     * `status`-bearing not-found `isNotFoundError` catches everywhere else in
+     * this package.
+     */
+    deleteTrustedDomain(domain: string): Promise<void>;
+    /**
+     * #267: moves an already-created app's Login V2 base URI, read-modify-
+     * write (`@wtfalch/providers`' `ZitadelClient.updateOidcAppLoginBaseUri`).
+     * `zitadelLoginHost` below calls this for each live app whose client id
+     * the binding holds; `zitadelApp` never sets it at creation.
+     */
+    updateOidcAppLoginBaseUri(orgId: string, projectId: string, appId: string, loginBaseUri: string): Promise<void>;
+}
+/**
+ * #274 fix round 4: bridges `@wtfalch/providers`' real `ZitadelClient.
+ * listApps` -- a plain array, with no `loginBaseUri` or completeness signal
+ * -- into {@link ZitadelPort.listApps}'s own shape, so a host wiring that
+ * real client in satisfies this port without reaching into `executor.ts`
+ * itself to build the wrapper by hand. `complete: false` on every call:
+ * the real client's own `_search` request has no pagination on it yet
+ * (https://github.com/wtfalch/providers/issues/29), so this adapter cannot
+ * promise it read more than one page. `loginBaseUri` comes back `undefined`
+ * for every app for the identical reason -- the real client does not read
+ * it back at all yet, not "read it back as absent" -- which is exactly the
+ * state `zitadelLoginHost`'s fail-closed rule exists for: every pending
+ * host stays pending until the tracked change above lands and this adapter
+ * (or its replacement) can start reporting `string | null` for real.
+ */
+export declare function adaptZitadelListApps(client: {
+    listApps(orgId: string, projectId: string): Promise<ZitadelListAppsRawApp[]>;
+}): ZitadelPort['listApps'];
+/**
+ * The real `@wtfalch/providers` `ZitadelClient.listApps`' own return shape
+ * (its `ZitadelApp`) -- restated rather than imported, the same rule this
+ * package's doc comments already follow wherever a provider type is cited
+ * without a runtime dependency on the package that owns it existing yet.
+ */
+export interface ZitadelListAppsRawApp {
+    id: string;
+    name: string;
+    appType: 'web' | 'native' | 'api';
+    state: string;
 }
 /**
  * Provisions one org's organisation on Files (#80), matching
@@ -959,6 +1125,15 @@ export interface FoundryStepExecutorPorts {
      * step throws. The planner blocks these steps first while a key is not held.
      */
     platformOrg?: PlatformOrgPortSource;
+    /**
+     * #267: zitadel-login's own `LOGIN_HOST_BINDINGS` entry for the org -- see
+     * {@link LoginHostBindingsPort}'s own doc comment. Optional the same way
+     * `jobsScheduler`/`mailCopy` are: a host that has not wired this yet gets no
+     * login-host step at all -- the planner reports it blocked (the host also
+     * sets `FoundryPlanApplyOptions.loginHostBindings`), so nothing is trusted
+     * or repointed without the binding.
+     */
+    loginHostBindings?: LoginHostBindingsPort;
     /**
      * Hands a just-minted, one-time secret (today: an API app's
      * `clientSecret`) to the host, immediately after the provider returns it
@@ -1060,6 +1235,74 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * recorded).
      */
     private zitadelOwner;
+    /**
+     * `plan/diff.ts`'s `planLoginHost` (#267): adds the org's own company
+     * login host (`action.desired.host`) to the ZITADEL instance's trusted
+     * domains, writes zitadel-login's binding, then repoints the apps whose
+     * client id that binding holds. Apps created later are not in it yet:
+     * the next run replans (`diff.ts`'s `planLoginHost`) and moves them.
+     *
+     * #274: when the org's host has moved (`recorded[key]`, the *previous*
+     * run's resourceId, differs from this run's `host`), also removes every
+     * host that is no longer the org's current one from both places --
+     * `ensureTrustedDomain` and `upsertBinding` above only ever add, so
+     * without this an old host stays trusted and bound forever, and a later
+     * org that reuses the old slug inherits it unasked.
+     *
+     * #274 fix round 2: this always returns `host` -- the *current* desired
+     * host -- as its `resourceId`, never an old one, however many of its
+     * removals are still outstanding. Fix round 1 returned `previousHost`
+     * while a removal was skipped, banking on `planLoginHost` replanning the
+     * whole step off that mismatch alone; that loses track of the *new* host
+     * the moment a second host change moves `previousHost` on again (A -> B
+     * skipped, then B -> C: A's own removal has nothing left recording it was
+     * ever owed). `LOGIN_HOST_PENDING_REMOVAL_SCOPE_KEY`
+     * (`pendingRemovalHosts`/`pendingRemovalState`, `login-host.ts`) is the
+     * durable record instead -- every host still awaiting removal, independent
+     * of which one is current -- and `planLoginHost` replans the step whenever
+     * it is non-empty, not only when the current host itself differs.
+     *
+     * Whether a host is still "in use" is decided from each live app's actual
+     * ZITADEL Login V2 base URI (`ZitadelPort.listApps`' `loginBaseUri`), not
+     * from `boundAppIds` membership: fix round 1 skipped removal only while an
+     * app outside `boundAppIds` existed, but `boundAppIds` is deliberately
+     * narrower than "every live app" (it excludes `native`/`api` apps and any
+     * `web` app without a recorded client id yet) and a host can safely be
+     * removed even while such an app exists, so long as nothing is actually
+     * pointed at it. Removing by the wrong signal either breaks sign-in (an
+     * app repointed is not the same fact as an app with no client id yet) or
+     * strands a host forever (an org with a `native`/`api` app would never
+     * satisfy "every live app bound").
+     *
+     * #274 fix round 3, four more defects fix round 2 left:
+     *
+     * 1. The *current* host is excluded from the candidates for removal.
+     *    Without this, A -> B (A pending, not yet safe) -> A deletes the host
+     *    this very call just (re-)trusted and bound: a host already in
+     *    `LOGIN_HOST_PENDING_REMOVAL_SCOPE_KEY` from an earlier run can be
+     *    exactly the one the org's host is moving back to.
+     * 2. Fail closed on missing information, rather than ever reading
+     *    "nothing uses it" off of one: an app whose `loginBaseUri` cannot be
+     *    read at all (`undefined` -- which, until a real adapter is wired per
+     *    `ZitadelPort.listApps`'s own doc comment, is every app, every call)
+     *    means every pending host stays pending this run, not just the ones a
+     *    narrower check happened to miss.
+     * 3. Same fail-closed rule for `listApps`' own `complete` flag: an
+     *    incomplete read (today, always, for the identical reason) means the
+     *    set of apps this call saw could be missing one still pointed at a
+     *    pending host, so nothing is removed off of it either.
+     * 4. A base URI compares after lowercasing and trimming its trailing
+     *    `/` (`normalizedLoginBaseUri`) -- ZITADEL's own value and the one
+     *    this step constructs are not guaranteed to agree on case or a
+     *    trailing slash, and a comparison that is case- or slash-sensitive
+     *    both ways can report "in use" as "not" by accident.
+     * 5. Each live app's base URI is read as of *after* this call's own
+     *    repoint loop above, not the stale value `listApps` returned before
+     *    it: a bound app this very call just repointed away from a pending
+     *    host must not hold that host pending for one more run only because
+     *    the snapshot taken before the repoint still named it.
+     */
+    private zitadelLoginHost;
     /**
      * `plan/diff.ts`'s `planCustomers` (plan gap A9): the org's customers sign
      * in through a second ZITADEL org, `<slug> customers`, with
@@ -1108,28 +1351,34 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     private ensureLogVolume;
     private coolifyDatabase;
     /**
-     * Pushes the database's connection string into the app's environment as
-     * `DATABASE_URL` -- never also as `DATABASE_URL_OWNER` (Decision, this
-     * campaign's report). Archon's own boot script
-     * (`archon/scripts/migrate-and-start.sh`) treats a bare `DATABASE_URL` with
-     * no `DATABASE_URL_OWNER` as "before the split": it migrates and serves as
-     * the one role it has, which is exactly what a database Coolify just
-     * created (one superuser role, no separate runtime role yet) is. Setting
-     * both to the *same* superuser URL would instead take the split branch --
-     * `db-role-guard.sh` then refuses to boot, since `DATABASE_URL_OWNER` being
-     * set means it expects `DATABASE_URL` to connect as a distinct,
-     * non-superuser runtime role (`<database>_rt`), which nothing here creates.
-     * Minting that role's own password and URL is a provisioning step of its
-     * own, not built here (Finding, this campaign's report).
+     * Pushes the database's connection string into the app's environment,
+     * split the same way `cmsSite`'s own database is (#117, #239): the
+     * superuser connection as `DATABASE_URL_OWNER`, and a distinct, restricted
+     * `<dbName>_rt` role's connection as `DATABASE_URL`. Archon's and manage's
+     * own boot scripts (`db-role-guard.sh`) refuse to start against a
+     * superuser `DATABASE_URL`, and lokessmie's refuses to start without
+     * `DATABASE_URL_OWNER` at all -- a bare superuser `DATABASE_URL` with no
+     * `DATABASE_URL_OWNER` is "before the split" there too.
      *
-     * The connection string is a live credential
-     * (`postgres://user:password@host/db`): it is read from
-     * `CoolifyPort.getDatabase` and handed straight to `bulkUpsertEnvs` and
-     * nowhere else in this class -- never returned, never recorded in
-     * `serviceIds` (hence never in the store or an audit record), never logged,
-     * never interpolated into a thrown error.
+     * Both connection strings are live credentials
+     * (`postgres://user:password@host/db`): read from `CoolifyPort.getDatabase`
+     * (or minted here, for the runtime one) and handed straight to
+     * `bulkUpsertEnvs` and nowhere else in this class -- never returned, never
+     * recorded in `serviceIds` (hence never in the store or an audit record),
+     * never logged, never interpolated into a thrown error.
      */
     private pushDatabaseUrl;
+    /**
+     * `null` once the app already has a `DATABASE_URL` -- never rotated, the
+     * same rule `ensureCmsRuntimeUrl` follows and for the same reason: the
+     * app's own boot script creates or updates the live `<dbName>_rt` Postgres
+     * role from exactly the username/password this method mints, once:
+     * overwriting `DATABASE_URL` on a later apply would leave that
+     * already-created role's real password out of sync with whatever foundry
+     * hands the app next. See `ensureCmsRuntimeUrl`'s own doc comment for the
+     * parsing and encoding choices this mirrors exactly.
+     */
+    private ensureAppRuntimeUrl;
     /**
      * Pushes what the org's app needs to sign a user in through ZITADEL (gap
      * P2, `.plans/2026-09-26-level-1-org-map.md`) -- a second `bulkUpsertEnvs`
@@ -1146,8 +1395,10 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * (`AUTH_CLIENT_ID`), all ordered before `coolify:app` for exactly this
      * reason. `AUTH_APP_KEY` (#206 -- which broker an org's app registers with
      * is its own design question, left out of #204's own "How" rather than
-     * guessed) and DATABASE_URL_OWNER (a runtime-role split not built yet,
-     * `pushDatabaseUrl`'s own doc comment) are out of scope here (task brief).
+     * guessed) is out of scope here (task brief). `DATABASE_URL_OWNER`/
+     * `DATABASE_URL` are pushed by `pushDatabaseUrl` instead, not here --
+     * that call runs only once `hosting.database` is declared and
+     * provisioned, where this one is unconditional (#239).
      */
     private pushAppEnv;
     /**
@@ -1523,6 +1774,89 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     /** `deliverSecret`, tried up to {@link JOBS_DELIVERY_ATTEMPTS} times; true once one attempt succeeds. */
     private deliverWithRetry;
     private cloudflareTunnel;
+    /**
+     * #236: when this tunnel's DNS was last published under a domain that
+     * differs from the one `org` now declares, deletes every CNAME in the
+     * *old* domain's zone that points at this tunnel, so a domain switch
+     * never leaves the old domain still answering for it. Takes the previous
+     * domain and hostnames as plain arguments rather than reading them off
+     * `context` itself (round 3): `cloudflareTunnel` reads the old values
+     * before calling either this or `publishTunnelDnsRecords`, and (round 4
+     * finding 3) does not record the new domain/hostnames until *after* this
+     * method has returned, so a crash here still sees the old domain on retry.
+     * A no-op when the old zone itself is already gone.
+     *
+     * `previousHostnames` (round 3) is {@link CLOUDFLARE_TUNNEL_DNS_HOSTNAMES_SCOPE_KEY}'s
+     * recorded list, looked up one by one instead of a zone-wide
+     * `listDnsRecords` -- the real adapter's version of that call asks for one
+     * page and never walks the rest. A domain change recorded before that key
+     * existed falls back to the old zone-wide pass, the one case where no
+     * hostname list was ever written to look up instead.
+     *
+     * `previousTunnelId` (round 4 finding 1): the old domain's CNAMEs were
+     * published under whatever tunnel id was live the *last* time this step
+     * recorded that domain, which is `previousTunnelId`, not necessarily
+     * `tunnelId` -- a tunnel recreated under the same name
+     * (`findTunnelByName` returning a new id) in the same apply that also
+     * changes the domain leaves the old domain's records pointed at the old
+     * id. Matching only `tunnelId`'s target left them live forever. Both
+     * targets are checked so this stays a no-op once a retry has already
+     * moved the old domain onto the new id.
+     */
+    private deleteStaleTunnelDnsRecords;
+    /**
+     * #236: upserts a proxied CNAME to this tunnel for each of
+     * `tunnelIngressHostnames(org)` that actually belongs to `domain`'s own
+     * zone -- a hosting app still served off the shared `*.oikos.host`
+     * wildcard tunnel (`scripts/shared-ingress.mjs`) can appear in that list
+     * alongside `agora.<domain>` (#164's unconditional Agora hostname) when
+     * `hosting.usesDomain` is off, and `<slug>.oikos.host` is not this org's
+     * zone to touch.
+     *
+     * Checks every hostname for a conflicting record *before* writing any
+     * (round 2 finding: a conflict found only partway through a hostname-by-
+     * hostname pass left earlier hostnames written but the domain never
+     * recorded -- an orphaned partial write). An existing A or AAAA record,
+     * or a CNAME already pointed anywhere but this tunnel or (round 3) its own
+     * immediately prior tunnel id, blocks the whole step with a named
+     * conflict rather than being adopted or replaced, the same do-not-adopt
+     * policy {@link cloudflareZone} itself follows for the zone. A CNAME
+     * already pointed at this tunnel is left alone, so a second apply changes
+     * nothing. The caller ({@link cloudflareTunnel}) records the domain and the
+     * returned hostname list as scope ids only once this method -- and, on a
+     * domain change, the old domain's own cleanup -- has returned successfully
+     * (round 4 finding 3), so a crash mid-write is recovered by re-running
+     * this same idempotent step, never silently skipped.
+     *
+     * Round 3: `previousTunnelId` is the tunnel id this same step recorded
+     * last time it ran (`cloudflareTunnel`'s own `cloudflare:tunnel:<key>`
+     * resource id, read before `tunnel` above is computed for this run) -- a
+     * tunnel Cloudflare shows as recreated under the same name
+     * (`findTunnelByName` returning a new id for `<slug>-tunnel`) leaves every
+     * CNAME still pointed at the *old* id. That is this org's own stale
+     * record, not a foreign one, so it is repointed rather than refused.
+     *
+     * Round 4 finding 2: `previousHostnames` is this domain's own previously
+     * recorded hostname list (empty when the domain just changed --
+     * {@link cloudflareTunnel} hands the *whole* old domain to
+     * {@link deleteStaleTunnelDnsRecords} for that case instead). A name in it
+     * that the org's current config no longer produces is dropped from
+     * `hostnames` below but was never cleaned up before this round: its CNAME
+     * stayed live and its name stayed in the recorded list forever, because
+     * only a domain *change* ever ran cleanup. Each dropped name's CNAME is
+     * deleted here when it still points at this tunnel or its immediately
+     * prior id; a name already gone, or now pointed at something foreign, is
+     * simply left out of the returned list -- nothing here is this method's to
+     * reclaim or report as a conflict.
+     *
+     * Round 5 finding 1: `context` is used only to record
+     * {@link CLOUDFLARE_TUNNEL_DNS_PENDING_DOMAIN_SCOPE_KEY}/
+     * {@link CLOUDFLARE_TUNNEL_DNS_PENDING_HOSTNAMES_SCOPE_KEY} after each
+     * individual CNAME write below succeeds, so a crash or a thrown conflict
+     * partway through never leaves an already-created CNAME out of every
+     * recorded list -- `destroy` checks this pending pair too.
+     */
+    private publishTunnelDnsRecords;
     /**
      * `plan/diff.ts`'s `planZone`: finds or creates the Cloudflare zone for the
      * org's own domain. Refuses to adopt a zone the store already records