@ontrails/regrade 0.2.0

package/src/downstream/vocabulary.ts

@@ -0,0 +1,3094 @@
+import {
+  InternalError,
+  Result,
+  ValidationError,
+  escapeRegExp,
+  isPlainObject,
+  matchesAnyPathGlob,
+} from '@ontrails/core';
+import { parseWithDiagnostics } from '@ontrails/source';
+import type { SourceComment } from '@ontrails/source';
+import { createHash } from 'node:crypto';
+import {
+  dirname,
+  extname,
+  isAbsolute,
+  join,
+  normalize,
+  relative,
+} from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { z } from 'zod';
+
+import {
+  DEFAULT_IGNORED_DIRECTORIES,
+  collectDownstreamSources,
+} from './collect.js';
+import type { DownstreamCollectionOptions, SkippedSource } from './collect.js';
+import type {
+  PreparedRegradeRunIdentity,
+  RegradeApplySummary,
+  RegradeReport,
+  RegradeReportEntry,
+} from './report.js';
+import { buildRegradeScanSummary } from './scan-summary.js';
+
+export type VocabularyVerdict = 'applied' | 'deferred' | 'modified' | 'skipped';
+
+export type VocabularyOccurrenceSourceKind = 'source-comment' | 'tsdoc';
+
+export const vocabularyDispositionValues = [
+  'code-context-out-of-engine',
+  'docs-only',
+  'explicit-preserve',
+  'forward-pointer',
+  'historical-by-policy',
+  'ignored-by-scope',
+  'in-family-modified',
+  'in-family-unresolved',
+  'out-of-family',
+  'preserve-current-live-api',
+] as const;
+
+export type VocabularyDisposition =
+  (typeof vocabularyDispositionValues)[number];
+
+const vocabularyDispositions = new Set<string>(vocabularyDispositionValues);
+
+export interface VocabularyPreserveRule {
+  readonly disposition?: VocabularyDisposition;
+  readonly forms?: readonly string[];
+  readonly pattern: string;
+  readonly reason?: string;
+  readonly paths?: readonly string[];
+}
+
+export interface VocabularyPreserveInventoryEntry extends VocabularyPreserveRule {
+  readonly evidence: readonly string[];
+  readonly source: 'derived-live-api';
+}
+
+export interface VocabularyScopePolicy {
+  readonly disposition: VocabularyDisposition;
+  readonly expectMatches?: boolean | undefined;
+  readonly paths: readonly string[];
+  readonly reason: string;
+}
+
+export type VocabularyScopeTier = 'in-scope' | 'policy-classified';
+
+export interface VocabularyRegradeScope {
+  readonly exclude?: readonly string[];
+  readonly extensions?: readonly string[];
+  /**
+   * @deprecated Use `exclude` path globs for new plans. This remains as a
+   * compatibility bridge for pre-path-scope plans that intentionally disabled
+   * the collector's default directory pruning.
+   */
+  readonly ignoredDirectories?: readonly string[];
+  readonly include?: readonly string[];
+  readonly policyClassified?: readonly VocabularyScopePolicy[];
+  readonly teachingSurfaces?: readonly string[];
+}
+
+/**
+ * One authored root-relative file move in a vocabulary plan.
+ *
+ * @example
+ * ```ts
+ * const rename: VocabularyFileRename = {
+ *   from: 'docs/old.md',
+ *   to: 'docs/new.md',
+ * };
+ * ```
+ */
+export interface VocabularyFileRename {
+  readonly from: string;
+  readonly to: string;
+}
+
+/**
+ * Derived reference-closure totals for one governed file move.
+ *
+ * @example
+ * ```ts
+ * console.log(evidence.rewritten, evidence.historical);
+ * ```
+ */
+export interface VocabularyFileRenameEvidence extends VocabularyFileRename {
+  readonly deferred: number;
+  readonly historical: number;
+  readonly preserved: number;
+  readonly rewritten: number;
+  readonly skipped: number;
+}
+
+/**
+ * One deterministic form proposal synthesized from a vocabulary seed.
+ *
+ * @example
+ * ```ts
+ * const proposal: VocabularyFormProposal = {
+ *   from: 'legacies',
+ *   kind: 'safe-rewrite',
+ *   reason: 'default-morphology',
+ *   source: 'default-morphology',
+ *   to: 'currents',
+ * };
+ * ```
+ */
+export interface VocabularyFormProposal {
+  readonly from: string;
+  readonly kind: 'review' | 'safe-rewrite';
+  readonly reason: string;
+  readonly source:
+    | 'default-morphology'
+    | 'plan-defer'
+    | 'plan-override'
+    | 'seed';
+  readonly to?: string;
+}
+
+export interface VocabularyRegradePlan {
+  readonly caseSensitive?: boolean;
+  readonly deferForms?: readonly string[];
+  readonly fileRenames?: readonly VocabularyFileRename[];
+  readonly from: string;
+  readonly id?: string;
+  readonly intent?: string;
+  readonly kind: 'vocabulary';
+  readonly overrides?: Readonly<Record<string, string>>;
+  readonly preserve?: readonly VocabularyPreserveRule[];
+  readonly scope?: VocabularyRegradeScope;
+  readonly to: string;
+}
+
+export interface VocabularyOccurrence {
+  readonly column: number;
+  readonly context: string;
+  readonly disposition: VocabularyDisposition;
+  readonly end: number;
+  readonly form: string;
+  readonly line: number;
+  readonly path: string;
+  readonly reason: string;
+  readonly replacement?: string;
+  readonly start: number;
+  readonly scopeTier: VocabularyScopeTier;
+  readonly sourceKind?: VocabularyOccurrenceSourceKind;
+  readonly verdict: VocabularyVerdict;
+}
+
+export interface VocabularyRunLedger {
+  readonly cycle: number;
+  readonly forms: Readonly<Record<string, VocabularyVerdict>>;
+  readonly occurrences: readonly VocabularyOccurrence[];
+}
+
+export interface VocabularyRunGate {
+  readonly remaining: number;
+  readonly remainingByDisposition: Partial<
+    Readonly<Record<VocabularyDisposition, number>>
+  >;
+  readonly reasons: readonly string[];
+  readonly status: 'green' | 'open';
+}
+
+export interface VocabularyRunReport {
+  readonly applied: number;
+  readonly deferred: number;
+  readonly dispositions: Partial<
+    Readonly<Record<VocabularyDisposition, number>>
+  >;
+  readonly filesChanged: number;
+  readonly fileRenames?: readonly VocabularyFileRenameEvidence[];
+  readonly gate: VocabularyRunGate;
+  readonly modified: number;
+  readonly open: number;
+  readonly skipped: number;
+  readonly scopeTiers: Readonly<Record<VocabularyScopeTier, number>>;
+  readonly teachingSurfaces: {
+    readonly expected: readonly string[];
+    readonly missing: readonly string[];
+    readonly touched: readonly string[];
+  };
+}
+
+export interface VocabularyRegradeRun {
+  readonly ledger: VocabularyRunLedger;
+  readonly plan: VocabularyRegradePlan;
+  readonly preserveInventory?: readonly VocabularyPreserveInventoryEntry[];
+  readonly report: VocabularyRunReport;
+}
+
+export const VOCABULARY_TRANSITION_RECORD_SCHEMA_VERSION = 1;
+
+export interface VocabularyTransitionRecordEnvironment {
+  readonly commitSha?: string;
+  readonly engineVersion?: string;
+  readonly graphHash?: string;
+  readonly root: string;
+}
+
+export interface VocabularyTransitionRecord {
+  readonly environment: VocabularyTransitionRecordEnvironment;
+  readonly kind: 'vocabulary-transition-record';
+  readonly recordPath: string;
+  readonly report: Omit<RegradeReport, 'record'>;
+  readonly schemaVersion: typeof VOCABULARY_TRANSITION_RECORD_SCHEMA_VERSION;
+  readonly transition: {
+    readonly from: string;
+    readonly id: string;
+    readonly to: string;
+  };
+}
+
+export interface VocabularyTransitionRecordSummary {
+  readonly path: string;
+  readonly schemaVersion: typeof VOCABULARY_TRANSITION_RECORD_SCHEMA_VERSION;
+  readonly status: 'candidate' | 'applied' | 'checked';
+}
+
+interface SourceFile {
+  readonly absolutePath: string;
+  readonly path: string;
+  readonly source: string;
+  readonly sourceBytes: string;
+}
+
+interface SourceOccurrence extends VocabularyOccurrence {
+  readonly absolutePath: string;
+}
+
+type VocabularySourceKind = 'all' | 'comments';
+
+const sourceCommentKind = (
+  file: SourceFile,
+  comment: SourceComment
+): VocabularyOccurrenceSourceKind =>
+  comment.type === 'Block' && file.source.startsWith('/**', comment.start)
+    ? 'tsdoc'
+    : 'source-comment';
+
+interface SourceOccurrenceDraft extends Omit<
+  SourceOccurrence,
+  'disposition' | 'reason' | 'scopeTier' | 'verdict'
+> {
+  readonly contextColumn: number;
+}
+
+interface VocabularyEvaluation {
+  readonly entries: readonly RegradeReportEntry[];
+  readonly occurrences: readonly SourceOccurrence[];
+  readonly scanned: number;
+  readonly skipped: readonly SkippedSource[];
+  readonly run: VocabularyRegradeRun;
+}
+
+const VOCABULARY_SOURCE_EXTENSIONS = Object.freeze([
+  '.js',
+  '.jsx',
+  '.json',
+  '.jsonc',
+  '.md',
+  '.mdx',
+  '.mjs',
+  '.ts',
+  '.tsx',
+  '.txt',
+  '.yaml',
+  '.yml',
+]);
+
+const uniqueSorted = (values: readonly string[]): readonly string[] =>
+  [...new Set(values)].toSorted((a, b) => a.localeCompare(b));
+
+const vocabularyDispositionCounts = (
+  occurrences: readonly VocabularyOccurrence[]
+): Partial<Readonly<Record<VocabularyDisposition, number>>> => {
+  const counts = new Map<VocabularyDisposition, number>();
+  for (const occurrence of occurrences) {
+    counts.set(
+      occurrence.disposition,
+      (counts.get(occurrence.disposition) ?? 0) + 1
+    );
+  }
+  return Object.fromEntries(
+    [...counts.entries()].toSorted(([left], [right]) =>
+      left.localeCompare(right)
+    )
+  );
+};
+
+const vocabularyFormVerdicts = (
+  occurrences: readonly VocabularyOccurrence[]
+): Readonly<Record<string, VocabularyVerdict>> => {
+  const priority: Readonly<Record<VocabularyVerdict, number>> = {
+    applied: 1,
+    deferred: 3,
+    modified: 2,
+    skipped: 0,
+  };
+  const forms: Record<string, VocabularyVerdict> = {};
+  for (const occurrence of occurrences) {
+    if (occurrence.verdict === 'applied') {
+      continue;
+    }
+    const current = forms[occurrence.form];
+    if (
+      current === undefined ||
+      priority[occurrence.verdict] > priority[current]
+    ) {
+      forms[occurrence.form] = occurrence.verdict;
+    }
+  }
+  return forms;
+};
+
+const vocabularyScopeTierCounts = (
+  occurrences: readonly VocabularyOccurrence[]
+): Readonly<Record<VocabularyScopeTier, number>> => ({
+  'in-scope': occurrences.filter(
+    (occurrence) => occurrence.scopeTier === 'in-scope'
+  ).length,
+  'policy-classified': occurrences.filter(
+    (occurrence) => occurrence.scopeTier === 'policy-classified'
+  ).length,
+});
+
+const vocabularyScopeEvidence = (
+  plan: VocabularyRegradePlan,
+  occurrences: readonly VocabularyOccurrence[]
+): {
+  readonly gateReasons: readonly string[];
+  readonly scopeTiers: Readonly<Record<VocabularyScopeTier, number>>;
+  readonly teachingSurfaces: VocabularyRunReport['teachingSurfaces'];
+} => {
+  const expected = uniqueSorted(plan.scope?.teachingSurfaces ?? []);
+  const touched = expected.filter((pattern) =>
+    occurrences.some(
+      (occurrence) =>
+        occurrence.scopeTier === 'in-scope' &&
+        matchesAnyPathGlob(occurrence.path, [pattern])
+    )
+  );
+  const missing = expected.filter((pattern) => !touched.includes(pattern));
+  const expectedPolicyMissing =
+    plan.scope?.policyClassified?.some(
+      (policy) =>
+        policy.expectMatches === true &&
+        !occurrences.some(
+          (occurrence) =>
+            occurrence.scopeTier === 'policy-classified' &&
+            matchesAnyPathGlob(occurrence.path, policy.paths)
+        )
+    ) ?? false;
+  return {
+    gateReasons: [
+      ...(expectedPolicyMissing
+        ? ['expected-policy-classified-evidence-missing']
+        : []),
+      ...(missing.length === 0 ? [] : ['expected-teaching-surfaces-missing']),
+    ],
+    scopeTiers: vocabularyScopeTierCounts(occurrences),
+    teachingSurfaces: { expected, missing, touched },
+  };
+};
+
+const isVocabularyTokenCharacter = (
+  value: string,
+  routeLike: boolean
+): boolean => /[A-Za-z0-9_$-]/.test(value) || (routeLike && value === '/');
+
+const isVocabularyTokenCharacterAt = (
+  source: string,
+  index: number,
+  routeLike: boolean
+): boolean => {
+  if (index < 0 || index >= source.length) {
+    return false;
+  }
+  const value = source.at(index) ?? '';
+  if (isVocabularyTokenCharacter(value, routeLike)) {
+    return true;
+  }
+  if (!routeLike || value !== '.') {
+    return false;
+  }
+  return (
+    isVocabularyTokenCharacter(source.at(index - 1) ?? '', false) &&
+    isVocabularyTokenCharacter(source.at(index + 1) ?? '', false)
+  );
+};
+
+const hasWordBoundary = (
+  source: string,
+  start: number,
+  end: number,
+  form: string
+): boolean => {
+  const routeLike = form.includes('/');
+  return (
+    !isVocabularyTokenCharacterAt(source, start - 1, routeLike) &&
+    !isVocabularyTokenCharacterAt(source, end, routeLike)
+  );
+};
+
+const expandVocabularyNeighborSpan = (
+  source: string,
+  start: number,
+  end: number,
+  form: string
+): { readonly end: number; readonly start: number } => {
+  const routeLike = form.includes('/');
+  let expandedStart = start;
+  while (
+    expandedStart > 0 &&
+    isVocabularyTokenCharacterAt(source, expandedStart - 1, routeLike)
+  ) {
+    expandedStart -= 1;
+  }
+
+  let expandedEnd = end;
+  while (
+    expandedEnd < source.length &&
+    isVocabularyTokenCharacterAt(source, expandedEnd, routeLike)
+  ) {
+    expandedEnd += 1;
+  }
+
+  return { end: expandedEnd, start: expandedStart };
+};
+
+const lineColumnForOffset = (
+  source: string,
+  offset: number
+): { readonly column: number; readonly line: number } => {
+  let line = 1;
+  let column = 1;
+  for (let index = 0; index < offset; index += 1) {
+    const codePoint = source.codePointAt(index);
+    if (
+      codePoint === 10 ||
+      codePoint === 13 ||
+      codePoint === 0x20_28 ||
+      codePoint === 0x20_29
+    ) {
+      if (codePoint === 13 && source.codePointAt(index + 1) === 10) {
+        index += 1;
+      }
+      line += 1;
+      column = 1;
+    } else {
+      column += 1;
+    }
+  }
+  return { column, line };
+};
+
+const contextDetailsForOffset = (
+  source: string,
+  start: number,
+  end: number
+): { readonly context: string; readonly contextColumn: number } => {
+  let lineStart = start;
+  while (lineStart > 0) {
+    const codePoint = source.codePointAt(lineStart - 1);
+    if (
+      codePoint === 10 ||
+      codePoint === 13 ||
+      codePoint === 0x20_28 ||
+      codePoint === 0x20_29
+    ) {
+      break;
+    }
+    lineStart -= 1;
+  }
+  let lineEnd = end;
+  while (lineEnd < source.length) {
+    const codePoint = source.codePointAt(lineEnd);
+    if (
+      codePoint === 10 ||
+      codePoint === 13 ||
+      codePoint === 0x20_28 ||
+      codePoint === 0x20_29
+    ) {
+      break;
+    }
+    lineEnd += 1;
+  }
+  const rawLine = source.slice(lineStart, lineEnd);
+  const leadingTrimmed = rawLine.length - rawLine.trimStart().length;
+  return {
+    context: rawLine.trim(),
+    contextColumn: start - lineStart - leadingTrimmed + 1,
+  };
+};
+
+const isMarkdownPath = (path: string): boolean =>
+  path.endsWith('.md') || path.endsWith('.mdx');
+
+const packageRouteCodeExtensions = new Set([
+  '.cjs',
+  '.cts',
+  '.js',
+  '.jsx',
+  '.mjs',
+  '.mts',
+  '.ts',
+  '.tsx',
+]);
+
+const isPackageRouteCodeOccurrence = (path: string, form: string): boolean =>
+  packageRouteCodeExtensions.has(extname(path)) &&
+  /^@[^/]+\/[^/]+(?:\/.*)?$/.test(form);
+
+const isPackageManifestPath = (path: string): boolean =>
+  path === 'package.json' || path.endsWith('/package.json');
+
+const sourceLineBoundsForOffset = (
+  source: string,
+  start: number,
+  end: number
+): { readonly lineEnd: number; readonly lineStart: number } => {
+  const lineStart = source.lastIndexOf('\n', start - 1) + 1;
+  const nextLine = source.indexOf('\n', end);
+  return { lineEnd: nextLine === -1 ? source.length : nextLine, lineStart };
+};
+
+const markdownBacktickRuns = (value: string): readonly RegExpMatchArray[] => [
+  ...value.matchAll(/(?<!\\)`+/g),
+];
+
+const isMarkdownInlineCodeContext = (
+  source: string,
+  start: number,
+  end: number
+): boolean => {
+  const { lineEnd, lineStart } = sourceLineBoundsForOffset(source, start, end);
+  const line = source.slice(lineStart, lineEnd);
+  const relativeStart = start - lineStart;
+  const relativeEnd = end - lineStart;
+  let openRun: { readonly length: number; readonly start: number } | undefined;
+
+  for (const run of markdownBacktickRuns(line)) {
+    const runStart = run.index ?? 0;
+    const [value] = run;
+    const runLength = value.length;
+    if (openRun === undefined) {
+      openRun = { length: runLength, start: runStart };
+      continue;
+    }
+    if (runLength !== openRun.length) {
+      continue;
+    }
+    if (
+      openRun.start + openRun.length <= relativeStart &&
+      relativeEnd <= runStart
+    ) {
+      return true;
+    }
+    openRun = undefined;
+  }
+
+  return false;
+};
+
+const markdownFenceLinePattern = /^\s*(?:>\s*){0,8}(```|~~~)/;
+
+const isMarkdownFenceContext = (source: string, start: number): boolean => {
+  const before = source.slice(0, start);
+  let fenced = false;
+  for (const line of before.split('\n')) {
+    if (markdownFenceLinePattern.test(line)) {
+      fenced = !fenced;
+    }
+  }
+  return fenced;
+};
+
+const isMarkdownCodeContext = (
+  file: SourceFile,
+  start: number,
+  end: number
+): boolean =>
+  isMarkdownPath(file.path) &&
+  (isMarkdownInlineCodeContext(file.source, start, end) ||
+    isMarkdownFenceContext(file.source, start));
+
+const vocabularyOccurrenceReason = (
+  preserveRule: VocabularyPreserveRule | undefined,
+  markdownCodeContext: boolean,
+  defaultReason: string
+): string => {
+  if (preserveRule !== undefined) {
+    return preserveRule.reason ?? 'preserved-by-plan';
+  }
+  if (markdownCodeContext) {
+    return 'markdown-code-context';
+  }
+  return defaultReason;
+};
+
+const capturedVocabularyVerdict = (
+  preserveRule: VocabularyPreserveRule | undefined,
+  markdownCodeContext: boolean
+): VocabularyVerdict => {
+  if (preserveRule !== undefined) {
+    return 'skipped';
+  }
+  if (markdownCodeContext) {
+    return 'deferred';
+  }
+  return 'modified';
+};
+
+const vocabularyOccurrenceDisposition = (
+  verdict: VocabularyVerdict,
+  preserveRule: VocabularyPreserveRule | undefined,
+  markdownCodeContext: boolean
+): VocabularyDisposition => {
+  if (preserveRule !== undefined) {
+    return preserveRule.disposition ?? 'explicit-preserve';
+  }
+  if (markdownCodeContext) {
+    return 'code-context-out-of-engine';
+  }
+  if (verdict === 'modified') {
+    return 'in-family-modified';
+  }
+  return 'in-family-unresolved';
+};
+
+const preserveCase = (sourceForm: string, replacement: string): string => {
+  if (sourceForm.toUpperCase() === sourceForm) {
+    return replacement.toUpperCase();
+  }
+  const first = sourceForm.at(0);
+  if (first !== undefined && first.toUpperCase() === first) {
+    return replacement.at(0)?.toUpperCase() + replacement.slice(1);
+  }
+  return replacement;
+};
+
+const isSimpleVocabularyWord = (value: string): boolean =>
+  /^[A-Za-z]+$/.test(value);
+
+const endsWithConsonantY = (value: string): boolean => {
+  const penultimate = value.at(-2);
+  return (
+    value.endsWith('y') &&
+    penultimate !== undefined &&
+    !/[aeiou]/.test(penultimate)
+  );
+};
+
+const pluralize = (value: string): string => {
+  const lower = value.toLowerCase();
+  let lowerForm: string;
+  if (endsWithConsonantY(lower)) {
+    lowerForm = `${lower.slice(0, -1)}ies`;
+  } else if (
+    lower.endsWith('s') ||
+    lower.endsWith('x') ||
+    lower.endsWith('ch')
+  ) {
+    lowerForm = `${lower}es`;
+  } else {
+    lowerForm = `${lower}s`;
+  }
+  return preserveCase(value, lowerForm);
+};
+
+const pastTenseForm = (value: string): string => {
+  const lower = value.toLowerCase();
+  let lowerForm: string;
+  if (endsWithConsonantY(lower)) {
+    lowerForm = `${lower.slice(0, -1)}ied`;
+  } else if (lower.endsWith('e')) {
+    lowerForm = `${lower}d`;
+  } else {
+    lowerForm = `${lower}ed`;
+  }
+  return preserveCase(value, lowerForm);
+};
+
+const presentParticipleForm = (value: string): string => {
+  const lower = value.toLowerCase();
+  let lowerForm: string;
+  if (lower.endsWith('ie')) {
+    lowerForm = `${lower.slice(0, -2)}ying`;
+  } else if (lower.endsWith('e') && !lower.endsWith('ee')) {
+    lowerForm = `${lower.slice(0, -1)}ing`;
+  } else {
+    lowerForm = `${lower}ing`;
+  }
+  return preserveCase(value, lowerForm);
+};
+
+const defaultDeferredVocabularyForms = (from: string): readonly string[] => {
+  if (!isSimpleVocabularyWord(from)) {
+    return [];
+  }
+  return uniqueSorted([
+    pastTenseForm(from),
+    presentParticipleForm(from),
+  ]).filter((form) => form !== from && form !== pluralize(from));
+};
+
+const defaultVocabularyForms = (from: string, to: string) => {
+  const forms = new Map<string, string>([[from, to]]);
+  if (isSimpleVocabularyWord(from) && isSimpleVocabularyWord(to)) {
+    forms.set(pluralize(from), pluralize(to));
+  }
+  return forms;
+};
+
+const normalizedOverrideEntries = (
+  overrides: Readonly<Record<string, string>> | undefined
+): readonly [string, string][] =>
+  Object.entries(overrides ?? {}).toSorted(([left], [right]) =>
+    left.localeCompare(right)
+  );
+
+const formIdentityForPlan = (
+  plan: VocabularyRegradePlan,
+  form: string
+): string => (plan.caseSensitive === true ? form : form.toLowerCase());
+
+const targetFormsForPlan = (
+  plan: VocabularyRegradePlan
+): Map<string, string> => {
+  const forms = defaultVocabularyForms(plan.from, plan.to);
+  for (const [form, replacement] of normalizedOverrideEntries(plan.overrides)) {
+    forms.set(form, replacement);
+  }
+  return forms;
+};
+
+export const vocabularyRewriteFormsForPlan = (
+  plan: VocabularyRegradePlan
+): readonly (readonly [string, string])[] => [...targetFormsForPlan(plan)];
+
+const deferFormsForPlan = (plan: VocabularyRegradePlan): readonly string[] => {
+  const overrideForms = new Set(
+    normalizedOverrideEntries(plan.overrides).map(([form]) =>
+      formIdentityForPlan(plan, form)
+    )
+  );
+  return uniqueSorted([
+    ...defaultDeferredVocabularyForms(plan.from).filter(
+      (form) => !overrideForms.has(formIdentityForPlan(plan, form))
+    ),
+    ...(plan.deferForms ?? []),
+  ]);
+};
+
+const titleCaseVocabularyForm = (form: string): string => {
+  const first = form.at(0);
+  return first === undefined ? form : `${first.toUpperCase()}${form.slice(1)}`;
+};
+
+const commentReviewPlan = (
+  plan: VocabularyRegradePlan
+): VocabularyRegradePlan => ({
+  ...plan,
+  deferForms: uniqueSorted([
+    ...(plan.deferForms ?? []),
+    ...(plan.deferForms ?? []).map(titleCaseVocabularyForm),
+  ]),
+});
+
+/**
+ * Synthesize the deterministic form proposal carried by a minimal plan seed.
+ *
+ * @example
+ * ```ts
+ * const forms = deriveVocabularyFormProposals({
+ *   from: 'legacy',
+ *   kind: 'vocabulary',
+ *   to: 'current',
+ * });
+ * ```
+ */
+export const deriveVocabularyFormProposals = (
+  plan: VocabularyRegradePlan
+): readonly VocabularyFormProposal[] => {
+  const overrideForms = new Set(Object.keys(plan.overrides ?? {}));
+  const explicitDefers = new Set(
+    (plan.deferForms ?? []).map((form) => formIdentityForPlan(plan, form))
+  );
+  const safeProposals = [...targetFormsForPlan(plan).entries()].flatMap(
+    ([from, to]): readonly VocabularyFormProposal[] => {
+      if (explicitDefers.has(formIdentityForPlan(plan, from))) {
+        return [];
+      }
+      if (from === plan.from) {
+        return [
+          {
+            from,
+            kind: 'safe-rewrite',
+            reason: 'minimal-seed',
+            source: 'seed',
+            to,
+          },
+        ];
+      }
+      if (overrideForms.has(from)) {
+        return [
+          {
+            from,
+            kind: 'safe-rewrite',
+            reason: 'authored-or-governed-override',
+            source: 'plan-override',
+            to,
+          },
+        ];
+      }
+      return [
+        {
+          from,
+          kind: 'safe-rewrite',
+          reason: 'default-morphology',
+          source: 'default-morphology',
+          to,
+        },
+      ];
+    }
+  );
+  const casingProposals: VocabularyFormProposal[] = [];
+  if (isSimpleVocabularyWord(plan.from) && isSimpleVocabularyWord(plan.to)) {
+    const from = `${plan.from.slice(0, 1).toUpperCase()}${plan.from.slice(1)}`;
+    const to = `${plan.to.slice(0, 1).toUpperCase()}${plan.to.slice(1)}`;
+    if (from !== plan.from && !explicitDefers.has(from)) {
+      casingProposals.push({
+        from,
+        kind: 'review',
+        reason: 'uncertain-casing-or-public-name',
+        source: 'default-morphology',
+        to,
+      });
+    }
+  }
+  return [
+    ...safeProposals,
+    ...casingProposals,
+    ...deferFormsForPlan(plan).map((from) => ({
+      from,
+      kind: 'review' as const,
+      reason: explicitDefers.has(from)
+        ? 'authored-or-governed-defer'
+        : 'uncertain-morphology',
+      source: explicitDefers.has(from)
+        ? ('plan-defer' as const)
+        : ('default-morphology' as const),
+    })),
+  ].toSorted((left, right) =>
+    left.from === right.from
+      ? left.kind.localeCompare(right.kind)
+      : left.from.localeCompare(right.from)
+  );
+};
+
+const validateVocabularyScope = (
+  scope: VocabularyRegradeScope | undefined
+): Result<void, ValidationError> => {
+  const excludedDocsPattern = scope?.exclude?.find(
+    (pattern) =>
+      /(^|\/)docs(?:\/|$)/.test(pattern) ||
+      matchesAnyPathGlob('docs/regrade-teaching.md', [pattern]) ||
+      matchesAnyPathGlob('docs/regrade-teaching.mdx', [pattern])
+  );
+  if (excludedDocsPattern !== undefined) {
+    return Result.err(
+      new ValidationError(
+        `Vocabulary Regrade plans cannot hard-exclude docs with "${excludedDocsPattern}"; use a policyClassified rule with a reason.`
+      )
+    );
+  }
+  for (const policy of scope?.policyClassified ?? []) {
+    if (policy.paths.length === 0 || policy.reason.trim().length === 0) {
+      return Result.err(
+        new ValidationError(
+          'Vocabulary Regrade policyClassified rules require paths and a reason.'
+        )
+      );
+    }
+    const excludedPolicyPath = policy.paths.find((policyPath) =>
+      scope?.exclude?.some(
+        (excludedPath) =>
+          excludedPath === policyPath ||
+          matchesAnyPathGlob(policyPath, [excludedPath]) ||
+          matchesAnyPathGlob(excludedPath, [policyPath])
+      )
+    );
+    if (excludedPolicyPath !== undefined) {
+      return Result.err(
+        new ValidationError(
+          `Vocabulary Regrade scope cannot both exclude and policy-classify "${excludedPolicyPath}".`
+        )
+      );
+    }
+  }
+  return Result.ok();
+};
+
+const validateVocabularyPlan = (
+  plan: VocabularyRegradePlan
+): Result<void, ValidationError> => {
+  if (plan.from.trim().length === 0) {
+    return Result.err(
+      new ValidationError('Vocabulary Regrade plan `from` cannot be empty.')
+    );
+  }
+  if (plan.to.trim().length === 0) {
+    return Result.err(
+      new ValidationError('Vocabulary Regrade plan `to` cannot be empty.')
+    );
+  }
+  for (const [form, replacement] of normalizedOverrideEntries(plan.overrides)) {
+    if (form.trim().length === 0) {
+      return Result.err(
+        new ValidationError(
+          'Vocabulary Regrade plan override keys cannot be empty.'
+        )
+      );
+    }
+    if (replacement.trim().length === 0) {
+      return Result.err(
+        new ValidationError(
+          `Vocabulary Regrade plan override "${form}" cannot map to an empty replacement.`
+        )
+      );
+    }
+  }
+  for (const form of deferFormsForPlan(plan)) {
+    if (form.trim().length === 0) {
+      return Result.err(
+        new ValidationError(
+          'Vocabulary Regrade plan deferForms entries cannot be empty.'
+        )
+      );
+    }
+  }
+  for (const rule of plan.preserve ?? []) {
+    if (rule.pattern.trim().length === 0) {
+      return Result.err(
+        new ValidationError(
+          'Vocabulary Regrade plan preserve patterns cannot be empty.'
+        )
+      );
+    }
+    if (
+      rule.disposition !== undefined &&
+      !vocabularyDispositions.has(rule.disposition)
+    ) {
+      return Result.err(
+        new ValidationError(
+          `Vocabulary Regrade plan preserve disposition "${rule.disposition}" is not supported.`
+        )
+      );
+    }
+    if (rule.forms?.some((form) => form.trim().length === 0) === true) {
+      return Result.err(
+        new ValidationError(
+          'Vocabulary Regrade plan preserve forms cannot be empty.'
+        )
+      );
+    }
+  }
+  return validateVocabularyScope(plan.scope);
+};
+
+const validatePreserveInventory = (
+  inventory: readonly VocabularyPreserveInventoryEntry[] | undefined
+): Result<void, ValidationError> => {
+  for (const entry of inventory ?? []) {
+    if (entry.pattern.trim().length === 0) {
+      return Result.err(
+        new ValidationError(
+          'Vocabulary Regrade preserve inventory patterns cannot be empty.'
+        )
+      );
+    }
+    if (entry.forms?.some((form) => form.trim().length === 0) === true) {
+      return Result.err(
+        new ValidationError(
+          'Vocabulary Regrade preserve inventory forms cannot be empty.'
+        )
+      );
+    }
+    if (
+      entry.disposition !== undefined &&
+      !vocabularyDispositions.has(entry.disposition)
+    ) {
+      return Result.err(
+        new ValidationError(
+          `Vocabulary Regrade preserve inventory disposition "${entry.disposition}" is not supported.`
+        )
+      );
+    }
+    if (entry.evidence.length === 0) {
+      return Result.err(
+        new ValidationError(
+          'Vocabulary Regrade preserve inventory entries need evidence.'
+        )
+      );
+    }
+  }
+  return Result.ok();
+};
+
+const effectivePlanForRun = (
+  plan: VocabularyRegradePlan,
+  preserveInventory: readonly VocabularyPreserveInventoryEntry[] | undefined
+): VocabularyRegradePlan => {
+  if (preserveInventory === undefined || preserveInventory.length === 0) {
+    return plan;
+  }
+
+  return {
+    ...plan,
+    preserve: [...(plan.preserve ?? []), ...preserveInventory],
+  };
+};
+
+const vocabularyScanFlags = (plan: VocabularyRegradePlan): string =>
+  plan.caseSensitive === true ? 'g' : 'gi';
+
+const includedByScope = (
+  path: string,
+  scope: VocabularyRegradeScope | undefined
+): boolean =>
+  (scope?.include === undefined ||
+    scope.include.length === 0 ||
+    matchesAnyPathGlob(path, scope.include)) &&
+  !matchesAnyPathGlob(path, scope?.exclude);
+
+const compilePreservePattern = (pattern: string): RegExp => {
+  try {
+    return new RegExp(pattern);
+  } catch {
+    return new RegExp(escapeRegExp(pattern));
+  }
+};
+
+const globalPreservePattern = (pattern: RegExp): RegExp => {
+  const flags = pattern.flags.includes('g')
+    ? pattern.flags
+    : `${pattern.flags}g`;
+  return new RegExp(pattern.source, flags);
+};
+
+const patternOverlapsOccurrence = (
+  pattern: RegExp,
+  occurrence: SourceOccurrenceDraft
+): boolean => {
+  const occurrenceStart = occurrence.contextColumn - 1;
+  const occurrenceEnd = occurrenceStart + occurrence.form.length;
+
+  for (const match of occurrence.context.matchAll(
+    globalPreservePattern(pattern)
+  )) {
+    const matchStart = match.index ?? 0;
+    const matchEnd = matchStart + match[0].length;
+    if (
+      matchStart !== matchEnd &&
+      occurrenceStart < matchEnd &&
+      matchStart < occurrenceEnd
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+};
+
+const preserveRuleForOccurrence = (
+  occurrence: SourceOccurrenceDraft,
+  plan: VocabularyRegradePlan
+): VocabularyPreserveRule | undefined =>
+  plan.preserve?.find((rule) => {
+    if (rule.forms !== undefined && !rule.forms.includes(occurrence.form)) {
+      return false;
+    }
+    if (
+      rule.paths !== undefined &&
+      !matchesAnyPathGlob(occurrence.path, rule.paths)
+    ) {
+      return false;
+    }
+    const pattern = compilePreservePattern(rule.pattern);
+    if (
+      pattern.test(occurrence.form) ||
+      patternOverlapsOccurrence(pattern, occurrence)
+    ) {
+      return true;
+    }
+    return rule.forms === undefined && pattern.test(occurrence.context);
+  });
+
+const scopePolicyForPath = (
+  path: string,
+  scope: VocabularyRegradeScope | undefined
+): VocabularyScopePolicy | undefined =>
+  scope?.policyClassified?.find((policy) =>
+    matchesAnyPathGlob(path, policy.paths)
+  );
+
+const scopePolicyForOccurrence = (
+  occurrence: SourceOccurrenceDraft,
+  plan: VocabularyRegradePlan
+): VocabularyScopePolicy | undefined =>
+  scopePolicyForPath(occurrence.path, plan.scope);
+
+const occurrenceClassification = (
+  occurrence: SourceOccurrenceDraft,
+  plan: VocabularyRegradePlan
+): {
+  readonly preserveRule: VocabularyPreserveRule | undefined;
+  readonly scopeTier: VocabularyScopeTier;
+} => {
+  const policy = scopePolicyForOccurrence(occurrence, plan);
+  const preserveRule = preserveRuleForOccurrence(occurrence, plan);
+  return {
+    preserveRule:
+      preserveRule ??
+      (policy === undefined
+        ? undefined
+        : {
+            disposition: policy.disposition,
+            pattern: occurrence.form,
+            reason: policy.reason,
+          }),
+    scopeTier: policy === undefined ? 'in-scope' : 'policy-classified',
+  };
+};
+
+const occurrenceOverlaps = (
+  occurrences: readonly {
+    readonly end: number;
+    readonly start: number;
+  }[],
+  start: number,
+  end: number
+): boolean =>
+  occurrences.some(
+    (occurrence) => start < occurrence.end && occurrence.start < end
+  );
+
+const occurrenceDraftForSpan = (
+  file: SourceFile,
+  start: number,
+  end: number,
+  form = file.source.slice(start, end)
+): SourceOccurrenceDraft => {
+  const { column, line } = lineColumnForOffset(file.source, start);
+  const context = contextDetailsForOffset(file.source, start, end);
+  return {
+    absolutePath: file.absolutePath,
+    column,
+    context: context.context,
+    contextColumn: context.contextColumn,
+    end,
+    form,
+    line,
+    path: file.path,
+    start,
+  };
+};
+
+const deferredOccurrenceFromDraft = (
+  file: SourceFile,
+  plan: VocabularyRegradePlan,
+  baseOccurrence: SourceOccurrenceDraft,
+  reason = 'unclassified-neighbor'
+): SourceOccurrence => {
+  const { preserveRule, scopeTier } = occurrenceClassification(
+    baseOccurrence,
+    plan
+  );
+  const markdownCodeContext = isMarkdownCodeContext(
+    file,
+    baseOccurrence.start,
+    baseOccurrence.end
+  );
+  const verdict = preserveRule === undefined ? 'deferred' : 'skipped';
+  return {
+    absolutePath: baseOccurrence.absolutePath,
+    column: baseOccurrence.column,
+    context: baseOccurrence.context,
+    disposition: vocabularyOccurrenceDisposition(
+      verdict,
+      preserveRule,
+      markdownCodeContext
+    ),
+    end: baseOccurrence.end,
+    form: baseOccurrence.form,
+    line: baseOccurrence.line,
+    path: baseOccurrence.path,
+    reason: vocabularyOccurrenceReason(
+      preserveRule,
+      markdownCodeContext,
+      reason
+    ),
+    scopeTier,
+    start: baseOccurrence.start,
+    verdict,
+  };
+};
+
+const exactDeferredFormOccurrencesForFile = (
+  file: SourceFile,
+  plan: VocabularyRegradePlan,
+  deferForms: readonly string[],
+  targetFormSpans: readonly {
+    readonly end: number;
+    readonly start: number;
+  }[]
+): readonly SourceOccurrence[] => {
+  const occurrences: SourceOccurrence[] = [];
+  const authoredDeferForms = new Set(
+    (plan.deferForms ?? []).map((form) => formIdentityForPlan(plan, form))
+  );
+  for (const form of deferForms) {
+    const pattern = new RegExp(escapeRegExp(form), vocabularyScanFlags(plan));
+    for (const match of file.source.matchAll(pattern)) {
+      const start = match.index ?? 0;
+      const end = start + match[0].length;
+      const isAuthoredDefer = authoredDeferForms.has(
+        formIdentityForPlan(plan, form)
+      );
+      if (
+        !hasWordBoundary(file.source, start, end, form) ||
+        occurrenceOverlaps(occurrences, start, end) ||
+        (!isAuthoredDefer && occurrenceOverlaps(targetFormSpans, start, end))
+      ) {
+        continue;
+      }
+      occurrences.push(
+        deferredOccurrenceFromDraft(
+          file,
+          plan,
+          occurrenceDraftForSpan(file, start, end, match[0]),
+          'deferred-form'
+        )
+      );
+    }
+  }
+  return occurrences;
+};
+
+const targetFormSpansForFile = (
+  file: SourceFile,
+  plan: VocabularyRegradePlan,
+  targetForms: Map<string, string>
+): readonly {
+  readonly end: number;
+  readonly start: number;
+}[] => {
+  const spans: { end: number; start: number }[] = [];
+  for (const form of targetForms.keys()) {
+    const pattern = new RegExp(escapeRegExp(form), vocabularyScanFlags(plan));
+    for (const match of file.source.matchAll(pattern)) {
+      const start = match.index ?? 0;
+      const end = start + match[0].length;
+      if (
+        !hasWordBoundary(file.source, start, end, form) ||
+        occurrenceOverlaps(spans, start, end)
+      ) {
+        continue;
+      }
+      spans.push({ end, start });
+    }
+  }
+  return spans;
+};
+
+const occurrencesForFile = (
+  file: SourceFile,
+  plan: VocabularyRegradePlan,
+  targetForms: Map<string, string>,
+  deferredOccurrences: readonly SourceOccurrence[]
+): readonly SourceOccurrence[] => {
+  const occurrences: SourceOccurrence[] = [];
+  const candidates: SourceOccurrence[] = [];
+  const forms = [...targetForms.entries()].toSorted(
+    ([left], [right]) => right.length - left.length || left.localeCompare(right)
+  );
+
+  for (const [form, replacement] of forms) {
+    const pattern = new RegExp(escapeRegExp(form), vocabularyScanFlags(plan));
+    for (const match of file.source.matchAll(pattern)) {
+      const start = match.index ?? 0;
+      const end = start + match[0].length;
+      if (
+        !hasWordBoundary(file.source, start, end, form) ||
+        occurrenceOverlaps(deferredOccurrences, start, end)
+      ) {
+        continue;
+      }
+      const { column, line } = lineColumnForOffset(file.source, start);
+      const context = contextDetailsForOffset(file.source, start, end);
+      const baseOccurrence = {
+        absolutePath: file.absolutePath,
+        column,
+        context: context.context,
+        contextColumn: context.contextColumn,
+        end,
+        form: match[0],
+        line,
+        path: file.path,
+        start,
+      };
+      const { preserveRule, scopeTier } = occurrenceClassification(
+        baseOccurrence,
+        plan
+      );
+      const markdownCodeContext = isMarkdownCodeContext(file, start, end);
+      const packageRouteCodeContext = isPackageRouteCodeOccurrence(
+        file.path,
+        form
+      );
+      let verdict = capturedVocabularyVerdict(
+        preserveRule,
+        markdownCodeContext
+      );
+      const packageManifestContext = isPackageManifestPath(file.path);
+      if (
+        preserveRule === undefined &&
+        (packageRouteCodeContext || packageManifestContext)
+      ) {
+        verdict = 'deferred';
+      }
+      let capturedReason = 'captured-form';
+      if (packageRouteCodeContext) {
+        capturedReason = 'package-route-ast-required';
+      } else if (packageManifestContext) {
+        capturedReason = 'package-manifest-structured-edit-required';
+      }
+      candidates.push({
+        absolutePath: baseOccurrence.absolutePath,
+        column: baseOccurrence.column,
+        context: baseOccurrence.context,
+        disposition: vocabularyOccurrenceDisposition(
+          verdict,
+          preserveRule,
+          markdownCodeContext
+        ),
+        end: baseOccurrence.end,
+        form: baseOccurrence.form,
+        line: baseOccurrence.line,
+        path: baseOccurrence.path,
+        reason: vocabularyOccurrenceReason(
+          preserveRule,
+          markdownCodeContext,
+          capturedReason
+        ),
+        scopeTier,
+        ...(preserveRule === undefined &&
+        !markdownCodeContext &&
+        !packageRouteCodeContext &&
+        !packageManifestContext
+          ? { replacement: preserveCase(match[0], replacement) }
+          : {}),
+        start: baseOccurrence.start,
+        verdict,
+      });
+    }
+  }
+
+  for (const candidate of candidates.toSorted(
+    (left, right) =>
+      right.end - right.start - (left.end - left.start) ||
+      left.start - right.start
+  )) {
+    const overlaps = occurrences.some(
+      (occurrence) =>
+        candidate.start < occurrence.end && occurrence.start < candidate.end
+    );
+    if (!overlaps) {
+      occurrences.push(candidate);
+    }
+  }
+
+  return occurrences.toSorted((left, right) =>
+    left.path === right.path
+      ? left.start - right.start
+      : left.path.localeCompare(right.path)
+  );
+};
+
+const deferredOccurrencesForFile = (
+  file: SourceFile,
+  plan: VocabularyRegradePlan,
+  targetForms: Map<string, string>
+): readonly SourceOccurrence[] => {
+  const deferForms = deferFormsForPlan(plan);
+  const targetFormSpans = targetFormSpansForFile(file, plan, targetForms);
+  const knownForms = new Set(
+    plan.caseSensitive === true
+      ? [...targetForms.keys(), ...deferForms]
+      : [...targetForms.keys(), ...deferForms].flatMap((form) => [
+          form,
+          form.toLowerCase(),
+        ])
+  );
+  const lowerFrom = plan.from.toLowerCase();
+  const tokenPattern = /[A-Za-z_$][A-Za-z0-9_$-]*/g;
+  const occurrences = [
+    ...exactDeferredFormOccurrencesForFile(
+      file,
+      plan,
+      deferForms,
+      targetFormSpans
+    ),
+  ];
+
+  for (const form of targetForms.keys()) {
+    const pattern = new RegExp(escapeRegExp(form), vocabularyScanFlags(plan));
+    for (const match of file.source.matchAll(pattern)) {
+      const matchStart = match.index ?? 0;
+      const matchEnd = matchStart + match[0].length;
+      if (hasWordBoundary(file.source, matchStart, matchEnd, form)) {
+        continue;
+      }
+      const { end, start } = expandVocabularyNeighborSpan(
+        file.source,
+        matchStart,
+        matchEnd,
+        form
+      );
+      const matchedForm = file.source.slice(start, end);
+      const lowerMatchedForm = matchedForm.toLowerCase();
+      if (
+        occurrenceOverlaps(occurrences, start, end) ||
+        knownForms.has(matchedForm) ||
+        (plan.caseSensitive !== true && knownForms.has(lowerMatchedForm)) ||
+        !lowerMatchedForm.includes(lowerFrom)
+      ) {
+        continue;
+      }
+      occurrences.push(
+        deferredOccurrenceFromDraft(
+          file,
+          plan,
+          occurrenceDraftForSpan(file, start, end, matchedForm)
+        )
+      );
+    }
+  }
+
+  for (const match of file.source.matchAll(tokenPattern)) {
+    const [form] = match;
+    const lower = form.toLowerCase();
+    if (
+      knownForms.has(form) ||
+      (plan.caseSensitive !== true && knownForms.has(lower))
+    ) {
+      continue;
+    }
+    if (!lower.includes(lowerFrom)) {
+      continue;
+    }
+    const start = match.index ?? 0;
+    const end = start + form.length;
+    if (occurrenceOverlaps(occurrences, start, end)) {
+      continue;
+    }
+    occurrences.push(
+      deferredOccurrenceFromDraft(
+        file,
+        plan,
+        occurrenceDraftForSpan(file, start, end, form)
+      )
+    );
+  }
+  return occurrences.toSorted((left, right) =>
+    left.path === right.path
+      ? left.start - right.start
+      : left.path.localeCompare(right.path)
+  );
+};
+
+const entryForOccurrences = (
+  path: string,
+  occurrences: readonly SourceOccurrence[]
+): RegradeReportEntry | null => {
+  if (occurrences.length === 0) {
+    return null;
+  }
+  const hasDeferred = occurrences.some(
+    (occurrence) => occurrence.verdict === 'deferred'
+  );
+  const hasModified = occurrences.some(
+    (occurrence) => occurrence.verdict === 'modified'
+  );
+  if (hasDeferred) {
+    return {
+      notes: [
+        `Found ${occurrences.length} vocabulary occurrence(s); judgment deferred.`,
+      ],
+      outcome: 'needs-review',
+      path,
+      reason: 'vocabulary-judgment-deferred',
+      reviewDetails: occurrences
+        .filter((occurrence) => occurrence.verdict === 'deferred')
+        .map((occurrence) => ({
+          context: occurrence.context,
+          expectedTarget:
+            'Add an override or preserve rule to the regrade plan.',
+          judgment: 'unresolved' as const,
+          matchedForm: occurrence.form,
+          ...(occurrence.sourceKind === undefined
+            ? {}
+            : {
+                nodeKind:
+                  occurrence.sourceKind === 'tsdoc'
+                    ? 'TSDocComment'
+                    : 'SourceComment',
+              }),
+          reason: occurrence.reason,
+          span: {
+            column: occurrence.column,
+            end: occurrence.end,
+            line: occurrence.line,
+            start: occurrence.start,
+          },
+          symbol: occurrence.form,
+        })),
+    };
+  }
+  if (hasModified) {
+    return {
+      notes: [
+        `Found ${occurrences.length} vocabulary occurrence(s); safe modifications available.`,
+      ],
+      outcome: 'rewrite',
+      path,
+    };
+  }
+  return {
+    notes: [`Skipped ${occurrences.length} vocabulary occurrence(s).`],
+    outcome: 'no-op',
+    path,
+  };
+};
+
+const applyOccurrenceRewrites = (
+  file: SourceFile,
+  occurrences: readonly SourceOccurrence[]
+): string => {
+  let nextSource = file.source;
+  for (const occurrence of occurrences.toReversed()) {
+    if (
+      occurrence.verdict !== 'modified' ||
+      occurrence.replacement === undefined
+    ) {
+      continue;
+    }
+    nextSource =
+      nextSource.slice(0, occurrence.start) +
+      occurrence.replacement +
+      nextSource.slice(occurrence.end);
+  }
+  return nextSource;
+};
+
+const buildVocabularyEvaluation = (params: {
+  readonly apply?: boolean;
+  readonly effectivePlan?: VocabularyRegradePlan | undefined;
+  readonly files: readonly SourceFile[];
+  readonly plan: VocabularyRegradePlan;
+  readonly preserveInventory?: readonly VocabularyPreserveInventoryEntry[];
+  readonly root: string;
+  readonly skipped: readonly SkippedSource[];
+  readonly sourceKindForPath?:
+    | ((path: string) => VocabularySourceKind)
+    | undefined;
+}): VocabularyEvaluation => {
+  const effectivePlan = params.effectivePlan ?? params.plan;
+  const targetForms = targetFormsForPlan(effectivePlan);
+  const scopedFiles = params.files.filter((file) =>
+    includedByScope(file.path, effectivePlan.scope)
+  );
+  const scopeSkipped: SkippedSource[] = params.files
+    .filter((file) => !includedByScope(file.path, effectivePlan.scope))
+    .map((file) => ({ path: file.path, reason: 'excluded-by-regrade-scope' }));
+  const commentParseSkipped: SkippedSource[] = [];
+  const occurrences = scopedFiles.flatMap((file) => {
+    const sourceKind = params.sourceKindForPath?.(file.path) ?? 'all';
+    const scanPlan =
+      sourceKind === 'comments'
+        ? commentReviewPlan(effectivePlan)
+        : effectivePlan;
+    const deferredOccurrences = deferredOccurrencesForFile(
+      file,
+      scanPlan,
+      targetForms
+    );
+    const fileOccurrences = [
+      ...occurrencesForFile(file, scanPlan, targetForms, deferredOccurrences),
+      ...deferredOccurrences,
+    ];
+    if (sourceKind === 'all') {
+      return fileOccurrences;
+    }
+    if (fileOccurrences.length === 0) {
+      return [];
+    }
+    const parsed = parseWithDiagnostics(file.path, file.source);
+    if (parsed.diagnostics.length > 0 || parsed.ast === null) {
+      commentParseSkipped.push({
+        path: file.path,
+        reason: 'source-comment-parse-diagnostics',
+      });
+      return [];
+    }
+    return fileOccurrences.flatMap((occurrence) => {
+      const comment = parsed.comments.find(
+        (candidate) =>
+          candidate.start <= occurrence.start && occurrence.end <= candidate.end
+      );
+      if (comment === undefined) {
+        return [];
+      }
+      const sourceKindForOccurrence = sourceCommentKind(file, comment);
+      if (occurrence.verdict === 'skipped') {
+        return [{ ...occurrence, sourceKind: sourceKindForOccurrence }];
+      }
+      const { replacement: _replacement, ...reviewOccurrence } = occurrence;
+      return [
+        {
+          ...reviewOccurrence,
+          disposition: 'in-family-unresolved' as const,
+          reason: 'source-comment-requires-review',
+          sourceKind: sourceKindForOccurrence,
+          verdict: 'deferred' as const,
+        },
+      ];
+    });
+  });
+  const occurrencesByPath = new Map<string, SourceOccurrence[]>();
+  for (const occurrence of occurrences) {
+    const existing = occurrencesByPath.get(occurrence.path) ?? [];
+    occurrencesByPath.set(occurrence.path, [...existing, occurrence]);
+  }
+  const entries = [...occurrencesByPath.entries()]
+    .flatMap(([path, pathOccurrences]) => {
+      const entry = entryForOccurrences(path, pathOccurrences);
+      return entry === null ? [] : [entry];
+    })
+    .toSorted((left, right) => left.path.localeCompare(right.path));
+  const rewrittenPaths = new Set(
+    occurrences
+      .filter((occurrence) => occurrence.verdict === 'modified')
+      .map((occurrence) => occurrence.path)
+  );
+  const deferredForms = uniqueSorted(
+    occurrences
+      .filter((occurrence) => occurrence.verdict === 'deferred')
+      .map((occurrence) => occurrence.form)
+  );
+  const modifiedOccurrences = occurrences.filter(
+    (occurrence) => occurrence.verdict === 'modified'
+  );
+  const skippedOccurrences = occurrences.filter(
+    (occurrence) => occurrence.verdict === 'skipped'
+  );
+  const deferredOccurrences = occurrences.filter(
+    (occurrence) => occurrence.verdict === 'deferred'
+  );
+  const unresolvedOccurrences = occurrences.filter(
+    (occurrence) =>
+      occurrence.verdict === 'modified' || occurrence.verdict === 'deferred'
+  );
+  const forms = vocabularyFormVerdicts(occurrences);
+  const gateReasons: string[] = [];
+  if (modifiedOccurrences.length > 0) {
+    gateReasons.push(
+      params.apply === true
+        ? 'source-forms-remain-after-apply'
+        : 'safe-modifications-not-yet-applied'
+    );
+  }
+  if (deferredForms.length > 0) {
+    gateReasons.push('deferred-forms-or-occurrences');
+  }
+  if (commentParseSkipped.length > 0) {
+    gateReasons.push('source-comment-parse-diagnostics');
+  }
+  const open = unresolvedOccurrences.length;
+  const scopeEvidence = vocabularyScopeEvidence(effectivePlan, occurrences);
+  gateReasons.push(...scopeEvidence.gateReasons);
+
+  return {
+    entries: [
+      ...entries,
+      ...params.skipped.map((entry) => ({
+        outcome: 'skip' as const,
+        path: entry.path,
+        reason: entry.reason,
+      })),
+      ...scopeSkipped.map((entry) => ({
+        outcome: 'skip' as const,
+        path: entry.path,
+        reason: entry.reason,
+      })),
+      ...commentParseSkipped.map((entry) => ({
+        outcome: 'skip' as const,
+        path: entry.path,
+        reason: entry.reason,
+      })),
+    ].toSorted((left, right) => left.path.localeCompare(right.path)),
+    occurrences,
+    run: {
+      ledger: {
+        cycle: 1,
+        forms,
+        occurrences: occurrences.map(
+          ({ absolutePath: _absolutePath, ...occurrence }) => occurrence
+        ),
+      },
+      plan: params.plan,
+      ...(params.preserveInventory === undefined ||
+      params.preserveInventory.length === 0
+        ? {}
+        : { preserveInventory: params.preserveInventory }),
+      report: {
+        applied: params.apply === true ? modifiedOccurrences.length : 0,
+        deferred: deferredOccurrences.length,
+        dispositions: vocabularyDispositionCounts(occurrences),
+        filesChanged: params.apply === true ? rewrittenPaths.size : 0,
+        gate: {
+          reasons: gateReasons,
+          remaining: open,
+          remainingByDisposition: vocabularyDispositionCounts(
+            unresolvedOccurrences
+          ),
+          status: gateReasons.length === 0 ? 'green' : 'open',
+        },
+        modified: modifiedOccurrences.length,
+        open,
+        scopeTiers: scopeEvidence.scopeTiers,
+        skipped: skippedOccurrences.length,
+        teachingSurfaces: scopeEvidence.teachingSurfaces,
+      },
+    },
+    scanned: scopedFiles.length,
+    skipped: [...params.skipped, ...scopeSkipped, ...commentParseSkipped],
+  };
+};
+
+const skippedByReason = (
+  skipped: readonly SkippedSource[]
+): Readonly<Record<string, number>> => {
+  const counts = new Map<string, number>();
+  for (const entry of skipped) {
+    counts.set(entry.reason, (counts.get(entry.reason) ?? 0) + 1);
+  }
+  return Object.fromEntries(
+    [...counts.entries()].toSorted(([left], [right]) =>
+      left.localeCompare(right)
+    )
+  );
+};
+
+const withScannedPaths = (
+  report: RegradeReport,
+  paths: readonly string[]
+): RegradeReport => {
+  Object.defineProperty(report, 'scannedPaths', {
+    configurable: false,
+    enumerable: false,
+    value: Object.freeze([...paths]),
+    writable: false,
+  });
+  return report;
+};
+
+const cloneVocabularyReport = (report: RegradeReport): RegradeReport => {
+  const clone = structuredClone(report);
+  return report.scannedPaths === undefined
+    ? clone
+    : withScannedPaths(clone, report.scannedPaths);
+};
+
+const withApplySummary = (
+  report: RegradeReport,
+  apply: RegradeApplySummary
+): RegradeReport =>
+  withScannedPaths(
+    {
+      ...report,
+      apply,
+    },
+    report.scannedPaths ?? []
+  );
+
+const appliedVocabularyRunReport = (
+  postApply: VocabularyRegradeRun,
+  occurrences: readonly VocabularyOccurrence[],
+  apply: RegradeApplySummary
+): VocabularyRunReport => {
+  const scopeEvidence = vocabularyScopeEvidence(postApply.plan, occurrences);
+  const reasons = uniqueSorted([
+    ...postApply.report.gate.reasons.filter(
+      (reason) =>
+        reason !== 'expected-policy-classified-evidence-missing' &&
+        reason !== 'expected-teaching-surfaces-missing'
+    ),
+    ...scopeEvidence.gateReasons,
+  ]);
+  return {
+    ...postApply.report,
+    applied: apply.applied,
+    dispositions: vocabularyDispositionCounts(occurrences),
+    filesChanged: apply.filesChanged,
+    gate: {
+      ...postApply.report.gate,
+      reasons,
+      status: reasons.length === 0 ? 'green' : 'open',
+    },
+    scopeTiers: scopeEvidence.scopeTiers,
+    teachingSurfaces: scopeEvidence.teachingSurfaces,
+  };
+};
+
+const vocabularyRunWithAppliedOccurrences = (
+  postApply: VocabularyRegradeRun,
+  dryRun: VocabularyRegradeRun,
+  apply: RegradeApplySummary
+): VocabularyRegradeRun => {
+  const appliedOccurrences = dryRun.ledger.occurrences
+    .filter((occurrence) => occurrence.verdict === 'modified')
+    .map((occurrence) => ({ ...occurrence, verdict: 'applied' as const }));
+  const occurrences = [
+    ...postApply.ledger.occurrences,
+    ...appliedOccurrences,
+  ].toSorted(
+    (left, right) =>
+      left.path.localeCompare(right.path) ||
+      left.start - right.start ||
+      left.verdict.localeCompare(right.verdict)
+  );
+  return {
+    ...postApply,
+    ledger: {
+      ...postApply.ledger,
+      forms: vocabularyFormVerdicts(occurrences),
+      occurrences,
+    },
+    report: appliedVocabularyRunReport(postApply, occurrences, apply),
+  };
+};
+
+const applyVocabularyEvaluation = (
+  files: readonly SourceFile[],
+  evaluation: VocabularyEvaluation
+): Result<RegradeApplySummary, InternalError> => {
+  const changedFiles = new Set<string>();
+  let applied = 0;
+  for (const file of files) {
+    const fileOccurrences = evaluation.occurrences.filter(
+      (occurrence) =>
+        occurrence.path === file.path && occurrence.verdict === 'modified'
+    );
+    if (fileOccurrences.length === 0) {
+      continue;
+    }
+    const nextSource = applyOccurrenceRewrites(file, fileOccurrences);
+    if (nextSource === file.source) {
+      continue;
+    }
+    try {
+      writeFileSync(file.absolutePath, nextSource, 'utf8');
+    } catch (error: unknown) {
+      return Result.err(
+        new InternalError(
+          `Failed to apply vocabulary regrade rewrite for "${file.path}".`,
+          {
+            cause: error instanceof Error ? error : new Error(String(error)),
+            context: {
+              applied,
+              filesChanged: changedFiles.size,
+              path: file.path,
+            },
+          }
+        )
+      );
+    }
+    applied += fileOccurrences.length;
+    changedFiles.add(file.path);
+  }
+
+  const reviewFiles = new Set(
+    evaluation.occurrences
+      .filter((occurrence) => occurrence.verdict === 'deferred')
+      .map((occurrence) => occurrence.path)
+  );
+  const skippedOccurrences = evaluation.occurrences.filter(
+    (occurrence) => occurrence.verdict === 'skipped'
+  );
+
+  return Result.ok({
+    applied,
+    filesChanged: changedFiles.size,
+    review: reviewFiles.size,
+    skipped: skippedOccurrences.length + evaluation.skipped.length,
+    unknown: 0,
+  });
+};
+
+const readVocabularySourceFiles = (
+  collected: NonNullable<ReturnType<typeof collectDownstreamSources>>
+): {
+  readonly files: readonly SourceFile[];
+  readonly skipped: readonly SkippedSource[];
+} => {
+  const files: SourceFile[] = [];
+  const skipped: SkippedSource[] = [...collected.skipped];
+  for (const file of collected.files) {
+    try {
+      const bytes = readFileSync(file.absolutePath);
+      files.push({
+        absolutePath: file.absolutePath,
+        path: file.path,
+        source: bytes.toString('utf8'),
+        sourceBytes: bytes.toString('base64'),
+      });
+    } catch {
+      skipped.push({ path: file.path, reason: 'unreadable-file' });
+    }
+  }
+  return { files, skipped };
+};
+
+const buildRunVocabularyEvaluation = (params: {
+  readonly apply: boolean;
+  readonly effectivePlan: VocabularyRegradePlan;
+  readonly files: readonly SourceFile[];
+  readonly plan: VocabularyRegradePlan;
+  readonly preserveInventory:
+    | readonly VocabularyPreserveInventoryEntry[]
+    | undefined;
+  readonly root: string;
+  readonly skipped: readonly SkippedSource[];
+  readonly sourceKindForPath?:
+    | ((path: string) => VocabularySourceKind)
+    | undefined;
+}): VocabularyEvaluation =>
+  buildVocabularyEvaluation({
+    apply: params.apply,
+    effectivePlan: params.effectivePlan,
+    files: params.files,
+    plan: params.plan,
+    ...(params.preserveInventory === undefined
+      ? {}
+      : { preserveInventory: params.preserveInventory }),
+    root: params.root,
+    skipped: params.skipped,
+    sourceKindForPath: params.sourceKindForPath,
+  });
+
+const ignoredDirectoriesOpenedByPolicy = (
+  scope: VocabularyRegradeScope | undefined
+): readonly string[] =>
+  (scope?.ignoredDirectories ?? DEFAULT_IGNORED_DIRECTORIES).filter(
+    (directory) =>
+      scope?.policyClassified?.some((policy) =>
+        policy.paths.some((pattern) => pattern.split('/').includes(directory))
+      )
+  );
+
+const vocabularyIgnoredDirectories = (
+  scope: VocabularyRegradeScope | undefined
+): readonly string[] => {
+  const opened = ignoredDirectoriesOpenedByPolicy(scope);
+  return (scope?.ignoredDirectories ?? DEFAULT_IGNORED_DIRECTORIES).filter(
+    (directory) => !opened.includes(directory)
+  );
+};
+
+const filterVocabularyCollection = (
+  files: readonly { readonly absolutePath: string; readonly path: string }[],
+  scope: VocabularyRegradeScope | undefined,
+  sourceFilter: ((path: string) => boolean) | undefined
+): {
+  readonly files: readonly {
+    readonly absolutePath: string;
+    readonly path: string;
+  }[];
+  readonly skipped: readonly SkippedSource[];
+} => {
+  const opened = ignoredDirectoriesOpenedByPolicy(scope);
+  const selected = files.filter((file) => {
+    const openedDirectory = file.path
+      .split('/')
+      .some((segment) => opened.includes(segment));
+    return (
+      (!openedDirectory ||
+        scopePolicyForPath(file.path, scope) !== undefined) &&
+      (sourceFilter?.(file.path) ?? true)
+    );
+  });
+  const selectedPaths = new Set(selected.map((file) => file.path));
+  return {
+    files: selected,
+    skipped: files
+      .filter((file) => !selectedPaths.has(file.path))
+      .map((file) => ({
+        path: file.path,
+        reason:
+          sourceFilter?.(file.path) === false
+            ? 'not-selected-source'
+            : 'ignored-directory',
+      })),
+  };
+};
+
+interface VocabularyRunInputs {
+  readonly collectedRoot: string;
+  readonly effectivePlan: VocabularyRegradePlan;
+  readonly files: readonly SourceFile[];
+  readonly skipped: readonly SkippedSource[];
+}
+
+interface PrepareVocabularyRegradeRunParams {
+  readonly includeEntries?: 'actionable' | 'all';
+  readonly plan: VocabularyRegradePlan;
+  readonly preserveInventory?: readonly VocabularyPreserveInventoryEntry[];
+  readonly root: string;
+  readonly sourceFilter?: (path: string) => boolean;
+  readonly sourceKindForPath?: (path: string) => VocabularySourceKind;
+}
+
+const snapshotPrepareVocabularyRegradeRunParams = (
+  params: PrepareVocabularyRegradeRunParams
+): PrepareVocabularyRegradeRunParams => ({
+  ...(params.includeEntries === undefined
+    ? {}
+    : { includeEntries: params.includeEntries }),
+  plan: structuredClone(params.plan),
+  ...(params.preserveInventory === undefined
+    ? {}
+    : { preserveInventory: structuredClone(params.preserveInventory) }),
+  root: params.root,
+  ...(params.sourceFilter === undefined
+    ? {}
+    : { sourceFilter: params.sourceFilter }),
+  ...(params.sourceKindForPath === undefined
+    ? {}
+    : { sourceKindForPath: params.sourceKindForPath }),
+});
+
+const collectVocabularyRunInputs = (
+  params: PrepareVocabularyRegradeRunParams
+): VocabularyRunInputs | null => {
+  const effectivePlan = effectivePlanForRun(
+    params.plan,
+    params.preserveInventory
+  );
+  const collected = collectDownstreamSources(params.root, {
+    extensions: effectivePlan.scope?.extensions ?? VOCABULARY_SOURCE_EXTENSIONS,
+    ...(effectivePlan.scope?.exclude === undefined
+      ? {}
+      : { exclude: effectivePlan.scope.exclude }),
+    ...(effectivePlan.scope?.include === undefined
+      ? {}
+      : { include: effectivePlan.scope.include }),
+    ignoredDirectories: vocabularyIgnoredDirectories(effectivePlan.scope),
+  } satisfies DownstreamCollectionOptions);
+  if (collected === null) {
+    return null;
+  }
+  const filtered = filterVocabularyCollection(
+    collected.files,
+    effectivePlan.scope,
+    params.sourceFilter
+  );
+  const { files, skipped } = readVocabularySourceFiles({
+    ...collected,
+    files: filtered.files,
+    skipped: [...collected.skipped, ...filtered.skipped],
+  });
+  return { collectedRoot: collected.root, effectivePlan, files, skipped };
+};
+
+const vocabularyReportFromEvaluation = (params: {
+  readonly applySummary?: RegradeApplySummary;
+  readonly collectedRoot: string;
+  readonly dryRunEvaluation: VocabularyEvaluation;
+  readonly effectivePlan: VocabularyRegradePlan;
+  readonly entrySelection: 'actionable' | 'all';
+  readonly files: readonly SourceFile[];
+  readonly plan: VocabularyRegradePlan;
+  readonly reportEvaluation: VocabularyEvaluation;
+  readonly skipped: readonly SkippedSource[];
+}): RegradeReport => {
+  const reportEntries = params.reportEvaluation.entries;
+  const actionableEntries = reportEntries.filter(
+    (entry) => entry.outcome === 'rewrite' || entry.outcome === 'needs-review'
+  );
+  const reportSkippedByReason = skippedByReason(
+    params.reportEvaluation.skipped
+  );
+  const report: RegradeReport = withScannedPaths(
+    {
+      entries:
+        params.entrySelection === 'all' ? reportEntries : actionableEntries,
+      matched: actionableEntries.length,
+      review: reportEntries.filter((entry) => entry.outcome === 'needs-review')
+        .length,
+      rewritten: reportEntries.filter((entry) => entry.outcome === 'rewrite')
+        .length,
+      root: params.collectedRoot,
+      run:
+        params.applySummary === undefined
+          ? params.reportEvaluation.run
+          : vocabularyRunWithAppliedOccurrences(
+              params.reportEvaluation.run,
+              params.dryRunEvaluation.run,
+              params.applySummary
+            ),
+      scan: buildRegradeScanSummary({
+        matchedPaths: actionableEntries.map((entry) => entry.path),
+        occurrencePaths: params.reportEvaluation.occurrences.map(
+          (occurrence) => occurrence.path
+        ),
+        scanned: params.reportEvaluation.scanned,
+        skipped: params.reportEvaluation.skipped.length,
+        skippedByReason: reportSkippedByReason,
+      }),
+      scanned: params.reportEvaluation.scanned,
+      selectedClassIds: [
+        params.plan.id ?? `vocabulary:${params.plan.from}->${params.plan.to}`,
+      ],
+      skipped: params.reportEvaluation.skipped.length,
+      skipsByReason: reportSkippedByReason,
+      unknownClassIds: [],
+    },
+    params.files
+      .filter((file) => includedByScope(file.path, params.effectivePlan.scope))
+      .map((file) => file.path)
+  );
+  return params.applySummary === undefined
+    ? report
+    : withApplySummary(report, params.applySummary);
+};
+
+/**
+ * In-memory vocabulary evaluation ready for freshness-checked apply.
+ *
+ * @example
+ * ```ts
+ * const prepared = prepareVocabularyRegradeRun({ identity, plan, root });
+ * if (prepared.isOk() && prepared.value !== null) {
+ *   console.log(prepared.value.report.run?.gate.status);
+ * }
+ * ```
+ */
+export interface PreparedVocabularyRegradeRun {
+  readonly identity: PreparedRegradeRunIdentity;
+  readonly report: RegradeReport;
+  readonly sourceStateHash: string;
+}
+
+interface PreparedVocabularyRegradeRunState {
+  readonly dryRunEvaluation: VocabularyEvaluation;
+  readonly identity: PreparedRegradeRunIdentity;
+  readonly inputs: VocabularyRunInputs;
+  readonly params: PrepareVocabularyRegradeRunParams;
+  readonly sourceStateHash: string;
+}
+
+const preparedVocabularyRunStates = new WeakMap<
+  PreparedVocabularyRegradeRun,
+  PreparedVocabularyRegradeRunState
+>();
+
+const vocabularySourceStateHash = (files: readonly SourceFile[]): string =>
+  createHash('sha256')
+    .update(
+      JSON.stringify({
+        sources: files
+          .map((file) => ({ bytes: file.sourceBytes, path: file.path }))
+          .toSorted((left, right) => {
+            if (left.path < right.path) {
+              return -1;
+            }
+            if (left.path > right.path) {
+              return 1;
+            }
+            return 0;
+          }),
+      })
+    )
+    .digest('hex');
+
+const unreadableVocabularyPaths = (
+  skipped: readonly SkippedSource[]
+): readonly string[] =>
+  skipped
+    .filter(
+      (entry) =>
+        entry.reason === 'unreadable-file' ||
+        entry.reason === 'unreadable-directory'
+    )
+    .map((entry) => entry.path);
+
+const validateVocabularyPreparedIdentity = (
+  expected: PreparedRegradeRunIdentity,
+  actual: PreparedRegradeRunIdentity
+): Result<void, ValidationError> => {
+  for (const field of [
+    'planContentHash',
+    'policyHash',
+    'scopeHash',
+    'lockStateHash',
+    'toolVersion',
+  ] as const) {
+    if (expected[field] !== actual[field]) {
+      return Result.err(
+        new ValidationError(
+          `Prepared vocabulary Regrade identity field \`${field}\` is stale.`,
+          {
+            context: {
+              actual: actual[field],
+              expected: expected[field],
+              field,
+            },
+          }
+        )
+      );
+    }
+  }
+  return Result.ok();
+};
+
+/**
+ * Classify a vocabulary Regrade run once and retain it for checked apply.
+ *
+ * @example
+ * ```ts
+ * const prepared = prepareVocabularyRegradeRun({ identity, plan, root });
+ * if (prepared.isErr()) throw prepared.error;
+ * ```
+ */
+export const prepareVocabularyRegradeRun = (
+  params: PrepareVocabularyRegradeRunParams & {
+    readonly identity: PreparedRegradeRunIdentity;
+  }
+): Result<PreparedVocabularyRegradeRun | null, ValidationError> => {
+  const preparedParams = snapshotPrepareVocabularyRegradeRunParams(params);
+  const planValidation = validateVocabularyPlan(preparedParams.plan);
+  if (planValidation.isErr()) {
+    return planValidation;
+  }
+  const inventoryValidation = validatePreserveInventory(
+    preparedParams.preserveInventory
+  );
+  if (inventoryValidation.isErr()) {
+    return inventoryValidation;
+  }
+  const inputs = collectVocabularyRunInputs(preparedParams);
+  if (inputs === null) {
+    return Result.ok(null);
+  }
+  const unreadable = unreadableVocabularyPaths(inputs.skipped);
+  if (unreadable.length > 0) {
+    return Result.err(
+      new ValidationError(
+        'Prepared vocabulary Regrade sources must all be readable.',
+        { context: { paths: unreadable } }
+      )
+    );
+  }
+  const dryRunEvaluation = buildRunVocabularyEvaluation({
+    apply: false,
+    effectivePlan: inputs.effectivePlan,
+    files: inputs.files,
+    plan: preparedParams.plan,
+    preserveInventory: preparedParams.preserveInventory,
+    root: preparedParams.root,
+    skipped: inputs.skipped,
+    sourceKindForPath: preparedParams.sourceKindForPath,
+  });
+  const report = vocabularyReportFromEvaluation({
+    collectedRoot: inputs.collectedRoot,
+    dryRunEvaluation,
+    effectivePlan: inputs.effectivePlan,
+    entrySelection: preparedParams.includeEntries ?? 'actionable',
+    files: inputs.files,
+    plan: preparedParams.plan,
+    reportEvaluation: dryRunEvaluation,
+    skipped: inputs.skipped,
+  });
+  const prepared: PreparedVocabularyRegradeRun = {
+    identity: { ...params.identity },
+    report: cloneVocabularyReport(report),
+    sourceStateHash: vocabularySourceStateHash(inputs.files),
+  };
+  preparedVocabularyRunStates.set(prepared, {
+    dryRunEvaluation,
+    identity: { ...params.identity },
+    inputs,
+    params: preparedParams,
+    sourceStateHash: prepared.sourceStateHash,
+  });
+  return Result.ok(prepared);
+};
+
+/**
+ * Apply an in-memory vocabulary evaluation after identity and source checks.
+ *
+ * @example
+ * ```ts
+ * const applied = applyPreparedVocabularyRegradeRun(prepared, identity);
+ * if (applied.isErr()) throw applied.error;
+ * ```
+ */
+export const applyPreparedVocabularyRegradeRun = (
+  prepared: PreparedVocabularyRegradeRun,
+  identity: PreparedRegradeRunIdentity
+): Result<RegradeReport, InternalError | ValidationError> => {
+  const state = preparedVocabularyRunStates.get(prepared);
+  if (state === undefined) {
+    return Result.err(
+      new ValidationError(
+        'Prepared vocabulary Regrade run is not the original in-memory evaluation.'
+      )
+    );
+  }
+  const identityValidation = validateVocabularyPreparedIdentity(
+    state.identity,
+    identity
+  );
+  if (identityValidation.isErr()) {
+    return identityValidation;
+  }
+  const current = collectVocabularyRunInputs(state.params);
+  if (current === null) {
+    return Result.err(
+      new ValidationError(
+        'Prepared vocabulary Regrade root is no longer readable.'
+      )
+    );
+  }
+  const unreadable = unreadableVocabularyPaths(current.skipped);
+  if (unreadable.length > 0) {
+    return Result.err(
+      new ValidationError(
+        'Prepared vocabulary Regrade sources are no longer readable.',
+        { context: { paths: unreadable } }
+      )
+    );
+  }
+  const currentSourceStateHash = vocabularySourceStateHash(current.files);
+  if (currentSourceStateHash !== state.sourceStateHash) {
+    return Result.err(
+      new ValidationError(
+        'Prepared vocabulary Regrade source state is stale.',
+        {
+          context: {
+            actual: currentSourceStateHash,
+            expected: state.sourceStateHash,
+          },
+        }
+      )
+    );
+  }
+  const applyResult = applyVocabularyEvaluation(
+    state.inputs.files,
+    state.dryRunEvaluation
+  );
+  if (applyResult.isErr()) {
+    return applyResult;
+  }
+  const appliedFiles = state.inputs.files.map((file) => ({
+    ...file,
+    source: readFileSync(file.absolutePath, 'utf8'),
+  }));
+  const postApplyEvaluation = buildRunVocabularyEvaluation({
+    apply: true,
+    effectivePlan: state.inputs.effectivePlan,
+    files: appliedFiles,
+    plan: state.params.plan,
+    preserveInventory: state.params.preserveInventory,
+    root: state.params.root,
+    skipped: state.inputs.skipped,
+    sourceKindForPath: state.params.sourceKindForPath,
+  });
+  return Result.ok(
+    vocabularyReportFromEvaluation({
+      applySummary: applyResult.value,
+      collectedRoot: state.inputs.collectedRoot,
+      dryRunEvaluation: state.dryRunEvaluation,
+      effectivePlan: state.inputs.effectivePlan,
+      entrySelection: state.params.includeEntries ?? 'actionable',
+      files: appliedFiles,
+      plan: state.params.plan,
+      reportEvaluation: postApplyEvaluation,
+      skipped: state.inputs.skipped,
+    })
+  );
+};
+
+export const runVocabularyRegrade = (params: {
+  readonly apply?: boolean;
+  readonly includeEntries?: 'actionable' | 'all';
+  readonly plan: VocabularyRegradePlan;
+  readonly preserveInventory?: readonly VocabularyPreserveInventoryEntry[];
+  readonly root: string;
+  readonly sourceFilter?: (path: string) => boolean;
+  readonly sourceKindForPath?: (path: string) => VocabularySourceKind;
+}): Result<RegradeReport | null, InternalError | ValidationError> => {
+  const planValidation = validateVocabularyPlan(params.plan);
+  if (planValidation.isErr()) {
+    return planValidation;
+  }
+  const inventoryValidation = validatePreserveInventory(
+    params.preserveInventory
+  );
+  if (inventoryValidation.isErr()) {
+    return inventoryValidation;
+  }
+
+  const inputs = collectVocabularyRunInputs(params);
+  if (inputs === null) {
+    return Result.ok(null);
+  }
+  const { collectedRoot, effectivePlan, files, skipped } = inputs;
+
+  const dryRunEffectiveEvaluation = buildRunVocabularyEvaluation({
+    apply: false,
+    effectivePlan,
+    files,
+    plan: params.plan,
+    preserveInventory: params.preserveInventory,
+    root: params.root,
+    skipped,
+    sourceKindForPath: params.sourceKindForPath,
+  });
+  let reportEvaluation = dryRunEffectiveEvaluation;
+  let applySummary: RegradeApplySummary | undefined;
+
+  if (params.apply === true) {
+    const applyResult = applyVocabularyEvaluation(
+      files,
+      dryRunEffectiveEvaluation
+    );
+    if (applyResult.isErr()) {
+      return applyResult;
+    }
+    applySummary = applyResult.value;
+    const appliedFiles = files.map((file) => ({
+      ...file,
+      source: readFileSync(file.absolutePath, 'utf8'),
+    }));
+    reportEvaluation = buildRunVocabularyEvaluation({
+      apply: true,
+      effectivePlan,
+      files: appliedFiles,
+      plan: params.plan,
+      preserveInventory: params.preserveInventory,
+      root: params.root,
+      skipped,
+      sourceKindForPath: params.sourceKindForPath,
+    });
+  }
+
+  return Result.ok(
+    vocabularyReportFromEvaluation({
+      ...(applySummary === undefined ? {} : { applySummary }),
+      collectedRoot,
+      dryRunEvaluation: dryRunEffectiveEvaluation,
+      effectivePlan,
+      entrySelection: params.includeEntries ?? 'actionable',
+      files,
+      plan: params.plan,
+      reportEvaluation,
+      skipped,
+    })
+  );
+};
+
+const vocabularyPreserveRuleSchema = z.object({
+  disposition: z
+    .enum(vocabularyDispositionValues)
+    .optional()
+    .describe('Classification for occurrences preserved by this rule'),
+  forms: z
+    .array(z.string().min(1))
+    .optional()
+    .describe('Matched forms this preserve rule applies to'),
+  paths: z
+    .array(z.string())
+    .optional()
+    .describe('Root-relative path patterns where the preserve rule applies'),
+  pattern: z.string().describe('Regex or literal pattern to preserve'),
+  reason: z.string().optional().describe('Why this form is preserved'),
+});
+
+const vocabularyScopePolicySchema = z.object({
+  disposition: z
+    .enum(vocabularyDispositionValues)
+    .describe('Occurrence disposition assigned within this protected scope'),
+  expectMatches: z
+    .boolean()
+    .optional()
+    .describe('Require this policy scope to contribute occurrence evidence'),
+  paths: z
+    .array(z.string().min(1))
+    .min(1)
+    .describe('Root-relative protected path patterns'),
+  reason: z.string().min(1).describe('Why matching files are classified'),
+});
+
+const vocabularyPreserveInventoryEntrySchema =
+  vocabularyPreserveRuleSchema.extend({
+    evidence: z
+      .array(z.string().min(1))
+      .describe('Graph or surface facts that justify this derived preserve'),
+    source: z.literal('derived-live-api').describe('Derived inventory source'),
+  });
+
+const vocabularyDispositionCountSchema = z.object(
+  Object.fromEntries(
+    vocabularyDispositionValues.map((disposition) => [
+      disposition,
+      z.number().optional(),
+    ])
+  ) as Record<VocabularyDisposition, z.ZodOptional<z.ZodNumber>>
+);
+
+const vocabularyRegradeScopeSchema = z.object({
+  exclude: z
+    .array(z.string())
+    .optional()
+    .describe('Root-relative path patterns to exclude from this regrade'),
+  extensions: z
+    .array(z.string())
+    .optional()
+    .describe('Source file extensions to scan for this regrade'),
+  ignoredDirectories: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'Deprecated compatibility override for legacy plans. Use exclude globs for new plans.'
+    ),
+  include: z
+    .array(z.string())
+    .optional()
+    .describe('Root-relative path patterns to include in this regrade'),
+  policyClassified: z
+    .array(vocabularyScopePolicySchema)
+    .optional()
+    .describe(
+      'Protected paths that remain scanned and counted but are never rewritten by default'
+    ),
+  teachingSurfaces: z
+    .array(z.string().min(1))
+    .optional()
+    .describe('Expected current teaching-surface path patterns'),
+});
+
+export const vocabularyRegradePlanSchema = z.object({
+  caseSensitive: z
+    .boolean()
+    .optional()
+    .describe('Whether source form scanning preserves case exactly'),
+  deferForms: z
+    .array(z.string().min(1))
+    .optional()
+    .describe('Known forms that must be inventoried for review, not rewritten'),
+  fileRenames: z
+    .array(
+      z.object({
+        from: z.string().min(1).describe('Root-relative source file path'),
+        to: z.string().min(1).describe('Root-relative target file path'),
+      })
+    )
+    .optional()
+    .describe('Governed file moves whose references are derived from scope'),
+  from: z.string().min(1).describe('Source vocabulary term or phrase'),
+  id: z.string().optional().describe('Stable authored regrade plan id'),
+  intent: z.string().optional().describe('Human-authored migration intent'),
+  kind: z.literal('vocabulary').describe('Regrade plan kind'),
+  overrides: z
+    .record(z.string().min(1), z.string().min(1))
+    .optional()
+    .describe('Explicit source-form to target-form mappings'),
+  preserve: z
+    .array(vocabularyPreserveRuleSchema)
+    .optional()
+    .describe('Forms or contexts that are intentionally preserved'),
+  scope: vocabularyRegradeScopeSchema
+    .optional()
+    .describe('Source scope for this regrade plan'),
+  to: z.string().min(1).describe('Target vocabulary term or phrase'),
+});
+
+export const vocabularyRegradeRunOutput = z.object({
+  ledger: z
+    .object({
+      cycle: z.number().describe('Observed regrade run cycle'),
+      forms: z
+        .record(
+          z.string(),
+          z.enum(['applied', 'deferred', 'modified', 'skipped'])
+        )
+        .describe('Observed per-form triage verdicts for this run'),
+      occurrences: z
+        .array(
+          z.object({
+            column: z.number().describe('One-based source column'),
+            context: z.string().describe('Source-line context'),
+            disposition: z
+              .enum(vocabularyDispositionValues)
+              .describe('Occurrence-level classification beside the verdict'),
+            end: z.number().describe('Source end offset'),
+            form: z.string().describe('Matched vocabulary form'),
+            line: z.number().describe('One-based source line'),
+            path: z.string().describe('Root-relative POSIX path'),
+            reason: z.string().describe('Why the occurrence got this verdict'),
+            replacement: z
+              .string()
+              .optional()
+              .describe('Replacement text for modified verdicts'),
+            scopeTier: z
+              .enum(['in-scope', 'policy-classified'])
+              .describe('Three-tier scope classification for this occurrence'),
+            sourceKind: z
+              .enum(['source-comment', 'tsdoc'])
+              .optional()
+              .describe('Exact source-comment construct for comment inventory'),
+            start: z.number().describe('Source start offset'),
+            verdict: z
+              .enum(['applied', 'deferred', 'modified', 'skipped'])
+              .describe('Occurrence-level verdict'),
+          })
+        )
+        .describe('Observed occurrence-level ledger for this run'),
+    })
+    .describe('Observed run ledger'),
+  plan: vocabularyRegradePlanSchema.describe('Authored regrade plan'),
+  preserveInventory: z
+    .array(vocabularyPreserveInventoryEntrySchema)
+    .optional()
+    .describe(
+      'Derived live-API preserve inventory applied at run time without changing the authored plan'
+    ),
+  report: z
+    .object({
+      applied: z.number().describe('Modified occurrences applied to disk'),
+      deferred: z.number().describe('Deferred occurrence count'),
+      dispositions: z
+        .object(vocabularyDispositionCountSchema.shape)
+        .describe('Occurrence counts grouped by disposition'),
+      fileRenames: z
+        .array(
+          z.object({
+            deferred: z.number(),
+            from: z.string(),
+            historical: z.number(),
+            preserved: z.number(),
+            rewritten: z.number(),
+            skipped: z.number(),
+            to: z.string(),
+          })
+        )
+        .optional()
+        .describe('Governed file moves and derived reference outcomes'),
+      filesChanged: z.number().describe('Distinct files changed on disk'),
+      gate: z
+        .object({
+          reasons: z.array(z.string()).describe('Open-gate reasons'),
+          remaining: z.number().describe('Unresolved occurrence count'),
+          remainingByDisposition: z
+            .object(vocabularyDispositionCountSchema.shape)
+            .describe('Unresolved occurrence counts grouped by disposition'),
+          status: z
+            .enum(['green', 'open'])
+            .describe('Whether the run is complete'),
+        })
+        .describe('Completion gate derived from the run ledger'),
+      modified: z.number().describe('Modified occurrence count'),
+      open: z
+        .number()
+        .describe(
+          'Deferred or unapplied modified occurrences holding the gate open'
+        ),
+      scopeTiers: z
+        .object({
+          'in-scope': z.number(),
+          'policy-classified': z.number(),
+        })
+        .describe('Occurrence counts grouped by scope tier'),
+      skipped: z.number().describe('Skipped occurrence count'),
+      teachingSurfaces: z
+        .object({
+          expected: z.array(z.string()),
+          missing: z.array(z.string()),
+          touched: z.array(z.string()),
+        })
+        .describe('Expected and observed current teaching surfaces'),
+    })
+    .describe('Derived run report'),
+});
+
+const vocabularyTransitionRecordEnvironmentSchema = z
+  .object({
+    commitSha: z.string().optional(),
+    engineVersion: z.string().optional(),
+    graphHash: z.string().optional(),
+    root: z.string(),
+  })
+  .strict();
+
+const vocabularyTransitionRecordReportSchema = z
+  .object({
+    apply: z.unknown().optional(),
+    entries: z.array(z.unknown()),
+    matched: z.number(),
+    review: z.number(),
+    rewritten: z.number(),
+    root: z.string(),
+    run: vocabularyRegradeRunOutput,
+    scan: z.unknown(),
+    scanned: z.number(),
+    selectedClassIds: z.array(z.string()),
+    skipped: z.number(),
+    skipsByReason: z.record(z.string(), z.number()),
+    unknownClassIds: z.array(z.string()),
+  })
+  .strict();
+
+const normalizeTransitionRecordPath = (path: string): string =>
+  normalize(path).replaceAll('\\', '/');
+
+const isSafeRootRelativeRecordPath = (path: string): boolean => {
+  const normalized = normalizeTransitionRecordPath(path);
+  return (
+    normalized.length > 0 &&
+    !isAbsolute(normalized) &&
+    normalized !== '..' &&
+    !normalized.startsWith('../')
+  );
+};
+
+export const vocabularyTransitionRecordSchema = z
+  .object({
+    environment: vocabularyTransitionRecordEnvironmentSchema,
+    kind: z.literal('vocabulary-transition-record'),
+    recordPath: z.string().refine(isSafeRootRelativeRecordPath),
+    report: vocabularyTransitionRecordReportSchema,
+    schemaVersion: z.literal(VOCABULARY_TRANSITION_RECORD_SCHEMA_VERSION),
+    transition: z
+      .object({
+        from: z.string(),
+        id: z.string(),
+        to: z.string(),
+      })
+      .strict(),
+  })
+  .strict();
+
+const normalizeLegacyTransitionRecordScopeEvidence = (
+  value: unknown
+): unknown => {
+  if (
+    !isPlainObject(value) ||
+    value['schemaVersion'] !== VOCABULARY_TRANSITION_RECORD_SCHEMA_VERSION
+  ) {
+    return value;
+  }
+  const { report } = value;
+  if (!isPlainObject(report)) {
+    return value;
+  }
+  const { run } = report;
+  if (!isPlainObject(run)) {
+    return value;
+  }
+  const { ledger, report: runReport } = run;
+  if (
+    !isPlainObject(ledger) ||
+    !Array.isArray(ledger['occurrences']) ||
+    !isPlainObject(runReport)
+  ) {
+    return value;
+  }
+  const plan = vocabularyRegradePlanSchema.safeParse(run['plan']);
+  if (!plan.success) {
+    return value;
+  }
+  const vocabularyPlan = plan.data as VocabularyRegradePlan;
+  const occurrences = ledger['occurrences'].map((occurrence) =>
+    isPlainObject(occurrence) &&
+    typeof occurrence['path'] === 'string' &&
+    occurrence['scopeTier'] === undefined
+      ? {
+          ...occurrence,
+          scopeTier:
+            scopePolicyForPath(occurrence['path'], vocabularyPlan.scope) ===
+            undefined
+              ? 'in-scope'
+              : 'policy-classified',
+        }
+      : occurrence
+  );
+  const scopeEvidence = vocabularyScopeEvidence(
+    vocabularyPlan,
+    occurrences.filter(
+      (occurrence) =>
+        isPlainObject(occurrence) &&
+        typeof occurrence['path'] === 'string' &&
+        (occurrence['scopeTier'] === 'in-scope' ||
+          occurrence['scopeTier'] === 'policy-classified')
+    ) as unknown as readonly VocabularyOccurrence[]
+  );
+  return {
+    ...value,
+    report: {
+      ...report,
+      run: {
+        ...run,
+        ledger: { ...ledger, occurrences },
+        report: {
+          ...runReport,
+          ...(runReport['scopeTiers'] === undefined
+            ? { scopeTiers: scopeEvidence.scopeTiers }
+            : {}),
+          ...(runReport['teachingSurfaces'] === undefined
+            ? { teachingSurfaces: scopeEvidence.teachingSurfaces }
+            : {}),
+        },
+      },
+    },
+  };
+};
+
+const transitionRecordSlug = (run: VocabularyRegradeRun): string =>
+  `${run.plan.from}-to-${run.plan.to}`
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/g, '-')
+    .replaceAll(/^-|-$/g, '');
+
+const stableJson = (value: unknown): string =>
+  JSON.stringify(value, (_key, nested) => {
+    if (
+      nested === null ||
+      typeof nested !== 'object' ||
+      Array.isArray(nested)
+    ) {
+      return nested as unknown;
+    }
+    return Object.fromEntries(
+      Object.entries(nested as Record<string, unknown>).toSorted(
+        ([left], [right]) => left.localeCompare(right)
+      )
+    );
+  });
+
+const shortHashForRun = (
+  run: VocabularyRegradeRun,
+  environment?: Partial<VocabularyTransitionRecordEnvironment>
+): string => {
+  const explicitHash = environment?.graphHash ?? environment?.commitSha;
+  if (explicitHash !== undefined && explicitHash.length > 0) {
+    return explicitHash.slice(0, 7);
+  }
+  return createHash('sha256')
+    .update(stableJson({ ledger: run.ledger, plan: run.plan }))
+    .digest('hex')
+    .slice(0, 7);
+};
+
+export const vocabularyTransitionRecordPath = (params: {
+  readonly environment?: Partial<VocabularyTransitionRecordEnvironment>;
+  readonly root: string;
+  readonly run: VocabularyRegradeRun;
+}): string =>
+  join(
+    '.trails',
+    'regrade',
+    'history',
+    `${transitionRecordSlug(params.run)}-${shortHashForRun(params.run, params.environment)}.json`
+  );
+
+const reportWithoutRecord = (
+  report: RegradeReport
+): Omit<RegradeReport, 'record'> => {
+  const { record: _record, ...rest } = report;
+  return rest;
+};
+
+const transitionRecordPathForWrite = (params: {
+  readonly environment: VocabularyTransitionRecordEnvironment;
+  readonly recordPath?: string;
+  readonly report: RegradeReport;
+  readonly root: string;
+}): Result<string, ValidationError> => {
+  const recordPath =
+    params.recordPath ??
+    vocabularyTransitionRecordPath({
+      environment: params.environment,
+      root: params.root,
+      run: params.report.run as VocabularyRegradeRun,
+    });
+  const normalized = normalizeTransitionRecordPath(
+    isAbsolute(recordPath) ? relative(params.root, recordPath) : recordPath
+  );
+  if (!isSafeRootRelativeRecordPath(normalized)) {
+    return Result.err(
+      new ValidationError(
+        'Vocabulary transition record path must stay inside the regrade root.',
+        { context: { recordPath } }
+      )
+    );
+  }
+  return Result.ok(normalized);
+};
+
+export const buildVocabularyTransitionRecord = (params: {
+  readonly environment?: Partial<VocabularyTransitionRecordEnvironment>;
+  readonly recordPath?: string;
+  readonly report: RegradeReport;
+  readonly root: string;
+}): Result<VocabularyTransitionRecord, ValidationError> => {
+  if (params.report.run === undefined) {
+    return Result.err(
+      new ValidationError(
+        'Vocabulary transition records require a vocabulary Regrade report.'
+      )
+    );
+  }
+
+  const environment: VocabularyTransitionRecordEnvironment = {
+    ...(params.environment?.commitSha === undefined
+      ? {}
+      : { commitSha: params.environment.commitSha }),
+    ...(params.environment?.engineVersion === undefined
+      ? {}
+      : { engineVersion: params.environment.engineVersion }),
+    ...(params.environment?.graphHash === undefined
+      ? {}
+      : { graphHash: params.environment.graphHash }),
+    root: params.root,
+  };
+  const recordPathResult = transitionRecordPathForWrite({
+    environment,
+    report: params.report,
+    root: params.root,
+    ...(params.recordPath === undefined
+      ? {}
+      : { recordPath: params.recordPath }),
+  });
+  if (recordPathResult.isErr()) {
+    return recordPathResult;
+  }
+  const recordPath = recordPathResult.value;
+  const record: VocabularyTransitionRecord = {
+    environment,
+    kind: 'vocabulary-transition-record',
+    recordPath,
+    report: reportWithoutRecord(params.report),
+    schemaVersion: VOCABULARY_TRANSITION_RECORD_SCHEMA_VERSION,
+    transition: {
+      from: params.report.run.plan.from,
+      id:
+        params.report.run.plan.id ??
+        `vocabulary:${params.report.run.plan.from}->${params.report.run.plan.to}`,
+      to: params.report.run.plan.to,
+    },
+  };
+  const parsed = vocabularyTransitionRecordSchema.safeParse(record);
+  if (!parsed.success) {
+    return Result.err(
+      new ValidationError('Invalid vocabulary transition record.', {
+        context: { issues: parsed.error.issues },
+      })
+    );
+  }
+  return Result.ok(parsed.data as VocabularyTransitionRecord);
+};
+
+export const writeVocabularyTransitionRecord = (params: {
+  readonly environment?: Partial<VocabularyTransitionRecordEnvironment>;
+  readonly recordPath?: string;
+  readonly report: RegradeReport;
+  readonly root: string;
+  readonly status: VocabularyTransitionRecordSummary['status'];
+}): Result<
+  {
+    readonly record: VocabularyTransitionRecord;
+    readonly summary: VocabularyTransitionRecordSummary;
+  },
+  InternalError | ValidationError
+> => {
+  const recordResult = buildVocabularyTransitionRecord(params);
+  if (recordResult.isErr()) {
+    return recordResult;
+  }
+  const record = recordResult.value;
+  const absolutePath = isAbsolute(record.recordPath)
+    ? record.recordPath
+    : join(params.root, record.recordPath);
+  try {
+    mkdirSync(dirname(absolutePath), { recursive: true });
+    writeFileSync(absolutePath, `${JSON.stringify(record, null, 2)}\n`);
+  } catch (error) {
+    return Result.err(
+      new InternalError('Failed to write vocabulary transition record.', {
+        ...(error instanceof Error ? { cause: error } : {}),
+        context: { path: record.recordPath },
+      })
+    );
+  }
+  return Result.ok({
+    record,
+    summary: {
+      path: record.recordPath,
+      schemaVersion: record.schemaVersion,
+      status: params.status,
+    },
+  });
+};
+
+export const readVocabularyTransitionRecord = (
+  path: string
+): Result<VocabularyTransitionRecord, InternalError | ValidationError> => {
+  if (!existsSync(path)) {
+    return Result.err(
+      new ValidationError(`Vocabulary transition record "${path}" not found.`)
+    );
+  }
+  let parsedJson: unknown;
+  try {
+    parsedJson = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    return Result.err(
+      new InternalError('Failed to read vocabulary transition record.', {
+        ...(error instanceof Error ? { cause: error } : {}),
+        context: { path },
+      })
+    );
+  }
+  const parsed = vocabularyTransitionRecordSchema.safeParse(
+    normalizeLegacyTransitionRecordScopeEvidence(parsedJson)
+  );
+  if (!parsed.success) {
+    return Result.err(
+      new ValidationError('Invalid vocabulary transition record.', {
+        context: { issues: parsed.error.issues, path },
+      })
+    );
+  }
+  return Result.ok(parsed.data as VocabularyTransitionRecord);
+};
+
+export const transitionRecordReportWithSummary = (
+  report: RegradeReport,
+  summary: VocabularyTransitionRecordSummary
+): RegradeReport => ({ ...report, record: summary });