@wtfalch/foundry 0.10.0 → 0.12.0

package/dist/plan/cloudflared-connector.js

@@ -54,8 +54,15 @@ export async function ensureCloudflaredConnector(input) {
         }
     }
     if (!appId) {
+        if (input.adopted) {
+            throw new Error(`cloudflared connector ${input.appName}: the adopted app was not found`);
+        }
+        const { projectUuid, environment } = input;
+        if (!projectUuid || !environment) {
+            throw new Error(`cloudflared connector ${input.appName}: no project to find or create it in`);
+        }
         const found = await coolify.findApplicationByName(input.appName, {
-            environmentIds: [input.environment.id],
+            environmentIds: [environment.id],
         });
         if (found) {
             const live = await liveStatus(found.uuid);
@@ -64,21 +71,21 @@ export async function ensureCloudflaredConnector(input) {
                 status = live.status;
             }
         }
-    }
-    if (!appId) {
-        const server = await input.resolveServer();
-        const created = await coolify.createDockerfileApplication({
-            project_uuid: input.projectUuid,
-            server_uuid: server.uuid,
-            environment_name: input.environment.name,
-            environment_uuid: input.environment.uuid,
-            dockerfile: cloudflaredDockerfile(),
-            name: input.appName,
-            description: 'cloudflared connector for a Cloudflare tunnel',
-            instant_deploy: false,
-        });
-        appId = created.uuid;
-        justCreated = true;
+        if (!appId) {
+            const server = await input.resolveServer();
+            const created = await coolify.createDockerfileApplication({
+                project_uuid: projectUuid,
+                server_uuid: server.uuid,
+                environment_name: environment.name,
+                environment_uuid: environment.uuid,
+                dockerfile: cloudflaredDockerfile(),
+                name: input.appName,
+                description: 'cloudflared connector for a Cloudflare tunnel',
+                instant_deploy: false,
+            });
+            appId = created.uuid;
+            justCreated = true;
+        }
     }
     if (appId !== input.recordedConnectorAppId)
         await input.recordAppId(appId);
