@timekast/factory 1.28.1 → 2.0.1

package/dist/lib/provision-state.js

@@ -46,6 +46,118 @@ import { TIMEKAST_DIR } from './constants.js';
 export const PROVISION_DIR = TIMEKAST_DIR;
 /** Filename of the provision state document inside {@link PROVISION_DIR}. */
 export const PROVISION_STATE_FILE = 'provision.json';
+/** The canonical roles, in creation order. */
+export const VAULT_SYNC_ROLES = [
+    'vercel-production',
+    'vercel-preview',
+    'github-ci',
+];
+/** The key of {@link NeonRevokePending} inside the `vault` block. */
+export const NEON_REVOKE_PENDING_KEY = 'neonRevokePending';
+/**
+ * Narrow a persisted {@link NeonRevokePending}, else `null`. A damaged block reads as "nothing
+ * pending": the replaced keys keep their name, so the next rotation lists them again anyway.
+ */
+export function asNeonRevokePending(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const obj = value;
+    if (typeof obj.orgId !== 'string' || obj.orgId.trim() === '')
+        return null;
+    const keyIds = Array.isArray(obj.keyIds)
+        ? obj.keyIds.filter((id) => typeof id === 'string' && id.trim() !== '')
+        : [];
+    if (keyIds.length === 0)
+        return null;
+    const marker = obj.syncJobsAtWrite;
+    if (marker === null || typeof marker !== 'object' || Array.isArray(marker))
+        return null;
+    const syncJobsAtWrite = {};
+    for (const [id, job] of Object.entries(marker)) {
+        if (typeof job === 'string')
+            syncJobsAtWrite[id] = job;
+    }
+    return { orgId: obj.orgId, keyIds, syncJobsAtWrite };
+}
+/** The environment slugs of ADR-005 (duplicated from `vault-api.ts` — see {@link VaultState}). */
+export const VAULT_STATE_ENVS = Object.freeze({
+    main: 'main',
+    develop: 'develop',
+    local: 'local',
+});
+/**
+ * Build the `vault` block for a project id. Pure — no I/O, no external deps — so the local
+ * wrapper's tests (VAULT-003, root suite) can construct it exactly as provision writes it.
+ */
+export function buildVaultState(projectId, opts = {}) {
+    return {
+        projectId,
+        envs: { ...VAULT_STATE_ENVS },
+        ...(opts.done === undefined ? {} : { done: opts.done }),
+    };
+}
+/**
+ * The `vault` block of `.timekast/provision.json` is PRESENT but malformed (`vault: null`, no
+ * `projectId`, missing `envs.*`…). Typed so every path that decides vault-vs-file stops on it: "I
+ * could not tell" must never read as "no vault" — that would write secrets to `.env.local` (or
+ * create a second vault project) in a repo whose secrets live in the vault. Mirrors the
+ * wrapper's `readVaultBlock` (`scripts/tools/with-vault.mjs`), which refuses the same shapes.
+ */
+export class VaultLinkMalformedError extends CLIError {
+    constructor() {
+        super(`El bloque \`vault\` de \`${PROVISION_DIR}/${PROVISION_STATE_FILE}\` no tiene la forma esperada ` +
+            '(`projectId` + `envs.main`/`envs.develop`/`envs.local`). No decido a ciegas si este repo vive ' +
+            'en la bóveda. Corrígelo a mano: si el repo está en la bóveda, escribe el bloque con esa forma ' +
+            '(`projectId` es el id de su proyecto en la bóveda, con el mismo slug; `envs` es ' +
+            '`{ "main": "main", "develop": "develop", "local": "local" }`); si no lo está, borra el bloque. ' +
+            '`--adopt` no lo arregla: conserva el bloque del state que reemplaza.');
+        this.name = 'VaultLinkMalformedError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * The `vault` block of a parsed state object, fail-closed: `null` only when the key is ABSENT;
+ * a present block that does not narrow to {@link VaultState} throws.
+ *
+ * @throws {VaultLinkMalformedError} when `vault` is present but malformed (including `null`).
+ */
+function vaultBlockOf(obj) {
+    if (!Object.prototype.hasOwnProperty.call(obj, 'vault') || obj.vault === undefined)
+        return null;
+    const vault = asVaultState(obj.vault);
+    if (vault === null)
+        throw new VaultLinkMalformedError();
+    return vault;
+}
+/** Narrow an unknown value to a well-formed {@link VaultState}, else `null`. */
+export function asVaultState(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const obj = value;
+    if (typeof obj.projectId !== 'string' || obj.projectId.trim() === '')
+        return null;
+    const envs = obj.envs;
+    if (!envs ||
+        typeof envs.main !== 'string' ||
+        typeof envs.develop !== 'string' ||
+        typeof envs.local !== 'string') {
+        return null;
+    }
+    return obj;
+}
+/**
+ * Key of `.timekast/provision.json` that records a repo which DECLINED the vault
+ * (`factory vault adopt --decline`, ADOPT-004). A sibling of the `vault` block — never inside it —
+ * so neither can be mistaken for the other. `vault adopt --apply` deletes it (adopting is the newer
+ * decision), and `provision --adopt --force` carries it like the `vault` block.
+ */
+export const VAULT_DECLINED_KEY = 'vaultDeclined';
+/** The valid {@link ProvisionTarget} values, for the `--target` validation and the reader. */
+export const PROVISION_TARGETS = ['vercel', 'railway'];
+/** Narrow an unknown value to a {@link ProvisionTarget}. */
+export function isProvisionTarget(value) {
+    return typeof value === 'string' && PROVISION_TARGETS.includes(value);
+}
 /** Absolute path to the provision state file under a repo root. */
 export function provisionStatePath(rootDir) {
     return path.join(rootDir, PROVISION_DIR, PROVISION_STATE_FILE);
@@ -80,10 +192,12 @@ function asProvisionState(parsed) {
  *
  *   - file absent          → `null` (nothing to resume — a fresh run)
  *   - file present + valid  → the typed {@link ProvisionState}
- *   - file present + broken → `CLIError` pointing at `--force` to start over
+ *   - file unreadable / not JSON / not an object → `CLIError` with {@link UNREADABLE_STATE_REMEDY} (git holds the
+ *     committed copy; `--force` refuses that file — see `runProvision`)
+ *   - JSON of the wrong shape → `CLIError` pointing at `--force` to start over: the file parses,
+ *     so `--force` still carries its `vault` and `resend` blocks into the fresh run
  *
- * "Broken" covers an unreadable file (perms/race), non-JSON content, and
- * JSON-of-the-wrong-shape. Never throws a raw `JSON.parse` error.
+ * Never throws a raw `JSON.parse` error.
  *
  * @throws {CLIError} when the file exists but cannot be parsed into a valid state.
  */
@@ -96,22 +210,25 @@ export function readProvisionState(rootDir) {
         text = readFileSync(file, 'utf8');
     }
     catch {
-        throw new CLIError(`No se pudo leer el estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`). ` +
-            'Si está dañado, vuelve a correr con `--force` para descartarlo y empezar de cero.');
+        throw new CLIError(`No se pudo leer el estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`): ` +
+            UNREADABLE_STATE_REMEDY);
     }
     let parsed;
     try {
         parsed = JSON.parse(text);
     }
     catch {
-        throw new CLIError(`El estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`) está corrupto (JSON inválido). ` +
-            'Vuelve a correr con `--force` para descartarlo y empezar de cero.');
+        throw new CLIError(`El estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`) está corrupto (JSON inválido): ` +
+            UNREADABLE_STATE_REMEDY);
     }
     const state = asProvisionState(parsed);
     if (!state) {
         throw new CLIError(`El estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`) tiene una estructura inesperada. ` +
             'Vuelve a correr con `--force` para descartarlo y empezar de cero.');
     }
+    // Fail-closed on a present-but-malformed `vault` block: `state.vault` decides vault-vs-file
+    // for every later step (`vaultCtxFor`), and a truthy garbage block must not reach it either.
+    vaultBlockOf(state);
     return state;
 }
 /**
@@ -127,11 +244,15 @@ export function readProvisionState(rootDir) {
  * created resource's id is durable before the next (riskier) step runs.
  */
 export function writeProvisionState(rootDir, state) {
+    writeStateDocument(rootDir, state);
+}
+/** The atomic temp-file + rename swap every writer of the state file goes through. */
+function writeStateDocument(rootDir, document) {
     const dir = path.join(rootDir, PROVISION_DIR);
     mkdirSync(dir, { recursive: true });
     const target = provisionStatePath(rootDir);
     const tmp = path.join(dir, `.${PROVISION_STATE_FILE}.tmp`);
-    const body = `${JSON.stringify(state, null, 2)}\n`;
+    const body = `${JSON.stringify(document, null, 2)}\n`;
     try {
         writeFileSync(tmp, body, 'utf8');
         renameSync(tmp, target);
@@ -143,6 +264,91 @@ export function writeProvisionState(rootDir, state) {
             `${error?.message ?? 'error desconocido'}.`);
     }
 }
+/**
+ * The raw JSON object of the state file, whatever its shape; `null` when the file is absent.
+ *
+ * @throws {CLIError} when it exists but cannot be read, is not JSON or is not an object.
+ */
+function readStateObject(rootDir) {
+    const file = provisionStatePath(rootDir);
+    if (!existsSync(file))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new CLIError(`No pude leer \`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`: ${UNREADABLE_STATE_REMEDY}`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new CLIError(`\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\` no es un objeto JSON: ${UNREADABLE_STATE_REMEDY}`);
+    }
+    return parsed;
+}
+/**
+ * RWAY-003 — the SAVED destination (`target`) of `.timekast/provision.json`, in either shape of
+ * the file. `null` without a file or without the field. This is the ONLY thing of the file that
+ * decides a destination: no other block or file is evidence of one.
+ *
+ * 🔴 FAIL-CLOSED on a `target` that is present but is not `vercel`/`railway`: read as "no
+ * target", the next run would discover again and could save a different one over it.
+ *
+ * @throws {CLIError} when the file is unreadable, or `target` has an unknown value.
+ */
+export function readProvisionTarget(rootDir) {
+    const obj = readStateObject(rootDir);
+    if (!obj || !Object.prototype.hasOwnProperty.call(obj, 'target'))
+        return null;
+    if (isProvisionTarget(obj.target))
+        return obj.target;
+    throw new CLIError(`\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\` tiene un \`target\` que no reconozco ` +
+        `(\`${String(obj.target)}\`; válidos: ${PROVISION_TARGETS.join(', ')}). No lo sustituyo por mi ` +
+        `cuenta: ${UNREADABLE_STATE_REMEDY}`);
+}
+/**
+ * RWAY-003 — the repo's GitHub IDENTITY as the state records it (`github.repo` of the step shape,
+ * `githubRepo` of the adopted one); `null` when neither is there. Identity, never destination:
+ * it says WHICH repo to ask the platforms about, not where it deploys.
+ */
+export function readStateRepoIdentity(rootDir) {
+    const obj = readStateObject(rootDir);
+    if (!obj)
+        return null;
+    const github = obj.github;
+    const candidates = [github?.repo, obj.githubRepo];
+    for (const value of candidates) {
+        if (typeof value === 'string' && value.trim() !== '' && value !== ADOPT_UNKNOWN)
+            return value;
+    }
+    return null;
+}
+/**
+ * RWAY-003 — save `target` in `.timekast/provision.json`, touching NOTHING else of the file (in
+ * either shape). Without a file: only when `minimal` is given, it creates the minimal valid state
+ * with the target and no provider ids (a repo older than the CLI). Same atomic swap as every
+ * other writer.
+ *
+ * @returns `true` when it wrote, `false` when there was no file and no `minimal`.
+ * @throws {CLIError} when the file is unreadable (fail-closed: never rewritten blind).
+ */
+export function writeProvisionTarget(rootDir, target, minimal) {
+    const obj = readStateObject(rootDir);
+    if (obj) {
+        writeStateDocument(rootDir, { ...obj, target });
+        return true;
+    }
+    if (!minimal)
+        return false;
+    const state = {
+        projectName: minimal.projectName,
+        lifecycle: minimal.lifecycle,
+        scope: minimal.scope,
+        target,
+        createdAt: (minimal.now ?? (() => new Date()))().toISOString(),
+    };
+    writeStateDocument(rootDir, state);
+    return true;
+}
 /**
  * Discard the provision state (the `--force` path). Best-effort: a missing file
  * is a no-op, so `--force` is safe to pass on a fresh run.
@@ -192,8 +398,16 @@ export function adoptState(rootDir, partial, options = {}) {
         throw new CLIError(`Ya existe un estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`). ` +
             'Usa `--force` para sobrescribirlo con el resultado del adopt, o bórralo si reutilizas este directorio.');
     }
+    // Last-line guard (`runAdopt` checks first): an unreadable file carries nothing, so the
+    // rewrite would drop its `vault` block — never, not even with `force`.
+    if (isProvisionStateUnreadable(rootDir)) {
+        throw new CLIError(`No puedo leer \`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`: no lo reconstruyo, ni con \`--force\`. ` +
+            `Hazlo así: ${UNREADABLE_STATE_REMEDY}`);
+    }
     const slug = partial.slug ?? ADOPT_UNKNOWN;
     const now = options.now ?? (() => new Date());
+    // VAULT-002: carry the vault link (+ the Resend key id) of the state being overwritten.
+    const carried = readCarriedVaultFields(rootDir);
     const state = {
         lifecycle: 'live',
         slug,
@@ -204,6 +418,7 @@ export function adoptState(rootDir, partial, options = {}) {
         githubRepo: partial.githubRepo ?? ADOPT_UNKNOWN,
         domains: partial.domains ?? { dev: ADOPT_UNKNOWN, prod: ADOPT_UNKNOWN },
         adoptedAt: now().toISOString(),
+        ...carried,
     };
     const dir = path.join(rootDir, PROVISION_DIR);
     mkdirSync(dir, { recursive: true });
@@ -221,6 +436,123 @@ export function adoptState(rootDir, partial, options = {}) {
     }
     return state;
 }
+/**
+ * The `vault` + `resend` blocks of the state file on disk, whatever its shape — so a rewrite of
+ * the file in another shape (`--adopt --force`) keeps them. An unreadable file would carry
+ * nothing, which is why `adoptState` refuses it before calling this.
+ */
+function readCarriedVaultFields(rootDir) {
+    const file = provisionStatePath(rootDir);
+    if (!existsSync(file))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return {};
+    // 🔴 A present-but-malformed `vault` block stops the rewrite: dropping it would turn a vault
+    // repo into a "no vault" one on disk (VaultLinkMalformedError).
+    const vault = vaultBlockOf(parsed);
+    const resend = parsed.resend;
+    const backlog = carriedBacklog(parsed.backlog);
+    const declined = parsed[VAULT_DECLINED_KEY];
+    return {
+        ...(vault ? { vault } : {}),
+        ...(resend && typeof resend.apiKeyId === 'string' ? { resend } : {}),
+        ...(backlog ? { backlog } : {}),
+        ...(isVaultDeclinedMark(declined) ? { vaultDeclined: declined } : {}),
+        ...(isProvisionTarget(parsed.target) ? { target: parsed.target } : {}),
+        ...(isPlainObject(parsed.railway) ? { railway: parsed.railway } : {}),
+    };
+}
+/** A non-null, non-array object. */
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * RWAY-006 — the `railway` block of the state file, in either shape; `null` without a file or a
+ * block. Ids only. The drift (`doctor`/`status`) reads ONLY these ids (never a search by repo).
+ *
+ * @throws {CLIError} when the file is unreadable (the same remedy as every other reader).
+ */
+export function readRailwayBlock(rootDir) {
+    const obj = readStateObject(rootDir);
+    if (!obj || !isPlainObject(obj.railway))
+        return null;
+    return obj.railway;
+}
+/**
+ * RWAY-006 — the Railway `--adopt` over an EXISTING state file: write `target: 'railway'` and the
+ * `railway` block, touching NOTHING else of the file (either shape). The block of the destination
+ * being left (`vercel`, `vercelProjectId`, …) stays exactly as it was (Decision 17). Same atomic
+ * swap as every other writer.
+ *
+ * @throws {CLIError} when there is no file, or it is unreadable (never rewritten blind).
+ */
+export function writeRailwayAdoption(rootDir, railway) {
+    const obj = readStateObject(rootDir);
+    if (!obj) {
+        throw new CLIError(`No hay \`${PROVISION_DIR}/${PROVISION_STATE_FILE}\` sobre el cual registrar el bloque \`railway\`.`);
+    }
+    writeStateDocument(rootDir, { ...obj, target: 'railway', railway });
+}
+/** A persisted `backlog` block narrowed to {@link BacklogState}, else `null` (nothing carried). */
+function carriedBacklog(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const block = value;
+    if (typeof block.projectId !== 'string' || block.projectId.trim() === '')
+        return null;
+    return {
+        projectId: block.projectId,
+        ...(block.keyMinted === true ? { keyMinted: true } : {}),
+    };
+}
+/**
+ * The `resend` block of the state file on disk (either shape), read BEFORE a `--force` discard so
+ * the new run inherits it: without it the id of the project's live Resend key would be lost with
+ * the file, and the key would stay alive in Resend forever. The new run then queues that key in
+ * `pendingRevokeIds` when it mints a replacement, and revokes it once the new one is published.
+ * Best-effort: an unreadable file or a malformed block carries nothing.
+ */
+export function readCarriedResend(rootDir) {
+    const file = provisionStatePath(rootDir);
+    if (!existsSync(file))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const resend = parsed.resend;
+    if (!resend || typeof resend !== 'object')
+        return null;
+    if (typeof resend.apiKeyId !== 'string' || resend.apiKeyId.trim() === '')
+        return null;
+    if (typeof resend.domain !== 'string')
+        return null;
+    const pending = Array.isArray(resend.pendingRevokeIds)
+        ? resend.pendingRevokeIds.filter((id) => typeof id === 'string' && id !== '')
+        : [];
+    return {
+        apiKeyId: resend.apiKeyId,
+        domain: resend.domain,
+        ...(pending.length > 0 ? { pendingRevokeIds: pending } : {}),
+    };
+}
+/**
+ * RWAY-003 — the services that DEPLOY: a run that executes one of them needs a destination
+ * (`--target`, the saved one, or the discovered one). `vault`, `neon` and `backlog` do not.
+ */
+export const DEPLOY_SERVICES = ['github', 'vercel', 'railway', 'dns'];
 /**
  * True when `service`'s create step is already recorded in `state` — the check
  * `--resume` uses to skip a completed step. A `null` state (no prior run) means
@@ -230,6 +562,10 @@ export function isServiceComplete(state, service) {
     if (!state)
         return false;
     switch (service) {
+        case 'vault':
+            // Complete only when the whole alta finished — NOT on the mere presence of the block
+            // (the project id is recorded as soon as the project exists, before members/import).
+            return state.vault?.done === true;
         case 'neon':
             // Neon is complete only when the FINAL step landed (key minted + stored as
             // the GitHub Secret). developBranchId alone is NOT done — the steps after it
@@ -239,25 +575,97 @@ export function isServiceComplete(state, service) {
         case 'vercel':
             // Complete only when the env sync landed — NOT on the mere presence of
             // state.vercel (the github step writes `projectId` before the vercel step
-            // runs, so that alone would wrongly skip the env push).
-            return state.vercel?.envSynced === true;
+            // runs, so that alone would wrongly skip the env push). With a vault (SYNC-001) the
+            // values landing in the vault is not enough: the sync must have delivered them and the
+            // first deployment been triggered (`firstDeployTriggered`), or a timed-out wait would be
+            // skipped by `--resume` and the project would never deploy.
+            return (state.vercel?.envSynced === true &&
+                (state.vault === undefined || state.vercel.firstDeployTriggered === true));
         case 'github':
             // Complete only when the whole step finished — NOT on the mere presence of
             // state.github (its `repo` is recorded at the START of the step, so a step
             // that failed mid-way would be wrongly skipped on resume).
             return state.github?.done === true;
         case 'dns':
-            return state.dns !== undefined;
+            // Complete only when the Resend key reached the deploys too — NOT on the mere presence
+            // of state.dns (a run that attached the domains but could not publish the key records
+            // `resendKeyPending`, and `--resume` must retry that part instead of skipping it).
+            return state.dns !== undefined && state.dns.resendKeyPending !== true;
         case 'backlog':
             // Complete only when the per-project key was minted AND written — NOT on the
             // mere presence of state.backlog (its `projectId` is recorded before the mint,
             // so a run that created the project but failed to mint would be wrongly skipped
             // on resume, and the show-once key would never reach `.env.local`).
             return state.backlog?.keyMinted === true;
+        case 'railway':
+            // Complete once the whole step finished AND no environment's healthcheck is still pending:
+            // a `--resume` over a `pending` one re-enters the step, which then only repeats the probe.
+            return (state.railway?.done === true &&
+                !Object.values(state.railway.healthcheck ?? {}).includes('pending'));
         default:
             return false;
     }
 }
+const RAILWAY_ROLES = ['main', 'develop'];
+/** The Railway ids of a persisted `railway` block (either shape), or `null` without one. */
+function railwayIdsOf(block) {
+    if (block === null || typeof block !== 'object' || Array.isArray(block))
+        return null;
+    const rw = block;
+    const byRole = (value) => {
+        const out = {};
+        if (value === null || typeof value !== 'object')
+            return out;
+        for (const role of RAILWAY_ROLES) {
+            const id = realId(value[role]);
+            if (id)
+                out[role] = id;
+        }
+        return out;
+    };
+    const customDomains = [];
+    const push = (id, label) => {
+        if (id && !customDomains.some((d) => d.id === id))
+            customDomains.push({ id, label });
+    };
+    const kit = byRole(rw.customDomains);
+    for (const role of RAILWAY_ROLES)
+        push(kit[role] ?? null, `dominio del kit en \`${role}\``);
+    push(realId(rw.clientDomainId), 'dominio del cliente en `main`');
+    for (const adopted of Array.isArray(rw.adoptedDomains) ? rw.adoptedDomains : []) {
+        const host = realDomain(adopted?.domain);
+        push(realId(adopted?.id), `\`${host ?? '?'}\` en \`${adopted?.role ?? '?'}\``);
+    }
+    const pending = Array.isArray(rw.syncs?.pending)
+        ? rw.syncs.pending.filter((role) => RAILWAY_ROLES.includes(role))
+        : [];
+    return {
+        projectId: realId(rw.projectId),
+        serviceId: realId(rw.serviceId),
+        environments: byRole(rw.environments),
+        customDomains,
+        syncIds: byRole(rw.syncs?.ids),
+        syncsPending: pending,
+        creatingProjectName: typeof rw.creating?.projectName === 'string' && rw.creating.projectName.trim() !== ''
+            ? rw.creating.projectName.trim()
+            : null,
+    };
+}
+/** The Cloudflare record refs of a persisted `dns` block, well-formed ones only. */
+function cloudflareRecordsOf(dns) {
+    if (dns === null || typeof dns !== 'object')
+        return [];
+    const list = dns.cloudflareRecords;
+    if (!Array.isArray(list))
+        return [];
+    return list.flatMap((r) => {
+        const zoneId = realId(r?.zoneId);
+        const id = realId(r?.id);
+        if (!zoneId || !id || (r.type !== 'CNAME' && r.type !== 'TXT'))
+            return [];
+        return [{ zoneId, id, type: r.type, name: typeof r.name === 'string' ? r.name : '' }];
+    });
+}
 /** Coerce a persisted field to a real id, mapping the `unknown` sentinel + empties to `null`. */
 function realId(value) {
     if (typeof value !== 'string')
@@ -369,20 +777,20 @@ export function readDestroyTarget(rootDir) {
         text = readFileSync(file, 'utf8');
     }
     catch {
-        throw new CLIError(`No se pudo leer el estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`). ` +
-            'Si está dañado, bórralo o reconstrúyelo con `--adopt`.');
+        throw new CLIError(`No se pudo leer el estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`): ` +
+            UNREADABLE_STATE_REMEDY);
     }
     let parsed;
     try {
         parsed = JSON.parse(text);
     }
     catch {
-        throw new CLIError(`El estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`) está corrupto (JSON inválido). ` +
-            'Bórralo o reconstrúyelo con `--adopt`.');
+        throw new CLIError(`El estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`) está corrupto (JSON inválido): ` +
+            UNREADABLE_STATE_REMEDY);
     }
     if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw new CLIError(`El estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`) tiene una estructura inesperada. ` +
-            'Bórralo o reconstrúyelo con `--adopt`.');
+        throw new CLIError(`El estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`) no es un objeto JSON: ` +
+            UNREADABLE_STATE_REMEDY);
     }
     const obj = parsed;
     if (isAdoptedShape(obj)) {
@@ -397,17 +805,28 @@ export function readDestroyTarget(rootDir) {
             neonBranchDevId: realId(adopted.neonBranchDevId),
             vercelProjectId: realId(adopted.vercelProjectId),
             githubRepo: realRepo(adopted.githubRepo),
-            // The adopt backfill (PROV-007) does not reconstruct backlog central — nothing
-            // to tear down from an adopted stack; a normal provision state carries it.
+            // An adopted shape may CARRY a `backlog` block (`adoptState` keeps it for the preflight),
+            // but `--destroy` does not tear it down there — same policy as its `vault` block below.
             backlogProjectId: null,
             domains,
+            // The adopted shape can CARRY a `vault` block (see `adoptState`), but `--destroy` does not
+            // act on it there: an adopted stack is a live repo born before the CLI, and its vault is
+            // left to the adoption's owners (VAULT-004 §4).
+            vaultProjectId: null,
+            // The `resend` block, unlike `vault`/`backlog`, IS acted on in the adopted shape: the key is
+            // the project's own (send-only, limited to its domain), so revoking it touches nothing else,
+            // and dropping its id with the state would leave a live key nobody can name.
+            ...resendIdsOf(adopted.resend),
+            target: isProvisionTarget(obj.target) ? obj.target : null,
+            railway: railwayIdsOf(obj.railway),
+            cloudflareRecords: cloudflareRecordsOf(obj.dns),
         };
     }
     // Step-by-step ProvisionState shape.
     const step = obj;
     if (typeof step.projectName !== 'string' || step.projectName === '') {
         throw new CLIError(`El estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`) no tiene un \`projectName\`/\`slug\` válido. ` +
-            'Bórralo o reconstrúyelo con `--adopt`.');
+            'Reconstrúyelo con `factory provision --adopt --force` (conserva su bloque `vault`); no lo borres: perderías el vínculo con la bóveda.');
     }
     const lifecycle = step.lifecycle === 'ephemeral' ? 'ephemeral' : 'live';
     // The `dns` block now records the interim DEV domain (`{slug}-dev.<org zone>`)
