@wtfalch/foundry 0.17.0 → 0.18.0

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

@@ -0,0 +1,260 @@
+import { tunnelIngressHostnames } from './hostnames.js';
+import { lockedHostnames } from './locked-hostnames.js';
+import { appStepKey } from './platform-diff.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 const entryEdgeUndeliveredScopeKey = (entryKey) => `edge_key_undelivered_${entryKey}`;
+/** The id of a key that was live when its entry stopped declaring `uses.edge`, once handled. */
+export const entryEdgeRetiredScopeKey = (entryKey) => `edge_key_retired_${entryKey}`;
+export 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 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 const entryEdgeMintedAtScopeKey = (entryKey) => `edge_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 EDGE_ENTRY_KEY_WARN_WINDOW_DAYS = 30;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** The reserved labels last sent to the edge service, as that sorted list's own JSON. */
+export const EDGE_RESERVED_LABELS_APPLIED_SCOPE_KEY = 'edge_reserved_labels_applied';
+export const entryEdgeKeyName = (org, entry) => `${org.slug}-${entry.key}-edge`;
+/**
+ * Mail names foundry's mail setup puts on the org's domain. Stalwart's and
+ * Lettermint's own record names (DKIM selectors, return path) come back from
+ * the mail port at apply time, so only the fixed ones are listed here.
+ */
+const MAIL_LABELS = ['mail', 'autoconfig', 'autodiscover', '_dmarc'];
+/**
+ * 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 function edgeReservedLabels(org, platformHostnames = []) {
+    const labels = new Set(['www']);
+    const { domain } = org;
+    if (!domain)
+        return [...labels];
+    for (const label of MAIL_LABELS)
+        labels.add(label);
+    for (const entry of org.hosting.entries) {
+        for (const name of entry.hostnames) {
+            if (name !== '@' && name !== '*')
+                labels.add(name);
+        }
+    }
+    const suffix = `.${domain}`;
+    for (const host of [...tunnelIngressHostnames(org), ...lockedHostnames(org, platformHostnames)]) {
+        if (host.endsWith(suffix) && !host.startsWith('*.'))
+            labels.add(host.slice(0, -suffix.length));
+    }
+    return [...labels].sort();
+}
+/**
+ * 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 function planEntryEdgeKeys(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.edge`, 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 `edgeReady`: 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?.edge).map((e) => e.key));
+    const mainPrefix = `edge:key:${org.id}:`;
+    const undeliveredPrefix = 'edge_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[entryEdgeRetiredScopeKey(entryKey)] === id) {
+            continue;
+        }
+        goneEntryKeys.add(entryKey);
+    }
+    for (const entryKey of goneEntryKeys) {
+        if (!readiness.edgeReady) {
+            blocked.push({
+                description: `${org.slug}'s ${entryKey} edge key is blocked, not planned: the host supplies no edge service, or the platform has not enabled it`,
+                key: `${mainPrefix}${entryKey}`,
+            });
+            continue;
+        }
+        steps.push({
+            action: {
+                system: 'edge',
+                kind: 'key',
+                key: `${org.id}:${entryKey}`,
+                desired: { mode: 'retire' },
+            },
+            step: {
+                description: `revoke ${org.slug}'s ${entryKey} edge key: the entry no longer declares uses.edge`,
+                destroys: true,
+                migrates: false,
+            },
+        });
+    }
+    for (const entry of org.hosting.entries) {
+        if (!entry.uses?.edge)
+            continue;
+        const stepKey = appStepKey(org, entry.key);
+        const key = `edge:key:${stepKey}`;
+        const liveKeyId = recordedIds[key] && recordedIds[entryEdgeRetiredScopeKey(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[entryEdgeMintedAtScopeKey(entry.key)];
+            if (mintedAt) {
+                const expiresAt = Date.parse(mintedAt) + EDGE_ENTRY_KEY_DAYS * DAY_MS;
+                const daysLeft = Math.floor((expiresAt - now) / DAY_MS);
+                if (daysLeft < EDGE_ENTRY_KEY_WARN_WINDOW_DAYS) {
+                    blocked.push({
+                        description: `warning: ${org.slug}'s ${entry.key} edge 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} edge 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.edgeReady) {
+            block('the host supplies no edge 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: 'edge',
+                kind: 'key',
+                key: stepKey,
+                desired: {
+                    mode: 'mint',
+                    name: entryEdgeKeyName(org, entry),
+                    edgeUrl: readiness.edgeUrl,
+                },
+            },
+            step: {
+                description: `mint ${at} below the org, write EDGE_* env, restart the app`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, 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 function planEdgeReservedLabels(org, recordedIds, readiness, platformHostnames = []) {
+    const usesEdge = org.hosting.entries.some((e) => e.uses?.edge);
+    const applied = recordedIds[EDGE_RESERVED_LABELS_APPLIED_SCOPE_KEY];
+    if (!usesEdge && (!applied || applied === '[]')) {
+        return { step: null, blocked: [] };
+    }
+    if (!readiness.edgeReady) {
+        return {
+            step: null,
+            blocked: [
+                {
+                    description: `${org.slug}'s reserved labels are blocked: the host supplies no edge service, or the platform has not enabled it`,
+                    key: `edge:reserved-labels:${org.id}`,
+                },
+            ],
+        };
+    }
+    const labels = usesEdge ? edgeReservedLabels(org, platformHostnames) : [];
+    const wantJson = JSON.stringify(labels);
+    if (applied === wantJson) {
+        return { step: null, blocked: [] };
+    }
+    return {
+        step: {
+            action: { system: 'edge', kind: 'reserved-labels', key: org.id, desired: { labels } },
+            step: {
+                description: usesEdge
+                    ? `send ${org.slug}'s reserved labels to edge: ${labels.join(', ')}`
+                    : `clear ${org.slug}'s reserved labels from edge: no entry uses edge any more`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: [],
+    };
+}

package/dist/plan/executor.d.ts

@@ -2,7 +2,7 @@ import type { OrgMailOptions, OrgMailOrg, OrgMailResult } from '@wtfalch/email/p
 import type { DeclaredOrg, HostingBuildPack } from '../org.js';
 import type { DeclaredOrgStore } from '../store.js';
 import { type BrokerPort } from './broker-entries.js';
-import type { StepAction } from './diff.js';
+import { type StepAction } from './diff.js';
 import { type LoginHostBindingsPort } from './login-host.js';
 import { type MailCopyPort } from './mail-copy.js';
 import type { DestroyTarget, StepDestroyer, StepExecutionContext, StepExecutor } from './plan-apply.js';
@@ -80,11 +80,25 @@ export interface CoolifyPort {
      * `findOrCreateCmsApp`'s own check of whether an app it found by name
      * (rather than just created) needs starting again (#116 review round 3,
      * Finding 1).
+     *
+     * #480: also the rolling-update/health-check settings `updateApplication`
+     * patches on `platform:archon` (`is_consistent_container_name_enabled`,
+     * `custom_network_aliases`, `health_check_enabled`), so a drift check can
+     * tell a setting changed back by hand from one this run already applied.
+     * `is_consistent_container_name_enabled` comes back nested under
+     * `settings`, not at the top level -- confirmed against live Coolify
+     * 4.3.23 (PR #482 review); `custom_network_aliases` and
+     * `health_check_enabled` are both top-level there.
      */
     getApplication(uuid: string): Promise<{
         uuid: string;
         status?: string;
         custom_labels?: string | null;
+        settings?: {
+            is_consistent_container_name_enabled?: boolean;
+        };
+        custom_network_aliases?: string | null;
+        health_check_enabled?: boolean;
     }>;
     createGithubAppApplication(input: {
         project_uuid: string;
@@ -535,6 +549,75 @@ export interface CloudflarePort {
      */
     request<T>(method: string, path: string, body?: unknown, missingOkay?: boolean): Promise<T>;
 }
+/**
+ * One Cloudflare Workers rate limiting binding, Cloudflare's own "simple"
+ * shape -- the metadata part {@link WorkersPort.uploadScript} sends beside
+ * the module (#318).
+ */
+export interface WorkersRateLimitBinding {
+    type: 'ratelimit';
+    name: string;
+    namespace_id: string;
+    simple: {
+        limit: number;
+        period: number;
+    };
+}
+/**
+ * The Cloudflare Workers calls `cloudflareWorker` makes (#318, F8): deploys
+ * a plain Worker from an entry's `worker` declaration and routes it on the
+ * org's own zone. Optional on {@link FoundryStepExecutorPorts} -- a host
+ * with no Workers rights on its Cloudflare token (the issue's own "Human
+ * steps": the token needs them added first) wires none, and the planner
+ * reports every `worker` entry blocked instead of planning a step that would
+ * throw (`FoundryPlanApplyOptions.edgeWorkers`).
+ *
+ * `uploadScript` takes the *declared artifact reference*, not bytes:
+ * fetching `artifactUrl` and verifying it against `artifactSha256` happens
+ * behind this port, never in `cloudflareWorker` or anywhere else in this
+ * package (estate DECISIONS.md, 2026-10-04, "offline.tf Worker setup" --
+ * "Foundry consumes and deploys the artifact through the provider
+ * boundary... No manual build step and no source checkout/bundling in
+ * Foundry"). The real adapter refuses a fetched body whose digest does not
+ * match. The upload itself is a multipart request Cloudflare's API wants (a
+ * `metadata` part naming `main_module` and `bindings`, plus the module) --
+ * `CloudflarePort.request` sends JSON only, so this port names the call
+ * directly rather than forcing it through that escape hatch.
+ *
+ * `deleteRoute`/`deleteScript` are idempotent: deleting a route or script
+ * that is already gone resolves rather than throwing, the same contract
+ * `CloudflarePort.deleteDnsRecord`/`deleteAccessApp` give their own
+ * already-gone case via `isNotFoundError` at the call site -- here it is
+ * the port's own job, since `cloudflareWorker` deletes a route or script by
+ * id/name it already recorded, with nothing live to re-check first.
+ */
+export interface WorkersPort {
+    /** Whether a script named `name` already exists -- checked only on an entry's first-ever apply, so `cloudflareWorker` can refuse to overwrite a script it did not create instead of PUTting over it by its deterministic name. */
+    scriptExists(name: string): Promise<boolean>;
+    uploadScript(input: {
+        name: string;
+        artifactUrl: string;
+        artifactSha256: string;
+        compatibilityDate: string;
+        bindings?: WorkersRateLimitBinding[];
+    }): Promise<void>;
+    /** The script name currently bound to `pattern` in `zoneId`, or `undefined` for no route there. */
+    findRoute(zoneId: string, pattern: string): Promise<{
+        id: string;
+        script?: string;
+    } | undefined>;
+    /**
+     * Creates the route if absent; `cloudflareWorker` only calls this once `findRoute` has confirmed the pattern is foundry's own or unclaimed.
+     * With no `script` it creates Cloudflare's "no Worker" route (`POST /zones/{zone_id}/workers/routes` with `pattern` only), which turns Workers off for that pattern; a more specific pattern wins over a wildcard.
+     */
+    createRoute(zoneId: string, pattern: string, script?: string): Promise<{
+        id: string;
+    }>;
+    /** A no-op, not a throw, when `routeId` is already gone. */
+    deleteRoute(zoneId: string, routeId: string): Promise<void>;
+    /** A no-op, not a throw, when `name` is already gone. */
+    deleteScript(name: string): Promise<void>;
+}
 /**
  * One DNS record a Lettermint domain's own response says must be published --
  * `purpose` is Lettermint's own label (`return_path`, `dmarc`, `dkim_legacy`,
@@ -1257,6 +1340,37 @@ export interface AiOrganisationPort {
         limitMicros: string;
     }): Promise<unknown>;
 }
+/**
+ * #317 (F7): the edge service's own management API
+ * (https://github.com/wtfalch/edge, live on main, offering `mintKey`,
+ * `revokeKey` and `setReservedLabels`) -- this port states the shape this
+ * executor assumes of it. `organisationId` is the org itself: unlike
+ * `AiOrganisationPort.mintNestedKey`, edge takes no separate minter key
+ * id, so `edgeEntryKey` mints directly below the org. A real adapter
+ * wiring this port into `platform-providers.ts` is tracked separately
+ * (https://github.com/wtfalch/archon/issues/339).
+ */
+export interface EdgePort {
+    /**
+     * `domain` is required: edge's own `mintKey` refuses a request without a
+     * lowercase hostname and binds the key to it
+     * (`wtfalch/edge`'s `packages/service/src/keys.ts`) -- `edgeEntryKey`
+     * passes `org.domain`, which `validateEntryEdge` already requires before
+     * `uses.edge` is accepted.
+     */
+    mintKey(input: {
+        organisationId: string;
+        domain: string;
+        name: string;
+        expiresDays: number;
+    }): Promise<{
+        id: string;
+        secret: string;
+    }>;
+    revokeKey(organisationId: string, keyId: string): Promise<void>;
+    /** Refuses a label any hosting entry of `organisationId` already holds. Rerun whenever the org's own label set changes. */
+    setReservedLabels(organisationId: string, labels: string[]): Promise<void>;
+}
 /**
  * #173: the jobs scheduler's own admin API
  * (https://github.com/wtfalch/jobs, "The admin API", jobs#62), authenticated
@@ -1325,6 +1439,15 @@ export interface FoundryStepExecutorPorts {
     /** Flat, not a factory: `organisationId` is an explicit argument on every method of both ports (see each port's own doc comment; #177 dropped the `filesLimitsFor`/`aiLimitsFor` factories this used to need). */
     filesOrganisation?: FilesOrganisationPort;
     aiOrganisation?: AiOrganisationPort;
+    /**
+     * #317 (F7): mints an entry's edge key -- see {@link EdgePort}'s own
+     * doc comment. Optional the same way `jobsScheduler` is: a host with no
+     * edge service deployed builds the executor without one, and tells the
+     * planner so (`FoundryPlanApplyOptions.edge`), which then reports each
+     * entry's `uses.edge` step as blocked instead of planning one that would
+     * throw.
+     */
+    edge?: EdgePort;
     /**
      * #177: builds the files, AI and jobs ports from the platform's addresses
      * and held keys. A port set above overrides it (tests); with neither, the
@@ -1347,6 +1470,13 @@ export interface FoundryStepExecutorPorts {
      * `FoundryPlanApplyOptions.broker`).
      */
     broker?: BrokerPort;
+    /**
+     * #318: deploys and routes an entry's `worker` Worker -- see
+     * {@link WorkersPort}'s own doc comment. Optional the same way `broker` is:
+     * without it the plan reports each `worker` entry blocked (the host also
+     * sets `FoundryPlanApplyOptions.edgeWorkers`).
+     */
+    workers?: WorkersPort;
     /**
      * Hands a just-minted, one-time secret (today: an API app's
      * `clientSecret`) to the host, immediately after the provider returns it
@@ -1490,6 +1620,57 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * holds the hostname.
      */
     private cloudflareRateLimit;
+    /**
+     * `plan/diff.ts`'s `planWorkers` (#318, F8): deploys one entry's
+     * `worker` Worker and routes it on the org's own zone. Throws by name
+     * without a {@link WorkersPort}, the same `jobsRegistration` shape --
+     * `planWorkers` reports the step blocked instead while the host has
+     * none, so this only fires against a stale plan. The route is checked
+     * before upload: a foreign route already on the pattern is refused, never
+     * adopted or replaced (`cloudflareAccess`'s own precedent for a foreign
+     * resource on the same name), so a Worker is never deployed only to find
+     * nothing can route to it.
+     *
+     * Order on apply: record (and persist) the uploaded name and clear the
+     * retired marker, upload, record the pending route, create the route only
+     * if needed, delete any *previous* route this entry recorded on its own
+     * zone, then record the new route id/zone/pattern and the applied
+     * declaration last -- every crash point leaves a recorded trace that
+     * retire and destroy can clean up (#318 re-review), and per CLAUDE.md's
+     * "Declared changes apply" nothing is marked done until the
+     * live state actually matches it.
+     */
+    private cloudflareWorker;
+    /**
+     * Makes the no-Worker routes recorded for an entry match `patterns`: deletes
+     * the ones no longer wanted (all of them if the zone changed), creates the
+     * missing ones without a script. A route already on a pattern that is bound
+     * to a Worker is foreign and refused; one with no script is adopted. Records
+     * and persists after each change.
+     */
+    private syncWorkerExclusions;
+    /**
+     * The zone id a recorded route lives in, or `undefined` only when that
+     * zone is *positively* gone -- its apex resolves to no zone, or to a
+     * different zone than the one recorded (#318 re-review). Reads the zone
+     * recorded beside the route, never `org.domain`: the route id and its
+     * zone are always recorded together (the apply branch below writes both
+     * in the same batch, and the pending-route marker carries its own zone
+     * too), so a route id with no zone recorded cannot happen within this
+     * feature -- and re-resolving from `org.domain` as a fallback would risk
+     * looking up the *new* zone after a domain change and leaving the route
+     * live on the old one, the exact bug a recorded-per-route zone exists to
+     * avoid (#318 re-review).
+     */
+    private liveWorkerZone;
+    /** Deletes the route an interrupted apply was creating, if `findRoute` shows it exists, points at that apply's script, and is not `keepRouteId`. */
+    private deletePendingWorkerRoute;
+    /**
+     * Retire and destroy share this: delete the recorded route on its own
+     * zone, then any route an interrupted apply created but never recorded,
+     * then the script. Records nothing -- the caller does.
+     */
+    private teardownWorker;
     private zitadelIssuer;
     /**
      * `plan/diff.ts`'s `planOwner`: invites the org's owner into its ZITADEL
@@ -1761,6 +1942,22 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * comment), never logged, never interpolated into a thrown error -- the
      * same discipline `pushDatabaseUrl`'s doc comment states for a database's
      * own connection string.
+     *
+     * #491: none of the above applies to the org whose mail domain is the
+     * platform's own apex -- it shares the platform's existing Lettermint
+     * project (`platformLettermintProjectId`, from `DeclaredPlatform.mail`)
+     * instead of minting a `<slug>-app` one, and this method never creates or
+     * deletes a project for it. `platformApex`/`platformLettermintProjectId`
+     * come straight off this step's own `desired`, the same "the executor
+     * writes exactly what the plan showed" rule `coolifyMail` already follows
+     * for its own `apex`/`mailHost` -- the caller (`coolifyApp`) refuses a
+     * `desired` missing the `platformApex` key outright as a stale plan --
+     * checked here, after the no-op-until-a-mail-domain-exists return just
+     * below, rather than unconditionally at the call site: every other
+     * `coolify:app` concern (hostnames, ports, settings, the sign-in env...)
+     * has nothing to do with Lettermint and must keep working the moment a
+     * mail domain was never even recorded for this org, the same as before
+     * this field existed (review round 2, finding 3).
      */
     private ensureAppLettermintMail;
     /**
@@ -1796,6 +1993,12 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * it the same way the app step does, rather than assuming it already
      * exists -- the domain must never end up unrestricted, whichever step gets
      * there first.
+     *
+     * #491: this org's own `<slug>-relay` project is unaffected by whether it
+     * is the platform's own org -- only the domain restriction
+     * (`platformApex`/`platformLettermintProjectId`, forwarded to
+     * {@link ensureLettermintDomainRestriction}) and the delete loop below
+     * (which must never delete the platform's own project) change.
      */
     private ensureOrgLettermintRelay;
     /**
@@ -1818,6 +2021,21 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * unrestricted domain cannot verify and cannot send, whichever project
      * owns it (post-#140 review finding, restated here rather than only at
      * the one call site it used to have).
+     *
+     * #491: `platformApex`/`platformLettermintProjectId` cover both callers at
+     * once -- when `mailDomain` is the platform's own apex, the platform's
+     * project id is always folded into the restriction, so a plan that shares
+     * the platform's project (rather than minting a `<slug>-app` one) never
+     * ends up restricting that org's domain to nothing. A no-op for every
+     * other org's domain, since `mailDomain` never matches `platformApex` there.
+     * Review round 2, finding 4: a declared id that is not among `allProjects`
+     * (a mistype, or the project was deleted in Lettermint) is refused rather
+     * than folded in anyway -- that would restrict the apex to whatever *is*
+     * live (the relay project, say) plus an id naming nothing, which excludes
+     * the real platform project from its own domain exactly as completely as
+     * never restricting it at all. Centralised here rather than duplicated at
+     * each caller, since both {@link ensureAppLettermintMail} and
+     * {@link ensureOrgLettermintRelay} reach the apex through this one method.
      */
     private ensureLettermintDomainRestriction;
     /**
@@ -2356,6 +2574,13 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * domain recorded) and on a same-domain re-apply (compared
      * case-insensitively, the same rule {@link findExactLettermintDomain}
      * applies to the lookup itself).
+     *
+     * #491 review: also a no-op when the previous domain is the platform's own
+     * apex -- an org that moves its mail *off* that domain (`usesDomain` flips,
+     * or `org.domain` changes) must never delete it here, the same protection
+     * {@link parkLettermintMail} already gives the apex on a move to `off`.
+     * `planMail` only blocks a move *onto* the apex (no project id yet); a move
+     * away from it reaches this method with nothing to block it otherwise.
      */
     private deleteStaleLettermintDomain;
     /**
@@ -2398,6 +2623,10 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * A no-op until a previous apply recorded {@link MAIL_DOMAIN_SCOPE_KEY}:
      * nothing was ever provisioned for an org whose mail went straight from
      * never-applied to off.
+     *
+     * #491: when `mailDomain` is the platform's own apex, this must never
+     * delete the platform's own project (the delete loop skips it by id) or
+     * the platform's own domain (returns before the domain lookup/delete).
      */
     private parkLettermintMail;
     /**
@@ -2497,6 +2726,22 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * new key.
      */
     private revokeEntryKey;
+    /**
+     * F7 (#317): mints one entry's edge key directly below the org (edge
+     * takes no separate minter key id, unlike ai/files), writes `EDGE_URL`
+     * and `EDGE_API_KEY` to the entry's app env, then restarts it. Retires
+     * the key when `uses.edge` is removed. Follows the "one mint" rule
+     * (CLAUDE.md "Platform steps"): the id is recorded as undelivered and
+     * persisted before delivery is attempted, so a crash or a failed write
+     * never leads to a second mint -- `planEntryEdgeKeys` blocks instead.
+     */
+    private edgeEntryKey;
+    /**
+     * F7 (#317): `plan/entry-edge-key.ts`'s `planEdgeReservedLabels` --
+     * tells the edge service every label this org's own entries already
+     * hold, so edge refuses a customer claiming one of them.
+     */
+    private edgeReservedLabels;
     /**
      * F6b: mints or renews the org's own files key, or revokes the ones a
      * renewal replaced. The key is minted below the files organisation's owner