@wtfalch/foundry 0.4.0 → 0.6.0

package/dist/plan/index.d.ts

@@ -1,10 +1,33 @@
-export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, } from './live.js';
-export { readLiveResources } from './live.js';
+export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, PlatformCloudflareReader, PlatformCoolifyReader, PlatformLiveReaders, } from './live.js';
+export { readLiveResources, readLivePlatformResources } from './live.js';
 export type { StepAction, PlannedStep, PlanDetail } from './diff.js';
 export { computePlanDetail, toPlan } from './diff.js';
-export type { AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, FoundryPlanApplyOptions, } from './plan-apply.js';
-export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, } from './plan-apply.js';
+export type { PlatformPlanDetail } from './platform-diff.js';
+export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, } from './platform-diff.js';
+export type { HeldKeyResolver, OrgPlatformReadiness } from './platform-org.js';
+export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './platform-org.js';
+export type { PlatformOrgClientFactories } from './platform-org-ports.js';
+export { PlatformOrgBlockedError, PlatformOrgPorts } from './platform-org-ports.js';
+export type { AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, } from './plan-apply.js';
+export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan-apply.js';
+export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './platform-providers.js';
+export type { PlatformAuthDeps, PlatformAuthRuntime, PlatformFilesDeps, PlatformFilesRuntime, } from './platform-providers.js';
+export type { PlatformMailDeps, PlatformMailAdminPort, PlatformMailRuntime, } from './platform-providers.js';
+export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, } from './platform-providers.js';
+export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManagementKeyExistsError, createAiManagementKeyMinter, PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, } from './platform-providers.js';
+export type { AiManagementKeyMinter, PlatformAiDeps, PlatformAiRuntime, } from './platform-providers.js';
+export { createZitadelAdminMinter } from './zitadel-machine-user.js';
+export type { CallsSfuConnection, CallsSfuConnectionPort, CallsSfuKeysPort, CallsSfuSshConnector, CallsSfuPlatformDeps, } from './platform-sfu.js';
+export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep } from './platform-sfu.js';
+export type { MailCopyJob, MailCopyPort, MailCopyStepResult } from './mail-copy.js';
+export { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, MissingMailCopyAccountsError, MissingMailCopySourceTokenError, MissingMailCopyStalwartTokenError, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';
 export type { ScopeResolver, RecordedIds } from './providers-readers.js';
 export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
-export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, FilesOrgLimits, AiOrgLimits, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, } from './executor.js';
+export type { AgoraHostPort, AgoraHostValues } from './agora.js';
+export type { MailIdentityApp, MailIdentityAudienceCheck } from './mail-identity.js';
+export { checkMailIdentityAudience } from './mail-identity.js';
+export type { MailAllowlistApp } from './mail-identity-allowlist.js';
+export { checkMailAppsAllowlist } from './mail-identity-allowlist.js';
+export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, JobsSchedulerPort, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, PlatformOrgPortSource, } from './executor.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls } from './executor.js';
+export { HttpJobsSchedulerClient } from './jobs-scheduler-http.js';

package/dist/plan/index.js

@@ -1,5 +1,18 @@
-export { readLiveResources } from './live.js';
+export { readLiveResources, readLivePlatformResources } from './live.js';
 export { computePlanDetail, toPlan } from './diff.js';
