@wtfalch/foundry 0.9.0 → 0.11.0

package/dist/apply.d.ts

@@ -11,6 +11,13 @@ import type { AppliedState } from './state.js';
  * `@wtfalch/audit` records every plan and apply — who, when, the plan, the
  * result.
  */
+/** What {@link PlanApply.restore} put back: resource keys and env names, never a value. */
+export interface AdoptionRestored {
+    restored: string[];
+    envDeleted: string[];
+    /** Connector rows whose TUNNEL_TOKEN was left because it is not the one foundry wrote. */
+    tokenLeft?: string[];
+}
 export interface PlanApply {
     /** Reads live state from Zitadel, Coolify and Cloudflare and diffs it
      * against the declared org (#19 "Done when"). */
@@ -38,4 +45,13 @@ export interface PlanApply {
      * `destroy` only tears down what's left.
      */
     destroy(id: OrgId, confirmedOrgName: string): Promise<void>;
+    /**
+     * Puts an adopted app back as the snapshot recorded it (#311): the settings
+     * it had, its old env values, and none of the env names foundry added. Marks
+     * each adoption `restored`. Refused unless `confirmedOrgName` matches the
+     * org's `displayName`, once the snapshot is `confirmed` (the first
+     * successful apply after the adopting one), and, before any write, when the
+     * snapshot's vault entry is missing.
+     */
+    restore(id: OrgId, confirmedOrgName: string): Promise<AdoptionRestored>;
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, EnvValue, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, DeclaredOrg, } from './org.js';
+export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, HostingEntryUses, EntryAuth, EnvValue, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, DeclaredOrg, } from './org.js';
 export { APP_ENTRY_KEY, DEFAULT_MAIL_APPS, appEntry, validateBuyerIdentity, validateHosting, validateMail, validateOwner, validateSite, } from './org.js';
 export type { DeclaredPlatform, PlatformService, PlatformServiceKey } from './platform.js';
 export { PLATFORM_SERVICE_KEYS, defaultPlatformHostname, validatePlatform, } from './platform.js';
@@ -8,9 +8,10 @@ export type { SlugRejectionReason, SlugRejection } from './slug.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
 export type { Checkpoint, LastApplied, AppliedState } from './state.js';
 export type { PlanStep, UnmanagedItem, Plan } from './plan.js';
-export type { DeclaredOrgStore, PlatformStore, RequestedChangeStore } from './store.js';
+export type { Adoption, AdoptionKind, AdoptionState, AdoptionStore, DeclaredOrgStore, PlatformStore, RequestedChangeStore, } from './store.js';
+export type { AdoptionVault } from './plan/adoption-vault.js';
 export type { PlanApply } from './apply.js';
