@wtfalch/foundry 0.16.16 → 0.17.1

package/dist/org.d.ts

@@ -129,6 +129,27 @@ export interface ChatConfig {
 export interface CallsConfig {
     enabled: boolean;
     usesDomain: boolean;
+    /**
+     * #259: holds this org's calls Matrix stack on an older Synapse/MAS
+     * release during an ordered rollout, instead of whatever
+     * `versions.json` currently pins. `null`/absent follows the pinned
+     * release, same as today.
+     *
+     * Declared and validated here; not yet read anywhere a tag is actually
+     * applied. `executor.ts`'s `coolifyCalls` only ever sets Synapse's/MAS's
+     * image tag at creation (its own comment: "#251: only on create --
+     * nothing here patches `docker_registry_image_tag` on an app
+     * `findOrCreateCallsApp` found already running") -- there is no patch-
+     * and-redeploy path for an existing org's stack yet, pinned or not. A
+     * rollout mechanism needs that path before this field can hold anything
+     * back; building it is outside this change (#259's own "Human steps"
+     * raises a related open question about Coolify's auto-deploy that bears
+     * on the same path).
+     */
+    versionPin?: {
+        synapse?: string;
+        mas?: string;
+    } | null;
 }
 /**
  * The issuer's per-service opt-in into the org's `domain` fact.
@@ -157,6 +178,17 @@ export interface IssuerConfig {
 export interface SiteConfig {
     enabled: boolean;
     usesDomain: boolean;
+    /**
+     * The org's own skin repo for `plan/executor.ts`'s `cmsSite` site app
+     * (#245) -- `null` (the default) builds the shared `@wtfalch/cms` repo's
+     * `apps/site`, same sample skin as before this field existed. Only the
+     * repo the site app builds from; the cms admin app behind it always
+     * builds from the shared repo. Where the skin finally lives (an
+     * org-owned repo vs. a cms theme document served at runtime) is still
+     * undecided in https://github.com/wtfalch/cms/issues/55 -- this field and
+     * its default are the only part built until that closes.
+     */
+    repo?: string | null;
 }
 /**
  * A ZITADEL OIDC application kind foundry can provision inside an org's
@@ -299,6 +331,62 @@ export interface HostingEntry {
     env: Record<string, EnvValue>;
     /** What the entry signs in through. Absent means it uses nothing. */
     uses?: HostingEntryUses;
+    /**
+     * F8: a Cloudflare Worker foundry deploys from this entry's own repo,
+     * beside the app, on the org's own zone. Only our own repos may use this
+     * (#318: outside customers need Workers for Platforms, not built yet), so
+     * `validateEntryEdge` refuses it unless `repo` is set (every non-null
+     * `repo` already matches `wtfalch/...`, {@link REPO}) and the route's zone
+     * is the org's own domain.
+     */
+    edge?: EdgeConfig;
+}
+/**
+ * One Cloudflare rate limiting binding on a Worker (#318) -- Cloudflare's own
+ * "simple" shape: a fixed number of requests per period, where `period` is
+ * the only two values Cloudflare's rate limiting binding accepts.
+ */
+export interface EdgeRateLimitBinding {
+    name: string;
+    namespaceId: string;
+    limit: number;
+    period: 10 | 60;
+}
+/** {@link HostingEntry.edge}'s bindings, one list per binding kind -- only rate limits today. */
+export interface EdgeBindings {
+    rateLimits: EdgeRateLimitBinding[];
+}
+/**
+ * A plain Worker deployed beside a hosting entry (#318), named by one route
+ * on the org's own zone. `artifactUrl`/`artifactSha256` name a *built*
+ * module -- the entry's own repo builds and publishes it (a release asset,
+ * typically), foundry only fetches and verifies it against the declared
+ * digest before uploading (estate DECISIONS.md, 2026-10-04, "offline.tf
+ * Worker setup": "The app's automated build process builds the bundle
+ * outside Foundry; Foundry consumes and deploys the artifact through the
+ * provider boundary... No manual build step and no source checkout/bundling
+ * in Foundry"). `validateEntryEdge` refuses anything that is not an
+ * `https://` URL -- a bare path or relative file name is exactly the shape
+ * this decision rules out.
+ */
+export interface EdgeConfig {
+    /** Where foundry fetches the built module from, behind `WorkersPort` -- never checked out or bundled here. */
+    artifactUrl: string;
+    /** The built module's sha256, lowercase hex. Verified against the fetched bytes before upload, and the sole signal `planEdgeWorkers` diffs on: an org that rebuilds under an unchanged URL redeploys only when this changes. */
+    artifactSha256: string;
+    /**
+     * One route per entry today. A wildcard route (`*.<domain>/*`) matches
+     * every subdomain, which also captures every other hostname the org
+     * serves under that domain -- its own app included, e.g. `app.<domain>`
+     * -- since Cloudflare routes the most specific match but a Worker route
+     * has no path-based exclusion of its own; declare it carefully so it
+     * does not shadow the app. The apex itself (`<domain>`, no subdomain
+     * label) is never matched by a wildcard route -- not even partially --
+     * so an org that wants the apex reachable through a Worker declares a
+     * separate entry with that exact route; there is no exclusion list.
+     */
+    route: string;
+    bindings?: EdgeBindings;
 }
 /**
  * Sign-in for one entry: one ZITADEL client and one broker entry, signing in
@@ -352,7 +440,17 @@ export interface HostingEntryUses {
     auth?: EntryAuth;
     ai?: EntryAi;
     files?: EntryFiles;
+    /**
+     * F7 (#317): the entry gets its own names key, minted directly below the
+     * org with the names service, and `NAMES_URL`/`NAMES_API_KEY` in its env.
+     * Serves only the org's own domain (names claims `<label>.<org's domain>`),
+     * so `validateEntryNames` refuses it without `hosting.usesDomain` and an
+     * org `domain`.
+     */
+    names?: true;
 }