@@ -86,6 +93,7 @@ export async function ensureCloudflaredConnector(input) {
     const tokenChanged = justCreated || (await tunnelTokenDiffers(coolify, appId, token));
     if (tokenChanged) {
         try {
+            await input.beforeTokenWrite?.(token);
             await coolify.bulkUpsertEnvs(appId, [{ key: 'TUNNEL_TOKEN', value: token, literal: true }]);
         }
         catch {

package/dist/plan/diff.d.ts

@@ -1,5 +1,6 @@
 import type { DeclaredOrg, OrgId } from '../org.js';
 import type { Plan, PlanStep, UnmanagedItem, VersionChangeItem } from '../plan.js';
+import type { Adoption } from '../store.js';
 import { type AgoraHostReading } from './agora.js';
 import type { LiveResource } from './live.js';
 import { type OrgPlatformReadiness } from './platform-org.js';
@@ -34,6 +35,17 @@ export interface PlannedStep {
 export interface PlanOrgOptions {
     /** #267: the executor was built with a `loginHostBindings` port. */
     loginHostBindings?: boolean;
+    /**
+     * #311: the host wired an `AdoptionVault` and an `AdoptionStore`, and the
+     * rows it holds. An adopting org plans a `coolify:adopt` step for each
+     * resource with no active snapshot (`isActiveSnapshot`), or, with nothing
+     * wired, reports adoption blocked and plans neither it nor the resource's
+     * own step.
+     */
+    adoption?: {
+        wired: boolean;
+        adopted: readonly Adoption[];
+    };
     /** F5: the executor was built with a `broker` port. */
     broker?: boolean;
 }

package/dist/plan/diff.js

@@ -1,11 +1,12 @@
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY } from '../org.js';
+import { adoptedConnectorKey, adoptedResources, adoptedTunnelKey, declaredAdoptUuids, isActiveSnapshot, protectsKey, } from './adopt.js';
 import { NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraHostMissing, desiredAgoraEnv, } from './agora.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
 import { appHostname, entryHostnames, tunnelDnsHostnames } from './hostnames.js';
 import { LOGIN_BINDING_SCOPE_KEY, loginBindingState, loginHostClientIds, loginHostnameFor, pendingRemovalHosts, } from './login-host.js';
 import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, } from './mail-copy.js';
-import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, appEnvAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, versionNotAppliedLine, } from './platform-diff.js';
+import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, appDeployPendingScopeKey, appEnvAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, versionNotAppliedLine, } from './platform-diff.js';
 import { DEFAULT_ORG_PLATFORM_READINESS } from './platform-org.js';
 /** The `Plan` (#19's public contract) a `PlanDetail` carries. */
 export function toPlan(detail) {
@@ -173,6 +174,10 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         plannedSteps.push(customers);
     plannedSteps.push(...planIssuerApps(org, byKey, claimed));
     plannedSteps.push(...planEntryClients(org, byKey, claimed));
+    // #311: the snapshot of each adopted resource, before the database and app
+    // steps that first write to them.
+    const adoption = planAdoptions(org, options.adoption);
+    plannedSteps.push(...adoption.steps);
     // The Access gate before the database, app, tunnel and zone (#84): on a
     // first apply the hostname is gated before anything answers on it.
     plannedSteps.push(...planAccess(org, recordedIds));
@@ -182,16 +187,90 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // string into the app's environment once the database exists -- it can
     // only do that if the database step already ran and recorded the
     // database's resource id.
-    const database = planDatabase(org, byKey, claimed);
-    if (database)
+    // A park of an adopted resource is reported, never planned (#311).
+    const parks = [];
+    const notAdoptedPark = (s) => {
+        const held = adoptedPark(org, options.adoption?.adopted ?? [], recordedIds, s);
+        if (held)
+            parks.push(held);
+        return !held;
+    };
+    // An adopt step plans its resource's step after it, whatever the markers
+    // say: the adopted resource has not been configured by foundry yet.
+    const adopting = new Set(adoption.steps.map((s) => s.action.key));
+    const database = planDatabase(org, byKey, claimed) ??
+        (adopting.has(`coolify:database:${org.id}`)
+            ? {
+                action: {
+                    system: 'coolify',
+                    kind: 'database',
+                    key: org.id,
+                    desired: { enabled: true },
+                },
+                step: {
+                    description: `record ${org.slug}'s adopted database`,
+                    destroys: false,
+                    migrates: false,
+                },
+            }
+            : null);
+    if (database &&
+        notAdoptedPark(database) &&
+        !adoption.withheld.has(`coolify:database:${org.id}`)) {
         plannedSteps.push(database);
+    }
     const authIssuer = 'error' in agoraHost ? null : agoraHost.issuer;
-    const app = planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer);
-    plannedSteps.push(...app.steps);
+    const app = planApps(org, byKey, claimed, recordedIds, plannedSteps, adopting, authIssuer);
+    plannedSteps.push(...app.steps.filter((s) => notAdoptedPark(s) && !adoption.withheld.has(`coolify:app:${s.action.key}`)));
     // After the apps: the broker entry's key is minted into each app's env.
     const brokerEntries = planBrokerEntries(org, recordedIds, plannedSteps, options.broker ?? false);
     plannedSteps.push(...brokerEntries.steps);