-export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, } from './plan-apply.js';
+export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, } from './platform-diff.js';
+export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './platform-org.js';
+export { PlatformOrgBlockedError, PlatformOrgPorts } from './platform-org-ports.js';
+export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan-apply.js';
+export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './platform-providers.js';
+// #171: how a host signs files management requests with the delivered key.
+export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, } from './platform-providers.js';
+export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManagementKeyExistsError, createAiManagementKeyMinter, PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, } from './platform-providers.js';
+export { createZitadelAdminMinter } from './zitadel-machine-user.js';
+export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep } from './platform-sfu.js';
+export { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, MissingMailCopyAccountsError, MissingMailCopySourceTokenError, MissingMailCopyStalwartTokenError, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';
 export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
+export { checkMailIdentityAudience } from './mail-identity.js';
+export { checkMailAppsAllowlist } from './mail-identity-allowlist.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls } from './executor.js';
+export { HttpJobsSchedulerClient } from './jobs-scheduler-http.js';

package/dist/plan/jobs-scheduler-http.d.ts

@@ -0,0 +1,29 @@
+import type { JobsSchedulerPort } from './executor.js';
+/**
+ * #173: the real {@link JobsSchedulerPort}, a thin client over the jobs
+ * scheduler's admin HTTP API (https://github.com/wtfalch/jobs README, "The
+ * admin API", `POST /admin/projects`). The scheduler ships no SDK for this,
+ * so it is plain `fetch`.
+ *
+ * `adminToken` is the scheduler's `SCHEDULER_ADMIN_TOKEN` (`coolifyJobs`
+ * generates it and hands it to the host through `deliverSecret`); the host
+ * resolves it and builds this client. This package holds no credential of
+ * its own. The token and the credentials in a response never appear in a
+ * thrown error -- only the status and the scheduler's own `error` text,
+ * which the API builds from the name and URLs alone.
+ */
+export declare class HttpJobsSchedulerClient implements JobsSchedulerPort {
+    private readonly adminToken;
+    private readonly fetchImpl;
+    private readonly baseUrl;
+    constructor(baseUrl: string, adminToken: string, fetchImpl?: typeof fetch);
+    registerProject(input: {
+        name: string;
+        baseUrl: string;
+        alertUrl?: string;
+    }): Promise<{
+        id: string;
+        secret?: string;
+        syncKey?: string;
+    }>;
+}

package/dist/plan/jobs-scheduler-http.js

@@ -0,0 +1,50 @@
+/**
+ * #173: the real {@link JobsSchedulerPort}, a thin client over the jobs
+ * scheduler's admin HTTP API (https://github.com/wtfalch/jobs README, "The
+ * admin API", `POST /admin/projects`). The scheduler ships no SDK for this,
+ * so it is plain `fetch`.
+ *
+ * `adminToken` is the scheduler's `SCHEDULER_ADMIN_TOKEN` (`coolifyJobs`
+ * generates it and hands it to the host through `deliverSecret`); the host
+ * resolves it and builds this client. This package holds no credential of
+ * its own. The token and the credentials in a response never appear in a
+ * thrown error -- only the status and the scheduler's own `error` text,
+ * which the API builds from the name and URLs alone.
+ */
+export class HttpJobsSchedulerClient {
+    adminToken;
+    fetchImpl;
+    baseUrl;
+    constructor(baseUrl, adminToken, fetchImpl = fetch) {
+        this.adminToken = adminToken;
+        this.fetchImpl = fetchImpl;
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+    }
+    async registerProject(input) {
+        const response = await this.fetchImpl(`${this.baseUrl}/admin/projects`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${this.adminToken}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify(input),
+        });
+        const body = await response.json().catch(() => undefined);
+        const fields = typeof body === 'object' && body !== null ? body : {};
+        if (response.status !== 200 && response.status !== 201) {
+            const detail = typeof fields.error === 'string' ? `: ${fields.error}` : '';
+            throw new Error(`jobs scheduler: POST /admin/projects answered ${response.status}${detail}`);
+        }
+        if (typeof fields.id !== 'string' || fields.id.length === 0) {
+            throw new Error(`jobs scheduler: POST /admin/projects answered ${response.status} with no project id`);
+        }
+        // 200 is a repeat call: the scheduler returns just the id, never a secret.
+        if (response.status === 200)
+            return { id: fields.id };
+        return {
+            id: fields.id,
+            secret: typeof fields.secret === 'string' ? fields.secret : undefined,
+            syncKey: typeof fields.syncKey === 'string' ? fields.syncKey : undefined,
+        };
+    }
+}

package/dist/plan/live.d.ts

