@wtfalch/foundry 0.21.1 → 0.22.1

package/dist/plan/diff.js

@@ -7,10 +7,10 @@ import { planEntryAiKeys } from './entry-ai-key.js';
 import { planEdgeReservedLabels, planEntryEdgeKeys } from './entry-edge-key.js';
 import { planFilesKeys } from './entry-files-key.js';
 import { appHostname, entryHostnames, tunnelDnsHostnames } from './hostnames.js';
-import { LOGIN_BINDING_SCOPE_KEY, loginBindingState, loginHostClientIds, loginHostnameFor, pendingRemovalHosts, } from './login-host.js';
+import { LOGIN_BINDING_SCOPE_KEY, companyLoginTunnelHost, loginBindingState, loginHostClientIds, loginHostnameFor, pendingRemovalHosts, } from './login-host.js';
 import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, } from './mail-copy.js';
-import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, appEnvAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, serviceDbEnvAppliedScopeKey, versionNotAppliedLine, } from './platform-diff.js';
-import { DEFAULT_ORG_PLATFORM_READINESS } from './platform-org.js';
+import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, ORG_MAIL_APPLIED_MODE_SCOPE_KEY, ORG_MAIL_APPLIED_USES_DOMAIN_SCOPE_KEY, appEnvAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, serviceDbEnvAppliedScopeKey, versionNotAppliedLine, } from './platform-diff.js';
+import { DEFAULT_ORG_PLATFORM_READINESS, } from './platform-org.js';
 import { PLATFORM_AUTH_BROKER_MAIL_KEY_REF } from './platform-providers.js';
 import { appLabelsAppliedScopeKey, entryLabelHash, entryLabelSpec } from './proxy-labels.js';
 import { withStepSystem } from './step-system.js';
@@ -102,10 +102,23 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     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.
+    // is pushed just below, before mail.
     const zone = planZone(org, byKey, claimed);
     const zoneWaiting = zone.blocked !== null;
     const zoneBlocked = [];
+    // #555: steps that write DNS records, which go through edge.
+    const dnsBlocked = [];
+    // #553: a ZITADEL app provision whose app id is recorded needs the typed confirmation.
+    const guardApp = (step) => guardAppProvision(step, org, recordedIds);
+    // #567: before the first step that reads the zone (mail, the tunnel, the
+    // rate limit), so a domain with no zone yet gets it provisioned first.
+    const zoneReason = zone.step ? edgeNeeded(platformReadiness, ['zones']) : null;
+    if (zone.step && zoneReason) {
+        dnsBlocked.push(edgeBlockedItem(org, 'Cloudflare zone', 'cloudflare:zone', zoneReason));
+    }
+    else if (zone.step) {
+        plannedSteps.push(zone.step);
+    }
     const mail = planMail(org, byKey, claimed, recordedIds, platformReadiness.mailHost, platformReadiness.platformApex, platformReadiness.platformLettermintProjectId);
     // #238: own-domain mail publishes DNS records into the zone, so it waits for
     // an active zone -- blocked, not planned (rule 2).
@@ -115,6 +128,10 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
             key: 'coolify:mail:zone',
         });
     }
+    else if (mail.step && edgeNeeded(platformReadiness, ['zones', 'dns'])) {
+        // #555: its zone lookup and DNS records go through edge.
+        dnsBlocked.push(edgeBlockedItem(org, 'mail', 'coolify:mail', edgeNeeded(platformReadiness, ['zones', 'dns'])));
+    }
     else if (mail.step) {
         plannedSteps.push(mail.step);
     }
@@ -166,8 +183,9 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // step's recorded client id, the same way `coolifyApp` runs after the
     // hosted app's own `zitadel:app` steps.
     const cmsClient = planCmsClient(org, byKey, claimed);
-    if (cmsClient)
-        plannedSteps.push(cmsClient);
+    const cmsGuarded = guardApp(cmsClient);
+    if (cmsGuarded)
+        plannedSteps.push(cmsGuarded);
     const site = planSite(org, byKey, claimed);
     if (site)
         plannedSteps.push(site);
@@ -182,11 +200,29 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const customers = planCustomers(org, live, claimed, recordedIds);
     if (customers)
         plannedSteps.push(customers);
