@wtfalch/foundry 0.19.1 → 0.21.0

package/dist/plan/health-check-settings.d.ts

@@ -0,0 +1,47 @@
+/**
+ * #543: the one shared helper for the Coolify `updateApplication` quartet
+ * that turns an app's own container health check on -- lifted out of
+ * `platform-providers.ts`'s `provisionPlatformArchon` (#480), which sent
+ * these four fields by hand for Archon alone:
+ *
+ * ```
+ * health_check_enabled: true,
+ * health_check_path: ARCHON_HEALTH_CHECK_PATH,
+ * health_check_port: Number(ARCHON_PORT),
+ * health_check_start_period: ARCHON_HEALTH_CHECK_START_PERIOD_SECONDS,
+ * ```
+ *
+ * Archon's own doc comment explains why this exists at all: without a health
+ * check, Coolify's rolling update has nothing to wait on and stops the old
+ * container the moment the new one starts, before it can possibly be
+ * healthy -- the #475 incident's own failure mode, and the 2026-10-05 Archon
+ * 502 this issue (#543) was opened over. Every other app foundry creates
+ * that answers an HTTP health route gets the same four fields, through this
+ * one function, so a change to the shape (a fifth field, a different
+ * default) reaches every caller instead of drifting between Archon's copy
+ * and whichever app copied it next.
+ *
+ * `startPeriodSeconds` defaults to 30 -- Archon's own number
+ * (`ARCHON_HEALTH_CHECK_START_PERIOD_SECONDS`'s doc comment: "long enough
+ * for the slowest migration run plus boot seen so far, with margin; there is
+ * no live measurement to pin it to instead"). A caller whose app is known to
+ * be slower or faster to boot passes its own.
+ */
+/** The four Coolify `updateApplication` fields {@link healthCheckSettings} returns. */
+export interface HealthCheckPatch {
+    health_check_enabled: true;
+    health_check_path: string;
+    health_check_port: number;
+    health_check_start_period: number;
+}
+/** Archon's own number (see this module's doc comment) -- the default every other caller inherits unless it knows better. */
+export declare const DEFAULT_HEALTH_CHECK_START_PERIOD_SECONDS = 30;
+/**
+ * The quartet of `updateApplication` fields that turn on and configure an
+ * app's own Coolify health check, spread into whatever patch object a caller
+ * is already building (`{ ...patch, ...healthCheckSettings(path, port) }`).
+ * `port` is the port Coolify's health check probes *inside the container's
+ * own network* -- the same port the app's `ports_exposes` (or its
+ * Dockerfile's `EXPOSE`) names, not a public one.
+ */
+export declare function healthCheckSettings(path: string, port: number, startPeriodSeconds?: number): HealthCheckPatch;

package/dist/plan/health-check-settings.js

@@ -0,0 +1,47 @@
+/**
+ * #543: the one shared helper for the Coolify `updateApplication` quartet
+ * that turns an app's own container health check on -- lifted out of
+ * `platform-providers.ts`'s `provisionPlatformArchon` (#480), which sent
+ * these four fields by hand for Archon alone:
+ *
+ * ```
+ * health_check_enabled: true,
+ * health_check_path: ARCHON_HEALTH_CHECK_PATH,
+ * health_check_port: Number(ARCHON_PORT),
+ * health_check_start_period: ARCHON_HEALTH_CHECK_START_PERIOD_SECONDS,
+ * ```
+ *
+ * Archon's own doc comment explains why this exists at all: without a health
+ * check, Coolify's rolling update has nothing to wait on and stops the old
+ * container the moment the new one starts, before it can possibly be
+ * healthy -- the #475 incident's own failure mode, and the 2026-10-05 Archon
+ * 502 this issue (#543) was opened over. Every other app foundry creates
+ * that answers an HTTP health route gets the same four fields, through this
+ * one function, so a change to the shape (a fifth field, a different
+ * default) reaches every caller instead of drifting between Archon's copy
+ * and whichever app copied it next.
+ *
+ * `startPeriodSeconds` defaults to 30 -- Archon's own number
+ * (`ARCHON_HEALTH_CHECK_START_PERIOD_SECONDS`'s doc comment: "long enough
+ * for the slowest migration run plus boot seen so far, with margin; there is
+ * no live measurement to pin it to instead"). A caller whose app is known to
+ * be slower or faster to boot passes its own.
+ */
+/** Archon's own number (see this module's doc comment) -- the default every other caller inherits unless it knows better. */
+export const DEFAULT_HEALTH_CHECK_START_PERIOD_SECONDS = 30;
+/**
+ * The quartet of `updateApplication` fields that turn on and configure an
+ * app's own Coolify health check, spread into whatever patch object a caller
+ * is already building (`{ ...patch, ...healthCheckSettings(path, port) }`).
+ * `port` is the port Coolify's health check probes *inside the container's
+ * own network* -- the same port the app's `ports_exposes` (or its
+ * Dockerfile's `EXPOSE`) names, not a public one.
+ */
+export function healthCheckSettings(path, port, startPeriodSeconds = DEFAULT_HEALTH_CHECK_START_PERIOD_SECONDS) {
+    return {
+        health_check_enabled: true,
+        health_check_path: path,
+        health_check_port: port,
+        health_check_start_period: startPeriodSeconds,
+    };
+}

