@clossys/writer 0.3.9 → 0.4.0

package/src/cli.ts

@@ -132,10 +132,13 @@ import {
 } from "./addressability.js";
 import { checkCopyTraceability, type CopyGateFinding, type CopyGateIgnored, type CopyGateResult } from "./copy-gate.js";
 import { checkLocaleCoverage, type LocaleCoverageReport } from "./locale-coverage.js";
+import { liveTreeExists, scanLiveCopyTrees } from "./live-copy-gate.js";
 import { checkPassageComposition, readPassageRecord, type PassageGateResult } from "./passage.js";
 import { readCopyRecord } from "./registry.js";
+import { checkRenderRegistryParity } from "./render-registry-parity.js";
 import { scanCopySourceTree, type ScanResult, type UncheckedItem } from "./scan.js";
-import { checkVoiceDerivationCoverage, type VoiceDerivationCoverageResult } from "./voice/index.js";
+import { checkTreatmentWordBudgets, type TreatmentWordBudgetFinding } from "./treatment-word-budget.js";
+import { checkVoiceDerivationCoverage, parseVoiceRecord, type VoiceDerivationCoverageResult } from "./voice/index.js";
 
 const USAGE = `Usage: writer-check <record-file> [scan-dir] [options]
    or: writer-check voice-derivation-coverage <obligations-file> <brand-derived-rule-ids-file> [options]
@@ -154,6 +157,9 @@ are separate, stricter gates; neither runs as part of this default command.
 
 Options:
   --help         Print this message and exit 0.
+  --render-registry <file>  Path the surface passes to createCopyResolver at render. When set, must be the same file as record-file (after realpath). When omitted, record-file itself must be a CopyRegistry — not a plain CopyRecord or an in-memory-only store.
+  --live <dir>   Declared live-copy tree the page actually renders (repeatable). Requires --voice-record.
+  --voice-record <file>  Voice record JSON for claims when --live is set.
   --format <text|json>  Output format. Defaults to text. "json" prints exactly one
                  machine-readable object to stdout (see CopyTraceabilityReport in
                  cli.ts) instead of the human-readable report — "verdict" states the
@@ -206,6 +212,9 @@ export class CliInputError extends Error {}
 interface ParsedArgs {
   recordFile?: string;
   scanDir?: string;
+  renderRegistryFile?: string;
+  liveTrees: string[];
+  voiceRecordFile?: string;
   format: "text" | "json";
   help: boolean;
 }
@@ -213,6 +222,9 @@ interface ParsedArgs {
 function parseArgs(argv: string[]): ParsedArgs {
   let recordFile: string | undefined;
   let scanDir: string | undefined;
+  let renderRegistryFile: string | undefined;
+  const liveTrees: string[] = [];
+  let voiceRecordFile: string | undefined;
   let format: "text" | "json" = "text";
   let help = false;
 
@@ -222,6 +234,14 @@ function parseArgs(argv: string[]): ParsedArgs {
       help = true;
       continue;
     }
+    if (arg === "--render-registry") {
+      const value = argv[++i];
+      if (value === undefined || value.startsWith("-")) {
+        throw new CliInputError("--render-registry requires a file path");
+      }
+      renderRegistryFile = value;
+      continue;
+    }
     if (arg === "--format") {
       const value = argv[++i];
       if (value !== "text" && value !== "json") {
@@ -230,6 +250,18 @@ function parseArgs(argv: string[]): ParsedArgs {
       format = value;
       continue;
     }
+    if (arg === "--live") {
+      const value = argv[++i];
+      if (value === undefined || value.startsWith("-")) throw new CliInputError("--live requires a directory path");
+      liveTrees.push(value);
+      continue;
+    }
+    if (arg === "--voice-record") {
+      const value = argv[++i];
+      if (value === undefined || value.startsWith("-")) throw new CliInputError("--voice-record requires a file path");
+      voiceRecordFile = value;
+      continue;
+    }
     if (arg.startsWith("-")) {
       throw new CliInputError(`unknown flag "${arg}"`);
     }
@@ -242,7 +274,22 @@ function parseArgs(argv: string[]): ParsedArgs {
     }
   }
 
-  return { recordFile, scanDir, format, help };
+  if (liveTrees.length > 0 && !voiceRecordFile) {
+    throw new CliInputError("--voice-record is required when --live is declared");
+  }
+
+  return { recordFile, scanDir, renderRegistryFile, liveTrees, voiceRecordFile, format, help };
+}
+
+function printTreatmentWordBudgetReport(findings: TreatmentWordBudgetFinding[]): void {
+  if (findings.length === 0) {
+    console.log("No treatment word-budget findings.");
+    return;
+  }
+  console.log(`\n${findings.length} treatment word-budget finding(s):`);
+  for (const f of findings) {
+    console.log(`  [${f.rule}] ${f.entryId}  ${f.message}`);
+  }
 }
 
 function requireDirectory(label: string, path: string): void {
@@ -710,7 +757,12 @@ function printAddressabilityReport(result: AddressabilityGateResult): void {
   } else {
     console.log(`\n[addressability] ${result.violations.length} violation(s):`);
     for (const v of result.violations) {
-      const where = v.position === "markup-text" ? "a markup text node" : `the "${v.attribute}" attribute`;
+      const where =
+        v.position === "markup-text"
+          ? "a markup text node"
+          : v.position === "object-literal-copy"
+            ? `object-literal key "${v.keyPath ?? v.objectKey}"`
+            : `the "${v.attribute}" attribute`;
       console.log(`  [copy-addressability] ${v.file}:${v.line}  inline prose in ${where}, not resolved from the copy registry by id: ${v.raw}`);
     }
   }
@@ -856,6 +908,39 @@ export function main(argv: string[]): number {
     return 2;
   }
 
+  let recordRaw: unknown;
+  try {
+    recordRaw = JSON.parse(readFileSync(recordFile, "utf8"));
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    if (!jsonMode) {
+      console.error(`\nCopy record could not be re-read for registry parity: ${detail}`);
+      console.error("Refusing to report a pass without confirming the render registry store.");
+    }
+    emitJson(emptyReport(recordFile, scanDir, 2, `copy record could not be re-read: ${detail}`));
+    return 2;
+  }
+
+  const renderRegistryPath = args.renderRegistryFile ? resolve(args.renderRegistryFile) : undefined;
+  if (renderRegistryPath) requireFile("render-registry", renderRegistryPath);
+
+  const parity = checkRenderRegistryParity(recordFile, recordRaw, renderRegistryPath);
+  if (!parity.ok || !parity.registry) {
+    if (!jsonMode) {
+      console.error(`\nRender registry parity: ${parity.detail ?? parity.reason}`);
+      console.error("Refusing to report a pass when the CLI is not reading the same store createCopyResolver uses.");
+    }
+    emitJson(emptyReport(recordFile, scanDir, 2, parity.detail ?? parity.reason ?? "render registry parity failed"));
+    return 2;
+  }
+
+  const treatmentBudget = checkTreatmentWordBudgets(parity.registry);
+  if (!jsonMode && treatmentBudget.entriesChecked > 0) {
+    console.log(
+      `Treatment word budgets: ${treatmentBudget.entriesChecked} approved entr${treatmentBudget.entriesChecked === 1 ? "y" : "ies"} with a treatment checked.`,
+    );
+  }
+
   // No argv flag populates `pathExclusions` today — this CLI always calls
   // `scanCopySourceTree` with defaults (`[]`), so `scan.excludedFiles`/
   // `scan.pathExclusionFindings` are always empty in THIS binary as
@@ -944,6 +1029,66 @@ export function main(argv: string[]): number {
 
   const result = checkCopyTraceability(scan.candidates, scan.citations, read.record, scan.filesScanned, scan.unchecked);
   if (!jsonMode) printGateReport(result);
+  if (!jsonMode) printTreatmentWordBudgetReport(treatmentBudget.findings);
+
+  const hasTreatmentFindings = treatmentBudget.findings.length > 0;
+
+  if (args.liveTrees.length > 0) {
+    for (const livePath of args.liveTrees) {
+      const resolvedLive = resolve(livePath);
+      if (!liveTreeExists(resolvedLive)) {
+        if (!jsonMode) {
+          console.error(`\nDeclared live-copy tree "${resolvedLive}" does not exist.`);
+          console.error("Refusing to report a pass without scanning every declared live tree.");
+        }
+        emitJson(emptyReport(recordFile, scanDir, 2, `declared live-copy tree missing: ${resolvedLive}`));
+        return 2;
+      }
+    }
+    const voicePath = resolve(args.voiceRecordFile as string);
+    requireFile("voice-record", voicePath);
+    let voiceRaw: unknown;
+    try {
+      voiceRaw = JSON.parse(readFileSync(voicePath, "utf8"));
+    } catch (error) {
+      if (!jsonMode) console.error(`Voice record could not be loaded: ${error instanceof Error ? error.message : String(error)}`);
+      emitJson(emptyReport(recordFile, scanDir, 2, "voice record could not be loaded"));
+      return 2;
+    }
+    let voiceRecord;
+    try {
+      voiceRecord = parseVoiceRecord(voiceRaw);
+    } catch (error) {
+      if (!jsonMode) console.error(`Voice record is invalid: ${error instanceof Error ? error.message : String(error)}`);
+      emitJson(emptyReport(recordFile, scanDir, 2, "voice record is invalid"));
+      return 2;
+    }
+    const liveScan = scanLiveCopyTrees(voiceRecord, args.liveTrees.map((p) => resolve(p)));
+    if (!jsonMode) {
+      console.log(`Live-copy trees: ${args.liveTrees.length}, ${liveScan.filesScanned} file(s) scanned.`);
+      if (liveScan.findings.length > 0) {
+        console.log(`\n${liveScan.findings.length} live-copy finding(s):`);
+        for (const f of liveScan.findings) console.log(`  [${f.rule}] ${f.file}:${f.line}  ${f.message}`);
+      }
+    }
+    if (liveScan.findings.length > 0) {
+      const exitCode: 0 | 1 | 2 = result.unchecked.length > 0 ? 2 : 1;
+      emitJson({
+        recordFile,
+        scanDir,
+        verdict: result.unchecked.length > 0 ? "indeterminate" : "findings",
+        exitCode,
+        filesScanned: scan.filesScanned,
+        candidatesScanned: result.candidatesScanned,
+        matched: result.matched,
+        findings: result.findings,
+        ignored: result.ignored,
+        unchecked: result.unchecked,
+        parseFailures: scan.parseFailures.map((p) => ({ file: p.file, detail: p.detail })),
+      });
+      return exitCode;
+    }
+  }
 
   // `unchecked` wins over everything else in the exit-code decision — see
   // this file's own top doc comment for why it is a `2`, not a `1`: it
@@ -963,9 +1108,14 @@ export function main(argv: string[]): number {
   // the SAME object, so a consumer keying on `exitCode`/`verdict` alone
   // still fails closed exactly as this package intends, while a consumer
   // that reads further is never forced to throw away what was measured.
-  const exitCode: 0 | 1 | 2 = result.unchecked.length > 0 ? 2 : result.findings.length > 0 ? 1 : 0;
+  const exitCode: 0 | 1 | 2 =
+    result.unchecked.length > 0 ? 2 : result.findings.length > 0 || hasTreatmentFindings ? 1 : 0;
   const verdict: CopyTraceabilityReport["verdict"] =
-    result.unchecked.length > 0 ? "indeterminate" : result.findings.length > 0 ? "findings" : "clean";
+    result.unchecked.length > 0
+      ? "indeterminate"
+      : result.findings.length > 0 || hasTreatmentFindings
+        ? "findings"
+        : "clean";
   emitJson({
     recordFile,
     scanDir,
@@ -1176,24 +1326,82 @@ registry-text-match escape hatch here, unlike the default command.
 
 Options:
   --help         Print this message and exit 0.
+  --extensions <ext>  File extension(s) to scan, including the leading dot (for example .mjs). Repeatable, and each occurrence may itself be a comma-separated list (for example --extensions .mjs,.cjs); values union across both forms. When omitted, default is .ts, .tsx, .js, .jsx. When present, replaces that default. Every value must include the leading dot; a flag that resolves to zero extensions (for example a bare comma) is a usage error, never a vacuous pass.
+  --chrome <file>  Persistent chrome (site header, footer, skip link, nav labels) shell or layout file to scan in addition to scan-dir (repeatable; paths relative to scan-dir unless absolute). Each file must exist.
+  --require-chrome  Refuse to run (exit 2) when no --chrome file was declared — use when the surface mounts persistent chrome outside scan-dir.
 
-Exit codes: 0 = clean, 1 = at least one inline user-facing string found, 2 = could not run (bad input, nothing matched to scan, every matched file failed to parse, or a string position could not be confidently classified).
+Exit codes: 0 = clean, 1 = at least one inline user-facing string found, 2 = could not run (bad input, nothing matched to scan, every matched file failed to parse, a string position could not be confidently classified, a declared chrome file is missing, or --require-chrome was set without --chrome).
 `;
 
