@clossys/writer 0.3.9 → 0.5.0

package/src/cli.ts

@@ -109,6 +109,21 @@
  *       all. This is the explicit third state this gate is built around:
  *       "could not check" must never be reported as a pass.
  *
+ * A FIFTH and SIXTH subcommand, `approve` and `approval-state`, are
+ * dispatched the same way `addressability` and `passages` are — a fully
+ * separate top-level branch at the very bottom of this file, never folded
+ * through `main()`. `writer-check approve` writes a
+ * `CopyRegistryEntry.approval` record so nobody hand-edits one; its whole
+ * argument-parsing, validation, and atomic-write contract lives in
+ * `mainApproveCommand` (`./approve-cli.ts`) — this file only wires its
+ * exit code through. `writer-check approval-state` reports the current
+ * approval state of a registry from two angles at once: whether every
+ * approved entry's own record is current (`assessCopyApprovals`) and
+ * whether consumer source actually routes copy through the registry's
+ * approval lifecycle rather than around it (`scanApprovalBypass`/
+ * `checkApprovalBypass`); its own contract lives in
+ * `mainApprovalStateCommand` (`./approval.ts`).
+ *
  * A malformed `pathExclusions` entry (see `scan.ts`/`path-exclusions.ts`)
  * gets the same `2` treatment as `unchecked`, for the identical reason: an
  * exclusion list this run cannot trust means this run cannot say which
