@ontrails/regrade 1.0.0-beta.32 → 1.0.0-beta.41

package/src/downstream/vocabulary.ts

@@ -5,7 +5,16 @@ import {
   escapeRegExp,
   matchesAnyPathGlob,
 } from '@ontrails/core';
-import { readFileSync, writeFileSync } from 'node:fs';
+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 { collectDownstreamSources } from './collect.js';
@@ -19,12 +28,36 @@ import { buildRegradeScanSummary } from './scan-summary.js';
 
 export type VocabularyVerdict = 'deferred' | 'modified' | 'skipped';
 
+export const vocabularyDispositionValues = [
+  'code-context-out-of-engine',
+  'docs-only',
+  'explicit-preserve',
+  'forward-pointer',
+  '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 VocabularyRegradeScope {
   readonly exclude?: readonly string[];
   readonly extensions?: readonly string[];
@@ -38,6 +71,8 @@ export interface VocabularyRegradeScope {
 }
 
 export interface VocabularyRegradePlan {
+  readonly caseSensitive?: boolean;
+  readonly deferForms?: readonly string[];
   readonly from: string;
   readonly id?: string;
   readonly intent?: string;
@@ -51,6 +86,7 @@ export interface VocabularyRegradePlan {
 export interface VocabularyOccurrence {
   readonly column: number;
   readonly context: string;
+  readonly disposition: VocabularyDisposition;
   readonly end: number;
   readonly form: string;
   readonly line: number;
@@ -69,6 +105,9 @@ export interface VocabularyRunLedger {
 
 export interface VocabularyRunGate {
   readonly remaining: number;
+  readonly remainingByDisposition: Partial<
+    Readonly<Record<VocabularyDisposition, number>>
+  >;
   readonly reasons: readonly string[];
   readonly status: 'green' | 'open';
 }
@@ -76,6 +115,9 @@ export interface VocabularyRunGate {
 export interface VocabularyRunReport {
   readonly applied: number;
   readonly deferred: number;
+  readonly dispositions: Partial<
+    Readonly<Record<VocabularyDisposition, number>>
+  >;
   readonly filesChanged: number;
   readonly gate: VocabularyRunGate;
   readonly modified: number;
@@ -86,9 +128,38 @@ export interface VocabularyRunReport {
 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;
@@ -99,6 +170,13 @@ interface SourceOccurrence extends VocabularyOccurrence {
   readonly absolutePath: string;
 }
 
+interface SourceOccurrenceDraft extends Omit<
+  SourceOccurrence,
+  'disposition' | 'reason' | 'verdict'
+> {
+  readonly contextColumn: number;
+}
+
 interface VocabularyEvaluation {
   readonly entries: readonly RegradeReportEntry[];
   readonly occurrences: readonly SourceOccurrence[];
@@ -125,30 +203,73 @@ const VOCABULARY_SOURCE_EXTENSIONS = Object.freeze([
 const uniqueSorted = (values: readonly string[]): readonly string[] =>
   [...new Set(values)].toSorted((a, b) => a.localeCompare(b));
 
-const isVocabularyTokenCharacter = (value: string): boolean =>
-  /[A-Za-z0-9_$-]/.test(value);
+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 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
+  end: number,
+  form: string
 ): boolean => {
-  const before = start === 0 ? '' : (source.at(start - 1) ?? '');
-  const after = end >= source.length ? '' : (source.at(end) ?? '');
+  const routeLike = form.includes('/');
   return (
-    !isVocabularyTokenCharacter(before) && !isVocabularyTokenCharacter(after)
+    !isVocabularyTokenCharacterAt(source, start - 1, routeLike) &&
+    !isVocabularyTokenCharacterAt(source, end, routeLike)
   );
 };
 
 const expandVocabularyNeighborSpan = (
   source: string,
   start: number,
-  end: number
+  end: number,
+  form: string
 ): { readonly end: number; readonly start: number } => {
+  const routeLike = form.includes('/');
   let expandedStart = start;
   while (
     expandedStart > 0 &&
-    isVocabularyTokenCharacter(source.at(expandedStart - 1) ?? '')
+    isVocabularyTokenCharacterAt(source, expandedStart - 1, routeLike)
   ) {
     expandedStart -= 1;
   }
@@ -156,7 +277,7 @@ const expandVocabularyNeighborSpan = (
   let expandedEnd = end;
   while (
     expandedEnd < source.length &&
-    isVocabularyTokenCharacter(source.at(expandedEnd) ?? '')
+    isVocabularyTokenCharacterAt(source, expandedEnd, routeLike)
   ) {
     expandedEnd += 1;
   }
@@ -181,15 +302,155 @@ const lineColumnForOffset = (
   return { column, line };
 };
 
-const contextForOffset = (
+const contextDetailsForOffset = (
   source: string,
   start: number,
   end: number
-): string => {
+): { readonly context: string; readonly contextColumn: number } => {
   const lineStart = source.lastIndexOf('\n', start - 1) + 1;
   const nextLine = source.indexOf('\n', end);
   const lineEnd = nextLine === -1 ? source.length : nextLine;
-  return source.slice(lineStart, lineEnd).trim();
+  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 => {
@@ -203,16 +464,78 @@ const preserveCase = (sourceForm: string, replacement: string): string => {
   return replacement;
 };
 
-const pluralize = (value: string): string =>
-  value.endsWith('s') || value.endsWith('x') || value.endsWith('ch')
-    ? `${value}es`
-    : `${value}s`;
+const isSimpleVocabularyWord = (value: string): boolean =>
+  /^[A-Za-z]+$/.test(value);
 
-const defaultVocabularyForms = (from: string, to: string) =>
-  new Map<string, string>([
-    [from, to],
-    [pluralize(from), pluralize(to)],
-  ]);
+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
@@ -221,6 +544,11 @@ const normalizedOverrideEntries = (
     left.localeCompare(right)
   );
 
+const formIdentityForPlan = (
+  plan: VocabularyRegradePlan,
+  form: string
+): string => (plan.caseSensitive === true ? form : form.toLowerCase());
+
 const targetFormsForPlan = (
   plan: VocabularyRegradePlan
 ): Map<string, string> => {
@@ -231,6 +559,20 @@ const targetFormsForPlan = (
   return forms;
 };
 
+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 validateVocabularyPlan = (
   plan: VocabularyRegradePlan
 ): Result<void, ValidationError> => {
@@ -260,6 +602,15 @@ const validateVocabularyPlan = (
       );
     }
   }
+  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(
@@ -268,10 +619,83 @@ const validateVocabularyPlan = (
         )
       );
     }
+    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 Result.ok();
 };
 
+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
@@ -289,27 +713,202 @@ const compilePreservePattern = (pattern: string): RegExp => {
   }
 };
 
+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: Omit<SourceOccurrence, 'reason' | 'verdict'>,
+  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;
     }
-    return (
-      compilePreservePattern(rule.pattern).test(occurrence.context) ||
-      compilePreservePattern(rule.pattern).test(occurrence.form)
-    );
+    const pattern = compilePreservePattern(rule.pattern);
+    if (
+      pattern.test(occurrence.form) ||
+      patternOverlapsOccurrence(pattern, occurrence)
+    ) {
+      return true;
+    }
+    return rule.forms === undefined && pattern.test(occurrence.context);
   });
 
-const occurrencesForFile = (
+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 = preserveRuleForOccurrence(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
+    ),
+    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[] = [];
@@ -318,18 +917,23 @@ const occurrencesForFile = (
   );
 
   for (const [form, replacement] of forms) {
-    const pattern = new RegExp(escapeRegExp(form), 'gi');
+    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)) {
+      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: contextForOffset(file.source, start, end),
+        context: context.context,
+        contextColumn: context.contextColumn,
         end,
         form: match[0],
         line,
@@ -337,15 +941,54 @@ const occurrencesForFile = (
         start,
       };
       const preserveRule = preserveRuleForOccurrence(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({
-        ...baseOccurrence,
-        reason:
-          preserveRule?.reason ??
-          (preserveRule === undefined ? 'captured-form' : 'preserved-by-plan'),
-        ...(preserveRule === undefined
+        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
+        ),
+        ...(preserveRule === undefined &&
+        !markdownCodeContext &&
+        !packageRouteCodeContext &&
+        !packageManifestContext
           ? { replacement: preserveCase(match[0], replacement) }
           : {}),
-        verdict: preserveRule === undefined ? 'modified' : 'skipped',
+        start: baseOccurrence.start,
+        verdict,
       });
     }
   }
@@ -376,71 +1019,68 @@ const deferredOccurrencesForFile = (
   plan: VocabularyRegradePlan,
   targetForms: Map<string, string>
 ): readonly SourceOccurrence[] => {
+  const deferForms = deferFormsForPlan(plan);
+  const targetFormSpans = targetFormSpansForFile(file, plan, targetForms);
   const knownForms = new Set(
-    [...targetForms.keys()].flatMap((form) => [form, form.toLowerCase()])
+    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: SourceOccurrence[] = [];
-  const pushOccurrence = (
-    baseOccurrence: Omit<SourceOccurrence, 'reason' | 'verdict'>
-  ): void => {
-    const preserveRule = preserveRuleForOccurrence(baseOccurrence, plan);
-    occurrences.push({
-      ...baseOccurrence,
-      reason:
-        preserveRule?.reason ??
-        (preserveRule === undefined
-          ? 'unclassified-neighbor'
-          : 'preserved-by-plan'),
-      verdict: preserveRule === undefined ? 'deferred' : 'skipped',
-    });
-  };
+  const occurrences = [
+    ...exactDeferredFormOccurrencesForFile(
+      file,
+      plan,
+      deferForms,
+      targetFormSpans
+    ),
+  ];
 
   for (const form of targetForms.keys()) {
-    const pattern = new RegExp(escapeRegExp(form), 'gi');
+    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)) {
+      if (hasWordBoundary(file.source, matchStart, matchEnd, form)) {
         continue;
       }
       const { end, start } = expandVocabularyNeighborSpan(
         file.source,
         matchStart,
-        matchEnd
+        matchEnd,
+        form
       );
       const matchedForm = file.source.slice(start, end);
       const lowerMatchedForm = matchedForm.toLowerCase();
-      const overlaps = occurrences.some(
-        (occurrence) => start < occurrence.end && occurrence.start < end
-      );
       if (
-        overlaps ||
+        occurrenceOverlaps(occurrences, start, end) ||
         knownForms.has(matchedForm) ||
-        knownForms.has(lowerMatchedForm) ||
+        (plan.caseSensitive !== true && knownForms.has(lowerMatchedForm)) ||
         !lowerMatchedForm.includes(lowerFrom)
       ) {
         continue;
       }
-      const { column, line } = lineColumnForOffset(file.source, start);
-      pushOccurrence({
-        absolutePath: file.absolutePath,
-        column,
-        context: contextForOffset(file.source, start, end),
-        end,
-        form: matchedForm,
-        line,
-        path: file.path,
-        start,
-      });
+      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) || knownForms.has(lower)) {
+    if (
+      knownForms.has(form) ||
+      (plan.caseSensitive !== true && knownForms.has(lower))
+    ) {
       continue;
     }
     if (!lower.includes(lowerFrom)) {
@@ -448,23 +1088,16 @@ const deferredOccurrencesForFile = (
     }
     const start = match.index ?? 0;
     const end = start + form.length;
-    const overlaps = occurrences.some(
-      (occurrence) => start < occurrence.end && occurrence.start < end
-    );
-    if (overlaps) {
+    if (occurrenceOverlaps(occurrences, start, end)) {
       continue;
     }
-    const { column, line } = lineColumnForOffset(file.source, start);
-    pushOccurrence({
-      absolutePath: file.absolutePath,
-      column,
-      context: contextForOffset(file.source, start, end),
-      end,
-      form,
-      line,
-      path: file.path,
-      start,
-    });
+    occurrences.push(
+      deferredOccurrenceFromDraft(
+        file,
+        plan,
+        occurrenceDraftForSpan(file, start, end, form)
+      )
+    );
   }
   return occurrences.toSorted((left, right) =>
     left.path === right.path
@@ -548,22 +1181,37 @@ const applyOccurrenceRewrites = (
 
 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[];
 }): VocabularyEvaluation => {
-  const targetForms = targetFormsForPlan(params.plan);
+  const effectivePlan = params.effectivePlan ?? params.plan;
+  const targetForms = targetFormsForPlan(effectivePlan);
   const scopedFiles = params.files.filter((file) =>
-    includedByScope(file.path, params.plan.scope)
+    includedByScope(file.path, effectivePlan.scope)
   );
   const scopeSkipped: SkippedSource[] = params.files
-    .filter((file) => !includedByScope(file.path, params.plan.scope))
+    .filter((file) => !includedByScope(file.path, effectivePlan.scope))
     .map((file) => ({ path: file.path, reason: 'excluded-by-regrade-scope' }));
-  const occurrences = scopedFiles.flatMap((file) => [
-    ...occurrencesForFile(file, params.plan, targetForms),
-    ...deferredOccurrencesForFile(file, params.plan, targetForms),
-  ]);
+  const occurrences = scopedFiles.flatMap((file) => {
+    const deferredOccurrences = deferredOccurrencesForFile(
+      file,
+      effectivePlan,
+      targetForms
+    );
+    return [
+      ...occurrencesForFile(
+        file,
+        effectivePlan,
+        targetForms,
+        deferredOccurrences
+      ),
+      ...deferredOccurrences,
+    ];
+  });
   const occurrencesByPath = new Map<string, SourceOccurrence[]>();
   for (const occurrence of occurrences) {
     const existing = occurrencesByPath.get(occurrence.path) ?? [];
@@ -594,6 +1242,10 @@ const buildVocabularyEvaluation = (params: {
   const deferredOccurrences = occurrences.filter(
     (occurrence) => occurrence.verdict === 'deferred'
   );
+  const unresolvedOccurrences = occurrences.filter(
+    (occurrence) =>
+      occurrence.verdict === 'modified' || occurrence.verdict === 'deferred'
+  );
   const forms: Record<string, VocabularyVerdict> = {};
   for (const occurrence of occurrences) {
     const current = forms[occurrence.form];
@@ -620,7 +1272,7 @@ const buildVocabularyEvaluation = (params: {
   if (deferredForms.length > 0) {
     gateReasons.push('deferred-forms-or-occurrences');
   }
-  const open = modifiedOccurrences.length + deferredOccurrences.length;
+  const open = unresolvedOccurrences.length;
 
   return {
     entries: [
@@ -646,13 +1298,21 @@ const buildVocabularyEvaluation = (params: {
         ),
       },
       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,
@@ -744,56 +1404,109 @@ const applyVocabularyEvaluation = (
   });
 };
 
+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 {
+      files.push({
+        absolutePath: file.absolutePath,
+        path: file.path,
+        source: readFileSync(file.absolutePath, 'utf8'),
+      });
+    } 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[];
+}): 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,
+  });
+
 export const runVocabularyRegrade = (params: {
   readonly apply?: boolean;
   readonly includeEntries?: 'actionable' | 'all';
   readonly plan: VocabularyRegradePlan;
+  readonly preserveInventory?: readonly VocabularyPreserveInventoryEntry[];
   readonly root: string;
 }): 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 effectivePlan = effectivePlanForRun(
+    params.plan,
+    params.preserveInventory
+  );
 
   const collected = collectDownstreamSources(params.root, {
-    extensions: params.plan.scope?.extensions ?? VOCABULARY_SOURCE_EXTENSIONS,
-    ...(params.plan.scope?.exclude === undefined
+    extensions: effectivePlan.scope?.extensions ?? VOCABULARY_SOURCE_EXTENSIONS,
+    ...(effectivePlan.scope?.exclude === undefined
       ? {}
-      : { exclude: params.plan.scope.exclude }),
-    ...(params.plan.scope?.ignoredDirectories === undefined
+      : { exclude: effectivePlan.scope.exclude }),
+    ...(effectivePlan.scope?.include === undefined
       ? {}
-      : { ignoredDirectories: params.plan.scope.ignoredDirectories }),
+      : { include: effectivePlan.scope.include }),
+    ...(effectivePlan.scope?.ignoredDirectories === undefined
+      ? {}
+      : { ignoredDirectories: effectivePlan.scope.ignoredDirectories }),
   } satisfies DownstreamCollectionOptions);
   if (collected === null) {
     return Result.ok(null);
   }
 
-  const files: SourceFile[] = [];
-  const skipped: SkippedSource[] = [...collected.skipped];
-  for (const file of collected.files) {
-    try {
-      files.push({
-        absolutePath: file.absolutePath,
-        path: file.path,
-        source: readFileSync(file.absolutePath, 'utf8'),
-      });
-    } catch {
-      skipped.push({ path: file.path, reason: 'unreadable-file' });
-    }
-  }
+  const { files, skipped } = readVocabularySourceFiles(collected);
 
-  const dryRunEvaluation = buildVocabularyEvaluation({
+  const dryRunEffectiveEvaluation = buildRunVocabularyEvaluation({
     apply: false,
+    effectivePlan,
     files,
     plan: params.plan,
+    preserveInventory: params.preserveInventory,
     root: params.root,
     skipped,
   });
-  let reportEvaluation = dryRunEvaluation;
+  let reportEvaluation = dryRunEffectiveEvaluation;
   let applySummary: RegradeApplySummary | undefined;
 
   if (params.apply === true) {
-    const applyResult = applyVocabularyEvaluation(files, dryRunEvaluation);
+    const applyResult = applyVocabularyEvaluation(
+      files,
+      dryRunEffectiveEvaluation
+    );
     if (applyResult.isErr()) {
       return applyResult;
     }
@@ -802,10 +1515,12 @@ export const runVocabularyRegrade = (params: {
       ...file,
       source: readFileSync(file.absolutePath, 'utf8'),
     }));
-    reportEvaluation = buildVocabularyEvaluation({
+    reportEvaluation = buildRunVocabularyEvaluation({
       apply: true,
+      effectivePlan,
       files: appliedFiles,
       plan: params.plan,
+      preserveInventory: params.preserveInventory,
       root: params.root,
       skipped,
     });
@@ -860,6 +1575,14 @@ export const runVocabularyRegrade = (params: {
 };
 
 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()
@@ -868,6 +1591,23 @@ const vocabularyPreserveRuleSchema = z.object({
   reason: z.string().optional().describe('Why this form is preserved'),
 });
 
+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())
@@ -890,6 +1630,14 @@ const vocabularyRegradeScopeSchema = z.object({
 });
 
 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'),
   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'),
@@ -920,6 +1668,9 @@ export const vocabularyRegradeRunOutput = z.object({
           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'),
@@ -939,15 +1690,27 @@ export const vocabularyRegradeRunOutput = z.object({
     })
     .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'),
       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'),
@@ -963,3 +1726,282 @@ export const vocabularyRegradeRunOutput = z.object({
     })
     .describe('Projected 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 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(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 });