-    const tunnel = planTunnel(org, byKey, claimed, recordedIds);
+    // An adopt step of the tunnel or its connector plans the tunnel step after
+    // it, whatever the markers say: foundry has not merged its routes yet (#312).
+    const tunnelKey = adoptedTunnelKey(org);
+    const connectorKey = adoptedConnectorKey(org);
+    const tunnelHeld = adoption.withheld.has(tunnelKey) || adoption.withheld.has(connectorKey);
+    const planned = planTunnel(org, byKey, claimed, recordedIds);
+    const merging = org.hosting.adopt?.tunnel !== undefined &&
+        (planned !== null || adopting.has(tunnelKey) || adopting.has(connectorKey));
+    const tunnelPlanned = merging && planned?.action.desired.enabled !== false
+        ? {
+            action: {
+                system: 'cloudflare',
+                kind: 'tunnel',
+                key: org.id,
+                desired: { enabled: true },
+            },
+            step: {
+                description: `merge ${org.slug}'s routes into its adopted Cloudflare tunnel and keep the others`,
+                destroys: false,
+                migrates: false,
+            },
+        }
+        : planned;
+    // An adopted tunnel with no active snapshot and no adopt step in this plan
+    // (hosting off plans none) cannot be written to: reported blocked, no tunnel
+    // step, or the step would throw on every apply (rule 2, #312).
+    const adoptedRows = options.adoption?.adopted ?? [];
+    const activeRow = (key, uuid) => isActiveSnapshot(adoptedRows.find((r) => r.resourceKey === key), uuid ?? '');
+    const adoptable = org.hosting.adopt?.tunnel !== undefined &&
+        !tunnelHeld &&
+        !adopting.has(tunnelKey) &&
+        !adopting.has(connectorKey) &&
+        (!org.hosting.enabled ||
+            !(activeRow(tunnelKey, org.hosting.adopt.tunnel) &&
+                activeRow(connectorKey, org.hosting.adopt.connectorApp)));
+    if (adoptable) {
+        adoption.blocked.push({
+            description: `${org.slug}'s ${tunnelKey} is blocked, not planned: hosting is off, so its routes are not merged into the adopted tunnel`,
+            key: `coolify:adopt:${tunnelKey}`,
+        });
+    }
+    // Neither a snapshot-less adopted tunnel nor an undeclared one is written to
+    // or parked (#312); a blocked adoption plans no tunnel step (rule 2).
+    const tunnel = tunnelPlanned && notAdoptedPark(tunnelPlanned) && !tunnelHeld && !adoptable
+        ? tunnelPlanned
+        : null;
     // #238: a tunnel that is being provisioned waits for an active zone; parking
     // one never does.
     if (tunnel && zoneWaiting && tunnel.action.desired.enabled !== false) {
@@ -292,6 +371,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     unmanaged.push(...zoneBlocked);
     // #243: an appEnv source nothing will record is reported, not silently skipped.
     unmanaged.push(...app.blocked);
+    unmanaged.push(...adoption.blocked, ...parks);
     unmanaged.push(...brokerEntries.blocked);
     return { orgId: org.id, plannedSteps, unmanaged, versionChanges };
 }
@@ -1331,6 +1411,117 @@ function planAgora(org, byKey, claimed, recordedIds, reading) {
         blocked: null,
     };
 }
