@wtfalch/foundry 0.17.0 → 0.18.0

package/dist/plan/step-system.js

@@ -4,6 +4,7 @@ const PLATFORM_APP_SYSTEMS = {
     'platform:mail': 'stalwart',
     'platform:files': 'files',
     'platform:ai': 'ai',
+    'platform:edge': 'edge',
 };
 /** The system `action` touches. The one place that decides it, so no planner sets it by hand. */
 export function stepSystemOf(action) {

package/dist/plan/worker.d.ts

@@ -0,0 +1,134 @@
+import type { DeclaredOrg, HostingEntry, WorkerConfig } from '../org.js';
+import type { DraftStep } from './diff.js';
+/**
+ * F8 (#318): one plain Cloudflare Worker per hosting entry that declares
+ * `worker`, 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, `workerAppliedScopeKey`):
+ * `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 entryWorkerAppliedScopeKey: (entryKey: string) => string;
+export declare const entryWorkerRouteIdScopeKey: (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 entryWorkerRoutePatternScopeKey: (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`/
+ * `entryEdgeRetiredScopeKey` already give their own entry keys.
+ */
+export declare const entryWorkerRetiredScopeKey: (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 entryWorkerUploadedScopeKey: (entryKey: string) => string;
+/** The zone the recorded route id lives in, as {@link WorkerRouteZone} JSON -- so retire and destroy delete it on *that* zone even after `org.domain` changes or goes null. */
+export declare const entryWorkerRouteZoneScopeKey: (entryKey: string) => string;
+/** A route about to be created, as {@link WorkerRoutePending} 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 entryWorkerRoutePendingScopeKey: (entryKey: string) => string;
+/**
+ * The no-Worker routes kept beside an entry's wildcard Worker route, as
+ * {@link WorkerExclusions} JSON. Written after each create or delete, so a
+ * crash leaves every route that exists recorded.
+ */
+export declare const entryWorkerExclusionsScopeKey: (entryKey: string) => string;
+export interface WorkerExclusions extends WorkerRouteZone {
+    /** Route pattern to Cloudflare route id. */
+    routes: Record<string, string>;
+}
+export interface WorkerRouteZone {
+    id: string;
+    apex: string;
+}
+export interface WorkerRoutePending extends WorkerRouteZone {
+    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 workerTraceScopeKeys: (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 liveWorkers(orgId: string, recordedIds: Readonly<Record<string, string>>): Map<string, string>;
+/** The first 8 hex characters of org.id's own sha256 -- see {@link workerName}'s doc comment. */
+export declare const WORKER_ORG_HASH_LENGTH = 8;
+/** Cloudflare's own limit on a Worker script name. */
+export declare const 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 `WORKER_NAME_MAX_LENGTH` gives it,
+ * so only a short hash of it is used -- `validateEntryWorker` (`org.ts`)
+ * checks the resulting name never exceeds that limit.
+ */
+export declare const workerName: (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 WorkerWant}
+ * 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 WORKER_COMPATIBILITY_DATE = "2026-09-12";
+export type WorkerMode = 'apply' | 'retire';
+export interface WorkerWant {
+    name: string;
+    artifactUrl: string;
+    artifactSha256: string;
+    route: string;
+    bindings: WorkerConfig['bindings'];
+    /** No-Worker route patterns, sorted; set only for a wildcard route with hostnames to keep out. */
+    exclusions?: string[];
+}
+/**
+ * With a wildcard route (`*.<domain>/*`) the Worker would also capture every
+ * hostname foundry provisions on the domain, so each gets a no-Worker route
+ * `<hostname>/*` (a more specific pattern wins): every entry hostname plus the
+ * names `lockedHostnames` lists (Agora, Boule, the login host, platform apps).
+ * Never the wildcard itself.
+ */
+export declare function workerExclusions(org: DeclaredOrg, entry: HostingEntry, platformHostnames: readonly string[]): string[];
+export declare function wantedWorker(org: DeclaredOrg, entry: HostingEntry, platformHostnames?: readonly string[]): WorkerWant;
+type Blocked = Array<{
+    description: string;
+    key: string;
+}>;
+/**
+ * One step per entry whose `worker` config is new or changed, plus one retire
+ * step per entry whose Worker is recorded but no longer declared -- either
+ * because the entry dropped `worker` or because the entry itself is gone, the
+ * same "gone" scan `planEntryAiKeys`/`planFilesKeys`/`planEntryEdgeKeys`
+ * 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 planWorkers(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, workersAvailable: boolean, platformHostnames?: readonly string[]): {
+    steps: DraftStep[];
+    blocked: Blocked;
+};
+export {};

package/dist/plan/worker.js

@@ -0,0 +1,239 @@
+import { createHash } from 'node:crypto';
+import { entryHostnames } from './hostnames.js';
+import { lockedHostnames } from './locked-hostnames.js';
+import { appStepKey } from './platform-diff.js';
+/**
+ * F8 (#318): one plain Cloudflare Worker per hosting entry that declares
+ * `worker`, 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, `workerAppliedScopeKey`):
+ * `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.
+ */
+// Recorded scope keys keep their `edge_worker_` prefix: renaming them would orphan live Workers.
+export const entryWorkerAppliedScopeKey = (entryKey) => `edge_worker_applied_${entryKey}`;
+export const entryWorkerRouteIdScopeKey = (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 entryWorkerRoutePatternScopeKey = (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`/
+ * `entryEdgeRetiredScopeKey` already give their own entry keys.
+ */
+export const entryWorkerRetiredScopeKey = (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 entryWorkerUploadedScopeKey = (entryKey) => `edge_worker_uploaded_${entryKey}`;
+/** The zone the recorded route id lives in, as {@link WorkerRouteZone} JSON -- so retire and destroy delete it on *that* zone even after `org.domain` changes or goes null. */
+export const entryWorkerRouteZoneScopeKey = (entryKey) => `edge_worker_route_zone_${entryKey}`;
+/** A route about to be created, as {@link WorkerRoutePending} 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 entryWorkerRoutePendingScopeKey = (entryKey) => `edge_worker_route_pending_${entryKey}`;
+/**
+ * The no-Worker routes kept beside an entry's wildcard Worker route, as
+ * {@link WorkerExclusions} JSON. Written after each create or delete, so a
+ * crash leaves every route that exists recorded.
+ */
+export const entryWorkerExclusionsScopeKey = (entryKey) => `edge_worker_exclusions_${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 workerTraceScopeKeys = (entryKey) => [
+    entryWorkerUploadedScopeKey(entryKey),
+    entryWorkerRouteIdScopeKey(entryKey),
+    entryWorkerRouteZoneScopeKey(entryKey),
+    entryWorkerRoutePatternScopeKey(entryKey),
+    entryWorkerRoutePendingScopeKey(entryKey),
+    entryWorkerRetiredScopeKey(entryKey),
+    entryWorkerExclusionsScopeKey(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 liveWorkers(orgId, recordedIds) {
+    const mainPrefix = `cloudflare:worker:${orgId}:`;
+    const tracePrefixes = [
+        mainPrefix,
+        'edge_worker_uploaded_',
+        'edge_worker_route_id_',
+        'edge_worker_route_pending_',
+        'edge_worker_exclusions_',
+    ];
+    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[entryWorkerUploadedScopeKey(entryKey)] ?? '';
+        const partial = uploaded ||
+            recordedIds[entryWorkerRouteIdScopeKey(entryKey)] ||
+            recordedIds[entryWorkerRoutePendingScopeKey(entryKey)] ||
+            recordedIds[entryWorkerExclusionsScopeKey(entryKey)];
+        const retired = mainId !== '' && recordedIds[entryWorkerRetiredScopeKey(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 workerName}'s doc comment. */
+export const WORKER_ORG_HASH_LENGTH = 8;
+/** Cloudflare's own limit on a Worker script name. */
+export const 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 `WORKER_NAME_MAX_LENGTH` gives it,
+ * so only a short hash of it is used -- `validateEntryWorker` (`org.ts`)
+ * checks the resulting name never exceeds that limit.
+ */
+export const workerName = (org, entry) => 
+// The `-edge` suffix stays after the entry field rename to `worker`, so live Workers keep their names and are not orphaned.
+`${createHash('sha256').update(org.id).digest('hex').slice(0, 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 WorkerWant}
+ * 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 WORKER_COMPATIBILITY_DATE = '2026-09-12';
+/**
+ * With a wildcard route (`*.<domain>/*`) the Worker would also capture every
+ * hostname foundry provisions on the domain, so each gets a no-Worker route
+ * `<hostname>/*` (a more specific pattern wins): every entry hostname plus the
+ * names `lockedHostnames` lists (Agora, Boule, the login host, platform apps).
+ * Never the wildcard itself.
+ */
+export function workerExclusions(org, entry, platformHostnames) {
+    const route = entry.worker?.route;
+    const { domain } = org;
+    if (!route || !domain || !route.startsWith('*.'))
+        return [];
+    const names = new Set(lockedHostnames(org, platformHostnames));
+    for (const e of org.hosting.entries)
+        for (const h of entryHostnames(org, e))
+            names.add(h);
+    return [...names]
+        .filter((h) => h === domain || h.endsWith(`.${domain}`))
+        .map((h) => `${h}/*`)
+        .filter((pattern) => pattern !== route)
+        .sort();
+}
+export function wantedWorker(org, entry, platformHostnames = []) {
+    const worker = entry.worker;
+    const exclusions = workerExclusions(org, entry, platformHostnames);
+    return {
+        name: workerName(org, entry),
+        artifactUrl: worker.artifactUrl,
+        artifactSha256: worker.artifactSha256,
+        route: worker.route,
+        bindings: worker.bindings,
+        exclusions: exclusions.length > 0 ? exclusions : undefined,
+    };
+}
+/**
+ * One step per entry whose `worker` config is new or changed, plus one retire
+ * step per entry whose Worker is recorded but no longer declared -- either
+ * because the entry dropped `worker` or because the entry itself is gone, the
+ * same "gone" scan `planEntryAiKeys`/`planFilesKeys`/`planEntryEdgeKeys`
+ * 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 planWorkers(org, recordedIds, workersAvailable, platformHostnames = []) {
+    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.worker).map((e) => e.key) : []);
+    const mainPrefix = `cloudflare:worker:${org.id}:`;
+    // Every entryKey with a live, undeclared trace (`liveWorkers`): 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 liveWorkers(org.id, recordedIds).keys()) {
+        if (declared.has(entryKey))
+            continue;
+        const stepKey = `${org.id}:${entryKey}`;
+        if (!workersAvailable) {
+            blocked.push({
+                description: `${org.slug}'s ${entryKey} 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} Worker and its route: worker is no longer declared`,
+                destroys: true,
+                migrates: false,
+            },
+        });
+    }
+    if (!org.hosting.enabled)
+        return { steps, blocked };
+    for (const entry of org.hosting.entries) {
+        if (!entry.worker)
+            continue;
+        const stepKey = appStepKey(org, entry.key);
+        const key = `cloudflare:worker:${stepKey}`;
+        const at = `${org.slug}'s ${entry.key} Worker`;
+        if (!workersAvailable) {
+            blocked.push({
+                description: `${at} is blocked, not planned: the host supplies no WorkersPort`,
+                key,
+            });
+            continue;
+        }
+        const want = wantedWorker(org, entry, platformHostnames);
+        const wantJson = JSON.stringify(want);
+        const applied = recordedIds[entryWorkerAppliedScopeKey(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: WORKER_COMPATIBILITY_DATE, ...want },
+            },
+            step: {
+                description: `${applied ? 'update' : 'deploy'} ${at} on ${entry.worker.route}`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, blocked };
+}

package/dist/platform.d.ts

@@ -12,8 +12,25 @@ export interface PlatformService {
     hostname: string;
     gitRef: string;
 }
-/** The eight shared services a declared platform names, decided in #165. */
-export type PlatformServiceKey = 'auth' | 'mail' | 'sfu' | 'files' | 'ai' | 'jobs' | 'integrations' | 'archon';
+/**
+ * #491: `mail`'s own extra field, on top of every other service's shape.
+ * Company Included (or whichever org's mail domain is the platform's own
+ * apex) sends through the platform's existing Lettermint project rather than
+ * a second `<slug>-app` one of its own -- `undefined`/`null` until an
+ * operator declares which project that is. A ref only, never a value: the
+ * project's own sending token stays where it already lived, held under
+ * `PLATFORM_AUTH_BROKER_MAIL_KEY_REF` (`plan/platform-providers.ts`).
+ */
+export interface PlatformMailService extends PlatformService {
+    lettermintProjectId?: string | null;
+}
+/**
+ * The shared services a declared platform names, decided in #165, plus
+ * `edge` (#317, F7): the service that mints an entry's own edge key and
+ * holds the Cloudflare token `<username>.<org domain>` claims use, so no
+ * hosting entry ever holds that credential itself.
+ */
+export type PlatformServiceKey = 'auth' | 'mail' | 'sfu' | 'files' | 'ai' | 'jobs' | 'integrations' | 'archon' | 'edge';
 export declare const PLATFORM_SERVICE_KEYS: readonly PlatformServiceKey[];
 /**
  * The one shared platform every org's services run on -- decided in #165 as
@@ -42,13 +59,15 @@ export interface DeclaredPlatform {
      */
     serverIpv4?: string | null;
     auth: PlatformService;
-    mail: PlatformService;
+    mail: PlatformMailService;
     sfu: PlatformService;
     files: PlatformService;
     ai: PlatformService;
     jobs: PlatformService;
     integrations: PlatformService;
     archon: PlatformService;
+    /** #317 (F7). No deploy step reads this service's own `gitRef` yet -- `N1` is deployed by hand until it exists. */
+    edge: PlatformService;
 }
 /** `<service>.<apex>` -- the default `hostname` for a platform service, before an operator overrides it. */
 export declare function defaultPlatformHostname(service: PlatformServiceKey, apex: string): string;

package/dist/platform.js

@@ -9,6 +9,7 @@ export const PLATFORM_SERVICE_KEYS = [
     'jobs',
     'integrations',
     'archon',
+    'edge',
 ];
 /** `<service>.<apex>` -- the default `hostname` for a platform service, before an operator overrides it. */
 export function defaultPlatformHostname(service, apex) {
@@ -47,5 +48,10 @@ export function validatePlatform(platform) {
             return `${key}.gitRef must not be empty once ${key}.enabled is true`;
         }
     }
+    // #491: declared, never discovered -- a present-but-blank id is refused the
+    // same way `serverIpv4`'s blank string is, rather than being read as unset.
+    if (platform.mail.lettermintProjectId != null && !platform.mail.lettermintProjectId.trim()) {
+        return 'mail.lettermintProjectId must not be empty when set';
+    }
     return null;
 }

package/dist/store/postgres.js

@@ -578,7 +578,12 @@ function rowToPlatform(row) {
         apex: row.apex,
         ...(row.serverIpv4 ? { serverIpv4: row.serverIpv4 } : {}),
         auth: { enabled: row.authEnabled, hostname: row.authHostname, gitRef: row.authGitRef },
-        mail: { enabled: row.mailEnabled, hostname: row.mailHostname, gitRef: row.mailGitRef },
+        mail: {
+            enabled: row.mailEnabled,
+            hostname: row.mailHostname,
+            gitRef: row.mailGitRef,
+            ...(row.mailLettermintProjectId ? { lettermintProjectId: row.mailLettermintProjectId } : {}),
+        },
         sfu: { enabled: row.sfuEnabled, hostname: row.sfuHostname, gitRef: row.sfuGitRef },
         files: { enabled: row.filesEnabled, hostname: row.filesHostname, gitRef: row.filesGitRef },
         ai: { enabled: row.aiEnabled, hostname: row.aiHostname, gitRef: row.aiGitRef },
@@ -593,6 +598,11 @@ function rowToPlatform(row) {
             hostname: row.archonHostname,
             gitRef: row.archonGitRef,
         },
+        edge: {
+            enabled: row.edgeEnabled,
+            hostname: row.edgeHostname,
+            gitRef: row.edgeGitRef,
+        },
     };
 }
 function platformToRow(platform) {
@@ -607,6 +617,7 @@ function platformToRow(platform) {
         mailEnabled: platform.mail.enabled,
         mailHostname: platform.mail.hostname,
         mailGitRef: platform.mail.gitRef,
+        mailLettermintProjectId: platform.mail.lettermintProjectId ?? null,
         sfuEnabled: platform.sfu.enabled,
         sfuHostname: platform.sfu.hostname,
         sfuGitRef: platform.sfu.gitRef,
@@ -625,6 +636,9 @@ function platformToRow(platform) {
         archonEnabled: platform.archon.enabled,
         archonHostname: platform.archon.hostname,
         archonGitRef: platform.archon.gitRef,
+        edgeEnabled: platform.edge.enabled,
+        edgeHostname: platform.edge.hostname,
+        edgeGitRef: platform.edge.gitRef,
     };
 }
 /**

package/dist/store/schema.d.ts

@@ -1236,7 +1236,7 @@ export declare const foundryAuditEvents: import("drizzle-orm/pg-core").PgTableWi
             tableName: "foundry_audit_events";
             dataType: "string";
             columnType: "PgText";
-            data: "plan" | "destroy" | "apply";
+            data: "apply" | "plan" | "destroy";
             driverParam: string;
             notNull: true;
             hasDefault: false;
@@ -1248,7 +1248,7 @@ export declare const foundryAuditEvents: import("drizzle-orm/pg-core").PgTableWi
             identity: undefined;
             generated: undefined;
         }, {}, {
-            $type: "plan" | "destroy" | "apply";
+            $type: "apply" | "plan" | "destroy";
         }>;
         actorId: import("drizzle-orm/pg-core").PgColumn<{
             name: "actor_id";
@@ -1558,6 +1558,23 @@ export declare const foundryDeclaredPlatform: import("drizzle-orm/pg-core").PgTa
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        mailLettermintProjectId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "mail_lettermint_project_id";
+            tableName: "foundry_declared_platform";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         sfuEnabled: import("drizzle-orm/pg-core").PgColumn<{
             name: "sfu_enabled";
             tableName: "foundry_declared_platform";
@@ -1864,6 +1881,57 @@ export declare const foundryDeclaredPlatform: import("drizzle-orm/pg-core").PgTa
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        edgeEnabled: import("drizzle-orm/pg-core").PgColumn<{
+            name: "edge_enabled";
+            tableName: "foundry_declared_platform";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        edgeHostname: import("drizzle-orm/pg-core").PgColumn<{
+            name: "edge_hostname";
+            tableName: "foundry_declared_platform";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        edgeGitRef: import("drizzle-orm/pg-core").PgColumn<{
+            name: "edge_git_ref";
+            tableName: "foundry_declared_platform";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         serviceIds: import("drizzle-orm/pg-core").PgColumn<{
             name: "service_ids";
             tableName: "foundry_declared_platform";

package/dist/store/schema.js

@@ -158,6 +158,8 @@ export const foundryDeclaredPlatform = pgTable('foundry_declared_platform', {
     mailEnabled: boolean('mail_enabled').notNull().default(false),
     mailHostname: text('mail_hostname').notNull(),
     mailGitRef: text('mail_git_ref').notNull().default(''),
+    /** #491, `migrations/0044_platform_mail_lettermint_project.sql`. Declared, never discovered. */
+    mailLettermintProjectId: text('mail_lettermint_project_id'),
     sfuEnabled: boolean('sfu_enabled').notNull().default(false),
     sfuHostname: text('sfu_hostname').notNull(),
     sfuGitRef: text('sfu_git_ref').notNull().default(''),
@@ -176,6 +178,10 @@ export const foundryDeclaredPlatform = pgTable('foundry_declared_platform', {
     archonEnabled: boolean('archon_enabled').notNull().default(false),
     archonHostname: text('archon_hostname').notNull(),
     archonGitRef: text('archon_git_ref').notNull().default(''),
+    /** #317 (F7), `migrations/0043_platform_names.sql`, renamed from `names_*` by `0045_names_to_edge.sql`. */
+    edgeEnabled: boolean('edge_enabled').notNull().default(false),
+    edgeHostname: text('edge_hostname').notNull(),
+    edgeGitRef: text('edge_git_ref').notNull().default(''),
     /** `migrations/0018_platform_apply.sql`: the platform's applied state, `system:kind:key` to provider id. */
     serviceIds: jsonb('service_ids').$type().notNull().default({}),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",