@wtfalch/foundry 0.19.1 → 0.21.0

package/dist/bootstrap/declare.d.ts

@@ -21,6 +21,19 @@ export declare const DEFAULT_GIT_REF = "main";
  * file's loader follows.
  */
 export declare const DEFAULT_MAIL_IMAGE_TAG: string;
+/**
+ * #540: the Healthchecks image tag the platform's `hc` step runs.
+ * `platform.hc.gitRef` is an image tag, the same overload `mail.gitRef`
+ * carries. #540 shipped this floating at `'latest'`, with no
+ * `versions.json` pin and no `floatingTagBlocked` guard at all -- a real
+ * reviewed gap, closed round 2 the same way Stalwart's own tag is pinned:
+ * `versions.json`'s `hc` entry, checked against `healthchecks/healthchecks`'s
+ * real GitHub releases and Docker Hub tags (2026-10, latest stable `v4.4`)
+ * rather than guessed, and `hcImageTagBlocked` (`platform-providers.ts`)
+ * refuses a floating one the way `mailImageTagBlocked` already does for
+ * Stalwart.
+ */
+export declare const DEFAULT_HC_IMAGE_TAG: string;
 export interface BootstrapCompany {
     name: string;
     slug: string;

package/dist/bootstrap/declare.js

@@ -23,12 +23,28 @@ export const DEFAULT_GIT_REF = 'main';
  */
 export const DEFAULT_MAIL_IMAGE_TAG = VERSIONS.stalwart;
 /**
- * Every platform service except `sfu` and `edge` is enabled, like the other
- * steps: a service whose dependencies the host did not supply is reported
- * blocked, not planned. `sfu` stays off because it needs a held SSH key and
- * host fingerprint, a separate human step (issue 170). `edge` stays off
- * because the edge service (N1) does not exist yet -- a human deploys it
- * and sets its hostname before enabling it (#317's own "Human steps").
+ * #540: the Healthchecks image tag the platform's `hc` step runs.
+ * `platform.hc.gitRef` is an image tag, the same overload `mail.gitRef`
+ * carries. #540 shipped this floating at `'latest'`, with no
+ * `versions.json` pin and no `floatingTagBlocked` guard at all -- a real
+ * reviewed gap, closed round 2 the same way Stalwart's own tag is pinned:
+ * `versions.json`'s `hc` entry, checked against `healthchecks/healthchecks`'s
+ * real GitHub releases and Docker Hub tags (2026-10, latest stable `v4.4`)
+ * rather than guessed, and `hcImageTagBlocked` (`platform-providers.ts`)
+ * refuses a floating one the way `mailImageTagBlocked` already does for
+ * Stalwart.
+ */
+export const DEFAULT_HC_IMAGE_TAG = VERSIONS.hc;
+/**
+ * Every platform service except `sfu` is enabled, like the other steps: a
+ * service whose dependencies the host did not supply is reported blocked,
+ * not planned. `sfu` stays off because it needs a held SSH key and host
+ * fingerprint, a separate human step (issue 170). `edge` is on because every
+ * platform DNS record is written through it (F4.dns); its own Cloudflare API
+ * token is a held key (`cloudflare:edge:apiToken`), and until a human holds
+ * it the planner reports edge blocked, and auth, mail and archon with it.
+ * `hc` (#540) is on too: it needs no held key of its own, only edge's DNS,
+ * the same as mail and archon.
  */
 const SERVICES_ENABLED_BY_DEFAULT = new Set([
     'auth',
@@ -38,6 +54,8 @@ const SERVICES_ENABLED_BY_DEFAULT = new Set([
     'jobs',
     'integrations',
     'archon',
+    'edge',
+    'hc',
 ]);
 /**
  * The owner as `OwnerIdentity`, trimmed. Throws a plain error naming the
@@ -113,7 +131,13 @@ export function declaredPlatformFor(apex, serverIpv4) {
         services[key] = {
             enabled,
             hostname: defaultPlatformHostname(key, apex),
-            gitRef: !enabled ? '' : key === 'mail' ? DEFAULT_MAIL_IMAGE_TAG : DEFAULT_GIT_REF,
+            gitRef: !enabled
+                ? ''
+                : key === 'mail'
+                    ? DEFAULT_MAIL_IMAGE_TAG
+                    : key === 'hc'
+                        ? DEFAULT_HC_IMAGE_TAG
+                        : DEFAULT_GIT_REF,
         };
     }
     return {

package/dist/bootstrap/versions.d.ts

@@ -12,6 +12,7 @@ export interface PinnedVersions {
     livekit: string;
     cloudflared: string;
     stalwart: string;
+    hc: string;
 }
 export declare function loadVersions(): PinnedVersions;
 export declare const VERSIONS: PinnedVersions;

package/dist/index.d.ts

@@ -20,7 +20,9 @@ export type { FoundryStoreDb } from './store/postgres.js';
 export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, type AuditEventRow, type DeclaredOrgRow, type NewDeclaredOrgRow, type AppliedStateRow, type NewAppliedStateRow, type AppliedVersionRow, type NewAppliedVersionRow, type DeclaredPlatformRow, type NewDeclaredPlatformRow, type RequestedChangeRow, type NewRequestedChangeRow, } from './store/schema.js';
 export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, PlatformCloudflareReader, PlatformCoolifyReader, PlatformLiveReaders, StepAction, PlannedStep, StepSystem, PlanDetail, PlatformPlanDetail, AdoptCandidate, AdoptInput, AdoptPlan, AdoptSnapshot, AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, } from './plan/index.js';
 export { AdoptRefusedError } from './plan/index.js';
-export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, 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_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_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, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
+export { createEdgeAccess, createEdgeDns, createEdgeRateLimits, createEdgeTunnels, createEdgeWorkers, createEdgeZones, } from './plan/index.js';
+export type { AccessAppSummary, AccessDecision, AccessPolicyRule, AccessPort, DnsPort, EdgePlatformAccess, EdgePlatformDns, EdgePlatformRateLimits, EdgePlatformWorkers, EdgePlatformZones, EdgeZonesOptions, ZonePort, EdgeRateLimitsOptions, RateLimitPort, RateLimitRuleInput, EdgeWorkersOptions, EdgePlatformTunnels, TunnelPort, } from './plan/index.js';
+export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, 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_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_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, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
 export type { HeldKeyResolver, OrgPlatformReadiness } from './plan/index.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './plan/index.js';
 export type { PlatformOrgClientFactories } from './plan/index.js';
@@ -28,8 +30,10 @@ export { PlatformOrgBlockedError, PlatformOrgPorts } from './plan/index.js';
 export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, JobsSchedulerPort, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, PlatformOrgPortSource, AgoraHostPort, AgoraHostValues, LoginHostBinding, LoginHostBindingsPort, } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';
 export { HttpJobsSchedulerClient } from './plan/index.js';
+export type { HealthTarget, HealthTargetDepth, HealthTargetExpect } from './plan/index.js';
+export { healthTargets, platformHealthTargets } from './plan/index.js';
 export type { ScopeResolver, RecordedIds } from './plan/index.js';
-export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './plan/index.js';
+export { ProvidersAiReader, ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './plan/index.js';
 export type { ZitadelListAppsRawApp } from './plan/index.js';
 export { adaptZitadelListApps } from './plan/index.js';
 export type { MailIdentityApp, MailIdentityAudienceCheck } from './plan/index.js';
@@ -37,7 +41,7 @@ export { checkMailIdentityAudience } from './plan/index.js';
 export type { MailAllowlistApp } from './plan/index.js';
 export { checkMailAppsAllowlist } from './plan/index.js';
 export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, createZitadelAdminMinter, createZitadelProjectRoles, PLATFORM_AUTH_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './plan/index.js';
-export type { PlatformAuthDeps, PlatformAuthRuntime, PlatformFilesDeps, PlatformFilesRuntime, PlatformEdgeDeps, PlatformEdgeRuntime, } from './plan/index.js';
+export type { PlatformAuthDeps, PlatformAuthRuntime, PlatformFilesDeps, PlatformFilesRuntime, PlatformEdgeDeps, PlatformDnsFactory, PlatformAccessFactory, PlatformAccessPort, PlatformTunnelsFactory, PlatformEdgeRuntime, } from './plan/index.js';
 export type { PlatformMailDeps, PlatformMailAdminPort, PlatformMailRuntime, } from './plan/index.js';
 export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, PLATFORM_AUTH_INSTANCE_BEARER_REF, } from './plan/index.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 './plan/index.js';

package/dist/index.js

@@ -12,12 +12,14 @@ export { createPostgresAppliedVersionsStore, createPostgresDeclaredOrgStore, cre
 export { createPostgresAuditLog } from './store/audit.js';
 export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, } from './store/schema.js';
 export { AdoptRefusedError } from './plan/index.js';
-export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, 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_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_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, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
+export { createEdgeAccess, createEdgeDns, createEdgeRateLimits, createEdgeTunnels, createEdgeWorkers, createEdgeZones, } from './plan/index.js';
+export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, 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_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_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, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './plan/index.js';
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';
 export { HttpJobsSchedulerClient } from './plan/index.js';
-export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './plan/index.js';
+export { healthTargets, platformHealthTargets } from './plan/index.js';
+export { ProvidersAiReader, ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './plan/index.js';
 export { adaptZitadelListApps } from './plan/index.js';
 export { checkMailIdentityAudience } from './plan/index.js';
 export { checkMailAppsAllowlist } from './plan/index.js';

package/dist/migrations/0046_platform_hc.sql

@@ -0,0 +1,19 @@
+-- @wtfalch/foundry: #540 -- the platform's own heartbeat server (self-hosted
+-- Healthchecks), added to the declared platform the same way every other
+-- shared service here was (#165, #317). Mirrors `src/store/schema.ts`'s
+-- `foundryDeclaredPlatform` table additions. Backfills `hc_hostname` the
+-- same way `0043_platform_names.sql` backfilled `names_hostname`: the
+-- column must not be empty (`src/platform.ts`'s `validatePlatform`), and
+-- the table already carries its one live row by the time this runs.
+
+alter table foundry_declared_platform
+  add column if not exists hc_enabled boolean not null default false,
+  add column if not exists hc_hostname text,
+  add column if not exists hc_git_ref text not null default '';
+
+update foundry_declared_platform
+  set hc_hostname = 'hc.' || apex
+  where hc_hostname is null;
+
+alter table foundry_declared_platform
+  alter column hc_hostname set not null;

package/dist/plan/cloudflared-connector.d.ts

@@ -1,4 +1,5 @@
-import type { CloudflarePort, CoolifyPort } from './executor.js';
+import type { TunnelPort } from './edge-tunnels.js';
+import type { CoolifyPort } from './executor.js';
 /**
  * #197: the pinned `cloudflared` image, the same release tag as
  * `scripts/shared-ingress.mjs`'s and `calls-sfu.ts`'s own
@@ -24,7 +25,7 @@ export declare function cloudflaredDockerfile(): string;
  */
 export interface EnsureCloudflaredConnectorInput {
     coolify: Pick<CoolifyPort, 'findApplicationByName' | 'getApplication' | 'createDockerfileApplication' | 'bulkUpsertEnvs' | 'listEnvs' | 'deploy'>;
-    cloudflare: Pick<CloudflarePort, 'getTunnelToken'>;
+    tunnels: Pick<TunnelPort, 'getTunnelToken'>;
     /** The Cloudflare tunnel this connector dials into (already created and configured by the caller). */
     tunnelId: string;
     /** Fixed name, found before created -- so a second apply reuses this app rather than making a second one. */

package/dist/plan/cloudflared-connector.js

@@ -32,7 +32,7 @@ export function cloudflaredDockerfile() {
  * with no cause, because a Coolify error can echo the request body.
  */
 export async function ensureCloudflaredConnector(input) {
-    const { coolify, cloudflare } = input;
+    const { coolify, tunnels } = input;
     const liveStatus = async (uuid) => {
         try {
             return { found: true, status: (await coolify.getApplication(uuid)).status };
@@ -82,7 +82,7 @@ export async function ensureCloudflaredConnector(input) {
     }
     if (appId !== input.recordedConnectorAppId)
         await input.recordAppId(appId);
-    const token = await cloudflare.getTunnelToken(input.tunnelId);
+    const token = await tunnels.getTunnelToken(input.tunnelId);
     const tokenChanged = justCreated || (await tunnelTokenDiffers(coolify, appId, token));
     if (tokenChanged) {
         try {

package/dist/plan/deploy-health.js

@@ -62,6 +62,8 @@
  */
 const DEFAULT_READY_TIMEOUT_MS = 300_000;
 const DEFAULT_READY_INTERVAL_MS = 5_000;
+/** One health request's own limit: a connection that accepts and never answers counts as not healthy yet, instead of blocking the whole wait. */
+const HEALTH_REQUEST_TIMEOUT_MS = 5_000;
 /** The one terminal `CoolifyDeploymentStatus` that means the new version landed. */
 const DEPLOYMENT_SUCCEEDED = 'finished';
 /**
@@ -135,7 +137,9 @@ export async function waitForNewDeployment(coolify, appId, health, runtime, slee
 }
 async function matchesHealth(fetchImpl, health) {
     try {
-        const response = await fetchImpl(health.url);
+        const response = await fetchImpl(health.url, {
+            signal: AbortSignal.timeout(HEALTH_REQUEST_TIMEOUT_MS),
+        });
         if (!response.ok)
             return false;
         if (health.kind === 'ready')

package/dist/plan/diff.js

@@ -214,10 +214,6 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const edgeReservedLabels = planEdgeReservedLabels(org, recordedIds, platformReadiness, options.platformHostnames ?? []);
     if (edgeReservedLabels.step)
         plannedSteps.push(edgeReservedLabels.step);
-    // After the apps -- a edge key needs the entry's app recorded, the same
-    // dependency `planEntryAiKeys`/`planFilesKeys` have.
-    const entryEdgeKeys = planEntryEdgeKeys(org, recordedIds, plannedSteps, platformReadiness, (options.now ?? Date.now)());
-    plannedSteps.push(...entryEdgeKeys.steps);
     const tunnel = planTunnel(org, byKey, claimed, recordedIds);
     // #238: a tunnel that is being provisioned waits for an active zone; parking
     // one never does.
@@ -264,6 +260,10 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const boule = planBoule(org, byKey, claimed, recordedIds, authIssuer, options.otherSlugs ?? [], options.archonUrl ?? null);
     if (boule.step)
         plannedSteps.push(boule.step);
+    // After the apps and Boule -- an edge key needs its app recorded or planned,
+    // the same dependency `planEntryAiKeys`/`planFilesKeys` have.
+    const entryEdgeKeys = planEntryEdgeKeys(org, recordedIds, plannedSteps, platformReadiness, (options.now ?? Date.now)());
+    plannedSteps.push(...entryEdgeKeys.steps);
     // Boule's own broker entry, after its app: the entry needs the AUTH_APP_KEY
     // that step puts in the app's env.
     const bouleBroker = planBouleBrokerEntry(org, recordedIds, plannedSteps, options.broker ?? false);
@@ -1955,6 +1955,29 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
             blocked,
         };
     }
+    // #543: a human turning the health check off in the Coolify UI (or an app
+    // applied before this patch existed) is noticed the same way `hasLogVolume`
+    // just above is -- `coolifyApp` already sends the quartet on every run, so
+    // replanning this one step (the same action, nothing extra) is the whole
+    // repair. A reader that did not check (`healthCheckEnabled` absent) reads
+    // as compliant, like `hasLogVolume`.
+    // Only for an entry `coolifyApp` would set the check on (a static entry,
+    // or one with a declared port): otherwise the repair could never land and
+    // every apply would replan it.
+    if (live.config.healthCheckEnabled === false &&
+        (entry.buildPack === 'static' || entry.port !== null)) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `turn Coolify's health check back on for ${org.slug}'s ${label} (#543)`,
+                    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

package/dist/plan/edge-access.d.ts

@@ -0,0 +1,68 @@
+import type { AccessDecision, createEdgeClient } from '@wtfalch/edge';
+import { type WriteSlot } from './edge-dns.js';
+/** The edge SDK's platform Access client: `createEdgeClient({ ... }).platform.access`. */
+export type EdgePlatformAccess = ReturnType<typeof createEdgeClient>['platform']['access'];
+export type { AccessDecision };
+/** One Access rule in Cloudflare's own shape: `{ email: { email } }`, `{ everyone: {} }`, `{ service_token: { token_id } }`. */
+export type AccessPolicyRule = Record<string, unknown>;
+export interface AccessAppSummary {
+    /** Cloudflare's app id: what every edge Access call takes. */
+    id: string;
+    name: string;
+    domain: string;
+}
+/**
+ * Foundry's Cloudflare Access calls. Every Access call in foundry goes through
+ * this; the one implementation is {@link createEdgeAccess}, which speaks to the
+ * edge service with the platform credential.
+ */
+export interface AccessPort {
+    /** Every live Access app foundry may use: the platform's own, and ones nobody adopted yet. */
+    listAccessApps(): Promise<AccessAppSummary[]>;
+    createAccessApp(app: {
+        name: string;
+        domain: string;
+        type: 'self_hosted';
+    }): Promise<{
+        id: string;
+    }>;
+    listAccessPolicies(appId: string): Promise<Array<{
+        id: string;
+        name: string;
+        include?: AccessPolicyRule[];
+    }>>;
+    createAccessPolicy(appId: string, policy: {
+        name: string;
+        decision: AccessDecision;
+        include: AccessPolicyRule[];
+    }): Promise<{
+        id: string;
+    }>;
+    /**
+     * A service token's id by exact name -- the token itself is a live
+     * Cloudflare resource foundry never mints and whose secret it never reads.
+     * `undefined` when no token has that name; throws when more than one does.
+     */
+    findServiceTokenByName(name: string): Promise<{
+        id: string;
+    } | undefined>;
+    deleteAccessApp(appId: string): Promise<void>;
+}
+/**
+ * Edge answers a policy, delete or create call for a live Access app with no
+ * edge row `not_found` or 409 `exists` ("create or adopt it first"). So the
+ * adapter adopts an app the moment it is about to be used: an app it saw in a
+ * list (or that a create refused with `exists`) whose owner edge reported as
+ * `null` is remembered, and adopted just before the first call on it. An app
+ * foundry recorded in an earlier apply and now names by id only is looked up
+ * on `not_found`, adopted if unowned, and the call retried once, so a destroy
+ * deletes it instead of finding "nothing there". Adopt is idempotent and the
+ * list reports the owner afterwards, so nothing is recorded in the plan. An
+ * app with an owner is never adopted or changed. An adopt that edge skips
+ * (`taken`, `unsupported_type`) is an error. A `rate_limited` answer is
+ * retried with edge's hint, up to 5 tries.
+ */
+export declare function createEdgeAccess(client: EdgePlatformAccess, options?: {
+    sleep?: (ms: number) => Promise<void>;
+    writeSlot?: WriteSlot;
+}): AccessPort;

package/dist/plan/edge-access.js

@@ -0,0 +1,123 @@
+import { EdgeApiError } from '@wtfalch/edge';
+import { EDGE_DNS_WRITE_CONCURRENCY, limiter, rateLimitRetrier, } from './edge-dns.js';
+const isNotFound = (error) => error instanceof EdgeApiError && error.code === 'not_found';
+/** Edge's 409 for a live app on the domain with no edge row. */
+const isExists = (error) => error instanceof EdgeApiError && error.code === 'conflict' && error.reason === 'exists';
+/**
+ * Edge answers a policy, delete or create call for a live Access app with no
+ * edge row `not_found` or 409 `exists` ("create or adopt it first"). So the
+ * adapter adopts an app the moment it is about to be used: an app it saw in a
+ * list (or that a create refused with `exists`) whose owner edge reported as
+ * `null` is remembered, and adopted just before the first call on it. An app
+ * foundry recorded in an earlier apply and now names by id only is looked up
+ * on `not_found`, adopted if unowned, and the call retried once, so a destroy
+ * deletes it instead of finding "nothing there". Adopt is idempotent and the
+ * list reports the owner afterwards, so nothing is recorded in the plan. An
+ * app with an owner is never adopted or changed. An adopt that edge skips
+ * (`taken`, `unsupported_type`) is an error. A `rate_limited` answer is
+ * retried with edge's hint, up to 5 tries.
+ */
+export function createEdgeAccess(client, options = {}) {
+    const retrying = rateLimitRetrier(options.sleep);
+    const access = {
+        list: (filter) => retrying(() => client.list(filter)),
+        create: (input) => retrying(() => client.create(input)),
+        remove: (id) => retrying(() => client.remove(id)),
+        listPolicies: (appId) => retrying(() => client.listPolicies(appId)),
+        createPolicy: (appId, input) => retrying(() => client.createPolicy(appId, input)),
+        findServiceToken: (name) => retrying(() => client.findServiceToken(name)),
+        adopt: (input) => retrying(() => client.adopt(input)),
+    };
+    const writeSlot = options.writeSlot ?? limiter(EDGE_DNS_WRITE_CONCURRENCY);
+    /** app id -> a seen live app with no edge row yet. */
+    const unadopted = new Map();
+    const remember = (views) => {
+        for (const view of views) {
+            if (view.owner === null)
+                unadopted.set(view.id, view);
+            else
+                unadopted.delete(view.id);
+        }
+    };
+    const adopt = async (view) => {
+        const result = await writeSlot(() => access.adopt({ apps: [{ name: view.name, domain: view.domain, id: view.id }] }));
+        const skipped = result.skipped[0];
+        if (skipped) {
+            throw new Error(`edge access: ${view.name} (${view.domain}) cannot be adopted (${skipped.reason}); remove or fix it by hand`);
+        }
+        if (result.notFound.length > 0) {
+            throw new EdgeApiError(404, 'not_found', `edge access: ${view.name} is no longer live`);
+        }
+        unadopted.delete(view.id);
+    };
+    /** Runs a call on an app; adopts it first when seen unowned, and once more on `not_found`. */
+    const onApp = async (appId, call) => {
+        const seen = unadopted.get(appId);
+        if (seen)
+            await adopt(seen);
+        try {
+            return await call();
+        }
+        catch (error) {
+            if (!isNotFound(error))
+                throw error;
+            const live = (await access.list()).apps;
+            remember(live);
+            const view = live.find((a) => a.id === appId);
+            if (!view || view.owner !== null)
+                throw error;
+            await adopt(view);
+            return call();
+        }
+    };
+    const listAccessApps = async () => {
+        const { apps } = await access.list();
+        remember(apps);
+        return apps.map((a) => ({ id: a.id, name: a.name, domain: a.domain }));
+    };
+    return {
+        listAccessApps,
+        async createAccessApp(app) {
+            try {
+                const created = await writeSlot(() => access.create({ name: app.name, domain: app.domain, type: app.type }));
+                return { id: created.id };
+            }
+            catch (error) {
+                // A live app holds the domain with no edge row. The one of this name
+                // and domain is foundry's own from before edge owned Access: use it,
+                // adopting it before its first policy call. Any other app is refused.
+                if (!isExists(error))
+                    throw error;
+                const { apps } = await access.list({ domain: app.domain });
+                remember(apps);
+                const same = apps.find((a) => a.name === app.name && a.owner === null);
+                if (!same)
+                    throw error;
+                return { id: same.id };
+            }
+        },
+        async listAccessPolicies(appId) {
+            const { policies } = await onApp(appId, () => access.listPolicies(appId));
+            return policies.map((p) => ({ id: p.id, name: p.name, include: p.include }));
+        },
+        async createAccessPolicy(appId, policy) {
+            const created = await onApp(appId, () => writeSlot(() => access.createPolicy(appId, policy)));
+            return { id: created.id };
+        },
+        async findServiceTokenByName(name) {
+            try {
+                const { token } = await access.findServiceToken(name);
+                return token ? { id: token.id } : undefined;
+            }
+            catch (error) {
+                if (error instanceof EdgeApiError && error.code === 'conflict') {
+                    throw new Error(`edge access: more than one Cloudflare Access service token is named '${name}'; rename or remove the extras`);
+                }
+                throw error;
+            }
+        },
+        async deleteAccessApp(appId) {
+            await onApp(appId, () => writeSlot(() => access.remove(appId)));
+        },
+    };
+}

package/dist/plan/edge-dns.d.ts

@@ -0,0 +1,89 @@
+import type { createEdgeClient } from '@wtfalch/edge';
+/** The edge SDK's platform DNS client: `createEdgeClient({ ... }).platform.dns`. */
+export type EdgePlatformDns = ReturnType<typeof createEdgeClient>['platform']['dns'];
+export interface DnsRecordSummary {
+    id: string;
+    type: string;
+    content: string;
+    name: string;
+}
+export interface DnsRecordInput {
+    type: string;
+    name: string;
+    content: string;
+    proxied?: boolean;
+    ttl?: number;
+    /** Required for an `MX` record. */
+    priority?: number;
+}
+/**
+ * Foundry's DNS calls. Every record call in foundry goes through this; the one
+ * implementation is {@link createEdgeDns}, which speaks to the edge service
+ * with the platform credential. `zone` is the zone's own domain (what
+ * `ZonePort.findZoneByApex` returns as `name`), not a Cloudflare zone
+ * id: edge addresses a zone by its domain.
+ */
+export interface DnsPort {
+    /** An exact name + type match, so a stale record of a different type is never mistaken for a match. */
+    findDnsRecord(zone: string, name: string, type?: string): Promise<DnsRecordSummary[]>;
+    /**
+     * Every record of a type in the zone, for a domain recorded before
+     * `CLOUDFLARE_TUNNEL_DNS_HOSTNAMES_SCOPE_KEY` existed and so with no
+     * hostname list to look up instead.
+     */
+    listDnsRecords(zone: string, opts?: {
+        type?: string;
+        name?: string;
+    }): Promise<DnsRecordSummary[]>;
+    createDnsRecord(zone: string, rec: DnsRecordInput): Promise<{
+        id: string;
+        name: string;
+        content: string;
+    }>;
+    updateDnsRecord(zone: string, recordId: string, rec: DnsRecordInput): Promise<{
+        id: string;
+        name: string;
+        content: string;
+    }>;
+    deleteDnsRecord(zone: string, recordId: string): Promise<void>;
+}
+/** Edge answers its platform writes from one shared slot of 4 (company-less writes). */
+export declare const EDGE_DNS_WRITE_CONCURRENCY = 4;
+/**
+ * Edge lists a TXT record raw, quoted (`"v=spf1 ..."`, long values in several
+ * quoted chunks), but returns it unquoted from a create or update. Everything
+ * foundry compares sees the unquoted form.
+ */
+export declare function unquoteTxt(content: string): string;
+export type WriteSlot = <T>(task: () => Promise<T>) => Promise<T>;
+export declare function limiter(max: number): WriteSlot;
+/**
+ * Edge's company-less platform calls share one per-org slot of 4 and answer a
+ * full slot with `rate_limited` and a retry hint, without queueing. The SDK
+ * does not retry, so every call here waits the hint out, up to this many tries.
+ */
+export declare const EDGE_DNS_RATE_LIMIT_ATTEMPTS = 5;
+/**
+ * Retries a call edge answered `rate_limited`, waiting out its hint (capped at
+ * 30 s), up to {@link EDGE_DNS_RATE_LIMIT_ATTEMPTS} tries. Shared by every
+ * edge adapter, since all platform calls draw on the one slot.
+ */
+export declare function rateLimitRetrier(sleepOption?: (ms: number) => Promise<void>): <T>(task: () => Promise<T>) => Promise<T>;
+/**
+ * Edge answers an update or delete of a live record with no edge row
+ * `not_found` ("adopt it first"). So the adapter adopts a record the moment it
+ * is about to be changed or removed: every record it has returned that the
+ * list reported with `owner: null` is remembered, and adopted just before the
+ * first write that names it. Adopt is idempotent and the list reports the
+ * owner once adopted, so nothing is recorded in the plan and a later apply
+ * adopts nothing. A record foundry only reads (a foreign record it refuses to
+ * overwrite) is never adopted. An `unsupported_type`, `taken` or `organisation`
+ * skip is an error; an `unclaimed` record is left alone. A company's own record
+ * (edge answers `forbidden`) is never changed: the error names zone, name and
+ * type. A `rate_limited` answer is retried with edge's hint, up to 5 tries.
+ */
+export declare function createEdgeDns(client: EdgePlatformDns, options?: {
+    sleep?: (ms: number) => Promise<void>;
+    /** Share one slot of {@link EDGE_DNS_WRITE_CONCURRENCY} with the tunnel adapter: edge counts both. */
+    writeSlot?: WriteSlot;
+}): DnsPort;