Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
fix(hypit): namespace persisted route history
rpone1cb05da23991
diff --git a/.agents/skills/hypit/SKILL.md b/.agents/skills/hypit/SKILL.mdindex 716dd44b..67b051e2 100644--- a/.agents/skills/hypit/SKILL.md+++ b/.agents/skills/hypit/SKILL.md@@ -42,8 +42,11 @@ Cue and will overflow the Canvas. Read`references/script-time.md` and the caption craft before writing Script text; put breaks betweencomplete Alignment Units, never inside Dual Text.-Every route is resumable. At the start of a route, create the project's-`.hypit/route-state.json`; after any new turn, interruption, or context compaction, read+Every route is resumable. At the start of a route, create the project's current+`.hypit/route-state.json` view; the execution history lives at+`.hypit/routes/<route-id>/state.json`. Revisions likewise keep the current+`.hypit/revision-state.json` view and execution history under `.hypit/revisions/<revision-id>/`.+After any new turn, interruption, or context compaction, read`references/recovery.md`, inspect that snapshot and reconcile it against the artifacts and checksbefore continuing. Never resume from chat memory alone, and never repeat a completed or paid stepwithout verifying its durable evidence.diff --git a/.agents/skills/hypit/references/authoring.md b/.agents/skills/hypit/references/authoring.mdindex 304a2183..2857855a 100644--- a/.agents/skills/hypit/references/authoring.md+++ b/.agents/skills/hypit/references/authoring.md@@ -35,8 +35,9 @@ syntax, its references, its graph structure — and proves nothing about whethercan actually be built, nor that an uncertain requirement was understood correctly. `preview.md`proves the Run traces, before any Provider is reached.-Route commands write durable evidence to `.hypit/route-state.json`. If context is compressed, read-`recovery.md`, reconcile the project, and resume from the reported `next_action`.+Route commands point `.hypit/route-state.json` at execution-scoped, content-addressed durable evidence.+If context is compressed, read `recovery.md`, reconcile the project, and resume from the reported+`next_action`.## Reuse an accepted Recorddiff --git a/.agents/skills/hypit/references/brief-intake.md b/.agents/skills/hypit/references/brief-intake.mdindex af589d6c..b36056c2 100644--- a/.agents/skills/hypit/references/brief-intake.md+++ b/.agents/skills/hypit/references/brief-intake.md@@ -55,7 +55,8 @@ the brief unfrozen while any unresolved answer could change the program's intent## Durable brief-Persist a concise `.hypit/brief` file (JSON or Markdown; do not put it in Author Source) containing:+Persist a concise JSON object at the one canonical path `.hypit/brief.json` (do not put it in Author+Source) containing:- user goal and audience;- intent, Hook/attention strategy and narrative progression;@@ -64,6 +65,12 @@ Persist a concise `.hypit/brief` file (JSON or Markdown; do not put it in Author- confirmed decisions and unresolved questions;- the expected SVML/SVS/SVRun structural consequences.+Write it atomically. It may be refined before `brief-frozen`; after that checkpoint its recorded+digest is immutable, and any mismatch is a recovery conflict rather than permission to overwrite+the old intent. Do not create `.hypit/brief`, `.hypit/brief.md`, or a second route-specific base brief.+Revision records its own request under `.hypit/revisions/<revision-id>/request.json` and never rewrites+the base brief.+Checkpoint `brief-frozen` only after unresolved questions no longer affect those consequences. Anagent may select fonts, package details and model tier when they are genuinely low risk; it may notinvent core facts, ranking criteria, claims, Hook or audience promises. The brief is the reference fordiff --git a/.agents/skills/hypit/references/original-authoring/route.md b/.agents/skills/hypit/references/original-authoring/route.mdindex c2b78fe4..b41f0d85 100644--- a/.agents/skills/hypit/references/original-authoring/route.md+++ b/.agents/skills/hypit/references/original-authoring/route.md@@ -102,7 +102,7 @@ exists, enumerate complete projects, and compare any semantically relevant projeintent, Hook and narrative to the request. If no example is semantically relevant, use the document'sgeneral fallback; absence of an example is not permission to guess or skip intake.-Ask only for unresolved, high-impact creative decisions. Freeze a concise `.hypit/brief` recording+Ask only for unresolved, high-impact creative decisions. Freeze a concise `.hypit/brief.json` recordingthe user's goal, audience, intent, Hook, narrative progression, visual/audio/text relationships,claims, confirmed decisions, unresolved questions, and expected SVML/SVS/SVRun consequences. Low-riskimplementation details are yours; core facts, claims, Hook and audience promise require confirmation.diff --git a/.agents/skills/hypit/references/quickstart.md b/.agents/skills/hypit/references/quickstart.mdindex c2506a3d..70be0bae 100644--- a/.agents/skills/hypit/references/quickstart.md+++ b/.agents/skills/hypit/references/quickstart.md@@ -37,7 +37,8 @@ For execution, preserve the full lifecycle: select the Profile, inspect the froz`runtime up` when preflight is not ready, submit a fresh automatically identified Build, inspect itsaccepted Records, retrieve Artifacts, and declare any reuse explicitly in a new Run Source.-Both production routes persist progress in `.hypit/route-state.json`; after an interruption, follow+Both production routes expose current progress in `.hypit/route-state.json` and preserve each+execution under `.hypit/routes/<route-id>/`; after an interruption, follow`references/recovery.md` and reconcile before resuming. Before `preview_check`, run`inspect_svml_vocabulary --run`, `validate_local_author_packages --run` and`validate_script_cues --run`; the preview and final checks repeat these gates.diff --git a/.agents/skills/hypit/references/recovery.md b/.agents/skills/hypit/references/recovery.mdindex 37e37c79..16c5fbf3 100644--- a/.agents/skills/hypit/references/recovery.md+++ b/.agents/skills/hypit/references/recovery.md@@ -1,8 +1,11 @@# Recovering a Hypit route after interruption or context compactionTreat every new turn as a possible context boundary. Do not continue from the chat transcript alone.-The durable source of progress is the project's `.hypit/route-state.json`; the durable source of truth-is the artifacts and checks it points to.+The project's `.hypit/route-state.json` is the current route view. Its `route_id` binds it to the+execution history at `.hypit/routes/<route-id>/state.json`; the durable source of truth is that+execution state plus the artifacts and checks it points to. Check reports are content-addressed under+`.hypit/evidence/<digest>/`; same-named files directly under `.hypit/` are compatibility/current views,+not historical evidence.## Recovery sequence@@ -42,7 +45,10 @@ first unmet `next_action`. `variant_init` reuses matching initialized copies anddestinations. A component/package digest change, missing inspection evidence or file outside`allowed_changes` is a conflict, not permission to overwrite it.-For a completed project with a new natural-language change, use `.hypit/revision-state.json` and the+For a completed project with a new natural-language change, use the current+`.hypit/revision-state.json` view and the execution directory named by its `revision_id` under+`.hypit/revisions/`. The immutable request is+`.hypit/revisions/<revision-id>/request.json`. Use the`revision_state` commands described in `revision/route.md`. The project may be supplied directly andneed not have a parent creation route. When a parent route snapshot exists, reconcile it togetherwith the revision snapshot; otherwise validate the supplied Run as the baseline and start Revision@@ -55,7 +61,7 @@ fold the batch into Revision.## What the state means-The state is a small snapshot, not a transcript. It records the current route step, completed steps,+The current state file is a small view, not a transcript. It records the execution id, current route step, completed steps,manual decisions, a short next action, and pointers to files such as `state.json`, `round.json`, renderoutputs, comparison/review logs, and the final check result. Full prompts and observer prose remain intheir existing logs and are never copied into the snapshot.diff --git a/.agents/skills/hypit/references/revision/route.md b/.agents/skills/hypit/references/revision/route.mdindex 71e7e5f3..905c5afa 100644--- a/.agents/skills/hypit/references/revision/route.md+++ b/.agents/skills/hypit/references/revision/route.md@@ -18,7 +18,8 @@ authoritative.## Recovery and state-Read `../../SKILL.md`, `../recovery.md`, the project's `.hypit/revision-state.json`, `git status`, and+Read `../../SKILL.md`, `../recovery.md`, the project's current `.hypit/revision-state.json` view, its+`.hypit/revisions/<revision-id>/state.json` history state and immutable `request.json`, `git status`, andthe parent `.hypit/route-state.json` only when one exists. Start the state once.From a completed reconstruction or original-authoring route:@@ -37,11 +38,15 @@ hypit-reference-video-tools revision_state --action start \--request 'raise the captions slightly'```-The snapshot is atomic and small. It records the parent route/state digest when one exists, request-summary, impact and affected Source, durable artifact references, decisions, current stage and+The current snapshot is atomic and small. Each start gets a new `revision_id`; its state and request+are kept under `.hypit/revisions/<revision-id>/`, so a later revision cannot overwrite the earlier+history. It records the execution-scoped parent route path/digest when one exists, request summary,+impact and affected Source, durable artifact references, decisions, current stage and`next_action`. Use `revision_state read` and `revision_state reconcile` after interruption or contextcompaction; never resume from chat memory. Manual intent mapping and Source edits require an explicitcheckpoint. Machine evidence may advance only when its file/check predicate is true.+When a gate command returns `evidence`, checkpoint that immutable path; do not point revision history+at a same-named latest-result view directly under `.hypit/`.Stages are:diff --git a/.agents/skills/hypit/references/variant-expansion/route.md b/.agents/skills/hypit/references/variant-expansion/route.mdindex bde3c6cb..8fb462b1 100644--- a/.agents/skills/hypit/references/variant-expansion/route.md+++ b/.agents/skills/hypit/references/variant-expansion/route.md@@ -24,6 +24,8 @@ At the start of a new turn or after context compaction:The base locator is `<base>/.hypit/variant-expansions/<batch-id>.json`; the canonical batch state is`<batch>/.hypit/variant-expansion-state.json`. Never recover a sibling batch path from chat memory.+Batch state read-modify-write operations are serialized by a batch-local lock; variant agents update+only their own variant record so concurrent completions cannot replace one another with stale arrays.## Batch statediff --git a/packages/reference-video-tools/README.md b/packages/reference-video-tools/README.mdindex 262906ab..aa1f45e1 100644--- a/packages/reference-video-tools/README.md+++ b/packages/reference-video-tools/README.md@@ -8,8 +8,16 @@ revision-state and variant-expansion CLI subcommands, including `list_svml_packaEach command prints one JSON result to stdout. The final source files are authored by the callingagent and checked with the installed `hypit check` command.+Route and revision current views remain at `.hypit/route-state.json` and+`.hypit/revision-state.json` for compatibility. Every start also writes execution history under+`.hypit/routes/<route-id>/state.json` or `.hypit/revisions/<revision-id>/state.json`; revision requests+live beside their state as `request.json`. Machine check reports are immutable, content-addressed+files under `.hypit/evidence/<digest>/`, while same-named root files are only latest-result views.+Commands that persist a report return its immutable path as `evidence`; state checkpoints should use+that path rather than reconstructing a root filename.+For a completed project change, `revision_state --action start|read|checkpoint|reconcile` stores a-small atomic `.hypit/revision-state.json` snapshot. Revision edits Source/Recipe/Run and reruns+small atomic current snapshot plus revision-scoped history. Revision edits Source/Recipe/Run and rerunsdeterministic gates; it does not invoke a VLM/observer or perform visual review. The project may behanded in as an already completed directory: after its baseline gates pass, Revision can startwithout a parent reconstruction or description route state.diff --git a/packages/reference-video-tools/src/index.ts b/packages/reference-video-tools/src/index.tsindex 09bd3457..90714c0e 100644--- a/packages/reference-video-tools/src/index.ts+++ b/packages/reference-video-tools/src/index.ts@@ -17,6 +17,7 @@ export {checkpointRouteState,readRouteState,reconcileRouteState,+ routeExecutionStatePath,routeStatePath,startRouteState,ROUTE_STATE_STEPS,@@ -27,6 +28,8 @@ export {checkpointRevisionState,readRevisionState,reconcileRevisionState,+ revisionExecutionStatePath,+ revisionRequestPath,revisionStatePath,startRevisionState,REVISION_STATE_VERSION,diff --git a/packages/reference-video-tools/src/revision-state.ts b/packages/reference-video-tools/src/revision-state.tsindex b8d3185d..0292ea35 100644--- a/packages/reference-video-tools/src/revision-state.ts+++ b/packages/reference-video-tools/src/revision-state.ts@@ -1,6 +1,8 @@-import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";-import { createHash } from "node:crypto";-import { dirname, join, resolve } from "node:path";+import { readFile, stat } from "node:fs/promises";+import { join, resolve, sep } from "node:path";++import { readRouteState, routeExecutionStatePath } from "./route-state.js";+import { atomicJson, digestPath, executionId, persistExecutionState } from "./state-files.js";/** A durable, small snapshot for a post-completion natural-language revision. */export type RevisionStatus = "active" | "complete" | "blocked";@@ -16,7 +18,7 @@ export type RevisionStep =| "revision-complete"| "build-complete";-export const REVISION_STATE_VERSION = 1 as const;+export const REVISION_STATE_VERSION = 2 as const;export const REVISION_STEPS: readonly RevisionStep[] = ["request-captured", "impact-assessed", "intent-mapped", "source-updated", "gates-checked","preview-rendered", "review-complete", "final-checked", "revision-complete", "build-complete",@@ -28,11 +30,17 @@ export const REVISION_STEPS: readonly RevisionStep[] = [const REQUIRED_REVISION_STEPS = new Set<number>([1, 2, 3, 4, 5, 8, 9]);export type RevisionState = {- readonly version: 1;+ readonly version: 2;+ readonly revision_id: string;readonly project_root: string;readonly run?: string;readonly parent_route?: "reconstruction" | "description";readonly parent_state_digest?: string;+ readonly parent_state_path?: string;+ readonly parent_revision_id?: string;+ readonly parent_revision_digest?: string;+ readonly parent_revision_path?: string;+ readonly intent_basis: string;readonly status: RevisionStatus;readonly current_step: number;readonly completed_steps: readonly number[];@@ -41,11 +49,13 @@ export type RevisionState = {readonly impact?: readonly string[];readonly affected_source?: readonly string[];readonly artifacts: Readonly<Record<string, string>>;+ readonly artifact_digests: Readonly<Record<string, string>>;readonly decisions: readonly string[];readonly next_action: string;readonly last_command?: string;readonly last_error?: string;readonly conflicts?: readonly string[];+ readonly created_at: string;readonly updated_at: string;};@@ -73,6 +83,14 @@ export function revisionStatePath(projectRoot: string): string {return join(resolve(projectRoot), ".hypit", "revision-state.json");}+export function revisionExecutionStatePath(projectRoot: string, revisionId: string): string {+ return join(resolve(projectRoot), ".hypit", "revisions", revisionId, "state.json");+}++export function revisionRequestPath(projectRoot: string, revisionId: string): string {+ return join(resolve(projectRoot), ".hypit", "revisions", revisionId, "request.json");+}+function nextUncompleted(completed: readonly number[]): number {const done = new Set(completed);for (let step = 1; step <= REVISION_STEPS.length; step += 1) {@@ -95,8 +113,12 @@ function assertState(value: unknown, path: string): asserts value is RevisionStaif (value === null || typeof value !== "object") throw new Error(`revision state at ${path} is not an object`);const state = value as Partial<RevisionState>;if (state.version !== REVISION_STATE_VERSION) throw new Error(`revision state at ${path} has unsupported version`);+ if (typeof state.revision_id !== "string" || state.revision_id.length === 0) throw new Error(`revision state at ${path} has no revision_id`);if (typeof state.project_root !== "string" || state.project_root.length === 0) throw new Error(`revision state at ${path} has no project_root`);if (state.parent_route !== undefined && state.parent_route !== "reconstruction" && state.parent_route !== "description") throw new Error(`revision state at ${path} has invalid parent_route`);+ if (state.parent_revision_id !== undefined && typeof state.parent_revision_id !== "string") throw new Error(`revision state at ${path} has invalid parent_revision_id`);+ if (state.parent_revision_digest !== undefined && typeof state.parent_revision_digest !== "string") throw new Error(`revision state at ${path} has invalid parent_revision_digest`);+ if (state.parent_revision_path !== undefined && typeof state.parent_revision_path !== "string") throw new Error(`revision state at ${path} has invalid parent_revision_path`);if (state.run !== undefined && typeof state.run !== "string") throw new Error(`revision state at ${path} has invalid run`);if (state.request !== undefined && typeof state.request !== "string") throw new Error(`revision state at ${path} has invalid request`);if (!REVISION_STEPS.length || typeof state.status !== "string" || !["active", "complete", "blocked"].includes(state.status)) throw new Error(`revision state at ${path} has invalid status`);@@ -104,21 +126,32 @@ function assertState(value: unknown, path: string): asserts value is RevisionStaif (!Array.isArray(state.completed_steps) || state.completed_steps.some((step) => !Number.isSafeInteger(step) || step < 1 || step > REVISION_STEPS.length)) throw new Error(`revision state at ${path} has invalid completed_steps`);if (state.in_progress !== null && (state.in_progress === undefined || typeof state.in_progress !== "object" || !Number.isSafeInteger(state.in_progress.step))) throw new Error(`revision state at ${path} has invalid in_progress`);if (state.artifacts === null || typeof state.artifacts !== "object" || Array.isArray(state.artifacts)) throw new Error(`revision state at ${path} has invalid artifacts`);+ if (state.artifact_digests === null || typeof state.artifact_digests !== "object" || Array.isArray(state.artifact_digests)) throw new Error(`revision state at ${path} has invalid artifact_digests`);if (!Array.isArray(state.decisions) || state.decisions.some((item) => typeof item !== "string")) throw new Error(`revision state at ${path} has invalid decisions`);if (state.impact !== undefined && (!Array.isArray(state.impact) || state.impact.some((item) => typeof item !== "string"))) throw new Error(`revision state at ${path} has invalid impact`);if (state.affected_source !== undefined && (!Array.isArray(state.affected_source) || state.affected_source.some((item) => typeof item !== "string"))) throw new Error(`revision state at ${path} has invalid affected_source`);- if (typeof state.next_action !== "string" || typeof state.updated_at !== "string") throw new Error(`revision state at ${path} is missing recovery fields`);+ if (typeof state.intent_basis !== "string" || typeof state.next_action !== "string" || typeof state.created_at !== "string" || typeof state.updated_at !== "string") throw new Error(`revision state at ${path} is missing recovery fields`);}async function writeRevisionState(state: RevisionState): Promise<RevisionState> {- const path = revisionStatePath(state.project_root);- await mkdir(dirname(path), { recursive: true });- const temporary = `${path}.tmp-${process.pid}-${Date.now()}`;- await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, "utf8");- await rename(temporary, path);+ await persistExecutionState(state.project_root, "revision-state.json", "revisions", state.revision_id, state);return state;}+function migrateRevisionState(value: unknown): RevisionState | undefined {+ if (value === null || typeof value !== "object" || (value as { version?: unknown }).version !== 1) return undefined;+ const previous = value as Omit<RevisionState, "version" | "revision_id" | "parent_state_path" | "intent_basis" | "artifact_digests" | "created_at"> & { readonly version: 1 };+ const createdAt = typeof previous.updated_at === "string" ? previous.updated_at : new Date().toISOString();+ return {+ ...previous,+ version: REVISION_STATE_VERSION,+ revision_id: executionId("revision"),+ intent_basis: previous.parent_state_digest === undefined ? "supplied-project" : "legacy-parent-route",+ artifact_digests: {},+ created_at: createdAt,+ };+}+export async function readRevisionState(projectRoot: string): Promise<RevisionState | undefined> {const path = revisionStatePath(projectRoot);const text = await readFile(path, "utf8").catch((error: unknown) => {@@ -130,6 +163,19 @@ export async function readRevisionState(projectRoot: string): Promise<RevisionSttry { parsed = JSON.parse(text); } catch (error) {throw new Error(`revision state at ${path} is invalid JSON; original file was preserved: ${error instanceof Error ? error.message : String(error)}`);}+ const migrated = migrateRevisionState(parsed);+ if (migrated !== undefined) {+ const requestPath = revisionRequestPath(migrated.project_root, migrated.revision_id);+ await atomicJson(requestPath, { revision_id: migrated.revision_id, request: migrated.request ?? null, intent_basis: migrated.intent_basis, migrated: true });+ const requestDigest = await digestPath(requestPath);+ const state = {+ ...migrated,+ artifacts: { ...migrated.artifacts, revision_request: requestPath },+ artifact_digests: requestDigest === undefined ? migrated.artifact_digests : { ...migrated.artifact_digests, revision_request: requestDigest },+ };+ await writeRevisionState(state);+ return state;+ }assertState(parsed, path);return parsed;}@@ -138,25 +184,45 @@ export async function startRevisionState(input: RevisionStateInput): Promise<Revconst projectRoot = resolve(input.projectRoot);const existing = await readRevisionState(projectRoot);if (existing !== undefined && existing.status !== "complete") throw new Error(`project already has an active revision at ${revisionStatePath(projectRoot)}`);- const parentPath = join(projectRoot, ".hypit", "route-state.json");- const parentBytes = await readFile(parentPath).catch(() => undefined);- const parentStateDigest = input.parentStateDigest ?? (parentBytes === undefined ? undefined : `sha256:${createHash("sha256").update(parentBytes).digest("hex")}`);- let parentRoute = input.parentRoute;- if (parentRoute === undefined && parentBytes !== undefined) {- try {- const parsed = JSON.parse(parentBytes.toString()) as { route?: unknown };- if (parsed.route === "reconstruction" || parsed.route === "description") parentRoute = parsed.route;- } catch { /* parent route remains explicit/unknown; recovery can still inspect the file */ }- }+ const parentState = await readRouteState(projectRoot);+ const parentStatePath = parentState === undefined ? undefined : routeExecutionStatePath(projectRoot, parentState.route_id);+ const parentStateDigest = input.parentStateDigest ?? (parentStatePath === undefined ? undefined : await digestPath(parentStatePath));+ const parentRevisionPath = existing === undefined ? undefined : revisionExecutionStatePath(projectRoot, existing.revision_id);+ const parentRevisionDigest = parentRevisionPath === undefined ? undefined : await digestPath(parentRevisionPath);+ const parentRoute = input.parentRoute ?? (parentState?.route === "reconstruction" || parentState?.route === "description" ? parentState.route : undefined);+ const canonicalBrief = join(projectRoot, ".hypit", "brief.json");+ const briefExists = await stat(canonicalBrief).then((value) => value.isFile(), () => false);+ const intentBasis = parentRevisionPath ?? parentStatePath ?? (briefExists ? canonicalBrief : "supplied-project");const now = new Date().toISOString();+ const revisionId = executionId("revision");+ const requestPath = revisionRequestPath(projectRoot, revisionId);+ await atomicJson(requestPath, {+ revision_id: revisionId,+ request: input.request ?? null,+ intent_basis: intentBasis,+ ...(parentStatePath === undefined ? {} : { parent_state_path: parentStatePath }),+ ...(parentStateDigest === undefined ? {} : { parent_state_digest: parentStateDigest }),+ ...(existing === undefined ? {} : { parent_revision_id: existing.revision_id }),+ ...(parentRevisionPath === undefined ? {} : { parent_revision_path: parentRevisionPath }),+ ...(parentRevisionDigest === undefined ? {} : { parent_revision_digest: parentRevisionDigest }),+ captured_at: now,+ });+ const requestDigest = await digestPath(requestPath);return writeRevisionState({- version: 1, project_root: projectRoot, status: "active", current_step: 1, completed_steps: [],- in_progress: { step: 1, started_at: now }, artifacts: {}, decisions: [],+ version: REVISION_STATE_VERSION, revision_id: revisionId, project_root: projectRoot, status: "active", current_step: 1, completed_steps: [],+ in_progress: { step: 1, started_at: now }, artifacts: { revision_request: requestPath },+ artifact_digests: requestDigest === undefined ? {} : { revision_request: requestDigest }, decisions: [],...(input.run === undefined ? {} : { run: resolve(projectRoot, input.run) }),...(parentRoute === undefined ? {} : { parent_route: parentRoute }),...(parentStateDigest === undefined ? {} : { parent_state_digest: parentStateDigest }),+ ...(parentStatePath === undefined ? {} : { parent_state_path: parentStatePath }),+ ...(existing === undefined ? {} : { parent_revision_id: existing.revision_id }),+ ...(parentRevisionPath === undefined ? {} : { parent_revision_path: parentRevisionPath }),+ ...(parentRevisionDigest === undefined ? {} : { parent_revision_digest: parentRevisionDigest }),...(input.request === undefined ? {} : { request: input.request }),+ intent_basis: intentBasis,next_action: `complete ${REVISION_STEPS[0]}`,+ created_at: now,updated_at: now,});}@@ -165,6 +231,7 @@ export async function checkpointRevisionState(input: RevisionCheckpointInput): Pconst projectRoot = resolve(input.projectRoot);const existing = await readRevisionState(projectRoot);if (existing === undefined) throw new Error(`no revision state at ${revisionStatePath(projectRoot)}; run revision_state start first`);+ if (input.request !== undefined && input.request !== existing.request) throw new Error("a revision request is immutable after revision_state start; start a new revision instead");const step = stepNumber(input.step);const completed = new Set(existing.completed_steps);if (input.status === "complete") completed.add(step);@@ -175,6 +242,12 @@ export async function checkpointRevisionState(input: RevisionCheckpointInput): P...existing.artifacts,...Object.fromEntries(Object.entries(input.artifacts).map(([key, value]) => [key, resolve(projectRoot, value)])),};+ const artifactDigests: Record<string, string> = { ...existing.artifact_digests };+ for (const [key, value] of Object.entries(artifacts)) {+ if (key !== "revision_request" && !value.includes(`${sep}.hypit${sep}evidence${sep}`)) continue;+ const digest = await digestPath(value);+ if (digest !== undefined) artifactDigests[key] = digest;+ }const decisions = input.decision === undefined || input.decision.trim().length === 0 || existing.decisions.includes(input.decision)? existing.decisions : [...existing.decisions, input.decision.trim()];return writeRevisionState({@@ -182,14 +255,13 @@ export async function checkpointRevisionState(input: RevisionCheckpointInput): P...(input.run === undefined ? {} : { run: resolve(projectRoot, input.run) }),...(input.parentRoute === undefined ? {} : { parent_route: input.parentRoute }),...(input.parentStateDigest === undefined ? {} : { parent_state_digest: input.parentStateDigest }),- ...(input.request === undefined ? {} : { request: input.request }),...(input.impact === undefined ? {} : { impact: [...input.impact] }),...(input.affectedSource === undefined ? {} : { affected_source: [...input.affectedSource] }),status: input.status === "blocked" ? "blocked" : next > REVISION_STEPS.length ? "complete" : "active",current_step: next,completed_steps: completedSteps,in_progress: input.status === "in_progress" ? { step, started_at: now } : input.status === "complete" ? (next > REVISION_STEPS.length ? null : { step: next, started_at: now }) : existing.in_progress,- artifacts, decisions,+ artifacts, artifact_digests: artifactDigests, decisions,next_action: input.nextAction?.trim() || (next > REVISION_STEPS.length ? "revision complete" : `complete ${REVISION_STEPS[next - 1]}`),...(input.command === undefined ? {} : { last_command: input.command }),...(input.error === undefined ? {} : { last_error: input.error }),@@ -207,8 +279,21 @@ export async function reconcileRevisionState(projectRoot: string): Promise<Revisif (existing === undefined) return undefined;const completed = new Set(existing.completed_steps);const conflicts: string[] = [];+ for (const [key, expected] of Object.entries(existing.artifact_digests)) {+ const path = existing.artifacts[key];+ const actual = path === undefined ? undefined : await digestPath(path);+ if (actual !== expected) conflicts.push(`${key} digest changed: expected ${expected}, found ${actual ?? "missing"}`);+ }+ if (existing.parent_state_path !== undefined && existing.parent_state_digest !== undefined) {+ const actual = await digestPath(existing.parent_state_path);+ if (actual !== existing.parent_state_digest) conflicts.push(`parent route digest changed: expected ${existing.parent_state_digest}, found ${actual ?? "missing"}`);+ }+ if (existing.parent_revision_path !== undefined && existing.parent_revision_digest !== undefined) {+ const actual = await digestPath(existing.parent_revision_path);+ if (actual !== existing.parent_revision_digest) conflicts.push(`parent revision digest changed: expected ${existing.parent_revision_digest}, found ${actual ?? "missing"}`);+ }const checks: Readonly<Record<number, string>> = {- 5: "gates_check", 6: "preview_render", 8: "final_check", 10: "build",+ 1: "revision_request", 5: "gates_check", 6: "preview_render", 8: "final_check", 10: "build",};for (const [rawStep, key] of Object.entries(checks)) {const step = Number(rawStep);@@ -220,7 +305,7 @@ export async function reconcileRevisionState(projectRoot: string): Promise<Revisconst next = nextUncompleted([...completed]);const now = new Date().toISOString();const { conflicts: _old, ...base } = existing;- return writeRevisionState({+ const state: RevisionState = {...base,status: next > REVISION_STEPS.length ? "complete" : existing.status === "blocked" ? "blocked" : "active",current_step: next,@@ -229,5 +314,11 @@ export async function reconcileRevisionState(projectRoot: string): Promise<Revisnext_action: next > REVISION_STEPS.length ? "revision complete" : `complete ${REVISION_STEPS[next - 1]}`,...(conflicts.length === 0 ? {} : { conflicts }),updated_at: now,- });+ };+ const unchanged = state.status === existing.status+ && state.current_step === existing.current_step+ && JSON.stringify(state.completed_steps) === JSON.stringify(existing.completed_steps)+ && JSON.stringify(state.conflicts ?? []) === JSON.stringify(existing.conflicts ?? [])+ && state.next_action === existing.next_action;+ return unchanged ? existing : writeRevisionState(state);}diff --git a/packages/reference-video-tools/src/route-state.ts b/packages/reference-video-tools/src/route-state.tsindex 9f2f5fc5..647d278f 100644--- a/packages/reference-video-tools/src/route-state.ts+++ b/packages/reference-video-tools/src/route-state.ts@@ -1,5 +1,7 @@-import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";-import { dirname, join, resolve } from "node:path";+import { readFile, stat } from "node:fs/promises";+import { join, resolve, sep } from "node:path";++import { digestPath, executionId, persistExecutionState } from "./state-files.js";export type RouteKind = "reconstruction" | "description" | "variant" | "variant-package";export type RouteStatus = "active" | "complete" | "blocked";@@ -23,7 +25,8 @@ export type VariantPackageRouteStep =export type RouteStep = ReconstructionRouteStep | DescriptionRouteStep | VariantRouteStep | VariantPackageRouteStep;export type RouteState = {- readonly version: 2;+ readonly version: 3;+ readonly route_id: string;readonly route: RouteKind;readonly project_root: string;readonly run?: string;@@ -33,11 +36,13 @@ export type RouteState = {readonly completed_steps: readonly number[];readonly in_progress: { readonly step: number; readonly started_at: string } | null;readonly artifacts: Readonly<Record<string, string>>;+ readonly artifact_digests: Readonly<Record<string, string>>;readonly decisions: readonly string[];readonly next_action: string;readonly last_command?: string;readonly last_error?: string;readonly conflicts?: readonly string[];+ readonly created_at: string;readonly updated_at: string;};@@ -58,7 +63,8 @@ export type RouteCheckpointInput = RouteStateInput & {readonly error?: string;};-export const ROUTE_STATE_VERSION = 2 as const;+export const ROUTE_STATE_VERSION = 3 as const;+const PREVIOUS_ROUTE_STATE_VERSION = 2 as const;const LEGACY_ROUTE_STATE_VERSION = 1 as const;const LEGACY_ROUTE_STATE_STEPS: Readonly<Record<RouteKind, readonly string[]>> = {reconstruction: [@@ -97,10 +103,15 @@ export function routeStatePath(projectRoot: string): string {return join(resolve(projectRoot), ".hypit", "route-state.json");}+export function routeExecutionStatePath(projectRoot: string, routeId: string): string {+ return join(resolve(projectRoot), ".hypit", "routes", routeId, "state.json");+}+function assertRouteState(value: unknown, path: string): asserts value is RouteState {if (value === null || typeof value !== "object") throw new Error(`route state at ${path} is not an object`);const state = value as Partial<RouteState>;if (state.version !== ROUTE_STATE_VERSION) throw new Error(`route state at ${path} has unsupported version`);+ if (typeof state.route_id !== "string" || state.route_id.length === 0) throw new Error(`route state at ${path} has no route_id`);if (state.route !== "reconstruction" && state.route !== "description" && state.route !== "variant" && state.route !== "variant-package") throw new Error(`route state at ${path} has an invalid route`);if (typeof state.project_root !== "string" || state.project_root.length === 0) throw new Error(`route state at ${path} has no project_root`);if (typeof state.status !== "string" || !["active", "complete", "blocked"].includes(state.status)) throw new Error(`route state at ${path} has an invalid status`);@@ -109,13 +120,27 @@ function assertRouteState(value: unknown, path: string): asserts value is RouteSif (!Array.isArray(state.completed_steps) || state.completed_steps.some((step) => !Number.isSafeInteger(step) || step < 1)) throw new Error(`route state at ${path} has invalid completed_steps`);if (state.in_progress !== null && (state.in_progress === undefined || typeof state.in_progress !== "object" || !Number.isSafeInteger(state.in_progress.step))) throw new Error(`route state at ${path} has invalid in_progress`);if (state.artifacts === null || typeof state.artifacts !== "object" || Array.isArray(state.artifacts)) throw new Error(`route state at ${path} has invalid artifacts`);+ if (state.artifact_digests === null || typeof state.artifact_digests !== "object" || Array.isArray(state.artifact_digests)) throw new Error(`route state at ${path} has invalid artifact_digests`);if (!Array.isArray(state.decisions) || state.decisions.some((item) => typeof item !== "string")) throw new Error(`route state at ${path} has invalid decisions`);if (state.conflicts !== undefined && (!Array.isArray(state.conflicts) || state.conflicts.some((item) => typeof item !== "string"))) throw new Error(`route state at ${path} has invalid conflicts`);- if (typeof state.next_action !== "string" || typeof state.updated_at !== "string") throw new Error(`route state at ${path} is missing recovery fields`);+ if (typeof state.next_action !== "string" || typeof state.created_at !== "string" || typeof state.updated_at !== "string") throw new Error(`route state at ${path} is missing recovery fields`);}function migrateLegacyRouteState(value: unknown, path: string): RouteState | undefined {- if (value === null || typeof value !== "object" || (value as { version?: unknown }).version !== LEGACY_ROUTE_STATE_VERSION) return undefined;+ if (value === null || typeof value !== "object") return undefined;+ const version = (value as { version?: unknown }).version;+ if (version === PREVIOUS_ROUTE_STATE_VERSION) {+ const previous = value as Omit<RouteState, "version" | "route_id" | "artifact_digests" | "created_at"> & { readonly version: 2 };+ const createdAt = typeof previous.updated_at === "string" ? previous.updated_at : new Date().toISOString();+ return {+ ...previous,+ version: ROUTE_STATE_VERSION,+ route_id: executionId(previous.route ?? "route"),+ artifact_digests: {},+ created_at: createdAt,+ };+ }+ if (version !== LEGACY_ROUTE_STATE_VERSION) return undefined;const legacy = value as Partial<RouteState>;if (legacy.route !== "reconstruction" && legacy.route !== "description") throw new Error(`route state at ${path} has an invalid route`);const route = legacy.route;@@ -144,6 +169,7 @@ function migrateLegacyRouteState(value: unknown, path: string): RouteState | undconst now = new Date().toISOString();return {version: ROUTE_STATE_VERSION,+ route_id: executionId(route),route,project_root: legacy.project_root!,...(legacy.run === undefined ? {} : { run: legacy.run }),@@ -153,6 +179,7 @@ function migrateLegacyRouteState(value: unknown, path: string): RouteState | undcompleted_steps: [...new Set(completed)].sort((a, b) => a - b),in_progress: currentStep > ROUTE_STATE_STEPS[route].length ? null : { step: currentStep, started_at: now },artifacts: legacy.artifacts ?? {},+ artifact_digests: {},decisions: legacy.decisions ?? [],// Legacy prose may point past the newly inserted gates; always derive the recovery action from// the first unmet v2 stage instead of carrying that stale cursor forward.@@ -161,6 +188,7 @@ function migrateLegacyRouteState(value: unknown, path: string): RouteState | und: `complete ${ROUTE_STATE_STEPS[route][currentStep - 1]}`,...(legacy.last_command === undefined ? {} : { last_command: legacy.last_command }),...(legacy.last_error === undefined ? {} : { last_error: legacy.last_error }),+ created_at: now,updated_at: now,};}@@ -186,11 +214,7 @@ export async function readRouteState(projectRoot: string): Promise<RouteState |}async function writeRouteState(state: RouteState): Promise<RouteState> {- const path = routeStatePath(state.project_root);- await mkdir(dirname(path), { recursive: true });- const temporary = `${path}.tmp-${process.pid}-${Date.now()}`;- await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, "utf8");- await rename(temporary, path);+ await persistExecutionState(state.project_root, "route-state.json", "routes", state.route_id, state);return state;}@@ -256,10 +280,11 @@ export async function startRouteState(input: RouteStateInput): Promise<RouteStatif (existing !== undefined && existing.status !== "complete" && (existing.route !== input.route || existing.project_root !== projectRoot)) {throw new Error(`project already has an active ${existing.route} route at ${routeStatePath(projectRoot)}`);}- if (existing !== undefined && existing.route === input.route) return existing;+ if (existing !== undefined && existing.status !== "complete" && existing.route === input.route) return existing;const now = new Date().toISOString();return await writeRouteState({version: ROUTE_STATE_VERSION,+ route_id: executionId(input.route),route: input.route,project_root: projectRoot,...(input.run === undefined ? {} : { run: resolve(projectRoot, input.run) }),@@ -268,9 +293,11 @@ export async function startRouteState(input: RouteStateInput): Promise<RouteStatcurrent_step: 1,completed_steps: [],in_progress: { step: 1, started_at: now },- artifacts: {},+ artifacts: existing?.artifacts.brief === undefined ? {} : { brief: existing.artifacts.brief },+ artifact_digests: existing?.artifact_digests.brief === undefined ? {} : { brief: existing.artifact_digests.brief },decisions: [],next_action: `complete ${ROUTE_STATE_STEPS[input.route][0]}`,+ created_at: now,updated_at: now,});}@@ -280,9 +307,26 @@ export async function checkpointRouteState(input: RouteCheckpointInput): Promiseconst existing = await readRouteState(projectRoot);if (existing === undefined) throw new Error(`no route state at ${routeStatePath(projectRoot)}; run route_state start first`);if (existing.route !== input.route) throw new Error(`route state is ${existing.route}, not ${input.route}`);+ if (existing.status === "complete") throw new Error(`route ${existing.route_id} is complete; start a new route instead of rewriting its history`);const step = stepNumber(input.route, input.step);const completed = new Set(existing.completed_steps);const status = input.status ?? "complete";+ if (input.route === "description" && step === stageNumber("description", "brief-frozen") && status === "complete") {+ const brief = input.artifacts?.brief ?? existing.artifacts.brief;+ const canonical = join(projectRoot, ".hypit", "brief.json");+ if (brief === undefined || resolve(projectRoot, brief) !== canonical) {+ throw new Error(`brief-frozen requires the canonical brief at ${canonical}`);+ }+ let parsedBrief: unknown;+ try { parsedBrief = JSON.parse(await readFile(canonical, "utf8")); }+ catch (error) { throw new Error(`brief-frozen requires valid JSON at ${canonical}: ${error instanceof Error ? error.message : String(error)}`); }+ if (parsedBrief === null || typeof parsedBrief !== "object" || Array.isArray(parsedBrief)) throw new Error(`brief-frozen requires a JSON object at ${canonical}`);+ const actualDigest = await digestPath(canonical);+ const frozenDigest = existing.artifact_digests.brief;+ if (frozenDigest !== undefined && actualDigest !== frozenDigest) {+ throw new Error(`the frozen base brief changed: expected ${frozenDigest}, found ${actualDigest ?? "missing"}; use Revision or a new project`);+ }+ }if (status === "complete") {// Named checkpoints are explicit user assertions and must not jump over earlier stages. Numeric// checkpoints remain compatible with route-aware automation, which may record a later durable@@ -303,6 +347,13 @@ export async function checkpointRouteState(input: RouteCheckpointInput): PromiseObject.entries(input.artifacts).map(([key, value]) => [key, normalizeArtifact(projectRoot, key, value)]),),};+ const artifactDigests: Record<string, string> = { ...existing.artifact_digests };+ const frozenKeys = new Set(["brief", "vocabulary", "baseline_manifest", "variant_brief", "allowed_changes", "guidance", "gap_plan", "types", "package_digest"]);+ for (const [key, value] of Object.entries(artifacts)) {+ if (!frozenKeys.has(key) && !value.includes(`${sep}.hypit${sep}evidence${sep}`)) continue;+ const digest = await digestPath(value);+ if (digest !== undefined) artifactDigests[key] = digest;+ }const state: RouteState = {...existing,...(input.run === undefined ? {} : { run: resolve(projectRoot, input.run) }),@@ -316,6 +367,7 @@ export async function checkpointRouteState(input: RouteCheckpointInput): Promise? (next > ROUTE_STATE_STEPS[input.route].length ? null : { step: next, started_at: now }): existing.in_progress,artifacts,+ artifact_digests: artifactDigests,decisions,next_action: input.nextAction?.trim()|| (next > ROUTE_STATE_STEPS[input.route].length ? "route complete" : `complete ${ROUTE_STATE_STEPS[input.route][next - 1]}`),@@ -348,6 +400,12 @@ async function evidenceSatisfied(key: string, path: string | undefined): Promisereturn value.passed === true;} catch { return false; }}+ if (key === "brief") {+ try {+ const value = JSON.parse(await readFile(path, "utf8"));+ return value !== null && typeof value === "object" && !Array.isArray(value);+ } catch { return false; }+ }if (key === "final_check") {try {const value = JSON.parse(await readFile(path, "utf8")) as { passed?: unknown };@@ -387,6 +445,11 @@ export async function reconcileRouteState(projectRoot: string): Promise<RouteStaif (existing === undefined) return undefined;const completed = new Set(existing.completed_steps);const conflicts: string[] = [];+ for (const [key, expected] of Object.entries(existing.artifact_digests)) {+ const path = existing.artifacts[key];+ const actual = path === undefined ? undefined : await digestPath(path);+ if (actual !== expected) conflicts.push(`${key} digest changed: expected ${expected}, found ${actual ?? "missing"}`);+ }const artifact = (name: string): string | undefined => existing.artifacts[name];const reconcileStep = async (step: number, key: string): Promise<void> => {const renderComplete = key === "preview_render"@@ -446,5 +509,10 @@ export async function reconcileRouteState(projectRoot: string): Promise<RouteSta...(conflicts.length === 0 ? {} : { conflicts }),updated_at: now,};- return await writeRouteState(state);+ const unchanged = state.status === existing.status+ && state.current_step === existing.current_step+ && JSON.stringify(state.completed_steps) === JSON.stringify(existing.completed_steps)+ && JSON.stringify(state.conflicts ?? []) === JSON.stringify(existing.conflicts ?? [])+ && state.next_action === existing.next_action;+ return unchanged ? existing : await writeRouteState(state);}diff --git a/packages/reference-video-tools/src/state-files.ts b/packages/reference-video-tools/src/state-files.tsnew file mode 100644index 00000000..fc1ea48c--- /dev/null+++ b/packages/reference-video-tools/src/state-files.ts@@ -0,0 +1,66 @@+import { createHash, randomUUID } from "node:crypto";+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";+import { dirname, join, resolve } from "node:path";++export function executionId(kind: string, now = new Date()): string {+ const timestamp = now.toISOString().replace(/[-:]/gu, "").replace(/\.\d{3}Z$/u, "Z");+ return `${kind}-${timestamp}-${randomUUID().slice(0, 8)}`;+}++export function jsonBytes(value: unknown): Buffer {+ return Buffer.from(`${JSON.stringify(value, null, 2)}\n`, "utf8");+}++export function sha256(bytes: Uint8Array): string {+ return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;+}++export async function digestPath(path: string): Promise<string | undefined> {+ const bytes = await readFile(path).catch(() => undefined);+ return bytes === undefined ? undefined : sha256(bytes);+}++export async function atomicWrite(path: string, bytes: Uint8Array): Promise<void> {+ await mkdir(dirname(path), { recursive: true });+ const temporary = `${path}.tmp-${process.pid}-${Date.now()}-${randomUUID().slice(0, 8)}`;+ await writeFile(temporary, bytes);+ await rename(temporary, path);+}++export async function atomicJson(path: string, value: unknown): Promise<void> {+ await atomicWrite(path, jsonBytes(value));+}++export async function persistExecutionState(+ projectRoot: string,+ currentName: string,+ historyKind: "routes" | "revisions",+ executionIdValue: string,+ value: unknown,+): Promise<string> {+ const root = resolve(projectRoot);+ const historyPath = join(root, ".hypit", historyKind, executionIdValue, "state.json");+ const bytes = jsonBytes(value);+ await atomicWrite(historyPath, bytes);+ await atomicWrite(join(root, ".hypit", currentName), bytes);+ return historyPath;+}++export async function persistEvidence(+ projectRoot: string,+ currentName: string,+ value: unknown,+): Promise<string> {+ const root = resolve(projectRoot);+ const bytes = jsonBytes(value);+ const digest = sha256(bytes).slice("sha256:".length);+ const evidencePath = join(root, ".hypit", "evidence", digest, currentName);+ await mkdir(dirname(evidencePath), { recursive: true });+ await writeFile(evidencePath, bytes, { flag: "wx" }).catch(async (error: unknown) => {+ if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;+ const existing = await readFile(evidencePath);+ if (!existing.equals(bytes)) throw new Error(`immutable evidence collision at ${evidencePath}`);+ });+ await atomicWrite(join(root, ".hypit", currentName), bytes);+ return evidencePath;+}diff --git a/packages/reference-video-tools/src/tools.ts b/packages/reference-video-tools/src/tools.tsindex 54cf426d..b5457210 100644--- a/packages/reference-video-tools/src/tools.ts+++ b/packages/reference-video-tools/src/tools.ts@@ -32,6 +32,7 @@ import {checkpointRouteState,readRouteState,reconcileRouteState,+ routeExecutionStatePath,routeStatePath,startRouteState,ROUTE_STATE_STEPS,@@ -42,10 +43,13 @@ import {checkpointRevisionState,readRevisionState,reconcileRevisionState,+ revisionExecutionStatePath,+ revisionRequestPath,revisionStatePath,startRevisionState,} from "./revision-state.js";import type { RevisionState, RevisionStep } from "./revision-state.js";+import { persistEvidence } from "./state-files.js";import {checkpointVariantExpansion,discoverVariantExpansions,@@ -286,11 +290,20 @@ export type GenerateText = (input: { readonly parts: readonly Part[]; readonly itype ObservationTask = { readonly key: string; readonly request: Request };function routeStateResult(state: RouteState | undefined): Record<string, unknown> {- return state === undefined ? { state: null } : { state, path: routeStatePath(state.project_root) };+ return state === undefined ? { state: null } : {+ state,+ path: routeStatePath(state.project_root),+ history_path: routeExecutionStatePath(state.project_root, state.route_id),+ };}function revisionStateResult(state: RevisionState | undefined): Record<string, unknown> {- return state === undefined ? { state: null } : { state, path: revisionStatePath(state.project_root) };+ return state === undefined ? { state: null } : {+ state,+ path: revisionStatePath(state.project_root),+ history_path: revisionExecutionStatePath(state.project_root, state.revision_id),+ request_path: revisionRequestPath(state.project_root, state.revision_id),+ };}function variantStateResult(state: Awaited<ReturnType<typeof readVariantExpansionState>>): Record<string, unknown> {@@ -427,10 +440,7 @@ async function autoRouteCheckpoint(}async function persistRouteEvidence(runPath: string, name: string, result: Record<string, unknown>): Promise<string> {- const path = join(dirname(resolve(runPath)), ".hypit", name);- await mkdir(dirname(path), { recursive: true });- await writeFile(path, `${JSON.stringify(result, null, 2)}\n`, "utf8");- return path;+ return persistEvidence(dirname(resolve(runPath)), name, result);}async function autoRouteError(runPath: string | undefined, command: string, error: unknown): Promise<void> {@@ -480,10 +490,7 @@ async function maybeCheckpointReferenceObservation(input: RecordObservationInput}async function persistRoutePlan(runPath: string, result: Record<string, unknown>): Promise<string> {- const path = join(dirname(resolve(runPath)), ".hypit", "route-plan.json");- await mkdir(dirname(path), { recursive: true });- await writeFile(path, `${JSON.stringify({ plan: result.plan ?? [], generated_at: new Date().toISOString() }, null, 2)}\n`, "utf8");- return path;+ return persistEvidence(dirname(resolve(runPath)), "route-plan.json", { plan: result.plan ?? [], generated_at: new Date().toISOString() });}function observation(status: Observation["status"], text: string): Observation { return { status, text }; }@@ -1864,14 +1871,15 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV}}const result = { packages: input.package_names, surfaces };+ let evidence: string | undefined;if (input.run !== undefined) {const runPath = resolve(invokedFrom(), input.run);- const evidence = await persistRouteEvidence(runPath, "vocabulary.json", result);+ evidence = await persistRouteEvidence(runPath, "vocabulary.json", result);const route = await readRouteState(dirname(runPath));const step = routeStepFor(route?.route ?? "reconstruction", "vocabulary-checked");await autoRouteCheckpoint(runPath, step, { vocabulary: evidence }, "validate_local_author_packages --run <build.svrun>");}- return result;+ return evidence === undefined ? result : { ...result, evidence };},async validate_local_author_packages(input): Promise<Record<string, unknown>> {@@ -1885,7 +1893,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV: "validate_script_cues --run <build.svrun>";await autoRouteCheckpoint(runPath, step, { package_ready: evidence }, next);} else await autoRouteError(runPath, "validate_local_author_packages", (result.packages as unknown[] ?? []));- return result;+ return { ...result, evidence };},async validate_script_cues(input): Promise<Record<string, unknown>> {@@ -1897,7 +1905,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVconst step = routeStepFor(route?.route ?? "reconstruction", "script-checked");await autoRouteCheckpoint(runPath, step, { script_cues: evidence }, "write main.svml, recipes.svs and build.svrun");} else await autoRouteError(runPath, "validate_script_cues", result.violations ?? result.errors ?? "cue validation failed");- return result;+ return { ...result, evidence };},/**@@ -2490,9 +2498,9 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVconst cueGate = await scriptCueCheck({ run: input.run });if (packageGate.passed !== true || cueGate.passed !== true) {const refused = { run: runPath, sound: false, package_gate: packageGate, script_cue_gate: cueGate, refused: "package or Script Cue gate failed" };- await persistRouteEvidence(runPath, "preview-check.json", refused);+ const evidence = await persistRouteEvidence(runPath, "preview-check.json", refused);await autoRouteError(runPath, "preview_check", refused.refused);- return refused;+ return { ...refused, evidence };}const result = await previewCheck(input, { packageRoot });const evidence = await persistRouteEvidence(runPath, "preview-check.json", result);@@ -2507,7 +2515,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVconst routeAfterSource = await readRouteState(dirname(runPath));await autoRouteCheckpoint(runPath, routeStepFor(routeAfterSource?.route ?? "reconstruction", "graph-checked"), { preview_check: evidence }, next);} else await autoRouteError(runPath, "preview_check", result.refused ?? result.problems ?? "preview check failed");- return result;+ return { ...result, evidence };} catch (error) {await autoRouteError(runPath, "preview_check", error);throw error;@@ -2521,9 +2529,9 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVconst cueGate = await scriptCueCheck({ run: input.run });if (packageGate.passed !== true || cueGate.passed !== true) {const refused = { run: runPath, passed: false, package_gate: packageGate, script_cue_gate: cueGate, issues: ["package or Script Cue gate failed"] };- await persistRouteEvidence(runPath, "final-check.json", refused);+ const evidence = await persistRouteEvidence(runPath, "final-check.json", refused);await autoRouteError(runPath, "reconstruction_check", refused.issues);- return refused;+ return { ...refused, evidence };}const result = await authoringCheck({ ...input, mode: "reconstruction" }, { packageRoot });const evidence = await persistRouteEvidence(runPath, "final-check.json", result);@@ -2534,7 +2542,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV}if (result.passed === true) { const route = await readRouteState(dirname(runPath)); await autoRouteCheckpoint(runPath, routeStepFor(route?.route ?? "reconstruction", "final-checked"), { final_check: evidence }, "submit the approved Build"); }else await autoRouteError(runPath, "reconstruction_check", result.issues ?? result.unresolved ?? "reconstruction check failed");- return result;+ return { ...result, evidence };} catch (error) {await autoRouteError(runPath, "reconstruction_check", error);throw error;@@ -2548,9 +2556,9 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVconst cueGate = await scriptCueCheck({ run: input.run });if (packageGate.passed !== true || cueGate.passed !== true) {const refused = { run: runPath, passed: false, package_gate: packageGate, script_cue_gate: cueGate, issues: ["package or Script Cue gate failed"] };- await persistRouteEvidence(runPath, "final-check.json", refused);+ const evidence = await persistRouteEvidence(runPath, "final-check.json", refused);await autoRouteError(runPath, "authoring_check", refused.issues);- return refused;+ return { ...refused, evidence };}const result = await authoringCheck({ ...input, mode: "description" }, { packageRoot });const evidence = await persistRouteEvidence(runPath, "final-check.json", result);@@ -2561,7 +2569,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV}if (result.passed === true) { const route = await readRouteState(dirname(runPath)); await autoRouteCheckpoint(runPath, routeStepFor(route?.route ?? "description", "final-checked"), { final_check: evidence }, "submit the approved Build"); }else await autoRouteError(runPath, "authoring_check", result.issues ?? result.unresolved ?? "authoring check failed");- return result;+ return { ...result, evidence };} catch (error) {await autoRouteError(runPath, "authoring_check", error);throw error;@@ -2732,6 +2740,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVconst cueEvidence = await persistRouteEvidence(runPath, "script-cues.json", cueGate);const previewEvidence = await persistRouteEvidence(runPath, "preview-check.json", graphGate);const finalEvidence = await persistRouteEvidence(runPath, "variant-check.json", result);+ result.evidence = finalEvidence;if (vocabularyPassed) await autoRouteCheckpoint(runPath, routeStepFor("variant", "vocabulary-checked"), { vocabulary: vocabularyPath });if (packageGate.passed === true) await autoRouteCheckpoint(runPath, routeStepFor("variant", "package-ready"), { package_ready: packageEvidence });if (cueGate.passed === true) await autoRouteCheckpoint(runPath, routeStepFor("variant", "script-checked"), { script_cues: cueEvidence });@@ -2766,25 +2775,28 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVconst currentRoute = await readRouteState(projectRoot);const outsideScope = Array.isArray((minimalDiff as { outside_allowed_changes?: unknown }).outside_allowed_changes)&& ((minimalDiff as { outside_allowed_changes: unknown[] }).outside_allowed_changes.length > 0);- const variants = batch.variants.map((variant) => variant.project_root === projectRoot- ? { ...variant, status: currentRoute?.status === "complete" ? "complete" as const+ const updatedVariant = batch.variants.find((variant) => variant.project_root === projectRoot);+ const variantUpdate = updatedVariant === undefined ? undefined : {+ ...updatedVariant, status: currentRoute?.status === "complete" ? "complete" as const: outsideScope ? "scope-expansion-required" as const : result.passed === true ? "dispatched" as const : "failed" as const,- ...(result.passed === true ? {} : { error: outsideScope ? "scope-expansion-required" : "variant_check failed" }) }- : variant);+ ...(result.passed === true ? {} : { error: outsideScope ? "scope-expansion-required" : "variant_check failed" }),+ };batch = await checkpointVariantExpansion({projectRoot: brief.base_project_root, outputRoot: brief.batch_root,step: batch.current_step <= VARIANT_EXPANSION_STEPS.length ? batch.current_step : VARIANT_EXPANSION_STEPS.length,- status: batch.status === "blocked" ? "blocked" : "in_progress", variants,+ status: batch.status === "blocked" ? "blocked" : "in_progress",+ ...(variantUpdate === undefined ? {} : { variantUpdates: [variantUpdate] }),});+ const variants = batch.variants;const reports = await Promise.all(variants.map(async (variant) => {- const path = join(variant.project_root, ".hypit", "variant-check.json");+ const childRoute = await readRouteState(variant.project_root);+ const path = childRoute?.artifacts.variant_check ?? join(variant.project_root, ".hypit", "variant-check.json");let report: { passed?: unknown } | undefined;try { report = JSON.parse(await readFile(path, "utf8")) as { passed?: unknown }; } catch { report = undefined; }- return { id: variant.id, project_root: variant.project_root, route_complete: (await readRouteState(variant.project_root))?.status === "complete", passed: report?.passed === true, report: path };+ return { id: variant.id, project_root: variant.project_root, route_complete: childRoute?.status === "complete", passed: report?.passed === true, report: path };}));const aggregate = { passed: reports.length > 0 && reports.every((item) => item.route_complete && item.passed), variants: reports, checked_at: new Date().toISOString() };- const aggregatePath = join(resolve(brief.batch_root), ".hypit", "aggregate-check.json");- await writeVariantJson(aggregatePath, aggregate);+ const aggregatePath = await persistEvidence(brief.batch_root, "aggregate-check.json", aggregate);if (reports.every((item) => item.route_complete)) {await checkpointVariantExpansion({ projectRoot: brief.base_project_root, outputRoot: brief.batch_root, step: "variants-complete", status: "complete", variants });}diff --git a/packages/reference-video-tools/src/variant-project.ts b/packages/reference-video-tools/src/variant-project.tsindex f967d026..c6500654 100644--- a/packages/reference-video-tools/src/variant-project.ts+++ b/packages/reference-video-tools/src/variant-project.ts@@ -380,7 +380,12 @@ export async function initializeVariantProjects(input: {}await mkdir(outputRoot, { recursive: true });const width = Math.max(3, String(slate.variants.length).length);- const inheritedVocabulary = join(projectRoot, ".hypit", "vocabulary.json");+ const currentRoute = await readFile(join(projectRoot, ".hypit", "route-state.json"), "utf8")+ .then((text) => JSON.parse(text) as { artifacts?: { vocabulary?: unknown } }, () => undefined)+ .catch(() => undefined);+ const inheritedVocabulary = typeof currentRoute?.artifacts?.vocabulary === "string"+ ? currentRoute.artifacts.vocabulary+ : join(projectRoot, ".hypit", "vocabulary.json");const initialized: InitializedVariant[] = [];const assignedIds = new Set<string>();for (const [index, variant] of slate.variants.entries()) {diff --git a/packages/reference-video-tools/src/variant-state.ts b/packages/reference-video-tools/src/variant-state.tsindex b247b3b3..e71d7878 100644--- a/packages/reference-video-tools/src/variant-state.ts+++ b/packages/reference-video-tools/src/variant-state.ts@@ -1,8 +1,10 @@import { createHash } from "node:crypto";-import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";+import { mkdir, open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";-import { checkpointRouteState, readRouteState, reconcileRouteState, routeStatePath } from "./route-state.js";+import { checkpointRouteState, readRouteState, reconcileRouteState, routeExecutionStatePath, routeStatePath } from "./route-state.js";+import { readRevisionState, revisionExecutionStatePath } from "./revision-state.js";+import { persistEvidence } from "./state-files.js";import { inspectVariantDiff, snapshotProject } from "./variant-project.js";export type VariantExpansionStatus = "active" | "complete" | "blocked";@@ -72,7 +74,9 @@ export type VariantExpansionState = {readonly baseline_digest: string;readonly parent_route?: "reconstruction" | "description";readonly parent_state_digest?: string;+ readonly parent_state_path?: string;readonly revision_state_digest?: string;+ readonly revision_state_path?: string;readonly request?: string;readonly count?: number;readonly delivery_mode: "source" | "build";@@ -127,6 +131,7 @@ export type VariantExpansionCheckpointInput = {readonly workloadDisclosure?: VariantWorkloadDisclosure;readonly packages?: readonly VariantExpansionPackage[];readonly variants?: readonly VariantExpansionVariant[];+ readonly variantUpdates?: readonly VariantExpansionVariant[];readonly decision?: string;readonly conflict?: string;readonly resolveConflict?: string;@@ -154,6 +159,30 @@ async function atomicJson(path: string, value: unknown): Promise<void> {await rename(temporary, path);}+async function withStateLock<T>(outputRoot: string, work: () => Promise<T>): Promise<T> {+ const lockPath = join(resolve(outputRoot), ".hypit", "variant-expansion-state.lock");+ await mkdir(dirname(lockPath), { recursive: true });+ for (let attempt = 0; attempt < 3_000; attempt += 1) {+ const handle = await open(lockPath, "wx").catch((error: unknown) => {+ if ((error as NodeJS.ErrnoException).code === "EEXIST") return undefined;+ throw error;+ });+ if (handle !== undefined) {+ try {+ await handle.writeFile(`${process.pid}\n`, "utf8");+ return await work();+ } finally {+ await handle.close().catch(() => undefined);+ await unlink(lockPath).catch(() => undefined);+ }+ }+ const stale = await stat(lockPath).then((value) => Date.now() - value.mtimeMs > 300_000, () => false);+ if (stale) await unlink(lockPath).catch(() => undefined);+ await new Promise((resolveWait) => setTimeout(resolveWait, 10));+ }+ throw new Error(`timed out waiting for variant state lock at ${lockPath}`);+}+function assertLocator(value: unknown, path: string): asserts value is VariantExpansionLocator {if (value === null || typeof value !== "object") throw new Error(`variant locator at ${path} is not an object`);const locator = value as Partial<VariantExpansionLocator>;@@ -267,7 +296,7 @@ function requiredPriorSteps(step: number, deliveryMode: "source" | "build"): reareturn Array.from({ length: step - 1 }, (_, index) => index + 1).filter((candidate) => !optional.has(candidate));}-export async function startVariantExpansion(input: StartVariantExpansionInput): Promise<VariantExpansionState> {+async function startVariantExpansionUnlocked(input: StartVariantExpansionInput): Promise<VariantExpansionState> {const projectRoot = resolve(input.projectRoot);const outputRoot = resolve(input.outputRoot);const outputRelative = relative(projectRoot, outputRoot);@@ -285,12 +314,14 @@ export async function startVariantExpansion(input: StartVariantExpansionInput):if (resolve(locatorAtId.output_root) !== outputRoot) throw new Error(`batch id ${batchId} already points to ${locatorAtId.output_root}`);}const baseline = await snapshotProject(projectRoot);- const parentStatePath = join(projectRoot, ".hypit", "route-state.json");- const revisionStatePath = join(projectRoot, ".hypit", "revision-state.json");- const parentStateBytes = await readFile(parentStatePath).catch(() => undefined);+ const parentState = await readRouteState(projectRoot);+ const revisionState = await readRevisionState(projectRoot);+ const parentStatePath = parentState === undefined ? undefined : routeExecutionStatePath(projectRoot, parentState.route_id);+ const revisionStatePath = revisionState === undefined ? undefined : revisionExecutionStatePath(projectRoot, revisionState.revision_id);+ const parentStateBytes = parentStatePath === undefined ? undefined : await readFile(parentStatePath).catch(() => undefined);const parentStateDigest = input.parentStateDigest?? (parentStateBytes === undefined ? undefined : `sha256:${createHash("sha256").update(parentStateBytes).digest("hex")}`);- const revisionStateDigest = input.revisionStateDigest ?? await digestFile(revisionStatePath);+ const revisionStateDigest = input.revisionStateDigest ?? (revisionStatePath === undefined ? undefined : await digestFile(revisionStatePath));let parentRoute = input.parentRoute;if (parentRoute === undefined && parentStateBytes !== undefined) {try {@@ -305,7 +336,9 @@ export async function startVariantExpansion(input: StartVariantExpansionInput):baseline_digest: baseline.digest,...(parentRoute === undefined ? {} : { parent_route: parentRoute }),...(parentStateDigest === undefined ? {} : { parent_state_digest: parentStateDigest }),+ ...(parentStatePath === undefined ? {} : { parent_state_path: parentStatePath }),...(revisionStateDigest === undefined ? {} : { revision_state_digest: revisionStateDigest }),+ ...(revisionStatePath === undefined ? {} : { revision_state_path: revisionStatePath }),...(input.request === undefined ? {} : { request: input.request }),...(input.count === undefined ? {} : { count: input.count }),delivery_mode: input.deliveryMode ?? "source", status: "active", current_step: 1, completed_steps: [],@@ -314,7 +347,17 @@ export async function startVariantExpansion(input: StartVariantExpansionInput):});}-export async function checkpointVariantExpansion(input: VariantExpansionCheckpointInput): Promise<VariantExpansionState> {+export async function startVariantExpansion(input: StartVariantExpansionInput): Promise<VariantExpansionState> {+ const projectRoot = resolve(input.projectRoot);+ const outputRoot = resolve(input.outputRoot);+ const outputRelative = relative(projectRoot, outputRoot);+ if (outputRelative.length === 0 || (!outputRelative.startsWith(`..${sep}`) && outputRelative !== ".." && !isAbsolute(outputRelative))) {+ throw new Error("variant output root must not be inside the base project");+ }+ return withStateLock(outputRoot, async () => startVariantExpansionUnlocked(input));+}++async function checkpointVariantExpansionUnlocked(input: VariantExpansionCheckpointInput): Promise<VariantExpansionState> {const existing = await readVariantExpansionState(input.projectRoot, input.outputRoot, input.batchId);if (existing === undefined) throw new Error("no variant expansion state; run variant_state --action start first");const step = stepNumber(input.step);@@ -362,11 +405,13 @@ export async function checkpointVariantExpansion(input: VariantExpansionCheckpoithrow new Error(`package ${pack.id} package_root must stay inside its staging project`);}const digest = (await snapshotProject(packageRoot, { preserveTopLevelOutputs: true })).digest;- const evidence = join(resolve(pack.staging_root), ".hypit", "package-digest.json");- await atomicJson(evidence, { package_id: pack.id, staging_root: stagingRoot, package_root: packageRoot, digest, frozen_at: now });+ const evidence = await persistEvidence(pack.staging_root, "package-digest.json", { package_id: pack.id, staging_root: stagingRoot, package_root: packageRoot, digest, frozen_at: now });await checkpointRouteState({ projectRoot: pack.staging_root, route: "variant-package", step: "package-ready", status: "complete", artifacts: { package_digest: evidence } });return { ...pack, staging_root: stagingRoot, package_root: packageRoot, route_state: routeStatePath(pack.staging_root), digest };}));+ const variants = input.variantUpdates === undefined+ ? input.variants+ : existing.variants.map((variant) => input.variantUpdates!.find((update) => update.id === variant.id) ?? variant);return writeState({...existing,status: status === "blocked" ? "blocked" : next > VARIANT_EXPANSION_STEPS.length ? "complete" : "active",@@ -375,7 +420,7 @@ export async function checkpointVariantExpansion(input: VariantExpansionCheckpoiartifacts, decisions, conflicts,...(input.workloadDisclosure === undefined ? {} : { workload_disclosure: input.workloadDisclosure }),...(packages === undefined ? {} : { packages }),- ...(input.variants === undefined ? {} : { variants: input.variants }),+ ...(variants === undefined ? {} : { variants }),next_action: input.nextAction?.trim() || (next > VARIANT_EXPANSION_STEPS.length ? "variant expansion complete" : `complete ${VARIANT_EXPANSION_STEPS[next - 1]}`),...(input.command === undefined ? {} : { last_command: input.command }),...(input.error === undefined ? {} : { last_error: input.error }),@@ -383,6 +428,12 @@ export async function checkpointVariantExpansion(input: VariantExpansionCheckpoi});}+export async function checkpointVariantExpansion(input: VariantExpansionCheckpointInput): Promise<VariantExpansionState> {+ const locator = await selectedLocator(input.projectRoot, input.outputRoot, input.batchId);+ if (locator === undefined) throw new Error("no variant expansion state; run variant_state --action start first");+ return withStateLock(locator.output_root, async () => checkpointVariantExpansionUnlocked({ ...input, outputRoot: locator.output_root }));+}+async function exists(path: string | undefined): Promise<boolean> {return path !== undefined && await stat(path).then(() => true, () => false);}@@ -393,7 +444,7 @@ async function validJson(path: string | undefined, predicate: (value: unknown) =catch { return false; }}-export async function reconcileVariantExpansion(projectRoot: string, outputRoot?: string, batchId?: string): Promise<VariantExpansionState | undefined> {+async function reconcileVariantExpansionUnlocked(projectRoot: string, outputRoot?: string, batchId?: string): Promise<VariantExpansionState | undefined> {const existing = await readVariantExpansionState(projectRoot, outputRoot, batchId);if (existing === undefined) return undefined;const completed = new Set(existing.completed_steps);@@ -401,9 +452,9 @@ export async function reconcileVariantExpansion(projectRoot: string, outputRoot?const addConflict = (message: string): void => { if (!conflicts.includes(message)) conflicts.push(message); };const baseline = await snapshotProject(existing.project_root);if (baseline.digest !== existing.baseline_digest) addConflict(`[reconcile] base project digest changed: expected ${existing.baseline_digest}, found ${baseline.digest}`);- const parentDigest = await digestFile(join(existing.project_root, ".hypit", "route-state.json"));+ const parentDigest = await digestFile(existing.parent_state_path ?? join(existing.project_root, ".hypit", "route-state.json"));if (existing.parent_state_digest !== undefined && parentDigest !== existing.parent_state_digest) addConflict(`[reconcile] parent route state digest changed: expected ${existing.parent_state_digest}, found ${parentDigest ?? "missing"}`);- const revisionDigest = await digestFile(join(existing.project_root, ".hypit", "revision-state.json"));+ const revisionDigest = await digestFile(existing.revision_state_path ?? join(existing.project_root, ".hypit", "revision-state.json"));if (existing.revision_state_digest !== undefined && revisionDigest !== existing.revision_state_digest) addConflict(`[reconcile] revision state digest changed: expected ${existing.revision_state_digest}, found ${revisionDigest ?? "missing"}`);const packages: VariantExpansionPackage[] = [];@@ -428,7 +479,7 @@ export async function reconcileVariantExpansion(projectRoot: string, outputRoot?const errors = Array.isArray(diff.errors) ? diff.errors.map(String).join(", ") : "variant baseline evidence failed";addConflict(`[reconcile] variant ${variant.id} scope evidence is invalid: ${errors}`);}- const check = await validJson(join(variant.project_root, ".hypit", "variant-check.json"), (value) => (value as { passed?: unknown })?.passed === true);+ const check = await validJson(route?.artifacts.variant_check ?? join(variant.project_root, ".hypit", "variant-check.json"), (value) => (value as { passed?: unknown })?.passed === true);const { error: _oldError, ...variantWithoutError } = variant;variants.push({...variantWithoutError,@@ -500,3 +551,9 @@ export async function reconcileVariantExpansion(projectRoot: string, outputRoot?updated_at: now,});}++export async function reconcileVariantExpansion(projectRoot: string, outputRoot?: string, batchId?: string): Promise<VariantExpansionState | undefined> {+ const locator = await selectedLocator(projectRoot, outputRoot, batchId);+ if (locator === undefined) return undefined;+ return withStateLock(locator.output_root, async () => reconcileVariantExpansionUnlocked(projectRoot, locator.output_root, locator.batch_id));+}diff --git a/packages/reference-video-tools/test/route-state.test.ts b/packages/reference-video-tools/test/route-state.test.tsindex a5ff3f93..2dcade9e 100644--- a/packages/reference-video-tools/test/route-state.test.ts+++ b/packages/reference-video-tools/test/route-state.test.ts@@ -82,9 +82,12 @@ test("a completed route no longer blocks a new route", async () => {await checkpointRouteState({ projectRoot: root, route: "reconstruction", step, status: "complete" });}assert.equal((await readRouteState(root))?.status, "complete");+ const completed = await readRouteState(root);const restarted = await startRouteState({ projectRoot: root, route: "description" });assert.equal(restarted.route, "description");assert.deepEqual(restarted.completed_steps, []);+ assert.notEqual(restarted.route_id, completed?.route_id);+ assert.equal(JSON.parse(await readFile(join(root, ".hypit", "routes", completed!.route_id, "state.json"), "utf8")).status, "complete");});test("checkpoint artifacts are merged and stale machine evidence is rolled back", async () => {@@ -111,9 +114,10 @@ test("checkpoint artifacts are merged and stale machine evidence is rolled back"test("description reconciliation uses brief and vocabulary evidence rather than reference artifacts", async () => {const root = await mkdtemp(join(tmpdir(), "hypit-route-state-"));- const brief = join(root, "brief.md");+ const brief = join(root, ".hypit", "brief.json");const vocabulary = join(root, "vocabulary.json");- await writeFile(brief, "brief", "utf8");+ await mkdir(join(root, ".hypit"), { recursive: true });+ await writeFile(brief, JSON.stringify({ intent: "brief" }), "utf8");await writeFile(vocabulary, JSON.stringify({ packages: [], surfaces: [] }), "utf8");await startRouteState({ projectRoot: root, route: "description" });await checkpointRouteState({ projectRoot: root, route: "description", step: 2, status: "complete", artifacts: { brief } });@@ -122,6 +126,9 @@ test("description reconciliation uses brief and vocabulary evidence rather thanassert.equal(state?.completed_steps.includes(2), true);assert.equal(state?.completed_steps.includes(3), true);assert.equal(state?.completed_steps.includes(6), false);+ await writeFile(brief, JSON.stringify({ intent: "changed after freeze" }), "utf8");+ const conflicted = await reconcileRouteState(root);+ assert.match(conflicted?.conflicts?.join("\n") ?? "", /brief digest changed/u);});test("an interrupted in-progress step resumes at the first unmet step", async () => {@@ -145,7 +152,7 @@ test("v1 route snapshots migrate by stage name and re-open new gates", async ()artifacts: {}, decisions: [], next_action: "write Source", updated_at: new Date().toISOString(),}), "utf8");const migrated = await readRouteState(root);- assert.equal(migrated?.version, 2);+ assert.equal(migrated?.version, 3);assert.equal(migrated?.completed_steps.includes(3), true);assert.equal(migrated?.completed_steps.includes(4), false, "new vocabulary gate is not guessed from old source state");assert.equal(migrated?.current_step, 4);