@wtfalch/foundry 0.6.0 → 0.7.1

package/dist/plan/diff.js

@@ -1,6 +1,7 @@
-import { NO_AGORA_HOST_VALUES, agoraEnvDrift, agoraHostMissing, desiredAgoraEnv, } from './agora.js';
+import { NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraHostMissing, desiredAgoraEnv, } from './agora.js';
+import { LOGIN_BINDING_SCOPE_KEY, loginBindingState, loginHostClientIds, loginHostnameFor, } from './login-host.js';
 import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, } from './mail-copy.js';
-import { ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, } from './platform-diff.js';
+import { APP_ENV_APPLIED_SCOPE_KEY, DB_ENV_APPLIED_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, resolveAppEnv, } from './platform-diff.js';
 import { DEFAULT_ORG_PLATFORM_READINESS } from './platform-org.js';
 /** The `Plan` (#19's public contract) a `PlanDetail` carries. */
 export function toPlan(detail) {
@@ -53,7 +54,11 @@ function resourceKey(system, kind, key) {
  * app with the platform's jobs scheduler, idempotent on the *recorded*
  * resource id like {@link planOwner} rather than a live resource, since
  * nothing in `live` can report a scheduler registration (no reader exists for
- * it). Everything
+ * it). #267 adds one more, right after {@link planOwner} and before every
+ * app-creating step below: {@link planLoginHost}, the org's own company
+ * login host -- also idempotent on the *recorded* resource id, since
+ * `live` has no notion of a ZITADEL trusted domain or a login binding
+ * either. Everything
  * else in `live` that none of these eighteen singletons and however many
  * declared issuer apps claim is unmanaged. The full field-by-field provisioning surface (SSO,
  * guests, calls on the org's own domain, adopted/bespoke apps, the actual
@@ -61,7 +66,7 @@ function resourceKey(system, kind, key) {
  * Company Factory end to end", which wires real readers and executors
  * against this seam.
  */
-export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AGORA_HOST_VALUES, jobsAvailable = false, platformReadiness = DEFAULT_ORG_PLATFORM_READINESS) {
+export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AGORA_HOST_VALUES, jobsAvailable = false, platformReadiness = DEFAULT_ORG_PLATFORM_READINESS, options = {}) {
     const byKey = new Map(live.map((r) => [resourceKey(r.system, r.kind, r.key), r]));
     const claimed = new Set();
     const plannedSteps = [];
@@ -71,9 +76,29 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const owner = planOwner(org, recordedIds, platformReadiness.authReady);
     if (owner)
         plannedSteps.push(owner);
+    // #267: after the ZITADEL org step, before any app's own issuer
+    // application. Apps created later in this run are not in the binding yet;
+    // the next run replans this step and repoints them.
+    const loginHost = planLoginHost(org, recordedIds, platformReadiness.authReady, issuer.step !== null, options.loginHostBindings ?? false);
+    if (loginHost.step)
+        plannedSteps.push(loginHost.step);
+    // Planned ahead of everything that needs the zone live (#238); its own step
+    // is still pushed in its usual place below.
+    const zone = planZone(org, byKey, claimed);
+    const zoneWaiting = zone.blocked !== null;
+    const zoneBlocked = [];
     const mail = planMail(org, byKey, claimed, recordedIds, platformReadiness.mailHost);
-    if (mail.step)
+    // #238: own-domain mail publishes DNS records into the zone, so it waits for
+    // an active zone -- blocked, not planned (rule 2).
+    if (mail.step && zoneWaiting && org.mail.usesDomain && org.domain) {
+        zoneBlocked.push({
+            description: `${org.slug}'s mail is blocked, not planned: the zone for ${org.domain} is not active yet`,
+            key: 'coolify:mail:zone',
+        });
+    }
+    else if (mail.step) {
         plannedSteps.push(mail.step);
+    }
     const mailCopy = planMailCopy(org, byKey, recordedIds);
     if (mailCopy)
         plannedSteps.push(mailCopy);
@@ -135,21 +160,36 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const database = planDatabase(org, byKey, claimed);
     if (database)
         plannedSteps.push(database);
-    const app = planApp(org, byKey, claimed);
-    if (app)
-        plannedSteps.push(app);
-    const tunnel = planTunnel(org, byKey, claimed);
-    if (tunnel)
+    const app = planApp(org, byKey, claimed, recordedIds, plannedSteps);
+    if (app.step)
+        plannedSteps.push(app.step);
+    const tunnel = planTunnel(org, byKey, claimed, recordedIds);
+    // #238: a tunnel that is being provisioned waits for an active zone; parking
+    // one never does.
+    if (tunnel && zoneWaiting && tunnel.action.desired.enabled !== false) {
+        zoneBlocked.push({
+            description: `${org.slug}'s Cloudflare tunnel is blocked, not planned: the zone for ${org.domain} is not active yet`,
+            key: 'cloudflare:tunnel',
+        });
+    }
+    else if (tunnel) {
         plannedSteps.push(tunnel);
-    const zone = planZone(org, byKey, claimed);
-    if (zone)
-        plannedSteps.push(zone);
+    }
+    if (zone.step)
+        plannedSteps.push(zone.step);
     // Right after the zone (#43): `cloudflareRateLimit` resolves the zone by
     // apex domain, so the zone step above must already have run (or the zone
     // must already exist live) by the time this one's action executes.
     const rateLimit = planRateLimit(org, recordedIds);
-    if (rateLimit)
+    if (rateLimit && zoneWaiting) {
+        zoneBlocked.push({
+            description: `${org.slug}'s sign-in rate limit is blocked, not planned: the zone for ${org.domain} is not active yet`,
+            key: 'cloudflare:ratelimit',
+        });
+    }
+    else if (rateLimit) {
         plannedSteps.push(rateLimit);
+    }
     // After the apps: the customers org is granted the project the first app
     // step creates.
     const customers = planCustomers(org, live, claimed, recordedIds);
@@ -199,6 +239,10 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // budget, key) would otherwise also have nothing to act on.
     if (issuer.blocked)
         unmanaged.push({ description: issuer.blocked, key: 'zitadel:issuer' });
+    // #267 (rule 2): a login host with no ZITADEL org to trust it in is blocked, not planned to throw.
+    if (loginHost.blocked) {
+        unmanaged.push({ description: loginHost.blocked, key: 'zitadel:login-host' });
+    }
     if (mail.blocked)
         unmanaged.push({ description: mail.blocked, key: 'coolify:mail' });
     // #162: reported separately from `mail.blocked` -- missing an owner
@@ -218,6 +262,13 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         unmanaged.push({ description: storage.blocked, key: 'files:storage' });
     if (aiBudget.blocked)
         unmanaged.push({ description: aiBudget.blocked, key: 'ai:budget' });
+    // #238: a pending zone, reported here with its nameservers rather than
+    // silently treated as converged.
+    if (zone.blocked)
+        unmanaged.push({ description: zone.blocked, key: 'cloudflare:zone' });
+    unmanaged.push(...zoneBlocked);
+    // #243: an appEnv source nothing will record is reported, not silently skipped.
+    unmanaged.push(...app.blocked);
     return { orgId: org.id, plannedSteps, unmanaged };
 }
 /**
@@ -355,6 +406,83 @@ function planOwner(org, recordedIds, authReady) {
         },
     };
 }
+/**
+ * #267: the org's own company login host (`login-host.ts`'s
+ * `loginHostnameFor`) -- `auth.<domain>` once the org has one,
+ * `<slug>-auth.oikos.host` for tier 1. Idempotent on the *recorded*
+ * resource id, the same shape `planOwner` above uses and for the same
+ * reason: `ZitadelReader.listResources` has no notion of a trusted domain
+ * or a login binding, so there is nothing in `live` this step could ever
+ * claim or compare against.
+ *
+ * Unlike `planOwner`, a re-run is not simply "already done or not": the
+ * recorded value is compared against {@link loginHostnameFor}'s own value
+ * for *this* apply, so an org moving from tier 1 onto its own domain (or
+ * losing one) replans this step rather than staying silent forever once
+ * first applied -- `executor.ts`'s `zitadelLoginHost` then also moves every
+ * already-live app onto the new base URI. Mints nothing either way: adding
+ * a trusted domain is not a one-time secret, so there is no "undelivered"
+ * guard to check the way `planJobsRegistration`'s own does.
+ *
+ * Ordered right after `planOwner` (not after mail, chat, or any hosting
+ * step), for the same reason `planOwner`'s own doc comment gives: on a
+ * first-ever apply the ZITADEL org this step's executor needs
+ * (`context.recordedIds().zitadel_org`) has already been recorded by the
+ * issuer step two steps before it in the same run, and this step itself
+ * runs well before `planIssuerApps`/`planCmsClient`/`planAgoraClient`
+ * create any app under the org's project -- #267's own "before any app's
+ * issuer application".
+ */
+function planLoginHost(org, recordedIds, authReady, issuerPlanned, bindingsWired) {
+    const none = { step: null, blocked: null };
+    const key = resourceKey('zitadel', 'login-host', org.id);
+    const host = loginHostnameFor(org);
+    // Already applied -- a re-run plans nothing unless the host changed or an app
+    // client id appeared since the binding was last written (#267, rule 4).
+    if (recordedIds[key] === host &&
+        recordedIds[LOGIN_BINDING_SCOPE_KEY] ===
+            loginBindingState(host, loginHostClientIds(recordedIds))) {
+        return none;
+    }
+    // #177: nothing to add a trusted domain to yet -- `planIssuer` already
+    // reports the platform's sign-in as blocked, so this step stays silent
+    // rather than repeating it, the same rule `planOwner` follows.
+    if (!authReady)
+        return none;
+    // Isolation between orgs rests on zitadel-login's binding, and repointing
+    // an app at a host with no binding breaks its sign-in: trust nothing and
+    // repoint nothing until the port that writes the binding is wired.
+    if (!bindingsWired) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s login host ${host} waits for the loginHostBindings port, which the host has not wired`,
+        };
+    }
+    // No ZITADEL org to trust the host in: wait for it, unless the issuer step
+    // in this very plan creates it first (it runs before this one).
+    if (!recordedIds[ZITADEL_ORG_SCOPE_KEY] && !issuerPlanned) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s login host ${host} waits for its ZITADEL org, which is not recorded yet`,
+        };
+    }
+    return {
+        step: {
+            action: {
+                system: 'zitadel',
+                kind: 'login-host',
+                key: org.id,
+                desired: { host },
+            },
+            step: {
+                description: `set ${org.slug}'s login host to ${host}`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}
 /**
  * #162: the flat scope id `executor.ts`'s `ensureOwnerMailbox` records once
  * it has given the org's owner a mailbox (`MAIL_OWNER_MAILBOX_SCOPE_KEY`
@@ -364,6 +492,8 @@ function planOwner(org, recordedIds, authReady) {
 const MAIL_OWNER_MAILBOX_SCOPE_KEY = 'mail_owner_mailbox';
 /** #230: restated from `executor.ts`'s `MAIL_ROLE_MAILBOXES_SCOPE_KEY`, same rule: comma-joined local parts already created. */
 const MAIL_ROLE_MAILBOXES_SCOPE_KEY = 'mail_role_mailboxes';
+/** Restated from `executor.ts`, the same rule: the app id of the org tunnel's cloudflared connector. */
+const CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY = 'cloudflare_tunnel_connector_app';
 /** Restated from `executor.ts`, the same rule: the mail domain the last apply resolved. */
 const MAIL_DOMAIN_SCOPE_KEY = 'mail_domain';
 /** Restated from `executor.ts`, the same rule: the id of an ai key minted but not delivered. */
@@ -546,6 +676,10 @@ function planMailCopy(org, byKey, recordedIds) {
     };
 }
 function planChat(org, byKey, claimed) {
+    // Chat off (not in v1): plan nothing, and leave any live chat unclaimed so
+    // it is reported in `unmanaged` and never adopted or destroyed.
+    if (!org.chat.enabled)
+        return null;
     const key = resourceKey('coolify', 'chat', org.id);
     const live = byKey.get(key);
     if (live)
@@ -1203,23 +1337,103 @@ function planHostingToggle(system, kind, desiredEnabled, org, byKey, claimed, de
  * resource's `enabled` field -- a live resource nothing has actually
  * checked yet is assumed fine rather than replanned every time.
  */
-function planApp(org, byKey, claimed) {
+function planApp(org, byKey, claimed, recordedIds, plannedSteps) {
+    // #243: an `appEnv` source with no recorded value and no step planned to
+    // record one this run has nothing to push, now or after this apply.
+    const sourceStep = {
+        filesOrganisationId: ['files', 'organisation'],
+        aiOrganisationId: ['ai', 'organisation'],
+        mailDomain: ['coolify', 'mail'],
+    };
+    const { values: wantedEnv, unresolved } = resolveAppEnv(org, recordedIds);
+    const blocked = org.hosting.enabled
+        ? unresolved
+            .filter(([, source]) => !plannedSteps.some((p) => p.action.system === sourceStep[source][0] &&
+            p.action.kind === sourceStep[source][1]))
+            .map(([name, source]) => ({
+            description: `${org.slug}'s app env ${name} is blocked, not planned: its source ${source} has no recorded value yet`,
+            key: `coolify:app:env:${name}`,
+        }))
+        : [];
     const toggled = planHostingToggle('coolify', 'app', org.hosting.enabled, org, byKey, claimed, () => `provision ${org.slug}'s app`, () => `park ${org.slug}'s app (stops serving; app data is retained, not deleted -- #7 corrections 1)`);
     if (toggled)
-        return toggled;
+        return { step: toggled, blocked };
     if (!org.hosting.enabled)
-        return null;
+        return { step: null, blocked };
     const live = byKey.get(resourceKey('coolify', 'app', org.id));
-    if (!live || live.config.hasLogVolume !== false)
-        return null;
-    return {
-        action: { system: 'coolify', kind: 'app', key: org.id, desired: { enabled: true } },
-        step: {
-            description: `add a durable log directory to ${org.slug}'s app (persistent volume at /app/logs + LOG_DIR) so a database outage does not erase the evidence (#75)`,
-            destroys: false,
-            migrates: false,
-        },
+    if (!live)
+        return { step: null, blocked };
+    const action = {
+        system: 'coolify',
+        kind: 'app',
+        key: org.id,
+        desired: { enabled: true },
     };
+    if (live.config.hasLogVolume === false) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `add a durable log directory to ${org.slug}'s app (persistent volume at /app/logs + LOG_DIR) so a database outage does not erase the evidence (#75)`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked,
+        };
+    }
+    // #239 (rule 4), from live state: an app with a database but no
+    // `DATABASE_URL_OWNER` env still has the pre-split superuser URL, or never
+    // got the push. Names only, never values. A reader that did not list env
+    // names (`envNames` absent) reads as compliant, like `hasLogVolume`.
+    const envNames = live.config.envNames;
+    const dbLive = byKey.get(resourceKey('coolify', 'database', org.id));
+    const dbReady = org.hosting.database && Boolean(recordedIds[`coolify:database:${org.id}`]);
+    if (dbReady && dbLive?.config.hasInternalUrl === false) {
+        // Rule 2: the push cannot succeed yet, so report it rather than replan
+        // forever.
+        blocked.push({
+            description: `${org.slug}'s app database URLs are blocked, not planned: the database reports no internal connection URL yet`,
+            key: 'coolify:app:database-url',
+        });
+    }
+    else if (dbReady &&
+        // Only a read that saw the URL replans: an unread database (a failed
+        // read) would plan a step that pushes nothing, forever.
+        dbLive?.config.hasInternalUrl === true &&
+        ((Array.isArray(envNames) && !envNames.includes('DATABASE_URL_OWNER')) ||
+            // A crash between the push and the restart leaves the env right and no
+            // marker: replan once more to restart and set it.
+            !recordedIds[DB_ENV_APPLIED_SCOPE_KEY])) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `give ${org.slug}'s app its owner and runtime database URLs and restart it (#239)`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked,
+        };
+    }
+    // #243 (rule 3): a changed `hosting.appEnv` reaches an app that is already
+    // live. `pushAppEnv` records what it pushed, so this plans the same step
+    // again, with a redeploy, only once the resolved map differs from that.
+    if (JSON.stringify(wantedEnv) !== (recordedIds[APP_ENV_APPLIED_SCOPE_KEY] ?? '{}')) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `push ${org.slug}'s changed app env (appEnv) and redeploy the app`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked,
+        };
+    }
+    return { step: null, blocked };
 }
 /**
  * #173: register the org's own app with the platform's jobs scheduler
@@ -1327,12 +1541,48 @@ function planDatabase(org, byKey, claimed) {
  * domain) plans no per-org tunnel for Agora: `<slug>-agora.oikos.host` rides
  * the shared `*.oikos.host` wildcard tunnel (`scripts/shared-ingress.mjs`).
  */