+/**
+ * #311: one `coolify:adopt` step per adopted resource that has no adoption row
+ * yet. It `migrates`, so apply needs the org's name typed. With no vault and
+ * store wired, each is reported blocked instead, and `withheld` names the
+ * resources whose own step must not plan either: it would write to a live
+ * resource nothing has snapshotted (rule 2).
+ */
+function planAdoptions(org, adoption) {
+    const steps = [];
+    const blocked = [];
+    const withheld = new Set();
+    for (const resource of adoptedResources(org)) {
+        const what = resource.kind === 'app'
+            ? `${resource.entry.key} app`
+            : resource.kind === 'connector'
+                ? 'cloudflared connector'
+                : resource.kind;
+        if (!adoption?.wired) {
+            withheld.add(resource.resourceKey);
+            blocked.push({
+                description: `${org.slug}'s adoption of its ${what} is blocked, not planned: no adoption vault is wired`,
+                key: `coolify:adopt:${resource.resourceKey}`,
+            });
+            continue;
+        }
+        const row = adoption.adopted.find((r) => r.resourceKey === resource.resourceKey);
+        // A new snapshot of another uuid would record foundry's own earlier writes.
+        if (row?.state === 'adopted' && row.settings.uuid !== resource.uuid) {
+            withheld.add(resource.resourceKey);
+            blocked.push({
+                description: `${org.slug}'s ${resource.resourceKey} is adopted as ${String(row.settings.uuid)}, not ${resource.uuid}: restore the adopted ${resource.kind} first, not planned`,
+                key: `coolify:adopt:${resource.resourceKey}`,
+            });
+            continue;
+        }
+        if (isActiveSnapshot(row, resource.uuid))
+            continue;
+        // A snapshot of a uuid another key holds would record foundry's own writes.
+        const holder = adoption.adopted.find((r) => r.resourceKey !== resource.resourceKey &&
+            protectsKey(r) &&
+            r.settings.uuid === resource.uuid);
+        if (holder) {
+            withheld.add(resource.resourceKey);
+            blocked.push({
+                description: `${org.slug}'s ${resource.resourceKey} declares ${resource.uuid}, which ${holder.resourceKey} already adopted: declare it under one key, not planned`,
+                key: `coolify:adopt:${resource.resourceKey}`,
+            });
+            continue;
+        }
+        steps.push({
+            action: {
+                system: 'coolify',
+                kind: 'adopt',
+                key: resource.resourceKey,
+                desired: { uuid: resource.uuid },
+            },
+            step: {
+                description: `adopt ${org.slug}'s ${what} (Coolify ${resource.uuid}): snapshot it, then change only what the org declares`,
+                destroys: false,
+                migrates: true,
+            },
+        });
+    }
+    // An entry that was adopted and no longer declares `adopt` is not managed
+    // as foundry's own app or database (rule 2), restored or not.
+    const held = (key) => adoption?.adopted.some((r) => r.resourceKey === key && protectsKey(r));
+    const undeclared = [
+        ...(org.hosting.enabled
+            ? [
+                ...(org.hosting.adopt?.database ? [] : [`coolify:database:${org.id}`]),
+                ...org.hosting.entries
+                    .filter((entry) => !entry.adopt)
+                    .map((entry) => `coolify:app:${appStepKey(org, entry.key)}`),
+            ]
+            : []),
+        // The tunnel and its connector are held with hosting off too (#312).
+        ...(org.hosting.adopt?.tunnel ? [] : [adoptedTunnelKey(org)]),
+        ...(org.hosting.adopt?.connectorApp ? [] : [adoptedConnectorKey(org)]),
+    ];
+    for (const key of undeclared.filter(held)) {
+        withheld.add(key);
+        blocked.push({
+            description: `${org.slug}'s ${key} was adopted, so foundry does not manage it as its own: declare adopt again, or run restore to put it back as it was, not planned`,
+            key: `coolify:adopt:${key}`,
+        });
+    }
+    return { steps, blocked, withheld };
+}
+/**
+ * The blocked item for a park step on a resource foundry adopted: its key has
+ * a row that protects it (`adopted`, `confirmed` or `restored`), or its recorded id is a uuid the org
+ * declares as adopted. `null` for any other step (#311).
+ */
+function adoptedPark(org, rows, recordedIds, { action }) {
+    if (action.desired.enabled !== false)
+        return null;
+    const parkable = action.system === 'coolify'
+        ? action.kind === 'app' || action.kind === 'database'
+        : action.system === 'cloudflare' && action.kind === 'tunnel';
+    if (!parkable)
+        return null;
+    const key = `${action.system}:${action.kind}:${action.key}`;
+    const id = recordedIds[key];
+    const held = rows.some((r) => r.resourceKey === key && protectsKey(r));
+    if (!held && !(id && declaredAdoptUuids(org).has(id)))
+        return null;
+    return {
+        description: `${org.slug}'s ${key} is adopted, not stopped: foundry never stops a resource it adopted`,
+        key: `coolify:adopt:${key}`,
+    };
+}
 /**
  * The shared on/off shape behind {@link planApp}, {@link planDatabase} and
  * {@link planTunnel} (#71): a per-org singleton resource, keyed by the org
@@ -1435,7 +1626,24 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
         key: stepKey,
         desired: { enabled: true },
     };
-    if (live.config.hasLogVolume === false) {
+    // An adopted app patched but not yet deployed: replanned whatever the
+    // markers say (#311).
+    if (entry.adopt && recordedIds[appDeployPendingScopeKey(entryKey)]) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `deploy ${org.slug}'s ${label} settings to the adopted app`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked,
+        };
+    }
+    // An adopted app gets no volume (`executor.ts`'s `coolifyApp`), so a missing
+    // one is not a drift (#311).
+    if (live.config.hasLogVolume === false && !entry.adopt) {
         return {
             step: {
                 action,
@@ -1454,7 +1662,11 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
     // names (`envNames` absent) reads as compliant, like `hasLogVolume`.
     const envNames = live.config.envNames;
     const dbLive = byKey.get(resourceKey('coolify', 'database', org.id));
-    const dbReady = entry.database && Boolean(recordedIds[`coolify:database:${org.id}`]);
+    // An adopted app or database keeps the addresses it has (#311).
+    const dbReady = entry.database &&
+        !entry.adopt &&
+        !org.hosting.adopt?.database &&
+        Boolean(recordedIds[`coolify:database:${org.id}`]);
     if (dbReady && dbLive?.config.hasInternalUrl === false) {
         // Rule 2: the push cannot succeed yet, so report it rather than replan
         // forever.
@@ -1564,7 +1776,7 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
  * {@link planApp} once per hosting entry. A key with no declared entry still
  * runs for `app`, so an org that turns hosting off parks the app it has live.
  */