+const ADDRESSABILITY_EXTENSION_RE = /^\.[a-zA-Z0-9]+$/;
+
 interface AddressabilityParsedArgs {
   scanDir?: string;
+  /** Set only when the caller passed at least one `--extensions` flag. */
+  extensions?: string[];
+  chromeFiles: string[];
+  requireChrome: boolean;
   help: boolean;
 }
 
 function parseAddressabilityArgs(argv: string[]): AddressabilityParsedArgs {
   let scanDir: string | undefined;
+  const extensions: string[] = [];
+  const chromeFiles: string[] = [];
   let help = false;
+  let sawExtensions = false;
+  let requireChrome = false;
 
-  for (const arg of argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i] as string;
     if (arg === "--help" || arg === "-h") {
       help = true;
       continue;
     }
+    if (arg === "--require-chrome") {
+      requireChrome = true;
+      continue;
+    }
+    if (arg === "--chrome") {
+      const value = argv[++i];
+      if (value === undefined || value.startsWith("-")) {
+        throw new CliInputError("--chrome requires a file path");
+      }
+      chromeFiles.push(value);
+      continue;
+    }
+    if (arg === "--extensions") {
+      sawExtensions = true;
+      const value = argv[++i];
+      if (value === undefined || value.startsWith("-")) {
+        throw new CliInputError("--extensions requires an extension such as .mjs");
+      }
+      // Repeatable AND comma-separated: `--extensions .mjs,.cjs` and
+      // `--extensions .mjs --extensions .cjs` union to the same set. Every
+      // token from the split is validated individually — a bare comma or a
+      // trailing/leading comma yields an empty token, which is a usage
+      // error below rather than being silently dropped (an --extensions
+      // flag that resolves to zero extensions must never fall back to the
+      // default set — that would be a vacuous pass on the caller's own
+      // explicit-but-empty request).
+      const tokens = value.split(",");
+      if (tokens.length === 0 || tokens.some((token) => token.trim().length === 0)) {
+        throw new CliInputError(
+          `--extensions requires at least one non-empty extension such as .mjs, got ${JSON.stringify(value)}`,
+        );
+      }
+      for (const rawToken of tokens) {
+        const token = rawToken.trim().toLowerCase();
+        if (!token.startsWith(".")) {
+          throw new CliInputError(`--extensions values must include the leading dot, got ${JSON.stringify(token)}`);
+        }
+        if (!ADDRESSABILITY_EXTENSION_RE.test(token)) {
+          throw new CliInputError(`invalid --extensions value ${JSON.stringify(token)}`);
+        }
+        extensions.push(token);
+      }
+      continue;
+    }
     if (arg.startsWith("-")) {
       throw new CliInputError(`unknown flag "${arg}"`);
     }
@@ -1204,7 +1412,7 @@ function parseAddressabilityArgs(argv: string[]): AddressabilityParsedArgs {
     }
   }
 
