@wtfalch/foundry 0.17.1 → 0.19.0

package/dist/plan/diff.d.ts

@@ -51,8 +51,10 @@ export interface PlanOrgOptions {
     now?: () => number;
     /** #374: the Archon that bills this org (`plan-apply.ts`'s `orgArchonUrl`), written into Boule's env as `ARCHON_URL`. `null` with no platform wired. */
     archonUrl?: string | null;
-    /** #318: the executor was built with a `WorkersPort`, read by `planEdgeWorkers`. */
+    /** #318: the executor was built with a `WorkersPort`, read by `planWorkers`. */
     edgeWorkers?: boolean;
+    /** The platform's own service hostnames: `edgeReservedLabels` reserves them under the org's domain, and a wildcard Worker route (`planWorkers`) keeps them out. */
+    platformHostnames?: readonly string[];
 }
 export interface PlanDetail {
     orgId: OrgId;

package/dist/plan/diff.js

@@ -1,12 +1,11 @@
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY, ownerMailboxRecorded, ownerMailboxes } from '../org.js';
-import { AGORA_ACTIVATED_ENV_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
+import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
 import { BOULE_BROKER_ENTRY_KEY, bouleEnvDrift, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
-import { planEdgeWorkers } from './edge-worker.js';
 import { planEntryAiKeys } from './entry-ai-key.js';
+import { planEdgeReservedLabels, planEntryEdgeKeys } from './entry-edge-key.js';
 import { planFilesKeys } from './entry-files-key.js';
-import { planEntryNamesKeys, planNamesReservedLabels } from './entry-names-key.js';
 import { appHostname, entryHostnames, tunnelDnsHostnames } from './hostnames.js';
 import { LOGIN_BINDING_SCOPE_KEY, loginBindingState, loginHostClientIds, loginHostnameFor, pendingRemovalHosts, } from './login-host.js';
 import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, } from './mail-copy.js';
@@ -15,6 +14,7 @@ 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';
+import { planWorkers } from './worker.js';
 /** The `Plan` (#19's public contract) a `PlanDetail` carries. */
 export function toPlan(detail) {
     return {
@@ -82,7 +82,11 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const byKey = new Map(live.map((r) => [resourceKey(r.system, r.kind, r.key), r]));
     const claimed = new Set();
     const plannedSteps = [];
-    const issuer = planIssuer(org, byKey, claimed, platformReadiness.authReady);
+    // The platform's own org: its domain is the platform apex (the same fact
+    // #491 reads for mail). It signs in on the shared instance's own host, so
+    // `issuer.usesDomain` never moves it.
+    const isPlatformOrg = isPlatformOwnOrg(org, platformReadiness.platformApex);
+    const issuer = planIssuer(org, byKey, claimed, platformReadiness.authReady, isPlatformOrg);
     if (issuer.step)
         plannedSteps.push(issuer.step);
     plannedSteps.push(...planOwners(org, recordedIds, platformReadiness.authReady, 'error' in agoraHost ? null : agoraHost.issuer));
@@ -94,7 +98,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // URL (`https://<platform.auth.hostname>`), the same value every org's
     // sign-in already reads through `planOwners` above -- no separate port
     // or plumbing needed to know the platform's own auth hostname.
-    platformAuthHostnameFrom('error' in agoraHost ? null : agoraHost.issuer));
+    platformAuthHostnameFrom('error' in agoraHost ? null : agoraHost.issuer), isPlatformOrg);
     if (loginHost.step)
         plannedSteps.push(loginHost.step);
     // Planned ahead of everything that needs the zone live (#238); its own step
@@ -206,14 +210,14 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     plannedSteps.push(...filesKeys.steps);
     // F7 (#317): reserved labels before any entry's own key, so a label is
     // never claimable by a customer in the gap between an entry's key going
-    // live and its siblings' labels reaching names.
-    const namesReservedLabels = planNamesReservedLabels(org, recordedIds, platformReadiness);
-    if (namesReservedLabels.step)
-        plannedSteps.push(namesReservedLabels.step);
-    // After the apps -- a names key needs the entry's app recorded, the same
+    // live and its siblings' labels reaching edge.
+    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 entryNamesKeys = planEntryNamesKeys(org, recordedIds, plannedSteps, platformReadiness, (options.now ?? Date.now)());
-    plannedSteps.push(...entryNamesKeys.steps);
+    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.
@@ -274,16 +278,16 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // F8 (#318), after Agora and Boule, not right after the zone: a route
     // already bound by a hand-made entry, another entry's route, a taken
     // script name, or no Workers token all throw at apply, and `runSteps`
-    // stops at the first failure -- planned this early, a failing edge step
+    // stops at the first failure -- planned this early, a failing worker step
     // stopped Agora (and everything after it) from provisioning at all
     // (#318 re-review). `cloudflareWorker` still resolves the zone by apex
     // domain the same way `planRateLimit` does, so a deploy (never a
     // retire, which needs no new zone) still waits for it.
-    const edgeWorkers = planEdgeWorkers(org, recordedIds, options.edgeWorkers ?? false);
+    const edgeWorkers = planWorkers(org, recordedIds, options.edgeWorkers ?? false, options.platformHostnames ?? []);
     for (const step of edgeWorkers.steps) {
         if (zoneWaiting && step.action.desired.mode === 'apply') {
             zoneBlocked.push({
-                description: `${org.slug}'s ${step.action.key.slice(org.id.length + 1)} edge Worker is blocked, not planned: the zone for ${org.domain} is not active yet`,
+                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,
             });
         }
@@ -312,8 +316,8 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     unmanaged.push(...filesKeys.blocked);
     unmanaged.push(...entryAiKeys.blocked);
     unmanaged.push(...edgeWorkers.blocked);
-    unmanaged.push(...entryNamesKeys.blocked);
-    unmanaged.push(...namesReservedLabels.blocked);
+    unmanaged.push(...entryEdgeKeys.blocked);
+    unmanaged.push(...edgeReservedLabels.blocked);
     // Same for a jobs registration that cannot run (no scheduler wired) or must
     // not run again (minted, never delivered).
     if (jobsRegistration.blocked) {
@@ -391,7 +395,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
  * already exists live is unaffected: its own domain-move logic runs
  * regardless, since that never re-provisions the ZITADEL org itself.
  */
-function planIssuer(org, byKey, claimed, authReady) {
+function planIssuer(org, byKey, claimed, authReady, isPlatformOrg = false) {
     const key = resourceKey('zitadel', 'issuer', org.id);
     const live = byKey.get(key);
     const desiredUsesDomain = org.issuer.usesDomain;
@@ -420,9 +424,14 @@ function planIssuer(org, byKey, claimed, authReady) {
         };
     }
     claimed.add(key);
-    const liveUsesDomain = Boolean(live.config.usesDomain);
-    if (liveUsesDomain === desiredUsesDomain)
+    // The platform's own org already signs in on the shared host: no move. A
+    // live issuer that does not say (the reader never does: foundry v1 never
+    // moves one) is not read as a different one either.
+    if (isPlatformOrg ||
+        live.config.usesDomain === undefined ||
+        Boolean(live.config.usesDomain) === desiredUsesDomain) {
         return { step: null, blocked: null };
+    }
     const domain = org.domain ?? 'the org domain';
     return {
         step: {
@@ -519,6 +528,9 @@ function planOwners(org, recordedIds, authReady, authIssuer) {
  * computed `auth.<domain>` against, so the platform's own org never plans
  * its login host equal to the shared ZITADEL instance's own.
  */
+function isPlatformOwnOrg(org, platformApex) {
+    return Boolean(org.domain && platformApex && org.domain.toLowerCase() === platformApex.toLowerCase());
+}
 function platformAuthHostnameFrom(issuer) {
     if (!issuer)
         return null;
@@ -565,16 +577,58 @@ function platformAuthHostnameFrom(issuer) {
  * platform's own domain, never plans the shared ZITADEL instance's own login
  * host as its own -- `auth.companyincluded.com` colliding with itself.
  */
-function planLoginHost(org, recordedIds, authReady, issuerPlanned, bindingsWired, platformAuthHostname) {
+function planLoginHost(org, recordedIds, authReady, issuerPlanned, bindingsWired, platformAuthHostname, isPlatformOrg) {
     const none = { step: null, blocked: null };
     const key = resourceKey('zitadel', 'login-host', org.id);
-    const host = loginHostnameFor(org, platformAuthHostname);
+    // The platform's own org signs in on the shared instance's host whatever
+    // `issuer.usesDomain` says (turning it on would move the issuer).
+    // Before that host is known, plan nothing: a guessed host would delete the
+    // working one, and a normal step would trust a domain `destroy` later deletes.
+    if (isPlatformOrg && platformAuthHostname === null) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s login host is waiting for the platform auth host`,
+        };
+    }
+    const sharedInstanceHost = isPlatformOrg && platformAuthHostname !== null;
+    const host = sharedInstanceHost ? platformAuthHostname : loginHostnameFor(org);
     // #488: the guard in `loginHostnameFor` fired -- the org's own domain host
     // would have been the platform's shared ZITADEL instance host.
-    const sharedInstanceHost = Boolean(org.domain) &&
-        org.issuer.usesDomain &&
-        `auth.${org.domain}` === platformAuthHostname &&
-        host !== `auth.${org.domain}`;
+    if (sharedInstanceHost) {
+        // The host is the shared instance's own: nothing to trust or bind, and an
+        // org with no recorded host already signs in there. Only an org recorded
+        // on another host (the old `<slug>-auth.oikos.host`) plans one step, to
+        // move its apps over and remove the old host; then it plans nothing.
+        const recordedHost = recordedIds[key];
+        const moving = recordedHost !== undefined && recordedHost !== host;
+        const removalOwed = pendingRemovalHosts(recordedIds).length > 0;
+        if (!authReady || !(moving || removalOwed))
+            return none;
+        // The same gates as the normal branch: the executor's shared step also
+        // needs the binding port and the ZITADEL org.
+        const waiting = loginHostWaiting(org, host, recordedIds, bindingsWired, issuerPlanned);
+        return waiting ?? stepFor(true);
+    }
+    function stepFor(shared) {
+        return {
+            step: {
+                action: {
+                    system: 'zitadel',
+                    kind: 'login-host',
+                    key: org.id,
+                    desired: shared ? { host, shared: true } : { host },
+                },
+                step: {
+                    description: shared
+                        ? `move ${org.slug}'s apps onto the platform's own sign-in host ${host}`
+                        : `set ${org.slug}'s login host to ${host}`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked: null,
+        };
+    }
     // Already applied -- a re-run plans nothing unless the host changed, an app
     // client id appeared since the binding was last written (#267, rule 4), or
     // an earlier host change still has a removal owed (#274 fix round 2):
@@ -595,6 +649,10 @@ function planLoginHost(org, recordedIds, authReady, issuerPlanned, bindingsWired
     // Isolation between orgs rests on zitadel-login's binding, and repointing
     // an app at a host with no binding breaks its sign-in: trust nothing and
     // repoint nothing until the port that writes the binding is wired.
+    return loginHostWaiting(org, host, recordedIds, bindingsWired, issuerPlanned) ?? stepFor(false);
+}
+/** Why a login-host step cannot run yet, or `null` when nothing is missing. */
+function loginHostWaiting(org, host, recordedIds, bindingsWired, issuerPlanned) {
     if (!bindingsWired) {
         return {
             step: null,
@@ -609,24 +667,7 @@ function planLoginHost(org, recordedIds, authReady, issuerPlanned, bindingsWired
             blocked: `${org.slug}'s login host ${host} waits for its ZITADEL org, which is not recorded yet`,
         };
     }
-    return {
-        step: {
-            action: {
-                system: 'zitadel',
-                kind: 'login-host',
-                key: org.id,
-                desired: { host },
-            },
-            step: {
-                description: sharedInstanceHost
-                    ? `set ${org.slug}'s login host to ${host}: its domain host (auth.${org.domain}) is the platform's own shared ZITADEL instance host, so it stays on oikos.host`
-                    : `set ${org.slug}'s login host to ${host}`,
-                destroys: false,
-                migrates: false,
-            },
-        },
-        blocked: null,
-    };
+    return null;
 }
 /** #230: restated from `executor.ts`'s `MAIL_ROLE_MAILBOXES_SCOPE_KEY`, same rule: comma-joined local parts already created. */
 const MAIL_ROLE_MAILBOXES_SCOPE_KEY = 'mail_role_mailboxes';
@@ -1594,6 +1635,13 @@ function planAgora(org, byKey, claimed, recordedIds, reading) {
     if (liveEnv.AGORA_CONFIG === undefined && !drift.includes('AGORA_CONFIG')) {
         drift.push('AGORA_CONFIG');
     }
+    // #506: an app Coolify never got `ports_exposes` on (or got the wrong one)
+    // answers 502 behind the tunnel even though its env already matches --
+    // exactly the Company Included incident this issue names. Compared
+    // separately from `drift` above: it is a Coolify application setting, not
+    // an env var, and `providers-readers.ts`'s `withAgoraEnvConfig` reads it
+    // from `getApplication`, never `listEnvs`.
+    const portDrift = live.config.ports_exposes !== AGORA_APP_PORTS_EXPOSES;
     // #442: `drift` alone, once this step has ever run, is comparing `env`
     // against Coolify's own env store -- which the executor's `bulkUpsertEnvs`
     // leaves matching `env` the moment the write succeeds, restarted or not.
@@ -1604,14 +1652,18 @@ function planAgora(org, byKey, claimed, recordedIds, reading) {
     // actually serving this exact `env`; while it disagrees, the step stays
     // planned no matter what Coolify's env store already shows.
     const activated = recordedIds[AGORA_ACTIVATED_ENV_SCOPE_KEY] === agoraEnvRevision(env);
-    if (drift.length === 0 && activated)
+    if (drift.length === 0 && activated && !portDrift)
         return { step: null, blocked: null };
+    const reasons = [
+        ...(drift.length > 0 ? [`${drift.join(', ')} missing or different`] : []),
+        ...(portDrift ? ["ports_exposes wrong -- Traefik can't reach it"] : []),
+    ];
     return {
         step: {
             action,
             step: {
-                description: drift.length > 0
-                    ? `update ${org.slug}'s Agora config (${drift.join(', ')} missing or different)`
+                description: reasons.length > 0
+                    ? `update ${org.slug}'s Agora config (${reasons.join('; ')})`
                     : `activate ${org.slug}'s Agora config -- written but not yet confirmed restarted`,
                 destroys: false,
                 migrates: false,
@@ -1735,13 +1787,13 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
  * park-not-delete rule (#7 corrections 1) -- turning it off never deletes
  * the org's own app, database or tunnel configuration, it parks it.
  */
-function planHostingToggle(system, kind, desiredEnabled, org, byKey, claimed, describeProvision, describePark, stepKey = org.id) {
+function planHostingToggle(system, kind, desiredEnabled, org, byKey, claimed, describeProvision, describePark, stepKey = org.id, isOn = (live) => live.config.enabled !== false) {
     const key = resourceKey(system, kind, stepKey);
     const live = byKey.get(key);
     // A live resource is on unless it says it is parked. Providers' own
     // configs carry no `enabled` field at all, so only a park step's
     // explicit `enabled: false` reads as off.
-    const liveEnabled = live !== undefined && live.config.enabled !== false;
+    const liveEnabled = live !== undefined && isOn(live);
     if (!desiredEnabled) {
         // Nothing declared and nothing live: there is nothing to park.
         if (!live)
@@ -2192,7 +2244,18 @@ function planTunnel(org, byKey, claimed, recordedIds) {
         (org.site.enabled && Boolean(org.domain)) ||
         (org.calls.enabled && org.calls.usesDomain && Boolean(org.domain)) ||
         Boolean(org.domain);
-    const toggled = planHostingToggle('cloudflare', 'tunnel', desired, org, byKey, claimed, () => `provision a Cloudflare tunnel for ${org.slug}'s app`, () => `park ${org.slug}'s Cloudflare tunnel (configuration is retained, not deleted -- #7 corrections 1)`);
+    const toggled = planHostingToggle('cloudflare', 'tunnel', desired, org, byKey, claimed, () => `provision a Cloudflare tunnel for ${org.slug}'s app`, () => `park ${org.slug}'s Cloudflare tunnel (configuration is retained, not deleted -- #7 corrections 1)`, org.id, 
+    // Cloudflare's status, read against what is declared: a park cannot change
+    // it, so judging on/off by status alone would never let the plan empty.
+    // Wanted on: only `down` needs a repair (`inactive` is a fresh tunnel
+    // whose connector has not dialled in yet). Wanted off: only a connected
+    // tunnel needs parking; `inactive` and `down` are already parked.
+    (live) => {
+        const status = live.config.status;
+        if (typeof status !== 'string')
+            return live.config.enabled !== false;
+        return desired ? status !== 'down' : status === 'healthy' || status === 'degraded';
+    });
     if (toggled || !desired)
         return toggled;
     // A live, enabled tunnel re-plans the same step again when either:
@@ -2214,10 +2277,10 @@ function planTunnel(org, byKey, claimed, recordedIds) {
     // differ from the names now declared. An org that never recorded a list
     // has nothing to compare, so only the domain check above applies to it.
     const published = recordedIds[CLOUDFLARE_TUNNEL_DNS_HOSTNAMES_SCOPE_KEY];
-    const namesChanged = published !== undefined &&
+    const edgeChanged = published !== undefined &&
         org.domain !== null &&
         sortedNames(published.split(',')) !== sortedNames(tunnelDnsHostnames(org, org.domain));
-    const dnsStale = recordedIds[CLOUDFLARE_TUNNEL_DNS_DOMAIN_SCOPE_KEY] !== org.domain || namesChanged;
+    const dnsStale = recordedIds[CLOUDFLARE_TUNNEL_DNS_DOMAIN_SCOPE_KEY] !== org.domain || edgeChanged;
     if (!connectorMissing && !dnsStale)
         return null;
     return {

package/dist/plan/entry-edge-key.d.ts

@@ -0,0 +1,79 @@
+import type { DeclaredOrg, HostingEntry } from '../org.js';
+import type { DraftStep } from './diff.js';
+import type { OrgPlatformReadiness } from './platform-org.js';
+/**
+ * F7 (#317): one edge key per entry with `uses.edge`, minted directly
+ * below the org with the edge service (`EdgePort.mintKey({
+ * organisationId, ... })` -- no org-level root key the way files/ai have
+ * one, since the edge service takes the org id itself). `EDGE_URL` and
+ * `EDGE_API_KEY` go to the entry's env and nowhere else. A edge key has no
+ * declared renewal window in the issue, so unlike `planEntryAiKeys`/
+ * `planFilesKeys` this mints once and never renews.
+ *
+ * `EDGE_*` is written in this step, after the app's own `coolify:app`
+ * create (which never knows the key yet), so the app's first boot has
+ * neither and its first deploy restarts once this step's env write lands --
+ * the same one-extra-restart shape `planEntryAiKeys`'s `AI_*`/
+ * `planFilesKeys`'s `FILES_*` already have, not a names-specific gap.
+ *
+ * A domain change after mint is not detected (#317 re-review): the key is
+ * bound to the domain passed at mint time, but nothing here records that
+ * domain to compare against a later `org.domain`, so an org that changes
+ * domains keeps a edge key still bound to the old one. Not built --
+ * resolving it needs a manual revoke-and-re-mint (drop `uses.edge`, apply,
+ * re-add it) until this is.
+ */
+export declare const entryEdgeUndeliveredScopeKey: (entryKey: string) => string;
+/** The id of a key that was live when its entry stopped declaring `uses.edge`, once handled. */
+export declare const entryEdgeRetiredScopeKey: (entryKey: string) => string;
+export declare const ENTRY_EDGE_KEY_DELIVERY_ATTEMPTS = 3;
+/** How long an entry's edge key lives. The issue names no renewal window, so this mints once and never renews. */
+export declare const EDGE_ENTRY_KEY_DAYS = 365;
+/** The ISO time a delivered key's mint succeeded -- the only trace of its age, since there is no renewal to track against. */
+export declare const entryEdgeMintedAtScopeKey: (entryKey: string) => string;
+/** A key with fewer days left than this is surfaced as a blocked warning row (#317 review): still live, but nothing here renews it. */
+export declare const EDGE_ENTRY_KEY_WARN_WINDOW_DAYS = 30;
+/** The reserved labels last sent to the edge service, as that sorted list's own JSON. */
+export declare const EDGE_RESERVED_LABELS_APPLIED_SCOPE_KEY = "edge_reserved_labels_applied";
+export declare const entryEdgeKeyName: (org: DeclaredOrg, entry: HostingEntry) => string;
+/**
+ * Every label under `org.domain` that foundry provisions or the platform
+ * uses, so edge never lets a company claim one: the hostnames foundry routes
+ * (`tunnelIngressHostnames`: entries, site, cms, calls, Agora, Boule, share),
+ * the names it locks (`lockedHostnames`: also the sign-in host and the
+ * platform's service hostnames), each entry's own labels, the mail labels
+ * and `www`. The entry's `*` is the space users claim in, so it reserves
+ * nothing, and neither does the bare domain.
+ *
+ * An org without a domain has no hostnames edge sees (`uses.edge` needs a
+ * domain), so it reserves `www` only.
+ */
+export declare function edgeReservedLabels(org: DeclaredOrg, platformHostnames?: readonly string[]): string[];
+type Blocked = Array<{
+    description: string;
+    key: string;
+}>;
+/**
+ * One step per entry whose edge key is missing, plus one retire step per
+ * entry whose `uses.edge` was removed but still has a recorded key.
+ * Blocked, not planned (rule 2), while the platform has no edge service
+ * wired, the entry's app is not recorded, or a previous mint's delivery
+ * failed.
+ */
+export declare function planEntryEdgeKeys(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], readiness: OrgPlatformReadiness, now?: number): {
+    steps: DraftStep[];
+    blocked: Blocked;
+};
+/**
+ * The reserved-labels step: resent whenever the org's own label set
+ * (`edgeReservedLabels`) differs from what was last sent. While the org
+ * uses edge at all (at least one entry with `uses.edge`) that set is
+ * `edgeReservedLabels(org)`; once the last entry drops `uses.edge`, this
+ * clears whatever was last sent (an empty list) rather than leaving it
+ * stuck in names forever -- a one-time step, same as any other change.
+ */
+export declare function planEdgeReservedLabels(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, readiness: OrgPlatformReadiness, platformHostnames?: readonly string[]): {
+    step: DraftStep | null;
+    blocked: Blocked;
+};
+export {};