@clossys/writer 0.3.9 → 0.5.0

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/messaging-kit.ts

@@ -0,0 +1,195 @@
+/**
+ * The messaging-kit copy kind: a pitch and a boilerplate, each in three
+ * lengths, resolved from a `CopyRegistry` under six reserved entry ids.
+ *
+ * A consumer reuses the same "about us" text in press, footers and email,
+ * and needs it to carry the same approval evidence as any other rendered
+ * copy. This module is a reserved copy kind, not a second text store or a
+ * second approval path: it asks `resolveCopyRef` for each id, so everything
+ * that resolver refuses is refused here for the same reason.
+ *
+ * Invariants:
+ *
+ * - K1: every `resolveCopyRef` refusal is reported with its own reason,
+ *   tagged with the field it belongs to.
+ * - K2: `"messaging-placeholder"` when an entry declares placeholders or its
+ *   text is one the resolver would rewrite; `"messaging-blank"` when the
+ *   resolved text is empty after trimming. These are literal texts, not
+ *   templates.
+ * - K3: `"messaging-ladder-order"` when `countCopyWords` does not strictly
+ *   increase within a ladder (pitch: one-liner, elevator, paragraph; then
+ *   boilerplate: short, medium, long). It is reported on the later field,
+ *   and only between two fields that both resolved.
+ * - K4: all six are attempted on every call. `kit` and `resolutions` exist
+ *   only when `issues` is empty, so there is no partial kit. `options.now`
+ *   is fixed once per call. Nothing here throws for any input.
+ * - K5: no word targets beyond K3. An FAQ and a tagline are out of scope
+ *   (`site.tagline` is already a reserved site-identity id).
+ *
+ * No real copy ships here. The ids are reserved names; the words are the
+ * consumer's own.
+ */
+
+import { prepareOptions, resolveField } from "./field-options.js";
+import type { FieldLabels } from "./field-options.js";
+import type { CopyResolveIssue, CopyResolveIssueReason, CopyResolveOptions } from "./resolve.js";
+import { countCopyWords } from "./treatment-word-budget.js";
+import type { CopyRegistry, CopyResolution } from "./types.js";
+
+/** Reserved copy id for the shortest pitch. */
+export const MESSAGING_PITCH_ONE_LINER_COPY_ID = "messaging.pitch.one-liner";
+
+/** Reserved copy id for the elevator pitch. */
+export const MESSAGING_PITCH_ELEVATOR_COPY_ID = "messaging.pitch.elevator";
+
+/** Reserved copy id for the paragraph-length pitch. */
+export const MESSAGING_PITCH_PARAGRAPH_COPY_ID = "messaging.pitch.paragraph";
+
+/** Reserved copy id for the short boilerplate. */
+export const MESSAGING_BOILERPLATE_SHORT_COPY_ID = "messaging.boilerplate.short";
+
+/** Reserved copy id for the medium boilerplate. */
+export const MESSAGING_BOILERPLATE_MEDIUM_COPY_ID = "messaging.boilerplate.medium";
+
+/** Reserved copy id for the long boilerplate. */
+export const MESSAGING_BOILERPLATE_LONG_COPY_ID = "messaging.boilerplate.long";
+
+/** All six reserved messaging-kit copy ids: the pitch ladder, then the boilerplate ladder. */
+export const MESSAGING_KIT_COPY_IDS = [
+  MESSAGING_PITCH_ONE_LINER_COPY_ID,
+  MESSAGING_PITCH_ELEVATOR_COPY_ID,
+  MESSAGING_PITCH_PARAGRAPH_COPY_ID,
+  MESSAGING_BOILERPLATE_SHORT_COPY_ID,
+  MESSAGING_BOILERPLATE_MEDIUM_COPY_ID,
+  MESSAGING_BOILERPLATE_LONG_COPY_ID,
+] as const;
+
+/** Which entry of the kit an issue is about. */
+export type MessagingKitField =
+  | "pitch.oneLiner"
+  | "pitch.elevator"
+  | "pitch.paragraph"
+  | "boilerplate.short"
+  | "boilerplate.medium"
+  | "boilerplate.long";
+
+/**
+ * Every reason `resolveMessagingKit` can report: whatever `resolveCopyRef`
+ * refuses, plus the three refusals specific to the kit.
+ */
+export type MessagingKitIssueReason =
+  | CopyResolveIssueReason
+  | "messaging-blank"
+  | "messaging-placeholder"
+  | "messaging-ladder-order";
+
+/** One reason the kit could not be resolved, tagged with its field. */
+export interface MessagingKitIssue extends Omit<CopyResolveIssue, "reason"> {
+  reason: MessagingKitIssueReason;
+  field: MessagingKitField;
+}
+
+/** The resolved text of the kit, by ladder. */
+export interface MessagingKit {
+  pitch: { oneLiner: string; elevator: string; paragraph: string };
+  boilerplate: { short: string; medium: string; long: string };
+}
+
+/** Each entry's `CopyResolution`, shaped like `MessagingKit`. */
+export interface MessagingKitResolutions {
+  pitch: { oneLiner: CopyResolution; elevator: CopyResolution; paragraph: CopyResolution };
+  boilerplate: { short: CopyResolution; medium: CopyResolution; long: CopyResolution };
+}
+
+/**
+ * The outcome of `resolveMessagingKit`. `kit` and `resolutions` are present
+ * only when `complete` is `true`; `issues` is empty exactly then.
+ */
+export interface MessagingKitResolution {
+  complete: boolean;
+  kit?: MessagingKit;
+  resolutions?: MessagingKitResolutions;
+  issues: MessagingKitIssue[];
+}
+
+/** `CopyResolveOptions` plus the requested locale, which is a ref field for the underlying resolver. */
+export type MessagingKitOptions = CopyResolveOptions & { locale?: string };
+
+const FIELDS: readonly { field: MessagingKitField; id: string; ladder: "pitch" | "boilerplate" }[] = [
+  { field: "pitch.oneLiner", id: MESSAGING_KIT_COPY_IDS[0], ladder: "pitch" },
+  { field: "pitch.elevator", id: MESSAGING_KIT_COPY_IDS[1], ladder: "pitch" },
+  { field: "pitch.paragraph", id: MESSAGING_KIT_COPY_IDS[2], ladder: "pitch" },
+  { field: "boilerplate.short", id: MESSAGING_KIT_COPY_IDS[3], ladder: "boilerplate" },
+  { field: "boilerplate.medium", id: MESSAGING_KIT_COPY_IDS[4], ladder: "boilerplate" },
+  { field: "boilerplate.long", id: MESSAGING_KIT_COPY_IDS[5], ladder: "boilerplate" },
+];
+
+const LABELS: FieldLabels<"messaging-placeholder" | "messaging-blank"> = {
+  optionsSubject: "Messaging kit",
+  entrySubject: (id) => `Messaging kit entry "${id}"`,
+  placeholderReason: "messaging-placeholder",
+  blankReason: "messaging-blank",
+};
+
+/**
+ * Resolves the messaging kit from `registry`, under the six ids in
+ * `MESSAGING_KIT_COPY_IDS`. All six are attempted on every call and every
+ * issue is reported in id order, tagged with its `field`; `kit` and
+ * `resolutions` are returned only when there are no issues.
+ *
+ * `options` are `resolveCopyRef`'s (`target`, `acceptDelegateInProduction`,
+ * `now`) plus an optional `locale`, which is forwarded as the ref's locale
+ * rather than as an option. Malformed options produce an `"invalid-options"`
+ * issue per field. Pure apart from the clock read that `now` defaults to;
+ * the registry is not modified and no input makes this throw.
+ */
+export function resolveMessagingKit(
+  registry: CopyRegistry | unknown,
+  options?: MessagingKitOptions | unknown,
+): MessagingKitResolution {
+  const prepared = prepareOptions(options);
+  const issues: MessagingKitIssue[] = [];
+  const resolved: CopyResolution[] = [];
+  const words: (number | undefined)[] = [];
+  FIELDS.forEach(({ field, id, ladder }, index) => {
+    const outcome = resolveField(registry, field, id, prepared, LABELS);
+    issues.push(...outcome.issues);
+    const resolution = outcome.resolution;
+    if (resolution) resolved[index] = resolution;
+    words[index] = resolution ? countCopyWords(resolution.text) : undefined;
+
+    const previous = index - 1;
+    const before = previous >= 0 && FIELDS[previous]!.ladder === ladder ? words[previous] : undefined;
+    const current = words[index];
+    if (before !== undefined && current !== undefined && !(current > before)) {
+      issues.push({
+        reason: "messaging-ladder-order",
+        field,
+        id,
+        message: `Messaging kit entry "${id}" has ${current} words, which is not more than the ${before} of "${FIELDS[previous]!.id}".`,
+      });
+    }
+  });
+
+  if (issues.length > 0 || resolved.length !== FIELDS.length) return { complete: false, issues };
+  const [oneLiner, elevator, paragraph, short, medium, long] = resolved as [
+    CopyResolution,
+    CopyResolution,
+    CopyResolution,
+    CopyResolution,
+    CopyResolution,
+    CopyResolution,
+  ];
+  return {
+    complete: true,
+    kit: {
+      pitch: { oneLiner: oneLiner.text, elevator: elevator.text, paragraph: paragraph.text },
+      boilerplate: { short: short.text, medium: medium.text, long: long.text },
+    },
+    resolutions: {
+      pitch: { oneLiner, elevator, paragraph },
+      boilerplate: { short, medium, long },
+    },
+    issues: [],
+  };
+}