-function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer) {
+function planApps(org, byKey, claimed, recordedIds, plannedSteps, adopting, authIssuer) {
     const steps = [];
     const blocked = [];
     // An entry removed from the list while its app is recorded is parked like a
@@ -1586,6 +1798,17 @@ function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer) {
                 continue;
         }
         const app = planApp(org, key, byKey, claimed, recordedIds, plannedSteps, authIssuer);
+        const stepKey = appStepKey(org, key);
+        if (!app.step && adopting.has(`coolify:app:${stepKey}`)) {
+            app.step = {
+                action: { system: 'coolify', kind: 'app', key: stepKey, desired: { enabled: true } },
+                step: {
+                    description: `apply ${org.slug}'s ${key === APP_ENTRY_KEY ? 'app' : `${key} app`} settings, hostnames and env to the adopted app`,
+                    destroys: false,
+                    migrates: false,
+                },
+            };
+        }
         // The executor pushes the issuer the plan read, the way Agora gets its host values.
         if (app.step && app.step.action.desired.enabled !== false) {
             const signsIn = org.hosting.entries.some((e) => e.key === key && e.uses?.auth);

package/dist/plan/executor.d.ts

@@ -1,6 +1,9 @@
 import type { OrgMailOptions, OrgMailOrg, OrgMailResult } from '@wtfalch/email/postmaster';
 import type { DeclaredOrg, HostingBuildPack } from '../org.js';
-import type { DeclaredOrgStore } from '../store.js';
+import type { UnmanagedItem } from '../plan.js';
+import type { Adoption, AdoptionStore, DeclaredOrgStore } from '../store.js';
+import { type IngressRoute } from './adopt.js';
+import type { AdoptionVault } from './adoption-vault.js';
 import { type BrokerPort } from './broker-entries.js';
 import type { StepAction } from './diff.js';
 import { type LoginHostBindingsPort } from './login-host.js';
@@ -181,9 +184,13 @@ export interface CoolifyPort {
      * `is_preview === false` the same way a deployed-config reader must.
      */
     listEnvs(applicationUuid: string): Promise<Array<{
+        uuid?: string;
         key: string;
         value: string;
         is_preview: boolean;
+        is_buildtime?: boolean;
+        is_literal?: boolean;
+        is_multiline?: boolean;
     }>>;
     /** Escape hatch (`CoolifyClient.raw`) — used for stop/start, which have no typed method yet. */
     raw(method: string, path: string, body?: unknown): Promise<unknown>;
@@ -380,6 +387,18 @@ export interface CloudflarePort {
         name: string;
     }>;
     putTunnelConfig(tunnelId: string, config: unknown): Promise<unknown>;
+    /**
+     * #312: the tunnel's live configuration, `config` null for a tunnel never
+     * configured. Matches `@wtfalch/providers`' `CloudflareClient.getTunnelConfig`.
+     * `cloudflareTunnel` reads it on every apply of an adopted tunnel, to merge
+     * its routes into the live ingress list rather than overwrite it.
+     */
+    getTunnelConfig(tunnelId: string): Promise<{
+        config: {
+            ingress: IngressRoute[];
+            [field: string]: unknown;
+        } | null;
+    }>;
     /**
      * The tunnel's connector token (#197) -- a `cloudflared` container reads
      * this at boot to dial into the tunnel. A live credential: matches
@@ -585,6 +604,18 @@ export interface LettermintPort {
      */
     restrictDomainToProjects(domainId: string, projectIds: readonly string[]): Promise<void>;
 }
+/**
+ * `OrgMailOrg` with `domain` required (#345): a relay route is keyed to a
+ * domain, and `OrgMailOrg.domain` is absent for a level-1 org (its domain is
+ * `${slug}.${apex}`, resolved only once `applyOrgMail` returns
+ * `OrgMailResult.domain`) -- so a caller of `MailPort`'s three relay methods
+ * below must already hold that resolved domain and pass it explicitly,
+ * rather than the port guessing or refusing on a level-1 org's bare
+ * `mailOrgFor` result.
+ */
+export type OrgRelayMailOrg = OrgMailOrg & {
+    readonly domain: string;
+};
 /**
  * The Stalwart calls this executor makes for one org's mail, shaped to match
  * `@wtfalch/email/postmaster`'s `applyOrgMail`/`parkOrgMail` method-for-method
@@ -599,14 +630,17 @@ export interface MailPort {
      * (#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`
+     * on the resolved domain, so this port method never has to. `options` is
+     * the same `{ apex, mailHost }` `applyOrgMail`/`parkOrgMail` take, needed
+     * for the same reason: `@wtfalch/email/postmaster`'s `createMailbox` takes
+     * it to resolve the shared mail apex (#335). `ensureOwnerMailbox`
      * and `ensureRoleMailboxes` (#230) below are this executor's callers, and each checks its own recorded scope
      * id first, so a second apply never calls this at all.
      */
     createMailbox(org: OrgMailOrg, mailbox: {
         address: string;
         name: string;
-    }): Promise<void>;
+    }, options: OrgMailOptions): Promise<void>;
     /**
      * Upserts this org's own outbound relay route on Stalwart (#149): an
      * `MtaRoute` through Lettermint, restricted to `org`'s domain, keyed by
@@ -617,25 +651,29 @@ export interface MailPort {
      * minted (`ensureOrgLettermintRelay`'s own mint rule) -- it goes straight
      * here and nowhere else: never returned, never recorded, never logged, the
      * same discipline `ensureAppLettermintMail`'s own doc comment states for
-     * `LETTERMINT_API_TOKEN`.
+     * `LETTERMINT_API_TOKEN`. `org.domain` is required (#345): a level-1 org
+     * has none of its own on `OrgMailOrg`, so the caller passes the domain
+     * `applyOrgMail` already resolved for it.
      */