-  return { scanDir, help };
+  return { scanDir, help, extensions: sawExtensions ? extensions : undefined, chromeFiles, requireChrome };
 }
 
 /**
@@ -1223,12 +1431,23 @@ export function mainAddressabilityCheck(argv: string[]): number {
   const scanDir = resolve(args.scanDir ?? process.cwd());
   requireDirectory("scan-dir", scanDir);
 
+  if (args.requireChrome && args.chromeFiles.length === 0) {
+    throw new CliInputError("--require-chrome was set but no --chrome file was declared");
+  }
+
   console.log(`Scan directory: ${scanDir}`);
+  if (args.chromeFiles.length > 0) {
+    console.log(`Chrome files: ${args.chromeFiles.join(", ")}`);
+  }
+
+  const scanOptions: { extensions?: string[]; chromeFiles?: string[] } = {};
+  if (args.extensions) scanOptions.extensions = args.extensions;
+  if (args.chromeFiles.length > 0) scanOptions.chromeFiles = args.chromeFiles;
 
   // Throws (fail-closed) on an unreadable directory, exactly like
   // `scanCopySourceTree` — caught by `runAddressabilityCheck()`'s own
   // catch-all below.
-  const scan = scanAddressabilitySources(scanDir);
+  const scan = scanAddressabilitySources(scanDir, scanOptions);
   printAddressabilityAccounting(scan);
 
   const result = checkAddressability(scan);

package/src/fold-wallpaper-gate.ts

@@ -0,0 +1,29 @@
+/**
+ * Built-in fold wallpaper phrases — generic competitor copy, not consumer-specific.
+ */
+
+export const FOLD_WALLPAPER_PHRASES: readonly string[] = [
+  "for founders and operators",
+  "ai intelligence",
+  "ai-native",
+  "for founders",
+];
+
+function isAlphanumeric(ch: string): boolean {
+  return /[a-z0-9]/i.test(ch);
+}
+
+/** Case-insensitive, whole-phrase-ish match inside a string literal value. */
+export function findFoldWallpaperPhrase(value: string): string | undefined {
+  const haystack = value.toLowerCase();
+  const ordered = [...FOLD_WALLPAPER_PHRASES].sort((a, b) => b.length - a.length);
+  for (const phrase of ordered) {
+    const idx = haystack.indexOf(phrase);
+    if (idx === -1) continue;
+    const beforeOk = idx === 0 || !isAlphanumeric(haystack[idx - 1] ?? "");
+    const afterIdx = idx + phrase.length;
+    const afterOk = afterIdx >= haystack.length || !isAlphanumeric(haystack[afterIdx] ?? "");
+    if (beforeOk && afterOk) return phrase;
+  }
+  return undefined;
+}