package/src/passage.ts

@@ -37,7 +37,8 @@
  *
  * This file ships no example content of anyone's real copy — the same
  * "vocabulary layer, never a source of real words" constraint `types.ts`
- * documents for `CopyEntry`/`CopyRecord`. Every fixture in this package's
+ * documents for `CopyEntry`/`CopyRecord` (its one exemption is the shipped
+ * front-door defaults, which this file does not touch). Every fixture in this package's
  * own tests is structural placeholder text, never something a product
  * would actually show a user.
  *

package/src/plan-authority.ts

@@ -0,0 +1,160 @@
+// Whether the bytes of an Advisor plan record authorize copy a delegate
+// approved on production (issue #1586). The plan's optional
+// `delegatedCopyApproval` declares that grant, and an approval binds the plan
+// it grants for: this reads the field only through a latest decision that
+// names the plan's own canonical digest. Two files define what is read, both
+// in the public repository, not shipped in this package: the plan contract,
+// docs/contracts/advisor-plan.json (see its DELEGATED COPY APPROVAL and
+// APPROVAL BINDING sections), and the digest definition,
+// docs/contracts/advisor-plan-digest.md.
+//
+// It is a pure function of the bytes: it reads no file, keeps nothing between
+// calls and never looks at the clock, because a plan approval has no expiry
+// of its own. It takes bytes, not a parsed object, because the digest is
+// defined only over a plan that was read strictly, and an object a caller
+// built can carry getters or proxies that answer validation, the digest and
+// the scope check differently. What it does not prove is who wrote the
+// decision, or where the bytes came from: see this package's README.
+
+import { readContractDocument } from "./generated/contract-schema.generated.js";
+import { planViolations } from "./plan-contract.js";
+import { digestOfValidPlan } from "./plan-digest.js";
+import type { PlanDocument } from "./plan-rules.js";
+
+/** Why a plan's bytes did not authorize delegate-approved copy on production. */
+export type PlanDelegateCopyRefusal =
+  /** The argument is not a `Uint8Array` (a Node `Buffer` is one). */
+  | "plan-not-bytes"
+  /** The bytes are not strict JSON: not valid UTF-8, a byte order mark, a syntax error, or a key repeated at any depth. */
+  | "plan-unreadable"
+  /** The plan does not validate against the plan contract, schema and code rules. */
+  | "plan-invalid"
+  /** The plan does not declare `delegatedCopyApproval`. */
+  | "delegated-copy-approval-absent"
+  | "no-decisions"
+  /** Defence in depth: a valid plan's decision times always parse. */
+  | "decision-time-unparseable"
+  /** A decision at the latest instant has not chosen "approved". */
+  | "latest-decision-not-approved"
+  /** A decision at the latest instant is an approval that names no sha256 digest. */
+  | "approval-without-subject-digest"
+  /** Decisions at the latest instant name different digests. */
+  | "latest-decisions-disagree"
+  /** The latest approval names a digest other than this plan's own. */
+  | "subject-digest-mismatch";
+
+/** What `planDelegateCopyAuthority()` decided. Frozen, and carries no plan text. */
+export type PlanDelegateCopyAuthority =
+  | {
+      readonly authorized: true;
+      /** The plan's canonical digest, which the latest approval names. */
+      readonly planDigest: string;
+      /** The plan's `delegatedCopyApproval.scopes`, copied; absent when the plan declares none, which covers every entry. */
+      readonly scopes?: readonly string[];
+    }
+  | {
+      readonly authorized: false;
+      readonly refusal: PlanDelegateCopyRefusal;
+      /** Only with "plan-invalid": each violation's rule and position, never a value. */
+      readonly violations?: readonly { readonly rule: string; readonly path: string }[];
+    };
+
+const SUBJECT_DIGEST = /^sha256:[0-9a-f]{64}$/;
+
+function refuse(refusal: PlanDelegateCopyRefusal, violations?: readonly { readonly rule: string; readonly path: string }[]): PlanDelegateCopyAuthority {
+  if (violations === undefined) return Object.freeze({ authorized: false, refusal });
+  return Object.freeze({ authorized: false, refusal, violations: Object.freeze(violations.map((violation) => Object.freeze({ rule: violation.rule, path: violation.path }))) });
+}
+
+/**
+ * The positions of the decisions made at the latest instant, by `at` and
+ * never by array position, in array order. Times are compared as instants
+ * (`Date.parse`), so `2026-09-21T00:00:00Z` and `2026-09-21T02:00:00+02:00`
+ * tie. Null when there are no decisions, or when any `at` does not parse to a
+ * finite time, because then time cannot say which is latest. Exported for
+ * tests, not from the package entry point.
+ */
+export function latestDecisionIndices(decisions: readonly { readonly at: string }[]): number[] | null {
+  if (decisions.length === 0) return null;
+  const times = decisions.map((decision) => Date.parse(decision.at));
+  if (!times.every(Number.isFinite)) return null;
+  // A reduce, not Math.max(...times): spreading a very long list into arguments throws a RangeError.
+  const latest = times.reduce((highest, time) => (time > highest ? time : highest), Number.NEGATIVE_INFINITY);
+  const indices: number[] = [];
+  times.forEach((time, index) => {
+    if (time === latest) indices.push(index);
+  });
+  return indices;
+}
+
+/** True for a real `Uint8Array` (a Node `Buffer` is one), never a `DataView`, another typed array or a proxy. */
+export function isPlanBytes(value: unknown): value is Uint8Array {
+  try {
+    return value instanceof Uint8Array && ArrayBuffer.isView(value);
+  } catch {
+    return false; // instanceof throws on a revoked proxy
+  }
+}
+
+/**
+ * Whether the bytes of a plan record authorize delegate-approved copy on
+ * production. Checks run in this order and the first that fails refuses:
+ *
+ * 1. the argument is a `Uint8Array` (`plan-not-bytes`);
+ * 2. the bytes are strict JSON (`plan-unreadable`);
+ * 3. the plan validates against the plan contract, R1-R12 included
+ *    (`plan-invalid`, with each violation's rule and position);
+ * 4. the plan declares `delegatedCopyApproval` (`delegated-copy-approval-absent`);
+ * 5-9. the plan's latest decision, found by time and never by array
+ *    position, has chosen "approved" and names one sha256 `subjectDigest`.
+ *    When several decisions share the latest instant, every one is examined:
+ *    the outcome does not depend on their order;
+ * 10. that digest equals the plan's own canonical digest, computed here from
+ *    the same bytes (`subject-digest-mismatch`). The digest covers
+ *    `delegatedCopyApproval`, so a declaration added, removed or edited after
+ *    the approval leaves the plan unapproved for this purpose.
+ *
+ * Never throws for a bad argument and never echoes plan text. The result and
+ * everything in it is frozen, and copied from the bytes, which are copied
+ * before they are read.
+ */
+export function planDelegateCopyAuthority(planBytes: Uint8Array | unknown): PlanDelegateCopyAuthority {
+  if (!isPlanBytes(planBytes)) return refuse("plan-not-bytes");
+  // A copy, so nothing the caller does to its buffer during or after this call changes what is read.
+  const bytes = new Uint8Array(planBytes);
+
+  let value: unknown;
+  try {
+    value = readContractDocument(bytes);
+  } catch {
+    return refuse("plan-unreadable");
+  }
+
+  const violations = planViolations(value);
+  if (violations.length > 0) return refuse("plan-invalid", violations);
+  const plan = value as PlanDocument;
+
+  if (!Object.hasOwn(plan, "delegatedCopyApproval")) return refuse("delegated-copy-approval-absent");
+  if (plan.decisions.length === 0) return refuse("no-decisions");
+
+  const latestIndices = latestDecisionIndices(plan.decisions);
+  if (latestIndices === null) return refuse("decision-time-unparseable");
+  const latest = latestIndices.map((index) => plan.decisions[index]!);
+  if (latest.some((decision) => decision.chosen !== "approved")) return refuse("latest-decision-not-approved");
+
+  const subjects = latest.map((decision) => (Object.hasOwn(decision, "subjectDigest") ? decision.subjectDigest : undefined));
+  if (subjects.some((subject) => typeof subject !== "string" || !SUBJECT_DIGEST.test(subject))) return refuse("approval-without-subject-digest");
+  if (subjects.some((subject) => subject !== subjects[0])) return refuse("latest-decisions-disagree");
+
+  let digest: string;
+  try {
+    digest = digestOfValidPlan(plan as unknown as Readonly<Record<string, unknown>>);
+  } catch {
+    return refuse("plan-invalid", []);
+  }
+  if (subjects[0] !== digest) return refuse("subject-digest-mismatch");
+
+  const declaration = plan.delegatedCopyApproval!;
+  if (!Object.hasOwn(declaration, "scopes") || declaration.scopes === undefined) return Object.freeze({ authorized: true, planDigest: digest });
+  return Object.freeze({ authorized: true, planDigest: digest, scopes: Object.freeze([...declaration.scopes]) });
+}

