@wtfalch/foundry 0.31.0 → 0.33.1

package/dist/plan/confirm-upgrade.d.ts

@@ -0,0 +1,17 @@
+import type { VersionChangeItem } from '../plan.js';
+export interface UnconfirmedUpgrade {
+    service: string;
+    from?: string;
+    to?: string;
+}
+/**
+ * Whether a change of `service` from `from` to `to` needs a confirmation:
+ * any change on a stateful service, otherwise a major or minor difference.
+ * A git ref or branch name has no major or minor, so it never counts as a jump.
+ */
+export declare function versionChangeNeedsConfirmation(service: string, from: string, to: string): boolean;
+/**
+ * The lines that need a confirmation `confirmUpgrade` does not give. A name
+ * must match `VersionChangeItem.service` exactly; no value confirms all.
+ */
+export declare function unconfirmedUpgrades(versionChanges: readonly VersionChangeItem[] | undefined, confirmUpgrade: readonly string[] | undefined): UnconfirmedUpgrade[];

package/dist/plan/confirm-upgrade.js

@@ -0,0 +1,47 @@
+/**
+ * The `VersionChangeItem.service` names whose data the service migrates on
+ * first boot with a new image, so going back to the old image may not undo
+ * it. Stalwart is reported as `mail`, the name of its plan step. Postgres
+ * has no version-change line yet; its name is here for when it gets one.
+ */
+const STATEFUL_VERSION_CHANGE_SERVICES = new Set([
+    'zitadel',
+    'mail',
+    'synapse',
+    'mas',
+    'postgres',
+]);
+function majorMinor(version) {
+    const match = /^v?(\d+)\.(\d+)\.\d+/.exec(version.trim());
+    return match ? `${match[1]}.${match[2]}` : null;
+}
+/**
+ * Whether a change of `service` from `from` to `to` needs a confirmation:
+ * any change on a stateful service, otherwise a major or minor difference.
+ * A git ref or branch name has no major or minor, so it never counts as a jump.
+ */
+export function versionChangeNeedsConfirmation(service, from, to) {
+    if (from === to)
+        return false;
+    if (STATEFUL_VERSION_CHANGE_SERVICES.has(service))
+        return true;
+    const a = majorMinor(from);
+    const b = majorMinor(to);
+    return a !== null && b !== null && a !== b;
+}
+/**
+ * The lines that need a confirmation `confirmUpgrade` does not give. A name
+ * must match `VersionChangeItem.service` exactly; no value confirms all.
+ */
+export function unconfirmedUpgrades(versionChanges, confirmUpgrade) {
+    const confirmed = new Set(confirmUpgrade ?? []);
+    const seen = new Set();
+    const result = [];
+    for (const line of versionChanges ?? []) {
+        if (!line.needsConfirmation || confirmed.has(line.service) || seen.has(line.service))
+            continue;
+        seen.add(line.service);
+        result.push({ service: line.service, from: line.from, to: line.to });
+    }
+    return result;
+}

package/dist/plan/diff.d.ts

@@ -55,6 +55,8 @@ export interface PlanOrgOptions {
     archonUrl?: string | null;
     /** #318: the executor was built with a `WorkersPort`, read by `planWorkers`. */
     edgeWorkers?: boolean;
+    /** The executor was built with an `ownerInviteMail` port; without it each owner's invite is blocked. */
+    ownerInviteMail?: boolean;
     /** The platform's own service hostnames: `edgeReservedLabels` reserves them under the org's domain, and a wildcard Worker route (`planWorkers`) keeps them out. */
     platformHostnames?: readonly string[];
 }