@@ -1,6 +1,6 @@
 import type { OrgId } from '../org.js';
 /**
- * One resource as seen live in one of foundry's six systems.
+ * One resource as seen live in one of foundry's seven systems.
  *
  * `key` is unique within `(system, kind)`. Per-org singleton resources
  * (issuer, mail, chat, storage's spend limit, AI's budget, the cms site, the
@@ -13,9 +13,22 @@ import type { OrgId } from '../org.js';
  * is keyed however that system names it, so it can still be matched, or left
  * {@link https://github.com/wtfalch/foundry/issues/10 unmanaged}, by
  * `computePlanDetail`.
+ *
+ * #173 adds the seventh system, `jobs`: not a resource Coolify, Cloudflare or
+ * any of the others reports, but the jobs scheduler's own admin API
+ * (https://github.com/wtfalch/jobs, jobs#62) -- an org's registration with it,
+ * keyed by the {@link OrgId} like every other per-org singleton.
  */
 export interface LiveResource {
-    system: 'zitadel' | 'coolify' | 'cloudflare' | 'files' | 'ai' | 'cms';
+    /**
+     * `'sfu'` (#170) has no reader wired below -- there is no cheap way to
+     * probe the calls SFU VM's own state over SSH during planning, so
+     * `platform-diff.ts`'s `planSfu` always plans its step when
+     * `DeclaredPlatform.sfu.enabled` is true, rather than diffing against a
+     * live resource the way every other system here does. It is still part of
+     * this union so `StepAction.system` (`diff.ts`) can name it.
+     */
+    system: 'zitadel' | 'coolify' | 'cloudflare' | 'files' | 'ai' | 'cms' | 'jobs' | 'sfu';
     kind: string;
     key: string;
     config: Record<string, unknown>;
@@ -64,3 +77,39 @@ export interface LiveReaders {
 }
 /** Every live resource foundry can see for `orgId`, across all six systems. */
 export declare function readLiveResources(orgId: OrgId, readers: LiveReaders): Promise<LiveResource[]>;
+/**
+ * #167: one narrow interface per system reading the shared platform's own
+ * resources (`platform.ts`'s `DeclaredPlatform`) -- the platform-scoped
+ * counterpart to {@link ZitadelReader}/{@link CoolifyReader}/
+ * {@link CloudflareReader} above. There is no {@link OrgId} to scope a read
+ * by: `DeclaredPlatform` is one record, not one per org, so `listResources`
+ * here takes no argument at all.
+ *
+ * `cloudflare` is wired for #167's own `cloudflare:zone` step
+ * (`platform-diff.ts`'s `planApexZone`); #173 adds `coolify`, for the jobs
+ * scheduler's own Coolify app (`platform-diff.ts`'s `planJobs`). The rest of
+ * the platform's eventual surface (`platform-diff.ts`'s own doc comment:
+ * "every other service ... is left for its own issue to plan") adds a reader
+ * here, and to {@link PlatformLiveReaders} and {@link readLivePlatformResources}
+ * below, as each service's own step lands -- the same way `LiveReaders` above
+ * grew from three readers to six across #19, #27 and #80.
+ */
+export interface PlatformCloudflareReader {
+    listResources(): Promise<LiveResource[]>;
+}
+/** #173: the platform's own Coolify-hosted jobs scheduler (`platform-diff.ts`'s `planJobs`). */
+export interface PlatformCoolifyReader {
+    listResources(): Promise<LiveResource[]>;
+}
+export interface PlatformLiveReaders {
+    cloudflare: PlatformCloudflareReader;
+    /**
+     * Optional so every #167-era caller -- everything that plans/applies only
+     * the apex zone -- is unaffected. Without one the scheduler could never be
+     * seen live, so `planJobs` plans no step and reports the scheduler as
+     * blocked (an `unmanaged` item) rather than re-planning it forever.
+     */
+    coolify?: PlatformCoolifyReader;
+}
+/** Every live resource foundry can see for the platform, across every wired reader (#167, #173). */
+export declare function readLivePlatformResources(readers: PlatformLiveReaders): Promise<LiveResource[]>;

package/dist/plan/live.js

@@ -10,3 +10,11 @@ export async function readLiveResources(orgId, readers) {
     ]);
     return [...zitadel, ...coolify, ...cloudflare, ...files, ...ai, ...cms];
 }