package/dist/plan/health-targets.d.ts

@@ -0,0 +1,86 @@
+import type { DeclaredOrg } from '../org.js';
+import type { DeclaredPlatform } from '../platform.js';
+/**
+ * #541: every service foundry runs, for an outside uptime prober -- the gap
+ * `healthUrls` (`executor.ts`) left open. That function returns one bare URL
+ * per hosting/site app and `[]` for a company that runs neither, even though
+ * foundry always runs Boule, Agora and sign-in for every org, and mail, chat,
+ * calls and the shared sign-in broker whenever that org has them
+ * (`health-urls.test.ts` line 59 is the empty list this issue replaces for
+ * probing). The platform's own services (ZITADEL, the broker, Archon, mail,
+ * ai, files, integrations, edge) had no health list at all.
+ *
+ * `healthTargets`/`platformHealthTargets` are that list, richer than a bare
+ * URL string: `url: null` plus `reason` says "not probed" rather than hiding
+ * the service, and `restartSafe` tells a future auto-restart step which
+ * failing checks it must never act on by itself.
+ *
+ * Every hostname below comes from the function that already owns it --
+ * `bouleHostnameFor`, `agoraHostnameFor`, `loginHostnameFor`, `cmsHostnameFor`,
+ * `callsHostnameFor`, `entryHostnames` -- never a second copy of the rule
+ * that builds one, the same discipline `healthUrls`'s own doc comment states
+ * ("Exported so archon ... never repeats this file's hostname rules").
+ * `cmsHostnameFor`/`callsHostnameFor` were private to `executor.ts`; this
+ * issue exports them for that reason alone, and `healthUrls` itself is
+ * untouched -- Archon still imports it.
+ *
+ * The *paths* below are not discovered here -- none of the apps they belong
+ * to (auth, chat, calls) are built in this repo -- so they are hand-verified
+ * facts (#541's own "Real paths today"), cited beside each one against
+ * whatever this repo already knows about the service that owns it.
+ * `expect` is `{ status: 200 }` everywhere: nothing in this estate's own
+ * wait-for-ready logic (`platform-providers.ts`'s `waitForInstance`/
+ * `waitForMailInstance`, both `response.ok` alone, no body read) asserts a
+ * response body today, so this catalogue does not invent one either.
+ */
+/** `'deep'` when the route queries its own database, `'shallow'` when it answers without one, `'page'` when only a page load (no API) is possible. */
+export type HealthTargetDepth = 'deep' | 'shallow' | 'page';
+export interface HealthTargetExpect {
+    status: number;
+    /** Set only for a route this estate's own code already asserts a body against; none do today (see this file's own doc comment). */
+    body?: string;
+}
+export interface HealthTarget {
+    /**
+     * A stable id, e.g. `'boule'`, `'agora'`, `'login'`, `'mail'`. Not unique
+     * *across* `healthTargets` and `platformHealthTargets` -- the two catalogue
+     * different things reached at different hostnames (a company's own
+     * `loginHostnameFor` vs. the platform's shared `platform.auth.hostname`),
+     * even when the id reads the same.
+     */
+    service: string;
+    /** `null` when nothing here can be probed from outside -- see `reason`. */
+    url: string | null;
+    expect: HealthTargetExpect;
+    depth: HealthTargetDepth;
+    /**
+     * False for anything a future "restart on red" step must never touch
+     * mid-incident on its own: a database, auth (ZITADEL, zitadel-login, the
+     * broker), mail, chat's Synapse and MAS, the calls service, jobs, Archon.
+     * Everything else here is a stateless app container, safe to bounce.
+     */
+    restartSafe: boolean;
+    /** True when Cloudflare Access gates the hostname, so a prober with no service token reads every check as a redirect, never a real answer. */
+    behindAccess: boolean;
+    /** Set only when `url` is `null`: why nothing can be probed yet. */
+    reason?: string;
+}
+/**
+ * One target per service foundry runs for this company (#541). Always Boule,
+ * Agora and login; mail, chat (the chat service, Synapse, MAS), calls and
+ * the broker whenever the org has them; then whichever of hosting or site
+ * the org runs, if either.
+ */
+export declare function healthTargets(org: DeclaredOrg): HealthTarget[];
+/**
+ * The seven platform services #541 names (`platform:auth`, `platform:archon`,
+ * `platform:mail`, `platform:ai`, `platform:files`, `platform:integrations`,
+ * `platform:edge`) -- `platform:sfu` and `platform:jobs` are shared platform
+ * resources too, but neither is in that list, and this issue does not expand
+ * it: the SFU has no hostname (`platform-sfu.ts`'s own doc comment: no cheap
+ * way to read it over SSH, let alone over HTTP) and the jobs scheduler's
+ * admin API answers 401 with no token (`platform-providers.ts`'s own
+ * `coolify:jobs` step), so an outside prober could not usefully reach either
+ * one anyway.
+ */
+export declare function platformHealthTargets(platform: DeclaredPlatform): HealthTarget[];