-    applyOrgRelay(org: OrgMailOrg, secret: string): Promise<void>;
+    applyOrgRelay(org: OrgRelayMailOrg, secret: string): Promise<void>;
     /**
      * Drops this org's relay route (#149), implemented with
      * `@wtfalch/email/postmaster`'s own `removeOrgRelay` -- a missing route is
      * a no-op, so `parkLettermintMail` can call this unconditionally before it
-     * deletes the Lettermint project the route pointed at.
+     * deletes the Lettermint project the route pointed at. `org.domain` is
+     * required (#345), the same reason {@link MailPort.applyOrgRelay} needs it.
      */
-    removeOrgRelay(org: OrgMailOrg): Promise<void>;
+    removeOrgRelay(org: OrgRelayMailOrg): Promise<void>;
     /**
      * True once this org's relay route exists on Stalwart with a secret set
      * (#149). `ensureOrgLettermintRelay`'s own mint rule reads this alongside
      * Lettermint's own project listing: a project without a live route (the
      * route recorded a token this executor never minted) is exactly as
      * unhealthy as a route with no project behind it, so a fresh mint fixes
-     * either.
+     * either. `org.domain` is required (#345), the same reason
+     * {@link MailPort.applyOrgRelay} needs it.
      */
-    hasOrgRelay(org: OrgMailOrg): Promise<boolean>;
+    hasOrgRelay(org: OrgRelayMailOrg): Promise<boolean>;
 }
 /**
  * The shared calls SFU's own per-org LiveKit API credentials (#122, #127,
@@ -1185,6 +1223,17 @@ export interface FoundryStepExecutorPorts {
      * passes the same store instance it constructs `FoundryPlanApply` with.
      */
     declaredOrgStore: Pick<DeclaredOrgStore, 'findOrgIdForZone'>;