@@ -134,7 +136,7 @@ export declare function computePlanDetail(org: DeclaredOrg, live: LiveResource[]
  * computed `auth.<domain>` against, so the platform's own org never plans
  * its login host equal to the shared ZITADEL instance's own.
  */
-export declare function isPlatformOwnOrg(org: DeclaredOrg, platformApex: string | null): boolean;
+export declare function isPlatformOwnOrg(org: Pick<DeclaredOrg, 'id'>, platformOwnerOrgId: string | null): boolean;
 /**
  * What {@link planOrgPostgres} reports about the org's one shared Postgres
  * server and its fixed schema topology (#444a, "manifest-and-plan-only"):

package/dist/plan/diff.js

@@ -1,7 +1,7 @@
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, ownerMailboxRecorded, ownerMailboxes, } from '../org.js';
 import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CHAT_CALLS_APPLIED_SCOPE_KEY, CHAT_CALLS_TOKEN_SCOPE_KEY, CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, chatCallsApplied, chatHasUpstreams, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
-import { BOULE_BROKER_ENTRY_KEY, BOULE_MAIL_TOKEN_ENV, bouleEnvDrift, bouleMailTokenDrift, bouleMailWanted, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
+import { BOULE_BRIDGE_SECRET_ENV, BOULE_BROKER_ENTRY_KEY, BOULE_MAIL_TOKEN_ENV, BOULE_PEER_PASSWORD_ENV, BOULE_SECRETS_RESTARTED_SCOPE_KEY, bouleEnvDrift, bouleMailTokenDrift, bouleMailWanted, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
 import { chatInternalNames, chatUpstreams } from './chat-matrix.js';
 import { planEntryAiKeys } from './entry-ai-key.js';
@@ -16,6 +16,7 @@ import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_
 import { DEFAULT_ORG_PLATFORM_READINESS, } from './platform-org.js';
 import { PLATFORM_AUTH_BROKER_MAIL_KEY_REF } from './platform-providers.js';
 import { appLabelsAppliedScopeKey, entryLabelHash, entryLabelSpec } from './proxy-labels.js';
+import { ZITADEL_ORG_DOMAIN_BLOCKED_SCOPE_KEY, ZITADEL_ORG_DOMAIN_SCOPE_KEY, ZITADEL_ORG_REGISTRATION_CLOSED_SCOPE_KEY, signInDomainBlockedText, signInOrgDomain, } from './sign-in-org.js';
 import { withStepSystem } from './step-system.js';
 import { planWorkers } from './worker.js';
 /** The `Plan` (#19's public contract) a `PlanDetail` carries. */
@@ -165,11 +166,19 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // The platform's own org: its domain is the platform apex (the same fact
     // #491 reads for mail). It signs in on the shared instance's own host, so
     // `issuer.usesDomain` never moves it.
-    const isPlatformOrg = isPlatformOwnOrg(org, platformReadiness.platformApex);
+    const isPlatformOrg = isPlatformOwnOrg(org, platformReadiness.platformOwnerOrgId);
     const issuer = planIssuer(org, byKey, claimed, platformReadiness.authReady, isPlatformOrg);
     if (issuer.step)
         plannedSteps.push(issuer.step);
-    plannedSteps.push(...planOwners(org, recordedIds, platformReadiness.authReady, platformReadiness.authIssuer));
+    // Before the domain and the owners: no invite runs on an org still open to registration.
+    const registrationClosed = planOrgRegistrationClosed(org, recordedIds, platformReadiness.authReady, issuer.step);
+    if (registrationClosed)
+        plannedSteps.push(registrationClosed);
+    const orgDomain = planOrgDomain(org, recordedIds, platformReadiness.authReady, issuer.step);
+    if (orgDomain)
+        plannedSteps.push(orgDomain);
+    const owners = planOwners(org, recordedIds, platformReadiness.authReady, platformReadiness.authIssuer, options.ownerInviteMail ?? false, registrationClosed !== null);
+    plannedSteps.push(...owners.steps);
     // #267: after the ZITADEL org step, before any app's own issuer
     // application. Apps created later in this run are not in the binding yet;
     // the next run replans this step and repoints them.
@@ -506,6 +515,10 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // budget, key) would otherwise also have nothing to act on.
     if (issuer.blocked)
         unmanaged.push({ description: issuer.blocked, key: 'zitadel:issuer' });
+    unmanaged.push(...owners.blocked);
+    const domainBlocked = orgDomainBlocked(org, recordedIds);
+    if (domainBlocked)
+        unmanaged.push(domainBlocked);
     // #267 (rule 2): a login host with no ZITADEL org to trust it in is blocked, not planned to throw.
     if (loginHost.blocked) {
         unmanaged.push({ description: loginHost.blocked, key: 'zitadel:login-host' });
@@ -698,6 +711,70 @@ function planIssuer(org, byKey, claimed, authReady, isPlatformOrg = false) {
         blocked: null,
     };
 }
+/**
+ * Closes self-registration on a ZITADEL org that already exists and has no
+ * recorded close: one made before foundry closed it, or one whose close failed
+ * inside the issuer step. A fresh org is closed inside the issuer step, so
+ * nothing is planned beside that step. While this step is planned no owner is
+ * invited ({@link planOwners}).
+ */
+function planOrgRegistrationClosed(org, recordedIds, authReady, issuerStep) {
+    if (!authReady)
+        return null;
+    if (issuerStep?.action.desired.provision === true)
+        return null;
+    if (!recordedIds.zitadel_org)
+        return null;
+    if (recordedIds[ZITADEL_ORG_REGISTRATION_CLOSED_SCOPE_KEY] === recordedIds.zitadel_org) {
+        return null;
+    }
+    return {
+        action: { system: 'zitadel', kind: 'registration-closed', key: org.id, desired: {} },
+        step: {
+            description: `switch self-registration off on ${org.slug}'s sign-in org`,
+            destroys: false,
+            migrates: false,
+        },
+    };
+}
+/** The blocked item for an org sign-in domain the sign-in server refused to make primary. */
+function orgDomainBlocked(org, recordedIds) {
+    const domain = signInOrgDomain(org);
+    if (recordedIds[ZITADEL_ORG_DOMAIN_BLOCKED_SCOPE_KEY]?.toLowerCase() !== domain)
+        return null;
+    if (recordedIds[ZITADEL_ORG_DOMAIN_SCOPE_KEY]?.toLowerCase() === domain)
+        return null;
+    return { description: signInDomainBlockedText(org.slug, domain), key: 'zitadel:domain' };
+}
+/**
+ * Registers the org's sign-in domain (its own, or `<slug>.oikos.host`) on its ZITADEL org
+ * and makes it primary, so an owner signs in as `name@<domain>`. Idempotent on the
+ * *recorded* `zitadel_org_domain`: a changed declared domain plans it again. A fresh
+ * org gets its domain inside the issuer step, so nothing is planned beside that step.
+ * Nothing is planned until the ZITADEL org exists.
+ */
+function planOrgDomain(org, recordedIds, authReady, issuerStep) {
+    if (!authReady)
+        return null;
+    if (issuerStep?.action.desired.provision === true)
+        return null;
+    if (!recordedIds.zitadel_org)
+        return null;
+    const domain = signInOrgDomain(org);
+    if (recordedIds[ZITADEL_ORG_DOMAIN_SCOPE_KEY]?.toLowerCase() === domain)
+        return null;
+    // Refused once: reported as blocked (see `orgDomainBlocked`), not planned again.
+    if (recordedIds[ZITADEL_ORG_DOMAIN_BLOCKED_SCOPE_KEY]?.toLowerCase() === domain)
+        return null;
+    return {
+        action: { system: 'zitadel', kind: 'domain', key: org.id, desired: { domain } },
+        step: {
+            description: `register ${domain} as ${org.slug}'s sign-in domain`,
+            destroys: false,
+            migrates: false,
+        },
+    };
+}
 /**
  * The org's owners, one step each, each invited by ZITADEL email once the org's ZITADEL org
  * exists (goal line: "the org's owner is invited by ZITADEL email and sets a
@@ -718,6 +795,11 @@ function planIssuer(org, byKey, claimed, authReady, isPlatformOrg = false) {
  * issuer step immediately before it in the same run: `plan-apply.ts`'s
  * `runSteps` awaits each planned step in array order, one at a time.
  *
+ * An owner signs in as `name@<org domain>`, so each unrecorded owner needs a work
+ * address (`mailboxAddress`, or `mail.ownerMailboxAddress` for the first owner) and the
+ * host needs an `ownerInviteMail` port to send the first-sign-in link to the personal
+ * address. Without either, that owner is a blocked item named by position (rule 2).
+ *
  * `desired` carries the owner's email so the executor can pass it to
  * `ZitadelClient.inviteOrgOwner` — but the step's own `description` never
  * does. `Plan` (the public contract `AuditLog.recordPlan`/`recordApply`
@@ -726,19 +808,40 @@ function planIssuer(org, byKey, claimed, authReady, isPlatformOrg = false) {
  * nothing here puts it anywhere beyond what audit already records for the
  * org.
  */
-function planOwners(org, recordedIds, authReady, authIssuer) {
+function planOwners(org, recordedIds, authReady, authIssuer, ownerInviteMail, registrationOpen = false) {
+    const steps = [];
+    const blocked = [];
+    // The close step is planned in this plan; the invites come with the next one, after it succeeded.
+    if (registrationOpen)
+        return { steps, blocked };
     // #177: nothing to invite into yet -- `planIssuer` already reports the
     // platform's sign-in as blocked, so these steps stay silent rather than
     // repeating it.
     if (!authReady)
-        return [];
-    const steps = [];
+        return { steps, blocked };
+    const mailboxes = ownerMailboxes(org);
     org.owners.forEach((owner, index) => {
         // Every owner is keyed by its lowercased email (as `validateOwners` compares
         // it), so reordering the list never moves a key onto another person.
         const key = `${org.id}:${owner.email.toLowerCase()}`;
         if (recordedIds[resourceKey('zitadel', 'owner', key)])
             return; // already invited.
+        const position = index + 1;
+        const mailboxAddress = mailboxes[index]?.address;
+        if (!mailboxAddress) {
+            blocked.push({
+                description: `${org.slug}'s owner ${position} is blocked, not planned: no mailboxAddress is declared, and the owner signs in as name@<the org's domain>`,
+                key: `zitadel:owner:${position}`,
+            });
+            return;
+        }
+        if (!ownerInviteMail) {
+            blocked.push({
+                description: `${org.slug}'s owner ${position} is blocked, not planned: the host has no ownerInviteMail port, and the owner cannot open their work mailbox yet`,
+                key: `zitadel:owner:${position}`,
+            });
+            return;
+        }
         steps.push({
             action: {
                 system: 'zitadel',
@@ -746,6 +849,7 @@ function planOwners(org, recordedIds, authReady, authIssuer) {
                 key,
                 desired: {
                     email: owner.email,
+                    mailboxAddress,
                     givenName: owner.givenName,
                     familyName: owner.familyName,
                     // The platform's login app, where the invite link must land (it serves `/verify`).
@@ -761,7 +865,7 @@ function planOwners(org, recordedIds, authReady, authIssuer) {
             },
         });
     });
-    return steps;
+    return { steps, blocked };
 }
 /**
  * #488: the bare hostname out of an issuer URL (`https://<hostname>`, the
@@ -771,8 +875,8 @@ function planOwners(org, recordedIds, authReady, authIssuer) {
  * computed `auth.<domain>` against, so the platform's own org never plans
  * its login host equal to the shared ZITADEL instance's own.
  */
-export function isPlatformOwnOrg(org, platformApex) {
-    return Boolean(org.domain && platformApex && org.domain.toLowerCase() === platformApex.toLowerCase());
+export function isPlatformOwnOrg(org, platformOwnerOrgId) {
+    return Boolean(platformOwnerOrgId && org.id === platformOwnerOrgId);
 }
 function platformAuthHostnameFrom(issuer) {
     if (!issuer)
@@ -2237,6 +2341,7 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
         ? `${org.slug}'s Boule mail is blocked, not planned: ${mailBlockedReason}`
         : null;
     const mailOn = mailWanted && !mailBlocked;
+    const platformOwner = isPlatformOwnOrg(org, readiness.platformOwnerOrgId);
     const action = {
         system: 'coolify',
         kind: 'boule',
@@ -2249,6 +2354,8 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
             platformApex: readiness.platformApex,
             platformLettermintProjectId: readiness.platformLettermintProjectId,
             mailBlocked: mailBlocked !== null,
+            // Only the platform's own org's Boule gets the peer password for Archon.
+            platformOwner,
         },
     };
     if (!live) {
@@ -2269,6 +2376,15 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
         bouleMailTokenDrift(liveEnv[BOULE_MAIL_TOKEN_ENV], live.config.appMailToken)) {
         drift.push(BOULE_MAIL_TOKEN_ENV);
     }
+    // The peer password is secret, so only its absence is compared.
+    if (platformOwner && !liveEnv[BOULE_PEER_PASSWORD_ENV])
+        drift.push(BOULE_PEER_PASSWORD_ENV);
+    if (platformOwner && !liveEnv[BOULE_BRIDGE_SECRET_ENV])
+        drift.push(BOULE_BRIDGE_SECRET_ENV);
+    // Secrets written but Boule not restarted since: plan the step so it restarts, minting nothing.
+    if (platformOwner && !recordedIds[BOULE_SECRETS_RESTARTED_SCOPE_KEY]) {
+        drift.push('restart after the peer password and bridge secret');
+    }
     if (drift.length === 0)
         return { step: null, blocked: null, mailBlocked };
     return {
@@ -2323,10 +2439,17 @@ function planHostingToggle(system, kind, desiredEnabled, org, byKey, claimed, de
         step: { description: describeProvision(), destroys: false, migrates: false },
     };
 }
+/**
+ * The git source of the retired shared default app (`apps/hestia`, deleted in
+ * #447). {@link planApp} uses it only to recognise a live app still built
+ * from it, which it deletes instead of parking: nothing can redeploy it.
+ */
+const RETIRED_DEFAULT_APP_REPO = 'wtfalch/foundry';
 /**
  * The org's own app on Coolify (`org.ts`'s `HostingConfig.enabled`, #71), a
  * per-org singleton resource modeled on {@link planSite}: park, not delete,
- * on the way off (#7 corrections 1).
+ * on the way off (#7 corrections 1) -- except a live app built from
+ * {@link RETIRED_DEFAULT_APP_REPO}, which is deleted (#447).
  *
  * #75: every app foundry deploys also carries a durable log directory (a
  * persistent volume mounted at `/app/logs`, `LOG_DIR` in its env) so a
@@ -2411,10 +2534,49 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
             });
         }
     }
-    const toggled = planHostingToggle('coolify', 'app', entry !== undefined, org, byKey, claimed, () => `provision ${org.slug}'s ${label}`, () => `park ${org.slug}'s ${label} (stops serving; app data is retained, not deleted -- #7 corrections 1)`, stepKey);
+    // #447: no shared default app any more. Migration 0029 wrote `repo: null`
+    // for every org without a bespoke app and nothing rewrites that data, so
+    // the entry stays declared but is blocked here and never provisioned.
+    const noRepo = entry !== undefined && entry.repo === null;
+    if (noRepo) {
+        blocked.push({
+            description: `${org.slug}'s ${label} repo is blocked, not planned: there is no shared default app any more (#447)`,
+            key: blockedKey('repo'),
+        });
+    }
+    const toggled = planHostingToggle('coolify', 'app', entry !== undefined && !noRepo, org, byKey, claimed, () => `provision ${org.slug}'s ${label}`, () => `park ${org.slug}'s ${label} (stops serving; app data is retained, not deleted -- #7 corrections 1)`, stepKey);
+    // #447: only the live app's own `git_repository` decides, never the
+    // declared entry (a `repo: null` entry can sit over a bespoke app, which is
+    // parked as before). Only the `app` key ever held the default app, and an
+    // entry that declares a repo is never a candidate. The reader does not
+    // surface the Dockerfile location, so the repo is the whole match. Checked
+    // whether or not the app is already parked, so a parked leftover is not
+    // stranded.
+    if (entryKey === APP_ENTRY_KEY && (entry === undefined || noRepo)) {
+        const liveApp = byKey.get(resourceKey('coolify', 'app', stepKey));
+        if (liveApp?.config.git_repository === RETIRED_DEFAULT_APP_REPO) {
+            claimed.add(resourceKey('coolify', 'app', stepKey));
+            return {
+                step: {
+                    action: {
+                        system: 'coolify',
+                        kind: 'app',
+                        key: stepKey,
+                        desired: { enabled: false, delete: true },
+                    },
+                    step: {
+                        description: `delete ${org.slug}'s ${label}: it still builds from the retired shared default app, which no longer exists to redeploy from (#447)`,
+                        destroys: true,
+                        migrates: false,
+                    },
+                },
+                blocked,
+            };
+        }
+    }
     if (toggled)
         return { step: toggled, blocked };
-    if (!entry)
+    if (!entry || noRepo)
         return { step: null, blocked };
     const live = byKey.get(resourceKey('coolify', 'app', stepKey));
     if (!live)

package/dist/plan/executor.d.ts

@@ -14,6 +14,7 @@ import { type LoginHostBindingsPort } from './login-host.js';
 import { type MailCopyPort } from './mail-copy.js';
 import type { DestroyTarget, StepDestroyer, StepExecutionContext, StepExecutor } from './plan-apply.js';
 import type { EdgePortName } from './platform-org.js';
+export declare function coolifyProjectMark(org: Pick<DeclaredOrg, 'id'>): string;
 /**
  * The Coolify calls this executor makes, shaped to match
  * `@wtfalch/providers/coolify`'s `CoolifyClient` method-for-method — a real
@@ -36,6 +37,12 @@ export interface CoolifyPort {
         name: string;
         description?: string | null;
     } | null>;
+    /** A project's environments (`CoolifyClient.listEnvironments`), read-only. */
+    listEnvironments(projectUuid: string): Promise<Array<{
+        id: number;
+        uuid: string;
+        name: string;
+    }>>;
     createProject(name: string, description?: string): Promise<{
         uuid: string;
     }>;
@@ -878,10 +885,22 @@ export interface ZitadelPort {
         givenName: string;
         familyName: string;
         email: string;
-    }, urlTemplate?: string): Promise<{
+        username?: string;
+    }, urlTemplate?: string, returnCode?: boolean): Promise<{
         userId: string;
         created: boolean;
+        inviteCode?: string;
     }>;
+    /** Adds a domain to the org. Idempotent: a domain already on the org is a no-op. */
+    addOrgDomain(orgId: string, domain: string): Promise<void>;
+    /** Makes a domain already on the org its primary one. Idempotent: no-op when it already is. */
+    setPrimaryOrgDomain(orgId: string, domain: string): Promise<void>;
+    setUserMetadata(orgId: string, userId: string, key: string, value: string): Promise<void>;
+    getUserMetadata(orgId: string, userId: string, key: string): Promise<string | null>;
+    findUserByEmail(orgId: string, email: string): Promise<{
+        userId: string;
+        state: string;
+    } | null>;
     /**
      * Adds a role to a project. Idempotent: a role that already exists is not
      * an error. `@wtfalch/providers`' `ZitadelClient` has no project-role API,
@@ -1456,6 +1475,16 @@ export interface FoundryStepExecutorPorts {
      * compilation over one dependency nothing else needs.
      */
     mailCopy?: MailCopyPort;
+    /**
+     * Mails an owner's first-sign-in link to their personal address. The link
+     * carries the one-time invite code `inviteOrgOwner` returned, so an error
+     * from `send` must not repeat `link`. Optional: without it the planner
+     * reports each owner's invite as blocked, because the owner's work address
+     * is not a mailbox they can open yet.
+     */
+    ownerInviteMail?: {
+        send(to: string, link: string): Promise<void>;
+    };
     /**
      * #463: the cross-homeserver copy chat's forward re-key needs -- see
      * {@link ChatRekeyPort}'s own doc comment. Optional the same way
@@ -1661,7 +1690,10 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     private edgeRateLimits;
     private edgeZones;
     private edgeWriteSlot;
+    /** Secrets this executor minted or was handed; see `StepExecutor.secretsHandled`. */
+    private readonly handledSecrets;
     constructor(ports: FoundryStepExecutorPorts);
+    secretsHandled(): readonly string[];
     /** #555: the edge-routed ports this executor was built with itself (they win over edge). */
     ownEdgePorts(): Partial<Record<EdgePortName, boolean>>;
     execute(action: StepAction, context: StepExecutionContext): Promise<{
@@ -1765,12 +1797,30 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     private teardownWorker;
     private zitadelIssuer;
     /**
-     * `plan/diff.ts`'s `planOwner`: invites the org's owner into its ZITADEL
-     * org by email. Never logs, returns or throws the email itself -- only the
-     * invited user id, handed back as `resourceId` so `runSteps` records it
-     * under `zitadel:owner:<orgId>:<email>`, which is exactly what makes the next
-     * `plan()` call idempotent (`planOwner` plans nothing once that key is
-     * recorded).
+     * `plan/diff.ts`'s `planOrgRegistrationClosed`: closes self-registration on
+     * the recorded ZITADEL org, for an org made before foundry did this or whose
+     * close failed in the issuer step. Recorded only after the close returned.
+     */
+    private zitadelRegistrationClosed;
+    /**
+     * `plan/diff.ts`'s `planOrgDomain`: registers the org's sign-in domain on
+     * its recorded ZITADEL org and makes it primary, for an org whose ZITADEL
+     * org was made before foundry did this. Records the domain only after both
+     * calls succeeded.
+     */
+    private zitadelDomain;
+    /**
+     * `plan/diff.ts`'s `planOwners`: makes the owner's account in the org's
+     * ZITADEL org and mails the first-sign-in link to their personal address.
+     * The account's username is the local part of `mailboxAddress` and its email
+     * is `mailboxAddress`, so the owner signs in as `name@<org domain>`; the
+     * personal address is kept as the `personal_email` metadata. The invite code
+     * ZITADEL returns goes only into that mail. Nothing here logs, returns or
+     * throws the personal address or the code -- only the invited user id, handed
+     * back as `resourceId` so `runSteps` records it under
+     * `zitadel:owner:<orgId>:<email>`, which is exactly what makes the next
+     * `plan()` call idempotent. A failure after the account exists records
+     * nothing: the next apply finds the account by username and mints a new code.
      */
     private zitadelOwner;
     /**
@@ -1992,6 +2042,14 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     private bouleBrokerEntry;
     /** The shared tail of both broker-entry steps: read the app's key, write the entry, record what was written. */
     private writeAppBrokerEntry;
+    /**
+     * `null` once the app already has `AUTHZ_PEER_PASSWORD_OPERATOR`: minted only
+     * the first time and never rotated, like {@link ensureAuthCookieSecret}.
+     */
+    private ensurePeerPassword;
+    /** Same rule for the secret Archon's invite form sends to Boule. */
+    private ensureBridgeSecret;
+    private mintIfAbsent;
     /**
      * `null` once the app already has one -- `AUTH_COOKIE_SECRET` is generated
      * only the first time (task brief), never regenerated or overwritten, so a