package/dist/plan/health-targets.js

@@ -0,0 +1,344 @@
+import { APP_ENTRY_KEY, appEntry } from '../org.js';
+import { agoraHostnameFor } from './agora.js';
+import { bouleHostnameFor } from './boule.js';
+import { callsHostnameFor, cmsHostnameFor } from './executor.js';
+import { entryHostnames } from './hostnames.js';
+import { loginHostnameFor } from './login-host.js';
+function okExpect() {
+    return { status: 200 };
+}
+const DEFAULT_API_HEALTH_PATH = '/api/health';
+const STATIC_PAGE_PATH = '/';
+/** zitadel-login's own readiness route (#541's "Real paths today"). `depth: 'shallow'`, not `'deep'`: login holds no database of its own (`login-host.ts`), whatever its name suggests. */
+const LOGIN_READY_PATH = '/ready';
+/** The broker answers on `platform.auth.hostname` under `AUTH_BROKER_PATH_PATTERN` (`platform-providers.ts`, `'^/api(/|$)'`), so its own health path carries that prefix. */
+const BROKER_HEALTH_PATH = '/api/healthy';
+/** `platform-providers.ts`'s own `waitForInstance` call target (`` `https://${hostname}/debug/healthz}` ``), also the one path `AUTH_ZITADEL_PATH_PATTERN` names by name. */
+const ZITADEL_HEALTH_PATH = '/debug/healthz';
+/**
+ * `platform-providers.ts`'s own private `STALWART_READY_PATH` ('/healthz/ready'),
+ * restated here: that constant is not exported, and exporting it (or
+ * importing the whole provider module for one string) costs more than a
+ * second copy of a value both cite back to Stalwart's own route.
+ */
+const STALWART_READY_PATH = '/healthz/ready';
+const CHAT_SERVICE_HEALTH_PATH = '/_chat/health';
+const CALLS_HEALTH_PATH = '/healthz';
+/** Boule, Agora and the company's own login host: every org gets these, with no flag to check (the "Why" this issue opens with). */
+function alwaysOnTargets(org) {
+    return [
+        {
+            service: 'boule',
+            url: `https://${bouleHostnameFor(org)}${DEFAULT_API_HEALTH_PATH}`,
+            expect: okExpect(),
+            depth: 'deep',
+            restartSafe: true,
+            behindAccess: false,
+        },
+        {
+            // Caddy serves Agora statically (`agora.ts`'s own doc comment: its
+            // Dockerfile serves Caddy on 8080) -- no `/api/health` to ask, so only
+            // a page load proves it is up ("static Agora /" in #541's own list).
+            service: 'agora',
+            url: `https://${agoraHostnameFor(org)}${STATIC_PAGE_PATH}`,
+            expect: okExpect(),
+            depth: 'page',
+            restartSafe: true,
+            behindAccess: false,
+        },
+        {
+            service: 'login',
+            url: `https://${loginHostnameFor(org)}${LOGIN_READY_PATH}`,
+            expect: okExpect(),
+            depth: 'shallow',
+            restartSafe: false,
+            behindAccess: false,
+        },
+    ];
+}
+/**
+ * The shared sign-in broker (`broker-entries.ts`), when this company depends
+ * on it: any hosting entry declaring `uses.auth` signs in through it. The
+ * broker is the platform's one app, not a per-company address `org` alone
+ * can build -- its real, reachable URL is `platformHealthTargets`'s own
+ * `'auth-broker'` target, under `platform.auth.hostname`. This target still
+ * belongs in a company's own list (#541: "Include ... the broker when the
+ * company has them") so a status page scoped to one company shows every
+ * service that company's sign-in actually depends on, even a shared one.
+ */
+function brokerTarget(org) {
+    const usesBroker = org.hosting.entries.some((entry) => Boolean(entry.uses?.auth));
+    if (!usesBroker)
+        return null;
+    return {
+        service: 'broker',
+        url: null,
+        expect: okExpect(),
+        depth: 'shallow',
+        restartSafe: false,
+        behindAccess: false,
+        reason: "the sign-in broker is the platform's one shared app (broker-entries.ts), not a per-company address this function can build from `org` alone -- see platformHealthTargets's 'auth-broker' target",
+    };
+}
+/**
+ * Mail, when this company's mail is not off. Every org's mail is served by
+ * the one shared Stalwart instance (`executor.ts`'s `mailOrgFor`), never a
+ * per-org app, so there is no per-company hostname to build here either --
+ * `platformHealthTargets`'s own `'mail'` target is the real, reachable one.
+ */
+function mailTarget(org) {
+    if (org.mail.mode === 'off')
+        return null;
+    return {
+        service: 'mail',
+        url: null,
+        expect: okExpect(),
+        depth: 'deep',
+        restartSafe: false,
+        behindAccess: false,
+        reason: "mail is the platform's one shared Stalwart instance, not a per-company address this function can build from `org` alone -- see platformHealthTargets's 'mail' target",
+    };
+}
+/**
+ * Chat, when enabled (on by default for a new org -- `org.ts`'s own
+ * `ChatConfig` doc comment). The chat service is the only one of the three
+ * with a public route of its own, proxied through Agora
+ * (`chat-matrix.ts`'s own "NO PUBLIC HOSTNAME OF ITS OWN": Synapse and MAS
+ * answer only on Coolify's internal network, never a tunnel or DNS record).
+ */
+function chatTargets(org) {
+    if (!org.chat.enabled)
+        return [];
+    const noPublicHostname = "chat's Synapse and MAS have no public hostname of their own (chat-matrix.ts: 'NO PUBLIC HOSTNAME OF ITS OWN') -- only the chat service's own route through Agora is reachable from outside";
+    return [
+        {
+            service: 'chat',
+            url: `https://${agoraHostnameFor(org)}${CHAT_SERVICE_HEALTH_PATH}`,
+            expect: okExpect(),
+            depth: 'deep',
+            restartSafe: true,
+            behindAccess: false,
+        },
+        {
+            service: 'chat-synapse',
+            url: null,
+            expect: okExpect(),
+            depth: 'shallow',
+            restartSafe: false,
+            behindAccess: false,
+            reason: noPublicHostname,
+        },
+        {
+            service: 'chat-mas',
+            url: null,
+            expect: okExpect(),
+            depth: 'shallow',
+            restartSafe: false,
+            behindAccess: false,
+            reason: noPublicHostname,
+        },
+    ];
+}
+/**
+ * Calls, when enabled. Unlike chat, the calls *service* is the one thing
+ * with its own public hostname (`callsHostnameFor`); its own Synapse/MAS are
+ * internal-only the same way chat's are (`calls-matrix.ts`'s own "NO PUBLIC
+ * HOSTNAME OF ITS OWN"), so this issue does not add separate targets for
+ * them -- #541's own "How" lists "calls" as one service here, not three the
+ * way chat's is spelled out.
+ */
+function callsTargets(org) {
+    if (!org.calls.enabled)
+        return [];
+    return [
+        {
+            service: 'calls',
+            url: `https://${callsHostnameFor(org)}${CALLS_HEALTH_PATH}`,
+            expect: okExpect(),
+            depth: 'shallow',
+            restartSafe: false,
+            behindAccess: false,
+        },
+    ];
+}
+/** One hosting entry's own target, the `healthUrls` fallback rule restated richly rather than copied differently. */
+function hostingEntryTarget(org, entry) {
+    const [hostname] = entryHostnames(org, entry);
+    if (!hostname) {
+        return {
+            service: entry.key,
+            url: null,
+            expect: okExpect(),
+            depth: 'shallow',
+            restartSafe: true,
+            behindAccess: false,
+            reason: `the '${entry.key}' entry is internal: it has no public hostname (entryHostnames) to probe`,
+        };
+    }
+    const path = entry.healthPath ?? (entry.buildPack === 'static' ? STATIC_PAGE_PATH : DEFAULT_API_HEALTH_PATH);
+    return {
+        service: entry.key,
+        url: `https://${hostname}${path}`,
+        expect: okExpect(),
+        depth: entry.buildPack === 'static' ? 'page' : entry.database ? 'deep' : 'shallow',
+        restartSafe: true,
+        // Only the `app` entry may be gated behind Cloudflare Access at all
+        // (`org.ts`'s own `HostingEntry.accessEmails` doc comment).
+        behindAccess: entry.key === APP_ENTRY_KEY && entry.accessEmails.length > 0,
+    };
+}
+/**
+ * The org's own app: either its hosting entries, or its site + cms pair,
+ * never both -- the same `if` / `else if` `healthUrls` uses, restated so the
+ * richer shape stays in step with it rather than drifting from a second,
+ * differently-written version of the same choice.
+ */
+function appTargets(org) {
+    if (org.hosting.enabled && appEntry(org.hosting)) {
+        return org.hosting.entries.map((entry) => hostingEntryTarget(org, entry));
+    }
+    if (org.site.enabled && org.domain) {
+        return [
+            {
+                service: 'site',
+                url: `https://${org.domain}${DEFAULT_API_HEALTH_PATH}`,
+                expect: okExpect(),
+                depth: 'deep',
+                restartSafe: true,
+                behindAccess: false,
+            },
+            {
+                service: 'cms',
+                url: `https://${cmsHostnameFor(org)}${DEFAULT_API_HEALTH_PATH}`,
+                expect: okExpect(),
+                depth: 'deep',
+                restartSafe: true,
+                behindAccess: false,
+            },
+        ];
+    }
+    return [];
+}
+/**
+ * One target per service foundry runs for this company (#541). Always Boule,
+ * Agora and login; mail, chat (the chat service, Synapse, MAS), calls and
+ * the broker whenever the org has them; then whichever of hosting or site
+ * the org runs, if either.
+ */
+export function healthTargets(org) {
+    const targets = alwaysOnTargets(org);
+    const broker = brokerTarget(org);
+    if (broker)
+        targets.push(broker);
+    const mail = mailTarget(org);
+    if (mail)
+        targets.push(mail);
+    targets.push(...chatTargets(org));
+    targets.push(...callsTargets(org));
+    targets.push(...appTargets(org));
+    return targets;
+}
+/**
+ * ZITADEL, zitadel-login and the broker all answer on the one
+ * `platform.auth.hostname`, path-routed (`platform-providers.ts`'s own
+ * `provisionPlatformAuth`: `AUTH_ZITADEL_PATH_PATTERN` and
+ * `AUTH_BROKER_PATH_PATTERN`, with login the catch-all for everything
+ * neither matches) -- three services foundry runs under the one
+ * `platform:auth` step, so three targets here, not one.
+ */
+function authTargets(platform) {
+    const hostname = platform.auth.hostname;
+    return [
+        {
+            service: 'auth-zitadel',
+            url: `https://${hostname}${ZITADEL_HEALTH_PATH}`,
+            expect: okExpect(),
+            depth: 'shallow',
+            restartSafe: false,
+            behindAccess: false,
+        },
+        {
+            service: 'auth-login',
+            url: `https://${hostname}${LOGIN_READY_PATH}`,
+            expect: okExpect(),
+            depth: 'shallow',
+            restartSafe: false,
+            behindAccess: false,
+        },
+        {
+            service: 'auth-broker',
+            url: `https://${hostname}${BROKER_HEALTH_PATH}`,
+            expect: okExpect(),
+            depth: 'shallow',
+            restartSafe: false,
+            behindAccess: false,
+        },
+    ];
+}
+/** Why `platform:ai`/`platform:files` have nothing to probe yet: both runners are created with no Coolify `domains`, tunnel or DNS of their own (`platform-providers.ts`'s own doc comments, verbatim in each reason below). */
+function internalOnlyTarget(service, reason) {
+    return {
+        service,
+        url: null,
+        expect: okExpect(),
+        depth: 'shallow',
+        restartSafe: true,
+        behindAccess: false,
+        reason,
+    };
+}
+/**
+ * The seven platform services #541 names (`platform:auth`, `platform:archon`,
+ * `platform:mail`, `platform:ai`, `platform:files`, `platform:integrations`,
+ * `platform:edge`) -- `platform:sfu` and `platform:jobs` are shared platform
+ * resources too, but neither is in that list, and this issue does not expand
+ * it: the SFU has no hostname (`platform-sfu.ts`'s own doc comment: no cheap
+ * way to read it over SSH, let alone over HTTP) and the jobs scheduler's
+ * admin API answers 401 with no token (`platform-providers.ts`'s own
+ * `coolify:jobs` step), so an outside prober could not usefully reach either
+ * one anyway.
+ */
+export function platformHealthTargets(platform) {
+    return [
+        ...authTargets(platform),
+        {
+            service: 'archon',
+            url: `https://${platform.archon.hostname}${DEFAULT_API_HEALTH_PATH}`,
+            expect: okExpect(),
+            depth: 'deep',
+            restartSafe: false,
+            behindAccess: false,
+        },
+        {
+            service: 'mail',
+            url: `https://${platform.mail.hostname}${STALWART_READY_PATH}`,
+            expect: okExpect(),
+            depth: 'deep',
+            restartSafe: false,
+            behindAccess: false,
+        },
+        internalOnlyTarget('ai', "platform:ai's runner is created with no Coolify domains, tunnel, DNS record or Access app (platform-providers.ts) -- nothing public to probe yet"),
+        internalOnlyTarget('files', "platform:files' runner is created with no domains either, the same as platform:auth's apps (platform-providers.ts) -- nothing public to probe yet"),
+        {
+            service: 'integrations',
+            url: null,
+            expect: okExpect(),
+            depth: 'shallow',
+            restartSafe: true,
+            behindAccess: false,
+            reason: "platform:integrations' hostname has no Cloudflare wiring of its own (platform-providers.ts: 'no Cloudflare wiring is created for hostname') -- whether it resolves at all depends on DNS this executor never set up",
+        },
+        {
+            // Edge gets a real tunnel and DNS record, unlike ai/files/integrations
+            // (`provisionPlatformEdge`'s own doc comment: "the public-service shape
+            // provisionPlatformMail/provisionPlatformAuth use ... EDGE_URL has to
+            // be reachable by every org's own app").
+            service: 'edge',
+            url: `https://${platform.edge.hostname}${DEFAULT_API_HEALTH_PATH}`,
+            expect: okExpect(),
+            depth: 'deep',
+            restartSafe: true,
+            behindAccess: false,
+        },
+    ];
+}

