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 reconstruction route follow-up issues

rpone2e6405c2d192
diff --git a/.agents/skills/hypit/references/element-review.md b/.agents/skills/hypit/references/element-review.md
index f6c6e194..307c9db2 100644
--- a/.agents/skills/hypit/references/element-review.md
+++ b/.agents/skills/hypit/references/element-review.md
@@ -171,10 +171,13 @@ the `image_refs`, and — on a task that carries them — `transcript_ref` and `
nothing else. Not what you built, not which component drew it, not what you expect it to find, not
another look's answer. Take the returned text and record it yourself, so one writer owns the log.
-**Do not open the pictures yourself.** Whatever visual ability the model running this round has, using
-it makes the reader and the builder the same reader, and the round stops being evidence of anything.
-This is the same prohibition the `gemini` observer gets for free by sending its pictures to a separate
-request; one subagent per task is what makes the other paths equal to it rather than merely faster.
+**Do not open the reference pictures yourself before the blind answer is recorded.** Whatever visual
+ability the model running this round has, using the reference makes the reader and the builder the same
+reader, and the round stops being evidence of anything. After a comparison or review has been recorded,
+the Agent may open frames from its own render to diagnose an implementation defect; it must never use
+that debugging path to inspect the reference. This is the same prohibition the `gemini` observer gets
+for free by sending its pictures to a separate request; one subagent per task is what makes the other
+paths equal to it rather than merely faster.
Answering inline is the fallback for a harness with no subagents, and only that. Read them one after
another rather than merging them into a single look — what the round is for is the set of findings
diff --git a/.agents/skills/hypit/references/environment.md b/.agents/skills/hypit/references/environment.md
index 87e8df5d..1df9eca9 100644
--- a/.agents/skills/hypit/references/environment.md
+++ b/.agents/skills/hypit/references/environment.md
@@ -132,8 +132,9 @@ may also use it as the Distribution when no installed CLI exists, as described a
projects in this checkout live under `<checkout-root>/projects/<project-name>/`; they remain independent
author projects and are not part of the repository workspace globs.
-A project directory carries its own `package.json` — a name and `"private": true` is the whole file,
-since nothing reads its fields. `hypit check`, `plan` and `build` locate the package root by walking
+A project directory carries its own `package.json` with the runtime-safe minimum
+`{ "name": "<project-name>", "version": "0.0.0", "private": true, "type": "module" }`.
+`hypit check`, `plan` and `build` locate the package root by walking
up from the project until some `package.json` appears; the file is what stops that walk at the
project, so `packages/<slug>/` resolves from there rather than from whichever ancestor
directory happened to hold one. It is matched by no `pnpm-workspace.yaml` glob and adds the project
diff --git a/.agents/skills/hypit/references/layout-checks.md b/.agents/skills/hypit/references/layout-checks.md
index bd672f58..92815519 100644
--- a/.agents/skills/hypit/references/layout-checks.md
+++ b/.agents/skills/hypit/references/layout-checks.md
@@ -33,6 +33,15 @@ hypit-reference-video-tools layout_accept --run <build.svrun> \
hypit-reference-video-tools layout_check --run <build.svrun>
```
+Several candidates from the same report can be accepted atomically with a JSON array (or an object
+containing `findings`):
+
+```bash
+hypit-reference-video-tools layout_accept --run <build.svrun> --batch acceptances.json
+```
+
+Each entry is `{ "finding": "<id>", "reason": "<why this measured relationship is intentional>" }`.
+
`layout-checked` means the browser/Producer pass executed and every candidate has been judged: repaired
candidates disappeared and intentional candidates carry a persisted reason. It does **not** mean the
mechanical checker reported zero candidates. A browser, font or Producer execution failure is a hard
diff --git a/.agents/skills/hypit/references/local-author-package.md b/.agents/skills/hypit/references/local-author-package.md
index fe5d693b..94276c9b 100644
--- a/.agents/skills/hypit/references/local-author-package.md
+++ b/.agents/skills/hypit/references/local-author-package.md
@@ -33,6 +33,10 @@ project's package manager once; otherwise no install step is needed. Leaving act
means discovering at the end that nothing is selected — a failure that looks like broken code and is
not. Everything after them is specific to this component and cannot be copied from anywhere.
+If the package exposes a Style-like Surface, publish the Style record under the bare authored id
+(`id`) and have Source refer to that bare id. Do not invent `${id}.style` or `${id}.value` for the
+Style record; reserve suffixed ids for genuinely separate outputs such as Tracks.
+
## Required reading
**Read this whole file first.** The rules that decide what the package is — read the observation
diff --git a/.agents/skills/hypit/references/original-authoring/route.md b/.agents/skills/hypit/references/original-authoring/route.md
index a90251ba..c64141d2 100644
--- a/.agents/skills/hypit/references/original-authoring/route.md
+++ b/.agents/skills/hypit/references/original-authoring/route.md
@@ -76,8 +76,8 @@ model tier and how many takes are **yours to decide rather than to ask for**.
launcher substitution rule. `../runtime.md` — the hard boundary between a project and a Distribution.
When working in this checkout, put the independent project at
-`<checkout-root>/projects/<video-name>/` (use a safe slug), with a `package.json` carrying a name and
-`"private": true`.
+`<checkout-root>/projects/<video-name>/` (use a safe slug), with a `package.json` carrying the runtime
+minimum: `name`, `version: "0.0.0"`, `private: true` and `type: "module"`.
### 2. Load credentials
diff --git a/.agents/skills/hypit/references/preview.md b/.agents/skills/hypit/references/preview.md
index 197c2253..8f8a52e0 100644
--- a/.agents/skills/hypit/references/preview.md
+++ b/.agents/skills/hypit/references/preview.md
@@ -100,8 +100,10 @@ extension writes one still from the middle of it.
A whole round is one call: `--batch <renders.json>`, an array of `{element, segment|selection|tokens,
out}` inheriting the Run, and the `renders` array `reconstruction_check` returns is exactly that.
-**The program is drawn once for the whole round** and each entry is cut out of those frames, so asking
-for eight windows costs one render and eight cuts. The picture does not depend on `--element` — it is
+The program is realized once into a shared preview frame cache for the whole round, then the entries
+are processed serially and cut from those frames. Asking for eight windows therefore costs one full
+draw and eight cuts without concurrent workers racing over the shared `preview.svrun`. The picture
+does not depend on `--element` — it is
everything the Source places over those words — so two elements over one stretch share the render as
well.
diff --git a/.agents/skills/hypit/references/reconstruction/comparison-round.md b/.agents/skills/hypit/references/reconstruction/comparison-round.md
index c105cef8..75c4d1d6 100644
--- a/.agents/skills/hypit/references/reconstruction/comparison-round.md
+++ b/.agents/skills/hypit/references/reconstruction/comparison-round.md
@@ -118,9 +118,10 @@ wrote its observations.
**On the `gemini` observer, that observer is not you.** The command sends the reference clip and the
rendered clip as an unlabelled pair and returns the differences in words. Do not open the reference
-yourself and look at it, whatever visual ability the model running this round has, and do not look at
-the rendered reconstruction either. A second observer is a second opinion paid for with the very bias
-it claims to correct: it sees the reconstruction, knows what was built, and confirms what it expects.
+yourself and look at it before the blind answer is recorded. After the answer is recorded, you may
+inspect frames from your own render to diagnose an implementation defect; never inspect the reference
+through that debugging path. A second observer is a second opinion paid for with the very bias it
+claims to correct: it sees the reconstruction, knows what was built, and confirms what it expects.
This is why a font that is wrong is caught — the comparison names it, and the package is repaired,
rather than a font being chosen because it resembles what you remember.
diff --git a/.agents/skills/hypit/references/reconstruction/route.md b/.agents/skills/hypit/references/reconstruction/route.md
index 64d046c8..2fb183ff 100644
--- a/.agents/skills/hypit/references/reconstruction/route.md
+++ b/.agents/skills/hypit/references/reconstruction/route.md
@@ -125,7 +125,8 @@ report that no runnable Hypit Distribution is present and stop.
When working in this checkout, create the independent project at
`<checkout-root>/projects/<video-name>-reverse/` (use a safe slug). Use a directory the author named
only if they explicitly named one. Give it a `package.json`
-with a name and `"private": true`, and nothing else — no field in it is read. `hypit check`, `plan`
+with the runtime-safe minimum `{ "name": "<project-name>", "version": "0.0.0", "private": true, "type": "module" }`.
+`hypit check`, `plan`
and `build` find the package root by walking up from the project until a `package.json` appears, so
this file is what stops that walk at the project and lets the project's `packages/<slug>/` resolve. It
matches no `pnpm-workspace.yaml` glob, so it enrolls the directory in nothing.
@@ -367,8 +368,8 @@ hypit-reference-video-tools render_element projects/<name>/build.svrun --batch r
```
`comparison-round.md` uses preview-mock estimate timing; `--reference-id` selects comparison evidence, not mock timing.
-The program is drawn once and every entry is cut out of those frames, so render
-the whole list in one `--batch` call.
+The program is realized once into a shared preview frame cache and entries are cut serially, so render
+the whole list in one `--batch` call; the batch does not run concurrent preview staging workers.
Keep `.hypit/layout-check.json` beside the round. Its realized stable-state measurements remain
candidate evidence; the reference and observer/Agent intent judgement remain authoritative.
diff --git a/.agents/skills/hypit/references/recovery.md b/.agents/skills/hypit/references/recovery.md
index e4229204..0e7c78aa 100644
--- a/.agents/skills/hypit/references/recovery.md
+++ b/.agents/skills/hypit/references/recovery.md
@@ -83,7 +83,10 @@ hypit-reference-video-tools route_state --action checkpoint \
```
Layout candidates use their dedicated persisted decision file instead of a prose route checkpoint:
-run `layout_accept --run <run> --finding <id> --reason <text>`, rerun `layout_check`, then reconcile.
+run `layout_accept --run <run> --finding <id> --reason <text>` (or `--batch <acceptances.json>`),
+rerun `layout_check`, then reconcile. Keep shell stdout reports outside `.hypit/`; the tools replace
+state and evidence there atomically, and a redirect that keeps the destination open can make that
+rename fail on some platforms.
`reconcile` never guesses a creative decision. It can advance from durable files and passing checks,
but leaves an unrecorded manual step as the next action. If a recorded artifact disappeared, the next
diff --git a/docs/guide/author-packages.md b/docs/guide/author-packages.md
index 2affa7a3..7dbd0ae4 100644
--- a/docs/guide/author-packages.md
+++ b/docs/guide/author-packages.md
@@ -9,6 +9,13 @@ An author package extends the video vocabulary with a new component. Authors use
`<import>` and XML elements in their `.svml` source. No change to Core, the CLI or any aggregate
package is needed.
+## Public ids for Style-like Surfaces
+
+When a Surface publishes a Style-like value, its public record is the bare authored id (`${id}`),
+not `${id}.style` or `${id}.value`. Author Source then references it with the bare id, for example
+`style={board-style}`. Suffixes such as `.track` remain appropriate for separate Track outputs; they
+must not be added to the Style record merely to describe its role.
+
## 1. Create the package
```bash
diff --git a/docs/quickstart/styles.md b/docs/quickstart/styles.md
index b5f06cf4..dcef6b29 100644
--- a/docs/quickstart/styles.md
+++ b/docs/quickstart/styles.md
@@ -159,7 +159,7 @@ media.product {
frame-paint: #111116;
clip: rounded;
radius: 28;
- padding: 0;
+ padding: "0";
border-width: 1;
border-style: solid;
border-color: #FFFFFF20;
diff --git a/docs/zh/guide/author-packages.md b/docs/zh/guide/author-packages.md
index a186209e..4e7f4b79 100644
--- a/docs/zh/guide/author-packages.md
+++ b/docs/zh/guide/author-packages.md
@@ -7,6 +7,12 @@ description: 添加新的作者层组件的分步指南。
作者包用一个新组件扩展视频词汇。作者在自己的 `.svml` 源码里通过 `<import>` 和 XML 元素来使用它。无需改动 Core、CLI 或任何聚合包。
+## Style-like Surface 的公开 id
+
+如果 Surface 发布的是 Style-like 值,公开 Record 必须使用作者写下的裸 id(`${id}`),不能写成
+`${id}.style` 或 `${id}.value`。Author Source 也使用裸 id,例如 `style={board-style}`;只有真正
+独立的 Track 等输出才使用 `.track` 一类后缀。
+
## 1. 创建包
```bash
diff --git a/docs/zh/quickstart/styles.md b/docs/zh/quickstart/styles.md
index ff3de8a6..efa368c7 100644
--- a/docs/zh/quickstart/styles.md
+++ b/docs/zh/quickstart/styles.md
@@ -154,7 +154,7 @@ media.product {
frame-paint: #111116;
clip: rounded;
radius: 28;
- padding: 0;
+ padding: "0";
border-width: 1;
border-style: solid;
border-color: #FFFFFF20;
diff --git a/packages/reference-video-tools/README.md b/packages/reference-video-tools/README.md
index 8340ee64..242a28cd 100644
--- a/packages/reference-video-tools/README.md
+++ b/packages/reference-video-tools/README.md
@@ -7,6 +7,9 @@ revision-state and variant-expansion CLI subcommands, including `list_svml_packa
`observe_reference`, `record_observation`, `inspect_svml_vocabulary`, and `compare_reconstruction`.
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.
+Keep redirected reports outside a project's `.hypit/` directory (for example `> round.json`). That
+directory is reserved for the tools' atomic evidence and state files; redirecting stdout to one of
+those files can keep the destination open while it is being atomically replaced on some platforms.
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
diff --git a/packages/reference-video-tools/src/authoring.ts b/packages/reference-video-tools/src/authoring.ts
index 8eb6bf4f..6115fa32 100644
--- a/packages/reference-video-tools/src/authoring.ts
+++ b/packages/reference-video-tools/src/authoring.ts
@@ -481,8 +481,8 @@ async function once(key: string, work: () => Promise<void>): Promise<void> {
export type RenderElementInput = {
/**
* A round of renders, run together. Each entry names its own element, stretch and output and
- * inherits `run` and `reference_id`. The route renders every element before it compares any, and
- * each render is now written under its own directory, so a round has nothing to serialise for.
+ * inherits `run` and `reference_id`. The full preview is realized and drawn once; entries then cut
+ * their own windows from that shared frame cache in order.
*/
readonly renders?: readonly RenderElementInput[];
/** Required for one render; a round carries them per entry and inherits `run` from the outer input. */
diff --git a/packages/reference-video-tools/src/checks.ts b/packages/reference-video-tools/src/checks.ts
index 75cca6f9..183d976f 100644
--- a/packages/reference-video-tools/src/checks.ts
+++ b/packages/reference-video-tools/src/checks.ts
@@ -937,6 +937,7 @@ export async function authoringCheck(
}
type LoggedComparison = {
+ readonly run?: string;
readonly element?: string;
readonly shot_id?: string;
readonly range?: { readonly segment?: string; readonly selection?: string; readonly tokens?: readonly [number, number] };
@@ -952,8 +953,11 @@ export async function authoringCheck(
?? (entry.range?.segment === undefined ? undefined : `segment ${entry.range.segment}`)
?? (entry.range?.selection === undefined ? undefined : `selection ${entry.range.selection}`)
?? "an unnamed stretch";
- const logPath = mode === "reconstruction"
+ const legacyComparisonPath = mode === "reconstruction"
? join(preparedRoot, reference!, "comparisons.jsonl")
+ : undefined;
+ const logPath = mode === "reconstruction"
+ ? join(dirname(runPath), ".hypit", "comparisons.jsonl")
: reviewLogPath(runPath);
// A reference is keyed by the video, and rightly: its observations are about that video and cost
// real money, so two reconstructions of one file share them. Its comparisons are not about the
@@ -969,13 +973,16 @@ export async function authoringCheck(
// project's evidence and there is nothing to separate.
const inThisProject = (entry: LoggedComparison): boolean => {
if (mode === "description") return true;
+ if (entry.run !== undefined) return resolve(entry.run) === runPath;
if (entry.image_path === undefined) return false;
const at = resolve(entry.image_path);
return at === packageRoot || at.startsWith(`${packageRoot}${sep}`);
};
- const everything = (await readFile(logPath, "utf8").catch(() => ""))
+ const logPaths = [logPath, legacyComparisonPath].filter((path, index, all): path is string => path !== undefined && all.indexOf(path) === index);
+ const everything = (await Promise.all(logPaths.map(async (path) => (await readFile(path, "utf8").catch(() => ""))
.split("\n").filter((line) => line.trim().length > 0)
- .flatMap((line) => { try { return [JSON.parse(line) as LoggedComparison]; } catch { return []; } });
+ .flatMap((line) => { try { return [JSON.parse(line) as LoggedComparison]; } catch { return []; } }))))
+ .flat();
const elsewhere = everything.length - everything.filter(inThisProject).length;
const logged = everything.filter(inThisProject);
// A pair handed out and not yet reported on. Naming these separately is what keeps an element with
diff --git a/packages/reference-video-tools/src/cli.ts b/packages/reference-video-tools/src/cli.ts
index d4c1ac7a..d00ed482 100644
--- a/packages/reference-video-tools/src/cli.ts
+++ b/packages/reference-video-tools/src/cli.ts
@@ -58,6 +58,7 @@ function usage(): string {
" hypit-reference-video-tools preview_check <build.svrun> [<hypit.runtime.json>]",
" hypit-reference-video-tools layout_check --run <build.svrun>",
" hypit-reference-video-tools layout_accept --run <build.svrun> --finding <id> --reason <text>",
+ " hypit-reference-video-tools layout_accept --run <build.svrun> --batch <acceptances.json>",
" hypit-reference-video-tools reconstruction_check <build.svrun> [--reference-id <id>]",
" hypit-reference-video-tools authoring_check <build.svrun>",
"",
@@ -116,8 +117,8 @@ function usage(): string {
"array — of the same objects a single call takes, minus reference_id, which comes from the flag:",
"`[{\"run\": \"main.svrun\", \"segment\": \"pro\", \"video_path\": \"renders/board-pro.mp4\", \"element\": \"board\"}, …]`.",
"Every render is finished before any comparison starts, so a round has no order to it; they are",
- "paced by HYPIT_REFERENCE_CONCURRENCY and each one's derived cuts are kept apart, so nothing in the",
- "round reads a file another is still writing. One comparison that fails takes only itself down and",
+ "staged serially from one shared preview frame cache; observer comparisons still use their normal",
+ "pacing and each one's derived cuts are kept apart, so nothing in the round reads a file another is still writing. One comparison that fails takes only itself down and",
"arrives under `failures` with the input that produced it; the rest are under `comparisons`.",
"",
"--video compares the whole stretch instead of one frame of it, which is what removes the problem of",
@@ -652,9 +653,20 @@ async function main(): Promise<void> {
} else if (command === "layout_check") {
result = await tools.layout_check((supplied ?? { run: required(flags, "run") }) as { run: string });
} else if (command === "layout_accept") {
- result = await tools.layout_accept((supplied ?? {
- run: required(flags, "run"), finding: required(flags, "finding"), reason: required(flags, "reason"),
- }) as { run: string; finding: string; reason: string });
+ if (supplied !== undefined) result = await tools.layout_accept(supplied as never);
+ else {
+ const batch = one(flags, "batch");
+ if (batch === undefined) {
+ result = await tools.layout_accept({ run: required(flags, "run"), finding: required(flags, "finding"), reason: required(flags, "reason") });
+ } else {
+ const decoded = JSON.parse(await readFile(batch, "utf8")) as unknown;
+ const findings = Array.isArray(decoded) ? decoded : decoded !== null && typeof decoded === "object"
+ ? (decoded as { findings?: unknown }).findings
+ : undefined;
+ if (!Array.isArray(findings)) throw new Error("layout_accept --batch expects a JSON array or an object with a findings array");
+ result = await tools.layout_accept({ run: required(flags, "run"), findings });
+ }
+ }
} else if (command === "reconstruction_check") {
const run = operands[0];
if (supplied === undefined && run === undefined) throw new Error(`a <build.svrun> is required\n\n${usage()}`);
diff --git a/packages/reference-video-tools/src/layout.ts b/packages/reference-video-tools/src/layout.ts
index ad499c63..71a5107f 100644
--- a/packages/reference-video-tools/src/layout.ts
+++ b/packages/reference-video-tools/src/layout.ts
@@ -12,7 +12,13 @@ import { authorSource, invokedFrom, realizeAuthoringPreview, repositoryRoot, sta
import { atomicJson } from "./state-files.js";
export type LayoutCheckInput = { readonly run: string; readonly package_root?: string };
-export type LayoutAcceptInput = { readonly run: string; readonly finding: string; readonly reason: string };
+export type LayoutAcceptance = { readonly finding: string; readonly reason: string };
+export type LayoutAcceptInput = {
+ readonly run: string;
+ readonly finding?: string;
+ readonly reason?: string;
+ readonly findings?: readonly LayoutAcceptance[];
+};
const LAYOUT_CHECKER_VERSION = 3 as const;
type Bounds = { readonly left: number; readonly top: number; readonly right: number; readonly bottom: number; readonly width: number; readonly height: number };
@@ -487,17 +493,32 @@ export async function layoutCheck(input: LayoutCheckInput): Promise<Record<strin
export async function layoutAccept(input: LayoutAcceptInput): Promise<Record<string, unknown>> {
const runPath = resolve(invokedFrom(), input.run);
- const reason = input.reason.trim();
- if (reason.length === 0) throw new Error("layout_accept requires a non-empty reason explaining why the measured geometry is intentional");
+ const acceptances = input.findings ?? (input.finding === undefined || input.reason === undefined
+ ? []
+ : [{ finding: input.finding, reason: input.reason }]);
+ if (acceptances.length === 0) throw new Error("layout_accept requires --finding/--reason or a non-empty findings batch");
const reportPath = layoutCheckPath(runPath);
const report = JSON.parse(await readFile(reportPath, "utf8")) as { layout_digest?: unknown; findings?: unknown };
if (typeof report.layout_digest !== "string" || !Array.isArray(report.findings)) throw new Error(`run layout_check first; ${reportPath} has no usable report`);
- const finding = report.findings.find((item) => item !== null && typeof item === "object" && (item as { id?: unknown }).id === input.finding);
- if (finding === undefined) throw new Error(`layout report contains no finding ${input.finding}`);
const path = layoutDecisionsPath(runPath);
const existing = await readDecisions(path);
- const decision: LayoutDecision = { finding: input.finding, layout_digest: report.layout_digest, reason, accepted_at: new Date().toISOString() };
- const decisions = [...existing.decisions.filter((item) => !(item.finding === decision.finding && item.layout_digest === decision.layout_digest)), decision];
+ const decisions = [...existing.decisions];
+ for (const acceptance of acceptances) {
+ const reason = acceptance.reason.trim();
+ if (reason.length === 0) throw new Error(`layout_accept requires a non-empty reason for ${acceptance.finding}`);
+ const finding = report.findings.find((item) => item !== null && typeof item === "object" && (item as { id?: unknown }).id === acceptance.finding);
+ if (finding === undefined) throw new Error(`layout report contains no finding ${acceptance.finding}`);
+ const decision: LayoutDecision = { finding: acceptance.finding, layout_digest: report.layout_digest, reason, accepted_at: new Date().toISOString() };
+ const index = decisions.findIndex((item) => item.finding === decision.finding && item.layout_digest === decision.layout_digest);
+ if (index >= 0) decisions.splice(index, 1);
+ decisions.push(decision);
+ }
await atomicJson(path, { version: 1, decisions });
- return { accepted: true, finding: input.finding, layout_digest: report.layout_digest, reason, decisions: path, next_action: `rerun layout_check --run ${runPath}` };
+ return {
+ accepted: true,
+ findings: acceptances.map((item) => item.finding),
+ layout_digest: report.layout_digest,
+ decisions: path,
+ next_action: `rerun layout_check --run ${runPath}`,
+ };
}
diff --git a/packages/reference-video-tools/src/tools.ts b/packages/reference-video-tools/src/tools.ts
index 37a479de..da641472 100644
--- a/packages/reference-video-tools/src/tools.ts
+++ b/packages/reference-video-tools/src/tools.ts
@@ -662,10 +662,18 @@ type LookLog = {
};
const comparisonLog = (root: string): LookLog => ({ root, file: "comparisons.jsonl", answer: "differences" });
+
+/** Comparisons are evidence for one reconstruction, not for the shared reference. */
+function comparisonLogForRun(run: string | undefined, referenceRootPath: string): LookLog {
+ return run === undefined
+ ? comparisonLog(referenceRootPath)
+ : comparisonLog(join(dirname(resolve(invokedFrom(), run)), ".hypit"));
+}
const reviewLog = (root: string): LookLog => ({ root, file: "reviews.jsonl", answer: "findings" });
async function appendLooked(log: LookLog, record: ComparisonRecord | ReviewRecord): Promise<void> {
await serially(log.root, async () => {
+ await mkdir(log.root, { recursive: true });
await appendFile(join(log.root, log.file), `${JSON.stringify(record)}\n`, "utf8");
});
}
@@ -1300,6 +1308,11 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
const runFragmentFacets = (contribution?.hostFacets ?? []).filter((facet) => facet.abi === "hypit.run-fragment-host@1");
const producers = modules.flatMap((module) => module.manifest.producers);
const fragmentValues = runFragmentFacets.flatMap((facet) => Object.values((facet.implementation as { fragments?: Record<string, { operations?: readonly unknown[]; exports?: readonly unknown[] }> }).fragments ?? {}));
+ // Author Markup Surface handlers seal Graph Fragments while decoding Source; those
+ // fragments are intentionally not exposed as a package Host facet. Keep the diagnostic
+ // useful for author packages by reporting their declared Surfaces as the lower bound when
+ // no explicit Run Fragment facet exists.
+ const fragmentCount = fragmentValues.length > 0 ? fragmentValues.length : surfaces.length;
if (surfaces.length === 0) errors.push("PACKAGE_NO_SURFACE");
if (producers.length === 0) errors.push("PACKAGE_NO_PRODUCER");
if (runFragmentFacets.length > 0 && fragmentValues.every((fragment) => (fragment.operations?.length ?? 0) === 0 || (fragment.exports?.length ?? 0) === 0)) errors.push("PACKAGE_NO_FRAGMENT");
@@ -1325,7 +1338,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
const graphUsed = modules.some((module) => graphModules.has(`${module.manifest.name}@${module.manifest.version}`));
if (!sourceImported) errors.push("PACKAGE_NOT_IMPORTED");
else if (!graphUsed) errors.push("PACKAGE_IMPORTED_BUT_UNUSED");
- results.push({ specifier, loaded_specifier: selected?.specifier, manifest: modules.length > 0, surfaces: surfaces.length, producers: producers.length, fragments: fragmentValues.length, run_fragment_facets: runFragmentFacets.length, source_imported: sourceImported, source_used: graphUsed, graph_used: graphUsed, status: errors.length === 0 ? "passed" : "failed", ...(errors.length === 0 ? {} : { errors }) });
+ results.push({ specifier, loaded_specifier: selected?.specifier, manifest: modules.length > 0, surfaces: surfaces.length, producers: producers.length, fragments: fragmentCount, run_fragment_facets: runFragmentFacets.length, source_imported: sourceImported, source_used: graphUsed, graph_used: graphUsed, status: errors.length === 0 ? "passed" : "failed", ...(errors.length === 0 ? {} : { errors }) });
}
for (const specifier of expected) {
if (!results.some((item) => item.specifier === specifier)) results.push({ specifier, status: "failed", errors: ["PACKAGE_EXPECTED_BUT_MISSING"] });
@@ -1380,6 +1393,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
const askerFor = async (
observer: Observer,
state: ReferenceState,
+ comparisonRun?: string,
): Promise<{ readonly ask: Asker; readonly pending: readonly ObservationTaskRequest[]; readonly paced?: boolean }> => {
if (observer === "agent") {
const pending: ObservationTaskRequest[] = [];
@@ -1411,7 +1425,9 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
key, instruction, prompt: [...parts, prompt, WATERMARK_RULE].join("\n\n"), image_refs: asPictures(media, state),
...(sound === true && words.length > 0 ? { transcript_ref: transcriptRef } : {}),
...(spoken.length === 0 ? {} : { transcript_words: spoken }),
- record_with: `record_observation --reference-id ${state.reference_id} --key ${key} --text-file <the answer>`,
+ record_with: `record_observation --reference-id ${state.reference_id} `
+ + `${comparisonRun === undefined ? "" : `--run ${comparisonRun} `}`
+ + `--key ${key} --text-file <the answer>`,
});
return observation("pending", "awaiting the agent observer");
},
@@ -1993,8 +2009,10 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
+ "computed in Canvas pixels subtracts the parent's origin.",
"An animation carries at least two keyframes, and every keyframe of one animation declares "
+ "the same properties: one that appears in some and not others is interpolated from the "
- + "element's own value on the frames it is missing from.",
- "A plain text element must provide exact ordered font artifacts and cannot combine them with raw font styles.",
+ + "element's own value on the frames it is missing from. `atFrame` is Present-relative; the "
+ + "document normalizes the animation domain to `max(presentDurationFrames, lastKeyframe.atFrame)`.",
+ "A plain text element must provide exact ordered font artifacts and cannot combine them with "
+ + "raw `font`, `font-family`, `font-style`, `font-synthesis` or `font-weight` styles.",
"A text element using glyph Paint cannot also declare raw stroke or paint-order styles.",
"A media element's artifact media type must match image/video, and still images cannot carry sampling.",
"A Surface with still timing cannot carry sampling; frame-based Surface sampling must match its typed timing.",
@@ -2055,7 +2073,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
+ createHash("sha256").update(renderedPath).digest("hex").slice(0, 8);
const standIn = await standInBeside(renderedPath);
const observer: Observer = state.observer ?? "gemini";
- const { ask, pending } = await askerFor(observer, state);
+ const { ask, pending } = await askerFor(observer, state, input.run);
// Which stretch of the reference the render is put beside. A render covers the words a Segment
// or a Selection marks, so that is what the reference is cut to; a shot is a cut in the picture
@@ -2161,7 +2179,8 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
.digest("hex").slice(0, 6)}`;
// Nothing changed since this pair was last answered, so nothing new can be said about it.
const digest = await fileDigest(renderedPath);
- const already = await answeredAlready(comparisonLog(root), {
+ const comparisonEvidence = comparisonLogForRun(input.run, root);
+ const already = await answeredAlready(comparisonEvidence, {
digest,
stretch: comparedStretch({ ...(shot === undefined ? {} : { shot_id: shot.shot_id }), ...(cut === undefined ? {} : { range: cut.record }) }),
clip: asClip,
@@ -2169,7 +2188,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
scope,
});
if (already !== undefined) {
- if (input.run !== undefined) await autoRouteCheckpoint(resolve(invokedFrom(), input.run), routeStepFor("reconstruction", "comparison-complete"), { comparison_log: join(root, "comparisons.jsonl") }, "repair differences, then rerun reconstruction_check");
+ if (input.run !== undefined) await autoRouteCheckpoint(resolve(invokedFrom(), input.run), routeStepFor("reconstruction", "comparison-complete"), { comparison_log: join(comparisonEvidence.root, comparisonEvidence.file) }, "repair differences, then rerun reconstruction_check");
return {
reference_id: state.reference_id,
observer,
@@ -2197,7 +2216,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
// What was compared, and what was seen. The record is what a gate reads to tell an element that
// was looked at from one that never was, and what an identical pair is answered from without
// asking again.
- await appendLooked(comparisonLog(root), {
+ await appendLooked(comparisonEvidence, {
at: startedAt,
id: comparisonId,
...(input.run === undefined ? {} : { run: resolve(invokedFrom(), input.run) }),
@@ -2215,7 +2234,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
...(differences.status === "complete" ? { differences: differences.text } : {}),
});
if (differences.status === "complete" && input.run !== undefined) {
- await autoRouteCheckpoint(resolve(invokedFrom(), input.run), routeStepFor("reconstruction", "comparison-complete"), { comparison_log: join(root, "comparisons.jsonl") }, "repair differences, then rerun reconstruction_check");
+ await autoRouteCheckpoint(resolve(invokedFrom(), input.run), routeStepFor("reconstruction", "comparison-complete"), { comparison_log: join(comparisonEvidence.root, comparisonEvidence.file) }, "repair differences, then rerun reconstruction_check");
}
return {
reference_id: state.reference_id,
@@ -2289,13 +2308,14 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
// that never was, and until this existed an agent-observer comparison could never leave `pending`.
if (key.startsWith("comparison:")) {
const comparisonId = key.slice("comparison:".length);
- const closed = await closeLooked(comparisonLog(root), comparisonId, text);
+ const comparisonEvidence = comparisonLogForRun(input.run, root);
+ const closed = await closeLooked(comparisonEvidence, comparisonId, text);
assert(closed, `${key} names no open comparison of reference ${input.reference_id}`);
- const comparison = (await readFile(join(root, "comparisons.jsonl"), "utf8"))
+ const comparison = (await readFile(join(comparisonEvidence.root, comparisonEvidence.file), "utf8"))
.split("\n").filter((line) => line.trim().length > 0).flatMap((line) => {
try { return [JSON.parse(line) as ComparisonRecord]; } catch { return []; }
}).find((entry) => entry.id === comparisonId);
- if (comparison?.run !== undefined) await autoRouteCheckpoint(comparison.run, routeStepFor("reconstruction", "comparison-complete"), { comparison_log: join(root, "comparisons.jsonl") }, "repair differences, then rerun reconstruction_check");
+ if (comparison?.run !== undefined) await autoRouteCheckpoint(comparison.run, routeStepFor("reconstruction", "comparison-complete"), { comparison_log: join(comparisonEvidence.root, comparisonEvidence.file) }, "repair differences, then rerun reconstruction_check");
await maybeCheckpointReferenceObservation(input);
return { reference_id: state.reference_id, key, stored_in: "comparisons" };
}
@@ -2480,7 +2500,10 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
const round = input.renders;
assert(round.length > 0, "renders is empty");
// Local work rather than a quota, so it is paced by the machine and not by the launch gap.
- const { done, failures } = await runBatch(round, locallyPaced(round.length), async (one) => await renderElement({
+ // Every entry shares the same preview-mock stage and frame cache. Keep the realization
+ // serialized so one worker cannot read a half-written preview.svrun while another is staging it;
+ // `once` still makes the actual full-program draw happen only once for the round.
+ const { done, failures } = await runBatch(round, { concurrency: 1, gapMs: 0 }, async (one) => await renderElement({
...one, run: one.run ?? input.run,
...(one.reference_id ?? input.reference_id === undefined ? {} : { reference_id: input.reference_id }),
} as RenderElementInput));