@wtfalch/foundry 0.5.0 → 0.6.0

package/dist/plan/diff.js

@@ -1,4 +1,5 @@
 import { NO_AGORA_HOST_VALUES, agoraEnvDrift, agoraHostMissing, desiredAgoraEnv, } from './agora.js';
+import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, } from './mail-copy.js';
 import { ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, } from './platform-diff.js';
 import { DEFAULT_ORG_PLATFORM_READINESS } from './platform-org.js';
 /** The `Plan` (#19's public contract) a `PlanDetail` carries. */
@@ -73,6 +74,9 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const mail = planMail(org, byKey, claimed, recordedIds, platformReadiness.mailHost);
     if (mail.step)
         plannedSteps.push(mail.step);
+    const mailCopy = planMailCopy(org, byKey, recordedIds);
+    if (mailCopy)
+        plannedSteps.push(mailCopy);
     const chat = planChat(org, byKey, claimed);
     if (chat)
         plannedSteps.push(chat);
@@ -197,6 +201,11 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         unmanaged.push({ description: issuer.blocked, key: 'zitadel:issuer' });
     if (mail.blocked)
         unmanaged.push({ description: mail.blocked, key: 'coolify:mail' });
+    // #162: reported separately from `mail.blocked` -- missing an owner
+    // mailbox address never blocks the rest of this org's mail.
+    if (mail.mailboxBlocked) {
+        unmanaged.push({ description: mail.mailboxBlocked, key: 'coolify:mail:owner-mailbox' });
+    }
     if (calls.blocked)
         unmanaged.push({ description: calls.blocked, key: 'coolify:calls' });
     if (filesOrganisation.blocked) {
@@ -353,6 +362,10 @@ function planOwner(org, recordedIds, authReady) {
  * `LOG_DIR` precedent follows for a value shared with `executor.ts`.
  */
 const MAIL_OWNER_MAILBOX_SCOPE_KEY = 'mail_owner_mailbox';
+/** #230: restated from `executor.ts`'s `MAIL_ROLE_MAILBOXES_SCOPE_KEY`, same rule: comma-joined local parts already created. */
+const MAIL_ROLE_MAILBOXES_SCOPE_KEY = 'mail_role_mailboxes';
+/** Restated from `executor.ts`, the same rule: the mail domain the last apply resolved. */
+const MAIL_DOMAIN_SCOPE_KEY = 'mail_domain';
 /** Restated from `executor.ts`, the same rule: the id of an ai key minted but not delivered. */
 export const AI_KEY_UNDELIVERED_SCOPE_KEY = 'ai_key_undelivered';
 /** Restated from `executor.ts`, the same rule: the id of a jobs project registered but not delivered. */
@@ -376,13 +389,14 @@ function planMail(org, byKey, claimed, recordedIds, mailHost) {
     // after having it would silently hide its own leftover mail resource from
     // the unmanaged list.
     if (org.mail.mode === 'off')
-        return { step: null, blocked: null };
+        return { step: null, blocked: null, mailboxBlocked: null };
     if (live)
         claimed.add(key);
     if (!mailHost) {
         return {
             step: null,
             blocked: `${org.slug}'s mail is blocked, not planned: the platform's mail server is off or not yet applied`,
+            mailboxBlocked: null,
         };
     }
     const desired = {
@@ -391,12 +405,33 @@ function planMail(org, byKey, claimed, recordedIds, mailHost) {
         apex: mailHost.apex,
         mailHost: mailHost.mailHost,
     };
-    // #162: an owner's mailbox is minted inside the same `coolify:mail` step,
-    // after `applyOrgMail` -- so as long as one is still owed, this step must
-    // keep showing up even once mode/usesDomain themselves have nothing left
-    // to change, or the operator would apply and never see it happen.
-    const mailboxOwed = Boolean(org.owner) && !recordedIds[MAIL_OWNER_MAILBOX_SCOPE_KEY];
-    const mailboxNote = mailboxOwed ? ` and give ${org.slug}'s owner a mailbox` : '';
+    // #162 (decided 2026-09-29): an owner's mailbox is minted inside the same
+    // `coolify:mail` step, after `applyOrgMail` -- so as long as one is still
+    // owed, this step must keep showing up even once mode/usesDomain
+    // themselves have nothing left to change, or the operator would apply and
+    // never see it happen. Nothing is guessed any more: without a declared
+    // `mail.ownerMailboxAddress`, the mailbox alone is reported blocked below
+    // (`mailboxBlocked`), the same "blocked, not planned" pattern a blocked
+    // Agora already follows (PR 180) -- the rest of this step, and every
+    // other step in the org's plan, is unaffected.
+    const mailboxAlreadyGiven = Boolean(recordedIds[MAIL_OWNER_MAILBOX_SCOPE_KEY]);
+    const hasOwner = Boolean(org.owner);
+    const ownerMailboxAddress = org.mail.ownerMailboxAddress ?? null;
+    const mailboxBlocked = hasOwner && !mailboxAlreadyGiven && !ownerMailboxAddress
+        ? `${org.slug}'s owner mailbox is blocked, not planned: mail.ownerMailboxAddress is not declared`
+        : null;
+    const mailboxOwed = hasOwner && !mailboxAlreadyGiven && ownerMailboxAddress !== null;
+    // #230: declared role mailboxes not yet recorded as created. Names only
+    // ever count here, never appear in a description, same as the owner's address.
+    // Recorded per address, so a changed mail domain owes its own set. A hosted
+    // org's domain is only known once recorded; until then every role is owed.
+    const createdRoles = new Set((recordedIds[MAIL_ROLE_MAILBOXES_SCOPE_KEY] ?? '').split(','));
+    const roleDomain = (org.mail.usesDomain && org.domain) || recordedIds[MAIL_DOMAIN_SCOPE_KEY];
+    const rolesOwed = (org.mail.roleMailboxes ?? []).filter((r) => !roleDomain || !createdRoles.has(`${r}@${roleDomain}`.toLowerCase())).length;
+    const ownerNote = mailboxOwed ? `give ${org.slug}'s owner a mailbox` : '';
+    const roleNote = rolesOwed > 0 ? `create ${rolesOwed} role mailbox(es) for ${org.slug}` : '';
+    const mailboxWork = [ownerNote, roleNote].filter(Boolean).join(' and ');
+    const mailboxNote = mailboxWork ? ` and ${mailboxWork}` : '';
     if (!live) {
         return {
             step: {
@@ -408,6 +443,7 @@ function planMail(org, byKey, claimed, recordedIds, mailHost) {
                 },
             },
             blocked: null,
+            mailboxBlocked,
         };
     }
     const liveMode = live.config.mode;
@@ -417,20 +453,21 @@ function planMail(org, byKey, claimed, recordedIds, mailHost) {
         // them (or it never recorded them). Re-applying is idempotent.
         const addressMoved = recordedIds[ORG_MAIL_APPLIED_APEX_SCOPE_KEY] !== mailHost.apex ||
             recordedIds[ORG_MAIL_APPLIED_HOST_SCOPE_KEY] !== mailHost.mailHost;
-        if (!mailboxOwed && !addressMoved)
-            return { step: null, blocked: null };
+        if (!mailboxWork && !addressMoved)
+            return { step: null, blocked: null, mailboxBlocked };
         return {
             step: {
                 action: { system: 'coolify', kind: 'mail', key: org.id, desired },
                 step: {
                     description: addressMoved
                         ? `re-apply ${org.slug}'s mail on the platform's mail host ${mailHost.mailHost}${mailboxNote}`
-                        : `give ${org.slug}'s owner a mailbox`,
+                        : mailboxWork,
                     destroys: false,
                     migrates: false,
                 },
             },
             blocked: null,
+            mailboxBlocked,
         };
     }
     if (liveUsesDomain && !desired.usesDomain) {
@@ -446,6 +483,21 @@ function planMail(org, byKey, claimed, recordedIds, mailHost) {
                 },
             },
             blocked: null,
+            mailboxBlocked,
+        };
+    }
+    // #113: moving from `received` to `hosted` is an MX cutover, and foundry
+    // never cuts over before an org's old mail has copied into Stalwart --
+    // `planMailCopy`'s own step is what runs that copy. Blocked, not planned,
+    // the same "withhold the step rather than apply it half-ready" rule
+    // `mailboxBlocked` already follows just above.
+    if (liveMode === 'received' &&
+        desired.mode === 'hosted' &&
+        !recordedIds[MAIL_COPY_DONE_SCOPE_KEY]) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s mail cannot move to hosted yet: its old mail is still being copied into Stalwart (coolify:mail-copy, #113)`,
+            mailboxBlocked,
         };
     }
     // A mode transition (#7 "Transitions") or turning a domain on is a
@@ -460,6 +512,37 @@ function planMail(org, byKey, claimed, recordedIds, mailHost) {
             },
         },
         blocked: null,