package/src/plan-contract.ts

@@ -0,0 +1,45 @@
+// Reads a plan record (issue #1586) against the shared plan contract
+// docs/contracts/advisor-plan.json -- in the public repository, not shipped in
+// this package. This package's build packs that contract into src/generated/
+// as plain data, with a generated copy of the one contract checker every
+// other reader of a plan also uses (packages/advisor/src/contract-schema.ts,
+// likewise in the public repository, not shipped in this package), so
+// Writer validates against the same definition with no runtime dependency on
+// any other package.
+
+import { ADVISOR_PLAN_CONTRACT } from "./generated/advisor-plan-contract.generated.js";
+import { formatContractViolation, validateAgainstContract } from "./generated/contract-schema.generated.js";
+import { planRuleViolations } from "./plan-rules.js";
+import type { PlanDocument, PlanRuleId } from "./plan-rules.js";
+
+/** One reason a plan is refused: `rule` is "schema" for the contract's keywords, else the code rule's id. */
+export interface PlanViolation {
+  readonly rule: "schema" | PlanRuleId;
+  /** The field at fault, like `staffing[1].repository`, or "" for the document itself. */
+  readonly path: string;
+  /** The whole message, starting with `plan` and the path; it never quotes a value. */
+  readonly message: string;
+}
+
+/** The plan contract refers to no other contract file, so every name is refused. */
+function refuseEveryName(name: string): never {
+  throw new Error(`the plan contract refers to no other contract, but the checker asked for ${JSON.stringify(name)}`);
+}
+
+/**
+ * Every reason `value` is not a valid plan: the plan contract's schema, then,
+ * once that passes, its code rules R1-R12. Empty means valid. Never throws
+ * for a bad value, and no message echoes a value from the plan.
+ */
+export function planViolations(value: unknown): PlanViolation[] {
+  const schema = validateAgainstContract(ADVISOR_PLAN_CONTRACT, value, refuseEveryName);
+  if (schema.length > 0) {
+    return schema.map((violation) => ({ rule: "schema", path: violation.path, message: formatContractViolation("plan", violation) }));
+  }
+  // The code rules relate fields to one another, so they run only on a plan whose shape is known good.
+  return planRuleViolations(value as PlanDocument).map((violation) => ({
+    rule: violation.rule,
+    path: violation.path,
+    message: `plan.${violation.path} ${violation.message} (rule ${violation.rule})`,
+  }));
+}

