@wtfalch/foundry 0.5.0 → 0.7.1

package/dist/plan/executor.d.ts

@@ -2,6 +2,8 @@ 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 LoginHostBindingsPort } from './login-host.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
@@ -139,13 +141,14 @@ export interface CoolifyPort {
     }>>;
     /**
      * Upsert environment variables on an application in one call — used here to
-     * push the database's `internal_db_url` in as the app's `DATABASE_URL`
-     * (hosting-wiring campaign), and, for the cms app, its `DATABASE_URL_OWNER`
-     * plus a freshly minted `DATABASE_URL` runtime-role credential (#117). Each
-     * value is a live credential: it must reach this call and nothing else —
-     * never a step's return value, `serviceIds` (hence the store), an audit
-     * record, a log or a thrown error. See `coolifyApp`'s `pushDatabaseUrl` and
-     * `cmsSite`'s `ensureCmsRuntimeUrl`.
+     * push the org's own app's `DATABASE_URL_OWNER` plus a freshly minted
+     * `DATABASE_URL` runtime-role credential (hosting-wiring campaign, split
+     * per #239 the same way #117 already splits the cms app's), and likewise
+     * for the cms app itself. Each value is a live credential: it must reach
+     * this call and nothing else — never a step's return value, `serviceIds`
+     * (hence the store), an audit record, a log or a thrown error. See
+     * `coolifyApp`'s `pushDatabaseUrl`/`ensureAppRuntimeUrl` and `cmsSite`'s
+     * `ensureCmsRuntimeUrl`.
      */
     bulkUpsertEnvs(applicationUuid: string, envs: Array<{
         key: string;
@@ -504,35 +507,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 +697,95 @@ 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[]>;
+    /**
+     * #267: adds the org's own company login host to the ZITADEL instance's
+     * trusted domains (`@wtfalch/providers`' `ZitadelClient.ensureTrustedDomain`)
+     * -- the functionally critical half of `zitadelLoginHost` below, per
+     * `auth/docs/company-login-hosts.md`'s enforcement section: "the issuer
+     * refuses a public host that is not one of the instance's trusted
+     * domains." Idempotent: lists first, adds only if not already trusted.
+     */
+    ensureTrustedDomain(domain: string): Promise<{
+        added: boolean;
+    }>;
+    /**
+     * #267: moves an already-created app's Login V2 base URI, read-modify-
+     * write (`@wtfalch/providers`' `ZitadelClient.updateOidcAppLoginBaseUri`).
+     * `zitadelLoginHost` below calls this for each live app whose client id
+     * the binding holds; `zitadelApp` never sets it at creation.
+     */
+    updateOidcAppLoginBaseUri(orgId: string, projectId: string, appId: string, loginBaseUri: string): Promise<void>;
 }
 /**
  * Provisions one org's organisation on Files (#80), matching
@@ -839,6 +961,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;
@@ -848,6 +979,15 @@ export interface FoundryStepExecutorPorts {
      * step throws. The planner blocks these steps first while a key is not held.
      */
     platformOrg?: PlatformOrgPortSource;
+    /**
+     * #267: zitadel-login's own `LOGIN_HOST_BINDINGS` entry for the org -- see
+     * {@link LoginHostBindingsPort}'s own doc comment. Optional the same way
+     * `jobsScheduler`/`mailCopy` are: a host that has not wired this yet gets no
+     * login-host step at all -- the planner reports it blocked (the host also
+     * sets `FoundryPlanApplyOptions.loginHostBindings`), so nothing is trusted
+     * or repointed without the binding.
+     */
+    loginHostBindings?: LoginHostBindingsPort;
     /**
      * Hands a just-minted, one-time secret (today: an API app's
      * `clientSecret`) to the host, immediately after the provider returns it
@@ -949,6 +1089,14 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * recorded).
      */
     private zitadelOwner;
+    /**
+     * `plan/diff.ts`'s `planLoginHost` (#267): adds the org's own company
+     * login host (`action.desired.host`) to the ZITADEL instance's trusted
+     * domains, writes zitadel-login's binding, then repoints the apps whose
+     * client id that binding holds. Apps created later are not in it yet:
+     * the next run replans (`diff.ts`'s `planLoginHost`) and moves them.
+     */
+    private zitadelLoginHost;
     /**
      * `plan/diff.ts`'s `planCustomers` (plan gap A9): the org's customers sign
      * in through a second ZITADEL org, `<slug> customers`, with
@@ -997,28 +1145,34 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     private ensureLogVolume;
     private coolifyDatabase;
     /**
-     * Pushes the database's connection string into the app's environment as
-     * `DATABASE_URL` -- never also as `DATABASE_URL_OWNER` (Decision, this
-     * campaign's report). Archon's own boot script
-     * (`archon/scripts/migrate-and-start.sh`) treats a bare `DATABASE_URL` with
-     * no `DATABASE_URL_OWNER` as "before the split": it migrates and serves as
-     * the one role it has, which is exactly what a database Coolify just
-     * created (one superuser role, no separate runtime role yet) is. Setting
-     * both to the *same* superuser URL would instead take the split branch --
-     * `db-role-guard.sh` then refuses to boot, since `DATABASE_URL_OWNER` being
-     * set means it expects `DATABASE_URL` to connect as a distinct,
-     * non-superuser runtime role (`<database>_rt`), which nothing here creates.
-     * Minting that role's own password and URL is a provisioning step of its
-     * own, not built here (Finding, this campaign's report).
+     * Pushes the database's connection string into the app's environment,
+     * split the same way `cmsSite`'s own database is (#117, #239): the
+     * superuser connection as `DATABASE_URL_OWNER`, and a distinct, restricted
+     * `<dbName>_rt` role's connection as `DATABASE_URL`. Archon's and manage's
+     * own boot scripts (`db-role-guard.sh`) refuse to start against a
+     * superuser `DATABASE_URL`, and lokessmie's refuses to start without
+     * `DATABASE_URL_OWNER` at all -- a bare superuser `DATABASE_URL` with no
+     * `DATABASE_URL_OWNER` is "before the split" there too.
      *
-     * The connection string is a live credential
-     * (`postgres://user:password@host/db`): it is read from
-     * `CoolifyPort.getDatabase` and handed straight to `bulkUpsertEnvs` and
-     * nowhere else in this class -- never returned, never recorded in
-     * `serviceIds` (hence never in the store or an audit record), never logged,
-     * never interpolated into a thrown error.
+     * Both connection strings are live credentials
+     * (`postgres://user:password@host/db`): read from `CoolifyPort.getDatabase`
+     * (or minted here, for the runtime one) and handed straight to
+     * `bulkUpsertEnvs` and nowhere else in this class -- never returned, never
+     * recorded in `serviceIds` (hence never in the store or an audit record),
+     * never logged, never interpolated into a thrown error.
      */
     private pushDatabaseUrl;
+    /**
+     * `null` once the app already has a `DATABASE_URL` -- never rotated, the
+     * same rule `ensureCmsRuntimeUrl` follows and for the same reason: the
+     * app's own boot script creates or updates the live `<dbName>_rt` Postgres
+     * role from exactly the username/password this method mints, once:
+     * overwriting `DATABASE_URL` on a later apply would leave that
+     * already-created role's real password out of sync with whatever foundry
+     * hands the app next. See `ensureCmsRuntimeUrl`'s own doc comment for the
+     * parsing and encoding choices this mirrors exactly.
+     */
+    private ensureAppRuntimeUrl;
     /**
      * Pushes what the org's app needs to sign a user in through ZITADEL (gap
      * P2, `.plans/2026-09-26-level-1-org-map.md`) -- a second `bulkUpsertEnvs`
@@ -1033,9 +1187,12 @@ 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) is out of scope here (task brief). `DATABASE_URL_OWNER`/
+     * `DATABASE_URL` are pushed by `pushDatabaseUrl` instead, not here --
+     * that call runs only once `hosting.database` is declared and
+     * provisioned, where this one is unconditional (#239).
      */
     private pushAppEnv;
     /**
@@ -1079,7 +1236,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 +1248,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 +1591,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 +1615,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 +1669,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.