package/src/index.ts

@@ -123,6 +123,16 @@ export type {
   AddressabilityViolation,
 } from "./addressability.js";
 
+export { checkRenderRegistryParity } from "./render-registry-parity.js";
+export type { RenderRegistryParityReason, RenderRegistryParityResult } from "./render-registry-parity.js";
+
+export { DEFAULT_TREATMENT_WORD_BUDGETS, checkTreatmentWordBudgets, countCopyWords } from "./treatment-word-budget.js";
+export type {
+  TreatmentWordBudgetFinding,
+  TreatmentWordBudgetResult,
+  TreatmentWordBudgetRule,
+} from "./treatment-word-budget.js";
+
 // Locale-coverage governance: is every declared locale covered by a source
 // locale's registry, where has a target locale drifted, has a translation
 // gone stale against an edited source (via content fingerprint), and does

package/src/live-copy-gate.ts

@@ -0,0 +1,150 @@
+/**
+ * Scans declared live-copy trees for claim-shaped and magnitude-shaped prose
+ * that is not accounted for in the voice claims register.
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { findFoldWallpaperPhrase } from "./fold-wallpaper-gate.js";
+import { checkCopy, type VoiceFinding, type VoiceRecord } from "./voice/index.js";
+
+const LIVE_FILE_RE = /\.(tsx?|jsx?|mdx?|md|json)$/i;
+const IGNORE_MARKER_RE = /(?:<!--|\/\*|\{\/\*|\/\/)\s*(?:copy-gate:ignore|voice-gate:ignore)/i;
+const CLAIM_CITATION_RE = /(?:<!--|\/\*|\{\/\*|\/\/)\s*claim:([a-zA-Z][a-zA-Z0-9-]*)/g;
+
+const NUMERIC_CLAIM_RE = new RegExp(
+  [
+    String.raw`[$€£]\s?\d[\d,]*(?:\.\d+)?\s?[kKmMbB]?\b`,
+    String.raw`\b\d+(?:\.\d+)?\s?%`,
+    String.raw`\b\d+(?:\.\d+)?[xX]\b`,
+    String.raw`\b\d{1,3}(?:,\d{3})+\b`,
+    String.raw`\b\d+(?:\.\d+)?\s?(?:million|billion|thousand)\b`,
+  ].join("|"),
+  "gi",
+);
+
+export interface LiveCopyFinding extends VoiceFinding {
+  file: string;
+  line: number;
+}
+
+export interface LiveCopyScanResult {
+  filesScanned: number;
+  findings: LiveCopyFinding[];
+}
+
+function walkLiveTree(root: string): string[] {
+  const files: string[] = [];
+  const stack = [resolve(root)];
+  while (stack.length > 0) {
+    const dir = stack.pop() as string;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name === ".git") continue;
+        stack.push(full);
+      } else if (entry.isFile() && LIVE_FILE_RE.test(entry.name)) {
+        files.push(full);
+      }
+    }
+  }
+  return files;
+}
+
+function extractStringLiterals(text: string): { line: number; value: string }[] {
+  const out: { line: number; value: string }[] = [];
+  const lines = text.split(/\r?\n/);
+  const literalRe = /(["'`])(?:(?!\1)[^\\]|\\.)*\1/g;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] as string;
+    if (IGNORE_MARKER_RE.test(line)) continue;
+    for (const m of line.matchAll(literalRe)) {
+      const raw = m[0] as string;
+      const value = raw.slice(1, -1);
+      if (value.trim().length > 0) out.push({ line: i + 1, value });
+    }
+  }
+  return out;
+}
+
+function lineHasClaimCitation(line: string): boolean {
+  CLAIM_CITATION_RE.lastIndex = 0;
+  return CLAIM_CITATION_RE.test(line);
+}
+
+export function scanLiveCopyTrees(record: VoiceRecord, roots: string[]): LiveCopyScanResult {
+  const findings: LiveCopyFinding[] = [];
+  let filesScanned = 0;
+
+  for (const root of roots) {
+    for (const file of walkLiveTree(root)) {
+      let text: string;
+      try {
+        text = readFileSync(file, "utf8");
+      } catch {
+        continue;
+      }
+      filesScanned++;
+      const lines = text.split(/\r?\n/);
+      for (const { line, value } of extractStringLiterals(text)) {
+        const sourceLine = lines[line - 1] ?? "";
+        if (lineHasClaimCitation(sourceLine)) continue;
+
+        const wallpaperPhrase = findFoldWallpaperPhrase(value);
+        if (wallpaperPhrase) {
+          findings.push({
+            rule: "fold-wallpaper",
+            severity: "error",
+            message: `Fold wallpaper phrase "${wallpaperPhrase}" is generic competitor copy and must not headline the hero.`,
+            path: value.slice(0, 80),
+            file,
+            line,
+          });
+        }
+
+        const voiceReport = checkCopy(record, value);
+        for (const f of voiceReport.findings) {
+          if (f.rule === "claim:unsupported") {
+            findings.push({ ...f, file, line });
+          }
+        }
+
+        if (NUMERIC_CLAIM_RE.test(value)) {
+          NUMERIC_CLAIM_RE.lastIndex = 0;
+          const covered = record.claims.some((claim) => {
+            if (!claim.requiresSupport) return true;
+            if (claim.factRef) return true;
+            const phrases = claim.matchPhrases.length > 0 ? claim.matchPhrases : [claim.text];
+            return phrases.some((p) => value.toLowerCase().includes(p.toLowerCase()));
+          });
+          if (!covered) {
+            findings.push({
+              rule: "live:magnitude-unmarked",
+              severity: "error",
+              message: `Magnitude-shaped copy is not covered by a supported claim in the voice register.`,
+              path: value.slice(0, 80),
+              file,
+              line,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return { filesScanned, findings };
+}
+
+export function liveTreeExists(path: string): boolean {
+  try {
+    return statSync(resolve(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/src/render-registry-parity.ts

@@ -0,0 +1,65 @@
+/**
+ * Ensures the registry file `writer-check` reads is the same store a surface
+ * passes to `createCopyResolver` at render — never a second, request-scoped
+ * module the CLI does not scan.
+ */
+
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { validateCopyRegistryShape } from "./schema.js";
+import type { CopyRegistry } from "./types.js";
+
+export type RenderRegistryParityReason =
+  | "render-registry-path-mismatch"
+  | "record-not-copy-registry";
+
+export interface RenderRegistryParityResult {
+  ok: boolean;
+  reason?: RenderRegistryParityReason;
+  detail?: string;
+  registry?: CopyRegistry;
+}
+
+/**
+ * Confirms `recordFile` is a `CopyRegistry` and, when `renderRegistryFile`
+ * is supplied, that both paths resolve to the same file (the render store
+ * and the gate store must be one file).
+ */
+export function checkRenderRegistryParity(
+  recordFile: string,
+  recordValue: unknown,
+  renderRegistryFile?: string,
+): RenderRegistryParityResult {
+  const registryFindings = validateCopyRegistryShape(recordValue);
+  if (registryFindings.length > 0) {
+    const detail = registryFindings.map((f) => f.message).join("; ");
+    return {
+      ok: false,
+      reason: "record-not-copy-registry",
+      detail: `record-file is not a CopyRegistry (the store createCopyResolver reads): ${detail}`,
+    };
+  }
+
+  if (renderRegistryFile !== undefined) {
+    const recordReal = safeRealpath(resolve(recordFile));
+    const renderReal = safeRealpath(resolve(renderRegistryFile));
+    if (recordReal !== renderReal) {
+      return {
+        ok: false,
+        reason: "render-registry-path-mismatch",
+        detail:
+          "record-file and --render-registry must be the same file — a second approved store the CLI does not read is not an approved registry.",
+      };
+    }
+  }
+
+  return { ok: true, registry: recordValue as CopyRegistry };
+}
+
+function safeRealpath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}

