@wtfalch/foundry 0.3.0 → 0.5.0

package/dist/plan/executor.d.ts

@@ -1,5 +1,6 @@
 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';
 /**
@@ -59,6 +60,7 @@ export interface CoolifyPort {
         uuid: string;
         is_usable: boolean;
         is_reachable: boolean;
+        ip?: string;
     }>>;
     requireGithubApp(preferredUuid?: string): Promise<{
         uuid: string;
@@ -104,6 +106,7 @@ export interface CoolifyPort {
         name: string;
         postgres_db: string;
         postgres_user: string;
+        postgres_initdb_args?: string;
     }): Promise<{
         uuid: string;
         internal_db_url: string;
@@ -199,6 +202,83 @@ export interface CoolifyPort {
     deleteApplication(uuid: string): Promise<unknown>;
     /** `FoundryPlanApply.destroy`'s teardown of the org's own database. */
     deleteDatabase(uuid: string): Promise<unknown>;
+    /**
+     * An application that runs a published image as-is (#128, `coolifyCalls`'s
+     * own Postgres) — matches `@wtfalch/providers`' `CoolifyClient.
+     * createDockerImageApplication` method-for-method.
+     */
+    createDockerImageApplication(input: {
+        project_uuid: string;
+        server_uuid: string;
+        environment_name: string;
+        environment_uuid: string;
+        docker_registry_image_name: string;
+        docker_registry_image_tag: string;
+        ports_exposes: string;
+        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;
+    }>;
+    /**
+     * An application built from an inline Dockerfile (#128, `coolifyCalls`'s own
+     * Synapse and MAS — neither's published image takes the module/command this
+     * stack needs from a plain image application) — matches `CoolifyClient.
+     * createDockerfileApplication` method-for-method.
+     */
+    createDockerfileApplication(input: {
+        project_uuid: string;
+        server_uuid: string;
+        environment_name: string;
+        environment_uuid: string;
+        dockerfile: string;
+        name?: string;
+        description?: string;
+        instant_deploy?: boolean;
+    }): Promise<{
+        uuid: string;
+    }>;
+    /**
+     * A single file mounted into the container (#128) — how `homeserver.yaml`
+     * and MAS's `config.yaml` reach a Docker-image application with no git
+     * repository of its own to carry them. Matches `CoolifyClient.
+     * createFileStorage` method-for-method.
+     */
+    createFileStorage(applicationUuid: string, input: {
+        mount_path: string;
+        content: string;
+    }): Promise<unknown>;
+    /** Updates an existing file storage's content in place. Matches `CoolifyClient.updateFileStorage`. */
+    updateFileStorage(applicationUuid: string, storageUuid: string, content: string): Promise<unknown>;
+    /**
+     * A generic application PATCH (#128) — `coolifyCalls` uses this to give
+     * Postgres/Synapse/MAS a fixed `custom_internal_name` so the other two can
+     * address each other by a name that never changes across a re-run, instead
+     * of guessing at Coolify's own container-naming scheme. Matches
+     * `CoolifyClient.updateApplication` method-for-method.
+     */
+    updateApplication(uuid: string, patch: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Queues a deployment (#128) — `coolifyCalls` calls this after writing a
+     * fresh Synapse/MAS config file, since a file-storage write alone does not
+     * reach the running container until its next deploy (issue #128's "a
+     * running app is redeployed when its config changed"). Fire-and-forget,
+     * like `restart` above: this executor does not poll a deployment to
+     * completion anywhere else, and `coolifyCalls` only calls this when the
+     * config it just wrote was actually freshly minted. Matches `CoolifyClient.
+     * deploy` method-for-method.
+     */
+    deploy(uuid: string, force?: boolean): Promise<unknown>;
 }
 /**
  * The Cloudflare calls this executor makes, shaped to match
@@ -222,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). */
@@ -240,6 +329,7 @@ export interface CloudflarePort {
     listAccessPolicies(appId: string): Promise<Array<{
         id: string;
         name: string;
+        include?: unknown[];
     }>>;
     createAccessPolicy(appId: string, policy: {
         name: string;
@@ -300,6 +390,105 @@ export interface CloudflarePort {
      */
     request<T>(method: string, path: string, body?: unknown, missingOkay?: boolean): Promise<T>;
 }
+/**
+ * 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 LettermintDnsRecordSpec {
+    readonly purpose: 'return_path' | 'dmarc' | 'dkim_legacy' | 'dkim_primary' | 'dkim_secondary';
+    readonly type: 'TXT' | 'CNAME' | 'MX';
+    readonly name: string;
+    readonly value: string;
+}
+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;
+}
+/**
+ * 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 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 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;
+        domain: string;
+        status: LettermintDomain['status'];
+    } | undefined>;
+    /** `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 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: LettermintDomain['status'];
+    }>;
+    /** `parkLettermintMail`'s own cleanup once an org's mail is parked (mode `'off'`). */
+    deleteDomain(id: string): Promise<void>;
+    /**
+     * `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).
+     */
+    createProject(name: string): Promise<{
+        project: LettermintProject;
+        token: string;
+    }>;
+    /** 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
  * `@wtfalch/email/postmaster`'s `applyOrgMail`/`parkOrgMail` method-for-method
@@ -309,6 +498,44 @@ export interface CloudflarePort {
 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, #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<{
+        apiKey: string;
+        apiSecret: string;
+    } | null>;
 }
 /**
  * The ZITADEL calls this executor makes. `findOrCreateOrg`/`findOrCreateProject`
@@ -359,6 +586,23 @@ export interface ZitadelPort {
         clientSecret: string;
     }>;
     deleteApp(orgId: string, projectId: string, appId: string): Promise<void>;
+    /**
+     * `zitadelApp`'s kind-change path reads this to find an app a prior,
+     * lost-response create already made under the new name, before calling
+     * `createOidcApp`/`createApiApp` again and orphaning that one under the
+     * same name. Matches `@wtfalch/providers/zitadel`'s `ZitadelClient.
+     * listApps` return shape exactly, so that client satisfies this port with
+     * no adapter -- it does not carry `clientId`/`clientSecret` (that provider
+     * method never parses either, and a secret is minted once, on creation,
+     * never handed back again), which is why the reuse path below cannot
+     * re-deliver either one.
+     */
+    listApps(orgId: string, projectId: string): Promise<Array<{
+        id: string;
+        name: string;
+        appType: 'web' | 'native' | 'api';
+        state: string;
+    }>>;
     /**
      * The org-owner flow (goal line): find-or-create the human user by email in
      * the org, then have ZITADEL email them an invite to set up a passkey.
@@ -389,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
@@ -416,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
@@ -427,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: {
@@ -450,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),
@@ -466,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: {
@@ -480,18 +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;
-    /** 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;
+    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;
+    /** 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
@@ -506,6 +862,14 @@ export interface FoundryStepExecutorPorts {
      * themselves.
      */
     deliverSecret(ref: string, secret: string): Promise<void>;
+    /**
+     * Read access to the declared-org store, narrowed to the one query
+     * `cloudflareZone` needs for its cross-org refusal check (#131) -- see that
+     * method's own doc comment for why a zone needs this where
+     * `cloudflareAccess` reads Cloudflare's own live state instead. A real host
+     * passes the same store instance it constructs `FoundryPlanApply` with.
+     */
+    declaredOrgStore: Pick<DeclaredOrgStore, 'findOrgIdForZone'>;
 }
 /**
  * Thrown by name for a step this executor deliberately does not implement:
@@ -526,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);
@@ -581,6 +959,16 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      */
     private zitadelCustomers;
     private zitadelApp;
+    /**
+     * The app an earlier attempt's recreate already made under the same
+     * name, whose response this executor never saw -- deleted before the
+     * create so no duplicate is left behind. Matches on name and the
+     * desired kind, and skips a removed app -- ZITADEL's
+     * search can return one that has since been deleted (`isNotFoundError`'s
+     * own doc comment covers why a delete can be retried into a 404), and
+     * that is not the survivor this is looking for.
+     */
+    private findRecreatedApp;
     private ensureZitadelProject;
     private ensureCoolifyProject;
     private resolveServer;
@@ -657,6 +1045,62 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * upsert a fresh value over it.
      */
     private ensureAuthCookieSecret;
+    /**
+     * #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).
+     *
+     * 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.
+     *
+     * 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.
+     *
+     * The token goes straight to `bulkUpsertEnvs` and nowhere else: never
+     * returned, never recorded in `serviceIds` (`recordScopeId`'s own doc
+     * comment), never logged, never interpolated into a thrown error -- the
+     * same discipline `pushDatabaseUrl`'s doc comment states for a database's
+     * own connection string.
+     */
+    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
@@ -774,15 +1218,204 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * this method is `cmsSite`'s only caller.
      */
     private findOrCreateCmsApp;
+    /**
+     * `plan/diff.ts`'s `planCalls`: the org's own calls Matrix stack, entirely
+     * separate from chat's (`calls-matrix.ts`'s own top doc comment) -- two
+     * Coolify-managed Postgres databases, a Synapse app and an MAS app, no
+     * public hostname of its own (neither app is reachable from outside
+     * Coolify's own Docker network) -- `coolifyCallsService` below (#145, part 2
+     * of #128) is the one that gets a public hostname, since it is the one a
+     * browser actually talks to. Park stops Synapse and MAS only, the same
+     * park-not-delete rule `coolifyApp`/`cmsSite` already follow (#7
+     * corrections 1) -- their databases are never touched from that branch, the
+     * same way `cmsSite`'s own database never is.
+     */
+    private coolifyCalls;
+    /**
+     * `coolifyCalls`'s own find-or-create for Synapse/MAS, restarting a
+     * found-but-stopped app (#116 review round 3, Finding 1's same fix). Reused
+     * by `coolifyCallsService` (#145) for the calls service app itself -- the
+     * same find-by-name-then-start-or-create shape applies unchanged.
+     */
+    private findOrCreateCallsApp;
+    /**
+     * `coolifyCalls`'s own database find-or-create, modeled on
+     * `ensureCmsDatabase`: `context.recordedIds()` is checked first since
+     * neither database has a `system:kind:key` slot of its own (this step's one
+     * auto-recorded `resourceId` is the MAS app, not either database --
+     * {@link CALLS_SYNAPSE_SCOPE_KEY}'s own doc comment), then `listDatabases`
+     * finds one already created by name before `createPostgresDatabase` makes
+     * one. Reused by `coolifyCallsService` (#145) for the calls service's own
+     * database, whose {@link CALLS_SERVICE_DB_SCOPE_KEY} has no
+     * `system:kind:key` slot of its own for the same reason.
+     */
+    private ensureCallsDatabase;
+    /**
+     * Reads back {@link CALLS_SECRET_ENV_KEYS} from the MAS app's own envs
+     * before minting fresh ones -- this stack's only memory across a re-run
+     * (`calls-matrix.ts`'s `CallsMatrixSecrets` doc comment). `changed: true`
+     * only when nothing usable was found: a partial set (a crash mid-mint) is
+     * still treated as "mint fresh", since MAS's shared secret and Synapse's
+     * copy of it must always agree.
+     */
+    private ensureCallsMatrixSecrets;
+    /**
+     * Upserts a file storage's content, creating it if the application has none
+     * at that mount path yet -- there is no way to read a file storage's
+     * current content back from Coolify to diff it, the same limit
+     * `archon/bootstrap/steps/chat-instance.ts`'s own `ensureFileStorage` notes,
+     * so an existing one is always re-written.
+     */
+    private ensureCallsFileStorage;
+    /**
+     * `plan/diff.ts`'s `planCallsService`: the org's own calls service --
+     * `wtfalch/calls`'s `packages/service`, wired to the calls Matrix stack
+     * {@link coolifyCalls} provisions and the shared LiveKit SFU (#122/#127).
+     * Static config checks run first, before any Coolify call (#128's own
+     * carried-over PR 344 review fix, restated in #145's own issue body): the
+     * calls Matrix stack must already be recorded, its MAS app must already
+     * carry its client id/secret, and the shared SFU's LiveKit credentials must
+     * already be resolvable -- none of the three is minted or guessed here.
+     * Park stops the app only, the same park-not-delete rule
+     * {@link coolifyCalls}/{@link coolifyApp} already follow (#7 corrections
+     * 1); its own database is never touched from that branch.
+     */
+    private coolifyCallsService;
+    /**
+     * Reads back the calls Matrix stack's MAS client id/secret from the MAS
+     * app's own envs ({@link CALLS_SECRET_ENV_KEYS}) -- never mints: minting
+     * either is {@link ensureCallsMatrixSecrets}'s own job, and a missing value
+     * here means that stack has not finished provisioning yet, not something
+     * this step can fix on its own.
+     */
+    private readCallsMasClientCredentials;
+    /**
+     * `null` once the calls service app already has a `CALLS_BINDING_SECRET` --
+     * never rotated, the same rule {@link ensureAuthCookieSecret} follows for
+     * `AUTH_COOKIE_SECRET`: it wraps the provider-token ciphertext already
+     * stored under any binding minted so far
+     * (`calls/packages/service/src/config.mjs`'s own doc comment on
+     * `CALLS_BINDING_SECRET`), so overwriting it would strand every binding
+     * minted under the old value. 32 raw bytes, hex-encoded -- the exact shape
+     * `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
+     * org's own domain. Refuses to adopt a zone the store already records
+     * under a *different* org's applied state (#131), the same
+     * do-not-adopt-a-foreign-resource rule `cloudflareAccess` above enforces --
+     * but where that method tells "foundry's own" from "foreign" by reading
+     * Cloudflare's own Access-app name live, a Cloudflare zone carries no
+     * org-identifying field of its own, so this asks the store instead. That
+     * matters because two different, DB-unique `domain` values (`org.ts`'s
+     * `validateDomain` plus its unique index) can still resolve to the same
+     * Cloudflare zone -- a zone is keyed by apex, and one org's domain can be a
+     * subdomain of another org's -- which is exactly the shared-zone,
+     * shared-hostname collision this ticket exists to refuse. An org re-running
+     * its own already-recorded zone is unaffected: the store then names this
+     * same org as the owner.
+     */
     private cloudflareZone;
     /**
      * `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.
+     * 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
@@ -791,6 +1424,38 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * mints the key on a background task; the next apply publishes it.
      */
     private publishMailDnsRecords;
+    /**
+     * 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 parkLettermintMail;
+    /**
+     * 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 publishLettermintDnsRecords;
+    /**
+     * Never overwrites an existing `_dmarc` record -- a stricter policy an org
+     * already set (`p=quarantine`/`p=reject`) should not be relaxed back to
+     * Lettermint's own `p=none` default.
+     */
+    private ensureLettermintDmarcRecord;
     /**
      * #80: provisions the org's own organisation on Files, before
      * {@link filesStorage} can set its spend limit. `provisionOrganisation` is
@@ -809,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
@@ -821,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;