@timekast/factory 1.28.1 → 2.0.0

package/dist/lib/claude-md.js

@@ -0,0 +1,320 @@
+/**
+ * `CLAUDE.md` retrofit — the kit-managed rules-INDEX import line (PROJ-006).
+ *
+ * The kit's `CLAUDE.md` moved from six explicit `@.claude/rules/*.md` imports to a
+ * single `@.claude/rules/INDEX.md` line that fans out to all of them. A derivative
+ * whose `CLAUDE.md` is dev-owned (it is: `diffLockfiles` routes it to `ignoreLocal`
+ * the moment it is edited) would never receive that line, so every rule the kit adds
+ * from now on lands on disk dead.
+ *
+ * This module is the WHOLE retrofit: classification (A/B/C), the idempotent
+ * insertion, and the closing report. `update.ts` only wires it into the flow.
+ *
+ * 🔴 ZERO MECHANICAL INTRUSION is the guarantee. The retrofit only ever ADDS one
+ * line, and only when it is absent. It never deletes, reorders or rewrites anything
+ * the dev wrote — the insertion is a string splice into the original bytes, so line
+ * endings, trailing whitespace and every other byte outside the inserted line survive
+ * untouched.
+ *
+ * The three cases (fixed in CP-A, discriminated off the LOCKFILE so `--verify` can
+ * produce the census with no network and no incoming manifest):
+ *
+ *   A — virgin:  the on-disk hash equals the hash the lockfile recorded → the dev
+ *                never touched it → the normal `overwriteSilent` branch propagates
+ *                the kit's version, which already carries the line. Untouched here.
+ *   B — edited outside the kit's zone: it differs from the lockfile, but it still
+ *                imports EVERY kit rule → the import block is intact → insert the
+ *                INDEX line if missing.
+ *   C — edited INSIDE the kit's zone: a kit rule is missing from the imports (the dev
+ *                took one out by hand) → do NOT touch. Report for manual review.
+ *                Deliberately conservative: guessing what the dev meant is exactly
+ *                the fragile heuristic the plan avoids.
+ */
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { CLAUDE_MD_FILE } from './constants.js';
+import { normalizeThenHash } from './lockfile.js';
+/** Repo-relative directory holding the kit's always-on rules. */
+export const RULES_DIR = '.claude/rules';
+/** Repo-relative path of the kit-managed rules index (full profile only). */
+export const RULES_INDEX_PATH = `${RULES_DIR}/INDEX.md`;
+/** The single line this retrofit owns. */
+export const RULES_INDEX_IMPORT = `@${RULES_INDEX_PATH}`;
+/**
+ * A flat kit rule file (`.claude/rules/<name>.md`). Nested paths are out: the
+ * always-on set the runtime auto-loads is flat, and a `methodology/` subdir under
+ * `rules/` would otherwise read as a rule.
+ */
+export const KIT_RULE_PATH_RE = /^\.claude\/rules\/[^/]+\.md$/;
+/** A bare `@.claude/rules/<name>.md` directive line (used to find the import block). */
+const RULE_IMPORT_LINE_RE = /^@\.claude\/rules\/[^/\s]+\.md$/;
+/**
+ * First-level markdown heading (`# Title`) — the insertion anchor of last resort.
+ * A leading BOM is tolerated: an editor that writes UTF-8-with-BOM puts ``
+ * before the `#` of line 1, and without this the file's own title would not match,
+ * pushing the insertion all the way to the end of the file for no good reason.
+ */
+const H1_RE = /^?#\s+\S/;
+/** A markdown fence delimiter line: three or more backticks or tildes, plus an optional info string. */
+const FENCE_RE = /^(`{3,}|~{3,})(.*)$/;
+/**
+ * The paths a markdown file `@import`s: a line whose trimmed text is `@<path>`.
+ * Same strictness as `doctor`'s original reader (which now calls THIS function, so
+ * the two can no longer drift): a prose mention is not a bare directive line and
+ * does not count.
+ *
+ * 🔴 Lines inside a fenced code block are SKIPPED. The kit's own docs show import
+ * lines inside ``` samples ("agrega `@.claude/rules/INDEX.md` así:"), and counting
+ * those would make a file that only DEMONSTRATES an import read as if it performed
+ * it — the retrofit would then skip the insertion, and `doctor` would report a rule
+ * as covered when the runtime never loads it. Both fence characters are handled,
+ * with or without an info string; a closing fence is one of the same character and
+ * at least as long, which is what keeps a nested ```` ```` ```` sample from closing
+ * its own container early.
+ */
+export function bareImportPaths(text) {
+    const lines = text.split('\n');
+    const fenced = markFenced(lines);
+    const out = [];
+    lines.forEach((raw, i) => {
+        if (fenced[i])
+            return;
+        const line = raw.trim();
+        if (line.startsWith('@'))
+            out.push(line.slice(1).trim());
+    });
+    return out;
+}
+/**
+ * Per-line "is this inside (or is) a fenced code block?" flags. Fence delimiter lines
+ * are flagged too — they are never directive lines, so flagging them costs nothing and
+ * keeps the scan a single pass. Shared by the reader above and by the insertion anchor
+ * below, so the two can never disagree about where the code samples are.
+ */
+function markFenced(lines) {
+    const flags = [];
+    let fence = null;
+    for (const raw of lines) {
+        const match = FENCE_RE.exec(raw.trim());
+        if (match) {
+            const char = match[1][0];
+            const length = match[1].length;
+            if (fence === null)
+                fence = { char, length };
+            // A closing fence: same character, at least as long, and no info string.
+            else if (char === fence.char && length >= fence.length && match[2].trim() === '')
+                fence = null;
+            flags.push(true);
+            continue;
+        }
+        flags.push(fence !== null);
+    }
+    return flags;
+}
+/**
+ * Resolve a path found inside an `@import` RELATIVE TO THE FILE THAT CONTAINS IT —
+ * the documented Claude Code rule for memory imports. It is the reason `INDEX.md`
+ * lists `@CORE.md` and not `@.claude/rules/CORE.md`: the latter would resolve to
+ * `.claude/rules/.claude/rules/CORE.md` and fail silently. Absolute and `~` paths
+ * are left verbatim (they are not repo-relative and nothing here can normalize them).
+ */
+export function resolveImportFrom(containerPath, imported) {
+    if (imported.startsWith('/') || imported.startsWith('~'))
+        return imported;
+    return path.posix.normalize(path.posix.join(path.posix.dirname(containerPath), imported));
+}
+/** The kit's always-on rules as recorded in a lockfile — the INDEX itself excluded. */
+export function kitRulePaths(lock) {
+    return lock.files
+        .map((f) => f.path)
+        .filter((p) => KIT_RULE_PATH_RE.test(p) && p !== RULES_INDEX_PATH);
+}
+/** True when the text already carries the bare INDEX import directive. */
+export function hasIndexImport(text) {
+    return bareImportPaths(text).includes(RULES_INDEX_PATH);
+}
+/**
+ * Kit rules the text does not cover. The INDEX line counts as covering ALL of them:
+ * that is literally what it does at runtime (one hop, it imports every rule), and
+ * without this an already-retrofitted `CLAUDE.md` — which imports the INDEX and
+ * nothing else — would classify as C and be reported as needing manual review on
+ * every later update.
+ */
+export function uncoveredKitRules(text, kitRules) {
+    if (hasIndexImport(text))
+        return [];
+    const imported = new Set(bareImportPaths(text));
+    return kitRules.filter((p) => !imported.has(p));
+}
+/** Scan `content` into lines, preserving each line's offsets and terminator. */
+function scanLines(content) {
+    const lines = [];
+    let start = 0;
+    for (;;) {
+        const nl = content.indexOf('\n', start);
+        if (nl === -1) {
+            lines.push({ start, end: content.length, text: content.slice(start), eol: '' });
+            return lines;
+        }
+        const raw = content.slice(start, nl);
+        const crlf = raw.endsWith('\r');
+        lines.push({
+            start,
+            end: nl + 1,
+            text: crlf ? raw.slice(0, -1) : raw,
+            eol: crlf ? '\r\n' : '\n',
+        });
+        start = nl + 1;
+    }
+}
+/**
+ * Add the INDEX import line, preserving every other byte. IDEMPOTENT: a text that
+ * already has the line is returned unchanged (identity, not a rewrite).
+ *
+ * Anchor, in order:
+ *   1. Immediately BEFORE the first `@.claude/rules/*.md` line — so the new import
+ *      lands inside the existing import block instead of orphaned at the bottom.
+ *   2. Otherwise right after the first `# H1` (the file's title).
+ *   3. Otherwise appended at the end.
+ *
+ * The inserted line borrows the terminator of the line it sits next to, so a CRLF
+ * file stays CRLF and a mixed file is not normalized.
+ */
+export function insertIndexImport(content) {
+    if (hasIndexImport(content))
+        return content;
+    const lines = scanLines(content);
+    const fallbackEol = lines.some((l) => l.eol === '\r\n') ? '\r\n' : '\n';
+    // Fence-aware like the reader: a rule import that only appears inside a ``` sample is
+    // not an import block, and splicing the new line in there would put a live directive
+    // inside a code block — invisible to the runtime and confusing in the doc.
+    const fenced = markFenced(lines.map((l) => l.text));
+    const firstRuleImport = lines.find((l, i) => !fenced[i] && RULE_IMPORT_LINE_RE.test(l.text.trim()));
+    if (firstRuleImport) {
+        const eol = firstRuleImport.eol || fallbackEol;
+        return (content.slice(0, firstRuleImport.start) +
+            RULES_INDEX_IMPORT +
+            eol +
+            content.slice(firstRuleImport.start));
+    }
+    const h1 = lines.find((l, i) => !fenced[i] && H1_RE.test(l.text));
+    if (h1) {
+        const at = h1.end;
+        const rest = content.slice(at);
+        // A blank line after the heading, and another before whatever followed — unless
+        // it already starts with one (never stack two blank lines).
+        const trailing = rest.length === 0 || rest.startsWith('\n') || rest.startsWith('\r') ? '' : fallbackEol;
+        return content.slice(0, at) + fallbackEol + RULES_INDEX_IMPORT + fallbackEol + trailing + rest;
+    }
+    const separator = content.length === 0 || content.endsWith('\n') ? '' : fallbackEol;
+    return content + separator + RULES_INDEX_IMPORT + fallbackEol;
+}
+/**
+ * Classify a `CLAUDE.md` — pure. `content: undefined` means "not on disk".
+ * `registeredHash` is the hash the lockfile recorded for it (absent on a lockfile
+ * that predates tracking it → it cannot be proven virgin, so it is treated as edited).
+ */
+export function classifyClaudeMd(opts) {
+    const { content, registeredHash, kitRules, profile } = opts;
+    if (content === undefined)
+        return { case: 'absent', action: 'none', uncovered: [] };
+    if (registeredHash !== undefined && normalizeThenHash(content) === registeredHash) {
+        // Virgin: the kit's own version is on disk. The `overwriteSilent` branch already
+        // propagates the new one (which carries the line) — nothing to retrofit here.
+        return { case: 'A', action: 'none', uncovered: [] };
+    }
+    const uncovered = uncoveredKitRules(content, kitRules);
+    if (uncovered.length > 0)
+        return { case: 'C', action: 'none', uncovered };
+    if (hasIndexImport(content))
+        return { case: 'B', action: 'already-present', uncovered: [] };
+    // The `core` profile does not ship `.claude/rules/INDEX.md` at all (it resolves its
+    // rules with explicit imports, and the INDEX pulls in `SK.md`, which `core` excludes
+    // on purpose). Inserting the line there would point at a file that never arrives.
+    if (profile === 'core')
+        return { case: 'B', action: 'skip-core', uncovered: [] };
+    return { case: 'B', action: 'insert', uncovered: [] };
+}
+/**
+ * Classify the `CLAUDE.md` of a repo on disk against its INSTALLED lockfile.
+ *
+ * 🔴 Must run BEFORE `applyPlan`. Case A is "disk == lockfile", and once the swap has
+ * written the incoming version that comparison is destroyed — every repo would read
+ * as edited.
+ */
+export function assessClaudeMd(rootDir, lock) {
+    const abs = path.join(rootDir, CLAUDE_MD_FILE);
+    const present = existsSync(abs) && statSync(abs).isFile();
+    return classifyClaudeMd({
+        content: present ? readFileSync(abs, 'utf8') : undefined,
+        registeredHash: lock.files.find((f) => f.path === CLAUDE_MD_FILE)?.hash,
+        kitRules: kitRulePaths(lock),
+        profile: lock.profile,
+    });
+}
+/**
+ * Perform the retrofit decided by {@link assessClaudeMd}. Returns true only when a
+ * line was actually written. Any other action is a no-op by construction.
+ *
+ * Best-effort like the rest of the post-apply maintenance: the brain is already
+ * installed and the lockfile already written, so a write failure warns and reports
+ * instead of failing an update that succeeded.
+ */
+export function applyClaudeMdRetrofit(rootDir, assessment) {
+    if (assessment.action !== 'insert')
+        return false;
+    const abs = path.join(rootDir, CLAUDE_MD_FILE);
+    try {
+        const before = readFileSync(abs, 'utf8');
+        const after = insertIndexImport(before);
+        if (after === before)
+            return false; // already there (idempotent re-entry)
+        writeFileSync(abs, after, 'utf8');
+        return true;
+    }
+    catch {
+        console.warn('Aviso: no se pudo agregar `@.claude/rules/INDEX.md` a tu `CLAUDE.md`; el cerebro se instaló igual. ' +
+            'Agrégala a mano para que las rules del kit se carguen.');
+        return false;
+    }
+}
+/**
+ * Name the case the repo's `CLAUDE.md` fell into — same closing-summary style with
+ * which the update already names the `package.json` aliases it put back or retired.
+ * `mode: 'preview'` is the `--verify` census (nothing was written).
+ */
+export function reportClaudeMd(assessment, mode, inserted = true) {
+    const { case: kind, action, uncovered } = assessment;
+    if (kind === 'absent') {
+        console.log(`\n\`${CLAUDE_MD_FILE}\`: no está en el disco. El update instala el del Factory (ya trae \`${RULES_INDEX_IMPORT}\`).`);
+        return;
+    }
+    if (kind === 'A') {
+        console.log(`\n\`${CLAUDE_MD_FILE}\` (caso A — sin ediciones tuyas): ${mode === 'applied' ? 'se actualizó' : 'se actualizaría'} con la versión del Factory, como siempre.`);
+        return;
+    }
+    if (kind === 'C') {
+        console.log(`\n\`${CLAUDE_MD_FILE}\` (caso C — necesita revisión manual): lo editaste y le faltan rules del kit ` +
+            `en los imports: ${uncovered.join(', ')}.`);
+        console.log(`  No se tocó nada. Agrega \`${RULES_INDEX_IMPORT}\` a mano (importa todas) o repón los imports que falten.`);
+        return;
+    }
+    // Case B — edited outside the kit's zone.
+    if (action === 'already-present') {
+        console.log(`\n\`${CLAUDE_MD_FILE}\` (caso B — lo editaste): ya importa \`${RULES_INDEX_IMPORT}\`; no se tocó.`);
+        return;
+    }
+    if (action === 'skip-core') {
+        console.log(`\n\`${CLAUDE_MD_FILE}\` (caso B — lo editaste): el perfil \`core\` no incluye \`${RULES_INDEX_PATH}\`, ` +
+            'así que no se agregó ninguna línea; no se tocó.');
+        return;
+    }
+    if (mode === 'preview') {
+        console.log(`\n\`${CLAUDE_MD_FILE}\` (caso B — lo editaste): le falta \`${RULES_INDEX_IMPORT}\`. ` +
+            'Un `factory update` la agrega sin tocar el resto (no se modificó nada ahora).');
+        return;
+    }
+    console.log(inserted
+        ? `\n\`${CLAUDE_MD_FILE}\` (caso B — lo editaste): se le agregó la línea \`${RULES_INDEX_IMPORT}\`; el resto quedó igual, byte a byte.`
+        : `\n\`${CLAUDE_MD_FILE}\` (caso B — lo editaste): no se pudo agregar \`${RULES_INDEX_IMPORT}\`; agrégala a mano.`);
+}

package/dist/lib/cloudflare-api.js

@@ -5,9 +5,15 @@
  * `vercel-env.ts` (`Authorization: Bearer ${token}` + a single central URL
  * builder + an injectable `fetchImpl` seam). Its scope is DNS-ONLY: it resolves
  * the org zone id, looks up an existing CNAME, creates one
- * (`proxied: false` so Vercel's own TLS terminates the domain), and PATCHes an
+ * (`proxied: false` so the hosting's own TLS terminates the domain), and PATCHes an
  * existing record that was manually left `proxied: true` back to `false`.
  *
+ * The CNAME destination is a PARAMETER (RWAY-005): Vercel's fixed
+ * {@link CNAME_VERCEL_TARGET}, or the `requiredValue` Railway returns for each
+ * domain. 🔴 A record that already exists pointing ANYWHERE ELSE stops with a
+ * {@link DnsRecordConflictError} naming both destinations — it is never rewritten
+ * (Decision 19: moving production traffic is the person's call, not the CLI's).
+ *
  * 🔴 Scope contract (issue §4 + the frozen plan): the token handed in here is the
  * shared org Cloudflare token from the rail, minted SCOPED to the org zones with
  * DNS-edit only — never an account-wide token (a DNS-write leak over an org zone could
@@ -23,8 +29,9 @@
  *     path is create-or-PATCH; a record is never removed to "fix" a failed call
  *     (issue §8). The ONE deletion shipped here ({@link deleteDnsRecord},
  *     BOOT-007) is DELIBERATE cleanup inside a flow a human already confirmed
- *     (retiring the interim domain after the client domain went live) — it is
- *     never an automatic recovery move.
+ *     (retiring the interim domain after the client domain went live, or a
+ *     `--destroy` — which first re-reads the record with {@link getDnsRecord}) —
+ *     it is never an automatic recovery move.
  *   - Read or log a token value. The token arrives as an argument and is handed
  *     straight to the `Authorization` header; it never reaches stdout.
  *
@@ -101,6 +108,50 @@ export function existingProvisionDomains(slug, dns) {
 }
 /** Timeout (ms) for every Cloudflare REST call — a dead network must not hang provision. */
 const CLOUDFLARE_API_TIMEOUT_MS = 30_000;
+/**
+ * The test-isolation marker the CLI's Vitest setup installs on `globalThis`
+ * (`cli/tests/setup/isolate-home-path.ts`) — the SAME registry symbol as `vault-api.ts`'s
+ * `VAULT_TEST_ISOLATION_KEY`, which the Railway client reads too. Resolved through
+ * `Symbol.for` instead of imported: `provision-state.ts` imports this module and must stay free
+ * of external deps (the root suite typechecks it without `cli/`'s `node_modules`), and
+ * `vault-api.ts` pulls them in. A marker, not `process.env.VITEST`: a CLI a test spawns as a
+ * subprocess inherits the env var and would turn a real run into a refusal.
+ */
+const TEST_ISOLATION_KEY = Symbol.for('@timekast/factory:vault.test-isolation');
+/** Under the CLI's Vitest setup without an injected `fetchImpl`: refuses before any request. */
+export class CloudflareSeamMissingError extends CLIError {
+    constructor() {
+        super('cloudflare-api: falta el seam `fetchImpl` bajo Vitest. Un test NUNCA habla con Cloudflare ' +
+            'real: pasa `{ fetchImpl }` en los deps (tests/unit/provision-railway-dns.test.ts tiene el patrón).');
+        this.name = 'CloudflareSeamMissingError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * A record that already exists with ANOTHER content than the one expected (RWAY-005, Decision
+ * 19). The CLI stops naming the record, what it points at now and what it should point at; it
+ * never rewrites it, because that would move live traffic (typically: a repo that moved from
+ * Vercel to Railway and still has its CNAME at `cname.vercel-dns.com`).
+ */
+export class DnsRecordConflictError extends CLIError {
+    recordType;
+    recordName;
+    current;
+    expected;
+    constructor(recordType, recordName, current, expected) {
+        super(`El registro ${recordType} \`${recordName}\` ya existe en Cloudflare y apunta a \`${current}\`, ` +
+            `no a \`${expected}\`.\n` +
+            'No lo reescribo: cambiarlo movería el tráfico que hoy sirve ese registro, y eso lo decides tú. ' +
+            `Si el destino correcto es \`${expected}\`, edita ese registro en Cloudflare (o bórralo) y ` +
+            'reintenta con `--resume`. No modifiqué ningún registro.');
+        this.name = 'DnsRecordConflictError';
+        this.recordType = recordType;
+        this.recordName = recordName;
+        this.current = current;
+        this.expected = expected;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
 /** A non-2xx (or `success: false`) response from the Cloudflare REST API. */
 export class CloudflareApiError extends Error {
     status;
@@ -145,6 +196,10 @@ export function cloudflareUrl(pathname, query = {}) {
  * permission/validation failures, so the HTTP status alone is not enough).
  */
 async function cloudflareApi(method, pathname, token, deps, body, query) {
+    if (!deps.fetchImpl &&
+        globalThis[TEST_ISOLATION_KEY] !== undefined) {
+        throw new CloudflareSeamMissingError();
+    }
     const fetchImpl = deps.fetchImpl ?? fetch;
     const url = cloudflareUrl(pathname, query);
     const init = {
@@ -266,16 +321,27 @@ export function zoneCandidatesOf(domain) {
  * @throws {CLIError} when NO candidate is visible to this token.
  */
 export async function resolveZoneIdForDomain(domain, token, deps = {}) {
+    return (await resolveZoneForDomain(domain, token, deps)).id;
+}
+/**
+ * {@link resolveZoneIdForDomain}, returning the zone's NAME too (RWAY-005): a record whose host
+ * a provider hands RELATIVE to the zone (Railway's `verificationDnsHost`) is written absolute
+ * with the zone that really contains the domain ({@link absoluteRecordName}) — never with a
+ * guessed apex nor a literal.
+ */
+export async function resolveZoneForDomain(domain, token, deps = {}) {
     const candidates = zoneCandidatesOf(domain);
     for (const candidate of candidates) {
         try {
-            return await resolveZoneIdForName(candidate, token, deps);
+            return { id: await resolveZoneIdForName(candidate, token, deps), name: candidate };
         }
         catch (error) {
             // Only "this zone is not visible" is a reason to try the next candidate.
-            // An API-level failure (403 out-of-scope, 5xx) propagates untouched.
-            if (error instanceof CloudflareApiError)
+            // An API-level failure (403 out-of-scope, 5xx) propagates untouched, and so does a
+            // missing test seam (it is not "zone not found").
+            if (error instanceof CloudflareApiError || error instanceof CloudflareSeamMissingError) {
                 throw error;
+            }
         }
     }
     throw new CLIError(`No se encontró en Cloudflare ninguna zona que contenga \`${domain}\` con el token usado.\n` +
@@ -283,6 +349,22 @@ export async function resolveZoneIdForDomain(domain, token, deps = {}) {
         'Verifica que el token esté scopeado a la zona (DNS-edit) y reintenta con `--resume`; ' +
         'si usas `--dns=cliente-cf`, confirma que la API key del cliente cubre esa zona.');
 }
+/**
+ * The ABSOLUTE record name for a host a provider gives RELATIVE to `zoneName` (RWAY-005 §8):
+ * `_railway-verify.mi-app` in `timekast.com` → `_railway-verify.mi-app.timekast.com`. A host
+ * that already ends in the zone (or is `@`/empty, the apex) is not suffixed again — written
+ * as-is, Cloudflare would create it under the wrong name or duplicate the zone.
+ */
+export function absoluteRecordName(host, zoneName) {
+    const zone = zoneName.replace(/\.$/, '').toLowerCase();
+    const bare = host.trim().replace(/\.$/, '');
+    if (bare === '' || bare === '@')
+        return zone;
+    const lower = bare.toLowerCase();
+    if (lower === zone || lower.endsWith(`.${zone}`))
+        return bare;
+    return `${bare}.${zone}`;
+}
 /**
  * Find an existing CNAME record for `name` in the zone (issue §8 idempotency).
  * Returns the record when present (so the caller can detect a `proxied: true`
@@ -298,67 +380,161 @@ export async function findCnameRecord(zoneId, name, token, deps = {}) {
     return (data.result ?? []).find((r) => r.name === name && r.type === 'CNAME') ?? null;
 }
 /**
- * Create a CNAME record pointing `name` → {@link CNAME_VERCEL_TARGET} with
- * `proxied: false` and `ttl: 1` (auto) — `POST /zones/{id}/dns_records` (issue §4).
- * `proxied: false` is non-negotiable: a proxied record would terminate TLS at
- * Cloudflare instead of letting Vercel issue+serve the cert for the domain.
+ * Create a CNAME record pointing `name` → `target` with `proxied: false` and `ttl: 1` (auto) —
+ * `POST /zones/{id}/dns_records` (issue §4). `target` is the destination of the repo:
+ * {@link CNAME_VERCEL_TARGET} for Vercel, the domain's `requiredValue` for Railway (RWAY-005).
+ * `proxied: false` is non-negotiable: a proxied record would terminate TLS at Cloudflare instead
+ * of letting the hosting issue+serve the cert for the domain.
  *
+ * @returns the id Cloudflare gave the record (`null` if the answer did not carry one).
  * @throws {CloudflareApiError} on any non-2xx / `success: false`.
  */
-export async function createCnameRecord(zoneId, name, token, deps = {}) {
-    await cloudflareApi('POST', `/zones/${encodeURIComponent(zoneId)}/dns_records`, token, deps, {
+export async function createCnameRecord(zoneId, name, target, token, deps = {}) {
+    const data = (await cloudflareApi('POST', `/zones/${encodeURIComponent(zoneId)}/dns_records`, token, deps, {
         type: 'CNAME',
         name,
-        content: CNAME_VERCEL_TARGET,
+        content: target,
         proxied: false,
         ttl: 1,
-    });
+    }));
+    return typeof data.result?.id === 'string' ? data.result.id : null;
 }
 /**
  * PATCH an existing CNAME record to `proxied: false` — `PATCH
- * /zones/{id}/dns_records/{recordId}` (issue §8). Used when a record was left
- * `proxied: true` by a manual edit: we flip the proxy flag in place. We NEVER
- * delete the record to "fix" it (a destructive change requires confirmation).
+ * /zones/{id}/dns_records/{recordId}` (issue §8). Used when a record was left `proxied: true`
+ * by a manual edit: we flip the proxy flag in place. `target` is sent as the content and MUST be
+ * the content the record already has — {@link ensureCnameRecord} only calls this after checking
+ * it (a record pointing elsewhere stops instead: Decision 19). We NEVER delete the record to
+ * "fix" it (a destructive change requires confirmation).
  *
  * @throws {CloudflareApiError} on any non-2xx / `success: false`.
  */
-export async function unproxyCnameRecord(zoneId, recordId, name, token, deps = {}) {
+export async function unproxyCnameRecord(zoneId, recordId, name, target, token, deps = {}) {
     await cloudflareApi('PATCH', `/zones/${encodeURIComponent(zoneId)}/dns_records/${encodeURIComponent(recordId)}`, token, deps, {
         type: 'CNAME',
         name,
-        content: CNAME_VERCEL_TARGET,
+        content: target,
         proxied: false,
     });
 }
+/** A CNAME destination normalized for comparison: no trailing dot, case-insensitive. */
+function normalizeHostContent(value) {
+    return value.trim().replace(/\.$/, '').toLowerCase();
+}
 /**
- * Idempotently ensure a `proxied: false` CNAME for `name` exists in the zone
- * (issue §4 + §8). Returns the outcome so the caller can narrate it (no-echo —
- * a domain name is not a secret, but the token never crosses this boundary):
- *   - `created`   — no record existed → POSTed a fresh `proxied: false` CNAME
- *   - `unproxied` — a `proxied: true` record existed → PATCHed it to `false`
- *   - `unchanged` — a `proxied: false` record already existed → nothing to do
- *
- * @throws {CloudflareApiError} on any non-2xx / `success: false` (caller maps it).
+ * The shared core of {@link ensureCnameRecord} and {@link ensureTxtRecord} (RWAY-005): look the
+ * record up by type + name and compare its CONTENT with the expected one.
+ *   - absent → POST (`created`);
+ *   - same content, `proxied: true` → PATCH the proxy off, content unchanged (`unproxied`);
+ *   - same content, `proxied: false` → nothing (`unchanged`);
+ *   - 🔴 other content (proxied or not) → {@link DnsRecordConflictError}, with NO PATCH and NO
+ *     DELETE (Decision 19).
+ * Returns the record id too, so the caller can record it in the state (ids, never values).
  */
-export async function ensureCnameRecord(zoneId, name, token, deps = {}) {
-    const existing = await findCnameRecord(zoneId, name, token, deps);
+export async function ensureUnproxiedRecord(zoneId, type, name, content, token, deps = {}) {
+    const existing = type === 'CNAME'
+        ? await findCnameRecord(zoneId, name, token, deps)
+        : await findDnsRecord(zoneId, 'TXT', name, token, deps);
     if (!existing) {
-        await createCnameRecord(zoneId, name, token, deps);
-        return 'created';
+        const id = type === 'CNAME'
+            ? await createCnameRecord(zoneId, name, content, token, deps)
+            : await createTxtRecord(zoneId, name, content, token, deps);
+        return { outcome: 'created', id };
+    }
+    const same = type === 'CNAME'
+        ? normalizeHostContent(existing.content) === normalizeHostContent(content)
+        : normalizeRecordContent(existing.content) === normalizeRecordContent(content);
+    if (!same) {
+        throw new DnsRecordConflictError(type, name, type === 'CNAME' ? existing.content : normalizeRecordContent(existing.content), content);
     }
     if (existing.proxied) {
-        // A manually-edited record left proxied:true → flip it (never delete — §8).
-        await unproxyCnameRecord(zoneId, existing.id, name, token, deps);
-        return 'unproxied';
+        // A manually-edited record left proxied:true → flip it, content untouched (never delete — §8).
+        if (type === 'CNAME') {
+            await unproxyCnameRecord(zoneId, existing.id, name, content, token, deps);
+        }
+        else {
+            await cloudflareApi('PATCH', `/zones/${encodeURIComponent(zoneId)}/dns_records/${encodeURIComponent(existing.id)}`, token, deps, { type, name, content, proxied: false });
+        }
+        return { outcome: 'unproxied', id: existing.id };
+    }
+    return { outcome: 'unchanged', id: existing.id };
+}
+/**
+ * Idempotently ensure a `proxied: false` CNAME `name → target` exists in the zone (issue §4 + §8,
+ * RWAY-005). Returns the outcome so the caller can narrate it (no-echo — a domain name is not a
+ * secret, but the token never crosses this boundary):
+ *   - `created`   — no record existed → POSTed a fresh `proxied: false` CNAME to `target`
+ *   - `unproxied` — a `proxied: true` record to `target` existed → PATCHed it to `false`
+ *   - `unchanged` — a `proxied: false` record to `target` already existed → nothing to do
+ *
+ * 🔴 A record pointing ANYWHERE ELSE (proxied or not) throws {@link DnsRecordConflictError}
+ * naming both destinations — never `unchanged`, never rewritten (Decision 19).
+ *
+ * @throws {CloudflareApiError} on any non-2xx / `success: false` (caller maps it).
+ */
+export async function ensureCnameRecord(zoneId, name, target, token, deps = {}) {
+    return (await ensureUnproxiedRecord(zoneId, 'CNAME', name, target, token, deps)).outcome;
+}
+/**
+ * Create a TXT record — `POST /zones/{id}/dns_records` (RWAY-005), for a provider's domain
+ * verification. A TXT cannot be proxied, so no `proxied` flag is sent (the same call shape the
+ * Resend records of {@link createDnsRecord} already use against the live API).
+ *
+ * @returns the id Cloudflare gave the record (`null` if the answer did not carry one).
+ * @throws {CloudflareApiError} on any non-2xx / `success: false`.
+ */
+async function createTxtRecord(zoneId, name, content, token, deps) {
+    const data = (await cloudflareApi('POST', `/zones/${encodeURIComponent(zoneId)}/dns_records`, token, deps, { type: 'TXT', name, content, ttl: 1 }));
+    return typeof data.result?.id === 'string' ? data.result.id : null;
+}
+/**
+ * Idempotently ensure the TXT `absoluteName → content` exists (RWAY-005) — same four cases as
+ * {@link ensureCnameRecord}: absent → `created`; same value and proxied → `unproxied`; same value
+ * → `unchanged`; 🔴 ANOTHER value → {@link DnsRecordConflictError}, never overwritten. The value
+ * is compared without Cloudflare's surrounding quotes. `absoluteName` must already be absolute
+ * ({@link absoluteRecordName}).
+ *
+ * @throws {CloudflareApiError} on any non-2xx / `success: false` (caller maps it).
+ */
+export async function ensureTxtRecord(zoneId, absoluteName, content, token, deps = {}) {
+    return (await ensureUnproxiedRecord(zoneId, 'TXT', absoluteName, content, token, deps)).outcome;
+}
+/**
+ * Read ONE DNS record by id — `GET /zones/{id}/dns_records/{recordId}` — or `null` when Cloudflare
+ * answers 404 (already gone). Read-only. `--destroy` (Railway) calls it before
+ * {@link deleteDnsRecord}: the ids come from the committed state, which is low-trust, so the live
+ * record's `type` and `name` are checked against what the stack owns before anything is deleted.
+ *
+ * @throws {CloudflareApiError} on any non-2xx other than 404 / `success: false`.
+ */
+export async function getDnsRecord(zoneId, recordId, token, deps = {}) {
+    let data;
+    try {
+        data = (await cloudflareApi('GET', `/zones/${encodeURIComponent(zoneId)}/dns_records/${encodeURIComponent(recordId)}`, token, deps));
     }
-    return 'unchanged';
+    catch (error) {
+        if (error instanceof CloudflareApiError && error.status === 404)
+            return null;
+        throw error;
+    }
+    const record = data.result;
+    if (!record || typeof record.type !== 'string' || typeof record.name !== 'string') {
+        throw new CloudflareApiError(200, 'la respuesta no trae `type` y `name` del registro', `GET /zones/${zoneId}/dns_records/${recordId}`);
+    }
+    return {
+        id: typeof record.id === 'string' ? record.id : recordId,
+        type: record.type,
+        name: record.name,
+        content: typeof record.content === 'string' ? record.content : '',
+        proxied: record.proxied === true,
+    };
 }
 /**
  * Delete a DNS record by id — `DELETE /zones/{id}/dns_records/{recordId}`
  * (BOOT-007). The ONE deletion in this module, and it is DELIBERATE: it runs only
  * inside a flow the human already confirmed (retiring the interim domain after the
- * client domain verified — the orphaned interim CNAME would otherwise resolve to
- * {@link CNAME_VERCEL_TARGET} and serve a 404 forever). It is NEVER used to
+ * client domain verified — the orphaned interim CNAME would otherwise keep resolving to
+ * the hosting's target and serve a 404 forever). It is NEVER used to
  * recover from a failed call — the module-header contract stands.
  *
  * Mirrors `removeVercelDomain`'s 404 tolerance: a record already gone (deleted by