+    /**
+     * #311: where an adoption keeps the env values of the live app it takes
+     * over. Optional with `adoptionStore`: without both, the planner reports
+     * adoption as blocked and plans no `coolify:adopt` step
+     * (`FoundryPlanApplyOptions`).
+     */
+    adoptionVault?: AdoptionVault;
+    /** #311: the rows that hold the non-secret part of each snapshot. */
+    adoptionStore?: AdoptionStore;
+    /** #311: the clock of a snapshot's `takenAt`; the host passes `FoundryPlanApply`'s own. Defaults to the real clock. */
+    now?: () => Date;
 }
 /**
  * Thrown by name for a step this executor deliberately does not implement:
@@ -1355,6 +1404,49 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     private ensureZitadelProject;
     private ensureCoolifyProject;
     private resolveServer;
+    /** The live app Coolify holds under `uuid`. The error names the id only (rule 6). */
+    private readLiveApp;
+    /** The live ingress routes of the adopted tunnel `id`. The error names the id only (rule 6). */
+    private readAdoptedIngress;
+    /**
+     * #311: for each adopted resource, the lines its `coolify:adopt` step shows
+     * (a setting with old value beside new; an env var by name only) and what
+     * is blocked. Read from the live app on every plan. No value of an env var
+     * leaves this method (rule 6).
+     */
+    adoptionReport(org: DeclaredOrg, recorded: Readonly<Record<string, string>>): Promise<{
+        details: Record<string, string[]>;
+        blocked: UnmanagedItem[];
+        withheld: string[];
+    }>;
+    /**
+     * #311: puts each adopted app back as its snapshot recorded it, touching
+     * only what foundry writes: the settings it patches and the env names it
+     * owns (an edit a person made to anything else stays). Owned names the
+     * snapshot has are written back with its value and flags; owned names it
+     * lacks are deleted; preview rows are left alone. Every vault entry and
+     * live read happens first, so a missing entry or a row that cannot be
+     * deleted refuses before any Coolify write. Errors name ids only, and the
+     * vault's env values go to `bulkUpsertEnvs` and nowhere else (rule 6).
+     */
+    restoreAdoption(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, rows: readonly Adoption[]): Promise<{
+        envDeleted: string[];
+        tokenLeft: string[];
+    }>;
+    /**
+     * #311: records what a live app or database looked like before foundry
+     * first writes to it, in this order: the env values to the vault, the
+     * non-secret settings to the row, then both read back and compared. The
+     * step writes nothing to Coolify, so a snapshot that fails stops the apply
+     * before any later step does. Every error names ids only (rule 6).
+     */
+    private coolifyAdopt;
+    /** #311: whether the resource was adopted: its row is `adopted` or `confirmed`, or `id` is a declared adopt uuid. */
+    private isAdopted;
+    /** #311: refuses to manage as foundry's own a resource whose row protects its key and whose declaration has no `adopt`. */
+    private refuseTakeover;
+    /** #311: refuses to write to a declared adopt uuid that has no active snapshot. */
+    private requireSnapshot;
     private coolifyApp;
     /**
      * #75: mounts a persistent volume at {@link LOG_DIR} on the app, unless one
@@ -1818,6 +1910,24 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     /** `deliverSecret`, tried up to {@link JOBS_DELIVERY_ATTEMPTS} times; true once one attempt succeeds. */
     private deliverWithRetry;
     private cloudflareTunnel;
+    /**
+     * Runs `call`; for an adopted resource a failure that is not one of this
+     * file's own messages (which name hostnames and record types only) is
+     * replaced by `label`, because a client's error text carries response
+     * bodies (rule 6, #312).
+     */
+    private guarded;
+    /**
+     * #312: writes the org's routes into the adopted tunnel's LIVE ingress list
+     * (`mergeIngress`), not the snapshot, so a route a person added since is
+     * kept too. The declared names go into the tunnel row's `written` only after
+     * the write that carried them succeeded, so a crash in between leaves a
+     * route taken as foreign and kept. Writes nothing when the merged list is the
+     * live one. Errors name the tunnel id and the operation only.
+     */
+    private mergeAdoptedIngress;
+    /** #312: replaces the `settings` of an adoption row, read fresh so no other key is lost. The state and `takenAt` stay. */
+    private updateAdoptionSettings;
     /**
      * #236: when this tunnel's DNS was last published under a domain that
      * differs from the one `org` now declares, deletes every CNAME in the