+/** Every live resource foundry can see for the platform, across every wired reader (#167, #173). */
+export async function readLivePlatformResources(readers) {
+    const [cloudflare, coolify] = await Promise.all([
+        readers.cloudflare.listResources(),
+        readers.coolify ? readers.coolify.listResources() : Promise.resolve([]),
+    ]);
+    return [...cloudflare, ...coolify];
+}

package/dist/plan/mail-copy.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Copies an org's old mail into Stalwart before its `received` -> `hosted`
+ * MX cutover (#113), using `@wtfalch/email/postmaster`'s `mailCopyPlan` to
+ * build the exact Vandelay `import`/`export` commands and nothing more --
+ * this module decides when to run them and what to do with the result, the
+ * same split `calls-sfu.ts` draws between a pure plan builder and the apply
+ * logic around it.
+ *
+ * Three things this step needs and never invents itself, mirroring
+ * `plan/platform-sfu.ts`'s own "a host supplies real clients" rule:
+ *
+ * - {@link MailCopyPort.resolveAccounts}: which accounts to copy, and where
+ *   each one's mail lands in Stalwart. Foundry tracks only an org's owner
+ *   mailbox (`org.mail.ownerMailboxAddress`) -- it has no roster of every
+ *   mailbox a Google Workspace or Microsoft 365 tenant holds, so the full
+ *   list is a fact a human supplies, read back here exactly the way a held
+ *   SSH key or API credential already is elsewhere in this package.
+ * - {@link MailCopyPort.resolveSourceToken}: the org's own admin bearer
+ *   token for its old provider, a per-org held key (#113 "Decided",
+ *   2026-09-30) -- never an environment variable this package sets itself.
+ * - {@link MailCopyPort.resolveStalwartToken}: the platform's own Stalwart
+ *   export credential (the admin key `impersonate` already covers,
+ *   `plan/platform-providers.ts`'s `provisionPlatformMail`), read back by
+ *   the host rather than minted again here.
+ *
+ * {@link MailCopyPort.run} is the fourth port: running one Vandelay command
+ * to completion in a one-off container (#113 "Decided": Coolify) and
+ * reporting how it went. Never throws on a non-zero exit -- the caller
+ * checks `exitCode`, the same "write a file, run a command, the caller
+ * checks it" shape `CallsSfuHostPort.exec` already uses, for the same
+ * reason: every value a real implementation might echo into stdout/stderr
+ * is the host's to redact, never this function's problem.
+ *
+ * **No new step type.** #113's first decision (2026-09-30) asked for a
+ * resumable step type of its own; the second (2026-10-01) replaced it with
+ * "keep foundry's one step contract": this step runs once per `apply`, the
+ * same as every other, and resumes only because `runMailCopyStep` is
+ * idempotent -- skip an account already recorded done, stop at the first
+ * one that fails this round, and let the *planner* (`plan/diff.ts`'s
+ * `planMailCopy`) decide whether to show the step again next time. "Rely on
+ * Vandelay's own rate limit for the Gmail daily cap" (#113 "Decided") means
+ * this function never inspects *why* an account failed -- a provider's
+ * daily transfer cap and a real failure look the same from here, so it
+ * always just stops and lets the next apply retry, rather than guessing.
+ */
+import type { MailCopyAccount, MailCopyProvider } from '@wtfalch/email/postmaster';
+import type { DeclaredOrg } from '../org.js';
+/** Scope id: a JSON array of account `source` addresses already fully copied for this org. Read by `plan/diff.ts`'s `planMailCopy` to report progress, and by `executor.ts`'s `mailCopy` to skip a finished account on the next apply. */
+export declare const MAIL_COPY_COMPLETED_SCOPE_KEY = "mail_copy_completed_accounts";
+/** Scope id: set to `'1'` once every account in the resolved plan has copied cleanly. `plan/diff.ts`'s `planMail` gates the `received` -> `hosted` mode flip on this being set. */
+export declare const MAIL_COPY_DONE_SCOPE_KEY = "mail_copy_done";
+/**
+ * Parses {@link MAIL_COPY_COMPLETED_SCOPE_KEY}'s recorded value back into
+ * the set of account addresses already copied. `[]` for anything that is
+ * not a JSON array of strings -- absent, corrupt, or a shape from before
+ * this existed -- the same "a malformed record reads as unapplied, never
+ * throws" rule `platform-diff.ts`'s `parseBrokerDeployRecord` already
+ * follows, and for the same reason: this is a planning read, not a
+ * validation boundary.
+ */
+export declare function parseMailCopyCompleted(raw: string | undefined): string[];
+/**
+ * Everything {@link mailCopyPlan} needs beyond the provider: the resolved
+ * account list and their Vandelay target mapping, the Stalwart JMAP base
+ * URL, and the archive directory the one-off container keeps its Vandelay
+ * SQLite archives in between runs (the host's own choice -- it also
+ * implements {@link MailCopyPort.run}, so it alone knows where that
+ * container's persistent storage is mounted).
+ */
+export interface MailCopyJob {
+    readonly provider: MailCopyProvider;
+    readonly accounts: readonly MailCopyAccount[];
+    readonly stalwartUrl: string;
+    readonly archiveDir: string;
+}
+export interface MailCopyPort {
+    /** `null` until a human has declared this org's accounts (#113's own "Decide" is silent on how; this package never guesses a roster). */
+    resolveAccounts(org: DeclaredOrg): Promise<MailCopyJob | null>;
+    /** `null` until a human has stored this org's admin token as a held key. */
+    resolveSourceToken(org: DeclaredOrg): Promise<string | null>;
+    /** `null` until the platform's own Stalwart export credential is held. */
+    resolveStalwartToken(): Promise<string | null>;
+    /** Runs one Vandelay command (`accountPlan.importArgv`/`exportArgv`) to completion, `VANDELAY_TOKEN` set to `token` for that one launch. */
+    run(argv: readonly string[], token: string): Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
+}
+export declare class MissingMailCopyAccountsError extends Error {
+    constructor(orgSlug: string);
+}
+export declare class MissingMailCopySourceTokenError extends Error {
+    constructor(orgSlug: string);
+}
+export declare class MissingMailCopyStalwartTokenError extends Error {
+    constructor(orgSlug: string);
+}
+export interface MailCopyStepResult {
+    /** Every account copied so far, this apply's newly-finished ones included -- what the executor records under {@link MAIL_COPY_COMPLETED_SCOPE_KEY}. */
+    readonly completed: readonly string[];
+    /** `true` once the job names at least one account and every one of them has copied cleanly. */
+    readonly done: boolean;
+    /** Why this apply stopped early, absent when nothing failed. */
+    readonly failure?: MailCopyFailure;
+}
+/** The account and phase a copy stopped at, and what Vandelay said -- never a token. */
+export interface MailCopyFailure {
+    readonly account: string;
+    readonly phase: 'import' | 'export';
+    /** Absent when `port.run` threw instead of returning an exit code. */
+    readonly exitCode?: number;
+    /** The last {@link STDERR_TAIL_LENGTH} characters of stderr (or the thrown error's message), with both tokens replaced. */
+    readonly detail: string;
+}
+/**
+ * Runs this apply's share of one org's mail copy: resolve the job and its
+ * credentials, skip whatever {@link alreadyCompleted} already names, then
+ * import and export each remaining account in turn, stopping at the first
+ * one that fails (import or export) rather than guessing whether that is a
+ * provider's daily cap or a real problem. Never throws for a Vandelay
+ * failure -- only for a missing port answer, which is a configuration gap,
+ * not something a retry fixes on its own.
+ */
+export declare function runMailCopyStep(org: DeclaredOrg, port: MailCopyPort, alreadyCompleted: ReadonlySet<string>): Promise<MailCopyStepResult>;

package/dist/plan/mail-copy.js

@@ -0,0 +1,166 @@
+/**
+ * Copies an org's old mail into Stalwart before its `received` -> `hosted`
+ * MX cutover (#113), using `@wtfalch/email/postmaster`'s `mailCopyPlan` to
+ * build the exact Vandelay `import`/`export` commands and nothing more --
+ * this module decides when to run them and what to do with the result, the
+ * same split `calls-sfu.ts` draws between a pure plan builder and the apply
+ * logic around it.
+ *
+ * Three things this step needs and never invents itself, mirroring
+ * `plan/platform-sfu.ts`'s own "a host supplies real clients" rule:
+ *
+ * - {@link MailCopyPort.resolveAccounts}: which accounts to copy, and where
+ *   each one's mail lands in Stalwart. Foundry tracks only an org's owner
+ *   mailbox (`org.mail.ownerMailboxAddress`) -- it has no roster of every
+ *   mailbox a Google Workspace or Microsoft 365 tenant holds, so the full
+ *   list is a fact a human supplies, read back here exactly the way a held
+ *   SSH key or API credential already is elsewhere in this package.
+ * - {@link MailCopyPort.resolveSourceToken}: the org's own admin bearer
+ *   token for its old provider, a per-org held key (#113 "Decided",
+ *   2026-09-30) -- never an environment variable this package sets itself.
+ * - {@link MailCopyPort.resolveStalwartToken}: the platform's own Stalwart
+ *   export credential (the admin key `impersonate` already covers,
+ *   `plan/platform-providers.ts`'s `provisionPlatformMail`), read back by
+ *   the host rather than minted again here.
+ *
+ * {@link MailCopyPort.run} is the fourth port: running one Vandelay command
+ * to completion in a one-off container (#113 "Decided": Coolify) and
+ * reporting how it went. Never throws on a non-zero exit -- the caller
+ * checks `exitCode`, the same "write a file, run a command, the caller
+ * checks it" shape `CallsSfuHostPort.exec` already uses, for the same
+ * reason: every value a real implementation might echo into stdout/stderr
+ * is the host's to redact, never this function's problem.
+ *
+ * **No new step type.** #113's first decision (2026-09-30) asked for a
+ * resumable step type of its own; the second (2026-10-01) replaced it with
+ * "keep foundry's one step contract": this step runs once per `apply`, the
+ * same as every other, and resumes only because `runMailCopyStep` is
+ * idempotent -- skip an account already recorded done, stop at the first
+ * one that fails this round, and let the *planner* (`plan/diff.ts`'s
+ * `planMailCopy`) decide whether to show the step again next time. "Rely on
+ * Vandelay's own rate limit for the Gmail daily cap" (#113 "Decided") means
+ * this function never inspects *why* an account failed -- a provider's
+ * daily transfer cap and a real failure look the same from here, so it
+ * always just stops and lets the next apply retry, rather than guessing.
+ */
+import { mailCopyPlan } from '@wtfalch/email/postmaster';
+/** Scope id: a JSON array of account `source` addresses already fully copied for this org. Read by `plan/diff.ts`'s `planMailCopy` to report progress, and by `executor.ts`'s `mailCopy` to skip a finished account on the next apply. */
+export const MAIL_COPY_COMPLETED_SCOPE_KEY = 'mail_copy_completed_accounts';
+/** Scope id: set to `'1'` once every account in the resolved plan has copied cleanly. `plan/diff.ts`'s `planMail` gates the `received` -> `hosted` mode flip on this being set. */
+export const MAIL_COPY_DONE_SCOPE_KEY = 'mail_copy_done';
+/**
+ * Parses {@link MAIL_COPY_COMPLETED_SCOPE_KEY}'s recorded value back into
+ * the set of account addresses already copied. `[]` for anything that is
+ * not a JSON array of strings -- absent, corrupt, or a shape from before
+ * this existed -- the same "a malformed record reads as unapplied, never
+ * throws" rule `platform-diff.ts`'s `parseBrokerDeployRecord` already
+ * follows, and for the same reason: this is a planning read, not a
+ * validation boundary.
+ */
+export function parseMailCopyCompleted(raw) {
+    if (!raw)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed) || !parsed.every((v) => typeof v === 'string'))
+        return [];
+    return parsed;
+}
+export class MissingMailCopyAccountsError extends Error {
+    constructor(orgSlug) {
+        super(`coolify:mail-copy for ${orgSlug}: no accounts are declared for this org's mail copy yet (#113)`);
+        this.name = 'MissingMailCopyAccountsError';
+    }
+}
+export class MissingMailCopySourceTokenError extends Error {
+    constructor(orgSlug) {
+        super(`coolify:mail-copy for ${orgSlug}: no admin token is held for this org's old mail provider yet (#113 "Decided", 2026-09-30)`);
+        this.name = 'MissingMailCopySourceTokenError';
+    }
+}
+export class MissingMailCopyStalwartTokenError extends Error {
+    constructor(orgSlug) {
+        super(`coolify:mail-copy for ${orgSlug}: no Stalwart export credential is held yet`);
+        this.name = 'MissingMailCopyStalwartTokenError';
+    }
+}
+const STDERR_TAIL_LENGTH = 500;
+/** Replaces every occurrence of each token, then keeps the tail: a real implementation may echo `VANDELAY_TOKEN` into stderr, and this must not carry it into a message. */
+function redactTail(text, tokens) {
+    let out = text;
+    for (const token of tokens)
+        out = out.split(token).join('[redacted]');
+    return out.slice(-STDERR_TAIL_LENGTH);
+}
+/**
+ * Runs this apply's share of one org's mail copy: resolve the job and its
+ * credentials, skip whatever {@link alreadyCompleted} already names, then
+ * import and export each remaining account in turn, stopping at the first
+ * one that fails (import or export) rather than guessing whether that is a
+ * provider's daily cap or a real problem. Never throws for a Vandelay
+ * failure -- only for a missing port answer, which is a configuration gap,
+ * not something a retry fixes on its own.
+ */
+export async function runMailCopyStep(org, port, alreadyCompleted) {
+    const job = await port.resolveAccounts(org);
+    if (!job)
+        throw new MissingMailCopyAccountsError(org.slug);
+    const sourceToken = await port.resolveSourceToken(org);
+    if (!sourceToken)
+        throw new MissingMailCopySourceTokenError(org.slug);
+    const stalwartToken = await port.resolveStalwartToken();
+    if (!stalwartToken)
+        throw new MissingMailCopyStalwartTokenError(org.slug);
+    const plan = mailCopyPlan({
+        provider: job.provider,
+        accounts: job.accounts,
+        stalwartUrl: job.stalwartUrl,
+        archiveDir: job.archiveDir,
+    });
+    const tokens = [sourceToken, stalwartToken];
+    const completed = new Set(alreadyCompleted);
+    let failure;
+    for (const accountPlan of plan.accounts) {
+        if (completed.has(accountPlan.source))
+            continue;
+        const phases = [
+            { phase: 'import', argv: accountPlan.importArgv, token: sourceToken },
+            { phase: 'export', argv: accountPlan.exportArgv, token: stalwartToken },
+        ];
+        for (const { phase, argv, token } of phases) {
+            try {
+                const ran = await port.run(argv, token);
+                if (ran.exitCode !== 0) {
+                    failure = {
+                        account: accountPlan.source,
+                        phase,
+                        exitCode: ran.exitCode,
+                        detail: redactTail(ran.stderr, tokens),
+                    };
+                }
+            }
+            catch (error) {
+                // A thrown run is a failed run: stop here, but keep what this apply finished.
+                failure = {
+                    account: accountPlan.source,
+                    phase,
+                    detail: redactTail(error instanceof Error ? error.message : String(error), tokens),
+                };
+            }
+            if (failure)
+                break;
+        }
+        if (failure)
+            break;
+        completed.add(accountPlan.source);
+    }
+    // `completed` may still hold a stale address no longer in the plan, so
+    // done is checked against the plan's own accounts, never `completed.size`.
+    const done = plan.accounts.length > 0 && plan.accounts.every((account) => completed.has(account.source));
+    return { completed: [...completed], done, ...(failure ? { failure } : {}) };
+}

package/dist/plan/mail-identity-allowlist.d.ts

@@ -0,0 +1,50 @@
+/**
+ * #34: a matching `requireAudience` value says nothing about *who* carries
+ * it.
+ *
+ * ZITADEL puts a project's own id into the default audience of any sign-in
+ * to that project, so every JWT app in the org's audience project mints a
+ * token Stalwart's OIDC directory accepts, whether or not that app has
+ * anything to do with mail. Two real instances were found by hand rather
+ * than by any check: `manage` shared the audience project and its sign-in
+ * tokens opened the signed-in person's mailbox until it moved to its own
+ * project (wtfalch/agora#100); `operator` was added to the same project
+ * later and has the same hole today (wtfalch/operator#11).
+ *
+ * {@link checkMailAppsAllowlist} faults on every JWT app in the audience
+ * project that is not on the org's own declared allow-list, naming the app
+ * and its client id -- the same way `org.ts`'s validators name the value
+ * they refuse. Decided by William (2026-09-30): only listed apps may read
+ * a person's mail; each org's declared config holds its own list
+ * ({@link MailConfig.mailApps} in `../org.js`, defaulting to
+ * {@link DEFAULT_MAIL_APPS} when the org declares none of its own).
+ *
+ * An exported pure function, the same "host calls it" shape #33's
+ * `checkMailIdentityAudience` (`./mail-identity.js`) takes. This module
+ * declares its own narrow app shape rather than importing that one's, so
+ * the two land independently of each other -- a host composing both checks
+ * adapts the same live app list to each. Deliberately silent on
+ * opaque-token apps: #33's check already names those on its own, and an
+ * app this function cannot classify is reported separately rather than
+ * folded into either list.
+ */
+export interface MailAllowlistApp {
+    /** ZITADEL's own app id. */
+    id: string;
+    /** The OIDC client id ZITADEL issued -- what a fault names, never a secret. */
+    clientId: string;
+    name: string;
+    /**
+     * How ZITADEL mints this app's access token. `undefined` means unknown
+     * (an `api` app, or a caller that cannot yet tell) and is never treated
+     * as `'jwt'` -- an app this function cannot classify as a JWT app is
+     * never faulted as an unlisted one.
+     */
+    accessTokenType?: 'jwt' | 'opaque';
+}
+/**
+ * Faults on every JWT app in `apps` that is not on `declaredMailApps`,
+ * naming the app and its client id. Empty means every JWT app the audience
+ * project holds is on the list (or there are no JWT apps at all).
+ */
+export declare function checkMailAppsAllowlist(apps: readonly MailAllowlistApp[], declaredMailApps: readonly string[]): string[];

package/dist/plan/mail-identity-allowlist.js

@@ -0,0 +1,11 @@
+/**
+ * Faults on every JWT app in `apps` that is not on `declaredMailApps`,
+ * naming the app and its client id. Empty means every JWT app the audience
+ * project holds is on the list (or there are no JWT apps at all).
+ */
+export function checkMailAppsAllowlist(apps, declaredMailApps) {
+    const allowed = new Set(declaredMailApps);
+    return apps
+        .filter((app) => app.accessTokenType === 'jwt' && !allowed.has(app.name))
+        .map((app) => `${app.name} (${app.clientId}) is not on the declared mail-apps list but mints a JWT Stalwart's audience rule accepts`);
+}