@wtfalch/foundry 0.16.16 → 0.17.1

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

@@ -0,0 +1,114 @@
+import type { DeclaredOrg, EdgeConfig, HostingEntry } from '../org.js';
+import type { DraftStep } from './diff.js';
+/**
+ * F8 (#318): one plain Cloudflare Worker per hosting entry that declares
+ * `edge`, deployed from a built artifact that entry's own repo publishes
+ * (estate DECISIONS.md, 2026-10-04: foundry fetches and verifies it, never
+ * checks it out or bundles it). Unlike `planEntryAiKeys`/`planFilesKeys`,
+ * there is no renewal window -- a Worker script has no expiry -- so a step
+ * is planned again only while the entry's own declared config (`route`,
+ * `bindings` or, crucially, `artifactSha256`) differs from what was last
+ * applied (recorded as that config's JSON, `edgeAppliedScopeKey`):
+ * `artifactSha256` is itself the declared signal that the built bytes
+ * changed, so a rebuild under an unchanged URL still redeploys as soon as
+ * the entry declares the new digest. "Blocked, not failing" (CLAUDE.md): a
+ * host whose executor carries no `WorkersPort` reports every entry's step
+ * (apply or retire) as blocked, not planned to a step that would throw.
+ */
+export declare const entryEdgeAppliedScopeKey: (entryKey: string) => string;
+export declare const entryEdgeRouteIdScopeKey: (entryKey: string) => string;
+/** The route pattern the recorded route id above was created for -- read to find and delete the *old* route when the declared route pattern changes. */
+export declare const entryEdgeRoutePatternScopeKey: (entryKey: string) => string;
+/**
+ * The script name retired, once a retire step completes. `runSteps` only
+ * ever writes a step's main recorded id from a *truthy* `resourceId`
+ * (`plan-apply.ts`), and retire returns none -- so the main
+ * `cloudflare:worker:<key>` id is never cleared by returning from the step,
+ * and without this marker the "gone" scan below would plan the same retire
+ * forever. Compared against that still-live id, the same convergence
+ * `entryAiRetiredScopeKey`/`entryFilesRetiredScopeKey`/
+ * `entryNamesRetiredScopeKey` already give their own entry keys.
+ */
+export declare const entryEdgeRetiredScopeKey: (entryKey: string) => string;
+/** The script name being uploaded, recorded (and persisted) *before* the upload call -- so a crash mid-upload or a failed route create still leaves a trail to the script rather than orphaning it, and a retry reads the script as foundry's own instead of tripping the `scriptExists` overwrite guard. Cleared once the step records success. */
+export declare const entryEdgeUploadedScopeKey: (entryKey: string) => string;
+/** The zone the recorded route id lives in, as {@link EdgeRouteZone} JSON -- so retire and destroy delete it on *that* zone even after `org.domain` changes or goes null. */
+export declare const entryEdgeRouteZoneScopeKey: (entryKey: string) => string;
+/** A route about to be created, as {@link EdgeRoutePending} JSON, recorded and persisted before `createRoute` -- so a crash or failed persist right after Cloudflare creates it still leaves retire and destroy something to find it by (`findRoute`). Cleared once the route id is recorded. */
+export declare const entryEdgeRoutePendingScopeKey: (entryKey: string) => string;
+export interface EdgeRouteZone {
+    id: string;
+    apex: string;
+}
+export interface EdgeRoutePending extends EdgeRouteZone {
+    pattern: string;
+    script: string;
+}
+/** The per-entry scope keys that mark something deployed or half-deployed, or that a retire already handled it -- cleared together once org destroy has torn the Worker down (#318 re-review: the retired marker was left out, so it stayed recorded as a stale leftover after the org itself was gone). */
+export declare const edgeWorkerTraceScopeKeys: (entryKey: string) => string[];
+/**
+ * Every entry key of `orgId` with something foundry deployed still live,
+ * mapped to the script name recorded for it (`''` if only a route trace is
+ * left). Read by the planner's gone-scan and by org destroy alike, so the two
+ * agree on what is live: the main `cloudflare:worker:<org>:<entry>` id
+ * (unless the retired marker matches it), or any partial-deploy trace -- the
+ * uploaded name, a recorded route id, or a pending route -- regardless of
+ * the retired marker, since an apply clears that marker before it leaves any
+ * of these (#318 re-review).
+ */
+export declare function liveEdgeWorkers(orgId: string, recordedIds: Readonly<Record<string, string>>): Map<string, string>;
+/** The first 8 hex characters of org.id's own sha256 -- see {@link edgeWorkerName}'s doc comment. */
+export declare const EDGE_WORKER_ORG_HASH_LENGTH = 8;
+/** Cloudflare's own limit on a Worker script name. */
+export declare const EDGE_WORKER_NAME_MAX_LENGTH = 63;
+/**
+ * `${8-hex-char hash of org.id}-${entry.key}-edge`, not `${org.slug}-...`
+ * (#318 re-review): a slug and an entry key both allow hyphens, so org
+ * `a-b` entry `c` and org `a` entry `b-c` produced the identical name
+ * `a-b-c-edge` on the one shared Cloudflare account -- `scriptExists` only
+ * caught the second of the two to apply, and two concurrent applies could
+ * both pass it. `org.id` is a UUID with no ambiguity of its own, but using
+ * it in full would make the fixed part of the name longer than most of the
+ * 63-character budget this port's `EDGE_WORKER_NAME_MAX_LENGTH` gives it,
+ * so only a short hash of it is used -- `validateEntryEdge` (`org.ts`)
+ * checks the resulting name never exceeds that limit.
+ */
+export declare const edgeWorkerName: (org: DeclaredOrg, entry: HostingEntry) => string;
+/**
+ * Foundry's own fixed compatibility date for every Worker it deploys -- not
+ * a per-entry declared value, so it is not part of {@link EdgeWorkerWant}
+ * and never triggers a re-plan on its own; bumping it is a foundry release,
+ * like {@link RATE_LIMIT_FREE_PLAN_PERIOD_SECONDS} is a fixed Cloudflare
+ * Free plan value rather than something an org declares.
+ */
+export declare const EDGE_WORKER_COMPATIBILITY_DATE = "2026-09-12";
+export type EdgeWorkerMode = 'apply' | 'retire';
+export interface EdgeWorkerWant {
+    name: string;
+    artifactUrl: string;
+    artifactSha256: string;
+    route: string;
+    bindings: EdgeConfig['bindings'];
+}
+export declare function wantedEdgeWorker(org: DeclaredOrg, entry: HostingEntry): EdgeWorkerWant;
+type Blocked = Array<{
+    description: string;
+    key: string;
+}>;
+/**
+ * One step per entry whose `edge` config is new or changed, plus one retire
+ * step per entry whose Worker is recorded but no longer declared -- either
+ * because the entry dropped `edge` or because the entry itself is gone, the
+ * same "gone" scan `planEntryAiKeys`/`planFilesKeys`/`planEntryNamesKeys`
+ * run over their own recorded keys, so removing a whole entry still cleans
+ * up its Worker. `workersAvailable` is the host's own
+ * `FoundryPlanApplyOptions.edgeWorkers` (mirrors `jobsAvailable`): without
+ * it, every entry's step -- apply or retire -- is reported blocked rather
+ * than planned to fail at apply. The caller (`diff.ts`) gates the *apply*
+ * steps further, on an active zone, the same way it gates `planRateLimit`.
+ */
+export declare function planEdgeWorkers(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, workersAvailable: boolean): {
+    steps: DraftStep[];
+    blocked: Blocked;
+};
+export {};

