@wtfalch/foundry 0.4.0 → 0.5.0

package/dist/plan/executor.d.ts

@@ -1,5 +1,5 @@
 import type { OrgMailOptions, OrgMailOrg, OrgMailResult } from '@wtfalch/email/postmaster';
-import type { DeclaredOrg, HostingBuildPack, OrgId } from '../org.js';
+import type { DeclaredOrg, HostingBuildPack } from '../org.js';
 import type { DeclaredOrgStore } from '../store.js';
 import type { StepAction } from './diff.js';
 import type { DestroyTarget, StepDestroyer, StepExecutionContext, StepExecutor } from './plan-apply.js';
@@ -60,6 +60,7 @@ export interface CoolifyPort {
         uuid: string;
         is_usable: boolean;
         is_reachable: boolean;
+        ip?: string;
     }>>;
     requireGithubApp(preferredUuid?: string): Promise<{
         uuid: string;
@@ -217,6 +218,15 @@ export interface CoolifyPort {
         name?: string;
         description?: string;
         instant_deploy?: boolean;
+        /**
+         * `host:container`, comma separated -- publishes host ports directly
+         * (`@wtfalch/providers`' `CoolifyClient.createDockerImageApplication`
+         * doc comment: "a tunnelled web app never needs and a mail server cannot
+         * do without"). Used by `platform-providers.ts`'s `provisionPlatformMail`
+         * (#169) for Stalwart's SMTP/submission ports, which cannot go through
+         * Cloudflare's HTTP-only tunnel the way `platform:auth`'s apps do.
+         */
+        ports_mappings?: string;
     }): Promise<{
         uuid: string;
     }>;
@@ -292,6 +302,15 @@ export interface CloudflarePort {
         name: string;
     }>;
     putTunnelConfig(tunnelId: string, config: unknown): Promise<unknown>;
+    /**
+     * The tunnel's connector token (#197) -- a `cloudflared` container reads
+     * this at boot to dial into the tunnel. A live credential: matches
+     * `@wtfalch/providers`' `CloudflareClient.getTunnelToken` method-for-method.
+     * A caller must hand this straight to `bulkUpsertEnvs` and nowhere else --
+     * never a log, an error, a return value or a recorded scope id (see
+     * `cloudflared-connector.ts`'s `ensureCloudflaredConnector`).
+     */
+    getTunnelToken(tunnelId: string): Promise<string>;
     /** `FoundryPlanApply.destroy`'s teardown of the org's own Cloudflare tunnel. */
     deleteTunnel(tunnelId: string): Promise<void>;
     /** `cloudflareAccess` finds the org's Access app by domain before creating one (#84). */
