@ontrails/trails 1.0.0-beta.32 → 1.0.0-beta.39

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # trails
 
+## 1.0.0-beta.39
+
+### Minor Changes
+
+- [`9518f5c`](https://github.com/outfitter-dev/trails/commit/9518f5cc892a87273a3bfdaa0d7319f98004ecb8): `trails regrade adjust <transition>` pulls a graduated transition back from consolidated history into an active plan minus the run ledger, preserving the stable transition id so subsequent applies append to the same history spine. Plan re-derivation (`regrade plan`) now carries `transitionId` forward from an existing active plan.
+- [`714939d`](https://github.com/outfitter-dev/trails/commit/714939d6ec143c55a1aba55b65bd11a8a2bfbf1e): Stacked/phased regrades ride the primary tooling: class-mode Regrade plans accept `include` path globs so one transition can be applied in scoped parts that all append to the same consolidated history, and an authored `--name` keys multi-class transitions to a clean transition-name filename instead of concatenated class ids.
+- [`65b362f`](https://github.com/outfitter-dev/trails/commit/65b362f65fa2a75e2121d1a8b31882d52fa0376b): Regrade history consolidates per transition, append-only: `regrade apply` appends a run entry stamped `{ planContentHash, lockHashAtRun }` to `.trails/regrade/history/<transition>.json` instead of overwriting lockhash-named files, identical re-runs are recognized as replays, the artifact carries a stable internal transition `id`, and `regrade check <transition>` verifies each recorded run at its own stamped lock. The report `history.status` union widens to `applied | checked | replay`.
+- [`7c05376`](https://github.com/outfitter-dev/trails/commit/7c05376a4ee2a66ef477d8f165205bf2fbbdc37f): `trails compile` and `trails validate` now collect adapter overlay overlays from the app module's `trailsOverlays` export and embed the validated facts as `overlays.<namespace>` in `trails.lock`, threading the registrations through every derivation site so compiled and freshly derived graphs stay hash-identical.
+- [`adf6419`](https://github.com/outfitter-dev/trails/commit/adf64191ea9e458d7405465ab6fa96ca72ab574c): Add `trails wayfind --overlay <namespace>`: a generic read of namespaced lock overlays (adapter-contributed facts) from saved artifacts, listing available namespaces on a miss — new fact families become inspectable with zero wayfinder edits.
+
+### Patch Changes
+
+- [`f42ca6e`](https://github.com/outfitter-dev/trails/commit/f42ca6e40b29155acec446e5bf44e52e014466bd): Hard cutover: the CLI consumes `cli` bindings from the app-authored surfaces overlay. Scalar bindings behave identically to the removed cliAliases (parity-tested) — the binding name splits on `.` into a transparent synonym command path for exactly one trail. List bindings arrive as command groups: each expanded member trail gets a group-prefixed route that dispatches the member trail with its identity preserved, and a singleton list stays a group. Expansion is fail-fast boundary validation: a scalar binding resolving to zero or multiple trails, or a group with an empty member union, is a `ValidationError` naming the binding. `DeriveTopoGraphOptions.cliAliases`, the `cliAliases`/`trailsCliAliases` app-module export convention, and the per-kind compile lift are deleted; `deriveCliCommands`/`createProgram` take `overlays` instead of `aliases`, and both topo-graph derivation pipelines expand the same bindings through one shared helper so runtime CLI routes and lock routes come from one semantic. A leftover legacy export is now a Warden error (`no-legacy-cli-alias-export`) naming the `surfaceOverlay({ cli: { ... } })` rewrite.
+
+  This is a breaking API removal shipped under the lockstep beta patch convention (pre-1.0 hard-cutover posture, zero external adoption); the removed options have no deprecation window by design.
+
+- [`bafde1f`](https://github.com/outfitter-dev/trails/commit/bafde1fc8172abb8d8617f69a3c7a70667626d10): Fresh derivations now collect app-module overlays through the shared channel compile uses. `@ontrails/adapter-kit` exports `resolveTrailsOverlays()`, the one reader of an app module's `trailsOverlays` export; the compile-path fresh app lease and Warden's fresh topo loading both go through it, making per-namespace drift asymmetry structurally impossible. Warden drift checks (`checkDrift` now accepts derive options carrying overlays) and the topo-aware rule context graph derive with the same overlays the committed lock embeds, so rules like `surface-overlay-coherence` fire on standard runs. Stale drift results name the drifted overlay namespaces (`DriftResult.driftedOverlayNamespaces`) and point at `trails compile` as the remediation.
+- [`b077fb7`](https://github.com/outfitter-dev/trails/commit/b077fb7ba6d9724cac6f0e59bc3fec9aec28984c): Add the export-restructure Regrade class family (TRL-1210). `export-restructure:cli-aliases` inverts legacy `cliAliases`/`trailsCliAliases` exports into `surfaceOverlay({ cli })` bindings inside the module's `trailsOverlays` export — adding the `@ontrails/core` import, deleting the legacy export, and routing anything it cannot prove safe (computed keys, spreads, in-module `aliases:` references) to `needs-review` with the exact target shape named. `export-restructure:mcp-trailheads` projects call-site MCP trailhead maps into `surfaceOverlay({ mcp })` group bindings: it rewrites in place when the same module exports `trailsOverlays`, and otherwise emits a classified `needs-review` handoff naming the module-overlay target while the call-site map stays as the richer-metadata override-in-context. Warden's fix-class union grows to `'export-restructure' | 'term-rewrite'`, `no-legacy-cli-alias-export` now advertises the `export-restructure` class, and `loadWardenRegradeClasses` supersedes `loadWardenTermRewriteClasses` (still exported) as the full Warden-routed class loader. Class-mode Regrade also gains the full plan lifecycle: `trails regrade plan --type class --class-ids ...` writes a `.trails/regrade/<slug>.json` plan carrying class ids, scope, and intent, `regrade check` re-runs the dry run and gates on outstanding rewrites or review, and `regrade apply` applies and graduates the plan to `.trails/regrade/history/<slug>-<hash>.json` — the same plan → check → apply → history evidence trail vocabulary regrades already had, now available to structural transforms. The class family ships for downstream apps bridging the pre-1.0 gap, so pre-cutover alias exports and trailhead maps migrate mechanically instead of by hand.
+- [`81373bc`](https://github.com/outfitter-dev/trails/commit/81373bc5e980bb06d56fb06af4f0986f72e318c7): Wave-2 MCP cutover to the app-authored `surfaces` overlay. The overlay's `mcp` bindings are now the authored, lockable default for the MCP surface: a list binding derives one grouped trailhead tool (member selection in `{ trail, input }`, member identity preserved in `{ trail, output }`, deterministic derived description), and a scalar binding derives an additional tool synonym whose MCP-safe name is published verbatim and must expand to exactly one trail. `deriveMcpTools`/`createServer` accept the new `overlays` option; `@ontrails/core` gains `expandMcpSurfaceBindings` and `deriveMcpTrailheadDescription`.
+
+  The call-site `CreateServerOptions.trailheads` map survives as permanent override-in-context design, not a compatibility bridge: when both channels are present, the call-site map wins at runtime. Warden's new `trailhead-override-divergence` rule (warn) names both sides when a call-site map's binding names or member selectors diverge from the authored overlay default.
+
+  Topographer now derives `graph.trailheads` from the overlay's `mcp` list bindings in both `deriveTopoGraph` and the store-side graph build, so trailhead facts flow from compiled locks into Wayfinder reads for the first time. The never-wired `DeriveTopoGraphOptions.trailheads` option and the `TopoGraphTrailheadDeclaration`/`TopoGraphTrailheadTrailSelector` types are removed — a beta-window hard cutover of an option no caller could reach; author the equivalent `mcp` list binding in `surfaceOverlay({ mcp })` instead.
+
+- [`a0517ef`](https://github.com/outfitter-dev/trails/commit/a0517efa01014754b1dc307169b21ae71a6e3620): Fresh app loading now resolves extensionless relative imports the way Bun does at runtime, so runtime-valid apps stay operator-loadable (`trails compile`, `trails warden`, and every other fresh-load path). When a relative import cannot be resolved at all, the failure is an actionable `ValidationError` naming the importer file and specifier instead of an opaque redacted "Internal server error".
+- [`a89d469`](https://github.com/outfitter-dev/trails/commit/a89d4696aa78f3dda9394c14665ab3ea8c0f313c): Make `trails compile` → `trails validate` round-trip deterministically (TRL-1191). The per-user topo store no longer reuses previously stored JSON Schema bytes by zod definition hash — that hash cannot see `.describe()` metadata or object field order, so a warm store could serve pre-edit schema values into a freshly compiled lock and make `validate` report it stale immediately. Every snapshot now regenerates schema JSON from the live Zod schema, the store's graph hash goes through the same shared `deriveStableHash` path as `deriveTopoGraphHash`, and the committed `trails.lock` omits the wallclock `generatedAt` field so recompiling unchanged sources yields a byte-identical lock. `TopoGraph.generatedAt` is now optional; locks written by earlier versions still parse.
+- [`a89d469`](https://github.com/outfitter-dev/trails/commit/a89d4696aa78f3dda9394c14665ab3ea8c0f313c): Make the per-user topo store an honest cache (TRL-1196). Every snapshot now records a content fingerprint of the app source set (`topo_snapshots.source_fingerprint`, store schema v14), `trails compile` reports it in its output, and Wayfinder artifact loading compares it against a freshly derived fingerprint — a mismatch surfaces as a `topo-store-source-fingerprint-mismatch` stale reason instead of silently serving pre-edit facts. Compile derives everything from live source on every run, so a poisoned or stale store can never reach `trails.lock`, with or without `--force`.
+- [`a89d469`](https://github.com/outfitter-dev/trails/commit/a89d4696aa78f3dda9394c14665ab3ea8c0f313c): Add the lock round-trip invariant gate (TRL-1200): `trails release smoke --check lock-roundtrip` discovers every committed `trails.lock`, recompiles each against a cold per-user store in a temporary state home, and asserts `validate` is green and the recompiled lock is byte-identical to the committed one. Failure output names the diverging section and the `trails compile` command that fixes it — hand-editing a lock is never the remediation. Wired into `bun run check` and the CI Governance job via `bun run lock:roundtrip`.
+
+## 1.0.0-beta.38
+
+## 1.0.0-beta.37
+
+### Patch Changes
+
+- [`09f15de`](https://github.com/outfitter-dev/trails/commit/09f15def8fcc8c28b0d604f436e6eeed46da8f37): Stage wide-net Regrade expansion candidates as structured plan review inventory with evidence, status, and pending counts.
+
+## 1.0.0-beta.36
+
+### Patch Changes
+
+- [`6e63e48`](https://github.com/outfitter-dev/trails/commit/6e63e483617b84cb6868d0c4d58d5b5a8d3b9ed2): Complete the v1 grouped surface-entry vocabulary cutover from facet to trailhead, including Regrade dogfood support for governed string literal renames and composed AST rewrite application.
+- [`26786a1`](https://github.com/outfitter-dev/trails/commit/26786a14acbe9ed03f69adbdac22968891e33df1): Persist vocabulary Regrade plan artifacts, expose plan/check/preview/apply flows across CLI and MCP, and write applied plan history for reviewed vocabulary migrations.
+
+## 1.0.0-beta.35
+
+## 1.0.0-beta.34
+
+### Patch Changes
+
+- [`d67558b`](https://github.com/outfitter-dev/trails/commit/d67558bea3bfa363ed57e0f4091b6eccbf2a7710): Run governed AST symbol renames from the registry-backed `trails regrade` command path, including MCP parity, while preserving derived live API forms.
+
+## 1.0.0-beta.33
+
+### Patch Changes
+
+- [`04a6057`](https://github.com/outfitter-dev/trails/commit/04a6057502281fb81d1eb77df140d07181bfdd07): Clean generated release output by suppressing internal dependency cascade noise in package changelogs and rendering generated release PR and GitHub Release notes from the same Highlights, Changes, and Package Versions summary.
+- [`0c40138`](https://github.com/outfitter-dev/trails/commit/0c40138efb962e779710daa172bdfd756d9d992f): Harden vocabulary regrades by deferring Markdown code contexts for review and
+  exposing structured preserve rules through the Trails `regrade` command.
+- [`7d65189`](https://github.com/outfitter-dev/trails/commit/7d65189cc33408755fe07a0b5679f1ed01123455): Expose derived live-API preserve inventory in vocabulary Regrade runs and have the Trails operator regrade surface derive current facet API preserves from live topo and MCP surface facts.
+- [`04bb8a4`](https://github.com/outfitter-dev/trails/commit/04bb8a42af4ada51a74b1d8c83697db92035b5e9): Expose vocabulary Regrade occurrence dispositions and disposition summary counts alongside mechanical verdicts.
+
+  Accept explicit preserve-rule dispositions through the `trails regrade` CLI/MCP contract.
+
 ## 1.0.0-beta.32
 
 ### Patch Changes

package/README.md

@@ -16,9 +16,9 @@ Common workflows:
 - `trails compile` writes root `trails.lock`.
 - `trails validate` checks root `trails.lock` for drift.
 - `trails wayfind`, `trails wayfind --trails --intent read`, `trails wayfind <id> --contract`, `trails wayfind <id> --deps`, `trails wayfind <id> --impact`, `trails wayfind pattern "wayfind.*"`, `trails wayfind query "release drift"`, `trails wayfind file <file> --outline`, and `trails wayfind diff ...` read graph artifacts and source outlines through Wayfinder for local navigation.
-- `trails schema <command...>` shows accepted CLI routes, aliases, flags, and schemas for an operator command.
+- `trails schema <command...>` shows accepted CLI routes, aliases, flags, and schemas for an operator command or command namespace.
 - `trails warden` runs Trails governance checks for contract and architecture drift. Use `--scope-exclude <glob>` or project `warden.scope.exclude` config when local notes, scratch space, or generated state should not be governed by Warden.
-- `trails regrade --root-dir <path> --json` dry-runs downstream migration checks; add `--apply` only to write safe rewrites. Use `trails regrade <from> <to> --root-dir <path> --json` for occurrence-level vocabulary regrade reports that include the authored plan, observed ledger, completion gate, and scan inventory by file type and top-level path. Add `--exclude <glob>` to keep migration scope away from local notes, scratch space, generated state, or other paths that should not be scanned for that transition; project config can provide `regrade.scope` defaults and explicit plan inputs override them. The same `regrade` trail is exposed through MCP for agent-driven migration checks.
+- `trails regrade plan <from> <to> --root-dir <path> --json` writes an active Regrade plan, `trails regrade plan --expand` stages wide-net review candidates in that plan, `trails regrade preview` reruns it without writing, and `trails regrade apply` consumes the plan and writes history. Use `plan --expand --dry-run` to inspect staged candidates without writing the active plan, and add `--dry-run` to `apply` to prove the apply path without mutating source. Use `trails regrade plans` and `trails regrade check` when a workspace has active plans that need inspection before apply. MCP exposes the same lifecycle as `trails_plan_regrade`, `trails_list_regrades`, `trails_check_regrade`, `trails_preview_regrade`, and `trails_apply_regrade`.
 - `trails guide` remains available for compatibility; prefer `trails wayfind --source live --module <app-module>` or saved-artifact Wayfinder reads for agent navigation.
 
 Trails is contract-first: define trails once with typed input, Result output, examples, and meta; the framework derives CLI, MCP, HTTP, and future surfaces from the same contracts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/trails",
-  "version": "1.0.0-beta.32",
+  "version": "1.0.0-beta.39",
   "bin": {
     "trails": "./bin/trails.ts"
   },
@@ -27,25 +27,26 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
-    "@ontrails/adapter-kit": "^1.0.0-beta.32",
-    "@ontrails/cli": "^1.0.0-beta.32",
-    "@ontrails/commander": "^1.0.0-beta.32",
-    "@ontrails/config": "^1.0.0-beta.32",
-    "@ontrails/core": "^1.0.0-beta.32",
-    "@ontrails/http": "^1.0.0-beta.32",
-    "@ontrails/mcp": "^1.0.0-beta.32",
-    "@ontrails/observe": "^1.0.0-beta.32",
-    "@ontrails/permits": "^1.0.0-beta.32",
-    "@ontrails/regrade": "^1.0.0-beta.32",
-    "@ontrails/topographer": "^1.0.0-beta.32",
-    "@ontrails/tracing": "^1.0.0-beta.32",
-    "@ontrails/warden": "^1.0.0-beta.32",
-    "@ontrails/wayfinder": "^1.0.0-beta.32",
+    "@ontrails/adapter-kit": "^1.0.0-beta.39",
+    "@ontrails/cli": "^1.0.0-beta.39",
+    "@ontrails/commander": "^1.0.0-beta.39",
+    "@ontrails/config": "^1.0.0-beta.39",
+    "@ontrails/core": "^1.0.0-beta.39",
+    "@ontrails/http": "^1.0.0-beta.39",
+    "@ontrails/mcp": "^1.0.0-beta.39",
+    "@ontrails/observe": "^1.0.0-beta.39",
+    "@ontrails/permits": "^1.0.0-beta.39",
+    "@ontrails/regrade": "^1.0.0-beta.39",
+    "@ontrails/topographer": "^1.0.0-beta.39",
+    "@ontrails/tracing": "^1.0.0-beta.39",
+    "@ontrails/warden": "^1.0.0-beta.39",
+    "@ontrails/wayfinder": "^1.0.0-beta.39",
     "commander": "^14.0.3",
     "typescript": "^5.9.3",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@ontrails/testing": "^1.0.0-beta.32"
+    "@ontrails/cloudflare": "^1.0.0-beta.39",
+    "@ontrails/testing": "^1.0.0-beta.39"
   }
 }

package/src/app.ts

@@ -1,4 +1,4 @@
-import { topo } from '@ontrails/core';
+import { surfaceOverlay, topo } from '@ontrails/core';
 import {
   wayfindAdaptersTrail,
   wayfindContoursTrail,
@@ -7,7 +7,8 @@ import {
   wayfindDiffTrail,
   wayfindErrorsTrail,
   wayfindExamplesTrail,
-  wayfindFacetsTrail,
+  wayfindOverlayTrail,
+  wayfindTrailheadsTrail,
   wayfindImpactTrail,
   wayfindNearbyTrail,
   wayfindOverviewTrail,
@@ -111,15 +112,16 @@ const cliWayfinderSupportTrails = {
   wayfindDescribeTrail,
   wayfindErrorsTrail,
   wayfindExamplesTrail,
-  wayfindFacetsTrail,
   wayfindImpactTrail,
   wayfindNearbyTrail,
   wayfindOutlineTrail,
+  wayfindOverlayTrail,
   wayfindOverviewTrail,
   wayfindResourcesTrail,
   wayfindSearchTrail,
   wayfindSignalsTrail,
   wayfindSurfacesTrail,
+  wayfindTrailheadsTrail,
   wayfindTrailsTrail,
   wayfindVersionsTrail,
 };
@@ -138,8 +140,27 @@ export const trailsCliIncludedTrails = [
   ]),
 ];
 
-export const trailsCliAliases = {
-  'survey.diff': [['diff']],
-} as const;
+export const trailsOverlays = [
+  surfaceOverlay({
+    cli: { diff: 'survey.diff' },
+    // Authored, lockable default for the operator MCP `inspect` trailhead.
+    // The call-site map in `mcp-options.ts` overrides it at runtime with
+    // richer metadata (description, deferred loading) over the same members.
+    mcp: {
+      inspect: [
+        'survey',
+        'topo',
+        'guide',
+        'survey.brief',
+        'survey.diff',
+        'survey.resource',
+        'survey.signal',
+        'survey.surfaces',
+        'survey.trail',
+        'topo.history',
+      ],
+    },
+  }),
+];
 
 export const app = topo('trails', operatorTrails, cliWayfinderTrails);

package/src/cli.ts

@@ -21,7 +21,7 @@ import type { CreateProgramOptions } from '@ontrails/commander';
 import { resolvePermitFromBearerToken } from '@ontrails/permits';
 import { deriveTopoGraph } from '@ontrails/topographer';
 
-import { app, trailsCliAliases, trailsCliIncludedTrails } from './app.js';
+import { app, trailsCliIncludedTrails, trailsOverlays } from './app.js';
 import { resolveInputWithClack } from './clack.js';
 import { getRetiredTopoCommandDiagnostic } from './retired-topo-command.js';
 import { attachCompletionsInstallCommand } from './run-completions-install.js';
@@ -302,11 +302,11 @@ const runSurfaceOnce = async (): Promise<void> => {
   const session = maybeInstallTraceSession();
   try {
     const surfaceOptions = {
-      aliases: trailsCliAliases,
       description: 'Agent-native, contract-first TypeScript framework',
       include: trailsCliIncludedTrails,
       name: 'trails',
       onResult: buildOnResult(session),
+      overlays: trailsOverlays,
       presets: [
         outputModePreset(),
         tracePreset(),

package/src/mcp-app.ts

@@ -6,6 +6,7 @@ import {
   wayfindDiffTrail,
   wayfindErrorsTrail,
   wayfindExamplesTrail,
+  wayfindOverlayTrail,
   wayfindImpactTrail,
   wayfindNearbyTrail,
   wayfindOverviewTrail,
@@ -32,6 +33,7 @@ export const trailsMcpApp = topo('trails', operatorTrails, {
   wayfindImpactTrail,
   wayfindNearbyTrail,
   wayfindOutlineTrail,
+  wayfindOverlayTrail,
   wayfindOverviewTrail,
   wayfindResourcesTrail,
   wayfindSearchTrail,

package/src/mcp-options.ts

@@ -1,4 +1,9 @@
-import type { CreateServerOptions, McpSurfaceFacetMap } from '@ontrails/mcp';
+import type {
+  CreateServerOptions,
+  McpSurfaceTrailheadMap,
+} from '@ontrails/mcp';
+
+import { trailsOverlays } from './app.js';
 
 export const trailsMcpIncludedTrails = [
   'adapter.check',
@@ -14,7 +19,12 @@ export const trailsMcpIncludedTrails = [
   'doctor',
   'draft.promote',
   'guide',
-  'regrade',
+  'adjust.regrade',
+  'apply.regrade',
+  'check.regrade',
+  'list.regrades',
+  'plan.regrade',
+  'preview.regrade',
   'release.check',
   'release.smoke',
   'revise',
@@ -47,7 +57,7 @@ export const trailsMcpIncludedTrails = [
   'wayfind.trails',
 ] as const;
 
-export const trailsMcpFacets = {
+export const trailsMcpTrailheads = {
   inspect: {
     description:
       'Inspect saved topo structure, resources, signals, surfaces, and diffs.',
@@ -65,13 +75,17 @@ export const trailsMcpFacets = {
       'topo.history',
     ],
   },
-} satisfies McpSurfaceFacetMap;
+} satisfies McpSurfaceTrailheadMap;
 
 export const trailsMcpSurfaceOptions = {
   description:
-    'Trails framework operator surface. Use MCP resources for cold context, direct tools for high-signal work, and the inspect facet for saved topo reads.',
-  facets: trailsMcpFacets,
+    'Trails framework operator surface. Use MCP resources for cold context, direct tools for high-signal work, and the inspect trailhead for saved topo reads.',
   include: trailsMcpIncludedTrails,
   mcpResources: { examples: true, graph: true, surfaceMap: true },
   name: 'trails',
+  // The overlay authors the lockable `inspect` default; the call-site map
+  // below is the runtime override-in-context with richer metadata
+  // (description, deferred loading) over the same member selectors.
+  overlays: trailsOverlays,
+  trailheads: trailsMcpTrailheads,
 } satisfies CreateServerOptions;

package/src/regrade/history.ts

@@ -0,0 +1,320 @@
+/**
+ * Consolidated, append-only Regrade transition history. One file per
+ * transition at `.trails/regrade/history/<transition>.json`; each apply
+ * appends a run entry stamped with the plan content hash and the lock hash
+ * observed at that run.
+ */
+
+import { InternalError, Result, ValidationError } from '@ontrails/core';
+import type { Result as TrailsResult } from '@ontrails/core';
+import { regradeReportOutput } from '@ontrails/regrade';
+import type { RegradeReport } from '@ontrails/regrade';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { z } from 'zod';
+
+import {
+  regradePlanArtifactSchema,
+  regradePlanContentHash,
+  regradePlanDirectory,
+  regradePlanSlugForBody,
+  regradeSourceHash,
+  rootRelativePath,
+} from './plan-artifact.js';
+import type { RegradePlanArtifact, RegradePlanBody } from './plan-artifact.js';
+
+/**
+ * Consolidated history schema version. Version 1 was the retired
+ * one-file-per-run shape whose filename carried the lock hash.
+ */
+export const REGRADE_HISTORY_SCHEMA_VERSION = 2;
+
+const regradeHistoryRunSchema = z
+  .object({
+    lockHashAtRun: z
+      .string()
+      .min(1)
+      .describe('Regrade source hash observed when this run applied'),
+    plan: regradePlanArtifactSchema.describe(
+      'Plan artifact consumed by this run'
+    ),
+    planContentHash: z
+      .string()
+      .min(1)
+      .describe('Canonical content hash of the resolved plan body'),
+    report: regradeReportOutput.describe('Applied report recorded by the run'),
+  })
+  .strict();
+
+const regradeHistoryArtifactSchema = z
+  .object({
+    id: z.string().min(1).describe('Stable transition identity'),
+    kind: z.literal('regrade-history'),
+    path: z.string().describe('Root-relative consolidated history path'),
+    runs: z.array(regradeHistoryRunSchema).min(1),
+    schemaVersion: z.literal(REGRADE_HISTORY_SCHEMA_VERSION),
+  })
+  .strict();
+
+interface RegradeHistoryRun {
+  readonly lockHashAtRun: string;
+  readonly plan: RegradePlanArtifact;
+  readonly planContentHash: string;
+  readonly report: RegradeReport;
+}
+
+export interface RegradeHistoryArtifact {
+  readonly id: string;
+  readonly kind: 'regrade-history';
+  readonly path: string;
+  readonly runs: readonly RegradeHistoryRun[];
+  readonly schemaVersion: typeof REGRADE_HISTORY_SCHEMA_VERSION;
+}
+
+export interface RegradeHistorySummary {
+  readonly path: string;
+  readonly schemaVersion: number;
+  readonly status: 'applied' | 'replay';
+}
+
+export const regradeHistoryPathForPlan = (
+  rootDir: string,
+  plan: RegradePlanBody
+): string =>
+  join(
+    regradePlanDirectory(rootDir),
+    'history',
+    `${regradePlanSlugForBody(plan)}.json`
+  );
+
+export const readRegradeHistoryArtifact = (
+  path: string
+): TrailsResult<RegradeHistoryArtifact, InternalError | ValidationError> => {
+  if (!existsSync(path)) {
+    return Result.err(
+      new ValidationError(`Regrade history "${path}" not found.`)
+    );
+  }
+  let parsedJson: unknown;
+  try {
+    parsedJson = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    return Result.err(
+      new InternalError('Failed to read Regrade history artifact.', {
+        ...(error instanceof Error ? { cause: error } : {}),
+        context: { path },
+      })
+    );
+  }
+  const parsed = regradeHistoryArtifactSchema.safeParse(parsedJson);
+  if (!parsed.success) {
+    return Result.err(
+      new ValidationError('Invalid Regrade history artifact.', {
+        context: { issues: parsed.error.issues, path },
+      })
+    );
+  }
+  return Result.ok(parsed.data as unknown as RegradeHistoryArtifact);
+};
+
+/**
+ * Deterministic transition identity minted at the first recorded run and
+ * preserved for the life of the consolidated history file.
+ */
+export const mintTransitionId = (
+  slug: string,
+  planContentHash: string,
+  lockHashAtRun: string
+): string =>
+  createHash('sha256')
+    .update(`${slug}\n${planContentHash}\n${lockHashAtRun}`)
+    .digest('hex')
+    .slice(0, 12);
+
+/**
+ * Append one applied run to the transition's consolidated history file. A
+ * run whose plan content hash and lock hash both equal the last recorded
+ * run's stamps is a replay: nothing is written and `status: 'replay'` is
+ * surfaced instead of a duplicate record.
+ */
+export const appendRegradeHistoryRun = (params: {
+  readonly artifact: RegradePlanArtifact;
+  readonly report: RegradeReport;
+  readonly rootDir: string;
+}): TrailsResult<RegradeHistorySummary, Error> => {
+  const absolutePath = regradeHistoryPathForPlan(
+    params.rootDir,
+    params.artifact.plan
+  );
+  const relativePath = rootRelativePath(params.rootDir, absolutePath);
+  const planContentHash = regradePlanContentHash(params.artifact.plan);
+  const lockHashAtRun = regradeSourceHash(params.report);
+  const entry: RegradeHistoryRun = {
+    lockHashAtRun,
+    plan: params.artifact,
+    planContentHash,
+    report: params.report,
+  };
+
+  let prior: RegradeHistoryArtifact | undefined;
+  if (existsSync(absolutePath)) {
+    const existing = readRegradeHistoryArtifact(absolutePath);
+    if (existing.isErr()) {
+      return existing;
+    }
+    prior = existing.value;
+    if (
+      params.artifact.transitionId !== undefined &&
+      params.artifact.transitionId !== prior.id
+    ) {
+      return Result.err(
+        new ValidationError(
+          'Regrade plan transition id mismatch — refusing to fork the consolidated history.',
+          {
+            context: {
+              history: prior.id,
+              path: relativePath,
+              plan: params.artifact.transitionId,
+            },
+          }
+        )
+      );
+    }
+    const lastRun = prior.runs.at(-1);
+    // A plan that carries the transition id (adjust round-trips, plan
+    // re-derivation) may evolve the plan identity on the same spine. A plan
+    // WITHOUT the id that disagrees with the recorded plan identity is a
+    // name collision, not a continuation — refuse instead of mixing runs
+    // from unrelated transitions into one history.
+    if (
+      params.artifact.transitionId === undefined &&
+      lastRun !== undefined &&
+      lastRun.plan.plan.id !== params.artifact.plan.id
+    ) {
+      return Result.err(
+        new ValidationError(
+          'Regrade history already records a different plan identity under this transition name. Use `regrade adjust <transition>` to continue it, or pick a different plan name.',
+          {
+            context: {
+              history: lastRun.plan.plan.id,
+              path: relativePath,
+              plan: params.artifact.plan.id,
+            },
+          }
+        )
+      );
+    }
+    if (
+      lastRun !== undefined &&
+      lastRun.planContentHash === planContentHash &&
+      lastRun.lockHashAtRun === lockHashAtRun
+    ) {
+      return Result.ok({
+        path: relativePath,
+        schemaVersion: REGRADE_HISTORY_SCHEMA_VERSION,
+        status: 'replay',
+      });
+    }
+  }
+
+  const artifact: RegradeHistoryArtifact = {
+    id:
+      prior === undefined
+        ? (params.artifact.transitionId ??
+          mintTransitionId(
+            regradePlanSlugForBody(params.artifact.plan),
+            planContentHash,
+            lockHashAtRun
+          ))
+        : prior.id,
+    kind: 'regrade-history',
+    path: relativePath,
+    runs: prior === undefined ? [entry] : [...prior.runs, entry],
+    schemaVersion: REGRADE_HISTORY_SCHEMA_VERSION,
+  };
+  const parsed = regradeHistoryArtifactSchema.safeParse(artifact);
+  if (!parsed.success) {
+    return Result.err(
+      new ValidationError('Invalid Regrade history artifact.', {
+        context: { issues: parsed.error.issues, path: relativePath },
+      })
+    );
+  }
+  try {
+    mkdirSync(dirname(absolutePath), { recursive: true });
+    writeFileSync(absolutePath, `${JSON.stringify(parsed.data, null, 2)}\n`);
+  } catch (error) {
+    return Result.err(
+      new InternalError('Failed to write Regrade history entry.', {
+        ...(error instanceof Error ? { cause: error } : {}),
+        context: { path: relativePath },
+      })
+    );
+  }
+  return Result.ok({
+    path: relativePath,
+    schemaVersion: REGRADE_HISTORY_SCHEMA_VERSION,
+    status: 'applied',
+  });
+};
+
+/**
+ * Verify every recorded run at its own stamped lock: recompute the plan
+ * content hash and lock hash from the recorded plan and report, then compare
+ * with the stamped values.
+ */
+export const verifyRegradeHistoryRuns = (
+  artifact: RegradeHistoryArtifact
+): TrailsResult<{ readonly runs: number }, ValidationError> => {
+  for (const [index, run] of artifact.runs.entries()) {
+    if (regradePlanContentHash(run.plan.plan) !== run.planContentHash) {
+      return Result.err(
+        new ValidationError('Regrade history run stamp mismatch.', {
+          context: {
+            field: 'planContentHash',
+            path: artifact.path,
+            run: index,
+          },
+        })
+      );
+    }
+    if (regradeSourceHash(run.report) !== run.lockHashAtRun) {
+      return Result.err(
+        new ValidationError('Regrade history run stamp mismatch.', {
+          context: { field: 'lockHashAtRun', path: artifact.path, run: index },
+        })
+      );
+    }
+  }
+  return Result.ok({ runs: artifact.runs.length });
+};
+
+const hasPathSeparator = (value: string): boolean =>
+  value.includes('/') || value.includes('\\');
+
+/**
+ * Resolve a transition name (with or without a `.json` suffix) to its
+ * consolidated history file. Path references are rejected — graduated
+ * history lookups are by transition name only.
+ */
+export const resolveRegradeHistoryPath = (
+  rootDir: string,
+  ref: string
+): TrailsResult<string, ValidationError> => {
+  if (hasPathSeparator(ref) || isAbsolute(ref)) {
+    return Result.err(
+      new ValidationError(
+        `Regrade history reference "${ref}" must be a transition name.`
+      )
+    );
+  }
+  const name = ref.endsWith('.json') ? ref.slice(0, -'.json'.length) : ref;
+  const path = join(regradePlanDirectory(rootDir), 'history', `${name}.json`);
+  if (!existsSync(path)) {
+    return Result.err(
+      new ValidationError(`No Regrade history for transition "${ref}" found.`)
+    );
+  }
+  return Result.ok(path);
+};

package/src/regrade/live-api-preserve.ts

@@ -0,0 +1,8 @@
+import type {
+  VocabularyPreserveInventoryEntry,
+  VocabularyRegradePlan,
+} from '@ontrails/regrade';
+
+export const deriveLiveApiPreserveInventory = async (
+  _plan: VocabularyRegradePlan
+): Promise<readonly VocabularyPreserveInventoryEntry[]> => [];