+        mailboxBlocked,
+    };
+}
+/**
+ * #113: the one-time copy of an org's old mail into Stalwart that must
+ * finish before `planMail` allows the `received` -> `hosted` MX cutover
+ * above. Planned only for that exact transition -- a fresh org declared
+ * `hosted` from the start, or one moving between any other pair of modes,
+ * has nothing to migrate from and never sees this step. Never matched
+ * against a live resource: like `platform-diff.ts`'s `planSfu`, there is no
+ * live state to probe here (`runMailCopyStep`'s own progress is recorded
+ * state, not something a reader lists), so this plans again on every apply
+ * until {@link MAIL_COPY_DONE_SCOPE_KEY} is recorded.
+ */
+function planMailCopy(org, byKey, recordedIds) {
+    if (org.mail.mode !== 'hosted')
+        return null;
+    if (recordedIds[MAIL_COPY_DONE_SCOPE_KEY])
+        return null;
+    const live = byKey.get(resourceKey('coolify', 'mail', org.id));
+    if (!live || live.config.mode !== 'received')
+        return null;
+    const completed = parseMailCopyCompleted(recordedIds[MAIL_COPY_COMPLETED_SCOPE_KEY]);
+    const progress = completed.length > 0 ? ` (${completed.length} account(s) already copied)` : '';
+    return {
+        action: { system: 'coolify', kind: 'mail-copy', key: org.id, desired: {} },
+        step: {
+            description: `copy ${org.slug}'s old mail into Stalwart before the MX cutover${progress} -- re-apply again to continue, or tomorrow if a provider's daily limit was hit`,
+            destroys: false,
+            migrates: false,
+        },
     };
 }
 function planChat(org, byKey, claimed) {

package/dist/plan/executor.d.ts

@@ -2,6 +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 { StepAction } from './diff.js';
+import { type MailCopyPort } from './mail-copy.js';
 import type { DestroyTarget, StepDestroyer, StepExecutionContext, StepExecutor } from './plan-apply.js';
 /**
  * The real {@link StepExecutor} (#20 "provision Company Factory end to
@@ -504,35 +505,65 @@ export interface MailPort {
      * `createMailbox`, resolving `org`'s domain to a `domainId` the same way
      * `applyOrgMail` does -- that function already refuses a duplicate `local`
      * on the resolved domain, so this port method never has to. `ensureOwnerMailbox`
-     * below is this executor's one caller, and it checks its own recorded scope
+     * and `ensureRoleMailboxes` (#230) below are this executor's callers, and each checks its own recorded scope
      * id first, so a second apply never calls this at all.
      */
     createMailbox(org: OrgMailOrg, mailbox: {
         address: string;
         name: string;
     }): Promise<void>;
+    /**
+     * Upserts this org's own outbound relay route on Stalwart (#149): an
+     * `MtaRoute` through Lettermint, restricted to `org`'s domain, keyed by
+     * `org.slug` -- the host implements this with `@wtfalch/email/postmaster`'s
+     * own `applyOrgRelay` (https://github.com/wtfalch/email/issues/118), which
+     * rebuilds the shared routing expression so two orgs' routes never
+     * collide. `secret` is the Lettermint project token this executor just
+     * minted (`ensureOrgLettermintRelay`'s own mint rule) -- it goes straight
+     * here and nowhere else: never returned, never recorded, never logged, the
+     * same discipline `ensureAppLettermintMail`'s own doc comment states for
+     * `LETTERMINT_API_TOKEN`.
+     */
+    applyOrgRelay(org: OrgMailOrg, secret: string): Promise<void>;
+    /**
+     * Drops this org's relay route (#149), implemented with
+     * `@wtfalch/email/postmaster`'s own `removeOrgRelay` -- a missing route is
+     * a no-op, so `parkLettermintMail` can call this unconditionally before it
+     * deletes the Lettermint project the route pointed at.
+     */
+    removeOrgRelay(org: OrgMailOrg): Promise<void>;
+    /**
+     * True once this org's relay route exists on Stalwart with a secret set
+     * (#149). `ensureOrgLettermintRelay`'s own mint rule reads this alongside
+     * Lettermint's own project listing: a project without a live route (the
+     * route recorded a token this executor never minted) is exactly as
+     * unhealthy as a route with no project behind it, so a fresh mint fixes
+     * either.
+     */
+    hasOrgRelay(org: OrgMailOrg): Promise<boolean>;
 }
 /**
- * The shared calls SFU's own LiveKit API credentials (#122, #127, #145).
- * Before #170, a human minted this pair by hand and `resolveCredentials`
- * read wherever `scripts/calls-sfu-deploy.mjs`'s own `CallsSfuConfig`
- * delivered it from -- this package never minted or invented a LiveKit
- * key/secret pair itself.
+ * The shared calls SFU's own per-org LiveKit API credentials (#122, #127,
+ * #145, #152). Before #170, a human minted one pair by hand, shared by every
+ * org, and `resolveCredentials` read wherever `scripts/calls-sfu-deploy.mjs`'s
+ * own `CallsSfuConfig` delivered it from -- this package never minted or
+ * invented a LiveKit key/secret pair itself.
  *
  * As of #170 the platform's own `sfu:livekit` step
- * (`plan/platform-sfu.ts`'s `applyCallsSfuPlatformStep`) mints the pair, the
- * first time it applies, and delivers it to held keys through
- * `CallsSfuKeysPort.deliverLivekitKeys`. `resolveCredentials` reads that same
+ * (`plan/platform-sfu.ts`'s `applyCallsSfuPlatformStep`) mints the pair, and
+ * as of #152 it mints one *per org*, the first time that org applies, and
+ * delivers it to held keys through `CallsSfuKeysPort.deliverLivekitKeys`,
+ * keyed by the org's slug. `resolveCredentials` reads a specific org's own
  * held-keys entry back -- still resolved by the host (archon), never minted
  * or read directly by this port itself, the same "the executor is
  * constructed with narrow ports ... a host supplies real clients" rule this
  * file's own top doc comment states for every provider credential.
  * `resolveCredentials` returns `null` before the platform's `sfu` step has
- * ever applied, the same "nothing recorded" signal a bare
+ * ever applied for that org, the same "nothing recorded" signal a bare
  * `CoolifyPort.listEnvs` gives `ensureCallsMatrixSecrets`.
  */
 export interface CallsSfuPort {
-    resolveCredentials(): Promise<{
+    resolveCredentials(orgSlug: string): Promise<{
         apiKey: string;
         apiSecret: string;
     } | null>;
@@ -664,6 +695,77 @@ export interface ZitadelPort {
         userId: string;
         token: string;
     }>;
+    /**
+     * #216 (building on #209/#215): mints a second, narrower machine user on
+     * the same instance, with only the `IAM_LOGIN_CLIENT` role -- never
+     * `IAM_OWNER`, which {@link mintAdminMachineUser} already covers and which
+     * this method must not reuse or grant in addition. The login app and the
+     * broker both refuse to start without this token
+     * (`platform-providers.ts`'s `provisionPlatformAuth`, "Known gaps").
+     *
+     * Idempotent on the user by `userName`, like {@link mintAdminMachineUser},
+     * but never on the token the same way: ZITADEL shows a PAT's value once,
+     * and a crash or a failed delivery between a prior mint and the caller
+     * recording it would otherwise leave that lost token live forever. Unlike
+     * {@link mintAdminMachineUser}, revoking this user's PAT destroys nothing
+     * -- nothing else was ever encrypted with it, the way ZITADEL's own
+     * masterkey protects the admin path's data -- so a real implementation
+     * lists and deletes every PAT this user already holds before minting a
+     * fresh one, leaving exactly one live token no matter how many times this
+     * is called for the same user. This is what lets the caller
+     * (`provisionPlatformAuth`) simply re-mint on every rerun until delivery
+     * succeeds, rather than blocking forever the way an undelivered admin key
+     * does.
+     *
+     * Refuses (a named error, never a silent reuse) when a `foundry-login-client`
+     * user already exists with any IAM role other than exactly
+     * `IAM_LOGIN_CLIENT` -- that user was not created by this method, and
+     * granting it an additional role, or reusing its PAT, would widen access
+     * this caller never asked for.
+     *
+     * #216 round 2: also returns `patId`, the minted PAT's own id, so the
+     * caller can hand it to {@link listLoginClientPats} after delivering the
+     * token and confirm nothing else revoked or replaced it in the meantime.
+     *
+     * #216 (third PR review): also returns `revokedPriorPat`, true exactly
+     * when a live PAT existed on this user and was revoked before this mint --
+     * never true on a first-ever mint, where nothing was live to revoke. The
+     * caller uses this to word a delivery-failure error correctly: on a
+     * re-mint the login app and broker are left with no live token at all
+     * (the old one is already gone); on a first mint they simply never had one
+     * yet.
+     */
+    mintLoginClientMachineUser(orgId: string, input: {
+        userName: string;
+        name: string;
+    }): Promise<{
+        userId: string;
+        token: string;
+        patId: string;
+        revokedPriorPat: boolean;
+    }>;
+    /**
+     * #216 round 2: every live PAT id on the `foundry-login-client` machine
+     * user, read straight from ZITADEL. `provisionPlatformAuth`
+     * (`platform-providers.ts`) calls this right after it delivers a freshly
+     * minted token to the login app and the broker, to close a race two
+     * concurrent applies can otherwise hit: run A mints token a and is about to
+     * deliver it; run B's own mint (`mintLoginClientMachineUser`, idempotent on
+     * the same `userName`) revokes a and mints token b first; run A then
+     * delivers the now-revoked a and would, without this check, still record
+     * success. Expecting the result to be exactly `[patId]` (the id
+     * {@link mintLoginClientMachineUser} returned) catches that: anything else
+     * means some other mint ran in between, so this run must fail rather than
+     * record delivery, leaving the next apply to re-mint and re-deliver.
+     *
+     * #216 round 3: a single call made once, after every write, cannot catch a
+     * write that lands after it -- `provisionPlatformAuth` now calls this
+     * again immediately before each individual write (each retry attempt of
+     * each of the login app's env, the broker's env, and each app's deploy),
+     * not only once at the end, so a write about to deliver a token this call
+     * reports no longer live is never attempted at all.
+     */
+    listLoginClientPats(orgId: string, userId: string): Promise<string[]>;
 }
 /**
  * Provisions one org's organisation on Files (#80), matching
@@ -839,6 +941,15 @@ export interface FoundryStepExecutorPorts {
     jobsScheduler?: JobsSchedulerPort;
     /** The shared calls SFU's own LiveKit credentials (#145) -- see {@link CallsSfuPort}'s own doc comment. */
     callsSfu: CallsSfuPort;
+    /**
+     * #113: the org's old-mail copy into Stalwart, ahead of a `received` ->
+     * `hosted` MX cutover -- see {@link MailCopyPort}'s own doc comment.
+     * Optional the same way `jobsScheduler` is: a host that never runs this
+     * transition builds the executor without it, and `coolify:mail-copy`
+     * throws a clear "not built" error rather than every other step losing
+     * compilation over one dependency nothing else needs.
+     */
+    mailCopy?: MailCopyPort;
     /** 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;
@@ -1033,9 +1144,10 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * `zitadel:issuer` (`AUTH_ORGANIZATION_ID`), `zitadel:owner`
      * (`OWNER_USER_ID`, gap P3) and every `zitadel:app` step
      * (`AUTH_CLIENT_ID`), all ordered before `coolify:app` for exactly this
-     * reason. AUTH_APP_KEY (waits on an auth broker registration API) and
-     * DATABASE_URL_OWNER (a runtime-role split not built yet, `pushDatabaseUrl`'s
-     * own doc comment) are out of scope here (task brief).
+     * reason. `AUTH_APP_KEY` (#206 -- which broker an org's app registers with
+     * is its own design question, left out of #204's own "How" rather than
+     * guessed) and DATABASE_URL_OWNER (a runtime-role split not built yet,
+     * `pushDatabaseUrl`'s own doc comment) are out of scope here (task brief).
      */
     private pushAppEnv;
     /**
@@ -1079,7 +1191,10 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * be deleted.
      *
      * `MAIL_FROM` is upserted every time: it depends only on the mail domain
-     * `coolify:mail` resolved.
+     * `coolify:mail` resolved and `org.mail.noReplyLocalPart` (#162, decided
+     * 2026-09-29 -- defaults to `'no-reply'`, restated here rather than
+     * imported from `org.ts`'s `DEFAULT_NO_REPLY_LOCAL_PART`, this file's own
+     * `LOG_DIR`-style convention).
      *
      * The token goes straight to `bulkUpsertEnvs` and nowhere else: never
      * returned, never recorded in `serviceIds` (`recordScopeId`'s own doc
@@ -1088,6 +1203,63 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * own connection string.
      */
     private ensureAppLettermintMail;
+    /**
+     * #149: mints this org's own Lettermint relay credential and writes it to
+     * Stalwart via `MailPort.applyOrgRelay`, the same mint rule
+     * {@link ensureAppLettermintMail} already uses for the org's app token --
+     * "healthy" means Stalwart's own route exists ({@link MailPort.hasOrgRelay}),
+     * AND Lettermint lists a project named `<slug>-relay` whose id
+     * {@link ORG_MAIL_RELAY_SCOPE_KEY} records for this
+     * exact mail domain (review finding: a route with a secret and a
+     * same-named project both present is not enough -- the project could be a
+     * lost-and-reprovisioned one this step never wrote a route for, and a mail
+     * domain switch must re-point the route rather than read as healthy
+     * forever because the old route still has a secret in it). A route with no
+     * live project behind it, a project the route's own secret never reached,
+     * or a recorded project id/domain that no longer matches, are all exactly
+     * as unhealthy as neither existing.
+     *
+     * A fresh project is created and its token written to Stalwart first, and
+     * only then is every other `<slug>-relay` project deleted -- a lost route
+     * and a duplicate project both end the same way. The new project's domain
+     * restriction runs before the token is written, so a failure there never
+     * touches the working route. Review finding: if either the
+     * domain-restriction step or `applyOrgRelay` throws after a
+     * fresh project was minted, that project is deleted before the error
+     * propagates -- otherwise every retry sees more than one `<slug>-relay`
+     * project and mints yet another one, growing the orphan count without
+     * bound.
+     *
+     * `coolify:mail` runs before `coolify:app` (`diff.ts`'s own step order), so
+     * this is very often the first of the two to reach the org's Lettermint
+     * domain: {@link ensureLettermintDomainRestriction} registers and restricts
+     * 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.
+     */
+    private ensureOrgLettermintRelay;
+    /**
+     * Deletes a just-minted project from inside a `catch`. A failed delete is
+     * dropped so it never replaces the error being rethrown; the orphan is
+     * swept by the next apply's duplicate delete.
+     */
+    private discardLettermintProject;
+    /**
+     * Ensures this org's Lettermint domain exists, is restricted to exactly
+     * the `<slug>-app`/`<slug>-relay` projects live in `allProjects`, has its
+     * DNS published and a verification triggered. Shared by
+     * {@link ensureAppLettermintMail} and {@link ensureOrgLettermintRelay}
+     * (#149) -- whichever of the two steps runs first on a fresh org creates
+     * the domain, and the other then finds it (`findExactLettermintDomain`).
+     *
+     * A crash between the restriction write and the DNS publish/verify below
+     * is safe even for a freshly created domain: DNS is only published, and
+     * verification only triggered, after the restriction -- so an
+     * 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).
+     */
+    private ensureLettermintDomainRestriction;
     /**
      * Review finding (post-#140 rework): {@link LettermintPort.findDomain}'s
      * own match is partial and case-insensitive, so a raw result can be a
@@ -1374,20 +1546,21 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * `@wtfalch/email/postmaster`'s `applyOrgMail`/`parkOrgMail` bound), then
      * publishes whatever Stalwart DNS records the call returns, and records the
      * resolved mail domain as a scope id ({@link MAIL_DOMAIN_SCOPE_KEY}).
-     * 2026-09-28 lettermint-org-mail swap: this step no longer calls the mail
-     * relay provider at all -- registering the domain, restricting it and
-     * publishing its own DNS records all moved to the app step
-     * (`ensureAppLettermintMail`, "Core rule"), since the first project can
-     * only exist once the token has a home. Parking mail (mode `'off'`) does
-     * still reach Lettermint, the one exception: {@link parkLettermintMail}
-     * deletes the org's own projects and then its domain, so a domain never
-     * ends up restricted only to dead projects.
+     *
+     * #149: this step also mints the org's own Lettermint *relay* credential
+     * ({@link ensureOrgLettermintRelay}) -- the app's own *sending* credential
+     * stays in the app step (`ensureAppLettermintMail`, "Core rule"), since the
+     * first app project can only exist once the token has a home. Parking mail
+     * (mode `'off'`) reaches Lettermint too: {@link parkLettermintMail} drops
+     * the relay route, then deletes the org's own projects and its domain, so
+     * a domain never ends up restricted only to dead projects and no route
+     * ever points at a project this apply is about to remove.
      *
      * Review finding: a mail domain switch (`org.domain` changes, or
      * `usesDomain` flips) must also delete the *old* Lettermint domain here,
      * before recording the new one -- otherwise it stays registered and
-     * restricted to the org's still-live `<slug>-app` project, which could
-     * then keep sending as it forever. {@link deleteStaleLettermintDomain}
+     * restricted to the org's still-live `<slug>-app`/`<slug>-relay` projects,
+     * which could then keep sending as it forever. {@link deleteStaleLettermintDomain}
      * does this by comparing the previously recorded domain (case-insensitive)
      * against the one this apply just resolved.
      *
@@ -1397,15 +1570,39 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      */
     private coolifyMail;
     /**
-     * #162: gives the org's declared owner a mailbox on its just-resolved mail
-     * domain, the one address this executor mints on its own
-     * ({@link MAIL_OWNER_LOCAL_PART}'s own doc comment). A no-op when the org
-     * has no owner yet, or once {@link MAIL_OWNER_MAILBOX_SCOPE_KEY} is already
-     * recorded -- checked first so a second apply never calls
-     * `MailPort.createMailbox` again, rather than relying on that port method's
-     * own duplicate refusal.
+     * `plan/diff.ts`'s `planMailCopy` (#113): this apply's share of copying
+     * the org's old mail into Stalwart, via `mail-copy.ts`'s `runMailCopyStep`
+     * -- the only thing this method itself does is read back what the last
+     * apply recorded, hand it to that function, and record what comes back.
+     * An account that failed to copy records the progress made, never
+     * `mail_copy_done`, then throws with the failing account, phase and
+     * redacted stderr tail, so the apply reports it as not done. A missing
+     * `mailCopy` port throws too: a configuration gap a retry cannot fix.
+     */
+    private mailCopy;
+    /**
+     * #162 (decided 2026-09-29): gives the org's declared owner a mailbox at
+     * its declared `mail.ownerMailboxAddress` -- nothing is guessed any more
+     * (the hardcoded `owner@<domain>` PR 163 shipped first is gone). A no-op
+     * when the org has no owner yet, when no address is declared yet
+     * (`plan/diff.ts`'s `planMail` reports that case as blocked, not planned,
+     * so this step's own mode/domain work still runs), or once
+     * {@link MAIL_OWNER_MAILBOX_SCOPE_KEY} is already recorded -- checked last
+     * so a second apply never calls `MailPort.createMailbox` again, rather
+     * than relying on that port method's own duplicate refusal.
      */
     private ensureOwnerMailbox;
+    /**
+     * #230: creates each of the org's declared `mail.roleMailboxes` on its
+     * just-resolved mail domain, once. A role mailbox has no person behind it,
+     * so its display name is just its local part, and like the owner's it is
+     * created with no password: `MailPort.createMailbox` takes none, so there
+     * is no secret to store or print. A "already has a mailbox" refusal from the port counts as created. The created set is recorded under
+     * {@link MAIL_ROLE_MAILBOXES_SCOPE_KEY} after every mailbox, so a second
+     * apply (or a retry after a crash) skips what exists rather than relying
+     * on the mail server's own duplicate refusal.
+     */
+    private ensureRoleMailboxes;
     /**
      * Deletes the org's previous Lettermint domain once the mail domain it was
      * registered under has changed -- otherwise it stays registered and
@@ -1427,9 +1624,13 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     /**
      * Parking mail (2026-09-28 lettermint-org-mail swap, "Core rule": "Parking
      * mail deletes the org's projects and then the domain itself, so no
-     * restriction points only at dead projects"). Deletes every Lettermint
-     * project named `<slug>-app` or `<slug>-relay`, then the org's own
-     * Lettermint domain, if one was found -- in that order, never the reverse.
+     * restriction points only at dead projects"). #149: first drops the
+     * Stalwart relay route with `MailPort.removeOrgRelay` -- a missing route is
+     * a no-op, per that port method's own contract, so this is safe to call
+     * even for an org whose relay was never minted -- then deletes every
+     * Lettermint project named `<slug>-app` or `<slug>-relay`, then the org's
+     * own Lettermint domain, if one was found -- in that order, never the
+     * reverse, so the route is always gone before the project it pointed at.
      * 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.