-    plannedSteps.push(...planIssuerApps(org, byKey, claimed));
-    plannedSteps.push(...planEntryClients(org, byKey, claimed));
+    for (const step of [
+        ...planIssuerApps(org, byKey, claimed),
+        ...planEntryClients(org, byKey, claimed),
+    ]) {
+        const guarded = guardApp(step);
+        if (guarded)
+            plannedSteps.push(guarded);
+    }
     // The Access gate before the database, app, tunnel and zone (#84): on a
     // first apply the hostname is gated before anything answers on it.
-    plannedSteps.push(...planAccess(org, recordedIds));
+    // An Access gate that cannot be planned must not leave the hostname it
+    // guards routed: the tunnel (and its DNS) that exposes it waits too.
+    let accessGateBlocked = false;
+    for (const step of planAccess(org, recordedIds)) {
+        const reason = edgeNeeded(platformReadiness, ['access']);
+        if (reason) {
+            accessGateBlocked = true;
+            dnsBlocked.push(edgeBlockedItem(org, `Access gate for ${step.action.key}`, 'cloudflare:access', reason));
+        }
+        else {
+            plannedSteps.push(step);
+        }
+    }
     // Database before app (hosting-wiring campaign): `plan-apply.ts`'s
     // `runSteps` executes `plannedSteps` in this array order, and the app's own
     // step (`executor.ts`'s `coolifyApp`) pushes the database's connection
@@ -214,10 +250,24 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const edgeReservedLabels = planEdgeReservedLabels(org, recordedIds, platformReadiness, options.platformHostnames ?? []);
     if (edgeReservedLabels.step)
         plannedSteps.push(edgeReservedLabels.step);
-    const tunnel = planTunnel(org, byKey, claimed, recordedIds);
+    const tunnel = planTunnel(org, byKey, claimed, recordedIds, isPlatformOrg, platformReadiness.platformApex);
     // #238: a tunnel that is being provisioned waits for an active zone; parking
     // one never does.
