@timekast/factory 1.28.1 → 2.0.1

package/dist/lib/vault-adopt.js

@@ -0,0 +1,1495 @@
+/**
+ * ADOPT-001 — the pieces of `factory vault adopt` that decide WHAT happens: the drift census of
+ * the files the wrapper runs, the inventory by name and non-reversible hash, the state of each
+ * key, the layout the apply writes (ADR-005), the confirmations it needs, the repo ↔ vault link
+ * it records and the retirement of `.env.local`. The command (`commands/vault.ts`) orchestrates
+ * them against the real services. Contract: `fx-secrets-vault §8`.
+ *
+ * 🔴 NO-ECHO. Values live in {@link InventoryValues} and in {@link PlannedWrite} — in memory, for
+ * the time of one run. Nothing that goes into the plan (`buildPlanEntries`) carries a value: only key
+ * NAMES, locations, and a display hash that cannot be reversed by dictionary (see
+ * {@link createDisplayHasher}). Errors name keys, never values.
+ *
+ * FIRST SYNC ON A LIVE DEPLOY (the user's answer, 2026-09-24): "importar primero; hacia GitHub,
+ * listar los nombres y detenerse antes de crear el sync si falta alguno en develop:/ci". So the
+ * layout below imports into the vault everything a deploy holds (a sync created afterwards finds
+ * the vault as a superset of its destination and deletes nothing), and GitHub — whose secrets are
+ * write-only — is compared by NAMES against `develop:/ci`.
+ */
+import { createHmac, randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { CLIError } from './cli-error.js';
+import { isFactoryCheckout } from './initial-migration.js';
+import { VAULT_WRAPPED_SCRIPTS, WITH_VAULT_SCRIPT_FILE } from './constants.js';
+import { LOCAL_ONLY_KEYS } from './env-file.js';
+import { normalizeThenHash } from './lockfile.js';
+import { getNeonProjectOrg, listNeonProjects } from './neon-api.js';
+import { detectCoreProfile, VAULT_POLICY_PATH } from './provision-preflight.js';
+import { adoptState, buildVaultState, hasProvisionState, isProvisionStateUnreadable, PROVISION_DIR, PROVISION_STATE_FILE, provisionStatePath, readDestroyTarget, readProvisionTarget, readRailwayBlock, readVaultDeclined, readVaultLink, UNREADABLE_STATE_REMEDY, VAULT_DECLINED_KEY, } from './provision-state.js';
+import { createRailResolver, RailError } from './rail.js';
+import { connectedProjects, createRailwayClient, railwayFetchTransport, RailwaySeamMissingError, } from './railway-api.js';
+import { createVaultClient, formatLocation, VAULT_CI_PATH, VAULT_ENV_DEVELOP, VAULT_ENV_LOCAL, VAULT_ENV_MAIN, VAULT_ROOT_PATH, VAULT_TEST_ISOLATION_KEY, VaultSeamMissingError, } from './vault-api.js';
+import { listEnvVarsWithValues, locateVercelProject } from './vercel-env.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** The developer machine's env file — the source of `local`, never of `main`/`develop`. */
+export const ENV_LOCAL_FILE = '.env.local';
+/** What `.env.local` is renamed to at the end of a successful `--apply` (`fx-secrets-vault §8`). */
+export const ENV_LOCAL_BACKUP_FILE = '.env.local.pre-vault.bak';
+/**
+ * Key of `.timekast/provision.json` that records a repo which DECLINED the vault. Lives in
+ * `provision-state.ts` with its reader (ADOPT-004); re-exported here, where ADOPT-001 put it.
+ */
+export { VAULT_DECLINED_KEY } from './provision-state.js';
+/**
+ * 🔴 THE list of the keys that are never a project's (`fx-secrets-vault §5`): the rail's tokens and
+ * coordinates. Found in `.env.local` OR in a deploy they are NOT imported — the vault never holds a
+ * rail token (`fx-secrets-vault §2`) — whatever their value: an old or rotated copy is still not
+ * the project's. The sync created afterwards removes them from a deploy. Confirmed by whoever runs
+ * the adoption. `NEON_API_KEY` and `RESEND_API_KEY` are NOT here: each can be the project's own
+ * (the Neon key is imported only when proven project-scoped, the Resend team key is replaced).
+ * `SHORTIO_API_KEY` in Factory mode goes to `develop:/ci` with the RAIL's value (never a file's).
+ */
+export const RETIRED_RAIL_KEYS = [
+    'VERCEL_TOKEN',
+    'VERCEL_TEAM_ID',
+    'CLOUDFLARE_API_TOKEN',
+    'CLOUDFLARE_R2_TOKEN',
+    'RAILWAY_TOKEN',
+    'SHORTIO_API_KEY',
+    'GAMMA_API_KEY',
+    'BACKLOG_ADMIN_TOKEN',
+    'PROPOSAL_ASSETS_R2_TOKEN',
+    'NEON_ORG',
+];
+/** Rail families by prefix (`CLOUDFLARE_*`, `GAMMA_*`) — same list, for the names §5 groups. */
+const RAIL_KEY_PREFIXES = ['CLOUDFLARE_', 'GAMMA_'];
+/** Keys the kit retired and nothing reads anymore: never imported, named "retirada". */
+export const RETIRED_UNREAD_KEYS = ['NEON_ORGANIZATION_ID'];
+/** Whether `key` is a rail key ({@link RETIRED_RAIL_KEYS}, or one of its prefixed families). */
+export function isRailKey(key) {
+    return RETIRED_RAIL_KEYS.includes(key) || RAIL_KEY_PREFIXES.some((p) => key.startsWith(p));
+}
+/** The URL shortener key — a rail token, except in Factory mode (its CI needs a copy). */
+export const SHORTIO_KEY = 'SHORTIO_API_KEY';
+/** The GitHub repo of the kit's origin — the second signal of Factory mode. */
+export const FACTORY_REPO = 'TimeKast/TimeKast-Factory';
+/** The Factory's own slug (`project-config.md §1`) — its vault project is named like this. */
+export const FACTORY_SLUG = 'timekast-factory';
+/**
+ * Whether the RESOLVED identity is the Factory's: slug `timekast-factory` AND repo
+ * `TimeKast/TimeKast-Factory`. Factory mode (two signals) is necessary but not enough to copy the
+ * rail's `SHORTIO_API_KEY`: a clone or a fork whose slug or repo resolves to anything else must not
+ * receive a rail token (`fx-secrets-vault §2`).
+ */
+export function isFactoryIdentity(slug, repo) {
+    return (slug.toLowerCase() === FACTORY_SLUG &&
+        repo !== null &&
+        repo.toLowerCase() === FACTORY_REPO.toLowerCase());
+}
+/** The Resend key: when a source holds the rail's TEAM key, the project's own replaces it. */
+export const RESEND_KEY = 'RESEND_API_KEY';
+/** The local-only key of `.env.local` that becomes `main:/ci`'s `DATABASE_URL` (Decision 3). */
+export const DATABASE_URL_MAIN_KEY = 'DATABASE_URL_MAIN';
+const DATABASE_URL_KEY = 'DATABASE_URL';
+/** The keys CI reads from `develop:/ci` that come from `.env.local` (they are local-only). */
+const CI_KEYS_FROM_LOCAL = ['NEON_API_KEY', 'NEON_PROJECT_ID'];
+/** The project's Neon key — imported only when proven project-scoped. */
+export const NEON_API_KEY = 'NEON_API_KEY';
+/** Length (hex chars) of the display hash. */
+export const DISPLAY_HASH_LENGTH = 12;
+const MAIN_ROOT = { env: VAULT_ENV_MAIN, path: VAULT_ROOT_PATH };
+const MAIN_CI = { env: VAULT_ENV_MAIN, path: VAULT_CI_PATH };
+const DEVELOP_ROOT = { env: VAULT_ENV_DEVELOP, path: VAULT_ROOT_PATH };
+const DEVELOP_CI = { env: VAULT_ENV_DEVELOP, path: VAULT_CI_PATH };
+const LOCAL_ROOT = { env: VAULT_ENV_LOCAL, path: VAULT_ROOT_PATH };
+// ---------------------------------------------------------------------------
+// The display hash
+// ---------------------------------------------------------------------------
+/**
+ * A hasher for the plan's display: HMAC-SHA256 keyed with 32 random bytes drawn ONCE per run,
+ * truncated to {@link DISPLAY_HASH_LENGTH} hex chars.
+ *
+ * Why not a plain SHA-256: a value of low entropy (`true`, a 4-digit PIN) would be recovered by
+ * hashing a small dictionary. With a key that never leaves the process's memory — not printed,
+ * not written, not exported — the same dictionary produces nothing comparable. Per run: two
+ * hashes are comparable WITHIN one plan (that is the point: equal/different at a glance) and never
+ * across runs, so a pasted plan does not become a lookup table over time. Truncated: the display
+ * only has to tell values apart within one plan; the state (`igual`/`distinta`) is decided on the
+ * values themselves, never on this string.
+ */
+export function createDisplayHasher() {
+    const key = randomBytes(32);
+    return (value) => createHmac('sha256', key).update(value, 'utf8').digest('hex').slice(0, DISPLAY_HASH_LENGTH);
+}
+// ---------------------------------------------------------------------------
+// Precondition 2 — the drift census of what the wrapper runs
+// ---------------------------------------------------------------------------
+/** A repo path inside a script value (`scripts/tools/db-query.ts`, `src/lib/db/seed.ts`…). */
+const SCRIPT_PATH_RE = /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+\.(?:m?[jt]s|c[jt]s)$/;
+/**
+ * The files the wrapped scripts invoke — read off the SAME registry the wiring uses
+ * (`VAULT_WRAPPED_SCRIPTS`) — plus the wrapper itself and `vault.json`, which it reads. Only the
+ * ones the lockfile tracks can drift (`src/` never is), so the census filters by it.
+ */
+export function wrapperRunFiles() {
+    const files = new Set([WITH_VAULT_SCRIPT_FILE, VAULT_POLICY_PATH]);
+    for (const spec of Object.values(VAULT_WRAPPED_SCRIPTS)) {
+        for (const value of [spec.cmd, ...spec.unwrapped]) {
+            for (const token of value.split(/\s+/)) {
+                if (SCRIPT_PATH_RE.test(token))
+                    files.add(token);
+            }
+        }
+    }
+    return [...files].sort();
+}
+/**
+ * The census of `factory update --verify`, restricted to {@link wrapperRunFiles}: every one the
+ * lockfile tracks that is missing on disk or differs from the registered hash (same normalized
+ * hash `update` uses). Empty = no fork in what the wrapper wraps.
+ */
+export function wrapperDrift(rootDir, lock) {
+    const wanted = new Set(wrapperRunFiles());
+    const drifted = [];
+    for (const entry of lock.files) {
+        if (!wanted.has(entry.path))
+            continue;
+        const abs = path.join(rootDir, entry.path);
+        if (!existsSync(abs)) {
+            drifted.push(entry.path);
+            continue;
+        }
+        if (normalizeThenHash(readFileSync(abs, 'utf8')) !== entry.hash)
+            drifted.push(entry.path);
+    }
+    return drifted.sort();
+}
+/** Placeholder of a display source whose value cannot be read. */
+export const UNREADABLE_MARK = 'ilegible';
+/** Classify one key (see {@link InventoryState}). Decided on the VALUES, never on a hash. */
+export function classifyKey(name, values) {
+    const deploy = [];
+    if (values.production.has(name))
+        deploy.push(values.production.get(name) ?? null);
+    if (values.preview.has(name))
+        deploy.push(values.preview.get(name) ?? null);
+    for (const source of values.railway.values()) {
+        if (source.has(name))
+            deploy.push(source.get(name));
+    }
+    if (deploy.some((value) => value === null))
+        return 'ilegible';
+    const local = values.local.get(name);
+    if (local === undefined)
+        return 'sólo en el deploy';
+    if (deploy.length === 0)
+        return 'sólo local';
+    return deploy.every((value) => value === local) ? 'igual' : 'distinta';
+}
+/**
+ * The writes of the apply, IN ORDER (a reference is always written after its target):
+ *
+ *   · `main:/`      ← Vercel production (never `.env.local`).
+ *   · `main:/ci`    ← `DATABASE_URL_MAIN` of `.env.local`, renamed `DATABASE_URL` (no suffixes).
+ *   · `develop:/`   ← Vercel preview; a value equal to production's is a REFERENCE to `main:/`
+ *                     (one copy of each shared value, `fx-secrets-vault §7`).
+ *   · `develop:/ci` ← the project's Neon key + id from `.env.local`; `DATABASE_URL` as a reference
+ *                     to `develop:/` (what provision writes).
+ *   · `local`       ← `.env.local`: a value equal to `main:/`'s is a reference there, one equal to
+ *                     `develop:/`'s own value a reference there, the rest its own. The Neon key and
+ *                     id arrive through the import of `develop:/ci`, so they are not repeated.
+ *
+ * Railway is not part of this layout: what only Railway holds is planned by
+ * {@link planRailwayImport} (ADOPT-002), one deploy root at a time, after these writes.
+ */
+export function planAdoptionLayout(values, options) {
+    const writes = [];
+    // A deploy never feeds a local-only key into `main:/`/`develop:/` (the guard would refuse it);
+    // `.env.local` still feeds it where it belongs (`develop:/ci`, `local`).
+    const skipDeploy = (key) => options.retired.has(key) || LOCAL_ONLY_KEYS.has(key);
+    const skip = (key) => options.retired.has(key) && !LOCAL_ONLY_KEYS.has(key);
+    const isResend = (key) => options.replaceResend && key === RESEND_KEY;
+    // main:/
+    const mainValues = new Map();
+    let mintedInMain = false;
+    const mintResend = (key) => {
+        if (mintedInMain)
+            return;
+        mintedInMain = true;
+        writes.push({ kind: 'minted-resend', location: MAIN_ROOT, key, origin: key });
+    };
+    for (const [key, value] of values.production) {
+        if (skipDeploy(key) || value === null)
+            continue;
+        if (isResend(key)) {
+            mintResend(key);
+            continue;
+        }
+        mainValues.set(key, value);
+        writes.push({ kind: 'value', location: MAIN_ROOT, key, origin: key, value });
+    }
+    // main:/ci
+    const directMain = values.local.get(DATABASE_URL_MAIN_KEY);
+    if (directMain !== undefined && !skip(DATABASE_URL_MAIN_KEY)) {
+        writes.push({
+            kind: 'value',
+            location: MAIN_CI,
+            key: DATABASE_URL_KEY,
+            origin: DATABASE_URL_MAIN_KEY,
+            value: directMain,
+        });
+    }
+    // develop:/
+    const developOwn = new Map();
+    const developHas = new Set();
+    for (const [key, value] of values.preview) {
+        if (skipDeploy(key) || value === null)
+            continue;
+        developHas.add(key);
+        if (isResend(key) || mainValues.get(key) === value) {
+            // Preview holds the team key and production does not: the minted key goes to main first.
+            if (isResend(key))
+                mintResend(key);
+            writes.push({
+                kind: 'reference',
+                location: DEVELOP_ROOT,
+                key,
+                origin: key,
+                target: { ...MAIN_ROOT, key },
+            });
+            continue;
+        }
+        developOwn.set(key, value);
+        writes.push({ kind: 'value', location: DEVELOP_ROOT, key, origin: key, value });
+    }
+    // develop:/ci
+    for (const key of CI_KEYS_FROM_LOCAL) {
+        const value = values.local.get(key);
+        if (value === undefined || skip(key))
+            continue;
+        if (key === NEON_API_KEY && options.importLocalNeonKey === false)
+            continue;
+        writes.push({ kind: 'value', location: DEVELOP_CI, key, origin: key, value });
+    }
+    if (developHas.has(DATABASE_URL_KEY)) {
+        writes.push({
+            kind: 'reference',
+            location: DEVELOP_CI,
+            key: DATABASE_URL_KEY,
+            origin: DATABASE_URL_KEY,
+            target: { ...DEVELOP_ROOT, key: DATABASE_URL_KEY },
+        });
+    }
+    for (const write of options.extra ?? [])
+        writes.push(write);
+    // local
+    for (const [key, value] of values.local) {
+        if (skip(key) || key === DATABASE_URL_MAIN_KEY || CI_KEYS_FROM_LOCAL.includes(key))
+            continue;
+        if (isResend(key)) {
+            mintResend(key);
+            writes.push({
+                kind: 'reference',
+                location: LOCAL_ROOT,
+                key,
+                origin: key,
+                target: { ...MAIN_ROOT, key },
+            });
+            continue;
+        }
+        if (mainValues.get(key) === value) {
+            writes.push({
+                kind: 'reference',
+                location: LOCAL_ROOT,
+                key,
+                origin: key,
+                target: { ...MAIN_ROOT, key },
+            });
+            continue;
+        }
+        if (developOwn.get(key) === value) {
+            writes.push({
+                kind: 'reference',
+                location: LOCAL_ROOT,
+                key,
+                origin: key,
+                target: { ...DEVELOP_ROOT, key },
+            });
+            continue;
+        }
+        writes.push({ kind: 'value', location: LOCAL_ROOT, key, origin: key, value });
+    }
+    return writes;
+}
+/** How a planned write is named in the plan — never with its value. */
+export function describeWrite(write) {
+    const where = formatLocation(write.location);
+    const renamed = write.key !== write.origin ? ` como \`${write.key}\`` : '';
+    if (write.kind === 'reference') {
+        return `${where}${renamed} (referencia a ${formatLocation(write.target)})`;
+    }
+    if (write.kind === 'minted-resend')
+        return `${where} (key propia del proyecto, nueva)`;
+    return `${where}${renamed}`;
+}
+/**
+ * Build the entries of the plan (one per key, sorted), the confirmations the apply needs and the
+ * blockers that stop it. Pure: values in, NAMES and hashes out.
+ */
+export function buildPlanEntries(input) {
+    const { values, writes, retired, hash } = input;
+    const names = new Set([
+        ...values.local.keys(),
+        ...values.production.keys(),
+        ...values.preview.keys(),
+    ]);
+    for (const source of values.railway.values())
+        for (const key of source.keys())
+            names.add(key);
+    const display = (value) => value === undefined ? undefined : value === null ? UNREADABLE_MARK : hash(value);
+    const entries = [];
+    const confirmations = [];
+    const unreadable = [];
+    for (const name of [...names].sort()) {
+        const state = classifyKey(name, values);
+        const railway = {};
+        for (const [label, source] of values.railway) {
+            if (source.has(name))
+                railway[label] = hash(source.get(name));
+        }
+        const sources = {
+            ...(values.local.has(name) ? { local: display(values.local.get(name)) } : {}),
+            ...(values.production.has(name) ? { production: display(values.production.get(name)) } : {}),
+            ...(values.preview.has(name) ? { preview: display(values.preview.get(name)) } : {}),
+            ...(Object.keys(railway).length > 0 ? { railway } : {}),
+        };
+        const targets = writes.filter((w) => w.origin === name).map(describeWrite);
+        const entry = { name, state, sources, targets };
+        if (retired.has(name)) {
+            entry.action = 'retirar';
+            entry.note =
+                input.notes?.get(name) ??
+                    (RETIRED_UNREAD_KEYS.includes(name)
+                        ? 'retirada — no se importa: ningún lector del kit la usa'
+                        : isRailKey(name)
+                            ? 'token del rail: no se importa a la bóveda (con huella igual o distinta a la del rail: ' +
+                                'una copia no es del proyecto) y el sync lo quita del despliegue'
+                            : 'clave sólo-local en un despliegue: no se importa ahí y el sync la quita del despliegue');
+        }
+        else if (input.notes?.has(name)) {
+            entry.note = input.notes.get(name);
+        }
+        else if (input.replaceResend && name === RESEND_KEY) {
+            entry.action = 'reemplazar';
+            entry.note =
+                'es la key de equipo del rail: se acuña una propia del proyecto (sólo envío, limitada a su dominio)';
+        }
+        else if (name === DATABASE_URL_MAIN_KEY && targets.length > 0) {
+            entry.action = 'renombrar';
+            entry.note =
+                'sin sufijo de entorno: la cadena directa de main vive en main:/ci como DATABASE_URL';
+        }
+        else if (targets.length === 0 && state !== 'ilegible') {
+            entry.note = isRailwayProvided(name)
+                ? 'variable propia de Railway: no se importa ni la borra el sync'
+                : 'sólo en Railway, en un entorno sin igual en la bóveda: no se importa aquí; ' +
+                    '`factory vault sync railway --railway-env <nombre>` la importa y crea su sync';
+        }
+        entries.push(entry);
+        if (state === 'ilegible') {
+            unreadable.push(name);
+            continue;
+        }
+        if (entry.action === 'retirar') {
+            confirmations.push({
+                name,
+                question: `\`${name}\` (${entry.note}). ¿Confirmas que no se importa?`,
+            });
+        }
+        else if (entry.action === 'reemplazar') {
+            confirmations.push({
+                name,
+                question: `\`${name}\` ${entry.note}. ¿Confirmas el reemplazo?`,
+            });
+        }
+        else if (targets.length > 0 && (state !== 'igual' || entry.action === 'renombrar')) {
+            confirmations.push({
+                name,
+                question: `\`${name}\` (${state}) → ${targets.join(', ')}. ¿Confirmas?`,
+            });
+        }
+    }
+    return { entries, confirmations, unreadable };
+}
+/** Read the raw state object (either shape), or `null` without a file. Fail-closed when unreadable. */
+function readRawState(rootDir) {
+    if (!hasProvisionState(rootDir))
+        return null;
+    if (isProvisionStateUnreadable(rootDir)) {
+        throw new CLIError(`No puedo leer \`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`: no guardo el vínculo con la bóveda ` +
+            `encima. ${UNREADABLE_STATE_REMEDY}`);
+    }
+    return JSON.parse(readFileSync(provisionStatePath(rootDir), 'utf8'));
+}
+/** Atomic write (temp file + rename), same discipline as `writeProvisionState`. */
+function writeRawState(rootDir, state, what = 'el vínculo con la bóveda') {
+    const dir = path.join(rootDir, PROVISION_DIR);
+    mkdirSync(dir, { recursive: true });
+    const target = provisionStatePath(rootDir);
+    const tmp = path.join(dir, `.${PROVISION_STATE_FILE}.vault-adopt.tmp`);
+    try {
+        writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+        renameSync(tmp, target);
+    }
+    catch (error) {
+        rmSync(tmp, { force: true });
+        throw new CLIError(`No se pudo guardar ${what} en \`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`: ` +
+            `${error?.message ?? 'error desconocido'}.`);
+    }
+}
+/**
+ * Record the repo ↔ vault link in `.timekast/provision.json` — the shape ADOPT-004 (declined)
+ * and ADOPT-009 (the Factory, lifecycle `live`, without `provision --adopt`) reuse:
+ *
+ *   · The file EXISTS (step-by-step or adopted shape): only the `vault` block is set — every other
+ *     key stays byte-for-byte what it was — and a {@link VAULT_DECLINED_KEY} mark is removed.
+ *   · There is NO file (a derivative born before `provision`): the file is born in the ADOPTED
+ *     shape, the one `factory provision --adopt` writes (`adoptState`, `lifecycle: 'live'`), with
+ *     what the adoption knows (slug, Vercel project, repo) and `unknown` for the rest, plus the
+ *     `vault` block. Every reader already accepts that shape (`readDestroyTarget`,
+ *     `readVaultLink`, the wrapper), `provision --adopt --force` completes the `unknown` ids later
+ *     and CARRIES the `vault` block, and `lifecycle: 'live'` keeps `--destroy` refusing. A
+ *     step-shaped file with only a `vault` block was the alternative, and `readProvisionState`
+ *     would read it as corrupt.
+ */
+export function writeAdoptionLink(rootDir, input) {
+    let raw = readRawState(rootDir);
+    if (raw === null) {
+        adoptState(rootDir, {
+            slug: input.slug,
+            ...(input.vercelProjectId ? { vercelProjectId: input.vercelProjectId } : {}),
+            ...(input.githubRepo ? { githubRepo: input.githubRepo } : {}),
+            ...(input.neonProjectId ? { neonProjectId: input.neonProjectId } : {}),
+        }, input.now ? { now: input.now } : {});
+        raw = readRawState(rootDir);
+    }
+    // A re-run CARRIES every field of the block that is not the link's own — above all
+    // `neonRevokePending` (ADOPT-008): dropping it would leave a replaced key alive with nobody to
+    // revoke it.
+    const previous = raw.vault !== null && typeof raw.vault === 'object' && !Array.isArray(raw.vault)
+        ? raw.vault
+        : {};
+    const link = {
+        ...previous,
+        ...buildVaultState(input.projectId, { done: true }),
+        ...(input.vercelProjectId ? { vercelProjectId: input.vercelProjectId } : {}),
+    };
+    raw.vault = link;
+    if (input.resend)
+        raw.resend = mergeResendBlock(raw.resend, input.resend);
+    delete raw[VAULT_DECLINED_KEY];
+    writeRawState(rootDir, raw);
+    return link;
+}
+/**
+ * The `resend` block after the adoption minted `next`: the key it REPLACES is never forgotten. The
+ * previous `apiKeyId` (when it is another key) and the previous `pendingRevokeIds` join `next`'s
+ * pending list — dropping them would leave live keys nobody can revoke by id. A previous delivery
+ * marker is NOT carried: it was taken before an older write, so a job after it proves nothing about
+ * the new key; without one, the settle takes the marker then (`settleResendRevokes`).
+ */
+export function mergeResendBlock(previous, next) {
+    const prev = previous !== null && typeof previous === 'object' && !Array.isArray(previous)
+        ? previous
+        : {};
+    const ids = [
+        ...(Array.isArray(prev.pendingRevokeIds) ? prev.pendingRevokeIds : []),
+        ...(typeof prev.apiKeyId === 'string' && prev.apiKeyId !== '' ? [prev.apiKeyId] : []),
+        ...(next.pendingRevokeIds ?? []),
+    ].filter((id) => typeof id === 'string' && id !== '' && id !== next.apiKeyId);
+    const pending = [...new Set(ids)];
+    const merged = { apiKeyId: next.apiKeyId, domain: next.domain };
+    if (pending.length > 0) {
+        merged.pendingRevokeIds = pending;
+        if (next.syncJobsAtPublish)
+            merged.syncJobsAtPublish = next.syncJobsAtPublish;
+    }
+    return merged;
+}
+/**
+ * ADOPT-004 — record that the repo DECLINES the vault, in the shape ADOPT-001 chose for the link
+ * (see {@link writeAdoptionLink}), and touch nothing else: no `.env.local`, no `package.json`, no
+ * network. Local only by construction — this function has no seam to reach a service.
+ *
+ *   · The repo is already in the vault (a well-formed `vault` block) → refuses, writes nothing.
+ *   · The mark is already there → nothing is written: a second `--decline` leaves the file
+ *     byte-for-byte as it was (the first timestamp stays).
+ *   · The file EXISTS (either shape) → only the {@link VAULT_DECLINED_KEY} key is added; every
+ *     other key stays what it was.
+ *   · There is NO file → it is born in the ADOPTED shape (`adoptState`, `lifecycle: 'live'`) with
+ *     the slug and `unknown` for every provider id — the declining run asks no provider — plus
+ *     the mark, and no `vault` block. `provision --adopt --force` completes the ids later and
+ *     carries the mark.
+ *
+ * Fail-closed: an unreadable file and a malformed `vault` block stop it (never "no vault").
+ *
+ * @throws {CLIError} when the repo is adopted, or the state cannot be read or written.
+ */
+export function writeDeclineMark(rootDir, input) {
+    const now = input.now ?? (() => new Date());
+    let raw = readRawState(rootDir);
+    const born = raw === null;
+    if (raw !== null) {
+        // Throws on a malformed block (VaultLinkMalformedError) — never read as "no vault".
+        if (readVaultLink(rootDir) !== null) {
+            throw new CLIError('Este repo ya está en la bóveda (tiene bloque `vault` en ' +
+                `\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`): no hay nada que declinar. No escribí nada.`);
+        }
+        if (Object.prototype.hasOwnProperty.call(raw, VAULT_DECLINED_KEY))
+            return 'already-declined';
+    }
+    else {
+        adoptState(rootDir, { slug: input.slug }, { now });
+        raw = readRawState(rootDir);
+    }
+    const mark = { at: now().toISOString() };
+    raw[VAULT_DECLINED_KEY] = mark;
+    try {
+        writeRawState(rootDir, raw, 'que el repo declinó la bóveda');
+    }
+    catch (error) {
+        // A file this run created without its mark would read as "undecided": take it back.
+        if (born)
+            rmSync(provisionStatePath(rootDir), { force: true });
+        throw error;
+    }
+    return 'declined';
+}
+/** The Vercel project id a previous adoption recorded inside the `vault` block, if any. */
+export function recordedAdoptionVercelId(vault) {
+    const id = vault?.vercelProjectId;
+    return typeof id === 'string' && id.trim() !== '' ? id.trim() : null;
+}
+/**
+ * Rename `.env.local` to {@link ENV_LOCAL_BACKUP_FILE} — the LAST step of the apply. Refuses when
+ * the backup already exists (never overwritten) or when git would track it: a derivative's
+ * `.gitignore` is born frozen and may not cover it, and a secret in the history is permanent.
+ */
+export async function retireEnvLocal(rootDir, isGitIgnored) {
+    const source = path.join(rootDir, ENV_LOCAL_FILE);
+    if (!existsSync(source))
+        return 'absent';
+    const backup = path.join(rootDir, ENV_LOCAL_BACKUP_FILE);
+    if (existsSync(backup))
+        return 'backup-exists';
+    if (!(await isGitIgnored(ENV_LOCAL_BACKUP_FILE)))
+        return 'backup-not-ignored';
+    renameSync(source, backup);
+    return 'renamed';
+}
+// ---------------------------------------------------------------------------
+// Railway — inventory, import and sync (API GraphQL with the rail's team token)
+// ---------------------------------------------------------------------------
+/** Railway's public GraphQL endpoint — re-exported from the client (RWAY-002), its only caller. */
+export { RAILWAY_GRAPHQL_URL } from './railway-api.js';
+/**
+ * Prefix of the variables Railway provides by itself to every service (`RAILWAY_ENVIRONMENT`,
+ * `RAILWAY_PUBLIC_DOMAIN`, …). They are the platform's, not the project's: never imported into the
+ * vault — `main:/` also feeds Vercel production, where they would be false — and never counted as
+ * something a sync would delete.
+ */
+export const RAILWAY_PROVIDED_PREFIX = 'RAILWAY_';
+/** Whether `key` is one of the variables Railway provides by itself. */
+export function isRailwayProvided(key) {
+    return key.startsWith(RAILWAY_PROVIDED_PREFIX);
+}
+/** The Railway client over `fetchImpl` with an already-read team token. */
+function railwayClientOver(token, fetchImpl) {
+    return createRailwayClient({ token, transport: railwayFetchTransport(fetchImpl) });
+}
+/**
+ * Every Railway project the TEAM token reaches, with its services and environments — through the
+ * client (RWAY-002). This is the token's proof of life too: a query over projects, NEVER `me`
+ * (`fx-secrets-vault §5`). Fail-closed: a missing list, or one with unread pages, throws.
+ */
+export async function listRailwayProjects(token, fetchImpl) {
+    return (await railwayClientOver(token, fetchImpl).listProjects()).map((p) => ({
+        id: p.id,
+        name: p.name,
+        services: p.services.map((s) => ({ id: s.id, name: s.name })),
+        environments: p.environments,
+    }));
+}
+/** The variables of one service in one environment — values in memory only (import first). */
+export async function readRailwayVariables(token, where, fetchImpl) {
+    return railwayClientOver(token, fetchImpl).readVariableValues(where);
+}
+/**
+ * Inventory the Railway project CONNECTED TO THE REPO (Decision 13: the platform decides the
+ * destination; a project's name need not match the repo): each service × environment with its
+ * variables, values in memory. `null` when no service is connected to `repo` — not an error: most
+ * repos only deploy to Vercel. 🔴 Two or more connected projects are several deploys of one code:
+ * `vault adopt` stops BEFORE writing anything and points at the several-deploys pattern — it never
+ * imports values of different deploys into one vault (`fx-secrets-vault §6`).
+ */
+export async function readRailwayInventory(repo, token, fetchImpl) {
+    const client = railwayClientOver(token, fetchImpl);
+    const matches = await client.findByConnectedRepo(repo);
+    const projects = connectedProjects(matches);
+    if (projects.length > 1) {
+        throw new CLIError(`Hay ${projects.length} proyectos de Railway conectados a \`${repo}\`: ` +
+            `${projects.map((p) => `\`${p.name}\` (${p.id})`).join(', ')}. Es un repo con varios despliegues: ` +
+            '`vault adopt` no importa a una sola bóveda valores de despliegues distintos.\n' +
+            '  · Cada despliegue es su propio proyecto de la bóveda, con una plantilla y el registro ' +
+            '`.timekast/deploys.json`: se operan con `factory vault deploys` (fx-secrets-vault §6).\n' +
+            'No hice nada.');
+    }
+    const [connected] = projects;
+    if (!connected)
+        return null;
+    const project = await client.getProject(connected.id);
+    if (!project) {
+        throw new CLIError(`Railway dejó de encontrar el proyecto \`${connected.name}\` (${connected.id}) entre la búsqueda y la ` +
+            'lectura. Repite. No hice nada.');
+    }
+    const sources = [];
+    for (const service of project.services) {
+        for (const environment of project.environments) {
+            const values = await client.readVariableValues({
+                projectId: project.id,
+                environmentId: environment.id,
+                serviceId: service.id,
+                serviceName: service.name,
+            });
+            sources.push({
+                label: `${service.name}@${environment.name}`,
+                service: { id: service.id, name: service.name },
+                environment,
+                values,
+            });
+        }
+    }
+    return { project: { id: project.id, name: project.name }, sources };
+}
+/** The vault environments a Railway sync may read from (their root folder). */
+export const RAILWAY_VAULT_ENVS = [VAULT_ENV_MAIN, VAULT_ENV_DEVELOP];
+/**
+ * The Railway syncs `vault adopt` proposes (ADOPT-002): one per service × environment whose
+ * Railway environment has the SAME NAME as a vault deploy environment (`main`, `develop`) —
+ * "cada entorno a su igual en Railway". A Railway environment with another name (`production`) is
+ * never mapped by guessing: it is returned in `unmapped`, and the plan points at
+ * `factory vault sync railway --railway-env <nombre>` (the user's answer, 2026-09-24).
+ */
+export function proposeRailwaySyncs(inventory) {
+    const proposals = [];
+    const unmapped = [];
+    for (const source of inventory.sources) {
+        const vaultEnv = RAILWAY_VAULT_ENVS.find((env) => env === source.environment.name);
+        if (vaultEnv)
+            proposals.push({ vaultEnv, source });
+        else
+            unmapped.push(source);
+    }
+    return { proposals, unmapped };
+}
+/** How a Railway sync is named in plans, questions and messages. */
+export function railwaySyncLabel(vaultEnv, source) {
+    return `${vaultEnv}:/ → Railway ${source.label}`;
+}
+/**
+ * The name a created Railway sync gets: `<slug>-railway-<env>-<service>`, lowercase, only
+ * `[a-z0-9-]` (the instance takes slug-shaped names). The service's NAME, not its id: readable in
+ * the vault's list, and the id stays in the destination config.
+ */
+export function railwaySyncName(slug, vaultEnv, serviceName) {
+    const service = serviceName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'service';
+    return `${slug}-railway-${vaultEnv}-${service}`;
+}
+/**
+ * Plan the import of Railway into one deploy root (`main:/` or `develop:/`) — the user's answer
+ * for the first sync over a live destination (2026-09-24): "importar primero". Pure: values in,
+ * writes and key NAMES out.
+ *
+ *   · A key the folder does not hold → written there (a reference to `main:/` when the folder is
+ *     `develop:/` and `main:/` holds the same value — one copy of each shared value).
+ *   · A key the folder holds with the same value → nothing.
+ *   · With another value → `differing` (the vault stays the single writer; the sync replaces
+ *     Railway's value — the person confirms it).
+ *   · A local-only key or a retired rail token → `removed` (the guard refuses it in a deploy root;
+ *     the sync removes it from Railway — the person confirms it).
+ *   · Railway's own `RAILWAY_*` variables → ignored ({@link isRailwayProvided}).
+ *
+ * `folder` is what the folder holds (or will hold) with references RESOLVED; `mainFolder` the same
+ * for `main:/` when `location` is `develop:/`.
+ */
+export function planRailwayImport(input) {
+    const plan = { writes: [], differing: [], removed: [], conflicting: [] };
+    const seen = new Map();
+    const conflicting = new Set();
+    for (const source of input.sources) {
+        for (const [key, value] of source) {
+            if (isRailwayProvided(key))
+                continue;
+            const before = seen.get(key);
+            if (before !== undefined && before !== value)
+                conflicting.add(key);
+            if (before === undefined)
+                seen.set(key, value);
+        }
+    }
+    const develop = input.location.env === VAULT_ENV_DEVELOP;
+    for (const key of [...seen.keys()].sort()) {
+        const value = seen.get(key);
+        if (input.retired.has(key) || LOCAL_ONLY_KEYS.has(key)) {
+            plan.removed.push(key);
+            continue;
+        }
+        if (conflicting.has(key)) {
+            plan.conflicting.push(key);
+            continue;
+        }
+        const current = input.folder.get(key);
+        if (current !== undefined) {
+            if (current !== value)
+                plan.differing.push(key);
+            continue;
+        }
+        if (develop && input.mainFolder?.get(key) === value) {
+            plan.writes.push({
+                kind: 'reference',
+                location: input.location,
+                key,
+                origin: key,
+                target: { ...MAIN_ROOT, key },
+            });
+            continue;
+        }
+        plan.writes.push({ kind: 'value', location: input.location, key, origin: key, value });
+    }
+    return plan;
+}
+/** Whether `sync` writes to this Railway service × environment (any source folder). */
+export function isRailwaySyncTo(sync, where) {
+    const config = sync.destinationConfig;
+    return (sync.destination === 'railway' &&
+        config.projectId === where.projectId &&
+        config.environmentId === where.environmentId &&
+        config.serviceId === where.serviceId);
+}
+/**
+ * Why an existing Railway sync of this destination is NOT the expected one — empty when it can be
+ * adopted as is. Same strictness as the repo syncs (ADR-005 §8): its source folder, deletion in the
+ * destination ON, auto-sync ON, no key schema. Never patched: named, and the run stops.
+ */
+export function railwaySyncDifferences(sync, expected) {
+    const differences = [];
+    if (!sync.source || sync.source.env !== expected.env || sync.source.path !== expected.path) {
+        differences.push(`su fuente es \`${sync.source ? formatLocation(sync.source) : 'desconocida'}\` ` +
+            `(espero \`${formatLocation(expected)}\`)`);
+    }
+    if (sync.disableSecretDeletion) {
+        differences.push('tiene desactivado el borrado en destino (espero activado)');
+    }
+    if (sync.isAutoSyncEnabled !== true) {
+        differences.push('no tiene el auto-sync encendido (espero encendido)');
+    }
+    if (sync.keySchema !== null && sync.keySchema !== '' && sync.keySchema !== '{{secretKey}}') {
+        differences.push(`renombra las claves con el esquema \`${sync.keySchema}\` (espero sin esquema)`);
+    }
+    return differences;
+}
+// ---------------------------------------------------------------------------
+// Local-only keys found in a deploy
+// ---------------------------------------------------------------------------
+/**
+ * The keys to retire: every rail key ({@link isRailKey}) and every retired key nothing reads
+ * ({@link RETIRED_UNREAD_KEYS}) found in any source — `.env.local` or a deploy — and every
+ * local-only key (`LOCAL_ONLY_KEYS`) found in a Vercel or Railway deploy — which the vault's write guard
+ * would refuse in `main:/`/`develop:/` anyway, and which must never reach a deploy (ADR-005).
+ */
+export function retiredKeys(values) {
+    const retired = new Set();
+    const everywhere = [values.local, values.production, values.preview, ...values.railway.values()];
+    for (const source of everywhere) {
+        for (const key of source.keys()) {
+            if (isRailKey(key) || RETIRED_UNREAD_KEYS.includes(key))
+                retired.add(key);
+        }
+    }
+    for (const key of LOCAL_ONLY_KEYS) {
+        if (values.production.has(key) || values.preview.has(key))
+            retired.add(key);
+        // ADOPT-002: a Railway sync reads a deploy root too, where the guard refuses these.
+        if ([...values.railway.values()].some((source) => source.has(key)))
+            retired.add(key);
+    }
+    return retired;
+}
+const SEALED_REASON = 'cifra datos guardados: una llave nueva los deja ilegibles para siempre';
+/**
+ * 🔴 THE table of the kit — the only place that says which `sensitive` var belongs to which class.
+ * A key NOT here is `desconocida` (asked; without an answer, sealed), except the encryption-key
+ * shapes of {@link SEALED_KEY_PATTERN}, which are sealed without asking.
+ */
+export const SENSITIVE_KEY_TABLE = {
+    DATABASE_URL: {
+        class: 'derivable',
+        derive: 'neon-pooled',
+        source: 'la API de Neon (con `NEON_API_KEY` del rail): la cadena pooled del branch de ese entorno',
+    },
+    NEXT_PUBLIC_APP_URL: {
+        class: 'derivable',
+        derive: 'app-url',
+        source: 'el dominio de ese entorno en Vercel',
+    },
+    WEBAUTHN_RP_ID: {
+        class: 'derivable',
+        derive: 'rp-id',
+        source: 'el dominio de producción en Vercel (el rpID es uno solo y no cambia)',
+    },
+    WEBAUTHN_RELATED_ORIGINS: {
+        class: 'derivable',
+        derive: 'related-origins',
+        source: 'el dominio de develop en Vercel',
+    },
+    AUTH_SECRET: {
+        class: 'rotable',
+        rotate: 'auth-secret',
+        effect: 'cierra todas las sesiones de ese entorno en cuanto el sync lo escriba',
+    },
+    AUTH_GOOGLE_SECRET: {
+        class: 'rotable',
+        rotate: 'provider',
+        effect: 'se reemite en la consola de Google; el secreto viejo deja de servir',
+    },
+    AUTH_GITHUB_SECRET: {
+        class: 'rotable',
+        rotate: 'provider',
+        effect: 'se reemite en la configuración de la OAuth App de GitHub; el secreto viejo deja de servir',
+    },
+    RESEND_API_KEY: {
+        class: 'rotable',
+        rotate: 'provider',
+        effect: 'se reemite en Resend (una key propia del proyecto, sólo envío); la vieja deja de servir',
+    },
+    MFA_ENCRYPTION_KEY: { class: 'sellada', reason: SEALED_REASON },
+};
+/**
+ * The shape of an encryption key the kit does not list (`LEGACY_CIPHER_KEY`,
+ * `DATA_ENCRYPTION_KEY`…): sealed WITHOUT asking — asking could only end in the one answer that
+ * destroys data.
+ */
+export const SEALED_KEY_PATTERN = /(ENCRYPT|CIPHER|CRYPT_KEY|_KEK$|SEAL)/;
+/**
+ * Classify one `sensitive` var — pure, on `{ key, type, target }`. The target is part of the
+ * contract (the same key may be sensitive in one environment and readable in another: each is
+ * classified where it is sensitive); the class depends on the key. A var that is NOT `sensitive`
+ * has no verdict here (`null`): it is read, or it blocks as unreadable.
+ */
+export function classifySensitive(input) {
+    if (input.type !== 'sensitive')
+        return null;
+    const known = SENSITIVE_KEY_TABLE[input.key];
+    if (known)
+        return known;
+    if (SEALED_KEY_PATTERN.test(input.key))
+        return { class: 'sellada', reason: SEALED_REASON };
+    return { class: 'desconocida' };
+}
+/** The vault folder a Vercel target is imported into (ADR-005 §1). */
+export function folderOfTarget(target) {
+    return target === 'production' ? MAIN_ROOT : DEVELOP_ROOT;
+}
+/**
+ * The text `adopt` prints when it stops on a sealed key — written for the developer's AGENT to
+ * follow: (1) which var, (2) why it cannot be regenerated, (3) the bridge deploy, (4) that a person
+ * authorizes and supervises it step by step, (5) that `vault adopt` is run again afterwards.
+ */
+export function sealedStopExplanation(sealed, slug, vaultProjectExists = true) {
+    const lines = [
+        '🔴 Me detengo sin escribir nada: hay llaves SELLADAS marcadas como sensitive en Vercel, que no ' +
+            'devuelve su valor, y que no están en la bóveda.',
+    ];
+    for (const { name, target } of sealed) {
+        const folder = formatLocation(folderOfTarget(target));
+        lines.push('', `\`${name}\` (Vercel ${target}):`, `  1. Variable: \`${name}\`, en Vercel ${target}; su lugar en la bóveda es \`${folder}\` del proyecto \`${slug}\`.`, '  2. Por qué no la regenero: cifra datos ya guardados (por ejemplo, los secretos de MFA de tus ' +
+            'usuarios). Una llave nueva los deja ilegibles para siempre, sin forma de volver atrás.', `  3. Cómo se recupera: con un deploy puente — un build único de este proyecto en Vercel ${target} ` +
+            `que lee \`${name}\` y la escribe directo a \`${folder}\` de la bóveda, sin imprimirla en ningún log.`, '  4. Ese deploy lo autoriza y lo supervisa paso a paso una persona: ni este comando ni un agente ' +
+            'lo disparan solos.', '  5. Cuando la llave esté en la bóveda, vuelve a correr `factory vault adopt --apply`: la reconoce ' +
+            'y continúa sin detenerse.');
+    }
+    if (!vaultProjectExists) {
+        lines.push('', manualVaultProjectSteps(slug, sealed.map(({ target }) => formatLocation(folderOfTarget(target)))));
+    }
+    lines.push('', 'Nunca se genera una llave nueva para destrabar la adopción (fx-secrets-vault §8, paso 4).');
+    return lines.join('\n');
+}
+/**
+ * What to do when a key must be loaded into the vault BY HAND (a sealed key's bridge deploy, a
+ * credential re-issued at its provider) and the repo's vault project does not exist yet — the SAME
+ * text for both stops, concrete: create it with the slug and your own session, with the `main`,
+ * `develop` and `local` environments and the destination folder of the key; the later
+ * `factory vault adopt --apply` adopts it by slug and completes members, deletion protection and
+ * the import. (`provision` is not the way here: the repo is already deployed.)
+ */
+export function manualVaultProjectSteps(slug, folders) {
+    const unique = [...new Set(folders)].map((folder) => `\`${folder}\``).join(', ');
+    return (`El proyecto \`${slug}\` todavía no existe en la bóveda. Para cargar la clave a mano, créalo tú en ` +
+        `la bóveda, con tu sesión: nombre \`${slug}\`, entornos \`${VAULT_ENV_MAIN}\`, \`${VAULT_ENV_DEVELOP}\` y ` +
+        `\`${VAULT_ENV_LOCAL}\`, y la carpeta destino de la clave (${unique}). Después, ` +
+        '`factory vault adopt --apply` lo adopta por su slug y completa lo demás: miembros, protección ' +
+        'contra borrado e import.');
+}
+/**
+ * Whether the vault is OFFERED in this repo — the same rule as `vault adopt` (ADOPT-001): not in
+ * `core`, detected by the lockfile's `profile: 'core'` OR by the absence of the wrapper
+ * (`scripts/tools/with-vault.mjs`), never by the absence of `package.json`.
+ */
+export function isVaultOffered(rootDir) {
+    return (detectCoreProfile(rootDir) === null && existsSync(path.join(rootDir, WITH_VAULT_SCRIPT_FILE)));
+}
+/** The mode from its three facts — pure. A link wins over a stale mark; a mark wins over `core`. */
+export function vaultModeOf(input) {
+    if (input.linked)
+        return 'bóveda';
+    if (input.declined)
+        return 'declinado';
+    if (!input.offered)
+        return 'no aplica';
+    return 'sin decidir';
+}
+/**
+ * Read the mode — local, synchronous, no network. A `provision.json` that cannot be read, or whose
+ * `vault` block is malformed, gives NO mode (never an invented one): `error` carries the same
+ * message every other reader gives, with its remedy.
+ */
+export function readVaultMode(rootDir) {
+    let link;
+    let declined;
+    try {
+        link = readVaultLink(rootDir);
+        declined = readVaultDeclined(rootDir);
+    }
+    catch (error) {
+        return {
+            mode: null,
+            link: null,
+            error: error instanceof CLIError
+                ? error.message
+                : 'No pude leer `.timekast/provision.json` (error interno).',
+        };
+    }
+    return {
+        mode: vaultModeOf({ linked: link !== null, declined, offered: isVaultOffered(rootDir) }),
+        link,
+        error: null,
+    };
+}
+/** The Vercel target each deploy environment of the vault syncs to (ADR-005 §1). */
+const DRIFT_PAIRS = [
+    { env: 'main', target: 'production' },
+    { env: 'develop', target: 'preview' },
+];
+/**
+ * What a Vercel repo's report says about Railway: not compared there. A repo whose destination IS
+ * Railway gets the `railway` form of the report instead (RWAY-006).
+ */
+export const DRIFT_RAILWAY_NOT_VERIFIED = 'no verificado';
+/**
+ * Compare one vault folder (references RESOLVED — what its sync delivers) with its Vercel target.
+ * Pure: values in, key NAMES + display hashes out. A `null` deploy value is unreadable.
+ */
+export function classifyDrift(input) {
+    const { vault, deploy, hash } = input;
+    const keys = [...new Set([...vault.keys(), ...deploy.keys()])].sort();
+    return keys.map((key) => {
+        const inVault = vault.has(key);
+        const inDeploy = deploy.has(key);
+        const deployValue = deploy.get(key);
+        let state;
+        if (inDeploy && deployValue === null)
+            state = 'ilegible';
+        else if (!inDeploy)
+            state = 'sólo en la bóveda';
+        else if (!inVault)
+            state = 'sólo en el deploy';
+        else
+            state = vault.get(key) === deployValue ? 'igual' : 'distinta';
+        return {
+            key,
+            env: input.env,
+            target: input.target,
+            state,
+            ...(inVault ? { vault: hash(vault.get(key)) } : {}),
+            ...(inDeploy
+                ? { deploy: deployValue === null ? UNREADABLE_MARK : hash(deployValue) }
+                : {}),
+        };
+    });
+}
+/** Time budget of the whole drift (vault + rail + Vercel) in `doctor`/`status`. */
+export const DRIFT_TIMEOUT_MS = 20_000;
+/**
+ * Where there is never a vault session (CI, a Vercel build, Railway): the drift is not even
+ * attempted — reported `no verificable`, which is informative and never a warning, so it does not
+ * dirty every CI run (the wrapper passes through on the same signals, `fx-secrets-vault §7`).
+ */
+export const DRIFT_SKIP_SIGNALS = ['CI', 'VERCEL', 'RAILWAY_ENVIRONMENT'];
+/** RWAY-006 — the saved destination is Railway (an unreadable file reads as "not Railway"). */
+function isRailwayDestination(rootDir) {
+    try {
+        return readProvisionTarget(rootDir) === 'railway';
+    }
+    catch {
+        return false;
+    }
+}
+/** The seams that reach a session, the network or the environment — REQUIRED under Vitest. */
+const REQUIRED_DRIFT_SEAMS = [
+    'vaultClient',
+    'rail',
+    'fetchImpl',
+    'env',
+];
+/** Why the drift could not be verified — the failure's own message (rail/vault/Vercel), never a value. */
+function driftFailureReason(error) {
+    if (error instanceof RailError || error instanceof CLIError)
+        return error.message;
+    return 'No pude verificar el drift (error interno al leer la bóveda o Vercel).';
+}
+/**
+ * The drift between the vault and Vercel, by display hash (ADOPT-004), for a repo in the vault:
+ * `main:/` against production and `develop:/` against preview, key by key. Reads only — the vault
+ * with the person's session, Vercel with the rail's token; the project is found with the SAME
+ * localizer `vault adopt` uses (recorded id first, then the project connected to the repo).
+ *
+ * Never throws for a missing session, network or project: those are `no verificable` with the
+ * failure's own message (the rail's names the login). Bounded by `timeoutMs`. The one exception is
+ * the test-isolation refusal: under Vitest, a call without its seams throws BEFORE any request.
+ */
+export async function computeVaultDrift(rootDir, link, deps = {}) {
+    const railway = isRailwayDestination(rootDir);
+    if (globalThis[VAULT_TEST_ISOLATION_KEY] !== undefined) {
+        for (const seam of REQUIRED_DRIFT_SEAMS) {
+            if (deps[seam] === undefined)
+                throw new VaultSeamMissingError(seam);
+        }
+        if (railway && !deps.railwayClient && !deps.railwayTransport) {
+            throw new RailwaySeamMissingError();
+        }
+    }
+    // The same failure, in the shape of the destination's report.
+    const unverifiable = (reason) => railway
+        ? { status: 'railway', railway: { status: 'no verificable', reason } }
+        : { status: 'no verificable', reason, railway: DRIFT_RAILWAY_NOT_VERIFIED };
+    const env = deps.env ?? process.env;
+    const signal = DRIFT_SKIP_SIGNALS.find((name) => env[name] !== undefined && env[name] !== '');
+    if (signal) {
+        return unverifiable(`aquí no hay sesión de la bóveda (\`${signal}\` está definida: CI o un despliegue). Corre el reporte en tu máquina.`);
+    }
+    const timeoutMs = deps.timeoutMs ?? DRIFT_TIMEOUT_MS;
+    const platform = railway ? 'Railway' : 'Vercel';
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(unverifiable(`la bóveda o ${platform} no respondieron en ${Math.round(timeoutMs / 1000)} s. Revisa tu conexión y repite.`)), timeoutMs);
+        timer.unref?.();
+    });
+    const work = (railway
+        ? readRailwayDrift(rootDir, link, deps, timeoutMs)
+        : readDrift(rootDir, link, deps, timeoutMs)).catch((error) => unverifiable(driftFailureReason(error)));
+    try {
+        return await Promise.race([work, timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function readDrift(rootDir, link, deps, timeoutMs) {
+    const rail = deps.rail ?? createRailResolver({ timeoutMs });
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const token = await rail.get('VERCEL_TOKEN');
+    const teamId = await rail.getOptional('VERCEL_TEAM_ID');
+    if (!teamId) {
+        return {
+            status: 'no verificable',
+            reason: 'falta `VERCEL_TEAM_ID` en `rail-timekast`: no sé en qué team de Vercel buscar. Pide a un admin que la cargue.',
+            railway: DRIFT_RAILWAY_NOT_VERIFIED,
+        };
+    }
+    const target = readDestroyTarget(rootDir);
+    const repo = target?.githubRepo ?? null;
+    const location = await locateVercelProject({
+        recordedId: recordedAdoptionVercelId(link) ?? target?.vercelProjectId ?? null,
+        repo,
+        token,
+        teamId,
+        deps: { fetchImpl },
+    });
+    if (location.kind === 'none') {
+        return {
+            status: 'no verificable',
+            reason: 'este repo no tiene proyecto de Vercel: ni registrado en `.timekast/provision.json` ni conectado ' +
+                `a \`${repo ?? '(repo sin registrar)'}\`. Sólo se compara la bóveda con Vercel.`,
+            railway: DRIFT_RAILWAY_NOT_VERIFIED,
+        };
+    }
+    if (location.kind === 'ambiguous') {
+        return {
+            status: 'no verificable',
+            reason: `hay ${location.candidates.length} proyectos de Vercel conectados a \`${repo}\` ` +
+                `(${location.candidates.map((p) => `\`${p.name}\``).join(', ')}) y no elijo uno a ciegas. ` +
+                'Un repo con varios despliegues se opera con `factory vault deploys` (fx-secrets-vault §6).',
+            railway: DRIFT_RAILWAY_NOT_VERIFIED,
+        };
+    }
+    const project = location.project;
+    const client = deps.vaultClient ?? createVaultClient({ timeoutMs });
+    const vars = await listEnvVarsWithValues(project.id, token, teamId, { fetchImpl });
+    const hash = deps.hash ?? createDisplayHasher();
+    const entries = [];
+    for (const pair of DRIFT_PAIRS) {
+        const deploy = new Map();
+        for (const v of vars) {
+            // A preview var pinned to a git branch is not `develop:/`'s destination: not compared.
+            if (v.target.includes(pair.target) && !(pair.target === 'preview' && v.gitBranch)) {
+                deploy.set(v.key, v.value);
+            }
+        }
+        const vaultEnv = pair.env === 'main' ? link.envs.main : link.envs.develop;
+        const vault = await client.readSecrets(link.projectId, { env: vaultEnv, path: VAULT_ROOT_PATH }, { expandReferences: true });
+        entries.push(...classifyDrift({ env: pair.env, target: pair.target, vault, deploy, hash }));
+    }
+    return {
+        status: 'verificado',
+        vercelProject: { id: project.id, name: project.name },
+        entries,
+        railway: DRIFT_RAILWAY_NOT_VERIFIED,
+    };
+}
+/** The four drift states from two maps of display hashes (Railway returns every value). */
+function compareHashes(vault, deploy) {
+    const keys = [...new Set([...vault.keys(), ...deploy.keys()])].sort();
+    return keys.map((key) => {
+        const v = vault.get(key);
+        const d = deploy.get(key);
+        const state = v === undefined
+            ? 'sólo en el deploy'
+            : d === undefined
+                ? 'sólo en la bóveda'
+                : v === d
+                    ? 'igual'
+                    : 'distinta';
+        return {
+            key,
+            state,
+            ...(v !== undefined ? { vault: v } : {}),
+            ...(d !== undefined ? { deploy: d } : {}),
+        };
+    });
+}
+/**
+ * RWAY-006 — the drift between the vault and Railway, by display hash: `main:/` against the
+ * environment the block maps as `main`, `develop:/` against `develop`. It reads ONLY the ids of the
+ * `railway` block (project, service, environments) — never a search by connected repo (a repo that
+ * today is connected elsewhere must not move the comparison). Without a block → "no verificable,
+ * corre `--adopt`" without asking Railway. Railway returns the VALUES: each one is reduced to its
+ * display hash by the client as it arrives, and only hashes reach the report. `PORT` is compared like
+ * any key (the vault writes it); only the platform's `RAILWAY_*` are left out.
+ */
+async function readRailwayDrift(rootDir, link, deps, timeoutMs) {
+    const unverifiable = (reason) => ({
+        status: 'railway',
+        railway: { status: 'no verificable', reason },
+    });
+    const rw = readRailwayBlock(rootDir);
+    const projectId = rw?.projectId;
+    const serviceId = rw?.serviceId;
+    if (!rw || !projectId || !serviceId || !rw.environments?.main) {
+        return unverifiable('`.timekast/provision.json` no tiene el bloque `railway` con el proyecto, el ' +
+            'servicio y el entorno `main`, y no busco el proyecto por mi cuenta. Corre ' +
+            '`factory provision --adopt --force --target=railway` (sin `--force` si el repo todavía no ' +
+            'tiene ese archivo).');
+    }
+    const rail = deps.rail ?? createRailResolver({ timeoutMs });
+    const client = deps.railwayClient ??
+        createRailwayClient({
+            rail,
+            ...(deps.railwayTransport ? { transport: deps.railwayTransport } : {}),
+        });
+    const redo = 'No busco otro: rehaz el bloque con `factory provision --adopt --force --target=railway`.';
+    const project = await client.getProject(projectId);
+    if (!project) {
+        return unverifiable(`Railway no tiene el proyecto \`${projectId}\` que registra el bloque \`railway\`. ${redo}`);
+    }
+    const service = project.services.find((s) => s.id === serviceId);
+    if (!service) {
+        return unverifiable(`el proyecto de Railway \`${project.name}\` ya no tiene el servicio \`${serviceId}\` que registra el bloque \`railway\`. ${redo}`);
+    }
+    const vaultClient = deps.vaultClient ?? createVaultClient({ timeoutMs });
+    const hash = deps.hash ?? createDisplayHasher();
+    const entries = [];
+    const notes = [];
+    for (const role of ['main', 'develop']) {
+        const environmentId = rw.environments[role];
+        if (!environmentId) {
+            notes.push('sin entorno `develop` mapeado en el bloque `railway`: sólo se compara `main`.');
+            continue;
+        }
+        const environment = project.environments.find((e) => e.id === environmentId);
+        if (!environment) {
+            return unverifiable(`el proyecto de Railway \`${project.name}\` ya no tiene el entorno \`${environmentId}\` que el bloque mapea como \`${role}\`. ${redo}`);
+        }
+        const deployed = await client.readVariableHashes({ projectId, environmentId, serviceId, serviceName: service.name }, hash);
+        const deploy = new Map([...deployed].filter(([key]) => !isRailwayProvided(key)));
+        const values = await vaultClient.readSecrets(link.projectId, { env: role === 'main' ? link.envs.main : link.envs.develop, path: VAULT_ROOT_PATH }, { expandReferences: true });
+        const vault = new Map([...values].map(([key, value]) => [key, hash(value)]));
+        for (const entry of compareHashes(vault, deploy)) {
+            entries.push({ ...entry, env: role, railwayEnv: environment.name });
+        }
+    }
+    return {
+        status: 'railway',
+        railway: {
+            status: 'verificado',
+            project: { id: project.id, name: project.name },
+            service: { id: service.id, name: service.name },
+            entries,
+            notes,
+        },
+    };
+}
+/** The text of the Railway drift (RWAY-006) — names and display hashes only. */
+function renderRailwayDrift(drift) {
+    const lines = [];
+    if (drift.status === 'no verificable') {
+        const [first, ...rest] = drift.reason.split('\n');
+        lines.push(`  Drift bóveda ↔ Railway: no verificable — ${first}`);
+        for (const extra of rest)
+            if (extra.trim())
+                lines.push(`    ${extra}`);
+    }
+    else {
+        const off = drift.entries.filter((e) => e.state !== 'igual');
+        const equal = drift.entries.length - off.length;
+        lines.push(`  Drift bóveda ↔ Railway (\`${drift.project.name}\` · servicio \`${drift.service.name}\`), por huella (HMAC con llave de esta corrida):`);
+        if (off.length === 0) {
+            lines.push(`    ✔ Sin drift: ${equal} claves iguales.`);
+        }
+        else {
+            for (const e of off) {
+                const hashes = [
+                    e.vault ? `bóveda=${e.vault}` : null,
+                    e.deploy ? `deploy=${e.deploy}` : null,
+                ]
+                    .filter(Boolean)
+                    .join(' ');
+                lines.push(`    · ${e.key} — ${e.env} ↔ ${e.railwayEnv}: ${e.state}${hashes ? ` (${hashes})` : ''}`);
+            }
+            lines.push(`    ${equal} claves iguales. Una clave distinta o sólo en el deploy es la huella de un segundo ` +
+                'escritor: el valor se cambia en la bóveda y llega por el sync (fx-secrets-vault §7). ' +
+                'Las variables `RAILWAY_*` son de la plataforma y no se comparan.');
+        }
+        for (const note of drift.notes)
+            lines.push(`    ${note}`);
+    }
+    lines.push('  Vercel: no aplica (el destino de este repo es Railway).');
+    return lines;
+}
+/**
+ * The mode (local) + the drift (network, bounded, only in `bóveda`). Never throws for a missing
+ * session, network or unreadable state — except the Vitest seam refusal of {@link computeVaultDrift}.
+ */
+export async function inspectRepoVault(rootDir, deps = {}) {
+    return repoVaultReportFor(rootDir, readVaultMode(rootDir), deps);
+}
+/** {@link inspectRepoVault} over a mode already read (so `doctor` reads the file once). */
+export async function repoVaultReportFor(rootDir, reading, deps = {}) {
+    const drift = reading.mode === 'bóveda' && reading.link
+        ? await computeVaultDrift(rootDir, reading.link, deps)
+        : { status: 'no aplica' };
+    return { mode: reading.mode, modeError: reading.error, drift };
+}
+/** The line that tells the person how to decide — only `doctor`, only in `sin decidir`. */
+export const ADOPT_SUGGESTION = '  Para pasarlo a la bóveda: `factory vault adopt` (sin `--apply` sólo enseña el plan). ' +
+    'Si decides que no: `factory vault adopt --decline` y no te lo vuelvo a proponer.';
+/** One line per mode — plain es-MX. */
+function modeLine(report) {
+    switch (report.mode) {
+        case 'bóveda':
+            return 'Bóveda de secretos: este repo vive en la bóveda (modo `bóveda`).';
+        case 'declinado':
+            return 'Bóveda de secretos: este repo declinó la bóveda (modo `declinado`); trabaja con `.env.local` y `env:push`.';
+        case 'sin decidir':
+            return 'Bóveda de secretos: sin decidir (modo `sin decidir`); este repo trabaja con `.env.local` y nadie ha decidido si pasa a la bóveda.';
+        case 'no aplica':
+            return 'Bóveda de secretos: no aplica (perfil `core` o sin `scripts/tools/with-vault.mjs`).';
+        default:
+            return `Bóveda de secretos: no pude leer el modo. ${report.modeError ?? ''}`.trimEnd();
+    }
+}
+/**
+ * The text of the vault section of `doctor`/`status` — key NAMES and display hashes only.
+ * `suggestAdopt` adds the `vault adopt` line (only `doctor` asks for it, only in `sin decidir`).
+ */
+export function renderRepoVault(report, opts) {
+    const lines = [modeLine(report)];
+    if (opts.suggestAdopt && report.mode === 'sin decidir')
+        lines.push(ADOPT_SUGGESTION);
+    const drift = report.drift;
+    if (drift.status === 'railway') {
+        lines.push(...renderRailwayDrift(drift.railway));
+    }
+    else if (drift.status === 'no verificable') {
+        const [first, ...rest] = drift.reason.split('\n');
+        lines.push(`  Drift bóveda ↔ Vercel: no verificable — ${first}`);
+        for (const extra of rest)
+            if (extra.trim())
+                lines.push(`    ${extra}`);
+        lines.push(`  Railway: ${DRIFT_RAILWAY_NOT_VERIFIED} (este reporte sólo compara con Vercel).`);
+    }
+    else if (drift.status === 'verificado') {
+        const off = drift.entries.filter((e) => e.state !== 'igual');
+        const equal = drift.entries.length - off.length;
+        lines.push(`  Drift bóveda ↔ Vercel (\`${drift.vercelProject.name}\`), por huella (HMAC con llave de esta corrida):`);
+        if (off.length === 0) {
+            lines.push(`    ✔ Sin drift: ${equal} claves iguales entre main ↔ production y develop ↔ preview.`);
+        }
+        else {
+            for (const e of off) {
+                const hashes = [
+                    e.vault ? `bóveda=${e.vault}` : null,
+                    e.deploy ? `deploy=${e.deploy}` : null,
+                ]
+                    .filter(Boolean)
+                    .join(' ');
+                lines.push(`    · ${e.key} — ${e.env} ↔ ${e.target}: ${e.state}${hashes ? ` (${hashes})` : ''}`);
+            }
+            lines.push(`    ${equal} claves iguales. Una clave distinta o sólo en el deploy es la huella de un segundo ` +
+                'escritor: el valor se cambia en la bóveda y llega por el sync (fx-secrets-vault §7). ' +
+                '`ilegible` = sensitive en Vercel (no devuelve su valor).');
+        }
+        lines.push(`  Railway: ${DRIFT_RAILWAY_NOT_VERIFIED} (este reporte sólo compara con Vercel).`);
+    }
+    return lines;
+}
+// ---------------------------------------------------------------------------
+// ADOPT-009 — Factory mode, the connected-and-empty deploy, the project's Neon key
+// ---------------------------------------------------------------------------
+/**
+ * Factory mode — the checkout of the kit's ORIGIN, which `vault adopt` adopts with the same command
+ * as any derivative. TWO signals at once, never one: no `.timekast/lockfile.json` (ADR-003,
+ * {@link isFactoryCheckout}) AND the `origin` remote is the Factory's GitHub repo (`owner/repo`
+ * compared without case). An old derivative without a lockfile has another origin; a checkout
+ * without `origin` has none — neither enters. The origin is read through the caller's seam.
+ */
+export async function isFactoryMode(rootDir, readOriginRepo) {
+    if (!isFactoryCheckout(rootDir))
+        return false;
+    const origin = await readOriginRepo(rootDir);
+    return origin !== null && origin.toLowerCase() === FACTORY_REPO.toLowerCase();
+}
+/**
+ * 🔴 A deploy is "connected and EMPTY" only when this is proven — fail-closed:
+ *   · there is a Vercel project and its env listing came back WITH the list, and the list is
+ *     empty (production and preview both come from that one listing): a response WITHOUT the list
+ *     (`null`), an error or ONE variable (of any target) is not empty;
+ *   · Railway was consulted and has no project: present, or not consulted (no `RAILWAY_TOKEN` in
+ *     the rail, an error of its API) is not empty.
+ * Anything else → the normal rule (`main`/`develop` from the deploy).
+ */
+export function isConnectedEmptyDeploy(input) {
+    return (input.hasVercelProject &&
+        input.vercelEnvs !== null &&
+        input.vercelEnvs.length === 0 &&
+        input.railway === 'ausente');
+}
+/**
+ * The keys that vary per deploy environment (`fx-secrets-vault §7`): on a connected-and-empty
+ * deploy they are generated or derived (`buildEnvPlan`), never read from `.env.local`.
+ */
+export const PER_ENV_KEYS = new Set([
+    'DATABASE_URL',
+    'AUTH_SECRET',
+    'NEXT_PUBLIC_APP_URL',
+    'NEXT_PUBLIC_APP_ENV',
+    'WEBAUTHN_RP_ID',
+    'WEBAUTHN_RELATED_ORIGINS',
+    'NODE_ENV',
+]);
+/** The encryption key `buildEnvPlan` carries — shared, sealed: from `.env.local`, never generated. */
+export const MFA_KEY = 'MFA_ENCRYPTION_KEY';
+/**
+ * On a connected-and-empty deploy, the keys of `.env.local` that MAY be the product's shared values
+ * (`MFA_ENCRYPTION_KEY`, the sender, product flags…): everything but the per-environment keys,
+ * the local-only ones, the rail's and the retired ones. Each one is confirmed by whoever runs —
+ * a "no" keeps it only in `local`.
+ */
+export function sharedCandidatesOf(local) {
+    return [...local.keys()]
+        .filter((key) => !PER_ENV_KEYS.has(key) &&
+        !LOCAL_ONLY_KEYS.has(key) &&
+        !isRailKey(key) &&
+        !RETIRED_UNREAD_KEYS.includes(key))
+        .sort();
+}
+/** Neon's API (same base as `neon-api.ts`) — for the proof of a project-scoped key. */
+const NEON_PROOF_BASE = 'https://console.neon.tech/api/v2';
+const NEON_PROOF_TIMEOUT_MS = 15_000;
+/**
+ * Whether `key` is PROVEN the project's own Neon key, by a NEGATIVE scope test:
+ *
+ *   1. the candidate answers 2xx on its project (`GET /projects/{id}`);
+ *   2. the rail's key names the project's org (`GET /projects/{id}` → `org_id`) and lists the org's
+ *      projects, from which ONE sibling (another project of the same org) is taken;
+ *   3. the candidate answers EXACTLY 404 on that sibling.
+ *
+ * Step 3 is what separates the three classes of key (verified live, 2026-09-12): a project-scoped
+ * key 404s on any other project of its org; an org key and a member's personal key both see every
+ * project of the org (2xx). `GET /users/me/organizations` does NOT separate them — an org key 404s
+ * there exactly like a project key — so it is not asked.
+ *
+ * Any doubt → NOT proven: a non-2xx on step 1, a rail read that fails, an org without a sibling (the
+ * test cannot run), and any answer other than 404 on step 3 (a 429, a 5xx, a 401, a timeout). The
+ * caller then mints one; it never imports a key it could not prove. The key travels in a header
+ * only; nothing of the responses is kept.
+ */
+export async function isProjectScopedNeonKey(key, projectId, deps) {
+    const status = async (pathname) => {
+        try {
+            const response = await deps.fetchImpl(`${NEON_PROOF_BASE}${pathname}`, {
+                method: 'GET',
+                headers: { Authorization: `Bearer ${key}`, Accept: 'application/json' },
+                signal: AbortSignal.timeout(NEON_PROOF_TIMEOUT_MS),
+            });
+            return response.status;
+        }
+        catch {
+            return null;
+        }
+    };
+    const own = await status(`/projects/${encodeURIComponent(projectId)}`);
+    if (own === null || own < 200 || own >= 300)
+        return false;
+    let sibling;
+    try {
+        const railKey = await deps.railKey();
+        const orgId = await getNeonProjectOrg(railKey, projectId, { fetchImpl: deps.fetchImpl });
+        if (!orgId)
+            return false;
+        const projects = await listNeonProjects(railKey, orgId, { fetchImpl: deps.fetchImpl });
+        sibling = projects.find((project) => project.id !== projectId)?.id;
+    }
+    catch {
+        return false;
+    }
+    if (!sibling)
+        return false;
+    return (await status(`/projects/${encodeURIComponent(sibling)}`)) === 404;
+}