package/src/schema.ts

@@ -121,6 +121,8 @@ function validateCopyEntryShape(value: unknown, path: string): CopyFinding[] {
   const context = value.context;
   const placeholders = value.placeholders;
   const factRef = value.factRef;
+  const treatment = value.treatment;
+  const maxWords = value.maxWords;
 
   const findings: CopyFinding[] = [];
 
@@ -189,6 +191,26 @@ function validateCopyEntryShape(value: unknown, path: string): CopyFinding[] {
     });
   }
 
+  if (treatment !== undefined && !isNonEmptyString(treatment)) {
+    findings.push({
+      rule: "treatment-shape",
+      severity: "error",
+      message: `${path}.treatment must be a non-empty string when present, got ${JSON.stringify(treatment)}.`,
+      path: `${path}.treatment`,
+    });
+  }
+
+  if (maxWords !== undefined) {
+    if (typeof maxWords !== "number" || !Number.isFinite(maxWords) || maxWords < 1) {
+      findings.push({
+        rule: "max-words-shape",
+        severity: "error",
+        message: `${path}.maxWords must be a positive finite number when present, got ${JSON.stringify(maxWords)}.`,
+        path: `${path}.maxWords`,
+      });
+    }
+  }
+
   return findings;
 }
 
@@ -461,6 +483,8 @@ function buildCopyRecord(value: Record<string, unknown>): CopyRecord {
       context: entry.context as string,
       placeholders: [...((entry.placeholders as string[] | undefined) ?? [])],
       factRef: entry.factRef as string | undefined,
+      treatment: entry.treatment as string | undefined,
+      maxWords: entry.maxWords as number | undefined,
     };
   });