package/dist/plan/index.d.ts

@@ -5,7 +5,7 @@ export { computePlanDetail, toPlan } from './diff.js';
 export type { StepSystem } from './step-system.js';
 export { stepSystemOf } from './step-system.js';
 export type { PlatformPlanDetail } from './platform-diff.js';
-export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, } from './platform-diff.js';
+export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, } from './platform-diff.js';
 export type { HeldKeyResolver, OrgPlatformReadiness } from './platform-org.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './platform-org.js';
 export type { PlatformOrgClientFactories } from './platform-org-ports.js';
@@ -15,7 +15,7 @@ export { AdoptRefusedError } from './adopt.js';
 export type { AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, } from './plan-apply.js';
 export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan-apply.js';
 export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, filesPublicHostsValue, filesShareDomains, } from './platform-providers.js';
-export type { PlatformAuthDeps, PlatformAuthRuntime, PlatformFilesDeps, PlatformFilesRuntime, PlatformEdgeDeps, PlatformEdgeRuntime, } from './platform-providers.js';
+export type { PlatformAuthDeps, PlatformAuthRuntime, PlatformFilesDeps, PlatformFilesRuntime, PlatformEdgeDeps, PlatformDnsFactory, PlatformAccessFactory, PlatformAccessPort, PlatformTunnelsFactory, PlatformEdgeRuntime, } from './platform-providers.js';
 export type { PlatformMailDeps, PlatformMailAdminPort, PlatformMailRuntime, } from './platform-providers.js';
 export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, PLATFORM_AUTH_INSTANCE_BEARER_REF, } from './platform-providers.js';
 export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManagementKeyExistsError, createAiManagementKeyMinter, PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, } from './platform-providers.js';