-function planTunnel(org, byKey, claimed) {
+function planTunnel(org, byKey, claimed, recordedIds) {
     const desired = (org.hosting.tunnel && org.hosting.usesDomain && Boolean(org.domain)) ||
         (org.site.enabled && Boolean(org.domain)) ||
         (org.calls.enabled && org.calls.usesDomain && Boolean(org.domain)) ||
         Boolean(org.domain);
-    return planHostingToggle('cloudflare', 'tunnel', desired, org, byKey, claimed, () => `provision a Cloudflare tunnel for ${org.slug}'s app`, () => `park ${org.slug}'s Cloudflare tunnel (configuration is retained, not deleted -- #7 corrections 1)`);
+    const toggled = planHostingToggle('cloudflare', 'tunnel', desired, org, byKey, claimed, () => `provision a Cloudflare tunnel for ${org.slug}'s app`, () => `park ${org.slug}'s Cloudflare tunnel (configuration is retained, not deleted -- #7 corrections 1)`);
+    if (toggled || !desired)
+        return toggled;
+    // #235: a live, enabled tunnel with no connector recorded -- a first
+    // connector create that failed, or a tunnel that predates connectors --
+    // plans the same step again. The step finds or creates the connector by
+    // name, so it never makes a second one.
+    const live = byKey.get(resourceKey('cloudflare', 'tunnel', org.id));
+    if (!live || recordedIds[CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY])
+        return null;
+    return {
+        action: { system: 'cloudflare', kind: 'tunnel', key: org.id, desired: { enabled: true } },
+        step: {
+            description: `run a cloudflared connector for ${org.slug}'s Cloudflare tunnel`,
+            destroys: false,
+            migrates: false,
+        },
+    };
+}
+/**
+ * #238: the org's own zone's live `status`/`name_servers`, read from the
+ * same `kind: 'zone'` {@link LiveResource} `planZone` already matches by key
+ * -- `@wtfalch/providers/cloudflare`'s `CloudflareClient.listResources`
+ * already returns both (`config: { id, status, name_servers }`), so nothing
+ * new has to be fetched; this just reads what was already there. `null`
+ * means no zone is live yet at all (not a readiness problem `planZone`
+ * itself reports -- it is still planning the zone's own creation).
+ */
+function zoneReadiness(domain, byKey) {
+    const zone = byKey.get(resourceKey('cloudflare', 'zone', domain));
+    if (!zone)
+        return null;
+    const config = zone.config;
+    return {
+        active: config.status === 'active',
+        nameServers: config.name_servers ?? [],
+    };
 }
 /**
  * The org's Cloudflare zone for its own domain (`org.ts`'s
@@ -1364,25 +1614,40 @@ function planZone(org, byKey, claimed) {
         (org.calls.enabled && org.calls.usesDomain) ||
         Boolean(org.domain);
     if (!usesDomain || !org.domain)
-        return null;
+        return { step: null, blocked: null };
     const key = resourceKey('cloudflare', 'zone', org.domain);
     const live = byKey.get(key);
-    if (live)
+    if (live) {
         claimed.add(key);
-    if (live)
-        return null;
+        const readiness = zoneReadiness(org.domain, byKey);
+        // #238: a zone stays pending until the customer changes nameservers at
+        // their registrar -- reported here, not silently treated as converged,
+        // so an apply says what it is waiting for. A later apply, once
+        // Cloudflare marks the zone active, reports nothing and the DNS- and
+        // mail-dependent steps below (`planMail`) resume.
+        if (readiness && !readiness.active) {
+            return {
+                step: null,
+                blocked: `${org.slug}'s zone for ${org.domain} is waiting for nameservers: ${readiness.nameServers.join(', ')}`,
+            };
+        }
+        return { step: null, blocked: null };
+    }
     return {
-        action: {
-            system: 'cloudflare',
-            kind: 'zone',
-            key: org.domain,
-            desired: { domain: org.domain },
-        },
         step: {
-            description: `provision a Cloudflare zone for ${org.domain}`,
-            destroys: false,
-            migrates: false,
+            action: {
+                system: 'cloudflare',
+                kind: 'zone',
+                key: org.domain,
+                desired: { domain: org.domain },
+            },
+            step: {
+                description: `provision a Cloudflare zone for ${org.domain}`,
+                destroys: false,
+                migrates: false,
+            },
         },
+        blocked: null,
     };
 }
 /**

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;
@@ -766,6 +768,24 @@ 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;
+    }>;
+    /**
+     * #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>;
 }
 /**
  * Provisions one org's organisation on Files (#80), matching
@@ -959,6 +979,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 +1089,14 @@ 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.
+     */
+    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 +1145,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 +1189,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;
     /**