-export { createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
+export { createPostgresAdoptionStore, createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
 export { createPostgresAuditLog } from './store/audit.js';
 export type { FoundryStoreDb } from './store/postgres.js';
 export { declaredOrgs, foundryAppliedState, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, type AuditEventRow, type DeclaredOrgRow, type NewDeclaredOrgRow, type AppliedStateRow, type NewAppliedStateRow, type DeclaredPlatformRow, type NewDeclaredPlatformRow, type RequestedChangeRow, type NewRequestedChangeRow, } from './store/schema.js';

package/dist/index.js

@@ -2,7 +2,7 @@ export { APP_ENTRY_KEY, DEFAULT_MAIL_APPS, appEntry, validateBuyerIdentity, vali
 export { PLATFORM_SERVICE_KEYS, defaultPlatformHostname, validatePlatform, } from './platform.js';
 export { REQUESTABLE_FIELDS, classifyChange, RequestedChangeError } from './requested-changes.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
-export { createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
+export { createPostgresAdoptionStore, createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
 export { createPostgresAuditLog } from './store/audit.js';
 export { declaredOrgs, foundryAppliedState, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, } from './store/schema.js';
 export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';

package/dist/migrations/0030_hosting_entry_hostnames.sql

@@ -0,0 +1,24 @@
+-- @wtfalch/foundry: each hosting entry names where it is served (org.ts's
+-- `HostingEntry.hostnames`). Mirrors `src/store/schema.ts`'s `hostingEntries`.
+--
+-- The `app` entry of an org with hosting.usesDomain on is served at the org's
+-- domain, so it gets ['@']; every other entry, and the `app` entry of an org
+-- with usesDomain off (served at <slug>.oikos.host), gets []. An org planned
+-- before this migration therefore plans the same names after it.
+--
+-- Copies and never drops: no column changes, only entries without a
+-- `hostnames` field gain one. Safe to run twice: an entry that has the field
+-- is left as it is.
+
+update foundry_declared_orgs o
+   set hosting_entries = (
+     select coalesce(jsonb_agg(
+              case when e ? 'hostnames' then e
+                   else e || jsonb_build_object(
+                     'hostnames',
+                     case when e ->> 'key' = 'app' and o.hosting_uses_domain
+                          then '["@"]'::jsonb else '[]'::jsonb end)
+              end order by t.ord), '[]'::jsonb)
+       from jsonb_array_elements(o.hosting_entries) with ordinality as t(e, ord))
+ where exists (
+   select 1 from jsonb_array_elements(o.hosting_entries) e where not (e ? 'hostnames'));

package/dist/migrations/0031_adoptions.sql

@@ -0,0 +1,37 @@
+-- @wtfalch/foundry: what foundry recorded before it first changed a live
+-- resource it took over in place (#311), and the org's declared live
+-- database. Mirrors `src/store/schema.ts`'s `foundryAdoptions` and
+-- `declaredOrgs.hostingAdopt`.
+--
+-- `settings` holds non-secret settings only. The secret part of the snapshot
+-- (env values) lives in the host's vault under `vault_ref`; no env value, URL
+-- or secret is ever written here. `kind` lists every kind the later slices add
+-- (tunnel, connector, access) so none of them needs to change this check.
+-- `state` moves adopted -> confirmed or restored or released. A row goes with
+-- its org (`on delete cascade`), so destroying a test org needs no extra step.
+--
+-- `hosting_adopt` is `HostingConfig.adopt`, null when the org adopts nothing.
+-- An entry's own `adopt` lives inside `hosting_entries` and needs no column.
+--
+-- Safe to run twice: nothing is dropped or rewritten.
+
+create table if not exists foundry_adoptions (
+  org_id        text not null,
+  resource_key  text not null,
+  kind          text not null,
+  taken_at      timestamptz not null,
+  settings      jsonb not null default '{}'::jsonb,
+  vault_ref     text,
+  state         text not null default 'adopted',
+
+  constraint foundry_adoptions_pkey primary key (org_id, resource_key),
+  constraint foundry_adoptions_org_fkey
+    foreign key (org_id) references foundry_declared_orgs (id) on delete cascade,
+  constraint foundry_adoptions_kind_check
+    check (kind in ('app', 'database', 'tunnel', 'connector', 'access')),
+  constraint foundry_adoptions_state_check
+    check (state in ('adopted', 'confirmed', 'restored', 'released'))
+);
+
+alter table foundry_declared_orgs
+  add column if not exists hosting_adopt jsonb;

package/dist/org.d.ts

@@ -196,9 +196,6 @@ export type HostingBuildPack = 'dockerfile' | 'nixpacks' | 'static' | 'dockercom
  * its apps. Each app is one of `entries`. `tunnel` is meaningless without the
  * apps running, so `validateHosting` below requires `enabled` before it can
  * be true.
- *
- * Until the planner reads more than one entry, only the entry keyed
- * {@link APP_ENTRY_KEY} is planned.
  */
 export interface HostingConfig {
     /** The org's apps run on Coolify. */
@@ -211,6 +208,15 @@ export interface HostingConfig {
     issuerApps: IssuerApp[];
     /** One entry per app the org runs. */
     entries: HostingEntry[];
+    /** Live resources foundry takes over in place instead of creating. */
+    adopt?: {
+        /** The Coolify uuid of the org's live database, taken over as `<slug>-db`. */
+        database?: string;
+        /** The id of the org's live Cloudflare tunnel: its routes are merged, never overwritten (#312). Requires `tunnel`. */
+        tunnel?: string;
+        /** The Coolify uuid of the live `cloudflared` app that dials into `tunnel` (#312). Requires `tunnel`. */
+        connectorApp?: string;
+    };
 }
 /** The key of the entry that is today's one app: the Coolify app named `<slug>`. */
 export declare const APP_ENTRY_KEY = "app";
@@ -234,6 +240,15 @@ export interface HostingEntry {
     port: number | null;
     /** The path that answers 200 when the app is healthy. `null` is none. */
     healthPath: string | null;
+    /**
+     * The names the entry is served at: `'@'` (the org's domain), a label under
+     * the domain, or `'*'` (reserved: a later change acts on it). Empty means an
+     * internal app, reached as `<slug>-<key>` on the Coolify network. Read only
+     * when `HostingConfig.usesDomain` is on and the org has a domain; otherwise
+     * the `app` entry is served at `<slug>.oikos.host` and no other entry may
+     * set any.
+     */
+    hostnames: string[];
     /** A Postgres database beside the app. At most one entry per org. */
     database: boolean;
     /** Deploy on every push to `branch`. Default: `true`. */
@@ -251,6 +266,27 @@ export interface HostingEntry {
      * this map.
      */
     env: Record<string, EnvValue>;
+    /** Takes over the live Coolify app with this uuid instead of creating one. */
+    adopt?: {
+        app: string;
+    };
+    /** What the entry signs in through. Absent means it uses nothing. */
+    uses?: HostingEntryUses;
+}
+/**
+ * Sign-in for one entry: one ZITADEL client and one broker entry, signing in
+ * ONE organisation. `staff` is the org's own ZITADEL org, `customers` the
+ * `<slug> customers` org. `registration` is the broker entry's sign-up switch.
+ * `replacesBrokerEntry` is the `name` of the hand-written broker `AUTH_APPS`
+ * entry this entry's own entry replaces; the first write removes it.
+ */
+export interface EntryAuth {
+    users: 'staff' | 'customers';
+    registration: 'open' | 'closed';
+    replacesBrokerEntry?: string;
+}
+export interface HostingEntryUses {
+    auth?: EntryAuth;
 }
 /**
  * A plain string is pushed as it is, so `validateHosting` refuses one that
@@ -281,8 +317,17 @@ export declare const APP_ENV_SOURCES: ReadonlySet<AppEnvSource>;
  * - Every `entries[]` entry follows {@link validateHostingEntry}; keys are
  *   unique, and at most one entry has a `database`, because the one
  *   `<slug>_rt` runtime role cannot serve two apps.
+ * - An adopted uuid (`entries[].adopt.app`, `adopt.database`) is non-empty
+ *   and only lowercase letters and digits (it goes into a URL path), and no two
+ *   entries adopt the same app. `adopt.database` needs an entry with `database`.
+ * - `adopt.tunnel` is a Cloudflare tunnel id (a UUID), `adopt.connectorApp` a
+ *   Coolify uuid that no entry or database adopts. `connectorApp` needs
+ *   `tunnel`, and both need `hosting.tunnel` (#312).
  */
-export declare function validateHosting(hosting: HostingConfig): string | null;
+export declare function validateHosting(hosting: HostingConfig, names?: {
+    domain: string | null;
+    locked: ReadonlySet<string>;
+}): string | null;
 export declare function validateDomain(domain: string): string | null;
 /**
  * `null` when `site` is valid; otherwise the reason it is not (#101).

package/dist/org.js

@@ -13,6 +13,9 @@ export const APP_ENV_SOURCES = new Set([
     'aiOrganisationId',
     'mailDomain',
 ]);
+const ADOPT_UUID = /^[a-z0-9]+$/;
+/** A Cloudflare tunnel id: a lowercase UUID with hyphens (#312). */
+const TUNNEL_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const ISSUER_APP_KINDS = new Set(['web', 'native', 'api']);
 const HOSTING_BUILD_PACKS = new Set([
     'dockerfile',
@@ -31,8 +34,14 @@ const HOSTING_BUILD_PACKS = new Set([
  * - Every `entries[]` entry follows {@link validateHostingEntry}; keys are
  *   unique, and at most one entry has a `database`, because the one
  *   `<slug>_rt` runtime role cannot serve two apps.
+ * - An adopted uuid (`entries[].adopt.app`, `adopt.database`) is non-empty
+ *   and only lowercase letters and digits (it goes into a URL path), and no two
+ *   entries adopt the same app. `adopt.database` needs an entry with `database`.
+ * - `adopt.tunnel` is a Cloudflare tunnel id (a UUID), `adopt.connectorApp` a
+ *   Coolify uuid that no entry or database adopts. `connectorApp` needs
+ *   `tunnel`, and both need `hosting.tunnel` (#312).
  */
-export function validateHosting(hosting) {
+export function validateHosting(hosting, names) {
     if (hosting.tunnel && !hosting.enabled) {
         return 'hosting.tunnel requires hosting.enabled';
     }
@@ -60,7 +69,27 @@ export function validateHosting(hosting) {
     if (hosting.enabled && !appEntry(hosting)) {
         return `hosting.enabled requires an entry keyed '${APP_ENTRY_KEY}'`;
     }
+    if (hosting.adopt?.database !== undefined && !hosting.adopt.database) {
+        return 'hosting.adopt.database needs a non-empty uuid';
+    }
+    if (hosting.adopt?.database && !ADOPT_UUID.test(hosting.adopt.database)) {
+        return 'hosting.adopt.database must be lowercase letters and digits only';
+    }
+    const { tunnel: adoptedTunnel, connectorApp } = hosting.adopt ?? {};
+    if (adoptedTunnel !== undefined && !TUNNEL_ID.test(adoptedTunnel)) {
+        return 'hosting.adopt.tunnel must be a Cloudflare tunnel id (a lowercase UUID with hyphens)';
+    }
+    if (connectorApp !== undefined && !ADOPT_UUID.test(connectorApp)) {
+        return 'hosting.adopt.connectorApp must be a non-empty uuid of lowercase letters and digits only';
+    }
+    if ((connectorApp === undefined) !== (adoptedTunnel === undefined)) {
+        return 'hosting.adopt.tunnel and hosting.adopt.connectorApp must be declared together';
+    }
+    if ((adoptedTunnel !== undefined || connectorApp !== undefined) && !hosting.tunnel) {
+        return 'hosting.adopt.tunnel and hosting.adopt.connectorApp require hosting.tunnel';
+    }
     const seenKeys = new Set();
+    const seenAdopted = new Set();
     for (const entry of hosting.entries) {
         if (seenKeys.has(entry.key)) {
             return `hosting.entries key '${entry.key}' is not unique`;
@@ -69,12 +98,76 @@ export function validateHosting(hosting) {
         const invalid = validateHostingEntry(entry, hosting.enabled);
         if (invalid)
             return invalid;
+        if (entry.adopt) {
+            if (!entry.adopt.app)
+                return `hosting entry '${entry.key}' adopt.app needs a non-empty uuid`;
+            if (!ADOPT_UUID.test(entry.adopt.app)) {
+                return `hosting entry '${entry.key}' adopt.app must be lowercase letters and digits only`;
+            }
+            if (seenAdopted.has(entry.adopt.app)) {
+                return `hosting entry '${entry.key}' adopts an app another entry already adopts`;
+            }
+            seenAdopted.add(entry.adopt.app);
+            if (entry.adopt.app === hosting.adopt?.database) {
+                return `hosting entry '${entry.key}' adopts the same uuid as hosting.adopt.database`;
+            }
+            if (entry.database && !hosting.adopt?.database) {
+                return `hosting entry '${entry.key}' adopts its app and sets database, so hosting.adopt.database must name the live database`;
+            }
+        }
+        const invalidAuth = validateEntryAuth(entry, hosting, names?.domain);
+        if (invalidAuth)
+            return invalidAuth;
+    }
+    if (hosting.adopt?.database && !hosting.entries.some((entry) => entry.database)) {
+        return 'hosting.adopt.database is set, so an entry must set database';
     }
+    if (connectorApp && (seenAdopted.has(connectorApp) || connectorApp === hosting.adopt?.database)) {
+        return 'hosting.adopt.connectorApp is the uuid of an adopted app or database';
+    }
+    const invalidNames = validateEntryHostnames(hosting, names);
+    if (invalidNames)
+        return invalidNames;
     if (hosting.entries.filter((entry) => entry.database).length > 1) {
         return 'at most one hosting entry may set database: the one runtime database role cannot serve two apps';
     }
     return null;
 }
+/**
+ * The rules for the names of every entry: each is `@`, `*` or a DNS label, no
+ * name twice, none on a name foundry owns (`plan/locked-hostnames.ts`), and
+ * none at all on a non-`app` entry while `usesDomain` is off. `names` is what
+ * the caller knows of the org; without it only the checks that need no domain
+ * run.
+ */
+function validateEntryHostnames(hosting, names) {
+    const taken = new Set();
+    for (const entry of hosting.entries) {
+        const at = `hosting.entries '${entry.key}'`;
+        if (!hosting.usesDomain && entry.key !== APP_ENTRY_KEY && entry.hostnames.length > 0) {
+            return `${at} hostnames need hosting.usesDomain: without it only the '${APP_ENTRY_KEY}' entry is served, at its own address`;
+        }
+        const reads = hosting.usesDomain && names?.domain;
+        if (reads && entry.key === APP_ENTRY_KEY && !entry.hostnames.some((n) => n !== '*')) {
+            return `${at} needs a hostname ('@' or a label) while hosting.usesDomain is on: '*' alone names nothing, and the app would fall back to the bare domain`;
+        }
+        for (const name of entry.hostnames) {
+            if (name !== '@' && name !== '*' && !ENTRY_KEY.test(name)) {
+                return `${at} hostname '${name}' must be '@', '*' or a DNS label`;
+            }
+            if (taken.has(name))
+                return `hostname '${name}' is held by two entries or listed twice`;
+            taken.add(name);
+            if (names?.domain &&
+                name !== '@' &&
+                name !== '*' &&
+                names.locked.has(`${name}.${names.domain}`)) {
+                return `${at} hostname '${name}' is a name foundry owns: ${name}.${names.domain}`;
+            }
+        }
+    }
+    return null;
+}
 const ENTRY_KEY = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
 const REPO = /^wtfalch\/[A-Za-z0-9._-]+$/;
 // The env names `pushAppEnv` and `pushDatabaseUrl` set themselves.
@@ -141,6 +234,46 @@ function validateHostingEntry(entry, enabled) {
     }
     return null;
 }
+/**
+ * `uses.auth`: its two switches are known values, sign-up is never open
+ * into the staff organisation, the entry has an exact
+ * hostname to sign in at (a `*` or an internal entry has none), and the
+ * client's name, which is the entry key, is not one another client holds.
+ */
+function validateEntryAuth(entry, hosting, domain) {
+    const auth = entry.uses?.auth;
+    if (!auth)
+        return null;
+    const at = `hosting.entries '${entry.key}' uses.auth`;
+    if (!hosting.enabled)
+        return `${at} requires hosting.enabled`;
+    if (auth.users !== 'staff' && auth.users !== 'customers') {
+        return `${at} users must be 'staff' or 'customers'`;
+    }
+    if (auth.registration !== 'open' && auth.registration !== 'closed') {
+        return `${at} registration must be 'open' or 'closed'`;
+    }
+    // The staff organisation holds the org's own people and its project.
+    if (auth.users === 'staff' && auth.registration === 'open') {
+        return `${at} registration 'open' needs users 'customers': nobody signs themselves up as staff`;
+    }
+    if (auth.replacesBrokerEntry !== undefined &&
+        (typeof auth.replacesBrokerEntry !== 'string' || auth.replacesBrokerEntry === '')) {
+        return `${at} replacesBrokerEntry must be the non-empty name of a broker entry`;
+    }
+    // With no domain the hostnames are not read (`entryHostnames`).
+    const hasName = hosting.usesDomain && domain !== null
+        ? entry.hostnames.some((name) => name !== '*')
+        : entry.key === APP_ENTRY_KEY;
+    if (!hasName)
+        return `${at} needs an exact hostname to sign in at`;
+    if (entry.key === 'agora' ||
+        entry.key === 'cms' ||
+        hosting.issuerApps.some((app) => app.name === entry.key)) {
+        return `${at} client name '${entry.key}' is already held by another ZITADEL client`;
+    }
+    return null;
+}
 function urlHasPassword(value) {
     try {
         return new URL(value).password !== '';

package/dist/plan/adopt.d.ts

@@ -0,0 +1,112 @@
+import type { DeclaredOrg, HostingEntry } from '../org.js';
+import type { Adoption } from '../store.js';
+/**
+ * Adoption (#311): foundry takes over a hand-made Coolify app or database
+ * where it is. Nothing in this file holds an env value: an env var is named,
+ * never quoted, in a detail line, an error or a blocked item (rule 6).
+ */
+interface AdoptedBase {
+    /** The `foundry_adoptions.resource_key`, and the `coolify:adopt` step's key. */
+    resourceKey: string;
+    uuid: string;
+}
+/**
+ * One app (with the entry that adopts it) or database an org declares by uuid,
+ * or (#312) its Cloudflare tunnel (`uuid` is the tunnel id) or the Coolify app
+ * that runs `cloudflared` for it.
+ */
+export type AdoptedResource = (AdoptedBase & {
+    kind: 'database';
+}) | (AdoptedBase & {
+    kind: 'app';
+    entry: HostingEntry;
+}) | (AdoptedBase & {
+    kind: 'tunnel';
+}) | (AdoptedBase & {
+    kind: 'connector';
+});
+/** The `foundry_adoptions.resource_key` of the org's adopted tunnel: also its `serviceIds` key (#312). */
+export declare const adoptedTunnelKey: (org: DeclaredOrg) => string;
+/** The `foundry_adoptions.resource_key` of the org's adopted connector app (#312). */
+export declare const adoptedConnectorKey: (org: DeclaredOrg) => string;
+/** Every resource the org adopts, the database first, then the apps, the tunnel and its connector. */
+export declare function adoptedResources(org: DeclaredOrg): AdoptedResource[];
+/**
+ * Every uuid the org declares as adopted, whether or not hosting is enabled
+ * now: a uuid in this set is never stopped or deleted by foundry (#311).
+ */
+export declare function declaredAdoptUuids(org: DeclaredOrg): Set<string>;
+/**
+ * A snapshot is ACTIVE when its row is `adopted` or `confirmed` and the uuid
+ * it recorded is the uuid the org declares now (#311). Only then may foundry
+ * write to the live resource.
+ */
+export declare function isActiveSnapshot(row: Adoption | null | undefined, uuid: string): boolean;
+/**
+ * A row in `adopted`, `confirmed` or `restored` protects its key: foundry never
+ * manages, stops or deletes that resource as its own. Only `released` lets go (#311).
+ */
+export declare function protectsKey(row: Adoption | null | undefined): boolean;
+/** Where the secret part of a snapshot lives in the `AdoptionVault`. */
+export declare function adoptionVaultRef(org: DeclaredOrg, resource: AdoptedResource): string;
+export type LiveApp = Record<string, unknown>;
+export declare function snapshotAppSettings(live: LiveApp): Record<string, unknown>;
+export declare const bareName: (name: string) => string;
+export declare const liveNames: (live: LiveApp) => string[];
+/**
+ * What an adopted entry changes on its live app: only a setting it declares
+ * that differs from live. The entry cannot tell a declared `branch`,
+ * `buildPack` or `autoDeploy` from its default, so those stay as they are; a
+ * `null` folder or port and an empty name list declare nothing. Never
+ * `custom_network_aliases`.
+ */
+export declare function adoptedAppPatch(entry: HostingEntry, names: readonly string[], live: LiveApp): Record<string, unknown>;
+/** One line per setting the patch changes, old value beside new. */
+export declare function adoptedPatchDetails(patch: Record<string, unknown>, live: LiveApp): string[];
+/**
+ * The PATCH body that puts an app's snapshot settings back. A field is sent
+ * only when the entry's declaration would have changed it from the snapshot
+ * (`adoptedAppPatch`), so a setting foundry never touched, or a person edited
+ * later, stays. With no entry, a field is sent when `live` differs from the
+ * snapshot. Coolify reads `fqdn` but takes `domains`. A field the snapshot had
+ * as null is cleared the way the plain app path clears it: a folder back to
+ * `/`, domains to the empty list. A port is never cleared, as on that path.
+ */
+export declare function restoreAppPatch(entry: HostingEntry | undefined, names: readonly string[], settings: Record<string, unknown>, live: LiveApp): Record<string, unknown>;
+/** One route of a tunnel's ingress list. Other fields (`originRequest`, `path`) ride along untouched. */
+export interface IngressRoute {
+    hostname?: string;
+    service: string;
+    [field: string]: unknown;
+}
+/** A hostname as compared: lower case, no trailing dot (DNS names ignore both). */
+export declare const normalizeHostname: (hostname: string) => string;
+/**
+ * What the merge leaves alone: every live route that is not for a declared
+ * name and not foundry's own route for a name it dropped. Whatever its shape:
+ * a hostname, only a `path`, or neither.
+ */
+export declare function foreignRoutes(live: readonly IngressRoute[], declared: readonly string[], service: string, written: ReadonlySet<string>): IngressRoute[];
+/** The declared names whose live routes the merge replaces: there are some, and they are not already foundry's one route. */
+export declare function replacedNames(live: readonly IngressRoute[], declared: readonly string[], service: string): string[];
+/** The names foundry removes from `live`: written, no longer declared, still its own route. */
+export declare const removedNames: (live: readonly IngressRoute[], declared: readonly string[], service: string, written: ReadonlySet<string>) => string[];
+/**
+ * The ingress list an adopted tunnel gets (#312): the declared exact names,
+ * then every foreign live route in its live order and unchanged, with the
+ * snapshot's routes for a name foundry dropped put back among them, then the
+ * declared wildcards, then the live catch-all as it is. Only a live list that
+ * does not end in a catch-all gets `http_status:404`.
+ */
+export declare function mergeIngress(live: readonly IngressRoute[], declared: readonly string[], service: string, written: ReadonlySet<string>, snapshot: readonly IngressRoute[]): IngressRoute[];
+/**
+ * The ingress list restore writes (#312): the live list without foundry's own
+ * route for a name it wrote (`written` accumulates for the life of the
+ * snapshot), plus the snapshot's routes for that name. A name with no live
+ * route that is exactly foundry's is left alone, as is a route a person added
+ * or edited, and the live catch-all. The `http_status:404` foundry appended is
+ * removed only while it is still last and the snapshot had no catch-all; an
+ * empty snapshot keeps the live catch-all, or gets one.
+ */
+export declare function restoreIngress(live: readonly IngressRoute[], snapshot: readonly IngressRoute[], service: string, written: ReadonlySet<string>): IngressRoute[];
+export {};