@@ -437,5 +856,218 @@ export function readDestroyTarget(rootDir) {
         githubRepo: realRepo(step.github?.repo),
         backlogProjectId: realId(step.backlog?.projectId),
         domains,
+        vaultProjectId: realId(asVaultState(step.vault)?.projectId),
+        ...resendIdsOf(step.resend),
+        target: isProvisionTarget(obj.target) ? obj.target : null,
+        railway: railwayIdsOf(obj.railway),
+        cloudflareRecords: cloudflareRecordsOf(step.dns),
+    };
+}
+/**
+ * The Resend key ids `--destroy` revokes, read from a persisted `resend` block of EITHER shape:
+ * the current key + the previous ones still pending. A missing or malformed block yields none.
+ */
+function resendIdsOf(block) {
+    if (block === null || typeof block !== 'object' || Array.isArray(block)) {
+        return { resendApiKeyId: null, resendPendingRevokeIds: [] };
+    }
+    const resend = block;
+    return {
+        resendApiKeyId: realId(resend.apiKeyId),
+        resendPendingRevokeIds: (Array.isArray(resend.pendingRevokeIds) ? resend.pendingRevokeIds : [])
+            .map(realId)
+            .filter((id) => id !== null),
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// VAULT-002 — does this repo live in the vault?
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * The remedy for a `.timekast/provision.json` that exists but cannot be read or parsed — the ONE
+ * wording every reader uses. The file is COMMITTED, so git holds the last good copy. NOT
+ * `--adopt`: over a file it cannot read, the adopt carries nothing, and the rebuilt state loses
+ * the `vault` block — the repo would then be treated as one without a vault (`runAdopt` refuses
+ * that case for the same reason).
+ */
+export const UNREADABLE_STATE_REMEDY = `restáuralo desde git (\`git checkout -- ${PROVISION_DIR}/${PROVISION_STATE_FILE}\`) o corrígelo a mano. ` +
+    'No lo reconstruyas con `factory provision --adopt`: sin poder leerlo, el adopt pierde el bloque `vault`.';
+/**
+ * True when `.timekast/provision.json` EXISTS but cannot be read, is not JSON, or is JSON that is
+ * not an object (`null`, an array, a scalar). `--adopt
+ * --force` refuses that case: it cannot carry the `vault` block of a file it cannot parse, so the
+ * rewrite would silently turn a repo that lives in the vault into one that does not.
+ */
+export function isProvisionStateUnreadable(rootDir) {
+    const file = provisionStatePath(rootDir);
+    if (!existsSync(file))
+        return false;
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        // A state is always a JSON object: `null`, an array or a scalar is as unusable as garbage,
+        // and reading it as "no state" would let `--force`/`--no-vault` drop the vault link.
+        return parsed === null || typeof parsed !== 'object' || Array.isArray(parsed);
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Read ONLY the `vault` block of `.timekast/provision.json`, whatever the shape of the rest of
+ * the file (step-by-step or adopted). Returns `null` when there is no state file or it carries NO
+ * `vault` key.
+ *
+ * 🔴 FAIL-CLOSED on a file that exists but cannot be read or parsed, AND on a `vault` block that
+ * is present but malformed (`vault: null` included): this answer decides whether a writer may
+ * touch `.env.local`, and "I could not tell" must never read as "no vault" — that would write
+ * secrets to a file Next.js loads in a repo whose secrets live in the vault.
+ *
+ * @throws {CLIError} when the state file exists but is unreadable or not JSON.
+ * @throws {VaultLinkMalformedError} when the `vault` block is present but malformed.
+ */
+export function readVaultLink(rootDir) {
+    const file = provisionStatePath(rootDir);
+    if (!existsSync(file))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new CLIError(`No pude leer \`${PROVISION_DIR}/${PROVISION_STATE_FILE}\` para saber si este repo vive en la bóveda. ` +
+            `No escribo secretos a ciegas: ${UNREADABLE_STATE_REMEDY}`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        // Not an object → not a state: fail closed like an unparseable file (never "no vault").
+        throw new CLIError(`\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\` no es un objeto JSON. ` +
+            `No escribo secretos a ciegas: ${UNREADABLE_STATE_REMEDY}`);
+    }
+    return vaultBlockOf(parsed);
+}
+/**
+ * The Neon revocations pending in the `vault` block ({@link NeonRevokePending}), or `null` when
+ * there are none — or no block. Same fail-closed reading as {@link readVaultLink}.
+ */
+export function readNeonRevokePending(rootDir) {
+    const link = readVaultLink(rootDir);
+    return link ? asNeonRevokePending(link.neonRevokePending) : null;
+}
+/**
+ * ADOPT-008 — the NARROW writer of {@link NeonRevokePending}: reads `.timekast/provision.json`,
+ * patches ONLY `vault.neonRevokePending` (sets it, or deletes it with `null`) and writes the file
+ * back with every other key — of the block and of the file, in either shape — untouched.
+ *
+ * 🔴 Never `state.vault = buildVaultState(...)` and never a full `writeProvisionState`: an adopted
+ * file holds `vercelProjectId`, `githubRepo` and the domains, and a whole-state write in another
+ * shape destroys them (incident 2026-09-12). That is why it writes even when a `--remint` over the
+ * adopted shape persists nothing else. When `state` is given, its in-memory `vault` block gets the
+ * same field, so a later `writeProvisionState` of the same run keeps it.
+ *
+ * @throws {CLIError} when there is no state file or no `vault` block (nowhere to record it), or
+ *   the file is unreadable. {@link VaultLinkMalformedError} on a malformed block.
+ */
+export function writeNeonRevokePending(rootDir, pending, state) {
+    const file = provisionStatePath(rootDir);
+    if (!existsSync(file)) {
+        throw new CLIError(`No hay \`${PROVISION_DIR}/${PROVISION_STATE_FILE}\` donde registrar las keys de Neon por revocar.`);
+    }
+    let raw;
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            throw new Error();
+        raw = parsed;
+    }
+    catch {
+        throw new CLIError(`No pude leer \`${PROVISION_DIR}/${PROVISION_STATE_FILE}\` para registrar las keys de Neon por revocar: ` +
+            UNREADABLE_STATE_REMEDY);
+    }
+    const block = vaultBlockOf(raw);
+    if (!block) {
+        throw new CLIError(`\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\` no tiene bloque \`vault\`: no hay dónde registrar las keys de Neon por revocar.`);
+    }
+    const target = raw.vault;
+    if (pending)
+        target[NEON_REVOKE_PENDING_KEY] = pending;
+    else
+        delete target[NEON_REVOKE_PENDING_KEY];
+    const dir = path.join(rootDir, PROVISION_DIR);
+    const tmp = path.join(dir, `.${PROVISION_STATE_FILE}.tmp`);
+    try {
+        writeFileSync(tmp, `${JSON.stringify(raw, null, 2)}\n`, 'utf8');
+        renameSync(tmp, file);
+    }
+    catch (error) {
+        rmSync(tmp, { force: true });
+        throw new CLIError(`No se pudo escribir \`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`: ` +
+            `${error?.message ?? 'error desconocido'}.`);
+    }
+    if (state?.vault) {
+        if (pending)
+            state.vault.neonRevokePending = pending;
+        else
+            delete state.vault.neonRevokePending;
+    }
+}
+/**
+ * The union of two pending records: every key id of both (the previous ones first, no duplicates),
+ * with the org and the delivery marker of `next` — the current run's. A pending id is never lost by
+ * a later writer: a key that stays alive with nobody to revoke it is the damage this prevents.
+ */
+export function mergeNeonRevokePending(previous, next) {
+    const prev = asNeonRevokePending(previous);
+    return {
+        orgId: next.orgId,
+        keyIds: [...new Set([...(prev?.keyIds ?? []), ...next.keyIds])],
+        syncJobsAtWrite: next.syncJobsAtWrite,
     };
 }
+/**
+ * ADD a run's pending revocations to what the file (and the run's in-memory state) already holds —
+ * {@link mergeNeonRevokePending} through the narrow {@link writeNeonRevokePending}. Every writer of
+ * NEW pending ids goes through here; only a settle, which shrinks the list, writes it directly.
+ */
+export function addNeonRevokePending(rootDir, pending, state) {
+    let merged = mergeNeonRevokePending(readNeonRevokePending(rootDir), pending);
+    if (state?.vault?.neonRevokePending) {
+        merged = mergeNeonRevokePending(state.vault.neonRevokePending, merged);
+    }
+    writeNeonRevokePending(rootDir, merged, state);
+    return merged;
+}
+/** True when the repo is linked to a vault project (see {@link readVaultLink}). */
+export function hasVaultLink(rootDir) {
+    return readVaultLink(rootDir) !== null;
+}
+/** Narrow a persisted {@link VAULT_DECLINED_KEY} value to a {@link VaultDeclinedMark}. */
+function isVaultDeclinedMark(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        typeof value.at === 'string');
+}
+/**
+ * Whether `.timekast/provision.json` records that the repo DECLINED the vault (ADOPT-004), in
+ * either shape of the file. `false` without a file or without the key. A key that is present
+ * counts as declined whatever its value: the mark only ever makes `doctor` stop suggesting
+ * `vault adopt`, so reading a damaged one as "declined" costs a suggestion, never a secret.
+ *
+ * @throws {CLIError} when the file exists but is unreadable, not JSON or not an object — the same
+ *   fail-closed answer {@link readVaultLink} gives ("I could not tell" is never "not declined").
+ */
+export function readVaultDeclined(rootDir) {
+    const file = provisionStatePath(rootDir);
+    if (!existsSync(file))
+        return false;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new CLIError(`No pude leer \`${PROVISION_DIR}/${PROVISION_STATE_FILE}\` para saber si este repo declinó la bóveda: ` +
+            UNREADABLE_STATE_REMEDY);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new CLIError(`\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\` no es un objeto JSON: ${UNREADABLE_STATE_REMEDY}`);
+    }
+    return Object.prototype.hasOwnProperty.call(parsed, VAULT_DECLINED_KEY);
+}