Skip to content

armgit / hypit

Public Imported from GitHub
0

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.

fix(hypit): namespace persisted route history

rpone1cb05da23991
diff --git a/.agents/skills/hypit/SKILL.md b/.agents/skills/hypit/SKILL.md
index 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 between
complete 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 checks
before continuing. Never resume from chat memory alone, and never repeat a completed or paid step
without verifying its durable evidence.
diff --git a/.agents/skills/hypit/references/authoring.md b/.agents/skills/hypit/references/authoring.md
index 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 whether
can 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 Record
diff --git a/.agents/skills/hypit/references/brief-intake.md b/.agents/skills/hypit/references/brief-intake.md
index 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. An
agent may select fonts, package details and model tier when they are genuinely low risk; it may not
invent core facts, ranking criteria, claims, Hook or audience promises. The brief is the reference for
diff --git a/.agents/skills/hypit/references/original-authoring/route.md b/.agents/skills/hypit/references/original-authoring/route.md
index 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 proje
intent, Hook and narrative to the request. If no example is semantically relevant, use the document's
general 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` recording
the user's goal, audience, intent, Hook, narrative progression, visual/audio/text relationships,
claims, confirmed decisions, unresolved questions, and expected SVML/SVS/SVRun consequences. Low-risk
implementation 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.md
index 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 its
accepted 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.md
index 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 compaction
Treat 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 and
destinations. 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 and
need not have a parent creation route. When a parent route snapshot exists, reconcile it together
with 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`, render
outputs, comparison/review logs, and the final check result. Full prompts and observer prose remain in
their 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.md
index 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`, and
the 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 context
compaction; never resume from chat memory. Manual intent mapping and Source edits require an explicit
checkpoint. 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.md
index 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 state
diff --git a/packages/reference-video-tools/README.md b/packages/reference-video-tools/README.md
index 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_packa
Each command prints one JSON result to stdout. The final source files are authored by the calling
agent 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 reruns
deterministic gates; it does not invoke a VLM/observer or perform visual review. The project may be
handed in as an already completed directory: after its baseline gates pass, Revision can start
without a parent reconstruction or description route state.
diff --git a/packages/reference-video-tools/src/index.ts b/packages/reference-video-tools/src/index.ts
index 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.ts
index 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 RevisionSta
if (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 RevisionSta
if (!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<RevisionSt
try { 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<Rev
const 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): P
const 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<Revis
if (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<Revis
const 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<Revis
next_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.ts
index 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 RouteS
if (!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 | und
const 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 | und
completed_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<RouteStat
if (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<RouteStat
current_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): Promise
const 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): Promise
Object.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): Promise
return 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<RouteSta
if (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.ts
new file mode 100644
index 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.ts
index 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 i
type 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 = {}): ReferenceV
const 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 = {}): ReferenceV
const 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 = {}): ReferenceV
const 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 = {}): ReferenceV
const 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 = {}): ReferenceV
const 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 = {}): ReferenceV
const 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 = {}): ReferenceV
const 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.ts
index 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.ts
index 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"): rea
return 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: VariantExpansionCheckpoi
throw 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: VariantExpansionCheckpoi
artifacts, 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.ts
index 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 than
assert.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);