@@ -132,10 +147,15 @@ 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 { mainApprovalStateCommand } from "./approval.js";
+import { mainApproveCommand } from "./approve-cli.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]
@@ -144,16 +164,24 @@ const USAGE = `Usage: writer-check <record-file> [scan-dir] [options]
   record-file    Path to a CopyRecord JSON file (see @clossys/writer's README). Required.
   scan-dir       Directory to scan for user-facing string/template literals. Defaults to the current working directory.
 
-See also "writer-check addressability [scan-dir]" and "writer-check passages
-<registry-file>" (this same file's other subcommands, both dispatched on
-argv[0] before anything below) — addressability asks whether user-facing
-prose is resolved from the copy registry by id, rather than typed inline;
-passages asks whether a passage composes registered entries/terms rather
-than inlining a literal or reaching into another passage's internals. Both
-are separate, stricter gates; neither runs as part of this default command.
+See also "writer-check addressability [scan-dir]", "writer-check passages
+<registry-file>", "writer-check approve <registry-file> <entry-id>...", and
+"writer-check approval-state <registry-file> <scan-dir>" (this same file's
+other subcommands, all dispatched on argv[0] before anything below) —
+addressability asks whether user-facing prose is resolved from the copy
+registry by id, rather than typed inline; passages asks whether a passage
+composes registered entries/terms rather than inlining a literal or
+reaching into another passage's internals; approve writes an entry's
+approval record; approval-state reports whether a
+registry's approval records are current and whether consumer source
+actually routes copy through them. All four are separate gates/commands;
+none 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
@@ -171,6 +199,8 @@ Run "writer-check voice-derivation-coverage --help" for the second subcommand's
 Run "writer-check locale-coverage --help" for the third subcommand's own usage.
 Run "writer-check addressability --help" for that subcommand's own usage.
 Run "writer-check passages --help" for the passage-composition subcommand's own usage.
+Run "writer-check approve --help" for the approval-recording subcommand's own usage.
+Run "writer-check approval-state --help" for the approval-state subcommand's own usage.
 `;
 
 const VOICE_DERIVATION_COVERAGE_USAGE = `Usage: writer-check voice-derivation-coverage <obligations-file> <brand-derived-rule-ids-file> [options]
@@ -206,6 +236,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 +246,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 +258,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 +274,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 +298,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 +781,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 +932,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 +1053,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 +1132,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 +1350,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 +1436,7 @@ function parseAddressabilityArgs(argv: string[]): AddressabilityParsedArgs {
     }
   }
 
-  return { scanDir, help };
+  return { scanDir, help, extensions: sawExtensions ? extensions : undefined, chromeFiles, requireChrome };
 }
 
 /**
@@ -1223,12 +1455,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);
@@ -1291,11 +1534,12 @@ function detectMainModule(): boolean {
 }
 
 /**
- * `writer-check`, `writer-check addressability`, and `writer-check passages`
- * are ONE `bin` entry, one compiled file, dispatched by an explicit FIRST
- * ARGUMENT — never by how this file was invoked (its own path, a symlink
- * name, an installed `bin` shim, ...). That is deliberate: this
- * repository's own root `package.json` invokes every gate by compiled path
+ * `writer-check`, `writer-check addressability`, `writer-check passages`,
+ * `writer-check approve`, and `writer-check approval-state` are ONE `bin`
+ * entry, one compiled file, dispatched by an explicit FIRST ARGUMENT — never
+ * by how this file was invoked (its own path, a symlink name, an installed
+ * `bin` shim, ...). That is deliberate: this repository's own root
+ * `package.json` invokes every gate by compiled path
  * (`node packages/ui/dist/tokens/contrast-cli.js`,
  * `node packages/controller/dist/cli.js`, ...), never by `bin` name, so
  * any dispatch keyed on the invoking path/name (a second `bin` entry
@@ -1305,7 +1549,11 @@ function detectMainModule(): boolean {
  * exactly the "runs the wrong thing without ever failing" failure mode a
  * gate must never have. `rawArgs[0]` is read BEFORE `main()`'s own
  * `parseArgs` ever sees the array, so the default command's argument
- * shape is completely unaffected by either subcommand existing at all.
+ * shape is completely unaffected by any subcommand existing at all.
+ * `mainApproveCommand`/`mainApprovalStateCommand` never throw (see their own
+ * doc comments), so — unlike `runAddressabilityCheck`/`runPassagesCheck`
+ * above — their branches assign `process.exitCode` directly, with no
+ * try/catch wrapper of their own to add.
  */
 if (detectMainModule()) {
   const rawArgs = process.argv.slice(2);
@@ -1313,6 +1561,10 @@ if (detectMainModule()) {
     runAddressabilityCheck(rawArgs.slice(1));
   } else if (rawArgs[0] === "passages") {
     runPassagesCheck(rawArgs.slice(1));
+  } else if (rawArgs[0] === "approve") {
+    process.exitCode = mainApproveCommand(rawArgs.slice(1));
+  } else if (rawArgs[0] === "approval-state") {
+    process.exitCode = mainApprovalStateCommand(rawArgs.slice(1));
   } else {
     run();
   }

package/src/field-options.ts

@@ -0,0 +1,134 @@
+/**
+ * The option handling and per-field resolution shared by the two reserved
+ * copy kinds that resolve literal text from a `CopyRegistry`: the site
+ * identity (`site-identity.ts`) and the messaging kit (`messaging-kit.ts`).
+ *
+ * Both asked the same two questions of every field — are the options
+ * well-formed, and does `resolveCopyRef` return literal, non-blank text —
+ * and used to answer them with two copies of the same code. They differ only
+ * in the words of their messages and in the names of their two own reasons,
+ * which the caller passes in as `FieldLabels`.
+ *
+ * Internal: not exported from the package index.
+ */
+
+import { resolveCopyRef } from "./resolve.js";
+import type { CopyResolveIssue, CopyResolveIssueReason, CopyResolveOptions } from "./resolve.js";
+import type { CopyRegistry, CopyRegistryEntry, CopyResolution } from "./types.js";
+
+export type PreparedOptions =
+  | { ok: true; locale: string | undefined; resolveOptions: CopyResolveOptions }
+  | { ok: false };
+
+/** The words and reasons a caller contributes to the shared resolution. */
+export interface FieldLabels<Reason extends string> {
+  /** Subject of the "options are malformed" message, e.g. `"Site identity"`. */
+  optionsSubject: string;
+  /** Subject of an entry's messages, e.g. `Site identity "site.name"`. */
+  entrySubject: (id: string) => string;
+  /** Reason reported when an entry declares placeholders or its text would be rewritten. */
+  placeholderReason: Reason;
+  /** Reason reported when the resolved text is blank after trimming. */
+  blankReason: Reason;
+}
+
+/** One reason a field could not be resolved, tagged with the caller's field name. */
+export interface FieldIssue<Field extends string, Reason extends string> extends Omit<CopyResolveIssue, "reason"> {
+  reason: CopyResolveIssueReason | Reason;
+  field: Field;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Splits `locale` (a ref field) from the options `resolveCopyRef` reads.
+ * `resolveCopyRef` only looks at `target`, `acceptDelegateInProduction`
+ * and `now`, so only those are forwarded; each property is read once.
+ * When `now` is absent it is fixed here once, so every field is judged
+ * against the same instant. The forwarded values are not validated here —
+ * `resolveCopyRef` still does that, and refuses a malformed one.
+ */
+export function prepareOptions(options: unknown): PreparedOptions {
+  if (options === undefined) return { ok: true, locale: undefined, resolveOptions: { now: new Date() } };
+  if (!isPlainObject(options)) return { ok: false };
+  try {
+    const { locale, target, acceptDelegateInProduction, now } = options;
+    if (locale !== undefined && (typeof locale !== "string" || locale.trim().length === 0)) return { ok: false };
+    const resolveOptions: Record<string, unknown> = { now: now === undefined ? new Date() : now };
+    if (target !== undefined) resolveOptions.target = target;
+    if (acceptDelegateInProduction !== undefined) resolveOptions.acceptDelegateInProduction = acceptDelegateInProduction;
+    return { ok: true, locale, resolveOptions: resolveOptions as CopyResolveOptions };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/**
+ * Resolves one reserved id as literal text. Every `resolveCopyRef` refusal is
+ * kept with its own reason, except that the placeholder-value reasons surface
+ * as `labels.placeholderReason`, once per field. Text that is blank after
+ * trimming, or an entry that declares placeholders or whose text the
+ * resolver would rewrite, is refused too. Never throws.
+ */
+export function resolveField<Field extends string, Reason extends string>(
+  registry: unknown,
+  field: Field,
+  id: string,
+  prepared: PreparedOptions,
+  labels: FieldLabels<Reason>,
+): { resolution?: CopyResolution; issues: FieldIssue<Field, Reason>[] } {
+  const subject = labels.entrySubject(id);
+  if (!prepared.ok) {
+    return { issues: [{ reason: "invalid-options", field, id, message: `${labels.optionsSubject} options are malformed.` }] };
+  }
+  try {
+    const ref = prepared.locale === undefined ? { id } : { id, locale: prepared.locale };
+    const result = resolveCopyRef(registry, ref, prepared.resolveOptions);
+    if (!result.complete || !result.resolution) {
+      const issues: FieldIssue<Field, Reason>[] = [];
+      let placeholderReported = false;
+      for (const issue of result.issues) {
+        if (issue.reason === "missing-placeholder-value" || issue.reason === "unexpected-placeholder-value") {
+          if (placeholderReported) continue;
+          placeholderReported = true;
+          issues.push({
+            reason: labels.placeholderReason,
+            field,
+            id,
+            message: `${subject} must be literal text; an entry that declares placeholders cannot be used.`,
+          });
+        } else {
+          issues.push({ ...issue, field });
+        }
+      }
+      if (issues.length === 0) {
+        issues.push({ reason: "invalid-registry", field, id, message: `${subject} could not be resolved.` });
+      }
+      return { issues };
+    }
+
+    const resolution = result.resolution;
+    if (resolution.text.trim().length === 0) {
+      return { issues: [{ reason: labels.blankReason, field, id, message: `${subject} resolved to blank text.` }] };
+    }
+    // The registry validated (resolution completed), so `entries` is a real array.
+    const entry = (registry as CopyRegistry).entries.find((candidate: CopyRegistryEntry) => candidate.id === id);
+    if (entry && ((entry.placeholders?.length ?? 0) > 0 || entry.text !== resolution.text)) {
+      return {
+        issues: [
+          {
+            reason: labels.placeholderReason,
+            field,
+            id,
+            message: `${subject} must be literal text; its entry declares placeholders or contains text the resolver would rewrite.`,
+          },
+        ],
+      };
+    }
+    return { resolution, issues: [] };
+  } catch {
+    return { issues: [{ reason: "invalid-registry", field, id, message: `${subject} could not be resolved.` }] };
+  }
+}

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/front-door.check.ts

@@ -0,0 +1,10 @@
+// Compile-time assertions for the front-door copy kind. This file has no
+// runtime footprint and is not exported from `index.ts`; `tsc` compiling it is
+// the check.
+
+import { resolveFrontDoorCopy } from "./front-door.js";
+
+// @ts-expect-error unknown front-door key
+resolveFrontDoorCopy("front-door.sign-in.heading", {});
+
+resolveFrontDoorCopy("front-door.sign-in.title", {});