@@ -27,7 +27,7 @@ export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep } from './pla
 export type { MailCopyJob, MailCopyPort, MailCopyStepResult } from './mail-copy.js';
 export { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, MissingMailCopyAccountsError, MissingMailCopySourceTokenError, MissingMailCopyStalwartTokenError, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';
 export type { ScopeResolver, RecordedIds } from './providers-readers.js';
-export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
+export { ProvidersAiReader, ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
 export type { AgoraHostPort, AgoraHostValues } from './agora.js';
 export type { BrokerPort } from './broker-entries.js';
 export { PlatformBrokerPort } from './broker-entries.js';
@@ -39,6 +39,20 @@ export type { MailAllowlistApp } from './mail-identity-allowlist.js';
 export { checkMailAppsAllowlist } from './mail-identity-allowlist.js';
 export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, JobsSchedulerPort, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, PlatformOrgPortSource, } from './executor.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls } from './executor.js';
+export type { HealthTarget, HealthTargetDepth, HealthTargetExpect } from './health-targets.js';
+export { healthTargets, platformHealthTargets } from './health-targets.js';
+export { createEdgeDns, EDGE_DNS_WRITE_CONCURRENCY } from './edge-dns.js';
+export type { DnsPort, DnsRecordInput, DnsRecordSummary, EdgePlatformDns } from './edge-dns.js';
+export { createEdgeAccess } from './edge-access.js';
+export type { AccessAppSummary, AccessDecision, AccessPolicyRule, AccessPort, EdgePlatformAccess, } from './edge-access.js';
+export { createEdgeWorkers } from './edge-workers.js';
+export type { EdgePlatformWorkers, EdgeWorkersOptions } from './edge-workers.js';
+export { createEdgeRateLimits } from './edge-ratelimits.js';
+export type { EdgePlatformRateLimits, EdgeRateLimitsOptions, RateLimitPort, RateLimitRuleInput, } from './edge-ratelimits.js';
+export { createEdgeZones } from './edge-zones.js';
+export type { EdgePlatformZones, EdgeZonesOptions, ZonePort } from './edge-zones.js';
+export { createEdgeTunnels } from './edge-tunnels.js';
+export type { EdgePlatformTunnels, TunnelIngress, TunnelPort, TunnelSummary, } from './edge-tunnels.js';
 export type { ZitadelListAppsRawApp } from './executor.js';
 export { adaptZitadelListApps } from './executor.js';
 export { HttpJobsSchedulerClient } from './jobs-scheduler-http.js';

package/dist/plan/index.js

@@ -1,7 +1,7 @@
 export { readLiveResources, readLivePlatformResources } from './live.js';
 export { computePlanDetail, toPlan } from './diff.js';
 export { stepSystemOf } from './step-system.js';
-export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, } from './platform-diff.js';
+export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, } from './platform-diff.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './platform-org.js';
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './platform-org-ports.js';
 export { AdoptRefusedError } from './adopt.js';