package/dist/plan/edge-worker.js

@@ -0,0 +1,201 @@
+import { createHash } from 'node:crypto';
+import { appStepKey } from './platform-diff.js';
+/**
+ * F8 (#318): one plain Cloudflare Worker per hosting entry that declares
+ * `edge`, deployed from a built artifact that entry's own repo publishes
+ * (estate DECISIONS.md, 2026-10-04: foundry fetches and verifies it, never
+ * checks it out or bundles it). Unlike `planEntryAiKeys`/`planFilesKeys`,
+ * there is no renewal window -- a Worker script has no expiry -- so a step
+ * is planned again only while the entry's own declared config (`route`,
+ * `bindings` or, crucially, `artifactSha256`) differs from what was last
+ * applied (recorded as that config's JSON, `edgeAppliedScopeKey`):
+ * `artifactSha256` is itself the declared signal that the built bytes
+ * changed, so a rebuild under an unchanged URL still redeploys as soon as
+ * the entry declares the new digest. "Blocked, not failing" (CLAUDE.md): a
+ * host whose executor carries no `WorkersPort` reports every entry's step
+ * (apply or retire) as blocked, not planned to a step that would throw.
+ */
+export const entryEdgeAppliedScopeKey = (entryKey) => `edge_worker_applied_${entryKey}`;
+export const entryEdgeRouteIdScopeKey = (entryKey) => `edge_worker_route_id_${entryKey}`;
+/** The route pattern the recorded route id above was created for -- read to find and delete the *old* route when the declared route pattern changes. */
+export const entryEdgeRoutePatternScopeKey = (entryKey) => `edge_worker_route_pattern_${entryKey}`;
+/**
+ * The script name retired, once a retire step completes. `runSteps` only
+ * ever writes a step's main recorded id from a *truthy* `resourceId`
+ * (`plan-apply.ts`), and retire returns none -- so the main
+ * `cloudflare:worker:<key>` id is never cleared by returning from the step,
+ * and without this marker the "gone" scan below would plan the same retire
+ * forever. Compared against that still-live id, the same convergence
+ * `entryAiRetiredScopeKey`/`entryFilesRetiredScopeKey`/
+ * `entryNamesRetiredScopeKey` already give their own entry keys.
+ */
+export const entryEdgeRetiredScopeKey = (entryKey) => `edge_worker_retired_${entryKey}`;
+/** The script name being uploaded, recorded (and persisted) *before* the upload call -- so a crash mid-upload or a failed route create still leaves a trail to the script rather than orphaning it, and a retry reads the script as foundry's own instead of tripping the `scriptExists` overwrite guard. Cleared once the step records success. */
+export const entryEdgeUploadedScopeKey = (entryKey) => `edge_worker_uploaded_${entryKey}`;
+/** The zone the recorded route id lives in, as {@link EdgeRouteZone} JSON -- so retire and destroy delete it on *that* zone even after `org.domain` changes or goes null. */
+export const entryEdgeRouteZoneScopeKey = (entryKey) => `edge_worker_route_zone_${entryKey}`;
+/** A route about to be created, as {@link EdgeRoutePending} JSON, recorded and persisted before `createRoute` -- so a crash or failed persist right after Cloudflare creates it still leaves retire and destroy something to find it by (`findRoute`). Cleared once the route id is recorded. */
+export const entryEdgeRoutePendingScopeKey = (entryKey) => `edge_worker_route_pending_${entryKey}`;
+/** The per-entry scope keys that mark something deployed or half-deployed, or that a retire already handled it -- cleared together once org destroy has torn the Worker down (#318 re-review: the retired marker was left out, so it stayed recorded as a stale leftover after the org itself was gone). */
+export const edgeWorkerTraceScopeKeys = (entryKey) => [
+    entryEdgeUploadedScopeKey(entryKey),
+    entryEdgeRouteIdScopeKey(entryKey),
+    entryEdgeRouteZoneScopeKey(entryKey),
+    entryEdgeRoutePatternScopeKey(entryKey),
+    entryEdgeRoutePendingScopeKey(entryKey),
+    entryEdgeRetiredScopeKey(entryKey),
+];
+/**
+ * Every entry key of `orgId` with something foundry deployed still live,
+ * mapped to the script name recorded for it (`''` if only a route trace is
+ * left). Read by the planner's gone-scan and by org destroy alike, so the two
+ * agree on what is live: the main `cloudflare:worker:<org>:<entry>` id
+ * (unless the retired marker matches it), or any partial-deploy trace -- the
+ * uploaded name, a recorded route id, or a pending route -- regardless of
+ * the retired marker, since an apply clears that marker before it leaves any
+ * of these (#318 re-review).
+ */
+export function liveEdgeWorkers(orgId, recordedIds) {
+    const mainPrefix = `cloudflare:worker:${orgId}:`;
+    const tracePrefixes = [
+        mainPrefix,
+        'edge_worker_uploaded_',
+        'edge_worker_route_id_',
+        'edge_worker_route_pending_',
+    ];
+    const entryKeys = new Set();
+    for (const [name, id] of Object.entries(recordedIds)) {
+        if (!id)
+            continue;
+        const prefix = tracePrefixes.find((p) => name.startsWith(p));
+        if (prefix)
+            entryKeys.add(name.slice(prefix.length));
+    }
+    const live = new Map();
+    for (const entryKey of entryKeys) {
+        const mainId = recordedIds[`${mainPrefix}${entryKey}`] ?? '';
+        const uploaded = recordedIds[entryEdgeUploadedScopeKey(entryKey)] ?? '';
+        const partial = uploaded ||
+            recordedIds[entryEdgeRouteIdScopeKey(entryKey)] ||
+            recordedIds[entryEdgeRoutePendingScopeKey(entryKey)];
+        const retired = mainId !== '' && recordedIds[entryEdgeRetiredScopeKey(entryKey)] === mainId;
+        if (!partial && (!mainId || retired))
+            continue;
+        live.set(entryKey, mainId || uploaded);
+    }
+    return live;
+}
+/** The first 8 hex characters of org.id's own sha256 -- see {@link edgeWorkerName}'s doc comment. */
+export const EDGE_WORKER_ORG_HASH_LENGTH = 8;
+/** Cloudflare's own limit on a Worker script name. */
+export const EDGE_WORKER_NAME_MAX_LENGTH = 63;
+/**
+ * `${8-hex-char hash of org.id}-${entry.key}-edge`, not `${org.slug}-...`
+ * (#318 re-review): a slug and an entry key both allow hyphens, so org
+ * `a-b` entry `c` and org `a` entry `b-c` produced the identical name
+ * `a-b-c-edge` on the one shared Cloudflare account -- `scriptExists` only
+ * caught the second of the two to apply, and two concurrent applies could
+ * both pass it. `org.id` is a UUID with no ambiguity of its own, but using
+ * it in full would make the fixed part of the name longer than most of the
+ * 63-character budget this port's `EDGE_WORKER_NAME_MAX_LENGTH` gives it,
+ * so only a short hash of it is used -- `validateEntryEdge` (`org.ts`)
+ * checks the resulting name never exceeds that limit.
+ */
+export const edgeWorkerName = (org, entry) => `${createHash('sha256').update(org.id).digest('hex').slice(0, EDGE_WORKER_ORG_HASH_LENGTH)}-${entry.key}-edge`;
+/**
+ * Foundry's own fixed compatibility date for every Worker it deploys -- not
+ * a per-entry declared value, so it is not part of {@link EdgeWorkerWant}
+ * and never triggers a re-plan on its own; bumping it is a foundry release,
+ * like {@link RATE_LIMIT_FREE_PLAN_PERIOD_SECONDS} is a fixed Cloudflare
+ * Free plan value rather than something an org declares.
+ */
+export const EDGE_WORKER_COMPATIBILITY_DATE = '2026-09-12';
+export function wantedEdgeWorker(org, entry) {
+    const edge = entry.edge;
+    return {
+        name: edgeWorkerName(org, entry),
+        artifactUrl: edge.artifactUrl,
+        artifactSha256: edge.artifactSha256,
+        route: edge.route,
+        bindings: edge.bindings,
+    };
+}
+/**
+ * One step per entry whose `edge` config is new or changed, plus one retire
+ * step per entry whose Worker is recorded but no longer declared -- either
+ * because the entry dropped `edge` or because the entry itself is gone, the
+ * same "gone" scan `planEntryAiKeys`/`planFilesKeys`/`planEntryNamesKeys`
+ * run over their own recorded keys, so removing a whole entry still cleans
+ * up its Worker. `workersAvailable` is the host's own
+ * `FoundryPlanApplyOptions.edgeWorkers` (mirrors `jobsAvailable`): without
+ * it, every entry's step -- apply or retire -- is reported blocked rather
+ * than planned to fail at apply. The caller (`diff.ts`) gates the *apply*
+ * steps further, on an active zone, the same way it gates `planRateLimit`.
+ */
+export function planEdgeWorkers(org, recordedIds, workersAvailable) {
+    const steps = [];
+    const blocked = [];
+    // Hosting off declares no Worker at all: the gone-scan below still runs,
+    // so a Worker deployed while hosting was on is retired rather than left
+    // live forever (#318 re-review). Only planning a *new* deploy is skipped.
+    const declared = new Set(org.hosting.enabled ? org.hosting.entries.filter((e) => e.edge).map((e) => e.key) : []);
+    const mainPrefix = `cloudflare:worker:${org.id}:`;
+    // Every entryKey with a live, undeclared trace (`liveEdgeWorkers`): the
+    // main id or any partial-deploy marker, so a deploy that failed after
+    // upload or mid-route-create is still found to retire (#318 review).
+    for (const entryKey of liveEdgeWorkers(org.id, recordedIds).keys()) {
+        if (declared.has(entryKey))
+            continue;
+        const stepKey = `${org.id}:${entryKey}`;
+        if (!workersAvailable) {
+            blocked.push({
+                description: `${org.slug}'s ${entryKey} edge Worker is blocked, not planned: the host supplies no WorkersPort`,
+                key: `${mainPrefix}${entryKey}`,
+            });
+            continue;
+        }
+        steps.push({
+            action: { system: 'cloudflare', kind: 'worker', key: stepKey, desired: { mode: 'retire' } },
+            step: {
+                description: `delete ${org.slug}'s ${entryKey} edge Worker and its route: edge is no longer declared`,
+                destroys: true,
+                migrates: false,
+            },
+        });
+    }
+    if (!org.hosting.enabled)
+        return { steps, blocked };
+    for (const entry of org.hosting.entries) {
+        if (!entry.edge)
+            continue;
+        const stepKey = appStepKey(org, entry.key);
+        const key = `cloudflare:worker:${stepKey}`;
+        const at = `${org.slug}'s ${entry.key} edge Worker`;
+        if (!workersAvailable) {
+            blocked.push({
+                description: `${at} is blocked, not planned: the host supplies no WorkersPort`,
+                key,
+            });
+            continue;
+        }
+        const want = wantedEdgeWorker(org, entry);
+        const wantJson = JSON.stringify(want);
+        const applied = recordedIds[entryEdgeAppliedScopeKey(entry.key)];
+        if (applied === wantJson)
+            continue; // Rerun: nothing changed, down to the built artifact's own digest.
+        steps.push({
+            action: {
+                system: 'cloudflare',
+                kind: 'worker',
+                key: stepKey,
+                desired: { mode: 'apply', compatibilityDate: EDGE_WORKER_COMPATIBILITY_DATE, ...want },
+            },
+            step: {
+                description: `${applied ? 'update' : 'deploy'} ${at} on ${entry.edge.route}`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, blocked };
+}

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

@@ -1,5 +1,5 @@
 import { type DeclaredOrg, type HostingEntry } from '../org.js';
-import type { PlannedStep } from './diff.js';
+import type { DraftStep } from './diff.js';
 import type { OrgPlatformReadiness } from './platform-org.js';
 /**
  * F6a: one ai key per entry with `uses.ai`, minted below the org's own ai key
@@ -49,8 +49,8 @@ export type EntryAiMode = 'mint' | 'renew' | 'settings' | 'finish' | 'retire';
  * entry's app or the ai address is not recorded, or after a mint whose
  * delivery failed: a second mint would leave two live keys.
  */
-export declare function planEntryAiKeys(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly PlannedStep[], readiness: OrgPlatformReadiness, now: number): {
-    steps: PlannedStep[];
+export declare function planEntryAiKeys(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], readiness: OrgPlatformReadiness, now: number): {
+    steps: DraftStep[];
     blocked: Array<{
         description: string;
         key: string;

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

@@ -1,5 +1,5 @@
 import { type DeclaredOrg, type HostingEntry } from '../org.js';
-import type { PlannedStep } from './diff.js';
+import type { DraftStep } from './diff.js';
 import type { OrgPlatformReadiness } from './platform-org.js';
 /**
  * F6b: the org's own files key, minted below the files organisation's
@@ -77,8 +77,8 @@ type Blocked = Array<{
  * it by its own `renew` step, and only then does `revoke-previous` revoke the
  * old org key, which revokes everything still below it.
  */
-export declare function planFilesKeys(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly PlannedStep[], readiness: OrgPlatformReadiness, now: number): {
-    steps: PlannedStep[];
+export declare function planFilesKeys(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], readiness: OrgPlatformReadiness, now: number): {
+    steps: DraftStep[];
     blocked: Blocked;
 };
 export {};

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

@@ -0,0 +1,73 @@
+import type { DeclaredOrg, HostingEntry } from '../org.js';
+import type { DraftStep } from './diff.js';
+import type { OrgPlatformReadiness } from './platform-org.js';
+/**
+ * F7 (#317): one names key per entry with `uses.names`, minted directly
+ * below the org with the names service (`NamesPort.mintKey({
+ * organisationId, ... })` -- no org-level root key the way files/ai have
+ * one, since the names service takes the org id itself). `NAMES_URL` and
+ * `NAMES_API_KEY` go to the entry's env and nowhere else. A names key has no
+ * declared renewal window in the issue, so unlike `planEntryAiKeys`/
+ * `planFilesKeys` this mints once and never renews.
+ *
+ * `NAMES_*` 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 names key still bound to the old one. Not built --
+ * resolving it needs a manual revoke-and-re-mint (drop `uses.names`, apply,
+ * re-add it) until this is.
+ */
+export declare const entryNamesUndeliveredScopeKey: (entryKey: string) => string;
+/** The id of a key that was live when its entry stopped declaring `uses.names`, once handled. */
+export declare const entryNamesRetiredScopeKey: (entryKey: string) => string;
+export declare const ENTRY_NAMES_KEY_DELIVERY_ATTEMPTS = 3;
+/** How long an entry's names key lives. The issue names no renewal window, so this mints once and never renews. */
+export declare const NAMES_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 entryNamesMintedAtScopeKey: (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 NAMES_ENTRY_KEY_WARN_WINDOW_DAYS = 30;
+/** The reserved labels last sent to the names service, as that sorted list's own JSON. */
+export declare const NAMES_RESERVED_LABELS_APPLIED_SCOPE_KEY = "names_reserved_labels_applied";
+export declare const entryNamesKeyName: (org: DeclaredOrg, entry: HostingEntry) => string;
+/**
+ * Every label a declared entry serves (`@`/`*` reserve nothing of their own:
+ * the bare domain and the wildcard are not names a customer could claim
+ * under names anyway), plus `www`, which `setReservedLabels`'s own doc
+ * comment in `executor.ts` explains is reserved unconditionally.
+ */
+export declare function namesReservedLabels(org: DeclaredOrg): string[];
+type Blocked = Array<{
+    description: string;
+    key: string;
+}>;
+/**
+ * One step per entry whose names key is missing, plus one retire step per
+ * entry whose `uses.names` was removed but still has a recorded key.
+ * Blocked, not planned (rule 2), while the platform has no names service
+ * wired, the entry's app is not recorded, or a previous mint's delivery
+ * failed.
+ */
+export declare function planEntryNamesKeys(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
+ * (`namesReservedLabels`) differs from what was last sent. While the org
+ * uses names at all (at least one entry with `uses.names`) that set is
+ * `namesReservedLabels(org)`; once the last entry drops `uses.names`, 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 planNamesReservedLabels(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, readiness: OrgPlatformReadiness): {
+    step: DraftStep | null;
+    blocked: Blocked;
+};
+export {};

package/dist/plan/entry-names-key.js

@@ -0,0 +1,236 @@
+import { appStepKey } from './platform-diff.js';
+/**
+ * F7 (#317): one names key per entry with `uses.names`, minted directly
+ * below the org with the names service (`NamesPort.mintKey({
+ * organisationId, ... })` -- no org-level root key the way files/ai have
+ * one, since the names service takes the org id itself). `NAMES_URL` and
+ * `NAMES_API_KEY` go to the entry's env and nowhere else. A names key has no
+ * declared renewal window in the issue, so unlike `planEntryAiKeys`/
+ * `planFilesKeys` this mints once and never renews.
+ *
+ * `NAMES_*` 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 names key still bound to the old one. Not built --
+ * resolving it needs a manual revoke-and-re-mint (drop `uses.names`, apply,
+ * re-add it) until this is.
+ */
+export const entryNamesUndeliveredScopeKey = (entryKey) => `names_key_undelivered_${entryKey}`;
+/** The id of a key that was live when its entry stopped declaring `uses.names`, once handled. */
+export const entryNamesRetiredScopeKey = (entryKey) => `names_key_retired_${entryKey}`;
+export const ENTRY_NAMES_KEY_DELIVERY_ATTEMPTS = 3;
+/** How long an entry's names key lives. The issue names no renewal window, so this mints once and never renews. */
+export const NAMES_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 const entryNamesMintedAtScopeKey = (entryKey) => `names_key_minted_at_${entryKey}`;
+/** 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 const NAMES_ENTRY_KEY_WARN_WINDOW_DAYS = 30;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** The reserved labels last sent to the names service, as that sorted list's own JSON. */
+export const NAMES_RESERVED_LABELS_APPLIED_SCOPE_KEY = 'names_reserved_labels_applied';
+export const entryNamesKeyName = (org, entry) => `${org.slug}-${entry.key}-names`;
+/**
+ * Every label a declared entry serves (`@`/`*` reserve nothing of their own:
+ * the bare domain and the wildcard are not names a customer could claim
+ * under names anyway), plus `www`, which `setReservedLabels`'s own doc
+ * comment in `executor.ts` explains is reserved unconditionally.
+ */
+export function namesReservedLabels(org) {
+    const labels = new Set(['www']);
+    for (const entry of org.hosting.entries) {
+        for (const name of entry.hostnames) {
+            if (name !== '@' && name !== '*')
+                labels.add(name);
+        }
+    }
+    return [...labels].sort();
+}
+/**
+ * One step per entry whose names key is missing, plus one retire step per
+ * entry whose `uses.names` was removed but still has a recorded key.
+ * Blocked, not planned (rule 2), while the platform has no names service
+ * wired, the entry's app is not recorded, or a previous mint's delivery
+ * failed.
+ */
+export function planEntryNamesKeys(org, recordedIds, plannedSteps, readiness, now = Date.now()) {
+    const steps = [];
+    const blocked = [];
+    const planned = (system, kind, k) => plannedSteps.some((p) => p.action.system === system && p.action.kind === kind && p.action.key === k);
+    // A key whose entry lost `uses.names`, or whose entry is gone entirely --
+    // either way it is no longer in `declared`, the same "gone" scan
+    // `planEntryAiKeys`/`planFilesKeys` run over their own recorded keys.
+    // Gated on `namesReady`: without a port there is nothing that could revoke
+    // it, so it is reported blocked, not planned to a step that would throw.
+    //
+    // Scanned from both the main recorded id and the undelivered marker: a
+    // key minted but never delivered never gets a main id (the mint step
+    // throws before `runSteps` sees a `resourceId`), so scanning the main
+    // prefix alone would never find it to revoke once its entry is gone
+    // (#317 review).
+    const declared = new Set(org.hosting.entries.filter((e) => e.uses?.names).map((e) => e.key));
+    const mainPrefix = `names:key:${org.id}:`;
+    const undeliveredPrefix = 'names_key_undelivered_';
+    const goneEntryKeys = new Set();
+    for (const [name, id] of Object.entries(recordedIds)) {
+        if (!id)
+            continue;
+        let entryKey;
+        if (name.startsWith(mainPrefix))
+            entryKey = name.slice(mainPrefix.length);
+        else if (name.startsWith(undeliveredPrefix))
+            entryKey = name.slice(undeliveredPrefix.length);
+        if (entryKey === undefined || declared.has(entryKey))
+            continue;
+        // Only the main id is subject to the retired-marker convergence check
+        // -- it's the one `runSteps` never clears on its own. An undelivered
+        // id is cleared directly on retire (no marker needed), so its mere
+        // presence here means it still needs revoking, regardless of what a
+        // stale, already-retired main id says: a key minted after a retire
+        // (mint, three failed deliveries, undeclare again) must not hide
+        // behind id A's retired marker just because id A's main-id field is
+        // still truthy (#317 re-review).
+        if (name.startsWith(mainPrefix) && recordedIds[entryNamesRetiredScopeKey(entryKey)] === id) {
+            continue;
+        }
+        goneEntryKeys.add(entryKey);
+    }
+    for (const entryKey of goneEntryKeys) {
+        if (!readiness.namesReady) {
+            blocked.push({
+                description: `${org.slug}'s ${entryKey} names key is blocked, not planned: the host supplies no names service, or the platform has not enabled it`,
+                key: `${mainPrefix}${entryKey}`,
+            });
+            continue;
+        }
+        steps.push({
+            action: {
+                system: 'names',
+                kind: 'key',
+                key: `${org.id}:${entryKey}`,
+                desired: { mode: 'retire' },
+            },
+            step: {
+                description: `revoke ${org.slug}'s ${entryKey} names key: the entry no longer declares uses.names`,
+                destroys: true,
+                migrates: false,
+            },
+        });
+    }
+    for (const entry of org.hosting.entries) {
+        if (!entry.uses?.names)
+            continue;
+        const stepKey = appStepKey(org, entry.key);
+        const key = `names:key:${stepKey}`;
+        const liveKeyId = recordedIds[key] && recordedIds[entryNamesRetiredScopeKey(entry.key)] !== recordedIds[key]
+            ? recordedIds[key]
+            : undefined;
+        if (liveKeyId) {
+            // No renewal: minted once. Still surfaced once it is close to or past
+            // its silent expiry -- there is no step to plan, since nothing here
+            // renews it, but a plan that says nothing about a key about to stop
+            // working is the gap this is for (#317 review). Prefixed `warning:`,
+            // the same convention `planBrokerEntries`'s invalid-AUTH_APPS notice
+            // uses, so a caller reading this list for real blockers (one a human
+            // mint could ever clear) can tell the two apart -- a permanently
+            // "blocked" row past day 335 that no action removes is the problem
+            // this prefix exists to avoid.
+            const mintedAt = recordedIds[entryNamesMintedAtScopeKey(entry.key)];
+            if (mintedAt) {
+                const expiresAt = Date.parse(mintedAt) + NAMES_ENTRY_KEY_DAYS * DAY_MS;
+                const daysLeft = Math.floor((expiresAt - now) / DAY_MS);
+                if (daysLeft < NAMES_ENTRY_KEY_WARN_WINDOW_DAYS) {
+                    blocked.push({
+                        description: `warning: ${org.slug}'s ${entry.key} names key ${daysLeft < 0 ? 'expired' : 'expires'} ${new Date(expiresAt).toISOString().slice(0, 10)} and is never renewed (#317): mint a new key by hand and update the entry's env`,
+                        key,
+                    });
+                }
+            }
+            continue;
+        }
+        const at = `${org.slug}'s ${entry.key} names key`;
+        const block = (why) => blocked.push({ description: `${at} is blocked: ${why}`, key });
+        // An undelivered key from a previous mint is no longer a reason to
+        // block forever: nothing here keeps the secret around to retry
+        // delivering it, so a mint step is still planned, and the executor
+        // itself revokes the stale id first before minting a fresh one (#317
+        // re-review) -- blocking indefinitely, as a prior round did, left the
+        // orphan live for up to 365 days with no recorded trace an operator
+        // could act on beyond this description.
+        if (!readiness.namesReady) {
+            block('the host supplies no names service, or the platform has not enabled it');
+            continue;
+        }
+        if (!recordedIds[`coolify:app:${stepKey}`] && !planned('coolify', 'app', stepKey)) {
+            block("the entry's app is not recorded yet");
+            continue;
+        }
+        steps.push({
+            action: {
+                system: 'names',
+                kind: 'key',
+                key: stepKey,
+                desired: {
+                    mode: 'mint',
+                    name: entryNamesKeyName(org, entry),
+                    namesUrl: readiness.namesUrl,
+                },
+            },
+            step: {
+                description: `mint ${at} below the org, write NAMES_* env, restart the app`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, blocked };
+}
+/**
+ * The reserved-labels step: resent whenever the org's own label set
+ * (`namesReservedLabels`) differs from what was last sent. While the org
+ * uses names at all (at least one entry with `uses.names`) that set is
+ * `namesReservedLabels(org)`; once the last entry drops `uses.names`, 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 function planNamesReservedLabels(org, recordedIds, readiness) {
+    const usesNames = org.hosting.entries.some((e) => e.uses?.names);
+    const applied = recordedIds[NAMES_RESERVED_LABELS_APPLIED_SCOPE_KEY];
+    if (!usesNames && (!applied || applied === '[]')) {
+        return { step: null, blocked: [] };
+    }
+    if (!readiness.namesReady) {
+        return {
+            step: null,
+            blocked: [
+                {
+                    description: `${org.slug}'s reserved labels are blocked: the host supplies no names service, or the platform has not enabled it`,
+                    key: `names:reserved-labels:${org.id}`,
+                },
+            ],
+        };
+    }
+    const labels = usesNames ? namesReservedLabels(org) : [];
+    const wantJson = JSON.stringify(labels);
+    if (applied === wantJson) {
+        return { step: null, blocked: [] };
+    }
+    return {
+        step: {
+            action: { system: 'names', kind: 'reserved-labels', key: org.id, desired: { labels } },
+            step: {
+                description: usesNames
+                    ? `send ${org.slug}'s reserved labels to names: ${labels.join(', ')}`
+                    : `clear ${org.slug}'s reserved labels from names: no entry uses names any more`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: [],
+    };
+}