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: tighten package authoring and observer evidence flow

rpone09c85978a34b
diff --git a/.agents/skills/hypit/references/local-author-package.md b/.agents/skills/hypit/references/local-author-package.md
index 09e51ee3..49c57800 100644
--- a/.agents/skills/hypit/references/local-author-package.md
+++ b/.agents/skills/hypit/references/local-author-package.md
@@ -59,37 +59,42 @@ hypit-reference-video-tools inspect_visual_contract
It answers the questions a component is written against — which element kinds exist, which style
names are admitted on them, which of those take an enum, how few keyframes an animation carries, and
-the four rules the seal enforces about parents, `order` and interpolation. Add
+the rules the seal enforces about parents, `order` and interpolation. Add
`--producers-of @hypit/temporal` for the Producers a Fragment calls to turn a Script name into a
-window, with their port names, and the same for any package whose Producers you chain. Every line is
-generated from the Composition schema and the Modules themselves, so it says what will be accepted
-rather than what one package happened to do. `inspect_svml_vocabulary` answers the other half: what a
-Source may write.
-
-Open a package's source only when neither command settles it — a role whose shape the guide leaves
-implicit, an export whose signature you need exactly. Use `hypit paths --json` to locate
-the installed Distribution and read **the one role you are stuck on**, not the package end to end.
-Find it by what it exports, since the filenames differ: `ranking` calls two of them `schedule.ts` and
-`render.ts`, `media-track` calls them `program.ts` and `lower.ts`, `comment-sticker` calls them
-`program.ts` and `author.ts`.
-
-Check every signature you take that way against the current package's exports before you rely on it.
-A call read out of any source that is not the installed Distribution — an older project in the same
-checkout, a snippet in an issue, something you remember — is a name that may no longer exist, and
-what it costs is a compile error at the end of a package rather than at the line that borrowed it.
-
-Four are needed by every component that draws and are stated nowhere in the guides, so they are here.
-Read the rest from source; these are the ones that stop a package before it starts:
+window. `@hypit/temporal-markup` is different: it owns the Surface-side
+`createTemporalWindowProjection`, `createTemporalInstantProjection`, and the corresponding
+attribute vocabularies. Every line is generated from the Composition schema and the Modules
+themselves, so it says what will be accepted rather than what one package happened to do.
+`inspect_svml_vocabulary` answers the other half: what a Source may write.
+
+When `inspect_svml_vocabulary` finds no close structural sibling, write from these documents and the
+minimal fixture at `examples/minimal-author-package/packages/example-component/`. Do not read an
+unrelated business package to discover generic API shapes. If the public contract still leaves a
+required shape undefined, report a repository documentation defect instead of continuing package
+archaeology.
+
+There is one deliberate exception. If vocabulary inspection proves that an installed package has the
+same input/output Types, timing contract, terminal Track and Surface ports, and only the Style,
+layout, Recipe or renderer policy differs, use the **close-sibling path**: read that package's README
+and only the role files needed for the change, copy the structure into the project package, and
+replace its Module identity, nominal Types, Producer names, activation and README. Never edit or
+reuse the sibling's identity. A new Caption family may follow this path from the closest Caption
+family while reusing the common `@hypit/caption` contract. Similar names or similar screenshots do
+not qualify.
+
+These four public signatures are a quick index. The complete object shapes, including literal
+Fragment and Manifest ports and the full Surface return value, are in the minimal fixture:
| From | Signature |
|---|---|
| `@hypit/elaborator` | `sealGraphFragment(fragment: Omit<GraphFragment, "format" \| "id">): GraphFragment` |
| `@hypit/composition` | `sealVisualTrack(value: Omit<VisualTrack, "kind">): VisualTrack` |
| `@hypit/component-kit` | `ProducerHandlerContext` — `{ command: InvokeProducerCommand; producer: ProducerRef; inputs: Readonly<Record<string, TypedRecord>> }` |
+| `@hypit/markup` | `SurfaceDecodeOutput` — `{ records, components, fragments, exports? }`; `SurfaceResolvedReference` carries `path`, `ref`, `type` and an optional `record` |
-The fourth is the shape of a filled media slot, which the boundary rules below describe in words: a
-blob input arrives in `inputs` as the `BlobRef` itself, not wrapped inline the way an authored value
-is, so read its `mediaType` off the Artifact rather than assuming what the slot's name suggests.
+A filled media slot arrives in `inputs` as the `BlobRef` itself, not wrapped inline the way an
+authored value is, so read its `mediaType` off the Artifact rather than assuming what the slot's name
+suggests.
## Package boundary
diff --git a/.agents/skills/hypit/references/reconstruction/continuity.md b/.agents/skills/hypit/references/reconstruction/continuity.md
index d8757594..cc5c3011 100644
--- a/.agents/skills/hypit/references/reconstruction/continuity.md
+++ b/.agents/skills/hypit/references/reconstruction/continuity.md
@@ -47,8 +47,11 @@ lifetime, and a scoped variation rather than a second Style. A new shot is never
change in appearance.
The reference supplies the lifetimes. The `persistent_systems` observation from `prepare_reference`
-reports these systems for the whole reference, including whether each one's appearance ever changes
-and where. Use it instead of inferring lifetimes from per-shot prose.
+is an inventory and a first lifetime hypothesis for the whole reference, including whether each one's
+appearance appears to change. Do not treat its position, exact visible intervals or continuity as
+settled geometry: confirm those claims with the relevant shot-level visual observations or an
+exactly-one-shot narrow question. When the whole-reference inventory conflicts with a shot-specific
+observation, preserve the conflict and use the more specific shot evidence for the reconstruction.
## Base pictures and designed fields
diff --git a/.agents/skills/hypit/references/reconstruction/evidence.md b/.agents/skills/hypit/references/reconstruction/evidence.md
index 02e6632a..60dd07f1 100644
--- a/.agents/skills/hypit/references/reconstruction/evidence.md
+++ b/.agents/skills/hypit/references/reconstruction/evidence.md
@@ -18,6 +18,12 @@ writes its own and the command is unused. A long answer arrives whole with `--te
`comparison-round.md` says when. `list_svml_packages` and `inspect_svml_vocabulary` read installed
vocabulary and have nothing to do with a reference video — `../vocabulary.md` documents them.
+Use the canonical observation envelopes when consuming results: `prepare_reference` exposes the four
+whole-reference observations under `observations.people_and_product`, `observations.voices`,
+`observations.persistent_systems` and `observations.places`; a narrow single or batch answer is under
+`result` and has the shape `{ status, text }`. The older direct fields and `answer` alias remain only
+for compatibility. Do not mix `.text`, `.answer.text` and `.result.text` as competing conventions.
+
A reference is found from the Distribution rather than from where you are standing, so these commands
may be run from anywhere. What does depend on where you are is which packages resolve: name the
project with `--package-root` when the command is not run from inside it. `paths` reports both roots
@@ -129,20 +135,28 @@ the Source's own values and is credited with `--element`.
## Narrow questions
-`--question` is a separate path. It requires one to three `--shot-id` values and answers only that
-question from those shots' clips and frames. Its answer is cached like any other, under a key naming
-the shots it was asked over and the question itself, so asking the same question again returns what
+`--question` is a separate path. It requires exactly one `--shot-id` and answers only that question
+from that shot's clip and frames. Keeping a measurement on one shot prevents descriptions from
+mixing different layouts or time ranges. Cross-shot continuity is handled by the built-in boundary
+and three-shot window observations, not by a narrow question. Its answer is cached like any other,
+under a key naming the shot and the question itself, so asking the same question again returns what
was already answered and reports `reused`. `--reobserve` is what asks again. A different question
-over the same shots gets its own key:
+over the same shot gets its own key:
```bash
hypit-reference-video-tools observe_reference --reference-id <id> --shot-id shot-007 \
--question "How thick is the outline on the caption words, relative to the stroke width of the letters?"
```
-Several at once is `--batch <questions.json>`, an array of `{shot_ids, question}`. Ask about visible
-attributes. Never ask which component to use. Do not re-observe the full shot to correct one: that is
-paid, and at temperature `1.0` it returns a paraphrase rather than a correction.
+Several at once is `--batch <questions.json>`, an array of `{shot_ids, question}` where every
+`shot_ids` array contains exactly one id. Ask about visible attributes. Never ask which component to
+use. Do not re-observe the full shot to correct one: that is paid, and at temperature `1.0` it returns
+a paraphrase rather than a correction.
+
+The whole-reference `persistent_systems` pass is an inventory and a lifetime hypothesis, not a settled
+measurement. Confirm geometry, exact start/end frames and intermittent gaps with shot-level evidence or
+an exactly-one-shot narrow question. If they conflict, preserve both statements with provenance and use
+the more specific shot evidence; never silently rewrite the original whole-reference observation.
## Boundaries
@@ -153,7 +167,7 @@ built or what you expect to be found. An observation is evidence rather than the
maker — which is a rule about what an observation may contain, so it binds when you are the one
writing it.
-Inspect every failed or unresolved result. Follow up with one narrow question over one to three
-relevant shots rather than repeating the entire analysis. Preserve successful cached observations
+Inspect every failed or unresolved result. Follow up with one narrow question over one relevant shot
+rather than repeating the entire analysis. Preserve successful cached observations
unless the selected shot or preparation stage must be refreshed. Do not pass model, concurrency,
rate-limit or temperature settings; on the `gemini` observer temperature is fixed at `1.0`.
diff --git a/.agents/skills/hypit/references/reconstruction/vocabulary.md b/.agents/skills/hypit/references/reconstruction/vocabulary.md
index 62fe0719..08ffc86b 100644
--- a/.agents/skills/hypit/references/reconstruction/vocabulary.md
+++ b/.agents/skills/hypit/references/reconstruction/vocabulary.md
@@ -28,8 +28,8 @@ measured rather than chosen:
- Each shot's `text_appearance` observation already describes drawn type in those terms. Read it
before asking anything.
-- Resolve what remains with a narrow `observe_reference --question` over the one to three shots where
- the element is most legible. Ask about visible attributes, never about components or syntax. A
+- Resolve what remains with a narrow `observe_reference --question` over the one shot where the
+ element is most legible. Ask about visible attributes, never about components or syntax. A
question costs one request and does not disturb cached observations.
- If the evidence came back inconclusive, ask again with a narrower question rather than accepting a
default: a value the observer never saw is not evidence.
diff --git a/.agents/skills/hypit/references/recovery.md b/.agents/skills/hypit/references/recovery.md
index 39f03232..e4443101 100644
--- a/.agents/skills/hypit/references/recovery.md
+++ b/.agents/skills/hypit/references/recovery.md
@@ -44,7 +44,7 @@ checkpoint:
```bash
hypit-reference-video-tools route_state --action checkpoint \
- --project-root <project> --route reconstruction --step 9 \
+ --project-root <project> --route reconstruction --state review-planned \
--status complete --next-action 'run final reconstruction_check' \
--decision 'caption box is intentionally centred'
```
diff --git a/docs/guide/author-packages.md b/docs/guide/author-packages.md
index 3426c429..d2f66948 100644
--- a/docs/guide/author-packages.md
+++ b/docs/guide/author-packages.md
@@ -57,17 +57,22 @@ export const myComponentManifest: ModuleManifest = {
name: myComponentModuleRef.name,
version: myComponentModuleRef.version,
dependencies: [],
- types: [ /* your nominal Types */ ],
+ types: [{ name: "Widget" }, { name: "WidgetProgram" }],
capabilities: [],
- producers: [ /* your deterministic Producers */ ],
+ producers: [{
+ name: "render-widget",
+ inputs: [{ name: "space", type: { module: { name: "@hypit/program-space", version: "1" }, name: "ProgramSpace" } }],
+ outputs: [{ name: "track", type: { module: myComponentModuleRef, name: "WidgetTrack" } }],
+ needs: [],
+ }],
};
export const myComponentMarkupSurfaces = [{
name: "widget",
tag: "Widget",
mode: "structured",
- outputs: [ /* Types this syntax may author */ ],
- vocabulary: { /* what this element is, and what it looks like — see step 5 */ },
+ outputs: [{ module: myComponentModuleRef, name: "Widget" }],
+ vocabulary: { /* see step 5 */ },
}] as const;
```
@@ -82,21 +87,38 @@ The Surface handler decodes the Markup Frontend's XML elements into typed author
// src/surface.ts
import type { StructuredSurfaceHandler } from "@hypit/markup";
-export const decodeMyComponentSurface: StructuredSurfaceHandler = ({ element }) => {
- // Read attributes and children from the XML element
- // Validate inputs
- // Emit typed Records and Operations into context
- // Return authored graph declarations
+export const decodeMyComponentSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ const id = textAttribute(element, "id");
+ const space = resolveReference(referenceAttribute(element, "space"));
+ if (space === undefined) throw new Error("Widget.space cannot be resolved");
+ const record: SurfaceRecordDraft = {
+ id: `${id}.value`, type: widgetTypes.widget,
+ value: { kind: "inline", value: { id } }, range: element.range,
+ };
+ const fragment = sealGraphFragment({
+ inputs: [{ name: "space", type: programSpaceTypes.programSpace }],
+ operations: [{ id: "render-widget", producer: widgetProducers.render,
+ inputs: { space: { kind: "fragment-input", name: "space" } },
+ result: { kind: "output", name: "track" } }],
+ exports: [{ name: "track", type: compositionTypes.visualTrack,
+ root: { kind: "fragment-operation", operation: "render-widget" } }],
+ });
+ const component: SurfaceComponentDraft = {
+ id, fragment: fragment.id, inputs: { space: space.ref },
+ outputs: { track: `${id}.track` }, range: element.range,
+ };
+ return { records: [record], components: [component], fragments: [fragment], exports: [`${id}.value`, `${id}.track`] };
};
```
[Component Anatomy](./component-anatomy.md) names every role a component package fills and where to
find each one in an existing package, since the filenames differ between packages.
-Look at existing Surface implementations for reference:
-- `packages/seedance/src/surface.ts` — Prompt, Speech and Video Surfaces
-- `packages/caption/src/surface.ts` — the common Program Surface; concrete Style/Track Surfaces live in Style-family packages
-- `packages/media-track/src/surface.ts` — Track, Item and Sequence Surfaces
+For a generic package, use the complete fixture at
+`examples/minimal-author-package/packages/example-component/` rather than copying an unrelated
+business package. A package whose vocabulary is structurally the same as an installed sibling may
+use that sibling's README and only the necessary role files as an implementation skeleton; create a
+new Module identity and do not edit the sibling.
## 5. Declare the Surface vocabulary and its preview
@@ -136,18 +158,17 @@ that only assembles a request.
`appearance` and `preview` answer different questions and neither replaces the other. `appearance`
says what the element draws in every case; the preview shows one honest instance of it.
-Study `packages/media-track/src/manifest.ts` for a complete vocabulary, and
-`packages/typography-track/`, `packages/caption-fine/`, `packages/deck-track/`,
-`packages/comment-sticker/`, `packages/screen-overlay/`, `packages/ranking/` and
-`packages/speech-track/` for their `preview/` directories.
+The fixture's manifest is the canonical small vocabulary example. For a close sibling, read that
+package's own README and vocabulary first, then only the role files needed for the changed behavior.
### Producing the preview image
The preview is a real frame of your own component, rendered locally. Nothing generates it for you,
and a mock-up drawn by hand is worse than no preview at all, because it claims to be output.
-Render one the way the repository's own visual tests do —
-`packages/hyperframes/test/browser-visual.test.ts` is the working example, and the sequence is:
+Render the fixture's preview Source with `hypit-reference-video-tools render_previews`. For a new
+package, use the same package-owned preview Source and keep one representative rendered frame. The
+sequence is:
1. build the Track value with your package's own render function, over a sealed ProgramSpace;
2. `sealComposition({ id, canvas, tracks })`, then `compileHyperframesDocument(composition, space)`
@@ -234,21 +255,40 @@ Manifest are loaded from its installed dependencies.
The `<import>` activates only author vocabulary. It never grants network, filesystem or credential
authority.
-## Existing examples to study
-
-| Package | What it demonstrates |
-|---|---|
-| `packages/seedance/` | Model family with multiple Surfaces (Prompt, Speech, Video) |
-| `packages/seedance-speaker/` | Higher-level binding that composes Script, a Text Template and Seedance |
-| `packages/caption/` | common Program, Cue/field contracts and whole-Atom timing |
-| `packages/caption-fine/` | one field-free Style and Track Surface family |
-| `packages/media-track/` | Track with Item/Sequence, layer, motion and handoff behavior |
-| `packages/typography-track/` | Typography overlay Track |
-| `packages/film/` | Composition target that consumes peer Tracks |
-| `packages/ranking/` | A Program that lays out cells and fills media slots, with `schedule.ts` and `render.ts` as its role files |
-| `packages/comment-sticker/` | The same roles under different filenames — `program.ts` and `author.ts` |
-| `packages/screen-overlay/` | An overlay whose geometry is computed rather than authored |
-
-The filenames differ between packages: what `component-anatomy.md` calls the Value layer and the
-lowering is `schedule.ts`/`render.ts` in `ranking`, `program.ts`/`lower.ts` in `media-track`, and
-`program.ts`/`author.ts` in `comment-sticker`. Find a role by what it exports, not by its filename.
+The fixture deliberately uses explicit role filenames so a new author does not need to infer the
+architecture from a large production package.
+
+## The complete literal shapes
+
+The fixture is the authoritative small example. These are the same object shapes in abbreviated
+form; there is no need to inspect a business package to discover them.
+
+```typescript
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+const fragment = sealGraphFragment({
+ inputs: [{ name: "space", type: programSpaceTypes.programSpace }],
+ operations: [{
+ id: "render-widget", producer: widgetProducers.render,
+ inputs: { space: input("space") },
+ result: { kind: "output", name: "track" },
+ }],
+ exports: [{ name: "track", type: compositionTypes.visualTrack, root: operation("render-widget") }],
+});
+
+// A structured Surface always returns these four collections. `exports` is optional.
+const decoded: SurfaceDecodeOutput = {
+ records: [{ id: "widget.value", type: widgetTypes.widget,
+ value: { kind: "inline", value: { id: "widget" } }, range: element.range }],
+ components: [{ id: "widget", fragment: fragment.id, inputs: { space: space.ref },
+ outputs: { track: "widget.track" }, range: element.range }],
+ fragments: [fragment],
+ exports: ["widget.value", "widget.track"],
+};
+```
+
+For temporal elements, the Surface side is `@hypit/temporal-markup`, not the graph-side
+`@hypit/temporal` module. Use `createTemporalWindowProjection` or
+`createTemporalInstantProjection` with the element, semantic reference and resolver, then append
+the returned `records`, `components` and `fragments` to the same `SurfaceDecodeOutput`.
diff --git a/docs/guide/component-anatomy.md b/docs/guide/component-anatomy.md
index 40c011a9..c3887607 100644
--- a/docs/guide/component-anatomy.md
+++ b/docs/guide/component-anatomy.md
@@ -26,10 +26,10 @@ thing to copy than its structure.
| Fragment | The graph a Surface expands into: inputs, operations, outputs | `fragment.ts` |
| Activation | The host facets a Host installs | `activation.ts` |
-Three packages worth comparing, because they name things differently and do the same work:
-`packages/ranking/` (`schedule.ts`, `style.ts`, `render.ts`), `packages/media-track/`
-(`program.ts`, `lower.ts`, `presentation.ts`) and `packages/comment-sticker/` (`program.ts`,
-`author.ts`).
+Use `examples/minimal-author-package/packages/example-component/` for the canonical role layout.
+Only when vocabulary inspection proves a close structural sibling should you inspect that sibling's
+README and the specific role files you must adapt; do not compare unrelated business packages to
+infer generic architecture.
## What each role must get right
@@ -40,12 +40,13 @@ needs no Core release.
**The value layer is where authored data becomes trustworthy.** Every value that crosses a boundary
gets an `assert…` that states what is wrong in the author's terms, and a `seal…` that canonicalises
it. A Producer that receives an unsealed value has no way to tell a mistake from a shape it has not
-met. `assertMediaItemSpec` and `sealMediaItemSpec` in `packages/media-track/src/program.ts` are the
-pattern.
+met. The fixture's value layer is the minimal pattern; a close sibling may be used as a bounded
+implementation skeleton only after vocabulary inspection.
**The Style decoder reads a Recipe, not a stylesheet.** It takes one `SvsRecipe` and the exact fonts,
validates the keys it admits, and produces a Style value. Unknown keys fail; defaults are declared,
-not implied. See `decodeCommentStickerStyle` in `packages/comment-sticker/src/author.ts`.
+not implied. Use the fixture's decoder for the generic boundary, or the selected close sibling when
+the new package intentionally extends that sibling's domain contract.
**The renderer turns a Program into elements and nothing else.** It resolves no timing of its own and
reaches into no other Track. Timing arrives already projected; placement arrives as a Frame.
diff --git a/examples/README.md b/examples/README.md
index df635b4e..0c3f9dd8 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -1 +1,4 @@
# Examples
+
+`minimal-author-package/` is a package-authoring fixture, not a complete video example. Video
+examples, when shipped, must contain a complete `main.svml`, Recipe and Run Source together.
diff --git a/examples/minimal-author-package/README.md b/examples/minimal-author-package/README.md
new file mode 100644
index 00000000..99013cab
--- /dev/null
+++ b/examples/minimal-author-package/README.md
@@ -0,0 +1,5 @@
+# Minimal author-package fixture
+
+Use this directory only as the generic author-package fixture. It is deliberately not a complete video
+project: the `packages/example-component` package is the authoritative small implementation, while
+the package's `preview/` asset demonstrates a Surface preview.
diff --git a/examples/minimal-author-package/packages/example-component/README.md b/examples/minimal-author-package/packages/example-component/README.md
new file mode 100644
index 00000000..61bc1c12
--- /dev/null
+++ b/examples/minimal-author-package/packages/example-component/README.md
@@ -0,0 +1,14 @@
+# Example component fixture
+
+This is the smallest complete author-package fixture. It is the canonical generic-package reference,
+not a production component or a video example.
+
+It contains a Module Manifest with nominal Types and deterministic Producers, validators, a structured
+Surface decoder returning `records`, `components`, `fragments` and `exports`, and sealed Fragments with
+literal `fragment-input`, `fragment-operation` and `output` references. `src/temporal.ts` shows the
+Surface-side `@hypit/temporal-markup` Window/Moment projections; that package is distinct from the
+graph-side `@hypit/temporal` Producers.
+
+The three Surfaces demonstrate a box, a text surface and a media slot. The slot is a graph input; it is
+not a file bundled by the package. `preview/Example.png` is a real catalogue frame supplied by the
+package's vocabulary.
diff --git a/examples/minimal-author-package/packages/example-component/package.json b/examples/minimal-author-package/packages/example-component/package.json
new file mode 100644
index 00000000..3c9ca445
--- /dev/null
+++ b/examples/minimal-author-package/packages/example-component/package.json
@@ -0,0 +1,19 @@
+{
+ "name": "@example/example-component",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": { ".": "./src/index.ts" },
+ "hypit": { "activation": "./src/activation.ts" },
+ "dependencies": {
+ "@hypit/component-kit": "workspace:*",
+ "@hypit/composition": "workspace:*",
+ "@hypit/elaborator": "workspace:*",
+ "@hypit/markup": "workspace:*",
+ "@hypit/protocol": "workspace:*",
+ "@hypit/program-space": "workspace:*",
+ "@hypit/temporal": "workspace:*",
+ "@hypit/temporal-markup": "workspace:*",
+ "@hypit/visual-ir": "workspace:*"
+ }
+}
diff --git a/examples/minimal-author-package/packages/example-component/preview/build.svrun b/examples/minimal-author-package/packages/example-component/preview/build.svrun
new file mode 100644
index 00000000..e2611870
--- /dev/null
+++ b/examples/minimal-author-package/packages/example-component/preview/build.svrun
@@ -0,0 +1,6 @@
+<?svml using="@hypit/run-markup@1"?>
+
+<svrun version="1">
+ <author source="./preview.svml"/>
+ <target output="box.track"/>
+</svrun>
diff --git a/examples/minimal-author-package/packages/example-component/preview/preview.svml b/examples/minimal-author-package/packages/example-component/preview/preview.svml
new file mode 100644
index 00000000..7d617e97
--- /dev/null
+++ b/examples/minimal-author-package/packages/example-component/preview/preview.svml
@@ -0,0 +1,8 @@
+<?svml using="@hypit/markup@1"?>
+
+<!-- Catalogue Source for the fixture. A host project supplies the ProgramSpace record named `space.main`.
+ The real catalogue frame is preview/Example.png; this file documents the smallest Surface call. -->
+<svml>
+ <import as="example" from="@example/example-component@1"/>
+ <example:Box id="box" space={space.main}/>
+</svml>
diff --git a/examples/minimal-author-package/packages/example-component/preview/recipes.svs b/examples/minimal-author-package/packages/example-component/preview/recipes.svs
new file mode 100644
index 00000000..b7bb15d5
--- /dev/null
+++ b/examples/minimal-author-package/packages/example-component/preview/recipes.svs
@@ -0,0 +1,5 @@
+<?svml using="@hypit/svs@1"?>
+
+<sheet version="1">
+ example.default { background: #6b7280; }
+</sheet>
diff --git a/examples/minimal-author-package/packages/example-component/src/activation.ts b/examples/minimal-author-package/packages/example-component/src/activation.ts
new file mode 100644
index 00000000..a9a95f02
--- /dev/null
+++ b/examples/minimal-author-package/packages/example-component/src/activation.ts
@@ -0,0 +1,10 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import { decodeExampleSurface, exampleComponent, exampleManifest, exampleMarkupSurfaces, exampleModuleRef } from "./index.js";
+
+export const hypitPackage = {
+ format: "hypit.node-package@1" as const,
+ modules: [{ manifest: exampleManifest }],
+ components: [exampleComponent],
+ hostFacets: exampleMarkupSurfaces.map((declaration) => createMarkupSurfaceHostFacet({ module: exampleModuleRef, declaration, handler: decodeExampleSurface })),
+};
+export default hypitPackage;
diff --git a/examples/minimal-author-package/packages/example-component/src/component.ts b/examples/minimal-author-package/packages/example-component/src/component.ts
new file mode 100644
index 00000000..99f480e4
--- /dev/null
+++ b/examples/minimal-author-package/packages/example-component/src/component.ts
@@ -0,0 +1,38 @@
+import { sealVisualTrack } from "@hypit/composition";
+import type { ProgramSpace } from "@hypit/program-space";
+import type { ComponentPackage, ProducerHandler } from "@hypit/component-kit";
+import { canonicalize } from "@hypit/protocol";
+import { VISUAL_IR_V1 } from "@hypit/visual-ir";
+import { exampleProducers, exampleTypes } from "./manifest.js";
+
+const inline = <T>(record: { readonly value: { readonly kind: string; readonly value?: unknown } } | undefined): T => {
+ if (record?.value.kind !== "inline") throw new Error("example producer input must be inline");
+ return record.value.value as T;
+};
+const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
+function render(kind: string, space: ProgramSpace) {
+ const frames = Math.max(1, Math.round(space.durationSec * space.frameRate.numerator / space.frameRate.denominator));
+ return sealVisualTrack({
+ programSpaceId: space.id,
+ visualIr: VISUAL_IR_V1,
+ id: `example-${kind}`,
+ presents: [{ id: `present-${kind}`, span: { startFrame: 0, endFrameExclusive: frames }, stacking: { order: 0, tieBreak: kind }, elements: [{
+ id: `${kind}-root`, kind: "box", order: 0,
+ style: [{ name: "background-color", value: "#6b7280" }],
+ }] }],
+ });
+}
+const producer = (kind: string): { readonly handler: ProducerHandler } => ({ handler: ({ inputs }) => ({ outputs: { track: output(render(kind, inline<ProgramSpace>(inputs.space))) }, needs: {} }) });
+
+export const exampleComponent = {
+ producers: [
+ { producer: exampleProducers.renderBox, ...producer("box") },
+ { producer: exampleProducers.renderText, ...producer("text") },
+ { producer: exampleProducers.renderMedia, ...producer("media") },
+ ],
+ validators: [
+ { type: exampleTypes.box, handler: () => {} },
+ { type: exampleTypes.text, handler: () => {} },
+ { type: exampleTypes.mediaSlot, handler: () => {} },
+ ],
+} satisfies ComponentPackage;
diff --git a/examples/minimal-author-package/packages/example-component/src/fragment.ts b/examples/minimal-author-package/packages/example-component/src/fragment.ts
new file mode 100644
index 00000000..7b68584e
--- /dev/null
+++ b/examples/minimal-author-package/packages/example-component/src/fragment.ts
@@ -0,0 +1,24 @@
+import { compositionTypes } from "@hypit/composition";
+import { sealGraphFragment } from "@hypit/elaborator";
+import { programSpaceTypes } from "@hypit/program-space";
+import { exampleProducers } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+export function createExampleFragment(producer: typeof exampleProducers[keyof typeof exampleProducers], id: string) {
+ return sealGraphFragment({
+ inputs: [{ name: "space", type: programSpaceTypes.programSpace }],
+ operations: [{
+ id,
+ producer,
+ inputs: { space: input("space") },
+ result: { kind: "output", name: "track" },
+ }],
+ exports: [{ name: "track", type: compositionTypes.visualTrack, root: operation(id) }],
+ });
+}
+
+export const exampleBoxFragment = createExampleFragment(exampleProducers.renderBox, "render-box");
+export const exampleTextFragment = createExampleFragment(exampleProducers.renderText, "render-text");
+export const exampleMediaFragment = createExampleFragment(exampleProducers.renderMedia, "render-media-slot");
diff --git a/examples/minimal-author-package/packages/example-component/src/index.ts b/examples/minimal-author-package/packages/example-component/src/index.ts
new file mode 100644
index 00000000..4dec87ff
--- /dev/null
+++ b/examples/minimal-author-package/packages/example-component/src/index.ts
@@ -0,0 +1,5 @@
+export { exampleComponent } from "./component.js";
+export { exampleBoxFragment, exampleMediaFragment, exampleTextFragment } from "./fragment.js";
+export { exampleManifest, exampleMarkupSurfaces, exampleModuleRef, exampleProducers, exampleTypes } from "./manifest.js";
+export { decodeExampleSurface } from "./surface.js";
+export { projectExampleMoment, projectExampleWindow, temporalInstantAttributeNames, temporalWindowAttributeNames } from "./temporal.js";
diff --git a/examples/minimal-author-package/packages/example-component/src/manifest.ts b/examples/minimal-author-package/packages/example-component/src/manifest.ts
new file mode 100644
index 00000000..e68d58c3
--- /dev/null
+++ b/examples/minimal-author-package/packages/example-component/src/manifest.ts
@@ -0,0 +1,59 @@
+import { readFile } from "node:fs/promises";
+import { compositionTypes } from "@hypit/composition";
+import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";
+import { programSpaceTypes } from "@hypit/program-space";
+import { temporalTypes } from "@hypit/temporal";
+
+const previewImage = (file: string) => ({
+ mediaType: "image/png",
+ path: `preview/${file}`,
+ open: async () => Uint8Array.from(await readFile(new URL(`../preview/${file}`, import.meta.url))),
+});
+
+export const exampleModuleRef = { name: "@example/example-component", version: "1" } as const;
+export const exampleTypes = {
+ box: { module: exampleModuleRef, name: "ExampleBox" },
+ text: { module: exampleModuleRef, name: "ExampleText" },
+ mediaSlot: { module: exampleModuleRef, name: "ExampleMediaSlot" },
+} satisfies Record<string, TypeRef>;
+export const exampleProducers = {
+ renderBox: { module: exampleModuleRef, name: "render-example-box" },
+ renderText: { module: exampleModuleRef, name: "render-example-text" },
+ renderMedia: { module: exampleModuleRef, name: "render-example-media-slot" },
+} satisfies Record<string, ProducerRef>;
+
+export const exampleManifest: ModuleManifest = {
+ format: "hypit.module@1", name: exampleModuleRef.name, version: exampleModuleRef.version,
+ dependencies: [
+ { module: compositionTypes.visualTrack.module },
+ { module: programSpaceTypes.programSpace.module },
+ { module: temporalTypes.window.module },
+ ],
+ types: Object.values(exampleTypes).map(({ name }) => ({ name })),
+ capabilities: [],
+ producers: Object.values(exampleProducers).map((producer) => ({
+ name: producer.name,
+ inputs: [{ name: "space", type: programSpaceTypes.programSpace }],
+ outputs: [{ name: "track", type: compositionTypes.visualTrack }],
+ needs: [],
+ })),
+};
+
+const vocabulary = (summary: string, example: string) => ({
+ summary,
+ appearance: "A deterministic, self-contained example surface rendered on the supplied ProgramSpace.",
+ preview: previewImage("Example.png"),
+ attributes: [
+ { name: "id", kind: "identifier" as const, required: true, summary: "Names this instance." },
+ { name: "space", kind: "reference" as const, required: true, accepts: [programSpaceTypes.programSpace], summary: "Selects the time space." },
+ ],
+ ports: [{ name: "track", type: compositionTypes.visualTrack, summary: "The terminal VisualTrack." }],
+ example,
+ notes: ["The same shape is used for box, text and media-slot surfaces; only the terminal Producer changes."],
+});
+
+export const exampleMarkupSurfaces = [
+ { name: "box", tag: "Box", mode: "structured", outputs: [exampleTypes.box, compositionTypes.visualTrack], vocabulary: vocabulary("A framed box surface.", "<example:Box id=\"box\" space={space.main}/>") },
+ { name: "text", tag: "Text", mode: "structured", outputs: [exampleTypes.text, compositionTypes.visualTrack], vocabulary: vocabulary("A text-bearing surface.", "<example:Text id=\"title\" space={space.main}>Hello</example:Text>") },
+ { name: "media-slot", tag: "MediaSlot", mode: "structured", outputs: [exampleTypes.mediaSlot, compositionTypes.visualTrack], vocabulary: vocabulary("A media slot whose content is a graph input.", "<example:MediaSlot id=\"shot\" space={space.main}/>") },
+] as const;
diff --git a/examples/minimal-author-package/packages/example-component/src/surface.ts b/examples/minimal-author-package/packages/example-component/src/surface.ts
new file mode 100644
index 00000000..92a21062
--- /dev/null
+++ b/examples/minimal-author-package/packages/example-component/src/surface.ts
@@ -0,0 +1,28 @@
+import type { StructuredElement, StructuredSurfaceHandler, SurfaceComponentDraft, SurfaceRecordDraft, SurfaceResolvedReference } from "@hypit/markup";
+import { exampleBoxFragment, exampleMediaFragment, exampleTextFragment } from "./fragment.js";
+import { exampleMarkupSurfaces, exampleTypes } from "./manifest.js";
+
+function text(element: StructuredElement, name: string): string {
+ const value = element.attributes[name];
+ if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${element.name}.${name} must be text.`);
+ return value.trim();
+}
+function reference(element: StructuredElement, name: string, resolve: (path: string) => SurfaceResolvedReference | undefined): SurfaceResolvedReference {
+ const value = element.attributes[name];
+ if (typeof value !== "object" || value.kind !== "reference") throw new Error(`${element.name}.${name} must be a reference.`);
+ const resolved = resolve(value.path);
+ if (resolved === undefined) throw new Error(`${element.name}.${name} cannot resolve ${value.path}`);
+ return resolved;
+}
+
+export const decodeExampleSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ const id = text(element, "id");
+ const space = reference(element, "space", resolveReference);
+ const surface = exampleMarkupSurfaces.find((item) => item.tag === element.name.split(":").at(-1));
+ if (surface === undefined) throw new Error(`Unknown example surface ${element.name}`);
+ const fragment = surface.name === "box" ? exampleBoxFragment : surface.name === "text" ? exampleTextFragment : exampleMediaFragment;
+ const type = surface.name === "box" ? exampleTypes.box : surface.name === "text" ? exampleTypes.text : exampleTypes.mediaSlot;
+ const record: SurfaceRecordDraft = { id: `${id}.value`, type, value: { kind: "inline", value: { id } }, range: element.range };
+ const component: SurfaceComponentDraft = { id, fragment: fragment.id, inputs: { space: space.ref }, outputs: { track: `${id}.track` }, range: element.range };
+ return { records: [record], components: [component], fragments: [fragment], exports: [`${id}.value`, `${id}.track`] };
+};
diff --git a/examples/minimal-author-package/packages/example-component/src/temporal.ts b/examples/minimal-author-package/packages/example-component/src/temporal.ts
new file mode 100644
index 00000000..a455a4e7
--- /dev/null
+++ b/examples/minimal-author-package/packages/example-component/src/temporal.ts
@@ -0,0 +1,6 @@
+import { createTemporalInstantProjection, createTemporalWindowProjection, temporalInstantAttributeNames, temporalWindowAttributeNames } from "@hypit/temporal-markup";
+
+/** The fixture intentionally exposes both projection helpers and their vocabularies. */
+export { temporalInstantAttributeNames, temporalWindowAttributeNames };
+export const projectExampleWindow = createTemporalWindowProjection;
+export const projectExampleMoment = createTemporalInstantProjection;
diff --git a/packages/reference-video-tools/README.md b/packages/reference-video-tools/README.md
index 26bd9c49..66025a66 100644
--- a/packages/reference-video-tools/README.md
+++ b/packages/reference-video-tools/README.md
@@ -24,6 +24,10 @@ deterministic gates; it does not invoke a VLM/observer or perform visual review.
Both observers produce the same observation keys in the same cache, so everything downstream reads one
shape. Neither receives SVML syntax, and neither writes SVML.
+The canonical result envelope is `prepare_reference.observations` for the four whole-reference passes,
+and `result: { status, text }` for a single or batch narrow answer. Direct whole-reference fields and
+the `answer` alias are retained only for older callers.
+
Run the CLI from the repository or an installed package:
```bash
@@ -89,9 +93,9 @@ defaulting to four at a time with a 1.5 second gap. They describe the quota behi
rather than anything about the video, so they are environment settings and not flags. Lower them if a
quota objects; the failure to expect is rate limiting, which backs off on its own before giving up.
-`--question` is a separate narrow path: it requires one to three `--shot-id` values, answers only
-that question from those shots' clips and frames in a single request, and neither reads nor writes
-the observation cache.
+`--question` is a separate narrow path: it requires exactly one `--shot-id`, answers only that
+question from that shot's clip and frames in a single request, and neither reads nor writes the
+observation cache. Cross-shot continuity uses the built-in boundary and three-shot window observations.
`compare_reconstruction` sends the named shot's reference frame and a rendered image as an
unlabelled pair and returns a description of their visible differences. It is never told which image
diff --git a/packages/reference-video-tools/src/cli.ts b/packages/reference-video-tools/src/cli.ts
index 237ca33f..0e8eeebf 100644
--- a/packages/reference-video-tools/src/cli.ts
+++ b/packages/reference-video-tools/src/cli.ts
@@ -29,11 +29,11 @@ function usage(): string {
" hypit-reference-video-tools route_state --action start|read|checkpoint|reconcile --project-root <dir> [options]",
" hypit-reference-video-tools revision_state --action start|read|checkpoint|reconcile --project-root <dir> [options]",
" start: --route reconstruction|description [--run <run>] [--reference-id <id>]",
- " checkpoint: --route <route> --step <n> [--status in_progress|complete|blocked] [--next-action <text>] [--artifacts <json>]",
+ " checkpoint: --route <route> (--state <stage> | --step <n>) [--status in_progress|complete|blocked] [--next-action <text>] [--artifacts <json>]",
" read/reconcile: --project-root <dir>",
" hypit-reference-video-tools prepare_reference --video-path <path or link> [--observer gemini|agent] [--redo media|transcript|people|voices|systems|places|all]",
" hypit-reference-video-tools observe_reference --reference-id <id> [--shot-id <id> ...] [--reobserve]",
- " hypit-reference-video-tools observe_reference --reference-id <id> --shot-id <id> [--shot-id <id> ...] --question <text>",
+ " hypit-reference-video-tools observe_reference --reference-id <id> --shot-id <id> --question <text>",
" hypit-reference-video-tools observe_reference --reference-id <id> --batch <questions.json>",
" hypit-reference-video-tools record_observation --reference-id <id> [--run <build.svrun>] --key <key> --text <text>|--text-file <path>",
" hypit-reference-video-tools record_observation --reference-id <id> [--run <build.svrun>] --batch <answers.json>",
@@ -192,6 +192,19 @@ function usage(): string {
].join("\n");
}
+function routeStateUsage(): string {
+ return [
+ "Usage:",
+ " hypit-reference-video-tools route_state --action start --project-root <dir> --route reconstruction|description [--run <run>] [--reference-id <id>]",
+ " hypit-reference-video-tools route_state --action read|reconcile --project-root <dir>",
+ " hypit-reference-video-tools route_state --action checkpoint --project-root <dir> --route reconstruction|description (--state <stage> | --step <n>) [options]",
+ "",
+ "Use exactly one of --state and --step. --state is the durable stage name; --step is retained for compatibility.",
+ "",
+ "Stages depend on the selected route. Read route.md for the ordered stage list.",
+ ].join("\n");
+}
+
// The authoring and check commands name what they act on positionally — a Run for `render_element`,
// `preview_check` and `reconstruction_check`, one or more package directories for `render_previews` —
// so a token that is not a flag is collected rather than refused. Every other command still refuses
@@ -276,11 +289,18 @@ async function main(): Promise<void> {
if (command === "list_svml_packages") {
result = await tools.list_svml_packages();
} else if (command === "route_state") {
+ if (flags.has("help") || flags.has("h")) {
+ report(`${routeStateUsage()}\n`);
+ return;
+ }
+ const routeStateFlags = new Set(["action", "project-root", "route", "run", "reference-id", "step", "state", "status", "next-action", "artifacts", "decision", "command", "error", "package-root", "input"]);
+ for (const name of flags.keys()) if (!routeStateFlags.has(name)) throw new Error(`unknown route_state option --${name}\n\n${routeStateUsage()}`);
const action = typeof supplied?.action === "string" ? supplied.action : one(flags, "action");
if (action !== "start" && action !== "read" && action !== "checkpoint" && action !== "reconcile") {
- throw new Error("--action must be start, read, checkpoint or reconcile");
+ throw new Error("--action must be start, read, checkpoint or reconcile\n\n" + routeStateUsage());
}
- const projectRoot = typeof supplied?.project_root === "string" ? supplied.project_root : required(flags, "project-root");
+ const projectRoot = typeof supplied?.project_root === "string" ? supplied.project_root : one(flags, "project-root");
+ if (projectRoot === undefined || projectRoot.trim().length === 0) throw new Error("--project-root is required\n\n" + routeStateUsage());
if (supplied !== undefined) {
result = await tools.route_state(supplied as RouteStateCommandInput);
} else if (action === "start") {
@@ -294,9 +314,15 @@ async function main(): Promise<void> {
} else {
const route = one(flags, "route");
if (route !== "reconstruction" && route !== "description") throw new Error("--route must be reconstruction or description");
- const step = Number(required(flags, "step"));
- if (!Number.isSafeInteger(step) || step < 1) throw new Error("--step must be a positive integer");
- const status = one(flags, "status");
+ const stepFlag = one(flags, "step");
+ const stateFlag = one(flags, "state");
+ if ((stepFlag === undefined) === (stateFlag === undefined)) throw new Error("checkpoint requires exactly one of --state <stage> or --step <n>\n\n" + routeStateUsage());
+ const numericStep = stepFlag === undefined ? undefined : Number(stepFlag);
+ if (stepFlag !== undefined && (!Number.isSafeInteger(numericStep) || numericStep! < 1)) throw new Error("--step must be a positive integer");
+ const step: number | string = stateFlag ?? numericStep!;
+ // A checkpoint names a completed stage unless the caller explicitly marks it in progress or blocked.
+ // This keeps the concise `--state <stage>` form useful while preserving the API's explicit statuses.
+ const status = one(flags, "status") ?? "complete";
if (status !== undefined && status !== "in_progress" && status !== "complete" && status !== "blocked") throw new Error("--status must be in_progress, complete or blocked");
const artifacts = one(flags, "artifacts");
let parsedArtifacts: Readonly<Record<string, string>> | undefined;
diff --git a/packages/reference-video-tools/src/index.ts b/packages/reference-video-tools/src/index.ts
index 04bdcdec..269fcc86 100644
--- a/packages/reference-video-tools/src/index.ts
+++ b/packages/reference-video-tools/src/index.ts
@@ -19,7 +19,7 @@ export {
ROUTE_STATE_STEPS,
ROUTE_STATE_VERSION,
} from "./route-state.js";
-export type { RouteCheckpointInput, RouteKind, RouteState, RouteStateInput } from "./route-state.js";
+export type { DescriptionRouteStep, ReconstructionRouteStep, RouteCheckpointInput, RouteKind, RouteState, RouteStateInput, RouteStep } from "./route-state.js";
export {
checkpointRevisionState,
readRevisionState,
diff --git a/packages/reference-video-tools/src/route-state.ts b/packages/reference-video-tools/src/route-state.ts
index 8b2973da..cdbda470 100644
--- a/packages/reference-video-tools/src/route-state.ts
+++ b/packages/reference-video-tools/src/route-state.ts
@@ -3,6 +3,17 @@ import { dirname, join, resolve } from "node:path";
export type RouteKind = "reconstruction" | "description";
export type RouteStatus = "active" | "complete" | "blocked";
+export type ReconstructionRouteStep =
+ | "environment" | "reference-prepared" | "reference-observed" | "vocabulary-checked"
+ | "package-ready" | "script-checked" | "source-authored" | "graph-checked"
+ | "review-planned" | "preview-rendered" | "comparison-complete" | "repairs-complete"
+ | "final-checked" | "build-complete";
+export type DescriptionRouteStep =
+ | "environment" | "brief-frozen" | "vocabulary-checked" | "package-ready"
+ | "script-checked" | "source-authored" | "graph-checked" | "review-planned"
+ | "preview-rendered" | "review-complete" | "repairs-complete" | "final-checked"
+ | "build-complete";
+export type RouteStep = ReconstructionRouteStep | DescriptionRouteStep;
export type RouteState = {
readonly version: 2;
@@ -31,7 +42,7 @@ export type RouteStateInput = {
};
export type RouteCheckpointInput = RouteStateInput & {
- readonly step: number;
+ readonly step: number | RouteStep;
readonly status?: "in_progress" | "complete" | "blocked";
readonly nextAction?: string;
readonly artifacts?: Readonly<Record<string, string>>;
@@ -90,33 +101,47 @@ function migrateLegacyRouteState(value: unknown, path: string): RouteState | und
if (value === null || typeof value !== "object" || (value as { version?: unknown }).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;
if (typeof legacy.project_root !== "string" || legacy.project_root.length === 0) throw new Error(`route state at ${path} has no project_root`);
- const oldSteps = LEGACY_ROUTE_STATE_STEPS[legacy.route];
+ const oldSteps = LEGACY_ROUTE_STATE_STEPS[route];
if (!Array.isArray(legacy.completed_steps) || legacy.completed_steps.some((step) => !Number.isSafeInteger(step) || step < 1 || step > oldSteps.length)) {
throw new Error(`route state at ${path} has invalid legacy completed_steps`);
}
const completedNames = legacy.completed_steps.map((step) => oldSteps[step - 1]!).filter(Boolean);
- const completed = completedNames.flatMap((name) => {
- const index = ROUTE_STATE_STEPS[legacy.route!].indexOf(name);
+ let completed = completedNames.flatMap((name) => {
+ const index = ROUTE_STATE_STEPS[route].indexOf(name);
return index < 0 ? [] : [index + 1];
});
+ // A legacy snapshot could claim source-authored (and later gates) before the v2 vocabulary,
+ // package and Script gates existed. Re-open that point and everything after it; artifacts/checks
+ // will earn the new stages again instead of letting an old numeric cursor bless an unverified package.
+ const sourceStage = ROUTE_STATE_STEPS[route].indexOf("source-authored") + 1;
+ const requiredStages = ["vocabulary-checked", "package-ready", "script-checked"]
+ .map((name) => ROUTE_STATE_STEPS[route].indexOf(name) + 1);
+ if (completed.includes(sourceStage) && requiredStages.some((stage) => !completed.includes(stage))) {
+ completed = completed.filter((stage) => stage < sourceStage);
+ }
// New gates are intentionally re-opened during migration. The first unmet predicate, not the
// legacy numeric cursor, is the only safe recovery point.
- const currentStep = nextUncompleted(legacy.route, completed);
+ const currentStep = nextUncompleted(route, completed);
const now = new Date().toISOString();
return {
version: ROUTE_STATE_VERSION,
- route: legacy.route,
+ route,
project_root: legacy.project_root!,
...(legacy.run === undefined ? {} : { run: legacy.run }),
...(legacy.reference_id === undefined ? {} : { reference_id: legacy.reference_id }),
- status: currentStep > ROUTE_STATE_STEPS[legacy.route].length ? "complete" : "active",
+ status: currentStep > ROUTE_STATE_STEPS[route].length ? "complete" : "active",
current_step: currentStep,
completed_steps: [...new Set(completed)].sort((a, b) => a - b),
- in_progress: currentStep > ROUTE_STATE_STEPS[legacy.route].length ? null : { step: currentStep, started_at: now },
+ in_progress: currentStep > ROUTE_STATE_STEPS[route].length ? null : { step: currentStep, started_at: now },
artifacts: legacy.artifacts ?? {},
decisions: legacy.decisions ?? [],
- next_action: legacy.next_action ?? `complete ${ROUTE_STATE_STEPS[legacy.route][currentStep - 1] ?? "route"}`,
+ // 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.
+ next_action: currentStep > ROUTE_STATE_STEPS[route].length
+ ? "route complete"
+ : `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 }),
updated_at: now,
@@ -165,6 +190,25 @@ function stageNumber(route: RouteKind, name: string): number {
return index + 1;
}
+function stepNumber(route: RouteKind, step: number | RouteStep): number {
+ if (typeof step === "number") {
+ if (!Number.isSafeInteger(step) || step < 1 || step > ROUTE_STATE_STEPS[route].length) {
+ throw new Error(`step ${step} is outside the ${route} route`);
+ }
+ return step;
+ }
+ return stageNumber(route, step);
+}
+
+function assertPriorStagesComplete(route: RouteKind, step: number, completed: ReadonlySet<number>): void {
+ const missing = Array.from({ length: step - 1 }, (_, index) => index + 1)
+ .filter((candidate) => !completed.has(candidate));
+ if (missing.length > 0) {
+ const names = missing.map((candidate) => ROUTE_STATE_STEPS[route][candidate - 1]).join(", ");
+ throw new Error(`cannot complete ${ROUTE_STATE_STEPS[route][step - 1]} before ${names}`);
+ }
+}
+
/** Source cannot be accepted until vocabulary, package and Script gates are durable. */
function assertSourcePrerequisites(route: RouteKind, step: number, completed: ReadonlySet<number>): void {
if (step !== stageNumber(route, "source-authored")) return;
@@ -207,14 +251,19 @@ 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 (input.step < 1 || input.step > ROUTE_STATE_STEPS[input.route].length) throw new Error(`step ${input.step} is outside the ${input.route} route`);
+ const step = stepNumber(input.route, input.step);
const completed = new Set(existing.completed_steps);
- if (input.status === "complete") {
- assertSourcePrerequisites(input.route, input.step, completed);
- completed.add(input.step);
+ const status = input.status ?? "complete";
+ 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
+ // artifact before an earlier manual checkpoint is written; reconcile still keeps that manual gap.
+ if (typeof input.step === "string") assertPriorStagesComplete(input.route, step, completed);
+ assertSourcePrerequisites(input.route, step, completed);
+ completed.add(step);
}
const completedSteps = [...completed].sort((a, b) => a - b);
- const next = input.status === "complete" ? nextUncompleted(input.route, completedSteps) : input.step;
+ const next = status === "complete" ? nextUncompleted(input.route, completedSteps) : step;
const now = new Date().toISOString();
const decisions = input.decision === undefined || input.decision.trim().length === 0 || existing.decisions.includes(input.decision)
? existing.decisions
@@ -229,12 +278,12 @@ export async function checkpointRouteState(input: RouteCheckpointInput): Promise
...existing,
...(input.run === undefined ? {} : { run: resolve(projectRoot, input.run) }),
...(input.referenceId === undefined ? {} : { reference_id: input.referenceId }),
- status: input.status === "blocked" ? "blocked" : next > ROUTE_STATE_STEPS[input.route].length ? "complete" : "active",
+ status: status === "blocked" ? "blocked" : next > ROUTE_STATE_STEPS[input.route].length ? "complete" : "active",
current_step: next,
completed_steps: completedSteps,
- in_progress: input.status === "in_progress"
- ? { step: input.step, started_at: now }
- : input.status === "complete"
+ in_progress: status === "in_progress"
+ ? { step, started_at: now }
+ : status === "complete"
? (next > ROUTE_STATE_STEPS[input.route].length ? null : { step: next, started_at: now })
: existing.in_progress,
artifacts,
diff --git a/packages/reference-video-tools/src/tools.ts b/packages/reference-video-tools/src/tools.ts
index 0bdca9d0..8c6dfcc0 100644
--- a/packages/reference-video-tools/src/tools.ts
+++ b/packages/reference-video-tools/src/tools.ts
@@ -36,6 +36,7 @@ import {
ROUTE_STATE_STEPS,
} from "./route-state.js";
import type { RouteKind, RouteState } from "./route-state.js";
+import type { RouteStep } from "./route-state.js";
import {
checkpointRevisionState,
readRevisionState,
@@ -74,8 +75,9 @@ export type ObserveReferenceInput = {
readonly reobserve?: boolean;
/**
* A round of narrow questions, asked together. Each entry names its own shots and its own question
- * and inherits `reference_id`. No narrow question's answer depends on another's, which is why the
- * route asks them at once — and why asking them one process at a time was a shell loop.
+ * and inherits `reference_id`; each `shot_ids` array must contain exactly one shot. No narrow
+ * question's answer depends on another's, which is why the route asks them at once — and why asking
+ * them one process at a time was a shell loop.
*/
readonly questions?: readonly { readonly shot_ids: readonly string[]; readonly question: string }[];
};
@@ -194,7 +196,7 @@ export type RecordReviewInput = {
export type RouteStateCommandInput =
| ({ readonly action: "start"; readonly project_root: string; readonly route: RouteKind; readonly run?: string; readonly reference_id?: string })
| ({ readonly action: "read" | "reconcile"; readonly project_root: string })
- | ({ readonly action: "checkpoint"; readonly project_root: string; readonly route: RouteKind; readonly step: number; readonly status?: "in_progress" | "complete" | "blocked"; readonly run?: string; readonly reference_id?: string; readonly next_action?: string; readonly artifacts?: Readonly<Record<string, string>>; readonly decision?: string; readonly command?: string; readonly error?: string });
+ | ({ readonly action: "checkpoint"; readonly project_root: string; readonly route: RouteKind; readonly step: number | RouteStep; readonly status?: "in_progress" | "complete" | "blocked"; readonly run?: string; readonly reference_id?: string; readonly next_action?: string; readonly artifacts?: Readonly<Record<string, string>>; readonly decision?: string; readonly command?: string; readonly error?: string });
export type RevisionStateCommandInput =
| ({ readonly action: "start"; readonly project_root: string; readonly run?: string; readonly parent_route?: "reconstruction" | "description"; readonly parent_state_digest?: string; readonly request?: string })
@@ -1086,6 +1088,12 @@ function prepared(state: ReferenceState): boolean {
}
function publicPrepare(state: ReferenceState): PrepareResult {
+ const observations = {
+ people_and_product: state.people_and_product ?? observation("failed", "not analyzed"),
+ voices: state.voices ?? observation("failed", "not analyzed"),
+ persistent_systems: state.persistent_systems ?? observation("failed", "not analyzed"),
+ places: state.places ?? observation("failed", "not analyzed"),
+ } as const;
return {
reference_id: state.reference_id,
status: prepared(state) ? "ready" : "partial",
@@ -1093,10 +1101,8 @@ function publicPrepare(state: ReferenceState): PrepareResult {
shots: state.shots,
storyboard_ref: state.storyboard_ref,
transcript: state.transcript ?? unavailable("not transcribed"),
- people_and_product: state.people_and_product ?? observation("failed", "not analyzed"),
- voices: state.voices ?? observation("failed", "not analyzed"),
- persistent_systems: state.persistent_systems ?? observation("failed", "not analyzed"),
- places: state.places ?? observation("failed", "not analyzed"),
+ ...observations,
+ observations,
};
}
@@ -1469,6 +1475,12 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
voices,
persistent_systems: systems,
places,
+ observations: {
+ people_and_product: people,
+ voices,
+ persistent_systems: systems,
+ places,
+ },
observer,
...(fetched === undefined ? {} : { source_url: fetched.url, downloaded: !fetched.cached }),
pending_observations: pending,
@@ -1508,7 +1520,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
const question = input.question?.trim() ?? "";
if (question.length > 0) {
assert(input.shot_ids !== undefined && input.shot_ids.length > 0, "question requires at least one shot id, so that it is answered from the shots it is about");
- assert(selected.length <= 3, "question accepts at most three shots");
+ assert(selected.length === 1, "question accepts exactly one shot id; use the built-in boundary/window observations for cross-shot continuity");
// Keyed by the shots it is asked over and by the question itself, so the observer that answers
// out of band has a key it can record against and a second, different question over the same
// shots gets its own. Keyed on the shots alone, the two would share an entry and the later one
@@ -1541,6 +1553,8 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
shot_ids: selected.map((shot) => shot.shot_id),
question,
observation_key: key,
+ result: answer,
+ // Compatibility alias for callers written before the canonical result envelope.
answer,
// Says the answer came back without asking anyone, so a reader knows they were not billed
// for it and that `--reobserve` is what asks again.
@@ -2125,7 +2139,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
return { reference_id: state.reference_id, key, stored_in: "comparisons" };
}
const shotKeys = new Set(state.shots.flatMap((shot) => [`visual:${shot.shot_id}`, `type:${shot.shot_id}`, `audio:${shot.shot_id}`, `boundary:${shot.shot_id}`, `window:${shot.shot_id}`]));
- // A narrow question is asked over one to three shots and keyed by them and by a digest of the
+ // A narrow question is asked over exactly one shot and keyed by it and by a digest of the
// question, so its key is matched the same way `observe_reference` builds it rather than
// enumerated here. A shot id is `shot-001`: the hyphen belongs in the class, and leaving it out
// rejected every key this tool actually produces, so an answer to a narrow question had nowhere
@@ -2133,7 +2147,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
const questionKey = /^question:([0-9a-z-]+(?:\+[0-9a-z-]+)*):[0-9a-f]{8}$/u.exec(key);
const knownShots = new Set(state.shots.map((shot) => shot.shot_id));
const askedOver = questionKey?.[1]!.split("+") ?? [];
- const isQuestion = questionKey !== null && askedOver.length <= 3 && askedOver.every((id) => knownShots.has(id));
+ const isQuestion = questionKey !== null && askedOver.length === 1 && askedOver.every((id) => knownShots.has(id));
assert(shotKeys.has(key) || isQuestion, `key ${key} is not an observation of reference ${input.reference_id}`);
// A round of answers arrives as a round of calls, and each one is a read-modify-write of this
// file. Two of them reading before either writes is how an answer disappears with no error.
diff --git a/packages/reference-video-tools/src/types.ts b/packages/reference-video-tools/src/types.ts
index 79e39b22..6eb8467c 100644
--- a/packages/reference-video-tools/src/types.ts
+++ b/packages/reference-video-tools/src/types.ts
@@ -113,6 +113,13 @@ export type PrepareResult = {
readonly shots: readonly Shot[];
readonly storyboard_ref: string;
readonly transcript: Transcript;
+ /** Canonical whole-reference observation envelope. Legacy direct fields remain for compatibility. */
+ readonly observations?: Readonly<{
+ readonly people_and_product: Observation;
+ readonly voices: Observation;
+ readonly persistent_systems: Observation;
+ readonly places: Observation;
+ }>;
readonly people_and_product: Observation;
readonly voices: Observation;
readonly persistent_systems: Observation;
diff --git a/packages/reference-video-tools/test/route-state.test.ts b/packages/reference-video-tools/test/route-state.test.ts
index 8c655350..a5ff3f93 100644
--- a/packages/reference-video-tools/test/route-state.test.ts
+++ b/packages/reference-video-tools/test/route-state.test.ts
@@ -38,6 +38,17 @@ test("route state starts once, checkpoints idempotently, and advances to the nex
assert.equal((await readRouteState(root))?.current_step, 2);
});
+test("named checkpoints default to complete and cannot skip an earlier stage", async () => {
+ const root = await mkdtemp(join(tmpdir(), "hypit-route-state-"));
+ await startRouteState({ projectRoot: root, route: "reconstruction" });
+ const completed = await checkpointRouteState({ projectRoot: root, route: "reconstruction", step: "environment" });
+ assert.deepEqual(completed.completed_steps, [1]);
+ await assert.rejects(
+ checkpointRouteState({ projectRoot: root, route: "reconstruction", step: "reference-observed" }),
+ /cannot complete reference-observed before reference-prepared/u,
+ );
+});
+
test("reconcile uses durable artifact pointers and preserves manual gaps", async () => {
const root = await mkdtemp(join(tmpdir(), "hypit-route-state-"));
const source = join(root, "main.svml");
diff --git a/packages/reference-video-tools/test/tools.test.ts b/packages/reference-video-tools/test/tools.test.ts
index d2825516..40a8dc3c 100644
--- a/packages/reference-video-tools/test/tools.test.ts
+++ b/packages/reference-video-tools/test/tools.test.ts
@@ -165,7 +165,8 @@ test("a narrow question costs one call, answers from the named shots and is answ
assert.deepEqual(calls[0]!.mimeTypes, ["video/mp4", "image/jpeg"]);
assert.equal(calls[0]!.text, "How thick is the caption outline?");
assert.deepEqual(result["shot_ids"], ["shot-003"]);
- assert.deepEqual(result["answer"], { status: "complete", text: "the caption sits above the lower edge" });
+ assert.deepEqual(result["result"], { status: "complete", text: "the caption sits above the lower edge" });
+ assert.deepEqual(result["answer"], result["result"], "answer remains only as a compatibility alias");
// The key carries the question as well as the shots, so a second question over the same shot is a
// separate entry rather than the first one's answer handed back under a shared key.
@@ -180,8 +181,8 @@ test("a narrow question costs one call, answers from the named shots and is answ
tools([]).observe_reference({ reference_id: REFERENCE, question: "which shot?" }),
/question requires at least one shot id/u);
await assert.rejects(
- tools([]).observe_reference({ reference_id: REFERENCE, shot_ids: ["shot-001", "shot-002", "shot-003", "shot-004"], question: "which shot?" }),
- /at most three shots/u);
+ tools([]).observe_reference({ reference_id: REFERENCE, shot_ids: ["shot-001", "shot-002"], question: "which shot?" }),
+ /exactly one shot id/u);
});
test("the key a narrow question is handed out under is one record_observation accepts", async () => {
@@ -199,7 +200,7 @@ test("the key a narrow question is handed out under is one record_observation ac
assert.equal(stored["stored_in"], "observations");
const again = await api.observe_reference({ reference_id: REFERENCE, shot_ids: ["shot-003"], question: "How thick is the caption outline?" });
- assert.deepEqual(again["answer"], { status: "complete", text: "two pixels" });
+ assert.deepEqual(again["result"], { status: "complete", text: "two pixels" });
});
test("reconstruction comparison sends an unlabelled pair and accepts rendered PNG frames", async () => {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 65f08faf..0ee2e9c0 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -259,6 +259,36 @@ importers:
specifier: ^1.6.4
+ examples/minimal-author-package/packages/example-component:
+ dependencies:
+ '@hypit/component-kit':
+ specifier: workspace:*
+ version: link:../../../../packages/component-kit
+ '@hypit/composition':
+ specifier: workspace:*
+ version: link:../../../../packages/composition
+ '@hypit/elaborator':
+ specifier: workspace:*
+ version: link:../../../../packages/elaborator
+ '@hypit/markup':
+ specifier: workspace:*
+ version: link:../../../../packages/markup
+ '@hypit/program-space':
+ specifier: workspace:*
+ version: link:../../../../packages/program-space
+ '@hypit/protocol':
+ specifier: workspace:*
+ version: link:../../../../packages/protocol
+ '@hypit/temporal':
+ specifier: workspace:*
+ version: link:../../../../packages/temporal
+ '@hypit/temporal-markup':
+ specifier: workspace:*
+ version: link:../../../../packages/temporal-markup
+ '@hypit/visual-ir':
+ specifier: workspace:*
+ version: link:../../../../packages/visual-ir
+
packages/artifact:
dependencies:
'@hypit/protocol':