@@ -14,11 +14,18 @@ export { createZitadelAdminMinter } from './zitadel-machine-user.js';
 export { createZitadelProjectRoles } from './zitadel-project-roles.js';
 export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep } from './platform-sfu.js';
 export { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, MissingMailCopyAccountsError, MissingMailCopySourceTokenError, MissingMailCopyStalwartTokenError, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';
-export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
+export { ProvidersAiReader, ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
 export { PlatformBrokerPort } from './broker-entries.js';
 export { loginHostnameFor } from './login-host.js';
 export { checkMailIdentityAudience } from './mail-identity.js';
 export { checkMailAppsAllowlist } from './mail-identity-allowlist.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls } from './executor.js';
+export { healthTargets, platformHealthTargets } from './health-targets.js';
+export { createEdgeDns, EDGE_DNS_WRITE_CONCURRENCY } from './edge-dns.js';
+export { createEdgeAccess } from './edge-access.js';
+export { createEdgeWorkers } from './edge-workers.js';
+export { createEdgeRateLimits } from './edge-ratelimits.js';
+export { createEdgeZones } from './edge-zones.js';
+export { createEdgeTunnels } from './edge-tunnels.js';
 export { adaptZitadelListApps } from './executor.js';
 export { HttpJobsSchedulerClient } from './jobs-scheduler-http.js';

package/dist/plan/live.d.ts

@@ -29,8 +29,19 @@ export interface LiveResource {
      * this union so `StepAction.system` (`diff.ts`) can name it. `'edge'`
      * (#317) is the same: a edge key has no live lookup of its own, the same
      * shape `ai`/`files` entry keys already follow.
+     *
+     * `'heartbeats'` (#540) is the one system here with a cheap live list of
+     * its own (`HeartbeatsPort.listChecks`, `platform-providers.ts`) --
+     * `platform-diff.ts`'s `planHeartbeats` still does not diff against a
+     * `LiveResource` list here: the reconcile step itself (list, create
+     * missing, delete stale) is what does that diffing, against the live
+     * check names. `planHeartbeats` plans that step only when its own
+     * recorded desired-set marker (`PLATFORM_HEARTBEATS_APPLIED_SCOPE_KEY`)
+     * no longer matches what is currently declared, never unconditionally --
+     * see that function's own doc comment for why "always planned" broke
+     * `bootstrapPlatform`.
      */
-    system: 'zitadel' | 'coolify' | 'cloudflare' | 'files' | 'ai' | 'cms' | 'jobs' | 'sfu' | 'edge';
+    system: 'zitadel' | 'coolify' | 'cloudflare' | 'files' | 'ai' | 'cms' | 'jobs' | 'sfu' | 'edge' | 'heartbeats';
     kind: string;
     key: string;
     config: Record<string, unknown>;

package/dist/plan/plan-apply.d.ts

@@ -208,6 +208,10 @@ export interface PlatformStepExecutor {
         mail?: string;
         /** #257: see `PlanPlatformOptions.blocked.backupExecutorMissing` (`platform-diff.ts`). */
         backupExecutorMissing?: boolean;
+        /** #540: see `PlanPlatformOptions.blocked.hc` (`platform-diff.ts`). */
+        hc?: string;
+        /** #540: see `PlanPlatformOptions.blocked.heartbeatsExecutorMissing` (`platform-diff.ts`). */
+        heartbeatsExecutorMissing?: boolean;
     }>;
     /**
      * Steps whose live state differs from the declared one in a way the recorded

package/dist/plan/plan-apply.js

@@ -8,7 +8,7 @@ import { AdoptRefusedError, adoptCandidates, adoptedKeysUnreadable, adoptedScope
 import { NO_AGORA_HOST_VALUES, readAgoraHost, } from './agora.js';
 import { AI_KEY_UNDELIVERED_SCOPE_KEY, JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY, computePlanDetail, toPlan, } from './diff.js';
 import { entryAiUndeliveredScopeKey } from './entry-ai-key.js';
-import { entryEdgeRetiredScopeKey, entryEdgeUndeliveredScopeKey } from './entry-edge-key.js';
+import { BOULE_EDGE_ENTRY_KEY, entryEdgeRetiredScopeKey, entryEdgeUndeliveredScopeKey, } from './entry-edge-key.js';
 import { FILES_ROOT_UNDELIVERED_SCOPE_KEY, entryFilesUndeliveredScopeKey, } from './entry-files-key.js';
 import { readLivePlatformResources, readLiveResources, } from './live.js';
 import { lockedHostnames } from './locked-hostnames.js';
@@ -1376,6 +1376,10 @@ function failedFields(org, detail, completed, serviceIds) {
             failed.add('hosting.entries.uses.edge');
         }
     }
+    // F3: Boule's own key, wanted whenever the org has a domain.
+    if (org.domain && serviceIds[entryEdgeUndeliveredScopeKey(BOULE_EDGE_ENTRY_KEY)]) {
+        failed.add('hosting.entries.uses.edge');
+    }
     // The same for a jobs registration whose credentials never reached the host.
     if (serviceIds[JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY] &&
         !serviceIds[`jobs:registration:${org.id}`]) {