package/src/plan-digest.ts

@@ -0,0 +1,81 @@
+// The canonical plan digest (issue #1586), implemented from its one
+// definition, docs/contracts/advisor-plan-digest.md -- in the public repository, not shipped in this package.
+// An approval binds this value, so it names exactly which plan was approved.
+// Every other reader of a plan implements the same definition separately, and
+// each is tested against the same fixture corpus,
+// docs/contracts/advisor-plan-digest.fixture.json (likewise in the public repository, not shipped in this package),
+// so all of them compute identical digests.
+// This is a third, separate reading of RFC 8785: strings go through
+// JSON.stringify, whose output for well-formed text is exactly the escaping
+// RFC 8785 requires, with a lone surrogate refused before it.
+
+import { createHash } from "node:crypto";
+import { planViolations } from "./plan-contract.js";
+
+/** The top-level plan members the digest leaves out: when the file was written, and the decisions an approval is recorded in. */
+export const PLAN_DIGEST_EXCLUDED_FIELDS: readonly string[] = ["asOf", "decisions"];
+
+const LONE_SURROGATE_CHECK = /[\uD800-\uDFFF]/u;
+
+/** A string as RFC 8785 writes it. Throws on a string that is not well-formed Unicode. */
+function canonicalString(text: string): string {
+  if (LONE_SURROGATE_CHECK.test(text)) throw new TypeError("canonical JSON refuses a string that is not well-formed Unicode (a lone surrogate)");
+  return JSON.stringify(text);
+}
+
+/**
+ * RFC 8785 (JSON Canonicalization Scheme) serialization: no whitespace,
+ * object members sorted by UTF-16 code units, strings escaped only where
+ * JSON requires, numbers as ECMAScript writes them. Throws on anything JSON
+ * cannot carry (undefined, a function, a bigint, a non-finite number, a hole
+ * in an array) and on a lone surrogate, rather than silently dropping or
+ * repairing it.
+ */
+export function canonicalJson(value: unknown): string {
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "boolean":
+      return value ? "true" : "false";
+    case "number":
+      if (!Number.isFinite(value)) throw new TypeError("canonical JSON refuses a non-finite number");
+      return String(value);
+    case "string":
+      return canonicalString(value);
+    case "object": {
+      if (Array.isArray(value)) {
+        const items: string[] = [];
+        for (let index = 0; index < value.length; index += 1) items.push(canonicalJson(value[index]));
+        return `[${items.join(",")}]`;
+      }
+      const record = value as Record<string, unknown>;
+      // The default sort compares UTF-16 code units, which is the order RFC 8785 requires.
+      const members = Object.keys(record)
+        .sort()
+        .map((key) => `${canonicalString(key)}:${canonicalJson(record[key])}`);
+      return `{${members.join(",")}}`;
+    }
+    default:
+      throw new TypeError(`canonical JSON refuses a value of type ${typeof value}`);
+  }
+}
+
+/**
+ * `sha256:` and the lowercase hex SHA-256 of the canonical JSON of a plan
+ * without `asOf` and `decisions`. Assumes `plan` already passed
+ * `planViolations()`: it checks nothing itself.
+ */
+export function digestOfValidPlan(plan: Readonly<Record<string, unknown>>): string {
+  const subject: Record<string, unknown> = {};
+  for (const key of Object.keys(plan)) if (!PLAN_DIGEST_EXCLUDED_FIELDS.includes(key)) subject[key] = plan[key];
+  return `sha256:${createHash("sha256").update(canonicalJson(subject), "utf8").digest("hex")}`;
+}
+
+/**
+ * The plan digest. Throws when the plan does not validate against the plan
+ * contract, rules included: an invalid plan has no digest.
+ */
+export function planDigest(plan: unknown): string {
+  const violations = planViolations(plan);
+  if (violations.length > 0) throw new TypeError(`an invalid plan has no digest: ${violations.map((violation) => violation.message).join("; ")}`);
+  return digestOfValidPlan(plan as Readonly<Record<string, unknown>>);
+}