@@ -310,6 +329,7 @@ export interface CloudflarePort {
     listAccessPolicies(appId: string): Promise<Array<{
         id: string;
         name: string;
+        include?: unknown[];
     }>>;
     createAccessPolicy(appId: string, policy: {
         name: string;
@@ -371,83 +391,103 @@ export interface CloudflarePort {
     request<T>(method: string, path: string, body?: unknown, missingOkay?: boolean): Promise<T>;
 }
 /**
- * One DNS record a Resend domain's own response names it must publish --
- * `record` is Resend's own label (`SPF`, `DKIM`, `DMARC`, `MX`), which
- * {@link ResendPort.createDomain}/{@link ResendPort.getDomain} return
- * alongside `type`/`name`/`value` for `coolifyMail` to act on, the same shape
- * https://resend.com/docs/api-reference/domains/create-domain documents.
+ * One DNS record a Lettermint domain's own response says must be published --
+ * `purpose` is Lettermint's own label (`return_path`, `dmarc`, `dkim_legacy`,
+ * `dkim_primary`, `dkim_secondary`), replacing Resend's `record` field, from
+ * {@link LettermintPort.createDomain}/{@link LettermintPort.getDomain}, the
+ * same shape https://lettermint.co/docs/api-reference/team/0.0.1/lettermint-team-openapi.json's
+ * `DomainDnsRecordData` documents (`fqdn`/`content` renamed to this port's own
+ * `name`/`value`, matching {@link publishLettermintDnsRecords}'s sibling
+ * `publishMailDnsRecords` naming).
  */
-export interface ResendDnsRecordSpec {
-    readonly record: 'SPF' | 'DKIM' | 'DMARC' | 'MX' | string;
-    readonly name: string;
+export interface LettermintDnsRecordSpec {
+    readonly purpose: 'return_path' | 'dmarc' | 'dkim_legacy' | 'dkim_primary' | 'dkim_secondary';
     readonly type: 'TXT' | 'CNAME' | 'MX';
+    readonly name: string;
     readonly value: string;
-    readonly priority?: number;
 }
-export interface ResendDomain {
+export interface LettermintDomain {
+    readonly id: string;
+    readonly domain: string;
+    readonly status: 'verified' | 'partially_verified' | 'pending_verification' | 'failed_verification';
+    readonly dnsRecords: readonly LettermintDnsRecordSpec[];
+}
+export interface LettermintProject {
     readonly id: string;
     readonly name: string;
-    readonly status: string;
-    readonly records?: readonly ResendDnsRecordSpec[];
 }
 /**
- * The Resend calls this executor makes to verify an org's mail domain (#138)
- * and mint its app's sending key (#140 rework) -- the shared Stalwart relays
- * every outbound message through Resend
+ * The Lettermint calls this executor makes to verify an org's mail domain
+ * (#138) and mint its app's sending project (#140 rework, 2026-09-28
+ * lettermint-org-mail swap) -- the shared Stalwart relays every outbound
+ * message through Lettermint
  * (https://github.com/wtfalch/email/blob/main/packages/email/src/postmaster/objects.ts#L149-L168),
- * which refuses mail from a domain Resend has not verified. `@wtfalch/providers`
- * has no Resend client yet, unlike Coolify/Cloudflare/ZITADEL above, so this
- * port names Resend's own REST shapes directly
- * (https://resend.com/docs/api-reference/domains/create-domain,
- * https://resend.com/docs/api-reference/api-keys/create-api-key,
- * https://resend.com/docs/api-reference/api-keys/list-api-keys,
- * https://resend.com/docs/api-reference/api-keys/delete-api-key) -- the same
- * prior art `wtfalch/app-template`'s `bootstrap/steps/resend-email.ts` already
- * proved against a live account. The relay's own `<slug>-relay` key
- * (`.plans/2026-09-27-org-mail-resend-design.md`) is a separate change, filed
- * as https://github.com/wtfalch/foundry/issues/149 and out of scope here.
+ * which refuses mail from a domain it has not verified. `@wtfalch/providers`
+ * has no Lettermint client yet, unlike Coolify/Cloudflare/ZITADEL above, so
+ * this port names Lettermint's own REST shapes directly
+ * (`.plans/2026-09-28-lettermint-api.md`, its own primary-source citations).
+ * Replaces `ResendPort` (#138/#140), trimmed to what `coolifyApp`/`coolifyMail`
+ * below actually call.
+ *
+ * Unlike Resend's per-domain sending key, a Lettermint domain is
+ * unrestricted by default -- any project in the team could send from it --
+ * so a project's own domain access is a separate call
+ * ({@link restrictDomainToProjects}), and the credential unit is a *project*,
+ * not a per-domain key: Lettermint's API mints, at most, one live token per
+ * project and has no call to list or revoke an individual token within one
+ * (`.plans/2026-09-28-lettermint-api.md` §4), so `<slug>-app` is a project
+ * name, never suffixed with a domain id the way Resend's key name was.
  */
-export interface ResendPort {
-    /** An exact name match, never a listing scan `coolifyMail` has to page itself. */
+export interface LettermintPort {
+    /**
+     * Lettermint's own `filter[domain]` match is partial and case-insensitive
+     * (`.plans/2026-09-28-lettermint-api.md` §3: "partial, case-insensitive"),
+     * so a result here can be a lookalike (`notacme.com`, `mail.acme.com`) --
+     * `domain` is returned precisely so every caller can reject one via
+     * `FoundryStepExecutor.findExactLettermintDomain` rather than a listing
+     * scan of its own.
+     */
     findDomain(name: string): Promise<{
         id: string;
-        name: string;
-        status: string;
+        domain: string;
+        status: LettermintDomain['status'];
     } | undefined>;
-    createDomain(name: string): Promise<ResendDomain>;
-    /** Re-reads a domain already found by {@link findDomain}, for its current status and DNS records. */
-    getDomain(id: string): Promise<ResendDomain>;
+    /** `POST /domains`, its response already carrying `dnsRecords`. */
+    createDomain(name: string): Promise<LettermintDomain>;
+    /** Re-reads a domain already found by {@link findDomain}, for its current DNS records. */
+    getDomain(id: string): Promise<LettermintDomain>;
     /**
-     * Asks Resend to re-check DNS now. `coolifyMail` never polls or waits on
-     * this -- the task brief: "do not block the plan on DNS propagation:
-     * record the status, and let the next apply re-check it (idempotent, like
-     * `applyOrgMail`)".
+     * Asks Lettermint to re-check DNS now. Never polled or awaited to
+     * completion -- the same "do not block the plan on DNS propagation" rule
+     * `ResendPort.verifyDomain` followed: record the status, and let the next
+     * apply re-check it.
      */
     verifyDomain(id: string): Promise<{
-        status: string;
+        status: LettermintDomain['status'];
     }>;
+    /** `parkLettermintMail`'s own cleanup once an org's mail is parked (mode `'off'`). */
+    deleteDomain(id: string): Promise<void>;
     /**
-     * Every key in the account, `id`+`name` only -- Resend never returns a
-     * key's token except at creation, so this is how the mint rule
-     * (`.plans/2026-09-27-org-mail-resend-design.md` "One rule for minting")
-     * tells whether the app's key is healthy before deciding to mint. `ensureAppResendKey`'s own doc comment below
-     * spells the rule out.
+     * `POST /projects`. `token` is the one-time secret -- Lettermint shows a
+     * project's token once, at creation, and the API has no call to mint a
+     * second one on the same project -- so a caller that loses it creates a
+     * fresh project instead (`ensureAppLettermintMail`'s own mint rule).
      */
-    listApiKeys(): Promise<Array<{
-        id: string;
-        name: string;
-    }>>;
-    /** Sending-only, scoped to one domain -- the app step's `<slug>-app@<domainId>` (`ensureAppResendKey`), minted under the mint rule. */
-    createApiKey(input: {
-        name: string;
-        permission: 'sending_access';
-        domainId: string;
-    }): Promise<{
-        id: string;
+    createProject(name: string): Promise<{
+        project: LettermintProject;
         token: string;
     }>;
-    /** Deletes one key by id -- the mint rule's own cleanup of an orphan, a duplicate, or a key for a mail domain the org no longer uses. */
-    deleteApiKey(id: string): Promise<void>;
+    /** Every project in the team, `id`+`name` only -- the mint rule's own health check and `parkLettermintMail`'s orphan scan both filter this by name themselves. */
+    listProjects(): Promise<readonly LettermintProject[]>;
+    /** Deletes one project by id -- the mint rule's own cleanup of an orphan or a duplicate, and `parkLettermintMail`'s teardown. */
+    deleteProject(id: string): Promise<void>;
+    /**
+     * `PUT /domains/{domainId}/projects`. Rebuilds the domain's whole
+     * restriction from `projectIds` -- never patched -- so a domain never ends
+     * up unrestricted (any team project could then send as the org) nor
+     * restricted only to a project already deleted.
+     */
+    restrictDomainToProjects(domainId: string, projectIds: readonly string[]): Promise<void>;
 }
 /**
  * The Stalwart calls this executor makes for one org's mail, shaped to match
@@ -458,18 +498,38 @@ export interface ResendPort {
 export interface MailPort {
     applyOrgMail(org: OrgMailOrg, options: OrgMailOptions): Promise<OrgMailResult>;
     parkOrgMail(org: OrgMailOrg, options: OrgMailOptions): Promise<void>;
+    /**
+     * Gives one person a mailbox on the org's already-resolved mail domain
+     * (#162). The host implements this with `@wtfalch/email/postmaster`'s own
+     * `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
+     * id first, so a second apply never calls this at all.
+     */
+    createMailbox(org: OrgMailOrg, mailbox: {
+        address: string;
+        name: string;
+    }): Promise<void>;
 }
 /**
- * The shared calls SFU's own LiveKit API credentials (#122, #127), resolved
- * by the host from wherever `scripts/calls-sfu-deploy.mjs`'s own
- * `CallsSfuConfig` delivered them (#145) -- this package never mints or
- * invents a LiveKit key/secret pair itself, the same "the executor is
- * constructed with narrow ports ... a host [archon] supplies real clients"
- * rule this file's own top doc comment states for every provider credential.
- * `resolveCredentials` returns `null` when the SFU has not been configured
- * yet, the same "nothing recorded" signal a bare `CoolifyPort.listEnvs` gives
- * `ensureCallsMatrixSecrets` -- just for a secret this package never held in
- * the first place, so there is nowhere here to read it back from itself.
+ * 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.
+ *
+ * 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
+ * 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
+ * `CoolifyPort.listEnvs` gives `ensureCallsMatrixSecrets`.
  */
 export interface CallsSfuPort {
     resolveCredentials(): Promise<{
@@ -573,26 +633,37 @@ export interface ZitadelPort {
     deleteProject(orgId: string, projectId: string): Promise<void>;
     /** `FoundryPlanApply.destroy`'s last step: removes the whole ZITADEL org and everything foundry made inside it. */
     deleteOrg(orgId: string): Promise<void>;
-}
-/**
- * One org's spend limit on Files, matching `files/packages/sdk/src/client.ts:154-166`'s
- * `setQuota`/`setBudget` (the caller's own organisation, resolved from its
- * signed request — no organisation id parameter, hence a factory per org
- * rather than one flat port).
- */
-export interface FilesOrgLimits {
-    setQuota(limitBytes: string | null): Promise<unknown>;
-    setBudget(limitMicros: string | null): Promise<unknown>;
-}
-/**
- * One org's budget on AI, matching `ai/packages/sdk/src/client.ts:94-101`'s
- * `updateBudget` (`UpdateBudget` from `ai/packages/sdk/src/types.ts:134-137`).
- */
-export interface AiOrgLimits {
-    updateBudget(input: {
-        keyId: string | null;
-        limitMicros: string;
-    }): Promise<unknown>;
+    /**
+     * #168: mints foundry's own machine user, on the platform's own freshly
+     * built ZITADEL instance, with the instance-wide admin role, and a fresh
+     * Personal Access Token for it -- "Foundry mints this key; nobody pastes
+     * it." `orgId` is the ZITADEL org the machine user lives in (every ZITADEL
+     * user belongs to some org, the same shape {@link inviteOrgOwner} already
+     * has for a human, even though the IAM_OWNER role this user gets is
+     * instance-wide once granted, not scoped to that org). Idempotent on the
+     * user itself -- a real client finds or creates it by `userName` -- but
+     * never on the token: ZITADEL shows a PAT's value once, at mint, and never
+     * again, the same "minted once, delivered once" rule {@link createApiApp}'s
+     * own doc comment follows for a client secret. The caller
+     * (`platform-providers.ts`'s `FoundryPlatformStepExecutor`) hands the token
+     * straight to {@link FoundryStepExecutorPorts.deliverSecret} and never
+     * returns, stores or logs it, and only calls this once per platform,
+     * guarded by its own recorded scope id -- never by anything this method
+     * does internally.
+     *
+     * `@wtfalch/providers` has no machine-user support at all yet (checked
+     * 2026-09-29) -- "being added to providers in parallel", the same
+     * precedent {@link createOidcApp}/{@link createApiApp} set above -- so this
+     * port states the shape it needs to land with; a real client that gains
+     * exactly this method satisfies it with no adapter.
+     */
+    mintAdminMachineUser(orgId: string, input: {
+        userName: string;
+        name: string;
+    }): Promise<{
+        userId: string;
+        token: string;
+    }>;
 }
 /**
  * Provisions one org's organisation on Files (#80), matching
@@ -600,9 +671,8 @@ export interface AiOrgLimits {
  * `createFilesManagementClient().provisionOrganisation`
  * (`ProvisionOrganisationInput`/`ProvisionOrganisationResult`,
  * `files/packages/sdk/src/types.ts:146-156`). Flat, not a factory, like
- * {@link ZitadelPort}: `organisationId` is an explicit call argument here,
- * unlike {@link FilesOrgLimits}'s tenant-scoped calls, which resolve the
- * caller's own organisation from its signed request instead.
+ * {@link ZitadelPort}: `organisationId` is an explicit call argument on every
+ * method here.
  *
  * Finding (this campaign's report): unlike {@link AiOrganisationPort}'s bearer
  * credential, `createFilesManagementClient`'s whole transport is "a signed
@@ -611,11 +681,17 @@ export interface AiOrgLimits {
  * request (`files/apps/host/src/lib/authz/service-assertion.ts`'s
  * `signManagementRequest`/`AssertionTrust`). A host can construct this without
  * any human session: it only needs the Ed25519 private key (`SigningIdentity`)
- * an operator's `MANAGEMENT_PUBLIC_KEYS`/`MANAGEMENT_ISSUER` pins — the same
- * signer {@link FilesOrgLimits} needs for `setQuota`/`setBudget`, since the
- * `organisation` field inside the signed claim selects the org per call, so
- * one shared keypair signs for every org rather than needing a secret per
- * org.
+ * an operator's `MANAGEMENT_PUBLIC_KEYS`/`MANAGEMENT_ISSUER` pins.
+ *
+ * #177: `setQuota`/`setBudget` (`files/packages/sdk/src/client.ts:154-166`)
+ * used to live on a separate `FilesOrgLimits` a host built per org through a
+ * `filesLimitsFor(orgId)` factory on `FoundryStepExecutorPorts` — ceremony
+ * left over from nothing but currying an id this port's own callers already
+ * have in hand. The signed claim's `organisation` field selects the org per
+ * call, so one shared keypair signs for every org already, the same signer
+ * `provisionOrganisation` uses; there was never a per-org client to build,
+ * only an org id to pass. Both methods now take it explicitly, like
+ * `provisionOrganisation` always did, and `filesLimitsFor` is gone.
  */
 export interface FilesOrganisationPort {
     provisionOrganisation(input: {
@@ -634,6 +710,9 @@ export interface FilesOrganisationPort {
         shareHost: string | null;
         created: boolean;
     }>;
+    /** #27, #177: the org's own spend limit on Files -- see this interface's own doc comment for why `organisationId` is explicit here. */
+    setQuota(organisationId: string, limitBytes: string | null): Promise<unknown>;
+    setBudget(organisationId: string, limitMicros: string | null): Promise<unknown>;
 }
 /**
  * Provisions one org's organisation on AI and switches its AI use on (#80),
@@ -650,6 +729,13 @@ export interface FilesOrganisationPort {
  * `ai.organisations:offer`, `ai.budgets:update`, among others) copied onto
  * it — used directly with `createAiClient`, unlike Files' signed-assertion
  * transport above.
+ *
+ * #172: `platform:ai` (`platform-providers.ts`'s `provisionPlatformAi`)
+ * deploys the ai host this port talks to, records its internal address
+ * (`PLATFORM_AI_INTERNAL_URL_SCOPE_KEY`) and delivers foundry's own
+ * management key under `PLATFORM_AI_MANAGEMENT_KEY_REF` -- but only through a
+ * host-supplied `AiManagementKeyMinter`, since that same script-only mint is
+ * still the one way ai issues its first platform credential.
  */
 export interface AiOrganisationPort {
     provisionOrganisation(input: {
@@ -664,21 +750,104 @@ export interface AiOrganisationPort {
         organisationId: string;
         offers: string[];
     }>;
+    /**
+     * Mints a key inside `organisationId` (#80 step 3, `wtfalch/ai#108`/`#113`),
+     * matching `ai/packages/sdk/src/client.ts`'s `issueOrganisationKey`
+     * (`IssueOrganisationKey`/`IssuedOrganisationKey`,
+     * `ai/packages/sdk/src/types.ts:150-166`). The secret comes back once, the
+     * same as `ZitadelPort.inviteOrgOwner`'s and `zitadelApp`'s own one-time
+     * secrets -- `aiKey` hands it straight to `deliverSecret` and returns only
+     * the key's id.
+     */
+    issueOrganisationKey(organisationId: string, input: {
+        name: string;
+        expiresDays: number;
+        permissions: string[];
+    }): Promise<{
+        organisationId: string;
+        id: string;
+        secret: string;
+    }>;
+    /**
+     * #27, #177: the org's own budget on AI, matching
+     * `ai/packages/sdk/src/client.ts:94-101`'s `updateBudget` (`UpdateBudget`
+     * from `ai/packages/sdk/src/types.ts:134-137`). Used to live on a separate
+     * `AiOrgLimits` a host built per org through an `aiLimitsFor(orgId)`
+     * factory on `FoundryStepExecutorPorts` -- the same dead currying
+     * {@link FilesOrganisationPort}'s own doc comment explains for
+     * `setQuota`/`setBudget`. `organisationId` is explicit here now, like
+     * every other method on this port.
+     */
+    updateBudget(organisationId: string, input: {
+        keyId: string | null;
+        limitMicros: string;
+    }): Promise<unknown>;
+}
+/**
+ * #173: the jobs scheduler's own admin API
+ * (https://github.com/wtfalch/jobs, "The admin API", jobs#62), authenticated
+ * with `SCHEDULER_ADMIN_TOKEN` as a bearer token by whatever real client
+ * satisfies this port -- this package holds no credential of its own, the
+ * same rule every other port in this file follows. No `@wtfalch/providers`
+ * client for this scheduler exists yet, so this port states the shape a real
+ * one should satisfy structurally, the same convention `ZitadelPort`'s
+ * not-yet-existing methods already follow.
+ *
+ * Matches `POST /admin/projects` method-for-method: idempotent by
+ * `(name, baseUrl)`. A first call returns the freshly minted `secret` and
+ * `syncKey`, shown exactly once; a repeat call for the same `(name, baseUrl)`
+ * returns just the `id`, with neither -- `jobsRegistration` below never
+ * re-delivers a secret it did not just mint, deciding purely on whether this
+ * resolves with one. A repeat call naming the same project under a different
+ * `baseUrl` is refused (the real API's `409`); this port surfaces that as a
+ * thrown error, like any other provider refusal in this file.
+ */
+export interface JobsSchedulerPort {
+    registerProject(input: {
+        name: string;
+        baseUrl: string;
+        alertUrl?: string;
+    }): Promise<{
+        id: string;
+        secret?: string;
+        syncKey?: string;
+    }>;
+}
+/**
+ * #177: where the org steps' files, AI and jobs ports come from when the host
+ * does not supply them. `platform-org-ports.ts`'s `PlatformOrgPorts` builds
+ * them from the platform's recorded addresses and held keys.
+ */
+export interface PlatformOrgPortSource {
+    files(): Promise<FilesOrganisationPort>;
+    ai(): Promise<AiOrganisationPort>;
+    jobs(): Promise<JobsSchedulerPort>;
 }
 export interface FoundryStepExecutorPorts {
     coolify: CoolifyPort;
     cloudflare: CloudflarePort;
     zitadel: ZitadelPort;
     mail: MailPort;
-    resend: ResendPort;
+    lettermint: LettermintPort;
+    /**
+     * #173: registers an org's own app with the platform's jobs scheduler -- see
+     * {@link JobsSchedulerPort}'s own doc comment. Optional: a host with no
+     * scheduler deployed builds the executor without one, and tells the planner
+     * so (`FoundryPlanApplyOptions.jobsScheduler`), which then reports each
+     * org's registration as blocked instead of planning a step that would throw.
+     */
+    jobsScheduler?: JobsSchedulerPort;
     /** The shared calls SFU's own LiveKit credentials (#145) -- see {@link CallsSfuPort}'s own doc comment. */
     callsSfu: CallsSfuPort;
-    /** A factory, not a flat client: Files/AI are org-scoped credentials the host resolves per org. */
-    filesLimitsFor: (orgId: OrgId) => FilesOrgLimits;
-    aiLimitsFor: (orgId: OrgId) => AiOrgLimits;
-    /** Flat, not a factory: `organisationId` is an explicit argument on both ports (see each port's own doc comment). */
-    filesOrganisation: FilesOrganisationPort;
-    aiOrganisation: AiOrganisationPort;
+    /** 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;
+    /**
+     * #177: builds the files, AI and jobs ports from the platform's addresses
+     * and held keys. A port set above overrides it (tests); with neither, the
+     * step throws. The planner blocks these steps first while a key is not held.
+     */
+    platformOrg?: PlatformOrgPortSource;
     /**
      * Hands a just-minted, one-time secret (today: an API app's
      * `clientSecret`) to the host, immediately after the provider returns it
@@ -721,6 +890,20 @@ export declare class NotBuiltError extends Error {
  * this file's hostname rules.
  */
 export declare function healthUrls(org: DeclaredOrg): string[];
+/** The one Access policy foundry puts on its own Access app (#84). */
+export declare const ACCESS_POLICY_NAME = "foundry: allowed emails";
+/**
+ * Whether an application's own Coolify `status` (`` `running:healthy`,
+ * `exited:unhealthy` `` -- `@wtfalch/providers`' own doc comment) means it is
+ * already up, or on its way there -- `findOrCreateCmsApp`'s own check of
+ * whether a found-but-parked app still needs `start`ing (#116 review round
+ * 3, Finding 1). Only `exited`/`stopped` (Coolify's own resting-off states;
+ * `stopped` is not one this codebase has verified against a live instance,
+ * included defensively) read as off; a missing `status` defaults to on, the
+ * same "nothing says it's off" convention `planHostingToggle` (`diff.ts`)
+ * uses for the org's own app.
+ */
+export declare function isRunningOrStarting(status: string | undefined): boolean;
 export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer {
     private readonly ports;
     constructor(ports: FoundryStepExecutorPorts);
@@ -863,32 +1046,40 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      */
     private ensureAuthCookieSecret;
     /**
-     * #140 rework: the hosted app's own Resend sending key, pushed as
-     * `RESEND_API_KEY` straight into the app's env, the one place its token
-     * ever lives (Resend shows a key's token once, at creation). A no-op until
-     * `coolify:mail` has recorded a {@link RESEND_DOMAIN_ID_SCOPE_KEY} for this
-     * org; the next apply fills it in once `coolify:mail` runs first
+     * #140 rework (2026-09-28 lettermint-org-mail swap, "Core rule" +
+     * "Credential model"): all of the org's Lettermint work now lives here,
+     * in the app step, since the first project -- and so the first domain
+     * restriction -- can only exist once the token has a home (the app env). A
+     * no-op until `coolify:mail` has recorded {@link MAIL_DOMAIN_SCOPE_KEY} for
+     * this org; the next apply fills it in once `coolify:mail` runs first
      * (`diff.ts`'s `computePlanDetail` order).
      *
-     * The key is named `<slug>-app@<resendDomainId>`, so a key limited to a
-     * mail domain the org no longer uses (a `usesDomain` flip moves it between
-     * `org.domain` and `<slug>.<apex>`) never passes for the current one.
-     * `RESEND_API_KEY_ID` sits beside the token in the env -- an id, not a
-     * secret -- so the env can say which key its token belongs to.
+     * Order, exactly as the swap's "Core rule" states it: ensure the
+     * `<slug>-app` project, ensure the mail domain, restrict that domain to the
+     * org's own projects, publish its DNS records, trigger verification, then
+     * delete every stale `<slug>-app` project. New projects are created and the
+     * domain restricted to them before any old project is deleted, so the
+     * restriction list never becomes empty.
      *
-     * The mint rule (`.plans/2026-09-27-org-mail-resend-design.md` "One rule
-     * for minting"): healthy when the env holds a token and its
-     * `RESEND_API_KEY_ID` is the one key Resend lists under the current name.
-     * Otherwise one fresh key is minted and written to the env first, and only
-     * then is every other `<slug>-app@` key deleted -- a lost mint response, a
-     * duplicate, a hand-made key, and a previous domain's key all end the same
-     * way. An app that was already running is restarted before that delete,
-     * since a container reads its env only at start (`running`, the same
-     * reason {@link ensureLogVolume} restarts one). The restart is not
-     * awaited to completion, so the old container can briefly outlive its key.
+     * Mint rule ("Credential model"): the project is healthy when the app env
+     * holds `LETTERMINT_API_TOKEN` and Lettermint lists exactly one project
+     * named `<slug>-app` -- unlike Resend's key, a Lettermint project's name
+     * carries no domain id, since a domain switch is handled entirely by
+     * {@link LettermintPort.restrictDomainToProjects} below and never needs a
+     * fresh project. Otherwise a fresh project is created and its token
+     * written to the env first, and only then is every other `<slug>-app`
+     * project deleted -- a lost mint response and a duplicate both end the
+     * same way. An app that was already running is restarted before that
+     * delete, since a container reads its env only at start (`running`, the
+     * same reason {@link ensureLogVolume} restarts one).
+     *
+     * The domain's restriction is rebuilt from every project named `<slug>-app`
+     * or `<slug>-relay` (the relay project itself is #149, not built yet) --
+     * never patched, so it can never end up scoped only to a project about to
+     * be deleted.
      *
      * `MAIL_FROM` is upserted every time: it depends only on the mail domain
-     * `coolify:mail` resolved (`RESEND_MAIL_DOMAIN_SCOPE_KEY`).
+     * `coolify:mail` resolved.
      *
      * The token goes straight to `bulkUpsertEnvs` and nowhere else: never
      * returned, never recorded in `serviceIds` (`recordScopeId`'s own doc
@@ -896,7 +1087,20 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * same discipline `pushDatabaseUrl`'s doc comment states for a database's
      * own connection string.
      */
-    private ensureAppResendKey;
+    private ensureAppLettermintMail;
+    /**
+     * Review finding (post-#140 rework): {@link LettermintPort.findDomain}'s
+     * own match is partial and case-insensitive, so a raw result can be a
+     * lookalike (`notacme.com`, `mail.acme.com`) rather than `name` itself --
+     * and every caller here full-replaces the found domain's project
+     * restriction ({@link LettermintPort.restrictDomainToProjects}), so taking
+     * a lookalike as a match would let it be taken over. Every domain lookup
+     * in this class (`ensureAppLettermintMail`, `parkLettermintMail`,
+     * `deleteStaleLettermintDomain`) goes through this instead of the port
+     * directly, and treats anything but an exact, case-insensitive match as
+     * not found.
+     */
+    private findExactLettermintDomain;
     /**
      * `plan/diff.ts`'s `planSite` (#116, slicing #99's "provision the cms app,
      * database and site app per org"): the 2026-09-25 decision
@@ -1096,6 +1300,56 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * `config.mjs`'s own regex requires.
      */
     private ensureCallsBindingSecret;
+    /**
+     * `plan/diff.ts`'s `planAgora`: provisions the org's own Agora
+     * (https://github.com/wtfalch/agora) as one more Coolify application, from
+     * that repo's `apps/agora/Dockerfile` ({@link AGORA_REPO}'s doc comment),
+     * and pushes its env. `findOrCreateCallsApp` is reused as-is for the
+     * find-by-name-then-start-or-create shape, like {@link coolifyCallsService}.
+     * There is no park branch: Agora is always on.
+     *
+     * The env comes from `plan/agora.ts`'s `desiredAgoraEnv`, the same function
+     * the plan compares the live app against, so a re-plan after this step is
+     * empty. The step never writes a partial config: when any input is missing
+     * (the org's ZITADEL org id or Agora client id, or an issuer or
+     * mail/messaging project id the host does not supply,
+     * `AgoraHostPort`, read by the plan) it throws naming each one, before
+     * it creates anything.
+     *
+     * `AGORA_CANONICAL_HOST` is always pushed. `AGORA_MAIL_UPSTREAM`/
+     * `AGORA_FILES_UPSTREAM` are pushed once the platform's own mail/files
+     * hosts are on and applied (#177's `platform-org.ts`'s
+     * `agoraHostValuesFromPlatform`, read by `plan-apply.ts` when no host
+     * `agora` port overrides it) -- absent otherwise. The chat upstreams are
+     * still never pushed: chat has no admin API yet
+     * (https://github.com/wtfalch/chat/issues/40). Agora answers 502 on those
+     * routes rather than serving anything wrong.
+     */
+    private coolifyAgora;
+    /**
+     * `plan/diff.ts`'s `planJobsRegistration`: registers the org's own app with
+     * the platform's jobs scheduler (`JobsSchedulerPort.registerProject`, the
+     * scheduler's `POST /admin/projects`), then hands the freshly minted
+     * `secret` and `syncKey` to the host through `deliverSecret` -- but only
+     * when this call actually minted them. The admin API is itself idempotent
+     * by `(name, baseUrl)`: a repeat call for an already-registered project
+     * resolves with just the `id`, and this never re-delivers a secret or sync
+     * key it did not just mint, the same "registers an app once" rule
+     * `diff.ts`'s own plan-level gate (recordedIds, mirroring `planOwner`)
+     * already provides on a normal re-plan -- this check is what keeps that
+     * true even if this step somehow runs twice on the same apply.
+     *
+     * Never logs, returns or records either credential (this file's own top
+     * doc comment's "a secret is never a step's return value" rule) -- only the
+     * scheduler's own non-secret project id comes back as `resourceId`.
+     */
+    /** #177: the host's own port when it supplies one, else the platform's, built from its address and held key. */
+    private filesPort;
+    private aiPort;
+    private jobsPort;
+    private jobsRegistration;
+    /** `deliverSecret`, tried up to {@link JOBS_DELIVERY_ATTEMPTS} times; true once one attempt succeeds. */
+    private deliverWithRetry;
     private cloudflareTunnel;
     /**
      * `plan/diff.ts`'s `planZone`: finds or creates the Cloudflare zone for the
@@ -1118,67 +1372,90 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * `plan/diff.ts`'s `planMail`: gives an org mail, moves it between modes,
      * or parks it on the one shared Stalwart instance (`this.ports.mail`,
      * `@wtfalch/email/postmaster`'s `applyOrgMail`/`parkOrgMail` bound), then
-     * publishes whatever DNS records the call returns, then registers the same
-     * mail domain with Resend (#138) -- the shared Stalwart relays every
-     * outbound message through Resend, and Resend refuses mail from a domain
-     * it has not verified. No step here ever deletes the app's Resend key:
-     * `diff.ts`'s `planMail` plans nothing for mode `'off'`, so turning mail
-     * off leaves the key live, like every other resource foundry stops
-     * managing (#10). Switching the mail domain replaces the key instead
-     * (`ensureAppResendKey`).
+     * 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.
+     *
+     * 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}
+     * does this by comparing the previously recorded domain (case-insensitive)
+     * against the one this apply just resolved.
+     *
+     * #162: once `applyOrgMail` has given the org a domain, {@link ensureOwnerMailbox}
+     * gives its declared owner a mailbox on it, so Agora's Mail section is not
+     * empty for them after the org's first apply.
      */
     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.
+     */
+    private ensureOwnerMailbox;
+    /**
+     * Deletes the org's previous Lettermint domain once the mail domain it was
+     * registered under has changed -- otherwise it stays registered and
+     * restricted to the org's still-live `<slug>-app` project after the switch
+     * (review finding, post-#140 rework). A no-op on first apply (no previous
+     * domain recorded) and on a same-domain re-apply (compared
+     * case-insensitively, the same rule {@link findExactLettermintDomain}
+     * applies to the lookup itself).
+     */
+    private deleteStaleLettermintDomain;
     /**
      * Upserts each DNS record `applyOrgMail` says foundry must publish, found
      * by an exact name+type match (`CloudflarePort.findDnsRecord`'s own doc
      * comment) so update never mistakes a stale record of a different type for
      * a match. A `DKIM` record can be absent on the first call, since Stalwart
-     * mints the key on a background task; the next apply publishes it. Returns
-     * the zone id so `registerResendDomain` publishes Resend's own records on
-     * the same zone without a second lookup.
+     * mints the key on a background task; the next apply publishes it.
      */
     private publishMailDnsRecords;
     /**
-     * #138: registers `domain` with Resend -- the custom domain, or
-     * `<slug>.<apex>` for a level-1 org, exactly what `publishMailDnsRecords`
-     * just published the Stalwart records for. Idempotent by name, the same way
-     * `applyOrgMail` itself is: found by `findDomain` rather than any id this
-     * class recorded, so a crash between here and the next apply just repeats
-     * the same find-or-create. Never blocks on DNS propagation (task brief):
-     * `verifyDomain` asks Resend to re-check once, and its returned status is
-     * neither polled nor awaited -- an unverified domain here is exactly what
-     * the next apply corrects.
-     *
-     * #140 rework: mints no key of its own any more. It records the domain's
-     * own id and the resolved mail domain as scope ids so `ensureAppResendKey`
-     * (`coolifyApp`) can mint the app's own `<slug>-app@<domainId>` key once the app
-     * exists, without this step or the app step calling Resend to look the
-     * domain back up.
-     */
-    private registerResendDomain;
-    /**
-     * Upserts each DNS record Resend's domain names, the same find-then-upsert
-     * `publishMailDnsRecords` above uses for Stalwart's own records -- except
-     * SPF is merged into whatever record that call just published rather than
-     * created a second time (RFC 7208 treats two `v=spf1` TXT records on one
-     * name as a permerror and silently breaks SPF for every sender on the
-     * domain), and an existing `_dmarc` record is never overwritten. Prior art:
-     * `wtfalch/app-template`'s `bootstrap/steps/resend-email.ts`.
+     * 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.
+     * 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.
      */
-    private publishResendDnsRecords;
+    private parkLettermintMail;
     /**
-     * Inserts Resend's `include:` token into whatever SPF record
-     * `publishMailDnsRecords` already published for this name, instead of
-     * creating a second `v=spf1` TXT record -- the classic foot-gun that makes
-     * every receiver treat SPF as a permerror and skip it entirely.
+     * Upserts each DNS record Lettermint's domain names, the same find-then-
+     * upsert `publishMailDnsRecords` above uses for Stalwart's own records --
+     * except an existing `_dmarc` record is never overwritten (a stricter
+     * policy an org already set, `p=quarantine`/`p=reject`, should not be
+     * relaxed back to Lettermint's own default). Resend's own domain also
+     * carried an apex `SPF` TXT record that had to be merged into whatever SPF
+     * record already existed there (RFC 7208: two `v=spf1` TXT records on one
+     * name is a permerror); Lettermint's own DNS records
+     * (`.plans/2026-09-28-lettermint-api.md` §3) have no such record -- its
+     * `purpose` enum is `return_path`/`dmarc`/`dkim_legacy`/`dkim_primary`/
+     * `dkim_secondary`, none of them SPF -- so that merge has no case left to
+     * handle here and is dropped rather than kept as dead code.
      */
-    private mergeResendSpfRecord;
+    private publishLettermintDnsRecords;
     /**
      * Never overwrites an existing `_dmarc` record -- a stricter policy an org
      * already set (`p=quarantine`/`p=reject`) should not be relaxed back to
-     * Resend's own `p=none` default.
+     * Lettermint's own `p=none` default.
      */
-    private ensureResendDmarcRecord;
+    private ensureLettermintDmarcRecord;
     /**
      * #80: provisions the org's own organisation on Files, before
      * {@link filesStorage} can set its spend limit. `provisionOrganisation` is
@@ -1197,6 +1474,16 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      */
     private aiOrganisation;
     private aiBudget;
+    /**
+     * #80 step 3: mints the org's own ai key, once, and hands its one-time
+     * secret straight to {@link FoundryStepExecutorPorts.deliverSecret} --
+     * never returned, stored in `serviceIds` or logged, the same discipline
+     * `zitadelApp`'s own `created.clientSecret` follows. `diff.ts`'s
+     * `planAiKey` never plans this step again once its resource id
+     * (the key's id, not its secret) is recorded, since ai's own API offers no
+     * way to check for an already-minted key.
+     */
+    private aiKey;
     /**
      * {@link StepDestroyer.destroy}: deletes the one resource
      * `FoundryPlanApply.destroy` names. A provider 404 (already gone) counts as
@@ -1209,3 +1496,23 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
         readonly recordedIds: Readonly<Record<string, string>>;
     }): Promise<void>;
 }
+/**
+ * True for a provider's own "already gone" response, however it surfaces --
+ * `@wtfalch/providers`' `ZitadelError` carries a structured `status: number`
+ * (`zitadel.ts`), while its Coolify and Cloudflare clients throw a plain
+ * `Error` whose message embeds the HTTP status (`` `Coolify ${method} ${path}
+ * → ${status}: ${text}` ``, `` `CF ${method} ${path} → ${status}: ${msg}` ``).
+ * Ports are structural here (this file's own top comment: never import a
+ * concrete provider class), so this cannot `instanceof`-check a real error
+ * type -- it duck-types a `status` field first.
+ *
+ * A prior version fell back to scanning the *whole* message for a standalone
+ * `404` when no `status` field was present. That is unsafe: the Coolify and
+ * Cloudflare clients put the resource path -- which can contain a hex UUID
+ * -- ahead of the status in the message, so a UUID that happens to contain
+ * the digits `404` (`9a404b12-...`) made a genuine 500 read as a 404. The
+ * fallback below instead anchors to the exact position both clients put the
+ * status in: the first `→ `, after the client, method and path, and before
+ * `:`. It never scans the path or the response body.
+ */
+export declare function isNotFoundError(error: unknown): boolean;