-    if (tunnel && zoneWaiting && tunnel.action.desired.enabled !== false) {
+    // #555: provisioning writes the tunnel config, the zone lookup and DNS; a
+    // park only writes the tunnel config (`cloudflareTunnel`'s `enabled === false`
+    // branch), so it needs the tunnels port alone.
+    const tunnelEdgeReason = tunnel
+        ? edgeNeeded(platformReadiness, tunnel.action.desired.enabled === false ? ['tunnels'] : ['tunnels', 'zones', 'dns'])
+        : null;
+    // Parking closes a hostname, so only a provision waits for a blocked gate.
+    const tunnelReason = tunnelEdgeReason ??
+        (tunnel && accessGateBlocked && tunnel.action.desired.enabled !== false
+            ? 'its Access gate is blocked, and the tunnel and DNS would expose the hostname without it'
+            : null);
+    if (tunnel && tunnelReason) {
+        dnsBlocked.push(edgeBlockedItem(org, 'Cloudflare tunnel', 'cloudflare:tunnel', tunnelReason));
+    }
+    else 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',
@@ -226,13 +276,15 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     else if (tunnel) {
         plannedSteps.push(tunnel);
     }
-    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 && zoneWaiting) {
+    const rateLimitReason = rateLimit ? edgeNeeded(platformReadiness, ['zones', 'ratelimits']) : null;
+    if (rateLimit && rateLimitReason) {
+        dnsBlocked.push(edgeBlockedItem(org, 'sign-in rate limit', 'cloudflare:ratelimit', rateLimitReason));
+    }
+    else 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',
@@ -246,8 +298,9 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // Its fixed ZITADEL client before the Coolify app it signs into:
     // `coolifyAgora` reads this step's recorded client id.
     const agoraClient = planAgoraClient(org, byKey, claimed);
-    if (agoraClient)
-        plannedSteps.push(agoraClient);
+    const agoraGuarded = guardApp(agoraClient);
+    if (agoraGuarded)
+        plannedSteps.push(agoraGuarded);
     const agora = planAgora(org, byKey, claimed, recordedIds, agoraHost);
     if (agora.step)
         plannedSteps.push(agora.step);
@@ -255,8 +308,9 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // shape as Agora and planned right after it. Its fixed ZITADEL client first,
     // for the same reason: `coolifyBoule` reads that step's recorded client id.
     const bouleClient = planBouleClient(org, byKey, claimed);
-    if (bouleClient)
-        plannedSteps.push(bouleClient);
+    const bouleGuarded = guardApp(bouleClient);
+    if (bouleGuarded)
+        plannedSteps.push(bouleGuarded);
     const boule = planBoule(org, byKey, claimed, recordedIds, authIssuer, options.otherSlugs ?? [], options.archonUrl ?? null);
     if (boule.step)
         plannedSteps.push(boule.step);
@@ -285,7 +339,12 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // retire, which needs no new zone) still waits for it.
     const edgeWorkers = planWorkers(org, recordedIds, options.edgeWorkers ?? false, options.platformHostnames ?? []);
     for (const step of edgeWorkers.steps) {
-        if (zoneWaiting && step.action.desired.mode === 'apply') {
+        // A retire never looks up the zone (`cloudflareWorker`), so only a deploy needs edge.
+        const workerReason = step.action.desired.mode === 'apply' ? edgeNeeded(platformReadiness, ['zones']) : null;
+        if (workerReason) {
+            dnsBlocked.push(edgeBlockedItem(org, `${step.action.key.slice(org.id.length + 1)} Worker`, step.action.key, workerReason));
+        }
+        else if (zoneWaiting && step.action.desired.mode === 'apply') {
             zoneBlocked.push({
                 description: `${org.slug}'s ${step.action.key.slice(org.id.length + 1)} Worker is blocked, not planned: the zone for ${org.domain} is not active yet`,
                 key: step.action.key,
@@ -361,6 +420,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     if (zone.blocked)
         unmanaged.push({ description: zone.blocked, key: 'cloudflare:zone' });
     unmanaged.push(...zoneBlocked);
+    unmanaged.push(...dnsBlocked);
     // #243: an appEnv source nothing will record is reported, not silently skipped.
     unmanaged.push(...app.blocked);
     unmanaged.push(...brokerEntries.blocked);
@@ -372,6 +432,52 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         versionChanges,
     };
 }
+/**
+ * #553: a plain ZITADEL app provision (not a `recreate`) is planned only when
+ * the live listing lacks the app by name. If an app id is recorded for it,
+ * the listing may simply have missed a live app, and nothing can read an app
+ * by id, so applying silently could replace a live sign-in client. The way
+ * out is the destroying `recreate` path: the step is planned as a
+ * replacement that asks for the typed confirmation, so a person who has
+ * checked the app is gone (deleted by hand in ZITADEL) says so, and apply
+ * then deletes the recorded id (a 404 is fine) and creates a new app.
+ * (A failed recreate clears the recorded id, so it is not caught here.)
+ */
+function guardAppProvision(step, org, recordedIds) {
+    if (!step || step.action.system !== 'zitadel' || step.action.kind !== 'app')
+        return step;
+    if (step.action.desired.recreate === true)
+        return step;
+    const recorded = recordedIds[`zitadel:app:${step.action.key}`];
+    if (!recorded)
+        return step;
+    return {
+        action: { ...step.action, desired: { ...step.action.desired, recreate: true } },
+        step: {
+            description: `replace ZITADEL app '${step.action.key}' for ${org.slug}: recorded app ${recorded} is not in ZITADEL's listing (a listing can miss a live app; if it is live, do not confirm -- apply deletes it and creates a new client id)`,
+            destroys: true,
+            migrates: false,
+        },
+    };
+}
+/**
+ * #555: why a step that needs these edge-routed ports cannot run, or `null`.
+ * `readiness.dnsBlocked` is set while edge is not applied; a port the host
+ * supplies itself (`readiness.ownEdgePorts`, mirroring the executor's
+ * `ports.dns` / `zones` / `access` / `ratelimits` / `tunnels`, which win over
+ * edge) needs no edge, so only a step that would really reach edge is blocked.
+ */
+function edgeNeeded(readiness, needs) {
+    if (!readiness.dnsBlocked)
+        return null;
+    return needs.every((port) => readiness.ownEdgePorts?.[port]) ? null : readiness.dnsBlocked;
+}
+function edgeBlockedItem(org, what, key, reason) {
+    return {
+        description: `${org.slug}'s ${what} is blocked, not planned: ${reason ?? ''} (#555)`,
+        key,
+    };
+}
 /**
  * The org's own ZITADEL org (issuer), a per-org singleton like every other
  * planner in this file, with one extra wrinkle: unlike mail/chat/site/app,
@@ -637,7 +743,7 @@ function planLoginHost(org, recordedIds, authReady, issuerPlanned, bindingsWired
     // nothing else here would replan the step to retry it.
     if (recordedIds[key] === host &&
         recordedIds[LOGIN_BINDING_SCOPE_KEY] ===
-            loginBindingState(host, loginHostClientIds(recordedIds)) &&
+            loginBindingState(host, loginHostClientIds(org, recordedIds)) &&
         pendingRemovalHosts(recordedIds).length === 0) {
         return none;
     }
@@ -776,7 +882,24 @@ platformApex, platformLettermintProjectId) {
     const roleNote = rolesOwed > 0 ? `create ${rolesOwed} role mailbox(es) for ${org.slug}` : '';
     const mailboxWork = [ownerNote, roleNote].filter(Boolean).join(' and ');
     const mailboxNote = mailboxWork ? ` and ${mailboxWork}` : '';
-    if (!live) {
+    // #554: no reader lists a live `coolify mail <org>` resource, so "applied"
+    // comes from the record: the domain, mode and `usesDomain` the step last
+    // wrote (`coolifyMail`). A changed declaration differs from it and plans.
+    const recordedDomain = recordedIds[MAIL_DOMAIN_SCOPE_KEY];
+    const recordedMode = recordedIds[ORG_MAIL_APPLIED_MODE_SCOPE_KEY];
+    const recordedUsesDomain = recordedIds[ORG_MAIL_APPLIED_USES_DOMAIN_SCOPE_KEY];
+    const domainMatches = Boolean(recordedDomain && org.domain && recordedDomain.toLowerCase() === org.domain.toLowerCase());
+    const appliedFromRecord = !live &&
+        Boolean(recordedDomain) &&
+        // Before `mail_applied_mode` existed, only a received or hosted apply
+        // recorded `mail_domain` (`off` returns before it); production's record is
+        // hosted. An unrecorded mode vouches for `hosted` only.
+        (recordedMode === undefined ? desired.mode === 'hosted' : recordedMode === desired.mode) &&
+        (recordedUsesDomain === undefined
+            ? desired.usesDomain && domainMatches
+            : recordedUsesDomain === String(desired.usesDomain) &&
+                (!desired.usesDomain || domainMatches));
+    if (!live && !appliedFromRecord) {
         return {
             step: {
                 action: { system: 'coolify', kind: 'mail', key: org.id, desired },
@@ -790,8 +913,8 @@ platformApex, platformLettermintProjectId) {
             mailboxBlocked,
         };
     }
-    const liveMode = live.config.mode;
-    const liveUsesDomain = Boolean(live.config.usesDomain);
+    const liveMode = live ? live.config.mode : desired.mode;
+    const liveUsesDomain = live ? Boolean(live.config.usesDomain) : desired.usesDomain;
     if (liveMode === desired.mode && liveUsesDomain === desired.usesDomain) {
         // #177: the platform's apex or mail host moved since this step last wrote
         // them (or it never recorded them). Re-applying is idempotent.
@@ -1476,7 +1599,12 @@ function planCmsClient(org, byKey, claimed) {
     if (live.config.appType === 'web')
         return null;
     return {
-        action: { system: 'zitadel', kind: 'app', key: 'cms', desired },
+        action: {
+            system: 'zitadel',
+            kind: 'app',
+            key: 'cms',
+            desired: { ...desired, recreate: true },
+        },
         step: {
             description: `recreate ZITADEL app 'cms' for ${org.slug} as web (was ${String(live.config.appType)})`,
             destroys: true,
@@ -1580,7 +1708,12 @@ function planAgoraClient(org, byKey, claimed) {
     if (live.config.appType === 'web')
         return null;
     return {
-        action: { system: 'zitadel', kind: 'app', key: 'agora', desired },
+        action: {
+            system: 'zitadel',
+            kind: 'app',
+            key: 'agora',
+            desired: { ...desired, recreate: true },
+        },
         step: {
             description: `recreate ZITADEL app 'agora' for ${org.slug} as web (was ${String(live.config.appType)})`,
             destroys: true,
@@ -1718,7 +1851,12 @@ function planBouleClient(org, byKey, claimed) {
     if (live.config.appType === 'web')
         return null;
     return {
-        action: { system: 'zitadel', kind: 'app', key: 'boule', desired },
+        action: {
+            system: 'zitadel',
+            kind: 'app',
+            key: 'boule',
+            desired: { ...desired, recreate: true },
+        },
         step: {
             description: `recreate ZITADEL app 'boule' for ${org.slug} as web (was ${String(live.config.appType)})`,
             destroys: true,
@@ -2168,6 +2306,19 @@ function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer, re
                 platformLettermintProjectId: readiness.platformLettermintProjectId,
             };
         }
+        // #555: the `app` entry's step publishes the mail domain's DNS records
+        // (`ensureAppLettermintMail`) once one is recorded, and those go through
+        // edge: blocked, not planned, while edge is not applied.
+        const appReason = edgeNeeded(readiness, ['zones', 'dns']);
+        if (appReason &&
+            key === APP_ENTRY_KEY &&
+            app.step &&
+            app.step.action.desired.enabled !== false &&
+            recordedIds[MAIL_DOMAIN_SCOPE_KEY]) {
+            blocked.push(edgeBlockedItem(org, 'app', 'coolify:app', appReason));
+            blocked.push(...app.blocked);
+            continue;
+        }
         if (app.step)
             steps.push(app.step);
         blocked.push(...app.blocked);
@@ -2283,7 +2434,7 @@ function sortedNames(names) {
  * 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, recordedIds) {
+function planTunnel(org, byKey, claimed, recordedIds, isPlatformOrg, platformApex) {
     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)) ||
@@ -2300,6 +2451,16 @@ function planTunnel(org, byKey, claimed, recordedIds) {
             return live.config.enabled !== false;
         return desired ? status !== 'down' : status === 'healthy' || status === 'degraded';
     });
+    // #568: the company's own login host is routed by the step, so a first
+    // provision carries it too; a park does not. Without a known platform apex
+    // the platform's own org cannot be told apart, so none is planned.
+    const loginHost = platformApex ? companyLoginTunnelHost(org, isPlatformOrg) : null;
+    if (toggled && toggled.action.desired.enabled !== false && loginHost) {
+        return {
+            ...toggled,
+            action: { ...toggled.action, desired: { ...toggled.action.desired, loginHost } },
+        };
+    }
     if (toggled || !desired)
         return toggled;
     // A live, enabled tunnel re-plans the same step again when either:
@@ -2323,12 +2484,18 @@ function planTunnel(org, byKey, claimed, recordedIds) {
     const published = recordedIds[CLOUDFLARE_TUNNEL_DNS_HOSTNAMES_SCOPE_KEY];
     const edgeChanged = published !== undefined &&
         org.domain !== null &&
-        sortedNames(published.split(',')) !== sortedNames(tunnelDnsHostnames(org, org.domain));
+        sortedNames(published.split(',')) !==
+            sortedNames(tunnelDnsHostnames(org, org.domain, loginHost));
     const dnsStale = recordedIds[CLOUDFLARE_TUNNEL_DNS_DOMAIN_SCOPE_KEY] !== org.domain || edgeChanged;
     if (!connectorMissing && !dnsStale)
         return null;
     return {
-        action: { system: 'cloudflare', kind: 'tunnel', key: org.id, desired: { enabled: true } },
+        action: {
+            system: 'cloudflare',
+            kind: 'tunnel',
+            key: org.id,
+            desired: loginHost ? { enabled: true, loginHost } : { enabled: true },
+        },
         step: {
             description: connectorMissing
                 ? `run a cloudflared connector for ${org.slug}'s Cloudflare tunnel`
@@ -2458,7 +2625,12 @@ function planIssuerApps(org, byKey, claimed) {
         if (live.config.appType === app.kind)
             continue;
         steps.push({
-            action: { system: 'zitadel', kind: 'app', key: app.name, desired },
+            action: {
+                system: 'zitadel',
+                kind: 'app',
+                key: app.name,
+                desired: { ...desired, recreate: true },
+            },
             step: {
                 description: `recreate ZITADEL app '${app.name}' for ${org.slug} as ${app.kind} (was ${String(live.config.appType)})`,
                 destroys: true,

package/dist/plan/executor.d.ts

@@ -12,27 +12,7 @@ import { type EdgePlatformZones, type ZonePort } from './edge-zones.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';
-/**
- * The real {@link StepExecutor} (#20 "provision Company Factory end to
- * end"): makes each {@link StepAction} `diff.ts` plans true against a real
- * Coolify, Cloudflare and ZITADEL, plus per-org organisations, spend limits
- * and (for AI) offers on Files and AI (#80). Scope and design are exactly
- * what `.claude/decisions-2026-09-24-executor.md`'s "Executor decisions"
- * section settled, referenced by name at each dispatch branch below.
- *
- * Built entirely from narrow ports (interfaces), never a concrete
- * `@wtfalch/providers` client: this package holds no credential and never
- * will (executor decisions: "the executor is constructed with narrow ports
- * ... a host [archon] supplies real clients. How the host gets provider
- * tokens from the keys Worker is the host's job, not this campaign's").
- * Every port method here is named and shaped to match a real method on
- * `@wtfalch/providers`' `CoolifyClient`/`CloudflareClient`/`ZitadelClient`
- * (checked against `providers` `origin/main`, 2026-09-24), or on
- * `@wtfalch/files`'/`@wtfalch/ai`'s own SDK clients (#80, checked against
- * each repo's own `main`, 2026-09-25), so a real client satisfies the port
- * structurally, with no adapter needed — see each port's own doc comment for
- * the one real method it does not yet have.
- */
+import type { EdgePortName } from './platform-org.js';
 /**
  * The Coolify calls this executor makes, shaped to match
  * `@wtfalch/providers/coolify`'s `CoolifyClient` method-for-method — a real
@@ -53,10 +33,19 @@ export interface CoolifyPort {
     findProjectByName(name: string): Promise<{
         uuid: string;
         name: string;
+        description?: string | null;
     } | null>;
     createProject(name: string, description?: string): Promise<{
         uuid: string;
     }>;
+    /**
+     * #569: what a project holds (`CoolifyClient.listResources`: its
+     * environments, applications and databases). Optional: without it an
+     * unmarked project cannot be shown empty, so it is refused.
+     */
+    listResources?(projectUuid: string): Promise<Array<{
+        kind: string;
+    }>>;
     findOrCreateEnvironment(projectUuid: string, name: string): Promise<{
         environment: {
             id: number;
@@ -421,6 +410,16 @@ export interface CoolifyPort {
         deploymentUuid: string;
         status: string;
     }>;
+    /**
+     * One deployment's status by its uuid (`queued`, `in_progress`, `finished`,
+     * `failed`, `cancelled-by-user`); throws a 404 for a uuid Coolify does not
+     * know. Matches `CoolifyClient.getDeployment` method-for-method. The
+     * platform's Archon step reads it to confirm a deploy it triggered and did
+     * not wait for.
+     */
+    getDeployment(deploymentUuid: string): Promise<{
+        status: string;
+    }>;
 }
 /**
  * The Cloudflare zone calls the platform steps make directly, shaped to match
@@ -799,6 +798,8 @@ export interface ZitadelPort {
             appType: 'web' | 'native' | 'api';
             state: string;
             loginBaseUri?: string | null;
+            /** Present only when the host's listing reads it; `zitadelApp` adopts with it, else with the recorded one. */
+            clientId?: string;
         }>;
         complete: boolean;
     }>;
@@ -987,10 +988,10 @@ export interface ZitadelPort {
  * 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`
+ * itself to build the wrapper by hand. `complete: true` on every call:
+ * since providers 0.7.4 the real client pages `_search` to the end. A host
+ * that supplies its own `listApps` keeps whatever `complete` it reports.
+ * Each app's `clientId` (providers 0.7.5) passes through. `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
@@ -1011,6 +1012,8 @@ export interface ZitadelListAppsRawApp {
     name: string;
     appType: 'web' | 'native' | 'api';
     state: string;
+    /** providers 0.7.5: the app's client id. Passed through to `ZitadelPort.listApps`. */
+    clientId?: string;
 }
 /**
  * Provisions one org's organisation on Files (#80), matching
@@ -1555,6 +1558,8 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     private edgeZones;
     private edgeWriteSlot;
     constructor(ports: FoundryStepExecutorPorts);
+    /** #555: the edge-routed ports this executor was built with itself (they win over edge). */
+    ownEdgePorts(): Partial<Record<EdgePortName, boolean>>;
     execute(action: StepAction, context: StepExecutionContext): Promise<{
         resourceId?: string;
     } | undefined>;
@@ -1784,9 +1789,9 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * container itself still writing nowhere). `wasAlreadyRunning` tells this
      * method whether `appId` names an app `coolifyApp` found already there
      * (restart it once the volume is created) or one it just created fresh
-     * (already about to get its first deploy/start from
-     * `createGithubAppApplication`'s own instant-deploy path, so a restart
-     * here would only be a redundant extra one).
+     * (`coolifyApp` deploys it after this call, #566, and that first start
+     * carries the storage, so a restart here would only be a redundant extra
+     * one).
      */
     private ensureLogVolume;
     private coolifyDatabase;