+/** The env names `uses.names` writes; `env` may not name them (#317). */
+export declare const NAMES_ENTRY_ENV_NAMES: readonly ["NAMES_URL", "NAMES_API_KEY"];
 /**
  * A plain string is pushed as it is, so `validateHosting` refuses one that
  * looks like a secret. `{ from }` names a value the plan already mints.
@@ -428,8 +526,19 @@ export declare function validateDomain(domain: string): string | null;
  * - `site.enabled` refuses an `issuerApps` entry named `cms`: the fixed cms
  *   client (#139, `plan/diff.ts`'s `planCmsClient`) already owns the
  *   `zitadel:app:cms` key, and the two would overwrite each other.
+ * - `site.repo`, if set, must be a repo under `wtfalch` (#245), the same
+ *   `REPO` rule {@link validateHostingEntry} already holds `HostingEntry.repo`
+ *   to.
  */
 export declare function validateSite(org: DeclaredOrg): string | null;
+/**
+ * #259: `calls.versionPin` holds this org's calls Matrix stack on an older
+ * release during an ordered rollout. A pin is a tag, held to the same
+ * "no floating tag" rule the pinned releases in `versions.json` already
+ * follow ({@link floatingTagBlocked}) -- a pin that floats would defeat the
+ * reason to pin at all.
+ */
+export declare function validateCalls(org: DeclaredOrg): string | null;
 /**
  * Per-org SSO. Decided to exist in #14 ("Also in scope") and its resolved
  * research #3 ("per-org SSO code exists unused"); nothing about its
@@ -483,9 +592,14 @@ export interface StorageConfig {
  * this is the declared value `apply` pushes onto it.
  *
  * A bigint-safe decimal string of a non-negative integer, never converted to
- * a number. `null` means uncapped. Spend itself (usage, money spent) is
- * never declared (#27 "Done when"): it is a runtime fact read live from AI's
- * usage ledger, shown beside this limit, never stored here.
+ * a number. `null` means no limit is declared -- not uncapped: `apply`
+ * (`diff.ts`'s `effectiveAiLimitMicros`) substitutes a default spend cap,
+ * `DEFAULT_AI_LIMIT_MICROS`, in that case (#484; Archon creates every
+ * company this way, and AI's own budget API has no uncapped
+ * representation). A declared numeric limit always wins over the default.
+ * Spend itself (usage, money spent) is never declared (#27 "Done when"): it
+ * is a runtime fact read live from AI's usage ledger, shown beside this
+ * limit, never stored here.
  */
 export interface AiConfig {
     limitMicros: string | null;
@@ -613,9 +727,20 @@ export declare function ownerMailboxRecorded(box: OwnerMailbox, recordedIds: Rea
  * two rules `validateHosting` already applies to `issuerApps`' names, for
  * the same reason: a duplicate or blank entry can never mean anything
  * different from leaving it out.
+ *
+ * A domain plus `mail.mode === 'received'` is tier 2 (own domain, MX stays
+ * at Google or Microsoft), which William dropped on 2026-10-04 (#422):
+ * only tier 1 (no domain) and tier 3 (own domain, `hosted`) are offered.
+ * Refused unless `opts.allowExistingTier2` says this exact combination was
+ * already the stored state before this write -- `store/postgres.ts`'s
+ * `update` passes that for an org already grandfathered into tier 2, so a
+ * patch that does not touch `domain` or `mail.mode` still goes through.
+ * `create` never passes it: a brand new org cannot already be grandfathered.
  */
 export declare function validateMail(org: Pick<DeclaredOrg, 'mail' | 'domain'> & {
     owners?: readonly OwnerIdentity[];
+}, opts?: {
+    allowExistingTier2?: boolean;
 }): string | null;
 /**
  * The form an app foundry does not own takes. Decided in #7's `#15`

package/dist/org.js

@@ -1,3 +1,4 @@
+import { floatingTagBlocked } from './bootstrap/versions.js';
 /** {@link MailConfig.mailApps} when the org declares none of its own (#34, decided 2026-09-30). */
 export const DEFAULT_MAIL_APPS = ['agora', 'webmail'];
 /** {@link MailConfig.noReplyLocalPart}'s own default, restated wherever it is read rather than imported (this file's `LOG_DIR`-style convention, named in `plan/executor.ts`'s own doc comments). */
@@ -35,6 +36,8 @@ export const FILES_ENTRY_ENV_NAMES = [
     'FILES_API_KEY',
 ];
 export const filesCollectionEnvName = (name) => `FILES_COLLECTION_${name}_ID`;
+/** The env names `uses.names` writes; `env` may not name them (#317). */
+export const NAMES_ENTRY_ENV_NAMES = ['NAMES_URL', 'NAMES_API_KEY'];
 /** The org's `app` entry: today's one app. */
 export function appEntry(hosting) {
     return hosting.entries.find((entry) => entry.key === APP_ENTRY_KEY);
@@ -129,10 +132,30 @@ export function validateHosting(hosting, names) {
         const invalidFiles = validateEntryFiles(entry, hosting, names?.domain);
         if (invalidFiles)
             return invalidFiles;
+        const invalidEdge = validateEntryEdge(entry, hosting, names?.domain, names?.locked);
+        if (invalidEdge)
+            return invalidEdge;
+        const invalidNamesUse = validateEntryNames(entry, hosting, names?.domain);
+        if (invalidNamesUse)
+            return invalidNamesUse;
     }
     if (hosting.entries.filter((entry) => entry.uses?.ai?.webhookPath !== undefined).length > 1) {
         return 'at most one hosting entry may set uses.ai webhookPath: ai keeps one webhook per organisation';
     }
+    // #318 re-review: two entries declaring the same edge route both throw at
+    // apply (`cloudflareWorker` refuses a route already bound to a Worker
+    // that is not its own), one of which stops Agora and everything planned
+    // after it provisioning at all -- refused here instead, before an apply
+    // ever reaches it.
+    const seenEdgeRoutes = new Set();
+    for (const entry of hosting.entries) {
+        if (!entry.edge)
+            continue;
+        if (seenEdgeRoutes.has(entry.edge.route)) {
+            return `hosting.entries '${entry.key}' edge route '${entry.edge.route}' is already declared by another entry`;
+        }
+        seenEdgeRoutes.add(entry.edge.route);
+    }
     const invalidNames = validateEntryHostnames(hosting, names);
     if (invalidNames)
         return invalidNames;
@@ -414,6 +437,127 @@ function validateEntryFiles(entry, hosting, domain) {
         return `${at} writes ${named}; remove it from env`;
     return null;
 }
+/** A route pattern's zone apex: the host part before the first `/`, with one leading `*.` label stripped. */
+function edgeRouteZone(route) {
+    const slash = route.indexOf('/');
+    if (slash < 1)
+        return null;
+    const host = route.slice(0, slash);
+    return host.startsWith('*.') ? host.slice(2) : host;
+}
+const EDGE_ROUTE = /^(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+\/.*$/;
+const EDGE_SHA256 = /^[0-9a-f]{64}$/;
+/**
+ * Restated, not shared, from `plan/edge-worker.ts`'s `EDGE_WORKER_ORG_HASH_LENGTH`/
+ * `EDGE_WORKER_NAME_MAX_LENGTH` -- importing them here would import that
+ * module's own `DeclaredOrg`/`HostingEntry` imports right back into this
+ * one. `edgeWorkerName`'s shape is `${8-hex-char hash}-${entry.key}-edge`;
+ * the hash and the `-edge` suffix are fixed length, so the entry key's own
+ * budget against Cloudflare's 63-character Worker name limit is fixed too.
+ */
+const EDGE_WORKER_NAME_FIXED_LENGTH = 8 + 1 + '-edge'.length;
+const EDGE_WORKER_NAME_MAX_LENGTH = 63;
+/**
+ * `edge`: the entry's own repo (never the shared standard app -- entries
+ * with `repo: null` have no Worker source of their own), an `https://`
+ * artifact URL with a lowercase-hex sha256 (never a bare path or relative
+ * file -- estate DECISIONS.md, 2026-10-04, rules out any checkout or
+ * bundling inside foundry), a route whose zone is the org's own domain
+ * (#318: our own projects only, never a customer's zone), and a rate limit
+ * binding's `period` restricted to the two values Cloudflare's simple rate
+ * limiting binding accepts.
+ */
+function validateEntryEdge(entry, hosting, domain, locked) {
+    const edge = entry.edge;
+    if (!edge)
+        return null;
+    const at = `hosting.entries '${entry.key}' edge`;
+    if (!hosting.enabled)
+        return `${at} requires hosting.enabled`;
+    if (entry.repo === null) {
+        return `${at} needs its own repo (repo: null is the shared standard app, not a Worker source)`;
+    }
+    if (entry.key.length > EDGE_WORKER_NAME_MAX_LENGTH - EDGE_WORKER_NAME_FIXED_LENGTH) {
+        return `${at} entry key is too long: the deployed Worker's name (an 8-character org hash, the key, and "-edge") must fit Cloudflare's ${EDGE_WORKER_NAME_MAX_LENGTH}-character limit`;
+    }
+    let artifactUrl;
+    try {
+        artifactUrl = new URL(edge.artifactUrl);
+    }
+    catch {
+        return `${at} artifactUrl must be an absolute URL, not a bare path or relative file`;
+    }
+    if (artifactUrl.protocol !== 'https:') {
+        return `${at} artifactUrl must be an https:// URL`;
+    }
+    if (artifactUrl.username || artifactUrl.password) {
+        return `${at} artifactUrl must not carry userinfo (a signed or credentialed URL ends up stored verbatim in recorded scope ids)`;
+    }
+    if (artifactUrl.search) {
+        return `${at} artifactUrl must not carry a query string (a signed or credentialed URL ends up stored verbatim in recorded scope ids)`;
+    }
+    // `URL.hash` is '' for a bare trailing `#`, so the raw string is checked.
+    if (edge.artifactUrl.includes('#')) {
+        return `${at} artifactUrl must not carry a fragment (refused for the same reason as a query string)`;
+    }
+    if (!EDGE_SHA256.test(edge.artifactSha256)) {
+        return `${at} artifactSha256 must be 64 lowercase hex characters`;
+    }
+    if (!EDGE_ROUTE.test(edge.route)) {
+        return `${at} route must be a hostname (an optional leading '*.' label, then at least two more labels) and a path, joined by '/'`;
+    }
+    const zone = edgeRouteZone(edge.route);
+    if (!domain || zone !== domain) {
+        return `${at} route '${edge.route}' must be on the org's own domain${domain ? ` (${domain})` : ''}: edge is only for our own projects`;
+    }
+    // #318 re-review: a Worker route has no path-based exclusion of its own,
+    // so a wildcard (`*.<domain>/*`) captures every hostname foundry already
+    // owns under the domain -- Agora, Boule, the login host and the rest of
+    // `locked-hostnames.ts`'s set -- not only the org's other entries. (A
+    // non-wildcard route can only ever be the bare apex here -- the check
+    // just above requires `edgeRouteZone(edge.route) === domain`, and that
+    // function returns a non-wildcard route's host unchanged -- and the apex
+    // alone is never itself a locked name, so there is no direct-match case
+    // to refuse alongside this one.)
+    if (locked && locked.size > 0 && edge.route.startsWith('*.')) {
+        return `${at} route '${edge.route}' is a wildcard: it would also capture ${[...locked].sort().join(', ')}, every hostname foundry already owns under this domain`;
+    }
+    for (const limit of edge.bindings?.rateLimits ?? []) {
+        if (!limit.name.trim())
+            return `${at} bindings.rateLimits needs a non-empty name`;
+        if (!limit.namespaceId.trim())
+            return `${at} bindings.rateLimits needs a non-empty namespaceId`;
+        if (!(Number.isInteger(limit.limit) && limit.limit > 0)) {
+            return `${at} bindings.rateLimits limit must be a positive whole number`;
+        }
+        if (limit.period !== 10 && limit.period !== 60) {
+            return `${at} bindings.rateLimits period must be 10 or 60 (Cloudflare allows no other value)`;
+        }
+    }
+    return null;
+}
+/**
+ * `uses.names`: serves only the org's own domain (names claims
+ * `<label>.<domain>`), so it needs `hosting.usesDomain` and a `domain`, and
+ * no `env` entry that names a value `uses.names` writes.
+ */
+function validateEntryNames(entry, hosting, domain) {
+    const names = entry.uses?.names;
+    if (names === undefined)
+        return null;
+    const at = `hosting.entries '${entry.key}' uses.names`;
+    if (names !== true)
+        return `${at} must be true`;
+    if (!hosting.enabled)
+        return `${at} requires hosting.enabled`;
+    if (!hosting.usesDomain || !domain) {
+        return `${at} needs hosting.usesDomain and an org domain: names serves only the org's own domain`;
+    }
+    const named = Object.keys(entry.env ?? {}).find((name) => NAMES_ENTRY_ENV_NAMES.includes(name));
+    if (named)
+        return `${at} writes ${named}; remove it from env`;
+    return null;
+}
 function urlHasPassword(value) {
     try {
         return new URL(value).password !== '';
@@ -483,6 +627,9 @@ export function validateDomain(domain) {
  * - `site.enabled` refuses an `issuerApps` entry named `cms`: the fixed cms
  *   client (#139, `plan/diff.ts`'s `planCmsClient`) already owns the
  *   `zitadel:app:cms` key, and the two would overwrite each other.
+ * - `site.repo`, if set, must be a repo under `wtfalch` (#245), the same
+ *   `REPO` rule {@link validateHostingEntry} already holds `HostingEntry.repo`
+ *   to.
  */
 export function validateSite(org) {
     if (org.site.enabled && !org.domain) {
@@ -497,6 +644,32 @@ export function validateSite(org) {
     if (org.site.enabled && org.hosting.issuerApps.some((app) => app.name === 'cms')) {
         return "site.enabled reserves the issuerApps name 'cms'";
     }
+    if (org.site.repo != null && !REPO.test(org.site.repo)) {
+        return 'site.repo must be a repo under wtfalch, or null';
+    }
+    return null;
+}
+/**
+ * #259: `calls.versionPin` holds this org's calls Matrix stack on an older
+ * release during an ordered rollout. A pin is a tag, held to the same
+ * "no floating tag" rule the pinned releases in `versions.json` already
+ * follow ({@link floatingTagBlocked}) -- a pin that floats would defeat the
+ * reason to pin at all.
+ */
+export function validateCalls(org) {
+    const pin = org.calls.versionPin;
+    if (!pin)
+        return null;
+    if (pin.synapse !== undefined) {
+        const blocked = floatingTagBlocked('Synapse', pin.synapse, 'v1.161.0');
+        if (blocked)
+            return `calls.versionPin ${blocked}`;
+    }
+    if (pin.mas !== undefined) {
+        const blocked = floatingTagBlocked('matrix-authentication-service', pin.mas, '1.24.0');
+        if (blocked)
+            return `calls.versionPin ${blocked}`;
+    }
     return null;
 }
 const ORG_NUMBER_PATTERN = /^\d{9}$/;
@@ -655,9 +828,21 @@ function validateOwnerMailboxes(org) {
  * two rules `validateHosting` already applies to `issuerApps`' names, for
  * the same reason: a duplicate or blank entry can never mean anything
  * different from leaving it out.
+ *
+ * A domain plus `mail.mode === 'received'` is tier 2 (own domain, MX stays
+ * at Google or Microsoft), which William dropped on 2026-10-04 (#422):
+ * only tier 1 (no domain) and tier 3 (own domain, `hosted`) are offered.
+ * Refused unless `opts.allowExistingTier2` says this exact combination was
+ * already the stored state before this write -- `store/postgres.ts`'s
+ * `update` passes that for an org already grandfathered into tier 2, so a
+ * patch that does not touch `domain` or `mail.mode` still goes through.
+ * `create` never passes it: a brand new org cannot already be grandfathered.
  */
-export function validateMail(org) {
+export function validateMail(org, opts) {
     const { mail } = org;
+    if (org.domain && mail.mode === 'received' && !opts?.allowExistingTier2) {
+        return `mail.mode 'received' (tier 2, own domain with mail elsewhere) is not offered; use 'hosted' or leave the domain off`;
+    }
     const address = mail.ownerMailboxAddress ?? null;
     if (address !== null) {
         if (!OWNER_EMAIL_PATTERN.test(address)) {

package/dist/plan/adopt.d.ts

@@ -0,0 +1,76 @@
+import type { DeclaredOrg } from '../org.js';
+import type { Plan } from '../plan.js';
+import type { LiveResource } from './live.js';
+/**
+ * Adopt a live app and its database in place (archon#271). The caller names
+ * what already runs in Coolify; foundry reads it, checks it is what it would
+ * have created for the entry, and records the ids so the next plan finds them
+ * instead of planning a create. Nothing here calls Coolify to change anything.
+ *
+ * No redeploy happens at adopt. The next normal plan may still propose
+ * updates to the adopted app (log volume, env push, hostnames, labels) because
+ * foundry's applied markers are absent; applying those redeploys the app. The
+ * host must show that plan to the operator before it is applied.
+ */
+export interface AdoptInput {
+    /** The declared hosting entry (`HostingEntry.key`) that takes the app over. It must have `database: true`. */
+    entryKey: string;
+    /** The Coolify application uuid. */
+    applicationUuid: string;
+    /** The Coolify Postgres database uuid. */
+    databaseUuid: string;
+    /** The Coolify project both live in. Optional when the org already records one. */
+    projectUuid?: string;
+}
+/** What the adopted resources looked like when adopted: the reader's output, never a secret. */
+export interface AdoptSnapshot {
+    adoptedAt: string;
+    projectUuid: string;
+    /** True when adopt recorded `coolify_project` itself, so release takes it out again. */
+    projectRecorded: boolean;
+    application: {
+        uuid: string;
+        config: Record<string, unknown>;
+    };
+    database: {
+        uuid: string;
+        config: Record<string, unknown>;
+    };
+}
+/** The flat scope key (no `:`) holding an entry's {@link AdoptSnapshot} as JSON. Its presence means "adopted". */
+export declare function adoptedScopeKey(entryKey: string): string;
+/** `null` when absent, or when it is not a snapshot (callers that delete must treat the latter as an error: see {@link adoptedKeysUnreadable}). */
+export declare function parseAdoptSnapshot(raw: string | undefined): AdoptSnapshot | null;
+/** The `adopted.<entry>` keys of `serviceIds` whose value is not a readable snapshot. */
+export declare function adoptedKeysUnreadable(serviceIds: Readonly<Record<string, string>>): string[];
+export declare function snapshotConfig(config: Record<string, unknown>): Record<string, unknown>;
+export declare class AdoptRefusedError extends Error {
+    readonly reasons: string[];
+    constructor(reasons: string[]);
+}
+export interface AdoptPlan {
+    plan: Plan;
+    /** Empty when the live resources match the entry. A non-empty list refuses `adopt` and the plan has no steps. */
+    mismatches: string[];
+    /** What `adopt` would record; absent with mismatches. */
+    snapshot?: AdoptSnapshot;
+}
+/** A live app or database in the project that this org has not recorded, for Archon's "Live, not theirs". */
+export interface AdoptCandidate {
+    kind: 'application' | 'database';
+    uuid: string;
+    name: string;
+    status?: string;
+    /** True when its name is the one foundry would have given it for the entry. */
+    matchesName: boolean;
+}
+/** Live applications and databases in the project that no recorded id of this org names. */
+export declare function adoptCandidates(org: DeclaredOrg, entryKey: string, recordedIds: Readonly<Record<string, string>>, live: readonly LiveResource[]): AdoptCandidate[];
+/**
+ * Checks `input` against the declaration, the recorded ids and the live
+ * resources of the project, and builds the plan steps. `live` is the reader's
+ * output for the project (`null` when the reader cannot read a project).
+ */
+export declare function planAdoptFrom(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, input: AdoptInput, live: readonly LiveResource[] | null, now: Date, 
+/** What another org already records among the three uuids, one reason each (`FoundryPlanApply.computeAdopt`). */
+claimedElsewhere?: readonly string[]): AdoptPlan;