Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
refactor(build): finalize result-oriented execution model
kashorinfd2387b738f7
diff --git a/.agents/skills/hypit/SKILL.md b/.agents/skills/hypit/SKILL.mdindex 2076e26d..8365a947 100644--- a/.agents/skills/hypit/SKILL.md+++ b/.agents/skills/hypit/SKILL.md@@ -1,280 +1,118 @@---name: hypit-description: Produce a complete video program from a description or reference video, revise a completed project, or batch-expand a validated project into independent variants; author, check, preview, build, inspect and retrieve Hypit/SVML projects; configure runtimes and credentials; develop missing project-local author packages; and apply native video production playbooks. Use for video production with Hypit and SVML/SVS/SVRun authoring; this is not for developing the Hypit repository itself.+description: Produce a complete video program from a description or reference video, revise a completed project, or create independent variants; author, inspect, preview, build and retrieve Hypit/SVML projects; configure runtimes and credentials; develop missing project-local author packages; and apply native video production playbooks. Use for video production with Hypit and SVML/SVS/SVRun authoring; this is not for developing the Hypit repository itself.---# Hypit-> **Scope boundary:** This is a production skill for creating, reconstructing, previewing, reviewing,-> revising and building videos with Hypit. It is **not a development skill for the Hypit repository-> itself**. If the task is to implement, debug, test, refactor or otherwise develop Hypit packages,-> CLIs, Studio, runtime or repository infrastructure, ignore the video-production routes and follow-> the repository's contributor/development instructions instead.+> **Scope boundary:** This is a production skill. When the task is to implement, debug, test or+> refactor the Hypit repository itself, do not use this production workflow.-## Session initialization+Complete the production task without asking the author to choose routine implementation details.+Interrupt only for an action that spends their money, for genuinely missing credentials, or for the+choice of observer that will read a reference video.-When this Skill is loaded for the first time in a new conversation, synchronize the complete Hypit-repository before entering any production route. If the selected Distribution is a Hypit contributor-checkout, update that checkout first:+Before a paid Build, run `hypit plan`, state the estimated cost and the selected Provider/credential+source without exposing secrets, and obtain approval. A Build is never an implicit consequence of a+preview, inspection or review command.-```bash-git pull --ff-only origin main-```--This is a whole-repository update: it refreshes the CLI, packages, services, examples, docs and Skill-source together. Do not treat an installed Skill update as a substitute for pulling the checkout.-After the checkout is current, refresh the installed global Skill as well:--```bash-npx --yes skills update hypit --global --yes-```--Run the repository pull and installed Skill refresh once per conversation, do not repeat them for later-turns, and then continue with the current request using the current checkout and refreshed Skill. Do-not reset or overwrite local changes: if `git pull --ff-only origin main` cannot fast-forward, stop and-report the sync conflict. If no contributor checkout is selected, there is no local repository to pull;-still run the global Skill refresh and report that only the installed Skill was updated. If either-operation cannot complete because the network or CLI is unavailable, report that the latest state could-not be confirmed before proceeding; never pretend the repository is current.+## Project model-**Run the route to the end without stopping.** There is one thing worth interrupting the author for;-everything else is yours to decide:+Keep these separate:-- **Spending their money.** A Build generates, and generating is billed. Say what it will cost and- get a yes before submitting one. Before asking for approval, report the Provider and credential- source used by every paid capability (without revealing secrets). Credential setup must already be- complete at the environment gate; do not defer login until this paid handoff.+- `.svml` Author Source describes the program;+- `.svs` Recipe Source describes generation choices;+- `.svrun` Run Source binds one executable request;+- `hypit.runtime.json` selects external execution facilities;+- a Build is one execution;+- a Result is the project-owned record of what that Build produced.-Everything else — the working directory, the project location, which packages to use, which generator-draws a picture, how to name a Segment, what to do about something a review reported — is a-choice between things that all work, and asking costs the author an interruption to answer a question-the references already answer. Decide it and keep going. A run that stops half way with a question is-a run the author has to restart.+Do not create route state, revision state, recovery cursors, content-addressed evidence directories or+aggregate approval state. Continue from the files that actually exist in the project. A reference+observation, render, comparison, layout report or Result is useful content; it is not proof that an+agent completed an abstract stage.-## Non-negotiable environment gate+Do not repeat a paid Build just because conversation context was compacted. Inspect the Run and its+Results directly. If a Result exists, use it. If execution is still active, use Runtime status. If+there is no Result and no active Build, ask before submitting a new paid Build.-For every video-production route — original authoring, reconstruction, revision, and variant work —-read `references/environment.md` completely and finish its environment setup before doing anything-else in the route. This is a hard prerequisite, not documentation to consult later. The completed-environment must include a selected Hypit Distribution, an explicit project boundary, the project's-Runtime Profile, resolved credentials for the capabilities the route will use, and every selected-managed program installed and healthy. Credential setup is part of this gate: default to HypiHub OAuth-without asking the author to choose, run the login yourself when the selected HypiHub OS credential is-missing, and continue only after it succeeds. Only when the author explicitly asks to use their own-provider key may you configure that less-recommended path instead. Run the required `hypit runtime up`-provisioning and health checks; WhisperX must report `Ready whisperx` (or an equivalent successful probe). Do this before-inspecting media or examples, preparing a reference, choosing an observer, freezing a brief, reading-vocabulary, writing Source, previewing, or building.+## Environment and credentials-Do not skip, replace, defer, or partially complete any environment step, and do not proceed because-the user asks to bypass it. If Distribution selection, project setup, credential resolution, Runtime-Profile selection, program installation, or any health check is incomplete or cannot be confirmed,-stop at the environment stage and repair it first. Authentication commands may be run to complete this-gate, but no production route may proceed without it and no later paid step may defer it.+Use an installed machine-wide CLI when available. In a contributor checkout, use that checkout's+Node entrypoints; the npm package is not currently published. Read `references/environment.md` before+the first production command and `references/credentials.md` when credentials are involved.-The credentialless `agent` observer is not a way around this rule. It may be used only after the-credential choice has been settled; never silently select it because no credential was found. For-reference analysis, strongly recommend Gemini VLM through the configured HypiHub or Vertex backend:-it can separate speakers, align who speaks when, and extract voice/timbre and presentation traits that-make later voice-design and dubbing more faithful. The calling agent is an explicit fallback, not a-credential bypass.+When running from a Hypit checkout, put author projects under `<checkout-root>/projects/<name>/`.+Load an existing checkout-root or project-root `.env` for commands, but never commit it or copy secrets+into Source, reports or prompts.-The supplied reference video is evidence only. It may be prepared, observed, sampled and compared,-but it must never be copied into the project or used as the final Film/Track/Take source. Do not wire-the reference path through `media:Video`, `asset:Video`, a media track, a Film, or a Run Target. Every-visible shot in a reconstruction must be newly authored as a generated take or as an explicitly-author-supplied replacement asset. A source that directly plays the reference is not a reconstruction-and must be rejected before preview or Build.--## Login-only fast path--If the request is only to sign in or authenticate HypiHub (for example, `login to hypit`), treat it as-credential setup, not video production. Do not read or enter the reconstruction, original-authoring,-observer, playbook, vocabulary, preview, or recovery routes; do not inspect media, create a project,-start a Worker, or ask which observer to use. Do not read any supporting reference for this path,-including `environment.md` and `credentials.md`; this section contains the needed login instructions.-This is a strict login-only fast path, not a general environment-diagnosis route. Do not run-`ls`, `find`, `rg`, `pwd`, `which`, `cat`, `head`, `tail`, `grep`, `doctor`, `runtime status`,-`runtime logs`, `runtime up`, any `--help` command, or any other exploratory command. Do not inspect-`.env`, `hypit.runtime.json`, package code, CredentialStore implementations, or repository metadata.-Do not compose exploratory shell commands around the login commands. Use the already selected Runtime-Profile (or the explicit profile the author names) and invoke the configured launcher directly. For-the standard HypiHub OAuth endpoint, the only allowed probe is:+For a login-only request, do no project discovery. Use only:```bashhypit auth status hypihub.default [--runtime <explicit-profile>]-```--If that status says the credential store is read-only, the Endpoint uses `env`, or the Endpoint is not-declared in the selected Profile, report that OAuth login is unavailable for the selected Endpoint and-stop immediately. Do not investigate why with source or filesystem reads. If the status is writable-and missing, first explain that no usable credential is configured, OAuth avoids copying an API key,-an account without an active subscription can purchase one at hypit.ai after signing in, and opening-login does not submit a paid generation; then immediately run:--```bashhypit auth login hypihub.default [--runtime <explicit-profile>]```-Wait for it to finish. The login-only path consists solely of `auth status`, the one short explanation,-and `auth login`; never add discovery, help, diagnostics, or source inspection between them.+Run login only when status says the selected credential store is writable and the credential is+missing. Explain that browser sign-in stores a session in the OS credential store and does not submit+a paid generation.-## Credentials: complete them during environment setup+## Authoring rules-During environment setup, before any media inspection, observer call, model call, preview, or Build,-check the selected HypiHub Endpoint's credential with `hypit auth status <endpoint> --runtime <profile>`.-If the writable OS credential is missing, explain that HypiHub OAuth is the default because it avoids-copying a key, then immediately run `hypit auth login <endpoint> --runtime <profile>` yourself. Do not-ask the author to run the command or paste a key. A configured credential needs no repeated login. If-the author explicitly requests their own key, configure the requested Provider instead and tell them-this is the less-recommended path. Never defer credential setup until a paid Build.+Every captioned or on-screen spoken passage must use short complete Cues separated by `||`. Default to+roughly 3–4 spoken words per Cue, fewer for dense words. Read `references/script-time.md` and the+caption craft before writing Script text.-When a selected HypiHub Endpoint is missing its OS credential, first tell the author why you are opening the login: no usable credential is configured, and browser sign-in lets Hypit use HypiHub without asking them to copy or paste an API key. If the account has no active Hypit subscription, they can purchase one on hypit.ai after signing in. The session is stored in the OS credential store, and opening login does not itself submit a paid generation. Then run `hypit auth login <endpoint> --runtime <profile>` yourself. The command opens the HypiHub login page, waits for the OAuth callback, and stores the resulting session in the OS credential store. Do not tell the author to copy a key or run the command manually. Continue only after login succeeds; if it is cancelled or fails, stop at environment setup.+Never rely on renderer wrapping to rescue a long Cue. Never hand-author SVG files, inline SVG or SVG+data URLs in an author project or project-local package. Never modify an installed package for one+project; use another public Surface or create a project-local package for a real capability gap.-Use this file only to route the task. A route file is a sequence of numbered steps, and each step-names the files it needs; read those when you reach that step rather than all of them up front.+The temporary `@hypit/ranking` branch restriction remains: do not select, read or use that installed+package. Use another applicable capability or develop a project-local alternative.-Keep `.svml` Author Source, `.svs` Recipe Source, `.svrun` Run Source, and-`hypit.runtime.json` Runtime Profile as separate languages and responsibilities.+## Direct inspection-Non-negotiable Script rule: every captioned or on-screen spoken passage must be split into short,-complete Cues with `||` in the Script. As the default, cut after roughly 3–4 spoken words (fewer when-the words are long or visually dense); longer runs require an explicit visual reason. Never rely on-renderer line wrapping or a wide Caption box to rescue a long Segment: a Segment without `||` is one-Cue and will overflow the Canvas. Read-`references/script-time.md` and the caption craft before writing Script text; put breaks between-complete Alignment Units, never inside Dual Text.+The reference-video commands are independent tools, not ordered stages:-Every route is resumable. At the start of a route, create the project's current-`.hypit/route-state.json` view; the execution history lives at-`.hypit/routes/<route-id>/state.json`. Revisions likewise keep the current-`.hypit/revision-state.json` view and execution history under `.hypit/revisions/<revision-id>/`.-After any new turn, interruption, or context compaction, read-`references/recovery.md`, inspect that snapshot and reconcile it against the artifacts and checks-before continuing. Never resume from chat memory alone, and never repeat a completed or paid step-without verifying its durable evidence.--## Conversation language preference--On the first production turn, infer the author's preferred reply language from the current request and-record it in the route JSON state as a decision such as `user-language: zh-CN` (use an appropriate BCP 47-language tag). If the author explicitly requests a different language, update that decision. On every-later turn in the same conversation, read the current route state and reply in its recorded language;-do not switch languages merely because a command, filename, prompt or quoted source uses another one.-Keep code, CLI commands, model names and quoted Script text unchanged. Login-only conversations have no-production route state; keep the preference in conversation context until a project route starts.--Temporary branch constraint: do not select, use or read the installed `@hypit/ranking` package or-its declarations, README, examples or source on this branch. If a request needs a ranking-like-visual system, choose another applicable installed capability or treat the requirement as a genuine-gap and use the formal project-local package workflow from the visible requirement. Do not copy,-vendor or modify `@hypit/ranking`. This is an internal routing constraint: do not tell the author-that a choice was made because of the skill or this constraint. Present the chosen alternative or-new local component as the normal production decision, with its practical rationale when useful.--Before Source is accepted, every route must complete persisted vocabulary inspection,-`validate_local_author_packages` for every project-owned package under the project's `packages/`-directory, and-`validate_script_cues` (maximum four visible words per Cue). `preview_check` and the route's final-check repeat these gates even if route-state claims they were completed.-When a Run contains accepted `build-record` pins, pass its Runtime Profile to-`validate_local_author_packages`, `preview_check`, `layout_check` and the final check so the archive-can resolve those Records before any graph or layout result is trusted.--Agent-boundary constraint: do not read or rely on the memory of Codex, Claude Code, or any other-coding agent.--Do not create or hand-author SVG images anywhere in an author project or project-local package.-This includes `.svg` assets, inline `<svg>` markup, and SVG data URLs.--Every route uses a Hypit Distribution and an independent author project. Prefer an installed-machine-wide CLI; when the task is running from a Hypit contributor checkout, use that checkout's-Node entrypoints instead. The npm package is not currently published, so absence of the `hypit`-command is not permission to install it from the registry. `references/environment.md` establishes-the boundary and launcher selection. Read it before the first command of any route.--When running from a Hypit checkout, create new author projects under-`<checkout-root>/projects/<project-name>/`. Before asking for credentials, check for `.env` at the-checkout root and at the project root, load any present file into the command environment, and use-the credentials it provides. If the loaded credentials satisfy the selected observer or Provider,-do not ask the author to repeat them; ask only when a required credential is genuinely absent or-invalid. Never commit `.env` or copy its secret values into route state, Source, logs or prompts.--## Route--- Reference-video reconstruction, reverse engineering, shot/B-roll/overlay analysis, or recreating- a video as Hypit source → read `references/reconstruction/route.md`. This is the route whatever- the author calls it — reconstruct, reverse-engineer, recreate, replicate, clone, remake, copy,- rebuild, or the same idea in any language — and **a video, with or without words around it, is- this route** even when no verb is given at all. A path to a file and a link to one — TikTok,- YouTube, Instagram, Bilibili — are the same request; a link is fetched with `yt-dlp` and everything- after that reads the file. A video with a change attached —- this one but with our presenter, our product, our brand — is this route too, and the change is made- on the finished reconstruction. The path is the whole request: the working directory, the project- location and the vocabulary are yours to decide rather than to ask for.-- Making a video from a description, brief, topic, script or format name, with nothing to copy →- read `references/original-authoring/route.md`. This is the route whatever shape the request takes —- "make me a 45-second ranking video", "a talking-head explainer about X", an ad for a product, a- written script to produce, a topic and a duration, a format named on its own, or the same idea in- any language — and **a description with no video attached is this route** even when no verb is- given at all. What it is for, who is in it and what it says are the author's; the working- directory, the project location, the packages and the generators are yours to decide rather than to- ask for.-- Every original-authoring request → read `references/brief-intake.md` and inspect complete projects- under the checkout's `examples/` directory when it exists. Analyze a semantically matching- project's author intent; otherwise use the document's general, open-ended fallback. Do not- hard-code video types or skip the brief-sufficiency gate.-- A completed project followed by a natural-language change → read `references/revision/route.md`- and use the independent `revision_state` route. The completed project may come from reconstruction,- original authoring, a completed variant or an earlier revision, or the author may supply an existing completed project- directory directly; it does not need to have been created in the current session. Restore the- element's role in the frozen intent, edit only Source/Recipe/Run, invalidate the affected graph- closure, and rerun deterministic gates. Revision never invokes VLM/observer visual inspection;- after the change, start Studio only when the current Run has no Studio session so the author can- see the updated result. This routing rule also applies after a paid Build has produced the full- video: revise the accepted-material Run, never the rendered artifact and never by resuming either- creation route.-- A request for many independent versions after reconstruction, original authoring or revision, or- from a validated existing project → read `references/variant-expansion/route.md`. The main agent- inspects examples, freezes format/Slate/component decisions, enumerates vocabulary, discloses the- fast/medium/new-package workload, and resolves package gaps before copying or dispatching variant- agents. Initial presenter/product/brand adaptation attached to a reconstruction remains inside the- reconstruction route; it is not Revision. Variant expansion defaults to mechanically checked- Source and performs no visual review or paid Build unless the author explicitly requests outputs.-- If original authoring or reconstruction created a project-local package, wait until that route is- complete, read `references/package-promotion.md`, and judge whether the component has clear, high- reuse value across unrelated videos. Only when that bar is met, ask the author whether they want the- Agent to move it into the Hypit repository's `packages/` folder and prepare a Pull Request for- Hypit. Do not interrupt the production route for this question, move or submit anything without- the author's answer, and do not suggest promotion for an ordinary component or one that only- contains this video's content.-- A syntax question about one element, or a source that already exists → read- `references/authoring.md`, then `references/quickstart.md` and the linked authoritative- docs/package READMEs. A whole video is `references/original-authoring/route.md`, not this file.-- Which package owns an element, what vocabulary is installed at all, or whether a capability is- genuinely missing → read `references/vocabulary.md`.-- Creating a new author component → read `references/local-author-package.md`. Both routes reach it- at the step that proves a vocabulary gap.-- Seeing what the sources produce, or proving the graph traces before any Build → read- `references/preview.md`.-- Recovering after interruption or context compaction → read `references/recovery.md` before any- other route step.-- Preview-only media realization, temporary preview Runs, mock Artifact caching, or estimated- SemanticTake timing → read `references/preview-mock.md`.-- Paid-build handoff, pre-payment mock confirmation, post-build Studio display, or Studio behavior- after a revision → read `references/studio-confirmation.md`.-- Runtime setup, plan/build/status/inspect/get/reuse → read `references/runtime.md`.-- Environment diagnosis or credentials → read `references/environment.md` and- `references/credentials.md`.-- Seedance prompt assembly → read `references/seedance-kits.md`.-- Production craft or format selection → read `references/playbooks/index.md` and follow its- required load order, which names the craft every program needs regardless of format.--Preserve unrelated changes. Keep credentials, generated media, runtime state, and logs out of-commits. Installed package declarations and published docs remain authoritative; repository-maintenance instructions apply only to contributors who deliberately cloned the repository.+```bash+hypit-reference-video-tools list_svml_packages+hypit-reference-video-tools inspect_svml_vocabulary --package <package>+hypit-reference-video-tools inspect_visual_schema+hypit-reference-video-tools validate_local_author_packages --run <build.svrun>+hypit-reference-video-tools validate_script_cues --run <build.svrun>+hypit check <build.svrun>+hypit-reference-video-tools preview_check <build.svrun>+hypit-reference-video-tools layout_check --run <build.svrun>+```-Studio URL handoff is mandatory: whenever a Studio process is started, capture the URL printed by-the server and include the exact URL in the user-facing response. A statement that Studio started-without the URL is incomplete; if the startup parameters change, stop the old process first and-report the new URL after the replacement is listening.+Use the reports that answer the current question. A report does not unlock another command. Layout+measurements are advisory; repair a genuine issue or record an intentional structural finding with+`layout_accept` and a reason.++When a Run contains accepted `build-record` pins, pass its Runtime Profile to commands that must read+those Results.++## Task routing++- Reference video, link, reconstruction or reverse engineering: read+ `references/reconstruction/route.md` and `references/reconstruction/observers.md`.+- Description, topic, script or format with no reference video: read+ `references/original-authoring/route.md` and `references/brief-intake.md`.+- A natural-language change to an existing completed project: read `references/revision/route.md`.+ Edit Source/Recipe/Run, never rendered media.+- Many independent versions: create ordinary independent project directories from the accepted source+ project and keep an explicit human-readable task list. Do not construct a second project history or+ variant state machine. Paid Builds remain individually approved.+- Package discovery or a possible capability gap: read `references/vocabulary.md`.+- A new author component: read `references/local-author-package.md`.+- Preview or visual inspection: read `references/preview.md`, `references/preview-mock.md`,+ `references/element-review.md` and `references/layout-checks.md` as needed.+- Runtime setup, Build, status, Result inspection and reuse: read `references/runtime.md`.+- Studio handoff: read `references/studio-confirmation.md`.+- Production craft: read `references/playbooks/index.md` and its required craft references.++If a project-local component has clear reuse value across unrelated videos, finish the current video+first, then read `references/package-promotion.md` and ask before moving it into the Hypit repository.++Preserve unrelated changes. Keep credentials, generated media, Runtime state and logs out of commits.+Whenever Studio is started, report the exact URL printed by the server.diff --git a/.agents/skills/hypit/references/authoring.md b/.agents/skills/hypit/references/authoring.mdindex 6eb5b1dc..c8c383ca 100644--- a/.agents/skills/hypit/references/authoring.md+++ b/.agents/skills/hypit/references/authoring.md@@ -1,103 +1,49 @@# Hypit source authoring-For a post-completion natural-language change, use `revision/route.md`. That route edits Source/Recipe/Run-and reruns deterministic gates only; this authoring page's visual review guidance does not apply to a-revision.+Read `quickstart.md` and the authoritative page it selects. Keep Author Source, Recipe Source and Run+Source complete rather than assembling independent per-shot fragments.-Read `quickstart.md`, then the authoritative published page it selects.-Keep Author Source, Recipe Source and Run Source complete and internally consistent rather than-assembling independent per-shot source fragments.+Before writing an element, inspect the owning package's public vocabulary and README. Never invent a+component, attribute, child, port, Recipe property or literal value, and never infer one package's+syntax from another.-Before writing an element, read the owning package README and inspect what its Surface actually-declares — `vocabulary.md` names the command and decides which package owns an element in the first-place. For `@hypit/<name>@1`, inspect its installed declaration and README with the vocabulary tool.-Never invent a-component, attribute, child, port, Recipe property or literal value. Do not infer one package's-syntax from a neighboring package.--An admitted declaration value is not a promise that every Provider endpoint accepts it. Before a-paid Build, run the Runtime preflight and read the selected Provider README for endpoint limits; a-Provider may reject a value that the model-neutral package declares. For example, KIE's GPT Image 2-endpoint rejects `4:3`, `3:4` and `4:5` even though the model contract admits those ratios. Resolve-such a mismatch before submission, never after the first paid generation has completed.--Install dependencies after package selections change. Validate with one command:+Use direct reports as needed:```bash-hypit-reference-video-tools preview_check path/to/project/build.svrun+hypit-reference-video-tools validate_local_author_packages --run <run>+hypit-reference-video-tools validate_script_cues --run <run>+hypit check <run>+hypit-reference-video-tools preview_check <run> [<runtime>]```-Before that command, persist vocabulary inspection and run `validate_local_author_packages --run`-and `validate_script_cues --run`. Local packages must have real Surface/Producer/Fragment exports and-be used by the compiled Graph; every caption Cue must be four or fewer visible words.--It checks every Source the Run reaches before it proves the graph traces — the Run, the Author it-names, and the Recipe sheets and kits the Author imports — then goes on to the wiring itself. One-`hypit check` of the Run covers that same closure, but running it separately would only report the-same failure twice.--**A check that passes is not a graph that traces.** `hypit check` proves a Source is legal — its-syntax, its references, its graph structure — and proves nothing about whether the tracks it declares-can actually be built, nor that an uncertain requirement was understood correctly. `preview.md`-proves the Run traces, before any Provider is reached.+`hypit check` answers whether Source is legal. `preview_check` answers whether the Run traces to a+Film or whether only external capabilities remain unresolved. Neither records project progress.-Route commands point `.hypit/route-state.json` at execution-scoped, content-addressed durable evidence.-If context is compressed, read `recovery.md`, reconcile the project, and resume from the reported-`next_action`.+An admitted model-neutral value is not proof that every Provider Endpoint accepts it. Before a paid+Build, read the selected Provider documentation and Runtime preflight. Resolve endpoint limitations+before submission.-## Reuse an accepted Record+## Reuse an accepted Result output-Hypit holds no implicit cache. Connect a Record an earlier Build accepted to a later Build by naming-it in the Run Source:+Reference a public output accepted by an earlier Build in a later Run:```svml<target output="final.video"/>-<build-record id="accepted-take" build="build-001"- output="opening-take.video"/>+<build-record id="accepted-take" build="build-001" output="opening-take.video"/><satisfy output="opening-take.video" candidate="accepted-take"/>```-The selected Candidate must supply the Logical Output's exact nominal Type. Core does not infer-creative equivalence or propagate a substitute-quality label downstream. Changing the Target list-alone does not select a Record.--Pin as soon as a Build accepts something. **A Build that fails still accepted everything upstream of-the failure** — every picture and every take that ran before the step that broke — and resubmitting-without pinning them buys the same bytes again. Run `--pin` against the failed Build before touching-the cause. `hypit history --source <author.svml> --pin` emits the pairs for the newest accepted-Record of each output; do not transcribe Build ids by hand.--For a Run opened in Studio, add `--exclude-targets` and keep every declared Target unresolved. A-Target satisfied by its accepted media Record is an opaque finished file, so Studio cannot trace it-to the current Film graph. The accepted-material Studio handoff is defined in-`studio-confirmation.md`.--Pinning accepted `build-record` Candidates does not invalidate the gates, but the archive must be-opened with the Runtime Profile so those Records can be resolved. Pass the profile to every gate that-supports it: `validate_local_author_packages --runtime <profile>`, `layout_check --runtime <profile>`,-`reconstruction_check --runtime <profile>` and `authoring_check --runtime <profile>`; for-`preview_check`, pass the profile as its optional second operand:-`preview_check <run> <profile>`. Never remove accepted pins or rerun a paid Build just to make a gate-read an archived Record.+The Candidate must have the exact nominal Type required by the Logical Output. Changing Targets alone+does not select a Result. When Studio or inspection needs a `build-record`, pass the Runtime Profile so+the Result repository can be opened.-**Pin what a Provider was paid to make, and nothing the Source computes.** `--pin` emits a line for-every accepted output, including the ones the Script's own structure produced: `speech.semantic`,-`speech.visual`, `speech.audio`, and the Caption Track's deterministic projection. Those are-projections of the Takes — free to rebuild, and measured against the Script as it was. Paste them-back after editing a Segment — renaming one, merging two — and the Build pins a skeleton whose-anchors describe a program that no longer exists. It does not fail: every Track times itself against-those stale anchors and the delivery is quietly wrong.+Reuse generated media and paid SemanticTakes when their generating inputs still mean the same thing.+If a Script Segment changes, do not keep a SemanticTake whose tokens and anchors describe the old+Segment. Deterministic Track projections are recomputed from current Source; they are not historical+media to pin.-**A `SemanticTake` is both.** Alignment is a served capability, so `<take>-semantic.take` is work-something was paid for and is worth pinning, and its tokens and anchors are keyed to the Script-Segment it aligned, so it goes stale on a Segment edit exactly as the projections above do. Pin it-while the Script is untouched; drop it for the Takes whose Segment you edited, and let those-re-align. This is the one line where "keep what was paid for" and "drop what the Script invalidated"-disagree, and the Script wins.+A failed Build may still have useful public outputs in its Result. Inspect and name those outputs, then+reference exactly the ones needed by the next Run. Do not resubmit the Build merely to recreate them.-This file is about writing an element correctly, which is a narrower question than making the video-right. What a Track should contain, when a picture may be generated at all, how long a thing stays on-screen and what shows through when it does not — those are decided in `playbooks/index.md`, whose-required load order names the craft every program needs regardless of format. A whole video is-`original-authoring/route.md`, not this file: a Source can pass every check above with every one of-those decisions still unmade.+For whole-video design decisions read `playbooks/index.md`. A later user-requested change follows+`revision/route.md` and edits Source/Recipe/Run, never generated media.diff --git a/.agents/skills/hypit/references/brief-intake.md b/.agents/skills/hypit/references/brief-intake.mdindex 2d314723..257aae4a 100644--- a/.agents/skills/hypit/references/brief-intake.md+++ b/.agents/skills/hypit/references/brief-intake.md@@ -53,7 +53,7 @@ skip intake. Use the user's words, installed vocabulary, craft references and thThis is an analysis method, not a list of ranking, interview, podcast or other type questions. Keepthe brief unfrozen while any unresolved answer could change the program's intent or graph.-## Durable brief+## Project briefPersist a concise JSON object at the one canonical path `.hypit/brief.json` (do not put it in AuthorSource) containing:@@ -61,17 +61,11 @@ Source) containing:- user goal and audience;- intent, Hook/attention strategy and narrative progression;- visual/audio/text relationships;-- example project path and digest, or the general-analysis basis;+- example project path, or the general-analysis basis;- confirmed decisions and unresolved questions;- the expected SVML/SVS/SVRun structural consequences.-Write it atomically. It may be refined before `brief-frozen`; after that checkpoint its recorded-digest is immutable, and any mismatch is a recovery conflict rather than permission to overwrite-the old intent. Do not create `.hypit/brief`, `.hypit/brief.md`, or a second route-specific base brief.-Revision records its own request under `.hypit/revisions/<revision-id>/request.json` and never rewrites-the base brief.--Checkpoint `brief-frozen` only after unresolved questions no longer affect those consequences. An-agent may select fonts, package details and model tier when they are genuinely low risk; it may not-invent core facts, ranking criteria, claims, Hook or audience promises. The brief is the reference for-later review and revision, not a copy of an example.+Keep one brief and edit it when the author clarifies intent. Do not create route-specific copies or a+second history of the brief. An agent may select fonts, package details and model tier when they are+genuinely low risk; it may not invent core facts, ranking criteria, claims, Hook or audience promises.+The brief is useful authoring content and the reference for later review, not a progress marker.diff --git a/.agents/skills/hypit/references/element-review.md b/.agents/skills/hypit/references/element-review.mdindex 307c9db2..75ad73e5 100644--- a/.agents/skills/hypit/references/element-review.md+++ b/.agents/skills/hypit/references/element-review.md@@ -1,7 +1,7 @@# Looking at what was built, before a Build runsThis visual-review page is for the initial reconstruction/description routes. A post-completion-revision does not use it, does not call a VLM/observer, and stops after deterministic gates; see+revision does not use it, does not call a VLM/observer, and stops after direct deterministic checks; see`revision/route.md`.Structural checks prove that a source is legal. They prove nothing about whether it looks like what@@ -15,19 +15,18 @@ reference, so it asks what differs — `reconstruction/comparison-round.md`. A pa description has none, so it asks whether the picture is what it was asked to be —`original-authoring/conformance-round.md`. Read this file first and that one after.-Whether an element is *wired at all* is a different gate with a different rule: `preview.md`'s-`preview_check` must pass before this round is reached, and its failures are repaired without any-attempt ceiling. A graph that does not trace is not a difference to weigh; it is work that is not-done.+Whether an element is *wired at all* is a different question: `preview.md`'s `preview_check` reports+graph failures before this visual round. A graph that does not trace is not a difference to weigh; it+is work that is not done.-Note what that gate covers: it proves the graph is wired, not that every track draws. Nothing is+That check proves the graph is wired, not that every track draws. Nothing ishanded to a Producer until the Build runs, so a Producer that refuses the media it receives surfacesthere rather than here.-The difference between the two gates is what each reports. `preview_check` names the graph failure —+The two reports answer different questions. `preview_check` names the graph failure —the target that does not trace, the chain that is missing — so its repairs are not guessing. This roundnames what is visibly wrong with the picture, in words, and a repair aims at something the round-named. Neither gate expects you to guess; each one tells you what is wrong, and you repair that.+named. Each report tells you what is wrong; neither records hidden progress or grants approval.## The round is named by the check, not chosen by you@@ -42,8 +41,8 @@ appears. This is also the floor, since every placed element declares something.A token range is the stable identity used by every command. `--segment` and `--selection` remainavailable for ranges that already have names.-The gate then holds the round to that list. An element looked at once used to pass; now every entry the-plan names has to have been answered.+The returned plan is the explicit review list. Review every entry it names; no separate workflow+state records whether the list is complete.### Render what the Source configures, not what the catalogue shows@@ -79,7 +78,7 @@ can be illegible on the picture that will replace it.`render_element` delegates this to `@hypit/preview-mock`. The realizer finds every relevant logicaloutput in the compiled Author/Run Graph — the takes, stills and slot contents — derives geometry fromGraph inputs, and materializes them through `@hypit/mock-media` in a temporary Run under-`.hypit/preview/<realization-digest>/`. Never `hypit image`, which pays for a generation+`.hypit/preview/<run-name>/`. Never `hypit image`, which pays for a generationthe video will not reuse, and never a placeholder drawn by a script written for the occasion.Geometry follows the fixed Graph policy: Canvas width/height first, then generation aspect-ratio,@@ -119,7 +118,7 @@ Do not treat a clearly platform/player/export-tool watermark as authored contentprovenance is obvious; if it could be part of the design, record the uncertainty instead of inventinga repair.-A mock lives only in this render. It is never written into the Source, and no gate reads it: the+A mock lives only in this render. It is never written into the Source, and no later check reads it: the`playback` check reads the Source's Recipes, so a mock cannot be mistaken for coverage.### The derived Run carries the mocks, and nothing else changes@@ -129,7 +128,7 @@ and the window is cut out of the frames afterwards, so every element the Sourcedrawn wherever the Source puts it — what is on screen over the words being looked at is what thedelivery will put there.-That derived Run is on disk under `<project>/.hypit/preview/<realization-digest>/preview.svrun`, beside+That derived Run is on disk under `<project>/.hypit/preview/<run-name>/preview.svrun`, besideits materialized Artifact attachments. Open itwhenever something you expected to see is not in the picture: an element that is in the Source andstill not on screen is the package failing to draw it.@@ -287,7 +286,7 @@ State plainly, in the completion report, that the following are unsettled:Caption, Media or Typography Track sits against the speech that is finally delivered is settled oncethat speech exists;- **whether the picture is continuous** — the frames nobody authored that- `playbooks/craft/frame-coverage.md` is about. One inherited edge is settled here: the gate reads each+ `playbooks/craft/frame-coverage.md` is about. One inherited edge is reported here: the check reads eachRecipe's `playback` and refuses an insert configured to stop when its material runs out. The rest —a window that starts late, a blend whose frames are half-covered, a schedule inside a component thatstops between activations — appear in the delivery;@@ -296,9 +295,9 @@ State plainly, in the completion report, that the following are unsettled:`playbooks/craft/seedance-directing.md` says how to trace a take's prompt back to the Segment's`dialogue` while the Source is being written, which is where this one is prevented.-The gate is the mechanical half of this: it names the elements nobody looked at and the timed pictures-configured to empty their windows, and refuses to pass while either remains. It cannot name what a-Build has not produced yet, which is why this list is stated rather than computed.+The mechanical report names elements with no recorded review and timed pictures configured to empty+their windows. It cannot name what a Build has not produced yet, which is why this list is stated+rather than computed.If a project-local package was built along the way, decide whether it should outlive this video andput that to the author: `package-promotion.md` says how to judge it and what promoting it actuallydiff --git a/.agents/skills/hypit/references/layout-checks.md b/.agents/skills/hypit/references/layout-checks.mdindex 75752bbf..d4356a55 100644--- a/.agents/skills/hypit/references/layout-checks.md+++ b/.agents/skills/hypit/references/layout-checks.md@@ -17,7 +17,7 @@ writes atomic state toIt reports only `realized_layout`: DOM bounds after official or project-local Producers run, includingparent or Canvas overflow, vertical offset of package-internal content, and partial overlap between-independent top-level tracks. It does not use literal SVML Canvas/Frame arithmetic as a quality gate.+independent top-level tracks. It does not treat literal SVML Canvas/Frame arithmetic as a quality verdict.`Present` is the Composition IR's time-bounded visual unit: one Producer output with its internaltext, icons, boxes and other elements. For each Present/content state, the checker derives its longest interval in which layout-affecting IR@@ -46,15 +46,13 @@ hypit-reference-video-tools layout_accept --run <build.svrun> --batch acceptanceEach 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-failure because no measurement was made; it must never be converted into an empty passing report.+The browser report separates candidates still needing judgement from intentional candidates carrying+a reason. It does **not** turn zero candidates into approval of the whole design. A browser, font or+Producer execution failure means no measurement was made and must be reported as such.-Finding identities include the relevant layout digest. A Source, SVS, package, runtime, font or-composition change invalidates affected acceptances. Rerun `layout_check` after any visual repair, and-rerun the affected declaration's visual review when the repair changed its look. The final gate needs-both settled layout evidence and current visual evidence where that route performs visual review.+Finding identities are readable structural names built from the finding kind, package, Track,+Present, element and related element. They do not fingerprint the project. Rerun `layout_check` after+a visual repair, and read the affected declaration again when its appearance changed.The 1 CSS px tolerance removes only browser numeric noise. It is not a design threshold and does notturn measurements beyond it into mandatory fixes. Do not copy or edit an installed package after adiff --git a/.agents/skills/hypit/references/local-author-package.md b/.agents/skills/hypit/references/local-author-package.mdindex 76224792..39ddf93a 100644--- a/.agents/skills/hypit/references/local-author-package.md+++ b/.agents/skills/hypit/references/local-author-package.md@@ -1,379 +1,61 @@-# Develop an author package for the project+# Project-local author packages-Use this workflow only after proving that no legal composition of installed packages expresses the-required behavior. A similar-looking tag is insufficient when its declared Types, timing or output-behavior differs. Never write an unknown tag before its package exists.+Create a local package only after inspecting installed vocabulary and confirming that no existing+Surface can express an important visual role. A small stylistic difference is not a missing+capability.-## Know what the element has to look like before deciding the package's shape+## Boundaries-Whatever settles that is the contract, and it is read before the first line of the package — not-assumed, not remembered, not rediscovered halfway. Which document settles it depends on where the-package came from:+- Put the package under the author project's `packages/` directory and use the project's own scope.+- Do not edit, vendor or copy an installed package.+- Keep the package reusable across multiple elements in this project; video-specific words, people,+ products and timing remain in Source/Recipe.+- Do not hand-author SVG assets or inline SVG.+- Use the public package activation, Surface, Producer and Fragment APIs only.-- **From a reference video**, the evidence for the element this package owns lives in the shot- observations (`type:` and `visual:` for its text and picture, `persistent_systems` for its- whole-reference life) and the word-level transcript. Read them.-- **From a description**, nothing external settles it, so it is settled by decision: the answers the- author froze and the appearance values written down before the sources were. `original-authoring/route.md`- requires both. A value nobody wrote down is one this package will be asked for later and will not- have.--Then write out, one line each, every appearance property that contract states — the typeface-character, the weights, the mix of faces, the colours, the stroke, the shadow, the motion, the-timing. A package whose declared vocabulary cannot express one of those lines is wrong before it is-written: widen the package until it carries every one of them. There is no acceptable shortfall —-a stated property is either expressed by the package or the package is not done. A-stated property silently dropped is how a title that runs two typefaces ends up as a-package that draws one font, and the round cannot repair what the package cannot express.--## Write `package.json` and the activation first--Write those two before any implementation. If the package has third-party npm dependencies, use the-project's package manager once; otherwise no install step is needed. Leaving activation until the end-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-before shaping it, a media slot is an input port, the package draws its own chrome, the Types are-frozen before parallel writing — are in this file, and they apply before any other reading.--Then read:--1. `../../../../docs/guide/component-anatomy.md` — the roles every component package fills. Read this- first; it is what the rest is measured against.-2. `../../../../docs/guide/author-packages.md`-3. `../../../../docs/guide/packages.md` and `../../../../docs/guide/conventions.md`-4. the installed `@hypit/component-kit` README--**Write the package from those docs.** They state each role, what it declares and what it hands the-next one, and that is what a new package is built out of. Author every file yourself against them:-the Manifest, the Types, the Surface and decoder, the Producers, the Fragment.--**What a Producer that draws may return is a command, not a package to read.**--```-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 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. `@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, record the missing shape and its effect in route state, then continue with-the closest bounded interpretation supported by the visible contract. Do not invent an undeclared-binding or silently treat the gap as resolved. After the route has finished, report the-Skill/documentation gap with the package/module and version, exact command and checkout commit,-missing Type/Surface/Producer field, complete inspection output, expected authoring shape, and the-smallest Source demonstrating the gap. A binding such as `<id>.audio` absent from both the README and-inspection output is reported this way.--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` |--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.--## Decoder and runtime value shapes--The Style decoder receives a decoded recipe as `{ path, properties }`: `path` is the authored recipe-id and `properties` is the canonical property map. A resolved authored reference may expose its-record; only read an inline value after checking `record.value.kind === "inline"`, then use-`record.value.value`. Never infer a value from the reference path.--The temporal-markup helpers take one object `{ id, subjectId?, element, semantic, resolveReference }`-and return `records`, `components`, `fragments` and a component-output `ref`. The resulting-`TemporalInstant` has `{ id, subjectId, source, projection, authority, frame }`; a-`TemporalWindow` has `{ id, subjectId, start, end, span }`, where each endpoint is a-`TemporalInstant` and `span` has `startFrame` and `endFrameExclusive`.--`SpatialFrame` uses `xPx`, `yPx`, `widthPx` and `heightPx`; `ProgramSpace` provides `id`,-`narrativeId`, `durationSec` and `frameRate` (`numerator` and `denominator`). A `fonts:Stack` Surface publishes a-`FontStackRef`; pass that same record to a Visual IR text element's `fonts` field.--## Package boundary--Place the package at `<project>/packages/<slug>/`, named in the project's own scope such as-`@my-project/<slug>`, with physical-version `0.0.0-dev` and logical Module version `1`. Only create a new package: do not-edit, extend, delete or overwrite an existing Hypit package to fill the gap.--The directory and package name may use any valid, descriptive slug; do not add a `local-` prefix-just to identify where the package was created. The package README documents its public contract,-syntax, inputs, outputs and preview. It does not need to say that the package is temporary,-project-level or otherwise describe its provenance.--The package it stands beside is untouched. A Style family that differs from `caption-fine` in its-timing model, or a board that differs from `ranking` in its rows, installs as a sibling: its own-Module ref, its own name for every nominal Type it declares, since a Type belongs to the Module that-declares it, and its own Producer names. The official packages are built for exactly this —-`caption-fine` states that Common Caption, Composition and Core know none of its Recipe fields or-layout policy, and `deck-track` that another Deck family can install independently and lower to the-same terminal `VisualTrack` without changing it. A sibling family is the designed extension point,-not a workaround.--Read "modelled on the installed packages" that way wherever it appears: the same role in the same-place in the graph, written for this component from the anatomy the guide states.--The project is never the Hypit Distribution. Do not move a local package into an official package-automatically. After the result is accepted, offer promotion as a separate contribution.--The component reaches Studio's generic Track fallback until its project adds a companion package,-for example `@my-project/<slug>-studio`, to the project's `hypit.studio.json`. That companion owns-only Studio interpretation and operations through `hypit.studio-adapter@1`; it never edits-`packages/studio`, and the author package never imports Studio. A generic block is valid while no-special interpretation is needed.--Know what that fallback gives it, because it is enough for a lot of packages. A project-local Track-producing a `VisualTrack` lands in the generic `role: "track"` lane when no companion claims the-Module. Studio draws it in a flat media lane and exposes five timing-parameters — `start`, `end` and `for` writable, `during` and `at` read-only — over a read-only-interaction: the block can be selected and seeked, not dragged or trimmed. A companion package is-what buys anything past that: parameters named for what the component actually has, child entities,-and a lane laid out the way it is shaped.--## Complete implementation--The main agent writes all code. Gemini must not receive or produce TypeScript, `package.json`,-Manifest, Surface, Producer, Validator or activation syntax.--Implement the parts required by the behavior, including:--- `package.json`, exports, dependencies and `hypit.activation`;-- Module Manifest, nominal Types and Producers;-- required Validators and deterministic Component handlers;-- Markup Surface vocabulary and decoder;-- activation contribution;-- lowering, Fragment or renderer implementation needed to produce the declared output;-- README and a preview for each visual Surface.--Choose raw versus structured Surface, timing dependencies, ProgramSpace, Frame, SemanticTrack,-Artifact, Recipe and output Types from the observed behavior and the anatomy the guide states. A-declaration-only or Surface-only package is incomplete.--For variable child counts, emit one child operation per child and chain those fixed-port results-through an append Producer (`previous`, `item` → `set`). Do not add an undeclared `items[]` input or-let a handler consume arbitrary children; every child must be represented by a sealed operation.--The fixture's `exampleAppendFragment` and `append-example-items` Producer are the runnable reference:-each operation has exactly `previous` and `item` inputs and returns `set`, so the returned set can be-fed into the next operation. The empty set is an ordinary typed Record. The handler never accepts-undeclared variadic input.--## The package draws itself--A package is installed vocabulary. `.svml`, `.svs` and `.svrun` are documents that use it. A package-that needs one of those documents in order to draw its own appearance has inverted that-relationship, and the symptom is unmistakable: the component imports cleanly and still shows-nothing.--- Chrome the component always shows — its paper, board, panel, ruled lines, texture, default- backdrop — belongs to the package. Commit it as an ordinary file under the package and read it- with `readFile(new URL("../assets/…", import.meta.url))`, the same way the Surface preview image- is read. Generate it once while authoring the package if it does not exist.-- Produce that file with `hypit image`:-- ```bash- hypit image --prompt "the surface this component draws on" \- --to <project>/packages/<slug>/assets/paper.png- ```-- It writes a picture and nothing else — no Source, no Build, no Record, no Runtime Profile. A- package asset is authoring input, not the output of anybody's video, so it is never a Target and- never a reason to write a Run Source. Writing one to obtain it is the mistake this section exists- to prevent.-- Only pictures that differ between videos are input ports: photographs, screenshots, thumbnails,- product shots, character images.-- A media **slot** — a card, a board, a phone screen, a monitor, any box whose content varies — is- an input port, not package content. It is declared as an attribute accepting the media type- (`image`, `video`, `media`, `surface`), and the content that fills it comes from the document, not- from the package. The frame is the component's; the content is not. A slot is a reusable input- even though this one reference happens to show a particular picture in it: the same component- serves a phone holding a screenshot or a video, a board holding two different inserts, because the- slots are inputs and each document fills them. Writing the observed content into the package is- the same failure as a missing inner picture, inverted: the frame was seen but the slot was closed.- `media-track:Item` and the `icon` port on `@hypit/ranking` are the shape this takes.-- **A slot is a graph edge, not a value the Surface can read.** The package's own texture resolves at- author time because it is a file the package ships; a slot holds whatever the document generated,- which does not exist until the Build runs. A Surface that reaches for it the way it reaches for its- own asset fails with the slot's value refusing to resolve during author compilation. Declare the- slot as a Fragment input carrying the Artifact type, give the Producer that consumes it a second- form for the case where the slot is filled, and read it from `inputs` as the Artifact it is —- a blob input arrives as the `BlobRef` itself rather than wrapped inline like every authored value.-- **The element kind follows the Artifact, not the slot.** A picture slot holds an image when the- document built one and a video when a Run satisfied it with footage, and which of those arrives is- not something the slot's name settles. Hard-code `kind: "image"` and the component builds for- whichever half of that the author did not choose. Decide from the Artifact's `mediaType` and the- same code serves both.-- Never require an input the installing project has no reason to choose. If a Run Source exists only- to produce the component's own texture, the texture is in the wrong place.-- **A slot that is not filled yet costs its own cell and nothing more.** The component's structure —- its rows, bars, frames, labels, the geometry it computes — is drawn whatever the slots turn out to- hold. Draw the elements whose material is there, leave the ones whose material is not, and measure- every cell either way so nothing moves when the rest arrive. A component that refuses to draw- anything because one slot holds material it cannot use has made the whole composition depend on- its most incomplete input, and the symptom reads as a dead Track rather than as a missing picture:- the Producer refuses, the Track never builds, and the rows nobody was waiting for vanish with it.- This is what a Source looks like for the whole stretch between being written and being built, which- is most of its life.-- A component that cannot render on its own cannot produce the preview image its Surface owes. Treat- a missing preview as evidence of this mistake rather than a step to skip.-- Produce that image with `hypit-reference-video-tools render_previews <package-dir>`. It keeps the- package-owned preview SVML, SVS and SVRun on the standard preview-mock/Producer path, then seeks the- middle frame of the target Present's longest stable interval in the fixed local browser. It does- not render a complete PNG sequence; when no interval is stable for two frames, it uses the middle- frame of the longest Present.--For a media slot, declare an Artifact Fragment input. Producer inputs are `TypedRecord`s: inspect-`inputs.media.value`; a filled slot is a BlobRef (`kind === "blob"`), while an authored structured-value is under `kind === "inline"`. Branch on BlobRef `mediaType` (`image/*` or `video/*`) when-choosing the Visual IR element, and still draw the empty frame/cell when no material is supplied.-`hypit image` is a direct, billed HypiHub image-model call (default `@hypit/gpt-image`, credential-HypiHub OAuth via `hypit auth login` at [hypit.ai](https://hypit.ai)); it does not use a project Runtime Profile, Build or Run Source. Obtain approval-before using it and reserve it for package-owned chrome.--```typescript-handler: ({ inputs }) => {- const media = inputs.media?.value.kind === "blob" ? inputs.media.value : undefined;- const kind = media?.mediaType.startsWith("video/") ? "video" : "image";- return { outputs: { track: output(renderSlot(kind, media)) }, needs: {} };-}-```--## Freeze the Types before writing in parallel--The nominal Types and the Manifest are what every other file agrees with, so write them first and-stop changing them. Once they are frozen, the value layer, the Style decoder and the renderer depend-on the Types rather than on each other and can be written in any order or at the same time. The-Surface, the Producer handlers and the Fragment follow, because they wire what those three produce.--Do not start that parallel stretch while a Type is still in question. Interface drift mid-flight-costs more than the ordering saves, and the symptom — a Producer rejecting a value that looks right —-is expensive to read.--## Install and validate--### Mechanical completion gate--Before Source can be considered authored, run:+Inspect the real schemas before implementing:```bash-hypit-reference-video-tools validate_local_author_packages --run <path/to/build.svrun> [--runtime <hypit.runtime.json>]+hypit-reference-video-tools inspect_svml_vocabulary --package <closest-package>+hypit-reference-video-tools inspect_visual_schema```-When the Run contains `build-record` pins, pass the same Runtime Profile used by the Build. The-validator opens that profile read-only so it can resolve accepted Records while compiling the Run;-otherwise a valid project package may be reported as imported but unused.+## Minimal package shape-Every project-owned author package under `<project>/packages/` must expose a non-empty Manifest, at least one-Markup Surface and at least one Producer. Its Surface decoder must expand to a real Graph Fragment with-operations and exports, and every Fragment operation Producer must belong to the package's own Module.-Run-fragment host facets are required only by packages that explicitly provide Run-side replacements such-as preview mocks; an author package is not required to expose one. The Run's compiled Graph must contain-an operation from that package, and the Author Source must import and use its Surface. An import without-use, a marker-only package, or a package replaced by a similar official component fails with a-machine-readable diagnostic. If no gap exists, do not leave an unused package in the project.-`validate_local_author_packages` discovers these package directories from-their manifests; the directory name is not a validation signal.+The package must provide:-The Host resolves the explicitly selected physical package name directly at-`<project>/packages/<package-basename>/` and supplies official `@hypit/*` imports from the read-only-tool Distribution. The `@hypit/*` namespace is reserved for that active Distribution; a project uses-its own npm scope and cannot shadow official ABI packages with a same-named dependency. A project-does not join Hypit's workspace and needs no npm link merely to expose-one of its own packages. Use the project's own package manager only when its package genuinely adds-third-party npm dependencies. Do not modify the Hypit Distribution, hide packages under `.hypit/` or-invent another loader.+- a `package.json` with the appropriate Hypit activation entry;+- a public Surface vocabulary with explicit inputs, outputs and Recipe properties;+- a Producer that returns the declared nominal output Type;+- a Fragment that projects the produced value into the Runtime/Composition system;+- a README describing the public vocabulary and a preview project using it.-Repair in this order:+Prefer composition of existing public operations over new Runtime capabilities. Add a new capability+only when an external or local service genuinely owns that work.-1. package/workspace resolution;-2. activation contribution;-3. Manifest, Producer, Type and Validator agreement;-4. Surface vocabulary and decoding;-5. implementation behavior;-6. source usage.+## Validation-A package that cannot be *wired* is not done. `hypit check` proves the Source is legal, and nothing-more; it will not tell you that the track a package produces cannot be traced to a Film at all. Run-the preview check — it checks every Source the Run reaches, then proves the graph traces — and repair-until it passes. A graph failure is not a difference to weigh, it is work that is not finished, and it-is not bounded by the round's attempt ceiling:+Install the project dependencies, then inspect the package through the same public loading path used+by an author project:```bash-hypit-reference-video-tools preview_check path/to/build.svrun+hypit-reference-video-tools list_svml_packages+hypit-reference-video-tools inspect_svml_vocabulary --package <local-package>+hypit-reference-video-tools validate_local_author_packages --run <project>/build.svrun+hypit-reference-video-tools validate_script_cues --run <project>/build.svrun+hypit check <project>/build.svrun+hypit-reference-video-tools preview_check <project>/build.svrun+hypit-reference-video-tools render_previews <project>/packages/<package>+hypit-reference-video-tools layout_check --run <project>/build.svrun```-If a mandatory gate itself appears defective, do not read or modify Distribution source and do not-silently continue. Record the exact command, complete error, project/package/run digest and the-reason the failure is attributable to the gate in a durable waiver evidence file:--```json-{- "waived": true,- "gate": "package_ready",- "diagnosis": "validator selected a transitive package instead of the project package",- "command": "validate_local_author_packages --run build.svrun",- "error": "<complete error>",- "package_digest": "<sha256>",- "run_digest": "<sha256>"-}-```--Checkpoint that evidence as a controlled waiver (or use `blocked` when no maintainer decision is-available):--```bash-hypit-reference-video-tools route_state --action checkpoint --project-root <project> --route <route> \- --state package-ready --status complete --artifacts '{"package_ready":".hypit/evidence/gate-waiver.json"}' \- --error "<exact gate error>" --decision "gate waiver recorded with reproducible diagnosis"-```--The waiver is visible in route state and remains subject to maintainer review; it preserves the-evidence without weakening package boundaries. Use `--status blocked` instead when continuation is-not explicitly authorized, and resume only after the gate is fixed or a decision is recorded.--It takes the Run Source, not the `.svml`. `preview.md` says why this spelling rather than the-`hypit-preview-check` bin: the subcommand honours `--package-root`, which is what a project-local-package needs when the Run is not at the project root. A pass here means the graph reaches a Film and-a semantic spine; it passes while the Providers are still unrun, and says which capabilities it is-waiting on. See `preview.md` for what that does and does not prove — notably, a-Producer that refuses the media kind it is handed is not caught here, because nothing is handed to-it until the Build runs.+These commands report separate facts. A package is ready when its declared vocabulary loads, the+project actually imports and uses it, the graph traces, its previews render, and visual inspection+matches the requested design. Do not manufacture an override file when a command is broken. Report+the exact defect, fix the tool or package, and rerun the relevant command.-Do not continue to final authoring until the package and sources pass the existing checks and the-graph traces.+## Promotion-When the result is accepted, `package-promotion.md` says how to judge whether the package should-outlive this one video and what promoting it costs.+Finish the video before considering promotion. If the component has clear value across unrelated+projects, read `package-promotion.md` and ask the author before moving it into the Hypit repository.+Otherwise it remains ordinary project source.diff --git a/.agents/skills/hypit/references/original-authoring/conformance-round.md b/.agents/skills/hypit/references/original-authoring/conformance-round.mdindex af968d02..17256666 100644--- a/.agents/skills/hypit/references/original-authoring/conformance-round.md+++ b/.agents/skills/hypit/references/original-authoring/conformance-round.md@@ -1,8 +1,8 @@# Reading each element against what it was asked to be-Completed reviews are durable evidence in the project review log and route snapshot. After a context-boundary, reconcile `.hypit/route-state.json` and continue from its `next_action`; do not repeat an-already completed local review.+Completed reviews are ordinary content in the project review log. After an interruption, inspect that+log and the current render directly. Repeat a local review only when the visible source changed or the+caller explicitly wants a new reading.**Read `../element-review.md` first.** It owns the round this file sits inside, and everything belowis what having no reference changes.diff --git a/.agents/skills/hypit/references/original-authoring/route.md b/.agents/skills/hypit/references/original-authoring/route.mdindex d29882b5..1002129f 100644--- a/.agents/skills/hypit/references/original-authoring/route.md+++ b/.agents/skills/hypit/references/original-authoring/route.md@@ -1,285 +1,74 @@-# Making a video from a description+# Original authoring-Read a step, do it, read the next one. Each step names the files it needs; read those at that step.+Use this workflow when the request supplies a description, topic, script or format but no reference+video.-This route produces a complete video program from what the author says they want: `main.svml`,-`recipes.svs`, `build.svrun` and the `hypit.runtime.json` that binds what they demand — wired, then-built once into a delivery.+## 1. Establish the project-The counterpart route is `../reconstruction/route.md`, which starts from a video to copy. Everything-between the two — what a picture is, what one generation owes another, which package owns an element-— is the same work and is written once, in the files these steps link. This page owns the order.+Read `../environment.md`, create an independent author project, and keep `.svml`, `.svs`, `.svrun`+and `hypit.runtime.json` separate. Read `../brief-intake.md`, semantically relevant complete examples,+and `../playbooks/index.md` before deciding the visual system.-**This route spends.** One Build generates the pictures, the takes, the speech and the render, and-step 13 is where the author says yes to it. There is no reference to check against, so the two things-a reconstruction gets for free have to be decided deliberately: what the program is *for*, and what- every appearance value *is*. Neither has an evidence file to consult. Write them down rather than- discovering them at render time.+Write the brief as ordinary project content. It may be edited when the request becomes clearer; there+is no frozen brief snapshot or hidden progress record.-If a completed project receives a natural-language change, use `../revision/route.md` instead of restarting-this route. Revision is Source/Recipe/Run-only and deterministic; it does not invoke a VLM or visual-observer.-This remains true after a paid Build has produced the full video: start `revision_state` against the-accepted-material Run, never edit the rendered file or resume the creation steps.+## 2. Choose vocabulary-If the same request also asks for many independent derivatives, finish this route through the final-deterministic gate, then enter `../variant-expansion/route.md`. The base project's format, examples,-component choices and package gaps are decided globally there before any variant agent starts.--This route has a hard environment gate. At route entry read `../environment.md` completely and finish-its environment steps (Distribution, project boundary, credentials, Runtime Profile, all selected-managed programs, and health checks) before entering the brief, example, vocabulary, Source, preview,-or Build steps. The local WhisperX Endpoint is one mandatory item and must report `Ready whisperx` (or-an equivalent successful health check). If no profile exists yet, create a minimal profile with local-media and WhisperX endpoints, select it, and provision it before continuing; extend that same profile-later. Do not proceed from a partial or unconfirmed environment, substitute another transcriber, or-continue because the user asks to bypass setup.--## Checkpoint and recovery--Start the project snapshot after creating the project directory:--```bash-hypit-reference-video-tools route_state --action start --project-root <project> \- --route description-```--Route tools update machine-owned stages after successful checks, renders, and reviews. Record an-explicit checkpoint after brief decisions, Source edits, repairs, and Build actions. After any-interruption or context compaction, read `../recovery.md`, run `route_state --action reconcile---project-root <project>`, and continue only from its `next_action`.--### Durable stage map--| state | update / completion predicate | recovery entry |-| --- | --- | --- |-| `environment` | explicit checkpoint after Distribution, project, credentials, Runtime Profile, selected programs and all health checks are ready | `hypit paths --json` / `hypit runtime up` |-| `brief-frozen` | explicit checkpoint naming the frozen brief, audience, format and claims | return to the brief checkpoint |-| `vocabulary-checked` | Run-scoped vocabulary inspection and the frozen `.hypit/component-fit.json` are both persisted | `inspect_svml_vocabulary --run <run>` |-| `source-authored` | explicit checkpoint naming `main.svml` (and Recipe/Run when available) | `hypit check <run>` |-| `package-ready` | every project-owned package under `packages/` has a real Surface/Producer/Fragment and is used by the compiled Graph | `validate_local_author_packages --run <run>` |-| `script-checked` | every caption Cue has at most four visible words | `validate_script_cues --run <run>` |-| `graph-checked` | `preview_check` returns `sound: true` after package and Cue gates | `preview_check <run>` |-| `layout-checked` | `layout_check` executed and every candidate was repaired or explicitly accepted | `layout_check --run <run>` / `layout_accept` |-| `review-planned` | `authoring_check` writes a plan | `authoring_check <run>` |-| `preview-rendered` | render output and timing sidecar both exist | `render_element --batch <round.json>` |-| `review-complete` | review log contains a complete record for the planned element | `review_element` / `record_review` |-| `repairs-complete` | explicit checkpoint after applying review findings | edit Source, then rerun the checks |-| `final-checked` | final `authoring_check` returns `passed: true` | `authoring_check <run>` |-| `build-complete` | explicit checkpoint after the durable Build record is accepted | `hypit build` (confirm cost first) |--The numeric `current_step` is only a cursor; `reconcile` starts at the first unmet predicate. It never-infers a creative brief, conformance judgement or repair from file presence alone.--## A description is the whole request--The author gives what the video should be — its subject, its length, its audience, who is in it, what-it says. The working directory, the project location, which packages to use, which generator, which-model tier and how many takes are **yours to decide rather than to ask for**.-------### 1. Select the Distribution and place the project--**Read now:** `../environment.md` — the three independent places, Distribution selection and the-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 the runtime-minimum: `name`, `version: "0.0.0"`, `private: true` and `type: "module"`.--### 2. Load credentials--Check `<checkout-root>/.env` first, then `<project-root>/.env` if present, and load each before-credential probing (the project file overrides duplicate names):--```bash-set -a-[ ! -f <checkout-root>/.env ] || . <checkout-root>/.env-[ ! -f <project-root>/.env ] || . <project-root>/.env-set +a-```--If the loaded variables satisfy the selected Provider, continue without asking the author for them-again. Ask only for a credential that is absent or invalid after both `.env` files are checked.--**Read now:** `../credentials.md` — which variables each Provider needs.--### 3. Make the brief sufficient before writing Source--**Read now:** `../brief-intake.md`. Always inspect the checkout root's `examples/` directory when it-exists, enumerate complete projects, and compare any semantically relevant project's recovered author-intent, Hook and narrative to the request. If no example is semantically relevant, use the document's-general fallback; absence of an example is not permission to guess or skip intake.--Ask only for unresolved, high-impact creative decisions. Freeze a concise `.hypit/brief.json` recording-the user's goal, audience, intent, Hook, narrative progression, visual/audio/text relationships,-claims, confirmed decisions, unresolved questions, and expected SVML/SVS/SVRun consequences. Low-risk-implementation details are yours; core facts, claims, Hook and audience promise require confirmation.-Do not enter `brief-frozen` or write paid-generation prompts until no unresolved answer can change the-Graph, Script, visual semantics, timing or generation inputs.--### 4. Read the craft and format guidance this program needs--1. Every craft file named in the first item of `../playbooks/index.md`'s required load order, in the- order it gives them.-2. Determine the format from the frozen intent, not from an example's directory name or a fixed type- list. If `../playbooks/index.md` has a matching format playbook, read it completely, including its- notes and footer, then read every additional craft file that footer names. If no format playbook- matches, follow the shared craft guidance and the open-ended intent analysis; do not invent a- type-specific checklist.--### Continuity is part of original authoring--This requirement applies even when there is no reference video. Before writing generation prompts,-establish one authoritative identity for every recurring person and product, one voice reference per-speaker, and one accepted image for each recurring location or physical setup. Reuse those references-across every take and derive alternate views from the accepted location image. Keep each continuous-shot group coherent in person, face, wardrobe, lighting, camera geometry, background, props and action-state. Do not ask a generator to recreate these facts from prose independently for each shot.--Use `../playbooks/craft/visual-continuity.md`, `../playbooks/craft/persona-and-audio.md` and-`../playbooks/craft/generated-dependencies.md` as the authority. The brief may leave visual details-unspecified; the Agent chooses them once and then treats the resulting anchors as fixed program facts.--### 5. Choose the packages--**Read now:** `../vocabulary.md` — which installed packages own the systems this program contains,-and whether any is genuinely missing. That file states why a system nobody inspected is one you are-about to invent, and this route is where that is easiest: there is no reference to contradict you.--For a proven gap, read `../local-author-package.md` completely and build the package.-Inspect the candidate packages now with `inspect_svml_vocabulary --package …` (without `--run`;-the Run is created in step 7). Apply the shared fit judgement, write the concise canonical-`.hypit/component-fit.json`, and checkpoint `vocabulary-checked` as `in_progress` before package-development. User-unspecified icon, shadow, radius and other micro-details are the Agent's design-space, not automatic gaps. For a proven gap, build the package and keep it ready for the-Run-scoped validation after all four source files exist. Do not treat an import or an empty package-as proof that the vocabulary gap is solved.--### 6. Write the Script--The Script comes first and the shots come out of it: a Segment is what one `whisperx:SemanticTake`-aligns one Take to, so how the Script is cut decides how many generations there are and where the-seams fall.--**Read now:** `../script-time.md` — where a Segment ends, where a forced seam goes, and why each-take's duration comes from `estimate:Speech` rather than from the duration the author asked for.--Hard layout gate: captioned speech must use `||` Cue breaks in the Script, normally every 3–4 spoken-words. A long Segment without breaks is not acceptable; it becomes one overflowing Cue.--Give every planned shot one job — hook, context, evidence, mechanism, reaction, payoff, transition,-or CTA. Delete shots with no distinct job.-Draft every Cue with `||` between complete Alignment Units, normally every 3–4 visible words. The-Run-scoped mechanical check happens after `build.svrun` is created in step 7.--### 7. Write the four sources--`main.svml`, `recipes.svs`, `build.svrun`, `hypit.runtime.json`. Write all four before building any-of them; the Runtime Profile is part of the deliverable.--**Read now:** `../authoring.md` — the syntax authority, the check set, and how an accepted Record is-reused in the Run Source. `../runtime.md` — how to author a Profile.--Author the Source before validating project-local packages: `package-ready` can only be completed-after `main.svml` and `build.svrun` compile a Graph that actually uses each package. Run the persisted,-Run-scoped gates before `hypit check`:+Inspect what actually exists:```bash-hypit-reference-video-tools inspect_svml_vocabulary --package <name> [--package …] --run build.svrun-hypit-reference-video-tools validate_local_author_packages --run build.svrun-hypit-reference-video-tools validate_script_cues --run build.svrun+hypit-reference-video-tools list_svml_packages+hypit-reference-video-tools inspect_svml_vocabulary --package <package>+hypit-reference-video-tools inspect_visual_schema```-The inspection completes `vocabulary-checked` only when the frozen component-fit file is still-valid.--`validate_local_author_packages` proves that every project-owned package under `packages/` has a real-Surface/Producer/Fragment and is used by the compiled Source Graph. `validate_script_cues` rejects-any Cue over four visible words; split it with `||` before continuing.+Use public Surfaces and Recipe fields. When no installed package can express an important role, read+`../local-author-package.md` and create a project-local package. Do not alter installed packages.-### 8. Check, then prove the graph traces+## 3. Author Source, Recipe and Run-`../authoring.md`'s check set proves the sources are legal, which is a narrower claim than the graph-tracing. `../preview.md` proves the Run traces before a Provider is reached. Neither is bounded by any-attempt ceiling: a graph that does not trace is work that is not done.+Write the smallest complete program. Every visible spoken passage uses short Cues separated by `||`,+normally 3–4 words. Apply the relevant craft references for coverage, captions, overlays, generated+dependencies, persona/audio and continuity.-### 9. Ask the check what to render, then render it--First run `layout_check --run <run>` and settle its candidates. **Read now:** `../layout-checks.md`.-The check is an assistant to judgement, not the source of truth: intentional crop, overlap or offset-may be accepted with a reason. Then ask the authoring check for the visual review plan.+Inspect the actual files directly:```bash-hypit-reference-video-tools authoring_check projects/<name>/build.svrun+hypit-reference-video-tools validate_local_author_packages --run ./build.svrun+hypit-reference-video-tools validate_script_cues --run ./build.svrun+hypit check ./build.svrun+hypit-reference-video-tools preview_check ./build.svrun+hypit-reference-video-tools layout_check --run ./build.svrun```-Its `plan` is the list: each entry an element and a word range, with the reason. Feed it to-`render_element --batch` — the program is drawn once and every entry is cut out of those frames.--Keep `.hypit/layout-check.json` with the renders. The reader still decides whether visible text or-marks fit the intent and whether any measured offset, overlap or bleed is deliberate.--**Read now:** `../element-review.md` — why each distinct visual declaration is read where it first appears.-`../preview.md` holds `render_element` itself.--Render the whole set before reading any of it. Studio is also free and is for the author to look at;-it is not the picture this round reads.--### 10. Read each element against what you asked for--**Read now:** `conformance-round.md` — what the element is judged against, the-`--intent-file` it is judged with, and what the reader is asked.--One subagent per picture where the harness has them, dispatched together, and never opened by you.+These commands are separate reports. Run the ones that answer a real question, repair confirmed+issues, and record a reason with `layout_accept` when a measured offset/overlap/overflow is intentional.-### 11. Repair against what the round returned+## 4. Read the visual result-Inside the two ceilings `../element-review.md` sets, in the dependency order it gives. A repair aimed-at something the round did not name is thrashing and earns no attempt.--### 12. Close the pre-Build work on the check+Use `authoring_check` to obtain a useful review plan, then render the named element/window locally:```bash-hypit-reference-video-tools authoring_check projects/<name>/build.svrun+hypit-reference-video-tools render_element ./build.svrun \+ --element <id> --tokens <from:to> --out ./review/<name>.mp4+hypit-reference-video-tools review_element --run ./build.svrun \+ --element <id> --tokens <from:to> --video ./review/<name>.mp4 \+ --intent-file ./review/<intent>.md```-**Done when:** `"passed": true`. It refuses while any drawing element has never been looked at, while-any stretch of the Script has nothing drawing a full frame over it, and while any timed picture is-configured to empty its window.--If the author requested batch variants, hand this checked Source to-`../variant-expansion/route.md` now. Do not Build the base or any variant unless finished media was-explicitly requested; the variant route owns its own aggregate and paid-build gates.--### 13. The Build--**Read now:** `../runtime.md` and `../studio-confirmation.md`. Before the paid gate, disclose the-selected Provider and credential source for every paid capability. Credentials must already be usable-from the completed environment gate; if one is missing or insufficient, stop and return to environment-setup. Then call the preview-mock realizer and-start Studio with its returned temporary `preview.svrun` (not the unresolved author Run). Show the-complete estimate-timed mock, return the exact URL printed by Studio, and obtain explicit acceptance-and cost approval. If the author declines, enter `../revision/route.md` and do not submit a Build. After-acceptance and paid Build submission, persist the accepted Build-Record Run, start Studio for that-Run, return its exact URL, and start the HyperFrames/final render concurrently.--Confirm credentials, the Runtime Profile, the installed packages, model limits, resolution and-Endpoint prerequisites. Run `doctor`, `check` and `plan`.--`plan` is what makes the cost sayable. **Say what the Build will cost and get the author's yes before-submitting it.** This is the one point on this route where their money is spent.--**Read now:** `../runtime.md` — submitting the Build, `status`, `inspect`, and `get` for the finished-Artifact.+Record out-of-band findings with `record_review`. Fix what conflicts with the brief; do not chase a+numeric score or repeat the same view merely to obtain a different answer.-### 14. Ask whether the package outlives the video+## 5. Build or hand off-If this job produced a project-local package, `../package-promotion.md` says how to judge whether it-should leave the project and what promoting it costs.+Read `../runtime.md` and `../studio-confirmation.md`. Use Studio to show the current Run and report its+exact URL. When the user wants generated media, run `hypit plan`, disclose cost and external Provider+selection, obtain approval, then run `hypit build` once.----+The Result from that Build is the durable answer. Give important Results/outputs human presentation+names. A later request edits the existing Source through `../revision/route.md`; it never edits the+rendered media.-When a step here grows past three sentences that are not links, its content belongs in a file of its-own, or in the shared file it should have linked.+For many variants, copy the accepted source project into ordinary independent directories and keep a+human-readable task list. Do not create an aggregate variant state system, and do not submit paid+Builds unless the author requested them.diff --git a/.agents/skills/hypit/references/playbooks/craft/b-roll.md b/.agents/skills/hypit/references/playbooks/craft/b-roll.mdindex 1343ecd1..463aa920 100644--- a/.agents/skills/hypit/references/playbooks/craft/b-roll.md+++ b/.agents/skills/hypit/references/playbooks/craft/b-roll.md@@ -107,7 +107,7 @@ only; narration, music, and effects remain explicit audio contributions.titles, arrows, comparisons, and cards on `typo:Track` or `media-track:Track`.- When exact UI or brand artwork matters, use the supplied asset as authored media rather than askinga generator to recreate it.-- A person-facing view and its device-facing reverse view must pass the hard geometry gate in+- A person-facing view and its device-facing reverse view must satisfy the explicit geometry rules in`visual-continuity.md`: opposing camera positions require different background sectors and differentdominant landmark sets. The same main background is an automatic rejection.- Follow `screen-demo.md` for context/proof pairs and physically possible screen orientation.diff --git a/.agents/skills/hypit/references/playbooks/craft/captions.md b/.agents/skills/hypit/references/playbooks/craft/captions.mdindex 7f575d50..9ca2d09c 100644--- a/.agents/skills/hypit/references/playbooks/craft/captions.md+++ b/.agents/skills/hypit/references/playbooks/craft/captions.md@@ -84,7 +84,7 @@ and twelve horizontal — which no JSON number can carry, so it travels as textspace. A single value is still written as one: `padding: "0"`.`cue-min-words` and `cue-max-words` are not Recipe properties. Cue length belongs to Script `||`-boundaries and the route's `validate_script_cues` gate.+boundaries and is reported directly by `validate_script_cues`.## Cue boundaries are marked in the Script, with `||`@@ -106,8 +106,8 @@ Treat roughly **3–4 spoken words per Cue as the hard default** (fewer for longdense designs). A longer Cue is an explicit exception that must be justified by the reference andverified in the rendered bounds; it is never the result of forgetting `||`.-The route's mechanical gate is stricter: `validate_script_cues --run <build.svrun>` rejects every Cue-over four visible words, including Dual Text display words. Split it with `||` between complete units.+`validate_script_cues --run <build.svrun>` reports every Cue over four visible words, including Dual+Text display words. Split it with `||` between complete units.Mark the breaks where the reference breaks. The observation for a shot says what is on screen atonce, and that is the Cue.diff --git a/.agents/skills/hypit/references/playbooks/craft/frame-coverage.md b/.agents/skills/hypit/references/playbooks/craft/frame-coverage.mdindex 0c71e534..be8534e3 100644--- a/.agents/skills/hypit/references/playbooks/craft/frame-coverage.md+++ b/.agents/skills/hypit/references/playbooks/craft/frame-coverage.md@@ -18,7 +18,7 @@ an interval inherits its edges whenever its length comes from something other th- a window derived from speech, which starts and stops with words and therefore excludes the silencearound and between them;- a still image has no duration-bearing timeline and must not receive a `playback` value; the- playback gate applies only to moving/generated media whose material can end before its window;+ playback check applies only to moving/generated media whose material can end before its window;- an insert, whose material ends where the generator stopped rather than where its window does — andthen draws nothing for the rest of it, because `playback` defaults to `once-start`, so whatever itwas covering is alone again mid-phrase. This is the one edge on the list a machine can find before a Build:diff --git a/.agents/skills/hypit/references/playbooks/craft/screen-demo.md b/.agents/skills/hypit/references/playbooks/craft/screen-demo.mdindex 5d7e5ea3..affcf526 100644--- a/.agents/skills/hypit/references/playbooks/craft/screen-demo.md+++ b/.agents/skills/hypit/references/playbooks/craft/screen-demo.md@@ -25,7 +25,7 @@ Define both views before generating either one:For example, a person-facing classroom view may show chairs behind the user, while the device-facingreverse view shows the lectern and blackboard behind the laptop. Writing only “the same classroom”-for both views is insufficient. Apply the complete gate in `visual-continuity.md`.+for both views is insufficient. Apply the complete geometry review in `visual-continuity.md`.## Keep the interface on the correct surfacediff --git a/.agents/skills/hypit/references/playbooks/craft/sfx.md b/.agents/skills/hypit/references/playbooks/craft/sfx.mdindex b3d5b627..87f26f57 100644--- a/.agents/skills/hypit/references/playbooks/craft/sfx.md+++ b/.agents/skills/hypit/references/playbooks/craft/sfx.md@@ -32,8 +32,8 @@ Declare the source, normalize it to audio-only `SynchronizedMedia`, and place it- Use `during={story.selection.NAME}` for a range, a Script Moment plus `for` for a point event, orexplicit `start`/`end` timing in the SemanticTrack frame domain — the last only for a program- with no speech to anchor to, the same gate `overlays.md` and `screen-demo.md` put on absolute- placement. Copying a video's own seconds into a `start=`/`end=` is the same defect+ with no speech to anchor to, under the same explicit-placement rule in `overlays.md` and `screen-demo.md`.+ Copying a video's own seconds into a `start=`/`end=` is the same defect`../../script-time.md` names for covering content.- Use `playback="once"` for a discrete effect, loop only for a genuinely repeating texture, andbounded pitch-preserving stretch only when the occupancy must fill an authored range.diff --git a/.agents/skills/hypit/references/playbooks/formats/mixcut.md b/.agents/skills/hypit/references/playbooks/formats/mixcut.mdindex 118610bb..939bfc77 100644--- a/.agents/skills/hypit/references/playbooks/formats/mixcut.md+++ b/.agents/skills/hypit/references/playbooks/formats/mixcut.md@@ -17,8 +17,8 @@ A crop of the same image is not a new beat.## Author the SVML shots-1. Generate or supply the exact first frame for each beat and pass every generated image through the- image review gate.+1. Generate or supply the exact first frame for each beat and review every generated image before it+ drives a video.2. Vendor `broll-v1.svs`; select one coherent material/edit language while varying the beat-specificEnglish `story` slot.3. Prefer `seedance:FrameVideo` when the first frame is the controlling fact. Usediff --git a/.agents/skills/hypit/references/playbooks/index.md b/.agents/skills/hypit/references/playbooks/index.mdindex ae45f470..c35906fd 100644--- a/.agents/skills/hypit/references/playbooks/index.md+++ b/.agents/skills/hypit/references/playbooks/index.md@@ -1,7 +1,7 @@# Hypit production playbooksUse these playbooks to author production decisions directly in `.svml`, `.svs`, and `.svrun`-sources. Each playbook names the SVML components, timing model, review gates, and reuse behavior+sources. Each playbook names the SVML components, timing model, review questions, and reuse behaviorneeded for that craft or format.## Required load orderdiff --git a/.agents/skills/hypit/references/preview-mock.md b/.agents/skills/hypit/references/preview-mock.mdindex f4171fb2..75b9e21b 100644--- a/.agents/skills/hypit/references/preview-mock.md+++ b/.agents/skills/hypit/references/preview-mock.md@@ -1,37 +1,16 @@-# Native preview mock realization+# Local preview material-Preview-only mock media belongs to `@hypit/preview-mock`; byte producers belong to-`@hypit/mock-media`, and generic graph inspection belongs to `@hypit/compiler-node`.+`@hypit/preview-mock` replaces unresolved image, video, audio and SemanticTake needs with local+stand-ins so the authored Graph can be viewed without paid generation.-The lifecycle is fixed:+The realizer writes a working directory for the Run under `.hypit/preview/<run-name>/`, containing a+native mock Run, a Studio-ready preview Run and ordinary local resources. Re-running the command+updates that working directory. It is disposable preview material, not Build history or authoritative+project state.-```text-build.svrun → compiler-node Author/Run Graph → preview-mock realization-→ mock.svrun + mock-media local Provider materialization-→ persisted content-addressed Artifacts + temporary .hypit/preview/<digest>/preview.svrun-→ Studio deterministic preview-```+The preview Run uses relative file Candidates and estimate timing. Mock media never enters Author+Source. Reference timing is used to select comparison windows, not to invent the preview's semantic+clock.-`realizePreviewMock({run, targets?, timing: "estimate"})` derives replacements from the compiled-Graph. It must not parse SVML dimensions, read a reference transcript, write a user Source, or emit-absolute-path `<file>` Candidates. The realizer first persists a native mock Run and then writes a-second temporary Run whose relative `<file>` Candidates point at the content-addressed results;-Studio can reopen that Run in a separate process without an in-memory attachment list or a-mock-media Provider (only local deterministic media tools may be enabled).--Mock mapping is ordinary graph substitution: image/video/audio BlobArtifact outputs use-`mock:image`, `mock:video`, and `mock:silence`; WhisperX SemanticTake outputs use the-`semantic-take-estimate` policy and preserve Narrative, Segment, Token, and Anchor identity.-Estimated timing is always `estimate:Speech`. Reference WhisperX remains evidence for shot/window-comparison only.--Geometry priority is Canvas width/height, then generation aspect-ratio, then the Canvas fallback.-Resolution labels such as `720p` and `2K` are not converted to pixels; contradictory geometry fails.-Mock Artifacts are content-addressed and cached by Author source digest, Run digest, target closure,-geometry policy, and timing mode. They never enter Author Source or coverage gates. Observers should-recognize mock regions as preview scaffolding and ignore them when assessing visual fidelity.--`reference-video-tools render_element` delegates to this realization, renders the complete program-once in Studio, cuts the requested window, writes a sidecar with `"timing_basis": "estimate"`, and-then invokes comparison. `make_placeholder`, hand-written SemanticTake JSON, hand-written `.media.json`,-SVML regex geometry extraction, and absolute-path Candidates are retired from the public route.+Use the exact `previewRun` path returned by the realizer. Do not reconstruct it from internal resource+names, and do not treat the presence of preview files as evidence that a paid Build ran.diff --git a/.agents/skills/hypit/references/preview.md b/.agents/skills/hypit/references/preview.mdindex 6ef27ca0..ce99b1ee 100644--- a/.agents/skills/hypit/references/preview.md+++ b/.agents/skills/hypit/references/preview.md@@ -1,179 +1,50 @@-# See what you authored, without paying+# See what you authored without paying-Revision work does not invoke the visual-review workflow described below. It may run deterministic-preview checks (and optionally render for artifact integrity), but never calls a VLM/observer; read-`revision/route.md` for that route.+Preview and inspection commands are independent. They do not write progress state or automatically+run one another.-`preview_check` and `render_element` advance the project's `.hypit/route-state.json` only after their-success predicates hold. After a new turn or interruption, read `recovery.md`, reconcile the state,-and resume from its `next_action`; do not rely on chat history.--Before preview, the command repeats `validate_local_author_packages` and `validate_script_cues`; a-failed package or Cue gate is a hard refusal and cannot be hidden by a passing Graph trace.--Three ways to look at a Source before a Provider is ever reached: prove the graph traces, render one-element to a still, and open the whole Run for a person. They answer different questions, and none of-them costs a generation.--## The graph traces before anybody opens it--`hypit check` proves a Source is legal; it proves nothing about whether the tracks it declares can-actually be built. A Run that does not trace fails the same way the moment the author opens Studio —-a new package with a bad schedule, a target that is not an output, a Film with no traceable-composition. Find that now, not on the author's screen:+## Trace the Run```bashhypit-reference-video-tools preview_check /path/to/project/build.svrun```-It takes the Run Source, not the Author SVML — Studio's unit of work is the Run, and it reads the-`.svml` back out of it.--The same check is also a bin of its own:--```bash-hypit-preview-check /path/to/project/build.svrun-```--When running from a contributor checkout, the exact launcher is-`node <checkout>/bin/hypit-preview-check.mjs /path/to/project/build.svrun`. The bare command above-is only the documented abbreviation; it is not a subcommand of `hypit`.--Prefer the subcommand. `--package-root <dir>` is needed only when the project has no `package.json`-or when an explicit package root is desired; it changes Host package lookup, not Source Workspace.-With a project-root `package.json`, omit it. The bare bin fixes the package root to the Run file's own-directory and takes no flags.--Either one refuses when the graph itself is wrong, and names what refused — a target that is not a-Film or Render output of the current SVML, a Film with no traceable composition, a Film with no-`SemanticTake` / Speech Track chain. This is not a guessing problem: the error says what is wrong, and-you repair that. A graph that does not trace is not done, and **every failure it reports must be-repaired until the check passes**, however many attempts that takes.--**One refusal is a pass, and it is the one you will see most.** A Source that declares its generation-rather than performing it leaves the closure waiting on Providers, and Studio requires the whole-closure before it will open. That is the expected state of a Source nobody has built yet, not a defect-in it. When every issue is `the Studio projection closure requires unresolved capabilities: …`, the-graph traced all the way to a Film and a semantic spine, and what remains is work a Provider has to-do. The subcommand returns `"sound": true` with the capabilities under `awaiting`; the bin prints-them and exits zero:--```-preview-check: the graph is sound, waiting on 6 capabilities.- - @hypit/seedance@1#seedance-2-mini- - @hypit/whisperx@1#whisperx-alignment- ...-```--Any other refusal means the graph is wrong and no amount of generation will fix it.--What this proves is that the graph is **wired**, not that every track **draws**. A Producer that-refuses the media kind it is handed is not caught here, because nothing is handed to it until the-Build runs.+`hypit check` proves Source legality; `preview_check` proves the Run can trace toward a Film. A report+whose only unresolved items are external Provider capabilities is a normal unbuilt project. Other+errors identify source or graph wiring to repair.-## Render one element, locally--One element — a new component, one caption system, one inserted card — is drawn without a paid-Provider by `render_element`. This is the picture to reach for whenever one element has to be looked-at rather than the whole program, and rendering the delivery to inspect a single piece is the waste it-exists to prevent. `element-review.md` says how many of these to draw and what to do with them; this-section owns the command.+## Render one element locally```bashhypit-reference-video-tools render_element /path/to/project/build.svrun \- --element <id> --segment <id>|--selection <id> --out <path>.mp4+ --element <id> --segment <id>|--selection <id>|--tokens <from:to> \+ --out <path>.mp4```-It compiles the Author/Run Graph once, delegates preview substitutions to `@hypit/preview-mock`,-materializes ordinary mock Artifacts through `@hypit/mock-media` into the temporary preview Store, and-drives the package's deterministic Producers from the generated `preview.svrun`. No mock file or-SemanticTake is hand-authored in the project.--`--element` takes the element's bare id — `captions`, the `id=` the Source wrote on the element. The-command appends the output suffix itself when it looks for the track, so `--element captions.track`-matches nothing: it refuses with `the Source places no element named captions.track` and lists the-bare ids that are placed.+The command realizes the Run with local preview media, renders once, and cuts the requested window.+It never writes mock Candidates into Author Source and never reaches a paid Provider. A batch file can+request several windows from the same realization.-`--segment` and `--selection` take a Script name, never a timestamp. `--tokens from:to` takes a-half-open range of the Script's own words, which is what a stretch nobody named is written as — a-caption Cue ends at a speaker change, so it has a range and no id. Without any of the three, the whole-program is drawn. An `--out` ending `.mp4`, `.mov` or `.webm` writes the stretch as a clip; any other-extension writes one still from the middle of it.+`--element` is the bare Source element id. The window is named in Script terms, never by copying a+reference timestamp. The returned sidecar records estimate timing.-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 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.+Use `layout_check` when actual browser geometry matters. Its overflow, overlap and offset candidates+are advisory measurements. Fix confirmed problems or annotate intentional geometry with+`layout_accept`; do not treat the report as an approval condition.-Each Segment's length comes from the Source's own `estimate:Speech`; `--reference-id` selects reference-evidence and comparison windows only. The sidecar records `"timing_basis": "estimate"`.+## Open the complete preview-Before reading the picture, run and settle `layout_check` and keep `.hypit/layout-check.json` with the-render. **Read now:** `layout-checks.md`. Its realized stable-state measurements are candidates for the-Agent to interpret, not automatic failures or instructions to edit. `layout_check` creates and records-the preview-mock Run and live Composition without encoding media; this later render reuses that same-upstream. The observer still confirms the look and the Agent decides whether any crop, offset or overlap-is intentional.--## Open the whole Run for a person--After the route's final check, read `studio-confirmation.md`: before a paid Build, start Hypit Studio-for the complete preview-mock Run and obtain the author's acceptance. After a revision, if Studio for-that Run is not already running, start it and give the author the URL; an existing Studio session-hot-reloads the changed Source. Stop the previous server before changing Studio startup parameters-(for example, selecting a different `--run`, `--workspace` or port) to avoid port conflicts; do not-restart merely because the same Run's SVML/SVS changed.+The preview realizer returns the exact `previewRun` path. Open that path rather than reconstructing a+directory name:```bash-cd /path/to/project-# Start Studio with the persisted previewRun returned by realizePreviewMock.-hypit-studio --run .hypit/preview/<digest>/preview.svrun --runtime hypit.runtime.json &+hypit-studio --run <previewRun> --runtime hypit.runtime.json```-`hypit-studio` is the standalone Studio launcher (`node <checkout>/bin/hypit-studio.mjs` in a-contributor checkout), not a `studio` subcommand of `hypit`.--If another Studio process is already using a different Run or startup parameters, stop that process-before launching this command; otherwise reuse the existing process and let its Source watcher reload.--Read the startup output for the chosen port and return the exact Studio URL to the author. `--run` is-required: Studio's unit of work is the Run-Source, and it reads the Author SVML back out of it. Pass `--runtime` only when the Author Source-reuses accepted Build records. `--workspace` selects the Source Workspace and defaults to the Run's-own directory, so pass it when the Run's relative Sources resolve against a different root.--Studio opens a Run whose material is satisfied. When a projection is missing it names the issue and-stops, so a Run that opens is a Run whose Tracks all resolved.--Contributor fixtures may provide a satisfied demonstration Run, but an ordinary installed-Distribution does not use its package directory as an author workspace.--## A timeline block retains its authored Selection--Studio keeps three stages of an item's time apart, and reading one for another misreads the program:--- the **semantic source** the author named — a Selection, Segment, Moment or Program, with its- identity and anchors on the Semantic Track;-- the **projection** of that source into frame space, after offset evaluation, clipping and frame- quantization. One resolved authored binding projects to one window;-- the **consumption** window the realized Track actually uses, which the projection does not have to- equal — a source-audio trim reads different samples than its target window, and a Ranking exposes- one outer window alongside its reveal phases.--A projection line connects a source to its realized window, and the projection view is read-only.-`../../../../docs/guide/studio-temporal-windows.md` is authoritative for what each stage carries.--When the executed lineage names a Selection or Moment, dragging the realized block may issue-`timeline.adjust` against that shared semantic identity. Script owns the inverse from semantic Anchor-identity back to markers, so every consumer follows the edit. This does not turn the block into a-Selection or infer a source from matching frames. Derived schedule phases and missing lineage remain-read-only.+Use the standalone Studio launcher. Reuse an existing process for the same Run and startup parameters;+stop it before changing those parameters. Report the exact URL printed after Studio starts.-Studio is a browser preview **for a person to look at**. It is not a source of images for an-automated comparison — that is what the local still render above is for.+Studio is for a person to inspect. Automated comparison uses `render_element` plus+`compare_reconstruction` or `review_element`.-`../../../../docs/quickstart/preview.md` is authoritative.+`../../../../docs/quickstart/preview.md` is authoritative for Studio behavior.diff --git a/.agents/skills/hypit/references/quickstart.md b/.agents/skills/hypit/references/quickstart.mdindex 708f4c3f..f1321ad0 100644--- a/.agents/skills/hypit/references/quickstart.md+++ b/.agents/skills/hypit/references/quickstart.md@@ -6,39 +6,21 @@ Published docs and installed package declarations are authoritative:|---|---|| Script semantics | `../../../../docs/quickstart/script.md` || SVS Recipes | `../../../../docs/quickstart/styles.md` |-| Media and Seedance | `../../../../docs/quickstart/generation.md` |-| Reusable Seedance Prompt Kits | the installed `@hypit/seedance-kits` README and selected Kit |-| Normalization, alignment and SemanticTrack assembly | `../../../../docs/quickstart/timing.md` |-| Caption, Media, Text, Audio Tracks | `../../../../docs/quickstart/tracks.md` and installed package READMEs |+| Media and generation | `../../../../docs/quickstart/generation.md` |+| Timing and SemanticTrack assembly | `../../../../docs/quickstart/timing.md` |+| Caption, Media, Text and Audio Tracks | `../../../../docs/quickstart/tracks.md` and package READMEs || Film and rendering | `../../../../docs/quickstart/composition.md` |-| Run Source, durable Runtime, Builds, retrieval, and reuse | `../../../../docs/quickstart/run.md` and `runtime.md` |+| Run, Runtime, Build, Result and reuse | `../../../../docs/quickstart/run.md` and `runtime.md` |-Canonical production path:+Canonical path:-`Script → estimate:Speech/text → Seedance or supplied media → pipeline:Normalize → whisperx:SemanticTake → speech:Track → peer Caption/Media/Typography/Audio Tracks → Film → render:Video`.+`Script → estimate:Speech/text → generated or supplied media → normalization → SemanticTake → speech:Track → peer visual/audio Tracks → Film → render:Video`.-Preview path uses the same Graph with `@hypit/preview-mock`: image/video/audio outputs are replaced-by ordinary mock Artifacts, and WhisperX `SemanticTake` is replaced by `semantic-take-estimate` using-`estimate:Speech`. This preview substitution never enters Author Source and is not final timing evidence.+Preview uses the same Graph with local mock media and estimate timing. It never edits Author Source and+never submits paid generation.-Use explicit imports, exact fonts, Canvas/Frames, the SemanticTrack, Targets, and Runtime-authority. There is no implicit cache; reuse is explicit with `build-record` + `satisfy`.+Use explicit imports, exact fonts, Canvas/Frames, SemanticTrack, Targets and Runtime authority. Reuse+is explicit through a named Result output referenced by `build-record` and `satisfy`.-`speech:Take source={...}` assembles one aligned `whisperx:SemanticTake` into the Track, in program-order. The take that speaks a Segment is the take that draws it, so that one value carries the-program time, the speech and the picture together; peer Media Tracks put inserts over it.--For a program with no spoken words, keep the `whisperx:SemanticTake` and `speech:Track` declarations —-the SemanticTrack is the frame domain every `start`/`end` window resolves into — satisfy-`<track>.semantic` through `.svrun` `build-record` and `satisfy`, keep `<track>.visual` and-`<track>.audio` out of the Film so the alignment goes unreached, and omit the Caption components.--For execution, preserve the full lifecycle: select the Profile, inspect the frozen plan, run-`runtime up` when preflight is not ready, submit a fresh automatically identified Build, inspect its-accepted Records, retrieve Artifacts, and declare any reuse explicitly in a new Run Source.--Both production routes expose current progress in `.hypit/route-state.json` and preserve each-execution under `.hypit/routes/<route-id>/`; after an interruption, follow-`recovery.md` and reconcile before resuming. Before `preview_check`, run-`inspect_svml_vocabulary --run`, `validate_local_author_packages --run` and-`validate_script_cues --run`; the preview and final checks repeat these gates.+Inspect the files and current Result directly after interruption. There is no route cursor to recover.+Do not submit a second paid Build when the needed Result already exists.diff --git a/.agents/skills/hypit/references/reconstruction/comparison-round.md b/.agents/skills/hypit/references/reconstruction/comparison-round.mdindex 99072ed3..a73c83ce 100644--- a/.agents/skills/hypit/references/reconstruction/comparison-round.md+++ b/.agents/skills/hypit/references/reconstruction/comparison-round.md@@ -1,8 +1,8 @@# Comparing what was built against the reference-Completed comparisons are durable evidence in `comparisons.jsonl` and the route snapshot. After a-context boundary, run `route_state --action reconcile` before comparing again; answered pairs are-reused and are not sent to the observer twice.+Completed comparisons are ordinary content in `comparisons.jsonl`. After an interruption, inspect+that log and the current render directly. Do not repeat paid generation; make another local comparison+only when the current task calls for a new observation.**Read `../element-review.md` first.** It owns the round this file sits inside: one element at a time,render what the Source configures, realize preview mocks for what a Build has not made, one round, two attempt ceilings,@@ -116,10 +116,10 @@ hypit-reference-video-tools compare_reconstruction --reference-id <id> --run <ruThis fallback compares the visible state at the range midpoint and does not claim anything aboutmotion. The judgement for a normal window still comes from the reference observation, never fromlooking at your own render and deciding that it does not move. If a longer clip returns-`INVALID_ARGUMENT`, record the complete error and treat it as a gate/provider defect rather than+`INVALID_ARGUMENT`, record the complete error and treat it as a comparison/provider defect rather thansilently switching evidence modes.-Pass `--element <id>` every time so the gate credits the comparison to that element.+Pass `--element <id>` every time so the comparison record names the element it assessed.## One observer reads the reference, and it is the one the reference was prepared withdiff --git a/.agents/skills/hypit/references/reconstruction/final-sources.md b/.agents/skills/hypit/references/reconstruction/final-sources.mdindex 78fb151c..a0ef083d 100644--- a/.agents/skills/hypit/references/reconstruction/final-sources.md+++ b/.agents/skills/hypit/references/reconstruction/final-sources.md@@ -37,7 +37,7 @@ where a literal read off the old reference would not.Then check and wire, in that order. `../authoring.md` holds the check set — all four commands, notonly the Author Source — and `../preview.md` holds the graph check that comes after it. A Source that-passes every check can still declare a Run that does not trace, and neither gate is bounded by the+passes every check can still declare a Run that does not trace, and neither check is bounded by theround's two-attempt ceiling: a graph that does not trace is not a difference to weigh, it is work thatis not done.diff --git a/.agents/skills/hypit/references/reconstruction/route.md b/.agents/skills/hypit/references/reconstruction/route.mdindex 02029278..ebaf61f7 100644--- a/.agents/skills/hypit/references/reconstruction/route.md+++ b/.agents/skills/hypit/references/reconstruction/route.md@@ -1,463 +1,94 @@-# Reference-video reconstruction route+# Reference-video reconstruction-Read a step, do it, read the next one. Each step names the files it needs; read those at that step.+Use this workflow whenever a video file or link is the thing to reproduce, including an initial+presenter/product/brand adaptation requested together with the reference.-## What this route delivers+## 1. Prepare and observe the reference-The complete environment is the hard gate. At route entry, read `../environment.md` completely, then-finish its checklist through the environment steps: Distribution, project boundary, credentials,-Runtime Profile, all selected managed programs, and health checks. The local WhisperX Endpoint is-mandatory and must report `Ready whisperx` (or an equivalent successful probe). Do not enter the-observation or authoring steps while any environment item is missing, installing, unhealthy, or-unconfirmed.--The components the video needs, `main.svml`, `recipes.svs`, `build.svrun`, and the Runtime Profile-that binds what they demand — **wired**, meaning `preview_check` proves every track the sources-declare traces to the Film. Every generation the Source declares is declared rather than performed:-no Build is submitted, and no video generation, speech synthesis, alignment or final render runs.-Those belong to the Build the author starts deliberately, after reading what was written.--Seeing the reconstruction is what that Build is for. What is settled here is that the graph traces,-which is the part a Build cannot repair. The route then pauses at the Studio confirmation handoff-before any paid Build; after explicit acceptance it may proceed with the Runtime Build lifecycle.-Once the paid Build has produced the accepted full video, any new natural-language change starts-`../revision/route.md` from that completed Run; never continue this creation route or edit the rendered file.--If the project is already complete and the author asks for a natural-language change, stop following-this creation route and read `../revision/route.md`. Revision edits Source/Recipe/Run and reruns deterministic-gates; it does not invoke a VLM or visual observer.--One exception, because it is not a generation of the video: a component's own surface — the field its-elements are drawn on — is produced while the package is authored, with `hypit image`, and committed-inside the package. `../playbooks/craft/generated-dependencies.md` draws that line.--**That exception covers the component's surface and nothing else.** Every other picture the video-shows — the inner picture of a card, an inserted screenshot, a thumbnail, a product shot, a logo-wall, a phone or monitor's content — is the video's content, and content is declared in `main.svml`-as a generation:--```svml-<copy:Value id="meme-look">A screenshot of a vertical social-media post…</copy:Value>-<gpt:Image id="meme-shot" prompt={meme-look} aspect-ratio="9:16" resolution="2K"/>-```--Writing `<media:Image src="./assets/meme.png"/>` instead spends money this route does not spend, and-loses the thing that mattered: the prompt. A declared generation carries its own description in the-Source, so it can be reread, corrected and rebuilt; a PNG on disk carries nothing, and the next-person has to invent the prompt again. `media:Image` is for material the author supplied.--The reference video itself is never supplied project media. It is observation/comparison evidence only.-Never copy it into project assets or wire its path into `media:Video`, `asset:Video`, a Media Track,-the Film, or a Run Target. Every visible shot must be newly authored as a generated take or an-explicitly author-supplied replacement asset. A project that directly plays the reference is invalid-and must be rejected before preview or Build.--Reference observation is part of the work and is expected to cost what it costs.--## The video is the whole request--The author gives one thing: a video, as a path to a file or as a link to one. A link — TikTok,-YouTube, Instagram, Bilibili — is fetched by `prepare_reference` before anything else runs, with the-`yt-dlp` pinned under `services/yt-dlp` and run through `uv`, and every step after that reads the downloaded file without knowing it was ever a link. The-download is cached by the link, so a route restarted after an interruption reaches the same bytes and-therefore the same reference rather than paying for its observations twice. The working directory, the project name, which-packages to use and where the result goes are yours to decide. Ask the author about the video and-nothing else — what it is for, who is in it, what it should say. Those answers describe the result-they want; record them and apply them at step 23. Never interrupt to ask which generator, which-package, which directory, or whether to proceed.--The author often wants the result to differ from the reference: their presenter, their product,-their brand. **Reconstruct the reference as it is anyway, all of it, and change it afterwards.** The-reconstruction is checkable only while it claims to reproduce the video that was observed: the-observations describe the reference and are cached, and `compare_reconstruction` judges a rendered-element against it. Author the change in early and the evidence describes one video while the sources-describe another.--If that same initial request also asks for many variants, step 23 still applies the requested-presenter/product/brand adaptation inside reconstruction. After step 24 passes, hand the adapted base-to `../variant-expansion/route.md`. Do not route the initial adaptation through Revision.--## Checkpoint and recovery--Start the project snapshot before the first route decision:--```bash-hypit-reference-video-tools route_state --action start --project-root <project> \- --route reconstruction-```--The route tools update machine-owned stages after successful checks, renders, and comparisons. After-reference/observer decisions, Source edits, repairs, or Build actions, write an explicit checkpoint.-After any interruption or context compaction, read `../recovery.md`, run `route_state --action-reconcile --project-root <project>`, and resume only from its `next_action`. The snapshot is evidence-of intent; files and check results remain the authority.--### Durable stage map--| state | update / completion predicate | recovery entry |-| --- | --- | --- |-| `environment` | explicit checkpoint after Distribution, project, credentials, Runtime Profile, selected programs and all health checks are ready | `hypit paths --json` / `hypit runtime up` |-| `reference-prepared` | checkpoint after `prepare_reference` reports ready `state.json` | `prepare_reference` or `route_state reconcile` |-| `reference-observed` | explicit observer checkpoint; all required observation answers are complete | `observe_reference` / `record_observation` |-| `vocabulary-checked` | Run-scoped vocabulary inspection and the frozen `.hypit/component-fit.json` are both persisted | `inspect_svml_vocabulary --run <run>` |-| `source-authored` | explicit checkpoint naming `main.svml` (and Recipe/Run when available) | `hypit check <run>` |-| `package-ready` | every project-owned package under `packages/` has a real Surface/Producer/Fragment and is used by the compiled Graph | `validate_local_author_packages --run <run>` |-| `script-checked` | every caption Cue has at most four visible words | `validate_script_cues --run <run>` |-| `graph-checked` | `preview_check` returns `sound: true` after package and Cue gates | `preview_check <run>` |-| `layout-checked` | `layout_check` executed and every candidate was repaired or explicitly accepted | `layout_check --run <run>` / `layout_accept` |-| `review-planned` | `reconstruction_check` writes a plan | `reconstruction_check <run>` |-| `preview-rendered` | render output and timing sidecar both exist | `render_element --batch <round.json>` |-| `comparison-complete` | comparison log contains a complete record for the planned element | `compare_reconstruction` / `record_observation` |-| `repairs-complete` | explicit checkpoint after applying comparison findings | edit Source, then rerun the checks |-| `final-checked` | final `reconstruction_check` returns `passed: true` after all gates | `reconstruction_check <run>` |-| `build-complete` | explicit checkpoint after the durable Build record is accepted | `hypit build` (confirm cost first) |--The numeric `current_step` is only a cursor; `reconcile` starts at the first unmet predicate. It never-infers the observer's creative judgement or a repair from file presence alone.-------## Phase 0 — Before any command--### 1. Select the Distribution--```bash-hypit paths --json-```--**Read now:** `../environment.md` — the three independent places, Distribution selection, the-prohibition on a registry install, the launcher substitution rule that makes every-`hypit-reference-video-tools` string below resolvable in a checkout, and the rule that commands-sharing reference state run from the same working directory.--**Done when:** an installed CLI or a contributor checkout is selected. If neither is available,-report that no runnable Hypit Distribution is present and stop.--### 2. Choose the project directory--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 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.--**Read now:** `../runtime.md` — the hard boundary between a project and a Distribution.--### 3. Load credentials--Check `<checkout-root>/.env` first, then `<project-root>/.env` if present, and load each before-credential probing (the project file overrides duplicate names):--```bash-set -a-[ ! -f <checkout-root>/.env ] || . <checkout-root>/.env-[ ! -f <project-root>/.env ] || . <project-root>/.env-set +a-```--If the loaded variables satisfy the selected observer/Provider, continue without asking the author-for them again. HypiHub OAuth is the default; only configure an author-owned key when explicitly requested.--**Read now:** `../credentials.md` — which variables each Provider needs. A variable a Provider needs-and this machine does not hold is named. If HypiHub OAuth is not configured, complete that login before-continuing; do not use `agent` to bypass the environment gate.--Create the project's `hypit.runtime.json` now with at least the local media and WhisperX endpoints,-then select and start it before reference preparation:--```bash-hypit runtime use hypit.runtime.json-hypit runtime up-```--Step 15 completes the same Profile with every capability reached by the authored Source; it does not-create the first Profile after transcription has already needed one. Checkpoint `environment` only-after this preliminary Profile and the selected credentials are ready.--### 4. Read the observer guidance--**Read now:** `observers.md`, down to and including "Say which path is running" — the cost of each-observer, the credential decision table, the disclosure the author is owed, and the rule that one-reference has one observer for its whole life.--### 5. Use the default Gemini observer--`observers.md`'s "Choosing" section holds the credential checks and disclosure. Environment setup has-already completed the credential flow. Use `gemini` by default; use `agent` only after an explicit user-request.--### 6. Say which observer is reading--One line, before any evidence starts.-------## Phase 1 — Evidence, with reading alongside--### 7. List installed vocabulary--```bash-hypit-reference-video-tools list_svml_packages-```--It resolves project-owned packages from the working directory (or the directory named by-`--package-root`) and resolves installed `@hypit/*` packages from the active Hypit Distribution-fallback. `--package-root` never replaces that Distribution root, so no `npm link` or package self-link-is needed. This is instant and may run before or during the sweep.--### 8. Prepare the reference--```bash-hypit-reference-video-tools prepare_reference --video-path <path or link> --observer gemini|agent-```--`--video-path` takes a link as readily as a path. The result names the link it fetched under-`source_url`, which is the only record of which video was reconstructed once the bytes are on disk.--Verify the WhisperX service answered its health probe before running this — a first start can spend-several minutes loading the model. `../environment.md` says how; `../host-setup.md` covers the-failure branches.--**Read now:** `evidence.md` — what the four whole-reference observations cover, what `transcript` is-and how to recover it when it reports `status: "unavailable"`, and the `--redo` values.--**Done when:** the four whole-reference observations and `transcript` exist. On the `agent` observer-they come back as `pending_observations` for you to answer with `record_observation`; answer those-four first, because `observe_reference` quotes them into every shot's question and refuses to run-until they exist.--### 9. Run the full sweep, in the background+Read `../environment.md`, `credentials.md` and `observers.md`. Ask once whether Gemini or the calling+agent should read the reference, then run:```bash+hypit-reference-video-tools prepare_reference --video-path <path-or-link> --observer <gemini|agent>hypit-reference-video-tools observe_reference --reference-id <reference-id>```-**Start this before step 10 and read while it runs.** Its prompts are fixed and nothing in step 10-changes what they ask. Reading first and observing afterwards makes the same run several minutes-longer for nothing.--On the `agent` observer, give each task its own subagent where the harness has them and run a pass-together; that is what makes the sweep parallel. Answering everything one call listed is not the end-of it — the sweep ends when `pending_observations` and `unresolved` are both empty.--### 10. Read the route's craft, while the sweep runs--Read completely, in this order — a reconstruction needs to know what a picture *is* before what one-generation owes another:--1. `continuity.md` — shot, overlay, B-roll, speaker, product and persistent-system rules.-2. Every craft file named in the first item of `../playbooks/index.md`'s required load order, in the- order it gives them. That page owns the list; restating it here is how a required file once became- reachable from one route and invisible to the other.-3. `../script-time.md` — what a Segment is bound to, and why never a number of seconds.-4. `../vocabulary.md` — how a package is chosen: enumerate every system before naming one, reuse- before compose before declaring a gap, and what a real gap obliges.-5. `vocabulary.md` — what the reference evidence adds to that: enumerating from the observations, and- measuring an appearance value rather than choosing it.--Do not skip one because the task looks like a familiar video format.-------## Phase 2 — Interpret the evidence--### 11. Collect the sweep and inspect what failed--`unresolved` lists observations that failed outright. A complete observation that says "unclear" is-still complete. Be most suspicious of anything an observation asserts about change over time.-`evidence.md` says why and what to do.--### 12. Settle conflicts with narrow questions--`evidence.md`'s "Narrow questions" section holds the command, what a question may ask, and why-re-observing a whole shot to correct one is the wrong repair.--**Done when:** every appearance value that changes what the viewer sees is measured rather than-defaulted, and every conflict between observations is settled.--### 13. Inspect candidate packages--```bash-hypit-reference-video-tools inspect_svml_vocabulary --package @hypit/<name> [--package …]-```--Enumerate the systems from the observations, then inspect a candidate for each. A system you never-inspected is a system you are about to invent. Apply `../vocabulary.md`'s shared fit judgement, write-the concise canonical `.hypit/component-fit.json`, and checkpoint `vocabulary-checked` as-`in_progress` before developing any gap. A small accepted variance belongs in that file; it is not a-reason to copy or modify an installed package.--### 14. Develop a project-local package, only for a proven gap--**Read now:** `../local-author-package.md`, completely.--**Done when:** the package has a real Manifest, Types, Producers, Validators, Surface, decoder,-Fragment, activation, README and preview, and `validate_local_author_packages --run <build.svrun>`-reports that the Source imports and compiled Graph uses it. A component that merely loads is not done.-If no gap remains, remove unused project-owned package directories.-------## Phase 3 — Author, check, wire--### 15. Write the sources and complete the Runtime Profile--Write `main.svml`, `recipes.svs` and `build.svrun`, then extend the existing `hypit.runtime.json` with-every capability those Sources reach. The Runtime Profile is part of the deliverable: without it the-first thing the author meets is `RUNTIME_CAPABILITY_UNBOUND`.--Author the Source before validating project-local packages: `package-ready` can only be completed-after `main.svml` and `build.svrun` compile a Graph that actually uses each package. Now persist the-Run-scoped half of the frozen vocabulary decision. This completes-`vocabulary-checked` only when `.hypit/component-fit.json` remains valid:--```bash-hypit-reference-video-tools inspect_svml_vocabulary --package @hypit/<name> [--package …] \- --run build.svrun-```--**Read now:**--- `final-sources.md` — Segment boundaries, the forced seam, and take durations from `estimate:Speech`.-- `../script-time.md` and `../playbooks/craft/captions.md` — every captioned passage must be split- with `||`, normally every 3–4 spoken words; do not rely on renderer wrapping.-- `../authoring.md` — never invent a component, attribute, child, port, Recipe property or literal- value, and how an accepted Record is reused in the Run Source.-- `../playbooks/craft/captions.md` — Cue breaks, the Recipe keys, and what recomputes when speech- changes.-- `../playbooks/craft/persona-and-audio.md` — one voice sample per person, and the identity anchors- that make step 23 cheap.-- `../playbooks/index.md` and the craft files it names for the systems this reference actually- contains. Those conditions can only be evaluated now, with the evidence in.--Do not author one source fragment per shot.-Before `hypit check`, run `validate_script_cues --run <build.svrun>`; every Cue must contain at most-four visible words and use `||` between complete Alignment Units.--### 16. Check every source, then prove the graph traces--One command does both: it checks every Source the Run reaches — the Run, the Author it names, the-Recipe sheets and kits the Author imports — and then proves the graph traces. A Source that does not-check is refused before tracing, with the file and position.--```bash-hypit-reference-video-tools preview_check /path/to/project/build.svrun-```--**Read now:** `../preview.md`, which says which refusal is the pass. A Source that declares its-generations rather than performing them is the state every reconstruction is in when its sources are-first written. This gate is not bounded by the round's attempt ceilings.--### 17. Create the comparison plan--Run `layout_check --run <run>` first and settle its candidates. **Read now:** `../layout-checks.md`.-Mechanical measurements only point the Agent toward relationships worth judging; the reference and-design intent decide whether any crop, offset or overlap is a problem. Then run-`reconstruction_check` once to persist the element/window plan. Do not invent a render list from-the Source; the check's plan is the durable handoff to the comparison round.-----+For the agent observer, answer every returned task with `record_observation`. Prepared clips, frames,+storyboard, transcript and observations are the actual working material under+`.hypit/reference-video-tools/`; no route snapshot is created around them.-## Phase 4 — The comparison round+Read `evidence.md`, `continuity.md` and the relevant production craft. Separate:-### 18. Read the round+- the base scene from covering overlays;+- an inset frame from the picture moving inside it;+- camera motion from motion inside the scene;+- persistent systems from one-off elements;+- spoken timing from visual shot boundaries.-**Read now:** `../element-review.md`, then `comparison-round.md`, as soon as the sources place an-element — that is the first moment the round has something to render.+## 2. Choose packages and author the faithful base-### 19. Ask the check what to render, then render it--`reconstruction_check` returns a `plan`: each entry an element and a word range, with the reason it-earned a look, and a picture path it will be rendered to. That is the round — it is not yours to work-out from the Source.--Its output is already a `render_element --batch` file: `renders` is in it. So:+Inspect installed vocabulary instead of guessing:```bash-hypit-reference-video-tools reconstruction_check projects/<name>/build.svrun --reference-id <id> > round.json-hypit-reference-video-tools render_element projects/<name>/build.svrun --batch round.json --reference-id <id>+hypit-reference-video-tools list_svml_packages+hypit-reference-video-tools inspect_svml_vocabulary --package <package>+hypit-reference-video-tools inspect_visual_schema```-`comparison-round.md` uses preview-mock estimate timing; `--reference-id` selects comparison evidence, not mock timing.-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.+Read `vocabulary.md` and `final-sources.md`. Reuse public Surfaces when they fit. Use+`../local-author-package.md` only for a genuine missing capability. Never copy or edit an installed+package.-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.+Write the faithful base before applying an initial requested presenter/product/brand substitution.+Short caption Cues use `||`, normally every 3–4 spoken words. Preserve shot coverage, overlay+continuity, picture-within-picture geometry and generated dependency ordering in Source/Recipe/Run.-### 20. Send every comparison at once+## 3. Inspect the authored program-The same file is a `compare_reconstruction --batch` file too — `comparisons` is in it, and each entry-carries `--element` already, so step 22 can credit it. Nothing is written between the two commands.+Run the direct reports that answer the current question:```bash-hypit-reference-video-tools compare_reconstruction --reference-id <id> --batch round.json+hypit-reference-video-tools validate_local_author_packages --run ./build.svrun+hypit-reference-video-tools validate_script_cues --run ./build.svrun+hypit check ./build.svrun+hypit-reference-video-tools preview_check ./build.svrun+hypit-reference-video-tools layout_check --run ./build.svrun```-### 21. Repair against the differences that round returned+These are independent reports. Layout output is advisory; repair a real issue or annotate intentional+geometry with `layout_accept` and a reason.-Within the two ceilings `../element-review.md` sets. Then return to step 19 for the next element.+## 4. Compare actual visual elements-### 22. Close the route on the check+Read `comparison-round.md`. Render one named element over a Script window, then compare the render to+the corresponding reference stretch:```bash-hypit-reference-video-tools reconstruction_check projects/<name>/build.svrun+hypit-reference-video-tools render_element ./build.svrun \+ --element <id> --segment <segment> --reference-id <reference-id> \+ --out ./review/<element>.mp4+hypit-reference-video-tools compare_reconstruction \+ --reference-id <reference-id> --run ./build.svrun --segment <segment> \+ --video ./review/<element>.mp4 --element <id>```-It names each element that has never been compared and the command that compares it, and reports-`"passed": false` until none are left. It asks for participation rather than convergence — the round-is deliberately bounded and may stop with visible differences remaining — so an element compared once-and stopped at its ceiling passes, and an element nobody looked at does not. It also refuses a-`playback` left at its default — `../playbooks/craft/generated-dependencies.md` says what to set — and-an uncovered stretch of the Script, and reports every Frame reaching past the Canvas.--How it picks a reference: exactly one prepared → it uses that one; several → it demands-`--reference-id <id>` and refuses without it; none → it refuses and tells you to run-`prepare_reference`.--A comparison run without `--element` is credited to no element, and a misspelled `--element` credits-nothing either — it reports logged element names that do not exist in the Source. Which package draws-an element makes no difference: a Track from installed vocabulary carries authored values exactly as-a project-local one does, and `render_element` stands in for the speech. A project that places no-drawing element passes with nothing to require.--**Done when:** `"passed": true`.--### 23. Apply the author's requested change--Read what you wrote and change it to what they asked for at the start. The identity of each recurring-person and product is already a single anchor, because `../playbooks/craft/persona-and-audio.md` and-`../playbooks/craft/visual-continuity.md` required that while you were writing.--If the author requests a change after seeing the preview, leave this route and follow-`../revision/route.md`; do not pay or Build a source that has not passed the final deterministic gate.--### 24. Re-run the final deterministic gate--After any requested change (or when there was none), run `reconstruction_check` again and require-`passed: true`. This is the last source/graph gate before the paid handoff.+Use a still only when both sides are actually still. For an out-of-band agent observation, close the+returned comparison id with `record_observation`. Each explicit comparison is new; no file digest+silently replaces it with an older answer.-If the initial request includes batch variants, enter `../variant-expansion/route.md` from this-checked, adapted base now. The variant route defaults to source delivery; do not Build the base first-unless the author explicitly requested it.+Use `reconstruction_check` as a summary of unreviewed elements, coverage and playback concerns. It is+not project state and does not prevent Build submission. Repair differences that matter to the+reference and the requested adaptation, then rerun only the affected inspection or comparison.-### 25. Studio confirmation and paid handoff+## 5. Build and deliver-**Read now:** `../runtime.md` and `../studio-confirmation.md`. Before realizing the preview-mock Run,-disclose the selected Provider and credential source for every paid capability. Credentials must already-be usable from the completed environment gate; if not, stop and return to environment setup. Realize the preview-mock Run first, then start Studio with-the returned temporary `preview.svrun` (never the original unresolved Run), show the complete-estimate-timed mock, return the exact URL printed by Studio, and obtain explicit acceptance and cost approval. If the author declines, enter-`../revision/route.md` and do not Build. Once accepted, submit the paid Build and persist its accepted-Build-Record Run; start Studio for that accepted Run, return the exact URL printed by Studio, while-the HyperFrames/final render proceeds concurrently.+Read `../runtime.md` and `../studio-confirmation.md`. Show the current Run in Studio and report its+exact URL. Before generation, run `hypit plan`, disclose cost and selected external services, obtain+approval, then run `hypit build` once.-After acceptance, continue with `../runtime.md` for the approved paid Build and retrieval lifecycle.+The resulting project-owned Result is what that Build produced. Name important Results/outputs for+human retrieval. A later natural-language change follows `../revision/route.md` and edits Source,+Recipe or Run—not the generated video.-When the accepted full video is available, a later request such as moving an element or raising-captions is a new revision request. Start `revision_state` against the accepted-material Run and-follow `../revision/route.md`; after its deterministic gates, Studio may hot-reload (or be started for the-Run if none is running), but Revision still performs no VLM/visual review.+For many variants, copy the accepted project into independent directories and maintain an explicit+task list. Do not create variant state, aggregate completion records or hidden recovery history.diff --git a/.agents/skills/hypit/references/recovery.md b/.agents/skills/hypit/references/recovery.mddeleted file mode 100644index 0e7c78aa..00000000--- a/.agents/skills/hypit/references/recovery.md+++ /dev/null@@ -1,99 +0,0 @@-# Recovering a Hypit route after interruption or context compaction--Treat every new turn as a possible context boundary. Do not continue from the chat transcript alone.-The project's `.hypit/route-state.json` is the current route view. Its `route_id` binds it to the-execution history at `.hypit/routes/<route-id>/state.json`; the durable source of truth is that-execution state plus the artifacts and checks it points to. Check reports are content-addressed under-`.hypit/evidence/<digest>/`; same-named files directly under `.hypit/` are compatibility/current views,-not historical evidence.--## Recovery sequence--1. Read `../SKILL.md`.-2. Read the route file that matches the project.-3. Read `<project>/.hypit/route-state.json` with `route_state --action read`.-4. Inspect `git status`, the recorded artifacts, and the last command.-5. Run `route_state --action reconcile --project-root <project>` (and inspect its conflict report).-6. Re-run the first unmet check or idempotent route command named by `next_action`; package and Cue-gates must be rerun before any preview or final check.-7. Continue only after the state reports the next step explicitly.--If the snapshot is missing, start one before continuing:--```bash-hypit-reference-video-tools route_state --action start \- --project-root <project> --route reconstruction|description|variant|variant-package --run <run>-```--Use `--route description` for original-authoring and `--route reconstruction` for reference-video-work. A project has one active route; a route mismatch is an error rather than an invitation to merge-two histories.-`variant_init` normally starts `variant`; the main agent starts `variant-package` explicitly for a-staging project after a vocabulary gap has been proven.--For batch variants, do not look for `.hypit/route-state.json` on the base and assume it names the-batch. Read `variant-expansion/route.md`, then discover the sibling batch from the base locator:--```bash-hypit-reference-video-tools variant_state --action discover --project-root <base>-hypit-reference-video-tools variant_state --action reconcile --project-root <base> --batch-id <id>-```--Read the returned canonical `<batch>/.hypit/variant-expansion-state.json`, reconcile every unfinished-`variant-package` staging route and `variant` project route, inspect conflicts, and execute only the-first unmet `next_action`. `variant_init` reuses matching initialized copies and refuses conflicting-destinations. A component/package digest change, missing inspection evidence or file outside-`allowed_changes` is a conflict, not permission to overwrite it.--That rule applies while the child is still in its initial `variant` route. Once a completed child has-started a user-requested Revision with `parent_route: variant`, its original `allowed_changes` is-historical evidence only. Reconcile the Revision independently; do not rerun `variant_check` or report-the Revision's authorized Source edits as variant batch scope conflicts.--For a completed project with a new natural-language change, use the current-`.hypit/revision-state.json` view and the execution directory named by its `revision_id` under-`.hypit/revisions/`. The immutable request is-`.hypit/revisions/<revision-id>/request.json`. Use the-`revision_state` commands described in `revision/route.md`. The project may be supplied directly and-need not have a parent creation route. When a parent route snapshot exists, reconcile it together-with the revision snapshot; otherwise validate the supplied Run as the baseline and start Revision-without inventing parent history. Revision does not call VLM/observer, render, or perform visual-review; it stops after the requested deterministic gates and leaves Studio untouched.--After a completed revision, a request for many derivatives starts a new variant-expansion batch from-the revised project. Reconcile the parent route and revision state before starting the batch; do not-fold the batch into Revision.--## What the state means--The current state file is a small view, not a transcript. It records the execution id, current route step, completed steps,-manual decisions, a short next action, and pointers to files such as `state.json`, `round.json`, render-outputs, comparison/review logs, and the final check result. Full prompts and observer prose remain in-their existing logs and are never copied into the snapshot.--Machine-owned commands update the snapshot only after their success predicate is true. Source writing,-repair, observer judgement, and Build submission are manual boundaries and require an explicit-checkpoint:--```bash-hypit-reference-video-tools route_state --action checkpoint \- --project-root <project> --route reconstruction --state review-planned \- --status complete --next-action 'run final reconstruction_check' \- --decision 'visual review completed against the reference'-```--Layout candidates use their dedicated persisted decision file instead of a prose route checkpoint:-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-reconciliation moves the route back to the first step whose evidence is missing.--## Idempotency and paid work--Repeated `prepare`, preview-mock, render, comparison, and check commands must reuse their existing-caches and logs. Never submit a paid Build merely because the context was compacted: inspect the state,-verify the Build/Record evidence, and resume observation with the existing command instead.diff --git a/.agents/skills/hypit/references/revision/route.md b/.agents/skills/hypit/references/revision/route.mdindex 1ab22bea..634387d2 100644--- a/.agents/skills/hypit/references/revision/route.md+++ b/.agents/skills/hypit/references/revision/route.md@@ -1,145 +1,29 @@-# Post-completion natural-language revision route--Use this route whenever a natural-language change targets a completed Hypit project. The project may-have just finished reconstruction, original authoring, variant expansion or an earlier revision, or the author may hand-over an already completed project directory directly. Revision does not require the current agent to-have created the project and does not require a parent creation route to exist.--For a directly supplied directory, first locate its canonical Run and Source/Recipe closure, then-run `validate_local_author_packages`, `validate_script_cues`, `hypit check`, `preview_check` and-`layout_check` to-confirm the existing project is a sound revision baseline. If `.hypit/route-state.json` exists, read-and reconcile it; if it does not, do not invent a reconstruction or description history. Start-`revision_state` without `--parent-route` and persist the baseline check evidence with the first-checkpoint.--Requests such as “move this element right” or “raise the captions” start a separate revision route.-Do not edit the rendered MP4, PNG, WAV, preview mock or Artifact directly. The source remains-authoritative.--Before any revision command or project inspection, read `../environment.md` completely and finish its-environment checklist. The selected Distribution, project boundary, credentials, Runtime Profile,-selected managed programs and their health checks must all be confirmed; the local WhisperX Endpoint-must report `Ready whisperx` (or an equivalent successful probe). Do not begin a revision from a-partial, installing, unhealthy or unconfirmed environment, even when the change itself appears-deterministic or the user asks to bypass setup.--## Recovery and state--Read `../../SKILL.md`, `../recovery.md`, the project's current `.hypit/revision-state.json` view, its-`.hypit/revisions/<revision-id>/state.json` history state and immutable `request.json`, `git status`, and-the parent `.hypit/route-state.json` only when one exists. Start the state once.--From a completed reconstruction or original-authoring route:--```bash-hypit-reference-video-tools revision_state --action start \- --project-root <project> --run build.svrun --parent-route description \- --request 'raise the captions slightly'-```--From one completed variant project, target that child directory rather than its base or batch root:--```bash-hypit-reference-video-tools revision_state --action start \- --project-root <batch>/023-example --run build.svrun --parent-route variant \- --request 'make the presenter framing tighter'-```--From a directly supplied completed project with no parent route state:--```bash-hypit-reference-video-tools revision_state --action start \- --project-root <project> --run build.svrun \- --request 'raise the captions slightly'-```--The current snapshot is atomic and small. Each start gets a new `revision_id`; its state and request-are kept under `.hypit/revisions/<revision-id>/`, so a later revision cannot overwrite the earlier-history. It records the execution-scoped parent route path/digest when one exists, request summary,-impact and affected Source, durable artifact references, decisions, current stage and-`next_action`. Use `revision_state read` and `revision_state reconcile` after interruption or context-compaction; never resume from chat memory. Manual intent mapping and Source edits require an explicit-checkpoint. Machine evidence may advance only when its file/check predicate is true.-When a gate command returns `evidence`, checkpoint that immutable path; do not point revision history-at a same-named latest-result view directly under `.hypit/`.--Stages are:--```text-request-captured → impact-assessed → intent-mapped → source-updated-→ gates-checked → preview-rendered → review-complete → final-checked-→ revision-complete → build-complete (only if paid generation changed)-```--`revision_state` checkpoints use the numeric `--step` flag, not a stage name. The mapping is:--| Step | Stage |-|---:|---|-| 1 | request-captured |-| 2 | impact-assessed |-| 3 | intent-mapped |-| 4 | source-updated |-| 5 | gates-checked |-| 6 | preview-rendered |-| 7 | review-complete |-| 8 | final-checked |-| 9 | revision-complete |-| 10 | build-complete |--For example, after editing Source, record step 4 with:--```bash-hypit-reference-video-tools revision_state --action checkpoint \- --project-root <project> --step 4 --status complete \- --decision "source update recorded"-```--Use the same numeric mapping for every later checkpoint; `--state` is not accepted by-`revision_state`.--`preview-rendered` and `review-complete` are not required work in this route. `review-complete` is-deliberately not a VLM/observer step. Revision does not call-`review_element`, `compare_reconstruction`, Vertex, WhisperX or any other visual observer. Mark that-stage only as an explicit mechanical checkpoint when the requested source change has been covered by-the deterministic checks. Revision itself performs no visual judgement; after it completes, if no-Studio session is running for the current Run, start Studio, capture the URL printed by the server,-and give the author the exact URL with the updated result.--## Work sequence--1. Read the current `main.svml`, `recipes.svs`, `build.svrun`, runtime profile, brief and the target- package README/vocabulary. Recover the target element's role in the author's intent. For a- directly supplied project, use its authored Source, project documentation and current graph as the- frozen intent evidence; do not force it through reconstruction or original authoring first. For a- completed variant, read the parent variant route's `variant_brief`, `format_plan`, `component_plan`- and immutable final-check evidence. Its `allowed_changes` explains how the batch agent originally- produced that variant, but it is not an authorization boundary for the user's later Revision.-2. Classify the request's impact: geometry/style, Script/semantic timing, graph structure, or paid- generation. Record the affected Source files and the smallest invalidated graph closure.-3. Map natural language to the authoritative field before editing. A request such as “move the- captions up slightly” maps to a Frame/Placement/Recipe/Style change; a changed line is a- Cue/SemanticTake/timing change; a new- component is a vocabulary-gap and package change. A Hook or opening change also requires checking- that later beats still fulfil its promise.-4. Edit only Source, Recipe or Run. Re-run package/Cue gates, `hypit check`, `preview_check` and- `layout_check`, then- checkpoint their immutable evidence as the Revision final gate. When the parent is `variant`, do- **not** run `variant_check`: that command belongs only to initial batch production and would- reapply the old `allowed_changes` to a new user-authorized request. Do not render, compare, review- or inspect any frame during revision. **Read now:** `../layout-checks.md`. Its browser measurements- are mechanical candidate evidence rather than visual judgement; repair genuine issues or persist a- reason for intentional geometry before completing `gates-checked`;- existing unchanged artifacts may be reused by digest. Once the gates pass, follow- `../studio-confirmation.md`'s conditional Studio handoff.-5. Check the final gate. Confirm cost again only when an image/video/voice generation input changed;- geometry and layout revisions do not trigger a paid Build. Build only after explicit approval.--Revision never edits or regenerates mock media. If a later, explicit Studio session previews the-updated Run, that session must continue using the existing SVRun-native preview-mock path; never-revive `make_placeholder`, hand-written SemanticTracks, or absolute-path mock Candidates.--If the author asks for many independent derivatives after this revision is complete, reconcile and-finish `revision_state`, then start `../variant-expansion/route.md` from the revised project. The-batch is not another revision step: its main agent rechecks examples, format/component plans, package-gaps and per-variant scopes before copying or dispatching work.+# Revising an existing project++A revision is an edit to the existing Source, Recipe or Run. It is not a new route object and it does+not require reconstruction history. The project directory supplied by the author is the baseline.++1. Read the request and inspect the current `.svml`, `.svs` and `.svrun` files.+2. Inspect `git diff` when the project is versioned so unrelated edits remain untouched.+3. Map the requested change to the smallest authoritative source fields.+4. Edit Source, Recipe or Run. Never edit a generated MP4, PNG, WAV or existing Result in place.+5. Run only the direct reports relevant to the change:++ ```bash+ hypit-reference-video-tools validate_local_author_packages --run <run>+ hypit-reference-video-tools validate_script_cues --run <run>+ hypit check <run>+ hypit-reference-video-tools preview_check <run> [<runtime>]+ hypit-reference-video-tools layout_check --run <run> [--runtime <runtime>]+ ```++ These reports do not form a sequence and do not approve the revision. Use them to find actual+ source, graph or layout problems.+6. If the change affects a reviewed visual declaration, render and review that declaration again.+ Do not invoke a visual observer when the visible design did not change.+7. If generation inputs changed and the author wants fresh generated media, run `hypit plan`, explain+ cost and obtain approval before a new Build. Otherwise reuse the existing Result inputs directly.+8. Show the updated Run in an existing Studio session, or start Studio and report its exact URL.++The completion record is the edited source plus any new Result the author approved. Do not write a+revision id, parent snapshot, progress cursor or duplicate history file.diff --git a/.agents/skills/hypit/references/runtime.md b/.agents/skills/hypit/references/runtime.mdindex c1441897..0a78dbac 100644--- a/.agents/skills/hypit/references/runtime.md+++ b/.agents/skills/hypit/references/runtime.md@@ -87,7 +87,7 @@ hypit build build.svrun --followhypit inspect <build-id>hypit get <build-id> \- --name final.video --to output/final.mp4+ --output final.video --to output/final.mp4```The paid-build handoff is defined in `studio-confirmation.md`: show the complete preview-mock Run in@@ -109,9 +109,9 @@ an active full-profile diagnosis and `runtime status` to observe the deployment.cheap preflight and fails before durable submission when deployment is not ready; it never installsor starts a Managed Program.-Use `runtime logs` to diagnose the Worker. Use `runtime down` to stop it from claiming more Builds.-External programs are intentionally independent; stop them only with `programs down`. Durable-Builds remain archived and neither command cancels remote Provider work.+Use `runtime logs` to diagnose the Worker. Use `runtime down` to stop it from advancing active Builds.+External programs are intentionally independent; stop them only with `programs down`. Saved Build+Results remain in the project Result repository, and neither command cancels remote Provider work.## Preserve durable semantics@@ -127,8 +127,8 @@ Builds remain archived and neither command cancels remote Provider work.terminal state without resubmitting or taking execution ownership.- Every `build` invocation creates a fresh automatic Build id. Source identity never reclaims anearlier Build; reuse across Builds exists only through explicit Run Source Candidates.-- `inspect` reads durable Build state and accepted Records. `get` copies an archived Artifact to the- requested destination.+- `inspect` reads one finished Build Result. `get --output <name>` reads or copies one uniquely named+ public Output from that Result.- A running Worker loads an installed Component package when a Build first names it and remembersevery physical package in that dependency closure. A later Build may add another installedComponent package without restarting the Worker; shared dependencies are not registered twice.@@ -147,30 +147,17 @@ Builds remain archived and neither command cancels remote Provider work.Read an identical repeat failure as this until you have ruled it out. Reasoning about why a correctfix did not work is how an afternoon goes, and the fix was never loaded.-- **Stop the Worker between Builds, never during one.** A remote generation belongs to the Provider,- and the Worker is the only thing watching it: take the Worker down mid-flight and the request keeps- running with nobody to collect it, passes its operation deadline, and fails — taking the whole Build- with it, not merely the requests that were in the air. `runtime status` reports what is queued,- running and reserved; wait for it to report nothing before stopping anything. This applies to the- Profile as much as the code — raising an Endpoint's `defaultConcurrency` needs the same restart, so- a change that costs nothing on an idle Runtime costs the whole Build on a busy one. Nothing is lost- by waiting: accepted Records are durable, and the requests still in flight are the expensive ones.-- **Check before every restart, and treat a running Build as a stop sign rather than a delay.** The- reading takes one command, and it is the same one whatever the reason for restarting:+- **Prefer stopping an idle Worker.** A changed Runtime Profile or already-loaded package code takes+ effect only after restart. Check active work first so an immediate in-process Producer is not+ interrupted. Asynchronous Provider Operations are durable and are polled again after restart; the+ Worker does not submit them a second time.++ Use the activity view before every restart:```bash- hypit runtime status # proceed only on Queued 0 · Running 0+ hypit activity # proceed when no active Builds are listed```- What follows a restart taken during a Build is not only the lost generation. The Build is left- `running` and holding the lane it reserved, a Worker claims only `queued` and `waiting` Builds, and- cancelling happens on a claimed Build — so it holds that lane against every later Build, and- `hypit cancel` reports the request and changes nothing. A current Worker takes such a Build back at- startup; an older one does not, and the symptom there is a queue that never moves while- `Active Operations` stays `0`. Read that pair — a Build `running` with no active operation — as this,- and restarting again is the one thing that cannot help.-## Keep the Distribution and every project physically separateThe Distribution reported by `hypit paths --json` is package-manager-owned and replaceable. Neverdiff --git a/.agents/skills/hypit/references/script-time.md b/.agents/skills/hypit/references/script-time.mdindex 76607ad3..9eb98a6e 100644--- a/.agents/skills/hypit/references/script-time.md+++ b/.agents/skills/hypit/references/script-time.md@@ -21,8 +21,8 @@ N:M Alignment Unit. A closing `</segment>` is also a hard Cue boundary: Cue counrestart at the next Segment, so a trailing `||` is not required merely to prevent a Cue crossingSegments.-The mechanical gate `validate_script_cues --run <build.svrun>` enforces a maximum of four visible-words per Cue. Fix the Script before `hypit check` or preview.+`validate_script_cues --run <build.svrun>` reports every Cue over four visible words. Fix the Script+before `hypit check` or preview.## A Segment is a stretch that is spoken as onediff --git a/.agents/skills/hypit/references/studio-confirmation.md b/.agents/skills/hypit/references/studio-confirmation.mdindex 666e563c..1079cc12 100644--- a/.agents/skills/hypit/references/studio-confirmation.md+++ b/.agents/skills/hypit/references/studio-confirmation.md@@ -1,70 +1,38 @@-# Studio confirmation and paid-build handoff+# Studio handoff and paid Build-This is the human handoff around both the reconstruction and original-authoring routes. It is not a-VLM review and it does not replace the route's mechanical checks.+Studio display and paid execution are separate decisions.-## Before the paid gate+## Before a paid Build-After the route-specific final check passes, but before submitting any paid Build:+1. Read the selected Runtime Profile and preflight. Tell the author which Provider, Endpoint and+ credential source will serve each paid capability without revealing secrets.+2. Produce a local preview through `render_element` or `realizePreviewMock` and use the exact+ `previewRun` path it returns.+3. Start Studio with that Run and report the exact URL printed by the server.+4. Explain that the preview uses local stand-in media and estimate timing.+5. Run `hypit plan`, state the estimated cost, and wait for explicit approval before `hypit build`.-0. Read the selected Runtime Profile and preflight result and tell the author which Provider and- credential source will be used for every paid capability (for example, KIE + `KIE_API_KEY`, or- HypiHub OAuth from the OS store). Never display the secret. Credentials must already be usable from- environment setup; if one is missing or cannot reach the requested model, stop and return to that gate.+If the author requests a change, edit Source/Recipe/Run through `revision/route.md`. Studio display is+not permission to spend money.-1. Realize the preview through the native `reference-video-tools render_element` path (or the- repository API `realizePreviewMock({ run: "<project>/build.svrun", timing: "estimate" })`).- The tool writes a durable `.hypit/preview/<digest>/mock.svrun` (the native mock materialization- Run), its content-addressed Artifacts, and a second `preview.svrun` whose relative file Candidates- point at those results. The realization is keyed by the Author/Run/target/geometry/timing digest,- so repeating the command reopens the cached bytes instead of generating new media or spending- Provider quota.-2. Start Hypit Studio with that returned `previewRun` path. Capture the URL printed by- `server.printUrls()` and give the author the exact URL (for example,- `http://localhost:5179/`) in the handoff. Studio can- therefore be started as a separate process and reopen the same bytes; it does not depend on an- in-memory attachment list or a mock-media endpoint (Studio may use the local FFmpeg endpoint for- deterministic inspect/normalize operations).-3. Let Studio show the complete program through the normal SVRun-native preview path:- `compiler-node Graph → mock.svrun/mock-media → persisted Artifacts → preview.svrun → Studio`.-4. Tell the author this is an estimate-timed, preview-only mock and ask whether the structure and- intended result are acceptable for paid generation.-5. Do not submit `hypit build` until the author explicitly accepts and confirms the cost.+## After a Build-If the author does not accept, do not Build. Capture the requested change and enter `revision/route.md`.-Revision edits Source/Recipe/Run and reruns deterministic gates; it does not ask an agent or VLM to-judge the picture.+Inspect the project-owned Result. It identifies the Build and its public outputs, including useful+intermediate component ports. Give important Results and outputs human presentation names.-## After the paid Build+To view or reuse accepted upstream material, write a separate Run with explicit `build-record` and+`satisfy` declarations. Do not satisfy the final target when Studio needs to trace the current Film+graph; keep the target unresolved and pin only the upstream generated values the preview needs.-Once the author has accepted and the paid Build is submitted/accepted, create/persist a derived Run-that selects the accepted Build Records (the same `<build-record>`/`<satisfy>` mechanism documented in-`runtime.md`), but never satisfy a Run Target such as `final.video`: Studio needs that Target to remain-connected to the current Film graph, not replaced by an opaque finished-media Candidate. Generate the-markup with `hypit history --source <author.svml> --pin --exclude-targets`, persist it in a separate-Studio Run, then start Studio for that accepted-material Run. The Build Run may retain the narrower set-of paid upstream pins it needs for reuse; neither Run pins its own Target. Start the HyperFrames/final-render at the same time; the render must not wait for the author to finish looking at Studio. Studio is-a live, read-only presentation of the current Run while the render proceeds. Report render/build status-and the Studio URL independently.+Start Studio for that accepted-material Run and report the URL. Rendering and Studio viewing may run+at the same time; neither waits for the other.-After that full video is delivered, any new natural-language change is routed to-`revision_state start --run <accepted-material-run>` and `revision/route.md`. It is not a second visual-review loop and it never edits the rendered artifact; the revision updates Source/Recipe/Run and-reruns only the deterministic gates before the next Studio handoff or paid Build confirmation.+## After an edit-## After a revision+Reuse a running Studio process for the same Run and startup parameters so its watcher can reload+Source. If the Run, workspace or port changes, stop the old process before starting another. A visual+edit may be reviewed when useful, but the revision has no hidden completion state and does not require+a new paid Build unless the author asks for regenerated material.-When a user-requested revision completes its deterministic gates, preserve a running Studio session-and let its file watcher hot-reload the updated SVML/SVS/SVRun. If the current Run has no Studio-session, start one for that Run, capture the URL printed by the server, and give the author the exact-URL so they can see the change. Do not invoke a-VLM, comparison, observer or visual judgement as part of Revision. Do not restart an already-running-Studio merely because Source changed. If the startup parameters change (for example a different Run,-workspace or port), stop the previous Studio first so the new server cannot collide with its port.--Use the existing `preview.md` startup command and `revision_state` snapshot. In a contributor-checkout, `hypit-studio` means `node <checkout>/bin/hypit-studio.mjs` and is a standalone entrypoint,-not `hypit studio`. Studio startup is a-display handoff, not permission to Build; a new paid generation still requires a fresh cost-confirmation.+In a contributor checkout, `hypit-studio` means+`node <checkout>/bin/hypit-studio.mjs`; it is a standalone entrypoint, not `hypit studio`.diff --git a/.agents/skills/hypit/references/variant-expansion/route.md b/.agents/skills/hypit/references/variant-expansion/route.mddeleted file mode 100644index add81ab0..00000000--- a/.agents/skills/hypit/references/variant-expansion/route.md+++ /dev/null@@ -1,318 +0,0 @@-# Variant expansion route--Use this route after a reconstruction, original-authoring or revision project has passed its final-deterministic gate, or when the author supplies an existing project that passes the same gate. It-derives exactly N independent source projects from one frozen base project. It does not reinterpret-initial reconstruction customization as Revision: presenter, product and brand changes included in-the original reconstruction request remain reconstruction step 23 work.--The default deliverable is checked Source. Do not render, visually review or submit a Build unless-the author explicitly asks for finished videos. A Build spends money and still requires a fresh cost-approval; context recovery is never approval to repeat it.--Before discovering or copying a batch, read `../environment.md` completely and finish its environment-checklist. The selected Distribution, project boundary, credentials, Runtime Profile, selected managed-programs and health checks must be confirmed; the local WhisperX Endpoint must report `Ready whisperx`-(or an equivalent successful probe). Do not treat source-only delivery or an existing completed base-as a reason to skip this gate.--## Recovery comes first--At the start of a new turn or after context compaction:--1. Re-read `../../SKILL.md` and this route.-2. Run `variant_state --action discover --project-root <base>`.-3. Read the canonical state it reports.-4. Inspect the parent route/revision digest, `git status`, recorded artifacts and `last_command`.-5. Run `variant_state --action reconcile --project-root <base> [--batch-id <id>]`.-6. Reconcile every unfinished `variant-package` staging route and every unfinished `variant` route.-7. Stop on recorded conflicts; otherwise execute only the first unmet step named by `next_action`.--The base locator is `<base>/.hypit/variant-expansions/<batch-id>.json`; the canonical batch state is-`<batch>/.hypit/variant-expansion-state.json`. Never recover a sibling batch path from chat memory.-Batch state read-modify-write operations are serialized by a batch-local lock; variant agents update-only their own variant record so concurrent completions cannot replace one another with stale arrays.--## Batch state--Start once, after the base project is selected:--```bash-hypit-reference-video-tools variant_state --action start \- --project-root <base> --output-root <batch-root> --run <base>/build.svrun \- --count <N> --delivery-mode source --request '<the complete request>'-```--Use `--delivery-mode build` only when the author explicitly requested finished variants. The durable-batch stages are:--```text-baseline-validated → examples-inspected → format-plan-frozen → slate-drafted-→ vocabulary-enumerated → component-plan-frozen → package-gaps-classified-→ workload-disclosed → package-gaps-resolved → slate-frozen → projects-copied-→ variants-dispatched → variants-complete → aggregate-checked-→ [build-planned → build-approved → build-complete] → expansion-complete-```--Manual creative decisions are checkpointed explicitly. `reconcile` may confirm machine predicates,-roll missing evidence back, and report digest or scope conflicts; it never invents a Format DNA,-Slate, component choice, allowed change or cost approval.--## 1. Validate and freeze the base--The base must be a completed reconstruction, original-authoring or revision project, or an existing-project that passes its corresponding deterministic checks. Record the parent route/revision digest.-Do not Build merely to create a base for expansion.--If the request began as “reconstruct this video with my product and make 100 variants,” finish the-reference reconstruction and apply that product/person/brand adaptation inside reconstruction first.-Variant expansion starts from that adapted, checked base. Revision is used only for a later natural--language change to an already completed project.--After an individual variant reaches `variant-complete`, a later natural-language change to that child-project leaves this route and starts `../revision/route.md` with `--parent-route variant`. The original-`allowed_changes` remains batch-production history; it does not constrain that Revision. Do not run-`variant_check` after Revision has started. Later batch reconciliation validates the immutable check-that completed the original variant and does not reinterpret Revision edits as batch scope escape.--## 2. Inspect examples and freeze format decisions--**Read now:** `../brief-intake.md`, then inspect complete projects under the checkout's `examples/`-directory when it exists. Recover intent, Hook, narrative development and the relationship between-visuals, audio and text. README clone sets are useful evidence of the intended expansion pattern, but-their Source, people, products, claims and assets are not templates.--**Read now:** `../playbooks/index.md`. Select each direction's format from its intent. Read the matching-format file named by that index completely and the craft files its footer names. Keep the base format-by default. A switch among ranking, street interview, podcast or another format is a high-change-direction and must be explicit in the plan.--Persist `format-plan.json`. Each direction entry records its id, quota, example basis and digest,-playbook path, and frozen Format DNA: Hook, narrative progression, speaker/role grammar, layout system,-timing model, caption/overlay behavior, audio relationship and what must remain invariant. The-dispatch step carries that direction entry into each numbered child. Checkpoint-`examples-inspected` and `format-plan-frozen`; file existence alone does not make either decision.--## 3. Draft the Slate--Write `slate.json` as a set of distinct direction quotas. Do not hand-write N full briefs when the-request asks for a large batch. The quotas must add up to exactly N, and each direction provides the-shared brief and allowed scope inherited by its concrete variants:--```json-{- "count": 100,- "directions": [- {- "id": "ranking-host",- "slug": "ranking-host",- "count": 20,- "brief": { "direction": "vary the host-led ranking presentation" },- "component_class": "svml-only",- "allowed_changes": ["main.svml"],- "vocabulary": { "mode": "inherited", "packages": [] }- }- ]-}-```--The main agent chooses the directions from the examples and divides the requested count among them.-`variant_init` expands each direction deterministically into numbered concrete variants (for example,-`ranking-host-01` through `ranking-host-20`) and persists each generated brief in that child's-`.hypit/variant-brief.json`. A child may make its concrete creative choice within the direction, but-must keep the inherited scope and its unique direction/ordinal identity. The older expanded-`variants` form remains readable for already-created batches.--`component_class` is one of `svml-only`, `existing-component`, `composed-components` or-`new-package`. Use `vocabulary.mode: "inspect"` and list the assigned packages whenever a variant-switches to a package the base did not use. A validated staging package can be injected once copied:--```json-"inject_packages": [- { "package_id": "my-component", "destination": "packages/my-component" }-]-```--The package id must name a ready package frozen in batch state; the tool resolves its recorded-`package_root` and refuses any digest mismatch. The destination must stay under the copied project's-`packages/` directory. `allowed_changes` is authoritative. A `svml-only` variant must allow exactly-`main.svml`. Add `.svs`, `build.svrun`, runtime or package paths only when the frozen decision actually-changes Recipe/Style, Graph/Target/Candidate, capability or component implementation.--Checkpoint `slate-drafted`, but do not freeze or dispatch it yet.--## 4. Enumerate vocabulary and decide package work globally--**Read now:** `../vocabulary.md`.--Use its shared fit judgement and immutable-package boundary; `component-plan.json` records the batch-decision instead of creating a second copy of those rules.--Before any package or variant agent starts, the main agent runs:--```bash-hypit-reference-video-tools list_svml_packages-hypit-reference-video-tools inspect_svml_vocabulary --package <candidate> [--package …]-```--Read every selected package's returned `readme_path`; never infer syntax from package source. Persist-the complete listing/inspection as the batch vocabulary evidence and write `component-plan.json`.-Classify every variant before dispatch:--- base components, SVML-only changes;-- an installed component the base does not currently use;-- a deliberate composition of installed components;-- a proven vocabulary gap requiring one project-local package.--The component plan names exact Module, Tag, relevant Recipe properties, package README and inspection-evidence. It also names which variants share each new package. Checkpoint `vocabulary-enumerated`,-`component-plan-frozen` and `package-gaps-classified`.--## 5. Disclose workload before agents start--Tell the author, without pausing by default:--- how many variants are fast `main.svml`-only work;-- how many change SVS/Run or switch/compose installed components;-- how many new packages are required, their purpose and affected variants;-- that new package development materially increases completion time;-- whether any requested delivery would invoke paid generation.--Persist the same counts and message in `workload_disclosure`, then checkpoint `workload-disclosed`.-Wait only for paid work, a material creative scope expansion, or a missing core decision.--## 6. Resolve every package gap before ordinary variants--Create one staging project per distinct gap and start:--```bash-hypit-reference-video-tools route_state --action start \- --project-root <staging> --route variant-package --run <staging>/build.svrun-```--The package agent must read `../vocabulary.md`, `../local-author-package.md`, the assigned format and-craft documents, `../authoring.md` and `../preview.md`. Its route is:--```text-gap-confirmed → guidance-loaded → types-frozen → implemented-→ vocabulary-inspected → package-validated → graph-checked → layout-checked → package-ready-```--It must repeat `list_svml_packages` and `inspect_svml_vocabulary` to confirm the gap, freeze Types and-Manifest before implementation, then run Run-scoped inspection, `validate_local_author_packages`,-`preview_check` and `layout_check`. Read `../layout-checks.md`; its candidates are judged, not blindly-fixed. If package assets require paid generation, obtain cost approval first.--When the route has passed through `graph-checked`, checkpoint the batch package entry with-`status: "ready"` and name the package directory as `package_root` when it is below the staging-project root. `variant_state` freezes that package tree's digest, writes package-digest evidence, and-completes the staging route's `package-ready` step. The same digest is injected into every assigned-variant; never develop the same component twice.--No dependent variant may be copied or dispatched while its package route is incomplete. Once every-gap is ready, checkpoint `package-gaps-resolved`, make all Slate decisions final, and checkpoint-`slate-frozen`.--## 7. Copy first--Run:--```bash-hypit-reference-video-tools variant_init \- --project-root <base> --output-root <batch-root> --slate <slate.json>-```--The command creates `NNN-<slug>/` projects under the batch root. It uses copy-on-write when the-filesystem supports it and falls back to ordinary copying. It preserves authored SVML, SVS, runtime,-configuration, local packages, ordinary assets and the top-level `build.svrun`; it excludes Git and-dependency state, old `.hypit`, secrets, logs/caches, non-canonical preview/mock/accepted-material-Runs and generated result directories. Media are never excluded merely because of their extension.--Historical `<build-record>` candidates and only the `<satisfy>` declarations selecting those-candidates are removed from each copied canonical Run. Authored files, values, files, fragments,-targets and unrelated satisfactions remain. The copied state records a digest for every retained-file, writes the variant brief and `allowed_changes`, starts its `variant` route, and injects only the-validated packages assigned to that variant. Re-running `variant_init` reuses matching initialized-projects and refuses conflicting destinations.--## 8. Dispatch variant agents in bounded waves--The main agent supplies each variant agent only its copied project and the fixed plan entry for its-direction. The main-agent, not the child, has already chosen examples, format, Format DNA, component strategy and scope.-Checkpoint `variants-dispatched` only after the agents have actually been assigned; route-state files-created by `variant_init` are not proof of dispatch.--Every variant agent reads:--1. its copied project, `.hypit/variant-brief.json` and `.hypit/allowed-changes.json`;-2. its generated brief plus the matching direction entries from `format-plan.json` and- `component-plan.json`;-3. the assigned format playbook and every craft document linked by its footer;-4. `../authoring.md`, `../script-time.md` and `../preview.md`;-5. the assigned package README and inspection evidence.--Checkpoint `guidance-loaded` after those reads. The agent does not rescan examples or replace the-format/component decision.--Vocabulary behavior is fixed:--- unchanged Module/Tag/component combination and Recipe contract may use the inherited base evidence;-- a package or component change requires `list_svml_packages`, Run-scoped- `inspect_svml_vocabulary`, and the returned README inside the copied project;-- a claimed new gap must be returned to the main agent. The variant agent may not start package- development or silently invent a Tag, attribute or Recipe value.--If the plan is inconsistent with installed declarations, record the conflict and stop that variant.-Do not widen scope, change format or choose another component locally.--## 9. Make the minimum change and check it--The variant route is:--```text-baseline-copied → brief-frozen → change-scope-frozen → guidance-loaded-→ vocabulary-verified → package-ready → script-checked → source-updated-→ graph-checked → layout-checked → final-checked → variant-complete-```--Change only the files named by `allowed_changes`:--- content, identity, product, Script and prompts in `main.svml`;-- Recipe/Style changes in `.svs`;-- Graph/Target/Candidate changes in `build.svrun`;-- capability changes in runtime;-- confirmed component changes in imports, project packages or dependencies.--Do not reformat, rename or rewrite unaffected files. Then run the package/Cue gates, `hypit check`,-`preview_check`, `layout_check --run <variant>/build.svrun`, settle every candidate by repair or an-explicit acceptance reason, and then run:--```bash-hypit-reference-video-tools variant_check --run <variant>/build.svrun-```--`variant_check` is mechanical only. It verifies settled layout evidence, vocabulary evidence, package use, Cue lengths, source-legality, graph tracing, frame-coverage/playback facts, generated-result leakage and the digest diff-against `allowed_changes`. Layout candidates remain evidence for the Agent, not mandatory edits. It-never renders media or invokes a VLM.--If the diff escapes `allowed_changes`, the route becomes blocked and the batch records-`scope-expansion-required`. The main agent decides whether the requested brief genuinely requires the-wider scope, atomically updates the batch variant record, baseline manifest, variant brief and-`.hypit/allowed-changes.json`, records the decision/conflict resolution in batch state, and-redispatches that variant. The three frozen scope copies must agree; a child never makes this change-silently.--## 10. Aggregate and optionally Build--As variants finish, `variant_check` updates their batch records and writes-`<batch>/.hypit/aggregate-check.json`. `variants-complete` requires every child route to be complete;-`aggregate-checked` requires every mechanical report to pass. Interrupted large batches resume only-unfinished routes.--For source delivery, checkpoint `expansion-complete` after aggregate success. For finished-video-delivery, prepare a Build plan and disclose the total cost, then checkpoint `build-planned`. Obtain-explicit approval and checkpoint `build-approved` before the first paid submission. Persist each-Build result and checkpoint `build-complete` only when all requested outputs are durable. Reconcile-the state before any retry so a context boundary never repeats a paid Build.diff --git a/.agents/skills/hypit/references/vocabulary.md b/.agents/skills/hypit/references/vocabulary.mdindex d68dcd3f..b75c81f0 100644--- a/.agents/skills/hypit/references/vocabulary.md+++ b/.agents/skills/hypit/references/vocabulary.md@@ -106,16 +106,14 @@ role files may be read as the bounded implementation skeleton; this is the onlyexception. When the fit is not good enough, use the project-local package route and author it fromthe visible requirement, inspect contract, README and `local-author-package.md`.-## Freeze the judgement+## Record the judgementBefore package development or Source authoring, write the decisions to the canonical`.hypit/component-fit.json`. Keep it concise and record only what affected the choice:```json{- "version": 1,- "route": "description",- "basis": ".hypit/brief.json and its frozen digest",+ "basis": ".hypit/brief.json","systems": [{"role": "ranking board","inspected_candidates": ["@hypit/ranking"],@@ -128,18 +126,9 @@ Before package development or Source authoring, write the decisions to the canon````accepted_variances` contains short natural-language differences only for-`reuse-with-accepted-variance`; it is empty for the other decisions. Checkpoint the file before-developing a gap. For `project-local-package`, `selected_package` names the planned project specifier.--```bash-hypit-reference-video-tools route_state --action checkpoint --project-root <project> \- --route description|reconstruction --state vocabulary-checked --status in_progress \- --artifacts '{"component_fit":".hypit/component-fit.json"}'-```--The later Run-scoped `inspect_svml_vocabulary --run <run>` persists the vocabulary evidence and-completes `vocabulary-checked` only while this frozen file is valid. After compaction, read it before-resuming package work, Source authoring or visual repair.+`reuse-with-accepted-variance`; it is empty for the other decisions. For `project-local-package`,+`selected_package` names the planned project specifier. This file records the actual design decision;+it does not unlock Source authoring and may be edited when the decision changes.## A real gapdiff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 69393d63..c1b2f930 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -55,6 +55,3 @@ jobs:- name: Testrun: pnpm test-- - name: Repository hygiene- run: pnpm test:releasediff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 3a369e7a..5cae932c 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -42,12 +42,11 @@ page belongs with the change to its counterpart.## Check your work-CI runs these three commands on every pull request. Run them locally first:+CI runs these commands on every pull request. Run them locally first:```bashpnpm check # TypeScript type-check-pnpm test # package, service-adapter and repository-boundary tests-pnpm test:release # repository hygiene+pnpm test # package and service-adapter tests```## Open the pull requestdiff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.mdindex 6b66c063..d9795fac 100644--- a/CONTRIBUTING.zh-CN.md+++ b/CONTRIBUTING.zh-CN.md@@ -35,12 +35,11 @@ pnpm install --frozen-lockfile## 自查-每个 Pull Request 的 CI 都会运行下面三条命令,提交前先在本地跑一遍:+每个 Pull Request 的 CI 都会运行下面这些命令,提交前先在本地跑一遍:```bashpnpm check # TypeScript 类型检查-pnpm test # 包、服务适配器与仓库边界测试-pnpm test:release # 仓库卫生检查+pnpm test # 包与服务适配器测试```## 提交 Pull Requestdiff --git a/docs/guide/author-packages.md b/docs/guide/author-packages.mdindex 0b6ee008..060c0232 100644--- a/docs/guide/author-packages.md+++ b/docs/guide/author-packages.md@@ -345,7 +345,7 @@ const label = {};```-The exact `fontArtifact` fields are shown by `inspect_visual_contract`; use a real Blob Artifact in+The exact `fontArtifact` fields are shown by `inspect_visual_schema`; use a real Blob Artifact in`sources`, with an explicit weight and style. The important boundary is that parent links, childcardinality, recipe properties, slot inputs and animation are declared explicitly and validated bytheir owning layer.diff --git a/docs/guide/runtime.md b/docs/guide/runtime.mdindex 2453a993..b908a8cf 100644--- a/docs/guide/runtime.md+++ b/docs/guide/runtime.md@@ -11,15 +11,16 @@ Hypit keeps three decisions separate:|---|---|| Workspace | Which source files and local assets compilation may read || Runtime Profile | Which environmental packages may be used |-| Local Runtime | How active Builds are queued, executed and observed |+| Local Runtime | How active Builds are durably advanced and observed || Project Build Results | Which completed public Outputs belong to each Build |Core is a domain neutral state machine. It accepts facts, derives Commands and verifies returnedRecords. It does not start processes, read credentials, choose Providers or know that a Build makesvideo.-`@hypit/runtime-local` is the default execution environment. It owns one Worker, scheduler, Build-queue and SQLite database. Those are one implementation, not user-selectable pseudo-components.+`@hypit/runtime-local` is the default execution environment. It owns one Worker, scheduler, the+pending-submission and active-execution state, and one SQLite database. Those are one implementation,+not user-selectable pseudo-components.## Runtime Profile@@ -32,10 +33,6 @@ The Profile contains only environmental choices that genuinely vary:"use": "@hypit/runtime-local","config": {"dataRoot": ".hypit/runtimes/local",- "results": {- "use": "@hypit/build-result-fs",- "config": { "path": ".hypit/results" }- },"credentials": {"env": { "use": "@hypit/credential-store-env" }},@@ -47,11 +44,20 @@ The Profile contains only environmental choices that genuinely vary:}```-* `results` optionally locates the project's complete Build Result repository. If omitted, it is- the ordinary `.hypit/results` directory in the project.* `credentials` selects stores for explicit credential references.* `endpoints` selects exact Provider implementations and their configuration.+Result storage belongs to the project, not the execution environment. A project may select it in+`hypit.results.json`; omitting the file uses the same filesystem default:++```json+{+ "format": "hypit.build-results@1",+ "use": "@hypit/build-result-fs",+ "config": { "path": ".hypit/results" }+}+```+Installing a package only makes an implementation available. A Profile must select it. The Profilecontains no Workspace, author imports or creative routing.@@ -75,24 +81,59 @@ Selecting a Profile writes a project pointer. Execution data stays under `dataRovalues/```-`check` and `plan` do not create Runtime data. SQLite holds only active execution facts, Provider-Operations and queue state. Each active Build has a private working byte directory. On an ordinary-complete, failed or cancelled path, once the Result is safely written, its heavy SQLite execution-rows and working bytes are removed. If writing the Result itself fails, the working state is kept for-local repair. One small terminal dispatch row may remain for Runtime status. It is not the history-source.+`check` and `plan` do not create Runtime data. Submission first prepares a non-schedulable row.+Only after the Result draft, attachments and working directory exist does one SQLite transaction make+the Build claimable. A pending submission left by a hard interruption is removed only by the exact+`hypit result discard <build-id>` operation; nothing scans or guesses.++An Execution stores active facts, Provider Operations, `wakeAt`, its current turn, cancellation, one+immutable decision and optional attention. It stores no phase. Once Result saving and working-directory+cleanup succeed, one transaction removes all owned SQLite rows with the Execution root last. Runtime+retains no finished Build-history row.++Every Build committed to a persistent Runtime must provide its project Result location and Author+Catalog. Execution without a Result is not a hidden alternate mode.Historical content lives in the selected project Result repository, not Runtime SQLite. With thedefault repository, `.hypit/results/<build-id>/result.json` names final Targets and every public-Author Output that actually completed on their route. Media is under that Result's `files/`;-structured values are under `values/`. `builds`, `history`, `inspect`, `get` and `build-record` use-the same repository interface. A Build queued for a detached Worker carries the exact repository+Author Output that actually completed on their route. Resource bytes are under that Result's `files/`;+Composite Value Documents are under `values/`; each document keeps canonical domain data separate+from its nested Resource-path bindings. `builds`, `history`, `inspect`, `get` and `build-record` use+the same repository interface. An active Build waiting for a detached Worker carries the exact repositorylocation it was given, so changing a Profile later cannot redirect that in-flight Build.+Author Graph and Run Graph remain compiler inputs. The Planner applies every `satisfy` globally,+computes the resulting dependency closure, and only then emits the immutable execution Definition:+selected initial Records, Producer steps, `Output -> Record` bindings, goals and Targets. Candidate+ids and the two source graphs do not enter Runtime persistence. Only zero-input Candidate sources+reached by that plan are then read, whether they name a local value, local file or historical Output.+A directly selected historical+Output gives Result storage one whole-Output forwarding address; historical inputs used inside a+new operation are staged once before the Build becomes active and produce ordinary current outputs.++The Result manifest itself may carry a human title, note and a list of highlighted public Outputs. Edit+those fields with `hypit result edit <build-id>`; this changes only that Build's `result.json`, does+not open the Runtime and does not create a project-wide metadata index. Studio reads the same fields+and can therefore show finished Builds even when no Runtime is selected.++`running` is neither a Result conclusion nor a persisted state. The stable Host `BuildView` derives+`submitting / ready / running / waiting / saving-result` from active facts. CLI and Studio consume that+view, never raw submission or execution persistence records. Once execution records its one `complete`, `failed` or+`cancelled` decision, a Worker can never claim it again. A Result has no `outcome` while accepting public+Outputs and is finished with exactly the same outcome. Result or cleanup failure adds independent+`attention = { step, error }` without changing the decision. Result browsing returns only finished+Results newest first, while an exact Build-id read can inspect a draft.++Every public Build id has the form `bld_YYYYMMDDTHHMMSSmmmZ_NNNNNNNNNN`. The UTC portion gives+Results a natural order; the final random nonce only prevents same-millisecond collisions and says+nothing about content equality or reuse. Pagination is keyset-based: `builds --before <build-id>` and+`history ... --before <build-id>` continue strictly before the last id returned.+For an S3-compatible repository:```json-"results": {+{+ "format": "hypit.build-results@1","use": "@hypit/build-result-s3","config": {"bucket": "my-video-results",@@ -104,21 +145,38 @@ For an S3-compatible repository:The AWS SDK uses its normal credential chain. `endpoint` and `forcePathStyle` are available forS3-compatible services. The prefix is the project boundary: each project should have its own-prefix. S3 changes only where complete Results live; it does not move Runtime SQLite, queues or+prefix. S3 changes only where complete Results live; it does not move Runtime SQLite, Provider capacity ortemporary working Artifacts into the bucket.+The S3 adapter maps each ordered Build id to a reversible newest-first physical prefix. It can request+one bounded delimiter page from object storage without a central index or duplicate catalog. Result+files are streamable by byte range, so+Studio video/audio requests do not load a whole remote file into memory first. `hypit doctor+[profile] --workspace <project>` actively checks the selected Result Store as well as the Runtime;+the storage check performs only a bounded read-only listing and does not scan Result history.+The Workspace is resolved independently from the explicit `--workspace`, the project containing theRuntime pointer, or the entry source directory. Runtime configuration cannot widen source access.-## Queue and concurrency+## Execution turns and concurrency-`build` admits a fresh Build and returns. The Worker advances every runnable Build while Core-preserves each Build's graph dependencies. Endpoint packages declare Provider and capability limits,-so work from separate Builds shares the exact external capacity that performs it.+`build` commits a fresh Build and returns. SQLite durably records every Build that needs another turn;+the Worker materializes its state only while advancing it and writes accepted facts back immediately.+There is no Build concurrency setting and Build identity is not a capacity resource.-Cancellation is best effort. Queued work is withdrawn before it starts; running work stops receiving-new commands and an Endpoint may try to cancel an already submitted external operation. Completed-output is retained and never rolled back.+Endpoint packages declare the two actual execution queues: one Provider pool and its model lanes.+Work from separate Builds shares those exact external capacities. Each resource has one limit: an+immediate call releases its slot when it returns, while an asynchronous Operation keeps the same slot+until it becomes terminal. Unrelated Builds and Commands may advance together.++Cancellation is best effort. Work that has not begun is withdrawn; running work stops receiving+new commands and an Endpoint may try to cancel an already submitted external operation. The active+Build is still advanced once to write its Result, without running generation Commands.+Completed output is retained and never rolled back.++Asynchronous Operations are stored before Endpoint `start()`. Immediate Producers and Endpoints+store a live command receipt before invocation and the complete Core event after return. If only the+started state survives, that Build fails explicitly; the same command is never invoked again.## Managed Programs@@ -147,9 +205,20 @@ hypit runtime down`runtime up` asks npm to prepare the selected adapters' exact upstream packages in the sharedmachine home, prepares declared Managed Programs, then starts the local Worker. `build` performs noprovisioning: it runs cheap read-only preflight, submits work only when ready, and ensures the Worker-is available. `status`, `queue` and `cancel` observe or control active work. A terminal Build is not-resumed. Reusing an earlier Result is an explicit Candidate in a new `.svrun`, not hidden Runtime-behavior.+is available. `activity` and `cancel` observe or control active work. `status` reads Runtime and Result as+independent sources, so failure on one side neither invents nor hides facts on the other. Without a+Runtime, a finished Result proves only its own outcome.++If Result writing or active-state cleanup fails, the decision remains immutable and attention identifies+the exact `result` or `cleanup` step. After fixing the external problem, an operator may run+`hypit result finish <build-id>`. The one-shot Result writer uses only stored Build facts, finished+Operation values, working bytes and the exact Result Repository; it never loads or invokes a Producer+or Endpoint. It idempotently writes the Result, removes the working directory, then atomically removes+the active SQLite aggregate. Only one Result writer may own that work at a time; this mutual-+exclusion lease is not a phase and never changes the decision. A Worker restarted after a hard interruption+clears the abandoned lease and records attention, but performs no storage action automatically. Missing bytes+fail explicitly instead of being regenerated.+Reusing an earlier Result is an explicit Candidate in a new `.svrun`, not hidden Runtime behavior.A running Worker loads installed Component packages as Builds first require them. A later Build mayname a new Component package without restarting the Worker; the Worker loads only packages it has@@ -157,6 +226,11 @@ not already seen from that package's complete dependency closure. Loaded packagereloaded, so editing a package or updating the Distribution still requires stopping an idle Workerbefore the next Build.+The Worker records the normalized literal Runtime Profile, not a hash. A changed Profile is not+silently applied to a live Worker. SQLite separately pins credential and Endpoint selection while any+pending or active Build remains, so a restarted Worker cannot poll an old Operation handle through new+Endpoint config.+Runtime packages are trusted local deployment code. npm or pnpm owns their installed versions;Hypit only selects exact requirements and invokes npm at the explicit `runtime up`/`packages install`boundary. It has no second package lock and does not claim that metadata is a sandbox.diff --git a/docs/guide/skill.md b/docs/guide/skill.mdindex 0e331f34..a2d5368d 100644--- a/docs/guide/skill.md+++ b/docs/guide/skill.md@@ -1,447 +1,103 @@-----title: Hypit Skill Architecture-description: How the Hypit skill turns descriptions and reference videos into checked projects.----+# Video authoring workflow-# Hypit Skill Architecture+Hypit keeps authoring, execution and results separate:-This document is the maintainer's map of the Hypit skill. The skill is an agent-driven production-workflow: the agent makes creative decisions, and repository tools turn those decisions into-SVML/SVS/SVRun, check the resulting graph, persist evidence and resume safely after interruption.+- Source, Recipe and Run describe what should be made.+- Runtime executes one Build from those inputs.+- Result records what that Build actually produced.+- Reference-video tools help an author understand and inspect content; they do not own Build or+ project history.-The important distinction is:+There is no route database, revision history, recovery cursor or aggregate project state. Work is+recoverable because the authored files and useful media/report files are ordinary project content,+not because a second system reconstructs an agent's past actions.-- the agent decides what the video means, what it should look like and what to change;-- tools decide whether the written project is legal, wired, covered, measurable and recoverable;-- a visual observer reports differences, but the agent decides whether a report is a real defect.+## Start from the request-## How a request becomes a video--```text-user request- → route selection- → intent/reference evidence- → format and vocabulary decisions- → Author Source + Recipe Source + Run Source + Runtime Profile- → graph/package/Cue/layout gates- → preview materialization and visual comparison (creation routes)- → repairs and repeated gates- → final deterministic gate- → Studio confirmation- → explicitly approved paid Build-```--The result is a complete video because the route does not stop at writing a prompt or a component:-it creates the Script and timing, connects every visual/audio Track to a Film, declares every external-generation in the Run, checks that the graph reaches the requested Target, and only then hands the-same Run to Studio or Build.--## Route selection and handoffs--| User input | Route | What it owns | Handoff |-|---|---|---|---|-| Description, topic, brief or named format with no reference video | `original-authoring` (original authoring) | Intent, Hook, Script, visual design and complete new project | Final gate → optional `variant-expansion`; later natural-language change → `revision` |-| Reference video or link, optionally “use my presenter/product/brand” | `reconstruction` (reconstruction) | Reference evidence, shot structure, matching Source, then the requested initial adaptation | Final gate → optional `variant-expansion`; later natural-language change → `revision` |-| Natural-language change to a completed project or completed variant | `revision` (revision) | A bounded Source/Recipe/Run edit and deterministic revalidation | Completed revision → optional `variant-expansion` or Studio/Build |-| N independent versions from a validated project | `variant-expansion` (variant expansion) | Global format/component plan, package gaps, copy-first projects and child-agent scopes | Each child → `variant-complete`; later manual change to one child → `revision` |--The initial presenter/product/brand change attached to a reconstruction remains inside reconstruction;-it is not routed through Revision. Revision begins only when the user later asks for another change.--## Shared phases--### 1. Environment and durable start--The agent selects the Distribution, independent project directory, Runtime Profile, credentials and-(for reconstruction) the observer. It starts the appropriate state machine before authoring:+Decide whether the task is original authoring or reconstruction from a reference. Then inspect the+available packages and the public vocabulary they expose:```bash-hypit-reference-video-tools route_state --action start --project-root <project> --route description-hypit-reference-video-tools route_state --action start --project-root <project> --route reconstruction+hypit-reference-video-tools list_svml_packages+hypit-reference-video-tools inspect_svml_vocabulary --package <package>+hypit-reference-video-tools inspect_visual_schema```-The Runtime Profile is written before any command that needs a managed capability. `hypit runtime use`-selects it and `hypit runtime up` prepares the local Worker/programs. This prevents later reference,-preview or Build steps from failing because the execution environment was never declared.+Reuse an existing Surface when it expresses the requested visual role. Develop a project-local author+package only when there is a real missing capability. Do not mutate an installed package to make one+project pass.-### 2. Establish intent or reference evidence+## Original authoring-For original authoring, read `brief-intake.md`, inspect semantically relevant complete projects under-`examples/`, recover their intent rather than copying their Source, select the format playbook and-freeze `.hypit/brief.json`. The brief records audience, Hook, narrative progression, visual/audio/text-relationships, claims and unresolved decisions.--For reconstruction, prepare the video and cache its bytes and whole-reference evidence:+Write the smallest Source, Recipe and Run that express the request. Inspect them directly:```bash-hypit-reference-video-tools prepare_reference --video-path <file-or-link> --observer <observer>-hypit-reference-video-tools observe_reference --reference-id <id>+hypit-reference-video-tools validate_local_author_packages --run ./build.svrun+hypit-reference-video-tools validate_script_cues --run ./build.svrun+hypit check ./build.svrun+hypit-reference-video-tools preview_check ./build.svrun+hypit-reference-video-tools layout_check --run ./build.svrun```-Preparation supplies media metadata, transcript/alignment and the reference observation envelope.-The observation sweep supplies persistent systems, people/voices, visual type and sound context for-the whole video. Shot observations and narrow questions resolve structure that cannot be safely-inferred from one frame. These artifacts are why reconstruction can produce a whole video rather-than only imitate one screenshot.--### 3. Choose format and vocabulary before Source+These commands are independent reports. One does not approve or unlock another. Fix an actual issue+because the report and the requested design justify the change. A layout candidate may be annotated+as intentional with `layout_accept`; the annotation is keyed by the structural finding name, not by a+snapshot of the whole project.-The main agent reads `playbooks/index.md`, the selected format and its linked craft documents. It-enumerates the visual/audio systems and runs:+For a visual review, render the element and window that matter, then read the result against an+explicit statement of intent:```bash-hypit-reference-video-tools list_svml_packages-hypit-reference-video-tools inspect_svml_vocabulary --package <candidate> [--package ...]-hypit-reference-video-tools inspect_visual_contract-```--`inspect_svml_vocabulary` is the public contract for what an installed Surface accepts. The visual-contract describes Visual Element shapes, admitted styles, enum values and seal invariants. The agent-records one concise component-fit decision per system in `.hypit/component-fit.json`: reuse an existing-package, reuse it with a small accepted variance, or develop a project-local package. Installed-package source is not needed for ordinary authoring. Only a confirmed close-sibling copy may read the-copied package's necessary role files.--If there is a real gap, the package route runs before dependent Source is accepted:--```text-gap-confirmed → guidance-loaded → types-frozen → implemented-→ vocabulary-inspected → package-validated → graph-checked-→ layout-checked → package-ready+hypit-reference-video-tools render_element ./build.svrun \+ --element title --segment intro --out ./review/title-intro.mp4+hypit-reference-video-tools review_element --run ./build.svrun \+ --element title --segment intro --video ./review/title-intro.mp4 \+ --intent-file ./review/title-intent.md```-The package agent uses `local-author-package.md`, the public contract and the minimal fixture. It must-expose a Manifest, Surface, Fragment, Producer, Validator, activation and preview, and it must be-imported and used by the project graph. `validate_local_author_packages` is the package gate.--After an original-authoring or reconstruction route completes, a project-local package may be-considered for contribution. Read the Skill reference `references/package-promotion.md` and ask the-author about a promotion when the component has clear, high reuse value across unrelated videos. If-the author agrees, move it into Hypit's `packages/` folder and prepare a Pull Request; ordinary-one-off components remain in the-project. This is a post-completion offer, not an interruption or an automatic repository change.--### 4. Author the four project sources--| File | Responsibility |-|---|---|-| `main.svml` | Script, narrative, component declarations, prompts and semantic timing references |-| `recipes.svs` | Style, appearance, playback, layout and other recipe values |-| `build.svrun` | Author binding, Candidates, satisfactions and Targets |-| `hypit.runtime.json` | Runtime packages, Providers, credentials and local execution |+`authoring_check` can summarize coverage, playback and recorded reviews, but it is not project state+and is not required to submit a Build.-The Script is written before shot-level generation: Segments define Take boundaries, Cues keep-captioned speech readable, and `estimate:Speech` provides deterministic timing. Source declarations-make each generation and graph edge explicit, so later checks can identify exactly what is wrong.+## Reconstruction-### 5. Deterministic graph and layout gates--Before visual comparison, the route runs:+Prepare the reference once:```bash-hypit-reference-video-tools validate_script_cues --run <run>-hypit check <run>-hypit-reference-video-tools preview_check <run>-hypit-reference-video-tools layout_check --run <run>-```--These gates answer different questions:--- package/Cue checks prove project packages and Script boundaries are usable;-- `hypit check` proves Source syntax, references and graph structure;-- `preview_check` proves tracks trace through packages to the Film;-- `layout_check` realizes the actual composition in a hidden browser and reports candidate geometry- findings such as internal vertical offsets, parent/Canvas overflow and settled top-level overlap.--Layout findings are evidence for the agent, not automatic truth. The agent repairs genuine problems or-records an intentional geometry decision with `layout_accept`, then reruns `layout_check` until all-candidates are resolved or accepted. A relevant Source, Recipe, package, font or runtime change-invalidates affected evidence.--The two extraction rules used by both creation routes are:--| Check | Extraction rule | Why |-|---|---|---|-| Visual review | For each distinct visual declaration/style change, take the **full clip at its first appearance**. | The full clip preserves entrance, movement, exit and transient visual differences. It avoids rechecking every caption text or timestamp when the visual declaration is unchanged. |-| Mechanical layout | For each `Present`, take one frame from its **longest stable interval**. | A settled frame measures actual DOM geometry without mistaking normal animation for overflow or offset. |--Do not swap these rules: visual review judges the complete clip against the brief or reference, while-`layout_check` only measures realized layout and returns candidates for the Agent. Content/time extremes-are not additional selection rules; stable overflow is found in the per-`Present` measurement, and-transient or media-internal problems remain visible to the full-clip review.--### 6. Creation-route visual review and repair--Original authoring calls `authoring_check`; reconstruction calls `reconstruction_check`. Each command-reads Source and creates the visual-review plan described above. The longest-stable-interval sample-belongs only to the separate hidden-browser `layout_check`, not to this visual review.--For each plan entry:--```text-render_element → rendered preview/mock artifact → visual observer/reviewer-→ record findings → agent repairs Source/Recipe/package choice → rerun gates-```--Reconstruction compares the rendered element against the prepared reference with-`compare_reconstruction`; original authoring uses `review_element`/`record_review` against the frozen-brief. The observer reports visible differences. The agent decides which are defects, intentional-design or an incorrect component-fit decision. It never copies or edits an installed package to force-a match. After repairs, the plan and mechanical gates are rerun until the final check passes.--### 7. Final gate, Studio and Build--`authoring_check` or `reconstruction_check` is the final deterministic gate. It requires package/Cue,-graph, layout and review/comparison evidence to be current. Only after it passes does the agent use-`studio-confirmation.md` to materialize the estimate-timed preview and show the live Run in Studio.-Studio acceptance is separate from visual comparison and confirms the intended structure before-spending. `hypit build` is submitted only after explicit cost approval.--## Route workflows--### `original-authoring` (original authoring)--```text-environment → brief-frozen → examples/format/craft decisions-→ vocabulary/component-fit → Script and four sources → source-authored-→ package-ready → script-checked → graph-checked → layout-checked-→ review-planned → preview-rendered → review-complete → repairs-complete-→ final-checked → Studio confirmation → optional Build+hypit-reference-video-tools prepare_reference --video-path ./reference.mp4 --observer agent+hypit-reference-video-tools observe_reference --reference-id <reference-id>```-This route turns an open-ended description into a complete program by freezing the intended viewer-result first, choosing a format and package vocabulary second, then writing every semantic and graph-edge needed by the Film. It has no reference video, so `brief.json` is the authority for later review.--| Step | Agent work | Tool or document | Durable result and reason |-|---|---|---|---|-| 1. Start | Choose the Distribution, project directory, runtime and credentials; start the route snapshot. | `environment.md`, `runtime.md`, `route_state start`, `hypit paths`, `hypit runtime use/up` | A runnable project and a recovery cursor exist before authoring begins. |-| 2. Make the request executable | Turn the description into audience, Hook, promise, beats, claims, speakers and visual/audio/text relationships. Inspect complete semantic examples; do not copy their Source. | `brief-intake.md`, `examples/` | `.hypit/brief.json` freezes what “correct” means, so review has a target instead of a vague “looks good”. |-| 3. Freeze format and craft | Select the matching playbook and load its required craft documents. For original authoring, establish recurring person, product, voice, location, wardrobe, lighting and prop anchors before writing generation prompts, then reuse them across takes. | `playbooks/index.md`, `formats/*.md`, `craft/visual-continuity.md`, `craft/persona-and-audio.md`, `craft/generated-dependencies.md` | The program gets a timing model, shot grammar, caption rules and explicit cross-shot identity/scene continuity even without a reference video. |-| 4. Fit components | Enumerate candidate packages, inspect their public vocabulary and decide reuse, accepted variance or a local package. | `list_svml_packages`, `inspect_svml_vocabulary`, `inspect_visual_contract`, `vocabulary.md`, `component-fit.json` | Every visual role has a legal Module/Tag/Recipe contract before Source is written; a real gap is solved once through `local-author-package.md`. |-| 5. Write the Script | Split the narration into Segments/Takes and short Cues; assign each shot one job and keep timing semantic. | `script-time.md`, `authoring.md` | `main.svml` contains the complete spoken/text progression and deterministic `estimate:Speech` timing. |-| 6. Wire the project | Author `main.svml`, `recipes.svs`, `build.svrun` and `hypit.runtime.json`; declare each generation, Track, Candidate, satisfaction and Target. | `authoring.md`, `runtime.md` | The Film graph is explicit and reproducible rather than a prompt plus disconnected assets. |-| 7. Prove sources and graph | Run package, Cue, syntax, graph-trace and realized-layout gates. | `validate_local_author_packages`, `validate_script_cues`, `hypit check`, `preview_check`, `layout_check` | The project is legal, every Track reaches the Film, and browser geometry has been measured before visual review. |-| 8. Plan the visual review | Ask the route check for one full clip at the first appearance of each distinct visual declaration/style change. | `authoring_check` | `.hypit/evidence/` records exactly what must be reviewed; the agent does not omit a style change or invent a render list. The longest stable sample is produced separately by `layout_check`. |-| 9. Render and review | Materialize the planned preview/mock clips, read every entry against the frozen brief, and record findings. | `render_element`, `review_element`, `record_review`, `element-review.md`, `conformance-round.md` | Each visual system has explicit evidence, including text fit, coverage, contrast, motion and geometry. |-| 10. Repair and close | Repair only confirmed issues, rerun affected gates and review entries, then run the final route check. | `layout_accept` when geometry is intentional; `authoring_check` | `final-checked` means no required visual review, graph, package, Cue or layout evidence is stale. |-| 11. Hand off | Create the estimate-timed preview-mock Run, show Studio, disclose cost and Build only after approval. | `preview-mock.md`, `studio-confirmation.md`, `hypit plan/build/status/inspect/get` | Studio sees the live Film graph; the paid Build reuses the checked Run and produces the complete delivery. |+The prepared shot clips, frames, transcript and observations live under+`.hypit/reference-video-tools/`. They are useful source material. `record_observation` fills an+explicit pending observation when the `agent` observer is used.-### `reconstruction` (reconstruction)+Author the project from the observed picture, words and timing. Render the element over the same+Script window and compare it directly:-```text-environment → reference-prepared → reference-observed-→ examples/format/craft decisions → vocabulary/component-fit-→ Script and four sources → source-authored → package-ready → script-checked → graph-checked-→ layout-checked → review-planned → preview-rendered → comparison-complete-→ repairs-complete → final-checked → initial-adaptation → final check again-→ Studio confirmation → optional Build-```--The reference is converted into durable evidence, not kept in agent memory. Observations define-people, persistent systems, shot boundaries, words and visual relationships; the Source recreates-those as Segments, Takes, Tracks and Film edges. The comparison round checks rendered results against-the corresponding reference stretches. That evidence/author/repair loop is what makes the route-capable of rebuilding the entire video.--The reconstruction order is deliberately different from a description-only job:--| Step | Agent work | Tool or document | Durable result and reason |-|---|---|---|---|-| 1. Prepare | Select the observer once, resolve a local file or download/cache a link, and start route state. | `observers.md`, `credentials.md`, `prepare_reference`, `route_state start` | A stable reference id, media metadata and observer choice prevent later turns from rereading a different file or silently changing observers. |-| 2. Observe the whole video | Run the fixed whole-reference sweep, then read its transcript/alignment, persistent systems, people/voices, visual type and sound context. | `observe_reference`, `evidence.md` | Whole-video evidence establishes what exists throughout the program; it is the basis for reconstructing every shot, not one representative frame. |-| 3. Resolve structure | Inspect shot boundaries and ask narrow questions where a single frame cannot establish an appearance value, transition or relationship. | `observe_reference --question`, `continuity.md`, `reconstruction/vocabulary.md` | Ambiguities become persisted evidence before Source is authored, so timing and continuity are not guessed from chat memory. |-| 4. Choose format and components | Read examples/playbooks, enumerate candidate packages, inspect public vocabulary and classify any real package gap. | `brief-intake.md`, `playbooks/index.md`, `list_svml_packages`, `inspect_svml_vocabulary`, `component-fit.json` | The recreated program has a legal component for each observed visual role; installed packages remain immutable. |-| 5. Build a faithful Source | Convert transcript and observations into Script Segments/Takes/Cues, then author all four sources and every graph edge. | `final-sources.md`, `authoring.md`, `script-time.md`, `runtime.md` | The source describes the entire reference timeline, including narration, overlays, B-roll, transitions, audio and Targets. |-| 6. Prove the baseline | Run Run-scoped vocabulary/package/Cue checks, syntax, graph tracing and realized layout. | `inspect_svml_vocabulary --run`, `validate_local_author_packages`, `validate_script_cues`, `hypit check`, `preview_check`, `layout_check` | No comparison is attempted until the written graph can actually produce every declared Track. |-| 7. Create the comparison plan | Determine every distinct declaration and every reference stretch it occupies; keep stable intervals and shot boundaries. | `reconstruction_check`, `comparison-round.md`, `element-review.md` | The plan covers the whole video, not only a convenient still; each item has its own reference tokens and render window. |-| 8. Render and compare | Render all planned stretches from the same Run, then submit the reference/render pairs to the selected observer. | `render_element --batch`, `compare_reconstruction --batch` | The observer reports visible differences while preserving the reference/render pairing and timing. |-| 9. Repair the reconstruction | Agent judges each finding against evidence, fixes Source/Recipe or a component decision, and never copies/edits an installed package. | `reconstruction/route.md`, `layout-checks.md`, `layout_accept` | Confirmed defects are repaired; intentional crop, overlap or offset can be documented without corrupting the package boundary. |-| 10. Recheck the faithful base | Rerun the comparison and deterministic gates until the reconstruction itself passes. | `reconstruction_check`, `preview_check`, `layout_check` | This separates “faithfully reconstructed” evidence from later author customization. |-| 11. Apply initial customization | Only now replace the requested presenter, product or brand in the completed reconstruction. Rerun the route check plus deterministic gates; differences caused by the requested adaptation are not silently treated as package defects. | `main.svml`/`recipes.svs`/`build.svrun`, `reconstruction_check`, `hypit check`, `preview_check`, `layout_check` | The reference evidence remains honest while the delivered base contains the requested adaptation. This is still reconstruction, not Revision. |-| 12. Hand off | Show the checked Run in Studio and request explicit cost approval before Build. | `studio-confirmation.md`, `hypit plan/build` | The same checked graph becomes the complete paid video; a later natural-language change routes to Revision. |--The reconstruction data flow is:--```text-reference bytes- ├─ transcript/alignment ───────────────→ Script Segments, Cues, estimate:Speech- ├─ whole-video observations ───────────→ people, voices, persistent visual/audio systems- └─ shot observations and questions ────→ shot boundaries, states, relationships- ↓- main.svml + recipes.svs + build.svrun + runtime profile- ↓- Tracks → packages → Film → Target- ↓- preview_check → review plan → render/compare every owed stretch- ↓- agent repairs → deterministic gates → Studio/Build-```--That mapping is the completeness guarantee: every observed word becomes timed Script, every observed-visual/audio role becomes a Track or package-backed element, and every Track must trace to the Film-before any paid generation is possible.--### `revision` (revision)--Revision can start from a directly supplied completed project, a reconstruction, an original project,-an earlier revision or one completed variant:--```text-request-captured → impact-assessed → intent-mapped → source-updated-→ gates-checked → optional preview-rendered/review-complete-→ final-checked → revision-complete → optional Build-```--The agent locates the canonical Run and validates the existing baseline. It maps natural language to-the smallest Source/Recipe/Run field, records the affected graph closure, edits only those layers,-and reruns package/Cue, `hypit check`, `preview_check` and `layout_check`. Revision performs no VLM or-reference comparison; Studio is only a display handoff after deterministic checks pass.--| Step | Agent work | Tool or document | Durable result and reason |-|---|---|---|---|-| 1. Locate baseline | Accept a completed project directory directly or locate the parent route/variant and canonical Run. | `revision_state start`, `route_state read/reconcile`, `git status` | `request.json` and a new revision id preserve the exact baseline; Revision never invents a missing reconstruction history. |-| 2. Assess impact | Decide whether the request affects geometry/style, Script/timing, graph wiring, package choice or paid generation. | `authoring.md`, current brief, component-fit, package README | `impact` and affected Source files define the smallest graph closure to invalidate. |-| 3. Map intent | Translate natural language to an authoritative field (Cue, Frame/Placement, Style, Candidate, Target, etc.). | `revision_state checkpoint`, source and graph inspection | The change is scoped before editing, preventing a casual request from rewriting unrelated files. |-| 4. Edit minimally | Modify only `main.svml`, `recipes.svs` or `build.svrun`; update runtime/package only when capability/component truly changes. | `revision/route.md`, `script-time.md`, `layout-checks.md` | Generated media and accepted Build artifacts remain untouched; source remains the authority. |-| 5. Revalidate | Run package/Cue, syntax, graph, preview and realized-layout checks; repair or accept layout candidates. | `validate_local_author_packages`, `validate_script_cues`, `hypit check`, `preview_check`, `layout_check`, `layout_accept` | `gates-checked` proves the revision is wired and measurable without invoking a visual observer. |-| 6. Finish or hand off | Persist final evidence, optionally show Studio, and Build only if generation inputs changed and cost is approved. | `revision_state`, `studio-confirmation.md`, `hypit plan/build` | A completed revision can feed another variant batch; a later request starts a new revision id. |--### `variant-expansion` (variant expansion)--The main agent makes global decisions before any child agent starts:--```text-baseline-validated → examples-inspected → format-plan-frozen → slate-drafted-→ vocabulary-enumerated → component-plan-frozen → package-gaps-classified-→ workload-disclosed → package-gaps-resolved → slate-frozen → projects-copied-→ variants-dispatched → variants-complete → aggregate-checked-→ [build-planned → build-approved → build-complete] → expansion-complete-```--Tools and outputs are:--1. `variant_state start` records the base, count, request and delivery mode.-2. `brief-intake.md`, examples and playbooks produce `format-plan.json`.-3. The main agent writes distinct direction quotas in `slate.json`; their counts add up to N. Each direction carries a shared brief and allowed file scope. `variant_init` expands the quotas into numbered concrete variants when dispatching, so a 100-item batch does not require 100 hand-written briefs.-4. `list_svml_packages` and `inspect_svml_vocabulary` produce global vocabulary evidence and- `component-plan.json`.-5. The workload disclosure tells the author how many variants are SVML-only, medium-scope or require- a new package. Each distinct package gap is solved once in staging and frozen by digest.-6. `variant_init` copies the base first, preserves author assets and Source, excludes generated state- and results, injects only ready packages and creates each child route state.-7. Child agents read their copied project, brief, plans, allowed scope, assigned README/evidence and- required playbook documents. They make the minimum change and run `validate_script_cues`,- `hypit check`, `preview_check`, `layout_check` and `variant_check`.-8. The batch aggregate check proves every child is complete. A later manual change to one child exits- this route and starts `revision` in that child directory.--Each child route is:--```text-baseline-copied → brief-frozen → change-scope-frozen → guidance-loaded-→ vocabulary-verified → package-ready → script-checked → source-updated-→ graph-checked → layout-checked → final-checked → variant-complete-```--The batch is intentionally “copy first, then edit”:--| Step | Main agent or child work | Tool or document | Durable result and reason |-|---|---|---|---|-| 1. Validate base | Confirm the parent creation/revision final gate and record its digest. | `route_state/revision_state reconcile`, `variant_state start` | Every child starts from the same known-good Film graph. |-| 2. Decide the slate | Inspect examples, choose the expansion directions and quotas whose total is N, and freeze each direction's Format DNA and allowed scope. | `brief-intake.md`, `playbooks/index.md`, `format-plan.json`, `slate.json` | Creative directions are decided once globally; dispatch expands each quota into a unique numbered child brief. |-| 3. Decide vocabulary/workload | Inspect packages and public vocabulary, choose reuse/composition/new package, then disclose fast/medium/new-package counts. | `list_svml_packages`, `inspect_svml_vocabulary`, `component-plan.json`, `variant_state checkpoint` | The author knows the cost/time impact before agents start; no child discovers a package gap halfway through. |-| 4. Stage new packages | Develop each distinct local package once, validate it in staging, freeze its digest and mark it ready. | `route_state --route variant-package`, `local-author-package.md`, `validate_local_author_packages`, `preview_check`, `layout_check` | Shared package work is reused safely and cannot mutate installed packages. |-| 5. Copy the base | Clone the project with copy-on-write where possible, retain authored assets/source, remove generated state/results and old Build bindings, inject only ready packages. | `variant_init` | Each child is independent, reproducible and free of stale paid/generated artifacts. |-| 6. Dispatch bounded work | Give each child its copied project, brief, format/component plan, README/evidence and allowed scope. | child `route_state`, `variant_state` | The batch can run in parallel while each child has an auditable contract. |-| 7. Verify and edit | Child verifies vocabulary only when its component changes, edits the minimum allowed files, and runs all mechanical gates. | `inspect_svml_vocabulary --run` when needed, `validate_script_cues`, `hypit check`, `preview_check`, `layout_check`, `variant_check` | A fast SVML-only variant stays fast; scope escapes become explicit conflicts instead of silent rewrites. |-| 8. Aggregate and deliver | Reconcile unfinished children, aggregate checks, and optionally plan/approve paid Builds. | `variant_state reconcile`, aggregate report, `hypit plan/build` | 100-item batches resume only unfinished children and never repeat a paid Build after compaction. |--## JSON state machines and recovery--State is split into a current pointer and execution-scoped history so context compression never becomes-the source of truth:--| Concern | Durable location |-|---|---|-| Creation current view | `<project>/.hypit/route-state.json` |-| Creation execution history/evidence | `<project>/.hypit/routes/<route-id>/state.json`, `.hypit/evidence/` |-| Base brief and component fit | `<project>/.hypit/brief.json`, `<project>/.hypit/component-fit.json` |-| Revision current view/history | `.hypit/revision-state.json`, `.hypit/revisions/<revision-id>/{state.json,request.json}` |-| Variant batch locator | `<base>/.hypit/variant-expansions/<batch-id>.json` |-| Variant batch state | `<batch>/.hypit/variant-expansion-state.json` |-| Child/staging state | Child or staging `.hypit/route-state.json` and route history |--Every state record contains the route id, current cursor, completed steps, `next_action`, decisions,-conflicts, last command, artifact paths and artifact digests. Machine evidence is content-addressed;-manual decisions such as the brief, component fit, format plan, Slate and allowed changes are recorded-explicitly rather than inferred from files.--A route transition is always a write of evidence, not a chat assertion:--```text-agent makes a decision or edits Source- → checkpoint records the decision and input digest-tool runs a check/render/review- → successful output is stored at an immutable evidence path-state advances only when that output satisfies the stage predicate- → current view + execution history are atomically updated-```--The state shape is intentionally small but explicit:--```json-{- "version": 1,- "route": "description",- "route_id": "...",- "current_step": "graph-checked",- "completed_steps": ["environment", "brief-frozen", "source-authored"],- "next_action": "layout_check --run build.svrun",- "decisions": { "brief": ".hypit/brief.json", "component_fit": ".hypit/component-fit.json" },- "evidence": [{ "kind": "preview_check", "path": ".hypit/evidence/...json", "digest": "..." }],- "conflicts": [],- "last_command": "hypit-reference-video-tools preview_check ..."-}+```bash+hypit-reference-video-tools render_element ./build.svrun \+ --element ranking --segment list --reference-id <reference-id> \+ --out ./review/ranking-list.mp4+hypit-reference-video-tools compare_reconstruction \+ --reference-id <reference-id> --run ./build.svrun --segment list \+ --video ./review/ranking-list.mp4 --element ranking```-`checkpoint` is for an explicit agent decision or completed command; `read` is for displaying the-durable cursor; `reconcile` recomputes only machine predicates and rolls back stale evidence; and-`discover` finds a batch locator after the agent no longer remembers its directory. A stage is never-advanced merely because a file happens to exist.+Every explicit comparison is a new observation. The tool does not hash a render and silently reuse an+older answer. `reconstruction_check` summarizes what has and has not been looked at; it does not own a+workflow cursor.-The public state commands are:+## Build and reuse-```bash-# creation routes-hypit-reference-video-tools route_state --action read --project-root <project>-hypit-reference-video-tools route_state --action checkpoint --project-root <project> \- --route <description|reconstruction> --state <stage>-hypit-reference-video-tools route_state --action reconcile --project-root <project>--# revision-hypit-reference-video-tools revision_state --action start --project-root <project> \- --run <project>/build.svrun --request '<change>'-hypit-reference-video-tools revision_state --action read --project-root <project>-hypit-reference-video-tools revision_state --action checkpoint --project-root <project> \- --step <stage-number> --status complete --decision '<what was decided>'-hypit-reference-video-tools revision_state --action reconcile --project-root <project>--# variant batch-hypit-reference-video-tools variant_state --action discover --project-root <base>-hypit-reference-video-tools variant_state --action checkpoint --project-root <base> \- --batch-id <id> --step <stage-number> --status complete-hypit-reference-video-tools variant_state --action read --project-root <base> --batch-id <id>-hypit-reference-video-tools variant_state --action reconcile --project-root <base> --batch-id <id>-```+Run `hypit plan` before paid generation when cost or external services matter. Run `hypit build` only+when the user wants the Build. The Build's public outputs are saved into its Result. Intermediate+component outputs that are public ports are saved as well, so later work can point at useful images,+videos or structured values without changing the Run target into a list of every intermediate value.-All JSON writes use a temporary file followed by atomic rename. A corrupt file is preserved and-reported, never replaced by an empty state. `reconcile` verifies each machine-step predicate, checks-parent/source/package/evidence digests, rolls stale steps back to the first unmet one and reports-conflicts. It never invents creative decisions, silently widens an allowed scope, repeats a completed-variant or resubmits a paid Build.+Repeated Builds are distinct Results even when the Run files are unchanged. Give important Results+and outputs human names through the Result presentation commands instead of inventing a content hash,+central artifact table or hidden project history.-After interruption or context compaction, read the skill and applicable route again, discover/read the-canonical state, reconcile it, inspect conflicts, and execute only the first unmet `next_action`.-This is why the skill can run a long reconstruction or a 100-variant expansion without relying on-conversation memory.+For bulk variants, use ordinary project directories and an explicit task list chosen by the caller.+Copying, scheduling and naming those projects belongs to that caller or a dedicated batch tool; the+reference-video package does not maintain a second variant state machine.diff --git a/docs/guide/testing.md b/docs/guide/testing.mdindex 3e01c4da..36c4d4ea 100644--- a/docs/guide/testing.md+++ b/docs/guide/testing.md@@ -91,8 +91,6 @@ explicitly opt-in, use no committed secret and fail before spending money unless|---|---|---|| `pnpm test:whisperx-service` | Python WhisperX service | Python 3.13, uv, frozen sync || `pnpm test:image-opencv` | the shared OpenCV Raster interpreter across both request variants | the service's own interpreter at `services/image-opencv/.venv`; set `HYPIT_OPENCV_PYTHON` to use another |-| `pnpm test:browser-visual` | rendered geometry, stacking and clipping in a real browser | a Chrome the HyperFrames CLI can start, `ffmpeg`, and `HYPIT_TEST_FONT_PATH` off macOS |-| `pnpm smoke:kie` | Live paid KIE generation | `KIE_API_KEY` |## Test fixturesdiff --git a/docs/quickstart.md b/docs/quickstart.mdindex b084ca22..88a892ef 100644--- a/docs/quickstart.md+++ b/docs/quickstart.md@@ -111,8 +111,8 @@ hypit plan build.svrunA project with `package.json` owns its third-party packages. A plain creative folder needs no Nodeproject and uses official packages from the installed Distribution. Source and exported files remain in the-project. By default, Build Results live under the project's `.hypit/results`; a Profile may point the-same complete Result model at S3. Active execution state always lives under the selected Profile's+project. By default, Build Results live under the project's `.hypit/results`; a project-owned+`hypit.results.json` may point the same complete Result model at S3. Active execution state always lives under the selected Profile's`dataRoot`.`runtime use` stores only a local pointer at `.hypit/runtime`. Source imports select authorpackages; the Profile independently selects Runtime packages through `use`.@@ -140,10 +140,10 @@ safe, but neither is required as a repetitive pre-Build ceremony.```bashhypit status <build-id> --watch-hypit queue+hypit activityhypit get <build-id> \- --name final.video \+ --output final.video \--to output/final.mp4```@@ -181,7 +181,7 @@ hypit runtime upThe Runtime creates a missing managed environment in the machine Program Home and reuses it acrossprojects and sessions. Do not run a service's `uv sync` from an author project.-Run `hypit doctor hypit.runtime.json` after changing a Runtime Profile. It reports missing tools,+Run `hypit doctor hypit.runtime.json` after changing a Runtime Profile or project Result Store. It reports missing tools,credentials and endpoint configuration without executing the graph.## Read nextdiff --git a/docs/quickstart/preview.md b/docs/quickstart/preview.mdindex cad4b949..126354cb 100644--- a/docs/quickstart/preview.md+++ b/docs/quickstart/preview.md@@ -17,7 +17,7 @@ hypit-studio --run examples/all-components-preview/studio.svrun --workspace .| Argument | Meaning || --- | --- || `--run <build.svrun>` | Run Source to open. Required. |-| `--runtime <hypit.runtime.json>` | Runtime Profile containing earlier Builds and Artifacts; required for `<build-record>`. |+| `--runtime <hypit.runtime.json>` | Optional Runtime Profile used only to show active `BuildView` and Operation information. Historical Results and `<build-record>` come from the project Result Store. || `--workspace <directory>` | Source access and writeback boundary; defaults to the Run directory. || `--port <number>` | HTTP port; defaults to `5179`. |diff --git a/docs/quickstart/run.md b/docs/quickstart/run.mdindex 5b07de4e..534ddd1d 100644--- a/docs/quickstart/run.md+++ b/docs/quickstart/run.md@@ -20,7 +20,7 @@ Ordinary work then follows the short path:```bashhypit plan build.svrunhypit build build.svrun --follow-hypit get <build-id> --name final.video --to output/final.mp4+hypit get <build-id> --output final.video --to output/final.mp4```The Quickstart installs the Distribution once. Every command on this page then works as `hypit`@@ -137,7 +137,7 @@ on `<build-record>` and use the current name on `<satisfy>`:```svml<build-record id="approved-opening"- build="bld_01234567-89ab-cdef-0123-456789abcdef" output="hook-take.video"/>+ build="bld_20260902T110000001Z_0000000001" output="hook-take.video"/><satisfy output="opening-shot.video" candidate="approved-opening"/>```@@ -145,6 +145,9 @@ Hypit never infers that two names mean the same author intent. Every `build` invfresh Build id and its own Result directory, even when nothing changed. A later Run reuses an Outputonly by naming the earlier Build id and Output here. If that earlier Output already forwards to anolder one, resolution follows the explicit chain; no bytes are copied into the new Result.+Forwarding applies only to a complete public Output. Structured JSON cannot recursively point at+another Output; a historical value consumed inside a new Fragment is an ordinary input and the new+Fragment's Output belongs to the current Result.### build-record@@ -154,7 +157,7 @@ Declares a zero-input Candidate backed by one named Output from a previous Build|---|---|| `id` | Local Candidate id within this Run Source || `build` | The automatically assigned id of the previous Build |-| `output` | The Logical Output name from that Build |+| `output` | The public Output name in that Build Result |### satisfy@@ -165,7 +168,9 @@ Connects a Candidate to a Logical Output:| `output` | The Logical Output to satisfy || `candidate` | The Candidate id (from `build-record`) |-The compiled plan prunes all upstream Operations that the selected Candidates replace. This is a+The Planner reads the complete Author Graph and Run Graph together. It prunes default Operations+that selected Candidates replace while retaining any Author Outputs the selected Candidate itself+still consumes. This is anew Build, not a continuation of the old one. Downstream processing (normalization, WhisperX,captioning, rendering) still runs against the reused media.@@ -260,7 +265,7 @@ only with `--workspace`. `--package-root` locates installed packages and never woutput/```-That is the zero-configuration Result repository. A Runtime Profile may instead select+That is the zero-configuration Result repository. A project-owned `hypit.results.json` may instead select`@hypit/build-result-s3`; commands and historical `build-record` references then use that samerepository. Runtime working Artifacts remain local and private to the Runtime.@@ -272,7 +277,7 @@ hypit runtime use hypit.runtime.json```Author and Run Sources select their packages through imports. The Runtime Profile selects its Host,-Result repository, credential and Endpoint packages through `use`. The installed package manager+credential and Endpoint packages through `use`; the project separately owns its Result repository. The installed package managerowns their versions.### 2. Diagnose the environment@@ -315,7 +320,7 @@ processes declared by Endpoints.### 4. Submit the Build```bash-hypit build build.svrun --name first-cut --follow+hypit build build.svrun --title first-cut --follow```Without `--follow`, `build` returns after durable submission. The detached Worker continues. With@@ -328,7 +333,7 @@ Attach or reattach an observer at any time:hypit status <build-id> --watch```-A plain `status <build-id>` prints one snapshot. `status --watch` exits at terminal state; use+A plain `status <build-id>` prints one snapshot. `status --watch` exits when the Result has an outcome; use`--max-wait-ms` when a script needs a bounded wait.| Flag | Description |@@ -336,8 +341,8 @@ A plain `status <build-id>` prints one snapshot. `status --watch` exits at termi| `--runtime` | One-command Runtime Profile override; normally select it once with `runtime use` || `--package-root` | Host directory containing the installed packages || `--workspace` | Explicit Source Workspace override |-| `--name` | Optional human-facing name for this independent Build |-| `--follow` | Wait for terminal state as an observer; durable execution remains with the Worker |+| `--title` | Optional human-facing Result title |+| `--follow` | Wait for a Result outcome as an observer; durable execution remains with the Worker |Each invocation creates a fresh Build id, even when the Author and Run Sources are unchanged. Thatis necessary for non-deterministic generation: cross-Build reuse belongs only to explicit Candidates@@ -355,7 +360,7 @@ public Output saved along their execution route:```bashhypit get <build-id> \- --name final.video \+ --output final.video \--to examples/talking-head-aroll/output/final.mp4```@@ -363,7 +368,7 @@ hypit get <build-id> \from that Result; a structured Output is read from its Result value file; a forwarded historicalOutput is followed to its declared earlier Result. The Runtime Profile is not involved.-The terminal Build result prints the exact `get --name …` command for every file Target;+The finished Build result prints the exact `get --output …` command for every file Target;there is no need to inspect opaque Record ids just to export `final.video`.### 6. Reuse in a new Builddiff --git a/docs/zh/guide/author-packages.md b/docs/zh/guide/author-packages.mdindex cd56fac6..b8bec17e 100644--- a/docs/zh/guide/author-packages.md+++ b/docs/zh/guide/author-packages.md@@ -218,4 +218,4 @@ pnpm install --frozen-lockfile当 vocabulary 证明输入/输出 Type、timing contract、终端 Track 和 Surface ports 高度相似,才可走 close-sibling 路径:读取该 sibling 的 README 与必要 role 文件,复制结构,重建-Module/Producer identity,并继续通过 package-ready、Source-use、preview 和最终 gate。+Module/Producer identity,并直接检查 Source 使用方式与 preview 结果。diff --git a/docs/zh/guide/runtime.md b/docs/zh/guide/runtime.mdindex 4a2a59b5..dc91df57 100644--- a/docs/zh/guide/runtime.md+++ b/docs/zh/guide/runtime.md@@ -5,19 +5,22 @@ description: Hypit Source 与 Core 之外的执行边界。# Runtime+实现审计与仍待处理的问题记录在+[Runtime 与 Build Result 实现审计](./runtime-build-result-audit.md)。+Hypit 把三个决定分开:| 所有者 | 决定什么 ||---|---|| Workspace | 编译能读取哪些 Source 和本地素材 || Runtime Profile | 允许使用哪些环境包 |-| Local Runtime | 活跃 Build 如何排队、执行和被观察 |+| Local Runtime | 活跃 Build 如何持久推进和被观察 || 项目 Build Results | 每个 Build 实际完成了哪些公开 Output |Core 是领域无关的状态机。它接收事实、派生 Command、验证 Record,不启动进程、不读取凭证、不选择 Provider,也不知道 Build 最终是不是视频。-`@hypit/runtime-local` 是默认执行环境。它自己拥有 Worker、调度器、Build 队列和 SQLite。+`@hypit/runtime-local` 是默认执行环境。它自己拥有 Worker、调度器、待提交状态、活跃执行状态和 SQLite。这些是同一个本地实现,不再伪装成需要用户逐项选择的组件。## Runtime Profile@@ -31,10 +34,6 @@ Profile 只保留真正会随环境变化的选择:"use": "@hypit/runtime-local","config": {"dataRoot": ".hypit/runtimes/local",- "results": {- "use": "@hypit/build-result-fs",- "config": { "path": ".hypit/results" }- },"credentials": {"env": { "use": "@hypit/credential-store-env" }},@@ -46,8 +45,21 @@ Profile 只保留真正会随环境变化的选择:}```-`results` 可选地指定项目的完整 Build Result 仓库;省略时就是项目里的 `.hypit/results`。-`credentials` 选择凭证存储;`endpoints` 选择明确的 Provider 实现。+`credentials` 选择凭证存储,`endpoints` 选择明确的 Provider 实现。Result 仓库不属于执行环境,+因此不能放进 Runtime Profile。++项目可以在根目录放置独立的 `hypit.results.json`:++```json+{+ "format": "hypit.build-results@1",+ "use": "@hypit/build-result-fs",+ "config": { "path": ".hypit/results" }+}+```++没有这个文件时使用同样的本地默认值。Runtime Profile 可以被多个项目复用,而每个项目仍拥有自己的+Result 地址。安装包只增加一种可选实现,不会自动激活。Profile 不包含 Workspace、作者 import 或隐藏的创作路由。@@ -72,22 +84,52 @@ Profile 只保留真正会随环境变化的选择:values/```-`check` 和 `plan` 不创建 Runtime 数据。SQLite 只保存活跃 Build 的执行事实、Provider-Operation 与队列状态;每个活跃 Build 有独立的临时字节目录。在普通的完整、失败或取消路径上,-Result 安全写完后,Definition/Facts、Operation 载荷、Catalog 和临时字节都会删除。如果失败的-正是 Result 写入本身,则保留执行状态供本地修复。Runtime 可以留一条很小的终态调度回执供-`status` 使用,但它不是历史权威。+`check` 和 `plan` 不创建 Runtime 数据。提交时先建立不可调度的暂存行;Result draft、附件和工作目录+准备完成后,一个 SQLite 事务才会让这个 Build 可领取。硬中断留下的待提交状态只能由+`hypit result discard <build-id>` 精确删除;系统不扫描或猜测。++SQLite 的 Execution 只保存活跃执行事实、Provider Operation、`wakeAt`、当前 turn、取消请求、唯一 decision+和可选 attention;不保存 phase。每个活跃 Execution 有独立临时字节目录。Result 保存与工作目录清理完成后,+Definition/Facts、Operation、Catalog、容量票据和 Execution 根在一个事务中删除。Runtime 中不存在已结束+Build 的历史行。++持久 Runtime 的每个 Build 都必须在提交完成前提供项目 Result 地址和 Author Catalog。没有 Result 的+执行不会作为另一种隐藏模式存在。历史内容属于所选的项目 Result 仓库,不属于 Runtime SQLite。使用默认仓库时,`.hypit/results/<build-id>/result.json` 记录最终 Target,以及这条执行路线上真正完成的所有公开-Author Output;媒体放在该 Result 的 `files/`,结构化值放在 `values/`。`builds`、`history`、+Author Output;Resource 字节放在该 Result 的 `files/`,Composite Value Document 放在 `values/`,+领域数据与嵌套 Resource 的路径绑定彼此分开。`builds`、`history`、`inspect`、`get` 和 `build-record` 都通过同一个仓库接口读取。提交给独立 Worker 的 Build 会带着-当时选定的仓库位置,因此之后修改 Profile 不会把已经排队的 Build 改写到别处。+当时选定的项目仓库位置;之后修改项目配置或从别的目录查询,活跃 Build 仍使用该准确地址。-使用 S3 或兼容服务时:+Author Graph 与 Run Graph 仍是两份完整的编译输入。Planner 全局应用所有 `satisfy`,求出替换后的依赖闭包,+然后才生成不可变执行 Definition:选中的初始 Record、Producer step、`Output → Record` 绑定、goal 与 Target。+Candidate id 和两张源码图都不会进入 Runtime 持久化。只有被该计划真正选中的零输入 Candidate 来源才会随后+读取,无论它指向本地值、本地文件还是历史 Output。历史 Output 若被直接选为公开 Output,Result 只保存一个+完整 Output 的转发地址;历史内容若被新 Operation 消费,则在 Build 生效前暂存一次,新产物照常属于当前 Result。++Result manifest 自己可以保存人类标题、备注和重点公开 Output。使用 `hypit result edit <build-id>`+修改的只是该 Build 的 `result.json`;它不打开 Runtime,也不建立项目级元数据索引。Studio 直接读取+这些字段,所以即使没有选择 Runtime,也能从 Result 列出历史 Build。++`running` 不是 Result 结论,也不是持久状态。Host 用活跃事实派生稳定的 `BuildView`:+`submitting / ready / running / waiting / saving-result`。CLI 和 Studio 只消费这个视图,不读取原始提交行或+Execution 持久记录。Execution 根据 `wakeAt` 与 turn 推进;+Execution 一旦写入唯一的 `complete / failed / cancelled` decision,就永远不能再被 Worker 领取。Result 在+接受公开 Output 期间没有 `outcome`,完成时写入与 decision 完全相同的 outcome。Result 或清理失败只增加+独立的 `attention = { step, error }`,不会改写 decision。历史浏览按 Build id 从新到旧只列出已有 outcome 的 Result;按+Build id 精确读取仍能看见 Result draft。++公开 Build id 固定为 `bld_YYYYMMDDTHHMMSSmmmZ_NNNNNNNNNN`。UTC 部分给 Result 自然时间顺序;末尾+随机串只用于避免同一毫秒冲突,不表达内容相等或复用。分页使用游标:`builds --before <build-id>` 与+`history ... --before <build-id>` 从上一页最后一个 id 之前继续。++使用 S3 或兼容服务时,项目的 `hypit.results.json` 改为:```json-"results": {+{+ "format": "hypit.build-results@1","use": "@hypit/build-result-s3","config": {"bucket": "my-video-results",@@ -99,19 +141,31 @@ Author Output;媒体放在该 Result 的 `files/`,结构化值放在 `valuesAWS SDK 使用它通常的凭证链;兼容服务还可以配置 `endpoint` 与 `forcePathStyle`。`prefix` 是项目边界,每个项目应使用自己的 prefix。S3 只改变完整 Build Result 的存放位置,不会把 Runtime-SQLite、队列或临时工作 Artifact 搬进 bucket。+SQLite、Provider 容量或临时工作 Artifact 搬进 bucket。++S3 adapter 会把有序 Build id 可逆地映射成“最新优先”的物理 prefix,因此对象存储可以直接返回有界+的一页,不需要中央索引或重复 catalog。Result 文件支持按字节范围流式读取,因此 Studio 预览远端+视频或音频时,不会先把完整文件装进内存。`hypit doctor [profile] --workspace <project>` 会同时主动+检查 Runtime 和项目选择的 Result Store;存储检查只做一次有上限的只读列表,不扫描历史 Result。Workspace 独立由显式 `--workspace`、Runtime 指针所在项目或入口 Source 目录确定。Runtime 配置不能扩大源码读取范围。-## 队列与并发+## Execution turn 与并发++`build` 保存一个全新 Build 后立即返回。SQLite 持久保存所有仍需要下一轮推进的 Build;Worker 只在推进+期间临时物化状态,并立即写回已经接受的 facts。没有 Build 并发配置,Build 身份也不是容量资源。++真正约束外部工作的容量只有 Endpoint 声明的 Provider 总池与其下面的模型 Lane。不同 Build 的 Command+共享这些真实容量。每项资源只有一个 `limit`:立即调用返回后释放,异步 Operation 则一直占用到终态;+互不冲突的 Build 与 Command 可以一起推进。-`build` 保存一个全新 Build 后立即返回。Worker 推进所有可运行的 Build,Core 保留每个-Build 的图依赖。Endpoint 包声明 Provider 与 capability 上限,因此不同 Build 的工作共享真正-执行它们的外部容量。+异步 Endpoint 在调用 `start` 前先保存 Operation;立即 Producer/Endpoint 在调用前先保存 command+交接状态。进程若停在“已开始但结果未落盘”的窗口,该 Build 明确失败,同一个 command 不会再次调用。-取消是尽力而为:未开始的工作直接撤回;运行中的 Build 不再接收新 Command,Endpoint 可以尝试-取消已经提交的外部 Operation。已经完成的产物永远保留,不做回滚。+取消是尽力而为:未开始的 Build 仍由 Worker 领取一次,但不会执行生成 Command,只写 Result+终态与清理;运行中的 Build 不再接收新 Command,Endpoint 可以尝试取消已经提交的外部 Operation。+已经完成并交接的 Output 保留,不做回滚。## Managed Programs@@ -139,13 +193,26 @@ hypit runtime down`runtime up` 先让 npm 把所选 Adapter 的精确上游包准备到机器共享目录,再准备 ManagedProgram 并启动本地 Worker。`build` 不做部署:它执行便宜只读预检,只在就绪后提交,并确保-Worker 可用。`status`、`queue`、`cancel` 用来观察和控制活跃工作。终态 Build 不恢复;复用-以前的 Result 必须在新的 `.svrun` 中显式写 Candidate。+Worker 可用。`activity`、`cancel` 用来观察和控制活跃工作;`status` 分别读取 Runtime 与 Result,一边失败+不会伪造或吞掉另一边的事实。没有 Runtime 时,已完成 Result 也只证明 Result 的 outcome,不能反推 Runtime。++Result 写入或活跃状态清理失败时,decision 保持不变,并记录 `attention.step = result | cleanup`。修好外部+问题后,操作人显式执行 `hypit result finish <build-id>`。它打开一次性 Result writer,不启动执行 Worker;+只读取已保存的 Build facts、已结束 Operation 值、工作字节和固定 Result Repository,不加载或调用 Producer+与 Endpoint。Result writer 核对并写入同一个 Result,再删除工作目录,最后原子删除整个 SQLite 活跃聚合。+同一个 Build 同时只能被一个 Result writer 占用;这个互斥 lease 不是 phase,也不改变 decision。+进程若硬中断,下一 Worker 只撤销遗留 lease、记录 attention,不自动执行存储动作。工作字节丢失会明确失败,不补生成。+已结束 Build 不恢复;复用以前的 Result 必须在新的 `.svrun` 中显式写 Candidate。运行中的 Worker 会在 Build 第一次需要某个已安装 Component 包时加载它。后续 Build 可以在不重启 Worker 的情况下新增 Component 包;Worker 会沿完整依赖闭包只加载尚未见过的部分。已经加载的包代码不会热更新,因此修改包代码或更新 Distribution 后,仍需等 Worker 空闲再将其停止,然后提交下一次 Build。+Worker 记录启动时规范化后的完整 Runtime Profile。Profile 在 Worker 存活期间改变时,`status` 会报告+配置已变化,`up` 会拒绝静默复用旧进程,Worker 也会停止;重新启动才会激活新环境。这里保存的是活动+进程配置文本,不是哈希,也不进入 Build Result。SQLite 另外只固定当前活跃执行使用的 credential 与+Endpoint 选择,避免新 Endpoint 配置轮询旧 handle。+Runtime 包是本地可信部署代码,其安装版本由 npm 或 pnpm 管理。Hypit 只在显式 `runtime up` /`packages install` 边界选择精确依赖并调用 npm,不维护第二份包锁,也不会把元数据冒充成沙箱。diff --git a/docs/zh/guide/skill.md b/docs/zh/guide/skill.mdindex c055a655..ff17e7ad 100644--- a/docs/zh/guide/skill.md+++ b/docs/zh/guide/skill.md@@ -1,395 +1,91 @@-----title: Hypit Skill 架构-description: Hypit skill 如何把描述或参考视频变成可检查、可恢复的项目。----+# 视频创作工作方式-# Hypit Skill 架构+Hypit 把创作、执行和结果分开:-这份文档是维护者理解 Hypit skill 的总图。skill 是由 agent 驱动的生产流程:agent 负责创意判断,-仓库工具负责把判断写成 SVML/SVS/SVRun,验证 graph,保存证据,并在中断后恢复。+- Source、Recipe、Run 描述要做什么;+- Runtime 执行一次 Build;+- Result 记录这次 Build 实际产生了什么;+- reference-video-tools 帮助作者理解、预览和检查内容,不管理 Build 历史或项目历史。-核心分工是:+项目不再维护 route 数据库、revision 历史、恢复游标或批次总状态。可继续工作的依据是项目中+真实存在的 Source、媒体和报告,而不是另一个系统对 agent 过去操作的复原。-- agent 决定视频要表达什么、应该长什么样、要改什么;-- 工具决定项目是否合法、graph 是否接通、布局和证据是否稳定;-- 视觉 observer 只报告差异,是否算问题由 agent 判断。+## 从真实需求开始-## 用户请求如何变成完整视频--```text-用户请求- → 路由选择- → 意图/参考证据- → 格式与词汇决策- → Author Source + Recipe Source + Run Source + Runtime Profile- → graph/package/Cue/layout 门禁- → 预览素材与视觉比对(创作路径)- → 修复并重复检查- → 最终确定性门禁- → Studio 确认- → 明确批准后的付费 Build-```--之所以能产出完整视频,是因为流程不止写提示词或组件:它会建立 Script 和时间关系,把所有-视觉/音频 Track 接到 Film,在 Run 中声明每个外部生成,检查 Target 是否真的可达,再把同一-个 Run 交给 Studio 或 Build。--## 路由选择与交接--| 用户输入 | 路径 | 负责内容 | 下一步 |-|---|---|---|---|-| 描述、主题、brief 或格式名,没有参考视频 | `original-authoring`(原创制作) | 意图、Hook、Script、视觉设计和完整新项目 | 最终门禁后可进 `variant-expansion`(变体扩展);之后修改进 `revision`(修改) |-| 参考视频或链接,可附带“换我的人物/产品/品牌” | `reconstruction`(复刻) | 参考证据、镜头结构、匹配 Source,以及本次初始改编 | 最终门禁后可进变体扩展;之后修改进 Revision |-| 对完成项目或完成变体的自然语言修改 | `revision`(修改) | 有边界的 Source/Recipe/Run 修改和确定性复验 | 完成后可进变体扩展,或交给 Studio/Build |-| 从已验证项目生产 N 个独立版本 | `variant-expansion`(变体扩展) | 全局格式/组件计划、包缺口、复制项目和子 agent 范围 | 每个子项目到 `variant-complete`;之后手动修改该子项目进 Revision |--复刻请求中一开始就附带的人物、产品、品牌替换仍属于复刻;只有后续再次提出自然语言修改才进入 Revision。--## 共用阶段--### 1. 环境与持久化启动--agent 选择 Distribution、独立项目目录、Runtime Profile、凭据,以及复刻路径的 observer。写作前启动对应状态机:+先判断任务是原创还是参考视频复刻,再查看现有包和它们公开的词汇:```bash-hypit-reference-video-tools route_state --action start --project-root <project> --route description-hypit-reference-video-tools route_state --action start --project-root <project> --route reconstruction+hypit-reference-video-tools list_svml_packages+hypit-reference-video-tools inspect_svml_vocabulary --package <package>+hypit-reference-video-tools inspect_visual_schema```-任何需要托管能力的命令之前必须先写 Runtime Profile,用 `hypit runtime use` 选择,用-`hypit runtime up` 准备 Worker/程序,避免参考、预览或 Build 到最后才发现执行环境未声明。+现有 Surface 能表达需要的视觉角色时直接复用。只有确实缺能力时才开发项目本地 author+package,不能为了一个项目去修改已安装包。-### 2. 建立意图或参考证据+## 原创视频-原创制作读取 `brief-intake.md`,检查 `examples/` 中语义匹配的完整项目,恢复其意图而不是复制-Source,选择格式 playbook,并冻结 `.hypit/brief.json`。brief 记录受众、Hook、叙事推进、-视觉/音频/文字关系、事实声明和未决决策。--复刻先准备视频并缓存媒体和全片证据:+用最小的 Source、Recipe、Run 表达需求,然后分别查看它们的真实情况:```bash-hypit-reference-video-tools prepare_reference --video-path <file-or-link> --observer <observer>-hypit-reference-video-tools observe_reference --reference-id <id>+hypit-reference-video-tools validate_local_author_packages --run ./build.svrun+hypit-reference-video-tools validate_script_cues --run ./build.svrun+hypit check ./build.svrun+hypit-reference-video-tools preview_check ./build.svrun+hypit-reference-video-tools layout_check --run ./build.svrun```-准备阶段提供媒体元数据、transcript/alignment 和参考观察包;全片观察提供持久系统、人物/声音、-视觉类型和声音上下文。镜头观察和窄问题解决不能从单帧安全推断的结构。这样复刻依据的是持久-证据,而不是 agent 对视频的短期记忆,所以可以重建整条视频。--### 3. 在写 Source 前确定格式和词汇+这些命令是相互独立的报告,不会互相批准或解锁。只有报告和设计需求共同说明存在实际问题时+才修改项目。布局测量只是候选提示;有意的几何关系可以用 `layout_accept` 写下理由。这个理由+关联的是可读的结构发现名称,不是整个项目快照。-主 agent 读取 `playbooks/index.md`、选定格式和其 footer 链接的 craft 文档,枚举视觉/音频系统,运行:+需要看具体视觉时,直接渲染相关元素和时间窗口,再按照明确的创作意图阅读结果:```bash-hypit-reference-video-tools list_svml_packages-hypit-reference-video-tools inspect_svml_vocabulary --package <candidate> [--package ...]-hypit-reference-video-tools inspect_visual_contract-```--`inspect_svml_vocabulary` 是已安装 Surface 的公开契约;visual contract 提供 Visual Element 形状、-允许的样式、枚举值和 seal 不变量。agent 在 `.hypit/component-fit.json` 中为每个系统记录:-复用现有包、复用并接受少量差异,或开发项目本地包。普通情况下不需要读取已安装包源码;只有-确认复制 close sibling 作为实现骨架时才读取被复制包的必要 role 文件。--确定存在真实缺口后,先完成包 staging 路径:--```text-gap-confirmed → guidance-loaded → types-frozen → implemented-→ vocabulary-inspected → package-validated → graph-checked-→ layout-checked → package-ready+hypit-reference-video-tools render_element ./build.svrun \+ --element title --segment intro --out ./review/title-intro.mp4+hypit-reference-video-tools review_element --run ./build.svrun \+ --element title --segment intro --video ./review/title-intro.mp4 \+ --intent-file ./review/title-intent.md```-包必须有 Manifest、Surface、Fragment、Producer、Validator、activation 和 preview,并且被项目-Source 导入、被 graph 使用;`validate_local_author_packages` 是包门禁。--原创或复刻路线完成后,可以考虑是否贡献项目本地包。阅读 Skill 参考文档 `references/package-promotion.md`,当组件在无关-视频中也有明确且很高的复用价值时,再向用户提出贡献建议。用户同意后,将它移入 Hypit 仓库的-`packages/` 文件夹并准备 Pull Request;普通的一次性组件留在项目内部。这是完成后的可选建议,-不会打断制作流程,也不会自动修改仓库。--### 4. 编写四个项目源文件--| 文件 | 职责 |-|---|---|-| `main.svml` | Script、叙事、组件声明、提示词和语义时间引用 |-| `recipes.svs` | 样式、外观、playback、布局等 Recipe 值 |-| `build.svrun` | Author 绑定、Candidate、satisfy 和 Target |-| `hypit.runtime.json` | Runtime 包、Provider、凭据和本地执行 |+`authoring_check` 可以汇总画面覆盖、播放策略和已经记录的 review,但它不是项目状态,也不是+提交 Build 的前置条件。-Script 先于镜头生成:Segment 定义 Take 边界,Cue 保证字幕可读,`estimate:Speech` 提供确定性时长。-Source 中每个生成和 graph edge 都显式写出,因此后续检查能定位问题。+## 参考视频复刻-### 5. 确定性 graph 与布局门禁--视觉比对前运行:+先准备参考视频:```bash-hypit-reference-video-tools validate_script_cues --run <run>-hypit check <run>-hypit-reference-video-tools preview_check <run>-hypit-reference-video-tools layout_check --run <run>-```--它们分别回答:--- package/Cue 检查:项目包和 Script 边界是否可用;-- `hypit check`:Source 语法、引用和 graph 结构是否合法;-- `preview_check`:Track 是否通过包接到 Film;-- `layout_check`:在隐藏浏览器中实现真实 composition,报告内部上下偏移、父级/Canvas 越界、稳定状态下顶层组件重叠等候选。--布局发现只是交给 agent 的辅助证据,不是自动真相。agent 修复真实问题,或用 `layout_accept` 记录有意几何,然后重跑 `layout_check`,直到候选消失或被接受。相关 Source、Recipe、包、字体或 runtime 改动会使证据失效。--视觉检查和机械布局检查使用两条不同的抽取规则:--| 检查 | 抽取规则 | 为什么这样做 |-|---|---|---|-| 视觉检查 | 每种不同视觉声明/样式变化,在首次出现处取一个**完整片段**。 | 完整片段保留出现、移动、离开和瞬时视觉差异;样式不变时无需因为每句 caption 或每个时间点重复检查。 |-| 机械布局检查 | 每个 `Present` 在自己的**最长稳定区间**取一帧。 | 稳定帧才能测量真实 DOM,避免把正常动画过程误报成越界或偏移。 |--两条规则不能互换:视觉检查对照 brief 或参考视频判断完整片段;`layout_check` 只测量真实布局并把结果作为候选交给 Agent。内容极值和时间极值不是额外选片规则:稳定越界由逐个 `Present` 的测量发现,瞬时或媒体内部的问题由完整片段的视觉检查负责。--### 6. 创作路径的视觉检查与修复--原创制作使用 `authoring_check`,复刻使用 `reconstruction_check`。命令读取 Source,按上面的视觉规则生成检查计划。最长稳定区间取样只属于另外的隐藏浏览器 `layout_check`,不属于视觉检查。--每个计划项按以下闭环执行:--```text-render_element → 预览/mock 素材 → 视觉 observer/reviewer-→ 记录发现 → agent 修复 Source/Recipe/组件决策 → 重跑门禁-```--复刻通过 `compare_reconstruction` 与对应参考片段比对;原创通过 `review_element`/`record_review` 与冻结 brief 比对。observer 报告看到的差异,agent 判断是缺陷、有意设计还是组件判断错误。不能复制或修改已安装包来强行贴合。修复后重复计划和机械门禁,直到最终检查通过。--### 7. 最终门禁、Studio 和 Build--`authoring_check` 或 `reconstruction_check` 是最终确定性门禁,要求 package/Cue、graph、layout 和-视觉检查/比对证据都仍然有效。通过后才按 `studio-confirmation.md` 生成 estimate 时长的预览并在-Studio 打开当前 Run。Studio 确认是付费前对结构的人工确认,不等同视觉比对;只有明确批准费用后才提交 `hypit build`。--## 四条路径的完整流程--### `original-authoring`(原创制作)--```text-environment → brief-frozen → examples/格式/craft 决策-→ vocabulary/component-fit → package-ready → Script 与四个源文件-→ script-checked → source-authored → graph-checked → layout-checked-→ review-planned → preview-rendered → review-complete → repairs-complete-→ final-checked → Studio 确认 → 可选 Build+hypit-reference-video-tools prepare_reference --video-path ./reference.mp4 --observer agent+hypit-reference-video-tools observe_reference --reference-id <reference-id>```-它先冻结观众结果,再选择格式和词汇,最后写出 Film 所需的所有语义和 graph edge;因为没有参考视频,后续视觉检查以 `brief.json` 为意图依据。--| 步骤 | Agent 做什么 | 工具或文档 | 持久化结果与作用 |-|---|---|---|---|-| 1. 启动 | 选择 Distribution、项目目录、runtime 和凭据,启动路线快照。 | `environment.md`、`runtime.md`、`route_state start`、`hypit paths`、`hypit runtime use/up` | 在写 Source 前就有可运行项目和恢复游标。 |-| 2. 把描述变成可执行 brief | 确定受众、Hook、承诺、节拍、事实声明、人物以及视觉/音频/文字关系;检查完整语义 examples,但不复制其 Source。 | `brief-intake.md`、`examples/` | `.hypit/brief.json` 冻结“什么算正确”,后续检查不靠模糊的“看起来不错”。 |-| 3. 冻结格式与 craft | 选择匹配的 playbook,并读取它要求的全部 craft 文档。原创时,在写生成提示词前先为反复出现的人物、产品、声音、地点、服装、灯光和道具建立锚点,再在各个 take 中复用。 | `playbooks/index.md`、`formats/*.md`、`craft/visual-continuity.md`、`craft/persona-and-audio.md`、`craft/generated-dependencies.md` | 即使没有参考视频,也能得到明确的时间模型、镜头语法、字幕规则,以及跨镜头的人物、场景和物品连续性。 |-| 4. 适配组件 | 枚举候选包,检查公开词汇,决定复用、接受少量差异,或开发项目本地包。 | `list_svml_packages`、`inspect_svml_vocabulary`、`inspect_visual_contract`、`vocabulary.md`、`component-fit.json` | 每个视觉角色在写 Source 前就有合法的 Module/Tag/Recipe 契约;真实缺口通过 `local-author-package.md` 一次解决。 |-| 5. 写 Script | 把旁白切成 Segment/Take 和短 Cue;每个镜头只承担一个明确任务,时间保持语义化。 | `script-time.md`、`authoring.md` | `main.svml` 包含完整的说话/文字推进和确定性的 `estimate:Speech` 时长。 |-| 6. 接通项目 | 编写 `main.svml`、`recipes.svs`、`build.svrun`、`hypit.runtime.json`;显式声明每个生成、Track、Candidate、satisfy 和 Target。 | `authoring.md`、`runtime.md` | Film graph 是完整、可复现的,不是一个提示词加上一堆互不相连的素材。 |-| 7. 证明 Source 与 graph | 运行包、Cue、语法、graph tracing 和真实布局门禁。 | `validate_local_author_packages`、`validate_script_cues`、`hypit check`、`preview_check`、`layout_check` | 项目合法、每条 Track 都能到达 Film,并且在视觉检查前已经测过浏览器布局。 |-| 8. 生成视觉检查计划 | 让路线检查为每种不同视觉声明/样式变化在首次出现处生成一个完整片段。 | `authoring_check` | `.hypit/evidence/` 记录必须检查的内容;Agent 不会漏掉样式变化,也不用手写 render 列表。最长稳定区间由独立的 `layout_check` 取样。 |-| 9. 渲染并检查 | 生成计划中的 preview/mock 片段,逐项对照冻结的 brief,记录发现。 | `render_element`、`review_element`、`record_review`、`element-review.md`、`conformance-round.md` | 每种视觉系统都有证据,覆盖文字适配、画面覆盖、对比度、运动和几何。 |-| 10. 修复并收口 | 只修复确认的问题,重跑受影响门禁和检查项,再运行最终路线检查。 | 有意几何用 `layout_accept`;最终用 `authoring_check` | `final-checked` 表示视觉、graph、包、Cue、布局证据都没有过期。 |-| 11. 交接 | 创建 estimate 时长的 preview-mock Run,先披露每个付费能力实际使用的 Provider 与凭据来源,再打开 Studio、披露费用,获批准后才 Build。缺少或不可用的 key 引导前往 https://hypit.ai 获取 HypiHub key。 | `preview-mock.md`、`studio-confirmation.md`、`hypit plan/build/status/inspect/get` | Studio 看到的是活的 Film graph;付费 Build 复用已检查的 Run,产出完整交付。 |+拆出的镜头、代表帧、逐词转录和观察结果保存在 `.hypit/reference-video-tools/`。它们本身就是+有用内容。使用 `agent` observer 时,`record_observation` 负责填写明确返回的待回答观察。-### `reconstruction`(复刻)+根据画面、文字和时间信息创作项目。需要比较时,把相关元素在相同 Script 窗口中渲染出来:-```text-environment → reference-prepared → reference-observed-→ examples/格式/craft 决策 → vocabulary/component-fit → package-ready-→ Script 与四个源文件 → script-checked → source-authored → graph-checked-→ layout-checked → review-planned → preview-rendered → comparison-complete-→ repairs-complete → final-checked → 初始改编 → 再跑 final check-→ Studio 确认 → 可选 Build-```--视频先被转换成可恢复的观察证据;观察定义人物、持久系统、镜头边界、文字和视觉关系,Source-再把它们表达为 Segment、Take、Track 和 Film edge。每轮把渲染结果与对应参考片段比对,修复后重跑,直到整条视频的最终门禁通过。--复刻的顺序必须这样安排,因为它要重建的是整条参考视频,而不是一个截图:--| 步骤 | Agent 做什么 | 工具或文档 | 持久化结果与作用 |-|---|---|---|---|-| 1. 准备参考 | 选择一次 observer,接收本地文件或下载并缓存链接视频,启动路线状态。 | `observers.md`、`credentials.md`、`prepare_reference`、`route_state start` | 得到稳定的 reference id、媒体元数据和 observer;恢复时不会换文件或换观察者。 |-| 2. 观察全片 | 运行固定的全片观察,读取 transcript/alignment、持久视觉系统、人物/声音、视觉类型和声音上下文。 | `observe_reference`、`evidence.md` | 全片证据说明视频中到底有哪些镜头和系统,是重建所有镜头的依据,不是挑一帧模仿。 |-| 3. 解决结构疑点 | 检查 shot 边界;单帧无法确定外观、转场或关系时,用窄问题补证据。 | `observe_reference --question`、`continuity.md`、`reconstruction/vocabulary.md` | 把歧义写入证据后再写 Source,时间和连续性不靠对话记忆猜。 |-| 4. 选择格式与组件 | 检查 examples/playbooks,枚举候选包,检查公开词汇,确认是否真的缺包。 | `brief-intake.md`、`playbooks/index.md`、`list_svml_packages`、`inspect_svml_vocabulary`、`component-fit.json` | 每个观察到的视觉角色都有合法组件;安装包保持不可变。 |-| 5. 写出忠实 Source | 把 transcript 和观察结果转成 Script 的 Segment/Take/Cue,再写四个源文件和所有 graph edge。 | `final-sources.md`、`authoring.md`、`script-time.md`、`runtime.md` | Source 描述完整参考时间线,包括旁白、叠加层、B-roll、转场、音频和 Target。 |-| 6. 证明基线 | 运行 Run 级词汇/包/Cue 检查、语法、graph tracing 和真实布局。 | `inspect_svml_vocabulary --run`、`validate_local_author_packages`、`validate_script_cues`、`hypit check`、`preview_check`、`layout_check` | 只有每条声明的 Track 都确实能产出时,才进入昂贵的视觉比对。 |-| 7. 生成比对计划 | 找出每种不同声明以及它覆盖的每个参考片段,保留稳定区间和 shot 边界。 | `reconstruction_check`、`comparison-round.md`、`element-review.md` | 计划覆盖整条视频,而不是挑一个好看的静帧;每项都有自己的 reference token 范围和渲染窗口。 |-| 8. 渲染并比对 | 用同一个 Run 渲染所有计划片段,再把参考/渲染成对交给指定 observer。 | `render_element --batch`、`compare_reconstruction --batch` | observer 报告可见差异,同时保留参考与渲染的对应关系和时间范围。 |-| 9. 修复复刻结果 | Agent 根据证据判断每条发现,修改 Source/Recipe 或组件决策;绝不复制/修改安装包。 | `reconstruction/route.md`、`layout-checks.md`、`layout_accept` | 真问题被修复;有意裁切、重叠或偏移可以记录理由,不破坏包边界。 |-| 10. 重新确认忠实基线 | 重跑比对和确定性门禁,直到“复刻本身”通过。 | `reconstruction_check`、`preview_check`、`layout_check` | 把忠实复刻证据与后续用户定制分开。 |-| 11. 应用初始改编 | 这时才把用户要求的人物、产品或品牌替换到已完成的复刻中。重跑路线检查和确定性门禁;由用户改编产生的差异不能被静默当成包缺陷。 | `main.svml`/`recipes.svs`/`build.svrun`、`reconstruction_check`、`hypit check`、`preview_check`、`layout_check` | 参考证据保持诚实,交付的母项目包含用户改编;这仍是 reconstruction,不是 Revision。 |-| 12. 交接 | 在 Studio 展示已检查 Run,明确列出每个付费 Provider/凭据来源并批准费用后才 Build;key 不足时先引导 HypiHub。 | `studio-confirmation.md`、`hypit plan/build` | 同一个已检查 graph 进入付费生成;之后的新自然语言修改才路由到 Revision。 |--复刻的数据流是:--```text-参考视频字节- ├─ transcript/alignment ───────────────→ Script 的 Segment、Cue、estimate:Speech- ├─ 全片观察 ──────────────────────────→ 人物、声音、持久视觉/音频系统- └─ 镜头观察与窄问题 ──────────────────→ shot 边界、状态和元素关系- ↓- main.svml + recipes.svs + build.svrun + runtime profile- ↓- Track → package → Film → Target- ↓- preview_check → 比对计划 → 渲染/比对每个应检查的片段- ↓- Agent 修复 → 确定性门禁 → Studio/Build-```--这就是“能复刻整条视频”的完整性保证:观察到的每段话都变成有时长的 Script,观察到的每个-视觉/音频角色都变成 Track 或由包实现的元素,并且在任何付费生成前,每条 Track 都必须能追到 Film。--### `revision`(修改)--Revision 可直接接收完成项目,也可接收复刻、原创、旧 Revision 或完成变体:--```text-request-captured → impact-assessed → intent-mapped → source-updated-→ gates-checked → 可选 preview-rendered/review-complete-→ final-checked → revision-complete → 可选 Build-```--agent 先定位 canonical Run 并验证基线,再把自然语言映射到最小 Source/Recipe/Run 字段,记录受-影响的 graph closure,只修改这些层并重跑 package/Cue、`hypit check`、`preview_check`、`layout_check`。-Revision 不调用 VLM 或参考比对;Studio 只是确定性检查通过后的显示交接。--| 步骤 | Agent 做什么 | 工具或文档 | 持久化结果与作用 |-|---|---|---|---|-| 1. 定位基线 | 可直接接收完成项目目录,也可定位父路线/变体和 canonical Run。 | `revision_state start`、`route_state read/reconcile`、`git status` | `request.json` 和新的 revision id 固定准确基线;不会凭空补造复刻历史。 |-| 2. 判断影响 | 判断请求影响几何/样式、Script/时间、graph、包选择还是付费生成。 | `authoring.md`、当前 brief、component-fit、包 README | `impact` 和受影响 Source 文件定义最小失效 graph closure。 |-| 3. 映射意图 | 把自然语言映射到权威字段,例如 Cue、Frame/Placement、Style、Candidate 或 Target。 | `revision_state checkpoint`、Source 与 graph 检查 | 先定范围再编辑,避免一个小请求重写无关文件。 |-| 4. 最小修改 | 只改 `main.svml`、`recipes.svs` 或 `build.svrun`;只有能力/组件真的变化才改 runtime/包。 | `revision/route.md`、`script-time.md`、`layout-checks.md` | 不碰 MP4、PNG、WAV、preview mock 或 Artifact;Source 始终是权威。 |-| 5. 重新验证 | 运行包/Cue、语法、graph、preview 和真实布局检查,修复或接受布局候选。 | `validate_local_author_packages`、`validate_script_cues`、`hypit check`、`preview_check`、`layout_check`、`layout_accept` | `gates-checked` 证明修改已接通且可测,不调用视觉 observer。 |-| 6. 完成或交接 | 保存最终证据,可选打开 Studio;只有生成输入变化并获费用批准才 Build。 | `revision_state`、`studio-confirmation.md`、`hypit plan/build` | 完成的 Revision 可以继续做变体;下一次修改会创建新的 revision id。 |--### `variant-expansion`(变体扩展)--主 agent 在任何子 agent 启动前完成全局决策:--```text-baseline-validated → examples-inspected → format-plan-frozen → slate-drafted-→ vocabulary-enumerated → component-plan-frozen → package-gaps-classified-→ workload-disclosed → package-gaps-resolved → slate-frozen → projects-copied-→ variants-dispatched → variants-complete → aggregate-checked-→ [build-planned → build-approved → build-complete] → expansion-complete-```--具体工作和产物:--1. `variant_state start` 记录母项目、数量、请求和交付模式。-2. `brief-intake.md`、examples 和 playbooks 生成 `format-plan.json`。-3. 主 agent 在 `slate.json` 中写出若干个不重复的变体方向和数量配额,所有配额之和正好为 N;每个方向声明共享 brief 和允许修改的文件范围。`variant_init` 在派发时再确定性展开成带编号的具体变体,因此 100 个变体不需要主 agent 手写 100 个 brief。-4. `list_svml_packages` 与 `inspect_svml_vocabulary` 形成全局词汇证据和 `component-plan.json`。-5. 工作量披露快速(只改 SVML)、中等(改 SVS/Run 或切换组件)和新包任务;每种新包只在 staging 开发一次,并以 digest 冻结。-6. `variant_init` 先复制母项目,保留作者资产和 Source,排除生成状态/结果,只注入已就绪的包,并建立每个子项目的 route state。-7. 子 agent 读取自己的项目、brief、plan、允许范围、指定 README/证据和 playbook,只做最小修改,然后运行 `validate_script_cues`、`hypit check`、`preview_check`、`layout_check`、`variant_check`。-8. 批次 aggregate check 证明所有子项目完成。之后对某个子项目的手动修改离开本路径,进入该目录的 Revision。--每个变体子项目使用:--```text-baseline-copied → brief-frozen → change-scope-frozen → guidance-loaded-→ vocabulary-verified → package-ready → script-checked → source-updated-→ graph-checked → layout-checked → final-checked → variant-complete-```--变体路线刻意采用“先复制、后修改”:--| 步骤 | 主 agent 或子 agent 的工作 | 工具或文档 | 持久化结果与作用 |-|---|---|---|---|-| 1. 验证母项目 | 确认父路线/Revision 已通过最终门禁并记录 digest。 | `route_state/revision_state reconcile`、`variant_state start` | 所有子项目从同一个已知良好的 Film graph 出发。 |-| 2. 决定 Slate | 检查 examples,决定变体方向及数量配额(总和为 N),冻结每个方向的 Format DNA 和允许范围。 | `brief-intake.md`、`playbooks/index.md`、`format-plan.json`、`slate.json` | 创意方向一次全局决定;派发时按方向配额展开唯一编号的子项目。 |-| 3. 决定词汇和工作量 | 检查包与公开词汇,决定复用/组合/新包,并披露快速、中等、新包数量。 | `list_svml_packages`、`inspect_svml_vocabulary`、`component-plan.json`、`variant_state checkpoint` | 子 agent 启动前用户就知道时间和成本影响,不会做到一半才发现缺包。 |-| 4. 预先开发新包 | 每个不同缺口只开发一次,在 staging 验证、冻结 digest、标记 ready。 | `route_state --route variant-package`、`local-author-package.md`、`validate_local_author_packages`、`preview_check`、`layout_check` | 多个变体安全复用同一个包,且不会修改安装包。 |-| 5. 先复制母项目 | 尽可能 copy-on-write,保留作者资产和 Source,删除生成状态/结果和旧 Build 绑定,只注入已 ready 的包。 | `variant_init` | 每个子项目独立、可复现,没有过期的付费产物或生成结果。 |-| 6. 分批派发 | 给每个子 agent 自己的目录、brief、格式/组件计划、README/证据和允许范围。 | 子项目 `route_state`、`variant_state` | 可以并行处理,同时每个变体都有可审计的任务契约。 |-| 7. 验证并最小修改 | 组件变化时才在副本中检查词汇,只改允许文件,运行所有机械门禁。 | 需要时 `inspect_svml_vocabulary --run`、`validate_script_cues`、`hypit check`、`preview_check`、`layout_check`、`variant_check` | 只改 SVML 的任务保持快速;越界修改会成为显式冲突,不会静默扩大。 |-| 8. 汇总交付 | 恢复未完成子项目,运行 aggregate check;需要成片时再计划/批准付费 Build。 | `variant_state reconcile`、aggregate report、`hypit plan/build` | 100 项批次只恢复未完成项,且上下文压缩后不会重复付费 Build。 |--## JSON 状态机与恢复--状态拆成当前指针和执行范围内的历史,避免上下文压缩成为唯一记忆来源:--| 内容 | 持久化位置 |-|---|---|-| 创作当前视图 | `<project>/.hypit/route-state.json` |-| 创作历史/证据 | `<project>/.hypit/routes/<route-id>/state.json`、`.hypit/evidence/` |-| brief 与组件判断 | `<project>/.hypit/brief.json`、`<project>/.hypit/component-fit.json` |-| Revision 当前视图/历史 | `.hypit/revision-state.json`、`.hypit/revisions/<revision-id>/{state.json,request.json}` |-| 变体批次 locator | `<base>/.hypit/variant-expansions/<batch-id>.json` |-| 变体批次状态 | `<batch>/.hypit/variant-expansion-state.json` |-| 子项目/staging 状态 | 子项目或 staging 的 `.hypit/route-state.json` 及其 history |--每份状态记录 route id、当前游标、完成步骤、`next_action`、决策、冲突、最后命令、证据路径和 digest。-机器证据可由工具确认;brief、component fit、format plan、Slate、allowed changes 等人工决策必须明确写入,不能从文件存在与否推断。--路线状态的每次推进都必须写入证据,不能只依赖聊天中的一句“完成了”:--```text-Agent 做出决策或修改 Source- → checkpoint 写入决策和输入 digest-工具执行检查/渲染/评审- → 成功结果写入不可变 evidence 路径-只有结果满足该步骤的成功谓词,状态才推进- → 当前视图和执行历史原子更新-```--状态结构保持精简,但关键字段明确:--```json-{- "version": 1,- "route": "description",- "route_id": "...",- "current_step": "graph-checked",- "completed_steps": ["environment", "brief-frozen", "source-authored"],- "next_action": "layout_check --run build.svrun",- "decisions": { "brief": ".hypit/brief.json", "component_fit": ".hypit/component-fit.json" },- "evidence": [{ "kind": "preview_check", "path": ".hypit/evidence/...json", "digest": "..." }],- "conflicts": [],- "last_command": "hypit-reference-video-tools preview_check ..."-}+```bash+hypit-reference-video-tools render_element ./build.svrun \+ --element ranking --segment list --reference-id <reference-id> \+ --out ./review/ranking-list.mp4+hypit-reference-video-tools compare_reconstruction \+ --reference-id <reference-id> --run ./build.svrun --segment list \+ --video ./review/ranking-list.mp4 --element ranking```-`checkpoint` 用于记录明确的 Agent 决策或已完成命令;`read` 用于读取持久化游标;`reconcile`-只重新计算机器成功谓词并让过期证据回滚;`discover` 用于 Agent 不再记得批次目录时通过 locator 找回批次。-文件存在本身永远不能推进状态。+每次明确发起的比较都是一次新的观察。工具不会根据文件摘要静默复用旧答案。+`reconstruction_check` 只汇总哪些内容看过、哪些没看过,不持有工作流游标。-常用接口:+## Build 与复用-```bash-# 创作路径-hypit-reference-video-tools route_state --action read --project-root <project>-hypit-reference-video-tools route_state --action checkpoint --project-root <project> \- --route <description|reconstruction> --state <stage>-hypit-reference-video-tools route_state --action reconcile --project-root <project>--# Revision-hypit-reference-video-tools revision_state --action start --project-root <project> \- --run <project>/build.svrun --request '<change>'-hypit-reference-video-tools revision_state --action read --project-root <project>-hypit-reference-video-tools revision_state --action checkpoint --project-root <project> \- --step <stage-number> --status complete --decision '<what was decided>'-hypit-reference-video-tools revision_state --action reconcile --project-root <project>--# 变体批次-hypit-reference-video-tools variant_state --action discover --project-root <base>-hypit-reference-video-tools variant_state --action checkpoint --project-root <base> \- --batch-id <id> --step <stage-number> --status complete-hypit-reference-video-tools variant_state --action read --project-root <base> --batch-id <id>-hypit-reference-video-tools variant_state --action reconcile --project-root <base> --batch-id <id>-```+外部生成涉及费用时先运行 `hypit plan`;用户需要执行时再运行 `hypit build`。Build 的公开输出+进入它自己的 Result。组件公开输出端口产生的中间图片、视频或结构值也会保存,因此后续工作+可以直接指向它们,不需要把 Run target 偷换成所有中间值的清单。-所有 JSON 都先写临时文件再原子 rename。损坏文件会被保留并报错,不会被空状态覆盖。`reconcile`-验证每个机器步骤的成功谓词,检查父路径、Source、包和证据 digest,把过期步骤回滚到第一个未-完成步骤并报告冲突;它不会发明创意决策、静默扩大 allowed scope、重复完成变体或重新提交付费 Build。+即使 Run 文件完全没变,多次 Build 仍然得到互相独立的 Result。重要的 Result 和输出使用+Result presentation 命令赋予人类名称,不建立内容摘要、中心 artifact 表或隐藏历史系统。-中断或上下文压缩后,重新读取 skill 和对应路径,发现/读取 canonical state,执行 reconcile,检查冲突,-然后只执行第一个未完成的 `next_action`。因此长时间复刻和 100 项变体批次都不依赖对话记忆。+批量变体使用普通项目目录和调用者明确维护的任务清单。复制、调度和命名属于调用者或专门的+批处理工具;reference-video-tools 不再维护第二套 variant 状态机。diff --git a/docs/zh/guide/testing.md b/docs/zh/guide/testing.mdindex 9dff4416..164f0e57 100644--- a/docs/zh/guide/testing.md+++ b/docs/zh/guide/testing.md@@ -80,8 +80,6 @@ test("generates a video", async (t) => {|---|---|---|| `pnpm test:whisperx-service` | Python WhisperX 服务 | Python 3.13、uv、frozen sync || `pnpm test:image-opencv` | OpenCV 图像变换 | 服务自带的解释器,位于 `services/image-opencv/.venv`;要用别的解释器就设 `HYPIT_OPENCV_PYTHON` |-| `pnpm test:browser-visual` | 真实浏览器中的渲染几何、层叠与裁剪 | HyperFrames CLI 能启动的 Chrome、`ffmpeg`;非 macOS 还需 `HYPIT_TEST_FONT_PATH` |-| `pnpm smoke:kie` | 实时付费的 KIE 生成 | `KIE_API_KEY` |## 测试 fixturesdiff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.mdindex c8f37fcc..88cc1b8e 100644--- a/docs/zh/quickstart.md+++ b/docs/zh/quickstart.md@@ -108,7 +108,7 @@ hypit plan build.svrun含有 `package.json` 的项目负责自己的第三方包;普通创作文件夹不需要成为 Node 项目,直接使用Distribution 里的官方包。默认情况下,完整 Build Result 位于项目的 `.hypit/results`;Profile-也可以把同一套 Result 模型指向 S3。Runtime 活跃状态与临时 Artifact 始终位于所选 Profile 的+不管理 Result,项目根的 `hypit.results.json` 可以把同一套 Result 模型指向 S3。Runtime 活跃状态与临时 Artifact 始终位于所选 Profile 的`dataRoot`。`runtime use` 只在 `.hypit/runtime` 保存一个本地指针。Source import 选择作者包,Profile 则通过 `use` 独立选择 Runtime 包。@@ -134,15 +134,15 @@ Build 前必须重复的仪式。```bashhypit status <build-id> --watch-hypit queue+hypit activityhypit get <build-id> \- --name final.video \+ --output final.video \--to output/final.mp4```-Runtime 会归档所有已经接受的中间 Record 和媒体。`get` 只负责把某个归档结果复制到便于人查看的位置,-不会决定哪些中间结果应该被保存。+Build Result 会保存目标路径上已经完成的所有公开 Author Output,包括媒体和结构化值。`get`+只负责按唯一公开名称读取或复制某个 Output,不会决定哪些中间结果应该被保存。## 真实 Build 可能使用的本地工具@@ -166,7 +166,7 @@ hypit runtime upRuntime 只会在机器 Program Home 中缺少托管环境时创建它,随后被所有项目和会话复用。不要在创作项目里手动执行服务的 `uv sync`。-修改 Runtime Profile 后运行 `hypit doctor hypit.runtime.json`。它会报告缺少的工具、凭据和+修改 Runtime Profile 或项目 Result Store 后运行 `hypit doctor hypit.runtime.json`。它会报告缺少的工具、凭据和Endpoint 配置,但不会执行作者图。## 接下来读什么diff --git a/docs/zh/quickstart/preview.md b/docs/zh/quickstart/preview.mdindex f0c50ad3..954ee905 100644--- a/docs/zh/quickstart/preview.md+++ b/docs/zh/quickstart/preview.md@@ -17,7 +17,7 @@ hypit-studio --run examples/all-components-preview/studio.svrun --workspace .| 参数 | 含义 || --- | --- || `--run <build.svrun>` | 要打开的 Run Source。必填。 |-| `--runtime <hypit.runtime.json>` | 选择包含早先 Build 与 Artifact 的 Runtime Profile;使用 `<build-record>` 时需要。 |+| `--runtime <hypit.runtime.json>` | 可选,只用于显示活动 `BuildView` 与 Operation;历史 Result 与 `<build-record>` 来自项目 Result Store。 || `--workspace <directory>` | Source 访问与写回边界;默认是 Run 所在目录。 || `--port <number>` | HTTP 端口,默认 `5179`。 |diff --git a/docs/zh/quickstart/run.md b/docs/zh/quickstart/run.mdindex b1b0e6d7..df36c661 100644--- a/docs/zh/quickstart/run.md+++ b/docs/zh/quickstart/run.md@@ -18,7 +18,7 @@ hypit runtime use hypit.runtime.json```bashhypit plan build.svrunhypit build build.svrun --follow-hypit get <build-id> --name final.video --to output/final.mp4+hypit get <build-id> --output final.video --to output/final.mp4```快速开始只需全局安装一次 Distribution。此后本页所有命令都直接写作 `hypit`,在任何独立视频项目中都一样。@@ -120,11 +120,12 @@ hypit history --source ./main.svml```svml<build-record id="approved-opening"- build="bld_01234567-89ab-cdef-0123-456789abcdef" output="hook-take.video"/>+ build="bld_20260902T110000001Z_0000000001" output="hook-take.video"/><satisfy output="opening-shot.video" candidate="approved-opening"/>```Hypit 永远不会猜测两个名字代表同一份作者意图。每次执行 `build` 都会得到新的 Build id 和独立 Result 目录,即使源码完全没变。后续 Run 只有明确写出旧 Build id 与 Output 时才复用;若旧 Output 本身继续转发到更老的 Result,就沿显式关系向前解析,不把文件复制进新 Result。+转发只适用于完整的公开 Output;结构化 JSON 不能在内部递归指向另一个 Output。历史值若只是新 Fragment 的一项输入,Fragment 产生的新 Output 仍属于当前 Result。### build-record@@ -134,7 +135,7 @@ Hypit 永远不会猜测两个名字代表同一份作者意图。每次执行 `|---|---|| `id` | 此 Run Source 内的本地 Candidate 标识符 || `build` | 先前 Build 自动分配的 id |-| `output` | 该 Build 中的逻辑输出名 |+| `output` | 该 Build Result 中的公开 Output 名 |### satisfy@@ -145,7 +146,7 @@ Hypit 永远不会猜测两个名字代表同一份作者意图。每次执行 `| `output` | 要满足的逻辑输出 || `candidate` | Candidate 标识符(来自 `build-record`) |-编译后的计划会裁剪所选 Candidate 取代的上游 Operation。这是一次新的 Build,而非旧 Build 的延续。下游处理(归一化、WhisperX、字幕生成、渲染)仍然会对复用的媒体执行。+Planner 会同时读取完整 Author Graph 与 Run Graph:裁剪所选 Candidate 替代掉的默认 Operation,同时保留该 Candidate 自身仍然消费的 Author Output。这是一次新的 Build,而非旧 Build 的延续。下游处理(归一化、WhisperX、字幕生成、渲染)仍然会对复用的媒体执行。Core 不再给 Candidate 标注 `exact` 或 `substitute`。选择 Candidate 本身就是这次运行的明确实现决定。系统校验类型兼容性,但不猜测创作等价性,也不把这种判断作为冗余元信息沿整条图传播。@@ -250,7 +251,7 @@ output/每次 Build 的权威结果位于 `.hypit/results/<build-id>/`:`result.json` 记录名字、状态、Target和公开 Output,媒体在 `files/`,结构化值在 `values/`。-这是无需配置的默认 Result 仓库。Runtime Profile 也可以选择 `@hypit/build-result-s3`;历史命令+这是无需配置的默认 Result 仓库。项目根的 `hypit.results.json` 也可以选择 `@hypit/build-result-s3`;历史命令与 `.svrun` 中的 `build-record` 会使用同一个仓库。Runtime 临时 Artifact 仍由 Runtime 在本地私有管理。@@ -313,7 +314,7 @@ status` 用于观察,`programs up|status|down` 只管理外部程序。### 4. 提交 Build```bash-hypit build build.svrun --name first-cut --follow+hypit build build.svrun --title first-cut --follow```不带 `--follow` 时,Build 在耐久提交后退出,后台 Worker 继续。带 `--follow` 时终端也只是观察者,并会报告 phase / Operation 数量变化;Ctrl-C 不会取消任务。@@ -324,14 +325,14 @@ hypit build build.svrun --name first-cut --followhypit status <build-id> --watch```-普通的 `status <build-id>` 只打印一次快照。`status --watch` 会在 Build 进入终态时退出;脚本需要限制等待时间时可以加 `--max-wait-ms`。+普通的 `status <build-id>` 只打印一次快照。`status --watch` 会在 Result 得到 outcome 时退出;脚本需要限制等待时间时可以加 `--max-wait-ms`。| 标志 | 说明 ||---|---|| `--runtime` | 单次命令的 Runtime Profile 覆盖;通常用 `runtime use` 选择一次即可 || `--package-root` | 存放已安装包的 Host 目录 || `--workspace` | 显式 Source Workspace 覆盖项 |-| `--name` | 给这次独立 Build 一个供人阅读的名字 |+| `--title` | 给这次 Result 一个供人阅读的标题 || `--follow` | 将 Build 进度流式输出到终端 |每次执行都会创建新的 Build id,即使 Author Source 和 Run Source 完全没变。这是非确定性生成@@ -349,13 +350,13 @@ hypit inspect <build-id>```bashhypit get <build-id> \- --name final.video \+ --output final.video \--to examples/talking-head-aroll/output/final.mp4````get` 解析一个精确的 `build + output` 地址并按需复制。文件从所属 Result 复制,结构化 Output从 Result 的值文件读取,历史转发则沿显式关系找到前一个 Result;整个过程不需要 Runtime Profile。-Build 的最终输出会为每个文件 Target 打印精确的 `get --name …` 命令。+Build 的最终输出会为每个文件 Target 打印精确的 `get --output …` 命令。### 6. 在新 Build 中复用@@ -374,4 +375,4 @@ hypit runtime down`runtime down` 只会让 Worker 停止领取新 Build,并保留外部程序;只有确实要停掉这些程序时才执行 `programs down`。两条命令都不会取消耐久 Build 或远程 Provider 工作。再次启动同一-Profile 后,会继续其中尚未完成的 dispatch。+Profile 后,会继续其中尚未完成的执行。diff --git a/package.json b/package.jsonindex 19998e4f..d52f9b8c 100644--- a/package.json+++ b/package.json@@ -44,11 +44,8 @@"docs:build": "vitepress build docs","docs:preview": "vitepress preview docs","test": "node test/run.mjs",- "test:release": "node --import tsx --test test/repository-hygiene.test.mjs","test:whisperx-service": "uv run --project services/whisperx --frozen python -m unittest discover -s services/whisperx/tests -p \"test_*.py\"",- "test:browser-visual": "node test/run.mjs browser-visual","test:image-opencv": "node test/run.mjs image-opencv",- "smoke:kie": "node --import tsx packages/provider-kie/test/live-smoke.ts","hypit": "node bin/hypit.mjs","studio": "pnpm --filter @hypit/studio exec node --import tsx start.ts"},diff --git a/packages/audio-track/test/audio-track.test.ts b/packages/audio-track/test/audio-track.test.tsindex f682312c..43f82cc0 100644--- a/packages/audio-track/test/audio-track.test.ts+++ b/packages/audio-track/test/audio-track.test.ts@@ -214,7 +214,7 @@ test("Selection and Moment each place one independent item", () => {assert.deepEqual(track.clips.map((clip) => clip.target.startSample), [48_000, 144_000]);});-test("one Track with overlaps and two peer Tracks compile to the same deterministic mix facts", () => {+test("one Track with overlaps and two peer Tracks compile to the same mix", () => {const sourceA = media("a", 48_000);const sourceB = media("b", 48_000);const first = { ...programTrack(sourceA, spec({ id: "a" })), id: "first" };@@ -240,9 +240,6 @@ test("one Track with overlaps and two peer Tracks compile to the same determinispeerPlan.clips.map(({ id: _id, ...clip }) => clip),combinedPlan.clips.map(({ id: _id, ...clip }) => clip),);- const localReceived = structuredClone(peerPlan);- const remoteReceived = JSON.parse(JSON.stringify(peerPlan)) as typeof peerPlan;- assert.deepEqual(localReceived, remoteReceived);});test("dynamic Fragment keeps every material and temporal dependency as an explicit input", () => {diff --git a/packages/build-result-fs/README.md b/packages/build-result-fs/README.mdindex e205afb0..efc8bbd5 100644--- a/packages/build-result-fs/README.md+++ b/packages/build-result-fs/README.md@@ -1,19 +1,23 @@# `@hypit/build-result-fs`Default project Build Result repository backed by ordinary files. The local Runtime uses-`.hypit/results` when `results` is omitted from its Profile, so a normal checkout needs no account or+`.hypit/results` when the project has no `hypit.results.json`, so a normal checkout needs no account orexternal service.An explicit selection can move the same repository elsewhere:```json{- "results": {- "use": "@hypit/build-result-fs",- "config": { "path": ".hypit/results" }- }+ "format": "hypit.build-results@1",+ "use": "@hypit/build-result-fs",+ "config": { "path": ".hypit/results" }}```-Relative paths are resolved from the Runtime Profile's directory. Each Build owns one directory with-its `result.json`, public files and structured values. There is no project-wide history database.+Relative paths are resolved from the project root. Each Build owns one directory with+its `result.json`, public Resource files and Composite Value Documents. A Value Document keeps+domain data separate from its nested Resource-path bindings. There is no project-wide history database.+Directories use the ordered public Build id, so browsing sorts names newest first and continues with+an explicit `before` cursor; only the requested Result manifests are opened. File reads support byte+ranges. Active diagnosis checks the selected directory (or its nearest+existing parent) for read/write access without creating a probe file.diff --git a/packages/build-result-fs/src/activation.ts b/packages/build-result-fs/src/activation.tsindex 2eda0f8c..c7a0a1de 100644--- a/packages/build-result-fs/src/activation.ts+++ b/packages/build-result-fs/src/activation.ts@@ -1,4 +1,6 @@-import { resolve } from "node:path";+import { constants } from "node:fs";+import { access, stat } from "node:fs/promises";+import { dirname, resolve } from "node:path";import { FileBuildResultRepository } from "@hypit/build-result";import { buildResultConfigExact, buildResultConfigObject, buildResultConfigString, createBuildResultRepositoryHostFacet } from "@hypit/build-result-kit";@@ -20,6 +22,36 @@ const filesystemBuildResultRepository = createBuildResultRepositoryHostFacet({repository: new FileBuildResultRepository(resolve(context.root, path)),};},+ async doctor(context) {+ const config = buildResultConfigObject(context.config, "filesystem Build Result Repository");+ const selected = buildResultConfigString(config.path, "Build Result path");+ if (selected === undefined) return [];+ const target = resolve(context.root, selected);+ let current = target;+ try {+ while (true) {+ const found = await stat(current).catch((error: unknown) => {+ if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined;+ throw error;+ });+ if (found !== undefined) {+ if (!found.isDirectory()) throw new Error(`${current} is not a directory`);+ await access(current, constants.R_OK | constants.W_OK);+ return [];+ }+ const parent = dirname(current);+ if (parent === current) throw new Error(`no existing parent directory for ${target}`);+ current = parent;+ }+ } catch (error) {+ return [{+ severity: "error" as const,+ code: "RESULT_REPOSITORY_UNAVAILABLE",+ message: error instanceof Error ? error.message : String(error),+ subject: target,+ }];+ }+ },});export const hypitPackage = {diff --git a/packages/build-result-kit/README.md b/packages/build-result-kit/README.mdindex 1a3e6f68..aff2608b 100644--- a/packages/build-result-kit/README.md+++ b/packages/build-result-kit/README.md@@ -5,6 +5,6 @@ Build manifests, public Outputs and their files. Runtime working Artifacts and astate are separate concerns.The selected repository is opened before submission and its serializable location travels with the-queued Build. A detached Worker therefore writes to the original destination even if the project's+active Build. A detached Worker therefore writes to the original destination even if the project'sactive Runtime Profile changes later. Repository packages implement one interface; Core and authorcomponents do not branch on filesystem, S3 or service type.diff --git a/packages/build-result-kit/src/index.ts b/packages/build-result-kit/src/index.tsindex 082c7193..f2fadd3b 100644--- a/packages/build-result-kit/src/index.ts+++ b/packages/build-result-kit/src/index.ts@@ -26,9 +26,18 @@ export type BuildResultRepositoryOpened = {readonly close?: () => void | Promise<void>;};+export type BuildResultRepositoryDiagnostic = {+ readonly severity: "error" | "warning" | "info";+ readonly code: string;+ readonly message: string;+ readonly subject?: string;+};+export type BuildResultRepositoryAdapter = {validate(context: BuildResultRepositoryContext): void;open(context: BuildResultRepositoryContext): BuildResultRepositoryOpened | Promise<BuildResultRepositoryOpened>;+ /** Active, read-only reachability/permission diagnosis for the selected backing store. */+ doctor?(context: BuildResultRepositoryContext): readonly BuildResultRepositoryDiagnostic[] | Promise<readonly BuildResultRepositoryDiagnostic[]>;};export type BuildResultRepositoryHostFacet = HostFacet & {@@ -45,12 +54,17 @@ export function createBuildResultRepositoryHostFacet(options: {readonly use: string;readonly validate: BuildResultRepositoryAdapter["validate"];readonly open: BuildResultRepositoryAdapter["open"];+ readonly doctor?: BuildResultRepositoryAdapter["doctor"];}): BuildResultRepositoryHostFacet {assert(options.use.trim().length > 0, "Build Result Repository use name is empty");return {abi: buildResultRepositoryHostAbi,offers: [options.use],- implementation: { validate: options.validate, open: options.open },+ implementation: {+ validate: options.validate,+ open: options.open,+ ...(options.doctor === undefined ? {} : { doctor: options.doctor }),+ },};}@@ -58,7 +72,10 @@ export function isBuildResultRepositoryHostFacet(value: HostFacet): value is Buiif (value.abi !== buildResultRepositoryHostAbi || value.offers?.length !== 1) return false;const implementation = value.implementation as Partial<BuildResultRepositoryAdapter> | null;return (- implementation !== null && typeof implementation === "object" && typeof implementation.validate === "function" && typeof implementation.open === "function"+ implementation !== null && typeof implementation === "object"+ && typeof implementation.validate === "function"+ && typeof implementation.open === "function"+ && (implementation.doctor === undefined || typeof implementation.doctor === "function"));}@@ -89,6 +106,17 @@ export class BuildResultRepositoryRegistry {adapter.validate(context);return await adapter.open(context);}++ async doctor(+ selection: BuildResultRepositorySelection,+ root: string,+ ): Promise<readonly BuildResultRepositoryDiagnostic[]> {+ const adapter = this.#adapters.get(selection.use);+ assert(adapter !== undefined, `Build Result Repository ${selection.use} is not installed`);+ const context = { root, config: selection.config ?? {} };+ adapter.validate(context);+ return await adapter.doctor?.(context) ?? [];+ }}export function buildResultConfigObject(value: CanonicalValue, subject: string): Record<string, CanonicalValue> {diff --git a/packages/build-result-s3/README.md b/packages/build-result-s3/README.mdindex 7b592dd1..b5b3169b 100644--- a/packages/build-result-s3/README.md+++ b/packages/build-result-s3/README.md@@ -1,18 +1,17 @@# `@hypit/build-result-s3`Opt-in S3-compatible repository for complete project Build Results. It stores Build manifests,-structured values and public files under one project prefix; Runtime working Artifacts remain local+Composite Value Documents and public Resource files under one project prefix; Runtime working Artifacts remain localto the selected Runtime implementation.```json{- "results": {- "use": "@hypit/build-result-s3",- "config": {- "bucket": "my-video-results",- "prefix": "projects/episode-12",- "region": "us-east-1"- }+ "format": "hypit.build-results@1",+ "use": "@hypit/build-result-s3",+ "config": {+ "bucket": "my-video-results",+ "prefix": "projects/episode-12",+ "region": "us-east-1"}}```@@ -21,7 +20,7 @@ to the selected Runtime implementation.optional. The AWS SDK uses its normal credential chain, so credentials stay outside the Profile.`endpoint` and `forcePathStyle` support compatible object stores.-Objects keep the same visible shape as the filesystem repository:+The repository exposes the same logical shape as the filesystem adapter:```text<prefix>/@@ -31,8 +30,19 @@ Objects keep the same visible shape as the filesystem repository:values/...```-There is no global Build table or shared Result namespace. A reused historical Output is a+Filesystem and S3 use the same Record-to-Result encoder. The adapter only writes the selected+relative document or byte path; it does not interpret domain values. A Value Document keeps canonical+domain data separate from the paths of nested Resources.++Physical object prefixes use a reversible descending-time form derived from the ordered Build id, so+S3 can return a newest-first delimiter page directly. This is only adapter key layout: callers still+address `build + output`, and no index object or global Build table exists. A reused historical Output is asmall forward reference to its producing Build and Output; following several such references stillreads the original file and does not upload another copy. While a Build is running, a private writerfile records only the state needed to continue publishing completed public Outputs and is removed when-the Result becomes terminal.+the Result receives its outcome.++Object listing uses a bounded cursor page. File reads accept normalized byte ranges, allowing Studio to+stream remote video and audio without buffering the complete object. The adapter's active doctor uses+one bounded prefix listing to verify credentials, bucket access and endpoint reachability; it creates+no probe object and reads no Result manifest.diff --git a/packages/build-result-s3/src/activation.ts b/packages/build-result-s3/src/activation.tsindex 4f7d04fe..c739ee80 100644--- a/packages/build-result-s3/src/activation.ts+++ b/packages/build-result-s3/src/activation.ts@@ -8,6 +8,25 @@ import {import { S3BuildResultRepository } from "./repository.js";+function repositoryFromConfig(configValue: Parameters<typeof buildResultConfigObject>[0]): S3BuildResultRepository {+ const config = buildResultConfigObject(configValue, "S3 Build Result Repository");+ const bucket = buildResultConfigString(config.bucket, "S3 bucket");+ if (bucket === undefined) throw new Error("S3 bucket is required");+ const prefix = buildResultConfigString(config.prefix, "S3 prefix");+ const expectedBucketOwner = buildResultConfigString(config.expectedBucketOwner, "S3 expectedBucketOwner");+ const region = buildResultConfigString(config.region, "S3 region");+ const endpoint = buildResultConfigString(config.endpoint, "S3 endpoint");+ const forcePathStyle = buildResultConfigBoolean(config.forcePathStyle, "S3 forcePathStyle");+ return new S3BuildResultRepository({+ bucket,+ ...(prefix === undefined ? {} : { prefix }),+ ...(expectedBucketOwner === undefined ? {} : { expectedBucketOwner }),+ ...(region === undefined ? {} : { region }),+ ...(endpoint === undefined ? {} : { endpoint }),+ ...(forcePathStyle === undefined ? {} : { forcePathStyle }),+ });+}+const s3BuildResultRepository = createBuildResultRepositoryHostFacet({use: "@hypit/build-result-s3",validate(context) {@@ -21,24 +40,27 @@ const s3BuildResultRepository = createBuildResultRepositoryHostFacet({buildResultConfigBoolean(config.forcePathStyle, "S3 forcePathStyle");},open(context) {- const config = buildResultConfigObject(context.config, "S3 Build Result Repository");- const bucket = buildResultConfigString(config.bucket, "S3 bucket");- if (bucket === undefined) throw new Error("S3 bucket is required");- const prefix = buildResultConfigString(config.prefix, "S3 prefix");- const expectedBucketOwner = buildResultConfigString(config.expectedBucketOwner, "S3 expectedBucketOwner");- const region = buildResultConfigString(config.region, "S3 region");- const endpoint = buildResultConfigString(config.endpoint, "S3 endpoint");- const forcePathStyle = buildResultConfigBoolean(config.forcePathStyle, "S3 forcePathStyle");- const repository = new S3BuildResultRepository({- bucket,- ...(prefix === undefined ? {} : { prefix }),- ...(expectedBucketOwner === undefined ? {} : { expectedBucketOwner }),- ...(region === undefined ? {} : { region }),- ...(endpoint === undefined ? {} : { endpoint }),- ...(forcePathStyle === undefined ? {} : { forcePathStyle }),- });+ const repository = repositoryFromConfig(context.config);return { repository, close: async () => await repository.close() };},+ async doctor(context) {+ const repository = repositoryFromConfig(context.config);+ try {+ await repository.diagnose();+ return [];+ } catch (error) {+ const config = buildResultConfigObject(context.config, "S3 Build Result Repository");+ const bucket = buildResultConfigString(config.bucket, "S3 bucket") ?? "unknown";+ return [{+ severity: "error" as const,+ code: "RESULT_REPOSITORY_UNAVAILABLE",+ message: error instanceof Error ? error.message : String(error),+ subject: `s3://${bucket}`,+ }];+ } finally {+ await repository.close();+ }+ },});export const hypitPackage = {diff --git a/packages/build-result-s3/src/client.ts b/packages/build-result-s3/src/client.tsindex 5cf68dab..7475d4e2 100644--- a/packages/build-result-s3/src/client.ts+++ b/packages/build-result-s3/src/client.ts@@ -10,13 +10,18 @@ import {UploadPartCommand,} from "@aws-sdk/client-s3";import type { S3ClientConfig } from "@aws-sdk/client-s3";+import type { BuildResultFileRange } from "@hypit/build-result";export type BuildResultS3Client = {put(key: string, bytes: Uint8Array, mediaType: string): Promise<void>;putStream(key: string, chunks: AsyncIterable<Uint8Array>, mediaType: string): Promise<void>;get(key: string): Promise<Uint8Array | undefined>;- open(key: string): Promise<AsyncIterable<Uint8Array> | undefined>;- list(prefix: string): Promise<readonly string[]>;+ open(key: string, range?: BuildResultFileRange): Promise<AsyncIterable<Uint8Array> | undefined>;+ list(prefix: string, options?: {+ readonly limit?: number;+ readonly after?: string;+ readonly delimiter?: string;+ }): Promise<readonly string[]>;delete(key: string): Promise<void>;close?(): void | Promise<void>;};@@ -180,12 +185,13 @@ export class AwsBuildResultS3Client implements BuildResultS3Client {}}- async open(key: string): Promise<AsyncIterable<Uint8Array> | undefined> {+ async open(key: string, range?: BuildResultFileRange): Promise<AsyncIterable<Uint8Array> | undefined> {try {const response = await this.#client.send(new GetObjectCommand({Bucket: this.#bucket,Key: key,+ ...(range === undefined ? {} : { Range: `bytes=${range.start}-${range.endExclusive - 1}` }),...this.#owner(),}),);@@ -200,7 +206,14 @@ export class AwsBuildResultS3Client implements BuildResultS3Client {}}- async list(prefix: string): Promise<readonly string[]> {+ async list(prefix: string, options: {+ readonly limit?: number;+ readonly after?: string;+ readonly delimiter?: string;+ } = {}): Promise<readonly string[]> {+ if (options.limit !== undefined && (!Number.isSafeInteger(options.limit) || options.limit < 1)) {+ throw new Error("S3 list limit must be a positive safe integer");+ }const keys: string[] = [];let continuationToken: string | undefined;do {@@ -208,11 +221,18 @@ export class AwsBuildResultS3Client implements BuildResultS3Client {new ListObjectsV2Command({Bucket: this.#bucket,Prefix: prefix,+ ...(options.after === undefined ? {} : { StartAfter: options.after }),+ ...(options.delimiter === undefined ? {} : { Delimiter: options.delimiter }),+ ...(options.limit === undefined ? {} : { MaxKeys: Math.min(1_000, options.limit - keys.length) }),...(continuationToken === undefined ? {} : { ContinuationToken: continuationToken }),...this.#owner(),}),);- keys.push(...(response.Contents ?? []).flatMap((item) => (item.Key === undefined ? [] : [item.Key])));+ keys.push(+ ...(response.CommonPrefixes ?? []).flatMap((item) => item.Prefix === undefined ? [] : [item.Prefix]),+ ...(response.Contents ?? []).flatMap((item) => item.Key === undefined ? [] : [item.Key]),+ );+ if (options.limit !== undefined && keys.length >= options.limit) return keys.slice(0, options.limit);continuationToken = response.IsTruncated === true ? response.NextContinuationToken : undefined;} while (continuationToken !== undefined);return keys;diff --git a/packages/build-result-s3/src/repository.ts b/packages/build-result-s3/src/repository.tsindex 695793ff..b0b630df 100644--- a/packages/build-result-s3/src/repository.ts+++ b/packages/build-result-s3/src/repository.ts@@ -1,34 +1,28 @@import type {BuildResultFileRef,+ BuildResultFileRange,BuildResultFinish,- BuildResultJsonValue,+ BuildResultValueDocument,BuildResultManifest,- BuildResultOutput,+ BuildResultPresentationUpdate,BuildResultRepository,BuildResultSeed,BuildResultSync,BuildResultWriter,- HistoricalBuildOutputRef,+ BuildResultWriterState,RepositoryBuildResultOutput,} from "@hypit/build-result";-import type { BlobRef, BuildState, StoredValue, TypedRecord } from "@hypit/protocol";+import {+ applyBuildResultPresentation,+ assertBuildResultValueDocument,+ assertBuildResultSeed,+ syncBuildResultOutputs,+} from "@hypit/build-result";+import { assertOrderedBuildId, buildIdCreatedAt } from "@hypit/protocol";import { AwsBuildResultS3Client } from "./client.js";import type { AwsBuildResultS3ClientOptions, BuildResultS3Client } from "./client.js";-type WriterState = {- readonly resources: Readonly<Record<string, string>>;- readonly aliases: readonly {- readonly name: string;- readonly output: string;- }[];- readonly reuses: readonly {- readonly candidate: string;- readonly build: string;- readonly output: string;- }[];-};-export type S3BuildResultRepositoryOptions = AwsBuildResultS3ClientOptions & {readonly prefix?: string;readonly client?: BuildResultS3Client;@@ -45,9 +39,17 @@ function normalizePrefix(value: string | undefined): string {return normalized;}-function safeBuild(build: string): string {- assert(build.trim().length > 0 && !build.includes("/") && !build.includes("\\"), "Build id is not a repository name");- return build;+function physicalBuild(build: string): string {+ assertOrderedBuildId(build);+ const createdAt = buildIdCreatedAt(build)!;+ const descendingTime = (Number.MAX_SAFE_INTEGER - createdAt).toString().padStart(16, "0");+ return `${descendingTime}-${build}`;+}++function publicBuild(physical: string): string | undefined {+ if (!/^\d{16}-bld_/u.test(physical)) return undefined;+ const build = physical.slice(17);+ return buildIdCreatedAt(build) === undefined || physicalBuild(build) !== physical ? undefined : build;}function safePath(path: string): string {@@ -56,51 +58,6 @@ function safePath(path: string): string {return path;}-function safeName(value: string): string {- const safe = value- .trim()- .replace(/[^a-zA-Z0-9._-]+/gu, "-")- .replace(/^-+|-+$/gu, "");- return safe.length === 0 ? "output" : safe;-}--function valueFileName(output: string): string {- return `${encodeURIComponent(output)}.json`;-}--function mediaExtension(mediaType: string): string {- const subtype = mediaType.split("/", 2)[1]?.split(";", 1)[0]?.trim().toLowerCase();- if (subtype === undefined || subtype.length === 0) return ".bin";- const conventional = subtype === "jpeg" ? "jpg" : subtype === "x-wav" ? "wav" : subtype;- const suffix = conventional.includes("+") ? conventional.slice(0, conventional.indexOf("+")) : conventional;- const safe = suffix.replace(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "");- return safe.length === 0 ? ".bin" : `.${safe}`;-}--function scalar(value: unknown): value is null | boolean | number | string {- return value === null || ["boolean", "number", "string"].includes(typeof value);-}--function isBlobRef(value: unknown): value is BlobRef {- if (value === null || Array.isArray(value) || typeof value !== "object") return false;- const item = value as Readonly<Record<string, unknown>>;- return item.kind === "blob" && typeof item.resource === "string" && typeof item.size === "number" && typeof item.mediaType === "string";-}--function resourceIdentity(artifact: BlobRef): string {- assert(artifact.resource !== undefined, "Build resource has no instance identity; the producing Store must return BlobRef.resource");- return artifact.resource;-}--function outputRecord(state: BuildState, output: string): TypedRecord | undefined {- const selection = state.plan.selections.find((item) => item.output === output);- return selection === undefined ? undefined : state.records.find((item) => item.id === selection.record);-}--function outputCandidate(state: BuildState, output: string): string | undefined {- return state.plan.selections.find((item) => item.output === output)?.candidate;-}-function encodeJson(value: unknown): Uint8Array {return new TextEncoder().encode(`${JSON.stringify(value, null, 2)}\n`);}@@ -130,124 +87,41 @@ class S3BuildResultWriter implements BuildResultWriter {async sync(input: BuildResultSync): Promise<BuildResultManifest> {const manifest = await this.read();- if (manifest.status !== "running") return manifest;+ if (manifest.outcome !== undefined) return manifest;const writer = await this.#repository.readWriter(this.#build);assert(writer !== undefined, `Build Result ${this.#build} has no writer state`);- const resources = new Map(Object.entries(writer.resources));- const outputs: Record<string, BuildResultOutput> = { ...manifest.outputs };- const materialize = async (artifact: BlobRef, preferredName: string): Promise<BuildResultFileRef> => {- if (artifact.origin !== undefined) {- return {- kind: "build-file",- build: artifact.origin.build,- path: artifact.origin.path,- size: artifact.size,- mediaType: artifact.mediaType,- };- }- const identity = resourceIdentity(artifact);- let path = resources.get(identity);- if (path === undefined) {- const base = safeName(preferredName);- let candidate = `files/${base}${mediaExtension(artifact.mediaType)}`;- let counter = 2;- const occupied = new Set(resources.values());- while (occupied.has(candidate)) {- candidate = `files/${base}-${counter}${mediaExtension(artifact.mediaType)}`;- counter += 1;- }- path = candidate;- resources.set(identity, path);- const chunks = await input.resources.open(artifact);- if (chunks === undefined) throw new Error(`Build resource ${identity} is unavailable`);- await this.#repository.writeFile(this.#build, path, chunks, artifact.mediaType);- }- return {- kind: "build-file",- path,- size: artifact.size,- mediaType: artifact.mediaType,- };- };- const convert = async (value: unknown, preferredName: string): Promise<BuildResultJsonValue> => {- if (isBlobRef(value)) return await materialize(value, preferredName);- if (scalar(value)) return value;- if (Array.isArray(value)) {- return await Promise.all(value.map(async (item, index) => await convert(item, `${preferredName}-${index + 1}`)));- }- assert(typeof value === "object", `Build Output ${preferredName} contains a non-canonical value`);- return Object.fromEntries(- await Promise.all(- Object.entries(value as Readonly<Record<string, unknown>>).map(async ([key, item]) => [key, await convert(item, `${preferredName}-${key}`)] as const),- ),- );- };- const outputValue = async (name: string, value: StoredValue): Promise<BuildResultOutput["value"]> => {- if (value.kind === "blob") return await materialize(value, name);- if (scalar(value.value)) return { kind: "inline", value: value.value };- const path = `values/${valueFileName(name)}`;- await this.#repository.writeJson(this.#build, path, await convert(value.value, name));- return { kind: "json", path };- };- const reuses = new Map(writer.reuses.map((item) => [item.candidate, item]));- const outputRank = (record: TypedRecord, reused: { readonly build: string; readonly output: string } | undefined): number =>- reused !== undefined ? 0 : record.value.kind === "blob" ? 1 : scalar(record.value.value) ? 2 : 3;- const ready = writer.aliases- .flatMap((alias) => {- const record = outputRecord(input.state, alias.output);- if (record === undefined) return [];- const reused = reuses.get(outputCandidate(input.state, alias.output) ?? "");- return [{ alias, record, reused }];- })- .sort((left, right) => {- return outputRank(left.record, left.reused) - outputRank(right.record, right.reused) || left.alias.name.localeCompare(right.alias.name);- });- for (const { alias, record, reused } of ready) {- const value: BuildResultOutput["value"] =- reused === undefined- ? await outputValue(alias.name, record.value)- : ({- kind: "build-output",- build: reused.build,- output: reused.output,- } satisfies HistoricalBuildOutputRef);- outputs[alias.name] = { type: record.type, value };- }- const now = Date.now();- const status = input.state.status === "complete" ? "complete" : input.state.status === "failed" ? "failed" : manifest.status;- const updated: BuildResultManifest = {- ...manifest,- updatedAt: now,- status,- ...(status === "running" ? {} : { finishedAt: manifest.finishedAt ?? now }),- outputs,- };- await this.#repository.writeWriter(this.#build, {- ...writer,- resources: Object.fromEntries(resources),+ const updated = await syncBuildResultOutputs({+ manifest,+ writer,+ sync: input,+ target: {+ writeResource: async (path, artifact, source) => {+ const chunks = await source.open(artifact);+ if (chunks === undefined) throw new Error(`Build resource ${artifact.resource} is unavailable`);+ await this.#repository.writeFile(this.#build, path, chunks, artifact.mediaType);+ },+ writeValue: async (path, document) => {+ await this.#repository.writeJson(this.#build, path, document);+ },+ },});- await this.#repository.writeManifest(this.#build, updated);- if (status !== "running") await this.#repository.deleteWriter(this.#build);- return updated;+ await this.#repository.writeWriter(this.#build, updated.writer);+ await this.#repository.writeManifest(this.#build, updated.manifest);+ return updated.manifest;}async finish(input: BuildResultFinish): Promise<BuildResultManifest> {const manifest = await this.read();- if (manifest.status !== "running") {- if (manifest.status !== input.status || input.failure === undefined || manifest.failure !== undefined) return manifest;- const updated = {- ...manifest,- failure: input.failure,- updatedAt: Date.now(),- };- await this.#repository.writeManifest(this.#build, updated);- return updated;+ if (manifest.outcome !== undefined) {+ assert(manifest.outcome === input.outcome && manifest.failure === input.failure,+ `Build Result ${manifest.id} is already finished with a different outcome`);+ await this.#repository.deleteWriter(this.#build);+ return manifest;}const now = Date.now();const updated: BuildResultManifest = {...manifest,- status: input.status,- updatedAt: now,+ outcome: input.outcome,finishedAt: manifest.finishedAt ?? now,...(input.failure === undefined ? {} : { failure: input.failure }),};@@ -268,7 +142,7 @@ export class S3BuildResultRepository implements BuildResultRepository {}#key(build: string, path: string): string {- const relative = `${safeBuild(build)}/${safePath(path)}`;+ const relative = `${physicalBuild(build)}/${safePath(path)}`;return this.#prefix.length === 0 ? relative : `${this.#prefix}/${relative}`;}@@ -289,11 +163,11 @@ export class S3BuildResultRepository implements BuildResultRepository {await this.writeJson(build, "result.json", manifest);}- async readWriter(build: string): Promise<WriterState | undefined> {- return await this.#readJson<WriterState>(build, ".writer.json");+ async readWriter(build: string): Promise<BuildResultWriterState | undefined> {+ return await this.#readJson<BuildResultWriterState>(build, ".writer.json");}- async writeWriter(build: string, state: WriterState): Promise<void> {+ async writeWriter(build: string, state: BuildResultWriterState): Promise<void> {await this.writeJson(build, ".writer.json", state);}@@ -302,27 +176,35 @@ export class S3BuildResultRepository implements BuildResultRepository {}async create(seed: BuildResultSeed): Promise<BuildResultWriter> {+ assertOrderedBuildId(seed.id);+ assertBuildResultSeed(seed);assert((await this.read(seed.id)) === undefined, `Build Result ${seed.id} already exists`);- assert(seed.name === undefined || seed.name.trim().length > 0, "Build Result name must not be empty");- const now = seed.startedAt ?? Date.now();+ for (const forward of seed.forwards ?? []) {+ assert(await this.resolve(forward.build, forward.sourceOutput) !== undefined,+ `Build ${forward.build} has no Output ${forward.sourceOutput}`);+ }const manifest: BuildResultManifest = {- format: "hypit.build-result@1",+ format: "hypit.build-result@2",id: seed.id,- ...(seed.name === undefined ? {} : { name: seed.name }),+ ...(seed.title === undefined ? {} : { title: seed.title }),source: seed.source,...(seed.run === undefined ? {} : { run: seed.run }),targets: [...seed.targets],- startedAt: now,- updatedAt: now,- status: "running",outputs: {},};- await this.writeManifest(seed.id, manifest);- await this.writeWriter(seed.id, {- resources: {},- aliases: seed.aliases,- reuses: seed.reuses ?? [],- });+ try {+ await this.writeWriter(seed.id, {+ resources: {},+ values: {},+ publishedOutputs: seed.publishedOutputs,+ forwards: seed.forwards ?? [],+ });+ await this.writeManifest(seed.id, manifest);+ } catch (error) {+ await this.#client.delete(this.#key(seed.id, ".writer.json")).catch(() => undefined);+ await this.#client.delete(this.#key(seed.id, "result.json")).catch(() => undefined);+ throw error;+ }return new S3BuildResultWriter(this, seed.id);}@@ -330,24 +212,61 @@ export class S3BuildResultRepository implements BuildResultRepository {return (await this.read(build)) === undefined ? undefined : new S3BuildResultWriter(this, build);}+ async remove(build: string): Promise<void> {+ const prefix = this.#key(build, "result.json").slice(0, -"result.json".length);+ const keys = await this.#client.list(prefix);+ await Promise.all(keys.filter((key) => key.startsWith(prefix)).map(async (key) => await this.#client.delete(key)));+ }+async read(build: string): Promise<BuildResultManifest | undefined> {const manifest = await this.#readJson<BuildResultManifest>(build, "result.json");- if (manifest !== undefined) assert(manifest.format === "hypit.build-result@1", `${build}/result.json is not a Build Result`);+ if (manifest !== undefined) assert(manifest.format === "hypit.build-result@2", `${build}/result.json is not a Build Result`);return manifest;}- async list(): Promise<readonly BuildResultManifest[]> {+ async updatePresentation(+ build: string,+ update: BuildResultPresentationUpdate,+ ): Promise<BuildResultManifest> {+ const manifest = await this.read(build);+ assert(manifest !== undefined, `Build Result ${build} does not exist`);+ const updated = applyBuildResultPresentation(manifest, update);+ await this.writeManifest(build, updated);+ return updated;+ }++ async browse(request: { readonly before?: string; readonly limit: number }) {+ assert(Number.isSafeInteger(request.limit) && request.limit > 0, "Build Result browse limit must be positive");+ if (request.before !== undefined) assertOrderedBuildId(request.before);const prefix = this.#prefix.length === 0 ? "" : `${this.#prefix}/`;- const suffix = "/result.json";- const builds = (await this.#client.list(prefix)).flatMap((key) => {- if (!key.startsWith(prefix) || !key.endsWith(suffix)) return [];- const build = key.slice(prefix.length, -suffix.length);- return build.length > 0 && !build.includes("/") ? [build] : [];- });- const manifests = (await Promise.all([...new Set(builds)].map(async (build) => await this.read(build)))).filter(- (item): item is BuildResultManifest => item !== undefined,- );- return manifests.sort((left, right) => right.startedAt - left.startedAt || left.id.localeCompare(right.id));+ const found: Array<BuildResultManifest & { readonly outcome: NonNullable<BuildResultManifest["outcome"]>; readonly finishedAt: number }> = [];+ let after = request.before === undefined ? undefined : `${prefix}${physicalBuild(request.before)}/`;+ while (found.length <= request.limit) {+ const page = await this.#client.list(prefix, {+ limit: Math.min(1_000, Math.max(32, request.limit + 1)),+ delimiter: "/",+ ...(after === undefined ? {} : { after }),+ });+ if (page.length === 0) break;+ for (const item of page) {+ after = item;+ if (!item.startsWith(prefix) || !item.endsWith("/")) continue;+ const physical = item.slice(prefix.length, -1);+ if (physical.includes("/")) continue;+ const build = publicBuild(physical);+ if (build === undefined) continue;+ const manifest = await this.read(build);+ if (manifest?.outcome === undefined || manifest.finishedAt === undefined) continue;+ found.push(manifest as typeof found[number]);+ if (found.length > request.limit) break;+ }+ if (found.length > request.limit || page.length < Math.min(1_000, Math.max(32, request.limit + 1))) break;+ }+ const results = found.slice(0, request.limit);+ return {+ results,+ ...(found.length > request.limit && results.length > 0 ? { next: results[results.length - 1]!.id } : {}),+ };}async resolve(build: string, output: string): Promise<RepositoryBuildResultOutput | undefined> {@@ -366,16 +285,20 @@ export class S3BuildResultRepository implements BuildResultRepository {currentOutput = entry.value.output;continue;}- if (entry.value.kind === "json") {- const value = await this.#readJson<BuildResultJsonValue>(currentBuild, entry.value.path);- assert(value !== undefined, `Build ${currentBuild} value ${entry.value.path} is unavailable`);+ if (entry.value.kind === "value") {+ const document = await this.#readJson<BuildResultValueDocument>(currentBuild, entry.value.path);+ assert(document !== undefined, `Build ${currentBuild} value ${entry.value.path} is unavailable`);+ assertBuildResultValueDocument(document, `Build ${currentBuild} Output ${currentOutput}`);return {build: currentBuild,output: currentOutput,type: entry.type,- value: { ...entry.value, value },+ value: { ...entry.value, document },};}+ const terminalKind = (entry.value as { readonly kind?: unknown }).kind;+ assert(terminalKind === "build-file" || terminalKind === "inline",+ `Build ${currentBuild} Output ${currentOutput} has unsupported Result value kind ${String(terminalKind)}`);return {build: currentBuild,output: currentOutput,@@ -385,8 +308,24 @@ export class S3BuildResultRepository implements BuildResultRepository {}}- async openFile(build: string, file: BuildResultFileRef): Promise<AsyncIterable<Uint8Array> | undefined> {- return await this.#client.open(this.#key(file.build ?? build, file.path));+ async openFile(+ build: string,+ file: BuildResultFileRef,+ range?: BuildResultFileRange,+ ): Promise<AsyncIterable<Uint8Array> | undefined> {+ if (range !== undefined) {+ assert(Number.isSafeInteger(range.start) && range.start >= 0, "Build Result file range start is invalid");+ assert(Number.isSafeInteger(range.endExclusive) && range.endExclusive > range.start,+ "Build Result file range end is invalid");+ assert(range.endExclusive <= file.size, "Build Result file range exceeds the declared file size");+ }+ return await this.#client.open(this.#key(build, file.path), range);+ }++ /** Verify that the configured bucket/prefix can be listed without loading Result history. */+ async diagnose(): Promise<void> {+ const prefix = this.#prefix.length === 0 ? "" : `${this.#prefix}/`;+ await this.#client.list(prefix, { limit: 1 });}async close(): Promise<void> {diff --git a/packages/build-result-s3/test/repository.test.ts b/packages/build-result-s3/test/repository.test.tsindex 333e1069..fbed95a6 100644--- a/packages/build-result-s3/test/repository.test.ts+++ b/packages/build-result-s3/test/repository.test.ts@@ -16,6 +16,12 @@ const takeType: TypeRef = {class MemoryS3 implements BuildResultS3Client {readonly objects = new Map<string, Uint8Array>();+ readonly listRequests: {+ readonly prefix: string;+ readonly limit?: number;+ readonly after?: string;+ readonly delimiter?: string;+ }[] = [];async put(key: string, bytes: Uint8Array): Promise<void> {this.objects.set(key, Uint8Array.from(bytes));@@ -43,16 +49,31 @@ class MemoryS3 implements BuildResultS3Client {return value === undefined ? undefined : Uint8Array.from(value);}- async open(key: string): Promise<AsyncIterable<Uint8Array> | undefined> {+ async open(key: string, range?: { readonly start: number; readonly endExclusive: number }): Promise<AsyncIterable<Uint8Array> | undefined> {const value = this.objects.get(key);if (value === undefined) return undefined;+ const selected = range === undefined ? value : value.slice(range.start, range.endExclusive);return (async function* () {- yield Uint8Array.from(value);+ yield Uint8Array.from(selected);})();}- async list(prefix: string): Promise<readonly string[]> {- return [...this.objects.keys()].filter((key) => key.startsWith(prefix));+ async list(prefix: string, options: {+ readonly limit?: number;+ readonly after?: string;+ readonly delimiter?: string;+ } = {}): Promise<readonly string[]> {+ this.listRequests.push({ prefix, ...options });+ const keys = [...this.objects.keys()].filter((key) => key.startsWith(prefix)).sort();+ const items = options.delimiter === undefined+ ? keys+ : [...new Set(keys.map((key) => {+ const remainder = key.slice(prefix.length);+ const split = remainder.indexOf(options.delimiter!);+ return split < 0 ? key : `${prefix}${remainder.slice(0, split + options.delimiter!.length)}`;+ }))];+ const selected = options.after === undefined ? items : items.filter((item) => item > options.after!);+ return options.limit === undefined ? selected : selected.slice(0, options.limit);}async delete(key: string): Promise<void> {@@ -63,12 +84,17 @@ class MemoryS3 implements BuildResultS3Client {function state(input: {readonly status?: BuildState["status"];readonly records: BuildState["records"];- readonly selections: BuildState["plan"]["selections"];+ readonly bindings: readonly { readonly output: string; readonly record: string }[];}): BuildState {return {status: input.status ?? "active",records: input.records,- plan: { selections: input.selections },+ plan: {+ outputBindings: input.bindings.map((binding) => ({+ ...binding,+ type: input.records.find((record) => record.id === binding.record)!.type,+ })),+ },} as unknown as BuildState;}@@ -87,12 +113,12 @@ test("S3 keeps the same Build Result model as the filesystem repository", asyncmediaType: "video/mp4",};const writer = await repository.create({- id: "bld_one",- name: "opening variants",+ id: "bld_20260902T100000000Z_0000000001",+ title: "opening variants",source: { path: "/project/main.svml" },run: { path: "/project/build.svrun" },- targets: ["final.video"],- aliases: [+ targets: ["shot.video"],+ publishedOutputs: [{ name: "shot.take", output: "logical:take" },{ name: "shot.video", output: "logical:video" },],@@ -110,15 +136,13 @@ test("S3 keeps the same Build Result model as the filesystem repository", async},},],- selections: [+ bindings: [{output: "logical:video",- candidate: "candidate:video",record: "record:video",},{output: "logical:take",- candidate: "candidate:take",record: "record:take",},],@@ -132,32 +156,111 @@ test("S3 keeps the same Build Result model as the filesystem repository", async},});- assert.equal(manifest.name, "opening variants");+ assert.equal(manifest.title, "opening variants");assert.equal(manifest.outputs["shot.video"]?.value.kind, "build-file");- assert.equal(manifest.outputs["shot.take"]?.value.kind, "json");+ assert.equal(manifest.outputs["shot.take"]?.value.kind, "value");assert.deepEqual(- [...client.objects.keys()].filter((key) => key.includes("/files/")),- ["projects/episode-12/bld_one/files/shot.video.mp4"],+ [...client.objects.keys()].filter((key) => key.includes("/files/")).map((key) => key.slice(key.indexOf("/files/"))),+ ["/files/file-0001.mp4"],);- const resolvedTake = await repository.resolve("bld_one", "shot.take");- assert.equal(resolvedTake?.value.kind, "json");- if (resolvedTake?.value.kind !== "json") throw new Error("expected structured result");- assert.deepEqual(resolvedTake.value.value, {- media: {- visual: {- artifact: {- kind: "build-file",- path: "files/shot.video.mp4",- size: bytes.byteLength,- mediaType: "video/mp4",- },+ const resolvedTake = await repository.resolve("bld_20260902T100000000Z_0000000001", "shot.take");+ assert.equal(resolvedTake?.value.kind, "value");+ if (resolvedTake?.value.kind !== "value") throw new Error("expected Composite Result value");+ assert.deepEqual(resolvedTake.value.document, {+ format: "hypit.result-value@1",+ value: { media: { visual: { artifact: null } } },+ resources: [{+ at: ["media", "visual", "artifact"],+ file: {+ kind: "build-file",+ path: "files/file-0001.mp4",+ size: bytes.byteLength,+ mediaType: "video/mp4",},- },+ }],});assert.deepEqual(- (await repository.list()).map((item) => item.id),- ["bld_one"],+ (await repository.browse({ limit: 20 })).results.map((item) => item.id),+ [],+ );+ await writer.finish({ outcome: "complete" });+ await writer.finish({ outcome: "complete" });+ assert.equal(client.objects.has("projects/episode-12/bld_20260902T100000000Z_0000000001/.writer.json"), false);+ await assert.rejects(+ writer.finish({ outcome: "failed", failure: "different" }),+ /already finished with a different outcome/u,);+ assert.deepEqual((await repository.browse({ limit: 20 })).results.map((item) => item.id), ["bld_20260902T100000000Z_0000000001"]);+ const presented = await repository.updatePresentation("bld_20260902T100000000Z_0000000001", {+ title: "Episode 12 opening",+ note: "Preferred composite.",+ highlightedOutputs: ["shot.video"],+ });+ assert.equal(presented.title, "Episode 12 opening");+ assert.equal(presented.note, "Preferred composite.");+ assert.deepEqual(presented.highlightedOutputs, ["shot.video"]);+});++test("S3 opens only the requested byte range of a Result file", async () => {+ const client = new MemoryS3();+ const repository = new S3BuildResultRepository({ bucket: "unused", client });+ const bytes = new TextEncoder().encode("0123456789");+ const build = "bld_20260902T100000010Z_0000000001";+ const physical = `${(Number.MAX_SAFE_INTEGER - Date.parse("2026-09-02T10:00:00.010Z")).toString().padStart(16, "0")}-${build}`;+ client.objects.set(`${physical}/files/video.mp4`, bytes);+ const stream = await repository.openFile(build, {+ kind: "build-file",+ path: "files/video.mp4",+ size: bytes.byteLength,+ mediaType: "video/mp4",+ }, { start: 2, endExclusive: 6 });+ assert.notEqual(stream, undefined);+ const chunks: number[] = [];+ for await (const chunk of stream!) chunks.push(...chunk);+ assert.equal(new TextDecoder().decode(Uint8Array.from(chunks)), "2345");+});++test("S3 diagnosis performs one bounded prefix listing", async () => {+ const client = new MemoryS3();+ const repository = new S3BuildResultRepository({+ bucket: "unused",+ prefix: "projects/episode-12",+ client,+ });+ await repository.diagnose();+ assert.deepEqual(client.listRequests, [{ prefix: "projects/episode-12/", limit: 1 }]);+});++test("S3 browses ordered Build ids newest first with a public cursor", async () => {+ const client = new MemoryS3();+ const repository = new S3BuildResultRepository({+ bucket: "unused",+ prefix: "projects/episode-12",+ client,+ });+ const ids = [+ "bld_20260902T100000001Z_0000000001",+ "bld_20260902T100000002Z_0000000001",+ "bld_20260902T100000003Z_0000000001",+ ];+ for (const id of ids) {+ const writer = await repository.create({+ id,+ source: { path: "/project/main.svml" },+ targets: ["video"],+ publishedOutputs: [{ name: "video", output: "logical:video" }],+ });+ await writer.finish({ outcome: "failed", failure: "ordering fixture" });+ }++ const first = await repository.browse({ limit: 2 });+ assert.deepEqual(first.results.map((item) => item.id), [ids[2], ids[1]]);+ assert.equal(first.next, ids[1]);+ if (first.next === undefined) throw new Error("expected an older Result cursor");+ const second = await repository.browse({ limit: 2, before: first.next });+ assert.deepEqual(second.results.map((item) => item.id), [ids[0]]);+ assert.equal(second.next, undefined);+ assert.equal(client.listRequests.at(-1)?.after?.endsWith(`-${ids[1]}/`), true);});test("S3 forwarding can cross several Builds without copying the historical file", async () => {@@ -165,10 +268,10 @@ test("S3 forwarding can cross several Builds without copying the historical fileconst repository = new S3BuildResultRepository({ bucket: "fixture", client });const bytes = new TextEncoder().encode("historical video");const original = await repository.create({- id: "bld_original",+ id: "bld_20260902T100000001Z_0000000001",source: { path: "/project/main.svml" },targets: ["video"],- aliases: [{ name: "video", output: "logical:video" }],+ publishedOutputs: [{ name: "video", output: "logical:video" }],});await original.sync({state: state({@@ -185,10 +288,9 @@ test("S3 forwarding can cross several Builds without copying the historical file},},],- selections: [+ bindings: [{output: "logical:video",- candidate: "candidate:video",record: "record:video",},],@@ -207,8 +309,8 @@ test("S3 forwarding can cross several Builds without copying the historical fileid,source: { path: "/project/main.svml" },targets: ["video"],- aliases: [{ name: "video", output: "logical:video" }],- reuses: [{ candidate: "candidate:reuse", build: fromBuild, output: "video" }],+ publishedOutputs: [{ name: "video", output: "logical:video" }],+ forwards: [{ output: "logical:video", build: fromBuild, sourceOutput: "video" }],});await writer.sync({state: state({@@ -225,10 +327,9 @@ test("S3 forwarding can cross several Builds without copying the historical file},},],- selections: [+ bindings: [{output: "logical:video",- candidate: "candidate:reuse",record: "record:reused",},],@@ -240,11 +341,11 @@ test("S3 forwarding can cross several Builds without copying the historical file},});};- await forward("bld_second", "bld_original");- await forward("bld_third", "bld_second");+ await forward("bld_20260902T100000002Z_0000000001", "bld_20260902T100000001Z_0000000001");+ await forward("bld_20260902T100000003Z_0000000001", "bld_20260902T100000002Z_0000000001");- const resolved = await repository.resolve("bld_third", "video");- assert.equal(resolved?.build, "bld_original");+ const resolved = await repository.resolve("bld_20260902T100000003Z_0000000001", "video");+ assert.equal(resolved?.build, "bld_20260902T100000001Z_0000000001");assert.equal(resolved?.value.kind, "build-file");if (resolved?.value.kind !== "build-file") throw new Error("expected historical file");const opened = await repository.openFile(resolved.build, resolved.value);diff --git a/packages/build-result/src/index.ts b/packages/build-result/src/index.tsindex 0e4acde7..22a2b6e8 100644--- a/packages/build-result/src/index.ts+++ b/packages/build-result/src/index.ts@@ -1,11 +1,18 @@+export {+ assertBuildResultValueDocument,+ assertBuildResultSeed,+} from "./types.js";+export { syncBuildResultOutputs } from "./writer.js";export {FileBuildResult,FileBuildResultRepository,+ applyBuildResultPresentation,+ browseBuildResults,buildResultDirectory,- listBuildResults,materializeBuildResultOutput,materializeRepositoryBuildResultOutput,readBuildResult,resolveBuildResultOutput,} from "./store.js";export type * from "./types.js";+export type * from "./writer.js";diff --git a/packages/build-result/src/store.ts b/packages/build-result/src/store.tsindex 1a272a9a..4da7181f 100644--- a/packages/build-result/src/store.ts+++ b/packages/build-result/src/store.ts@@ -13,26 +13,27 @@ import {import { createReadStream } from "node:fs";import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";-import type { BlobRef, BuildState, StoredValue, TypedRecord } from "@hypit/protocol";+import { assertBuildId, assertOrderedBuildId, buildIdCreatedAt } from "@hypit/protocol";+import type { BlobRef } from "@hypit/protocol";import type {+ BuildResultValueDocument,BuildResultResourceSource,BuildResultFileRef,+ BuildResultFileRange,BuildResultFinish,- BuildResultJsonValue,BuildResultManifest,- BuildResultOutput,+ BuildResultPresentationUpdate,BuildResultSeed,BuildResultSync,- HistoricalBuildOutputRef,ResolvedBuildResultOutput,BuildResultRepository,RepositoryBuildResultOutput,+ FinishedBuildResultManifest,} from "./types.js";--type WriterState = {- readonly resources: Readonly<Record<string, string>>;-};+import { assertBuildResultValueDocument, assertBuildResultSeed } from "./types.js";+import { syncBuildResultOutputs } from "./writer.js";+import type { BuildResultWriterState } from "./writer.js";const manifestName = "result.json";const writerStateName = ".writer.json";@@ -41,44 +42,42 @@ function assert(condition: unknown, message: string): asserts condition {if (!condition) throw new Error(message);}-function safeName(value: string): string {- const safe = value.trim().replace(/[^a-zA-Z0-9._-]+/gu, "-").replace(/^-+|-+$/gu, "");- return safe.length === 0 ? "output" : safe;-}--function valueFileName(output: string): string {- return `${encodeURIComponent(output)}.json`;-}--function mediaExtension(mediaType: string): string {- const subtype = mediaType.split("/", 2)[1]?.split(";", 1)[0]?.trim().toLowerCase();- if (subtype === undefined || subtype.length === 0) return ".bin";- const conventional = subtype === "jpeg" ? "jpg" : subtype === "x-wav" ? "wav" : subtype;- const suffix = conventional.includes("+") ? conventional.slice(0, conventional.indexOf("+")) : conventional;- const safe = suffix.replace(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "");- return safe.length === 0 ? ".bin" : `.${safe}`;-}--function isBlobRef(value: unknown): value is BlobRef {- if (value === null || Array.isArray(value) || typeof value !== "object") return false;- const item = value as Readonly<Record<string, unknown>>;- return item.kind === "blob"- && typeof item.resource === "string"- && typeof item.size === "number"- && Number.isSafeInteger(item.size)- && item.size >= 0- && typeof item.mediaType === "string"- && item.mediaType.length > 0;-}--function scalar(value: unknown): value is null | boolean | number | string {- return value === null || ["boolean", "number", "string"].includes(typeof value);-}--function resourceIdentity(artifact: BlobRef): string {- assert(artifact.resource !== undefined,- "Build resource has no instance identity; the producing Store must return BlobRef.resource");- return artifact.resource;+export function applyBuildResultPresentation(+ manifest: BuildResultManifest,+ update: BuildResultPresentationUpdate,+): BuildResultManifest {+ assert(manifest.outcome !== undefined, `Build Result ${manifest.id} is not finished`);+ const base = { ...manifest } as {+ title?: string;+ note?: string;+ highlightedOutputs?: readonly string[];+ } & BuildResultManifest;+ if (update.title !== undefined) {+ if (update.title === null) delete base.title;+ else {+ const title = update.title.trim();+ assert(title.length > 0, "Build Result title must not be empty");+ base.title = title;+ }+ }+ if (update.note !== undefined) {+ if (update.note === null) delete base.note;+ else {+ const note = update.note.trim();+ assert(note.length > 0, "Build Result note must not be empty");+ base.note = note;+ }+ }+ if (update.highlightedOutputs !== undefined) {+ const highlighted = [...new Set(update.highlightedOutputs)];+ for (const output of highlighted) {+ assert(manifest.outputs[output] !== undefined,+ `Build Result ${manifest.id} has no Output ${output}`);+ }+ if (highlighted.length === 0) delete base.highlightedOutputs;+ else base.highlightedOutputs = highlighted;+ }+ return base;}async function exists(path: string): Promise<boolean> {@@ -105,7 +104,7 @@ async function copyArtifactAtomic(if (await exists(destination)) return;await mkdir(dirname(destination), { recursive: true });const input = await source.open(artifact);- if (input === undefined) throw new Error(`Build resource ${resourceIdentity(artifact)} is unavailable`);+ if (input === undefined) throw new Error(`Build resource ${artifact.resource} is unavailable`);const temporary = `${destination}.part-${randomUUID()}`;const output = await open(temporary, "wx");try {@@ -122,19 +121,14 @@ async function copyArtifactAtomic(}}-function outputRecord(state: BuildState, output: string): TypedRecord | undefined {- const selection = state.plan.selections.find((item) => item.output === output);- if (selection === undefined) return undefined;- return state.records.find((item) => item.id === selection.record);-}--function outputCandidate(state: BuildState, output: string): string | undefined {- return state.plan.selections.find((item) => item.output === output)?.candidate;-}-export function buildResultDirectory(root: string, build: string): string {- assert(build.trim().length > 0 && !build.includes("/") && !build.includes("\\"), "Build id is not a directory name");- return join(resolve(root), build);+ assertBuildId(build);+ const directory = resolve(root);+ const target = resolve(directory, build);+ const relation = relative(directory, target);+ assert(relation.length > 0 && relation !== ".." && !relation.startsWith(`..${sep}`),+ `Build ${build} leaves Build Result root ${directory}`);+ return target;}export async function readBuildResult(directory: string): Promise<BuildResultManifest | undefined> {@@ -145,7 +139,7 @@ export async function readBuildResult(directory: string): Promise<BuildResultMan});if (text === undefined) return undefined;const value = JSON.parse(text) as BuildResultManifest;- assert(value.format === "hypit.build-result@1", `${path} is not a Hypit Build Result`);+ assert(value.format === "hypit.build-result@2", `${path} is not a Hypit Build Result`);return value;}@@ -159,20 +153,35 @@ function containedResultPath(directory: string, path: string): string {return absolute;}-export async function listBuildResults(root: string): Promise<readonly BuildResultManifest[]> {+export async function browseBuildResults(+ root: string,+ request: { readonly before?: string; readonly limit: number },+): Promise<{ readonly results: readonly FinishedBuildResultManifest[]; readonly next?: string }> {+ assert(Number.isSafeInteger(request.limit) && request.limit > 0, "Build Result browse limit must be positive");+ if (request.before !== undefined) assertOrderedBuildId(request.before);const directory = resolve(root);const entries = await readdir(directory, { withFileTypes: true }).catch((error: unknown) => {if (error instanceof Error && "code" in error && error.code === "ENOENT") return [];throw error;});- const manifests = await Promise.all(entries- .filter((entry) => entry.isDirectory())- .map(async (entry) => {- const manifest = await readBuildResult(join(directory, entry.name));- assert(manifest !== undefined, `${join(directory, entry.name)} has no result.json`);- return manifest;- }));- return manifests.sort((left, right) => right.startedAt - left.startedAt || left.id.localeCompare(right.id));+ const builds = entries+ .filter((entry) => entry.isDirectory() && !entry.name.startsWith(".preparing-"))+ .map((entry) => entry.name)+ .filter((build) => buildIdCreatedAt(build) !== undefined)+ .filter((build) => request.before === undefined || build < request.before)+ .sort((left, right) => right.localeCompare(left));+ const found: FinishedBuildResultManifest[] = [];+ for (const build of builds) {+ const manifest = await readBuildResult(join(directory, build));+ if (manifest?.outcome === undefined || manifest.finishedAt === undefined) continue;+ found.push(manifest as FinishedBuildResultManifest);+ if (found.length > request.limit) break;+ }+ const results = found.slice(0, request.limit);+ return {+ results,+ ...(found.length > request.limit && results.length > 0 ? { next: results[results.length - 1]!.id } : {}),+ };}export async function resolveBuildResultOutput(@@ -197,16 +206,22 @@ export async function resolveBuildResultOutput(currentOutput = entry.value.output;continue;}- if (entry.value.kind === "json") {- const value = JSON.parse(await readFile(containedResultPath(directory, entry.value.path), "utf8")) as BuildResultJsonValue;+ if (entry.value.kind === "value") {+ const document = JSON.parse(+ await readFile(containedResultPath(directory, entry.value.path), "utf8"),+ ) as BuildResultValueDocument;+ assertBuildResultValueDocument(document, `Build ${currentBuild} Output ${currentOutput}`);return {build: currentBuild,output: currentOutput,directory,type: entry.type,- value: { ...entry.value, value },+ value: { ...entry.value, document },};}+ const terminalKind = (entry.value as { readonly kind?: unknown }).kind;+ assert(terminalKind === "build-file" || terminalKind === "inline",+ `Build ${currentBuild} Output ${currentOutput} has unsupported Result value kind ${String(terminalKind)}`);return {build: currentBuild,output: currentOutput,@@ -226,7 +241,7 @@ export async function materializeBuildResultOutput(readonly build: string;readonly output: string;readonly path: string;- readonly kind: "file" | "json" | "inline";+ readonly kind: "file" | "value" | "inline";}> {const resolvedOutput = await resolveBuildResultOutput(root, build, output);if (resolvedOutput === undefined) throw new Error(`Build ${build} has no Output ${output}`);@@ -237,10 +252,7 @@ export async function materializeBuildResultOutput(if (resolvedOutput.value.kind === "inline") {await writeFile(temporary, `${JSON.stringify(resolvedOutput.value.value, null, 2)}\n`, { flag: "wx" });} else {- const sourceDirectory = resolvedOutput.value.kind === "build-file" && resolvedOutput.value.build !== undefined- ? buildResultDirectory(root, resolvedOutput.value.build)- : resolvedOutput.directory;- await copyFile(containedResultPath(sourceDirectory, resolvedOutput.value.path), temporary);+ await copyFile(containedResultPath(resolvedOutput.directory, resolvedOutput.value.path), temporary);}await rename(temporary, target);} catch (error) {@@ -253,7 +265,7 @@ export async function materializeBuildResultOutput(path: target,kind: resolvedOutput.value.kind === "build-file"? "file"- : resolvedOutput.value.kind === "json" ? "json" : "inline",+ : resolvedOutput.value.kind === "value" ? "value" : "inline",};}@@ -266,7 +278,7 @@ export async function materializeRepositoryBuildResultOutput(readonly build: string;readonly output: string;readonly path: string;- readonly kind: "file" | "json" | "inline";+ readonly kind: "file" | "value" | "inline";}> {const resolvedOutput = await repository.resolve(build, output);if (resolvedOutput === undefined) throw new Error(`Build ${build} has no Output ${output}`);@@ -276,8 +288,8 @@ export async function materializeRepositoryBuildResultOutput(try {if (resolvedOutput.value.kind === "inline") {await writeFile(temporary, `${JSON.stringify(resolvedOutput.value.value, null, 2)}\n`, { flag: "wx" });- } else if (resolvedOutput.value.kind === "json") {- await writeFile(temporary, `${JSON.stringify(resolvedOutput.value.value, null, 2)}\n`, { flag: "wx" });+ } else if (resolvedOutput.value.kind === "value") {+ await writeFile(temporary, `${JSON.stringify(resolvedOutput.value.document, null, 2)}\n`, { flag: "wx" });} else {const input = await repository.openFile(resolvedOutput.build, resolvedOutput.value);if (input === undefined) {@@ -299,7 +311,7 @@ export async function materializeRepositoryBuildResultOutput(build: resolvedOutput.build,output: resolvedOutput.output,path: target,- kind: resolvedOutput.value.kind === "build-file" ? "file" : resolvedOutput.value.kind === "json" ? "json" : "inline",+ kind: resolvedOutput.value.kind === "build-file" ? "file" : resolvedOutput.value.kind === "value" ? "value" : "inline",};}@@ -311,30 +323,38 @@ export class FileBuildResult {}static async create(root: string, seed: BuildResultSeed): Promise<FileBuildResult> {+ assertOrderedBuildId(seed.id);+ assertBuildResultSeed(seed);+ for (const forward of seed.forwards ?? []) {+ assert(await resolveBuildResultOutput(root, forward.build, forward.sourceOutput) !== undefined,+ `Build ${forward.build} has no Output ${forward.sourceOutput}`);+ }const directory = buildResultDirectory(root, seed.id);- assert(seed.name === undefined || seed.name.trim().length > 0, "Build Result name must not be empty");- await mkdir(directory, { recursive: true });- const existing = await readBuildResult(directory);- if (existing !== undefined) throw new Error(`Build Result ${seed.id} already exists`);- const now = seed.startedAt ?? Date.now();+ await mkdir(resolve(root), { recursive: true });+ const temporary = join(resolve(root), `.preparing-${seed.id}-${randomUUID()}`);+ await mkdir(temporary);const manifest: BuildResultManifest = {- format: "hypit.build-result@1",+ format: "hypit.build-result@2",id: seed.id,- ...(seed.name === undefined ? {} : { name: seed.name }),+ ...(seed.title === undefined ? {} : { title: seed.title }),source: seed.source,...(seed.run === undefined ? {} : { run: seed.run }),targets: [...seed.targets],- startedAt: now,- updatedAt: now,- status: "running",outputs: {},};- await writeJsonAtomic(join(directory, manifestName), manifest);- await writeJsonAtomic(join(directory, writerStateName), {- resources: {},- aliases: seed.aliases,- reuses: seed.reuses ?? [],- });+ try {+ await writeJsonAtomic(join(temporary, manifestName), manifest);+ await writeJsonAtomic(join(temporary, writerStateName), {+ resources: {},+ values: {},+ publishedOutputs: seed.publishedOutputs,+ forwards: seed.forwards ?? [],+ });+ await rename(temporary, directory);+ } catch (error) {+ await rm(temporary, { recursive: true, force: true });+ throw error;+ }return new FileBuildResult(directory);}@@ -353,117 +373,40 @@ export class FileBuildResult {async sync(input: BuildResultSync): Promise<BuildResultManifest> {const manifest = await this.read();- if (manifest.status !== "running") return manifest;+ if (manifest.outcome !== undefined) return manifest;const rawWriter = await readFile(join(this.directory, writerStateName), "utf8");- const writer = JSON.parse(rawWriter) as WriterState & {- readonly aliases: readonly { readonly name: string; readonly output: string }[];- readonly reuses: readonly { readonly candidate: string; readonly build: string; readonly output: string }[];- };- const resources = new Map(Object.entries(writer.resources));- const outputs: Record<string, BuildResultOutput> = { ...manifest.outputs };- const materialize = async (- artifact: BlobRef,- preferredName: string,- ): Promise<BuildResultFileRef> => {- if (artifact.origin !== undefined) {- return {- kind: "build-file",- build: artifact.origin.build,- path: artifact.origin.path,- size: artifact.size,- mediaType: artifact.mediaType,- };- }- const identity = resourceIdentity(artifact);- let relativePath = resources.get(identity);- if (relativePath === undefined) {- const base = safeName(preferredName);- let candidate = join("files", `${base}${mediaExtension(artifact.mediaType)}`);- let counter = 2;- const occupied = new Set(resources.values());- while (occupied.has(candidate)) {- candidate = join("files", `${base}-${counter}${mediaExtension(artifact.mediaType)}`);- counter += 1;- }- relativePath = candidate;- resources.set(identity, relativePath);- }- await copyArtifactAtomic(input.resources, artifact, join(this.directory, relativePath));- return { kind: "build-file", path: relativePath, size: artifact.size, mediaType: artifact.mediaType };- };- const convert = async (value: unknown, preferredName: string): Promise<BuildResultJsonValue> => {- if (isBlobRef(value)) return await materialize(value, preferredName);- if (scalar(value)) return value;- if (Array.isArray(value)) {- return await Promise.all(value.map(async (item, index) => await convert(item, `${preferredName}-${index + 1}`)));- }- assert(typeof value === "object", `Build Output ${preferredName} contains a non-canonical value`);- return Object.fromEntries(await Promise.all(Object.entries(value as Readonly<Record<string, unknown>>)- .map(async ([key, item]) => [key, await convert(item, `${preferredName}-${key}`)] as const)));- };- const outputValue = async (name: string, value: StoredValue): Promise<BuildResultOutput["value"]> => {- if (value.kind === "blob") return await materialize(value, name);- if (scalar(value.value)) return { kind: "inline", value: value.value };- const relativePath = join("values", valueFileName(name));- await writeJsonAtomic(join(this.directory, relativePath), await convert(value.value, name));- return { kind: "json", path: relativePath };- };- const reuses = new Map(writer.reuses.map((item) => [item.candidate, item]));- const outputRank = (record: TypedRecord, reused: { readonly build: string; readonly output: string } | undefined): number => reused !== undefined- ? 0- : record.value.kind === "blob" ? 1 : scalar(record.value.value) ? 2 : 3;- const ready = writer.aliases.flatMap((alias) => {- const record = outputRecord(input.state, alias.output);- if (record === undefined) return [];- const reused = reuses.get(outputCandidate(input.state, alias.output) ?? "");- return [{ alias, record, reused }];- }).sort((left, right) => {- return outputRank(left.record, left.reused) - outputRank(right.record, right.reused)- || left.alias.name.localeCompare(right.alias.name);- });- for (const { alias, record, reused } of ready) {- const value: BuildResultOutput["value"] = reused === undefined- ? await outputValue(alias.name, record.value)- : {- kind: "build-output",- build: reused.build,- output: reused.output,- } satisfies HistoricalBuildOutputRef;- outputs[alias.name] = { type: record.type, value };- }- const now = Date.now();- const status = input.state.status === "complete"- ? "complete"- : input.state.status === "failed" ? "failed" : manifest.status;- const updated: BuildResultManifest = {- ...manifest,- updatedAt: now,- status,- ...(status === "running" ? {} : { finishedAt: manifest.finishedAt ?? now }),- outputs,- };- await writeJsonAtomic(join(this.directory, writerStateName), {- ...writer,- resources: Object.fromEntries(resources),+ const writer = JSON.parse(rawWriter) as BuildResultWriterState;+ const directory = this.directory;+ const updated = await syncBuildResultOutputs({+ manifest,+ writer,+ sync: input,+ target: {+ async writeResource(path, artifact, source) {+ await copyArtifactAtomic(source, artifact, join(directory, path));+ },+ async writeValue(path, document) {+ await writeJsonAtomic(join(directory, path), document);+ },+ },});- await writeJsonAtomic(join(this.directory, manifestName), updated);- if (status !== "running") await rm(join(this.directory, writerStateName), { force: true });- return updated;+ await writeJsonAtomic(join(this.directory, writerStateName), updated.writer);+ await writeJsonAtomic(join(this.directory, manifestName), updated.manifest);+ return updated.manifest;}async finish(input: BuildResultFinish): Promise<BuildResultManifest> {const manifest = await this.read();- if (manifest.status !== "running") {- if (manifest.status !== input.status || input.failure === undefined || manifest.failure !== undefined) return manifest;- const updated = { ...manifest, failure: input.failure, updatedAt: Date.now() };- await writeJsonAtomic(join(this.directory, manifestName), updated);- return updated;+ if (manifest.outcome !== undefined) {+ assert(manifest.outcome === input.outcome && manifest.failure === input.failure,+ `Build Result ${manifest.id} is already finished with a different outcome`);+ await rm(join(this.directory, writerStateName), { force: true });+ return manifest;}const now = Date.now();const updated: BuildResultManifest = {...manifest,- status: input.status,- updatedAt: now,+ outcome: input.outcome,finishedAt: manifest.finishedAt ?? now,...(input.failure === undefined ? {} : { failure: input.failure }),};@@ -491,12 +434,27 @@ export class FileBuildResultRepository implements BuildResultRepository {return await readBuildResult(directory) === undefined ? undefined : await FileBuildResult.open(directory);}+ async remove(build: string): Promise<void> {+ await rm(buildResultDirectory(this.root, build), { recursive: true, force: true });+ }+async read(build: string): Promise<BuildResultManifest | undefined> {return await readBuildResult(buildResultDirectory(this.root, build));}- async list(): Promise<readonly BuildResultManifest[]> {- return await listBuildResults(this.root);+ async updatePresentation(+ build: string,+ update: BuildResultPresentationUpdate,+ ): Promise<BuildResultManifest> {+ const manifest = await this.read(build);+ assert(manifest !== undefined, `Build Result ${build} does not exist`);+ const updated = applyBuildResultPresentation(manifest, update);+ await writeJsonAtomic(join(buildResultDirectory(this.root, build), manifestName), updated);+ return updated;+ }++ async browse(request: { readonly before?: string; readonly limit: number }) {+ return await browseBuildResults(this.root, request);}async resolve(build: string, output: string): Promise<RepositoryBuildResultOutput | undefined> {@@ -506,11 +464,19 @@ export class FileBuildResultRepository implements BuildResultRepository {return portable;}- async openFile(build: string, file: BuildResultFileRef): Promise<AsyncIterable<Uint8Array> | undefined> {- const owner = file.build ?? build;- const directory = buildResultDirectory(this.root, owner);+ async openFile(+ build: string,+ file: BuildResultFileRef,+ range?: BuildResultFileRange,+ ): Promise<AsyncIterable<Uint8Array> | undefined> {+ const directory = buildResultDirectory(this.root, build);const path = containedResultPath(directory, file.path);if (!await exists(path)) return undefined;- return createReadStream(path);+ if (range === undefined) return createReadStream(path);+ assert(Number.isSafeInteger(range.start) && range.start >= 0, "Build Result file range start is invalid");+ assert(Number.isSafeInteger(range.endExclusive) && range.endExclusive > range.start,+ "Build Result file range end is invalid");+ assert(range.endExclusive <= file.size, "Build Result file range exceeds the declared file size");+ return createReadStream(path, { start: range.start, end: range.endExclusive - 1 });}}diff --git a/packages/build-result/src/types.ts b/packages/build-result/src/types.tsindex 4d728940..e1e7efb8 100644--- a/packages/build-result/src/types.ts+++ b/packages/build-result/src/types.ts@@ -1,42 +1,143 @@import type {BlobRef,BuildState,+ CanonicalValue,TypeRef,} from "@hypit/protocol";-export type BuildResultStatus = "running" | "complete" | "failed" | "cancelled";+/** The one durable conclusion of a finished Build. Active execution belongs to Runtime. */+export type BuildResultOutcome = "complete" | "failed" | "cancelled";export type BuildResultFileRef = {readonly kind: "build-file";- /** Omitted for this Build; present for a directly carried historical file. */- readonly build?: string;/** Forward-only path relative to the owning Build's result directory. */readonly path: string;readonly size: number;readonly mediaType: string;};+/** A normalized half-open byte range within one Result file. */+export type BuildResultFileRange = {+ readonly start: number;+ readonly endExclusive: number;+};+export type HistoricalBuildOutputRef = {readonly kind: "build-output";readonly build: string;readonly output: string;};-export type BuildResultJsonValue =- | null- | boolean- | number- | string- | readonly BuildResultJsonValue[]- | BuildResultFileRef- | HistoricalBuildOutputRef- | { readonly [key: string]: BuildResultJsonValue };+export type BuildResultValuePath = readonly (string | number)[];++export type BuildResultResourceBinding = {+ /** Location of one Resource inside `value`; the encoded slot itself is `null`. */+ readonly at: BuildResultValuePath;+ readonly file: BuildResultFileRef;+};++/**+ * Durable encoding of one Composite value. Domain data stays ordinary canonical data while+ * Result-local Resource addresses live beside it, so reserved-looking domain objects cannot be+ * mistaken for persistence metadata.+ */+export type BuildResultValueDocument = {+ readonly format: "hypit.result-value@1";+ readonly value: CanonicalValue;+ readonly resources: readonly BuildResultResourceBinding[];+};++function assertCanonicalValue(value: unknown, subject: string): asserts value is CanonicalValue {+ if (value === null || typeof value === "boolean" || typeof value === "string") return;+ if (typeof value === "number") {+ if (!Number.isFinite(value)) throw new Error(`${subject} contains a non-finite number`);+ return;+ }+ if (Array.isArray(value)) {+ value.forEach((item, index) => assertCanonicalValue(item, `${subject}[${index}]`));+ return;+ }+ if (typeof value !== "object") throw new Error(`${subject} is not canonical data`);+ for (const [key, child] of Object.entries(value as Readonly<Record<string, unknown>>)) {+ assertCanonicalValue(child, `${subject}.${key}`);+ }+}++function assertBuildResultFileRef(value: unknown, subject: string): asserts value is BuildResultFileRef {+ if (value === null || Array.isArray(value) || typeof value !== "object") {+ throw new Error(`${subject} is not a Build file reference`);+ }+ const item = value as Readonly<Record<string, unknown>>;+ if (item.kind !== "build-file" || typeof item.path !== "string" || item.path.length === 0+ || typeof item.size !== "number" || !Number.isSafeInteger(item.size) || item.size < 0+ || typeof item.mediaType !== "string" || item.mediaType.length === 0) {+ throw new Error(`${subject} is not a valid Build file reference`);+ }+}++function valueAtPath(value: CanonicalValue, path: BuildResultValuePath, subject: string): CanonicalValue {+ let current = value;+ for (const segment of path) {+ if (typeof segment === "number") {+ if (!Number.isSafeInteger(segment) || segment < 0 || !Array.isArray(current) || segment >= current.length) {+ throw new Error(`${subject} does not address a value slot`);+ }+ current = current[segment]!;+ continue;+ }+ if (typeof segment !== "string" || current === null || Array.isArray(current) || typeof current !== "object"+ || !Object.hasOwn(current, segment)) {+ throw new Error(`${subject} does not address a value slot`);+ }+ current = (current as Readonly<Record<string, CanonicalValue>>)[segment]!;+ }+ return current;+}++/** Validate the storage document before its Resource paths are decoded into Runtime values. */+export function assertBuildResultValueDocument(+ value: unknown,+ subject = "Build Result value",+): asserts value is BuildResultValueDocument {+ if (value === null || Array.isArray(value) || typeof value !== "object") {+ throw new Error(`${subject} is not a Result value document`);+ }+ const document = value as Readonly<Record<string, unknown>>;+ if (document.format !== "hypit.result-value@1" || !Array.isArray(document.resources)) {+ throw new Error(`${subject} is not a Result value document`);+ }+ const canonicalValue = document.value;+ assertCanonicalValue(canonicalValue, `${subject}.value`);+ const occupied = new Set<string>();+ document.resources.forEach((raw, index) => {+ if (raw === null || Array.isArray(raw) || typeof raw !== "object") {+ throw new Error(`${subject}.resources[${index}] is invalid`);+ }+ const binding = raw as Readonly<Record<string, unknown>>;+ if (!Array.isArray(binding.at) || binding.at.length === 0) {+ throw new Error(`${subject}.resources[${index}].at is invalid`);+ }+ for (const segment of binding.at) {+ if (typeof segment !== "string"+ && !(typeof segment === "number" && Number.isSafeInteger(segment) && segment >= 0)) {+ throw new Error(`${subject}.resources[${index}].at is invalid`);+ }+ }+ const path = JSON.stringify(binding.at);+ if (occupied.has(path)) throw new Error(`${subject} binds ${path} more than once`);+ occupied.add(path);+ if (valueAtPath(canonicalValue, binding.at, `${subject}.resources[${index}].at`) !== null) {+ throw new Error(`${subject}.resources[${index}].at must address a null Resource slot`);+ }+ assertBuildResultFileRef(binding.file, `${subject}.resources[${index}].file`);+ });+}export type BuildResultOutputValue =| BuildResultFileRef| HistoricalBuildOutputRef| { readonly kind: "inline"; readonly value: null | boolean | number | string }- | { readonly kind: "json"; readonly path: string };+ | { readonly kind: "value"; readonly path: string };export type BuildResultOutput = {readonly type: TypeRef;@@ -44,44 +145,90 @@ export type BuildResultOutput = {};export type BuildResultManifest = {- readonly format: "hypit.build-result@1";+ readonly format: "hypit.build-result@2";readonly id: string;- readonly name?: string;+ readonly title?: string;+ readonly note?: string;+ /** Human-selected public Outputs to surface first; names must exist in `outputs`. */+ readonly highlightedOutputs?: readonly string[];readonly source: { readonly path: string };readonly run?: { readonly path: string };/** Author-facing names of the Build's actual final goals. */readonly targets: readonly string[];- readonly startedAt: number;- readonly updatedAt: number;readonly finishedAt?: number;- readonly status: BuildResultStatus;+ /** Absent while this Result is still accepting completed public Outputs. */+ readonly outcome?: BuildResultOutcome;readonly failure?: string;readonly outputs: Readonly<Record<string, BuildResultOutput>>;};-export type BuildResultAlias = {+export type FinishedBuildResultManifest = BuildResultManifest & {+ readonly outcome: BuildResultOutcome;+ readonly finishedAt: number;+};++export type BuildResultPublishedOutput = {readonly name: string;readonly output: string;};-export type BuildResultReuse = {- /** Resolved Candidate id stored in the Build Plan. */- readonly candidate: string;- readonly build: string;+export type BuildResultForward = {+ /** Logical Output in the current Build whose entire value is carried forward. */readonly output: string;+ readonly build: string;+ readonly sourceOutput: string;};export type BuildResultSeed = {readonly id: string;- readonly name?: string;+ readonly title?: string;readonly source: { readonly path: string };readonly run?: { readonly path: string };readonly targets: readonly string[];- readonly aliases: readonly BuildResultAlias[];- readonly reuses?: readonly BuildResultReuse[];- readonly startedAt?: number;+ readonly publishedOutputs: readonly BuildResultPublishedOutput[];+ readonly forwards?: readonly BuildResultForward[];};+/** Validate the one-name-per-Output public Result surface before storage is touched. */+export function assertBuildResultSeed(seed: BuildResultSeed): void {+ if (seed.title !== undefined && seed.title.trim().length === 0) {+ throw new Error("Build Result title must not be empty");+ }+ const names = new Set<string>();+ const outputs = new Set<string>();+ for (const published of seed.publishedOutputs) {+ if (published.name.trim().length === 0) throw new Error("Published Output name must not be empty");+ if (published.output.trim().length === 0) throw new Error(`Published Output ${published.name} has no Logical Output`);+ if (names.has(published.name)) throw new Error(`Published Output name ${published.name} is repeated`);+ if (outputs.has(published.output)) {+ throw new Error(`Logical Output ${published.output} has more than one published name`);+ }+ names.add(published.name);+ outputs.add(published.output);+ }+ const targets = new Set<string>();+ for (const target of seed.targets) {+ if (!names.has(target)) throw new Error(`Target ${target} is not a published Output`);+ if (targets.has(target)) throw new Error(`Target ${target} is repeated`);+ targets.add(target);+ }+ const logicalOutputs = new Set(seed.publishedOutputs.map((published) => published.output));+ const forwards = new Set<string>();+ for (const forward of seed.forwards ?? []) {+ if (!logicalOutputs.has(forward.output)) {+ throw new Error(`Forwarded Logical Output ${forward.output} is not public`);+ }+ if (forwards.has(forward.output)) {+ throw new Error(`Logical Output ${forward.output} has more than one forward source`);+ }+ if (forward.build.trim().length === 0 || forward.sourceOutput.trim().length === 0) {+ throw new Error(`Logical Output ${forward.output} has an incomplete forward source`);+ }+ if (forward.build === seed.id) throw new Error(`Logical Output ${forward.output} cannot forward to its own Build`);+ forwards.add(forward.output);+ }+}+export type BuildResultResourceSource = {open(artifact: BlobRef): Promise<AsyncIterable<Uint8Array> | undefined>;};@@ -92,10 +239,32 @@ export type BuildResultSync = {};export type BuildResultFinish = {- readonly status: Exclude<BuildResultStatus, "running">;+ readonly outcome: BuildResultOutcome;readonly failure?: string;};+export type BuildResultPresentationUpdate = {+ /** `null` removes the current title; omission leaves it unchanged. */+ readonly title?: string | null;+ /** `null` removes the current note; omission leaves it unchanged. */+ readonly note?: string | null;+ /** An empty list clears the selection; omission leaves it unchanged. */+ readonly highlightedOutputs?: readonly string[];+};++export type BuildResultBrowseRequest = {+ /** Return Builds strictly older than this ordered Build id. */+ readonly before?: string;+ readonly limit: number;+};++export type BuildResultPage = {+ /** Newest first. */+ readonly results: readonly FinishedBuildResultManifest[];+ /** Last scanned Build id when an older page may exist. */+ readonly next?: string;+};+export type ResolvedBuildResultOutput = {readonly build: string;readonly output: string;@@ -104,7 +273,7 @@ export type ResolvedBuildResultOutput = {readonly value:| BuildResultFileRef| { readonly kind: "inline"; readonly value: null | boolean | number | string }- | { readonly kind: "json"; readonly path: string; readonly value: BuildResultJsonValue };+ | { readonly kind: "value"; readonly path: string; readonly document: BuildResultValueDocument };};/** Storage-neutral resolved Output. Physical repositories never enter Build or Run identity. */@@ -123,8 +292,17 @@ export type BuildResultWriter = {export type BuildResultRepository = {create(seed: BuildResultSeed): Promise<BuildResultWriter>;openWriter(build: string): Promise<BuildResultWriter | undefined>;+ /** Remove one exact Result created by a submission that never became claimable. */+ remove(build: string): Promise<void>;read(build: string): Promise<BuildResultManifest | undefined>;- list(): Promise<readonly BuildResultManifest[]>;+ /** Edit only human presentation stored inside this exact finished Result. */+ updatePresentation(build: string, update: BuildResultPresentationUpdate): Promise<BuildResultManifest>;+ /** Browse finished Results in descending Build-id time order. */+ browse(request: BuildResultBrowseRequest): Promise<BuildResultPage>;resolve(build: string, output: string): Promise<RepositoryBuildResultOutput | undefined>;- openFile(build: string, file: BuildResultFileRef): Promise<AsyncIterable<Uint8Array> | undefined>;+ openFile(+ build: string,+ file: BuildResultFileRef,+ range?: BuildResultFileRange,+ ): Promise<AsyncIterable<Uint8Array> | undefined>;};diff --git a/packages/build-result/src/writer.ts b/packages/build-result/src/writer.tsnew file mode 100644index 00000000..b6157232--- /dev/null+++ b/packages/build-result/src/writer.ts@@ -0,0 +1,184 @@+import type { BlobRef, CanonicalValue, TypedRecord } from "@hypit/protocol";++import type {+ BuildResultFileRef,+ BuildResultManifest,+ BuildResultOutput,+ BuildResultResourceSource,+ BuildResultSync,+ BuildResultValueDocument,+ BuildResultValuePath,+ HistoricalBuildOutputRef,+} from "./types.js";++export type BuildResultWriterState = {+ readonly resources: Readonly<Record<string, string>>;+ readonly values: Readonly<Record<string, string>>;+ readonly publishedOutputs: readonly { readonly name: string; readonly output: string }[];+ readonly forwards: readonly { readonly output: string; readonly build: string; readonly sourceOutput: string }[];+};++export type BuildResultWriteTarget = {+ writeResource(+ path: string,+ artifact: BlobRef,+ source: BuildResultResourceSource,+ ): Promise<void>;+ writeValue(path: string, document: BuildResultValueDocument): Promise<void>;+};++export type BuildResultSyncResult = {+ readonly manifest: BuildResultManifest;+ readonly writer: BuildResultWriterState;+};++function assert(condition: unknown, message: string): asserts condition {+ if (!condition) throw new Error(message);+}++function numberedPath(+ directory: "files" | "values",+ stem: "file" | "value",+ extension: string,+ occupied: ReadonlySet<string>,+): string {+ let index = 1;+ while (true) {+ const candidate = `${directory}/${stem}-${String(index).padStart(4, "0")}${extension}`;+ if (!occupied.has(candidate)) return candidate;+ index += 1;+ }+}++function mediaExtension(mediaType: string): string {+ const subtype = mediaType.split("/", 2)[1]?.split(";", 1)[0]?.trim().toLowerCase();+ if (subtype === undefined || subtype.length === 0) return ".bin";+ const conventional = subtype === "jpeg" ? "jpg" : subtype === "x-wav" ? "wav" : subtype;+ const suffix = conventional.includes("+") ? conventional.slice(0, conventional.indexOf("+")) : conventional;+ const safe = suffix.replace(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "");+ return safe.length === 0 ? ".bin" : `.${safe}`;+}++function scalar(value: unknown): value is null | boolean | number | string {+ return value === null || typeof value === "boolean" || typeof value === "string"+ || (typeof value === "number" && Number.isFinite(value));+}++function isBlobRef(value: unknown): value is BlobRef {+ if (value === null || Array.isArray(value) || typeof value !== "object") return false;+ const item = value as Readonly<Record<string, unknown>>;+ return item.kind === "blob"+ && typeof item.resource === "string"+ && item.resource.length > 0+ && typeof item.size === "number"+ && Number.isSafeInteger(item.size)+ && item.size >= 0+ && typeof item.mediaType === "string"+ && item.mediaType.length > 0;+}++function outputRecord(input: BuildResultSync, output: string): TypedRecord | undefined {+ const binding = input.state.plan.outputBindings.find((item) => item.output === output);+ return binding === undefined ? undefined : input.state.records.find((item) => item.id === binding.record);+}++/**+ * Encode accepted public Outputs exactly once, independently of the physical repository adapter.+ * The adapter only writes bytes/documents at the paths chosen here.+ */+export async function syncBuildResultOutputs(input: {+ readonly manifest: BuildResultManifest;+ readonly writer: BuildResultWriterState;+ readonly sync: BuildResultSync;+ readonly target: BuildResultWriteTarget;+}): Promise<BuildResultSyncResult> {+ const resources = new Map(Object.entries(input.writer.resources));+ const values = new Map(Object.entries(input.writer.values));+ const outputs: Record<string, BuildResultOutput> = { ...input.manifest.outputs };++ const materialize = async (artifact: BlobRef): Promise<BuildResultFileRef> => {+ const identity = artifact.resource;+ assert(identity.length > 0, "Build resource has no instance identity");+ let path = resources.get(identity);+ if (path === undefined) {+ path = numberedPath("files", "file", mediaExtension(artifact.mediaType), new Set(resources.values()));+ resources.set(identity, path);+ await input.target.writeResource(path, artifact, input.sync.resources);+ }+ return { kind: "build-file", path, size: artifact.size, mediaType: artifact.mediaType };+ };++ const encodeComposite = async (+ value: unknown,+ path: BuildResultValuePath = [],+ ): Promise<{ readonly value: CanonicalValue; readonly resources: BuildResultValueDocument["resources"] }> => {+ if (isBlobRef(value)) {+ return { value: null, resources: [{ at: path, file: await materialize(value) }] };+ }+ if (scalar(value)) return { value, resources: [] };+ if (Array.isArray(value)) {+ const children = await Promise.all(value.map(async (item, index) => await encodeComposite(item, [...path, index])));+ return {+ value: children.map((child) => child.value),+ resources: children.flatMap((child) => child.resources),+ };+ }+ assert(value !== null && typeof value === "object", "Build Output contains a non-canonical value");+ const entries = await Promise.all(Object.entries(value as Readonly<Record<string, unknown>>).map(async ([key, item]) => {+ return [key, await encodeComposite(item, [...path, key])] as const;+ }));+ return {+ value: Object.fromEntries(entries.map(([key, child]) => [key, child.value])),+ resources: entries.flatMap(([, child]) => child.resources),+ };+ };++ const outputValue = async (record: TypedRecord): Promise<BuildResultOutput["value"]> => {+ if (record.value.kind === "blob") return await materialize(record.value);+ if (scalar(record.value.value)) return { kind: "inline", value: record.value.value };+ const existingPath = values.get(record.id);+ if (existingPath !== undefined) return { kind: "value", path: existingPath };+ const path = numberedPath("values", "value", ".json", new Set(values.values()));+ values.set(record.id, path);+ const document: BuildResultValueDocument = {+ format: "hypit.result-value@1",+ ...await encodeComposite(record.value.value),+ };+ await input.target.writeValue(path, document);+ return { kind: "value", path };+ };++ const forwards = new Map(input.writer.forwards.map((item) => [item.output, item]));+ const outputRank = (record: TypedRecord, forward: HistoricalBuildOutputRef | undefined): number => forward !== undefined+ ? 0+ : record.value.kind === "blob" ? 1 : scalar(record.value.value) ? 2 : 3;+ const ready = input.writer.publishedOutputs.flatMap((published) => {+ if (outputs[published.name] !== undefined) return [];+ const record = outputRecord(input.sync, published.output);+ if (record === undefined) return [];+ const source = forwards.get(published.output);+ const forward = source === undefined ? undefined : {+ kind: "build-output" as const,+ build: source.build,+ output: source.sourceOutput,+ };+ return [{ published, record, forward }];+ }).sort((left, right) => outputRank(left.record, left.forward) - outputRank(right.record, right.forward)+ || left.published.name.localeCompare(right.published.name));++ for (const { published, record, forward } of ready) {+ outputs[published.name] = {+ type: record.type,+ value: forward ?? await outputValue(record),+ };+ }++ return {+ manifest: { ...input.manifest, outputs },+ writer: {+ ...input.writer,+ resources: Object.fromEntries(resources),+ values: Object.fromEntries(values),+ },+ };+}diff --git a/packages/build-result/test/result.test.ts b/packages/build-result/test/result.test.tsindex 79e3c572..7f6b4571 100644--- a/packages/build-result/test/result.test.ts+++ b/packages/build-result/test/result.test.ts@@ -1,10 +1,10 @@import assert from "node:assert/strict";-import { mkdtemp, readFile, readdir, rm } from "node:fs/promises";+import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";import { tmpdir } from "node:os";import { join } from "node:path";import test from "node:test";-import { FileBuildResult } from "@hypit/build-result";+import { FileBuildResult, FileBuildResultRepository } from "@hypit/build-result";import type { BlobRef, BuildState, TypeRef } from "@hypit/protocol";const videoType: TypeRef = {@@ -19,12 +19,17 @@ const takeType: TypeRef = {function state(input: {readonly status?: BuildState["status"];readonly records: BuildState["records"];- readonly selections: BuildState["plan"]["selections"];+ readonly bindings: readonly { readonly output: string; readonly record: string }[];}): BuildState {return {status: input.status ?? "active",records: input.records,- plan: { selections: input.selections },+ plan: {+ outputBindings: input.bindings.map((binding) => ({+ ...binding,+ type: input.records.find((record) => record.id === binding.record)?.type ?? videoType,+ })),+ },} as unknown as BuildState;}@@ -39,13 +44,14 @@ test("one same-Build resource backs a public video and a SemanticTake payload",};try {const result = await FileBuildResult.create(root, {- id: "bld_one",+ id: "bld_20260902T100000000Z_0000000001",source: { path: "/project/main.svml" },run: { path: "/project/build.svrun" },- targets: ["final.video"],- aliases: [+ targets: ["shot.video"],+ publishedOutputs: [{ name: "shot.video", output: "logical:shot-video" },{ name: "shot.take", output: "logical:shot-take" },+ { name: "shot.take-copy", output: "logical:shot-take-copy" },{ name: "unused.video", output: "logical:unused" },],});@@ -59,10 +65,11 @@ test("one same-Build resource backs a public video and a SemanticTake payload",value: { kind: "inline", value: { media: { visual: { artifact: video } } } },},],- selections: [- { output: "logical:shot-video", candidate: "candidate:generated-video", record: "record:video" },- { output: "logical:shot-take", candidate: "candidate:aligned-take", record: "record:take" },- { output: "logical:unused", candidate: "candidate:unused", record: "record:unused" },+ bindings: [+ { output: "logical:shot-video", record: "record:video" },+ { output: "logical:shot-take", record: "record:take" },+ { output: "logical:shot-take-copy", record: "record:take" },+ { output: "logical:unused", record: "record:unused" },],}),resources: {@@ -72,28 +79,117 @@ test("one same-Build resource backs a public video and a SemanticTake payload",},},});- assert.deepEqual(Object.keys(manifest.outputs).sort(), ["shot.take", "shot.video"]);+ assert.deepEqual(Object.keys(manifest.outputs).sort(), ["shot.take", "shot.take-copy", "shot.video"]);assert.equal(manifest.outputs["shot.video"]?.value.kind, "build-file");- assert.equal(manifest.outputs["shot.take"]?.value.kind, "json");+ assert.equal(manifest.outputs["shot.take"]?.value.kind, "value");const videoPath = manifest.outputs["shot.video"]?.value.kind === "build-file"? manifest.outputs["shot.video"].value.path: undefined;- const takePath = manifest.outputs["shot.take"]?.value.kind === "json"+ const takePath = manifest.outputs["shot.take"]?.value.kind === "value"? manifest.outputs["shot.take"].value.path: undefined;assert.ok(videoPath);assert.ok(takePath);- assert.equal(videoPath, "files/shot.video.mp4");+ assert.equal(manifest.outputs["shot.take-copy"]?.value.kind === "value"+ ? manifest.outputs["shot.take-copy"].value.path+ : undefined, takePath);+ assert.equal(videoPath, "files/file-0001.mp4");const take = JSON.parse(await readFile(join(result.directory, takePath), "utf8")) as {- readonly media: { readonly visual: { readonly artifact: { readonly path: string } } };+ readonly format: string;+ readonly value: { readonly media: { readonly visual: { readonly artifact: null } } };+ readonly resources: readonly [{ readonly at: readonly string[]; readonly file: { readonly path: string } }];};- assert.equal(take.media.visual.artifact.path, videoPath);+ assert.equal(take.format, "hypit.result-value@1");+ assert.equal(take.value.media.visual.artifact, null);+ assert.deepEqual(take.resources[0].at, ["media", "visual", "artifact"]);+ assert.equal(take.resources[0].file.path, videoPath);assert.deepEqual(await readdir(join(result.directory, "files")), [videoPath.split("/").at(-1)]);- const failed = await result.finish({ status: "failed", failure: "final render failed" });- assert.equal(failed.status, "failed");+ const failed = await result.finish({ outcome: "failed", failure: "final render failed" });+ assert.equal(failed.outcome, "failed");assert.equal(failed.failure, "final render failed");- assert.deepEqual(Object.keys(failed.outputs).sort(), ["shot.take", "shot.video"]);+ assert.deepEqual(Object.keys(failed.outputs).sort(), ["shot.take", "shot.take-copy", "shot.video"]);+ await result.finish({ outcome: "failed", failure: "final render failed" });+ assert.equal((await readdir(result.directory)).includes(".writer.json"), false);+ await assert.rejects(+ result.finish({ outcome: "complete" }),+ /already finished with a different outcome/u,+ );+ const repository = new FileBuildResultRepository(root);+ const presented = await repository.updatePresentation("bld_20260902T100000000Z_0000000001", {+ title: "Episode 12 opening",+ note: "Use the quieter take.",+ highlightedOutputs: ["shot.video", "shot.take", "shot.video"],+ });+ assert.equal(presented.title, "Episode 12 opening");+ assert.equal(presented.note, "Use the quieter take.");+ assert.deepEqual(presented.highlightedOutputs, ["shot.video", "shot.take"]);+ await assert.rejects(+ repository.updatePresentation("bld_20260902T100000000Z_0000000001", { highlightedOutputs: ["missing.output"] }),+ /has no Output missing\.output/u,+ );+ const cleared = await repository.updatePresentation("bld_20260902T100000000Z_0000000001", {+ title: null,+ note: null,+ highlightedOutputs: [],+ });+ assert.equal(cleared.title, undefined);+ assert.equal(cleared.note, undefined);+ assert.equal(cleared.highlightedOutputs, undefined);+ } finally {+ await rm(root, { recursive: true, force: true });+ }+});++test("filesystem repository streams one normalized byte range", async () => {+ const root = await mkdtemp(join(tmpdir(), "hypit-result-range-"));+ try {+ const directory = join(root, "bld_range");+ await mkdir(join(directory, "files"), { recursive: true });+ const bytes = new TextEncoder().encode("abcdefghij");+ await writeFile(join(directory, "files", "video.mp4"), bytes);+ const repository = new FileBuildResultRepository(root);+ const stream = await repository.openFile("bld_range", {+ kind: "build-file",+ path: "files/video.mp4",+ size: bytes.byteLength,+ mediaType: "video/mp4",+ }, { start: 3, endExclusive: 7 });+ assert.notEqual(stream, undefined);+ const chunks: number[] = [];+ for await (const chunk of stream!) chunks.push(...chunk);+ assert.equal(new TextDecoder().decode(Uint8Array.from(chunks)), "defg");+ } finally {+ await rm(root, { recursive: true, force: true });+ }+});++test("reserved-looking domain objects remain ordinary Composite data", async () => {+ const root = await mkdtemp(join(tmpdir(), "hypit-result-json-reference-"));+ const id = "bld_20260902T100000000Z_0000000001";+ try {+ const directory = join(root, id);+ await mkdir(join(directory, "values"), { recursive: true });+ await writeFile(join(directory, "result.json"), JSON.stringify({+ format: "hypit.build-result@2",+ id,+ source: { path: "main.svml" },+ targets: ["value"],+ outcome: "complete",+ finishedAt: 1,+ outputs: { value: { type: videoType, value: { kind: "value", path: "values/value-0001.json" } } },+ }));+ await writeFile(join(directory, "values", "value-0001.json"), JSON.stringify({+ format: "hypit.result-value@1",+ value: { nested: { kind: "build-output", build: id, output: "value" } },+ resources: [],+ }));+ const resolved = await new FileBuildResultRepository(root).resolve(id, "value");+ assert.equal(resolved?.value.kind, "value");+ if (resolved?.value.kind !== "value") throw new Error("expected Composite Result value");+ assert.deepEqual(resolved.value.document.value, {+ nested: { kind: "build-output", build: id, output: "value" },+ });} finally {await rm(root, { recursive: true, force: true });}@@ -102,12 +198,29 @@ test("one same-Build resource backs a public video and a SemanticTake payload",test("an explicitly reused public output is a forward reference and copies no bytes", async () => {const root = await mkdtemp(join(tmpdir(), "hypit-build-result-reuse-"));try {+ const prior = await FileBuildResult.create(root, {+ id: "bld_20260902T100000001Z_0000000001",+ source: { path: "/project/main.svml" },+ targets: ["opening.video"],+ publishedOutputs: [{ name: "opening.video", output: "logical:opening-video" }],+ });+ await prior.sync({+ state: state({+ records: [{+ id: "record:opening",+ type: videoType,+ value: { kind: "blob", resource: "res_opening", size: 10, mediaType: "video/mp4" },+ }],+ bindings: [{ output: "logical:opening-video", record: "record:opening" }],+ }),+ resources: { async open() { return (async function* () { yield new Uint8Array(10); })(); } },+ });const result = await FileBuildResult.create(root, {- id: "bld_new",+ id: "bld_20260902T100000002Z_0000000002",source: { path: "/project/main.svml" },- targets: ["final.video"],- aliases: [{ name: "shot.video", output: "logical:shot-video" }],- reuses: [{ candidate: "candidate:prior", build: "bld_old", output: "opening.video" }],+ targets: ["shot.video"],+ publishedOutputs: [{ name: "shot.video", output: "logical:shot-video" }],+ forwards: [{ output: "logical:shot-video", build: "bld_20260902T100000001Z_0000000001", sourceOutput: "opening.video" }],});const manifest = await result.sync({state: state({@@ -121,7 +234,7 @@ test("an explicitly reused public output is a forward reference and copies no bymediaType: "video/mp4",},}],- selections: [{ output: "logical:shot-video", candidate: "candidate:prior", record: "record:prior" }],+ bindings: [{ output: "logical:shot-video", record: "record:prior" }],}),resources: {async open() {@@ -131,10 +244,51 @@ test("an explicitly reused public output is a forward reference and copies no by});assert.deepEqual(manifest.outputs["shot.video"]?.value, {kind: "build-output",- build: "bld_old",+ build: "bld_20260902T100000001Z_0000000001",output: "opening.video",});} finally {await rm(root, { recursive: true, force: true });}});++test("filesystem Results have one public name per Output and browse newest first", async () => {+ const root = await mkdtemp(join(tmpdir(), "hypit-build-result-browse-"));+ const repository = new FileBuildResultRepository(root);+ const ids = [+ "bld_20260902T100000001Z_0000000001",+ "bld_20260902T100000002Z_0000000001",+ "bld_20260902T100000003Z_0000000001",+ ];+ try {+ await assert.rejects(repository.create({+ id: "bld_20260902T100000000Z_0000000001",+ source: { path: "/project/main.svml" },+ targets: ["video"],+ publishedOutputs: [+ { name: "video", output: "logical:video" },+ { name: "duplicate", output: "logical:video" },+ ],+ }), /has more than one published name/u);++ for (const id of ids) {+ const writer = await repository.create({+ id,+ source: { path: "/project/main.svml" },+ targets: ["video"],+ publishedOutputs: [{ name: "video", output: "logical:video" }],+ });+ await writer.finish({ outcome: "failed", failure: "ordering fixture" });+ }++ const first = await repository.browse({ limit: 2 });+ assert.deepEqual(first.results.map((item) => item.id), [ids[2], ids[1]]);+ assert.equal(first.next, ids[1]);+ if (first.next === undefined) throw new Error("expected an older Result cursor");+ const second = await repository.browse({ limit: 2, before: first.next });+ assert.deepEqual(second.results.map((item) => item.id), [ids[0]]);+ assert.equal(second.next, undefined);+ } finally {+ await rm(root, { recursive: true, force: true });+ }+});diff --git a/packages/cli/package.json b/packages/cli/package.jsonindex 651c1bea..2c5f1b78 100644--- a/packages/cli/package.json+++ b/packages/cli/package.json@@ -9,6 +9,7 @@},"dependencies": {"@hypit/build-result": "workspace:*",+ "@hypit/build-result-kit": "workspace:*","@hypit/compiler-node": "workspace:*","@hypit/elaborator": "workspace:*","@hypit/package-loader-node": "workspace:*",diff --git a/packages/cli/src/archive.ts b/packages/cli/src/archive.tsdeleted file mode 100644index 4af1bcbd..00000000--- a/packages/cli/src/archive.ts+++ /dev/null@@ -1,314 +0,0 @@-import { randomUUID } from "node:crypto";-import { mkdir, open, rename, rm, writeFile } from "node:fs/promises";-import { dirname } from "node:path";--import type { CliRuntimeResourceAccess } from "./runtime-port.js";-import { isResourceId } from "@hypit/protocol";-import type { BuildState, ResourceId, TypedRecord, TypeRef } from "@hypit/protocol";-import type { BuildCatalogEntry } from "@hypit/runtime";--type ArtifactIdentity = {- readonly resource: ResourceId;- readonly size: number;- readonly mediaType: string;-};--export type ArchivedArtifactReference = ArtifactIdentity & {- readonly record: string;- readonly path: string;-};--export type ArchivedLogicalOutput = {- readonly name: string;- readonly type: TypeRef;- readonly output: string;- readonly candidate: BuildState["plan"]["selections"][number]["candidate"];- readonly record: ReturnType<typeof summarizeRecord>;-};--function artifactIdentity(value: unknown): ArtifactIdentity | undefined {- if (value === null || Array.isArray(value) || typeof value !== "object") return undefined;- const candidate = value as Readonly<Record<string, unknown>>;- if (typeof candidate.resource !== "string" || !isResourceId(candidate.resource)- || typeof candidate.size !== "number" || !Number.isSafeInteger(candidate.size) || candidate.size < 0- || typeof candidate.mediaType !== "string" || candidate.mediaType.trim().length === 0) return undefined;- return { resource: candidate.resource, size: candidate.size, mediaType: candidate.mediaType };-}--function recordArtifact(record: TypedRecord): ArtifactIdentity | undefined {- if (record.value.kind === "blob") return artifactIdentity(record.value);- return artifactIdentity(record.value.value);-}--export async function materializeRecord(- runtime: Pick<CliRuntimeResourceAccess, "openResource">,- record: TypedRecord,- destination: string,-): Promise<- | { readonly kind: "artifact"; readonly path: string; readonly resource: string; readonly size: number; readonly mediaType: string }- | { readonly kind: "json"; readonly path: string; readonly size: number }-> {- await mkdir(dirname(destination), { recursive: true });- const artifact = recordArtifact(record);- if (artifact !== undefined) {- return await materializeArtifact(runtime, artifact, destination, `Record ${record.id}`);- }- const inline = record.value.kind === "inline" ? record.value.value : record.value;- const bytes = Buffer.from(`${JSON.stringify(inline, null, 2)}\n`, "utf8");- await writeFile(destination, bytes);- return { kind: "json", path: destination, size: bytes.byteLength };-}--export async function materializeArtifact(- runtime: Pick<CliRuntimeResourceAccess, "openResource">,- artifact: ArtifactIdentity,- destination: string,- subject = "Build archive",-): Promise<{ readonly kind: "artifact"; readonly path: string; readonly resource: string; readonly size: number; readonly mediaType: string }> {- await mkdir(dirname(destination), { recursive: true });- const source = await runtime.openResource(artifact.resource);- if (source === undefined) throw new Error(`Artifact ${artifact.resource} is absent from the selected ResourceStore`);- const temporary = `${destination}.hypit-${randomUUID()}.part`;- const output = await open(temporary, "wx");- let size = 0;- try {- for await (const chunk of source) {- size += chunk.byteLength;- await output.write(chunk);- }- await output.close();- if (size !== artifact.size) throw new Error(`Artifact ${artifact.resource} size differs from ${subject}`);- // Replace an explicitly selected destination only after the stream completes.- await rename(temporary, destination);- } catch (error) {- await output.close().catch(() => undefined);- await rm(temporary, { force: true });- throw error;- }- return { kind: "artifact", path: destination, ...artifact };-}--export function collectArtifacts(- value: unknown,- path = "$",- found: { path: string; artifact: ArtifactIdentity }[] = [],-): readonly {- readonly path: string;- readonly resource: ResourceId;- readonly size: number;- readonly mediaType: string;-}[] {- const artifact = artifactIdentity(value);- if (artifact !== undefined) found.push({ path, artifact });- if (Array.isArray(value)) {- value.forEach((item, index) => collectArtifacts(item, `${path}[${index}]`, found));- } else if (value !== null && typeof value === "object") {- for (const [key, item] of Object.entries(value)) collectArtifacts(item, `${path}.${key}`, found);- }- return found.map((item) => ({ path: item.path, ...item.artifact }));-}--export function findArchivedArtifact(state: BuildState, resource: string): readonly ArchivedArtifactReference[] {- if (!isResourceId(resource)) throw new Error(`--artifact requires a valid resource id, received ${resource}`);- return state.records.flatMap((record) => {- const value = record.value.kind === "blob" ? record.value : record.value.value;- return collectArtifacts(value)- .filter((artifact) => artifact.resource === resource)- .map((artifact) => ({ record: record.id, ...artifact }));- });-}--function summarizeRecord(record: TypedRecord) {- const value = record.value.kind === "blob" ? record.value : record.value.value;- return {- id: record.id,- type: record.type,- storage: record.value.kind,- artifacts: collectArtifacts(value),- };-}--function catalogAliasType(- state: BuildState,- ref: BuildCatalogEntry["aliases"][number]["ref"],-): TypeRef | undefined {- return ref.kind === "record"- ? state.program.records.find((record) => record.id === ref.id)?.type- : state.graph.outputs.find((output) => output.id === ref.id)?.type;-}--/**- * Public Logical Outputs that this exact Build actually selected and accepted.- *- * Catalog aliases alone are insufficient: a source can publish many Outputs while a Run targets- * only a small subgraph. Authored Record aliases are useful to `get`, but are not historical- * `build-record` Candidate roots, so this view intentionally excludes them as well.- */-export function acceptedArchivedOutputs(- state: BuildState,- catalog: BuildCatalogEntry,-): readonly ArchivedLogicalOutput[] {- const records = new Map(state.records.map((record) => [record.id, record]));- const selections = new Map(state.plan.selections.map((selection) => [selection.output, selection]));- return catalog.aliases.flatMap((alias) => {- if (alias.ref.kind !== "logical-output") return [];- const selection = selections.get(alias.ref.id);- if (selection === undefined) return [];- const record = records.get(selection.record);- if (record === undefined) return [];- return [{- name: alias.name,- type: record.type,- output: alias.ref.id,- candidate: selection.candidate,- record: summarizeRecord(record),- }];- });-}--export function selectArchivedRecord(- state: BuildState,- options: {- readonly record?: string;- readonly output?: string;- readonly name?: string;- readonly catalog?: BuildCatalogEntry;- },-): TypedRecord {- const selectors = [options.record, options.output, options.name].filter((item) => item !== undefined);- if (selectors.length > 1) {- throw new Error("get accepts one of --name, --record or --output");- }- let id = options.record;- let output = options.output;- if (options.name !== undefined) {- if (options.catalog === undefined) throw new Error("Build has no Host Catalog aliases");- const alias = options.catalog.aliases.find((item) => item.name === options.name);- if (alias === undefined) throw new Error(`Build Catalog has no output named ${options.name}`);- if (alias.ref.kind === "record") id = alias.ref.id;- else output = alias.ref.id;- }- if (output !== undefined) {- const selection = state.plan.selections.find((item) => item.output === output);- if (selection === undefined) throw new Error(`Build has no demanded Logical Output ${output}`);- id = selection.record;- }- if (id === undefined) {- const goals = [...new Set(state.plan.goals.map((goal) => goal.record))];- if (goals.length !== 1) {- throw new Error("get without a selector requires exactly one distinct target Record");- }- [id] = goals;- }- const record = state.records.find((item) => item.id === id);- if (record === undefined) throw new Error(`Record ${id} has not been accepted by this Build`);- return record;-}--export function inspectBuild(state: BuildState, catalog?: BuildCatalogEntry) {- const records = new Map(state.records.map((record) => [record.id, record]));- const selections = new Map(state.plan.selections.map((selection) => [selection.output, selection]));- return {- status: state.status,- targets: state.request.targets.map((target) => {- const selection = selections.get(target.output);- const record = selection === undefined ? undefined : records.get(selection.record);- return {- output: target.output,- ...(selection === undefined ? {} : {- candidate: selection.candidate,- record: selection.record,- accepted: record !== undefined,- }),- };- }),- demandedOutputs: state.plan.selections.map((selection) => ({- output: selection.output,- candidate: selection.candidate,- record: selection.record,- accepted: records.has(selection.record),- })),- records: state.records.map(summarizeRecord),- deterministic_durations: state.records.flatMap((record) =>- record.type.module.name === "@hypit/speech" && record.type.name === "SpeechDuration"- && record.value.kind === "inline" && typeof record.value.value === "number"- ? [{ record: record.id, seconds: record.value.value }]- : []),- diagnostics: state.diagnostics,- ...(catalog === undefined ? {} : {- presentation: {- source: catalog.source,- ...(catalog.run === undefined ? {} : { run: catalog.run }),- aliases: catalog.aliases.map((alias) => {- const record = alias.ref.kind === "record"- ? records.get(alias.ref.id)- : (() => {- const selection = selections.get(alias.ref.id);- return selection === undefined ? undefined : records.get(selection.record);- })();- const type = record?.type ?? catalogAliasType(state, alias.ref);- return {- name: alias.name,- ...(type === undefined ? {} : { type }),- ref: alias.ref,- ...(record === undefined ? { accepted: false } : { accepted: true, record: record.id }),- };- }),- },- }),- };-}--/** Compact Host presentation for routine list/status output. Detailed aliases belong to inspect. */-export function summarizeBuildCatalog(catalog: BuildCatalogEntry, state?: BuildState) {- const targetOutputs = new Set(state?.request.targets.map((target) => target.output) ?? []);- const targetRecords = new Set(state?.plan.goals.map((goal) => goal.record) ?? []);- return {- source: catalog.source,- ...(catalog.run === undefined ? {} : { run: catalog.run }),- aliasCount: catalog.aliases.length,- targets: catalog.aliases- .filter((alias) => alias.ref.kind === "logical-output"- ? targetOutputs.has(alias.ref.id)- : targetRecords.has(alias.ref.id))- .map((alias) => alias.name),- };-}--export type PinnedRecord = {- readonly output: string;- readonly build: string;- readonly candidate: string;- readonly markup: readonly string[];-};--/**- * The Run Source markup that selects an already accepted Record.- *- * Reuse is authored, never implied, so these pairs have to exist before a rerun will use what a- * previous Build produced. Written by eye from a Build id and an output name, the transcription is- * where an accepted Record quietly becomes a second paid generation.- *- * Entries are expected newest first; the first appearance of each output name wins.- */-export function pinnedRecords(- entries: readonly { readonly build: string; readonly output: { readonly name: string } }[],-): readonly PinnedRecord[] {- const seen = new Set<string>();- const pinned: PinnedRecord[] = [];- for (const entry of entries) {- if (seen.has(entry.output.name)) continue;- seen.add(entry.output.name);- const candidate = `record-${entry.output.name.replace(/[^a-zA-Z0-9]+/gu, "-").replace(/^-|-$/gu, "")}`;- pinned.push({- output: entry.output.name,- build: entry.build,- candidate,- markup: [- `<build-record id="${candidate}" build="${entry.build}" output="${entry.output.name}"/>`,- `<satisfy output="${entry.output.name}" candidate="${candidate}"/>`,- ],- });- }- return pinned;-}diff --git a/packages/cli/src/distribution.ts b/packages/cli/src/distribution.tsindex 9e632f4b..14fa0449 100644--- a/packages/cli/src/distribution.ts+++ b/packages/cli/src/distribution.ts@@ -1,6 +1,9 @@import type { NodeCompiler } from "@hypit/compiler-node";import type { LoadedPackage, NodePackageContribution } from "@hypit/package-loader-node";import type { NodeRuntimeHost } from "@hypit/runtime-host-node";+import type { BuildResultRepository } from "@hypit/build-result";+import type { BuildResultRepositoryLocation } from "@hypit/build-result-kit";+import type { BuildResultRepositoryDiagnostic } from "@hypit/build-result-kit";export type CliCompilerOptions = {/** Canonical containment boundary for Author and Run Sources plus source assets. */@@ -70,6 +73,23 @@ export type CliDistribution = {readonly packageRoot: string;readonly distributionPackageRoot?: string;}): Promise<NodeRuntimeHost>;+ /** Open project-owned Result history even when no Runtime Profile is selected. */+ openProjectResults?(projectRoot: string, options: {+ readonly packageRoot: string;+ readonly distributionPackageRoot?: string;+ }): Promise<{+ readonly location: BuildResultRepositoryLocation;+ readonly repository: BuildResultRepository;+ close(): void | Promise<void>;+ }>;+ /** Actively diagnose this project's selected Result Store without reading its history. */+ diagnoseProjectResults?(projectRoot: string, options: {+ readonly packageRoot: string;+ readonly distributionPackageRoot?: string;+ }): Promise<{+ readonly location?: BuildResultRepositoryLocation;+ readonly diagnostics: readonly BuildResultRepositoryDiagnostic[];+ }>;/*** Generate one picture for a package asset.*diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.tsindex eea0b271..f4c868ae 100644--- a/packages/cli/src/index.ts+++ b/packages/cli/src/index.ts@@ -1,15 +1,9 @@-export {- collectArtifacts,- materializeArtifact,- materializeRecord,- pinnedRecords,- selectArchivedRecord,-} from "./archive.js";-export type { PinnedRecord } from "./archive.js";+export { pinnedRecords } from "./reuse-markup.js";+export type { PinnedRecord } from "./reuse-markup.js";export { runCli } from "./main.js";export { discoverSourcePackages } from "./source-discovery.js";export { loadDiscoveredSourcePackages } from "./source-packages.js";-export { collectRunFrontends, loadRunFile, resolveBuildResultRecord } from "./run-file.js";+export { collectRunFrontends, loadRunFile, resolveBuildResultValue } from "./run-file.js";export type { LoadedRunFile } from "./run-file.js";export { hypitHostStateRoot, hypitProjectStateRoot } from "./paths.js";export { findRuntimeProfile } from "./runtime-selection.js";diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.tsindex a625b045..909ef564 100644--- a/packages/cli/src/main.ts+++ b/packages/cli/src/main.ts@@ -1,4 +1,4 @@-import { createHash, randomBytes, randomUUID } from "node:crypto";+import { createHash, randomBytes } from "node:crypto";import { createServer } from "node:http";import { spawn } from "node:child_process";import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";@@ -9,6 +9,7 @@ import {FileBuildResultRepository,materializeRepositoryBuildResultOutput,} from "@hypit/build-result";+import type { BuildResultManifest, BuildResultRepository } from "@hypit/build-result";import type { NodeCompiledSourceClosure } from "@hypit/compiler-node";import type { NodeRuntimeHost } from "@hypit/runtime-host-node";import {@@ -18,13 +19,11 @@ import {} from "@hypit/runtime-host-node";import { plannedNeeds } from "@hypit/runtime";import type { BuildCatalogDescriptor, CapacityReservation, OperationProgress } from "@hypit/runtime";+import { buildIdCreatedAt, orderedBuildId } from "@hypit/protocol";import type { BuildState, CapabilityRef, TypeRef } from "@hypit/protocol";import { parseSourceHeader } from "@hypit/source";-import {- pinnedRecords,- summarizeBuildCatalog,-} from "./archive.js";+import { pinnedRecords } from "./reuse-markup.js";import { unreachedGenerations } from "./reachability.js";import { typecheckProjectPackages } from "./package-typecheck.js";import { checkRunFile, collectRunFrontends, loadRunFile } from "./run-file.js";@@ -34,7 +33,7 @@ import type {CliManagedProgramProgress,CliManagedProgramReport,CliRuntime,- CliRuntimeArchiveControl,+ CliRuntimeControl,CliRuntimeController,} from "./runtime-port.js";import { writeCliHelp, writeCliOutput } from "./output.js";@@ -59,15 +58,20 @@ type ParsedArgs = {readonly packageRoot: string | undefined;readonly runtime: string | undefined;readonly follow: boolean;- /** Emit the Run Source markup that reuses these Records instead of listing them. */+ /** Emit Run Source markup that reuses these Outputs instead of listing them. */readonly pin: boolean;/** Omit this Build's requested Targets from history and generated pin markup. */readonly excludeTargets: boolean;readonly maxWaitMs: number | undefined;- readonly record: string | undefined;readonly output: string | undefined;- readonly name: string | undefined;- readonly artifact: string | undefined;+ readonly title: string | undefined;+ readonly note: string | undefined;+ readonly highlightedOutputs: readonly string[];+ readonly clearTitle: boolean;+ readonly clearNote: boolean;+ readonly clearHighlights: boolean;+ readonly limit: number;+ readonly before: string | undefined;readonly to: string | undefined;/** Prompt text, or the path of a text file holding it. */readonly prompt: string | undefined;@@ -81,12 +85,13 @@ type ParsedArgs = {readonly watch: boolean;readonly jsonl: boolean;readonly readyFile: string | undefined;+ readonly workerOwner: string | undefined;readonly reason: string | undefined;readonly slot: string | undefined;readonly from: string | undefined;/** Exact historical source path filter. It is Host presentation, never Build identity. */readonly source: string | undefined;- /** Exact option spellings seen after positional dispatch. */+ /** Exact option spellings seen after the positional command. */readonly seenOptions: readonly string[];};@@ -100,6 +105,16 @@ function base64url(bytes: Uint8Array): string {return Buffer.from(bytes).toString("base64").replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");}+function createPublicBuildId(now = Date.now()): string {+ return orderedBuildId(now, randomBytes(5).toString("hex").toUpperCase());+}++function buildCreatedAt(build: string): number {+ const createdAt = buildIdCreatedAt(build);+ if (createdAt === undefined) throw new Error(`Build id ${build} has no submission time`);+ return createdAt;+}+async function hypiHubOAuthLogin(io: CliIo): Promise<string> {const verifier = base64url(randomBytes(32));const challenge = base64url(createHash("sha256").update(verifier).digest());@@ -282,11 +297,11 @@ async function resolvePackageRoot(projectStart: string): Promise<string> {function parseArgs(argv: readonly string[]): ParsedArgs {const [command, ...tail] = argv;- const scoped = command === "programs" || command === "runtime" || command === "auth"+ const scoped = command === "programs" || command === "runtime" || command === "auth" || command === "result"|| command === "packages";const action = scoped ? tail[0] : undefined;const positional = scoped ? tail.slice(1) : tail;- const noFile = command === "builds" || command === "queue" || command === "paths"+ const noFile = command === "builds" || command === "activity" || command === "paths"|| command === "image";const hasFile = !noFile && positional[0] !== undefined && !positional[0]!.startsWith("--");const file = hasFile ? positional[0] : undefined;@@ -299,10 +314,15 @@ function parseArgs(argv: readonly string[]): ParsedArgs {let pin = false;let excludeTargets = false;let maxWaitMs: number | undefined;- let record: string | undefined;let output: string | undefined;- let name: string | undefined;- let artifact: string | undefined;+ let title: string | undefined;+ let note: string | undefined;+ const highlightedOutputs: string[] = [];+ let clearTitle = false;+ let clearNote = false;+ let clearHighlights = false;+ let limit = 20;+ let before: string | undefined;let to: string | undefined;let prompt: string | undefined;let model: string | undefined;@@ -314,6 +334,7 @@ function parseArgs(argv: readonly string[]): ParsedArgs {let watch = false;let jsonl = false;let readyFile: string | undefined;+ let workerOwner: string | undefined;let reason: string | undefined;let slot: string | undefined;let from: string | undefined;@@ -324,7 +345,7 @@ function parseArgs(argv: readonly string[]): ParsedArgs {if (item.startsWith("--")) {const repeatable = ["--json", "--jsonl", "--watch", "--verbose", "--debug",- "--no-color", "--follow", "--asset-root",+ "--no-color", "--follow", "--asset-root", "--highlight",].includes(item);if (!repeatable && seenOptions.has(item)) throw new Error(`${item} cannot be repeated`);seenOptions.add(item);@@ -390,33 +411,60 @@ function parseArgs(argv: readonly string[]): ParsedArgs {continue;}if (item === "--out") {- throw new Error("--out was removed: Build Results save completed public Outputs automatically; use `get <build-id> --name <output> --to <path>` for an optional copy");+ throw new Error("--out does not apply to Build submission; use `get <build-id> --output <name> --to <path>` for an optional copy");}- if (item === "--record") {+ if (item === "--output") {const value = rest[index + 1];- if (value === undefined || value.startsWith("--")) throw new Error("--record requires a Record id");- record = value;+ if (value === undefined || value.startsWith("--")) throw new Error("--output requires a public Output name");+ output = value;index += 1;continue;}- if (item === "--output") {+ if (item === "--title") {const value = rest[index + 1];- if (value === undefined || value.startsWith("--")) throw new Error("--output requires a Logical Output id");- output = value;+ if (value === undefined || value.startsWith("--")) throw new Error("--title requires text");+ title = value;index += 1;continue;}- if (item === "--name") {+ if (item === "--note") {const value = rest[index + 1];- if (value === undefined || value.startsWith("--")) throw new Error("--name requires a name");- name = value;+ if (value === undefined || value.startsWith("--")) throw new Error("--note requires text");+ note = value;index += 1;continue;}- if (item === "--artifact") {+ if (item === "--highlight") {const value = rest[index + 1];- if (value === undefined || value.startsWith("--")) throw new Error("--artifact requires a content digest");- artifact = value;+ if (value === undefined || value.startsWith("--")) throw new Error("--highlight requires an Output name");+ highlightedOutputs.push(value);+ index += 1;+ continue;+ }+ if (item === "--clear-title") {+ clearTitle = true;+ continue;+ }+ if (item === "--clear-note") {+ clearNote = true;+ continue;+ }+ if (item === "--clear-highlights") {+ clearHighlights = true;+ continue;+ }+ if (item === "--limit") {+ const value = rest[index + 1];+ if (value === undefined || value.startsWith("--")) throw new Error("--limit requires a positive integer");+ limit = Number(value);+ if (!Number.isSafeInteger(limit) || limit < 1) throw new Error("--limit requires a positive integer");+ index += 1;+ continue;+ }+ if (item === "--before") {+ const value = rest[index + 1];+ if (value === undefined || value.startsWith("--")) throw new Error("--before requires a Build id");+ before = value;index += 1;continue;}@@ -484,6 +532,13 @@ function parseArgs(argv: readonly string[]): ParsedArgs {index += 1;continue;}+ if (item === "--worker-owner") {+ const value = rest[index + 1];+ if (value === undefined || value.startsWith("--")) throw new Error("--worker-owner requires an identity");+ workerOwner = value;+ index += 1;+ continue;+ }if (item === "--reason") {const value = rest[index + 1];if (value === undefined || value.startsWith("--")) throw new Error("--reason requires text");@@ -526,10 +581,15 @@ function parseArgs(argv: readonly string[]): ParsedArgs {pin,excludeTargets,maxWaitMs,- record,output,- name,- artifact,+ title,+ note,+ highlightedOutputs,+ clearTitle,+ clearNote,+ clearHighlights,+ limit,+ before,to,prompt,model,@@ -541,6 +601,7 @@ function parseArgs(argv: readonly string[]): ParsedArgs {watch,jsonl,readyFile,+ workerOwner,reason,slot,from,@@ -569,14 +630,14 @@ function assertCommandOptions(args: ParsedArgs): void {add("--runtime", "--slot");if (args.action === "login") add("--from");break;- case "queue":+ case "activity":add("--runtime", "--watch", "--jsonl");break;case "paths":add("--runtime");break;case "get":- add("--workspace", "--name", "--record", "--output", "--artifact", "--to");+ add("--workspace", "--output", "--to");break;case "image":// A package asset needs credentials and nothing else; no Runtime Profile applies.@@ -585,13 +646,22 @@ function assertCommandOptions(args: ParsedArgs): void {case "cancel":add("--runtime", "--reason");break;+ case "result":+ if (args.action === "finish" || args.action === "discard") add("--runtime");+ if (args.action === "edit") {+ add("--workspace", "--title", "--note", "--highlight", "--clear-title", "--clear-note", "--clear-highlights");+ }+ break;+ case "doctor":+ add("--workspace");+ break;case "status":add("--runtime", "--watch");if (args.watch) add("--max-wait-ms");break;case "builds":case "history":- add("--workspace");+ add("--workspace", "--limit", "--before");if (args.command === "history") add("--source", "--pin", "--exclude-targets");break;case "inspect":@@ -603,15 +673,12 @@ function assertCommandOptions(args: ParsedArgs): void {break;case "build":add("--runtime", "--package-root", "--workspace", "--asset-root", "--follow",- "--max-wait-ms", "--name");+ "--max-wait-ms", "--title");break;}const invalid = args.seenOptions.find((item) => !allowed.has(item));if (invalid !== undefined) {const command = args.action === undefined ? args.command : `${args.command} ${args.action}`;- if (args.command === "doctor" && invalid === "--workspace") {- throw new Error("doctor does not compile a Source Workspace; remove --workspace");- }throw new Error(`${invalid} does not apply to ${command}`);}if (args.seenOptions.includes("--color") && args.seenOptions.includes("--no-color")) {@@ -622,21 +689,24 @@ function assertCommandOptions(args: ParsedArgs): void {function usage(): string {return ["usage:",- " hypit doctor [<runtime-profile>]",+ " hypit doctor [<runtime-profile>] [--workspace project]"," hypit programs up|down|status [<runtime-profile>] [--max-wait-ms milliseconds]"," hypit runtime use <runtime-profile>"," hypit runtime unset"," hypit runtime up|status|logs|down [<runtime-profile>]"," hypit packages install|status <package@exact-version>",- " hypit queue [--runtime profile.json] [--watch]",+ " hypit activity [--runtime profile.json] [--watch]"," hypit check <self-described-source> [--runtime profile.json] [--workspace workspace] [--asset-root directory]"," hypit plan <run-source> [--runtime profile.json] [--workspace workspace] [--asset-root directory]",- " hypit build <run-source> [--name name] [--runtime profile.json] [--workspace workspace] [--asset-root directory] [--follow]",+ " hypit build <run-source> [--title text] [--runtime profile.json] [--workspace workspace] [--asset-root directory] [--follow]"," hypit status <build-id> [--runtime profile.json] [--watch]",- " hypit builds [--workspace project]",- " hypit history [source-output-name] [--workspace project] [--source author.svml] [--pin] [--exclude-targets]",+ " hypit result finish <build-id> [--runtime profile.json]",+ " hypit result discard <build-id> [--runtime profile.json]",+ " hypit result edit <build-id> [--title text] [--note text] [--highlight output] [--workspace project]",+ " hypit builds [--workspace project] [--limit count] [--before build-id]",+ " hypit history [output-name] [--workspace project] [--source author.svml] [--limit count] [--before build-id] [--pin] [--exclude-targets]"," hypit inspect <build-id> [--workspace project]",- " hypit get <build-id> --name output-name [--workspace project] [--to path]",+ " hypit get <build-id> --output output-name [--workspace project] [--to path]"," hypit cancel <build-id> [--runtime profile.json] [--reason text]"," hypit auth status|login|logout <endpoint-instance> [--runtime profile.json] [--slot name] [--from secret-file]"," hypit image --prompt <text|text-file> --to <path.png> [--model package] [--aspect-ratio r] [--resolution r]",@@ -666,12 +736,22 @@ function createCatalogDescriptor(options: {readonly compilation: NodeCompiledSourceClosure;readonly run?: { readonly path: string };}): BuildCatalogDescriptor {- const aliases = options.compilation.exports.map((item) => {+ const publishedOutputs = options.compilation.exports.flatMap((item) => {if (item.ref.kind === "operation-result") {throw new Error(`public output ${item.name} was not lowered to a stable Record or Logical Output`);}- return { name: item.name, ref: item.ref };+ return item.ref.kind === "logical-output" ? [{ name: item.name, ref: item.ref }] : [];});+ const names = new Set<string>();+ const outputs = new Set<string>();+ for (const published of publishedOutputs) {+ if (names.has(published.name)) throw new Error(`public Output name ${published.name} is repeated`);+ if (outputs.has(published.ref.id)) {+ throw new Error(`Logical Output ${published.ref.id} has more than one public name`);+ }+ names.add(published.name);+ outputs.add(published.ref.id);+ }return {source: {path: resolve(options.source),@@ -679,7 +759,7 @@ function createCatalogDescriptor(options: {...(options.run === undefined ? {} : { run: {path: resolve(options.run.path),} }),- aliases,+ publishedOutputs,};}@@ -722,25 +802,17 @@ async function loadRuntime(host: NodeRuntimeHost): Promise<CliRuntime> {return await host.createRuntime();}-async function loadRuntimeArchive(+async function loadRuntimeControl(host: NodeRuntimeHost,readOnly = true,-): Promise<CliRuntimeArchiveControl> {- return await host.openArchive({ readOnly });+): Promise<CliRuntimeControl> {+ return await host.openControl({ readOnly });}function displayType(type: TypeRef): string {return `${type.module.name}@${type.module.version}/${type.name}`;}-function submissionStatus(- dispatch: NonNullable<Awaited<ReturnType<CliRuntime["status"]>>["dispatch"]>,-): CliBuildSubmission["status"] {- return dispatch.phase === "terminal"- ? dispatch.terminal!- : dispatch.phase;-}-function formatOperationProgress(progress: OperationProgress): string {if (progress.completed === undefined) return progress.phase;const amount = progress.total === undefined@@ -802,11 +874,12 @@ function inlineValuePreview(value: unknown, limit = 240): string {}async function observeBuild(- runtime: Pick<CliRuntimeArchiveControl, "activity" | "status">,+ runtime: Pick<CliRuntimeControl, "inspect">,initial: CliBuildSubmission,options: {readonly maxWaitMs?: number;readonly controller?: CliRuntimeController;+ readonly readResult: () => Promise<BuildResultManifest | undefined>;readonly onProgress?: (value: {readonly build: string;readonly phase: string;@@ -820,7 +893,22 @@ async function observeBuild(let pollDelayMs = 100;let observedActivity = false;const startedAt = Date.now();- while (current.status !== "complete" && current.status !== "failed" && current.status !== "cancelled") {+ const finishFromResult = async (): Promise<CliBuildSubmission> => {+ const result = await options.readResult();+ if (result?.outcome === undefined) {+ throw new Error(`Build ${current.id} left active Runtime state without a finished Result`);+ }+ return {+ id: current.id,+ state: current.state,+ completion: {+ build: current.id,+ outcome: result.outcome,+ ...(result.failure === undefined ? {} : { reason: result.failure }),+ },+ };+ };+ while ("view" in current && current.view.issue === undefined) {const elapsedMs = Date.now() - startedAt;const remainingMs = options.maxWaitMs === undefined? undefined@@ -830,18 +918,18 @@ async function observeBuild(? pollDelayMs: Math.min(pollDelayMs, remainingMs);await new Promise((resolveWait) => setTimeout(resolveWait, waitMs));- const status = await runtime.activity(current.id);+ const view = await runtime.inspect(current.id);observedActivity = true;- if (status.dispatch === undefined) {- throw new Error(`Build ${current.id} disappeared while it was being observed`);+ if (view === undefined) {+ current = await finishFromResult();+ break;}current = {id: current.id,state: current.state,- status: submissionStatus(status.dispatch),- dispatch: status.dispatch,+ view,};- if (!["complete", "failed", "cancelled"].includes(current.status)+ if (current.view.issue === undefined&& options.controller !== undefined) {const worker = await options.controller.worker.status();if (worker.state !== "running") {@@ -851,19 +939,19 @@ async function observeBuild();}}- const operations = Object.fromEntries([...new Set(status.operations.map((item) => item.status))]- .sort().map((state) => [state, status.operations.filter((item) => item.status === state).length]));- const activity = status.operations+ const operations = Object.fromEntries([...new Set(view.operations.map((item) => item.status))]+ .sort().map((state) => [state, view.operations.filter((item) => item.status === state).length]));+ const activity = view.operations.filter((item) => item.status === "pending").map((item) => `${item.endpoint}: ${item.progress === undefined? item.status: formatOperationProgress(item.progress)}`);const nextProgress = JSON.stringify({- phase: status.dispatch.phase,- terminal: status.dispatch.terminal,+ buildActivity: view.activity,+ outcome: view.outcome,operations,- activity: status.operations.map((item) => ({- id: item.id,+ activity: view.operations.map((item) => ({+ endpoint: item.endpoint,status: item.status,progress: item.progress,})),@@ -873,7 +961,7 @@ async function observeBuild(pollDelayMs = 100;options.onProgress?.({build: current.id,- phase: status.dispatch.phase,+ phase: view.activity,operations,activity,});@@ -881,45 +969,20 @@ async function observeBuild(pollDelayMs = Math.min(1_000, pollDelayMs * 2);}}- if (observedActivity) {- const status = await runtime.status(current.id);- if (status.dispatch === undefined) {- throw new Error(`Build ${current.id} disappeared while it was being observed`);+ if (observedActivity && "view" in current) {+ const view = await runtime.inspect(current.id);+ if (view === undefined) {+ return await finishFromResult();}current = {id: current.id,- state: status.build?.state ?? current.state,- status: submissionStatus(status.dispatch),- dispatch: status.dispatch,+ state: current.state,+ view,};}return current;}-type RuntimeArchiveView = Pick<CliRuntimeArchiveControl, "status" | "close">;--/**- * A Run Source needs the archive only when it names a historical Build Candidate.- * Delay Store assembly until that edge is actually resolved.- */-function lazyRuntimeArchive(- host: NodeRuntimeHost,-): RuntimeArchiveView {- let loading: Promise<CliRuntimeArchiveControl> | undefined;- const open = (): Promise<CliRuntimeArchiveControl> => {- loading ??= loadRuntimeArchive(host);- return loading;- };- return {- async status(build) {- return await (await open()).status(build);- },- async close() {- if (loading !== undefined) await (await loading).close();- },- };-}-export async function runCli(argv: readonly string[],io: CliIo,@@ -986,23 +1049,32 @@ export async function runCli(}return await opened;};- const projectResults = async (root = join(commandProjectRoot(), ".hypit", "results")) => {- if (args.runtime !== undefined) {- const host = await runtimeHost(args.runtime);- if (host.openResults !== undefined) return await host.openResults(root);+ const projectResults = async (projectRoot = commandProjectRoot()) => {+ if (distribution.openProjectResults !== undefined) {+ const packageRoot = await packageRootForProject(projectRoot);+ return await distribution.openProjectResults(projectRoot, {+ packageRoot,+ ...(distribution.packageRoot === undefined ? {} : { distributionPackageRoot: distribution.packageRoot }),+ });}+ const root = join(projectRoot, ".hypit", "results");return {location: {- root,- selection: { use: "@hypit/build-result-fs", config: { path: "." } },+ root: projectRoot,+ selection: { use: "@hypit/build-result-fs", config: { path: ".hypit/results" } },},repository: new FileBuildResultRepository(root),close() {},} as const;};if (args.command === "_worker") {- if (args.file === undefined || args.readyFile === undefined) throw new Error("internal Worker launch is incomplete");- await (await runtimeHost(args.file, await packageRootForProject())).runWorker(args.readyFile);+ if (args.file === undefined || args.readyFile === undefined || args.workerOwner === undefined) {+ throw new Error("internal Worker launch is incomplete");+ }+ await (await runtimeHost(+ args.file,+ args.packageRoot ?? await packageRootForProject(),+ )).runWorker(args.readyFile, args.workerOwner);return;}if (args.command === "runtime" && args.action === "use") {@@ -1063,28 +1135,44 @@ export async function runCli(|| args.command === "build" || args.command === "status" || args.command === "builds"|| args.command === "history"|| args.command === "inspect" || args.command === "get" || args.command === "cancel"+ || args.command === "result"|| args.command === "doctor" || args.command === "programs"- || args.command === "runtime" || args.command === "queue" || args.command === "paths"+ || args.command === "runtime" || args.command === "activity" || args.command === "paths"|| args.command === "image" || args.command === "packages";const operational = known || args.command === "auth";- const fileOptional = args.command === "builds" || args.command === "history" || args.command === "queue"+ const fileOptional = args.command === "builds" || args.command === "history" || args.command === "activity"|| args.command === "paths" || args.command === "image"|| args.command === "programs" || args.command === "runtime" || args.command === "doctor";if (!operational || (!fileOptional && args.file === undefined)) {throw new Error(usage());}- if (args.watch && args.command !== "queue" && args.command !== "status") {- throw new Error("--watch applies only to status or queue");+ if (args.watch && args.command !== "activity" && args.command !== "status") {+ throw new Error("--watch applies only to status or activity");}- if (args.jsonl && (args.command !== "queue" || !args.watch)) {- throw new Error("--jsonl applies only to queue --watch");+ if (args.jsonl && (args.command !== "activity" || !args.watch)) {+ throw new Error("--jsonl applies only to activity --watch");}- if (args.command === "queue" && args.watch && args.json) {- throw new Error("queue --watch is a stream; use --jsonl instead of --json");+ if (args.command === "activity" && args.watch && args.json) {+ throw new Error("activity --watch is a stream; use --jsonl instead of --json");}if (args.command === "history" && args.file === undefined && args.source === undefined) {throw new Error("history requires an output name or --source path");}+ if (args.command === "result" && args.action !== "finish"+ && args.action !== "discard" && args.action !== "edit") {+ throw new Error("result accepts finish, discard or edit");+ }+ if (args.command === "result" && args.action === "edit") {+ if (args.title !== undefined && args.clearTitle) throw new Error("--title and --clear-title are mutually exclusive");+ if (args.note !== undefined && args.clearNote) throw new Error("--note and --clear-note are mutually exclusive");+ if (args.highlightedOutputs.length > 0 && args.clearHighlights) {+ throw new Error("--highlight and --clear-highlights are mutually exclusive");+ }+ if (args.title === undefined && args.note === undefined && args.highlightedOutputs.length === 0+ && !args.clearTitle && !args.clearNote && !args.clearHighlights) {+ throw new Error("result edit requires a presentation change");+ }+ }assertCommandOptions(args);if (args.excludeTargets && !args.pin) {throw new Error("--exclude-targets requires history --pin");@@ -1195,12 +1283,29 @@ export async function runCli(throw new Error("doctor requires a Runtime Profile; run hypit runtime use <profile> or provide it positionally");}const profile = resolve(profileInput);- const result = await (await runtimeHost(profile)).doctor();+ const [result, projectResult] = await Promise.all([+ (await runtimeHost(profile)).doctor(),+ distribution.diagnoseProjectResults === undefined+ ? undefined+ : distribution.diagnoseProjectResults(commandProjectRoot(), {+ packageRoot: await packageRootForProject(),+ ...(distribution.packageRoot === undefined+ ? {}+ : { distributionPackageRoot: distribution.packageRoot }),+ }),+ ]);+ const diagnostics = [...result.diagnostics, ...(projectResult?.diagnostics ?? [])];const machine = {format: "hypit.cli-doctor@1" as const,- ok: !result.diagnostics.some((item) => item.severity === "error"),+ ok: !diagnostics.some((item) => item.severity === "error"),dataRoot: result.dataRoot,- diagnostics: result.diagnostics,+ ...(projectResult?.location === undefined ? {} : {+ resultRepository: {+ root: projectResult.location.root,+ use: projectResult.location.selection.use,+ },+ }),+ diagnostics,};writeCliOutput(io, args, { kind: "doctor", machine, profile });if (!machine.ok) io.setExitCode?.(1);@@ -1321,8 +1426,8 @@ export async function runCli(}// These are independent views over one Profile. Load them concurrently without inventing a// second registry; each selected package remains responsible for its own report.- const runtimeLoading = loadRuntimeArchive(await runtimeHost(profile));- let runtime: CliRuntimeArchiveControl | undefined;+ const runtimeLoading = loadRuntimeControl(await runtimeHost(profile));+ let runtime: CliRuntimeControl | undefined;try {const loaded = await Promise.all([controller.worker.status(),@@ -1331,15 +1436,16 @@ export async function runCli(]);const [worker, external, selectedRuntime] = loaded;runtime = selectedRuntime;- const queue = await runtime.queue();- const counts = Object.fromEntries(["queued", "running", "waiting", "terminal"]- .map((phase) => [phase, queue.dispatches.filter((item) => item.phase === phase).length]));- const lanes = summarizeQueueLanes(queue.capacity);+ const activity = await runtime.activity();+ const counts = Object.fromEntries(+ ["submitting", "ready", "running", "waiting", "saving-result"].map((name) =>+ [name, activity.builds.filter((item) => item.activity === name).length]),+ );+ const lanes = summarizeQueueLanes(activity.capacity);const ready = worker.state === "running"&& external.programs.every((item) => item.state.state === "ready");- const active = ["queued", "running", "waiting"]- .reduce((total, phase) => total + (counts[phase] ?? 0), 0);- const attention = active > 0 && !ready;+ const active = activity.builds.length;+ const attention = activity.builds.some((item) => item.issue !== undefined) || (active > 0 && !ready);const unavailable = external.programs.filter((item) => item.state.state !== "ready");const machine = {format: "hypit.cli-runtime-status@1" as const,@@ -1347,16 +1453,16 @@ export async function runCli(ready,attention,worker,- queue: { counts, lanes, capacity: queue.capacity },+ activity: { counts, lanes },programs: external.programs,};writeOperational(machine, "Runtime status", attention ? "warning" : ready ? "success" : "info", [["Worker", worker.state],- ["Queued", String(counts.queued ?? 0)],+ ["Ready", String(counts.ready ?? 0)],["Running", String(counts.running ?? 0)],["Waiting", String(counts.waiting ?? 0)],["Programs", `${external.programs.length - unavailable.length}/${external.programs.length} ready`],- ["Capacity reservations", String(queue.capacity.length)],+ ["Capacity reservations", String(activity.capacity.length)],], [...unavailable.map(programLine),...queueLaneLines(lanes),@@ -1430,59 +1536,59 @@ export async function runCli(}return;}- if (args.command === "builds" || args.command === "history" || args.command === "inspect" || args.command === "get") {+ if (args.command === "builds" || args.command === "history" || args.command === "inspect"+ || args.command === "get" || (args.command === "result" && args.action === "edit")) {const results = await projectResults();const repository = results.repository;try {if (args.command === "builds") {- const manifests = await repository.list();- const shown = manifests.slice(0, args.verbose ? undefined : 20);- const builds = shown.map((manifest) => ({+ const page = await repository.browse({ limit: args.limit, ...(args.before === undefined ? {} : { before: args.before }) });+ const builds = page.results.map((manifest) => ({build: manifest.id,- ...(manifest.name === undefined ? {} : { name: manifest.name }),- status: manifest.status,- startedAt: manifest.startedAt,+ createdAt: buildCreatedAt(manifest.id),+ ...(manifest.title === undefined ? {} : { title: manifest.title }),+ outcome: manifest.outcome,source: manifest.source,...(manifest.run === undefined ? {} : { run: manifest.run }),targets: manifest.targets,outputs: Object.keys(manifest.outputs),}));- writeOperational({ builds }, "Build results", "info", [["Builds", String(manifests.length)]],+ writeOperational({ format: "hypit.cli-builds@2", builds, ...(page.next === undefined ? {} : { next: page.next }) },+ "Build results", "info", [["Builds", String(builds.length)]],builds.map((item) => {const source = basename(item.run?.path ?? item.source.path);- const label = item.name === undefined ? item.build : `${item.name} · ${item.build}`;- return `${label}: ${item.status} · ${source} · ${item.outputs.length} outputs`;- }));+ const label = item.title === undefined ? item.build : `${item.title} · ${item.build}`;+ return `${label}: ${item.outcome} · ${new Date(item.createdAt).toLocaleString()} · ${source} · ${item.targets.join(", ")}`;+ }).concat(page.next === undefined ? [] : [`Older hypit builds --before ${page.next}`]));return;}if (args.command === "history") {- const manifests = await repository.list();+ const page = await repository.browse({ limit: args.limit, ...(args.before === undefined ? {} : { before: args.before }) });const source = args.source === undefined ? undefined : resolve(args.source);- const entries = manifests.flatMap((manifest) => {+ const entries = page.results.flatMap((manifest) => {if (source !== undefined && manifest.source.path !== source) return [];return Object.entries(manifest.outputs).flatMap(([name, output]) => {if (args.file !== undefined && name !== args.file) return [];if (args.excludeTargets && manifest.targets.includes(name)) return [];return [{build: manifest.id,- createdAt: manifest.startedAt,- status: manifest.status,+ createdAt: buildCreatedAt(manifest.id),+ outcome: manifest.outcome,source: manifest.source,...(manifest.run === undefined ? {} : { run: manifest.run }),output: { name, type: output.type, value: output.value },}];});- }).sort((left, right) => right.createdAt - left.createdAt- || left.output.name.localeCompare(right.output.name)- || left.build.localeCompare(right.build));+ });const pins = args.pin ? pinnedRecords(entries) : [];- const shown = entries.slice(0, args.verbose ? undefined : 20);writeOperational({+ format: "hypit.cli-history@2",query: {...(args.file === undefined ? {} : { output: args.file }),...(source === undefined ? {} : { source }),},entries,+ ...(page.next === undefined ? {} : { next: page.next }),...(args.pin ? { pins } : {}),}, entries.length === 0 ? "No Build Output history" : args.pin ? "Reuse these Outputs" : "Output history",entries.length === 0 ? "warning" : "info", [@@ -1491,10 +1597,13 @@ export async function runCli(["Outputs", String(entries.length)],], args.pin? ["Paste into a Run Source; every reference names one exact Build Output.", ...pins.flatMap((item) => item.markup)]- : shown.map((item) => {+ : entries.map((item) => {const created = new Date(item.createdAt).toISOString();- return `${item.build}: ${item.output.name} · ${created} · ${item.output.value.kind}`;- }));+ const kind = item.output.value.kind === "build-file"+ ? item.output.value.mediaType+ : item.output.value.kind === "inline" ? "inline value" : "structured value";+ return `${item.build}: ${item.output.name} · ${displayType(item.output.type)} · ${kind} · ${created}`;+ }).concat(page.next === undefined ? [] : [`Older hypit history${args.file === undefined ? "" : ` ${args.file}`} --before ${page.next}`]));return;}if (args.command === "inspect") {@@ -1506,10 +1615,11 @@ export async function runCli(type: output.type,value: output.value,}));- writeOperational({ result: manifest, outputs }, "Build Result detail", manifest.status === "failed" ? "error" : "info", [+ writeOperational({ format: "hypit.cli-inspect@2", result: manifest }, "Build Result detail", manifest.outcome === "failed" ? "error" : "info", [["Build", manifest.id],- ...(manifest.name === undefined ? [] : [["Name", manifest.name] as const]),- ["Status", manifest.status],+ ["Created", new Date(buildCreatedAt(manifest.id)).toLocaleString()],+ ...(manifest.title === undefined ? [] : [["Title", manifest.title] as const]),+ ["Outcome", manifest.outcome ?? "unfinished"],["Targets", String(manifest.targets.length)],["Outputs", String(outputs.length)],], [@@ -1518,31 +1628,50 @@ export async function runCli(]);return;}- if (args.record !== undefined || args.output !== undefined || args.artifact !== undefined) {- throw new Error("get now addresses Build Results by --name; Record, Logical Output id and Artifact digest selectors were removed");+ if (args.command === "result") {+ const manifest = await repository.updatePresentation(args.file!, {+ ...(args.clearTitle ? { title: null } : args.title === undefined ? {} : { title: args.title }),+ ...(args.clearNote ? { note: null } : args.note === undefined ? {} : { note: args.note }),+ ...(args.clearHighlights+ ? { highlightedOutputs: [] }+ : args.highlightedOutputs.length === 0 ? {} : { highlightedOutputs: args.highlightedOutputs }),+ });+ const presentation = {+ format: "hypit.cli-result-edit@2",+ build: manifest.id,+ title: manifest.title ?? null,+ note: manifest.note ?? null,+ highlightedOutputs: manifest.highlightedOutputs ?? [],+ };+ writeOperational(presentation, "Build Result updated", "success", [+ ["Build", manifest.id],+ ["Title", manifest.title ?? "—"],+ ["Highlighted", String(manifest.highlightedOutputs?.length ?? 0)],+ ], manifest.note === undefined ? [] : [`Note ${manifest.note}`]);+ return;}const manifest = await repository.read(args.file!);if (manifest === undefined) throw new Error(`Build Result ${args.file} does not exist`);const available = Object.keys(manifest.outputs);- const name = args.name+ const name = args.output?? (manifest.targets.length === 1 && manifest.outputs[manifest.targets[0]!] !== undefined? manifest.targets[0]: available.length === 1 ? available[0] : undefined);- if (name === undefined) throw new Error(`Build ${manifest.id} has several Outputs; select one with --name`);+ if (name === undefined) throw new Error(`Build ${manifest.id} has several Outputs; select one with --output`);const resolved = await repository.resolve(manifest.id, name);if (resolved === undefined) throw new Error(`Build ${manifest.id} has no Output ${name}`);if (args.to === undefined) {- writeOperational({ build: manifest.id, output: name, resolved }, "Build Output", "info", [+ writeOperational({ format: "hypit.cli-get@2", build: manifest.id, output: name, type: resolved.type, value: resolved.value }, "Build Output", "info", [["Build", manifest.id],["Output", name],["Type", displayType(resolved.type)],- ["Storage", resolved.value.kind],+ ...(resolved.value.kind === "build-file" ? [["Media", `${resolved.value.mediaType} · ${resolved.value.size} bytes`] as const] : []),], resolved.build === manifest.id && resolved.output === name? []: [`Forwards to ${resolved.build} / ${resolved.output}`]);} else {const materialized = await materializeRepositoryBuildResultOutput(repository, manifest.id, name, args.to);- writeOperational({ build: manifest.id, output: name, resolved, materialized }, "Build Output materialized", "success", [+ writeOperational({ format: "hypit.cli-get@2", build: manifest.id, output: name, path: materialized.path, kind: materialized.kind }, "Build Output materialized", "success", [["Build", manifest.id], ["Output", name], ["Path", materialized.path],]);}@@ -1551,187 +1680,279 @@ export async function runCli(await results.close();}}- if (args.command === "status" || args.command === "cancel" || args.command === "queue"+ if (args.command === "status" && args.runtime === undefined) {+ const openedResults = await projectResults();+ let result;+ try {+ result = await openedResults.repository.read(args.file!);+ } finally {+ await openedResults.close();+ }+ if (args.watch && result?.outcome === undefined) {+ throw new Error(+ `Build ${args.file} has no finished Result; select its Runtime to observe active execution`,+ );+ }+ const finished = result?.outcome !== undefined;+ const machine = {+ format: "hypit.cli-status@2",+ build: result === undefined ? null : {+ id: result.id,+ ...(result.outcome === undefined ? {} : { outcome: result.outcome }),+ result: {+ title: result.title,+ targets: result.targets,+ outputs: Object.keys(result.outputs),+ outcome: result.outcome,+ },+ operations: [],+ },+ };+ writeOperational(machine, result === undefined+ ? "Build Result not found"+ : finished ? "Build Result is finished" : "Build Result is unfinished",+ result === undefined || !finished ? "warning" : "info", [+ ["Build", args.file!],+ ["Runtime", "not selected; execution state is unknown"],+ ...(result?.outcome === undefined ? [] : [["Outcome", result.outcome] as const]),+ ["Operations", "0"],+ ], result === undefined ? [] : [+ "Result and Runtime are independent facts; select the Runtime to inspect active execution.",+ ]);+ if (result === undefined || !finished) io.setExitCode?.(1);+ return;+ }+ if (args.command === "status" || args.command === "cancel" || args.command === "activity"+ || (args.command === "result" && (args.action === "finish" || args.action === "discard"))) {if (args.runtime === undefined) {throw new Error(`${args.command} requires a Runtime; run hypit runtime use <profile> or pass --runtime <profile>`,);}- const runtime = await loadRuntimeArchive(await runtimeHost(args.runtime), args.command !== "cancel");+ const selectedHost = await runtimeHost(args.runtime);+ const runtime = await loadRuntimeControl(+ selectedHost,+ args.command !== "cancel",+ );try {- if (args.command === "queue") {+ if (args.command === "activity") {const controller = await runtimeController(args.runtime);let previous: string | undefined;- const writeQueue = async (): Promise<void> => {- const [queue, worker] = await Promise.all([- runtime.queue(),+ const writeActivity = async (): Promise<void> => {+ const [activity, worker] = await Promise.all([+ runtime.activity(),controller.worker.status(),]);- const queueView = JSON.stringify({- dispatches: queue.dispatches,- capacity: queue.capacity,+ const currentView = JSON.stringify({+ builds: activity.builds,+ capacity: activity.capacity,worker,- operations: queue.operations.map((item) => ({- id: item.id,- status: item.status,- progress: item.progress,- })),});- if (args.watch && queueView === previous) return;- previous = queueView;+ if (args.watch && currentView === previous) return;+ previous = currentView;const value = {- format: "hypit.cli-queue@1",+ format: "hypit.cli-activity@1",at: Date.now(),worker,- dispatches: queue.dispatches,- lanes: summarizeQueueLanes(queue.capacity),- capacity: queue.capacity,- operations: queue.operations.map((item) => ({- id: item.id,- build: item.build,- endpoint: item.endpoint,- pool: item.pool,- lane: item.lane,- status: item.status,- ...(item.progress === undefined ? {} : { progress: item.progress }),- })),+ builds: activity.builds,+ lanes: summarizeQueueLanes(activity.capacity),};- const active = queue.dispatches.filter((item) => item.phase !== "terminal");- const activeOperations = queue.operations.filter((item) =>- item.status === "pending");- const buildLines = active.slice(0, args.verbose ? undefined : 12).map((item) =>- `${item.build}: ${item.phase}${item.cancellation === undefined ? "" : " · cancelling"}`);- const laneLines = queueLaneLines(summarizeQueueLanes(queue.capacity));- const genericCapacityLines = queue.capacity.filter((item) => item.queue === undefined)- .slice(0, args.verbose ? undefined : 12)- .map((item) => `${item.resources.map((resource) => resource.id).join(" + ")}: remote · ${item.build}`);- const operationLines = activeOperations.slice(0, args.verbose ? undefined : 12).map((item) =>- `${item.build} · ${item.pool} → ${item.lane}: ${item.progress === undefined- ? item.status- : formatOperationProgress(item.progress)}`);- writeOperational(value, "Runtime queue", active.length === 0 ? "success" : "info", [- ["Active Builds", String(active.length)],+ const buildLines = activity.builds.slice(0, args.verbose ? undefined : 12).map((item) =>+ `${item.id}: ${item.activity}`+ + `${item.cancellationRequested ? " · cancelling" : ""}`+ + `${item.issue === undefined ? "" : ` · ${item.issue.scope}: ${item.issue.message}`}`);+ const activeOperations = activity.builds.flatMap((item) => item.operations)+ .filter((item) => item.status === "pending");+ const operationLines = args.verbose+ ? activity.builds.flatMap((build) => build.operations.filter((item) => item.status === "pending")+ .map((item) => `${build.id} · ${item.endpoint}: ${item.progress === undefined+ ? item.status+ : formatOperationProgress(item.progress)}`))+ : [];+ writeOperational(value, "Runtime activity", activity.builds.length === 0 ? "success" : "info", [+ ["Active Builds", String(activity.builds.length)],["Active Operations", String(activeOperations.length)],["Worker", worker.pid === undefined ? worker.state : `${worker.state} · ${worker.pid}`],- ["Operation tickets", String(queue.capacity.length)],], [...buildLines,...(operationLines.length === 0 ? [] : ["Operations:", ...operationLines]),- ...(laneLines.length === 0 ? [] : ["Provider queues:", ...laneLines]),- ...(genericCapacityLines.length === 0 ? [] : ["Other resources:", ...genericCapacityLines]),+ ...(args.verbose ? queueLaneLines(summarizeQueueLanes(activity.capacity)) : []),]);};- if (!args.watch) await writeQueue();+ if (!args.watch) await writeActivity();else while (true) {- await writeQueue();+ await writeActivity();await new Promise((resolveWait) => setTimeout(resolveWait, 1_000));}} else if (args.command === "status") {- let status = await runtime.status(args.file!);- if (args.watch && status.build !== undefined && status.dispatch !== undefined) {- await observeBuild(runtime, {- id: status.build.build,- state: status.build.state,- status: submissionStatus(status.dispatch),- dispatch: status.dispatch,- }, {- ...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),- controller: await runtimeController(args.runtime),- ...(args.json ? {} : {- onProgress: (progress) => {- const operations = Object.entries(progress.operations)- .map(([operationStatus, count]) => `${count} ${operationStatus}`)- .join(", ");- io.write(` · ${progress.build}: ${progress.phase}`- + `${operations.length === 0 ? "" : ` · ${operations}`}\n`);- for (const line of progress.activity) io.write(` ${line}\n`);- },- }),- });- status = await runtime.status(args.file!);+ let view = await runtime.inspect(args.file!);+ let result: BuildResultManifest | undefined;+ let resultReadError: string | undefined;+ let openedResults: Awaited<ReturnType<typeof projectResults>> | undefined;+ try {+ openedResults = await projectResults();+ if (args.watch && view !== undefined && view.issue === undefined) {+ const startedAt = Date.now();+ let delayMs = 100;+ let previous: string | undefined;+ const controller = await runtimeController(args.runtime);+ while (view !== undefined && view.issue === undefined) {+ const encoded = JSON.stringify(view);+ if (encoded !== previous && !args.json) {+ previous = encoded;+ io.write(` · ${view.id}: ${view.activity}`+ + `${view.operations.length === 0 ? "" : ` · ${view.operations.length} operation(s)`}\n`);+ delayMs = 100;+ } else {+ delayMs = Math.min(1_000, delayMs * 2);+ }+ const remaining = args.maxWaitMs === undefined+ ? undefined+ : args.maxWaitMs - (Date.now() - startedAt);+ if (remaining !== undefined && remaining <= 0) break;+ const worker = await controller.worker.status();+ if (worker.state !== "running") break;+ await new Promise((resolveWait) => setTimeout(resolveWait,+ remaining === undefined ? delayMs : Math.min(delayMs, remaining)));+ view = await runtime.inspect(args.file!);+ }+ }+ result = await openedResults.repository.read(args.file!);+ } catch (error) {+ resultReadError = error instanceof Error ? error.message : String(error);+ } finally {+ await openedResults?.close();}- const openedResults = await projectResults();- const result = await openedResults.repository.read(args.file!).finally(async () => await openedResults.close());- const found = status.build !== undefined || status.dispatch !== undefined || result !== undefined;- const effectiveStatus = status.dispatch === undefined- ? status.build?.state.status ?? result?.status- : submissionStatus(status.dispatch);+ const found = view !== undefined || result !== undefined;+ const activity = view?.activity;+ const outcome = result?.outcome ?? view?.outcome;+ const issue = view?.issue;+ const resultSummary = result === undefined ? undefined : {+ title: result.title,+ targets: result.targets,+ outputs: Object.keys(result.outputs),+ outcome: result.outcome,+ };const machine = {+ format: "hypit.cli-status@2",build: !found ? null : {- id: status.build?.build ?? status.dispatch?.build ?? result!.id,- status: effectiveStatus,- ...(status.build === undefined ? {} : {- coreStatus: status.build.state.status,- diagnostics: status.build.state.diagnostics,- }),- ...(result === undefined ? {} : { result }),+ id: view?.id ?? result!.id,+ ...(activity === undefined ? {} : { activity }),+ ...(outcome === undefined ? {} : { outcome }),+ ...(issue === undefined ? {} : { issue }),+ ...(resultSummary === undefined ? {} : { result: resultSummary }),+ operations: view?.operations ?? [],},- catalog: status.catalog === undefined- ? null- : summarizeBuildCatalog(status.catalog, status.build?.state),- operations: status.operations.map((operation) => ({- id: operation.id,- command: operation.command,- endpoint: operation.endpoint,- status: operation.status,- ...(operation.wakeAt === undefined ? {} : { wakeAt: operation.wakeAt }),- ...(operation.progress === undefined ? {} : { progress: operation.progress }),- ...(operation.failure === undefined ? {} : { failure: operation.failure }),- })),- dispatch: status.dispatch ?? null,+ ...(resultReadError === undefined ? {} : { resultReadError }),};- const phase = status.dispatch?.phase ?? "missing";- const notableOperations = status.operations.filter((operation) =>- operation.status !== "completed").slice(0, args.verbose ? undefined : 12);- const terminal = status.dispatch?.phase === "terminal";writeOperational(machine, !found? "Build not found"+ : issue !== undefined+ ? "Build needs attention": args.watch- ? terminal ? "Build finished" : "Build still running"+ ? activity === undefined ? "Build finished" : "Build still active": "Build status",!found? "warning"- : status.dispatch?.terminal === "failed"+ : issue !== undefined || resultReadError !== undefined+ ? "error"+ : outcome === "failed"? "error"- : args.watch && !terminal ? "warning" : "info", [+ : args.watch && activity !== undefined ? "warning" : "info", [["Build", args.file!],- ["Status", effectiveStatus ?? "missing"],- ...(status.build === undefined || terminal || effectiveStatus === status.build.state.status- ? []- : [["Core", status.build.state.status] as const]),- ["Dispatch", phase],- ["Operations", String(status.operations.length)],- ], notableOperations.map((operation) => operation.failure !== undefined+ ...(result?.title === undefined ? [] : [["Title", result.title] as const]),+ ...(activity === undefined ? [] : [["Activity", activity] as const]),+ ...(outcome === undefined ? [] : [["Outcome", outcome] as const]),+ ...(result === undefined ? [] : [["Outputs", String(Object.keys(result.outputs).length)] as const]),+ ], (view?.operations ?? []).filter((operation) => operation.status !== "completed")+ .slice(0, args.verbose ? undefined : 12).map((operation) => operation.failure !== undefined? `${operation.endpoint}: ${operation.failure.code} — ${operation.failure.message}`: operation.progress === undefined? `${operation.endpoint}: ${operation.status}`: `${operation.endpoint}: ${formatOperationProgress(operation.progress)}`)- .concat(status.dispatch?.reason === undefined ? [] : [`Reason ${status.dispatch.reason}`]));- if (!found || status.dispatch?.terminal === "failed") io.setExitCode?.(1);+ .concat(issue === undefined ? [] : [+ `${issue.scope === "result" ? "Result save" : "Cleanup"} ${issue.message}`,+ ])+ .concat(resultReadError === undefined ? [] : [`Result unavailable: ${resultReadError}`])+ .concat(issue === undefined ? [] : [`Finish hypit result finish ${args.file}`]));+ if (!found || issue !== undefined || resultReadError !== undefined || outcome === "failed") io.setExitCode?.(1);+ } else if (args.command === "result") {+ if (args.action === "discard") {+ const resultControl = await selectedHost.openResultControl();+ const discarded = await resultControl.discardSubmission(args.file!)+ .finally(async () => await resultControl.close());+ writeOperational({ format: "hypit.cli-result-discard@1", build: args.file, discarded }, discarded+ ? "Incomplete Build discarded"+ : "Incomplete Build not found", discarded ? "success" : "warning", [+ ["Build", args.file!],+ ["State", discarded ? "discarded" : "missing"],+ ], discarded ? [+ "The incomplete submission, Result draft and temporary Build files were removed.",+ ] : []);+ if (!discarded) io.setExitCode?.(1);+ return;+ }+ const before = await runtime.inspect(args.file!);+ if (before !== undefined && before.activity !== "saving-result") {+ throw new Error(`Build ${args.file} is still ${before.activity}; there is no Result write to finish`);+ }+ if (before !== undefined && before.issue === undefined) {+ const worker = await (await selectedHost.controller()).worker.status();+ if (worker.state === "running") {+ throw new Error(`Build ${args.file} Result is currently being written by the Runtime Worker`);+ }+ }+ const resultControl = await selectedHost.openResultControl();+ const finished = await resultControl.finishResult(args.file!)+ .finally(async () => await resultControl.close());+ if (finished === undefined) {+ const opened = await projectResults();+ const existing = await opened.repository.read(args.file!).finally(async () => await opened.close());+ if (existing?.outcome === undefined) {+ writeOperational({ format: "hypit.cli-result-finish@1", build: args.file, found: false },+ "Build not found", "warning", [["Build", args.file!]]);+ io.setExitCode?.(1);+ return;+ }+ writeOperational({ format: "hypit.cli-result-finish@1", build: args.file, outcome: existing.outcome },+ "Result already finished", "info", [["Build", args.file!], ["Outcome", existing.outcome]]);+ return;+ }+ writeOperational({+ format: "hypit.cli-result-finish@1",+ build: args.file,+ outcome: finished.outcome,+ ...(finished.issue === undefined ? {} : { issue: finished.issue }),+ }, finished.issue === undefined ? "Result finished" : "Result still needs attention",+ finished.issue === undefined ? "success" : "error", [+ ["Build", args.file!],+ ["Outcome", finished.outcome],+ ], finished.issue === undefined ? [] : [`${finished.issue.scope}: ${finished.issue.message}`]);+ if (finished.issue !== undefined) io.setExitCode?.(1);} else {- const result = await runtime.cancel(args.file!, args.reason);+ const active = await runtime.cancel(args.file!, args.reason);+ const openedResults = active === undefined ? await projectResults() : undefined;+ const finished = openedResults === undefined+ ? undefined+ : await openedResults.repository.read(args.file!).finally(async () => await openedResults.close());const machine = {+ format: "hypit.cli-cancel@2",build: args.file,- requested: result !== undefined- && (result.phase !== "terminal" || result.terminal === "cancelled"),- phase: result?.phase,- terminal: result?.terminal,+ requested: active?.cancellationRequested === true,+ ...(active === undefined ? {} : { activity: active.activity }),+ outcome: active?.outcome ?? finished?.outcome,};- const title = result === undefined+ const title = active === undefined && finished === undefined? "Build not found"- : result.terminal === "cancelled"- ? "Build cancelled"- : result.phase === "terminal"- ? "Build already finished"- : "Build cancellation requested";+ : active === undefined ? "Build already finished" : "Build cancellation requested";writeOperational(machine, title,- result === undefined ? "warning" : result.phase === "terminal" && result.terminal !== "cancelled" ? "info" : "success", [- ["Build", args.file!], ["Phase", result?.phase ?? "missing"],- ], result?.phase === "terminal" && result.terminal !== "cancelled"- ? [`No running work was changed; this Build is already ${result.terminal}.`]+ active === undefined && finished === undefined ? "warning" : active === undefined ? "info" : "success", [+ ["Build", args.file!], ...(machine.activity === undefined ? [] : [["Activity", machine.activity] as const]),+ ], active === undefined && finished?.outcome !== undefined+ ? [`No running work was changed; this Build is already ${finished.outcome}.`]: []);- if (result === undefined) io.setExitCode?.(1);+ if (active === undefined && finished === undefined) io.setExitCode?.(1);}} finally {await runtime.close();@@ -1745,7 +1966,7 @@ export async function runCli(const effectiveWorkspaceRoot = args.workspaceRoot?? selectedRuntimeProjectRoot?? dirname(resolve(args.file!));- const projectResultsRoot = join(effectiveWorkspaceRoot, ".hypit", "results");+ const projectResultsRoot = effectiveWorkspaceRoot;const sourcePackageRoot = effectivePackageRoot?? await resolvePackageRoot(effectiveWorkspaceRoot);const loadedPackageSet = distribution.discoverSourcePackages === undefined@@ -1802,7 +2023,7 @@ export async function runCli(targets: loaded.document.targets,candidates: Object.fromEntries(loaded.document.candidates.map((item) => [item.id, item.kind])),satisfactions: loaded.document.satisfactions,- unresolvedBuildRecords: loaded.unresolvedBuildRecords,+ unresolvedHistoricalOutputs: loaded.unresolvedHistoricalOutputs,deterministic_durations: deterministicSpeechDurationsFromGraph(loaded.author.graph, loaded.author.program.records),} as const;writeCliOutput(io, args, {@@ -1837,23 +2058,18 @@ export async function runCli(throw new Error("build requires a Runtime; run hypit runtime use <profile> or pass --runtime <profile>");}const buildResults = await projectResults(projectResultsRoot);- let archive: RuntimeArchiveView | undefined;let loadedRun;try {- archive = lazyRuntimeArchive(await runtimeHost(args.runtime));loadedRun = await loadRunFile({workspace,authorCompiler: compiler,frontends: runFrontends,packageContributions,- runtime: archive,results: buildResults.repository,});} catch (error) {await buildResults.close();throw error;- } finally {- await archive?.close();}const result = await (async () => {try {@@ -1875,7 +2091,7 @@ export async function runCli(const request = {// One CLI invocation is one execution instance. Source and Plan identity// remain in Core; they never reclaim a previous Build.- id: `bld_${randomUUID()}`,+ id: createPublicBuildId(),definition: result.definition,...(loadedPackageSet === undefined ? {} : {componentPackages: loadedPackageSet@@ -1886,41 +2102,35 @@ export async function runCli(attachments: result.compilation.attachments,result: {repository: buildResults.location,- ...(args.name === undefined ? {} : { name: args.name }),- reuses: result.compilation.run.document.candidates.flatMap((candidate) => {- if (candidate.kind !== "build-record") return [];- const resolvedCandidate = result.compilation.run.candidates[candidate.id];- return resolvedCandidate === undefined ? [] : [{- candidate: resolvedCandidate,- build: candidate.build,- output: candidate.output,- }];- }),+ ...(args.title === undefined ? {} : { title: args.title }),+ forwards: result.resultForwards.filter((forward) =>+ catalog.publishedOutputs.some((published) => published.ref.id === forward.output)),},} as const;const controller = await (await runtimeHost(args.runtime)).controller({packageRoot: sourcePackageRoot,});- let worker = await controller.worker.status();const preflight = await preflightPlan(await runtimeHost(args.runtime), result.state);// Build is an execution boundary, not a provisioning command. The cheap// preflight must already be clean; `runtime up` is the explicit place for// installing or starting declared programs.assertPreflight(preflight);- runtime = await loadRuntime(await runtimeHost(args.runtime));- let built = await runtime.build(request);+ let worker;try {worker = await controller.worker.up({...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),});} catch (error) {const detail = error instanceof Error ? error.message : String(error);- throw new Error(`Build ${built.id} is queued, but the Runtime Worker could not start: ${detail}`);+ throw new Error(`Runtime Worker could not start; no Build was queued: ${detail}`);}+ runtime = await loadRuntime(await runtimeHost(args.runtime));+ let built = await runtime.build(request);if (args.follow && runtime !== undefined) {built = await observeBuild(runtime, built, {...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),controller,+ readResult: async () => await buildResults.repository.read(built.id),...(args.json || args.jsonl ? {} : {onProgress: (progress) => {const operations = Object.entries(progress.operations)@@ -1933,22 +2143,26 @@ export async function runCli(}),});}- const terminal = built.dispatch.phase === "terminal";- const terminalResult = terminal+ const finished = "completion" in built;+ const activeView = "view" in built ? built.view : undefined;+ const completionReason = "completion" in built ? built.completion.reason : undefined;+ const buildOutcome = "completion" in built ? built.completion.outcome : activeView?.outcome;+ const issue = activeView?.issue;+ const finishedResult = finished? await buildResults.repository.read(built.id): undefined;- const targetOutputs = new Set(built.state.request.targets.map((target) => target.output));+ const targetOutputs = new Set(built.state.targets.map((target) => target.output));const presentation = catalog;- const targetAliases = presentation.aliases.filter((alias) =>- alias.ref.kind === "logical-output" && targetOutputs.has(alias.ref.id));- const targetPresentations = targetAliases.flatMap((alias) => {- const selection = built.state.plan.selections.find((item) => item.output === alias.ref.id);+ const targetPublishedOutputs = presentation.publishedOutputs.filter((published) =>+ targetOutputs.has(published.ref.id));+ const targetPresentations = targetPublishedOutputs.flatMap((published) => {+ const selection = built.state.plan.outputBindings.find((item) => item.output === published.ref.id);const record = selection === undefined? undefined: built.state.records.find((item) => item.id === selection.record);if (record === undefined) return [];return [{- alias,+ published,record,...(record?.value.kind === "inline"? { inline: inlineValuePreview(record.value.value) }@@ -1956,37 +2170,34 @@ export async function runCli(}];});const machine = {- build: built.id,- ...(args.name === undefined ? {} : { name: args.name }),- status: built.status,- worker,- ...(terminalResult === undefined ? {} : { result: terminalResult }),- goals: built.state.plan.goals.map((goal) => {- const record = built.state.records.find((item) => item.id === goal.record);- return {- record: goal.record,- type: goal.type,- ...(record === undefined ? {} : { value: record.value }),- };- }),- dispatch: {- phase: built.dispatch.phase,- ...(built.dispatch.cancellation === undefined ? {} : { cancellation: true }),- ...(built.dispatch.reason === undefined ? {} : { reason: built.dispatch.reason }),+ format: "hypit.cli-build@2",+ build: {+ id: built.id,+ ...(args.title === undefined ? {} : { title: args.title }),+ ...(activeView === undefined ? {} : { activity: activeView.activity }),+ ...(buildOutcome === undefined ? {} : { outcome: buildOutcome }),+ ...(issue === undefined ? {} : { issue }),+ ...(finishedResult === undefined ? {} : {+ result: {+ targets: finishedResult.targets,+ outputs: Object.keys(finishedResult.outputs),+ outcome: finishedResult.outcome,+ },+ }),},};const runtimeHint = runtimeNeedsHint ? ` --runtime ${args.runtime}` : "";- const resultTargets = terminalResult?.targets.flatMap((name) => {- const output = terminalResult.outputs[name];+ const resultTargets = finishedResult?.targets.flatMap((name) => {+ const output = finishedResult.outputs[name];return output === undefined ? [] : [{ name, output }];}) ?? [];- const terminalLines = resultTargets.length === 0 && targetPresentations.length === 0+ const finishedLines = resultTargets.length === 0 && targetPresentations.length === 0? [- ...(built.dispatch.reason === undefined ? [] : [`Reason ${built.dispatch.reason}`]),+ ...(completionReason === undefined ? [] : [`Reason ${completionReason}`]),`Inspect hypit inspect ${built.id}`,]: [- ...(built.dispatch.reason === undefined ? [] : [`Reason ${built.dispatch.reason}`]),+ ...(completionReason === undefined ? [] : [`Reason ${completionReason}`]),`Inspect hypit inspect ${built.id}`,...resultTargets.filter((item) => item.output.value.kind === "inline")@@ -1998,44 +2209,45 @@ export async function runCli(.filter((item) => item.output.value.kind !== "inline").slice(0, args.verbose ? undefined : 4).map((item) =>- `Export hypit get ${built.id} --name ${item.name} --to <path>`),+ `Export hypit get ${built.id} --output ${item.name} --to <path>`),...(resultTargets.length > 0 ? [] : targetPresentations.filter((item) => item.inline !== undefined)- .map((item) => `Result ${item.alias.name} = ${item.inline}`)),+ .map((item) => `Result ${item.published.name} = ${item.inline}`)),];writeOperational(machine, args.follow- ? terminal ? "Build finished" : "Build still running"+ ? finished ? "Build finished" : issue !== undefined ? "Result needs attention" : "Build still active": "Build submitted",- built.status === "failed" ? "error"- : built.status === "cancelled" || (args.follow && !terminal) ? "warning" : "success", [+ buildOutcome === "failed" || issue !== undefined ? "error"+ : buildOutcome === "cancelled" || (args.follow && !finished) ? "warning" : "success", [["Build", built.id],- ["Status", built.status],+ ...(activeView === undefined+ ? []+ : [["Activity", activeView.activity] as const]),+ ...(buildOutcome === undefined ? [] : [["Outcome", buildOutcome] as const]),["Worker", worker.state === "running" ? String(worker.pid) : worker.state],- ["Goals", String(terminalResult?.targets.length ?? machine.goals.length)],- ], terminal ? terminalLines : [+ ["Targets", String(finishedResult?.targets.length ?? targetPublishedOutputs.length)],+ ], finished ? finishedLines : issue !== undefined ? [+ `Result ${issue.scope}: ${issue.message}`,+ `Finish hypit result finish ${built.id}${runtimeHint}`,+ ] : [`Watch hypit status ${built.id}${runtimeHint} --watch`,`Cancel hypit cancel ${built.id}${runtimeHint}`,]);- if (built.status === "failed") io.setExitCode?.(1);+ if (buildOutcome === "failed" || issue !== undefined) io.setExitCode?.(1);} finally {await runtime?.close();await buildResults.close();}return;}- let runtime: RuntimeArchiveView | undefined;let planResults: Awaited<ReturnType<typeof projectResults>> | undefined;try {- runtime = args.runtime === undefined- ? undefined- : lazyRuntimeArchive(await runtimeHost(args.runtime));planResults = await projectResults(projectResultsRoot);const loaded = await loadRunFile({workspace,authorCompiler: compiler,frontends: runFrontends,packageContributions,- ...(runtime === undefined ? {} : { runtime }),results: planResults.repository,});const result = loaded.compiler.planCompilation(loaded);@@ -2057,10 +2269,10 @@ export async function runCli(run: loaded.path,outputNames,satisfactionNames: loaded.run.satisfactionNames,+ selections: result.selections,});if (preflight !== undefined && !preflight.ok) io.setExitCode?.(1);} finally {- await runtime?.close();await planResults?.close();}}diff --git a/packages/cli/src/output.ts b/packages/cli/src/output.tsindex 4e7e5e82..b0607e6c 100644--- a/packages/cli/src/output.ts+++ b/packages/cli/src/output.ts@@ -38,6 +38,7 @@ export type DoctorOutput = {readonly format: "hypit.cli-doctor@1";readonly ok: boolean;readonly dataRoot: string;+ readonly resultRepository?: { readonly root: string; readonly use: string };readonly diagnostics: readonly CliDiagnostic[];};@@ -65,7 +66,7 @@ export type RunCheckOutput = {readonly candidates: Readonly<Record<string, string>>;readonly satisfactions: readonly unknown[];readonly steps?: number;- readonly unresolvedBuildRecords?: readonly {+ readonly unresolvedHistoricalOutputs?: readonly {readonly id: string;readonly build: string;readonly output: string;@@ -126,6 +127,7 @@ export type CliPresentation =/** Presentation names declared by this Author Source and Run Source. Never used to plan. */readonly outputNames?: Readonly<Record<string, string>>;readonly satisfactionNames?: Readonly<Record<string, string>>;+ readonly selections?: readonly { readonly output: string; readonly candidate: string; readonly record: string }[];}| {readonly kind: "operational";@@ -214,6 +216,9 @@ function renderDoctor(view: Extract<CliPresentation, { kind: "doctor" }>, io: Cllines.push(...facts([["Profile", shortPath(view.profile)],["Data root", shortPath(view.machine.dataRoot)],+ ...(view.machine.resultRepository === undefined+ ? []+ : [["Result store", `${view.machine.resultRepository.use} · ${shortPath(view.machine.resultRepository.root)}`] as const]),], colors));lines.push("");if (view.machine.diagnostics.length === 0) {@@ -288,11 +293,11 @@ function renderRunCheck(["Satisfactions", String(view.machine.satisfactions.length)],...(view.machine.steps === undefined ? [] : [["Steps", String(view.machine.steps)] as const]),], colors));- const unresolved = view.machine.unresolvedBuildRecords ?? [];+ const unresolved = view.machine.unresolvedHistoricalOutputs ?? [];if (unresolved.length > 0) {lines.push("", heading("warning", `${unresolved.length} historical Candidate${unresolved.length === 1 ? "" : "s"} unresolved`, io, colors));for (const item of unresolved) lines.push(` ${item.id} ← ${item.build}/${item.output}`);- lines.push(` ${colors.dim("The Run source is valid. plan/build will resolve these archived values.")}`);+ lines.push(` ${colors.dim("The Run source is valid. plan/build will resolve these Result values.")}`);}return `${lines.join("\n")}\n`;}@@ -364,9 +369,10 @@ function renderPlan(const capabilityCount = view.machine.preflight.capabilities.length;lines.push(` ${colors.dim(`Runtime base checked; ${capabilityCount} demanded Endpoint ${capabilityCount === 1 ? "capability" : "capabilities"} checked.`)}`);}+ const selections = view.selections ?? [];const visibleSelections = verbose- ? plan.selections- : plan.selections.filter((selection) => view.satisfactionNames?.[selection.output] !== undefined);+ ? selections+ : selections.filter((selection) => view.satisfactionNames?.[selection.output] !== undefined);if (visibleSelections.length > 0) {lines.push("", colors.strong(verbose ? "Selections" : "Run choices"));for (const selection of visibleSelections) {@@ -437,7 +443,8 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undeficolors.accent(colors.strong("hypit doctor")),colors.dim("Diagnose one complete declarative Runtime Profile without submitting work."),"",- " hypit doctor [<runtime-profile>]",+ " hypit doctor [<runtime-profile>] [--workspace <project>]",+ " Checks the Runtime deployment and the project's selected Result Store.",],plan: [colors.accent(colors.strong("hypit plan")),@@ -452,9 +459,9 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undeficolors.accent(colors.strong("hypit build")),colors.dim("Submit one durable Build and ensure its selected Runtime Worker is available."),"",- " hypit build <run-source> [--name <name>] [--runtime <profile>] [--asset-root <directory>] [--follow]",+ " hypit build <run-source> [--title <text>] [--runtime <profile>] [--asset-root <directory>] [--follow]","",- " --name <name> give this execution a human-facing name",+ " --title <text> give this Result a human-facing title"," --follow observe the Build; the Worker still owns execution"," --max-wait-ms <ms> bound startup or follow waiting",],@@ -465,7 +472,7 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi" hypit runtime use <profile> select the Profile for this project"," hypit runtime unset remove only the local selection"," hypit runtime up [<profile>] prepare selected packages, programs and Worker",- " hypit runtime status [<profile>] inspect Worker, queue capacity and declared programs",+ " hypit runtime status [<profile>] inspect Worker, active Builds and declared programs"," hypit runtime logs [<profile>] read Worker logs"," hypit runtime down [<profile>] stop the Worker; external programs keep running",],@@ -487,12 +494,12 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi" hypit programs status [<profile>]"," hypit programs down [<profile>]",],- queue: [- colors.accent(colors.strong("hypit queue")),- colors.dim("Inspect durable Build dispatch and Provider pool capacity."),+ activity: [+ colors.accent(colors.strong("hypit activity")),+ colors.dim("Inspect active Builds and Provider pool capacity."),"",- " hypit queue [--runtime <profile>] [--watch]",- " hypit queue [--runtime <profile>] --watch --jsonl",+ " hypit activity [--runtime <profile>] [--watch]",+ " hypit activity [--runtime <profile>] --watch --jsonl",],paths: [colors.accent(colors.strong("hypit paths")),@@ -504,14 +511,14 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undeficolors.accent(colors.strong("hypit builds")),colors.dim("List project-owned Build Results without opening a Runtime."),"",- " hypit builds [--workspace <project>]",+ " hypit builds [--workspace <project>] [--limit <count>] [--before <build-id>]",],status: [colors.accent(colors.strong("hypit status")),colors.dim("Show one Build now, or keep watching it without owning execution."),""," hypit status <build-id> [--runtime <profile>] [--watch]",- " --watch observe until terminal; the Worker still owns execution",+ " --watch observe until a Result outcome or operator attention"," --max-wait-ms <ms> stop watching after a bounded wait",],inspect: [@@ -524,14 +531,14 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undeficolors.accent(colors.strong("hypit get")),colors.dim("Read or copy one exact named Build Output; copying never reruns work."),"",- " hypit get <build-id> --name <output-name> [--workspace <project>] [--to <path>]",+ " hypit get <build-id> --output <name> [--workspace <project>] [--to <path>]",],history: [colors.accent(colors.strong("hypit history")),colors.dim("Find project Build Outputs from local result manifests."),"",- " hypit history <output-name> [--workspace <project>] [--source <author-source>]",- " hypit history --source <author-source> [--workspace <project>]",+ " hypit history <output-name> [--workspace <project>] [--source <author-source>] [--limit <count>] [--before <build-id>]",+ " hypit history --source <author-source> [--workspace <project>] [--limit <count>] [--before <build-id>]",],cancel: [colors.accent(colors.strong("hypit cancel")),@@ -539,6 +546,18 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi""," hypit cancel <build-id> [--runtime <profile>] [--reason <text>]",],+ result: [+ colors.accent(colors.strong("hypit result")),+ colors.dim("Edit one Result, finish an interrupted Result write, or discard an incomplete submission."),+ "",+ " hypit result finish <build-id> [--runtime <profile>]",+ " hypit result discard <build-id> [--runtime <profile>]",+ " hypit result edit <build-id> [--workspace <project>] [--title <text>] [--note <text>]",+ " [--highlight <output> ...]",+ " --clear-title remove the Result's human title",+ " --clear-note remove its note",+ " --clear-highlights remove all highlighted Outputs",+ ],image: [colors.accent(colors.strong("hypit image")),colors.dim("Generate one picture into a file, for an asset that ships inside a package."),@@ -588,7 +607,7 @@ export function writeCliHelp(io: CliIo, topic?: string): void {row("runtime use <profile>", "select this project's execution environment", 40),row("plan <run-source>", "see exactly what this Run will demand", 40),row("build <run-source>", "submit durable work; add --follow to watch", 40),- row("get <build-id>", "read or copy an archived result", 40),+ row("get <build-id>", "read or copy a Result Output", 40),row("doctor [profile]", "diagnose deployment setup when needed", 40),"",colors.strong("Authoring"),@@ -602,8 +621,11 @@ export function writeCliHelp(io: CliIo, topic?: string): void {row("history [output]", "find named historical Build Outputs"),row("status <build-id> [--watch]", "show or continuously observe one Build"),row("inspect <build-id>", "inspect one project Build Result"),- row("get <build-id> --name <output>", "read or materialize one Build Output"),+ row("get <build-id> --output <name>", "read or materialize one Build Output"),row("cancel <build-id>", "withdraw one Build and reconcile submitted work"),+ row("result finish <build-id>", "finish an interrupted Result write"),+ row("result discard <build-id>", "discard one incomplete submission"),+ row("result edit <build-id>", "title, annotate or highlight one Result"),"",colors.strong("Runtime"),row("doctor [profile]", "validate deployment without executing"),@@ -611,7 +633,7 @@ export function writeCliHelp(io: CliIo, topic?: string): void {row("runtime up|status|logs|down", "prepare deployment and manage the Worker"),row("programs up|status|down", "manage declared external programs only"),row("packages install|status", "manage pinned upstream packages in the machine home"),- row("queue [--watch]", "inspect durable dispatch and shared capacity"),+ row("activity [--watch]", "inspect active Builds and shared capacity"),row("paths", "show every effective state location"),row("auth status|login|logout", "manage Endpoint-declared credential references"),"",diff --git a/packages/cli/src/reachability.ts b/packages/cli/src/reachability.tsindex 2d2f706c..bb8f802b 100644--- a/packages/cli/src/reachability.ts+++ b/packages/cli/src/reachability.ts@@ -32,7 +32,7 @@ export function unreachedGenerations(for (const binding of Object.values(step.needs)) built.add(binding.result);}// A satisfied output is deliberately not produced again; that is reuse working, not a leftover.- for (const selection of state.plan.selections) built.add(selection.record);+ for (const binding of state.plan.outputBindings) built.add(binding.record);// The author's name for a generation sits on the Logical Output, which selects a Candidate, which// roots at the Operation. Reporting the Operation's internal name instead would be accurate anddiff --git a/packages/cli/src/reuse-markup.ts b/packages/cli/src/reuse-markup.tsnew file mode 100644index 00000000..10e1cc54--- /dev/null+++ b/packages/cli/src/reuse-markup.ts@@ -0,0 +1,29 @@+export type PinnedRecord = {+ readonly output: string;+ readonly build: string;+ readonly candidate: string;+ readonly markup: readonly string[];+};++/** Emit explicit Run markup for the newest occurrence of each requested public Output. */+export function pinnedRecords(+ entries: readonly { readonly build: string; readonly output: { readonly name: string } }[],+): readonly PinnedRecord[] {+ const seen = new Set<string>();+ const pinned: PinnedRecord[] = [];+ for (const entry of entries) {+ if (seen.has(entry.output.name)) continue;+ seen.add(entry.output.name);+ const candidate = `record-${entry.output.name.replace(/[^a-zA-Z0-9]+/gu, "-").replace(/^-|-$/gu, "")}`;+ pinned.push({+ output: entry.output.name,+ build: entry.build,+ candidate,+ markup: [+ `<build-record id="${candidate}" build="${entry.build}" output="${entry.output.name}"/>`,+ `<satisfy output="${entry.output.name}" candidate="${candidate}"/>`,+ ],+ });+ }+ return pinned;+}diff --git a/packages/cli/src/run-file.ts b/packages/cli/src/run-file.tsindex 724642c6..dedd1ec4 100644--- a/packages/cli/src/run-file.ts+++ b/packages/cli/src/run-file.ts@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";import type {BuildResultRepository,BuildResultFileRef,- BuildResultJsonValue,+ BuildResultValuePath,RepositoryBuildResultOutput,} from "@hypit/build-result";import { NodeRunCompiler } from "@hypit/compiler-node";@@ -10,7 +10,6 @@ import type {NodeCompiledRun,NodeCompiler,} from "@hypit/compiler-node";-import type { CliRuntime } from "./runtime-port.js";import type { NodePackageContribution } from "@hypit/package-loader-node";import type { ArtifactAttachment, WorkspaceSession } from "@hypit/workspace";import type { BlobRef, CanonicalValue, StoredValue } from "@hypit/protocol";@@ -21,13 +20,21 @@ import {RunFrontendRegistry,} from "@hypit/run";import type { RunFrontend } from "@hypit/run";-import { selectArchivedRecord } from "./archive.js";export type LoadedRunFile = NodeCompiledRun & {readonly path: string;readonly compiler: NodeRunCompiler;};+type BuildResultResolutionSession = {+ readonly files: Map<string, ArtifactAttachment>;+ readonly outputs: Map<string, Promise<RepositoryBuildResultOutput | undefined>>;+};++function createBuildResultResolutionSession(): BuildResultResolutionSession {+ return { files: new Map(), outputs: new Map() };+}+export async function checkRunFile(options: {readonly workspace: WorkspaceSession;readonly authorCompiler: NodeCompiler;@@ -38,94 +45,96 @@ export async function checkRunFile(options: {return await compiler.checkSource(options.workspace.entry, options.workspace);}-function isResultFile(value: unknown): value is BuildResultFileRef {- if (value === null || Array.isArray(value) || typeof value !== "object") return false;- const item = value as Readonly<Record<string, unknown>>;- return item.kind === "build-file" && typeof item.path === "string"- && typeof item.size === "number" && typeof item.mediaType === "string";-}--function isResultOutput(value: unknown): value is {- readonly kind: "build-output";- readonly build: string;- readonly output: string;-} {- if (value === null || Array.isArray(value) || typeof value !== "object") return false;- const item = value as Readonly<Record<string, unknown>>;- return item.kind === "build-output" && typeof item.build === "string" && typeof item.output === "string";-}--function isBlob(value: unknown): value is BlobRef {- if (value === null || Array.isArray(value) || typeof value !== "object") return false;- const item = value as Readonly<Record<string, unknown>>;- return item.kind === "blob" && typeof item.resource === "string"- && typeof item.size === "number" && typeof item.mediaType === "string";+function replaceValueAtPath(+ value: CanonicalValue,+ path: BuildResultValuePath,+ replacement: BlobRef,+): CanonicalValue {+ if (path.length === 0) return replacement;+ const segment = path[0]!;+ const rest = path.slice(1);+ if (typeof segment === "number") {+ if (!Array.isArray(value) || segment < 0 || segment >= value.length) {+ throw new Error(`Result Resource path ${JSON.stringify(path)} does not address an array item`);+ }+ return value.map((item, index) => index === segment+ ? replaceValueAtPath(item, rest, replacement)+ : item);+ }+ if (value === null || Array.isArray(value) || typeof value !== "object" || !Object.hasOwn(value, segment)) {+ throw new Error(`Result Resource path ${JSON.stringify(path)} does not address an object property`);+ }+ return {+ ...value,+ [segment]: replaceValueAtPath(+ (value as Readonly<Record<string, CanonicalValue>>)[segment]!,+ rest,+ replacement,+ ),+ };}/** Resolve one historical public Output into an ordinary Run value plus lazy file attachments. */-export async function resolveBuildResultRecord(+export async function resolveBuildResultValue(repository: BuildResultRepository,build: string,output: string,+ session: BuildResultResolutionSession = createBuildResultResolutionSession(),): Promise<{readonly type: RepositoryBuildResultOutput["type"];readonly value: StoredValue;readonly attachments?: readonly ArtifactAttachment[];-} | undefined> {+ } | undefined> {const resultAttachment = async (owner: string, file: BuildResultFileRef): Promise<ArtifactAttachment> => {- const fileBuild = file.build ?? owner;+ const address = `${owner}\u0000${file.path}`;+ const existing = session.files.get(address);+ if (existing !== undefined) return existing;const artifact: BlobRef = {kind: "blob",resource: `res_${randomUUID()}`,size: file.size,mediaType: file.mediaType,- origin: { kind: "build-file", build: fileBuild, path: file.path },};- return {+ const attachment = {artifact,async open() {- const stream = await repository.openFile(fileBuild, file);- if (stream === undefined) throw new Error(`Build ${fileBuild} file ${file.path} is unavailable`);+ const stream = await repository.openFile(owner, file);+ if (stream === undefined) throw new Error(`Build ${owner} file ${file.path} is unavailable`);return stream;},};+ session.files.set(address, attachment);+ return attachment;};- const attachments: ArtifactAttachment[] = [];- const resultValue = async (- value: BuildResultJsonValue,- owner: string,- ): Promise<CanonicalValue | BlobRef> => {- if (isResultFile(value)) {- const attachment = await resultAttachment(owner, value);- attachments.push(attachment);- return attachment.artifact;- }- if (isResultOutput(value)) {- const forwarded = await repository.resolve(value.build, value.output);- if (forwarded === undefined) throw new Error(`Build ${value.build} has no Output ${value.output}`);- return await resolvedValue(forwarded);- }- if (Array.isArray(value)) {- return await Promise.all(value.map(async (item) => await resultValue(item, owner))) as CanonicalValue;- }- if (value !== null && typeof value === "object") {- return Object.fromEntries(await Promise.all(Object.entries(value)- .map(async ([key, item]) => [key, await resultValue(item, owner)] as const))) as CanonicalValue;- }- return value;- };- const resolvedValue = async (resolved: RepositoryBuildResultOutput): Promise<BlobRef | CanonicalValue> => {- if (resolved.value.kind === "build-file") return await resultValue(resolved.value, resolved.build);- if (resolved.value.kind === "inline") return resolved.value.value;- return await resultValue(resolved.value.value, resolved.build);- };- const resolved = await repository.resolve(build, output);+ const attachments = new Map<string, ArtifactAttachment>();+ const address = `${build}\u0000${output}`;+ let pending = session.outputs.get(address);+ if (pending === undefined) {+ pending = repository.resolve(build, output);+ session.outputs.set(address, pending);+ }+ const resolved = await pending;if (resolved === undefined) return undefined;- const value = await resolvedValue(resolved);+ let value: StoredValue;+ if (resolved.value.kind === "build-file") {+ const attachment = await resultAttachment(resolved.build, resolved.value);+ attachments.set(attachment.artifact.resource, attachment);+ value = attachment.artifact;+ } else if (resolved.value.kind === "inline") {+ value = { kind: "inline", value: resolved.value.value };+ } else {+ let composite = resolved.value.document.value;+ for (const binding of resolved.value.document.resources) {+ const attachment = await resultAttachment(resolved.build, binding.file);+ attachments.set(attachment.artifact.resource, attachment);+ composite = replaceValueAtPath(composite, binding.at, attachment.artifact);+ }+ value = { kind: "inline", value: composite };+ }return {type: resolved.type,- value: isBlob(value) ? value : { kind: "inline", value },- ...(attachments.length === 0 ? {} : { attachments }),+ value,+ ...(attachments.size === 0 ? {} : { attachments: [...attachments.values()] }),};}@@ -133,47 +142,22 @@ function createRunCompiler(options: {readonly authorCompiler: NodeCompiler;readonly frontends: readonly RunFrontend[];readonly packageContributions: readonly NodePackageContribution[];- readonly runtime?: Pick<CliRuntime, "status">;readonly results?: BuildResultRepository;}): NodeRunCompiler {+ const resultSession = createBuildResultResolutionSession();const fragments = new RunFragmentRegistry();for (const item of options.packageContributions) {installRunFragmentHostFacets(item.hostFacets ?? [], fragments);}const frontends = new RunFrontendRegistry();for (const frontend of options.frontends) frontends.register(frontend);- const archive = new Map<string, Awaited<ReturnType<CliRuntime["status"]>>>();- const archived = async (id: string) => {- const existing = archive.get(id);- if (existing !== undefined) return existing;- const status = await options.runtime!.status(id);- archive.set(id, status);- return status;- };return new NodeRunCompiler({authorCompiler: options.authorCompiler,frontends,fragments,- ...(options.results !== undefined ? {- async resolveBuildRecord(id: string, output: string) {- return await resolveBuildResultRecord(options.results!, id, output);- },- } : options.runtime === undefined ? {} : {- async resolveBuildRecord(id: string, output: string) {- const status = await archived(id);- if (status.build === undefined) return undefined;- const catalog = status.catalog;- const alias = catalog?.aliases.find((item) => item.name === output);- if (alias !== undefined && alias.ref.kind !== "logical-output") {- throw new Error(`Build ${id} alias ${output} is an authored Record, not a Logical Output`);- }- const record = alias === undefined- ? selectArchivedRecord(status.build.state, { output })- : selectArchivedRecord(status.build.state, {- name: output,- catalog: catalog as NonNullable<typeof catalog>,- });- return { type: record.type, value: record.value };+ ...(options.results === undefined ? {} : {+ async resolveHistoricalOutput(id: string, output: string) {+ return await resolveBuildResultValue(options.results!, id, output, resultSession);},}),});@@ -190,7 +174,6 @@ export async function loadRunFile(options: {readonly authorCompiler: NodeCompiler;readonly frontends: readonly RunFrontend[];readonly packageContributions: readonly NodePackageContribution[];- readonly runtime?: Pick<CliRuntime, "status">;readonly results?: BuildResultRepository;}): Promise<LoadedRunFile> {const compiler = createRunCompiler(options);diff --git a/packages/cli/src/runtime-port.ts b/packages/cli/src/runtime-port.tsindex 7226d772..cac2e9cf 100644--- a/packages/cli/src/runtime-port.ts+++ b/packages/cli/src/runtime-port.ts@@ -2,13 +2,12 @@ export type {ManagedProgramProgress as CliManagedProgramProgress,ManagedProgramReport as CliManagedProgramReport,RuntimeController as CliRuntimeController,- RuntimeHostArchive as CliRuntimeArchiveControl,- RuntimeHostResourceAccess as CliRuntimeResourceAccess,+ RuntimeHostControl as CliRuntimeControl,RuntimeHostBuildSubmission as CliBuildSubmission,RuntimeHostCredentialControl as CliCredentialControl,RuntimeHostCredentialStatus as CliCredentialStatus,RuntimeHostDoctorResult as CliRuntimeDoctorResult,RuntimeHostExecution as CliRuntime,- RuntimeHostStatus as CliRuntimeStatus,+ BuildView as CliBuildView,RuntimeWorkerState as CliRuntimeWorkerState,} from "@hypit/runtime-host-node";diff --git a/packages/cli/test/build-programs.test.ts b/packages/cli/test/build-programs.test.tsindex c3efa613..8ca490d6 100644--- a/packages/cli/test/build-programs.test.ts+++ b/packages/cli/test/build-programs.test.ts@@ -112,7 +112,7 @@ function distribution(preflight: async () => ({ dataRoot: "/tmp", diagnostics }),doctor: async () => ({ dataRoot: "/tmp", diagnostics: [] }),createRuntime: async () => { throw new Error("createRuntime is unavailable"); },- openArchive: async () => ({ status: async () => ({}) }),+ openControl: async () => ({ inspect: async () => undefined }),}),} as unknown as CliDistribution;}@@ -144,12 +144,12 @@ test("Build fails its cheap preflight before submitting or starting programs", aassert.deepEqual(calls, []);});-test("Build accepts a human name and never provisions programs after a clean preflight", async () => {+test("Build accepts a Result title and never provisions programs after a clean preflight", async () => {const calls: string[] = [];const source = await runSource();await assert.rejects(async () => await runCli(- ["build", source, "--name", "first-cut", "--runtime", "/p/hypit.runtime.json"],+ ["build", source, "--title", "first-cut", "--runtime", "/p/hypit.runtime.json"],io,distribution(calls, []),),@@ -158,17 +158,6 @@ test("Build accepts a human name and never provisions programs after a clean preassert.deepEqual(calls, []);});-test("the removed --no-programs switch is rejected", async () => {- await assert.rejects(- async () => await runCli(- ["build", "/p/build.svrun", "--no-programs"],- io,- distribution([], []),- ),- /unknown option --no-programs/u,- );-});-test("plan preserves the frozen plan but exits non-zero when cheap preflight fails", async () => {const source = await runSource();let output = "";diff --git a/packages/cli/test/build-results.test.ts b/packages/cli/test/build-results.test.tsindex b72d7b10..1f0d511f 100644--- a/packages/cli/test/build-results.test.ts+++ b/packages/cli/test/build-results.test.ts@@ -26,24 +26,25 @@ function completedState(): BuildState {status: "complete",records: [{ id: "record:stage", type: valueType, value: { kind: "inline", value: "ready" } }],plan: {- selections: [{ output: "logical:stage", candidate: "candidate:stage", record: "record:stage" }],+ outputBindings: [{ output: "logical:stage", record: "record:stage", type: valueType }],},} as unknown as BuildState;}async function fixture(root: string): Promise<void> {const result = await FileBuildResult.create(join(root, ".hypit", "results"), {- id: "bld_result",- name: "episode-stage",+ id: "bld_20260902T110000000Z_0000000001",+ title: "episode-stage",source: { path: join(root, "main.svml") },run: { path: join(root, "build.svrun") },- targets: ["final.video"],- aliases: [{ name: "stage.value", output: "logical:stage" }],+ targets: ["stage.value"],+ publishedOutputs: [{ name: "stage.value", output: "logical:stage" }],});await result.sync({state: completedState(),resources: { async open() { throw new Error("inline Result has no files"); } },});+ await result.finish({ outcome: "complete" });}async function jsonCommand(args: readonly string[], root: string): Promise<unknown> {@@ -61,46 +62,84 @@ test("builds, history, inspect and get read project Build Results without openinconst builds = await jsonCommand(["builds"], root) as {readonly builds: readonly {readonly build: string;- readonly name?: string;- readonly status: string;+ readonly title?: string;+ readonly outcome: string;readonly outputs: readonly string[];}[];};assert.equal(builds.builds.length, 1);- assert.equal(builds.builds[0]?.build, "bld_result");- assert.equal(builds.builds[0]?.name, "episode-stage");- assert.equal(builds.builds[0]?.status, "complete");+ assert.equal(builds.builds[0]?.build, "bld_20260902T110000000Z_0000000001");+ assert.equal(builds.builds[0]?.title, "episode-stage");+ assert.equal(builds.builds[0]?.outcome, "complete");assert.deepEqual(builds.builds[0]?.outputs, ["stage.value"]);const history = await jsonCommand(["history", "stage.value"], root) as {readonly entries: readonly { readonly build: string; readonly output: { readonly name: string } }[];};assert.equal(history.entries.length, 1);- assert.equal(history.entries[0]?.build, "bld_result");+ assert.equal(history.entries[0]?.build, "bld_20260902T110000000Z_0000000001");assert.equal(history.entries[0]?.output.name, "stage.value");- const inspected = await jsonCommand(["inspect", "bld_result"], root) as {- readonly result: { readonly id: string; readonly name?: string };- readonly outputs: readonly { readonly name: string; readonly target: boolean }[];+ const inspected = await jsonCommand(["inspect", "bld_20260902T110000000Z_0000000001"], root) as {+ readonly result: { readonly id: string; readonly title?: string };};- assert.equal(inspected.result.id, "bld_result");- assert.equal(inspected.result.name, "episode-stage");- assert.deepEqual(inspected.outputs, [{- name: "stage.value",- target: false,- type: valueType,- value: { kind: "inline", value: "ready" },- }]);+ assert.equal(inspected.result.id, "bld_20260902T110000000Z_0000000001");+ assert.equal(inspected.result.title, "episode-stage");const destination = join(root, "exported.json");- await jsonCommand(["get", "bld_result", "--name", "stage.value", "--to", destination], root);+ await jsonCommand(["get", "bld_20260902T110000000Z_0000000001", "--output", "stage.value", "--to", destination], root);assert.equal(await readFile(destination, "utf8"), "\"ready\"\n");} finally {await rm(root, { recursive: true, force: true });}});-test("build-record reads one exact result file and preserves its historical origin", async () => {+test("result edit changes only the exact project Result presentation without opening a Runtime", async () => {+ const root = await mkdtemp(join(tmpdir(), "hypit-cli-result-edit-"));+ try {+ await fixture(root);+ const edited = await jsonCommand([+ "result", "edit", "bld_20260902T110000000Z_0000000001",+ "--title", "Episode 12 B-roll",+ "--note", "Use the close-up for the opening beat.",+ "--highlight", "stage.value",+ "--highlight", "stage.value",+ ], root) as {+ readonly build: string;+ readonly title: string;+ readonly note: string;+ readonly highlightedOutputs: readonly string[];+ };+ assert.deepEqual(edited, {+ format: "hypit.cli-result-edit@2",+ build: "bld_20260902T110000000Z_0000000001",+ title: "Episode 12 B-roll",+ note: "Use the close-up for the opening beat.",+ highlightedOutputs: ["stage.value"],+ });++ const repository = new FileBuildResultRepository(join(root, ".hypit", "results"));+ const stored = await repository.read("bld_20260902T110000000Z_0000000001");+ assert.equal(stored?.title, "Episode 12 B-roll");+ assert.equal(stored?.note, "Use the close-up for the opening beat.");+ assert.deepEqual(stored?.highlightedOutputs, ["stage.value"]);++ const cleared = await jsonCommand([+ "result", "edit", "bld_20260902T110000000Z_0000000001", "--clear-title", "--clear-note", "--clear-highlights",+ ], root) as {+ readonly title: null;+ readonly note: null;+ readonly highlightedOutputs: readonly string[];+ };+ assert.equal(cleared.title, null);+ assert.equal(cleared.note, null);+ assert.deepEqual(cleared.highlightedOutputs, []);+ } finally {+ await rm(root, { recursive: true, force: true });+ }+});++test("build-record selects one exact Result Output without leaking its storage address into Core", async () => {const root = await mkdtemp(join(tmpdir(), "hypit-cli-result-reuse-"));try {const module = { name: "example.result-reuse", version: "1" } as const;@@ -167,11 +206,11 @@ test("build-record reads one exact result file and preserves its historical origconst resultsRoot = join(root, ".hypit", "results");const result = await FileBuildResult.create(resultsRoot, {- id: "bld_prior",+ id: "bld_20260902T110000001Z_0000000001",source: { path: join(root, "main.svml") },run: { path: join(root, "prior.svrun") },targets: ["shot.video"],- aliases: [{ name: "shot.video", output: "logical:video" }],+ publishedOutputs: [{ name: "shot.video", output: "logical:video" }],});const bytes = new TextEncoder().encode("prior video bytes");await result.sync({@@ -180,14 +219,14 @@ test("build-record reads one exact result file and preserves its historical origrecords: [{id: "record:video",type: videoType,- value: {+ value: { kind: "inline", value: { artifact: {kind: "blob",resource: "res_prior_video",size: bytes.byteLength,mediaType: "video/mp4",- },+ } } },}],- plan: { selections: [{ output: "logical:video", candidate: "candidate:video", record: "record:video" }] },+ plan: { outputBindings: [{ output: "logical:video", record: "record:video", type: videoType }] },} as unknown as BuildState,resources: {async open() {@@ -207,7 +246,7 @@ test("build-record reads one exact result file and preserves its historical orig<svrun version="1"><author source="./main.svml"/><target output="shot.video"/>- <build-record id="prior" build="bld_prior" output="shot.video"/>+ <build-record id="prior" build="bld_20260902T110000001Z_0000000001" output="shot.video"/><satisfy output="shot.video" candidate="prior"/></svrun>`, "utf8");@@ -229,12 +268,17 @@ test("build-record reads one exact result file and preserves its historical origconst candidate = loaded.run.graph.candidates[0];assert.equal(candidate?.root.kind, "value");const value = candidate?.root.kind === "value" ? candidate.root.value.value : undefined;- assert.equal(value?.kind, "blob");- assert.deepEqual(value?.kind === "blob" ? value.origin : undefined, {- kind: "build-file",- build: "bld_prior",- path: "files/shot.video.mp4",- });+ assert.equal(value?.kind, "inline");+ assert.equal(value?.kind === "inline"+ ? (value.value as { readonly artifact?: { readonly kind?: string } }).artifact?.kind+ : undefined, "blob");+ const logicalOutput = loaded.author.exports.find((item) => item.name === "shot.video")?.ref;+ assert.equal(logicalOutput?.kind, "logical-output");+ assert.deepEqual(loaded.compiler.planCompilation(loaded).resultForwards, [{+ output: logicalOutput!.id,+ build: "bld_20260902T110000001Z_0000000001",+ sourceOutput: "shot.video",+ }]);assert.equal(loaded.attachments.length, 1);assert.equal(opens, 0, "compilation does not read or summarize historical bytes");const reused: number[] = [];diff --git a/packages/cli/test/control-commands.test.ts b/packages/cli/test/control-commands.test.tsindex c73a3f2f..06c52f21 100644--- a/packages/cli/test/control-commands.test.ts+++ b/packages/cli/test/control-commands.test.ts@@ -3,23 +3,23 @@ import test from "node:test";import type { CliDistribution } from "../src/distribution.js";import { runCli } from "../src/main.js";-import type { CliCredentialControl, CliRuntimeArchiveControl } from "../src/runtime-port.js";+import type { CliCredentialControl, CliRuntimeControl } from "../src/runtime-port.js";-test("queue opens durable control without constructing execution Providers", async () => {+test("activity opens Runtime control without constructing execution Providers", async () => {const calls: string[] = [];const control = {- async queue() {- calls.push("control.queue");- return { dispatches: [], capacity: [], operations: [] };+ async activity() {+ calls.push("control.activity");+ return { builds: [], capacity: [] };},async close() {calls.push("control.close");},- } as unknown as CliRuntimeArchiveControl;+ } as unknown as CliRuntimeControl;const distribution = {openRuntimeHost: async (path: string) => ({profile: path,- openArchive: async () => {+ openControl: async () => {calls.push("control.create");return control;},@@ -35,64 +35,51 @@ test("queue opens durable control without constructing execution Providers", asylet output = "";await runCli(- ["queue", "--runtime", "/tmp/hypit-control-profile.json", "--json"],+ ["activity", "--runtime", "/tmp/hypit-control-profile.json", "--json"],{ write: (text) => { output += text; } },distribution,);- assert.deepEqual(calls, ["control.create", "control.queue", "control.close"]);+ assert.deepEqual(calls, ["control.create", "control.activity", "control.close"]);const result = JSON.parse(output) as {readonly format: string;readonly at: number;- readonly dispatches: readonly unknown[];- readonly capacity: readonly unknown[];- readonly operations: readonly unknown[];+ readonly builds: readonly unknown[];};- assert.equal(result.format, "hypit.cli-queue@1");+ assert.equal(result.format, "hypit.cli-activity@1");assert.equal(typeof result.at, "number");- assert.deepEqual(result.dispatches, []);- assert.deepEqual(result.capacity, []);- assert.deepEqual(result.operations, []);+ assert.deepEqual(result.builds, []);});-test("status --watch reattaches to one durable Build until it becomes terminal", async () => {+test("status --watch follows active execution, then reads its finished Result", async () => {const calls: string[] = [];- const state = {- id: "build-watch-state",- status: "active",- diagnostics: [],- };- const dispatch = (phase: "queued" | "terminal") => ({- build: "build-watch",- componentPackages: [],+ const resultLocation = {+ root: "/project",+ selection: { use: "@hypit/build-result-fs", config: { path: ".hypit/results" } },+ } as const;+ const view = () => ({+ id: "build-watch",createdAt: 1,- availableAt: 1,- phase,- ...(phase === "terminal" ? { terminal: "complete" } : {}),+ activity: "running" as const,+ cancellationRequested: false,+ targets: [],+ acceptedRecords: 0,+ outstandingCommands: 1,+ operations: [],});let statusReads = 0;const control = {- async status() {+ async inspect() {statusReads += 1;- calls.push("archive.status");- const terminal = statusReads > 1;- return {- build: { build: "build-watch", state },- catalog: undefined,- operations: [],- dispatch: dispatch(terminal ? "terminal" : "queued"),- };- },- async activity() {- calls.push("archive.activity");- return { operations: [], dispatch: dispatch("terminal") };+ calls.push("control.inspect");+ return statusReads === 1 ? view() : undefined;},- async close() { calls.push("archive.close"); },- } as unknown as CliRuntimeArchiveControl;+ async close() { calls.push("control.close"); },+ } as unknown as CliRuntimeControl;const distribution = {openRuntimeHost: async (path: string) => ({profile: path,- openArchive: async () => control,+ openControl: async () => control,controller: async () => ({worker: { status: async () => ({ state: "running", profile: path, pid: 1, logPath: "/tmp/worker.log" }) },}),@@ -100,6 +87,23 @@ test("status --watch reattaches to one durable Build until it becomes terminal",throw new Error("status must not construct execution Providers");},}),+ openProjectResults: async () => ({+ location: resultLocation,+ repository: {+ async read() {+ return {+ format: "hypit.build-result@2",+ id: "build-watch",+ source: { path: "main.svml" },+ targets: [],+ finishedAt: 2,+ outcome: "complete",+ outputs: {},+ };+ },+ },+ async close() {},+ }),} as unknown as CliDistribution;let output = "";@@ -108,21 +112,172 @@ test("status --watch reattaches to one durable Build until it becomes terminal",], { write: (text) => { output += text; } }, distribution);const result = JSON.parse(output) as {- readonly build: { readonly id: string; readonly status: string };- readonly dispatch: { readonly terminal?: string };+ readonly build: { readonly id: string; readonly outcome: string };};assert.equal(result.build.id, "build-watch");- assert.equal(result.build.status, "complete");- assert.equal(result.dispatch.terminal, "complete");+ assert.equal(result.build.outcome, "complete");assert.deepEqual(calls, [- "archive.status",- "archive.activity",- "archive.status",- "archive.status",- "archive.close",+ "control.inspect",+ "control.inspect",+ "control.close",]);});+test("status reads a finished project Result without a Runtime", async () => {+ const calls: string[] = [];+ const distribution = {+ openRuntimeHost: async () => {+ throw new Error("finished Result lookup must not open a Runtime");+ },+ openProjectResults: async () => ({+ repository: {+ async read(build: string) {+ calls.push(`result.read:${build}`);+ return {+ format: "hypit.build-result@2",+ id: build,+ source: { path: "main.svml" },+ targets: [],+ finishedAt: 2,+ outcome: "complete",+ outputs: {},+ };+ },+ },+ async close() { calls.push("result.close"); },+ }),+ } as unknown as CliDistribution;+ let output = "";++ await runCli([+ "status", "build-finished", "--json",+ ], { write: (text) => { output += text; } }, distribution);++ const result = JSON.parse(output) as {+ readonly build: { readonly id: string; readonly outcome: string };+ };+ assert.equal(result.build.id, "build-finished");+ assert.equal(result.build.outcome, "complete");+ assert.deepEqual(calls, ["result.read:build-finished", "result.close"]);+});++test("status preserves Runtime decision and attention when its Result Store is unavailable", async () => {+ const view = {+ id: "build-result-unavailable",+ createdAt: 1,+ activity: "saving-result" as const,+ outcome: "failed" as const,+ issue: { scope: "result" as const, message: "S3 unavailable" },+ cancellationRequested: false,+ targets: [],+ acceptedRecords: 0,+ outstandingCommands: 0,+ operations: [],+ };+ const control = {+ async inspect() { return view; },+ async close() {},+ } as unknown as CliRuntimeControl;+ const distribution = {+ openRuntimeHost: async (path: string) => ({+ profile: path,+ openControl: async () => control,+ }),+ async openProjectResults() { throw new Error("S3 unavailable"); },+ } as unknown as CliDistribution;+ let output = "";+ let exitCode = 0;++ await runCli([+ "status", view.id, "--runtime", "/tmp/runtime.json", "--json",+ ], { write: (text) => { output += text; }, setExitCode: (code) => { exitCode = code; } }, distribution);++ const result = JSON.parse(output) as {+ readonly build: typeof view;+ readonly resultReadError: string;+ };+ assert.equal(result.build.outcome, "failed");+ assert.equal(result.build.issue.scope, "result");+ assert.equal(result.resultReadError, "S3 unavailable");+ assert.equal(exitCode, 1);+});++test("result finish writes only an already-decided Result that needs attention", async () => {+ let finishes = 0;+ const blocked = {+ id: "build-blocked",+ createdAt: 1,+ activity: "saving-result" as const,+ outcome: "complete" as const,+ issue: { scope: "result" as const, message: "result store unavailable" },+ cancellationRequested: false,+ targets: [],+ acceptedRecords: 1,+ outstandingCommands: 0,+ operations: [],+ };+ const control = {+ async inspect() { return blocked; },+ async close() {},+ } as unknown as CliRuntimeControl;+ const resultControl = {+ async finishResult() {+ finishes += 1;+ return { id: blocked.id, outcome: blocked.outcome };+ },+ async close() {},+ };+ const distribution = {+ openRuntimeHost: async (path: string) => ({+ profile: path,+ openControl: async () => control,+ openResultControl: async () => resultControl,+ createRuntime: async () => {+ throw new Error("continuing a Result must not construct execution Providers");+ },+ }),+ } as unknown as CliDistribution;+ let output = "";++ await runCli([+ "result", "finish", "build-blocked", "--runtime", "/tmp/runtime.json", "--json",+ ], { write: (text) => { output += text; } }, distribution);++ assert.equal(finishes, 1);+ assert.deepEqual(JSON.parse(output), {+ format: "hypit.cli-result-finish@1",+ build: "build-blocked",+ outcome: "complete",+ });+});++test("result discard invokes only the exact one-shot Result control", async () => {+ const calls: string[] = [];+ const distribution = {+ openRuntimeHost: async (path: string) => ({+ profile: path,+ openControl: async () => ({ async close() { calls.push("control.close"); } }),+ openResultControl: async () => ({+ async discardSubmission(build: string) {+ calls.push(`discard:${build}`);+ return true;+ },+ async close() { calls.push("result-control.close"); },+ }),+ }),+ } as unknown as CliDistribution;+ let output = "";++ await runCli([+ "result", "discard", "build-submitting", "--runtime", "/tmp/runtime.json", "--json",+ ], { write: (text) => { output += text; } }, distribution);++ assert.deepEqual(calls, ["discard:build-submitting", "result-control.close", "control.close"]);+ assert.deepEqual(JSON.parse(output), {+ format: "hypit.cli-result-discard@1", build: "build-submitting", discarded: true,+ });+});+test("command options fail closed instead of being silently ignored", async () => {const distribution = {openRuntimeHost: async (path: string) => {@@ -138,25 +293,19 @@ test("command options fail closed instead of being silently ignored", async () =);await assert.rejects(async () => await runCli([- "queue", "--runtime", "/tmp/one.json", "--runtime", "/tmp/two.json",+ "activity", "--runtime", "/tmp/one.json", "--runtime", "/tmp/two.json",], io, distribution),/--runtime cannot be repeated/u,);- await assert.rejects(- async () => await runCli([- "build", "/tmp/build.svrun", "--runtime", "/tmp/runtime.json", "--build-id", "legacy-build",- ], io, distribution),- /unknown option --build-id/u,- );await assert.rejects(async () => await runCli(["doctor", "/tmp/runtime.json", "--workspace", "/tmp",], io, distribution),- /doctor does not compile a Source Workspace; remove --workspace/u,+ /profile delegated: .*runtime\.json/u,);await assert.rejects(async () => await runCli([- "queue", "--runtime", "/tmp/hypit.runtime.ts",+ "activity", "--runtime", "/tmp/hypit.runtime.ts",], io, distribution),/profile delegated: .*hypit\.runtime\.ts/u,);@@ -248,19 +397,29 @@ test("auth login rejects a read-only CredentialStore before asking for a secret"test("cancelling a completed Build reports that no cancellation was requested", async () => {const control = {- async cancel() {- return {- build: "build-complete",- phase: "terminal",- terminal: "complete",- };- },+ async cancel() { return undefined; },async close() {},- } as unknown as CliRuntimeArchiveControl;+ } as unknown as CliRuntimeControl;const distribution = {openRuntimeHost: async (path: string) => ({profile: path,- openArchive: async () => control,+ openControl: async () => control,+ }),+ openProjectResults: async () => ({+ repository: {+ async read() {+ return {+ format: "hypit.build-result@2",+ id: "build-complete",+ source: { path: "main.svml" },+ targets: [],+ finishedAt: 2,+ outcome: "complete",+ outputs: {},+ };+ },+ },+ async close() {},}),} as unknown as CliDistribution;let output = "";@@ -270,9 +429,9 @@ test("cancelling a completed Build reports that no cancellation was requested",], { write: (text) => { output += text; } }, distribution);assert.deepEqual(JSON.parse(output), {+ format: "hypit.cli-cancel@2",build: "build-complete",requested: false,- phase: "terminal",- terminal: "complete",+ outcome: "complete",});});diff --git a/packages/cli/test/output.test.ts b/packages/cli/test/output.test.tsindex 7461f966..dbd49cad 100644--- a/packages/cli/test/output.test.ts+++ b/packages/cli/test/output.test.ts@@ -144,10 +144,10 @@ test("plan keeps named Run choices visible and leaves graph internals to verboseneeds: {},}],goals: [],- selections: [{+ outputBindings: [{output: "logical:take",- candidate: "candidate:preview",record: "record:take",+ type: { module: { name: "example.media", version: "1" }, name: "Take" },}],};const output = capture(human, {@@ -156,6 +156,7 @@ test("plan keeps named Run choices visible and leaves graph internals to verboserun: "/project/build.svrun",outputNames: { "logical:take": "take.video" },satisfactionNames: { "logical:take": "preview" },+ selections: [{ output: "logical:take", candidate: "candidate:preview", record: "record:take" }],});assert.match(output, /Run choices/u);assert.match(output, /take\.video\s+← preview/u);@@ -169,6 +170,7 @@ test("plan keeps named Run choices visible and leaves graph internals to verboserun: "/project/build.svrun",outputNames: { "logical:take": "take.video" },satisfactionNames: { "logical:take": "preview" },+ selections: [{ output: "logical:take", candidate: "candidate:preview", record: "record:take" }],}), /2\s+@hypit\/media@1/u);});@@ -177,7 +179,7 @@ test("a plan with no Needs stays compact without knowing any Provider names", ()format: "hypit.plan@1",steps: [],goals: [],- selections: [],+ outputBindings: [],};const output = capture(human, {kind: "plan",@@ -193,7 +195,7 @@ test("plan runtime preflight presents only demanded capabilities", () => {format: "hypit.plan@1",steps: [],goals: [],- selections: [],+ outputBindings: [],};const preflight: PlanPreflight = {ok: false,@@ -247,7 +249,7 @@ test("command help explains only the selected shell grammar", () => {assert.doesNotMatch(output, /Authoring/u);});-test("archive commands have their own help instead of falling back to the global screen", () => {+test("Result commands have their own help instead of falling back to the global screen", () => {let output = "";writeCliHelp({ write(text) { output += text; } }, "get");assert.match(output, /^hypit get\n/u);diff --git a/packages/cli/test/pin.test.ts b/packages/cli/test/pin.test.tsindex 1ae68909..0fde9ed5 100644--- a/packages/cli/test/pin.test.ts+++ b/packages/cli/test/pin.test.ts@@ -3,7 +3,7 @@ import test from "node:test";import { parseRunDocument } from "@hypit/run-markup";-import { pinnedRecords } from "../src/archive.js";+import { pinnedRecords } from "../src/reuse-markup.js";test("pinned Records emit Run Source markup that parses, one per output", () => {const pins = pinnedRecords([diff --git a/packages/cli/test/reachability.test.ts b/packages/cli/test/reachability.test.tsindex 4f655386..0805a2e6 100644--- a/packages/cli/test/reachability.test.ts+++ b/packages/cli/test/reachability.test.ts@@ -36,7 +36,7 @@ const state = {format: "hypit.plan@1",steps: [{ id: "step:used", producer, inputs: {}, outputs: { image: "record:used" }, needs: {} }],goals: [],- selections: [{ output: "output:reused", candidate: "candidate:reused", record: "record:reused" }],+ outputBindings: [{ output: "output:reused", record: "record:reused", type: producer }],},} as unknown as BuildState;@@ -78,7 +78,7 @@ test("a generation is reported under the name the author wrote, not the step ins},],} as unknown as CompiledGraph;- const empty = { plan: { format: "hypit.plan@1", steps: [], goals: [], selections: [] } } as unknown as BuildState;+ const empty = { plan: { format: "hypit.plan@1", steps: [], goals: [], outputBindings: [] } } as unknown as BuildState;assert.deepEqual(unreachedGenerations(expanded, empty, { "output:picked": "orphan.image" }).map((item) => item.name), ["orphan.image"]);});diff --git a/packages/cli/test/runtime-selection.test.ts b/packages/cli/test/runtime-selection.test.tsindex b65924b9..0900ce1b 100644--- a/packages/cli/test/runtime-selection.test.ts+++ b/packages/cli/test/runtime-selection.test.ts@@ -6,7 +6,7 @@ import test from "node:test";import type { CliDistribution } from "../src/distribution.js";import { runCli } from "../src/main.js";-import type { CliRuntimeArchiveControl } from "../src/runtime-port.js";+import type { CliRuntimeControl } from "../src/runtime-port.js";import { findRuntimeProfile, selectRuntimeProfile } from "../src/runtime-selection.js";test("project Runtime selection is a relative local pointer discovered from nested sources", async () => {@@ -40,15 +40,15 @@ test("runtime use lets later CLI commands reuse the selected Profile", async ()await writeFile(otherProfile, "{}\n", "utf8");const calls: string[] = [];const control = {- async queue() { return { dispatches: [], capacity: [], operations: [] }; },+ async activity() { return { builds: [], capacity: [] }; },async close() {},- } as unknown as CliRuntimeArchiveControl;+ } as unknown as CliRuntimeControl;const distribution = {openRuntimeHost: async (path: string) => ({profile: path,resolvePaths: async () => ({}),- openArchive: async () => {- calls.push(`queue:${resolve(path)}`);+ openControl: async () => {+ calls.push(`activity:${resolve(path)}`);return control;},controller: async () => ({@@ -59,13 +59,13 @@ test("runtime use lets later CLI commands reuse the selected Profile", async ()process.chdir(root);await runCli(["runtime", "use", profile, "--json"], { write() {} }, distribution);- await runCli(["queue", "--json"], { write() {} }, distribution);- await runCli(["queue", "--runtime", otherProfile, "--json"], { write() {} }, distribution);+ await runCli(["activity", "--json"], { write() {} }, distribution);+ await runCli(["activity", "--runtime", otherProfile, "--json"], { write() {} }, distribution);await runCli(["runtime", "unset", "--json"], { write() {} }, distribution);assert.deepEqual(calls, [- `queue:${await realpath(profile)}`,- `queue:${otherProfile}`,+ `activity:${await realpath(profile)}`,+ `activity:${otherProfile}`,]);assert.equal(await findRuntimeProfile(root), undefined);} finally {diff --git a/packages/compiler-node/src/compiler.ts b/packages/compiler-node/src/compiler.tsindex 11eb081a..c9f927f7 100644--- a/packages/compiler-node/src/compiler.ts+++ b/packages/compiler-node/src/compiler.ts@@ -199,4 +199,9 @@ export class NodeCompiler {return link(closure, program.records);}+ /** Admit one selected Run value through the same Type-owner boundary as authored Records. */+ async admitRecord(program: LinkedProgram, record: import("@hypit/protocol").TypedRecord): Promise<void> {+ await this.#admitRecord(program.closure, record);+ }+}diff --git a/packages/compiler-node/src/run.ts b/packages/compiler-node/src/run.tsindex 1799c8b7..0edef86b 100644--- a/packages/compiler-node/src/run.ts+++ b/packages/compiler-node/src/run.ts@@ -1,12 +1,11 @@import type { WorkspaceSession } from "@hypit/workspace";-import { resolveCompiledSourceExport } from "@hypit/elaborator";import {- sealBuildRequest,- sealCompiledGraph,sliceExecution,defineBuild,materializeBuild,+ planBuild,} from "@hypit/core";+import type { BuildCandidateSelection } from "@hypit/core";import type {ArtifactAttachment,} from "@hypit/workspace";@@ -16,10 +15,12 @@ import type {StoredValue,TypeRef,} from "@hypit/protocol";+import { sameType } from "@hypit/protocol";import {collectRunModuleRequests,compileRunSource,resolveRunDocument,+ sealRunGraph,} from "@hypit/run";import type {RunCompilation,@@ -39,7 +40,7 @@ export type NodeRunCompilerOptions = {readonly authorCompiler: NodeCompiler;readonly frontends: RunFrontendRegistryLike;readonly fragments: RunFragmentRegistryLike;- readonly resolveBuildRecord?: (+ readonly resolveHistoricalOutput?: (build: string,output: string,) => Promise<{@@ -71,7 +72,7 @@ export type NodeCheckedRun = {readonly author: NodeCompiledSourceClosure;readonly program: LinkedProgram;readonly document: RunCompilation["document"];- readonly unresolvedBuildRecords: readonly {+ readonly unresolvedHistoricalOutputs: readonly {readonly id: string;readonly build: string;readonly output: string;@@ -81,6 +82,14 @@ export type NodeCheckedRun = {export type PlannedBuild = {readonly compilation: NodeCompiledRun;+ /** Compiler-only explanation of how the two graphs became the execution plan. */+ readonly selections: readonly BuildCandidateSelection[];+ /** Whole-Output historical sources selected by the plan; Result storage may forward them directly. */+ readonly resultForwards: readonly {+ readonly output: string;+ readonly build: string;+ readonly sourceOutput: string;+ }[];/** Immutable authority persisted once for every fresh Runtime Build. */readonly definition: BuildDefinition;/** Materialized plan/read view; durable Stores persist Definition + Facts instead. */@@ -191,7 +200,7 @@ export class NodeRunCompiler {* Validate both source documents without materializing historical Build values.** A future BuildRecord is valid Run intent even before that Build exists. It- * becomes executable only when plan/build resolves its exact archived value.+ * becomes executable only when plan/build resolves its exact historical Result value.*/async checkSource(source: RunSourceUnit, workspace: WorkspaceSession): Promise<NodeCheckedRun> {const decoded = await compileRunSource(source, this.#options.frontends);@@ -204,62 +213,53 @@ export class NodeRunCompiler {author.program,collectRunModuleRequests(decoded.document, this.#options.fragments),);- const authorOutput = (name: string) => resolveCompiledSourceExport(author, name);- const imports = new Map(decoded.document.imports.map((item) => [item.as, item.from]));- const candidateNames = new Set<string>();- for (const declaration of decoded.document.candidates) {- if (declaration.kind === "provided") {- await storedValueFromWorkspace(workspace, source, declaration.from);- candidateNames.add(declaration.id);- continue;- }- if (declaration.kind === "file") {- await fileValueFromWorkspace(workspace, source, declaration.from, declaration.mediaType);- candidateNames.add(declaration.id);- continue;- }- if (declaration.kind === "build-record") {- candidateNames.add(declaration.id);- continue;- }- const packageName = imports.get(declaration.using.alias);- if (packageName === undefined) throw new Error(`Run Fragment alias ${declaration.using.alias} is not imported`);- const fragment = this.#options.fragments.resolve(packageName, declaration.using.name);- if (fragment === undefined) throw new Error(`${packageName} exports no Run Fragment ${declaration.using.name}`);- const inputs = new Map(declaration.inputs.map((item) => [item.name, item.from]));- for (const expected of fragment.inputs) {- const from = inputs.get(expected.name);- if (from === undefined) throw new Error(`Run Fragment ${declaration.id} has no input ${expected.name}`);- const actual = authorOutput(from).type;- if (actual.name !== expected.type.name- || actual.module.name !== expected.type.module.name- || actual.module.version !== expected.type.module.version) {- throw new Error(`Run Fragment ${declaration.id} input ${expected.name} has the wrong type`);- }- }- const unknownInput = declaration.inputs.find((item) => !fragment.inputs.some((expected) => expected.name === item.name));- if (unknownInput !== undefined) throw new Error(`Run Fragment ${declaration.id} has unknown input ${unknownInput.name}`);- const selected = declaration.exports ?? fragment.exports.map((item) => item.name);- for (const name of selected) {- if (!fragment.exports.some((item) => item.name === name)) {- throw new Error(`Run Fragment ${declaration.id} has no export ${name}`);- }- candidateNames.add(`${declaration.id}.${name}`);- }- }- for (const satisfaction of decoded.document.satisfactions) {- const output = authorOutput(satisfaction.output);- if (output.ref.kind !== "logical-output") {- throw new Error(`${satisfaction.output} is an authored Record, not a realizable Logical Output`);- }- if (!candidateNames.has(satisfaction.candidate)) {- throw new Error(`Unknown Run Candidate ${satisfaction.candidate}`);- }+ const executionCompilation = program === author.program ? author : { ...author, program };+ const structuralRun = await resolveRunDocument(decoded.document, {+ compilation: executionCompilation,+ fragments: this.#options.fragments,+ });+ const structuralPlan = planBuild(program, author.graph, structuralRun.graph);+ const selectedLocalSources = new Set(structuralPlan.selections+ .filter((selection) => {+ const candidateSource = structuralRun.candidateSources[selection.candidate];+ return candidateSource?.kind === "stored-value" || candidateSource?.kind === "file";+ })+ .map((selection) => selection.candidate));+ const resolvedValues = new Map<string, StoredValue>();+ for (const candidate of selectedLocalSources) {+ const candidateSource = structuralRun.candidateSources[candidate]!;+ const value = candidateSource.kind === "stored-value"+ ? await storedValueFromWorkspace(workspace, source, candidateSource.from)+ : candidateSource.kind === "file"+ ? await fileValueFromWorkspace(workspace, source, candidateSource.from, candidateSource.mediaType)+ : undefined;+ if (value !== undefined) resolvedValues.set(candidate, value);}- for (const target of decoded.document.targets) {- const output = authorOutput(target.output);- if (output.ref.kind !== "logical-output") {- throw new Error(`${target.output} is an authored Record, not a realizable Logical Output`);+ const checkedRunGraph = sealRunGraph({+ ...structuralRun.graph,+ candidates: structuralRun.graph.candidates.map((candidate) => {+ const value = resolvedValues.get(candidate.id);+ if (value === undefined) return candidate;+ if (candidate.root.kind !== "value") throw new Error(`Run Candidate ${candidate.id} is not a zero-input value`);+ return {+ ...candidate,+ root: {+ kind: "value" as const,+ value: { id: candidate.root.value.id, value },+ },+ };+ }),+ });+ const checkedPlan = planBuild(program, author.graph, checkedRunGraph);+ const admitRecord = (this.#options.authorCompiler as NodeCompiler & {+ readonly admitRecord?: NodeCompiler["admitRecord"];+ }).admitRecord;+ if (typeof admitRecord === "function") {+ const localRecordIds = new Set(checkedPlan.selections+ .filter((selection) => selectedLocalSources.has(selection.candidate))+ .map((selection) => selection.record));+ for (const record of checkedPlan.initialRecords) {+ if (localRecordIds.has(record.id)) await admitRecord.call(this.#options.authorCompiler, program, record);}}return {@@ -268,7 +268,7 @@ export class NodeRunCompiler {author,program,document: decoded.document,- unresolvedBuildRecords: decoded.document.candidates.flatMap((item) => item.kind === "build-record"+ unresolvedHistoricalOutputs: decoded.document.candidates.flatMap((item) => item.kind === "build-record"? [{ id: item.id, build: item.build, output: item.output }]: []),attachments: mergeAttachments([author.attachments, await workspace.attachments()]),@@ -288,23 +288,73 @@ export class NodeRunCompiler {collectRunModuleRequests(decoded.document, this.#options.fragments),);const executionCompilation = program === author.program ? author : { ...author, program };- const resolveBuildRecord = this.#options.resolveBuildRecord;+ const resolveHistoricalOutput = this.#options.resolveHistoricalOutput;const buildAttachments: ArtifactAttachment[] = [];- const run = await resolveRunDocument(decoded.document, {+ const structuralRun = await resolveRunDocument(decoded.document, {compilation: executionCompilation,fragments: this.#options.fragments,- readStoredValue: async (from) => await storedValueFromWorkspace(workspace, source, from),- readFile: async (from, mediaType) => await fileValueFromWorkspace(workspace, source, from, mediaType),- async resolveBuildRecord(build, output) {- if (resolveBuildRecord === undefined) {- throw new Error(`Run contains historical Build Candidate ${build}; plan/build requires --runtime to resolve it`);- }- const resolved = await resolveBuildRecord(build, output);- if (resolved === undefined) return undefined;- buildAttachments.push(...(resolved.attachments ?? []));- return { type: resolved.type, value: resolved.value };- },});+ const structuralPlan = planBuild(program, author.graph, structuralRun.graph);+ const selectedSources = new Set(structuralPlan.selections+ .filter((selection) => structuralRun.candidateSources[selection.candidate] !== undefined)+ .map((selection) => selection.candidate));+ const resolvedValues = new Map<string, StoredValue>();+ for (const candidate of selectedSources) {+ const candidateSource = structuralRun.candidateSources[candidate]!;+ if (candidateSource.kind === "stored-value") {+ resolvedValues.set(candidate, await storedValueFromWorkspace(workspace, source, candidateSource.from));+ continue;+ }+ if (candidateSource.kind === "file") {+ resolvedValues.set(candidate, await fileValueFromWorkspace(+ workspace,+ source,+ candidateSource.from,+ candidateSource.mediaType,+ ));+ continue;+ }+ if (resolveHistoricalOutput === undefined) {+ throw new Error(`Historical Build Candidate ${candidateSource.build}/${candidateSource.output} requires a project Result Store`);+ }+ const resolved = await resolveHistoricalOutput(candidateSource.build, candidateSource.output);+ if (resolved === undefined) {+ throw new Error(`Build ${candidateSource.build} has no Output ${candidateSource.output}`);+ }+ const declaration = structuralRun.graph.candidates.find((item) => item.id === candidate)!;+ if (!sameType(resolved.type, declaration.type)) {+ throw new Error(`Build ${candidateSource.build} Output ${candidateSource.output} has the wrong type for its satisfied Logical Output`);+ }+ resolvedValues.set(candidate, resolved.value);+ buildAttachments.push(...(resolved.attachments ?? []));+ }+ const run = {+ ...structuralRun,+ graph: sealRunGraph({+ ...structuralRun.graph,+ candidates: structuralRun.graph.candidates.map((candidate) => {+ const resolved = resolvedValues.get(candidate.id);+ if (resolved === undefined) return candidate;+ if (candidate.root.kind !== "value") throw new Error(`Historical Candidate ${candidate.id} is not a zero-input value`);+ return {+ ...candidate,+ root: {+ kind: "value" as const,+ value: { id: candidate.root.value.id, value: resolved },+ },+ };+ }),+ }),+ };+ const admitted = planBuild(program, author.graph, run.graph);+ const admitRecord = (this.#options.authorCompiler as NodeCompiler & {+ readonly admitRecord?: NodeCompiler["admitRecord"];+ }).admitRecord;+ if (typeof admitRecord === "function") {+ for (const record of admitted.initialRecords) {+ await admitRecord.call(this.#options.authorCompiler, program, record);+ }+ }return {source: source.id,authorSource: authorSource.id,@@ -316,23 +366,23 @@ export class NodeRunCompiler {}planCompilation(compilation: NodeCompiledRun): PlannedBuild {- const authorGraph = compilation.author.graph;- const selected = new Map(compilation.run.graph.satisfactions.map((item) => [item.output, item.candidate]));- const fullGraph = sealCompiledGraph({- outputs: authorGraph.outputs.map((output) => ({- ...output,- primary: selected.get(output.id) ?? output.primary,- })),- candidates: [...authorGraph.candidates, ...compilation.run.graph.candidates],- operations: [...authorGraph.operations, ...compilation.run.graph.operations],+ const sliced = sliceExecution(compilation.program, compilation.author.graph, compilation.run.graph);+ const definition = defineBuild({+ program: sliced.program,+ initialRecords: sliced.initialRecords,+ plan: sliced.plan,+ targets: sliced.targets,});- const fullRequest = sealBuildRequest({- targets: compilation.run.graph.targets,- });- const sliced = sliceExecution(compilation.program, fullGraph, fullRequest);- const definition = defineBuild(sliced.program, sliced.graph, fullRequest);const state = materializeBuild(definition, []);- return { compilation, definition, state };+ const resultForwards = sliced.selections.flatMap((selection) => {+ const source = compilation.run.candidateSources[selection.candidate];+ return source?.kind !== "build-output" ? [] : [{+ output: selection.output,+ build: source.build,+ sourceOutput: source.output,+ }];+ });+ return { compilation, selections: sliced.selections, resultForwards, definition, state };}async planFile(file: string): Promise<PlannedBuild> {diff --git a/packages/compiler-node/test/compiler.test.ts b/packages/compiler-node/test/compiler.test.tsindex ba1df4cb..4db10bcd 100644--- a/packages/compiler-node/test/compiler.test.ts+++ b/packages/compiler-node/test/compiler.test.ts@@ -404,12 +404,12 @@ test("Run-only Fragment modules extend the execution closure without polluting t"the durable Build keeps only modules needed by its selected execution slice",);assert.equal(planned.definition.plan, planned.state.plan);- assert.equal(planned.definition.request, planned.state.request);+ assert.equal(planned.definition.targets, planned.state.targets);assert.equal(planned.definition.plan.steps.length, 1);assert.equal(planned.definition.plan.steps[0]?.producer.name, previewProducer.name);});-test("static Run checking accepts a future BuildRecord without opening a BuildArchive", async () => {+test("static Run checking accepts a future BuildRecord without opening project Results", async () => {const root = await mkdtemp(join(tmpdir(), "hypit-future-build-record-"));const authorFile = join(root, "main.svml");const runFile = join(root, "reuse.svrun");@@ -435,15 +435,52 @@ test("static Run checking accepts a future BuildRecord without opening a BuildAr});const workspace = await new NodeFilesystemWorkspace({ root }).open(runFile);const checked = await runCompiler.checkSource(workspace.entry, workspace);- assert.deepEqual(checked.unresolvedBuildRecords, [{+ assert.deepEqual(checked.unresolvedHistoricalOutputs, [{id: "prior",build: "future-build",output: "hello.result",}]);await assert.rejects(runCompiler.compileSource(workspace.entry, workspace),- /plan\/build requires --runtime to resolve it/u,+ /requires a project Result Store/u,);++ await writeFile(authorFile, `<?svml using="@hypit/markup@1"?>+ <svml>+ <import as="lab" from="example.compiler-lab@1"/>+ <lab:Result id="hello"/><lab:Result id="unused-history"/>+ <lab:Result id="unused-value"/><lab:Result id="unused-file"/>+ </svml>`, "utf8");+ await writeFile(runFile, `<?svml using="@hypit/run-markup@1"?>+ <svrun version="1">+ <author source="./main.svml"/>+ <target output="hello.result"/>+ <build-record id="prior" build="future-build" output="unused-history.result"/>+ <value id="fixed" type="example.compiler-lab@1#Result" from="./missing-value.json"/>+ <file id="media" type="example.compiler-lab@1#Result" from="./missing-file.mp4" media-type="video/mp4"/>+ <satisfy output="unused-history.result" candidate="prior"/>+ <satisfy output="unused-value.result" candidate="fixed"/>+ <satisfy output="unused-file.result" candidate="media"/>+ </svrun>`, "utf8");+ const unusedWorkspace = await new NodeFilesystemWorkspace({ root }).open(runFile);+ const compiled = await runCompiler.compileSource(unusedWorkspace.entry, unusedWorkspace);+ assert.equal(runCompiler.planCompilation(compiled).state.plan.steps.length, 1,+ "unreachable zero-input Candidates are never opened or substituted into the selected execution");++ await writeFile(join(root, "selected-value.json"), JSON.stringify({ kind: "inline", value: "ready" }), "utf8");+ await writeFile(join(root, "selected-file.mp4"), new Uint8Array([1, 2, 3]));+ await writeFile(runFile, `<?svml using="@hypit/run-markup@1"?>+ <svrun version="1">+ <author source="./main.svml"/>+ <target output="unused-value.result"/><target output="unused-file.result"/>+ <value id="fixed" type="example.compiler-lab@1#Result" from="./selected-value.json"/>+ <file id="media" type="example.compiler-lab@1#Result" from="./selected-file.mp4" media-type="video/mp4"/>+ <satisfy output="unused-value.result" candidate="fixed"/>+ <satisfy output="unused-file.result" candidate="media"/>+ </svrun>`, "utf8");+ const selectedWorkspace = await new NodeFilesystemWorkspace({ root }).open(runFile);+ const selected = runCompiler.planCompilation(await runCompiler.compileSource(selectedWorkspace.entry, selectedWorkspace));+ assert.deepEqual(selected.definition.initialRecords.map((record) => record.value.kind).sort(), ["blob", "inline"]);});test("source assets become graph values and a Host transfer bundle without closure metadata", async () => {diff --git a/packages/core/README.md b/packages/core/README.mdindex 6c2ad367..23c4b9d4 100644--- a/packages/core/README.md+++ b/packages/core/README.md@@ -2,13 +2,17 @@The domain neutral graph compiler and build state machine.-Core links module declarations, validates a compiled graph and walks backwards from the requested-targets. Explicit candidate selections decide how each logical output is realized. The result is a-finite `BuildPlan` containing only the operations needed for that build.+Core links module declarations and plans one complete Author Graph together with one complete Run+Graph. Starting at the Targets, it applies explicit satisfactions, follows every dependency introduced+by the selected Candidates, and derives one finite execution closure without rewriting either source+graph.Execution is one immutable `BuildDefinition` followed by accepted `BuildFact` values. `BuildMachine`reconstructs the current view, emits the next commands and accepts their results. The materialized`BuildState` is a disposable view rather than durable authority.+`BuildDefinition` contains only the selected Program, initial Records, Producer steps,+`Output -> Record` bindings and Targets. Graphs, satisfactions and Candidate identities end at the+planning boundary.Core does not parse source files, load packages, execute components, call providers, store artifactbytes or know what a video is. Those responsibilities remain in compiler and runtime packages.diff --git a/packages/core/src/graph.ts b/packages/core/src/graph.tsindex 1970cc7f..0f12efab 100644--- a/packages/core/src/graph.ts+++ b/packages/core/src/graph.ts@@ -57,7 +57,6 @@ function normalizedStoredValue(value: StoredValue): StoredValue {if (value.kind === "inline") return { kind: "inline", value: canonicalize(value.value) };return {kind: "blob",- ...(value.origin === undefined ? {} : { origin: { ...value.origin } }),resource: value.resource,size: value.size,mediaType: value.mediaType,diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 47587c1b..04d06cff 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -18,8 +18,8 @@ export {verifyBuildRequest,verifyCompiledGraph,} from "./graph.js";-export { compileBuild, plannedNeeds } from "./plan.js";-export type { PlannedNeed } from "./plan.js";+export { compileBuild, planBuild, plannedNeeds } from "./plan.js";+export type { BuildCandidateSelection, PlannedExecution, PlannedNeed } from "./plan.js";export { sliceExecution } from "./slice.js";export {admitBuildResult,diff --git a/packages/core/src/plan.ts b/packages/core/src/plan.tsindex 3e3ddf3d..a0fd686d 100644--- a/packages/core/src/plan.ts+++ b/packages/core/src/plan.ts@@ -9,18 +9,18 @@ import type {OperationNode,ProducerStep,RecordId,+ RunGraph,+ Satisfaction,TypeRef,TypedRecord,} from "@hypit/protocol";-import { canonicalStringify } from "@hypit/protocol";import { invariant } from "./error.js";import {operationResultRecord,resolveCandidate,resolveLogicalOutput,resolveOperation,- satisfiedCandidate,verifyBuildRequest,} from "./graph.js";import { resolveProducer } from "./link.js";@@ -98,27 +98,60 @@ export function plannedNeeds(state: BuildState): readonly PlannedNeed[] {function planContent(steps: readonly ProducerStep[],goals: BuildPlan["goals"],- selections: BuildPlan["selections"],+ outputBindings: BuildPlan["outputBindings"],): BuildPlan {return {format: "hypit.plan@1",steps,goals,- selections,+ outputBindings,};}-export function compileBuild(+/** Candidate identity is useful only while the two source graphs are being planned. */+export type BuildCandidateSelection = {+ readonly output: string;+ readonly candidate: string;+ readonly record: string;+};++export type PlannedExecution = {+ readonly plan: BuildPlan;+ readonly selections: readonly BuildCandidateSelection[];+ readonly initialRecords: readonly TypedRecord[];+};++function compilePlanning(program: LinkedProgram,graph: CompiledGraph,request: BuildRequest,-): BuildPlan {+ satisfactions: readonly Satisfaction[],+): PlannedExecution {verifyBuildRequest(program, graph, request);+ const selectedCandidates = new Map<string, string>();+ for (const satisfaction of satisfactions) {+ const output = resolveLogicalOutput(graph, satisfaction.output);+ const candidate = resolveCandidate(graph, satisfaction.candidate);+ invariant(+ !selectedCandidates.has(output.id),+ "DUPLICATE_RUN_SATISFACTION",+ `${output.id} is satisfied more than once`,+ output.id,+ );+ invariant(+ sameType(candidate.type, output.type),+ "CANDIDATE_RESULT_TYPE_MISMATCH",+ `${candidate.id} supplies ${typeKey(candidate.type)}, not ${typeKey(output.type)}`,+ candidate.id,+ );+ selectedCandidates.set(output.id, candidate.id);+ }+const authored = new Map(program.records.map((record) => [record.id, record]));const demandedOperations = new Map<string, OperationNode>();const resolvedOutputs = new Map<string, ResolvedSource>();- const selections = new Map<string, BuildPlan["selections"][number]>();+ const selections = new Map<string, BuildCandidateSelection>();const operationSource = (id: string): ResolvedSource => {const operation = resolveOperation(graph, id);@@ -149,7 +182,7 @@ export function compileBuild(}if (resolvedOutputs.has(ref.id)) continue;const output = resolveLogicalOutput(graph, ref.id);- const candidate = satisfiedCandidate(graph, ref.id);+ const candidate = resolveCandidate(graph, selectedCandidates.get(ref.id) ?? output.primary);let resolved: ResolvedSource;if (candidate.root.kind === "value") {const record: TypedRecord = {@@ -222,14 +255,49 @@ export function compileBuild(.map(({ source }) => ({ record: source.record, type: source.type })).sort((a, b) => a.record.localeCompare(b.record));const sortedSelections = [...selections.values()].sort((a, b) => a.output.localeCompare(b.output));- const plan = planContent(steps, goals, sortedSelections);- validatePlanStructure(program, graph, plan);- return plan;+ const outputBindings = sortedSelections.map((selection) => ({+ output: selection.output,+ record: selection.record,+ type: resolveLogicalOutput(graph, selection.output).type,+ }));+ const initialRecords = selectedProvidedRecords(program, graph, sortedSelections);+ const plan = planContent(steps, goals, outputBindings);+ verifyBuildPlan(program, initialRecords, plan);+ return { plan, selections: sortedSelections, initialRecords };}-function validatePlanStructure(+/** Plan one Author Graph with one complete Run Graph without rewriting either graph. */+export function planBuild(+ program: LinkedProgram,+ authorGraph: CompiledGraph,+ runGraph: RunGraph,+): PlannedExecution {+ invariant(runGraph.format === "hypit.run-graph@1", "UNSUPPORTED_RUN_GRAPH", "unsupported Run Graph");+ const graph: CompiledGraph = {+ format: "hypit.graph@1",+ outputs: authorGraph.outputs,+ candidates: [...authorGraph.candidates, ...runGraph.candidates],+ operations: [...authorGraph.operations, ...runGraph.operations],+ };+ const request: BuildRequest = {+ format: "hypit.build-request@1",+ targets: runGraph.targets,+ };+ return compilePlanning(program, graph, request, runGraph.satisfactions);+}++/** Author-only planning convenience. Run compilation should call `planBuild`. */+export function compileBuild(program: LinkedProgram,graph: CompiledGraph,+ request: BuildRequest,+): BuildPlan {+ return compilePlanning(program, graph, request, []).plan;+}++export function verifyBuildPlan(+ program: LinkedProgram,+ initialRecords: readonly TypedRecord[],plan: BuildPlan,): void {invariant(plan.format === "hypit.plan@1", "UNSUPPORTED_PLAN", "unsupported build plan format");@@ -237,7 +305,7 @@ function validatePlanStructure(const records = new Map<RecordId, ProducedRecord>();for (const record of program.records) records.set(record.id, { type: record.type });- for (const record of selectedProvidedRecords(program, graph, plan)) {+ for (const record of initialRecords) {invariant(!records.has(record.id), "DUPLICATE_RECORD", `record ${record.id} has multiple sources`, record.id);records.set(record.id, { type: record.type });}@@ -288,11 +356,13 @@ function validatePlanStructure(}}- for (const selection of plan.selections) {- const output = resolveLogicalOutput(graph, selection.output);- const record = records.get(selection.record);- invariant(record !== undefined, "UNKNOWN_SELECTION_RECORD", `${selection.output} selects ${selection.record}`);- invariant(sameType(record.type, output.type), "SELECTION_TYPE_MISMATCH", selection.output);+ const outputIds = new Set<string>();+ for (const binding of plan.outputBindings) {+ invariant(!outputIds.has(binding.output), "DUPLICATE_OUTPUT_BINDING", `${binding.output} is bound more than once`);+ outputIds.add(binding.output);+ const record = records.get(binding.record);+ invariant(record !== undefined, "UNKNOWN_OUTPUT_RECORD", `${binding.output} binds ${binding.record}`);+ invariant(sameType(record.type, binding.type), "OUTPUT_BINDING_TYPE_MISMATCH", binding.output);}for (const goal of plan.goals) {const supplied = records.get(goal.record);@@ -307,11 +377,12 @@ function validatePlanStructure(export function selectedProvidedRecords(program: LinkedProgram,graph: CompiledGraph,- plan: BuildPlan,+ selections: readonly BuildCandidateSelection[],): readonly TypedRecord[] {const authored = new Set(program.records.map((record) => record.id));const records = new Map<string, TypedRecord>();- for (const selection of plan.selections) {+ const candidates = new Map<string, string>();+ for (const selection of selections) {const candidate = resolveCandidate(graph, selection.candidate);if (candidate.root.kind !== "value") continue;const record: TypedRecord = {@@ -321,13 +392,14 @@ export function selectedProvidedRecords(};invariant(selection.record === record.id, "SELECTION_RECORD_MISMATCH", `${selection.output} does not select ${record.id}`);invariant(!authored.has(record.id), "PROVIDED_RECORD_CONFLICT", `${record.id} conflicts with authored input`, record.id);- const previous = records.get(record.id);+ const previousCandidate = candidates.get(record.id);invariant(- previous === undefined || canonicalStringify(previous) === canonicalStringify(record),+ previousCandidate === undefined || previousCandidate === candidate.id,"PROVIDED_RECORD_CONFLICT",- `${record.id} has conflicting Provided Values`,+ `${record.id} is supplied by both ${previousCandidate ?? "an authored Record"} and ${candidate.id}`,record.id,);+ candidates.set(record.id, candidate.id);records.set(record.id, record);}return [...records.values()].sort((left, right) => left.id.localeCompare(right.id));diff --git a/packages/core/src/reducer.ts b/packages/core/src/reducer.tsindex 8ab8db64..d4d81dd0 100644--- a/packages/core/src/reducer.ts+++ b/packages/core/src/reducer.ts@@ -1,7 +1,6 @@import type {BuildDefinition,BuildFact,- BuildPlan,BuildRequest,BuildState,CoreCommand,@@ -20,7 +19,7 @@ import type {import { canonicalize, SvmlError } from "@hypit/protocol";import { invariant } from "./error.js";import { resolveProducer, verifyRecordStructure } from "./link.js";-import { compileBuild, producerStep, selectedProvidedRecords } from "./plan.js";+import { planBuild, producerStep, verifyBuildPlan } from "./plan.js";function commandId(kind: "producer" | "need", subject: string): string {return `${kind}:${subject}`;@@ -239,21 +238,19 @@ export function start(graph: CompiledGraph,request: BuildRequest,): BuildState {- const plan: BuildPlan = compileBuild(program, graph, request);- const state: BuildState = {- format: "hypit.build@1",+ const planned = planBuild(program, graph, {+ format: "hypit.run-graph@1",+ candidates: [],+ operations: [],+ satisfactions: [],+ targets: request.targets,+ });+ return initialBuildView(defineBuild({program,- graph,- request,- plan,- status: "active",- records: [...program.records, ...selectedProvidedRecords(program, graph, plan)],- steps: plan.steps.map((step) => ({ id: step.id, status: "pending" })),- needs: [],- outstanding: [],- diagnostics: [],- };- return state;+ initialRecords: planned.initialRecords,+ plan: planned.plan,+ targets: request.targets,+ }));}export function reduce(state: BuildState, event?: CommandResult): BuildState {@@ -261,42 +258,32 @@ export function reduce(state: BuildState, event?: CommandResult): BuildState {return schedule(next);}-function definitionContent(- state: Pick<BuildState, "program" | "graph" | "request" | "plan">,-): Omit<BuildDefinition, "format"> {- return {- program: state.program,- graph: state.graph,- request: state.request,- plan: state.plan,- };-}--/** Compile one immutable finite Build definition. Runtime execution never changes it. */+/** Seal one already selected execution. Graphs and Candidates do not cross this boundary. */export function defineBuild(- program: LinkedProgram,- graph: CompiledGraph,- request: BuildRequest,+ input: Omit<BuildDefinition, "format">,): BuildDefinition {- const initial = start(program, graph, request);- return {- format: "hypit.build-definition@1",- ...definitionContent(initial),- };+ verifyBuildPlan(input.program, input.initialRecords, input.plan);+ invariant(input.targets.length > 0, "EMPTY_BUILD_TARGETS", "Build has no Targets");+ const bindings = new Set(input.plan.outputBindings.map((binding) => binding.output));+ const targets = new Set<string>();+ for (const target of input.targets) {+ invariant(bindings.has(target.output), "UNKNOWN_BUILD_TARGET", `${target.output} has no Output binding`, target.output);+ invariant(!targets.has(target.output), "DUPLICATE_BUILD_TARGET", `${target.output} is targeted twice`, target.output);+ targets.add(target.output);+ }+ return { format: "hypit.build-definition@2", ...input };}function initialBuildView(definition: BuildDefinition): BuildState {+ invariant(definition.format === "hypit.build-definition@2", "UNSUPPORTED_BUILD_DEFINITION", definition.format);+ verifyBuildPlan(definition.program, definition.initialRecords, definition.plan);return {format: "hypit.build@1",program: definition.program,- graph: definition.graph,- request: definition.request,plan: definition.plan,+ targets: definition.targets,status: "active",- records: [- ...definition.program.records,- ...selectedProvidedRecords(definition.program, definition.graph, definition.plan),- ],+ records: [...definition.program.records, ...definition.initialRecords],steps: definition.plan.steps.map((step) => ({ id: step.id, status: "pending" })),needs: [],outstanding: [],diff --git a/packages/core/src/slice.ts b/packages/core/src/slice.tsindex 0168b53c..df72b3bc 100644--- a/packages/core/src/slice.ts+++ b/packages/core/src/slice.ts@@ -1,21 +1,21 @@import type {- BuildRequest,CompiledGraph,GraphValueRef,LinkedProgram,ModuleRef,+ RunGraph,} from "@hypit/protocol";-import { sealCompiledGraph } from "./graph.js";import { createResolvedClosure, link } from "./link.js";-import { compileBuild } from "./plan.js";+import { planBuild } from "./plan.js";+import type { BuildCandidateSelection } from "./plan.js";function moduleKey(ref: ModuleRef): string {return `${ref.name}\u0000${ref.version}`;}/**- * Materialize exactly the execution graph selected by one BuildRequest.+ * Materialize exactly the execution selected by one Author Graph and one Run Graph.** Candidate choice is Core semantics: once an alternate Candidate satisfies an* output, only that Candidate's reachable upstream graph survives. Hosts must@@ -23,11 +23,23 @@ function moduleKey(ref: ModuleRef): string {*/export function sliceExecution(program: LinkedProgram,- graph: CompiledGraph,- request: BuildRequest,-): { readonly program: LinkedProgram; readonly graph: CompiledGraph } {- const preliminary = compileBuild(program, graph, request);- const outputById = new Map(graph.outputs.map((item) => [item.id, item]));+ authorGraph: CompiledGraph,+ runGraph: RunGraph,+): {+ readonly program: LinkedProgram;+ readonly plan: ReturnType<typeof planBuild>["plan"];+ readonly initialRecords: ReturnType<typeof planBuild>["initialRecords"];+ readonly targets: RunGraph["targets"];+ readonly selections: readonly BuildCandidateSelection[];+} {+ const preliminary = planBuild(program, authorGraph, runGraph);+ const graph = {+ format: "hypit.graph@1" as const,+ outputs: authorGraph.outputs,+ candidates: [...authorGraph.candidates, ...runGraph.candidates],+ operations: [...authorGraph.operations, ...runGraph.operations],+ };+ const outputById = new Map(authorGraph.outputs.map((item) => [item.id, item]));const candidateById = new Map(graph.candidates.map((item) => [item.id, item]));const operationById = new Map(graph.operations.map((item) => [item.id, item]));const selectionByOutput = new Map(preliminary.selections.map((item) => [item.output, item]));@@ -62,10 +74,8 @@ export function sliceExecution(outputs.add(id);visitCandidate(selectionByOutput.get(id)?.candidate ?? output.primary);};- request.targets.forEach((target) => visitOutput(target.output));+ runGraph.targets.forEach((target) => visitOutput(target.output));- const selectedOutputs = graph.outputs.filter((item) => outputs.has(item.id));- const selectedCandidates = graph.candidates.filter((item) => candidates.has(item.id));const selectedOperations = graph.operations.filter((item) => operations.has(item.id));const authoredRecords = program.records.filter((record) => records.has(record.id));@@ -80,8 +90,8 @@ export function sliceExecution(resolved.manifest.dependencies.forEach((item) => requireModule(item.module));};selectedOperations.forEach((item) => requireModule(item.producer.module));- selectedOutputs.forEach((item) => requireModule(item.type.module));- selectedCandidates.forEach((item) => requireModule(item.type.module));+ preliminary.plan.outputBindings.forEach((item) => requireModule(item.type.module));+ preliminary.initialRecords.forEach((item) => requireModule(item.type.module));authoredRecords.forEach((item) => requireModule(item.type.module));const closure = createResolvedClosure(program.closure.modules@@ -90,10 +100,9 @@ export function sliceExecution(const slicedProgram = link(closure, authoredRecords);return {program: slicedProgram,- graph: sealCompiledGraph({- outputs: selectedOutputs,- candidates: selectedCandidates,- operations: selectedOperations,- }),+ plan: preliminary.plan,+ initialRecords: preliminary.initialRecords,+ targets: runGraph.targets,+ selections: preliminary.selections,};}diff --git a/packages/core/test/core.test.ts b/packages/core/test/core.test.tsindex 8b83cc82..3909bce5 100644--- a/packages/core/test/core.test.ts+++ b/packages/core/test/core.test.ts@@ -90,7 +90,13 @@ test("Core executes a finite plan through an external Need and completion", () =test("Build Definition plus admitted Facts restores the same next Command", () => {const initial = createGreetingBuild();- const definition = defineBuild(initial.program, initial.graph, initial.request);+ const authored = new Set(initial.program.records.map((record) => record.id));+ const definition = defineBuild({+ program: initial.program,+ initialRecords: initial.records.filter((record) => !authored.has(record.id)),+ plan: initial.plan,+ targets: initial.targets,+ });const machine = new BuildMachine(definition);const facts: BuildFact[] = [];const prompt = machine.commands()[0];diff --git a/packages/core/test/demand.test.ts b/packages/core/test/demand.test.tsindex 338dcf67..402646fc 100644--- a/packages/core/test/demand.test.ts+++ b/packages/core/test/demand.test.ts@@ -2,7 +2,10 @@ import assert from "node:assert/strict";import test from "node:test";import {createResolvedClosure,+ defineBuild,link,+ materializeBuild,+ planBuild,reduce,sealBuildRequest,sealCompiledGraph,@@ -282,23 +285,25 @@ function request(targets: readonly string[]): BuildRequest {});}-function selectCandidates(graph: CompiledGraph, satisfactions: readonly Satisfaction[]): CompiledGraph {- const selected = new Map(satisfactions.map((item) => [item.output, item.candidate]));- return sealCompiledGraph({- outputs: graph.outputs.map((item) => ({ ...item, primary: selected.get(item.id) ?? item.primary })),- candidates: graph.candidates,- operations: graph.operations,- });-}-function startSelected(program: LinkedProgram,graph: CompiledGraph,targets: readonly string[],satisfactions: readonly Satisfaction[] = [],): BuildState {- const selected = selectCandidates(graph, satisfactions);- return start(program, selected, request(targets));+ const planned = planBuild(program, graph, {+ format: "hypit.run-graph@1",+ candidates: [],+ operations: [],+ satisfactions,+ targets: targets.map((outputId) => ({ output: outputId })),+ });+ return materializeBuild(defineBuild({+ program,+ initialRecords: planned.initialRecords,+ plan: planned.plan,+ targets: targets.map((outputId) => ({ output: outputId })),+ }), []);}function fixture(targets: readonly string[], satisfactions: readonly Satisfaction[] = []): BuildState {@@ -411,8 +416,8 @@ test("Case G: two single-output full-input Candidates share both upstream Valuesconst b2 = state.plan.steps.find((step) => step.id === "b2");assert.deepEqual(b1?.inputs, { A: "provided:A", B: "provided:B" });assert.deepEqual(b2?.inputs, { A: "provided:A", B: "provided:B" });- assert.equal(state.plan.selections.find((item) => item.output === "b.C")?.candidate, "b1");- assert.equal(state.plan.selections.find((item) => item.output === "b.D")?.candidate, "b2");+ assert.equal(state.plan.outputBindings.find((item) => item.output === "b.C")?.record, "operation:C");+ assert.equal(state.plan.outputBindings.find((item) => item.output === "b.D")?.record, "operation:D");});test("Case G: shared zero-input upstream Operations appear exactly once", () => {@@ -470,7 +475,7 @@ test("two Candidates that name one OperationId demand exactly one execution", ()const state = start(program, graph, request(["left", "right"]));assert.deepEqual(stepIds(state), ["left-operation"]);assert.deepEqual(- state.plan.selections.map((selection) => [selection.output, selection.record]),+ state.plan.outputBindings.map((selection) => [selection.output, selection.record]),[["left", "identity:left"], ["right", "identity:left"]],);});@@ -484,8 +489,8 @@ test("one independent Candidate may explicitly satisfy multiple compatible Logic]);assert.deepEqual(stepIds(state), ["left-operation"]);assert.deepEqual(- state.plan.selections.map((selection) => [selection.output, selection.candidate]),- [["left", "shared-candidate"], ["right", "shared-candidate"]],+ state.plan.outputBindings.map((selection) => [selection.output, selection.record]),+ [["left", "identity:left"], ["right", "identity:left"]],);});diff --git a/packages/core/test/greeting-fixture.ts b/packages/core/test/greeting-fixture.tsindex 48289669..9b96a6b7 100644--- a/packages/core/test/greeting-fixture.ts+++ b/packages/core/test/greeting-fixture.ts@@ -163,6 +163,7 @@ export function greetingGraph(includeSide = false): CompiledGraph {export function createGreetingBuild(options?: {readonly generationRealization?: "primary" | "placeholder";readonly includeSideTarget?: boolean;+ readonly targetOutputs?: readonly string[];}): BuildState {const closure = createResolvedClosure([manifest]);const authored = sealRecord({@@ -182,9 +183,8 @@ export function createGreetingBuild(options?: {}): sourceGraph;const request = sealBuildRequest({- targets: [...(options?.includeSideTarget ? [{ output: "side-document" }] : []), {- output: "document",- }],+ targets: options?.targetOutputs?.map((output) => ({ output }))+ ?? [...(options?.includeSideTarget ? [{ output: "side-document" }] : []), { output: "document" }],});return start(program, graph, request);}diff --git a/packages/driver-node/src/driver.ts b/packages/driver-node/src/driver.tsindex 60c37ba4..e50b475c 100644--- a/packages/driver-node/src/driver.ts+++ b/packages/driver-node/src/driver.ts@@ -212,8 +212,7 @@ export class NodeDriver {endpointId: registration.id,resources: registration.scheduling?.resources ?? [{id: `endpoint:${registration.id}`,- maxActive: 1,- maxInFlight: 1,+ limit: 1,}],...(registration.scheduling?.queue === undefined ? {} : { queue: registration.scheduling.queue }),registration,@@ -308,6 +307,9 @@ export class NodeDriver {command: base.command,endpoint: base.endpoint,});+ if (history.length > 1) {+ throw new Error(`Command ${base.command} has multiple asynchronous Operations; refusing to submit or choose between them`);+ }const latest = history[0];if (latest?.status === "completed" || latest?.status === "cancelled") {return await this.#completedOperation(state, executable, latest, latest.id);@@ -318,6 +320,16 @@ export class NodeDriver {if (latest?.status === "failed") {return await this.#completedOperation(state, executable, latest, latest.id);}+ if (latest?.status === "pending" && latest.handle === undefined) {+ const unknown = await operations.update(latest.id, {+ status: "failed",+ failure: {+ code: "SUBMISSION_UNKNOWN",+ message: `Operation ${latest.id} stopped before its Endpoint acknowledgement was stored; the same Build will not submit it again`,+ },+ });+ return await this.#completedOperation(state, executable, unknown, latest.id);+ }const fresh = latest === undefined;const identity = fresh? { id: `op_${randomUUID()}`, ...base }@@ -331,7 +343,23 @@ export class NodeDriver {};let outcome: EndpointOutcome;if (latest === undefined) {- outcome = await executable.registration.endpoint.start(endpointContext);+ await operations.create({+ ...identity,+ status: "pending",+ progress: { phase: "submitting" },+ });+ try {+ outcome = await executable.registration.endpoint.start(endpointContext);+ } catch (error) {+ const unknown = await operations.update(identity.id, {+ status: "failed",+ failure: {+ code: "SUBMISSION_UNKNOWN",+ message: `Endpoint start ended without a stored acknowledgement: ${failureMessage(error)}`,+ },+ });+ return await this.#completedOperation(state, executable, unknown, identity.id);+ }} else {if (latest.status !== "pending" || latest.handle === undefined) {throw new Error(`Operation ${latest.id} cannot be polled`);@@ -342,7 +370,7 @@ export class NodeDriver {});}const write = async (update: OperationUpdate): Promise<OperationSnapshot> =>- fresh ? await operations.create({ ...identity, ...update }) : await operations.update(identity.id, update);+ await operations.update(identity.id, update);if (outcome.status === "pending") {const written = await write({status: "pending",@@ -369,16 +397,14 @@ export class NodeDriver {identity.id,);}- const written = await write({+ // Validate before the terminal completion becomes durable. Result writing may later+ // accept this stored value without loading or calling the Endpoint package again.+ const event = await this.#endpointEvent(state, executable, outcome.result);+ await write({status: "completed",completion: outcome.result,});- return await this.#completedOperation(- state,- executable,- written,- identity.id,- );+ return { status: "completed", event };}async #execute(@@ -496,7 +522,7 @@ export class NodeDriver {if (executable === undefined || !("endpointId" in executable)|| executable.endpointId !== operation.endpoint|| executable.registration.kind !== "asynchronous") {- throw new Error(`Operation ${operation.id} does not match the regenerated Endpoint Command`);+ throw new Error(`Operation ${operation.id} does not match the current Endpoint Command`);}const endpointContext = {command: structuredClone(executable.command),diff --git a/packages/driver-node/src/registry.ts b/packages/driver-node/src/registry.tsindex 6919ef59..c70de342 100644--- a/packages/driver-node/src/registry.ts+++ b/packages/driver-node/src/registry.ts@@ -41,10 +41,8 @@ function verifyScheduling(scheduling: EndpointScheduling | undefined): void {if (scheduling.resources.length === 0) throw new Error("scheduling resources must not be empty");const ids = scheduling.resources.map((resource) => {if (resource.id.trim().length === 0) throw new Error("scheduling resource id must not be empty");- for (const [name, value] of [["maxActive", resource.maxActive], ["maxInFlight", resource.maxInFlight]] as const) {- if (!Number.isSafeInteger(value) || value < 1) {- throw new Error(`scheduling resource ${resource.id} ${name} must be a positive safe integer`);- }+ if (!Number.isSafeInteger(resource.limit) || resource.limit < 1) {+ throw new Error(`scheduling resource ${resource.id} limit must be a positive safe integer`);}return resource.id;});diff --git a/packages/driver-node/test/scheduler.test.ts b/packages/driver-node/test/scheduler.test.tsindex 2e05e82e..0fd3ed24 100644--- a/packages/driver-node/test/scheduler.test.ts+++ b/packages/driver-node/test/scheduler.test.ts@@ -149,8 +149,7 @@ function configuredExecutor(options: {scheduling: {resources: [{id: options.resource,- maxActive: options.defaultConcurrency,- maxInFlight: options.defaultConcurrency,+ limit: options.defaultConcurrency,}],},},@@ -196,8 +195,8 @@ function asyncExecutor(scheduling: {queue: { pool: "fixture.account", lane: "generation" },resources: [- { id: "pool:fixture.account", maxActive: 1, maxInFlight: 1 },- { id: "lane:fixture.account/generation", maxActive: 1, maxInFlight: 1 },+ { id: "pool:fixture.account", limit: 1 },+ { id: "lane:fixture.account/generation", limit: 1 },],},},@@ -295,6 +294,45 @@ test("an asynchronous Endpoint starts once and is polled until complete", asyncassert.equal((await operations.read(pending.operation))?.status, "completed");});+test("a persisted submitting Operation is never submitted again after its caller stops", async () => {+ const durable = memoryOperations();+ let interruptCreate = true;+ const operations: OperationStore = {+ ...durable,+ async create(operation) {+ const stored = await durable.create(operation);+ if (interruptCreate) {+ interruptCreate = false;+ throw new Error("caller stopped after the Operation row was stored");+ }+ return stored;+ },+ };+ let starts = 0;+ const endpoint: AsyncEndpoint = {+ start() {+ starts += 1;+ return { status: "pending", handle: { remoteJob: "must-not-exist" } };+ },+ poll() {+ throw new Error("an unacknowledged Operation cannot be polled");+ },+ };+ const [interrupted] = await new LocalBuildScheduler(asyncExecutor(endpoint, operations))+ .run([{ id: "submission-window", state: createGreetingBuild() }]);+ assert.equal(interrupted?.status, "paused");+ assert.equal(starts, 0);+ const [stored] = await operations.list({ build: "submission-window" });+ assert.equal(stored?.status, "pending");+ assert.equal(stored?.handle, undefined);++ const [resumed] = await new LocalBuildScheduler(asyncExecutor(endpoint, operations))+ .run([{ id: "submission-window", state: interrupted!.state }]);+ assert.equal(resumed?.status, "failed");+ assert.equal(resumed?.state.diagnostics.at(-1)?.code, "SUBMISSION_UNKNOWN");+ assert.equal(starts, 0);+});+test("wakeAt prevents early polling and Runtime cancellation becomes a terminal Core failure", async () => {const operations = memoryOperations();let polls = 0;diff --git a/packages/elaborator/README.md b/packages/elaborator/README.mdindex 951f2e35..c4ad6981 100644--- a/packages/elaborator/README.md+++ b/packages/elaborator/README.md@@ -50,7 +50,7 @@ into Source Closure identity. It does not know whether a Host obtained the bytesbrowser upload, repository object or remote content store.Frontend output passes a Host-owned Record admission hook before linking. The hook is permitted to-reject a Record but is forbidden to rewrite Record identity, Type, value, digest, or origin.+reject a Record but is forbidden to rewrite Record identity, Type or value.`@hypit/compiler-node` wires this to `@hypit/validation` by default, so authoredvalues use the same Type-owner gate as Producer, Provider and provided Candidate values.@@ -59,7 +59,7 @@ contains no JavaScript callback, ambient file lookup, credential access or Runtiexpansion the Elaborator verifies producer ports, types, cycles, reachable exports and SemanticInput Envelopes.-Expansion assigns hygienic identities from `fragment digest + author instance id + local id`.+Expansion assigns hygienic identities from `Fragment id + author instance id + local id`.Multiple exports of one instance therefore share internal Operations, while two explicit instancesremain two nodes even when their content is identical. Author exports become Logical Outputs withPrimary Candidates; Run exports become independent typed Candidates plus explicit Satisfactiondiff --git a/packages/elaborator/src/author.ts b/packages/elaborator/src/author.tsindex 4d88609e..78ca6ef3 100644--- a/packages/elaborator/src/author.ts+++ b/packages/elaborator/src/author.ts@@ -291,7 +291,7 @@ export function elaborateAuthorGraph(inputs[input.name] = { kind: "logical-output", id: binding.id };}const instance = elaborateGraphFragment(program, component.fragment, {- id: component.declaration.id,+ id: `author:${component.declaration.id}`,fragment: component.fragment.id,inputs,});diff --git a/packages/elaborator/src/source.ts b/packages/elaborator/src/source.tsindex a402a9d5..9dc70970 100644--- a/packages/elaborator/src/source.ts+++ b/packages/elaborator/src/source.ts@@ -498,7 +498,7 @@ export async function compileSourceClosure(const resolved = await request.resolveAsset(rawSource, assetRequest);const artifact = resolved.artifact;assert(artifact.kind === "blob", "INVALID_SOURCE_ASSET", `${assetRequest.from} did not resolve to a BlobRef`);- assert(isResourceId(artifact.resource), "INVALID_SOURCE_ASSET_DIGEST", `${assetRequest.from} has an invalid digest`);+ assert(isResourceId(artifact.resource), "INVALID_SOURCE_ASSET_RESOURCE", `${assetRequest.from} has an invalid Resource identity`);assert(Number.isSafeInteger(artifact.size) && artifact.size >= 0, "INVALID_SOURCE_ASSET_SIZE", `${assetRequest.from} has an invalid size`);assert(artifact.mediaType === assetRequest.mediaType,diff --git a/packages/elaborator/test/fragment.test.ts b/packages/elaborator/test/fragment.test.tsindex 8e61d574..62915d2e 100644--- a/packages/elaborator/test/fragment.test.ts+++ b/packages/elaborator/test/fragment.test.ts@@ -194,12 +194,10 @@ test("one FragmentInstance shares its generation Operation across all exports",);});-test("the same Fragment instance is deterministic while distinct instances never content-dedupe", () => {+test("distinct Fragment instances never content-dedupe", () => {const linked = program();const opening = instance(linked, "opening");- const openingAgain = instance(linked, "opening");const closing = instance(linked, "closing");- assert.deepEqual(opening, openingAgain);assert.notEqual(opening.id, closing.id);assert.equal(new Set([...opening.operations, ...closing.operations].map((operation) => operation.id)).size,diff --git a/packages/endpoint-kit/README.md b/packages/endpoint-kit/README.mdindex 4ef00c44..6502bb2f 100644--- a/packages/endpoint-kit/README.md+++ b/packages/endpoint-kit/README.md@@ -8,7 +8,8 @@ limits, then installs handlers into a Host registrar.Immediate endpoints return a result directly. Asynchronous endpoints implement `start`, `poll` andoptional best effort `cancel`. Provider pool and capability lane limits control concurrency without-changing Core demand.+changing Core demand. Each resource declares one limit; asynchronous work retains that slot until+its persisted Operation is terminal.Endpoint packages are selected by a Runtime Profile, never activated by author imports. This packagedepends on no Node filesystem, queue implementation or video domain.diff --git a/packages/endpoint-kit/src/index.ts b/packages/endpoint-kit/src/index.tsindex 10a6a4b0..2c058b1e 100644--- a/packages/endpoint-kit/src/index.ts+++ b/packages/endpoint-kit/src/index.ts@@ -75,8 +75,8 @@ export type AsyncEndpoint = {export type EndpointScheduling = {readonly resources: readonly {readonly id: string;- readonly maxActive: number;- readonly maxInFlight: number;+ /** Maximum Commands occupying this active Provider resource across Builds. */+ readonly limit: number;}[];readonly queue?: {readonly pool: string;@@ -265,13 +265,11 @@ export function defineEndpointPackage(options: DefineEndpointPackageOptions): Enresources: [{id: `pool:${options.pool}`,- maxActive: authorityConcurrency,- maxInFlight: authorityConcurrency,+ limit: authorityConcurrency,},{id: `lane:${options.pool}/${lane}`,- maxActive: laneConcurrency,- maxInFlight: laneConcurrency,+ limit: laneConcurrency,},],},diff --git a/packages/endpoint-kit/test/endpoint.test.ts b/packages/endpoint-kit/test/endpoint.test.tsindex 6b42db7d..3c486772 100644--- a/packages/endpoint-kit/test/endpoint.test.ts+++ b/packages/endpoint-kit/test/endpoint.test.ts@@ -72,8 +72,8 @@ test("one Endpoint definition generates one configured instance and host-neutralassert.deepEqual(registrations[0]?.options.scheduling, {queue: { pool: "example.personal", lane: "text-generation" },resources: [- { id: "pool:example.personal", maxActive: 3, maxInFlight: 3 },- { id: "lane:example.personal/text-generation", maxActive: 1, maxInFlight: 1 },+ { id: "pool:example.personal", limit: 3 },+ { id: "lane:example.personal/text-generation", limit: 1 },],});});diff --git a/packages/fonts-open/test/fonts-open.test.ts b/packages/fonts-open/test/fonts-open.test.tsindex 5d906e18..6b13d0b3 100644--- a/packages/fonts-open/test/fonts-open.test.ts+++ b/packages/fonts-open/test/fonts-open.test.ts@@ -1,19 +1,13 @@import assert from "node:assert/strict";-import { readFileSync } from "node:fs";-import { createRequire } from "node:module";import test from "node:test";import {decodeOpenFontFaceSurface,decodeOpenFontStackSurface,- openFontFamilies,- openFontFamiliesByCategory,- openFontFamilyNames,} from "@hypit/fonts-open";import type { FontArtifactRef, FontStackRef } from "@hypit/media";import type { StructuredElement, StructuredSurfaceHandler } from "@hypit/markup";-const require = createRequire(import.meta.url);const range = { start: 0, end: 80 };async function decode(@@ -55,41 +49,6 @@ async function decodeFace(family: string, weight: string, style: string) {return { ...result, font: result.value as unknown as FontArtifactRef };}-test("the catalog exposes 109 publishable open families with frontend metadata", () => {- assert.equal(openFontFamilyNames.length, 109);- assert.equal(Object.values(openFontFamiliesByCategory).flat().length, 109);- for (const family of Object.values(openFontFamilies)) {- assert.ok(family.label);- assert.ok(family.intendedUse);- assert.ok(["OFL-1.1", "Apache-2.0"].includes(family.license));- }-});--test("catalog license metadata matches every installed Fontsource package", () => {- for (const [name, family] of Object.entries(openFontFamilies)) {- const packagePath = require.resolve(`${family.packageName}/package.json`);- const packageJson = JSON.parse(readFileSync(packagePath, "utf8")) as { readonly license: string };- assert.equal(packageJson.license, family.license, name);- }-});--test("every declared family, static weight and style can materialize exact bytes", async () => {- for (const name of openFontFamilyNames) {- const family = openFontFamilies[name];- const weights = family.kind === "static" || family.kind === "static-split" || family.kind === "external-split"- ? family.weights- : [family.minimumWeight];- for (const weight of weights) {- for (const style of family.styles) {- const { font, requests } = await decodeFace(name, String(weight), style);- assert.ok(font.sources.length > 0, `${name} ${weight} ${style}`);- assert.equal(requests.length, font.sources.length, `${name} ${weight} ${style}`);- assert.equal(new Set(requests.map((request) => request.from)).size, requests.length, name);- }- }- }-});-test("one Latin variable face contributes one exact installed source", async () => {const { font, requests } = await decodeFace("inter", "700", "italic");assert.equal(font.weight, 700);diff --git a/packages/generation/src/request.ts b/packages/generation/src/request.tsindex bb878fd0..8ef51af5 100644--- a/packages/generation/src/request.ts+++ b/packages/generation/src/request.ts@@ -113,7 +113,7 @@ export type GenerationPortSubset = {/*** Ports that may be absent while a graph is still attaching values. If they* are present, their item and cardinality rules are still checked. Exact- * finalization never uses this escape hatch.+ * Result writing never uses this escape hatch.*/readonly defer?: readonly string[];};diff --git a/packages/gpt-image/test/surface.test.ts b/packages/gpt-image/test/surface.test.tsindex c45254bd..79db6be4 100644--- a/packages/gpt-image/test/surface.test.ts+++ b/packages/gpt-image/test/surface.test.ts@@ -2,16 +2,14 @@ import assert from "node:assert/strict";import test from "node:test";import { artifactTypes } from "@hypit/artifact";-import { markupSurfaceHostFacetAbi, parseStructuredElement } from "@hypit/markup";+import { parseStructuredElement } from "@hypit/markup";import type { StructuredSurfaceHandler, SurfaceResolvedReference } from "@hypit/markup";import { textTypes } from "@hypit/text";-import gptImageNodePackage from "../src/activation.js";import {decodeCleanGptImageSurface,decodeGptImageSurface,} from "../src/surface.js";-import { gptImageCleanMarkupSurfaces, gptImageMarkupSurfaces } from "../src/index.js";const refs = new Map<string, SurfaceResolvedReference>([["prompt", {@@ -85,18 +83,6 @@ test("clean GPT Image Surface adds the official denoise as one visible downstreaassert.deepEqual(clean?.inputs.program, { kind: "fragment-input", name: "cleanup" });});-test("the physical package carries both independently importable Surface implementations", () => {- assert.deepEqual([- { name: "@hypit/gpt-image", surfaces: gptImageMarkupSurfaces.map((surface) => surface.tag) },- { name: "@hypit/gpt-image/clean", surfaces: gptImageCleanMarkupSurfaces.map((surface) => surface.tag) },- ], [- { name: "@hypit/gpt-image", surfaces: ["Image"] },- { name: "@hypit/gpt-image/clean", surfaces: ["Image"] },- ]);- assert.equal(gptImageNodePackage.hostFacets- .filter((facet) => facet.abi === markupSurfaceHostFacetAbi).length, 2);-});-test("GPT Image Surface rejects hidden inline prompts and undeclared child shapes", async () => {await assert.rejects(decode('<gpt:Image id="bad" prompt="inline" aspect-ratio="9:16" resolution="2K"/>', decodeGptImageSurface),diff --git a/packages/media/src/schema.ts b/packages/media/src/schema.tsindex 10a7ebed..1c46c1ec 100644--- a/packages/media/src/schema.ts+++ b/packages/media/src/schema.ts@@ -7,10 +7,6 @@ const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema;const blobArtifactSchema = (mediaTypes?: readonly string[]): ValueSchema => object({kind: { schema: { kind: "literal", value: "blob" } },resource: { schema: { kind: "string", minLength: 5, maxLength: 256 } },- origin: { schema: object({- kind: { schema: { kind: "literal", value: "build-file" } },- build: { schema: string }, path: { schema: string },- }), optional: true },size: { schema: integer },mediaType: { schema: mediaTypes === undefined ? string : { kind: "string", enum: mediaTypes } },});diff --git a/packages/protocol/src/build-id.ts b/packages/protocol/src/build-id.tsnew file mode 100644index 00000000..c6405d8e--- /dev/null+++ b/packages/protocol/src/build-id.ts@@ -0,0 +1,52 @@+function assert(condition: unknown, message: string): asserts condition {+ if (!condition) throw new Error(message);+}++const ORDERED_BUILD_ID = /^bld_(\d{8}T\d{9}Z)_([0-9A-Z]{10})$/u;++function timestampText(value: number): string {+ assert(Number.isSafeInteger(value) && value >= 0, "Build time must be a non-negative safe integer");+ return new Date(value).toISOString()+ .replace(/[-:.]/gu, "")+ .replace(/(\d{8}T\d{6})(\d{3})Z/u, "$1$2Z");+}++/**+ * Create the one public, chronologically sortable Build identity form.+ *+ * The nonce exists only to keep independent submissions in the same millisecond distinct. It is+ * not a content digest and has no reuse, equality or storage semantics.+ */+export function orderedBuildId(createdAt: number, nonce: string): string {+ assert(/^[0-9A-Z]{10}$/u.test(nonce), "Build nonce must be ten upper-case alphanumeric characters");+ return `bld_${timestampText(createdAt)}_${nonce}`;+}++/** Submission time carried by an ordered Build id, or undefined for a non-public/internal id. */+export function buildIdCreatedAt(value: string): number | undefined {+ const match = ORDERED_BUILD_ID.exec(value);+ if (match === null) return undefined;+ const raw = match[1]!;+ const iso = `${raw.slice(0, 4)}-${raw.slice(4, 6)}-${raw.slice(6, 8)}`+ + `T${raw.slice(9, 11)}:${raw.slice(11, 13)}:${raw.slice(13, 15)}.${raw.slice(15, 18)}Z`;+ const createdAt = Date.parse(iso);+ return Number.isFinite(createdAt) && timestampText(createdAt) === raw ? createdAt : undefined;+}++export function assertOrderedBuildId(value: string): void {+ assertBuildId(value);+ assert(buildIdCreatedAt(value) !== undefined,+ "Build id must contain its UTC submission time and a ten-character nonce");+}++/**+ * Runtime Build ids are opaque identities, but every durable Host currently+ * uses one id as one filesystem/S3 path segment. Keep that boundary explicit:+ * an id is never a path and the two dot directory entries are never Builds.+ */+export function assertBuildId(value: string): void {+ assert(value.length > 0 && value === value.trim(), "Build id must be a non-empty unpadded name");+ assert(value !== "." && value !== "..", "Build id must not be a dot directory");+ assert(!value.includes("/") && !value.includes("\\") && !value.includes("\0"),+ "Build id must be one path-free name");+}diff --git a/packages/protocol/src/build.ts b/packages/protocol/src/build.tsindex ed97df4b..11f1706f 100644--- a/packages/protocol/src/build.ts+++ b/packages/protocol/src/build.ts@@ -118,10 +118,10 @@ export type BuildRequest = {readonly targets: readonly BuildTarget[];};-export type BuildSelection = {+export type BuildOutputBinding = {readonly output: LogicalOutputId;- readonly candidate: CandidateId;readonly record: RecordId;+ readonly type: TypeRef;};export type ProducerStep = {@@ -141,7 +141,17 @@ export type BuildPlan = {readonly format: "hypit.plan@1";readonly steps: readonly ProducerStep[];readonly goals: readonly BuildGoal[];- readonly selections: readonly BuildSelection[];+ /** Every Logical Output reached by the selected execution, independent of how it was supplied. */+ readonly outputBindings: readonly BuildOutputBinding[];+};++/** The complete execution intent compiled from one `.svrun` source. */+export type RunGraph = {+ readonly format: "hypit.run-graph@1";+ readonly candidates: readonly Candidate[];+ readonly operations: readonly OperationNode[];+ readonly satisfactions: readonly Satisfaction[];+ readonly targets: readonly BuildTarget[];};export type LinkedProgram = {@@ -201,11 +211,12 @@ export type BuildDiagnostic = {/** Immutable finite program selected by one Author Graph plus one Run Graph. */export type BuildDefinition = {- readonly format: "hypit.build-definition@1";+ readonly format: "hypit.build-definition@2";readonly program: LinkedProgram;- readonly graph: CompiledGraph;- readonly request: BuildRequest;+ /** Selected zero-input values. Candidate identity has already served its planning purpose. */+ readonly initialRecords: readonly TypedRecord[];readonly plan: BuildPlan;+ readonly targets: readonly BuildTarget[];};type BuildFactBase = {@@ -241,9 +252,8 @@ export type BuildFact = ProducerAppliedFact | NeedAppliedFact | CommandFailedFacexport type BuildState = {readonly format: "hypit.build@1";readonly program: LinkedProgram;- readonly graph: CompiledGraph;- readonly request: BuildRequest;readonly plan: BuildPlan;+ readonly targets: readonly BuildTarget[];readonly status: "active" | "complete" | "failed";readonly records: readonly TypedRecord[];readonly steps: readonly StepState[];diff --git a/packages/protocol/src/index.ts b/packages/protocol/src/index.tsindex ebf89d95..a52aeab9 100644--- a/packages/protocol/src/index.ts+++ b/packages/protocol/src/index.ts@@ -1,4 +1,5 @@export * from "./canonical.js";+export * from "./build-id.js";export * from "./error.js";export { modulePackageAbi } from "./module.js";export { blobRefObjectSchema } from "./value.js";diff --git a/packages/protocol/src/value.ts b/packages/protocol/src/value.tsindex 935b69aa..a4767174 100644--- a/packages/protocol/src/value.ts+++ b/packages/protocol/src/value.ts@@ -12,12 +12,6 @@ export type BlobRef = {readonly kind: "blob";/** One admitted resource instance. Equal bytes admitted twice keep distinct identities. */readonly resource: ResourceId;- /** Exact durable origin carried only when a historical Build file enters a new execution. */- readonly origin?: {- readonly kind: "build-file";- readonly build: string;- readonly path: string;- };readonly size: number;readonly mediaType: string;};@@ -83,17 +77,6 @@ export function blobRefObjectSchema(mediaTypes?: readonly string[]): ValueSchemafields: {kind: { schema: { kind: "literal", value: "blob" } },resource: { schema: { kind: "string", minLength: 5 } },- origin: {- schema: {- kind: "object",- fields: {- kind: { schema: { kind: "literal", value: "build-file" } },- build: { schema: { kind: "string", minLength: 1 } },- path: { schema: { kind: "string", minLength: 1 } },- },- },- optional: true,- },size: { schema: { kind: "number", integer: true, minimum: 0 } },mediaType: {schema: mediaTypes === undefineddiff --git a/packages/protocol/test/canonical.test.ts b/packages/protocol/test/canonical.test.tsindex 086930ac..ca008ac3 100644--- a/packages/protocol/test/canonical.test.ts+++ b/packages/protocol/test/canonical.test.ts@@ -1,7 +1,15 @@import assert from "node:assert/strict";import test from "node:test";-import { canonicalize, canonicalStringify, isResourceId } from "@hypit/protocol";+import {+ assertBuildId,+ assertOrderedBuildId,+ buildIdCreatedAt,+ canonicalize,+ canonicalStringify,+ isResourceId,+ orderedBuildId,+} from "@hypit/protocol";test("canonical values have stable key order and preserve array order", () => {assert.equal(canonicalStringify({ b: 1, a: 2 }), '{"a":2,"b":1}');@@ -24,3 +32,20 @@ test("Resource ids retain their narrow execution-reference syntax", () => {assert.equal(isResourceId("fixture-resource"), false);assert.equal(isResourceId("md5:abc"), false);});++test("Build ids cannot address a parent or nested path", () => {+ assert.doesNotThrow(() => assertBuildId("build-19"));+ for (const value of ["..", ".", "episode/19", "episode\\19", " padded "]) {+ assert.throws(() => assertBuildId(value), /Build id/u);+ }+});++test("public Build ids carry sortable UTC submission time without content semantics", () => {+ const earlier = orderedBuildId(Date.parse("2026-09-02T10:20:30.123Z"), "0000000001");+ const later = orderedBuildId(Date.parse("2026-09-02T10:20:30.124Z"), "0000000000");+ assert.equal(earlier, "bld_20260902T102030123Z_0000000001");+ assert.equal(buildIdCreatedAt(earlier), Date.parse("2026-09-02T10:20:30.123Z"));+ assert.ok(earlier < later);+ assert.doesNotThrow(() => assertOrderedBuildId(earlier));+ assert.throws(() => assertOrderedBuildId("build-19"), /UTC submission time/u);+});diff --git a/packages/provider-hyperframes-aws-lambda/README.md b/packages/provider-hyperframes-aws-lambda/README.mdindex 2581d3bd..8a9593da 100644--- a/packages/provider-hyperframes-aws-lambda/README.md+++ b/packages/provider-hyperframes-aws-lambda/README.md@@ -26,6 +26,3 @@ dependency.The production client uses the AWS SDK default credential chain. No access key is accepted by thepackage configuration or written into Build state.--The opt-in live canary uses a fresh operation identity on every run and cleans its exact-render/site prefixes by default.diff --git a/packages/provider-hyperframes-aws-lambda/package.json b/packages/provider-hyperframes-aws-lambda/package.jsonindex be865b13..9268f7fe 100644--- a/packages/provider-hyperframes-aws-lambda/package.json+++ b/packages/provider-hyperframes-aws-lambda/package.json@@ -7,9 +7,6 @@"exports": {".": "./src/index.ts"},- "scripts": {- "canary": "node --import tsx test/live-canary.ts"- },"hypit": {"activation": "./src/activation.ts"},diff --git a/packages/provider-hyperframes-aws-lambda/test/live-canary.ts b/packages/provider-hyperframes-aws-lambda/test/live-canary.tsdeleted file mode 100644index 30675df0..00000000--- a/packages/provider-hyperframes-aws-lambda/test/live-canary.ts+++ /dev/null@@ -1,225 +0,0 @@-#!/usr/bin/env node-import assert from "node:assert/strict";-import { execFile } from "node:child_process";-import { randomUUID } from "node:crypto";-import { mkdtemp, rm, writeFile } from "node:fs/promises";-import { tmpdir } from "node:os";-import { join } from "node:path";-import { setTimeout as delay } from "node:timers/promises";-import { promisify } from "node:util";--import {- DeleteObjectsCommand,- ListObjectsV2Command,- S3Client,-} from "@aws-sdk/client-s3";-import {- sealComposition,- sealVisualTrack,-} from "@hypit/composition";-import {- EndpointRegistry,- MemoryResourceStore,-} from "@hypit/driver-node";-import type {- EndpointOutcome,- AsyncEndpoint,-} from "@hypit/endpoint-kit";-import { compileHyperframesDocument } from "@hypit/hyperframes";-import type { HyperframesDocument } from "@hypit/hyperframes";-import {- mediaTypes,- verifyRenderedVisual,-} from "@hypit/media";-import type { RenderedVisual } from "@hypit/media";-import { sealProgramSpace } from "@hypit/program-space";-import {- createAwsLambdaHyperframesProvider,-} from "@hypit/provider-hyperframes-aws-lambda";-import {- } from "@hypit/protocol";-import type {- CanonicalValue,- Need,-} from "@hypit/protocol";-import {- hyperframesVisualRequest,- renderHyperframesCapabilities,-} from "@hypit/render-hyperframes";--function requiredEnvironment(name: string): string {- const value = process.env[name];- if (value === undefined || value.length === 0) throw new Error(`set ${name}`);- return value;-}--const stateMachineArn = requiredEnvironment("HYPIT_HYPERFRAMES_STATE_MACHINE_ARN");-const bucketName = requiredEnvironment("HYPIT_HYPERFRAMES_BUCKET");-const region = requiredEnvironment("AWS_REGION");--const run = promisify(execFile);-const memorySizeMb = Number.parseInt(process.env.HYPIT_HYPERFRAMES_MEMORY_MB ?? "2048", 10);-assert(Number.isSafeInteger(memorySizeMb) && memorySizeMb >= 2_048, "invalid HyperFrames canary memory size");--function documentFixture(canaryId: string): HyperframesDocument {- const frameRate = { numerator: 24, denominator: 1 } as const;- const frameCount = 24;- const programSpace = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",- durationSec: 1,- frameRate,- });- const track = sealVisualTrack({ programSpaceId: "test-space",- visualIr: "hypit.visual-ir@1",- id: `hyperframes-aws-canary-${canaryId}`,- presents: [{- id: "card",- span: { startFrame: 0, endFrameExclusive: frameCount },- stacking: { order: 1, tieBreak: "card" },- elements: [{- id: "background",- order: 0,- kind: "box",- style: [- { name: "position", value: "absolute" },- { name: "inset", value: 0 },- { name: "background", value: "#261447" },- { name: "border-radius", value: "12px" },- ],- animation: {- keyframes: [- { atFrame: 0, style: [{ name: "opacity", value: 0.35 }] },- { atFrame: frameCount, easing: "linear", style: [{ name: "opacity", value: 1 }] },- ],- },- }],- }],- });- return compileHyperframesDocument(sealComposition({- id: `hyperframes-aws-canary-${canaryId}`,- canvas: { width: 160, height: 96, clearColor: "#000000" },- tracks: [track],- }), programSpace);-}--function requestNeed(document: HyperframesDocument, canaryId: string): Need {- const constraints = hyperframesVisualRequest(document);- return {- id: `need:hyperframes-aws-canary:${canaryId}`,- capability: renderHyperframesCapabilities.renderVisual,- returns: mediaTypes.renderedVisual,- constraints,- result: `record:hyperframes-aws-canary:${canaryId}`,- };-}--async function endpointFor(request: Need): Promise<AsyncEndpoint> {- const registry = new EndpointRegistry();- await createAwsLambdaHyperframesProvider({- instance: "hyperframes.aws-lambda.canary",- stateMachineArn,- bucketName,- quality: "draft",- targetChunkFrames: 12,- maxParallelChunks: 2,- defaultMemorySizeMb: memorySizeMb,- defaultConcurrency: 1,- pollIntervalMs: 2_000,- maxOperationMs: 10 * 60_000,- }).install(registry);- const resolution = registry.resolve(request);- assert.equal(resolution.status, "resolved");- assert.equal(resolution.registration.kind, "asynchronous");- return resolution.registration.endpoint;-}--async function deletePrefix(s3: S3Client, prefix: string): Promise<void> {- let continuationToken: string | undefined;- do {- const page = await s3.send(new ListObjectsV2Command({- Bucket: bucketName,- Prefix: prefix,- ...(continuationToken === undefined ? {} : { ContinuationToken: continuationToken }),- }));- const objects = (page.Contents ?? []).flatMap((item) => item.Key === undefined ? [] : [{ Key: item.Key }]);- if (objects.length > 0) {- await s3.send(new DeleteObjectsCommand({ Bucket: bucketName, Delete: { Objects: objects, Quiet: true } }));- }- continuationToken = page.IsTruncated === true ? page.NextContinuationToken : undefined;- } while (continuationToken !== undefined);-}--async function main(): Promise<void> {- const canaryId = process.env.HYPIT_HYPERFRAMES_CANARY_ID ?? randomUUID().slice(0, 16);- const document = documentFixture(canaryId);- const need = requestNeed(document, canaryId);- const endpoint = await endpointFor(need);- const resources = new MemoryResourceStore();- const commandId = `command:hyperframes-aws-canary:${canaryId}`;- const operation = `operation:hyperframes-aws-canary:${canaryId}`;- const context = {- command: { kind: "fulfill-need", id: commandId, need } as const,- need,- resources,- credentials: {},- operation,- };- let lastHandle: CanonicalValue | undefined;- const work = await mkdtemp(join(tmpdir(), "hypit-hyperframes-canary-"));- try {- let outcome: EndpointOutcome = await endpoint.start(context);- for (let polls = 0; outcome.status === "pending"; polls += 1) {- assert(polls < 300, "HyperFrames canary exceeded 300 polls");- lastHandle = outcome.handle;- const waitMs = Math.max(0, (outcome.wakeAt ?? Date.now()) - Date.now());- if (waitMs > 0) await delay(waitMs);- outcome = await endpoint.poll({ ...context, handle: outcome.handle });- }- if (outcome.status === "failed") {- throw new Error(`${outcome.failure.code}: ${outcome.failure.message}`);- }- assert.equal(outcome.status, "completed");- assert.equal(outcome.result.value.kind, "inline");- const visual = outcome.result.value.value as unknown as RenderedVisual;- verifyRenderedVisual(visual);- const bytes = await resources.get(visual.artifact.resource);- assert(bytes !== undefined && bytes.byteLength === visual.artifact.size);-- const output = join(work, "visual.mp4");- await writeFile(output, bytes);- const { stdout } = await run(process.env.HYPIT_CANARY_FFPROBE ?? "ffprobe", [- "-v", "error", "-count_frames", "-select_streams", "v:0",- "-show_entries", "stream=codec_name,nb_read_frames,width,height",- "-of", "json", output,- ], { timeout: 30_000, maxBuffer: 1024 * 1024 });- const probe = JSON.parse(stdout) as {- streams?: Array<{ codec_name?: string; nb_read_frames?: string; width?: number; height?: number }>;- };- assert.deepEqual(probe.streams, [{- codec_name: "h264",- width: 160,- height: 96,- nb_read_frames: "24",- }]);-- process.stdout.write(`${JSON.stringify({- canaryId,- stateMachineArn,- bucketName,- artifact: visual.artifact,- frameRate: visual.frameRate,- frameCount: visual.frameCount,- canvas: visual.canvas,- probe: probe.streams[0],- }, null, 2)}\n`);- } finally {- await rm(work, { recursive: true, force: true });- if (process.env.HYPIT_HYPERFRAMES_CANARY_KEEP !== "1" && lastHandle !== undefined) {- const handle = lastHandle as unknown as { executionName?: string; site?: { siteId?: string } };- const s3 = new S3Client({ region });- if (handle.executionName !== undefined) await deletePrefix(s3, `renders/${handle.executionName}/`);- if (handle.site?.siteId !== undefined) await deletePrefix(s3, `sites/${handle.site.siteId}/`);- }- }-}--await main();diff --git a/packages/provider-hyperframes-aws-lambda/test/provider.test.ts b/packages/provider-hyperframes-aws-lambda/test/provider.test.tsindex e4235dff..eca6011c 100644--- a/packages/provider-hyperframes-aws-lambda/test/provider.test.ts+++ b/packages/provider-hyperframes-aws-lambda/test/provider.test.ts@@ -263,7 +263,7 @@ test("one submission is polled and streams the output into the ResourceStore", aconst { client, state } = fakeClient();const { endpoint, registration } = await endpointFor(request, client);assert.equal(registration.scheduling?.resources.find((item) =>- item.id.startsWith("pool:"))?.maxActive, 2);+ item.id.startsWith("pool:"))?.limit, 2);const memory = new MemoryResourceStore();let streamed = 0;diff --git a/packages/provider-hyperframes-local/test/provider.test.ts b/packages/provider-hyperframes-local/test/provider.test.tsindex 059ad4cf..e8517654 100644--- a/packages/provider-hyperframes-local/test/provider.test.ts+++ b/packages/provider-hyperframes-local/test/provider.test.ts@@ -103,7 +103,7 @@ test("local HyperFrames Provider exposes one exact visual capability and two sep}]);const resolved = await handlerFor(requestNeed());assert.equal(resolved.registration.scheduling?.resources.find((item) =>- item.id.startsWith("pool:"))?.maxActive, 1,+ item.id.startsWith("pool:"))?.limit, 1,"Runtime request admission must remain separate from HyperFrames frame workers");});diff --git a/packages/provider-image-opencv-local/test/program.test.ts b/packages/provider-image-opencv-local/test/program.test.tsindex a8732176..aa305e40 100644--- a/packages/provider-image-opencv-local/test/program.test.ts+++ b/packages/provider-image-opencv-local/test/program.test.ts@@ -1,5 +1,5 @@import assert from "node:assert/strict";-import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";+import { mkdtemp, rm, writeFile } from "node:fs/promises";import { existsSync } from "node:fs";import { tmpdir } from "node:os";import { isAbsolute, join } from "node:path";@@ -52,11 +52,3 @@ test("an interpreter carrying another OpenCV major is a mismatch, not a failure"await rm(directory, { recursive: true, force: true });}});--test("the major versions the probe demands are the ones the packaged project installs", async () => {- const project = localOpenCvProgram(context()).installation?.commands[0]?.args.at(-2);- assert.ok(project);- const pyproject = await readFile(join(project, "pyproject.toml"), "utf8");- assert.match(pyproject, /"opencv-python-headless>=4\./u, "probe expects cv2 4.x");- assert.match(pyproject, /"numpy>=2\./u, "probe expects numpy 2.x");-});diff --git a/packages/provider-image-opencv-local/test/provider.test.ts b/packages/provider-image-opencv-local/test/provider.test.tsindex eec0ead5..4a6a25ab 100644--- a/packages/provider-image-opencv-local/test/provider.test.ts+++ b/packages/provider-image-opencv-local/test/provider.test.ts@@ -128,7 +128,6 @@ test("the local Provider returns only a new image BlobArtifact", {assert.equal(result.value.kind, "blob");assert.equal(result.value.mediaType, "image/png");assert.equal(await resources.has(result.value.resource), true);- assert.deepEqual(Object.keys(result.value).sort(), ["digest", "kind", "mediaType", "size"]);const output = await resources.get(result.value.resource);assert(output !== undefined);const encoded = Buffer.from(output);diff --git a/packages/provider-kie/README.md b/packages/provider-kie/README.mdindex 8bf8a0c1..9a50e0b4 100644--- a/packages/provider-kie/README.md+++ b/packages/provider-kie/README.md@@ -10,7 +10,7 @@ choose another model.It imports no exact-model package. Every supported Capability contributes one `KieRoute`: exactCapability, return Type, request compiler, media/count limits and result packer. All Routes share one-upload, admission, paid submission, checkpoint, polling and download state machine. Model mappings+upload, admission, paid submission, durable Operation polling and download state machine. Model mappingsgenerate eleven Routes; Background Removal contributes the twelfth.## Supported catalog@@ -96,25 +96,10 @@ Manifests actually imported by the author document; installing KIE does not add4. Successful result URLs are converted to short-lived download URLs, bounded while streaming,immediately admitted into that Build's working byte area, and removed from durableresult metadata.-5. The selected `BuildDispatchStore` owns shared Build capacity. This Provider contributes one KIE+5. The selected Runtime Execution Store owns shared Build capacity. This Provider contributes one KIEpool plus exact capability lanes and a conservative create-task interval; it does not introduce Redis or another source ofBuild truth.-The automated suite uses an adversarial fake KIE service. The credentialed smoke command is a paid-deployment test and is intentionally not run by the public repository test suite. It must be enabled-explicitly and keeps a stable Runtime directory under the operating system temporary directory so-an interrupted paid task can continue polling from its SQLite checkpoint:--```sh-HYPIT_KIE_LIVE=1 KIE_API_KEY=... pnpm smoke:kie-```--The default case is `gpt-image-2`. Set `HYPIT_KIE_SMOKE_CASES=all` or a comma-separated subset of-`gpt-image-2,nano-banana-2,seedream-5-lite,seedance-2-mini,minimax-h3,grok-imagine`.-Set `HYPIT_KIE_SMOKE_REFERENCE` to add the optional `gpt-image-2-edit` upload case; only use an asset-that is explicitly approved for external upload.--`KIE_BASE_URL` and `HYPIT_KIE_SMOKE_ROOT` are optional deployment overrides. The command prints-credit usage, the content digest and a local inspection copy, but never prints or persists the key.-A representative run of all six families and the optional upload case has passed. Generated-results are deployment evidence and are intentionally not committed as a dated transcript.+The automated suite uses an adversarial fake KIE service. It covers submission ambiguity,+continuation of accepted tasks, polling, bounded downloads and failures without spending money or+requiring deployment credentials.diff --git a/packages/provider-kie/src/mapping.ts b/packages/provider-kie/src/mapping.tsindex 365ea3de..bd10572e 100644--- a/packages/provider-kie/src/mapping.ts+++ b/packages/provider-kie/src/mapping.ts@@ -1,6 +1,11 @@import type { CapabilityRef, ModuleRef } from "@hypit/protocol";import type { GenerationWireMapping } from "@hypit/generation";+export type KieGenerationWireMapping = GenerationWireMapping & {+ /** Values advertised by the model vocabulary but refused by this KIE route. */+ readonly unsupportedPortValues?: Readonly<Record<string, readonly (string | number | boolean)[]>>;+};+/*** How KIE names each model's declared input ports.*@@ -95,7 +100,7 @@ const grokPreviewMapping: GenerationWireMapping = {},};-const gptImageMapping: GenerationWireMapping = {+const gptImageMapping: KieGenerationWireMapping = {capability: { module: GPT_IMAGE, name: "gpt-image-2" },result: "image",routes: [@@ -108,6 +113,9 @@ const gptImageMapping: GenerationWireMapping = {resolution: { as: "value", field: "resolution" },images: { as: "urlArray", field: "input_urls" },},+ unsupportedPortValues: {+ aspectRatio: ["4:3", "3:4", "4:5"],+ },};function nanoBananaMapping(model: string): GenerationWireMapping {@@ -143,7 +151,7 @@ const seedreamMapping: GenerationWireMapping = {},};-export const kieModelCatalog: readonly GenerationWireMapping[] = [+export const kieModelCatalog: readonly KieGenerationWireMapping[] = [seedanceMapping("seedance-2", "bytedance/seedance-2"),seedanceMapping("seedance-2-fast", "bytedance/seedance-2-fast"),seedanceMapping("seedance-2-mini", "bytedance/seedance-2-mini"),diff --git a/packages/provider-kie/src/provider.ts b/packages/provider-kie/src/provider.tsindex 01c8cfcf..91c821b6 100644--- a/packages/provider-kie/src/provider.ts+++ b/packages/provider-kie/src/provider.ts@@ -11,9 +11,7 @@ import type {BlobRef,CanonicalValue,ResourceId,- Need,} from "@hypit/protocol";-import type { GenerationRequest } from "@hypit/generation";import {defineEndpointPackage,wakeAfter,@@ -24,7 +22,6 @@ import type { ResourceStore, CredentialRef } from "@hypit/runtime";import {kieRouteForCapability,kieRoutes,- supportsKieGptImageRequest,verifyKieRoutes,} from "./routes.js";import type { KieTaskRequest } from "./routes.js";@@ -53,11 +50,9 @@ export type CreateKieProviderOptions = {};type KieHandle = {- readonly contract: "hypit.kie-operation@1";readonly taskId: string;readonly routeKey: string;readonly startedAt: number;- readonly polls: number;};class KieError extends Error {@@ -226,7 +221,7 @@ class KieClient {+ `Content-Type: ${artifact.mediaType}\r\n\r\n`,);const fields = encode(- `\r\n--${boundary}\r\nContent-Disposition: form-data; name="uploadPath"\r\n\r\nsvml/resources`+ `\r\n--${boundary}\r\nContent-Disposition: form-data; name="uploadPath"\r\n\r\nhypit/resources`+ `\r\n--${boundary}\r\nContent-Disposition: form-data; name="fileName"\r\n\r\n${fileName}`+ `\r\n--${boundary}--\r\n`,);@@ -418,13 +413,11 @@ function readHandle(value: CanonicalValue | undefined, context: EndpointPollCont}const handle = object(value, "KIE handle") as unknown as KieHandle;const route = kieRouteForCapability(context.need.capability);- if (handle.contract !== "hypit.kie-operation@1"- || typeof handle.taskId !== "string"+ if (typeof handle.taskId !== "string"|| route === undefined|| handle.routeKey !== route.key- || !Number.isSafeInteger(handle.startedAt)- || !Number.isSafeInteger(handle.polls)) {- throw new KieError("KIE_HANDLE_INVALID", "KIE handle does not match the regenerated Need");+ || !Number.isSafeInteger(handle.startedAt)) {+ throw new KieError("KIE_HANDLE_INVALID", "KIE handle does not match the current Need");}return handle;}@@ -464,11 +457,9 @@ function endpoint(options: {await options.gate.enter();const taskId = await options.client.createTask(task, key);const handle: KieHandle = {- contract: "hypit.kie-operation@1",taskId,routeKey: route.key,startedAt: options.now(),- polls: 0,};return wakeAfter(canonicalize(handle), options.pollIntervalMs, options.now(), {phase: "submitted",@@ -496,8 +487,7 @@ function endpoint(options: {const data = await options.client.taskInfo(handle.taskId, key);const state = data.state;if (state === "waiting" || state === "queuing" || state === "generating") {- const next = { ...handle, polls: handle.polls + 1 };- return wakeAfter(canonicalize(next), options.pollIntervalMs, options.now(), {+ return wakeAfter(canonicalize(handle), options.pollIntervalMs, options.now(), {phase: state,});}@@ -589,9 +579,7 @@ export function createKieProvider(config: CreateKieProviderOptions) {: { maxConcurrency: laneConcurrency[route.capability.name] }),lifecycle: "asynchronous" as const,endpoint: providerEndpoint,- ...(route.capability.module.name === "@hypit/gpt-image" ? {- supports: (need: Need) => supportsKieGptImageRequest(need.constraints as unknown as GenerationRequest),- } : {}),+ ...(route.supports === undefined ? {} : { supports: route.supports }),})),});}diff --git a/packages/provider-kie/src/routes.ts b/packages/provider-kie/src/routes.tsindex c132a129..d6472d0c 100644--- a/packages/provider-kie/src/routes.ts+++ b/packages/provider-kie/src/routes.ts@@ -10,11 +10,12 @@ import {sealGeneratedImageSet,sealGeneratedVideoSet,} from "@hypit/generation";-import type { GenerationArtifactUrlResolver, GenerationRequest, GenerationWireMapping } from "@hypit/generation";+import type { GenerationArtifactUrlResolver, GenerationRequest } from "@hypit/generation";import { canonicalize } from "@hypit/protocol";-import type { BlobRef, CanonicalValue, CapabilityRef, StoredValue, TypeRef } from "@hypit/protocol";+import type { BlobRef, CanonicalValue, CapabilityRef, Need, StoredValue, TypeRef } from "@hypit/protocol";import { kieModelCatalog, verifyKieModelCatalog } from "./mapping.js";+import type { KieGenerationWireMapping } from "./mapping.js";export type KieTaskRequest = {readonly model: string;@@ -27,6 +28,7 @@ export type KieRoute = {readonly returns: TypeRef;readonly media: "image" | "video";readonly maxResults: number;+ readonly supports?: (need: Need) => boolean;readonly compile: (constraints: CanonicalValue,resolve: GenerationArtifactUrlResolver,@@ -38,29 +40,37 @@ function capabilityKey(ref: CapabilityRef): string {return `${ref.module.name}@${ref.module.version}#${ref.name}`;}-export function supportsKieGptImageRequest(request: GenerationRequest): boolean {- if (request.ports.aspectRatio === undefined) return true;- const ratio = request.ports.aspectRatio[0];- // KIE's GPT Image 2 endpoints reject these ratios even though the model- // vocabulary advertises them. Refuse before upload or paid submission.- if (ratio === "4:3" || ratio === "3:4" || ratio === "4:5") {- return false;+function supportsKieGenerationRequest(+ mapping: KieGenerationWireMapping,+ request: GenerationRequest,+): boolean {+ for (const [port, unsupported] of Object.entries(mapping.unsupportedPortValues ?? {})) {+ const values = request.ports[port] ?? [];+ if (values.some((value) => (typeof value === "string" || typeof value === "number" || typeof value === "boolean")+ && unsupported.includes(value))) return false;}return true;}-function validateKieGptImageRequest(request: GenerationRequest): void {- if (!supportsKieGptImageRequest(request)) {- const ratio = request.ports.aspectRatio?.[0];- throw new Error(`KIE GPT Image 2 does not accept aspect ratio ${String(ratio)}; use auto, 1:1, 3:2, 2:3, 16:9, 9:16 or 21:9`);+function validateKieGenerationRequest(+ mapping: KieGenerationWireMapping,+ request: GenerationRequest,+): void {+ for (const [port, unsupported] of Object.entries(mapping.unsupportedPortValues ?? {})) {+ const value = request.ports[port]?.find((item) =>+ (typeof item === "string" || typeof item === "number" || typeof item === "boolean")+ && unsupported.includes(item));+ if (value !== undefined) {+ throw new Error(`KIE ${mapping.capability.name} does not accept ${port} ${String(value)}`);+ }}}-const kieGenerationMappings = kieModelCatalog.map((mapping) => {+const kieGenerationMappings: readonly (KieGenerationWireMapping & { readonly result: "image" | "video" })[] = kieModelCatalog.map((mapping) => {if (mapping.result === "audio") {throw new Error(`KIE route ${mapping.capability.name} declares unsupported audio output`);}- return mapping as GenerationWireMapping & { readonly result: "image" | "video" };+ return mapping as KieGenerationWireMapping & { readonly result: "image" | "video" };});const generationRoutes: readonly KieRoute[] = kieGenerationMappings.map((mapping) => ({@@ -69,9 +79,15 @@ const generationRoutes: readonly KieRoute[] = kieGenerationMappings.map((mappingreturns: mapping.result === "image" ? generationTypes.imageSet : generationTypes.videoSet,media: mapping.result,maxResults: mapping.result === "image" ? 16 : 8,+ ...(mapping.unsupportedPortValues === undefined ? {} : {+ supports: (need: Need) => supportsKieGenerationRequest(+ mapping,+ need.constraints as unknown as GenerationRequest,+ ),+ }),compile: async (constraints, resolve) => {const request = constraints as unknown as GenerationRequest;- if (mapping.capability.module.name === "@hypit/gpt-image") validateKieGptImageRequest(request);+ validateKieGenerationRequest(mapping, request);return await compileWireRequest(mapping, request, resolve);},packageResult: (artifacts) => ({diff --git a/packages/provider-kie/test/live-smoke.ts b/packages/provider-kie/test/live-smoke.tsdeleted file mode 100644index 7712ef9f..00000000--- a/packages/provider-kie/test/live-smoke.ts+++ /dev/null@@ -1,424 +0,0 @@-import { randomUUID } from "node:crypto";-import { mkdir, readFile, writeFile } from "node:fs/promises";-import { tmpdir } from "node:os";-import { join, resolve } from "node:path";-import { FileResourceStore } from "@hypit/resource-store-fs";-import { EnvironmentCredentialStore } from "@hypit/credential-store-env";-import { registerTypeValidatorFacets } from "@hypit/component-kit";-import {- createResolvedClosure,- defineBuild,- link,- sealBuildRequest,- sealCompiledGraph,- sealRecord,- start,-} from "@hypit/core";-import { narrativeManifest } from "@hypit/narrative";-import { mediaManifest } from "@hypit/media";-import {- generationComponent,- generationManifest,- verifyGeneratedImageSet,- verifyGeneratedVideoSet,-} from "@hypit/generation";-import {- gptImageComponent,- gptImageEndpoints,- gptImageManifest,- sealGptImage2Request,-} from "@hypit/gpt-image";-import {- grokImagineComponent,- grokImagineEndpoints,- grokImagineManifest,- sealGrokImagineRequest,-} from "@hypit/grok-imagine";-import { createLocalRuntime } from "@hypit/runtime-local";-import type { LocalBuildSubmission } from "@hypit/runtime-local";-import {- minimaxH3Component,- minimaxH3Endpoints,- minimaxH3Manifest,- sealMinimaxH3Request,-} from "@hypit/minimax-h3";-import type { ExactModelEndpoint, ExactModelModule } from "@hypit/model-kit";-import {- nanoBananaComponent,- nanoBananaEndpoints,- nanoBananaManifest,- sealNanoBananaRequest,-} from "@hypit/nano-banana";-import { createKieProvider } from "@hypit/provider-kie";-import type {- BlobRef,- CanonicalValue,- ModuleManifest,- TypedRecord,-} from "@hypit/protocol";-import { credentialRef } from "@hypit/runtime";-import { SqliteRuntimeState } from "@hypit/store-sqlite";-import {- sealSeedanceRequest,- seedanceComponent,- seedanceEndpoints,- seedanceManifest,-} from "@hypit/seedance";-import {- sealSeedreamRequest,- seedreamComponent,- seedreamEndpoints,- seedreamManifest,-} from "@hypit/seedream";-import { admitRecord, TypeValidatorRegistry } from "@hypit/validation";--type SmokeCase = {- readonly key: string;- readonly media: "image" | "video";- readonly endpoint: ExactModelEndpoint;- readonly manifest: ModuleManifest;- readonly component: ExactModelModule["component"];- readonly request: CanonicalValue;- readonly ids: {- readonly request: string;- readonly source: string;- readonly output: string;- readonly candidate: string;- readonly operation: string;- readonly need: string;- readonly result: string;- };-};--function assert(condition: unknown, message: string): asserts condition {- if (!condition) throw new Error(message);-}--function object(value: unknown, subject: string): Record<string, unknown> {- assert(value !== null && typeof value === "object" && !Array.isArray(value), `${subject} is not an object`);- return value as Record<string, unknown>;-}--function endpoint(value: ExactModelEndpoint | undefined, subject: string): ExactModelEndpoint {- assert(value !== undefined, `${subject} endpoint is unavailable`);- return value;-}--function apiBaseUrl(value: string): string {- const url = new URL(value);- assert(url.protocol === "https:" || url.hostname === "localhost", "KIE_BASE_URL must use HTTPS or localhost");- return url.href.replace(/\/$/u, "");-}--async function accountCredits(baseUrl: string, key: string): Promise<number> {- const response = await fetch(`${baseUrl}/api/v1/chat/credit`, {- method: "GET",- headers: { authorization: `Bearer ${key}` },- });- const text = await response.text();- if (!response.ok) throw new Error(`KIE credit check returned HTTP ${response.status}: ${text.slice(0, 300)}`);- const body = object(JSON.parse(text), "KIE credit response");- assert(body.code === 200 && typeof body.data === "number" && Number.isFinite(body.data),- `KIE credit response is invalid: ${text.slice(0, 300)}`);- return body.data;-}--function resultExtension(mediaType: string): string {- const known: Readonly<Record<string, string>> = {- "image/jpeg": ".jpg",- "image/png": ".png",- "image/webp": ".webp",- "video/mp4": ".mp4",- "video/quicktime": ".mov",- "video/webm": ".webm",- };- return known[mediaType] ?? ".bin";-}--function caseIds(key: string, media: "image" | "video"): SmokeCase["ids"] {- if (key === "gpt-image-2") {- return {- request: "request:gpt-image-2-live",- source: "@hypit/provider-kie/live-smoke/gpt-image-2@1",- output: "result:image",- candidate: "candidate:gpt-image-2",- operation: "operation:gpt-image-2",- need: "need:gpt-image-2",- result: "result:gpt-image-2",- };- }- return {- request: `request:${key}-live`,- source: `@hypit/provider-kie/live-smoke/${key}@1`,- output: `result:${key}`,- candidate: `candidate:${key}`,- operation: `operation:${key}`,- need: `need:${key}`,- result: `result:${key}:${media}`,- };-}--function referenceMediaType(path: string): string {- const lower = path.toLowerCase();- if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";- if (lower.endsWith(".webp")) return "image/webp";- if (lower.endsWith(".png")) return "image/png";- throw new Error("HYPIT_KIE_SMOKE_REFERENCE must be a PNG, JPEG or WebP image");-}--async function smokeCases(root: string): Promise<readonly SmokeCase[]> {- const productPrompt = "A single translucent glass sphere on a matte cobalt blue background, centered studio product photograph, soft shadow, no text.";- const motionPrompt = "A translucent glass sphere slowly rolls across a matte cobalt blue studio floor, locked camera, soft shadow, no text.";- const cases: Array<Omit<SmokeCase, "ids">> = [- {- key: "gpt-image-2",- media: "image",- endpoint: endpoint(gptImageEndpoints.image, "GPT Image 2"),- manifest: gptImageManifest,- component: gptImageComponent,- request: sealGptImage2Request({- prompt: [productPrompt],- aspectRatio: ["1:1"],- }) as unknown as CanonicalValue,- },- {- key: "nano-banana-2",- media: "image",- endpoint: endpoint(nanoBananaEndpoints.v2, "Nano Banana 2"),- manifest: nanoBananaManifest,- component: nanoBananaComponent,- request: sealNanoBananaRequest("nano-banana-2", {- prompt: [productPrompt],- aspectRatio: ["1:1"],- resolution: ["1K"],- outputFormat: ["png"],- }) as unknown as CanonicalValue,- },- {- key: "seedream-5-lite",- media: "image",- endpoint: endpoint(seedreamEndpoints.image, "Seedream 5 Lite"),- manifest: seedreamManifest,- component: seedreamComponent,- request: sealSeedreamRequest({- prompt: [productPrompt],- aspectRatio: ["1:1"],- quality: ["basic"],- outputFormat: ["png"],- nsfwCheck: [true],- }) as unknown as CanonicalValue,- },- {- key: "seedance-2-mini",- media: "video",- endpoint: endpoint(seedanceEndpoints.mini, "Seedance 2 Mini"),- manifest: seedanceManifest,- component: seedanceComponent,- request: sealSeedanceRequest("seedance-2-mini", {- prompt: [motionPrompt],- resolution: ["480p"],- aspectRatio: ["1:1"],- duration: [4],- generateAudio: [false],- webSearch: [false],- }) as unknown as CanonicalValue,- },- {- key: "minimax-h3",- media: "video",- endpoint: endpoint(minimaxH3Endpoints.video, "MiniMax H3"),- manifest: minimaxH3Manifest,- component: minimaxH3Component,- request: sealMinimaxH3Request({- prompt: [motionPrompt],- duration: [6],- aspectRatio: ["16:9"],- }) as unknown as CanonicalValue,- },- {- key: "grok-imagine",- media: "video",- endpoint: endpoint(grokImagineEndpoints.video, "Grok Imagine"),- manifest: grokImagineManifest,- component: grokImagineComponent,- request: sealGrokImagineRequest("grok-imagine-video", {- prompt: [motionPrompt],- aspectRatio: ["2:3"],- resolution: ["480p"],- duration: [6],- }) as unknown as CanonicalValue,- },- ];- const referencePath = process.env.HYPIT_KIE_SMOKE_REFERENCE;- if (referencePath !== undefined) {- const absolute = resolve(referencePath);- const store = new FileResourceStore(join(root, ".svml", "artifacts"));- const reference = await store.put(await readFile(absolute), referenceMediaType(absolute));- cases.push({- key: "gpt-image-2-edit",- media: "image",- endpoint: endpoint(gptImageEndpoints.image, "GPT Image 2 edit"),- manifest: gptImageManifest,- component: gptImageComponent,- request: sealGptImage2Request({- prompt: ["Keep the glass sphere unchanged and replace the blue background with a matte warm orange studio background, no text."],- aspectRatio: ["1:1"],- images: [{ role: "image", artifact: reference }],- }) as unknown as CanonicalValue,- });- }- return cases.map((item) => ({ ...item, ids: caseIds(item.key, item.media) }));-}--function selectCases(cases: readonly SmokeCase[]): readonly SmokeCase[] {- const requested = process.env.HYPIT_KIE_SMOKE_CASES ?? "gpt-image-2";- if (requested === "all") return cases;- const keys = requested.split(",").map((item) => item.trim()).filter((item) => item.length > 0);- assert(keys.length > 0, "HYPIT_KIE_SMOKE_CASES selected no cases");- const available = new Map(cases.map((item) => [item.key, item]));- return keys.map((key) => {- const item = available.get(key);- assert(item !== undefined, `unknown KIE smoke case ${key}; choose ${[...available.keys()].join(", ")}, or all`);- return item;- });-}--async function createBuild(item: SmokeCase): Promise<ReturnType<typeof start>> {- const closure = createResolvedClosure([mediaManifest, narrativeManifest, generationManifest, item.manifest]);- const validators = new TypeValidatorRegistry();- registerTypeValidatorFacets(validators, generationComponent.validators);- registerTypeValidatorFacets(validators, item.component.validators);- const draft = sealRecord({- id: item.ids.request,- type: item.endpoint.requestType,- value: { kind: "inline", value: item.request },- });- const authored = await admitRecord(closure, draft, validators);- const program = link(closure, [authored]);- const graph = sealCompiledGraph({- outputs: [{- id: item.ids.output,- type: item.endpoint.returns,- primary: item.ids.candidate,- }],- candidates: [{- id: item.ids.candidate,- type: item.endpoint.returns,- root: { kind: "operation", result: { kind: "operation-result", operation: item.ids.operation } },- }],- operations: [{- id: item.ids.operation,- producer: item.endpoint.producer,- inputs: { request: { kind: "record", id: authored.id } },- result: {- kind: "need",- name: "generation",- id: item.ids.need,- record: item.ids.result,- },- }],- });- return start(program, graph, sealBuildRequest({- targets: [{ output: item.ids.output }],- }));-}--function generatedArtifact(item: SmokeCase, records: readonly TypedRecord[]): BlobRef {- const record = records.find((candidate) => candidate.id === item.ids.result);- assert(record !== undefined, `completed ${item.key} Build has no generated Record`);- assert(record.value.kind === "inline", `${item.key} generated Record is not inline`);- if (item.media === "image") verifyGeneratedImageSet(record.value.value);- else verifyGeneratedVideoSet(record.value.value);- const product = object(record.value.value, item.media === "image" ? "GeneratedImageSet" : "GeneratedVideoSet");- const artifacts = product[item.media === "image" ? "images" : "videos"];- assert(Array.isArray(artifacts) && artifacts.length > 0, `${item.key} generated Product has no artifacts`);- const first = object(artifacts[0], `${item.key} generated artifact`);- assert(first.kind === "blob" && typeof first.resource === "string"- && typeof first.size === "number" && typeof first.mediaType === "string", `${item.key} BlobRef is invalid`);- return first as unknown as BlobRef;-}--async function inspectArtifact(root: string, item: SmokeCase, artifact: BlobRef): Promise<string> {- const artifactPath = join(root, ".svml", "artifacts", "resources", artifact.resource);- const inspectPath = join(root, `${item.key}-live${resultExtension(artifact.mediaType)}`);- await writeFile(inspectPath, await readFile(artifactPath), { flag: "w" });- return inspectPath;-}--function failureMessage(item: SmokeCase, build: LocalBuildSubmission): string {- const diagnostic = build.state.diagnostics.map((entry) => `${entry.code}: ${entry.message}`).join("; ");- return `${item.key} KIE smoke Build ${build.status}: ${diagnostic || build.dispatch.reason || "no diagnostic"}`;-}--async function main(): Promise<void> {- assert(process.env.HYPIT_KIE_LIVE === "1",- "KIE live smoke is paid and opt-in; set HYPIT_KIE_LIVE=1 explicitly");- const key = process.env.KIE_API_KEY;- assert(key !== undefined && key.length > 0, "KIE_API_KEY is required");- const baseUrl = apiBaseUrl(process.env.KIE_BASE_URL ?? "https://api.kie.ai");- const root = resolve(process.env.HYPIT_KIE_SMOKE_ROOT ?? join(tmpdir(), "hypit-kie-live"));- await mkdir(root, { recursive: true });- const selected = selectCases(await smokeCases(root));- console.log(`KIE smoke cases: ${selected.map((item) => item.key).join(", ")}`);- console.log(`KIE smoke Runtime root: ${root}`);-- const provider = createKieProvider({- instance: "kie.live-smoke",- apiBaseUrl: baseUrl,- apiKey: credentialRef("env", "KIE_API_KEY"),- defaultConcurrency: 1,- pollIntervalMs: 3_000,- });- const state = new SqliteRuntimeState(join(root, ".hypit", "runtime.sqlite"));- const runtime = await createLocalRuntime({- buildStore: state.builds,- buildCatalog: state.catalog,- operationStore: state.operations,- dispatchStore: state.dispatch,- resourceStore: new FileResourceStore(join(root, ".hypit", "artifacts")),- credentialStore: new EnvironmentCredentialStore(),- components: [- generationComponent,- ...[...new Map(selected.map((item) => [item.manifest.name, item.component])).values()],- ],- endpoints: [provider],- close: () => state.close(),- });- const failures: string[] = [];- const workerAbort = new AbortController();- const workerRun = runtime.work({- idlePollMs: 100,- signal: workerAbort.signal,- });- try {- for (const item of selected) {- const before = await accountCredits(baseUrl, key);- console.log(`[${item.key}] credits before: ${before}`);- try {- const state = await createBuild(item);- const build = await runtime.build(- { id: `bld_${randomUUID()}`, definition: defineBuild(state.program, state.graph, state.request) },- { follow: true, pollIntervalMs: 1_000, maxWaitMs: 20 * 60_000 },- );- if (build.status !== "complete") throw new Error(failureMessage(item, build));- const artifact = generatedArtifact(item, build.state.records);- const inspectPath = await inspectArtifact(root, item, artifact);- console.log(`[${item.key}] artifact: ${artifact.resource}`);- console.log(`[${item.key}] inspection copy: ${inspectPath}`);- } catch (error) {- const message = error instanceof Error ? error.message : String(error);- failures.push(`${item.key}: ${message}`);- console.error(`[${item.key}] FAILED: ${message}`);- }- const after = await accountCredits(baseUrl, key);- console.log(`[${item.key}] credits after: ${after}; consumed: ${before - after}`);- }- } finally {- workerAbort.abort();- await workerRun;- await runtime.close();- }- if (failures.length > 0) throw new Error(`KIE live smoke failures:\n${failures.join("\n")}`);-}--await main();diff --git a/packages/provider-kie/test/models.test.ts b/packages/provider-kie/test/models.test.tsindex 3bd37ac1..6bc35dee 100644--- a/packages/provider-kie/test/models.test.ts+++ b/packages/provider-kie/test/models.test.ts@@ -1,45 +1,34 @@import assert from "node:assert/strict";import test from "node:test";-import { videoContractManifests } from "../../../test/support/video-domain.js";-import { createResolvedClosure } from "@hypit/core";--import { verifyGraphFragment } from "@hypit/elaborator";import { MemoryResourceStore } from "@hypit/driver-node";import {assertMappingCoversPorts,compileWireRequest,- generationManifest,} from "@hypit/generation";import type { GenerationPortTable } from "@hypit/generation";import {gptImageDefinition,- gptImageManifest,sealGptImage2Request,} from "@hypit/gpt-image";import {grokImagineDefinition,- grokImagineManifest,sealGrokImagineRequest,} from "@hypit/grok-imagine";import {minimaxH3Definition,- minimaxH3Manifest,sealMinimaxH3Request,} from "@hypit/minimax-h3";import {nanoBananaDefinition,- nanoBananaManifest,sealNanoBananaRequest,} from "@hypit/nano-banana";import { kieModelCatalog } from "@hypit/provider-kie";-import { seedanceDefinition, seedanceManifest, seedancePorts, sealSeedanceRequest } from "@hypit/seedance";+import { seedanceDefinition, sealSeedanceRequest } from "@hypit/seedance";import {seedreamDefinition,- seedreamManifest,sealSeedreamRequest,} from "@hypit/seedream";-import type { CapabilityRef, LinkedProgram } from "@hypit/protocol";-import { textManifest } from "@hypit/text";+import type { CapabilityRef } from "@hypit/protocol";/*** Every exact model this repository ships, paired with the Capability it publishes.@@ -58,25 +47,6 @@ function capabilityKey(ref: CapabilityRef): string {const upload = async (artifact: { readonly resource: string }) => `https://upload.test/${artifact.resource}`;-test("the selected KIE release is six exact model families and no Grok image capability", () => {- assert.equal(kieModelCatalog.length, 11);- assert.equal(- kieModelCatalog.some((item) => item.capability.name.startsWith("grok-") && item.result === "image"),- false,- );- assert.deepEqual(- [...new Set(kieModelCatalog.map((item) => item.capability.module.name))].sort(),- [- "@hypit/gpt-image",- "@hypit/grok-imagine",- "@hypit/minimax-h3",- "@hypit/nano-banana",- "@hypit/seedance",- "@hypit/seedream",- ],- );-});-/*** The check the old hand-written translators could not perform. Forgetting a* reference role or an item field used to surface only after paid generation@@ -93,58 +63,6 @@ test("the KIE mapping covers every port every exact model declares", () => {}});-test("dropping one reference modality from a mapping fails coverage before any spend", () => {- const seedance = kieModelCatalog.find((item) => item.capability.name === "seedance-2-mini");- assert.ok(seedance);- const { referenceAudio: _dropped, ...withoutAudio } = seedance.fields;- assert.throws(- () => assertMappingCoversPorts(seedancePorts["seedance-2-mini"], { ...seedance, fields: withoutAudio }),- /does not cover port referenceAudio/u,- );-});--test("all model manifests close over the shared generation contract and every Fragment verifies", () => {- const definitions = [- seedanceDefinition,- minimaxH3Definition,- grokImagineDefinition,- gptImageDefinition,- nanoBananaDefinition,- seedreamDefinition,- ];- const closure = createResolvedClosure([- ...videoContractManifests,- textManifest,- generationManifest,- seedanceManifest,- minimaxH3Manifest,- grokImagineManifest,- gptImageManifest,- nanoBananaManifest,- seedreamManifest,- ]);- const program: LinkedProgram = {- closure,- records: [],- };- definitions.forEach((definition) => {- Object.values(definition.endpoints).forEach((endpoint) => verifyGraphFragment(program, endpoint.fragment));- });-});--test("Seedream safety policy remains explicit author content", () => {- const base = {- prompt: ["A fashion editorial."],- aspectRatio: ["3:4"],- quality: ["basic"],- outputFormat: ["png"],- };- const unchecked = sealSeedreamRequest({ ...base, nsfwCheck: [false] });- const checked = sealSeedreamRequest({ ...base, nsfwCheck: [true] });- assert.deepEqual(unchecked.ports.nsfwCheck, [false]);- assert.deepEqual(checked.ports.nsfwCheck, [true]);-});-test("all eleven exact capabilities route to their documented KIE model slug", async () => {const store = new MemoryResourceStore();const image = await store.put(new Uint8Array([1]), "image/png");diff --git a/packages/provider-kie/test/provider.test.ts b/packages/provider-kie/test/provider.test.tsindex 5d68f793..4ac407b7 100644--- a/packages/provider-kie/test/provider.test.ts+++ b/packages/provider-kie/test/provider.test.ts@@ -62,7 +62,6 @@ test("all KIE capabilities share one asynchronous task engine and differ only bydefaultConcurrency: 8,laneConcurrency: { "seedance-2-mini": 4 },});- assert.equal(provider.offers.length, 12);const registry = new EndpointRegistry();await provider.install(registry);const seed = need(sealSeedanceRequest("seedance-2-mini", {@@ -81,8 +80,8 @@ test("all KIE capabilities share one asynchronous task engine and differ only byassert.deepEqual(seedResolution.registration.scheduling, {queue: { pool: "kie.default", lane: "seedance-2-mini" },resources: [- { id: "pool:kie.default", maxActive: 8, maxInFlight: 8 },- { id: "lane:kie.default/seedance-2-mini", maxActive: 4, maxInFlight: 4 },+ { id: "pool:kie.default", limit: 8 },+ { id: "lane:kie.default/seedance-2-mini", limit: 4 },],});});@@ -111,6 +110,8 @@ test("KIE uploads referenced resources, polls one task, and persists generated bfor await (const chunk of init?.body as unknown as AsyncIterable<Uint8Array>) chunks.push(chunk);const multipart = Buffer.concat(chunks).toString("latin1");assert.match(multipart, /name="fileName"\r\n\r\nres_[a-zA-Z0-9-]+\.png/u);+ assert.match(multipart, /name="uploadPath"\r\n\r\nhypit\/resources/u);+ assert.doesNotMatch(multipart, /svml\/resources/u);assert.ok(Buffer.concat(chunks).includes(Buffer.from([1, 2, 3])));return Response.json({success: true,@@ -177,7 +178,7 @@ test("KIE uploads referenced resources, polls one task, and persists generated bassert.equal(await resources.has(videos[0]!.resource as `res_${string}`), true);});-test("KIE fulfills generic Background Removal with the documented Recraft wire contract", async () => {+test("KIE fulfills generic Background Removal with the documented Recraft wire mapping", async () => {const resources = new MemoryResourceStore();const source = await resources.put(new Uint8Array([1, 2, 3, 4]), "image/png");const request = removeBackgroundNeed(backgroundRemovalRequest(source) as unknown as CanonicalValue);diff --git a/packages/ranking/test/ranking.test.ts b/packages/ranking/test/ranking.test.tsindex ee9f8821..12fbf0d2 100644--- a/packages/ranking/test/ranking.test.ts+++ b/packages/ranking/test/ranking.test.ts@@ -498,7 +498,7 @@ test("visual and sound event plans share exact phase frames while absent sound sassert.deepEqual(audio.clips.map((clip) => clip.gain), [0.8, 0.6, 0.8, 0.6]);});-test("each component owns a distinct event law and repeated lowering is canonical", () => {+test("each component owns a distinct event law", () => {const tierOwner = header("tier-board", "tier-events");const tierItems = [tierSpec("direct", "s"), tierSpec("drop", "a", "drop")];const tier = decodeTierBoardStyle(recipe("ranking.tier", { rows: [{ id: "s", label: "S", color: "#ef4444" }, { id: "a", label: "A", color: "#22c55e" }] }), font).style;@@ -510,12 +510,6 @@ test("each component owns a distinct event law and repeated lowering is canonicaconst top = decodeTopThreeStyle(recipe("ranking.top"), font).style;assert.deepEqual(buildTopThreeSoundEvents(schedule(topOwner, topItems), top, specs(topOwner, topItems)).events.map((item) => item.kind), ["appear"]);- const columnOwner = header("column", "deterministic");- const columnItems = [columnSpec("one", 3)];- const columnStyle = decodeColumnStyle(recipe("ranking.column"), font).style;- let set = appendColumnItem(createColumnItemSet(), columnItems[0]!);- const program = buildColumnProgram(columnOwner, canvas, frame, columnSchedule(columnOwner, columnItems, { one: early }), columnStyle, set);- assert.deepEqual(renderColumn(space, program), renderColumn(space, program));});test("all three author Surfaces preserve explicit semantic, spatial, font, image and optional sound graph edges", async () => {diff --git a/packages/reference-video-tools/README.md b/packages/reference-video-tools/README.mdindex a07c6993..cb4ce2ed 100644--- a/packages/reference-video-tools/README.md+++ b/packages/reference-video-tools/README.md@@ -1,141 +1,82 @@# `@hypit/reference-video-tools`-CLI tools for reconstructing a reference video with Hypit.--The package exposes reference-observation, vocabulary/gate, rendering, review, route-state,-revision-state and variant-expansion CLI subcommands, including `list_svml_packages`, `prepare_reference`,-`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-`.hypit/routes/<route-id>/state.json` or `.hypit/revisions/<revision-id>/state.json`; revision requests-live beside their state as `request.json`. Machine check reports are immutable, content-addressed-files under `.hypit/evidence/<digest>/`, while same-named root files are only latest-result views.-Commands that persist a report return its immutable path as `evidence`; state checkpoints should use-that path rather than reconstructing a root filename.--For a completed project change, `revision_state --action start|read|checkpoint|reconcile` stores a-small atomic current snapshot plus revision-scoped history. Revision edits Source/Recipe/Run and reruns-deterministic gates; it does not invoke a VLM/observer or perform visual review. The project may be-handed in as an already completed directory: after its baseline gates pass, Revision can start-without a parent reconstruction or description route state. A completed child from variant expansion-starts Revision with `--parent-route variant`; its original batch `allowed_changes` and `variant_check`-apply only to initial production, not to the later user-authorized edit.--For a validated source project that needs independent derivatives, `variant_state` stores the atomic-batch snapshot and base-project locator, `variant_init` copies the authored project without generated-results or secrets, and `variant_check` enforces the declared file scope plus the deterministic-package, Cue, graph, coverage and playback gates. Variant checking performs no render or visual-review. A paid Build remains a separate, explicitly approved action.--`--observer` on `prepare_reference` chooses who reads the reference, once per reference:--- `gemini` uploads the shot clips and the whole video to the configured Gemini backend at a fixed- temperature of `1.0`. With `HYPIT_GEMINI_PROVIDER=auto` (the default), it uses HypiHub when- `HYPIHUB_API_KEY` is set and otherwise uses Vertex with `GOOGLE_CLOUD_PROJECT` and- `GOOGLE_APPLICATION_CREDENTIALS_JSON`. If the configured key cannot reach the selected model,- get a HypiHub key at https://hypit.ai or use `agent`.-- `agent` reaches no Provider. `prepare_reference` and `observe_reference` return each observation as- a task carrying its prompt and the pictures to answer it from — one tile of evenly sampled frames- per shot, the storyboard for the whole reference — and the calling agent answers them with- `record_observation`.--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:+Direct tools for understanding a reference video and inspecting or previewing a Hypit project.++The package does not own a production workflow. It has no route/revision/variant state machine, no+checkpoint or recovery cursor, no content-addressed evidence directory, and no aggregate approval+state. Calling a command performs that command. It does not silently advance another process.++The useful outputs are ordinary content:++- prepared reference media, shots and transcript under `.hypit/reference-video-tools/`;+- reference observations and explicit comparison/review logs;+- requested stills, clips and package previews;+- direct JSON reports about vocabulary, package loading, Script Cues, graph tracing and realized+ browser layout.++These files can be opened, named, copied or removed directly. A repeated comparison or review is a+new explicit observation; it is not suppressed by comparing file hashes.++## Commands```bashhypit-reference-video-tools list_svml_packages-hypit-reference-video-tools prepare_reference --video-path ./reference.mp4-hypit-reference-video-tools prepare_reference --video-path ./reference.mp4 --redo people-hypit-reference-video-tools prepare_reference --video-path ./reference.mp4 --redo transcript+hypit-reference-video-tools prepare_reference --video-path ./reference.mp4 --observer agenthypit-reference-video-tools observe_reference --reference-id <reference-id>-hypit-reference-video-tools observe_reference --reference-id <reference-id> --shot-id shot-007-hypit-reference-video-tools observe_reference --reference-id <reference-id> --shot-id shot-007 --question "How thick is the outline on the caption words?"-hypit-reference-video-tools observe_reference --reference-id <reference-id> --shot-id shot-007 --reobserve+hypit-reference-video-tools record_observation --reference-id <reference-id> --key <key> --text-file ./answer.mdhypit-reference-video-tools inspect_svml_vocabulary --package @hypit/media-track --tag Track-hypit-reference-video-tools compare_reconstruction --reference-id <reference-id> --shot-id shot-007 --image ./rendered.png-hypit-reference-video-tools variant_state --action discover --project-root ./projects/base-hypit-reference-video-tools variant_state --action start --project-root ./projects/base --output-root ./projects/base-variants/<batch-id> --count 100-hypit-reference-video-tools variant_init --project-root ./projects/base --output-root ./projects/base-variants/<batch-id> --slate ./slate.json-hypit-reference-video-tools variant_check --run ./projects/base-variants/<batch-id>/001-example/build.svrun+hypit-reference-video-tools validate_local_author_packages --run ./build.svrun+hypit-reference-video-tools validate_script_cues --run ./build.svrun+hypit-reference-video-tools preview_check ./build.svrun+hypit-reference-video-tools layout_check --run ./build.svrun+hypit-reference-video-tools render_element ./build.svrun --element title --segment intro --out ./title.mp4+hypit-reference-video-tools compare_reconstruction --reference-id <reference-id> --run ./build.svrun --segment intro --video ./title.mp4 --element title+hypit-reference-video-tools review_element --run ./build.svrun --element title --segment intro --video ./title.mp4 --intent-file ./title-intent.md+hypit-reference-video-tools reconstruction_check ./build.svrun --reference-id <reference-id>+hypit-reference-video-tools authoring_check ./build.svrun```-For automation, every command also accepts `--input '{"...":"..."}'` with the complete JSON input-object. This is useful when the calling agent already has a structured request.--`list_svml_packages` reports every installed package that declares an activation, with the Surface-tags it registers. `inspect_svml_vocabulary` reads packages you can already name, and the Build CLI-is deliberately unable to scan a directory, so this is how a caller finds out what vocabulary exists-instead of working from memory.--`prepare_reference` requires a local video path and stores derived media under the checkout's-gitignored `.hypit/reference-video-tools/` directory, which is where every other command reads it-from whichever directory it is run in. It produces four full-reference observations: `people_and_product`,-`voices`, `persistent_systems` — the on-screen text and graphic systems that continue or recur across-the whole video, each one's lifetime, and whether its appearance ever changes — and `places`: how-many locations the video was shot in, which camera positions appear in each, which parts of the video-use each one, and each position described in enough detail to draw from the words alone. Without `--redo`, completed stages are reused. Use `--redo media` to rebuild shot media and-clear derived observations, `--redo transcript` to measure the words again, or `--redo people`, `--redo voices`, `--redo systems`, `--redo places`, or `--redo all` to-rerun only the selected full-reference stages.--It also produces `transcript`: the verbatim speech of the whole reference with a start and an end for-every single word. Placing an on-screen text reveal against the line that triggers it needs the time-of the word, not of the sentence around it, and that question comes up in every reconstruction. The-speech audio is extracted to `speech.wav` beside the shot media and measured by the local WhisperX-Provider in `@hypit/provider-whisperx-local`, which answers a loopback service on-`http://127.0.0.1:8765`; start the selected managed service with `hypit runtime up`.-The result reports `status`, `transcript_ref` and `word_count`, and the words themselves live in-`transcript.json` as passages, each with a `words` array of `{ text, start_seconds, end_seconds, score }`.-The transcript is deterministic local evidence rather than an observation: it is never written to the-observation cache and nothing about it is sent to Gemini. A machine with no WhisperX service running-reports `status: "unavailable"` with the reason and prepares everything else.--`observe_reference` observes every unfinished shot, or only the shots named by `--shot-id`. Each shot-produces three observations — `visual` (base picture, covering content, continuity, whether the frame-is a depicted scene or a flat designed field, and each framed element's inner picture separately from-its frame), `text_appearance` (typeface, weight, size, spacing, colour, stroke, shadow, glow,-per-word emphasis, position and entry of drawn text), and `audio`. The picture observation also-states whether the picture moves and how, separating camera movement from movement within it, since a-held still and a moving shot are reconstructed differently. Each cut adds one `continuity`-observation covering both whether the two shots are one continuous camera shot and whether an overlay-continues across the boundary. The preceding tail frame, audio tail and full-reference context are-attached automatically. Completed observations are reused; `--reobserve` is the only way to run a-completed one again.--Shots are never shorter than one second: a fragment below that is merged into the shot before it,-because clips that short carry no evidence and the model rejects them outright.--`HYPIT_REFERENCE_CONCURRENCY` and `HYPIT_REFERENCE_LAUNCH_GAP_MS` set how fast requests are issued,-defaulting to four at a time with a 1.5 second gap. They describe the quota behind the credentials-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 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-is which, what was built, or how. `--question` narrows it to one region of the picture and nothing-else. Results are not cached, because the rendered side changes on every iteration.--`unresolved` lists the keys of observations that failed. It is not a judgement about evidence-quality: a complete observation that says "unclear" is still complete.--Gemini uses `HYPIT_GEMINI_PROVIDER=auto|hypihub|vertex` to select its backend. The backends are-provided by `@hypit/provider-hypihub` and `@hypit/provider-vertex`. HypiHub uses-`HYPIHUB_API_KEY` and optional `HYPIHUB_BASE_URL` (default `https://hypit.ai`); Vertex uses the-existing `GOOGLE_CLOUD_PROJECT`, `GOOGLE_APPLICATION_CREDENTIALS_JSON` and optional-`GOOGLE_CLOUD_LOCATION`. The model defaults to `gemini-3.1-pro-preview`. A missing or insufficient-user key should be resolved by obtaining a HypiHub key at https://hypit.ai, not by changing Source.+Every command prints one JSON result. Commands also accept `--input '{...}'` when structured input is+more convenient. Batch forms read JSON arrays from files for observations, comparisons, renders,+reviews and layout decisions.++## Reference preparation++`prepare_reference` accepts a local path or a supported video URL. It extracts bounded shot clips,+representative frames, a storyboard, speech audio and a word-timed transcript. The returned reference+id contains the source filename, byte length and modification time so it is inspectable without a+lookup table.++`--observer gemini` uses HypiHub or Vertex according to the configured provider. `--observer agent`+calls no visual provider; it returns observation tasks with local pictures and transcript context for+the calling agent to answer through `record_observation`.++Prepared stages are reused until the caller explicitly asks for `--redo ...` or `--reobserve`. This+is ordinary working data for one reference, not Build history.++## Inspection and review++`inspect_svml_vocabulary` reports the public Surfaces of packages the caller names.+`inspect_visual_schema` reports the actual Composition schema accepted from drawing Producers.+`validate_local_author_packages`, `validate_script_cues`, `preview_check`, `layout_check`,+`reconstruction_check` and `authoring_check` are independent reports. None approves or unlocks+another command.++`layout_check` always measures the current realized DOM. Its report contains advisory candidates such+as overflow, overlap and vertical offset. `layout_accept` attaches a human reason to a structural+finding id; it does not fingerprint the project or cache a previous measurement.++`render_element` draws one element directly from the Run using local preview media. A comparison reads+that render against the requested reference stretch. A review reads it against an explicit intent.+Their JSONL logs contain the actual question, paths and prose answer so later inspection does not+depend on a separate state database.++## Environment++Reference observation uses `HYPIT_GEMINI_PROVIDER=auto|hypihub|vertex`. HypiHub reads+`HYPIHUB_API_KEY` and optional `HYPIHUB_BASE_URL`; Vertex reads `GOOGLE_CLOUD_PROJECT`,+`GOOGLE_APPLICATION_CREDENTIALS_JSON` and optional `GOOGLE_CLOUD_LOCATION`.++Transcript preparation uses the selected local WhisperX service. Start services through the normal+Runtime configuration with `hypit runtime up`. `HYPIT_REFERENCE_CONCURRENCY` and+`HYPIT_REFERENCE_LAUNCH_GAP_MS` only control observation request pacing.diff --git a/packages/reference-video-tools/src/authoring.ts b/packages/reference-video-tools/src/authoring.tsindex fefe8583..740a3be0 100644--- a/packages/reference-video-tools/src/authoring.ts+++ b/packages/reference-video-tools/src/authoring.ts@@ -15,7 +15,7 @@ import type { CompiledGraph } from "@hypit/protocol";import { parseScript } from "@hypit/script";import { videoCliDistribution } from "@hypit/video-cli";import { loadStudioCompanionRegistry } from "@hypit/studio/src/companion-profile.js";-import { openStudioArchive } from "@hypit/studio/src/archive.js";+import { openStudioBuildLibrary } from "@hypit/studio/src/build-library.js";import { loadStudioDomain } from "@hypit/studio/src/domain.js";import type { Preview } from "@hypit/studio/src/programme.js";import { preview } from "@hypit/studio/src/programme.js";@@ -582,9 +582,10 @@ export async function realizeAuthoringPreview(input: {const registry = await loadStudioCompanionRegistry({ workspaceRoot: projectRoot, packageRoot, distributionPackageRoot });const domain = await loadStudioDomain({ run: runPath, workspaceRoot: projectRoot, packageRoot });const runtimePath = input.runtime === undefined ? undefined : resolve(cwd, input.runtime);- const archive = await openStudioArchive(runtimePath, packageRoot, projectRoot, distributionPackageRoot);+ const buildLibrary = await openStudioBuildLibrary(runtimePath, packageRoot, projectRoot, distributionPackageRoot);try {- const original = await loadStudioRun({ run: runPath, domain, registry, ...(archive === undefined ? {} : { archive }) });+ const original = await loadStudioRun({ run: runPath, domain, registry,+ ...(buildLibrary === undefined ? {} : { buildLibrary }) });const graph: CompiledGraph = {format: "hypit.graph@1",outputs: original.source.compiled.graph.outputs,@@ -603,11 +604,11 @@ export async function realizeAuthoringPreview(input: {});const previewRegistry = await loadStudioCompanionRegistry({ workspaceRoot: projectRoot, packageRoot, distributionPackageRoot });const previewDomain = await loadStudioDomain({ run: previewMock.previewRun, workspaceRoot: projectRoot, packageRoot });- const previewArchive = await openStudioArchive(runtimePath, packageRoot, projectRoot, distributionPackageRoot);+ const previewBuildLibrary = await openStudioBuildLibrary(runtimePath, packageRoot, projectRoot, distributionPackageRoot);try {const loadedPreview = await loadStudioRun({run: previewMock.previewRun, domain: previewDomain, registry: previewRegistry,- ...(previewArchive === undefined ? {} : { archive: previewArchive }),+ ...(previewBuildLibrary === undefined ? {} : { buildLibrary: previewBuildLibrary }),});const previewRun = { ...loadedPreview, attachments: [...loadedPreview.attachments, ...previewMock.attachments] };const inspection = inspectStudioRun(previewRegistry, previewRun.source, previewRun, new Set([@@ -626,7 +627,6 @@ export async function realizeAuthoringPreview(input: {outputRefs: [inspection.filmComposition, ...inspection.projections.map((item) => item.ref)],compositionRef: inspection.filmComposition,projections: inspection.projections,- ...(previewArchive === undefined ? {} : { archive: previewArchive }),endpoints: deterministicEndpoints,});const programFrames = Math.max(1, ...built.anchors.values());@@ -653,7 +653,7 @@ export async function realizeAuthoringPreview(input: {programFrames, frameOfToken, selections, segmentTokenCounts,};} finally {- await previewArchive?.close();+ await previewBuildLibrary?.close();}} catch (error) {const issues = (error as { readonly issues?: unknown } | null)?.issues;@@ -662,7 +662,7 @@ export async function realizeAuthoringPreview(input: {}throw error instanceof Error ? error : new Error(String(error));} finally {- await archive?.close();+ await buildLibrary?.close();}}diff --git a/packages/reference-video-tools/src/checks.ts b/packages/reference-video-tools/src/checks.tsindex 2bb177aa..14cc81e3 100644--- a/packages/reference-video-tools/src/checks.ts+++ b/packages/reference-video-tools/src/checks.ts@@ -8,7 +8,7 @@ import { loadNodePackageSelection, physicalPackageName } from "@hypit/package-loimport { parseScript, validateCaptionCueLengths } from "@hypit/script";import { videoCliDistribution } from "@hypit/video-cli";import { loadStudioCompanionRegistry } from "@hypit/studio/src/companion-profile.js";-import { openStudioArchive } from "@hypit/studio/src/archive.js";+import { openStudioBuildLibrary } from "@hypit/studio/src/build-library.js";import { loadStudioDomain } from "@hypit/studio/src/domain.js";import { loadStudioRun } from "@hypit/studio/src/run.js";import { readStudioSession } from "@hypit/studio/src/session.js";@@ -182,7 +182,7 @@ export async function previewCheck(const registry = await loadStudioCompanionRegistry({ workspaceRoot, packageRoot, distributionPackageRoot });const domain = await loadStudioDomain({ run: runPath, workspaceRoot, packageRoot });- const archive = await openStudioArchive(runtimePath, packageRoot, workspaceRoot, distributionPackageRoot);+ const buildLibrary = await openStudioBuildLibrary(runtimePath, packageRoot, workspaceRoot, distributionPackageRoot);let session: StudioSession | undefined;let refusal: string | undefined;@@ -192,7 +192,7 @@ export async function previewCheck(run: runPath,domain,registry,- ...(archive === undefined ? {} : { archive }),+ ...(buildLibrary === undefined ? {} : { buildLibrary }),});// Preflight first, so an unopenable Run is reported as the refusal it is// rather than as whatever the build happens to fail on afterwards.@@ -202,7 +202,6 @@ export async function previewCheck(registry,run,workspaceRoot,- ...(archive === undefined ? {} : { archive }),revision: 0,});} catch (error) {@@ -213,15 +212,15 @@ export async function previewCheck(refusal = error instanceof Error ? error.message : String(error);}} finally {- // Close before reporting: a runtime archive left open outlives the check.- await archive?.close();+ // Close before reporting: the read-only Runtime connection must not outlive the check.+ await buildLibrary?.close();}if (refusal !== undefined) return { run: runPath, sound: false, sources, refused: refusal };if (awaiting !== undefined) {// The graph traced all the way to a Film and a semantic spine; what is left is- // work a Provider has to do. That is a pass for this gate, and the delivery+ // work a Provider has to do. That is sound for this report, and the delivery// measurements happen on the real Build either way.const noun = awaiting.length === 1 ? "capability" : "capabilities";return {@@ -276,7 +275,6 @@ export type AuthoringCheckInput = ReconstructionCheckInput & {readonly mode?: AuthoringCheckMode;};-export type MechanicalAuthoringCheckInput = { readonly run: string };/*** Where a description-authored project's reviews are logged.@@ -513,7 +511,7 @@ function frameGeometry(svml: string): FrameGeometry {* speech, so it renders before a Build like any other.** A look counts once it has been answered: in band (`complete`, the gemini observer) or handed out- * and closed by whoever answered it (`pending` until then). Only `failed` is not a look. The gate+ * and closed by whoever answered it (`pending` until then). Only `failed` is not a look. The report* cannot judge whether the stretch an element was looked at over actually showed it, so the stretches* are reported for a reader, and a lone look is called out rather than assumed meaningful.*@@ -997,7 +995,7 @@ export async function authoringCheck(// has reported on, and crediting it credited the tool call rather than the look..filter((entry) => entry.status === "complete");- // Which stretches each element was compared against, in order. The gate cannot judge whether a+ // Which stretches each element was compared against, in order. The report cannot judge whether a// stretch was the right one to compare against — it does not know what the element draws — so it// reports them and lets a reader notice a component compared against one that never showed it.const rounds = new Map<string, string[]>();@@ -1026,7 +1024,7 @@ export async function authoringCheck(// A logged look and a planned one are compared as word ranges, because that is the one form both// can always be put in: a look recorded against a Segment resolves to the words that Segment marks,// and a look recorded against a Cue was never anything else. Comparing the names instead would let- // a Cue in the middle of a Segment match the Segment, and the coverage this gate claims would be+ // a Cue in the middle of a Segment match the Segment, and the coverage this report claims would be// wider than the coverage it has.const asTokens = (entry: LoggedComparison): string | undefined => {if (entry.range?.tokens !== undefined) return `${entry.range.tokens[0]}-${entry.range.tokens[1]}`;@@ -1068,7 +1066,7 @@ export async function authoringCheck(compared_against: [...new Set(stretches)],state,timing_basis: timingBasis(element.id),- // The gate cannot judge whether the stretch chosen actually showed the element, so a lone+ // The report cannot judge whether the stretch chosen actually showed the element, so a lone// comparison is called out for a reader to confirm rather than silently accepted....(stretches.length === 1 ? { note: `single ${looking} — confirm this stretch shows the element, not a look-alike` } : {}),};@@ -1281,34 +1279,3 @@ export async function authoringCheck(}),};}--/**- * Source-only delivery gate for variant expansion.- *- * It reuses the authoring check's graph-independent analysis but deliberately does not require a- * render, comparison, review log or VLM judgement. Only deterministic failures (unresolved vocabulary,- * uncovered Script words and timed- * pictures that empty their windows) decide `passed` here.- */-export async function mechanicalAuthoringCheck(- input: MechanicalAuthoringCheckInput,- roots: { readonly packageRoot: string },-): Promise<Record<string, unknown>> {- const result = await authoringCheck({ run: input.run, mode: "description" }, roots);- const playback = Array.isArray(result.playback) ? result.playback : [];- const uncovered = Array.isArray(result.uncovered) ? result.uncovered : [];- const unresolved = result.unresolved_packages;- const summary = Array.isArray(result.summary) ? result.summary.map(String) : [];- const unreadable = summary.some((line) => line.startsWith("no aliased package import could be read")- || line.startsWith("no package the Source imports publishes a Surface that draws"));- const passed = playback.length === 0 && uncovered.length === 0 && unresolved === undefined && !unreadable;- return {- run: result.run,- passed,- summary,- playback,- uncovered,- ...(unresolved === undefined ? {} : { unresolved_packages: unresolved }),- note: "Mechanical variant gate only; no render, VLM comparison or visual review was performed.",- };-}diff --git a/packages/reference-video-tools/src/cli.ts b/packages/reference-video-tools/src/cli.tsindex 04570c22..3b40bb8c 100644--- a/packages/reference-video-tools/src/cli.ts+++ b/packages/reference-video-tools/src/cli.ts@@ -2,7 +2,7 @@import { readFile } from "node:fs/promises";import { createReferenceVideoTools } from "./tools.js";-import type { CompareReconstructionInput, ObserveReferenceInput, RecordObservationInput, RenderElementInput, ReviewElementInput, RouteStateCommandInput, RevisionStateCommandInput, VariantStateCommandInput } from "./tools.js";+import type { CompareReconstructionInput, ObserveReferenceInput, RecordObservationInput, RenderElementInput, ReviewElementInput } from "./tools.js";/*** A word range written on the command line as `from:to`, half-open.@@ -26,15 +26,6 @@ function usage(): string {return ["Usage:"," hypit-reference-video-tools list_svml_packages",- " 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]",- " hypit-reference-video-tools variant_state --action discover|start|read|checkpoint|reconcile --project-root <dir> [options]",- " hypit-reference-video-tools variant_init --project-root <base> --output-root <batch> --slate <slate.json>",- " hypit-reference-video-tools variant_check --run <variant>/build.svrun [--runtime <hypit.runtime.json>]",- " route_state start: --route reconstruction|description|variant|variant-package [--run <run>] [--reference-id <id>]",- " revision_state start: [--run <run>] [--parent-route reconstruction|description|variant] [--request <text>]",- " 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> --question <text>",@@ -44,7 +35,7 @@ function usage(): string {" hypit-reference-video-tools inspect_svml_vocabulary --package <name> [--package <name> ...] [--tag <tag> ...] [--without-previews] [--run <build.svrun>]"," hypit-reference-video-tools validate_local_author_packages --run <build.svrun> [--runtime <hypit.runtime.json>] [--expected-package <name> ...]"," hypit-reference-video-tools validate_script_cues --run <build.svrun>",- " hypit-reference-video-tools inspect_visual_contract [--shape visual-track|visual-element|box|mask|text|image|video|surface|text-flow|text-typography|text-paint|text-document|path-command] [--producers-of <package> ...]",+ " hypit-reference-video-tools inspect_visual_schema [--shape visual-track|visual-element|box|mask|text|image|video|surface|text-flow|text-typography|text-paint|text-document|path-command] [--producers-of <package> ...]"," hypit-reference-video-tools paths"," hypit-reference-video-tools compare_reconstruction --reference-id <id> --run <build.svrun> --segment <id>|--selection <id>|--tokens <from:to> --video <path>|--image <path> [--question <scope>] [--element <id>] [--tolerance-frames <n>]"," hypit-reference-video-tools compare_reconstruction --reference-id <id> --shot-id <id> --video <path>|--image <path> [--question <scope>] [--element <id>] [--tolerance-frames <n>]",@@ -72,7 +63,7 @@ function usage(): string {"picture over, and which timed pictures are configured to stop before their window ends. Comparison","asks for participation rather than convergence, so an element compared once passes. With one","prepared reference it uses that one; with several it requires --reference-id.",- "Each element records the preview timing basis — native estimate or not recorded — so the gate knows",+ "Each element records the preview timing basis — native estimate or not recorded — so the report knows","not recorded — which says whether anything that changes with elapsed time inside its window has","been looked at, or only its layout.","",@@ -99,7 +90,7 @@ function usage(): string {"Manifest promises is drawn by hand and left alone.","","--element names the reconstructed element the image draws. It is written to the reference's",- "comparison log and never sent to the observer, so the comparison stays blind while a later gate can",+ "comparison log and never sent to the observer, so the comparison stays blind while a later report can","still tell which elements have been compared.","","compare_reconstruction takes the stretch of the reference two ways. --segment and --selection name",@@ -133,12 +124,12 @@ function usage(): string {"fill and is therefore still whatever the reference does.","","Mock media is materialized by the local mock Provider and cached by @hypit/preview-mock; it never",- "enters Author Source and is ignored by coverage gates. Timing uses estimate:Speech, while reference",+ "enters Author Source and is ignored by coverage reports. Timing uses estimate:Speech, while reference","WhisperX is reserved for comparison evidence and window selection.","","record_observation takes the keys the agent observer is handed: the four whole-reference keys, a","shot key such as visual:shot-003 or boundary:shot-004, a narrow question keyed by the shots it was",- "asked over and by the question itself (question:shot-003+shot-004:<digest>), and a comparison keyed",+ "asked over and by the question itself, and a comparison keyed","by the `comparison_id` compare_reconstruction returned (comparison:<id>). Pass the key back exactly","as it was handed out. A comparison's answer is written back onto its own line of the log, which is","what makes it count toward coverage; until then reconstruction_check lists it under",@@ -175,7 +166,7 @@ function usage(): string {"words WhisperX measured — `transcript_words` for its own stretch, `transcript_ref` for the whole","file — since that observer reads pictures and the words are the only record of when speech happens.","",- "inspect_visual_contract answers what a Producer that draws may return: the element kinds, the style",+ "inspect_visual_schema answers what a Producer that draws may return: the element kinds, the style","names admitted on them, which take an enum, the only local styles allowed in keyframes","(clip-path, filter, opacity and transform), and how few keyframes an animation carries. Every line is","generated from the Composition schema, so it says what the seal will accept rather than what one",@@ -196,19 +187,6 @@ function usage(): string {].join("\n");}-function routeStateUsage(): string {- return [- "Usage:",- " hypit-reference-video-tools route_state --action start --project-root <dir> --route reconstruction|description|variant|variant-package [--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|variant|variant-package (--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@@ -294,176 +272,6 @@ async function main(): Promise<void> {let result: unknown;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\n\n" + routeStateUsage());- }- 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") {- const route = one(flags, "route");- if (route !== "reconstruction" && route !== "description" && route !== "variant" && route !== "variant-package") throw new Error("--route must be reconstruction, description, variant or variant-package");- result = await tools.route_state({ action, project_root: projectRoot, route,- ...(one(flags, "run") === undefined ? {} : { run: one(flags, "run") }),- ...(one(flags, "reference-id") === undefined ? {} : { reference_id: one(flags, "reference-id") }) } as RouteStateCommandInput);- } else if (action === "read" || action === "reconcile") {- result = await tools.route_state({ action, project_root: projectRoot });- } else {- const route = one(flags, "route");- if (route !== "reconstruction" && route !== "description" && route !== "variant" && route !== "variant-package") throw new Error("--route must be reconstruction, description, variant or variant-package");- 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;- if (artifacts !== undefined) {- try { parsedArtifacts = JSON.parse(artifacts) as Readonly<Record<string, string>>; } catch (error) { throw new Error(`--artifacts is not valid JSON: ${error instanceof Error ? error.message : String(error)}`); }- }- result = await tools.route_state({ action, project_root: projectRoot, route, step,- ...(status === undefined ? {} : { status }),- ...(one(flags, "run") === undefined ? {} : { run: one(flags, "run") }),- ...(one(flags, "reference-id") === undefined ? {} : { reference_id: one(flags, "reference-id") }),- ...(one(flags, "next-action") === undefined ? {} : { next_action: one(flags, "next-action") }),- ...(parsedArtifacts === undefined ? {} : { artifacts: parsedArtifacts }),- ...(one(flags, "decision") === undefined ? {} : { decision: one(flags, "decision") }),- ...(one(flags, "command") === undefined ? {} : { command: one(flags, "command") }),- ...(one(flags, "error") === undefined ? {} : { error: one(flags, "error") }),- } as RouteStateCommandInput);- }- } else if (command === "revision_state") {- 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");- }- const projectRoot = typeof supplied?.project_root === "string" ? supplied.project_root : required(flags, "project-root");- if (supplied !== undefined) {- result = await tools.revision_state(supplied as RevisionStateCommandInput);- } else if (action === "start") {- const parentRoute = one(flags, "parent-route");- if (parentRoute !== undefined && parentRoute !== "reconstruction" && parentRoute !== "description" && parentRoute !== "variant") throw new Error("--parent-route must be reconstruction, description or variant");- result = await tools.revision_state({ action, project_root: projectRoot,- ...(one(flags, "run") === undefined ? {} : { run: one(flags, "run") }),- ...(parentRoute === undefined ? {} : { parent_route: parentRoute }),- ...(one(flags, "parent-state-digest") === undefined ? {} : { parent_state_digest: one(flags, "parent-state-digest") }),- ...(one(flags, "request") === undefined ? {} : { request: one(flags, "request") }),- } as RevisionStateCommandInput);- } else if (action === "read" || action === "reconcile") {- result = await tools.revision_state({ action, project_root: projectRoot });- } else {- const stepRaw = required(flags, "step");- const numericStep = Number(stepRaw);- const step: number | string = Number.isSafeInteger(numericStep) && numericStep >= 1 ? numericStep : stepRaw;- const status = one(flags, "status");- if (status !== undefined && status !== "in_progress" && status !== "complete" && status !== "blocked") throw new Error("--status must be in_progress, complete or blocked");- const parentRoute = one(flags, "parent-route");- if (parentRoute !== undefined && parentRoute !== "reconstruction" && parentRoute !== "description" && parentRoute !== "variant") throw new Error("--parent-route must be reconstruction, description or variant");- let artifacts: Readonly<Record<string, string>> | undefined;- const artifactRaw = one(flags, "artifacts");- if (artifactRaw !== undefined) {- try { artifacts = JSON.parse(artifactRaw) as Readonly<Record<string, string>>; } catch (error) { throw new Error(`--artifacts is not valid JSON: ${error instanceof Error ? error.message : String(error)}`); }- }- result = await tools.revision_state({ action, project_root: projectRoot, step,- ...(status === undefined ? {} : { status }),- ...(one(flags, "run") === undefined ? {} : { run: one(flags, "run") }),- ...(parentRoute === undefined ? {} : { parent_route: parentRoute }),- ...(one(flags, "parent-state-digest") === undefined ? {} : { parent_state_digest: one(flags, "parent-state-digest") }),- ...(one(flags, "request") === undefined ? {} : { request: one(flags, "request") }),- ...(one(flags, "next-action") === undefined ? {} : { next_action: one(flags, "next-action") }),- ...(artifacts === undefined ? {} : { artifacts }),- ...(one(flags, "decision") === undefined ? {} : { decision: one(flags, "decision") }),- ...(one(flags, "command") === undefined ? {} : { command: one(flags, "command") }),- ...(one(flags, "error") === undefined ? {} : { error: one(flags, "error") }),- ...(many(flags, "impact").length === 0 ? {} : { impact: many(flags, "impact") }),- ...(many(flags, "affected-source").length === 0 ? {} : { affected_source: many(flags, "affected-source") }),- } as RevisionStateCommandInput);- }- } else if (command === "variant_state") {- const action = typeof supplied?.action === "string" ? supplied.action : one(flags, "action");- if (action !== "discover" && action !== "start" && action !== "read" && action !== "checkpoint" && action !== "reconcile") {- throw new Error("--action must be discover, start, read, checkpoint or reconcile");- }- const projectRoot = typeof supplied?.project_root === "string" ? supplied.project_root : required(flags, "project-root");- if (supplied !== undefined) {- result = await tools.variant_state(supplied as VariantStateCommandInput);- } else if (action === "discover") {- result = await tools.variant_state({ action, project_root: projectRoot });- } else if (action === "start") {- const deliveryMode = one(flags, "delivery-mode");- if (deliveryMode !== undefined && deliveryMode !== "source" && deliveryMode !== "build") throw new Error("--delivery-mode must be source or build");- const countRaw = one(flags, "count");- const count = countRaw === undefined ? undefined : Number(countRaw);- if (count !== undefined && (!Number.isSafeInteger(count) || count < 1)) throw new Error("--count must be a positive integer");- const parentRoute = one(flags, "parent-route");- if (parentRoute !== undefined && parentRoute !== "reconstruction" && parentRoute !== "description" && parentRoute !== "variant") throw new Error("--parent-route must be reconstruction, description or variant");- result = await tools.variant_state({- action, project_root: projectRoot, output_root: required(flags, "output-root"),- ...(one(flags, "run") === undefined ? {} : { run: one(flags, "run") }),- ...(one(flags, "request") === undefined ? {} : { request: one(flags, "request") }),- ...(count === undefined ? {} : { count }),- ...(deliveryMode === undefined ? {} : { delivery_mode: deliveryMode }),- ...(parentRoute === undefined ? {} : { parent_route: parentRoute }),- ...(one(flags, "parent-state-digest") === undefined ? {} : { parent_state_digest: one(flags, "parent-state-digest") }),- ...(one(flags, "revision-state-digest") === undefined ? {} : { revision_state_digest: one(flags, "revision-state-digest") }),- } as VariantStateCommandInput);- } else if (action === "read" || action === "reconcile") {- const outputRoot = one(flags, "output-root");- const batchId = one(flags, "batch-id");- result = await tools.variant_state({- action, project_root: projectRoot,- ...(outputRoot === undefined ? {} : { output_root: outputRoot }),- ...(batchId === undefined ? {} : { batch_id: batchId }),- });- } else {- const stepRaw = required(flags, "step");- const numericStep = Number(stepRaw);- const step: number | string = Number.isSafeInteger(numericStep) && numericStep >= 1 ? numericStep : stepRaw;- const status = one(flags, "status") ?? "complete";- if (status !== "in_progress" && status !== "complete" && status !== "blocked") throw new Error("--status must be in_progress, complete or blocked");- const parseObject = <T>(name: string): T | undefined => {- const raw = one(flags, name);- if (raw === undefined) return undefined;- try { return JSON.parse(raw) as T; } catch (error) { throw new Error(`--${name} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`); }- };- result = await tools.variant_state({- action, project_root: projectRoot, step, status,- ...(one(flags, "output-root") === undefined ? {} : { output_root: one(flags, "output-root") }),- ...(one(flags, "batch-id") === undefined ? {} : { batch_id: one(flags, "batch-id") }),- ...(one(flags, "next-action") === undefined ? {} : { next_action: one(flags, "next-action") }),- ...(parseObject<Record<string, string>>("artifacts") === undefined ? {} : { artifacts: parseObject<Record<string, string>>("artifacts") }),- ...(parseObject<VariantStateCommandInput & object>("workload-disclosure") === undefined ? {} : { workload_disclosure: parseObject("workload-disclosure") }),- ...(parseObject<readonly unknown[]>("packages") === undefined ? {} : { packages: parseObject("packages") }),- ...(parseObject<readonly unknown[]>("variants") === undefined ? {} : { variants: parseObject("variants") }),- ...(one(flags, "decision") === undefined ? {} : { decision: one(flags, "decision") }),- ...(one(flags, "conflict") === undefined ? {} : { conflict: one(flags, "conflict") }),- ...(one(flags, "resolve-conflict") === undefined ? {} : { resolve_conflict: one(flags, "resolve-conflict") }),- ...(one(flags, "command") === undefined ? {} : { command: one(flags, "command") }),- ...(one(flags, "error") === undefined ? {} : { error: one(flags, "error") }),- } as VariantStateCommandInput);- }- } else if (command === "variant_init") {- result = await tools.variant_init((supplied ?? {- project_root: required(flags, "project-root"), output_root: required(flags, "output-root"), slate: required(flags, "slate"),- }) as { project_root: string; output_root: string; slate: string });- } else if (command === "variant_check") {- result = await tools.variant_check((supplied ?? {- run: required(flags, "run"), ...(one(flags, "runtime") === undefined ? {} : { runtime: one(flags, "runtime") }),- }) as { run: string; runtime?: string });} else if (command === "prepare_reference") {const observer = one(flags, "observer");if (observer !== undefined && observer !== "gemini" && observer !== "agent") throw new Error("--observer must be gemini or agent");@@ -591,8 +399,8 @@ async function main(): Promise<void> {...(one(flags, "tolerance-frames") === undefined ? {} : { tolerance_frames: Number(one(flags, "tolerance-frames")) }),};result = await tools.compare_reconstruction(input as CompareReconstructionInput);- } else if (command === "inspect_visual_contract") {- result = await tools.inspect_visual_contract({+ } else if (command === "inspect_visual_schema") {+ result = await tools.inspect_visual_schema({...(one(flags, "shape") === undefined ? {} : { shape: one(flags, "shape")! }),...(many(flags, "producers-of").length === 0 ? {} : { producers: many(flags, "producers-of") }),});@@ -647,7 +455,7 @@ async function main(): Promise<void> {const input = supplied ?? { package_dirs: operands };result = await tools.render_previews(input as { package_dirs: readonly string[] });} else if (command === "preview_check") {- // The runtime archive is the second operand rather than a flag, the way the Run itself is: both+ // The Runtime Profile is the second operand rather than a flag, the way the Run itself is: both// name a file this command opens, and the pair reads as one argument list.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/index.ts b/packages/reference-video-tools/src/index.tsindex 831a1c4b..5abf70c0 100644--- a/packages/reference-video-tools/src/index.ts+++ b/packages/reference-video-tools/src/index.ts@@ -6,68 +6,5 @@ export type {RecordObservationInput,InspectVocabularyInput,ValidateLocalAuthorPackagesInput,- RouteStateCommandInput,- RevisionStateCommandInput,- VariantStateCommandInput,- VariantInitInput,- VariantCheckInput,} from "./tools.js";-export type { MechanicalAuthoringCheckInput, ScriptCueCheckInput } from "./checks.js";-export {- checkpointRouteState,- componentFitPath,- componentFitSatisfied,- readRouteState,- reconcileRouteState,- routeExecutionStatePath,- routeStatePath,- startRouteState,- ROUTE_STATE_STEPS,- ROUTE_STATE_VERSION,- COMPONENT_FIT_VERSION,-} from "./route-state.js";-export type { DescriptionRouteStep, ReconstructionRouteStep, RouteCheckpointInput, RouteKind, RouteState, RouteStateInput, RouteStep, VariantPackageRouteStep, VariantRouteStep } from "./route-state.js";-export {- checkpointRevisionState,- readRevisionState,- reconcileRevisionState,- revisionExecutionStatePath,- revisionRequestPath,- revisionStatePath,- startRevisionState,- REVISION_STATE_VERSION,- REVISION_STEPS,-} from "./revision-state.js";-export type { RevisionCheckpointInput, RevisionParentRoute, RevisionState, RevisionStateInput, RevisionStatus, RevisionStep } from "./revision-state.js";-export {- checkpointVariantExpansion,- discoverVariantExpansions,- readVariantExpansionState,- reconcileVariantExpansion,- startVariantExpansion,- variantExpansionLocatorPath,- variantExpansionStatePath,- VARIANT_EXPANSION_STATE_VERSION,- VARIANT_EXPANSION_STEPS,-} from "./variant-state.js";-export type {- StartVariantExpansionInput,- VariantExpansionCheckpointInput,- VariantExpansionLocator,- VariantExpansionPackage,- VariantExpansionState,- VariantExpansionStatus,- VariantExpansionStep,- VariantExpansionVariant,- VariantWorkloadDisclosure,-} from "./variant-state.js";-export {- findGeneratedLeakage,- initializeVariantProjects,- inspectSourceVocabularyUsage,- inspectVariantDiff,- removeGeneratedRunBindings,- snapshotProject,-} from "./variant-project.js";-export type { ApprovedVariantPackage, InitializedVariant, SlateDirection, SlatePackageInjection, SlateVariant, VariantProjectManifest, VariantSlate } from "./variant-project.js";-export { expandVariantSlate } from "./variant-project.js";+export type { ScriptCueCheckInput } from "./checks.js";diff --git a/packages/reference-video-tools/src/layout.ts b/packages/reference-video-tools/src/layout.tsindex 400a2f29..f7618183 100644--- a/packages/reference-video-tools/src/layout.ts+++ b/packages/reference-video-tools/src/layout.ts@@ -1,6 +1,5 @@-import { createHash } from "node:crypto";import { createReadStream } from "node:fs";-import { readFile, readdir, stat } from "node:fs/promises";+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";import { createServer } from "node:http";import { createRequire } from "node:module";import { dirname, extname, join, normalize, resolve, sep } from "node:path";@@ -9,7 +8,6 @@ import { spawnSync } from "node:child_process";import puppeteer from "puppeteer-core";import { authorSource, invokedFrom, realizeAuthoringPreview, repositoryRoot, stageAuthoringPreview } from "./authoring.js";-import { atomicJson } from "./state-files.js";export type LayoutCheckInput = {readonly run: string;@@ -23,8 +21,6 @@ export type LayoutAcceptInput = {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 };type RawFinding = {readonly kind: "vertical-offset" | "parent-overflow" | "canvas-overflow" | "peer-overlap";@@ -43,71 +39,34 @@ type RawFinding = {type LayoutDecision = {readonly finding: string;- readonly layout_digest: string;readonly reason: string;readonly accepted_at: string;};-type LayoutDecisions = { readonly version: 1; readonly decisions: readonly LayoutDecision[] };+type LayoutDecisions = { readonly decisions: readonly LayoutDecision[] };function projectRoot(runPath: string): string { return dirname(runPath); }export function layoutCheckPath(runPath: string): string { return join(projectRoot(runPath), ".hypit", "layout-check.json"); }export function layoutDecisionsPath(runPath: string): string { return join(projectRoot(runPath), ".hypit", "layout-decisions.json"); }-function hash(value: unknown): string {- return `sha256:${createHash("sha256").update(typeof value === "string" ? value : JSON.stringify(value)).digest("hex")}`;-}+function round(value: number): number { return Math.round(value * 1000) / 1000; }-async function inputDigests(runPath: string, sourcePath: string): Promise<Readonly<Record<string, string>>> {- const files = new Set<string>([runPath]);- const queue = [sourcePath];- while (queue.length > 0) {- const path = queue.shift()!;- if (files.has(path)) continue;- files.add(path);- const source = await readFile(path, "utf8").catch(() => undefined);- if (source === undefined) continue;- for (const match of source.matchAll(/<import\s+[^>]*\bsource="([^"]+)"[^>]*\/?\s*>/gu)) {- queue.push(resolve(dirname(path), match[1]!));- }- }- const root = dirname(runPath);- for (const name of ["package.json", "pnpm-lock.yaml", "hypit.runtime.json"]) {- const path = join(root, name);- if (await stat(path).then((value) => value.isFile(), () => false)) files.add(path);- }- const localPackages = join(root, "packages");- const visit = async (directory: string): Promise<void> => {- const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);- for (const entry of entries) {- if (entry.name === "node_modules" || entry.name === ".hypit") continue;- const path = join(directory, entry.name);- if (entry.isDirectory()) await visit(path);- else if (entry.isFile()) files.add(path);- }- };- await visit(localPackages);- const result: Record<string, string> = {};- for (const path of [...files].sort()) {- const bytes = await readFile(path).catch(() => undefined);- if (bytes !== undefined) result[path] = hash(bytes);- }- return result;+async function writeJson(path: string, value: unknown): Promise<void> {+ await mkdir(dirname(path), { recursive: true });+ await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");}-function round(value: number): number { return Math.round(value * 1000) / 1000; }-async function readDecisions(path: string): Promise<LayoutDecisions> {const source = await readFile(path, "utf8").catch((error: unknown) => {if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;throw error;});- if (source === undefined) return { version: 1, decisions: [] };+ if (source === undefined) return { decisions: [] };let value: unknown;try { value = JSON.parse(source); }catch (error) { throw new Error(`layout decisions at ${path} are invalid JSON; original file was preserved: ${error instanceof Error ? error.message : String(error)}`); }const decisions = value as Partial<LayoutDecisions>;- if (decisions.version !== 1 || !Array.isArray(decisions.decisions)) throw new Error(`layout decisions at ${path} have an unsupported shape`);+ if (!Array.isArray(decisions.decisions)) throw new Error(`layout decisions at ${path} have an unsupported shape`);return decisions as LayoutDecisions;}@@ -448,11 +407,18 @@ function aggregate(findings: readonly RawFinding[]): RawFinding[] {return [...grouped.values()].map((finding) => ({ ...finding, pixels: round(finding.pixels), ratio: round(finding.ratio) }));}-function withIdentity(findings: readonly RawFinding[], digest: string, packages: ReadonlyMap<string, string>, decisions: LayoutDecisions): readonly Record<string, unknown>[] {- const accepted = new Map(decisions.decisions.filter((item) => item.layout_digest === digest).map((item) => [item.finding, item] as const));+function findingId(finding: RawFinding, packageName: string | undefined): string {+ return [finding.kind, packageName, finding.track, finding.present, finding.element, finding.related]+ .filter((part): part is string => part !== undefined && part.length > 0)+ .map((part) => encodeURIComponent(part))+ .join("/");+}++function withIdentity(findings: readonly RawFinding[], packages: ReadonlyMap<string, string>, decisions: LayoutDecisions): readonly Record<string, unknown>[] {+ const accepted = new Map(decisions.decisions.map((item) => [item.finding, item] as const));return findings.map((finding) => {const packageName = finding.track === undefined ? undefined : packages.get(finding.track);- const id = hash([finding.kind, finding.layer, packageName ?? "", finding.track ?? "", finding.present ?? "", finding.element, finding.related ?? "", digest]);+ const id = findingId(finding, packageName);const decision = accepted.get(id);return {id, ...finding, ...(packageName === undefined ? {} : { package: packageName }),@@ -465,42 +431,22 @@ function withIdentity(findings: readonly RawFinding[], digest: string, packages:export async function layoutCheck(input: LayoutCheckInput): Promise<Record<string, unknown>> {const runPath = resolve(invokedFrom(), input.run);const source = await authorSource(runPath);- const inputs = await inputDigests(runPath, source.path);const realized = await realizeAuthoringPreview(input);const { stage, document, mediaTypes } = await stageAuthoringPreview(realized);- const digest = hash({- checker: LAYOUT_CHECKER_VERSION,- inputs,- graph: realized.built.source.compiled.graph,- program: realized.built.source.compiled.program.records,- composition: realized.built.composition,- served: [...realized.built.served.keys()].sort(),- });const decisionsPath = layoutDecisionsPath(runPath);const decisions = await readDecisions(decisionsPath);- await atomicJson(decisionsPath, decisions);+ await writeJson(decisionsPath, decisions);const currentPath = layoutCheckPath(runPath);- const cached = await readFile(currentPath, "utf8").then((text) => JSON.parse(text) as Record<string, unknown>, () => undefined);- let raw: RawFinding[];- let samples: readonly StableSample[];- if (cached?.layout_digest === digest && Array.isArray(cached.raw_findings) && Array.isArray(cached.samples)) {- raw = cached.raw_findings as RawFinding[];- samples = cached.samples as StableSample[];- } else {- samples = framePlan(realized.built.composition).filter((sample) => sample.frame < document.frameCount);- raw = aggregate(await realizedFindings(realized, stage, mediaTypes, samples));- }- const findings = withIdentity(raw, digest, packageByTrack(realized), decisions);+ const samples = framePlan(realized.built.composition).filter((sample) => sample.frame < document.frameCount);+ const raw = aggregate(await realizedFindings(realized, stage, mediaTypes, samples));+ const findings = withIdentity(raw, packageByTrack(realized), decisions);const pending = findings.filter((finding) => finding.disposition === "agent-review-required");const result = {- version: LAYOUT_CHECKER_VERSION,run: runPath,source: source.path,- input_digests: inputs,- layout_digest: digest,- executed: true,- settled: pending.length === 0,- semantics: "candidate-evidence-only",+ checked: true,+ reviewed: pending.length === 0,+ semantics: "advisory-measurements",note: "Mechanical measurements assist the Agent; they are not findings of fault and never override design intent. Repair a genuine issue or use layout_accept with a reason for intentional geometry.",samples,raw_findings: raw,@@ -509,8 +455,8 @@ export async function layoutCheck(input: LayoutCheckInput): Promise<Record<strinaccepted_count: findings.length - pending.length,checked_at: new Date().toISOString(),};- await atomicJson(currentPath, result);- return { ...result, evidence: currentPath, decisions: decisionsPath };+ await writeJson(currentPath, result);+ return { ...result, report: currentPath, decisions: decisionsPath };}export async function layoutAccept(input: LayoutAcceptInput): Promise<Record<string, unknown>> {@@ -520,8 +466,8 @@ export async function layoutAccept(input: LayoutAcceptInput): Promise<Record<str: [{ 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 report = JSON.parse(await readFile(reportPath, "utf8")) as { findings?: unknown };+ if (!Array.isArray(report.findings)) throw new Error(`run layout_check first; ${reportPath} has no usable report`);const path = layoutDecisionsPath(runPath);const existing = await readDecisions(path);const decisions = [...existing.decisions];@@ -530,16 +476,15 @@ export async function layoutAccept(input: LayoutAcceptInput): Promise<Record<strif (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);+ const decision: LayoutDecision = { finding: acceptance.finding, reason, accepted_at: new Date().toISOString() };+ const index = decisions.findIndex((item) => item.finding === decision.finding);if (index >= 0) decisions.splice(index, 1);decisions.push(decision);}- await atomicJson(path, { version: 1, decisions });+ await writeJson(path, { decisions });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/media.ts b/packages/reference-video-tools/src/media.tsindex 71b536fa..49828653 100644--- a/packages/reference-video-tools/src/media.ts+++ b/packages/reference-video-tools/src/media.ts@@ -1,4 +1,3 @@-import { createHash } from "node:crypto";import { mkdir, readFile, stat, writeFile } from "node:fs/promises";import { cpus } from "node:os";import { join, resolve } from "node:path";@@ -284,6 +283,7 @@ export async function writeJson(path: string, value: unknown): Promise<void> { aexport async function readJson<T>(path: string): Promise<T | undefined> { try { return JSON.parse(await readFile(path, "utf8")) as T; } catch { return undefined; } }export async function referenceId(videoPath: string): Promise<string> {const info = await stat(videoPath);- const value = `${resolve(videoPath)}\u0000${info.size}\u0000${info.mtimeMs}`;- return `ref-${createHash("sha256").update(value).digest("hex").slice(0, 24)}`;+ const name = resolve(videoPath).split(/[\\/]/u).at(-1)?.replace(/\.[^.]+$/u, "")+ .replace(/[^0-9A-Za-z._-]+/gu, "-").replace(/^-+|-+$/gu, "") || "video";+ return `ref-${name}-${info.size}-${Math.trunc(info.mtimeMs)}`;}diff --git a/packages/reference-video-tools/src/revision-state.ts b/packages/reference-video-tools/src/revision-state.tsdeleted file mode 100644index c99a180d..00000000--- a/packages/reference-video-tools/src/revision-state.ts+++ /dev/null@@ -1,352 +0,0 @@-import { readFile, stat } from "node:fs/promises";-import { join, resolve, sep } from "node:path";--import { readRouteState, routeExecutionStatePath } from "./route-state.js";-import { atomicJson, digestPath, executionId, persistExecutionState } from "./state-files.js";--/** A durable, small snapshot for a post-completion natural-language revision. */-export type RevisionStatus = "active" | "complete" | "blocked";-export type RevisionParentRoute = "reconstruction" | "description" | "variant";-export type RevisionStep =- | "request-captured"- | "impact-assessed"- | "intent-mapped"- | "source-updated"- | "gates-checked"- | "preview-rendered"- | "review-complete"- | "final-checked"- | "revision-complete"- | "build-complete";--export const REVISION_STATE_VERSION = 2 as const;-export const REVISION_STEPS: readonly RevisionStep[] = [- "request-captured", "impact-assessed", "intent-mapped", "source-updated", "gates-checked",- "preview-rendered", "review-complete", "final-checked", "revision-complete", "build-complete",-];--// Revision is intentionally source-and-gate only. A preview render or VLM-// review is never a prerequisite, and a paid Build is conditional on the-// impact of the change and a fresh user approval.-const REQUIRED_REVISION_STEPS = new Set<number>([1, 2, 3, 4, 5, 8, 9]);--export type RevisionState = {- readonly version: 2;- readonly revision_id: string;- readonly project_root: string;- readonly run?: string;- readonly parent_route?: RevisionParentRoute;- readonly parent_state_digest?: string;- readonly parent_state_path?: string;- readonly parent_revision_id?: string;- readonly parent_revision_digest?: string;- readonly parent_revision_path?: string;- readonly intent_basis: string;- readonly status: RevisionStatus;- readonly current_step: number;- readonly completed_steps: readonly number[];- readonly in_progress: { readonly step: number; readonly started_at: string } | null;- readonly request?: string;- readonly impact?: readonly string[];- readonly affected_source?: readonly string[];- readonly artifacts: Readonly<Record<string, string>>;- readonly artifact_digests: Readonly<Record<string, string>>;- readonly decisions: readonly string[];- readonly next_action: string;- readonly last_command?: string;- readonly last_error?: string;- readonly conflicts?: readonly string[];- readonly created_at: string;- readonly updated_at: string;-};--export type RevisionStateInput = {- readonly projectRoot: string;- readonly run?: string;- readonly parentRoute?: RevisionParentRoute;- readonly parentStateDigest?: string;- readonly request?: string;-};--export type RevisionCheckpointInput = RevisionStateInput & {- readonly step: number | RevisionStep;- readonly status?: "in_progress" | "complete" | "blocked";- readonly nextAction?: string;- readonly artifacts?: Readonly<Record<string, string>>;- readonly decision?: string;- readonly command?: string;- readonly error?: string;- readonly impact?: readonly string[];- readonly affectedSource?: readonly string[];-};--export function revisionStatePath(projectRoot: string): string {- return join(resolve(projectRoot), ".hypit", "revision-state.json");-}--export function revisionExecutionStatePath(projectRoot: string, revisionId: string): string {- return join(resolve(projectRoot), ".hypit", "revisions", revisionId, "state.json");-}--export function revisionRequestPath(projectRoot: string, revisionId: string): string {- return join(resolve(projectRoot), ".hypit", "revisions", revisionId, "request.json");-}--function nextUncompleted(completed: readonly number[]): number {- const done = new Set(completed);- for (let step = 1; step <= REVISION_STEPS.length; step += 1) {- if (REQUIRED_REVISION_STEPS.has(step) && !done.has(step)) return step;- }- return REVISION_STEPS.length + 1;-}--function stepNumber(step: RevisionStep | number): number {- if (typeof step === "number") {- if (!Number.isSafeInteger(step) || step < 1 || step > REVISION_STEPS.length) throw new Error(`revision step ${step} is outside the revision route`);- return step;- }- const index = REVISION_STEPS.indexOf(step);- if (index < 0) throw new Error(`unknown revision step ${step}`);- return index + 1;-}--function assertState(value: unknown, path: string): asserts value is RevisionState {- if (value === null || typeof value !== "object") throw new Error(`revision state at ${path} is not an object`);- const state = value as Partial<RevisionState>;- if (state.version !== REVISION_STATE_VERSION) throw new Error(`revision state at ${path} has unsupported version`);- if (typeof state.revision_id !== "string" || state.revision_id.length === 0) throw new Error(`revision state at ${path} has no revision_id`);- if (typeof state.project_root !== "string" || state.project_root.length === 0) throw new Error(`revision state at ${path} has no project_root`);- if (state.parent_route !== undefined && state.parent_route !== "reconstruction" && state.parent_route !== "description" && state.parent_route !== "variant") throw new Error(`revision state at ${path} has invalid parent_route`);- if (state.parent_revision_id !== undefined && typeof state.parent_revision_id !== "string") throw new Error(`revision state at ${path} has invalid parent_revision_id`);- if (state.parent_revision_digest !== undefined && typeof state.parent_revision_digest !== "string") throw new Error(`revision state at ${path} has invalid parent_revision_digest`);- if (state.parent_revision_path !== undefined && typeof state.parent_revision_path !== "string") throw new Error(`revision state at ${path} has invalid parent_revision_path`);- if (state.run !== undefined && typeof state.run !== "string") throw new Error(`revision state at ${path} has invalid run`);- if (state.request !== undefined && typeof state.request !== "string") throw new Error(`revision state at ${path} has invalid request`);- if (!REVISION_STEPS.length || typeof state.status !== "string" || !["active", "complete", "blocked"].includes(state.status)) throw new Error(`revision state at ${path} has invalid status`);- if (typeof state.current_step !== "number" || !Number.isSafeInteger(state.current_step) || state.current_step < 1 || state.current_step > REVISION_STEPS.length + 1) throw new Error(`revision state at ${path} has invalid current_step`);- if (!Array.isArray(state.completed_steps) || state.completed_steps.some((step) => !Number.isSafeInteger(step) || step < 1 || step > REVISION_STEPS.length)) throw new Error(`revision state at ${path} has invalid completed_steps`);- if (state.in_progress !== null && (state.in_progress === undefined || typeof state.in_progress !== "object" || !Number.isSafeInteger(state.in_progress.step))) throw new Error(`revision state at ${path} has invalid in_progress`);- if (state.artifacts === null || typeof state.artifacts !== "object" || Array.isArray(state.artifacts)) throw new Error(`revision state at ${path} has invalid artifacts`);- if (state.artifact_digests === null || typeof state.artifact_digests !== "object" || Array.isArray(state.artifact_digests)) throw new Error(`revision state at ${path} has invalid artifact_digests`);- if (!Array.isArray(state.decisions) || state.decisions.some((item) => typeof item !== "string")) throw new Error(`revision state at ${path} has invalid decisions`);- if (state.impact !== undefined && (!Array.isArray(state.impact) || state.impact.some((item) => typeof item !== "string"))) throw new Error(`revision state at ${path} has invalid impact`);- if (state.affected_source !== undefined && (!Array.isArray(state.affected_source) || state.affected_source.some((item) => typeof item !== "string"))) throw new Error(`revision state at ${path} has invalid affected_source`);- if (typeof state.intent_basis !== "string" || typeof state.next_action !== "string" || typeof state.created_at !== "string" || typeof state.updated_at !== "string") throw new Error(`revision state at ${path} is missing recovery fields`);-}--async function writeRevisionState(state: RevisionState): Promise<RevisionState> {- await persistExecutionState(state.project_root, "revision-state.json", "revisions", state.revision_id, state);- return state;-}--function migrateRevisionState(value: unknown): RevisionState | undefined {- if (value === null || typeof value !== "object" || (value as { version?: unknown }).version !== 1) return undefined;- const previous = value as Omit<RevisionState, "version" | "revision_id" | "parent_state_path" | "intent_basis" | "artifact_digests" | "created_at"> & { readonly version: 1 };- const createdAt = typeof previous.updated_at === "string" ? previous.updated_at : new Date().toISOString();- return {- ...previous,- version: REVISION_STATE_VERSION,- revision_id: executionId("revision"),- intent_basis: previous.parent_state_digest === undefined ? "supplied-project" : "legacy-parent-route",- artifact_digests: {},- created_at: createdAt,- };-}--export async function readRevisionState(projectRoot: string): Promise<RevisionState | undefined> {- const path = revisionStatePath(projectRoot);- const text = await readFile(path, "utf8").catch((error: unknown) => {- if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;- throw error;- });- if (text === undefined) return undefined;- let parsed: unknown;- try { parsed = JSON.parse(text); } catch (error) {- throw new Error(`revision state at ${path} is invalid JSON; original file was preserved: ${error instanceof Error ? error.message : String(error)}`);- }- const migrated = migrateRevisionState(parsed);- if (migrated !== undefined) {- const requestPath = revisionRequestPath(migrated.project_root, migrated.revision_id);- await atomicJson(requestPath, { revision_id: migrated.revision_id, request: migrated.request ?? null, intent_basis: migrated.intent_basis, migrated: true });- const requestDigest = await digestPath(requestPath);- const state = {- ...migrated,- artifacts: { ...migrated.artifacts, revision_request: requestPath },- artifact_digests: requestDigest === undefined ? migrated.artifact_digests : { ...migrated.artifact_digests, revision_request: requestDigest },- };- await writeRevisionState(state);- return state;- }- assertState(parsed, path);- return parsed;-}--export async function startRevisionState(input: RevisionStateInput): Promise<RevisionState> {- const projectRoot = resolve(input.projectRoot);- const existing = await readRevisionState(projectRoot);- if (existing !== undefined && existing.status !== "complete") throw new Error(`project already has an active revision at ${revisionStatePath(projectRoot)}`);- const parentState = await readRouteState(projectRoot);- const parentStatePath = parentState === undefined ? undefined : routeExecutionStatePath(projectRoot, parentState.route_id);- const parentStateDigest = input.parentStateDigest ?? (parentStatePath === undefined ? undefined : await digestPath(parentStatePath));- const parentRevisionPath = existing === undefined ? undefined : revisionExecutionStatePath(projectRoot, existing.revision_id);- const parentRevisionDigest = parentRevisionPath === undefined ? undefined : await digestPath(parentRevisionPath);- const parentRoute = input.parentRoute ?? (parentState?.route === "reconstruction" || parentState?.route === "description" || parentState?.route === "variant" ? parentState.route : undefined);- const canonicalBrief = join(projectRoot, ".hypit", "brief.json");- const briefExists = await stat(canonicalBrief).then((value) => value.isFile(), () => false);- const intentBasis = parentRevisionPath ?? parentStatePath ?? (briefExists ? canonicalBrief : "supplied-project");- const now = new Date().toISOString();- const revisionId = executionId("revision");- const requestPath = revisionRequestPath(projectRoot, revisionId);- await atomicJson(requestPath, {- revision_id: revisionId,- request: input.request ?? null,- intent_basis: intentBasis,- ...(parentStatePath === undefined ? {} : { parent_state_path: parentStatePath }),- ...(parentStateDigest === undefined ? {} : { parent_state_digest: parentStateDigest }),- ...(existing === undefined ? {} : { parent_revision_id: existing.revision_id }),- ...(parentRevisionPath === undefined ? {} : { parent_revision_path: parentRevisionPath }),- ...(parentRevisionDigest === undefined ? {} : { parent_revision_digest: parentRevisionDigest }),- captured_at: now,- });- const requestDigest = await digestPath(requestPath);- return writeRevisionState({- version: REVISION_STATE_VERSION, revision_id: revisionId, project_root: projectRoot, status: "active", current_step: 1, completed_steps: [],- in_progress: { step: 1, started_at: now }, artifacts: { revision_request: requestPath },- artifact_digests: requestDigest === undefined ? {} : { revision_request: requestDigest }, decisions: [],- ...(input.run === undefined ? {} : { run: resolve(projectRoot, input.run) }),- ...(parentRoute === undefined ? {} : { parent_route: parentRoute }),- ...(parentStateDigest === undefined ? {} : { parent_state_digest: parentStateDigest }),- ...(parentStatePath === undefined ? {} : { parent_state_path: parentStatePath }),- ...(existing === undefined ? {} : { parent_revision_id: existing.revision_id }),- ...(parentRevisionPath === undefined ? {} : { parent_revision_path: parentRevisionPath }),- ...(parentRevisionDigest === undefined ? {} : { parent_revision_digest: parentRevisionDigest }),- ...(input.request === undefined ? {} : { request: input.request }),- intent_basis: intentBasis,- next_action: `complete ${REVISION_STEPS[0]}`,- created_at: now,- updated_at: now,- });-}--export async function checkpointRevisionState(input: RevisionCheckpointInput): Promise<RevisionState> {- const projectRoot = resolve(input.projectRoot);- const existing = await readRevisionState(projectRoot);- if (existing === undefined) throw new Error(`no revision state at ${revisionStatePath(projectRoot)}; run revision_state start first`);- if (input.request !== undefined && input.request !== existing.request) throw new Error("a revision request is immutable after revision_state start; start a new revision instead");- const step = stepNumber(input.step);- const artifacts = input.artifacts === undefined ? existing.artifacts : {- ...existing.artifacts,- ...Object.fromEntries(Object.entries(input.artifacts).map(([key, value]) => [key, resolve(projectRoot, value)])),- };- if (step === stepNumber("gates-checked") && input.status === "complete") {- const layout = artifacts.layout_check;- const value = layout === undefined ? undefined : await readFile(layout, "utf8").then((source) => JSON.parse(source) as { executed?: unknown; settled?: unknown }, () => undefined);- if (value?.executed !== true || value.settled !== true || !(await layoutEvidenceCurrent(layout))) {- throw new Error("gates-checked requires a successful layout_check whose candidates are repaired or explicitly accepted");- }- }- const completed = new Set(existing.completed_steps);- if (input.status === "complete") completed.add(step);- const completedSteps = [...completed].sort((a, b) => a - b);- const next = input.status === "complete" ? nextUncompleted(completedSteps) : step;- const now = new Date().toISOString();- const artifactDigests: Record<string, string> = { ...existing.artifact_digests };- for (const [key, value] of Object.entries(artifacts)) {- if (key !== "revision_request" && key !== "layout_check" && key !== "layout_decisions" && !value.includes(`${sep}.hypit${sep}evidence${sep}`)) continue;- const digest = await digestPath(value);- if (digest !== undefined) artifactDigests[key] = digest;- }- const decisions = input.decision === undefined || input.decision.trim().length === 0 || existing.decisions.includes(input.decision)- ? existing.decisions : [...existing.decisions, input.decision.trim()];- return writeRevisionState({- ...existing,- ...(input.run === undefined ? {} : { run: resolve(projectRoot, input.run) }),- ...(input.parentRoute === undefined ? {} : { parent_route: input.parentRoute }),- ...(input.parentStateDigest === undefined ? {} : { parent_state_digest: input.parentStateDigest }),- ...(input.impact === undefined ? {} : { impact: [...input.impact] }),- ...(input.affectedSource === undefined ? {} : { affected_source: [...input.affectedSource] }),- status: input.status === "blocked" ? "blocked" : next > REVISION_STEPS.length ? "complete" : "active",- current_step: next,- completed_steps: completedSteps,- in_progress: input.status === "in_progress" ? { step, started_at: now } : input.status === "complete" ? (next > REVISION_STEPS.length ? null : { step: next, started_at: now }) : existing.in_progress,- artifacts, artifact_digests: artifactDigests, decisions,- next_action: input.nextAction?.trim() || (next > REVISION_STEPS.length ? "revision complete" : `complete ${REVISION_STEPS[next - 1]}`),- ...(input.command === undefined ? {} : { last_command: input.command }),- ...(input.error === undefined ? {} : { last_error: input.error }),- updated_at: now,- });-}--async function fileExists(path: string | undefined): Promise<boolean> {- return path !== undefined && await stat(path).then((value) => value.isFile(), () => false);-}--async function layoutEvidenceCurrent(path: string | undefined): Promise<boolean> {- if (path === undefined) return false;- try {- const report = JSON.parse(await readFile(path, "utf8")) as { executed?: unknown; settled?: unknown; input_digests?: Record<string, unknown> };- if (report.executed !== true || report.settled !== true || report.input_digests === undefined) return false;- for (const [file, expected] of Object.entries(report.input_digests)) {- if (typeof expected !== "string" || await digestPath(file) !== expected) return false;- }- return true;- } catch { return false; }-}--/** Reconcile only machine-verifiable revision stages; creative mapping and review stay explicit. */-export async function reconcileRevisionState(projectRoot: string): Promise<RevisionState | undefined> {- const existing = await readRevisionState(projectRoot);- if (existing === undefined) return undefined;- const completed = new Set(existing.completed_steps);- const conflicts: string[] = [];- for (const [key, expected] of Object.entries(existing.artifact_digests)) {- const path = existing.artifacts[key];- const actual = path === undefined ? undefined : await digestPath(path);- if (actual !== expected) conflicts.push(`${key} digest changed: expected ${expected}, found ${actual ?? "missing"}`);- }- if (existing.parent_state_path !== undefined && existing.parent_state_digest !== undefined) {- const actual = await digestPath(existing.parent_state_path);- if (actual !== existing.parent_state_digest) conflicts.push(`parent route digest changed: expected ${existing.parent_state_digest}, found ${actual ?? "missing"}`);- }- if (existing.parent_revision_path !== undefined && existing.parent_revision_digest !== undefined) {- const actual = await digestPath(existing.parent_revision_path);- if (actual !== existing.parent_revision_digest) conflicts.push(`parent revision digest changed: expected ${existing.parent_revision_digest}, found ${actual ?? "missing"}`);- }- const checks: Readonly<Record<number, string>> = {- 1: "revision_request", 5: "gates_check", 6: "preview_render", 8: "final_check", 10: "build",- };- for (const [rawStep, key] of Object.entries(checks)) {- const step = Number(rawStep);- const present = await fileExists(existing.artifacts[key]);- const layoutSatisfied = step !== 5 || existing.status === "complete" || await (async () => {- const path = existing.artifacts.layout_check;- if (path === undefined) return false;- try {- const value = JSON.parse(await readFile(path, "utf8")) as { executed?: unknown; settled?: unknown };- return value.executed === true && value.settled === true && await layoutEvidenceCurrent(path);- } catch { return false; }- })();- if (present && layoutSatisfied) completed.add(step);- else if (completed.has(step)) { completed.delete(step); conflicts.push(`step ${step} (${key}) was marked complete but its evidence is missing`); }- }- // A later machine artifact cannot silently credit the manual intent/source stages.- const next = nextUncompleted([...completed]);- const now = new Date().toISOString();- const { conflicts: _old, ...base } = existing;- const state: RevisionState = {- ...base,- status: next > REVISION_STEPS.length ? "complete" : existing.status === "blocked" ? "blocked" : "active",- current_step: next,- completed_steps: [...completed].sort((a, b) => a - b),- in_progress: next > REVISION_STEPS.length ? null : { step: next, started_at: now },- next_action: next > REVISION_STEPS.length ? "revision complete" : `complete ${REVISION_STEPS[next - 1]}`,- ...(conflicts.length === 0 ? {} : { conflicts }),- updated_at: now,- };- const unchanged = state.status === existing.status- && state.current_step === existing.current_step- && JSON.stringify(state.completed_steps) === JSON.stringify(existing.completed_steps)- && JSON.stringify(state.conflicts ?? []) === JSON.stringify(existing.conflicts ?? [])- && state.next_action === existing.next_action;- return unchanged ? existing : writeRevisionState(state);-}diff --git a/packages/reference-video-tools/src/route-state.ts b/packages/reference-video-tools/src/route-state.tsdeleted file mode 100644index 87ce1fe3..00000000--- a/packages/reference-video-tools/src/route-state.ts+++ /dev/null@@ -1,701 +0,0 @@-import { readFile, stat } from "node:fs/promises";-import { join, resolve, sep } from "node:path";--import { digestPath, executionId, persistExecutionState } from "./state-files.js";--export type RouteKind = "reconstruction" | "description" | "variant" | "variant-package";-export type RouteStatus = "active" | "complete" | "blocked";-export type ReconstructionRouteStep =- | "environment" | "reference-prepared" | "reference-observed" | "vocabulary-checked"- | "package-ready" | "script-checked" | "source-authored" | "graph-checked" | "layout-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" | "layout-checked" | "review-planned"- | "preview-rendered" | "review-complete" | "repairs-complete" | "final-checked"- | "build-complete";-export type VariantRouteStep =- | "baseline-copied" | "brief-frozen" | "change-scope-frozen" | "guidance-loaded"- | "vocabulary-verified" | "package-ready" | "script-checked" | "source-updated"- | "graph-checked" | "layout-checked" | "final-checked" | "variant-complete";-export type VariantPackageRouteStep =- | "gap-confirmed" | "guidance-loaded" | "types-frozen" | "implemented"- | "vocabulary-inspected" | "package-validated" | "graph-checked" | "layout-checked" | "package-ready";-export type RouteStep = ReconstructionRouteStep | DescriptionRouteStep | VariantRouteStep | VariantPackageRouteStep;--export type RouteState = {- readonly version: 4;- readonly route_id: string;- readonly route: RouteKind;- readonly project_root: string;- readonly run?: string;- readonly reference_id?: string;- readonly status: RouteStatus;- readonly current_step: number;- readonly completed_steps: readonly number[];- readonly in_progress: { readonly step: number; readonly started_at: string } | null;- readonly artifacts: Readonly<Record<string, string>>;- readonly artifact_digests: Readonly<Record<string, string>>;- readonly decisions: readonly string[];- readonly next_action: string;- readonly last_command?: string;- readonly last_error?: string;- readonly conflicts?: readonly string[];- readonly created_at: string;- readonly updated_at: string;-};--export type RouteStateInput = {- readonly projectRoot: string;- readonly route: RouteKind;- readonly run?: string;- readonly referenceId?: string;-};--export type RouteCheckpointInput = RouteStateInput & {- readonly step: number | RouteStep;- readonly status?: "in_progress" | "complete" | "blocked";- readonly nextAction?: string;- readonly artifacts?: Readonly<Record<string, string>>;- readonly decision?: string;- readonly command?: string;- readonly error?: string;-};--export const COMPONENT_FIT_VERSION = 1 as const;-const COMPONENT_FIT_DECISIONS = new Set([- "reuse-existing",- "reuse-with-accepted-variance",- "project-local-package",-]);--export const ROUTE_STATE_VERSION = 4 as const;-const PREVIOUS_ROUTE_STATE_VERSION = 3 as const;-const EARLIER_ROUTE_STATE_VERSION = 2 as const;-const LEGACY_ROUTE_STATE_VERSION = 1 as const;-const LEGACY_ROUTE_STATE_STEPS: Readonly<Record<RouteKind, readonly string[]>> = {- reconstruction: [- "environment", "reference-prepared", "reference-observed", "source-authored", "graph-checked",- "review-planned", "preview-rendered", "comparison-complete", "repairs-complete", "final-checked", "build-complete",- ],- description: [- "environment", "brief-frozen", "source-authored", "vocabulary-checked", "graph-checked",- "review-planned", "preview-rendered", "review-complete", "repairs-complete", "final-checked", "build-complete",- ],- variant: [],- "variant-package": [],-};--export const ROUTE_STATE_STEPS: Readonly<Record<RouteKind, readonly string[]>> = {- reconstruction: [- "environment", "reference-prepared", "reference-observed", "vocabulary-checked", "package-ready",- "script-checked", "source-authored", "graph-checked", "layout-checked", "review-planned", "preview-rendered",- "comparison-complete", "repairs-complete", "final-checked", "build-complete",- ],- description: [- "environment", "brief-frozen", "vocabulary-checked", "package-ready", "script-checked", "source-authored",- "graph-checked", "layout-checked", "review-planned", "preview-rendered", "review-complete", "repairs-complete", "final-checked", "build-complete",- ],- variant: [- "baseline-copied", "brief-frozen", "change-scope-frozen", "guidance-loaded", "vocabulary-verified",- "package-ready", "script-checked", "source-updated", "graph-checked", "layout-checked", "final-checked", "variant-complete",- ],- "variant-package": [- "gap-confirmed", "guidance-loaded", "types-frozen", "implemented", "vocabulary-inspected",- "package-validated", "graph-checked", "layout-checked", "package-ready",- ],-};--const PREVIOUS_ROUTE_STATE_STEPS: Readonly<Record<RouteKind, readonly string[]>> = {- reconstruction: ["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"],- description: ["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"],- variant: ["baseline-copied", "brief-frozen", "change-scope-frozen", "guidance-loaded", "vocabulary-verified", "package-ready", "script-checked", "source-updated", "graph-checked", "final-checked", "variant-complete"],- "variant-package": ["gap-confirmed", "guidance-loaded", "types-frozen", "implemented", "vocabulary-inspected", "package-validated", "graph-checked", "package-ready"],-};--export function routeStatePath(projectRoot: string): string {- return join(resolve(projectRoot), ".hypit", "route-state.json");-}--export function componentFitPath(projectRoot: string): string {- return join(resolve(projectRoot), ".hypit", "component-fit.json");-}--export function routeExecutionStatePath(projectRoot: string, routeId: string): string {- return join(resolve(projectRoot), ".hypit", "routes", routeId, "state.json");-}--function isCreationRoute(route: RouteKind): route is "description" | "reconstruction" {- return route === "description" || route === "reconstruction";-}--function assertComponentFit(value: unknown, path: string, route: "description" | "reconstruction"): void {- if (value === null || typeof value !== "object" || Array.isArray(value)) {- throw new Error(`component fit at ${path} is not an object`);- }- const fit = value as {- version?: unknown;- route?: unknown;- basis?: unknown;- systems?: unknown;- };- if (fit.version !== COMPONENT_FIT_VERSION) throw new Error(`component fit at ${path} has unsupported version`);- if (fit.route !== route) throw new Error(`component fit at ${path} is for ${String(fit.route)}, not ${route}`);- if (typeof fit.basis !== "string" || fit.basis.trim().length === 0) throw new Error(`component fit at ${path} has no basis`);- if (!Array.isArray(fit.systems) || fit.systems.length === 0) throw new Error(`component fit at ${path} has no visual systems`);- for (const [index, value] of fit.systems.entries()) {- if (value === null || typeof value !== "object" || Array.isArray(value)) {- throw new Error(`component fit at ${path} has an invalid system at index ${index}`);- }- const system = value as {- role?: unknown;- inspected_candidates?: unknown;- selected_package?: unknown;- decision?: unknown;- rationale?: unknown;- accepted_variances?: unknown;- };- if (typeof system.role !== "string" || system.role.trim().length === 0) throw new Error(`component fit at ${path} system ${index} has no role`);- if (!Array.isArray(system.inspected_candidates) || system.inspected_candidates.some((item) => typeof item !== "string")) {- throw new Error(`component fit at ${path} system ${index} has invalid inspected_candidates`);- }- if (typeof system.selected_package !== "string" || system.selected_package.trim().length === 0) throw new Error(`component fit at ${path} system ${index} has no selected_package`);- if (typeof system.decision !== "string" || !COMPONENT_FIT_DECISIONS.has(system.decision)) throw new Error(`component fit at ${path} system ${index} has an invalid decision`);- if (typeof system.rationale !== "string" || system.rationale.trim().length === 0) throw new Error(`component fit at ${path} system ${index} has no rationale`);- if (!Array.isArray(system.accepted_variances)) throw new Error(`component fit at ${path} system ${index} has invalid accepted_variances`);- if (system.decision === "reuse-with-accepted-variance" && system.accepted_variances.length === 0) {- throw new Error(`component fit at ${path} system ${index} accepts variance but names none`);- }- if (system.decision !== "reuse-with-accepted-variance" && system.accepted_variances.length > 0) {- throw new Error(`component fit at ${path} system ${index} names variance for ${system.decision}`);- }- }-}--export async function componentFitSatisfied(projectRoot: string, route: RouteKind): Promise<boolean> {- if (!isCreationRoute(route)) return false;- const path = componentFitPath(projectRoot);- try {- assertComponentFit(JSON.parse(await readFile(path, "utf8")), path, route);- return true;- } catch {- return false;- }-}--function assertRouteState(value: unknown, path: string): asserts value is RouteState {- if (value === null || typeof value !== "object") throw new Error(`route state at ${path} is not an object`);- const state = value as Partial<RouteState>;- if (state.version !== ROUTE_STATE_VERSION) throw new Error(`route state at ${path} has unsupported version`);- if (typeof state.route_id !== "string" || state.route_id.length === 0) throw new Error(`route state at ${path} has no route_id`);- if (state.route !== "reconstruction" && state.route !== "description" && state.route !== "variant" && state.route !== "variant-package") throw new Error(`route state at ${path} has an invalid route`);- if (typeof state.project_root !== "string" || state.project_root.length === 0) throw new Error(`route state at ${path} has no project_root`);- if (typeof state.status !== "string" || !["active", "complete", "blocked"].includes(state.status)) throw new Error(`route state at ${path} has an invalid status`);- const currentStep = state.current_step;- if (typeof currentStep !== "number" || !Number.isSafeInteger(currentStep) || currentStep < 1 || currentStep > ROUTE_STATE_STEPS[state.route].length + 1) throw new Error(`route state at ${path} has an invalid current_step`);- if (!Array.isArray(state.completed_steps) || state.completed_steps.some((step) => !Number.isSafeInteger(step) || step < 1)) throw new Error(`route state at ${path} has invalid completed_steps`);- if (state.in_progress !== null && (state.in_progress === undefined || typeof state.in_progress !== "object" || !Number.isSafeInteger(state.in_progress.step))) throw new Error(`route state at ${path} has invalid in_progress`);- if (state.artifacts === null || typeof state.artifacts !== "object" || Array.isArray(state.artifacts)) throw new Error(`route state at ${path} has invalid artifacts`);- if (state.artifact_digests === null || typeof state.artifact_digests !== "object" || Array.isArray(state.artifact_digests)) throw new Error(`route state at ${path} has invalid artifact_digests`);- if (!Array.isArray(state.decisions) || state.decisions.some((item) => typeof item !== "string")) throw new Error(`route state at ${path} has invalid decisions`);- if (state.conflicts !== undefined && (!Array.isArray(state.conflicts) || state.conflicts.some((item) => typeof item !== "string"))) throw new Error(`route state at ${path} has invalid conflicts`);- if (typeof state.next_action !== "string" || typeof state.created_at !== "string" || typeof state.updated_at !== "string") throw new Error(`route state at ${path} is missing recovery fields`);-}--function migrateLegacyRouteState(value: unknown, path: string): RouteState | undefined {- if (value === null || typeof value !== "object") return undefined;- const version = (value as { version?: unknown }).version;- if (version === PREVIOUS_ROUTE_STATE_VERSION) {- const previous = value as Omit<RouteState, "version" | "completed_steps" | "current_step" | "in_progress"> & {- readonly version: 3;- readonly completed_steps: readonly number[];- readonly current_step: number;- readonly in_progress: { readonly step: number; readonly started_at: string } | null;- };- const names = previous.completed_steps.map((step) => PREVIOUS_ROUTE_STATE_STEPS[previous.route][step - 1]).filter((name): name is string => name !== undefined);- const completed = previous.status === "complete"- ? ROUTE_STATE_STEPS[previous.route].map((_name, index) => index + 1)- : names.flatMap((name) => {- const index = ROUTE_STATE_STEPS[previous.route].indexOf(name);- return index < 0 ? [] : [index + 1];- });- const currentStep = nextUncompleted(previous.route, completed);- return {- ...previous,- version: ROUTE_STATE_VERSION,- current_step: currentStep,- completed_steps: completed,- in_progress: currentStep > ROUTE_STATE_STEPS[previous.route].length ? null : { step: currentStep, started_at: previous.updated_at },- next_action: currentStep > ROUTE_STATE_STEPS[previous.route].length ? "route complete" : `complete ${ROUTE_STATE_STEPS[previous.route][currentStep - 1]}`,- };- }- if (version === EARLIER_ROUTE_STATE_VERSION) {- const previous = value as Omit<RouteState, "version" | "route_id" | "artifact_digests" | "created_at" | "completed_steps" | "current_step" | "in_progress"> & {- readonly version: 2;- readonly completed_steps: readonly number[];- readonly current_step: number;- readonly in_progress: { readonly step: number; readonly started_at: string } | null;- };- const createdAt = typeof previous.updated_at === "string" ? previous.updated_at : new Date().toISOString();- const names = previous.completed_steps.map((step) => PREVIOUS_ROUTE_STATE_STEPS[previous.route][step - 1]).filter((name): name is string => name !== undefined);- const completed = previous.status === "complete"- ? ROUTE_STATE_STEPS[previous.route].map((_name, index) => index + 1)- : names.flatMap((name) => {- const index = ROUTE_STATE_STEPS[previous.route].indexOf(name);- return index < 0 ? [] : [index + 1];- });- const currentStep = nextUncompleted(previous.route, completed);- return {- ...previous,- version: ROUTE_STATE_VERSION,- route_id: executionId(previous.route ?? "route"),- artifact_digests: {},- created_at: createdAt,- current_step: currentStep,- completed_steps: completed,- in_progress: currentStep > ROUTE_STATE_STEPS[previous.route].length ? null : { step: currentStep, started_at: createdAt },- next_action: currentStep > ROUTE_STATE_STEPS[previous.route].length ? "route complete" : `complete ${ROUTE_STATE_STEPS[previous.route][currentStep - 1]}`,- };- }- if (version !== LEGACY_ROUTE_STATE_VERSION) return undefined;- const legacy = value as Partial<RouteState>;- if (legacy.route !== "reconstruction" && legacy.route !== "description") throw new Error(`route state at ${path} has an invalid route`);- const route = legacy.route;- 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[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);- 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(route, completed);- const now = new Date().toISOString();- return {- version: ROUTE_STATE_VERSION,- route_id: executionId(route),- route,- project_root: legacy.project_root!,- ...(legacy.run === undefined ? {} : { run: legacy.run }),- ...(legacy.reference_id === undefined ? {} : { reference_id: legacy.reference_id }),- 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[route].length ? null : { step: currentStep, started_at: now },- artifacts: legacy.artifacts ?? {},- artifact_digests: {},- decisions: legacy.decisions ?? [],- // Legacy prose may point past the newly inserted gates; always derive the recovery action from- // the first unmet v2 stage instead of carrying that stale cursor forward.- 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 }),- created_at: now,- updated_at: now,- };-}--export async function readRouteState(projectRoot: string): Promise<RouteState | undefined> {- const path = routeStatePath(projectRoot);- const text = await readFile(path, "utf8").catch((error: unknown) => {- if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;- throw error;- });- if (text === undefined) return undefined;- let parsed: unknown;- try { parsed = JSON.parse(text); } catch (error) {- throw new Error(`route state at ${path} is invalid JSON; original file was preserved: ${error instanceof Error ? error.message : String(error)}`);- }- const migrated = migrateLegacyRouteState(parsed, path);- if (migrated !== undefined) {- await writeRouteState(migrated);- return migrated;- }- assertRouteState(parsed, path);- return parsed;-}--async function writeRouteState(state: RouteState): Promise<RouteState> {- await persistExecutionState(state.project_root, "route-state.json", "routes", state.route_id, state);- return state;-}--function nextUncompleted(route: RouteKind, completed: readonly number[]): number {- const done = new Set(completed);- const steps = ROUTE_STATE_STEPS[route];- for (let step = 1; step <= steps.length; step += 1) if (!done.has(step)) return step;- return steps.length + 1;-}--function stageNumber(route: RouteKind, name: string): number {- const index = ROUTE_STATE_STEPS[route].indexOf(name);- if (index < 0) throw new Error(`route ${route} has no ${name} stage`);- return index + 1;-}--const SCALAR_ARTIFACT_KEYS = new Set(["observer", "timing_basis", "timingBasis", "mode", "status"]);-function normalizeArtifact(projectRoot: string, key: string, value: string): string {- // Artifact maps historically accepted strings for both file references and tiny metadata values.- // Preserve the latter; resolving `observer: "gemini"` as a filesystem path corrupts the snapshot.- return SCALAR_ARTIFACT_KEYS.has(key) ? value : resolve(projectRoot, value);-}--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 {- const sourceStage = route === "variant" ? "source-updated"- : route === "variant-package" ? "implemented" : "source-authored";- if (step !== stageNumber(route, sourceStage)) return;- const required = route === "variant"- ? ["vocabulary-verified", "package-ready", "script-checked"]- : route === "variant-package" ? [] : ["vocabulary-checked", "package-ready", "script-checked"];- const requiredSteps = required- .map((name) => stageNumber(route, name));- const missing = requiredSteps.filter((item) => !completed.has(item));- if (missing.length > 0) {- const names = missing.map((item) => ROUTE_STATE_STEPS[route][item - 1]).join(", ");- throw new Error(`${sourceStage} cannot be completed before ${names}`);- }-}--export async function startRouteState(input: RouteStateInput): Promise<RouteState> {- const projectRoot = resolve(input.projectRoot);- const existing = await readRouteState(projectRoot);- if (existing !== undefined && existing.status !== "complete" && (existing.route !== input.route || existing.project_root !== projectRoot)) {- throw new Error(`project already has an active ${existing.route} route at ${routeStatePath(projectRoot)}`);- }- if (existing !== undefined && existing.status !== "complete" && existing.route === input.route) return existing;- const now = new Date().toISOString();- return await writeRouteState({- version: ROUTE_STATE_VERSION,- route_id: executionId(input.route),- route: input.route,- project_root: projectRoot,- ...(input.run === undefined ? {} : { run: resolve(projectRoot, input.run) }),- ...(input.referenceId === undefined ? {} : { reference_id: input.referenceId }),- status: "active",- current_step: 1,- completed_steps: [],- in_progress: { step: 1, started_at: now },- artifacts: existing?.artifacts.brief === undefined ? {} : { brief: existing.artifacts.brief },- artifact_digests: existing?.artifact_digests.brief === undefined ? {} : { brief: existing.artifact_digests.brief },- decisions: [],- next_action: `complete ${ROUTE_STATE_STEPS[input.route][0]}`,- created_at: now,- updated_at: now,- });-}--export async function checkpointRouteState(input: RouteCheckpointInput): Promise<RouteState> {- const projectRoot = resolve(input.projectRoot);- const existing = await readRouteState(projectRoot);- if (existing === undefined) throw new Error(`no route state at ${routeStatePath(projectRoot)}; run route_state start first`);- if (existing.route !== input.route) throw new Error(`route state is ${existing.route}, not ${input.route}`);- if (existing.status === "complete") throw new Error(`route ${existing.route_id} is complete; start a new route instead of rewriting its history`);- const step = stepNumber(input.route, input.step);- const completed = new Set(existing.completed_steps);- const status = input.status ?? "complete";- const artifacts = input.artifacts === undefined ? existing.artifacts : {- ...existing.artifacts,- ...Object.fromEntries(- Object.entries(input.artifacts).map(([key, value]) => [key, normalizeArtifact(projectRoot, key, value)]),- ),- };- if (input.artifacts?.component_fit !== undefined- && (!isCreationRoute(input.route) || step !== stageNumber(input.route, "vocabulary-checked"))) {- throw new Error("component_fit may be checkpointed only with vocabulary-checked on a creation route");- }- if (input.route === "description" && step === stageNumber("description", "brief-frozen") && status === "complete") {- const brief = artifacts.brief;- const canonical = join(projectRoot, ".hypit", "brief.json");- if (brief === undefined || resolve(projectRoot, brief) !== canonical) {- throw new Error(`brief-frozen requires the canonical brief at ${canonical}`);- }- let parsedBrief: unknown;- try { parsedBrief = JSON.parse(await readFile(canonical, "utf8")); }- catch (error) { throw new Error(`brief-frozen requires valid JSON at ${canonical}: ${error instanceof Error ? error.message : String(error)}`); }- if (parsedBrief === null || typeof parsedBrief !== "object" || Array.isArray(parsedBrief)) throw new Error(`brief-frozen requires a JSON object at ${canonical}`);- const actualDigest = await digestPath(canonical);- const frozenDigest = existing.artifact_digests.brief;- if (frozenDigest !== undefined && actualDigest !== frozenDigest) {- throw new Error(`the frozen base brief changed: expected ${frozenDigest}, found ${actualDigest ?? "missing"}; use Revision or a new project`);- }- }- if (isCreationRoute(input.route) && step === stageNumber(input.route, "vocabulary-checked")) {- const canonical = componentFitPath(projectRoot);- const fit = artifacts.component_fit;- if (fit !== undefined && fit !== canonical) throw new Error(`component fit must use the canonical path ${canonical}`);- if (fit !== undefined && !(await componentFitSatisfied(projectRoot, input.route))) {- throw new Error(`component fit at ${canonical} is missing or invalid`);- }- const frozenDigest = existing.artifact_digests.component_fit;- const actualDigest = fit === undefined ? undefined : await digestPath(canonical);- if (completed.has(step) && frozenDigest !== undefined && actualDigest !== frozenDigest) {- throw new Error("component fit changed after it was frozen; run route_state reconcile before reclassifying it");- }- if (status === "complete") {- if (!(await evidenceSatisfied("vocabulary", artifacts.vocabulary))) {- throw new Error("vocabulary-checked requires valid Run-scoped vocabulary evidence");- }- if (fit !== canonical || !(await componentFitSatisfied(projectRoot, input.route))) {- throw new Error(`vocabulary-checked requires the canonical component fit at ${canonical}`);- }- }- }- 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 = 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- : [...existing.decisions, input.decision.trim()];- const artifactDigests: Record<string, string> = { ...existing.artifact_digests };- const frozenKeys = new Set(["brief", "vocabulary", "component_fit", "baseline_manifest", "variant_brief", "allowed_changes", "guidance", "gap_plan", "types", "package_digest", "layout_check", "layout_decisions"]);- for (const [key, value] of Object.entries(artifacts)) {- if (!frozenKeys.has(key) && !value.includes(`${sep}.hypit${sep}evidence${sep}`)) continue;- if (key === "component_fit" && input.artifacts?.component_fit === undefined) continue;- const digest = await digestPath(value);- if (digest !== undefined) artifactDigests[key] = digest;- }- const state: RouteState = {- ...existing,- ...(input.run === undefined ? {} : { run: resolve(projectRoot, input.run) }),- ...(input.referenceId === undefined ? {} : { reference_id: input.referenceId }),- status: status === "blocked" ? "blocked" : next > ROUTE_STATE_STEPS[input.route].length ? "complete" : "active",- current_step: next,- completed_steps: completedSteps,- 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,- artifact_digests: artifactDigests,- decisions,- next_action: input.nextAction?.trim()- || (next > ROUTE_STATE_STEPS[input.route].length ? "route complete" : `complete ${ROUTE_STATE_STEPS[input.route][next - 1]}`),- ...(input.command === undefined ? {} : { last_command: input.command }),- ...(input.error === undefined ? {} : { last_error: input.error }),- updated_at: now,- };- return await writeRouteState(state);-}--async function exists(path: string | undefined): Promise<boolean> {- if (path === undefined) return false;- return await stat(path).then(() => true, () => false);-}--async function evidenceSatisfied(key: string, path: string | undefined): Promise<boolean> {- if (!(await exists(path)) || path === undefined) return false;- // Check artifacts are written as JSON by the route-aware commands. Reconcile deliberately- // verifies their success predicate instead of treating a stale/failing report as completion.- if (key === "preview_check") {- try {- const value = JSON.parse(await readFile(path, "utf8")) as { sound?: unknown };- return value.sound === true;- } catch { return false; }- }- if (key === "package_ready" || key === "script_cues" || key === "vocabulary") {- try {- const value = JSON.parse(await readFile(path, "utf8")) as { passed?: unknown; surfaces?: unknown[]; packages?: unknown[] };- if ((value as { waived?: unknown }).waived === true- && typeof (value as { diagnosis?: unknown }).diagnosis === "string"- && ((value as { diagnosis?: string }).diagnosis?.trim().length ?? 0) > 0) return true;- if (key === "vocabulary") return Array.isArray(value.surfaces) || Array.isArray(value.packages);- return value.passed === true;- } catch { return false; }- }- if (key === "brief") {- try {- const value = JSON.parse(await readFile(path, "utf8"));- return value !== null && typeof value === "object" && !Array.isArray(value);- } catch { return false; }- }- if (key === "final_check") {- try {- const value = JSON.parse(await readFile(path, "utf8")) as { passed?: unknown };- return value.passed === true;- } catch { return false; }- }- if (key === "layout_check") {- try {- const value = JSON.parse(await readFile(path, "utf8")) as { executed?: unknown; settled?: unknown };- return value.executed === true && value.settled === true;- } catch { return false; }- }- if (key === "comparison_log" || key === "review_log") {- try {- const lines = (await readFile(path, "utf8")).split("\n").filter((line) => line.trim().length > 0);- return lines.some((line) => {- try {- const value = JSON.parse(line) as { status?: unknown };- return value.status === "complete";- } catch { return false; }- });- } catch { return false; }- }- if (key === "reference_state") {- try {- const value = JSON.parse(await readFile(path, "utf8")) as { shots?: unknown; video?: unknown };- return Array.isArray(value.shots) && value.video !== undefined;- } catch { return false; }- }- if (key === "reference_observations") {- try {- const value = JSON.parse(await readFile(path, "utf8")) as Record<string, { status?: unknown }>;- const entries = Object.values(value);- return entries.length > 0 && entries.every((item) => item?.status === "complete");- } catch { return false; }- }- return true;-}--async function layoutEvidenceCurrent(path: string | undefined): Promise<boolean> {- if (path === undefined) return false;- try {- const report = JSON.parse(await readFile(path, "utf8")) as { executed?: unknown; settled?: unknown; input_digests?: Record<string, unknown> };- if (report.executed !== true || report.settled !== true || report.input_digests === undefined) return false;- for (const [file, expected] of Object.entries(report.input_digests)) {- if (typeof expected !== "string" || await digestPath(file) !== expected) return false;- }- return true;- } catch { return false; }-}--/** Reconcile a snapshot with the small, durable evidence pointers it records. */-export async function reconcileRouteState(projectRoot: string): Promise<RouteState | undefined> {- const existing = await readRouteState(projectRoot);- if (existing === undefined) return undefined;- const completed = new Set(existing.completed_steps);- const conflicts: string[] = [];- for (const [key, expected] of Object.entries(existing.artifact_digests)) {- const path = existing.artifacts[key];- const actual = path === undefined ? undefined : await digestPath(path);- if (actual !== expected) conflicts.push(`${key} digest changed: expected ${expected}, found ${actual ?? "missing"}`);- }- const artifact = (name: string): string | undefined => existing.artifacts[name];- const reconcileStep = async (step: number, key: string): Promise<void> => {- const renderComplete = key === "preview_render"- ? await evidenceSatisfied("render_sidecar", artifact("render_sidecar"))- : true;- const satisfied = renderComplete && await evidenceSatisfied(key, artifact(key))- && (key !== "layout_check" || await layoutEvidenceCurrent(artifact(key)));- if (satisfied) completed.add(step);- else {- if (completed.has(step)) conflicts.push(`step ${step} (${key}) was marked complete but its evidence is missing or failed`);- completed.delete(step);- }- };- const evidenceByStep: Readonly<Record<RouteKind, Readonly<Record<number, string>>>> = {- reconstruction: {- 2: "reference_state", 3: "reference_observations", 4: "vocabulary", 5: "package_ready", 6: "script_cues",- 7: "author_source", 8: "preview_check", 9: "layout_check", 10: "review_plan", 11: "preview_render", 12: "comparison_log", 14: "final_check", 15: "build",- },- description: {- 2: "brief", 3: "vocabulary", 4: "package_ready", 5: "script_cues", 6: "author_source", 7: "preview_check",- 8: "layout_check", 9: "review_plan", 10: "preview_render", 11: "review_log", 13: "final_check", 14: "build",- },- variant: {- 1: "baseline_manifest", 2: "variant_brief", 3: "allowed_changes", 4: "guidance",- 5: "vocabulary", 6: "package_ready", 7: "script_cues", 8: "author_source",- 9: "preview_check", 10: "layout_check", 11: "variant_check", 12: "variant_check",- },- "variant-package": {- 1: "gap_plan", 2: "guidance", 3: "types", 4: "package_source", 5: "vocabulary",- 6: "package_ready", 7: "preview_check", 8: "layout_check", 9: "package_digest",- },- };- for (const [step, key] of Object.entries(evidenceByStep[existing.route])) {- await reconcileStep(Number(step), key);- }- if (existing.status !== "complete" && isCreationRoute(existing.route)) {- const vocabularyStep = stageNumber(existing.route, "vocabulary-checked");- const canonical = componentFitPath(existing.project_root);- const fitPath = artifact("component_fit");- const expectedDigest = existing.artifact_digests.component_fit;- const actualDigest = fitPath === undefined ? undefined : await digestPath(fitPath);- const fitSatisfied = fitPath === canonical- && await componentFitSatisfied(existing.project_root, existing.route)- && expectedDigest !== undefined- && actualDigest === expectedDigest;- if (!fitSatisfied) {- if (completed.has(vocabularyStep)) {- conflicts.push(`step ${vocabularyStep} (vocabulary-checked) has no valid frozen component fit`);- }- for (let step = vocabularyStep; step <= ROUTE_STATE_STEPS[existing.route].length; step += 1) completed.delete(step);- }- }- if (existing.route !== "variant-package") {- const sourceName = existing.route === "variant" ? "source-updated" : "source-authored";- const vocabularyName = existing.route === "variant" ? "vocabulary-verified" : "vocabulary-checked";- const sourceStep = stageNumber(existing.route, sourceName);- const gateSteps = [vocabularyName, "package-ready", "script-checked"]- .map((name) => stageNumber(existing.route, name));- if (completed.has(sourceStep) && gateSteps.some((step) => !completed.has(step))) {- conflicts.push(`step ${sourceStep} (${sourceName}) was marked complete before vocabulary/package/Script gates`);- completed.delete(sourceStep);- }- }- const completedSteps = [...completed].sort((a, b) => a - b);- const next = nextUncompleted(existing.route, completedSteps);- const now = new Date().toISOString();- const { conflicts: _oldConflicts, ...withoutConflicts } = existing;- const state: RouteState = {- ...withoutConflicts,- status: next > ROUTE_STATE_STEPS[existing.route].length ? "complete" : existing.status === "blocked" ? "blocked" : "active",- current_step: next,- completed_steps: completedSteps,- in_progress: next > ROUTE_STATE_STEPS[existing.route].length ? null : { step: next, started_at: now },- next_action: next > ROUTE_STATE_STEPS[existing.route].length ? "route complete" : `complete ${ROUTE_STATE_STEPS[existing.route][next - 1]}`,- ...(conflicts.length === 0 ? {} : { conflicts }),- updated_at: now,- };- const unchanged = state.status === existing.status- && state.current_step === existing.current_step- && JSON.stringify(state.completed_steps) === JSON.stringify(existing.completed_steps)- && JSON.stringify(state.conflicts ?? []) === JSON.stringify(existing.conflicts ?? [])- && state.next_action === existing.next_action;- return unchanged ? existing : await writeRouteState(state);-}diff --git a/packages/reference-video-tools/src/contract.ts b/packages/reference-video-tools/src/schema.tssimilarity index 72%rename from packages/reference-video-tools/src/contract.tsrename to packages/reference-video-tools/src/schema.tsindex 177e2fa2..8934a3e5 100644--- a/packages/reference-video-tools/src/contract.ts+++ b/packages/reference-video-tools/src/schema.ts@@ -1,17 +1,6 @@import type { ValueSchema } from "@hypit/protocol";-/**- * Read a declared shape back as prose an author can act on.- *- * A package that draws returns a Visual Track from its Producer, and every field on it — which- * element kinds exist, which style names are admitted, which of them take an enum, how few keyframes- * an animation may have — is declared in `composition`'s own schema. Nothing read that schema, so the- * only way to learn the shape was to open another package and copy it, which is how a component gets- * written against one example's habits rather than against the contract.- *- * This renders the schema instead. It is generated from the declaration, so it cannot say something- * the code does not.- */+/** Render a declared value shape as prose an author can act on. */export function describeSchema(schema: ValueSchema, indent = ""): string[] {const step = `${indent} `;switch (schema.kind) {@@ -26,8 +15,6 @@ export function describeSchema(schema: ValueSchema, indent = ""): string[] {return lines;}case "oneOf": {- // A union of objects each pinned by one literal is how the schema spells "these kinds"; naming- // the discriminating values is more use than printing every variant in full.const pinned = schema.variants.map((variant) => {if (variant.kind !== "object") return undefined;const literal = Object.entries(variant.fields)diff --git a/packages/reference-video-tools/src/state-files.ts b/packages/reference-video-tools/src/state-files.tsdeleted file mode 100644index fc1ea48c..00000000--- a/packages/reference-video-tools/src/state-files.ts+++ /dev/null@@ -1,66 +0,0 @@-import { createHash, randomUUID } from "node:crypto";-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";-import { dirname, join, resolve } from "node:path";--export function executionId(kind: string, now = new Date()): string {- const timestamp = now.toISOString().replace(/[-:]/gu, "").replace(/\.\d{3}Z$/u, "Z");- return `${kind}-${timestamp}-${randomUUID().slice(0, 8)}`;-}--export function jsonBytes(value: unknown): Buffer {- return Buffer.from(`${JSON.stringify(value, null, 2)}\n`, "utf8");-}--export function sha256(bytes: Uint8Array): string {- return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;-}--export async function digestPath(path: string): Promise<string | undefined> {- const bytes = await readFile(path).catch(() => undefined);- return bytes === undefined ? undefined : sha256(bytes);-}--export async function atomicWrite(path: string, bytes: Uint8Array): Promise<void> {- await mkdir(dirname(path), { recursive: true });- const temporary = `${path}.tmp-${process.pid}-${Date.now()}-${randomUUID().slice(0, 8)}`;- await writeFile(temporary, bytes);- await rename(temporary, path);-}--export async function atomicJson(path: string, value: unknown): Promise<void> {- await atomicWrite(path, jsonBytes(value));-}--export async function persistExecutionState(- projectRoot: string,- currentName: string,- historyKind: "routes" | "revisions",- executionIdValue: string,- value: unknown,-): Promise<string> {- const root = resolve(projectRoot);- const historyPath = join(root, ".hypit", historyKind, executionIdValue, "state.json");- const bytes = jsonBytes(value);- await atomicWrite(historyPath, bytes);- await atomicWrite(join(root, ".hypit", currentName), bytes);- return historyPath;-}--export async function persistEvidence(- projectRoot: string,- currentName: string,- value: unknown,-): Promise<string> {- const root = resolve(projectRoot);- const bytes = jsonBytes(value);- const digest = sha256(bytes).slice("sha256:".length);- const evidencePath = join(root, ".hypit", "evidence", digest, currentName);- await mkdir(dirname(evidencePath), { recursive: true });- await writeFile(evidencePath, bytes, { flag: "wx" }).catch(async (error: unknown) => {- if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;- const existing = await readFile(evidencePath);- if (!existing.equals(bytes)) throw new Error(`immutable evidence collision at ${evidencePath}`);- });- await atomicWrite(join(root, ".hypit", currentName), bytes);- return evidencePath;-}diff --git a/packages/reference-video-tools/src/tools.ts b/packages/reference-video-tools/src/tools.tsindex 8a0b8041..d3f5dd38 100644--- a/packages/reference-video-tools/src/tools.ts+++ b/packages/reference-video-tools/src/tools.ts@@ -1,7 +1,6 @@import { access, appendFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";import { spawn } from "node:child_process";import { cpus } from "node:os";-import { createHash } from "node:crypto";import { deflateSync } from "node:zlib";import { basename, dirname, join, resolve } from "node:path";import { loadNodePackageSelection, locateNodePackage, physicalPackageName } from "@hypit/package-loader-node";@@ -18,7 +17,7 @@ import {} from "@hypit/composition";import { VISUAL_STYLE_ENUM_VALUES_V1, VISUAL_STYLE_NAMES_V1 } from "@hypit/visual-ir";-import { describeSchema } from "./contract.js";+import { describeSchema } from "./schema.js";import { videoCliDistribution } from "@hypit/video-cli";import { createHypiHubGeminiGenerator } from "@hypit/provider-hypihub";import { createVertexGeminiGenerator } from "@hypit/provider-vertex";@@ -28,62 +27,13 @@ import { authorSource, invokedFrom, nearestPackageRoot, referenceRoot, referenceimport type { RenderElementInput, RenderPreviewsInput, SpokenRange, StandInFocus, StandInSidecar } from "./authoring.js";import { downloadReferenceVideo, isReferenceUrl } from "@hypit/yt-dlp";import { loadStudioCompanionRegistry } from "@hypit/studio/src/companion-profile.js";-import { openStudioArchive } from "@hypit/studio/src/archive.js";+import { openStudioBuildLibrary } from "@hypit/studio/src/build-library.js";import { loadStudioDomain } from "@hypit/studio/src/domain.js";import { loadStudioRun } from "@hypit/studio/src/run.js";-import { authoringCheck, mechanicalAuthoringCheck, previewCheck, reviewLogPath, scriptCueCheck } from "./checks.js";+import { authoringCheck, previewCheck, reviewLogPath, scriptCueCheck } from "./checks.js";import type { AuthoringCheckInput, PreviewCheckInput, ReconstructionCheckInput, ScriptCueCheckInput } from "./checks.js";-import {- checkpointRouteState,- componentFitPath,- componentFitSatisfied,- readRouteState,- reconcileRouteState,- routeExecutionStatePath,- routeStatePath,- startRouteState,- 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,- reconcileRevisionState,- revisionExecutionStatePath,- revisionRequestPath,- revisionStatePath,- startRevisionState,-} from "./revision-state.js";-import type { RevisionParentRoute, RevisionState, RevisionStep } from "./revision-state.js";-import { persistEvidence } from "./state-files.js";import { layoutAccept, layoutCheck } from "./layout.js";import type { LayoutAcceptInput, LayoutCheckInput } from "./layout.js";-import {- checkpointVariantExpansion,- discoverVariantExpansions,- readVariantExpansionState,- reconcileVariantExpansion,- startVariantExpansion,- variantExpansionStatePath,- VARIANT_EXPANSION_STEPS,-} from "./variant-state.js";-import type {- VariantExpansionCheckpointInput,- VariantExpansionPackage,- VariantExpansionStep,- VariantExpansionVariant,- VariantWorkloadDisclosure,-} from "./variant-state.js";-import {- findGeneratedLeakage,- initializeVariantProjects,- inspectSourceVocabularyUsage,- inspectVariantDiff,- snapshotProject,- writeVariantJson,-} from "./variant-project.js";-import type { ApprovedVariantPackage, VariantProjectManifest } from "./variant-project.js";import {assert,completelyStill,@@ -123,7 +73,7 @@ export type ObserveReferenceInput = {};export type RecordObservationInput = {readonly reference_id: string;- /** Optional Run used to persist reconstruction route progress after an out-of-band answer. */+ /** Optional Run used to place comparison observations beside the project that requested them. */readonly run?: string;readonly key?: string;readonly text?: string;@@ -176,7 +126,7 @@ export type CompareReconstructionInput = {readonly question?: string;/*** Names the reconstructed element this image draws, for the comparison log only. It is never sent- * to the observer: the comparison stays blind, and this is what lets a later gate tell which+ * to the observer: the comparison stays blind, and this is what lets a later report tell which* elements have been compared and which have never been looked at.*/readonly element?: string;@@ -196,7 +146,7 @@ export type CompareReconstructionInput = {* The counterpart of `compare_reconstruction` on the route with no reference. There is nothing to* differ from, so the question is conformance: does the picture match the description, and what is* visibly wrong with it. That makes it one-sided, which is the only structural difference — the- * render is prepared the same way, the log has the same shape, and the same gate reads it.+ * render is prepared the same way, the log has the same shape, and the same report reads it.** There is no observer choice here. The picture is a local render and nobody is billed to look at it,* so the task always comes back to be answered rather than being sent anywhere.@@ -237,25 +187,6 @@ export type RecordReviewInput = {readonly text: string;};-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 | 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?: RevisionParentRoute; readonly parent_state_digest?: string; readonly request?: string })- | ({ readonly action: "read" | "reconcile"; readonly project_root: string })- | ({ readonly action: "checkpoint"; readonly project_root: string; readonly step: number | RevisionStep; readonly status?: "in_progress" | "complete" | "blocked"; readonly run?: string; readonly parent_route?: RevisionParentRoute; readonly parent_state_digest?: string; readonly request?: string; readonly next_action?: string; readonly artifacts?: Readonly<Record<string, string>>; readonly decision?: string; readonly command?: string; readonly error?: string; readonly impact?: readonly string[]; readonly affected_source?: readonly string[] });--export type VariantStateCommandInput =- | ({ readonly action: "discover"; readonly project_root: string })- | ({ readonly action: "start"; readonly project_root: string; readonly output_root: string; readonly run?: string; readonly request?: string; readonly count?: number; readonly delivery_mode?: "source" | "build"; readonly parent_route?: "reconstruction" | "description" | "variant"; readonly parent_state_digest?: string; readonly revision_state_digest?: string })- | ({ readonly action: "read" | "reconcile"; readonly project_root: string; readonly output_root?: string; readonly batch_id?: string })- | ({ readonly action: "checkpoint"; readonly project_root: string; readonly output_root?: string; readonly batch_id?: string; readonly step: number | VariantExpansionStep; readonly status?: "in_progress" | "complete" | "blocked"; readonly next_action?: string; readonly artifacts?: Readonly<Record<string, string>>; readonly workload_disclosure?: VariantWorkloadDisclosure; readonly packages?: readonly VariantExpansionPackage[]; readonly variants?: readonly VariantExpansionVariant[]; readonly decision?: string; readonly conflict?: string; readonly resolve_conflict?: string; readonly command?: string; readonly error?: string });--export type VariantInitInput = { readonly project_root: string; readonly output_root: string; readonly slate: string };-export type VariantCheckInput = { readonly run: string; readonly runtime?: string };-export type { RenderElementInput, RenderPreviewsInput } from "./authoring.js";export type { PreviewCheckInput, ReconstructionCheckInput } from "./checks.js";@@ -266,7 +197,7 @@ export type ReferenceVideoTools = {inspect_svml_vocabulary(input: InspectVocabularyInput): Promise<Record<string, unknown>>;validate_local_author_packages(input: ValidateLocalAuthorPackagesInput): Promise<Record<string, unknown>>;validate_script_cues(input: ScriptCueCheckInput): Promise<Record<string, unknown>>;- inspect_visual_contract(input: { readonly shape?: string; readonly producers?: readonly string[] }): Promise<Record<string, unknown>>;+ inspect_visual_schema(input: { readonly shape?: string; readonly producers?: readonly string[] }): Promise<Record<string, unknown>>;paths(): Promise<Record<string, unknown>>;compare_reconstruction(input: CompareReconstructionInput): Promise<Record<string, unknown>>;record_observation(input: RecordObservationInput): Promise<Record<string, unknown>>;@@ -278,18 +209,8 @@ export type ReferenceVideoTools = {layout_check(input: LayoutCheckInput): Promise<Record<string, unknown>>;layout_accept(input: LayoutAcceptInput): Promise<Record<string, unknown>>;reconstruction_check(input: ReconstructionCheckInput): Promise<Record<string, unknown>>;- /**- * The same gate for a program authored from a description. It resolves no reference, credits an- * element from the project's own review log, and refuses on everything the Source alone decides —- * an uncovered stretch, a Frame past the Canvas, a `playback` left at its default — all of which- * were unreachable to this route while the check began by demanding a reference.- */+ /** The corresponding direct report for a program authored from a description. */authoring_check(input: Omit<AuthoringCheckInput, "mode" | "reference_id">): Promise<Record<string, unknown>>;- route_state(input: RouteStateCommandInput): Promise<Record<string, unknown>>;- revision_state(input: RevisionStateCommandInput): Promise<Record<string, unknown>>;- variant_state(input: VariantStateCommandInput): Promise<Record<string, unknown>>;- variant_init(input: VariantInitInput): Promise<Record<string, unknown>>;- variant_check(input: VariantCheckInput): Promise<Record<string, unknown>>;};type ToolOptions = {@@ -303,225 +224,13 @@ type ToolOptions = {export type GenerateText = (input: { readonly parts: readonly GeminiInlinePart[]; readonly instruction: string }) => Promise<string>;type ObservationTask = { readonly key: string; readonly request: Request };-function routeStateResult(state: RouteState | undefined): Record<string, unknown> {- return state === undefined ? { state: null } : {- state,- path: routeStatePath(state.project_root),- history_path: routeExecutionStatePath(state.project_root, state.route_id),- };-}--function revisionStateResult(state: RevisionState | undefined): Record<string, unknown> {- return state === undefined ? { state: null } : {- state,- path: revisionStatePath(state.project_root),- history_path: revisionExecutionStatePath(state.project_root, state.revision_id),- request_path: revisionRequestPath(state.project_root, state.revision_id),- };-}--function variantStateResult(state: Awaited<ReturnType<typeof readVariantExpansionState>>): Record<string, unknown> {- return state === undefined ? { state: null } : { state, path: variantExpansionStatePath(state.output_root) };-}--function routeStepFor(route: RouteKind, name: string): number | undefined {- const aliases: Readonly<Record<string, string>> = route === "variant"- ? { "vocabulary-checked": "vocabulary-verified", "source-authored": "source-updated" }- : route === "variant-package"- ? { "vocabulary-checked": "vocabulary-inspected", "package-ready": "package-validated", "source-authored": "implemented" }- : {};- const stage = aliases[name] ?? name;- const index = ROUTE_STATE_STEPS[route].indexOf(stage);- if (index < 0) return undefined;- return index + 1;-}--async function runRouteStateCommand(input: RouteStateCommandInput): Promise<Record<string, unknown>> {- if (input.action === "start") {- const state = await startRouteState({ projectRoot: input.project_root, route: input.route, ...(input.run === undefined ? {} : { run: input.run }), ...(input.reference_id === undefined ? {} : { referenceId: input.reference_id }) });- return routeStateResult(state);- }- if (input.action === "read") return routeStateResult(await readRouteState(input.project_root));- if (input.action === "reconcile") return routeStateResult(await reconcileRouteState(input.project_root));- if (input.action !== "checkpoint") throw new Error(`unsupported route state action ${input.action}`);- const state = await checkpointRouteState({- projectRoot: input.project_root,- route: input.route,- step: input.step,- ...(input.status === undefined ? {} : { status: input.status }),- ...(input.run === undefined ? {} : { run: input.run }),- ...(input.reference_id === undefined ? {} : { referenceId: input.reference_id }),- ...(input.next_action === undefined ? {} : { nextAction: input.next_action }),- ...(input.artifacts === undefined ? {} : { artifacts: input.artifacts }),- ...(input.decision === undefined ? {} : { decision: input.decision }),- ...(input.command === undefined ? {} : { command: input.command }),- ...(input.error === undefined ? {} : { error: input.error }),- });- return routeStateResult(state);-}--async function runRevisionStateCommand(input: RevisionStateCommandInput): Promise<Record<string, unknown>> {- if (input.action === "start") {- return revisionStateResult(await startRevisionState({- projectRoot: input.project_root,- ...(input.run === undefined ? {} : { run: input.run }),- ...(input.parent_route === undefined ? {} : { parentRoute: input.parent_route }),- ...(input.parent_state_digest === undefined ? {} : { parentStateDigest: input.parent_state_digest }),- ...(input.request === undefined ? {} : { request: input.request }),- }));- }- if (input.action === "read") return revisionStateResult(await readRevisionState(input.project_root));- if (input.action === "reconcile") return revisionStateResult(await reconcileRevisionState(input.project_root));- if (input.action !== "checkpoint") throw new Error(`unsupported revision state action ${input.action}`);- return revisionStateResult(await checkpointRevisionState({- projectRoot: input.project_root,- step: input.step,- ...(input.status === undefined ? {} : { status: input.status }),- ...(input.run === undefined ? {} : { run: input.run }),- ...(input.parent_route === undefined ? {} : { parentRoute: input.parent_route }),- ...(input.parent_state_digest === undefined ? {} : { parentStateDigest: input.parent_state_digest }),- ...(input.request === undefined ? {} : { request: input.request }),- ...(input.next_action === undefined ? {} : { nextAction: input.next_action }),- ...(input.artifacts === undefined ? {} : { artifacts: input.artifacts }),- ...(input.decision === undefined ? {} : { decision: input.decision }),- ...(input.command === undefined ? {} : { command: input.command }),- ...(input.error === undefined ? {} : { error: input.error }),- ...(input.impact === undefined ? {} : { impact: input.impact }),- ...(input.affected_source === undefined ? {} : { affectedSource: input.affected_source }),- }));-}--async function runVariantStateCommand(input: VariantStateCommandInput): Promise<Record<string, unknown>> {- if (input.action === "discover") {- const batches = await discoverVariantExpansions(input.project_root);- return { project_root: resolve(input.project_root), batches, active: batches.filter((batch) => batch.status !== "complete") };- }- if (input.action === "start") {- return variantStateResult(await startVariantExpansion({- projectRoot: input.project_root, outputRoot: input.output_root,- ...(input.run === undefined ? {} : { run: input.run }),- ...(input.request === undefined ? {} : { request: input.request }),- ...(input.count === undefined ? {} : { count: input.count }),- ...(input.delivery_mode === undefined ? {} : { deliveryMode: input.delivery_mode }),- ...(input.parent_route === undefined ? {} : { parentRoute: input.parent_route }),- ...(input.parent_state_digest === undefined ? {} : { parentStateDigest: input.parent_state_digest }),- ...(input.revision_state_digest === undefined ? {} : { revisionStateDigest: input.revision_state_digest }),- }));- }- if (input.action === "read") return variantStateResult(await readVariantExpansionState(input.project_root, input.output_root, input.batch_id));- if (input.action === "reconcile") return variantStateResult(await reconcileVariantExpansion(input.project_root, input.output_root, input.batch_id));- if (input.action !== "checkpoint") throw new Error(`unsupported variant state action ${(input as { action: string }).action}`);- const checkpoint: VariantExpansionCheckpointInput = {- projectRoot: input.project_root, step: input.step,- ...(input.output_root === undefined ? {} : { outputRoot: input.output_root }),- ...(input.batch_id === undefined ? {} : { batchId: input.batch_id }),- ...(input.status === undefined ? {} : { status: input.status }),- ...(input.next_action === undefined ? {} : { nextAction: input.next_action }),- ...(input.artifacts === undefined ? {} : { artifacts: input.artifacts }),- ...(input.workload_disclosure === undefined ? {} : { workloadDisclosure: input.workload_disclosure }),- ...(input.packages === undefined ? {} : { packages: input.packages }),- ...(input.variants === undefined ? {} : { variants: input.variants }),- ...(input.decision === undefined ? {} : { decision: input.decision }),- ...(input.conflict === undefined ? {} : { conflict: input.conflict }),- ...(input.resolve_conflict === undefined ? {} : { resolveConflict: input.resolve_conflict }),- ...(input.command === undefined ? {} : { command: input.command }),- ...(input.error === undefined ? {} : { error: input.error }),- };- return variantStateResult(await checkpointVariantExpansion(checkpoint));-}--async function autoRouteCheckpoint(- runPath: string | undefined,- step: number | undefined,- artifacts: Readonly<Record<string, string>> = {},- nextAction?: string,- command?: string,-): Promise<void> {- if (runPath === undefined || step === undefined) return;- const projectRoot = dirname(resolve(runPath));- const state = await readRouteState(projectRoot);- if (state === undefined || state.status === "complete") return;- await checkpointRouteState({- projectRoot,- route: state.route,- step,- status: "complete",- run: runPath,- artifacts,- command: command ?? `route step ${step}`,- ...(nextAction === undefined ? {} : { nextAction }),- });-}--async function persistRouteEvidence(runPath: string, name: string, result: Record<string, unknown>): Promise<string> {- return persistEvidence(dirname(resolve(runPath)), name, result);-}--async function readSettledLayout(runPath: string): Promise<Record<string, unknown>> {- const path = join(dirname(resolve(runPath)), ".hypit", "layout-check.json");- try {- const value = JSON.parse(await readFile(path, "utf8")) as Record<string, unknown>;- return {- passed: value.executed === true && value.settled === true,- evidence: path,- executed: value.executed === true,- settled: value.settled === true,- pending_count: value.pending_count,- semantics: value.semantics,- };- } catch {- return { passed: false, evidence: path, executed: false, settled: false, reason: "run layout_check first" };- }-}--async function autoRouteError(runPath: string | undefined, command: string, error: unknown): Promise<void> {- if (runPath === undefined) return;- const resolved = resolve(invokedFrom(), runPath);- const projectRoot = dirname(resolved);- const state = await readRouteState(projectRoot);- if (state === undefined || state.status === "complete") return;- await checkpointRouteState({- projectRoot,- route: state.route,- step: state.current_step <= ROUTE_STATE_STEPS[state.route].length ? state.current_step : ROUTE_STATE_STEPS[state.route].length,- status: "in_progress",- run: resolved,- command,- error: error instanceof Error ? error.message : String(error),- });-}--async function renderEvidence(output: unknown): Promise<Readonly<Record<string, string>>> {- if (typeof output !== "string") return {};- const rendered = resolve(invokedFrom(), output);- const sidecar = standInSidecarPath(rendered);- const [renderFile, sidecarFile] = await Promise.all([- stat(rendered).then((value) => value.isFile(), () => false),- stat(sidecar).then((value) => value.isFile(), () => false),- ]);- return renderFile && sidecarFile ? { preview_render: rendered, render_sidecar: sidecar } : {};-}+let eventSequence = 0;-async function referenceObservationComplete(referenceId: string): Promise<boolean> {- const state = await readJson<ReferenceState>(join(stateRoot(referenceId), "state.json")).catch(() => undefined);- if (state === undefined || !prepared(state)) return false;- const observations = await readJson<Record<string, Observation>>(join(state.root, "observations.json")) ?? {};- const required = state.shots.flatMap((shot, index) => [- `visual:${shot.shot_id}`, `type:${shot.shot_id}`, `audio:${shot.shot_id}`,- ...(index === 0 ? [] : [`boundary:${shot.shot_id}`]),- ]);- return required.every((key) => observations[key]?.status === "complete")- && Object.values(observations).every((value) => value?.status === "complete");-}--async function maybeCheckpointReferenceObservation(input: RecordObservationInput): Promise<void> {- if (input.run === undefined || !(await referenceObservationComplete(input.reference_id))) return;- const runPath = resolve(invokedFrom(), input.run);- await autoRouteCheckpoint(runPath, routeStepFor("reconstruction", "reference-observed"), { reference_observations: join(stateRoot(input.reference_id), "observations.json") }, "inspect vocabulary and resolve any package gap");-}--async function persistRoutePlan(runPath: string, result: Record<string, unknown>): Promise<string> {- return persistEvidence(dirname(resolve(runPath)), "route-plan.json", { plan: result.plan ?? [], generated_at: new Date().toISOString() });+function eventId(label: string, at = new Date()): string {+ eventSequence += 1;+ const readable = label.trim().replace(/[^0-9A-Za-z._-]+/gu, "-").replace(/^-+|-+$/gu, "") || "item";+ const time = at.toISOString().replace(/[-:.TZ]/gu, "");+ return `${readable}-${time}-${eventSequence.toString(36)}`;}function observation(status: Observation["status"], text: string): Observation { return { status, text }; }@@ -573,7 +282,7 @@ export type ComparisonRecord = {/*** Names this comparison so an observer that answers out of band can close it. The `agent` observer* is handed the pair and the question and returns nothing in band, so without a name the entry- * stayed `pending` for ever and a gate had to choose between crediting an unanswered comparison and+ * stayed `pending` for ever and a report had to choose between crediting an unanswered comparison and* crediting none of them.*/readonly id: string;@@ -584,7 +293,6 @@ export type ComparisonRecord = {readonly range?: ComparedRange;readonly element?: string;readonly image_path: string;- readonly image_digest: string;readonly observer: Observer;readonly status: Observation["status"];readonly scoped: boolean;@@ -604,7 +312,7 @@ export type ComparisonRecord = {/*** One line per element review on the route that has no reference to compare against.*- * The fields it shares with `ComparisonRecord` are spelled the same, so the gate reads one shape from+ * The fields it shares with `ComparisonRecord` are spelled the same, so reports read one shape from* either log without an adapter. What differs is the question: a comparison reports how two pictures* differ, and a review reports whether one picture is what it was asked to be — so it carries the* intent it was judged against, and its answer is `findings`.@@ -617,11 +325,10 @@ export type ReviewRecord = {/*** The window, named the way it was asked for. Only the name: `ComparedRange` also carries where the* reference speaks those words and how the cut was snapped to its shot boundaries, and none of that- * exists here. The gate reads the name and nothing else from either log.+ * exists here. Reports read the name and nothing else from either log.*/readonly range?: { readonly segment?: string; readonly selection?: string; readonly tokens?: readonly [number, number] };readonly image_path: string;- readonly image_digest: string;readonly status: Observation["status"];readonly scope?: string;readonly clip?: boolean;@@ -632,10 +339,6 @@ export type ReviewRecord = {readonly findings?: string;};-async function fileDigest(path: string): Promise<string> {- return `sha256:${createHash("sha256").update(await readFile(path)).digest("hex")}`;-}-/*** What timed the stand-in behind a rendered picture, read from beside the picture itself.*@@ -682,65 +385,6 @@ async function appendLooked(log: LookLog, record: ComparisonRecord | ReviewRecor});}-/**- * An answered comparison of the same two files, asked the same way.- *- * The render's digest is what makes this safe, because it is also the repair detector: change- * anything the element draws and the bytes change, so the pair is new and is asked again. Bytes that- * did not change mean the edit did not reach the picture, and putting the identical pair in front of- * the observer a second time buys a paraphrase of the first answer.- *- * The stretch and the scope are part of the key because they are the rest of the question. The same- * render against a different stretch is a different comparison — the reference side moved — and that- * is the case this must not swallow.- */-async function answeredAlready(- log: LookLog,- key: {- readonly digest: string; readonly stretch: string; readonly clip: boolean;- /** Which element the answer was credited to, and what the observer was asked to limit itself to. */- readonly element: string; readonly scope: string;- },-): Promise<(ComparisonRecord & ReviewRecord) | undefined> {- const lines = (await readFile(join(log.root, log.file), "utf8").catch(() => "")).split("\n");- for (const line of lines.reverse()) {- if (line.trim().length === 0) continue;- let record: ComparisonRecord & ReviewRecord;- try { record = JSON.parse(line) as ComparisonRecord & ReviewRecord; } catch { continue; }- if (record.status !== "complete" || record[log.answer] === undefined) continue;- if (record.image_digest !== key.digest) continue;- if (comparedStretch(record) !== key.stretch) continue;- if ((record.clip ?? false) !== key.clip) continue;- // The element and the scope are part of the question. `render_element` draws the whole stretch- // rather than the element alone, so two elements over one Segment can be byte-identical renders,- // and what separates their comparisons is which element the answer is credited to and what the- // observer was told to limit itself to. Keyed on the bytes alone, one element's answer would be- // handed back for another and counted as having looked at it.- if ((record.element ?? "") !== key.element) continue;- if ((record.scope ?? "") !== key.scope) continue;- return record;- }- return undefined;-}--/**- * What a look was made over, in the form it was asked for.- *- * A word range is written as its own form because the finest thing worth looking at is not always a- * thing the Script named — a caption Cue is a run of words with no id — and a gate comparing a round- * against a plan has to be able to tell one of those from another.- */-function comparedStretch(record: {- readonly shot_id?: string;- readonly range?: { readonly segment?: string; readonly selection?: string; readonly tokens?: readonly [number, number] };-}): string {- return record.shot_id- ?? (record.range?.tokens === undefined ? undefined : `tokens:${record.range.tokens[0]}-${record.range.tokens[1]}`)- ?? (record.range?.segment === undefined ? undefined : `segment:${record.range.segment}`)- ?? (record.range?.selection === undefined ? undefined : `selection:${record.range.selection}`)- ?? "";-}-/*** Record the differences against the comparison that asked for them, and mark it answered.*@@ -1259,7 +903,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVconst packagesRoot = join(projectRoot, "packages");// Project package directories are discovered by their location and manifest, not by a// naming convention. A package created for one video may use any valid descriptive slug;- // requiring a `local-` prefix would let other project-owned packages evade this gate.+ // requiring a `local-` prefix would let other project-owned packages evade this validation.const projectPackageDirectories = (await readdir(packagesRoot, { withFileTypes: true }).catch(() => [])).filter((entry) => entry.isDirectory() && entry.name !== "node_modules" && !entry.name.startsWith(".")).map((entry) => join(packagesRoot, entry.name));@@ -1296,15 +940,16 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVconst registry = await loadStudioCompanionRegistry({ workspaceRoot: projectRoot, packageRoot: projectRoot, distributionPackageRoot });const domain = await loadStudioDomain({ run: runPath, workspaceRoot: projectRoot, packageRoot: projectRoot });const runtimePath = input.runtime === undefined ? undefined : resolve(invokedFrom(), input.runtime);- const archive = await openStudioArchive(runtimePath, projectRoot, projectRoot, distributionPackageRoot);+ const buildLibrary = await openStudioBuildLibrary(runtimePath, projectRoot, projectRoot, distributionPackageRoot);try {- const loaded = await loadStudioRun({ run: runPath, domain, registry, ...(archive === undefined ? {} : { archive }) });+ const loaded = await loadStudioRun({ run: runPath, domain, registry,+ ...(buildLibrary === undefined ? {} : { buildLibrary }) });graphModules = new Set([...loaded.source.compiled.graph.operations.map((operation) => `${operation.producer.module.name}@${operation.producer.module.version}`),...loaded.run.graph.operations.map((operation) => `${operation.producer.module.name}@${operation.producer.module.version}`),]);} finally {- await archive?.close();+ await buildLibrary?.close();}}} catch {@@ -1698,11 +1343,9 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVif (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 === 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- // would be answered with the earlier one's text.- const key = `question:${selected.map((shot) => shot.shot_id).join("+")}:${createHash("sha256").update(question).digest("hex").slice(0, 8)}`;+ // Keep the actual question in the key. It remains directly inspectable and distinguishes two+ // questions over the same shot without inventing a second identifier namespace.+ const key = `question:${selected.map((shot) => shot.shot_id).join("+")}:${encodeURIComponent(question)}`;const path = join(state.root, "observations.json");const held = (await readJson<Record<string, Observation>>(path))?.[key];const reused = held?.status === "complete" && input.reobserve !== true;@@ -1731,8 +1374,6 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVquestion,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....(reused ? { reused: true } : {}),@@ -1925,53 +1566,15 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV}}const result = { packages: input.package_names, surfaces };- let evidence: string | undefined;- let componentFitRequired: string | undefined;- if (input.run !== undefined) {- const runPath = resolve(invokedFrom(), input.run);- evidence = await persistRouteEvidence(runPath, "vocabulary.json", result);- const route = await readRouteState(dirname(runPath));- const step = routeStepFor(route?.route ?? "reconstruction", "vocabulary-checked");- if (route?.route === "description" || route?.route === "reconstruction") {- const fit = componentFitPath(dirname(runPath));- if (await componentFitSatisfied(dirname(runPath), route.route)) {- await autoRouteCheckpoint(runPath, step, { vocabulary: evidence, component_fit: fit }, "validate_local_author_packages --run <build.svrun>");- } else componentFitRequired = fit;- } else {- await autoRouteCheckpoint(runPath, step, { vocabulary: evidence }, "validate_local_author_packages --run <build.svrun>");- }- }- return evidence === undefined ? result : {- ...result,- evidence,- ...(componentFitRequired === undefined ? {} : { component_fit_required: componentFitRequired }),- };+ return result;},async validate_local_author_packages(input): Promise<Record<string, unknown>> {- const result = await validateLocalAuthorPackages(input);- const runPath = resolve(invokedFrom(), input.run);- const evidence = await persistRouteEvidence(runPath, "package-ready.json", result);- if (result.passed === true) {- const route = await readRouteState(dirname(runPath));- const step = routeStepFor(route?.route ?? "reconstruction", "package-ready");- const next = route?.route === "variant-package" ? "run preview_check for the staging project"- : "validate_script_cues --run <build.svrun>";- await autoRouteCheckpoint(runPath, step, { package_ready: evidence }, next);- } else await autoRouteError(runPath, "validate_local_author_packages", (result.packages as unknown[] ?? []));- return { ...result, evidence };+ return await validateLocalAuthorPackages(input);},async validate_script_cues(input): Promise<Record<string, unknown>> {- const result = await scriptCueCheck(input);- const runPath = resolve(invokedFrom(), input.run);- const evidence = await persistRouteEvidence(runPath, "script-cues.json", result);- if (result.passed === true) {- const route = await readRouteState(dirname(runPath));- const step = routeStepFor(route?.route ?? "reconstruction", "script-checked");- await autoRouteCheckpoint(runPath, step, { script_cues: evidence }, "write main.svml, recipes.svs and build.svrun");- } else await autoRouteError(runPath, "validate_script_cues", result.violations ?? result.errors ?? "cue validation failed");- return { ...result, evidence };+ return await scriptCueCheck(input);},/**@@ -1983,7 +1586,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV* declared schema, so it cannot drift from what the seal will accept. Without it the only way to* learn the shape was to open a package that already draws and copy its habits.*/- async inspect_visual_contract(input): Promise<Record<string, unknown>> {+ async inspect_visual_schema(input): Promise<Record<string, unknown>> {const shapes: Record<string, ValueSchema> = {"visual-track": visualTrackSchema,"visual-element": visualElementSchema,@@ -2089,11 +1692,9 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVassert(file?.isFile(), `${clip ? "video_path" : "image_path"} is not a file: ${renderedPath}`);const scope = input.question?.trim() ?? "";const startedAt = new Date().toISOString();- // Everything this call derives is written under this name, so two comparisons of one stretch —- // two elements drawn over the same Segment, or one element read twice — never write each other's- // files. The render is what distinguishes them, so the render names the slot.- const slot = `${basename(renderedPath).replace(/\.[^.]*$/u, "")}-`- + createHash("sha256").update(renderedPath).digest("hex").slice(0, 8);+ // Each explicit comparison gets its own readable directory. Repeating the command is a new+ // observation by request; no hidden equivalence rule silently reuses an older answer.+ const slot = eventId(basename(renderedPath).replace(/\.[^.]*$/u, ""), new Date(startedAt));const standIn = await standInBeside(renderedPath);const observer: Observer = state.observer ?? "gemini";const { ask, pending } = await askerFor(observer, state, input.run);@@ -2195,50 +1796,14 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV+ " two as sequences rather than as single moments. Neither grid is one continuous camera"+ " shot; a stretch may contain cuts.": "";- // The slot already names this render and this stretch uniquely within the reference, and the- // clock separates two readings of the same pair, so it is what the answer is recorded against.- const comparisonId = `${slot}-${createHash("sha256")- .update(`${slot}|${input.segment ?? input.selection ?? input.shot_id ?? ""}|${startedAt}`)- .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 comparisonId = slot;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,- element: input.element?.trim() ?? "",- scope,- });- if (already !== undefined) {- 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,- ...(shot === undefined ? {} : { shot_id: shot.shot_id }),- ...(cut === undefined ? {} : { range: cut.record }),- compared: asClip ? "clip" : "still",- reused: {- answered_at: already.at,- comparison_id: already.id,- note: "the same render, against the same stretch, asked the same way. The render's bytes are "- + "identical to the ones already compared, so nothing drawn has changed since — and a "- + "second reading of one pair is a paraphrase, not evidence. Repair against the "- + "differences below, or render a change and compare that.",- },- differences: { status: "complete", text: already.differences! },- unresolved: [],- pending_observations: pending,- };- }const differences = await ask(`comparison:${comparisonId}`, {media: [referenceMedia, renderedMedia],instruction: `You compare two supplied ${unit} and describe their visible differences in natural language only. You are not told how either was made. Do not write code, markup, SVML, component names, or production advice.`,prompt: `Two ${unit} are supplied in order: one, then two. Call them one and two throughout your answer, and say which of the two each difference is in.${reading}${asClip ? "\n\nThe two clips may have different total durations or playback speeds. Compare corresponding visual stages and events rather than matching the same elapsed second, and do not treat a duration difference alone as a visual defect." : ""}${asClip ? cut?.incomplete ?? "" : ""}${scope.length === 0 ? "" : `\n\nLimit the comparison to this: ${scope}`}\n\nStart with a geometry pass before style: identify the Canvas, the outer frame or background box, and the inner text/element. For every region intended to be vertically centred, compare inner and outer centres on the Y axis and report whether it is too high or too low. Do not treat deliberate left/right bias as a defect. Check containment separately (inner content inside its outer frame; outer frame inside the Canvas), naming the overflowing edge and approximate amount. Check that the outer frame is wide and tall enough for the longest line or mark including padding, stroke, shadow and corner treatment. Treat overlap candidates as prompts for inspection only: the supplied reference or settled brief and intent decide whether an overlap or offset is correct; never recommend removing an intentional overlap merely because it exists. Distinguish intentional bleed, crop, or enter/exit motion from accidental overflow. Then describe every other visible difference between them: layout and arrangement, the position and size of each element, cropping and margins, colour, typeface, weight, letter and line spacing, alignment, outline or stroke, shadow, glow, borders and corner treatment, and anything present in one and absent from the other.${asClip ? " Also describe differences in what changes over the stretch: what appears, what leaves, in what order, and how anything moves." : ""} State plainly which differences are large enough to read as a different design and which are minor. If they are visually equivalent, say exactly that.\n\nDo not speculate about how either was produced, which one is a source, or which one is a copy. Return natural language only.`,});- // 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.+ // What was compared, and what was seen. The record is useful content, not a workflow cursor.await appendLooked(comparisonEvidence, {at: startedAt,id: comparisonId,@@ -2247,7 +1812,6 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV...(cut === undefined ? {} : { range: cut.record }),...(input.element === undefined ? {} : { element: input.element.trim() }),image_path: renderedPath,- image_digest: digest,observer,status: differences.status,scoped: scope.length > 0,@@ -2256,9 +1820,6 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV...(standIn === undefined ? {} : { stand_in: standIn }),...(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(comparisonEvidence.root, comparisonEvidence.file) }, "repair differences, then rerun reconstruction_check");- }return {reference_id: state.reference_id,observer,@@ -2323,35 +1884,30 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVconst current = await readJson<ReferenceState>(join(root, "state.json")) ?? state;await writeJson(join(root, "state.json"), { ...current, [field]: observation("complete", text) });});- await maybeCheckpointReferenceObservation(input);return { reference_id: state.reference_id, key, stored_in: "state" };}// A comparison is answered against the entry it opened in the log rather than against the- // observation cache: the log is what a gate reads to tell an element that was looked at from one+ // observation cache: the log is what a report reads to tell an element that was looked at from one// 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 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(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(comparisonEvidence.root, comparisonEvidence.file) }, "repair differences, then rerun reconstruction_check");- await maybeCheckpointReferenceObservation(input);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 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- // to go on the one observer that has to record its answers by hand.- const questionKey = /^question:([0-9a-z-]+(?:\+[0-9a-z-]+)*):[0-9a-f]{8}$/u.exec(key);+ // Narrow questions carry the encoded question itself after the shot id. That is longer than an+ // opaque token, but it is inspectable and requires no side table.+ const questionKey = /^question:([0-9a-z-]+(?:\+[0-9a-z-]+)*):(.+)$/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 === 1 && askedOver.every((id) => knownShots.has(id));+ let validEncodedQuestion = false;+ if (questionKey !== null) {+ try { validEncodedQuestion = decodeURIComponent(questionKey[2]!).trim().length > 0; }+ catch { validEncodedQuestion = false; }+ }+ const isQuestion = questionKey !== null && validEncodedQuestion && 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.@@ -2361,7 +1917,6 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVcache[key] = observation("complete", text);await writeJson(path, cache);});- await maybeCheckpointReferenceObservation(input);return { reference_id: state.reference_id, key, stored_in: "observations" };},@@ -2403,7 +1958,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVconst renderedPath = resolve(invokedFrom(), input.video_path ?? input.image_path!);await stat(renderedPath).catch(() => { throw new Error(`cannot read ${renderedPath}`); });- const slot = `${basename(renderedPath).replace(/\.[^.]+$/u, "")}-${createHash("sha256").update(renderedPath).digest("hex").slice(0, 8)}`;+ const slot = eventId(basename(renderedPath).replace(/\.[^.]+$/u, ""));const standIn = await standInBeside(renderedPath);const scope = input.question?.trim() ?? "";const startedAt = new Date().toISOString();@@ -2423,32 +1978,17 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV: await cutFrame(renderedPath, drawn.duration / 2, target);}- const digest = await fileDigest(renderedPath);const range = {...(input.segment === undefined ? {} : { segment: input.segment }),...(input.selection === undefined ? {} : { selection: input.selection }),...(input.tokens === undefined ? {} : { tokens: input.tokens }),};- const stretch = comparedStretch({ range });- // Nothing about the picture or the question changed since this was last answered, so nothing new- // can be said about it. Here this is what bounds the looking: a review costs no vendor money, so- // without it a round could re-ask the same picture until it liked the answer.- const already = await answeredAlready(reviewLog(root), { digest, stretch, clip: asClip, element, scope });- if (already !== undefined) {- return {- run: runPath, element, ...(input.segment === undefined ? {} : { segment: input.segment }),- ...(input.selection === undefined ? {} : { selection: input.selection }),- reviewed: asClip ? "clip" : "still",- reused: { answered_at: already.at, review_id: already.id, findings: already.findings },- };- }-- const reviewId = `${slot}-${createHash("sha256").update(`${slot}|${stretch}|${startedAt}`).digest("hex").slice(0, 6)}`;+ const reviewId = slot;const unit = asClip ? "grid of frames sampled evenly across the stretch, laid out in reading order: left to right, then top to bottom" : "still picture";const record: ReviewRecord = {at: startedAt, id: reviewId, element,range,- image_path: renderedPath, image_digest: digest, status: "pending",+ image_path: renderedPath, status: "pending",...(scope.length === 0 ? {} : { scope }), clip: asClip,...(standIn === undefined ? {} : { stand_in: standIn }),intent,@@ -2512,7 +2052,6 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVassert(text.length > 0, "text is required; a review that found nothing wrong says so in words");const closed = await closeLooked(reviewLog(root), id, text);assert(closed, `${id} names no open review of ${runPath}`);- await autoRouteCheckpoint(runPath, routeStepFor("description", "review-complete"), { review_log: reviewLogPath(runPath) }, "repair findings, then rerun authoring_check");return { run: runPath, review_id: id, stored_in: reviewLogPath(runPath) };},@@ -2530,18 +2069,6 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV...one, run: one.run ?? input.run,...(one.reference_id ?? input.reference_id === undefined ? {} : { reference_id: input.reference_id }),} as RenderElementInput));- if (failures.length === 0 && done.length > 0) {- const run = round[0]?.run ?? input.run;- const first = done[0] as Record<string, unknown>;- const evidence = await renderEvidence(first.out);- if (Object.keys(evidence).length > 0) {- await autoRouteCheckpoint(run === undefined ? undefined : resolve(invokedFrom(), run), routeStepFor((await readRouteState(dirname(resolve(invokedFrom(), run ?? ""))))?.route ?? "reconstruction", "preview-rendered"),- evidence, "compare_reconstruction or review_element");- }- } else if (failures.length > 0) {- const failedRun = round[0]?.run ?? input.run;- await autoRouteError(failedRun, "render_element", failures[0]?.error ?? "render failed");- }return {rendered: done.length,failed: failures.length,@@ -2549,18 +2076,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV...(failures.length === 0 ? {} : { failures }),};}- try {- const result = await renderElement(input);- const evidence = await renderEvidence(result.out);- if (Object.keys(evidence).length > 0) {- await autoRouteCheckpoint(input.run === undefined ? undefined : resolve(invokedFrom(), input.run), routeStepFor((await readRouteState(dirname(resolve(invokedFrom(), input.run ?? ""))))?.route ?? "reconstruction", "preview-rendered"),- evidence, "compare_reconstruction or review_element");- }- return result;- } catch (error) {- await autoRouteError(input.run, "render_element", error);- throw error;- }+ return await renderElement(input);},async render_previews(input): Promise<Record<string, unknown>> {@@ -2568,73 +2084,11 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV},async preview_check(input): Promise<Record<string, unknown>> {- const runPath = resolve(invokedFrom(), input.run);- try {- const packageGate = await validateLocalAuthorPackages({ run: input.run, ...(input.runtime === undefined ? {} : { runtime: input.runtime }) });- const cueGate = await scriptCueCheck({ run: input.run });- if (packageGate.passed !== true || cueGate.passed !== true) {- const refused = { run: runPath, sound: false, package_gate: packageGate, script_cue_gate: cueGate, refused: "package or Script Cue gate failed" };- const evidence = await persistRouteEvidence(runPath, "preview-check.json", refused);- await autoRouteError(runPath, "preview_check", refused.refused);- return { ...refused, evidence };- }- const result = await previewCheck(input, { packageRoot });- const evidence = await persistRouteEvidence(runPath, "preview-check.json", result);- if (result.sound === true) {- const source = await authorSource(runPath).catch(() => undefined);- const route = await readRouteState(dirname(runPath));- const sourceStep = routeStepFor(route?.route ?? "reconstruction", "source-authored");- const next = "run layout_check --run <build.svrun>";- await autoRouteCheckpoint(runPath, sourceStep, source === undefined ? {} : { author_source: source.path }, next);- const routeAfterSource = await readRouteState(dirname(runPath));- await autoRouteCheckpoint(runPath, routeStepFor(routeAfterSource?.route ?? "reconstruction", "graph-checked"), { preview_check: evidence }, next);- } else await autoRouteError(runPath, "preview_check", result.refused ?? result.problems ?? "preview check failed");- return { ...result, evidence };- } catch (error) {- await autoRouteError(runPath, "preview_check", error);- throw error;- }+ return await previewCheck(input, { packageRoot });},async layout_check(input): Promise<Record<string, unknown>> {- const runPath = resolve(invokedFrom(), input.run);- try {- const result = await layoutCheck(input);- const evidence = typeof result.evidence === "string" ? result.evidence : join(dirname(runPath), ".hypit", "layout-check.json");- const decisions = typeof result.decisions === "string" ? result.decisions : join(dirname(runPath), ".hypit", "layout-decisions.json");- const route = await readRouteState(dirname(runPath));- if (route !== undefined && route.status !== "complete") {- const step = routeStepFor(route.route, "layout-checked");- if (step !== undefined) {- if (result.settled === true) {- await autoRouteCheckpoint(runPath, step, { layout_check: evidence, layout_decisions: decisions },- route.route === "variant" ? "run variant_check --run <build.svrun>"- : route.route === "variant-package" ? "freeze the package digest and checkpoint package-ready"- : "plan the visual declaration review");- } else {- await checkpointRouteState({- projectRoot: dirname(runPath), route: route.route, step, status: "in_progress", run: runPath,- artifacts: { layout_check: evidence, layout_decisions: decisions }, command: "layout_check",- nextAction: "Agent reviews each layout candidate, repairs genuine issues or records intentional geometry with layout_accept, then reruns layout_check",- });- }- }- }- const revision = await readRevisionState(dirname(runPath));- if (revision !== undefined && revision.status !== "complete") {- await checkpointRevisionState({- projectRoot: dirname(runPath), step: "gates-checked", status: "in_progress", run: runPath,- artifacts: { layout_check: evidence, layout_decisions: decisions }, command: "layout_check",- nextAction: result.settled === true- ? "complete the remaining revision gates"- : "Agent reviews layout candidates; repair or accept them, then rerun layout_check",- });- }- return result;- } catch (error) {- await autoRouteError(runPath, "layout_check", error);- throw error;- }+ return await layoutCheck(input);},async layout_accept(input): Promise<Record<string, unknown>> {@@ -2642,319 +2096,13 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV},async reconstruction_check(input): Promise<Record<string, unknown>> {- const runPath = resolve(invokedFrom(), input.run);- try {- const packageGate = await validateLocalAuthorPackages({ run: input.run, ...(input.runtime === undefined ? {} : { runtime: input.runtime }) });- const cueGate = await scriptCueCheck({ run: input.run });- if (packageGate.passed !== true || cueGate.passed !== true) {- const refused = { run: runPath, passed: false, package_gate: packageGate, script_cue_gate: cueGate, issues: ["package or Script Cue gate failed"] };- const evidence = await persistRouteEvidence(runPath, "final-check.json", refused);- await autoRouteError(runPath, "reconstruction_check", refused.issues);- return { ...refused, evidence };- }- const authored = await authoringCheck({ ...input, mode: "reconstruction" }, { packageRoot });- const layout = await readSettledLayout(runPath);- const result: Record<string, unknown> = layout.passed === true ? { ...authored, layout }- : { ...authored, passed: false, layout, issues: [...(Array.isArray(authored.issues) ? authored.issues : []), "layout candidates are unresolved or layout_check has not run"] };- const evidence = await persistRouteEvidence(runPath, "final-check.json", result);- if (Array.isArray(result.plan)) {- const planPath = await persistRoutePlan(runPath, result);- const route = await readRouteState(dirname(runPath));- await autoRouteCheckpoint(runPath, routeStepFor(route?.route ?? "reconstruction", "review-planned"), { review_plan: planPath }, "render_element --batch <round.json>");- }- if (result.passed === true) { const route = await readRouteState(dirname(runPath)); await autoRouteCheckpoint(runPath, routeStepFor(route?.route ?? "reconstruction", "final-checked"), { final_check: evidence }, "submit the approved Build"); }- else await autoRouteError(runPath, "reconstruction_check", result.issues ?? result.unresolved ?? "reconstruction check failed");- return { ...result, evidence };- } catch (error) {- await autoRouteError(runPath, "reconstruction_check", error);- throw error;- }+ return await authoringCheck({ ...input, mode: "reconstruction" }, { packageRoot });},async authoring_check(input): Promise<Record<string, unknown>> {- const runPath = resolve(invokedFrom(), input.run);- try {- const packageGate = await validateLocalAuthorPackages({ run: input.run, ...(input.runtime === undefined ? {} : { runtime: input.runtime }) });- const cueGate = await scriptCueCheck({ run: input.run });- if (packageGate.passed !== true || cueGate.passed !== true) {- const refused = { run: runPath, passed: false, package_gate: packageGate, script_cue_gate: cueGate, issues: ["package or Script Cue gate failed"] };- const evidence = await persistRouteEvidence(runPath, "final-check.json", refused);- await autoRouteError(runPath, "authoring_check", refused.issues);- return { ...refused, evidence };- }- const authored = await authoringCheck({ ...input, mode: "description" }, { packageRoot });- const layout = await readSettledLayout(runPath);- const result: Record<string, unknown> = layout.passed === true ? { ...authored, layout }- : { ...authored, passed: false, layout, issues: [...(Array.isArray(authored.issues) ? authored.issues : []), "layout candidates are unresolved or layout_check has not run"] };- const evidence = await persistRouteEvidence(runPath, "final-check.json", result);- if (Array.isArray(result.plan)) {- const planPath = await persistRoutePlan(runPath, result);- const route = await readRouteState(dirname(runPath));- await autoRouteCheckpoint(runPath, routeStepFor(route?.route ?? "description", "review-planned"), { review_plan: planPath }, "render_element --batch <round.json>");- }- if (result.passed === true) { const route = await readRouteState(dirname(runPath)); await autoRouteCheckpoint(runPath, routeStepFor(route?.route ?? "description", "final-checked"), { final_check: evidence }, "submit the approved Build"); }- else await autoRouteError(runPath, "authoring_check", result.issues ?? result.unresolved ?? "authoring check failed");- return { ...result, evidence };- } catch (error) {- await autoRouteError(runPath, "authoring_check", error);- throw error;- }- },-- async route_state(input): Promise<Record<string, unknown>> {- return await runRouteStateCommand(input);- },-- async revision_state(input): Promise<Record<string, unknown>> {- return await runRevisionStateCommand(input);- },-- async variant_state(input): Promise<Record<string, unknown>> {- return await runVariantStateCommand(input);- },-- async variant_init(input): Promise<Record<string, unknown>> {- const batch = await reconcileVariantExpansion(input.project_root, input.output_root);- if (batch === undefined) throw new Error("no variant expansion state; run variant_state --action start first");- if (batch.conflicts.length > 0) throw new Error(`variant_init is blocked by unresolved conflicts: ${batch.conflicts.join("; ")}`);- const required = ["workload-disclosed", "package-gaps-resolved", "slate-frozen"]- .map((name) => VARIANT_EXPANSION_STEPS.indexOf(name as VariantExpansionStep) + 1);- const missing = required.filter((step) => !batch.completed_steps.includes(step));- if (missing.length > 0) throw new Error(`variant_init is blocked until ${missing.map((step) => VARIANT_EXPANSION_STEPS[step - 1]).join(", ")}`);- const initialized = await initializeVariantProjects({- projectRoot: input.project_root, outputRoot: input.output_root, slatePath: input.slate,- expectedBaseDigest: batch.baseline_digest,- ...(batch.count === undefined ? {} : { expectedCount: batch.count }),- approvedPackages: batch.packages.flatMap((pack): ApprovedVariantPackage[] => pack.status === "ready" && pack.digest !== undefined- ? [{ id: pack.id, package_root: pack.package_root ?? pack.staging_root, digest: pack.digest }] : []),- });- const readPlan = async (key: "format_plan" | "component_plan"): Promise<unknown> => {- const path = batch.artifacts[key];- if (path === undefined) throw new Error(`batch state has no ${key} artifact`);- try { return JSON.parse(await readFile(path, "utf8")); }- catch (error) { throw new Error(`cannot read ${key} at ${path}: ${error instanceof Error ? error.message : String(error)}`); }- };- const [formatPlan, componentPlan] = await Promise.all([readPlan("format_plan"), readPlan("component_plan")]);- const selectedPlan = async (plan: unknown, item: { readonly id: string; readonly brief: string }): Promise<unknown> => {- if (plan !== null && typeof plan === "object" && Array.isArray((plan as { variants?: unknown }).variants)) {- const entry = ((plan as { variants: unknown[] }).variants).find((candidate) => candidate !== null && typeof candidate === "object" && (candidate as { id?: unknown }).id === item.id);- if (entry !== undefined) return entry;- }- let directionId: string | undefined;- try {- const brief = JSON.parse(await readFile(item.brief, "utf8")) as {- direction_id?: unknown;- brief?: { direction_id?: unknown };- };- const value = brief.direction_id ?? brief.brief?.direction_id;- directionId = typeof value === "string" ? value : undefined;- } catch { directionId = undefined; }- if (directionId !== undefined && plan !== null && typeof plan === "object" && Array.isArray((plan as { directions?: unknown }).directions)) {- const entry = ((plan as { directions: unknown[] }).directions).find((candidate) => candidate !== null && typeof candidate === "object" && (candidate as { id?: unknown }).id === directionId);- if (entry !== undefined) return entry;- }- return plan;- };- const variants: VariantExpansionVariant[] = [];- for (const item of initialized.variants) {- const formatPlanPath = join(item.project_root, ".hypit", "format-plan.json");- const componentPlanPath = join(item.project_root, ".hypit", "component-plan.json");- await writeVariantJson(formatPlanPath, { variant_id: item.id, source: batch.artifacts.format_plan, plan: await selectedPlan(formatPlan, item) });- await writeVariantJson(componentPlanPath, { variant_id: item.id, source: batch.artifacts.component_plan, plan: await selectedPlan(componentPlan, item) });- await startRouteState({ projectRoot: item.project_root, route: "variant", run: item.run });- await checkpointRouteState({ projectRoot: item.project_root, route: "variant", step: 1, status: "complete", artifacts: { baseline_manifest: item.manifest } });- await checkpointRouteState({ projectRoot: item.project_root, route: "variant", step: 2, status: "complete", artifacts: { variant_brief: item.brief } });- await checkpointRouteState({ projectRoot: item.project_root, route: "variant", step: 3, status: "complete", artifacts: { allowed_changes: item.allowed_changes } });- if (item.vocabulary_mode === "inherited") {- await checkpointRouteState({ projectRoot: item.project_root, route: "variant", step: 5, status: "complete", artifacts: { vocabulary: join(item.project_root, ".hypit", "vocabulary.json") } });- }- variants.push({ ...item, route_state: routeStatePath(item.project_root), format_plan: formatPlanPath, component_plan: componentPlanPath });- }- const copyManifest = join(resolve(input.output_root), ".hypit", "variant-copy-manifest.json");- await writeVariantJson(copyManifest, {- version: 1, project_root: resolve(input.project_root), output_root: resolve(input.output_root),- base_digest: initialized.base_digest, slate: resolve(input.slate), variants, created_at: new Date().toISOString(),- });- const state = await checkpointVariantExpansion({- projectRoot: input.project_root, outputRoot: input.output_root, step: "projects-copied", status: "complete",- artifacts: { copy_manifest: copyManifest, slate: resolve(input.slate) }, variants,- command: `variant_init --project-root ${resolve(input.project_root)} --output-root ${resolve(input.output_root)} --slate ${resolve(input.slate)}`,- nextAction: "dispatch only the variant routes whose package prerequisites are ready",- });- return { passed: true, state, copy_manifest: copyManifest, variants };+ return await authoringCheck({ ...input, mode: "description" }, { packageRoot });},- async variant_check(input): Promise<Record<string, unknown>> {- const runPath = resolve(invokedFrom(), input.run);- const projectRoot = dirname(runPath);- const route = await readRouteState(projectRoot);- if (route?.route !== "variant") throw new Error(`${projectRoot} has no active variant route`);- const revision = await readRevisionState(projectRoot);- if (revision?.parent_route === "variant") {- throw new Error(`${projectRoot} has entered post-completion Revision; variant_check cannot reapply the original batch allowed_changes`);- }- const briefPath = join(projectRoot, ".hypit", "variant-brief.json");- const brief = JSON.parse(await readFile(briefPath, "utf8")) as {- id?: string;- batch_root?: string;- base_project_root?: string;- };- const manifestPath = join(projectRoot, ".hypit", "variant-baseline-manifest.json");- let manifest: VariantProjectManifest | undefined;- try { manifest = JSON.parse(await readFile(manifestPath, "utf8")) as VariantProjectManifest; }- catch { manifest = undefined; }- const batch = brief.batch_root === undefined || brief.base_project_root === undefined- ? undefined : await readVariantExpansionState(brief.base_project_root, brief.batch_root);- const expectedVariant = batch?.variants.find((variant) => resolve(variant.project_root) === projectRoot && (brief.id === undefined || variant.id === brief.id));- const stateBindingPassed = manifest !== undefined && expectedVariant !== undefined- && JSON.stringify(manifest.allowed_changes) === JSON.stringify(expectedVariant.allowed_change_paths)- && manifest.vocabulary_mode === expectedVariant.vocabulary_mode- && JSON.stringify(manifest.vocabulary_packages) === JSON.stringify(expectedVariant.vocabulary_packages)- && manifest.vocabulary_digest === expectedVariant.vocabulary_digest- && JSON.stringify(manifest.package_injections) === JSON.stringify(expectedVariant.package_injections);- const vocabularyPath = join(projectRoot, ".hypit", "vocabulary.json");- let vocabulary: Record<string, unknown> | undefined;- try { vocabulary = JSON.parse(await readFile(vocabularyPath, "utf8")) as Record<string, unknown>; }- catch { vocabulary = undefined; }- const requiredPackages = manifest?.vocabulary_packages ?? [];- const vocabularyMode = manifest?.vocabulary_mode ?? "inspect";- const evidencePackages = Array.isArray(vocabulary?.packages) ? vocabulary.packages.filter((item): item is string => typeof item === "string") : [];- const evidenceSurfaces = Array.isArray(vocabulary?.surfaces)- ? vocabulary.surfaces.filter((item): item is Record<string, unknown> => item !== null && typeof item === "object") : [];- const evidenceShapePassed = vocabulary !== undefined && Array.isArray(vocabulary.packages) && Array.isArray(vocabulary.surfaces);- const vocabularyBytes = await readFile(vocabularyPath).catch(() => undefined);- const vocabularyDigest = vocabularyBytes === undefined ? undefined : `sha256:${createHash("sha256").update(vocabularyBytes).digest("hex")}`;- const sourceUsage = await inspectSourceVocabularyUsage(runPath).catch(() => ({ imports: [] as readonly string[], tags: [] as readonly string[] }));- const baselineImports = manifest?.source_imports ?? [];- const addedImports = sourceUsage.imports.filter((name) => !baselineImports.includes(name));- const requiredImportedAndUsed = requiredPackages.every((name) => {- const imported = sourceUsage.imports.includes(name);- const tags = evidenceSurfaces.filter((surface) => surface.package_name === name)- .flatMap((surface) => typeof surface.tag === "string" ? [surface.tag] : []);- return imported && tags.length > 0 && tags.some((tag) => sourceUsage.tags.includes(tag));- });- const inheritedContractPassed = vocabularyMode === "inherited"- && manifest?.vocabulary_digest !== undefined && vocabularyDigest === manifest.vocabulary_digest- && JSON.stringify(sourceUsage.imports) === JSON.stringify(baselineImports)- && JSON.stringify(sourceUsage.tags) === JSON.stringify(manifest.source_tags);- const inspectedContractPassed = vocabularyMode === "inspect"- && requiredPackages.length > 0- && requiredPackages.every((name) => evidencePackages.includes(name))- && addedImports.every((name) => requiredPackages.includes(name))- && requiredImportedAndUsed;- const packageBindings = await Promise.all((manifest?.package_injections ?? []).map(async (injection) => ({- ...injection,- current_digest: await snapshotProject(join(projectRoot, injection.destination), { preserveTopLevelOutputs: true }).then((snapshot) => snapshot.digest, () => undefined),- })));- const packageBindingsPassed = packageBindings.every((binding) => binding.current_digest === binding.digest);- const vocabularyPassed = stateBindingPassed && evidenceShapePassed && packageBindingsPassed- && (inheritedContractPassed || inspectedContractPassed);- const packageGate = await validateLocalAuthorPackages({ run: runPath, ...(input.runtime === undefined ? {} : { runtime: input.runtime }) });- const cueGate = await scriptCueCheck({ run: runPath });- const graphGate = packageGate.passed === true && cueGate.passed === true- ? await previewCheck({ run: runPath, ...(input.runtime === undefined ? {} : { runtime: input.runtime }) }, { packageRoot })- .catch((error) => ({ run: runPath, sound: false, refused: error instanceof Error ? error.message : String(error) }))- : { run: runPath, sound: false, refused: "package or Script Cue gate failed" };- const mechanics = await mechanicalAuthoringCheck({ run: runPath }, { packageRoot })- .catch((error) => ({ run: runPath, passed: false, error: error instanceof Error ? error.message : String(error) }));- const minimalDiff = await inspectVariantDiff(projectRoot)- .catch((error) => ({ passed: false, error: error instanceof Error ? error.message : String(error) }));- const generatedLeakage = await findGeneratedLeakage(projectRoot, runPath)- .catch((error) => ({ passed: false, error: error instanceof Error ? error.message : String(error) }));- const layoutGate = await readSettledLayout(runPath);- const result: Record<string, unknown> = {- run: runPath,- passed: vocabularyPassed && packageGate.passed === true && cueGate.passed === true- && graphGate.sound === true && layoutGate.passed === true && mechanics.passed === true && minimalDiff.passed === true && generatedLeakage.passed === true,- vocabulary: {- passed: vocabularyPassed, mode: vocabularyMode, required_packages: requiredPackages, evidence: vocabularyPath,- evidence_digest: vocabularyDigest, baseline_digest: manifest?.vocabulary_digest,- state_binding: stateBindingPassed, evidence_shape: evidenceShapePassed,- baseline_imports: baselineImports, current_imports: sourceUsage.imports, added_imports: addedImports,- baseline_tags: manifest?.source_tags ?? [], current_tags: sourceUsage.tags,- required_packages_imported_and_used: requiredImportedAndUsed,- package_bindings: packageBindings,- },- package_gate: packageGate, script_cue_gate: cueGate, graph: graphGate, layout: layoutGate, mechanics, minimal_diff: minimalDiff,- generated_result_leakage: generatedLeakage,- visual_review: "not performed",- };- const packageEvidence = await persistRouteEvidence(runPath, "package-ready.json", packageGate);- const cueEvidence = await persistRouteEvidence(runPath, "script-cues.json", cueGate);- const previewEvidence = await persistRouteEvidence(runPath, "preview-check.json", graphGate);- const finalEvidence = await persistRouteEvidence(runPath, "variant-check.json", result);- result.evidence = finalEvidence;- if (vocabularyPassed) await autoRouteCheckpoint(runPath, routeStepFor("variant", "vocabulary-checked"), { vocabulary: vocabularyPath });- if (packageGate.passed === true) await autoRouteCheckpoint(runPath, routeStepFor("variant", "package-ready"), { package_ready: packageEvidence });- if (cueGate.passed === true) await autoRouteCheckpoint(runPath, routeStepFor("variant", "script-checked"), { script_cues: cueEvidence });- if (graphGate.sound === true) {- const source = await authorSource(runPath).catch(() => undefined);- await autoRouteCheckpoint(runPath, routeStepFor("variant", "source-authored"), source === undefined ? {} : { author_source: source.path });- await autoRouteCheckpoint(runPath, routeStepFor("variant", "graph-checked"), { preview_check: previewEvidence });- }- if (layoutGate.passed === true) {- await autoRouteCheckpoint(runPath, routeStepFor("variant", "layout-checked"), {- layout_check: String(layoutGate.evidence), layout_decisions: join(projectRoot, ".hypit", "layout-decisions.json"),- });- }- if (result.passed === true) {- await autoRouteCheckpoint(runPath, routeStepFor("variant", "final-checked"), { variant_check: finalEvidence });- const readyToComplete = await readRouteState(projectRoot);- const completeStep = ROUTE_STATE_STEPS.variant.indexOf("variant-complete") + 1;- const allPrior = Array.from({ length: completeStep - 1 }, (_, index) => index + 1)- .every((step) => readyToComplete?.completed_steps.includes(step) === true);- if (allPrior) {- await checkpointRouteState({ projectRoot, route: "variant", step: "variant-complete", status: "complete", artifacts: { variant_check: finalEvidence } });- }- } else {- const outsideScope = Array.isArray((minimalDiff as { outside_allowed_changes?: unknown }).outside_allowed_changes)- && ((minimalDiff as { outside_allowed_changes: unknown[] }).outside_allowed_changes.length > 0);- if (outsideScope) {- await checkpointRouteState({ projectRoot, route: "variant", step: route.current_step, status: "blocked", run: runPath,- command: "variant_check", error: "scope-expansion-required" });- } else await autoRouteError(runPath, "variant_check", result);- }-- result.route_state = await readRouteState(projectRoot);-- if (brief.batch_root !== undefined && brief.base_project_root !== undefined) {- let batch = await reconcileVariantExpansion(brief.base_project_root, brief.batch_root);- if (batch !== undefined) {- const currentRoute = await readRouteState(projectRoot);- const outsideScope = Array.isArray((minimalDiff as { outside_allowed_changes?: unknown }).outside_allowed_changes)- && ((minimalDiff as { outside_allowed_changes: unknown[] }).outside_allowed_changes.length > 0);- const updatedVariant = batch.variants.find((variant) => variant.project_root === projectRoot);- const variantUpdate = updatedVariant === undefined ? undefined : {- ...updatedVariant, status: currentRoute?.status === "complete" ? "complete" as const- : outsideScope ? "scope-expansion-required" as const : result.passed === true ? "dispatched" as const : "failed" as const,- ...(result.passed === true ? {} : { error: outsideScope ? "scope-expansion-required" : "variant_check failed" }),- };- batch = await checkpointVariantExpansion({- projectRoot: brief.base_project_root, outputRoot: brief.batch_root,- step: batch.current_step <= VARIANT_EXPANSION_STEPS.length ? batch.current_step : VARIANT_EXPANSION_STEPS.length,- status: batch.status === "blocked" ? "blocked" : "in_progress",- ...(variantUpdate === undefined ? {} : { variantUpdates: [variantUpdate] }),- });- const variants = batch.variants;- const reports = await Promise.all(variants.map(async (variant) => {- const childRoute = await readRouteState(variant.project_root);- const path = childRoute?.artifacts.variant_check ?? join(variant.project_root, ".hypit", "variant-check.json");- let report: { passed?: unknown } | undefined;- try { report = JSON.parse(await readFile(path, "utf8")) as { passed?: unknown }; } catch { report = undefined; }- return { id: variant.id, project_root: variant.project_root, route_complete: childRoute?.status === "complete", passed: report?.passed === true, report: path };- }));- const aggregate = { passed: reports.length > 0 && reports.every((item) => item.route_complete && item.passed), variants: reports, checked_at: new Date().toISOString() };- const aggregatePath = await persistEvidence(brief.batch_root, "aggregate-check.json", aggregate);- if (reports.every((item) => item.route_complete)) {- await checkpointVariantExpansion({ projectRoot: brief.base_project_root, outputRoot: brief.batch_root, step: "variants-complete", status: "complete", variants });- }- if (aggregate.passed) {- await checkpointVariantExpansion({ projectRoot: brief.base_project_root, outputRoot: brief.batch_root, step: "aggregate-checked", status: "complete", artifacts: { aggregate_check: aggregatePath }, variants });- }- }- }- return result;- },};return tools;}diff --git a/packages/reference-video-tools/src/variant-project.ts b/packages/reference-video-tools/src/variant-project.tsdeleted file mode 100644index ed3dac7b..00000000--- a/packages/reference-video-tools/src/variant-project.ts+++ /dev/null@@ -1,609 +0,0 @@-import { createHash } from "node:crypto";-import { createReadStream } from "node:fs";-import { constants, chmod, copyFile, lstat, mkdir, readFile, readdir, readlink, rename, symlink, writeFile } from "node:fs/promises";-import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";--import { parseRunDocument } from "@hypit/run-markup";--export type VariantManifestEntry = {- readonly path: string;- readonly kind: "file" | "symlink";- readonly digest: string;- readonly size: number;- readonly mode: number;-};--export type VariantProjectManifest = {- readonly version: 1;- readonly project_root: string;- readonly base_project_root: string;- readonly base_digest: string;- readonly slate_entry_digest: string;- readonly allowed_changes: readonly string[];- readonly vocabulary_mode: "inherited" | "inspect";- readonly vocabulary_packages: readonly string[];- readonly vocabulary_digest?: string;- readonly source_imports: readonly string[];- readonly source_tags: readonly string[];- readonly package_injections: readonly {- readonly package_id: string;- readonly destination: string;- readonly digest: string;- }[];- readonly files: readonly VariantManifestEntry[];- readonly digest: string;- readonly created_at: string;-};--export type SlatePackageInjection = { readonly package_id: string; readonly destination: string };-export type SlateVariant = {- readonly id?: string;- readonly slug: string;- readonly brief?: unknown;- readonly component_class?: "svml-only" | "existing-component" | "composed-components" | "new-package";- readonly allowed_changes: readonly string[];- readonly vocabulary?: { readonly mode?: "inherited" | "inspect"; readonly packages?: readonly string[] };- readonly inject_packages?: readonly SlatePackageInjection[];- readonly [key: string]: unknown;-};-export type SlateDirection = Omit<SlateVariant, "id" | "slug"> & {- readonly id: string;- readonly slug: string;- readonly count: number;-};-/** The authored slate contains direction quotas; concrete variants are expanded at dispatch time. */-export type VariantSlate = {- readonly count?: number;- readonly directions?: readonly SlateDirection[];- /** Legacy expanded form remains readable for already-created batches. */- readonly variants?: readonly SlateVariant[];- readonly [key: string]: unknown;-};--export type InitializedVariant = {- readonly id: string;- readonly slug: string;- readonly project_root: string;- readonly run: string;- readonly manifest: string;- readonly brief: string;- readonly allowed_changes: string;- readonly allowed_change_paths: readonly string[];- readonly component_class: "svml-only" | "existing-component" | "composed-components" | "new-package";- readonly vocabulary_mode: "inherited" | "inspect";- readonly vocabulary_packages: readonly string[];- readonly vocabulary_digest?: string;- readonly package_injections: VariantProjectManifest["package_injections"];- readonly status: "ready";-};--const EXCLUDED_DIRECTORIES = new Set([".git", "node_modules", ".hypit", ".cache", ".turbo"]);-const EXCLUDED_TOP_LEVEL_DIRECTORIES = new Set([- "coverage", "renders", "generated", "artifacts", "logs", "cache", "build-artifacts", "builds", "output", "outputs", "dist",-]);-const SECRET_FILE = /^(?:\.env(?:\..+)?|\.npmrc|\.yarnrc|credentials?(?:\..+)?\.json|secrets?(?:\..+)?\.json|service-account(?:\..+)?\.json)$/iu;--function normalizedRelative(path: string): string {- return path.split(sep).join("/");-}--function exclusionReason(relativePath: string, directory: boolean, preserveTopLevelOutputs = false): string | undefined {- const normalized = normalizedRelative(relativePath);- const parts = normalized.split("/").filter(Boolean);- const name = parts.at(-1) ?? "";- if (parts.some((part) => EXCLUDED_DIRECTORIES.has(part))) return "generated or dependency directory";- const insideProjectPackage = parts[0] === "packages" && parts.length > 2;- if (!preserveTopLevelOutputs && !insideProjectPackage && parts.some((part) => EXCLUDED_TOP_LEVEL_DIRECTORIES.has(part))) {- return "generated output directory";- }- if (directory) return undefined;- if (SECRET_FILE.test(name) || /\.(?:pem|key)$/iu.test(name)) return "credential or secret file";- if (/\.(?:log|tmp|tsbuildinfo)$/iu.test(name)) return "log or cache file";- if (extname(name).toLowerCase() === ".svrun" && normalized !== "build.svrun") return "non-canonical preview/mock/accepted-material Run";- return undefined;-}--async function fileDigest(path: string): Promise<string> {- const hash = createHash("sha256");- await new Promise<void>((fulfil, reject) => {- const stream = createReadStream(path);- stream.on("data", (chunk) => hash.update(chunk));- stream.on("error", reject);- stream.on("end", fulfil);- });- return `sha256:${hash.digest("hex")}`;-}--function manifestDigest(entries: readonly VariantManifestEntry[]): string {- return `sha256:${createHash("sha256").update(JSON.stringify(entries)).digest("hex")}`;-}--function jsonDigest(value: unknown): string {- return `sha256:${createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;-}--async function walkProject(root: string, preserveTopLevelOutputs = false): Promise<readonly VariantManifestEntry[]> {- const entries: VariantManifestEntry[] = [];- const visit = async (directory: string): Promise<void> => {- const children = await readdir(directory, { withFileTypes: true });- children.sort((left, right) => left.name.localeCompare(right.name));- for (const child of children) {- const path = join(directory, child.name);- const rel = normalizedRelative(relative(root, path));- if (exclusionReason(rel, child.isDirectory(), preserveTopLevelOutputs) !== undefined) continue;- const stats = await lstat(path);- if (stats.isDirectory()) {- await visit(path);- } else if (stats.isSymbolicLink()) {- const target = await readlink(path);- entries.push({ path: rel, kind: "symlink", digest: `sha256:${createHash("sha256").update(target).digest("hex")}`, size: target.length, mode: stats.mode & 0o777 });- } else if (stats.isFile()) {- entries.push({ path: rel, kind: "file", digest: await fileDigest(path), size: stats.size, mode: stats.mode & 0o777 });- }- }- };- await visit(root);- return entries.sort((left, right) => left.path.localeCompare(right.path));-}--export async function snapshotProject(projectRoot: string, options: { readonly preserveTopLevelOutputs?: boolean } = {}): Promise<{ readonly files: readonly VariantManifestEntry[]; readonly digest: string }> {- const files = await walkProject(resolve(projectRoot), options.preserveTopLevelOutputs === true);- return { files, digest: manifestDigest(files) };-}--async function copyOne(source: string, destination: string, mode: number): Promise<void> {- await mkdir(dirname(destination), { recursive: true });- try { await copyFile(source, destination, constants.COPYFILE_FICLONE); }- catch { await copyFile(source, destination); }- await chmod(destination, mode);-}--async function copySelectedTree(sourceRoot: string, destinationRoot: string, preserveTopLevelOutputs = false): Promise<void> {- const visit = async (sourceDirectory: string): Promise<void> => {- const children = await readdir(sourceDirectory, { withFileTypes: true });- children.sort((left, right) => left.name.localeCompare(right.name));- for (const child of children) {- const source = join(sourceDirectory, child.name);- const rel = normalizedRelative(relative(sourceRoot, source));- if (exclusionReason(rel, child.isDirectory(), preserveTopLevelOutputs) !== undefined) continue;- const destination = join(destinationRoot, rel);- const stats = await lstat(source);- if (stats.isDirectory()) {- await mkdir(destination, { recursive: true });- await visit(source);- } else if (stats.isSymbolicLink()) {- await mkdir(dirname(destination), { recursive: true });- await symlink(await readlink(source), destination);- } else if (stats.isFile()) {- await copyOne(source, destination, stats.mode & 0o777);- }- }- };- await mkdir(destinationRoot, { recursive: true });- await visit(sourceRoot);-}--function attribute(text: string, name: string): string | undefined {- return new RegExp(`\\b${name}="([^"]+)"`, "u").exec(text)?.[1];-}--export async function removeGeneratedRunBindings(runPath: string): Promise<{ readonly removed_build_records: readonly string[]; readonly removed_satisfactions: readonly string[] }> {- const original = await readFile(runPath, "utf8");- const runBody = (source: string): string => source.replace(/^\s*<\?svml\s+using="[^"]+"\?>\s*/u, "");- parseRunDocument(runPath, runBody(original));- const buildIds = new Set<string>();- for (const match of original.matchAll(/<build-record\b[^>]*\/\s*>/gsu)) {- const id = attribute(match[0], "id");- if (id !== undefined) buildIds.add(id);- }- if (buildIds.size === 0) return { removed_build_records: [], removed_satisfactions: [] };- const satisfactions: string[] = [];- let cleaned = original.replace(/<build-record\b[^>]*\/\s*>\s*/gsu, "");- cleaned = cleaned.replace(/<satisfy\b[^>]*\/\s*>\s*/gsu, (element) => {- const candidate = attribute(element, "candidate");- if (candidate === undefined || !buildIds.has(candidate)) return element;- satisfactions.push(candidate);- return "";- });- parseRunDocument(runPath, runBody(cleaned));- const temporary = `${runPath}.tmp-${process.pid}-${Date.now()}`;- await writeFile(temporary, cleaned, "utf8");- await rename(temporary, runPath);- return { removed_build_records: [...buildIds], removed_satisfactions: satisfactions };-}--function safeSlug(value: string): string {- const slug = value.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "");- if (slug.length === 0) throw new Error(`variant slug ${JSON.stringify(value)} has no filesystem-safe characters`);- return slug.slice(0, 64);-}--function validateVariantEntries(variants: readonly unknown[], path: string): asserts variants is readonly SlateVariant[] {- if (variants.length === 0) throw new Error(`${path} must contain at least one variant`);- const slugs = new Set<string>();- const ids = new Set<string>();- for (const [index, item] of variants.entries()) {- if (item === null || typeof item !== "object") throw new Error(`${path} variants[${index}] must be an object`);- const variant = item as Partial<SlateVariant>;- if (typeof variant.slug !== "string" || variant.slug.trim().length === 0) throw new Error(`${path} variants[${index}] has no slug`);- const slug = safeSlug(variant.slug);- if (slugs.has(slug)) throw new Error(`${path} repeats variant slug ${slug}`);- slugs.add(slug);- if (variant.id !== undefined) {- if (typeof variant.id !== "string" || variant.id.trim().length === 0) throw new Error(`${path} variants[${index}] has an invalid id`);- if (ids.has(variant.id.trim())) throw new Error(`${path} repeats variant id ${variant.id.trim()}`);- ids.add(variant.id.trim());- }- if (!Array.isArray(variant.allowed_changes) || variant.allowed_changes.length === 0 || variant.allowed_changes.some((entry) => typeof entry !== "string" || entry.trim().length === 0)) {- throw new Error(`${path} variants[${index}] must declare non-empty allowed_changes`);- }- for (const allowed of variant.allowed_changes) {- const normalized = normalizedRelative(allowed).replace(/^\.\//u, "");- if (isAbsolute(allowed) || normalized === ".." || normalized.startsWith("../") || normalized === ".hypit" || normalized.startsWith(".hypit/")) {- throw new Error(`${path} variants[${index}] has unsafe allowed_changes entry ${allowed}`);- }- }- const componentClass = variant.component_class;- if (componentClass !== undefined && componentClass !== "svml-only" && componentClass !== "existing-component"- && componentClass !== "composed-components" && componentClass !== "new-package") {- throw new Error(`${path} variants[${index}] has invalid component_class`);- }- if ((componentClass ?? "svml-only") === "svml-only") {- const normalizedAllowed = variant.allowed_changes.map((entry) => normalizedRelative(entry).replace(/^\.\//u, ""));- if (normalizedAllowed.length !== 1 || normalizedAllowed[0] !== "main.svml") {- throw new Error(`${path} variants[${index}] is svml-only and must allow exactly main.svml`);- }- }- if (variant.vocabulary?.mode !== undefined && variant.vocabulary.mode !== "inherited" && variant.vocabulary.mode !== "inspect") {- throw new Error(`${path} variants[${index}] has invalid vocabulary.mode`);- }- if (variant.vocabulary?.packages !== undefined && (!Array.isArray(variant.vocabulary.packages)- || variant.vocabulary.packages.some((entry) => typeof entry !== "string" || entry.trim().length === 0))) {- throw new Error(`${path} variants[${index}] has invalid vocabulary.packages`);- }- if ((componentClass === "existing-component" || componentClass === "composed-components" || componentClass === "new-package")- && (variant.vocabulary?.mode !== "inspect" || (variant.vocabulary.packages?.length ?? 0) === 0)) {- throw new Error(`${path} variants[${index}] changes components and must inspect at least one assigned package`);- }- const injections = variant.inject_packages ?? [];- if (!Array.isArray(injections) || injections.some((entry) => entry === null || typeof entry !== "object"- || typeof entry.package_id !== "string" || entry.package_id.trim().length === 0- || typeof entry.destination !== "string" || entry.destination.trim().length === 0)) {- throw new Error(`${path} variants[${index}] has invalid inject_packages`);- }- if ((componentClass ?? "svml-only") === "new-package" && injections.length === 0) {- throw new Error(`${path} variants[${index}] is new-package but declares no package injection`);- }- if ((componentClass ?? "svml-only") !== "new-package" && injections.length > 0) {- throw new Error(`${path} variants[${index}] may inject packages only when component_class is new-package`);- }- const injectionIds = injections.map((entry) => entry.package_id.trim());- if (new Set(injectionIds).size !== injectionIds.length) throw new Error(`${path} variants[${index}] repeats an injected package id`);- const injectionDestinations = injections.map((entry) => normalizedRelative(entry.destination).replace(/^\.\//u, ""));- if (new Set(injectionDestinations).size !== injectionDestinations.length) throw new Error(`${path} variants[${index}] repeats an injection destination`);- for (const destination of injectionDestinations) {- if (isAbsolute(destination) || destination === "packages" || !destination.startsWith("packages/")- || destination.includes("/../") || destination.endsWith("/..")) {- throw new Error(`${path} variants[${index}] has unsafe package injection destination ${destination}`);- }- }- }-}--function assertSlate(value: unknown, path: string): asserts value is VariantSlate {- if (value === null || typeof value !== "object") throw new Error(`${path} must contain directions`);- const slate = value as VariantSlate;- if (slate.count !== undefined && (!Number.isSafeInteger(slate.count) || slate.count <= 0)) {- throw new Error(`${path} count must be a positive integer`);- }- if (Array.isArray(slate.directions)) {- if (slate.directions.length === 0) throw new Error(`${path} must contain at least one direction`);- let total = 0;- const ids = new Set<string>();- const slugs = new Set<string>();- for (const [index, direction] of slate.directions.entries()) {- if (direction === null || typeof direction !== "object") throw new Error(`${path} directions[${index}] must be an object`);- if (typeof direction.id !== "string" || direction.id.trim().length === 0) throw new Error(`${path} directions[${index}] has no id`);- if (typeof direction.slug !== "string" || direction.slug.trim().length === 0) throw new Error(`${path} directions[${index}] has no slug`);- if (!Number.isSafeInteger(direction.count) || direction.count <= 0) throw new Error(`${path} directions[${index}] count must be a positive integer`);- const slug = safeSlug(direction.slug);- if (ids.has(direction.id.trim())) throw new Error(`${path} repeats direction id ${direction.id.trim()}`);- if (slugs.has(slug)) throw new Error(`${path} repeats direction slug ${slug}`);- ids.add(direction.id.trim()); slugs.add(slug); total += direction.count;- validateVariantEntries([{ ...direction, id: `${direction.id}-1`, slug: `${direction.slug}-1` }], `${path} directions[${index}]`);- }- if (slate.count !== undefined && slate.count !== total) throw new Error(`${path} count ${slate.count} does not equal direction quotas ${total}`);- return;- }- if (Array.isArray(slate.variants)) {- validateVariantEntries(slate.variants, path);- return;- }- throw new Error(`${path} must contain directions`);-}--export function expandVariantSlate(slate: VariantSlate, path = "slate.json"): readonly SlateVariant[] {- assertSlate(slate, path);- if (slate.directions === undefined) return slate.variants!;- const total = slate.directions.reduce((sum, direction) => sum + direction.count, 0);- const variants: SlateVariant[] = [];- for (const direction of slate.directions) {- const directionId = direction.id.trim();- const directionSlug = safeSlug(direction.slug);- for (let ordinal = 1; ordinal <= direction.count; ordinal += 1) {- const suffix = String(ordinal).padStart(Math.max(2, String(direction.count).length), "0");- const { count: _count, id: _directionId, slug: _directionSlug, ...template } = direction;- const brief = direction.brief !== undefined && direction.brief !== null && typeof direction.brief === "object"- ? { ...(direction.brief as Record<string, unknown>), direction_id: directionId, direction_index: ordinal }- : { direction: direction.brief ?? directionId, direction_id: directionId, direction_index: ordinal };- variants.push({ ...template, id: `${directionId}-${suffix}`, slug: `${directionSlug}-${suffix}`, brief } as SlateVariant);- }- }- const slugs = new Set(variants.map((variant) => safeSlug(variant.slug)));- if (slugs.size !== variants.length) throw new Error(`${path} direction quotas expand to duplicate variant slugs`);- if (slate.count !== undefined && slate.count !== variants.length) throw new Error(`${path} count ${slate.count} does not equal expanded variants ${variants.length}`);- return variants;-}--export async function writeVariantJson(path: string, value: unknown): Promise<void> {- await mkdir(dirname(path), { recursive: true });- const temporary = `${path}.tmp-${process.pid}-${Date.now()}`;- await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, "utf8");- await rename(temporary, path);-}--function inside(root: string, path: string): boolean {- const rel = relative(root, path);- return rel.length === 0 || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));-}--export type ApprovedVariantPackage = {- readonly id: string;- readonly package_root: string;- readonly digest: string;-};--async function injectPackages(- projectRoot: string,- injections: readonly SlatePackageInjection[] | undefined,- approvedPackages: ReadonlyMap<string, ApprovedVariantPackage>,-): Promise<VariantProjectManifest["package_injections"]> {- const injected: VariantProjectManifest["package_injections"][number][] = [];- for (const injection of injections ?? []) {- if (typeof injection?.package_id !== "string" || typeof injection.destination !== "string") throw new Error("inject_packages entries require package_id and destination");- const approved = approvedPackages.get(injection.package_id);- if (approved === undefined) throw new Error(`package injection ${injection.package_id} is not a ready frozen batch package`);- const source = resolve(approved.package_root);- const destination = resolve(projectRoot, injection.destination);- if (!inside(projectRoot, destination) || !normalizedRelative(relative(projectRoot, destination)).startsWith("packages/")) {- throw new Error(`package injection destination must stay under packages/: ${injection.destination}`);- }- const present = await lstat(destination).then(() => true, () => false);- if (present) throw new Error(`package injection would overwrite ${destination}`);- const sourceStats = await lstat(source).catch(() => undefined);- if (sourceStats?.isDirectory() !== true) throw new Error(`package injection source is not a directory: ${source}`);- const sourceDigest = (await snapshotProject(source, { preserveTopLevelOutputs: true })).digest;- if (sourceDigest !== approved.digest) throw new Error(`package injection ${injection.package_id} changed after it was frozen: expected ${approved.digest}, found ${sourceDigest}`);- await copySelectedTree(source, destination, true);- const destinationDigest = (await snapshotProject(destination, { preserveTopLevelOutputs: true })).digest;- if (destinationDigest !== approved.digest) throw new Error(`package injection ${injection.package_id} did not copy byte-for-byte into ${destination}`);- injected.push({ package_id: injection.package_id, destination: normalizedRelative(relative(projectRoot, destination)), digest: approved.digest });- }- return injected;-}--export async function inspectSourceVocabularyUsage(runPath: string): Promise<{ readonly imports: readonly string[]; readonly tags: readonly string[] }> {- const visited = new Set<string>();- const imports = new Set<string>();- const tags = new Set<string>();- const visit = async (path: string): Promise<void> => {- const absolute = resolve(path);- if (visited.has(absolute)) return;- visited.add(absolute);- const source = await readFile(absolute, "utf8");- for (const match of source.matchAll(/\bfrom="([^"]+)@\d+"/gu)) if (match[1]!.startsWith("@")) imports.add(match[1]!);- for (const match of source.matchAll(/<([A-Z][A-Za-z0-9_.:-]*)\b/gu)) tags.add(match[1]!);- for (const match of source.matchAll(/\bsource="([^"#]+)"/gu)) {- const child = match[1]!;- if (child.startsWith("@") || child.startsWith("http://") || child.startsWith("https://")) continue;- await visit(resolve(dirname(absolute), child));- }- };- await visit(runPath);- return { imports: [...imports].sort(), tags: [...tags].sort() };-}--export async function initializeVariantProjects(input: {- readonly projectRoot: string;- readonly outputRoot: string;- readonly slatePath: string;- readonly expectedBaseDigest?: string;- readonly expectedCount?: number;- readonly approvedPackages?: readonly ApprovedVariantPackage[];-}): Promise<{ readonly slate: VariantSlate; readonly base_digest: string; readonly variants: readonly InitializedVariant[] }> {- const projectRoot = resolve(input.projectRoot);- const outputRoot = resolve(input.outputRoot);- if (inside(projectRoot, outputRoot)) throw new Error("variant output root must not be inside the base project");- const slatePath = resolve(input.slatePath);- let slateValue: unknown;- try { slateValue = JSON.parse(await readFile(slatePath, "utf8")); }- catch (error) { throw new Error(`cannot read slate ${slatePath}: ${error instanceof Error ? error.message : String(error)}`); }- assertSlate(slateValue, slatePath);- const slate = slateValue;- const variantsInSlate = expandVariantSlate(slate, slatePath);- if (input.expectedCount !== undefined && variantsInSlate.length !== input.expectedCount) {- throw new Error(`slate expands to ${variantsInSlate.length} variants, expected ${input.expectedCount}`);- }- const approvedPackages = new Map((input.approvedPackages ?? []).map((pack) => [pack.id, pack]));- for (const variant of variantsInSlate) {- for (const injection of variant.inject_packages ?? []) {- if (!approvedPackages.has(injection.package_id)) throw new Error(`slate references package ${injection.package_id}, which is not ready and frozen in batch state`);- }- }- const base = await snapshotProject(projectRoot);- if (input.expectedBaseDigest !== undefined && input.expectedBaseDigest !== base.digest) {- throw new Error(`base project digest changed: expected ${input.expectedBaseDigest}, found ${base.digest}`);- }- await mkdir(outputRoot, { recursive: true });- const width = Math.max(3, String(variantsInSlate.length).length);- const currentRoute = await readFile(join(projectRoot, ".hypit", "route-state.json"), "utf8")- .then((text) => JSON.parse(text) as { artifacts?: { vocabulary?: unknown } }, () => undefined)- .catch(() => undefined);- const inheritedVocabulary = typeof currentRoute?.artifacts?.vocabulary === "string"- ? currentRoute.artifacts.vocabulary- : join(projectRoot, ".hypit", "vocabulary.json");- const initialized: InitializedVariant[] = [];- const assignedIds = new Set<string>();- for (const [index, variant] of variantsInSlate.entries()) {- const number = String(index + 1).padStart(width, "0");- const slug = safeSlug(variant.slug);- const id = typeof variant.id === "string" && variant.id.trim().length > 0 ? variant.id.trim() : number;- const slateEntryDigest = jsonDigest(variant);- if (assignedIds.has(id)) throw new Error(`slate resolves more than one variant to id ${id}`);- assignedIds.add(id);- const variantRoot = join(outputRoot, `${number}-${slug}`);- const manifestPath = join(variantRoot, ".hypit", "variant-baseline-manifest.json");- const alreadyInitialized = await readFile(manifestPath, "utf8").then(() => true, () => false);- if (alreadyInitialized) {- let manifest: VariantProjectManifest;- let brief: { id?: unknown; slug?: unknown; slate_entry_digest?: unknown };- let allowed: { allowed_changes?: unknown };- try {- manifest = JSON.parse(await readFile(manifestPath, "utf8")) as VariantProjectManifest;- brief = JSON.parse(await readFile(join(variantRoot, ".hypit", "variant-brief.json"), "utf8")) as { id?: unknown; slug?: unknown; slate_entry_digest?: unknown };- allowed = JSON.parse(await readFile(join(variantRoot, ".hypit", "allowed-changes.json"), "utf8")) as { allowed_changes?: unknown };- } catch (error) {- throw new Error(`existing variant ${variantRoot} has unreadable initialization evidence: ${error instanceof Error ? error.message : String(error)}`);- }- const diff = await inspectVariantDiff(variantRoot);- if (manifest.base_digest !== base.digest || manifest.slate_entry_digest !== slateEntryDigest- || brief.id !== id || brief.slug !== slug || brief.slate_entry_digest !== slateEntryDigest- || JSON.stringify(allowed.allowed_changes) !== JSON.stringify(variant.allowed_changes)- || diff.passed !== true) {- throw new Error(`existing variant ${variantRoot} conflicts with the current base or slate`);- }- } else {- const occupied = await readdir(variantRoot).then((items) => items.length > 0, () => false);- if (occupied) throw new Error(`variant destination already exists without a manifest: ${variantRoot}`);- await copySelectedTree(projectRoot, variantRoot);- const run = join(variantRoot, "build.svrun");- const hasRun = await lstat(run).then((stats) => stats.isFile(), () => false);- if (!hasRun) throw new Error(`base project has no canonical top-level build.svrun`);- await removeGeneratedRunBindings(run);- const packageInjections = await injectPackages(variantRoot, variant.inject_packages, approvedPackages);- const vocabularyMode = variant.vocabulary?.mode ?? "inherited";- let vocabularyDigest: string | undefined;- if (vocabularyMode === "inherited") {- const evidence = await readFile(inheritedVocabulary).catch(() => undefined);- if (evidence === undefined) throw new Error(`variant ${id} inherits vocabulary but ${inheritedVocabulary} is missing`);- vocabularyDigest = `sha256:${createHash("sha256").update(evidence).digest("hex")}`;- await mkdir(join(variantRoot, ".hypit"), { recursive: true });- await writeFile(join(variantRoot, ".hypit", "vocabulary.json"), evidence);- }- const briefPath = join(variantRoot, ".hypit", "variant-brief.json");- const allowedPath = join(variantRoot, ".hypit", "allowed-changes.json");- await writeVariantJson(briefPath, { ...variant, id, slug, slate_entry_digest: slateEntryDigest, index: index + 1, batch_root: outputRoot, base_project_root: projectRoot });- await writeVariantJson(allowedPath, { allowed_changes: variant.allowed_changes });- const copied = await snapshotProject(variantRoot);- const sourceUsage = await inspectSourceVocabularyUsage(join(variantRoot, "build.svrun"));- const manifest: VariantProjectManifest = {- version: 1, project_root: variantRoot, base_project_root: projectRoot, base_digest: base.digest,- slate_entry_digest: slateEntryDigest, allowed_changes: variant.allowed_changes,- vocabulary_mode: vocabularyMode, vocabulary_packages: variant.vocabulary?.packages ?? [],- ...(vocabularyDigest === undefined ? {} : { vocabulary_digest: vocabularyDigest }),- source_imports: sourceUsage.imports, source_tags: sourceUsage.tags, package_injections: packageInjections,- files: copied.files, digest: copied.digest, created_at: new Date().toISOString(),- };- await writeVariantJson(manifestPath, manifest);- }- const componentClass = variant.component_class === "existing-component" || variant.component_class === "composed-components" || variant.component_class === "new-package"- ? variant.component_class : "svml-only";- const persistedManifest = JSON.parse(await readFile(manifestPath, "utf8")) as VariantProjectManifest;- initialized.push({- id, slug, project_root: variantRoot, run: join(variantRoot, "build.svrun"), manifest: manifestPath,- brief: join(variantRoot, ".hypit", "variant-brief.json"), allowed_changes: join(variantRoot, ".hypit", "allowed-changes.json"),- allowed_change_paths: persistedManifest.allowed_changes,- component_class: componentClass, vocabulary_mode: variant.vocabulary?.mode ?? "inherited",- vocabulary_packages: variant.vocabulary?.packages ?? [],- ...(persistedManifest.vocabulary_digest === undefined ? {} : { vocabulary_digest: persistedManifest.vocabulary_digest }),- package_injections: persistedManifest.package_injections,- status: "ready",- });- }- return { slate, base_digest: base.digest, variants: initialized };-}--function globExpression(pattern: string): RegExp {- const normalized = normalizedRelative(pattern).replace(/^\.\//u, "");- let source = "^";- for (let index = 0; index < normalized.length; index += 1) {- const character = normalized[index]!;- if (character === "*") {- if (normalized[index + 1] === "*") { source += ".*"; index += 1; }- else source += "[^/]*";- } else if (character === "?") source += "[^/]";- else source += character.replace(/[|\\{}()[\]^$+?.]/gu, "\\$&");- }- return new RegExp(`${source}$`, "u");-}--export async function inspectVariantDiff(projectRoot: string): Promise<Record<string, unknown>> {- const root = resolve(projectRoot);- const manifestPath = join(root, ".hypit", "variant-baseline-manifest.json");- let manifest: VariantProjectManifest;- try { manifest = JSON.parse(await readFile(manifestPath, "utf8")) as VariantProjectManifest; }- catch (error) { return { passed: false, manifest: manifestPath, errors: [`BASELINE_MANIFEST_UNREADABLE: ${error instanceof Error ? error.message : String(error)}`] }; }- if (manifest.version !== 1 || !Array.isArray(manifest.files) || !Array.isArray(manifest.allowed_changes)) {- return { passed: false, manifest: manifestPath, errors: ["BASELINE_MANIFEST_INVALID"] };- }- const allowedPath = join(root, ".hypit", "allowed-changes.json");- const allowedChanges = manifest.allowed_changes;- try {- const currentAllowed = JSON.parse(await readFile(allowedPath, "utf8")) as { allowed_changes?: unknown };- if (!Array.isArray(currentAllowed.allowed_changes) || currentAllowed.allowed_changes.some((item) => typeof item !== "string" || item.trim().length === 0)) {- return { passed: false, manifest: manifestPath, allowed_changes: allowedPath, errors: ["ALLOWED_CHANGES_INVALID"] };- }- if (JSON.stringify(currentAllowed.allowed_changes) !== JSON.stringify(manifest.allowed_changes)) {- return { passed: false, manifest: manifestPath, allowed_changes: allowedPath, errors: ["ALLOWED_CHANGES_CHANGED_OUTSIDE_BATCH_STATE"], outside_allowed_changes: [] };- }- } catch (error) {- return { passed: false, manifest: manifestPath, allowed_changes: allowedPath, errors: [`ALLOWED_CHANGES_UNREADABLE: ${error instanceof Error ? error.message : String(error)}`] };- }- const current = await snapshotProject(root);- const before = new Map(manifest.files.map((entry) => [entry.path, entry]));- const after = new Map(current.files.map((entry) => [entry.path, entry]));- const changed = [...new Set([...before.keys(), ...after.keys()])].filter((path) => {- const left = before.get(path); const right = after.get(path);- return left?.digest !== right?.digest || left?.kind !== right?.kind || left?.mode !== right?.mode;- }).sort();- const allowed = allowedChanges.map(globExpression);- const outside = changed.filter((path) => !allowed.some((pattern) => pattern.test(path)));- return {- passed: outside.length === 0,- manifest: manifestPath,- baseline_digest: manifest.digest,- current_digest: current.digest,- allowed_changes: allowedChanges,- changed,- outside_allowed_changes: outside,- };-}--export async function findGeneratedLeakage(projectRoot: string, runPath: string): Promise<Record<string, unknown>> {- const root = resolve(projectRoot);- const leaks: { path: string; reason: string }[] = [];- const visit = async (directory: string): Promise<void> => {- for (const child of await readdir(directory, { withFileTypes: true }).catch(() => [])) {- const path = join(directory, child.name);- const rel = normalizedRelative(relative(root, path));- if (rel === ".hypit" || rel.startsWith(".hypit/") || rel === "node_modules" || rel.startsWith("node_modules/") || rel === ".git" || rel.startsWith(".git/")) continue;- const reason = exclusionReason(rel, child.isDirectory());- if (reason !== undefined) { leaks.push({ path: rel, reason }); continue; }- if (child.isDirectory()) await visit(path);- }- };- await visit(root);- const run = await readFile(resolve(runPath), "utf8").catch(() => "");- const generatedCandidates = [...run.matchAll(/<build-record\b[^>]*\bid="([^"]+)"[^>]*\/\s*>/gsu)].map((match) => match[1]!);- return { passed: leaks.length === 0 && generatedCandidates.length === 0, leaks, generated_build_candidates: generatedCandidates };-}diff --git a/packages/reference-video-tools/src/variant-state.ts b/packages/reference-video-tools/src/variant-state.tsdeleted file mode 100644index 6909e6a5..00000000--- a/packages/reference-video-tools/src/variant-state.ts+++ /dev/null@@ -1,572 +0,0 @@-import { createHash } from "node:crypto";-import { mkdir, open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";--import { checkpointRouteState, readRouteState, reconcileRouteState, routeExecutionStatePath, routeStatePath } from "./route-state.js";-import { readRevisionState, revisionExecutionStatePath } from "./revision-state.js";-import { persistEvidence } from "./state-files.js";-import { expandVariantSlate, inspectVariantDiff, snapshotProject } from "./variant-project.js";-import type { VariantSlate } from "./variant-project.js";--export type VariantExpansionStatus = "active" | "complete" | "blocked";-export type VariantExpansionStep =- | "baseline-validated" | "examples-inspected" | "format-plan-frozen" | "slate-drafted"- | "vocabulary-enumerated" | "component-plan-frozen" | "package-gaps-classified"- | "workload-disclosed" | "package-gaps-resolved" | "slate-frozen" | "projects-copied"- | "variants-dispatched" | "variants-complete" | "aggregate-checked" | "build-planned"- | "build-approved" | "build-complete" | "expansion-complete";--export const VARIANT_EXPANSION_STATE_VERSION = 1 as const;-export const VARIANT_EXPANSION_STEPS: readonly VariantExpansionStep[] = [- "baseline-validated", "examples-inspected", "format-plan-frozen", "slate-drafted",- "vocabulary-enumerated", "component-plan-frozen", "package-gaps-classified", "workload-disclosed",- "package-gaps-resolved", "slate-frozen", "projects-copied", "variants-dispatched",- "variants-complete", "aggregate-checked", "build-planned", "build-approved", "build-complete",- "expansion-complete",-];--export type VariantWorkloadDisclosure = {- readonly svml_only: number;- readonly medium: number;- readonly new_packages: number;- readonly package_purposes?: readonly string[];- readonly paid_generation: boolean;- readonly disclosed_at: string;-};--export type VariantExpansionVariant = {- readonly id: string;- readonly slug: string;- readonly project_root: string;- readonly run: string;- readonly route_state: string;- readonly manifest: string;- readonly brief: string;- readonly format_plan?: string;- readonly component_plan?: string;- readonly allowed_changes: string;- readonly allowed_change_paths: readonly string[];- readonly component_class: "svml-only" | "existing-component" | "composed-components" | "new-package";- readonly vocabulary_mode: "inherited" | "inspect";- readonly vocabulary_packages: readonly string[];- readonly vocabulary_digest?: string;- readonly package_injections: readonly { readonly package_id: string; readonly destination: string; readonly digest: string }[];- readonly status: "ready" | "dispatched" | "complete" | "failed" | "scope-expansion-required";- readonly error?: string;-};--export type VariantExpansionPackage = {- readonly id: string;- readonly purpose: string;- readonly staging_root: string;- readonly package_root?: string;- readonly route_state: string;- readonly digest?: string;- readonly status: "planned" | "active" | "ready" | "failed";- readonly error?: string;-};--export type VariantExpansionState = {- readonly version: 1;- readonly batch_id: string;- readonly project_root: string;- readonly output_root: string;- readonly run?: string;- readonly baseline_digest: string;- readonly parent_route?: "reconstruction" | "description" | "variant";- readonly parent_state_digest?: string;- readonly parent_state_path?: string;- readonly revision_state_digest?: string;- readonly revision_state_path?: string;- readonly request?: string;- readonly count?: number;- readonly delivery_mode: "source" | "build";- readonly status: VariantExpansionStatus;- readonly current_step: number;- readonly completed_steps: readonly number[];- readonly in_progress: { readonly step: number; readonly started_at: string } | null;- readonly artifacts: Readonly<Record<string, string>>;- readonly workload_disclosure?: VariantWorkloadDisclosure;- readonly packages: readonly VariantExpansionPackage[];- readonly variants: readonly VariantExpansionVariant[];- readonly decisions: readonly string[];- readonly conflicts: readonly string[];- readonly next_action: string;- readonly last_command?: string;- readonly last_error?: string;- readonly created_at: string;- readonly updated_at: string;-};--export type VariantExpansionLocator = {- readonly version: 1;- readonly batch_id: string;- readonly project_root: string;- readonly output_root: string;- readonly state_path: string;- readonly baseline_digest: string;- readonly status: VariantExpansionStatus;- readonly updated_at: string;-};--export type StartVariantExpansionInput = {- readonly projectRoot: string;- readonly outputRoot: string;- readonly run?: string;- readonly request?: string;- readonly count?: number;- readonly deliveryMode?: "source" | "build";- readonly parentRoute?: "reconstruction" | "description" | "variant";- readonly parentStateDigest?: string;- readonly revisionStateDigest?: string;-};--export type VariantExpansionCheckpointInput = {- readonly projectRoot: string;- readonly outputRoot?: string;- readonly batchId?: string;- readonly step: number | VariantExpansionStep;- readonly status?: "in_progress" | "complete" | "blocked";- readonly nextAction?: string;- readonly artifacts?: Readonly<Record<string, string>>;- readonly workloadDisclosure?: VariantWorkloadDisclosure;- readonly packages?: readonly VariantExpansionPackage[];- readonly variants?: readonly VariantExpansionVariant[];- readonly variantUpdates?: readonly VariantExpansionVariant[];- readonly decision?: string;- readonly conflict?: string;- readonly resolveConflict?: string;- readonly command?: string;- readonly error?: string;-};--export function variantExpansionStatePath(outputRoot: string): string {- return join(resolve(outputRoot), ".hypit", "variant-expansion-state.json");-}--export function variantExpansionLocatorPath(projectRoot: string, batchId: string): string {- return join(resolve(projectRoot), ".hypit", "variant-expansions", `${batchId}.json`);-}--async function digestFile(path: string): Promise<string | undefined> {- const bytes = await readFile(path).catch(() => undefined);- return bytes === undefined ? undefined : `sha256:${createHash("sha256").update(bytes).digest("hex")}`;-}--async function atomicJson(path: string, value: unknown): Promise<void> {- await mkdir(dirname(path), { recursive: true });- const temporary = `${path}.tmp-${process.pid}-${Date.now()}`;- await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, "utf8");- await rename(temporary, path);-}--async function withStateLock<T>(outputRoot: string, work: () => Promise<T>): Promise<T> {- const lockPath = join(resolve(outputRoot), ".hypit", "variant-expansion-state.lock");- await mkdir(dirname(lockPath), { recursive: true });- for (let attempt = 0; attempt < 3_000; attempt += 1) {- const handle = await open(lockPath, "wx").catch((error: unknown) => {- if ((error as NodeJS.ErrnoException).code === "EEXIST") return undefined;- throw error;- });- if (handle !== undefined) {- try {- await handle.writeFile(`${process.pid}\n`, "utf8");- return await work();- } finally {- await handle.close().catch(() => undefined);- await unlink(lockPath).catch(() => undefined);- }- }- const stale = await stat(lockPath).then((value) => Date.now() - value.mtimeMs > 300_000, () => false);- if (stale) await unlink(lockPath).catch(() => undefined);- await new Promise((resolveWait) => setTimeout(resolveWait, 10));- }- throw new Error(`timed out waiting for variant state lock at ${lockPath}`);-}--function assertLocator(value: unknown, path: string): asserts value is VariantExpansionLocator {- if (value === null || typeof value !== "object") throw new Error(`variant locator at ${path} is not an object`);- const locator = value as Partial<VariantExpansionLocator>;- if (locator.version !== 1 || typeof locator.batch_id !== "string" || typeof locator.output_root !== "string" || typeof locator.state_path !== "string") {- throw new Error(`variant locator at ${path} is invalid`);- }-}--function assertState(value: unknown, path: string): asserts value is VariantExpansionState {- if (value === null || typeof value !== "object") throw new Error(`variant expansion state at ${path} is not an object`);- const state = value as Partial<VariantExpansionState>;- if (state.version !== 1) throw new Error(`variant expansion state at ${path} has unsupported version`);- if (typeof state.batch_id !== "string" || typeof state.project_root !== "string" || typeof state.output_root !== "string") throw new Error(`variant expansion state at ${path} has invalid roots`);- if (typeof state.baseline_digest !== "string" || (state.delivery_mode !== "source" && state.delivery_mode !== "build")) throw new Error(`variant expansion state at ${path} has invalid baseline metadata`);- if (state.status !== "active" && state.status !== "complete" && state.status !== "blocked") throw new Error(`variant expansion state at ${path} has invalid status`);- if (!Number.isSafeInteger(state.current_step) || state.current_step! < 1 || state.current_step! > VARIANT_EXPANSION_STEPS.length + 1) throw new Error(`variant expansion state at ${path} has invalid current_step`);- if (!Array.isArray(state.completed_steps) || state.completed_steps.some((step) => !Number.isSafeInteger(step) || step < 1 || step > VARIANT_EXPANSION_STEPS.length)) throw new Error(`variant expansion state at ${path} has invalid completed_steps`);- if (state.artifacts === null || typeof state.artifacts !== "object" || Array.isArray(state.artifacts)) throw new Error(`variant expansion state at ${path} has invalid artifacts`);- if (!Array.isArray(state.packages) || !Array.isArray(state.variants) || !Array.isArray(state.decisions) || !Array.isArray(state.conflicts)) throw new Error(`variant expansion state at ${path} has invalid collections`);- if (typeof state.next_action !== "string" || typeof state.created_at !== "string" || typeof state.updated_at !== "string") throw new Error(`variant expansion state at ${path} is missing recovery fields`);-}--async function readJsonPreserving(path: string, subject: string): Promise<unknown | undefined> {- const text = await readFile(path, "utf8").catch((error: unknown) => {- if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;- throw error;- });- if (text === undefined) return undefined;- try { return JSON.parse(text); }- catch (error) { throw new Error(`${subject} at ${path} is invalid JSON; original file was preserved: ${error instanceof Error ? error.message : String(error)}`); }-}--async function writeLocator(state: VariantExpansionState): Promise<void> {- const locator: VariantExpansionLocator = {- version: 1, batch_id: state.batch_id, project_root: state.project_root, output_root: state.output_root,- state_path: variantExpansionStatePath(state.output_root), baseline_digest: state.baseline_digest,- status: state.status, updated_at: state.updated_at,- };- await atomicJson(variantExpansionLocatorPath(state.project_root, state.batch_id), locator);-}--async function writeState(state: VariantExpansionState): Promise<VariantExpansionState> {- await atomicJson(variantExpansionStatePath(state.output_root), state);- await writeLocator(state);- return state;-}--export async function discoverVariantExpansions(projectRoot: string): Promise<readonly VariantExpansionLocator[]> {- const root = join(resolve(projectRoot), ".hypit", "variant-expansions");- const files = await import("node:fs/promises").then(({ readdir }) => readdir(root)).catch((error: unknown) => {- if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];- throw error;- });- const locators: VariantExpansionLocator[] = [];- for (const file of files.filter((name) => name.endsWith(".json")).sort()) {- const path = join(root, file);- const value = await readJsonPreserving(path, "variant locator");- assertLocator(value, path);- locators.push(value);- }- return locators.sort((left, right) => right.updated_at.localeCompare(left.updated_at));-}--async function selectedLocator(projectRoot: string, outputRoot?: string, batchId?: string): Promise<VariantExpansionLocator | undefined> {- if (outputRoot !== undefined) {- const path = variantExpansionStatePath(outputRoot);- const state = await readJsonPreserving(path, "variant expansion state");- if (state === undefined) return undefined;- assertState(state, path);- if (resolve(state.project_root) !== resolve(projectRoot)) throw new Error(`${path} belongs to ${state.project_root}, not ${resolve(projectRoot)}`);- return {- version: 1, batch_id: state.batch_id, project_root: state.project_root, output_root: state.output_root,- state_path: path, baseline_digest: state.baseline_digest, status: state.status, updated_at: state.updated_at,- };- }- const locators = await discoverVariantExpansions(projectRoot);- if (batchId !== undefined) return locators.find((item) => item.batch_id === batchId);- return locators.find((item) => item.status !== "complete") ?? locators[0];-}--export async function readVariantExpansionState(projectRoot: string, outputRoot?: string, batchId?: string): Promise<VariantExpansionState | undefined> {- const locator = await selectedLocator(projectRoot, outputRoot, batchId);- if (locator === undefined) return undefined;- const value = await readJsonPreserving(locator.state_path, "variant expansion state");- if (value === undefined) throw new Error(`variant locator ${variantExpansionLocatorPath(projectRoot, locator.batch_id)} points to missing state ${locator.state_path}`);- assertState(value, locator.state_path);- if (resolve(value.project_root) !== resolve(projectRoot)) throw new Error(`${locator.state_path} belongs to ${value.project_root}, not ${resolve(projectRoot)}`);- return value;-}--function nextUncompleted(completed: ReadonlySet<number>, deliveryMode: "source" | "build"): number {- const optional = deliveryMode === "source" ? new Set([15, 16, 17]) : new Set<number>();- for (let step = 1; step <= VARIANT_EXPANSION_STEPS.length; step += 1) {- if (!optional.has(step) && !completed.has(step)) return step;- }- return VARIANT_EXPANSION_STEPS.length + 1;-}--function stepNumber(step: number | VariantExpansionStep): number {- if (typeof step === "number") {- if (!Number.isSafeInteger(step) || step < 1 || step > VARIANT_EXPANSION_STEPS.length) throw new Error(`variant expansion step ${step} is outside the route`);- return step;- }- const index = VARIANT_EXPANSION_STEPS.indexOf(step);- if (index < 0) throw new Error(`unknown variant expansion step ${step}`);- return index + 1;-}--function requiredPriorSteps(step: number, deliveryMode: "source" | "build"): readonly number[] {- const optional = deliveryMode === "source" ? new Set([15, 16, 17]) : new Set<number>();- return Array.from({ length: step - 1 }, (_, index) => index + 1).filter((candidate) => !optional.has(candidate));-}--async function startVariantExpansionUnlocked(input: StartVariantExpansionInput): Promise<VariantExpansionState> {- const projectRoot = resolve(input.projectRoot);- const outputRoot = resolve(input.outputRoot);- const outputRelative = relative(projectRoot, outputRoot);- if (outputRelative.length === 0 || (!outputRelative.startsWith(`..${sep}`) && outputRelative !== ".." && !isAbsolute(outputRelative))) {- throw new Error("variant output root must not be inside the base project");- }- const batchId = basename(outputRoot);- if (batchId.length === 0 || batchId === "." || batchId === "..") throw new Error("variant output root must end in a batch id");- if (input.count !== undefined && (!Number.isSafeInteger(input.count) || input.count < 1)) throw new Error("variant count must be a positive integer");- const existing = await readVariantExpansionState(projectRoot, outputRoot);- if (existing !== undefined) return existing;- const locatorAtId = await readJsonPreserving(variantExpansionLocatorPath(projectRoot, batchId), "variant locator");- if (locatorAtId !== undefined) {- assertLocator(locatorAtId, variantExpansionLocatorPath(projectRoot, batchId));- if (resolve(locatorAtId.output_root) !== outputRoot) throw new Error(`batch id ${batchId} already points to ${locatorAtId.output_root}`);- }- const baseline = await snapshotProject(projectRoot);- const parentState = await readRouteState(projectRoot);- const revisionState = await readRevisionState(projectRoot);- const parentStatePath = parentState === undefined ? undefined : routeExecutionStatePath(projectRoot, parentState.route_id);- const revisionStatePath = revisionState === undefined ? undefined : revisionExecutionStatePath(projectRoot, revisionState.revision_id);- const parentStateBytes = parentStatePath === undefined ? undefined : await readFile(parentStatePath).catch(() => undefined);- const parentStateDigest = input.parentStateDigest- ?? (parentStateBytes === undefined ? undefined : `sha256:${createHash("sha256").update(parentStateBytes).digest("hex")}`);- const revisionStateDigest = input.revisionStateDigest ?? (revisionStatePath === undefined ? undefined : await digestFile(revisionStatePath));- let parentRoute = input.parentRoute;- if (parentRoute === undefined && parentStateBytes !== undefined) {- try {- const parsed = JSON.parse(parentStateBytes.toString()) as { route?: unknown };- if (parsed.route === "reconstruction" || parsed.route === "description" || parsed.route === "variant") parentRoute = parsed.route;- } catch { /* corrupt parent state is reported by reconcile rather than hidden here */ }- }- const now = new Date().toISOString();- return writeState({- version: 1, batch_id: batchId, project_root: projectRoot, output_root: outputRoot,- ...(input.run === undefined ? {} : { run: resolve(projectRoot, input.run) }),- baseline_digest: baseline.digest,- ...(parentRoute === undefined ? {} : { parent_route: parentRoute }),- ...(parentStateDigest === undefined ? {} : { parent_state_digest: parentStateDigest }),- ...(parentStatePath === undefined ? {} : { parent_state_path: parentStatePath }),- ...(revisionStateDigest === undefined ? {} : { revision_state_digest: revisionStateDigest }),- ...(revisionStatePath === undefined ? {} : { revision_state_path: revisionStatePath }),- ...(input.request === undefined ? {} : { request: input.request }),- ...(input.count === undefined ? {} : { count: input.count }),- delivery_mode: input.deliveryMode ?? "source", status: "active", current_step: 1, completed_steps: [],- in_progress: { step: 1, started_at: now }, artifacts: {}, packages: [], variants: [], decisions: [], conflicts: [],- next_action: `complete ${VARIANT_EXPANSION_STEPS[0]}`, created_at: now, updated_at: now,- });-}--export async function startVariantExpansion(input: StartVariantExpansionInput): Promise<VariantExpansionState> {- const projectRoot = resolve(input.projectRoot);- const outputRoot = resolve(input.outputRoot);- const outputRelative = relative(projectRoot, outputRoot);- if (outputRelative.length === 0 || (!outputRelative.startsWith(`..${sep}`) && outputRelative !== ".." && !isAbsolute(outputRelative))) {- throw new Error("variant output root must not be inside the base project");- }- return withStateLock(outputRoot, async () => startVariantExpansionUnlocked(input));-}--async function checkpointVariantExpansionUnlocked(input: VariantExpansionCheckpointInput): Promise<VariantExpansionState> {- const existing = await readVariantExpansionState(input.projectRoot, input.outputRoot, input.batchId);- if (existing === undefined) throw new Error("no variant expansion state; run variant_state --action start first");- const step = stepNumber(input.step);- const status = input.status ?? "complete";- const completed = new Set(existing.completed_steps);- if (status === "complete" && typeof input.step === "string") {- const missing = requiredPriorSteps(step, existing.delivery_mode).filter((candidate) => !completed.has(candidate));- if (missing.length > 0) throw new Error(`cannot complete ${VARIANT_EXPANSION_STEPS[step - 1]} before ${missing.map((candidate) => VARIANT_EXPANSION_STEPS[candidate - 1]).join(", ")}`);- }- if (status === "complete" && step === 8 && input.workloadDisclosure === undefined && existing.workload_disclosure === undefined) {- throw new Error("workload-disclosed requires a persisted workload_disclosure");- }- if (input.workloadDisclosure !== undefined && existing.count !== undefined- && input.workloadDisclosure.svml_only + input.workloadDisclosure.medium !== existing.count) {- throw new Error(`workload disclosure accounts for ${input.workloadDisclosure.svml_only + input.workloadDisclosure.medium} variants, expected ${existing.count}`);- }- if (status === "complete") completed.add(step);- const next = status === "complete" ? nextUncompleted(completed, existing.delivery_mode) : step;- const now = new Date().toISOString();- const artifacts = input.artifacts === undefined ? existing.artifacts : {- ...existing.artifacts,- ...Object.fromEntries(Object.entries(input.artifacts).map(([key, value]) => [key, resolve(existing.project_root, value)])),- };- const decisions = input.decision === undefined || input.decision.trim().length === 0 || existing.decisions.includes(input.decision.trim())- ? existing.decisions : [...existing.decisions, input.decision.trim()];- const resolved = input.resolveConflict?.trim();- const retainedConflicts = resolved === undefined || resolved.length === 0- ? existing.conflicts : existing.conflicts.filter((message) => message !== resolved);- const conflicts = input.conflict === undefined || input.conflict.trim().length === 0 || retainedConflicts.includes(input.conflict.trim())- ? retainedConflicts : [...retainedConflicts, input.conflict.trim()];- if (input.packages !== undefined) {- const packageIds = input.packages.map((pack) => pack.id);- if (packageIds.some((id) => id.trim().length === 0) || new Set(packageIds).size !== packageIds.length) {- throw new Error("variant packages require distinct non-empty ids");- }- }- const packages: VariantExpansionPackage[] | undefined = input.packages === undefined ? undefined : await Promise.all(input.packages.map(async (pack) => {- if (pack.status !== "ready") return pack;- const route = await readRouteState(pack.staging_root);- if (route?.route !== "variant-package") throw new Error(`package ${pack.id} has no variant-package route at ${pack.staging_root}`);- const stagingRoot = resolve(pack.staging_root);- const packageRoot = resolve(pack.package_root ?? pack.staging_root);- const packageRelative = relative(stagingRoot, packageRoot);- if (packageRelative === ".." || packageRelative.startsWith(`..${sep}`) || isAbsolute(packageRelative)) {- throw new Error(`package ${pack.id} package_root must stay inside its staging project`);- }- const digest = (await snapshotProject(packageRoot, { preserveTopLevelOutputs: true })).digest;- const evidence = await persistEvidence(pack.staging_root, "package-digest.json", { package_id: pack.id, staging_root: stagingRoot, package_root: packageRoot, digest, frozen_at: now });- await checkpointRouteState({ projectRoot: pack.staging_root, route: "variant-package", step: "package-ready", status: "complete", artifacts: { package_digest: evidence } });- return { ...pack, staging_root: stagingRoot, package_root: packageRoot, route_state: routeStatePath(pack.staging_root), digest };- }));- const variants = input.variantUpdates === undefined- ? input.variants- : existing.variants.map((variant) => input.variantUpdates!.find((update) => update.id === variant.id) ?? variant);- return writeState({- ...existing,- status: status === "blocked" ? "blocked" : next > VARIANT_EXPANSION_STEPS.length ? "complete" : "active",- current_step: next, completed_steps: [...completed].sort((a, b) => a - b),- in_progress: next > VARIANT_EXPANSION_STEPS.length ? null : { step: next, started_at: now },- artifacts, decisions, conflicts,- ...(input.workloadDisclosure === undefined ? {} : { workload_disclosure: input.workloadDisclosure }),- ...(packages === undefined ? {} : { packages }),- ...(variants === undefined ? {} : { variants }),- next_action: input.nextAction?.trim() || (next > VARIANT_EXPANSION_STEPS.length ? "variant expansion complete" : `complete ${VARIANT_EXPANSION_STEPS[next - 1]}`),- ...(input.command === undefined ? {} : { last_command: input.command }),- ...(input.error === undefined ? {} : { last_error: input.error }),- updated_at: now,- });-}--export async function checkpointVariantExpansion(input: VariantExpansionCheckpointInput): Promise<VariantExpansionState> {- const locator = await selectedLocator(input.projectRoot, input.outputRoot, input.batchId);- if (locator === undefined) throw new Error("no variant expansion state; run variant_state --action start first");- return withStateLock(locator.output_root, async () => checkpointVariantExpansionUnlocked({ ...input, outputRoot: locator.output_root }));-}--async function exists(path: string | undefined): Promise<boolean> {- return path !== undefined && await stat(path).then(() => true, () => false);-}--async function validJson(path: string | undefined, predicate: (value: unknown) => boolean = () => true): Promise<boolean> {- if (!(await exists(path)) || path === undefined) return false;- try { return predicate(JSON.parse(await readFile(path, "utf8"))); }- catch { return false; }-}--async function reconcileVariantExpansionUnlocked(projectRoot: string, outputRoot?: string, batchId?: string): Promise<VariantExpansionState | undefined> {- const existing = await readVariantExpansionState(projectRoot, outputRoot, batchId);- if (existing === undefined) return undefined;- const completed = new Set(existing.completed_steps);- const conflicts = existing.conflicts.filter((message) => !message.startsWith("[reconcile] "));- const addConflict = (message: string): void => { if (!conflicts.includes(message)) conflicts.push(message); };- const baseline = await snapshotProject(existing.project_root);- if (baseline.digest !== existing.baseline_digest) addConflict(`[reconcile] base project digest changed: expected ${existing.baseline_digest}, found ${baseline.digest}`);- const parentDigest = await digestFile(existing.parent_state_path ?? join(existing.project_root, ".hypit", "route-state.json"));- if (existing.parent_state_digest !== undefined && parentDigest !== existing.parent_state_digest) addConflict(`[reconcile] parent route state digest changed: expected ${existing.parent_state_digest}, found ${parentDigest ?? "missing"}`);- const revisionDigest = await digestFile(existing.revision_state_path ?? join(existing.project_root, ".hypit", "revision-state.json"));- if (existing.revision_state_digest !== undefined && revisionDigest !== existing.revision_state_digest) addConflict(`[reconcile] revision state digest changed: expected ${existing.revision_state_digest}, found ${revisionDigest ?? "missing"}`);-- const packages: VariantExpansionPackage[] = [];- for (const pack of existing.packages) {- const route = await reconcileRouteState(pack.staging_root);- const currentDigest = await snapshotProject(pack.package_root ?? pack.staging_root, { preserveTopLevelOutputs: true }).then((snapshot) => snapshot.digest, () => undefined);- if (pack.digest !== undefined && currentDigest !== pack.digest) {- addConflict(`[reconcile] package ${pack.id} digest changed: expected ${pack.digest}, found ${currentDigest ?? "missing"}`);- }- const { error: _oldError, ...packWithoutError } = pack;- packages.push({ ...packWithoutError, status: route?.status === "complete" && pack.digest !== undefined && currentDigest === pack.digest ? "ready" : route?.status === "blocked" ? "failed" : "active",- ...(route === undefined ? { error: "route-state-missing" } : {}) });- }-- const variants: VariantExpansionVariant[] = [];- for (const variant of existing.variants) {- const route = await reconcileRouteState(variant.project_root);- const revision = await readRevisionState(variant.project_root);- const revisedAfterVariant = route?.route === "variant" && revision?.parent_route === "variant"- && revision.parent_state_path === routeExecutionStatePath(variant.project_root, route.route_id);- let outside: readonly unknown[] = [];- if (!revisedAfterVariant) {- const diff = await inspectVariantDiff(variant.project_root);- outside = Array.isArray(diff.outside_allowed_changes) ? diff.outside_allowed_changes : [];- if (outside.length > 0) addConflict(`[reconcile] variant ${variant.id} changed outside allowed_changes: ${outside.join(", ")}`);- if (diff.passed !== true && outside.length === 0) {- const errors = Array.isArray(diff.errors) ? diff.errors.map(String).join(", ") : "variant baseline evidence failed";- addConflict(`[reconcile] variant ${variant.id} scope evidence is invalid: ${errors}`);- }- }- const check = await validJson(route?.artifacts.variant_check ?? join(variant.project_root, ".hypit", "variant-check.json"), (value) => (value as { passed?: unknown })?.passed === true);- const { error: _oldError, ...variantWithoutError } = variant;- variants.push({- ...variantWithoutError,- status: revisedAfterVariant && route?.status === "complete" && check ? "complete"- : outside.length > 0 ? "scope-expansion-required"- : route?.status === "complete" && check ? "complete"- : route?.status === "blocked" ? "failed" : route === undefined ? "failed" : variant.status === "ready" ? "ready" : "dispatched",- ...(route === undefined ? { error: "route-state-missing" } : {}),- });- }-- const artifact = (key: string): string | undefined => existing.artifacts[key];- const predicates = new Map<number, () => Promise<boolean>>([- [1, async () => await validJson(artifact("baseline_check"), (value) => (value as { passed?: unknown })?.passed === true)- || (await readRouteState(existing.project_root))?.status === "complete"],- [2, async () => await validJson(artifact("examples"))],- [3, async () => await validJson(artifact("format_plan"))],- [4, async () => await validJson(artifact("slate"), (value) => {- try { return expandVariantSlate(value as VariantSlate, artifact("slate") ?? "slate.json").length > 0; } catch { return false; }- })],- [5, async () => await validJson(artifact("vocabulary"), (value) => Array.isArray((value as { packages?: unknown })?.packages) || Array.isArray((value as { surfaces?: unknown })?.surfaces))],- [6, async () => await validJson(artifact("component_plan"))],- [7, async () => await validJson(artifact("package_gaps"))],- [9, async () => {- const slatePath = artifact("slate");- if (slatePath === undefined) return false;- let slate: VariantSlate;- try { slate = JSON.parse(await readFile(slatePath, "utf8")) as typeof slate; } catch { return false; }- let variantsInSlate: readonly { component_class?: unknown; inject_packages?: readonly { package_id?: unknown }[] }[];- try { variantsInSlate = expandVariantSlate(slate, slatePath); } catch { return false; }- if (variantsInSlate.some((variant) => variant.component_class === "new-package" && (variant.inject_packages?.length ?? 0) === 0)) return false;- const required = new Set(variantsInSlate.flatMap((variant) => variant.component_class === "new-package"- ? (variant.inject_packages ?? []).flatMap((injection) => typeof injection.package_id === "string" ? [injection.package_id] : [])- : []));- return packages.every((pack) => pack.status === "ready")- && [...required].every((id) => packages.some((pack) => pack.id === id && pack.status === "ready" && pack.digest !== undefined));- }],- [10, async () => await validJson(artifact("slate"), (value) => {- try {- const variants = expandVariantSlate(value as VariantSlate, artifact("slate") ?? "slate.json");- return existing.count === undefined || variants.length === existing.count;- } catch { return false; }- })],- [11, async () => variants.length > 0 && (await Promise.all(variants.map(async (variant) => await exists(variant.manifest) && await exists(variant.project_root)))).every(Boolean)],- [12, async () => variants.length > 0 && (await Promise.all(variants.map(async (variant) => await exists(variant.route_state)))).every(Boolean)],- [13, async () => variants.length > 0 && variants.every((variant) => variant.status === "complete")],- [14, async () => await validJson(artifact("aggregate_check"), (value) => (value as { passed?: unknown })?.passed === true)],- [17, async () => completed.has(16) && await validJson(artifact("build"), (value) => (value as { passed?: unknown; status?: unknown })?.passed === true || (value as { status?: unknown })?.status === "complete")],- [18, async () => completed.has(14) && (existing.delivery_mode === "source" || completed.has(17))],- ]);- const machineSteps = new Set([1, 9, 11, 13, 14, 17, 18]);- for (const [step, predicate] of predicates) {- const satisfied = await predicate();- if (completed.has(step) && !satisfied) {- completed.delete(step);- addConflict(`[reconcile] step ${step} (${VARIANT_EXPANSION_STEPS[step - 1]}) was marked complete but its evidence is missing or failed`);- } else if (machineSteps.has(step) && satisfied) completed.add(step);- }- if (existing.workload_disclosure === undefined && completed.has(8)) {- completed.delete(8);- addConflict("[reconcile] workload-disclosed was marked complete without a persisted disclosure");- }- if (conflicts.length > 0) {- completed.delete(18);- }- const next = nextUncompleted(completed, existing.delivery_mode);- const now = new Date().toISOString();- return writeState({- ...existing,- status: next > VARIANT_EXPANSION_STEPS.length ? "complete" : existing.status === "blocked" ? "blocked" : "active",- current_step: next, completed_steps: [...completed].sort((a, b) => a - b),- in_progress: next > VARIANT_EXPANSION_STEPS.length ? null : { step: next, started_at: now },- conflicts, packages, variants,- next_action: next > VARIANT_EXPANSION_STEPS.length ? "variant expansion complete" : `complete ${VARIANT_EXPANSION_STEPS[next - 1]}`,- updated_at: now,- });-}--export async function reconcileVariantExpansion(projectRoot: string, outputRoot?: string, batchId?: string): Promise<VariantExpansionState | undefined> {- const locator = await selectedLocator(projectRoot, outputRoot, batchId);- if (locator === undefined) return undefined;- return withStateLock(locator.output_root, async () => reconcileVariantExpansionUnlocked(projectRoot, locator.output_root, locator.batch_id));-}diff --git a/packages/reference-video-tools/test/gates.test.ts b/packages/reference-video-tools/test/gates.test.tsdeleted file mode 100644index c3e29f7f..00000000--- a/packages/reference-video-tools/test/gates.test.ts+++ /dev/null@@ -1,33 +0,0 @@-import assert from "node:assert/strict";-import test from "node:test";-import { mkdir, mkdtemp, writeFile } from "node:fs/promises";-import { tmpdir } from "node:os";-import { join } from "node:path";--import { createReferenceVideoTools } from "../src/tools.js";--async function project(): Promise<string> {- const root = await mkdtemp(join(tmpdir(), "hypit-gates-"));- await writeFile(join(root, "package.json"), JSON.stringify({ name: "gate-fixture", private: true }), "utf8");- await mkdir(join(root, "packages", "local-empty", "src"), { recursive: true });- await writeFile(join(root, "packages", "local-empty", "package.json"), JSON.stringify({- name: "@fixture/local-empty", version: "0.0.0-dev", type: "module", exports: { ".": "./src/index.ts" },- hypit: { activation: "./src/activation.ts" }, dependencies: {},- }), "utf8");- await writeFile(join(root, "packages", "local-empty", "src", "index.ts"), "export const empty = true;\n", "utf8");- await writeFile(join(root, "packages", "local-empty", "src", "activation.ts"), "export default { format: 'hypit.node-package@1', modules: [], hostFacets: [] };\n", "utf8");- await writeFile(join(root, "main.svml"), `<svml><import as="script" from="@hypit/script@1"/><script:Script id="story"><opening>one two three four five</opening></script></svml>\n`, "utf8");- await writeFile(join(root, "build.svrun"), `<svrun><author source="main.svml"/></svrun>\n`, "utf8");- return root;-}--test("local package gate rejects an empty activation and an unbroken long Cue", async () => {- const root = await project();- const tools = createReferenceVideoTools({ packageRoot: root });- const packageResult = await tools.validate_local_author_packages({ run: join(root, "build.svrun") });- assert.equal(packageResult.passed, false);- assert.match(JSON.stringify(packageResult), /PACKAGE_NO_SURFACE/u);- const cueResult = await tools.validate_script_cues({ run: join(root, "build.svrun") });- assert.equal(cueResult.passed, false);- assert.equal((cueResult.violations as { wordCount: number }[])[0]?.wordCount, 5);-});diff --git a/packages/reference-video-tools/test/plan.test.ts b/packages/reference-video-tools/test/plan.test.tsindex 0a9fabd4..6069c83b 100644--- a/packages/reference-video-tools/test/plan.test.ts+++ b/packages/reference-video-tools/test/plan.test.ts@@ -27,7 +27,7 @@ function planFor(svml: string) {return reviewPlan({ svml, svmlPath: "main.svml", scriptBody: scriptBody(svml), drawn: BROLL });}-// Under-covering is the silent direction: the gate passes, the round runs, and the second design is+// Under-covering is the silent direction: the plan looks complete, the round runs, and the second design is// simply never drawn. The two exclusion lists this key is built from will grow as packages are added,// and widening one by an attribute that actually decides what a picture looks like merges two groups// into one. That edit has no visible symptom, so it is the one worth pinning.@@ -72,7 +72,7 @@ const CAPTIONS = `<?svml using="@hypit/markup@1"?>// A caption Track is one tag with no window on it, so reading its placements the ordinary way finds// one design however many the Program hands out. An override is written inside the Program, and the// stretch it covers is a genuinely different picture that nothing on the Track mentions — so leaving-// it out is a design nobody looks at while the gate reports full coverage.+// it out is a design nobody looks at while the plan reports full coverage.test("a caption Style override is its own look, over the stretch it covers", () => {const plan = reviewPlan({svml: CAPTIONS, svmlPath: "main.svml", scriptBody: scriptBody(CAPTIONS),diff --git a/packages/reference-video-tools/test/route-state.test.ts b/packages/reference-video-tools/test/route-state.test.tsdeleted file mode 100644index 1690af84..00000000--- a/packages/reference-video-tools/test/route-state.test.ts+++ /dev/null@@ -1,211 +0,0 @@-import assert from "node:assert/strict";-import test from "node:test";-import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";-import { tmpdir } from "node:os";-import { join } from "node:path";--import {- checkpointRouteState,- componentFitPath,- readRouteState,- reconcileRouteState,- routeStatePath,- startRouteState,- ROUTE_STATE_STEPS,-} from "../src/route-state.js";--async function writeComponentFit(root: string, route: "description" | "reconstruction"): Promise<string> {- const path = componentFitPath(root);- await mkdir(join(root, ".hypit"), { recursive: true });- await writeFile(path, JSON.stringify({- version: 1,- route,- basis: route === "description" ? ".hypit/brief.json" : "reference-test",- systems: [{- role: "test system",- inspected_candidates: ["@hypit/test"],- selected_package: "@hypit/test",- decision: "reuse-existing",- rationale: "sufficiently similar for the test",- accepted_variances: [],- }],- }), "utf8");- return path;-}--async function completeDescriptionSourceGates(root: string): Promise<void> {- const vocabulary = join(root, "vocabulary.json");- const componentFit = await writeComponentFit(root, "description");- const packageReady = join(root, "package-ready.json");- const scriptCues = join(root, "script-cues.json");- await writeFile(vocabulary, JSON.stringify({ packages: [], surfaces: [] }), "utf8");- await writeFile(packageReady, JSON.stringify({ passed: true }), "utf8");- await writeFile(scriptCues, JSON.stringify({ passed: true }), "utf8");- await checkpointRouteState({ projectRoot: root, route: "description", step: 3, status: "complete", artifacts: { vocabulary, component_fit: componentFit } });- await checkpointRouteState({ projectRoot: root, route: "description", step: 4, status: "complete", artifacts: { package_ready: packageReady } });- await checkpointRouteState({ projectRoot: root, route: "description", step: 5, status: "complete", artifacts: { script_cues: scriptCues } });-}--test("route state starts once, checkpoints idempotently, and advances to the next step", async () => {- const root = await mkdtemp(join(tmpdir(), "hypit-route-state-"));- const started = await startRouteState({ projectRoot: root, route: "reconstruction", run: "build.svrun" });- assert.equal(started.current_step, 1);- assert.equal(started.run, join(root, "build.svrun"));- const completed = await checkpointRouteState({ projectRoot: root, route: "reconstruction", step: 1, status: "complete", nextAction: "prepare reference" });- assert.deepEqual(completed.completed_steps, [1]);- assert.equal(completed.current_step, 2);- const repeated = await checkpointRouteState({ projectRoot: root, route: "reconstruction", step: 1, status: "complete" });- assert.deepEqual(repeated.completed_steps, [1]);- 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");- await writeFile(source, "source", "utf8");- await startRouteState({ projectRoot: root, route: "description" });- await completeDescriptionSourceGates(root);- await checkpointRouteState({ projectRoot: root, route: "description", step: 6, status: "complete", artifacts: { author_source: source } });- const reconciled = await reconcileRouteState(root);- assert.equal(reconciled?.completed_steps.includes(6), true);- assert.equal(reconciled?.current_step, 1, "manual earlier steps remain owed instead of being guessed from a later file");-});--test("corrupt route state fails without replacing the original file", async () => {- const root = await mkdtemp(join(tmpdir(), "hypit-route-state-"));- await mkdir(join(root, ".hypit"), { recursive: true });- await writeFile(routeStatePath(root), "{broken", "utf8");- await assert.rejects(readRouteState(root), /invalid JSON.*original file was preserved/u);- assert.equal(await readFile(routeStatePath(root), "utf8"), "{broken");-});--test("a project cannot switch an active route", async () => {- const root = await mkdtemp(join(tmpdir(), "hypit-route-state-"));- await startRouteState({ projectRoot: root, route: "reconstruction" });- await assert.rejects(startRouteState({ projectRoot: root, route: "description" }), /already has an active reconstruction route/u);-});--test("a completed route no longer blocks a new route", async () => {- const root = await mkdtemp(join(tmpdir(), "hypit-route-state-"));- const vocabulary = join(root, "vocabulary.json");- const componentFit = await writeComponentFit(root, "reconstruction");- await writeFile(vocabulary, JSON.stringify({ packages: [], surfaces: [] }), "utf8");- await startRouteState({ projectRoot: root, route: "reconstruction" });- for (let step = 1; step <= ROUTE_STATE_STEPS.reconstruction.length; step += 1) {- await checkpointRouteState({- projectRoot: root,- route: "reconstruction",- step,- status: "complete",- ...(step === 4 ? { artifacts: { vocabulary, component_fit: componentFit } } : {}),- });- }- assert.equal((await readRouteState(root))?.status, "complete");- const completed = await readRouteState(root);- const restarted = await startRouteState({ projectRoot: root, route: "description" });- assert.equal(restarted.route, "description");- assert.deepEqual(restarted.completed_steps, []);- assert.notEqual(restarted.route_id, completed?.route_id);- assert.equal(JSON.parse(await readFile(join(root, ".hypit", "routes", completed!.route_id, "state.json"), "utf8")).status, "complete");-});--test("checkpoint artifacts are merged and stale machine evidence is rolled back", async () => {- const root = await mkdtemp(join(tmpdir(), "hypit-route-state-"));- const source = join(root, "main.svml");- const check = join(root, "preview-check.json");- await writeFile(source, "source", "utf8");- await writeFile(check, JSON.stringify({ sound: true }), "utf8");- await startRouteState({ projectRoot: root, route: "description" });- await completeDescriptionSourceGates(root);- await checkpointRouteState({ projectRoot: root, route: "description", step: 6, status: "complete", artifacts: { author_source: source } });- await checkpointRouteState({ projectRoot: root, route: "description", step: 7, status: "complete", artifacts: { preview_check: check } });- const mergedArtifacts = (await readRouteState(root))?.artifacts ?? {};- assert.equal(mergedArtifacts.author_source, source);- assert.equal(mergedArtifacts.preview_check, check);- await reconcileRouteState(root);- assert.equal((await readRouteState(root))?.completed_steps.includes(7), true);- await writeFile(check, JSON.stringify({ sound: false }), "utf8");- const rolledBack = await reconcileRouteState(root);- assert.equal(rolledBack?.completed_steps.includes(7), false);- assert.equal(rolledBack?.current_step, 1);- assert.match(rolledBack?.conflicts?.[0] ?? "", /step 7.*preview_check/u);-});--test("description reconciliation uses brief and vocabulary evidence rather than reference artifacts", async () => {- const root = await mkdtemp(join(tmpdir(), "hypit-route-state-"));- const brief = join(root, ".hypit", "brief.json");- const vocabulary = join(root, "vocabulary.json");- const componentFit = await writeComponentFit(root, "description");- await mkdir(join(root, ".hypit"), { recursive: true });- await writeFile(brief, JSON.stringify({ intent: "brief" }), "utf8");- await writeFile(vocabulary, JSON.stringify({ packages: [], surfaces: [] }), "utf8");- await startRouteState({ projectRoot: root, route: "description" });- await checkpointRouteState({ projectRoot: root, route: "description", step: 2, status: "complete", artifacts: { brief } });- await checkpointRouteState({ projectRoot: root, route: "description", step: 3, status: "complete", artifacts: { vocabulary, component_fit: componentFit } });- const state = await reconcileRouteState(root);- assert.equal(state?.completed_steps.includes(2), true);- assert.equal(state?.completed_steps.includes(3), true);- assert.equal(state?.completed_steps.includes(6), false);- await writeFile(brief, JSON.stringify({ intent: "changed after freeze" }), "utf8");- await writeFile(componentFit, JSON.stringify({ changed: true }), "utf8");- const conflicted = await reconcileRouteState(root);- const conflicts = conflicted?.conflicts?.join("\n") ?? "";- assert.match(conflicts, /brief digest changed/u);- assert.match(conflicts, /component_fit digest changed/u);- assert.equal(conflicted?.completed_steps.includes(3), false);-});--test("an interrupted in-progress step resumes at the first unmet step", async () => {- const root = await mkdtemp(join(tmpdir(), "hypit-route-state-"));- await startRouteState({ projectRoot: root, route: "reconstruction" });- await checkpointRouteState({ projectRoot: root, route: "reconstruction", step: 1, status: "complete" });- const interrupted = await checkpointRouteState({ projectRoot: root, route: "reconstruction", step: 2, status: "in_progress", nextAction: "finish reference preparation" });- assert.equal(interrupted.in_progress?.step, 2);- const resumed = await reconcileRouteState(root);- assert.equal(resumed?.current_step, 2);- assert.equal(resumed?.in_progress?.step, 2);- assert.equal(resumed?.next_action, "complete reference-prepared");-});--test("v1 route snapshots migrate by stage name and re-open new gates", async () => {- const root = await mkdtemp(join(tmpdir(), "hypit-route-state-"));- await mkdir(join(root, ".hypit"), { recursive: true });- await writeFile(routeStatePath(root), JSON.stringify({- version: 1, route: "reconstruction", project_root: root, status: "active", current_step: 4,- completed_steps: [1, 2, 3, 4], in_progress: { step: 4, started_at: new Date().toISOString() },- artifacts: {}, decisions: [], next_action: "write Source", updated_at: new Date().toISOString(),- }), "utf8");- const migrated = await readRouteState(root);- assert.equal(migrated?.version, 4);- assert.equal(migrated?.completed_steps.includes(3), true);- assert.equal(migrated?.completed_steps.includes(4), false, "new vocabulary gate is not guessed from old source state");- assert.equal(migrated?.current_step, 4);-});--test("source-authored cannot bypass vocabulary, package and Script gates", async () => {- const root = await mkdtemp(join(tmpdir(), "hypit-route-state-"));- await startRouteState({ projectRoot: root, route: "reconstruction" });- const sourceStep = ROUTE_STATE_STEPS.reconstruction.indexOf("source-authored") + 1;- await assert.rejects(- checkpointRouteState({ projectRoot: root, route: "reconstruction", step: sourceStep, status: "complete" }),- /source-authored cannot be completed before/u,- );- const statePath = routeStatePath(root);- const raw = JSON.parse(await readFile(statePath, "utf8")) as Record<string, unknown>;- raw.completed_steps = [4, 5, 6, sourceStep];- await writeFile(statePath, `${JSON.stringify(raw)}\n`, "utf8");- const reconciled = await reconcileRouteState(root);- assert.equal(reconciled?.completed_steps.includes(sourceStep), false);- assert.equal((reconciled?.conflicts?.length ?? 0) > 0, true);-});diff --git a/packages/reference-video-tools/test/tools.test.ts b/packages/reference-video-tools/test/tools.test.tsindex 23da1ded..b924066a 100644--- a/packages/reference-video-tools/test/tools.test.ts+++ b/packages/reference-video-tools/test/tools.test.ts@@ -167,7 +167,6 @@ test("a narrow question costs one call, answers from the named shots and is answassert.match(calls[0]!.text, /platform UI|editing-software watermark/u);assert.deepEqual(result["shot_ids"], ["shot-003"]);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.diff --git a/packages/run-markup/README.md b/packages/run-markup/README.mdindex 44721bc5..e86ba39d 100644--- a/packages/run-markup/README.md+++ b/packages/run-markup/README.md@@ -20,15 +20,16 @@ The Author Source's own Header—not this file and not its suffix—selects its`<value>` declares a typed zero-input `StoredValue`. `<file>` admits ordinary sourcebytes as the explicitly named blob Type; Run itself does not assume an Artifact module.-`<build-record>` exposes a verified prior Build Record as a zero-input Candidate. `<fragment>`+`<build-record>` exposes one exact named Output from a prior Build Result as a zero-input Candidate. `<fragment>`instantiates a trusted package Fragment and mayexport several Candidates backed by shared Operations. Two declarations are two instances; onedeclaration with several exports is one instance.-The `output` on `<build-record>` may be the prior source's public output alias. The Host resolves it-through its Build Catalog to the verified logical Record before Run compilation. Core never sees or-trusts the presentation alias, and the historical value receives no automatic semantic-relationship-claim against the output it is selected to satisfy.+The `output` on `<build-record>` is the prior Result's unique public Output name. After Core plans the+complete Author and Run graphs, the Host resolves only the selected zero-input Candidate sources;+unreached local values, local files and historical Outputs are not opened. Core receives only the typed Candidate value,+and the historical value receives no automatic semantic-relationship claim+against the output it is selected to satisfy.Imports form the opening prologue. They name Fragment libraries already admitted by the Host; theydo not install packages. Provider credentials, queues, Stores, Endpoint bindings and inlinediff --git a/packages/run-markup/test/run.test.ts b/packages/run-markup/test/run.test.tsindex dcdfb49a..13ca9274 100644--- a/packages/run-markup/test/run.test.ts+++ b/packages/run-markup/test/run.test.ts@@ -1,19 +1,18 @@import assert from "node:assert/strict";import test from "node:test";-import { fixtureResource } from "../../../test/fixture-resource.js";import {createResolvedClosure,+ defineBuild,link,- reduce,- sealBuildRequest,+ materializeBuild,+ planBuild,sealCompiledGraph,sealRecord,- start,} from "@hypit/core";import { sealGraphFragment } from "@hypit/elaborator";import type { CompiledSourceClosure } from "@hypit/elaborator";-import type { CompiledGraph, ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";+import type { BuildState, ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";import {compileRunSource,createRunFragmentHostFacet,@@ -98,16 +97,14 @@ function previewFragment() {});}-function realize(compilation: CompiledSourceClosure, run: Awaited<ReturnType<typeof resolveRunDocument>>): CompiledGraph {- const selected = new Map(run.graph.satisfactions.map((item) => [item.output, item.candidate]));- return sealCompiledGraph({- outputs: compilation.graph.outputs.map((item) => ({- ...item,- primary: selected.get(item.id) ?? item.primary,- })),- candidates: [...compilation.graph.candidates, ...run.graph.candidates],- operations: [...compilation.graph.operations, ...run.graph.operations],- });+function realize(compilation: CompiledSourceClosure, run: Awaited<ReturnType<typeof resolveRunDocument>>): BuildState {+ const planned = planBuild(compilation.program, compilation.graph, run.graph);+ return materializeBuild(defineBuild({+ program: compilation.program,+ initialRecords: planned.initialRecords,+ plan: planned.plan,+ targets: run.graph.targets,+ }), []);}async function compileDocument(body: string) {@@ -159,12 +156,8 @@ test("one multi-export Fragment declaration remains one execution", async () =>const run = await resolveRunDocument(compiled.document, {compilation,fragments,- readStoredValue() { throw new Error("not used"); },- readFile() { throw new Error("not used"); },- resolveBuildRecord() { throw new Error("not used"); },});- const graph = realize(compilation, run);- const state = start(compilation.program, graph, sealBuildRequest({ targets: run.graph.targets }));+ const state = realize(compilation, run);assert.equal(state.plan.steps.filter((item) => item.producer.name === "preview").length, 1);});@@ -179,14 +172,10 @@ test("a Provided Value is an ordinary zero-input Candidate", async () => {const run = await resolveRunDocument(compiled.document, {compilation,fragments: new RunFragmentRegistry(),- readStoredValue() { return { kind: "inline", value: "already rendered" }; },- readFile() { throw new Error("not used"); },- resolveBuildRecord() { throw new Error("not used"); },});- const graph = realize(compilation, run);- const state = start(compilation.program, graph, sealBuildRequest({ targets: run.graph.targets }));+ const state = realize(compilation, run);assert.equal(state.plan.steps.length, 0);- assert.equal(state.records.some((record) => record.id === "provided:fixed"), true);+ assert.equal(state.records.some((record) => record.id === "provided:run:fixed"), true);});test("a source file is an ordinary BlobArtifact Candidate", async () => {@@ -200,35 +189,19 @@ test("a source file is an ordinary BlobArtifact Candidate", async () => {const run = await resolveRunDocument(compiled.document, {compilation,fragments: new RunFragmentRegistry(),- readStoredValue() { throw new Error("not used"); },- readFile(from, mediaType) {- assert.equal(from, "./approved.mp4");- assert.equal(mediaType, "video/mp4");- return { kind: "blob", resource: fixtureResource("approved video"), size: 14, mediaType };- },- resolveBuildRecord() { throw new Error("not used"); },});assert.equal(run.graph.candidates.length, 1);assert.equal(run.graph.candidates[0]?.type.module.name, "@hypit/artifact");assert.equal(run.graph.candidates[0]?.type.name, "BlobArtifact");+ assert.deepEqual(run.candidateSources[run.graph.candidates[0]!.id], {+ kind: "file",+ from: "./approved.mp4",+ mediaType: "video/mp4",+ });});-test("a Build Record resolves a Host Catalog alias without entering Core", async () => {+test("a Build Record stays a structural zero-input Candidate until planning selects it", async () => {const compilation = fixture();- let historical = start(compilation.program, compilation.graph, sealBuildRequest({- targets: [{ output: "left" }],- }));- historical = reduce(historical);- const command = historical.outstanding.find((item) => item.kind === "invoke-producer");- assert.ok(command);- const event = {- kind: "producer-completed" as const,- command: command.id,- outputs: { media: { kind: "inline" as const, value: "archived media" } },- needs: {},- };- historical = reduce(historical, event);-const compiled = await compileDocument(`<svrun version="1"><author source="./main.svml"/><target output="right"/><build-record id="prior" build="prior-build" output="friendly-shot"/>@@ -237,20 +210,14 @@ test("a Build Record resolves a Host Catalog alias without entering Core", asyncconst run = await resolveRunDocument(compiled.document, {compilation,fragments: new RunFragmentRegistry(),- readStoredValue() { throw new Error("not used"); },- readFile() { throw new Error("not used"); },- resolveBuildRecord(build, output) {- assert.equal(build, "prior-build");- assert.equal(output, "friendly-shot");- const selection = historical.plan.selections.find((item) => item.output === "left");- const record = historical.records.find((item) => item.id === selection?.record);- assert.ok(record);- return { type: record.type, value: record.value };- },});- const graph = realize(compilation, run);- const state = start(compilation.program, graph, sealBuildRequest({ targets: run.graph.targets }));- assert.equal(state.plan.steps.length, 0);+ const candidate = run.graph.satisfactions[0]!.candidate;+ assert.deepEqual(run.candidateSources[candidate], {+ kind: "build-output",+ build: "prior-build",+ output: "friendly-shot",+ });+ assert.equal(run.graph.candidates.find((item) => item.id === candidate)?.root.kind, "value");});test("Run imports are a prologue and Runtime settings are not language elements", () => {@@ -278,9 +245,6 @@ test("a Target-only source still compiles one mandatory Run Graph", async () =>const run = await resolveRunDocument(compiled.document, {compilation,fragments: new RunFragmentRegistry(),- readStoredValue() { throw new Error("not used"); },- readFile() { throw new Error("not used"); },- resolveBuildRecord() { throw new Error("not used"); },});assert.equal(run.graph.operations.length, 0);assert.equal(run.graph.targets[0]?.output, "left");diff --git a/packages/run/src/candidate.ts b/packages/run/src/candidate.tsindex 78f2ada4..9d948113 100644--- a/packages/run/src/candidate.ts+++ b/packages/run/src/candidate.ts@@ -20,12 +20,12 @@ export function createProvidedCandidate(input: ProvidedCandidateInput): Candidat? { kind: "inline" as const, value: canonicalize(input.value.value) }: { ...input.value };return {- id: `candidate:${input.id}`,+ id: `candidate:run:${input.id}`,type: input.type,root: {kind: "value",value: {- id: input.record ?? `provided:${input.id}`,+ id: input.record ?? `provided:run:${input.id}`,value,},},diff --git a/packages/run/src/resolve.ts b/packages/run/src/resolve.tsindex 00d603ad..dd02444d 100644--- a/packages/run/src/resolve.ts+++ b/packages/run/src/resolve.ts@@ -3,13 +3,12 @@ import {exportRunFragment,resolveCompiledSourceExport,} from "@hypit/elaborator";-import { canonicalStringify } from "@hypit/protocol";+import { sameType } from "@hypit/protocol";import type {Candidate,GraphValueRef,ModuleRef,OperationNode,- StoredValue,} from "@hypit/protocol";import {createProvidedCandidate,@@ -68,20 +67,7 @@ function logicalOutput(context: ResolveRunDocumentContext, name: string): stringreturn exported.ref.id;}-function assertStoredValue(value: unknown, subject: string): asserts value is StoredValue {- if (value === null || typeof value !== "object" || Array.isArray(value)) {- throw new Error(`${subject} must contain one StoredValue object`);- }- const item = value as Record<string, unknown>;- if (item.kind === "inline" && Object.hasOwn(item, "value")) return;- if (item.kind === "blob"- && typeof item.resource === "string"- && Number.isSafeInteger(item.size)- && typeof item.mediaType === "string") return;- throw new Error(`${subject} is not an inline or blob StoredValue`);-}--/** Resolve both source graphs completely before Core derives a finite BuildPlan. */+/** Resolve both source graph structures before Core derives a finite BuildPlan. */export async function resolveRunDocument(document: RunDocument,context: ResolveRunDocumentContext,@@ -90,56 +76,72 @@ export async function resolveRunDocument(const candidates = new Map<string, Candidate>();const operations = new Map<string, OperationNode>();const addCandidate = (candidate: Candidate): void => {- const existing = candidates.get(candidate.id);- if (existing !== undefined && canonicalStringify(existing) !== canonicalStringify(candidate)) {- throw new Error(`Run Candidate ${candidate.id} has conflicting definitions`);- }+ if (candidates.has(candidate.id)) throw new Error(`Run Candidate ${candidate.id} is declared twice`);candidates.set(candidate.id, candidate);};const addOperation = (operation: OperationNode): void => {- const existing = operations.get(operation.id);- if (existing !== undefined && canonicalStringify(existing) !== canonicalStringify(operation)) {- throw new Error(`Run Operation ${operation.id} has conflicting definitions`);- }+ if (operations.has(operation.id)) throw new Error(`Run Operation ${operation.id} is declared twice`);operations.set(operation.id, operation);};const candidateNames = new Map<string, string>();+ const candidateSources = new Map<string, RunCompilation["candidateSources"][string]>();+ const declarationIds = new Set<string>();const bindCandidateName = (name: string, candidate: string): void => {if (candidateNames.has(name)) throw new Error(`Run Candidate reference ${name} is declared twice`);candidateNames.set(name, candidate);};for (const declaration of document.candidates) {+ if (declarationIds.has(declaration.id)) throw new Error(`Run Candidate ${declaration.id} is declared twice`);+ declarationIds.add(declaration.id);if (declaration.kind === "provided") {- const value = await context.readStoredValue(declaration.from);- assertStoredValue(value, declaration.from);- const candidate = createProvidedCandidate({ id: declaration.id, type: declaration.type, value });+ const candidate = createProvidedCandidate({+ id: declaration.id,+ type: declaration.type,+ value: { kind: "inline", value: null },+ });addCandidate(candidate);bindCandidateName(declaration.id, candidate.id);+ candidateSources.set(candidate.id, { kind: "stored-value", from: declaration.from });continue;}if (declaration.kind === "file") {- const value = await context.readFile(declaration.from, declaration.mediaType);- assertStoredValue(value, declaration.from);const candidate = createProvidedCandidate({id: declaration.id,type: declaration.type,- value,+ value: { kind: "inline", value: null },});addCandidate(candidate);bindCandidateName(declaration.id, candidate.id);+ candidateSources.set(candidate.id, {+ kind: "file",+ from: declaration.from,+ mediaType: declaration.mediaType,+ });continue;}if (declaration.kind === "build-record") {- const record = await context.resolveBuildRecord(declaration.build, declaration.output);- if (record === undefined) {- throw new Error(- `Build ${declaration.build} has no accepted output ${declaration.output}; update build-record ${declaration.id}`,- );+ const destinations = document.satisfactions+ .filter((item) => item.candidate === declaration.id)+ .map((item) => resolveCompiledSourceExport(context.compilation, item.output));+ if (destinations.length === 0) continue;+ const type = destinations[0]!.type;+ for (const destination of destinations) {+ if (destination.ref.kind !== "logical-output") {+ throw new Error(`${declaration.id} satisfies an authored Record rather than a Logical Output`);+ }+ if (!sameType(destination.type, type)) {+ throw new Error(`Historical Candidate ${declaration.id} is used for incompatible Logical Output types`);+ }}- const candidate = createProvidedCandidate({ id: declaration.id, ...record });+ const candidate = createProvidedCandidate({ id: declaration.id, type, value: { kind: "inline", value: null } });addCandidate(candidate);bindCandidateName(declaration.id, candidate.id);+ candidateSources.set(candidate.id, {+ kind: "build-output",+ build: declaration.build,+ output: declaration.output,+ });continue;}const packageName = imports.get(declaration.using.alias);@@ -149,7 +151,7 @@ export async function resolveRunDocument(throw new Error(`${packageName} exports no Run Fragment ${declaration.using.name}`);}const instance = elaborateGraphFragment(context.compilation.program, fragment, {- id: declaration.id,+ id: `run:${declaration.id}`,fragment: fragment.id,inputs: Object.fromEntries(declaration.inputs.map((item) => [item.name, authorRef(context, item.from)])),});@@ -186,6 +188,7 @@ export async function resolveRunDocument(document,graph,candidates: Object.fromEntries([...candidateNames.entries()].sort(([left], [right]) => left.localeCompare(right))),+ candidateSources: Object.fromEntries([...candidateSources.entries()].sort(([left], [right]) => left.localeCompare(right))),satisfactionNames: Object.fromEntries([...satisfactionNames.entries()].sort(([left], [right]) => left.localeCompare(right))),};}diff --git a/packages/run/src/types.ts b/packages/run/src/types.tsindex aa5ced2a..25a6b904 100644--- a/packages/run/src/types.ts+++ b/packages/run/src/types.ts@@ -5,10 +5,11 @@ import type {import type {Candidate,OperationNode,+ RunGraph,Satisfaction,- StoredValue,TypeRef,} from "@hypit/protocol";+export type { RunGraph } from "@hypit/protocol";import type { SourceHeader, SourceUnit } from "@hypit/source";export type RunSourceUnit = SourceUnit;@@ -51,7 +52,7 @@ export type RunBuildRecord = {readonly kind: "build-record";readonly id: string;readonly build: string;- /** Logical Output id selected by the prior Build; independent of the current author graph. */+ /** Unique public Output name inside the prior Build Result. */readonly output: string;};@@ -118,33 +119,22 @@ export interface RunFragmentRegistryLike {resolve(packageName: string, fragmentName: string): GraphFragment | undefined;}-/** Complete, mandatory execution-intent graph. Empty alternate Candidate sets are still a Run Graph. */-export type RunGraph = {- readonly format: "hypit.run-graph@1";- readonly candidates: readonly Candidate[];- readonly operations: readonly OperationNode[];- readonly satisfactions: readonly Satisfaction[];- readonly targets: readonly { readonly output: string }[];-};-export type ResolveRunDocumentContext = {readonly compilation: CompiledSourceClosure;readonly fragments: RunFragmentRegistryLike;- readonly readStoredValue: (from: string) => Promise<StoredValue> | StoredValue;- readonly readFile: (from: string, mediaType: string) => Promise<StoredValue> | StoredValue;- /** Host archive boundary: resolve exactly one accepted historical output, never expose Build state. */- readonly resolveBuildRecord: (- build: string,- output: string,- ) => Promise<{ readonly type: TypeRef; readonly value: StoredValue } | undefined>- | { readonly type: TypeRef; readonly value: StoredValue }- | undefined;};+export type RunCandidateSource =+ | { readonly kind: "stored-value"; readonly from: string }+ | { readonly kind: "file"; readonly from: string; readonly mediaType: string }+ | { readonly kind: "build-output"; readonly build: string; readonly output: string };+export type RunCompilation = {readonly document: RunDocument;readonly graph: RunGraph;readonly candidates: Readonly<Record<string, string>>;+ /** Sources for zero-input Candidates, materialized only after global planning selects them. */+ readonly candidateSources: Readonly<Record<string, RunCandidateSource>>;/** Author-written Candidate name selected for each resolved Logical Output. Presentation only. */readonly satisfactionNames: Readonly<Record<string, string>>;};diff --git a/packages/runtime-host-node/src/index.ts b/packages/runtime-host-node/src/index.tsindex cb620f1b..44f6ac7f 100644--- a/packages/runtime-host-node/src/index.ts+++ b/packages/runtime-host-node/src/index.ts@@ -3,15 +3,12 @@ import { constants } from "node:fs";import { homedir } from "node:os";import { delimiter, isAbsolute, join, resolve } from "node:path";import type { ArtifactAttachment } from "@hypit/workspace";-import type { BuildResultReuse } from "@hypit/build-result";-import type { BuildResultRepository } from "@hypit/build-result";+import type { BuildResultForward } from "@hypit/build-result";import type { BuildResultRepositoryLocation } from "@hypit/build-result-kit";-import type { BuildDefinition, BuildState, CapabilityRef, ResourceId } from "@hypit/protocol";+import type { BuildDefinition, BuildState, CapabilityRef } from "@hypit/protocol";import type {BuildCatalogDescriptor,- BuildCatalogEntry,- BuildDispatchSnapshot,- BuildSnapshot,+ BuildCompletion,CapacityReservation,CredentialRef,OperationSnapshot,@@ -19,18 +16,43 @@ import type {} from "@hypit/runtime";import type { RuntimeDoctorDiagnostic } from "@hypit/runtime-kit";-export type RuntimeHostBuildSubmission = {+export type RuntimeHostActiveBuildSubmission = {readonly id: string;readonly state: BuildState;- readonly status: "queued" | "running" | "waiting" | "complete" | "failed" | "cancelled";- readonly dispatch: BuildDispatchSnapshot;+ readonly view: BuildView;};-export type RuntimeHostStatus = {- readonly build: BuildSnapshot | undefined;- readonly catalog: BuildCatalogEntry | undefined;- readonly operations: readonly OperationSnapshot[];- readonly dispatch: BuildDispatchSnapshot | undefined;+export type RuntimeHostFinishedBuildSubmission = {+ readonly id: string;+ readonly state: BuildState;+ readonly completion: BuildCompletion;+};++export type RuntimeHostBuildSubmission = RuntimeHostActiveBuildSubmission | RuntimeHostFinishedBuildSubmission;++export type BuildActivity = "submitting" | "ready" | "running" | "waiting" | "saving-result";++export type BuildOperationView = {+ readonly endpoint: string;+ readonly status: OperationSnapshot["status"];+ readonly progress?: OperationSnapshot["progress"];+ readonly failure?: OperationSnapshot["failure"];+};++/** Stable Host view. Runtime persistence records never cross this boundary. */+export type BuildView = {+ readonly id: string;+ readonly createdAt: number;+ readonly activity: BuildActivity;+ readonly outcome?: BuildCompletion["outcome"];+ readonly issue?: { readonly scope: "result" | "cleanup"; readonly message: string };+ readonly cancellationRequested: boolean;+ readonly source?: { readonly path: string };+ readonly run?: { readonly path: string };+ readonly targets: readonly string[];+ readonly acceptedRecords: number;+ readonly outstandingCommands: number;+ readonly operations: readonly BuildOperationView[];};export type RuntimeHostCredentialStatus = {@@ -43,25 +65,24 @@ export type RuntimeHostCredentialStatus = {readonly writable: boolean;};-export type RuntimeHostArchive = {- status(build: string): Promise<RuntimeHostStatus>;- activity(build: string): Promise<{- readonly operations: readonly OperationSnapshot[];- readonly dispatch: BuildDispatchSnapshot | undefined;- }>;- queue(): Promise<{- readonly dispatches: readonly BuildDispatchSnapshot[];+export type RuntimeHostControl = {+ inspect(build: string): Promise<BuildView | undefined>;+ activity(): Promise<{+ readonly builds: readonly BuildView[];readonly capacity: readonly CapacityReservation[];- readonly operations: readonly OperationSnapshot[];}>;- builds(): Promise<readonly BuildCatalogEntry[]>;- cancel(build: string, reason?: string): Promise<BuildDispatchSnapshot | undefined>;+ cancel(build: string, reason?: string): Promise<BuildView | undefined>;close(): void | Promise<void>;};-export type RuntimeHostResourceAccess = {- readResource(resource: ResourceId): Promise<Uint8Array | undefined>;- openResource(resource: ResourceId): Promise<AsyncIterable<Uint8Array> | undefined>;+/** One-shot Result write or incomplete-submission cleanup with no execution Providers. */+export type RuntimeHostResultControl = {+ finishResult(build: string): Promise<{+ readonly id: string;+ readonly outcome: BuildCompletion["outcome"];+ readonly issue?: { readonly scope: "result" | "cleanup"; readonly message: string };+ } | undefined>;+ discardSubmission(build: string): Promise<boolean>;close(): void | Promise<void>;};@@ -75,18 +96,18 @@ export type RuntimeHostCredentialControl = {close(): void | Promise<void>;};-export type RuntimeHostExecution = RuntimeHostArchive & RuntimeHostResourceAccess & RuntimeHostCredentialControl & {+export type RuntimeHostExecution = RuntimeHostControl & RuntimeHostCredentialControl & RuntimeHostResultControl & {build(request: {readonly id: string;readonly definition: BuildDefinition;readonly componentPackages?: readonly string[];- readonly catalog?: BuildCatalogDescriptor;+ readonly catalog: BuildCatalogDescriptor;readonly attachments?: readonly ArtifactAttachment[];- /** Project-owned result destination, resolved before this Build enters the durable queue. */- readonly result?: {+ /** Project-owned Result destination, fixed before this Build becomes active. */+ readonly result: {readonly repository: BuildResultRepositoryLocation;- readonly name?: string;- readonly reuses?: readonly BuildResultReuse[];+ readonly title?: string;+ readonly forwards?: readonly BuildResultForward[];};}, options?: {readonly follow?: boolean;@@ -122,6 +143,7 @@ export type ManagedProgramReport = {export type RuntimeWorkerState = {readonly state: "running" | "stopped";+ readonly configuration?: "current" | "changed";readonly profile: string;readonly pid?: number;readonly startedAt?: number;@@ -163,15 +185,10 @@ export type NodeRuntimeHost = {readonly packageRoot?: string;}): Promise<RuntimeController>;createRuntime(): Promise<RuntimeHostExecution>;- openArchive(options?: { readonly readOnly?: boolean }): Promise<RuntimeHostArchive>;- openResources(): Promise<RuntimeHostResourceAccess>;+ openControl(options?: { readonly readOnly?: boolean }): Promise<RuntimeHostControl>;+ /** Open only Result-writing dependencies; never construct execution Providers. */+ openResultControl(): Promise<RuntimeHostResultControl>;openCredentials(endpoint: string): Promise<RuntimeHostCredentialControl>;- /** Open the project Repository selected by this Profile, or the supplied zero-config file default. */- openResults?(defaultRoot: string): Promise<{- readonly location: BuildResultRepositoryLocation;- readonly repository: BuildResultRepository;- close(): void | Promise<void>;- }>;/** Explicitly prepare upstream packages selected by this Runtime Profile. */prepare(options?: {readonly onProgress?: (event: import("./packages.js").HostPackageProgress) => void;@@ -188,7 +205,7 @@ export type NodeRuntimeHost = {doctor(options?: {readonly capabilities?: readonly CapabilityRef[];}): Promise<RuntimeHostDoctorResult>;- runWorker(readyFile: string): Promise<void>;+ runWorker(readyFile: string, owner: string): Promise<void>;};/**diff --git a/packages/runtime-local/README.md b/packages/runtime-local/README.mdindex b63f94d8..8011d48e 100644--- a/packages/runtime-local/README.md+++ b/packages/runtime-local/README.md@@ -1,7 +1,7 @@# `@hypit/runtime-local`-The default local Runtime for Hypit. It owns the Worker, scheduler, active SQLite execution state-and Build queue. Project-owned Build Results hold terminal public Outputs.+The default local Runtime for Hypit. It owns the Worker, scheduler and active SQLite execution+worklist. Project-owned Build Results hold finished public Outputs.A Runtime Profile selects only the environmental parts that genuinely vary:@@ -12,10 +12,6 @@ A Runtime Profile selects only the environmental parts that genuinely vary:"use": "@hypit/runtime-local","config": {"dataRoot": ".hypit/runtimes/local",- "results": {- "use": "@hypit/build-result-fs",- "config": { "path": ".hypit/results" }- },"credentials": {"env": { "use": "@hypit/credential-store-env" }},@@ -25,15 +21,33 @@ A Runtime Profile selects only the environmental parts that genuinely vary:}```-Submitting a Build stores it and returns. The local Worker advances several Builds concurrently while-sharing the configured command limit. Endpoint packages declare their own Provider and model limits.+A project that wants a non-default Result repository owns a separate `hypit.results.json`:++```json+{+ "format": "hypit.build-results@1",+ "use": "@hypit/build-result-s3",+ "config": { "bucket": "team-results", "prefix": "projects/episode-12" }+}+```++Submitting a Build stores it and returns. The Worker may advance unrelated Builds together; only the+resources declared by their Commands constrain execution. Endpoint packages declare the Provider+pool and model-lane limits that govern actual external work. Build identity is not a capacity+resource and creates no second queue.Cancellation prevents new work and makes a best effort to cancel an external operation already submitted;completed output is never rolled back.-`results` is optional. Without it, Hypit uses the project's `.hypit/results` directory with no cloud-account or service. It may instead select `@hypit/build-result-s3` for a shared project repository.+Without `hypit.results.json`, Hypit uses the project's `.hypit/results` directory with no cloud+account or service. The project may instead select `@hypit/build-result-s3` for a shared repository.Runtime working Resources remain internal and Build-local; there is no ResourceStore selector. After-a Result is terminal, history is read from the selected repository, not Runtime SQLite.+a Result has an outcome, history is read from the selected repository, not Runtime SQLite.++Saving a finished Result is a separate, idempotent storage action. If that write is interrupted, the+Build keeps its already-decided outcome and reports exact operator attention. `hypit result finish+<build-id>` performs only that pending write and active-state cleanup; it does not run the execution+Worker, call a Producer or load Provider Endpoint packages. `hypit result discard <build-id>` is only+for a submission that never became active and therefore has no Result to save.Source imports select author packages. Runtime Profile entries select only code allowed to access files,credentials, processes or networks. Installing a package changes neither selection.diff --git a/packages/runtime-local/package.json b/packages/runtime-local/package.jsonindex 1022a6f6..64cf25dd 100644--- a/packages/runtime-local/package.json+++ b/packages/runtime-local/package.json@@ -16,6 +16,7 @@"@hypit/build-result-fs": "workspace:*","@hypit/build-result-kit": "workspace:*","@hypit/component-kit": "workspace:*",+ "@hypit/core": "workspace:*","@hypit/driver-node": "workspace:*","@hypit/endpoint-kit": "workspace:*","@hypit/package-loader-node": "workspace:*",@@ -27,7 +28,6 @@"@hypit/validation": "workspace:*"},"devDependencies": {- "@hypit/credential-store-env": "workspace:*",- "@hypit/core": "workspace:*"+ "@hypit/credential-store-env": "workspace:*"}}diff --git a/packages/runtime-local/src/config.ts b/packages/runtime-local/src/config.tsindex de2e7265..c517817e 100644--- a/packages/runtime-local/src/config.ts+++ b/packages/runtime-local/src/config.ts@@ -1,5 +1,5 @@import { readFile, rm, stat } from "node:fs/promises";-import { dirname, resolve } from "node:path";+import { dirname, relative, resolve, sep } from "node:path";import {collectLoadedNodePackageComponents,@@ -7,19 +7,21 @@ import {loadNodePackageSelection,} from "@hypit/package-loader-node";import type { NodePackageSelectionRequest } from "@hypit/package-loader-node";-import { canonicalize } from "@hypit/protocol";+import { assertBuildId, canonicalize, canonicalStringify } from "@hypit/protocol";import type { CanonicalValue, CapabilityRef } from "@hypit/protocol";import {CompositeCredentialStore,} from "@hypit/runtime";import type { CredentialStore } from "@hypit/runtime";import { FileResourceStore } from "@hypit/resource-store-fs";+import { FileBuildResultRepository } from "@hypit/build-result";import {buildResultRepositoryHostAbi,BuildResultRepositoryRegistry,isBuildResultRepositoryHostFacet,} from "@hypit/build-result-kit";import type {+ BuildResultRepositoryDiagnostic,BuildResultRepositoryLocation,BuildResultRepositoryOpened,} from "@hypit/build-result-kit";@@ -47,15 +49,15 @@ import { SqliteRuntimeState } from "@hypit/store-sqlite";import { createLocalRuntime } from "./runtime.js";import {- createLocalRuntimeArchiveControl,- createLocalRuntimeResourceAccess,+ createLocalRuntimeControl,} from "./control.js";import { createLocalCredentialControl } from "./credentials.js";+import { createLocalResultWriter } from "./result-writer.js";import type {LocalCredentialControl,+ LocalResultWriter,LocalRuntime,- LocalRuntimeArchiveControl,- LocalRuntimeResourceAccess,+ LocalRuntimeControl,} from "./types.js";export type RuntimeConfigEntry = {@@ -68,11 +70,21 @@ export type RuntimeConfigEntry = {export type RuntimeConfigDocument = {readonly format: "hypit.runtime-profile@1";readonly dataRoot: string;- readonly results?: RuntimeConfigEntry;readonly credentials: readonly RuntimeConfigEntry[];readonly endpoints: readonly RuntimeConfigEntry[];};+export type ProjectBuildResultConfig = {+ readonly format: "hypit.build-results@1";+ readonly use: string;+ readonly config?: CanonicalValue;+};++export type ProjectBuildResultDoctorResult = {+ readonly location?: BuildResultRepositoryLocation;+ readonly diagnostics: readonly BuildResultRepositoryDiagnostic[];+};+export type LoadRuntimeConfigOptions = {readonly registry?: RuntimeAdapterRegistry;readonly resultRegistry?: BuildResultRepositoryRegistry;@@ -80,6 +92,8 @@ export type LoadRuntimeConfigOptions = {readonly distributionPackageRoot?: string;/** Persistent machine/user state. Defaults to the platform Hypit state root. */readonly hostStateRoot?: string;+ /** Worker-only ownership check performed before reclaiming or claiming execution. */+ readonly assertExecutionOwner?: () => Promise<void> | void;};export type RuntimeConfigDoctorResult = {@@ -139,7 +153,7 @@ function entry(value: unknown, instance: string, subject: string, poolAllowed =function entries(value: unknown, subject: string, poolAllowed = false): readonly RuntimeConfigEntry[] {const values = object(value ?? {}, subject);- return Object.entries(values).map(([instance, item]) => {+ return Object.entries(values).sort(([left], [right]) => left.localeCompare(right)).map(([instance, item]) => {requiredString(instance, `${subject} instance`);return entry(item, instance, `${subject}.${instance}`, poolAllowed);});@@ -157,8 +171,7 @@ export function parseRuntimeConfig(value: unknown): RuntimeConfigDocument {throw new Error(`Local Runtime loader cannot activate ${String(runtime.use)}`);}const config = object(runtime.config, "$runtime.runtime.config");- exactKeys(config, ["dataRoot", "results", "credentials", "endpoints"], "$runtime.runtime.config");- const results = config.results === undefined ? undefined : entry(config.results, "results", "$runtime.runtime.config.results");+ exactKeys(config, ["dataRoot", "credentials", "endpoints"], "$runtime.runtime.config");const credentials = entries(config.credentials, "$runtime.runtime.config.credentials");const endpoints = entries(config.endpoints, "$runtime.runtime.config.endpoints", true);const ids = [...credentials, ...endpoints].map((value) => value.instance);@@ -166,7 +179,6 @@ export function parseRuntimeConfig(value: unknown): RuntimeConfigDocument {return {format: "hypit.runtime-profile@1",dataRoot: requiredString(config.dataRoot, "$runtime.runtime.config.dataRoot"),- ...(results === undefined ? {} : { results }),credentials,endpoints,};@@ -249,22 +261,6 @@ async function installBuildResultAdapter(if (!registry.has(use)) throw new Error(`Package selection did not provide Build Result Repository ${use}`);}-function resultLocation(opened: OpenedRuntimeConfig, defaultRoot: string): BuildResultRepositoryLocation {- const selected = opened.document.results;- return selected === undefined- ? {- root: resolve(defaultRoot),- selection: { use: "@hypit/build-result-fs", config: { path: "." } },- }- : {- root: opened.profileRoot,- selection: {- use: selected.use,- ...(selected.config === undefined ? {} : { config: selected.config }),- },- };-}-async function openBuildResultLocation(location: BuildResultRepositoryLocation,options: LoadRuntimeConfigOptions,@@ -275,18 +271,93 @@ async function openBuildResultLocation(return await registry.open(location.selection, location.root);}-export async function openBuildResultRepositoryFromConfig(- path: string,- defaultRoot: string,+export async function openBuildResultRepositoryLocation(+ location: BuildResultRepositoryLocation,+ options: LoadRuntimeConfigOptions = {},+): Promise<BuildResultRepositoryOpened> {+ const root = resolve(location.root);+ const registry = options.resultRegistry ?? new BuildResultRepositoryRegistry();+ return await openBuildResultLocation(location, options, resolve(options.packageRoot ?? root), registry);+}++export async function openProjectBuildResultRepository(+ projectRoot: string,options: LoadRuntimeConfigOptions = {},): Promise<BuildResultRepositoryOpened & { readonly location: BuildResultRepositoryLocation }> {- const opened = await openRuntimeConfig(path, options.packageRoot);- const location = resultLocation(opened, defaultRoot);+ const root = resolve(projectRoot);+ const selected = await projectBuildResultLocation(root);+ const location = selected.location;+ if (selected.implicit) {+ return {+ location,+ repository: new FileBuildResultRepository(resolve(root, ".hypit/results")),+ };+ }const registry = options.resultRegistry ?? new BuildResultRepositoryRegistry();- const result = await openBuildResultLocation(location, options, opened.packageRoot, registry);+ const result = await openBuildResultLocation(location, options, resolve(options.packageRoot ?? root), registry);return { ...result, location };}+async function projectBuildResultLocation(root: string): Promise<{+ readonly location: BuildResultRepositoryLocation;+ readonly implicit: boolean;+}> {+ const configPath = resolve(root, "hypit.results.json");+ const text = await readFile(configPath, "utf8").catch((error: unknown) => {+ if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined;+ throw error;+ });+ let selection: BuildResultRepositoryLocation["selection"];+ const implicit = text === undefined;+ if (text === undefined) {+ selection = { use: "@hypit/build-result-fs", config: { path: ".hypit/results" } };+ } else {+ const item = object(JSON.parse(text), "$results");+ exactKeys(item, ["format", "use", "config"], "$results");+ if (item.format !== "hypit.build-results@1") {+ throw new Error("$results.format must be hypit.build-results@1");+ }+ selection = {+ use: requiredString(item.use, "$results.use"),+ ...(item.config === undefined ? {} : { config: canonicalize(item.config) }),+ };+ }+ return { location: { root, selection }, implicit };+}++/** Diagnose the project-owned Result Store without reading Result history or mutating storage. */+export async function doctorProjectBuildResultRepository(+ projectRoot: string,+ options: LoadRuntimeConfigOptions = {},+): Promise<ProjectBuildResultDoctorResult> {+ const root = resolve(projectRoot);+ let location: BuildResultRepositoryLocation | undefined;+ try {+ location = (await projectBuildResultLocation(root)).location;+ const registry = options.resultRegistry ?? new BuildResultRepositoryRegistry();+ await installBuildResultAdapter(+ registry,+ resolve(options.packageRoot ?? root),+ location.selection.use,+ options.distributionPackageRoot,+ );+ return {+ location,+ diagnostics: await registry.doctor(location.selection, location.root),+ };+ } catch (error) {+ return {+ ...(location === undefined ? {} : { location }),+ diagnostics: [{+ severity: "error",+ code: "RESULT_REPOSITORY_INVALID",+ message: error instanceof Error ? error.message : String(error),+ subject: resolve(root, "hypit.results.json"),+ }],+ };+ }+}+export async function resolveRuntimeConfigPaths(path: string,options: LoadRuntimeConfigOptions = {},@@ -305,7 +376,6 @@ export async function prepareRuntimeConfigPackages(if (options.distributionPackageRoot === undefined) return [];const { document } = await openRuntimeConfig(path, options.packageRoot);const requirements = await distributionExternalPackageRequirements([- ...(document.results === undefined ? [] : [document.results.use]),...document.credentials.map((item) => item.use),...document.endpoints.map((item) => item.use),], options.distributionPackageRoot);@@ -405,17 +475,21 @@ function statePath(root: string): string {}function buildWorkPath(root: string, build: string): string {- if (build.trim().length === 0 || build.includes("/") || build.includes("\\")) {- throw new Error("Build id is not a working-directory name");+ assertBuildId(build);+ const work = resolve(root, "work");+ const target = resolve(work, build);+ const relation = relative(work, target);+ if (relation.length === 0 || relation === ".." || relation.startsWith(`..${sep}`)) {+ throw new Error(`Build ${build} leaves Runtime work root ${work}`);}- return resolve(root, "work", build);+ return target;}async function inspectRuntimeConfig(path: string,options: RuntimeInspectionOptions,): Promise<RuntimeConfigDoctorResult> {- const { absolute, document, root, profileRoot, packageRoot } = await openRuntimeConfig(path, options.packageRoot);+ const { absolute, document, root, packageRoot } = await openRuntimeConfig(path, options.packageRoot);const hostStateRoot = resolve(options.hostStateRoot ?? hypitHostStateRoot());const diagnostics: RuntimeDoctorDiagnostic[] = [];try {@@ -426,19 +500,8 @@ async function inspectRuntimeConfig(}}const registry = options.registry ?? new RuntimeAdapterRegistry();- const resultRegistry = options.resultRegistry ?? new BuildResultRepositoryRegistry();try {await installRuntimeAdapters(registry, packageRoot, runtimePackageSelection(document), options.distributionPackageRoot);- if (document.results !== undefined) {- await installBuildResultAdapter(resultRegistry, packageRoot, document.results.use, options.distributionPackageRoot);- resultRegistry.validate(- {- use: document.results.use,- ...(document.results.config === undefined ? {} : { config: document.results.config }),- },- profileRoot,- );- }} catch (error) {return { dataRoot: root, diagnostics: [diagnostic(error, "RUNTIME_PACKAGE_SELECTION_INVALID")] };}@@ -518,9 +581,7 @@ async function inspectRuntimeConfig(code: "RUNTIME_CREDENTIAL_MISSING",message: `${slot.label} for Endpoint ${slot.endpoint} is not configured. ${slot.ref.store === "env"- ? slot.ref.key === "HYPIHUB_API_KEY"- ? `Sign in with HypiHub using: hypit auth login ${slot.endpoint} --runtime ${absolute}`- : `Set ${slot.ref.key} in this process environment.`+ ? `Set ${slot.ref.key} in this process environment.`: `Configure it with: hypit auth login ${slot.endpoint} --runtime ${absolute}`}`,subject: `${slot.endpoint}.${slot.slot}`,});@@ -564,15 +625,16 @@ export async function createRuntimeFromConfig(const registry = options.registry ?? new RuntimeAdapterRegistry();const resultRegistry = options.resultRegistry ?? new BuildResultRepositoryRegistry();await installRuntimeAdapters(registry, packageRoot, runtimePackageSelection(document), options.distributionPackageRoot);- await installBuildResultAdapter(- resultRegistry,- packageRoot,- document.results?.use ?? "@hypit/build-result-fs",- options.distributionPackageRoot,- );const state = new SqliteRuntimeState(statePath(root));+ // Only selections that can change Command execution or an Operation handle are pinned until+ // every Build using them has left active Runtime state.+ const environmentConfig = canonicalStringify({+ credentials: document.credentials,+ endpoints: document.endpoints,+ });let credentials: Awaited<ReturnType<typeof openCredentialStores>> | undefined;try {+ await state.environment.use(environmentConfig);credentials = await openCredentialStores(document, root, hostStateRoot, registry);const endpoints = await Promise.all(document.endpoints.map(async (item) => await registry.createEndpoint(item.use,@@ -582,7 +644,14 @@ export async function createRuntimeFromConfig(buildStore: state.builds,buildCatalog: state.catalog,operationStore: state.operations,- dispatchStore: state.dispatch,+ commandExecutionStore: state.commandExecutions,+ assertEnvironment: async () => {+ await state.environment.assert(environmentConfig);+ await options.assertExecutionOwner?.();+ },+ executionStore: state.execution,+ removeActiveBuild: async (build) => await state.removeActiveBuild(build),+ submissionStore: state.submissions,resourceStore: new FileResourceStore(resolve(root, "resources")),resourceStoreForBuild: (build) => new FileResourceStore(buildWorkPath(root, build)),clearBuildResources: async (build) => {@@ -611,28 +680,44 @@ export async function createRuntimeFromConfig(}}-export async function createRuntimeArchiveFromConfig(+export async function createRuntimeControlFromConfig(path: string,options: LoadRuntimeConfigOptions & { readonly readOnly?: boolean } = {},-): Promise<LocalRuntimeArchiveControl> {+): Promise<LocalRuntimeControl> {const { root } = await openRuntimeConfig(path, options.packageRoot);const state = new SqliteRuntimeState(statePath(root), { readOnly: options.readOnly === true });- return createLocalRuntimeArchiveControl({+ return createLocalRuntimeControl({buildStore: state.builds,buildCatalog: state.catalog,operationStore: state.operations,- dispatchStore: state.dispatch,+ executionStore: state.execution,+ submissionStore: state.submissions,close: () => state.close(),});}-export async function createRuntimeResourceAccessFromConfig(+export async function createRuntimeResultControlFromConfig(path: string,options: LoadRuntimeConfigOptions = {},-): Promise<LocalRuntimeResourceAccess> {- const { root } = await openRuntimeConfig(path, options.packageRoot);- return createLocalRuntimeResourceAccess({+): Promise<LocalResultWriter> {+ const { root, packageRoot } = await openRuntimeConfig(path, options.packageRoot);+ const state = new SqliteRuntimeState(statePath(root));+ const resultRegistry = options.resultRegistry ?? new BuildResultRepositoryRegistry();+ return createLocalResultWriter({+ buildStore: state.builds,+ operationStore: state.operations,+ commandExecutionStore: state.commandExecutions,+ executionStore: state.execution,+ removeActiveBuild: async (build) => await state.removeActiveBuild(build),+ submissionStore: state.submissions,resourceStore: new FileResourceStore(resolve(root, "resources")),+ resourceStoreForBuild: (build) => new FileResourceStore(buildWorkPath(root, build)),+ clearBuildResources: async (build) => {+ await rm(buildWorkPath(root, build), { recursive: true, force: true });+ },+ openBuildResultRepository: async (location) =>+ await openBuildResultLocation(location, options, packageRoot, resultRegistry),+ close: () => state.close(),});}diff --git a/packages/runtime-local/src/control.ts b/packages/runtime-local/src/control.tsindex f9ca1740..0057d8b5 100644--- a/packages/runtime-local/src/control.ts+++ b/packages/runtime-local/src/control.ts@@ -1,79 +1,104 @@-import {- isStreamingResourceStore,-} from "@hypit/runtime";-import type {- CreateLocalRuntimeArchiveControlOptions,- CreateLocalRuntimeResourceAccessOptions,- LocalRuntimeArchiveControl,- LocalRuntimeResourceAccess,+ CreateLocalRuntimeControlOptions,+ LocalRuntimeControl,} from "./types.js";+import { buildExecutionActivity } from "@hypit/runtime";+import type {+ PendingBuildSubmission,+ BuildCatalogEntry,+ BuildExecutionSnapshot,+ BuildSnapshot,+ OperationSnapshot,+} from "@hypit/runtime";+import type { BuildView } from "@hypit/runtime-host-node";+import { buildIdCreatedAt } from "@hypit/protocol";-/** Durable execution-state control that never opens or depends on a ResourceStore. */-export function createLocalRuntimeArchiveControl(- options: CreateLocalRuntimeArchiveControlOptions,-): LocalRuntimeArchiveControl {+function buildView(input: {+ readonly build: string;+ readonly snapshot?: BuildSnapshot;+ readonly catalog?: BuildCatalogEntry;+ readonly submission?: PendingBuildSubmission;+ readonly execution?: BuildExecutionSnapshot;+ readonly operations: readonly OperationSnapshot[];+}): BuildView | undefined {+ if (input.submission === undefined && input.execution === undefined) return undefined;+ const createdAt = buildIdCreatedAt(input.build);+ if (createdAt === undefined) throw new Error(`Active Build ${input.build} has no ordered public id`);+ const runtimeActivity = input.execution === undefined ? undefined : buildExecutionActivity(input.execution);+ const activity: BuildView["activity"] = input.submission !== undefined+ ? "submitting"+ : runtimeActivity!;+ const names = new Map(input.catalog?.publishedOutputs.map((item) => [item.ref.id, item.name]) ?? []);+ const targets = input.snapshot?.state.targets.map((target) => {+ const name = names.get(target.output);+ if (name === undefined) throw new Error(`Build ${input.build} target ${target.output} has no published Output name`);+ return name;+ }) ?? [];+ return {+ id: input.build,+ createdAt,+ activity,+ ...(input.execution?.decision === undefined ? {} : { outcome: input.execution.decision.outcome }),+ ...(input.execution?.attention === undefined ? {} : {+ issue: { scope: input.execution.attention.step, message: input.execution.attention.error },+ }),+ cancellationRequested: input.execution?.cancellation !== undefined,+ ...(input.catalog?.source === undefined ? {} : { source: input.catalog.source }),+ ...(input.catalog?.run === undefined ? {} : { run: input.catalog.run }),+ targets,+ acceptedRecords: input.snapshot?.state.records.length ?? 0,+ outstandingCommands: input.snapshot?.state.outstanding.length ?? 0,+ operations: input.operations.map((operation) => ({+ endpoint: operation.endpoint,+ status: operation.status,+ ...(operation.progress === undefined ? {} : { progress: operation.progress }),+ ...(operation.failure === undefined ? {} : { failure: operation.failure }),+ })),+ };+}++/** Active Runtime control that never opens or depends on a ResourceStore. */+export function createLocalRuntimeControl(+ options: CreateLocalRuntimeControlOptions,+): LocalRuntimeControl {const buildCatalog = options.buildCatalog;+ const inspect = async (build: string): Promise<BuildView | undefined> => {+ const [snapshot, catalog, operations, submission, execution] = await Promise.all([+ options.buildStore.read(build),+ buildCatalog?.read(build),+ options.operationStore.list({ build }),+ options.submissionStore.read(build),+ options.executionStore.read(build),+ ]);+ return buildView({+ build,+ ...(snapshot === undefined ? {} : { snapshot }),+ ...(catalog === undefined ? {} : { catalog }),+ ...(submission === undefined ? {} : { submission }),+ ...(execution === undefined ? {} : { execution }),+ operations,+ });+ };return {- async activity(build) {- const [operations, dispatch] = await Promise.all([- options.operationStore.list({ build }),- options.dispatchStore.read(build),- ]);- return { operations, dispatch };- },- async status(build) {- const [snapshot, catalog, operations, dispatch] = await Promise.all([- options.buildStore.read(build),- buildCatalog?.read(build),- options.operationStore.list({ build }),- options.dispatchStore.read(build),+ inspect,+ async activity() {+ const [submissions, executions, capacity] = await Promise.all([+ options.submissionStore.list(),+ options.executionStore.list(),+ options.executionStore.listCapacity(),]);return {- build: snapshot,- catalog,- operations,- dispatch,- };- },- async queue() {- const [dispatches, capacity] = await Promise.all([- options.dispatchStore.list({ phases: ["queued", "running", "waiting"] }),- options.dispatchStore.listCapacity(),- ]);- const operationHistory = (await Promise.all(dispatches.map(async (item) =>- await options.operationStore.list({ build: item.build })))).flat();- return {- dispatches,+ builds: (await Promise.all([...submissions, ...executions].map(async (item) =>+ await inspect(item.build))))+ .filter((item): item is BuildView => item !== undefined)+ .sort((left, right) => right.id.localeCompare(left.id)),capacity,- operations: operationHistory,};},- async builds() {- return await buildCatalog?.list() ?? [];- },async cancel(build, reason) {- if (await options.dispatchStore.read(build) === undefined) return undefined;- return await options.dispatchStore.requestCancellation(build, reason);- },- close() {- return options.close?.();- },- };-}--/** Explicit active-resource byte access with no dependency on execution-state Stores. */-export function createLocalRuntimeResourceAccess(- options: CreateLocalRuntimeResourceAccessOptions,-): LocalRuntimeResourceAccess {- return {- async readResource(resource) {- return await options.resourceStore.get(resource);- },- async openResource(resource) {- if (isStreamingResourceStore(options.resourceStore)) return await options.resourceStore.open(resource);- const bytes = await options.resourceStore.get(resource);- return bytes === undefined ? undefined : (async function* () { yield bytes; })();+ if (await options.executionStore.read(build) === undefined) return undefined;+ await options.executionStore.requestCancellation(build, reason);+ return await inspect(build);},close() {return options.close?.();diff --git a/packages/runtime-local/src/host.ts b/packages/runtime-local/src/host.tsindex 902dc38c..2b3f62b6 100644--- a/packages/runtime-local/src/host.ts+++ b/packages/runtime-local/src/host.ts@@ -4,15 +4,15 @@ import type {RuntimeWorkerLaunch,} from "@hypit/runtime-host-node";import { hypitHostStateRoot } from "@hypit/runtime-host-node";-import { resolve } from "node:path";+import { join, resolve } from "node:path";+import { SqliteRuntimeState } from "@hypit/store-sqlite";import {- createRuntimeArchiveFromConfig,- createRuntimeResourceAccessFromConfig,+ createRuntimeControlFromConfig,+ createRuntimeResultControlFromConfig,createRuntimeCredentialsFromConfig,createRuntimeFromConfig,doctorRuntimeConfig,- openBuildResultRepositoryFromConfig,prepareRuntimeConfigPackages,preflightRuntimeConfig,resolveRuntimeConfigPaths,@@ -25,6 +25,7 @@ import {import {ensureRuntimeProcess,markRuntimeProcessReady,+ runtimeProcessOwnsCurrentProfile,runtimeProcessLogs,runtimeProcessStatus,stopRuntimeProcess,@@ -100,12 +101,12 @@ export async function openLocalRuntimeHost(},controller,createRuntime: async () => await createRuntimeFromConfig(profile, { packageRoot: basePackageRoot, ...distribution }),- openArchive: async (options) => await createRuntimeArchiveFromConfig(profile, {+ openControl: async (options) => await createRuntimeControlFromConfig(profile, {packageRoot: basePackageRoot,...distribution,...(options?.readOnly === undefined ? {} : { readOnly: options.readOnly }),}),- openResources: async () => await createRuntimeResourceAccessFromConfig(profile, {+ openResultControl: async () => await createRuntimeResultControlFromConfig(profile, {packageRoot: basePackageRoot,...distribution,}),@@ -114,19 +115,6 @@ export async function openLocalRuntimeHost(endpoint,{ packageRoot: basePackageRoot, ...distribution },),- openResults: async (defaultRoot) => {- const opened = await openBuildResultRepositoryFromConfig(profile, defaultRoot, {- packageRoot: basePackageRoot,- ...distribution,- });- return {- location: opened.location,- repository: opened.repository,- close: async () => {- await opened.close?.();- },- };- },prepare: async (options) => await prepareRuntimeConfigPackages(profile, {packageRoot: basePackageRoot,...distribution,@@ -142,22 +130,68 @@ export async function openLocalRuntimeHost(...distribution,...(options?.capabilities === undefined ? {} : { capabilities: options.capabilities }),}),- runWorker: async (readyFile) => {- const runtime = await createRuntimeFromConfig(profile, { packageRoot: basePackageRoot, ...distribution });+ runWorker: async (readyFile, owner) => {+ const selected = await resolveRuntimeConfigPaths(profile, { packageRoot: basePackageRoot, ...distribution });+ const leaseState = new SqliteRuntimeState(join(selected.dataRoot, "runtime.sqlite"));+ const leaseMs = 30_000;+ const acquiredAt = Date.now();+ const acquired = await leaseState.workerLease.acquire({+ owner,+ pid: process.pid,+ acquiredAt,+ expiresAt: acquiredAt + leaseMs,+ });+ if (!acquired) {+ leaseState.close();+ throw new Error("another Runtime Worker owns this Runtime");+ }+ let runtime: Awaited<ReturnType<typeof createRuntimeFromConfig>> | undefined;const abort = new AbortController();const stop = (): void => abort.abort();process.once("SIGTERM", stop);process.once("SIGINT", stop);+ let renewal = Promise.resolve();+ const heartbeat = setInterval(() => {+ renewal = renewal.then(async () => {+ if (!await runtimeProcessOwnsCurrentProfile(profile, selected.dataRoot, owner)) {+ abort.abort(new Error("Runtime Profile changed; this Worker stopped before using mixed configuration"));+ return;+ }+ const renewed = await leaseState.workerLease.renew(owner, process.pid, Date.now() + leaseMs);+ if (!renewed) abort.abort(new Error("Runtime Worker ownership was lost"));+ }).catch((error: unknown) => abort.abort(error));+ }, 5_000);try {- await markRuntimeProcessReady(readyFile);+ const assertExecutionOwner = async (): Promise<void> => {+ const lease = await leaseState.workerLease.read();+ if (lease?.owner !== owner || lease.pid !== process.pid || lease.expiresAt <= Date.now()) {+ throw new Error("Runtime Worker no longer owns this Runtime");+ }+ };+ runtime = await createRuntimeFromConfig(profile, {+ packageRoot: basePackageRoot,+ ...distribution,+ assertExecutionOwner,+ });await runtime.work({idlePollMs: 250,signal: abort.signal,+ ready: async () => {+ await assertExecutionOwner();+ if (!await runtimeProcessOwnsCurrentProfile(profile, selected.dataRoot, owner)) {+ throw new Error("Runtime Profile changed while the Worker was starting");+ }+ await markRuntimeProcessReady(readyFile, owner);+ },});} finally {+ clearInterval(heartbeat);+ await renewal.catch(() => undefined);process.removeListener("SIGTERM", stop);process.removeListener("SIGINT", stop);- await runtime.close();+ await runtime?.close();+ await leaseState.workerLease.release(owner, process.pid).catch(() => undefined);+ leaseState.close();}},};diff --git a/packages/runtime-local/src/index.ts b/packages/runtime-local/src/index.tsindex 38d255c6..b5c55eec 100644--- a/packages/runtime-local/src/index.ts+++ b/packages/runtime-local/src/index.ts@@ -1,18 +1,20 @@export {- createLocalRuntimeArchiveControl,- createLocalRuntimeResourceAccess,+ createLocalRuntimeControl,} from "./control.js";export { createLocalCredentialControl } from "./credentials.js";+export { createLocalResultWriter } from "./result-writer.js";export {createLocalRuntime,} from "./runtime.js";export { openLocalRuntimeHost } from "./host.js";export {createRuntimeFromConfig,- createRuntimeArchiveFromConfig,- createRuntimeResourceAccessFromConfig,+ createRuntimeControlFromConfig,+ createRuntimeResultControlFromConfig,createRuntimeCredentialsFromConfig,- openBuildResultRepositoryFromConfig,+ doctorProjectBuildResultRepository,+ openProjectBuildResultRepository,+ openBuildResultRepositoryLocation,declaredManagedPrograms,doctorRuntimeConfig,prepareRuntimeConfigPackages,diff --git a/packages/runtime-local/src/result-writer.ts b/packages/runtime-local/src/result-writer.tsnew file mode 100644index 00000000..51f68a6d--- /dev/null+++ b/packages/runtime-local/src/result-writer.ts@@ -0,0 +1,229 @@+import { randomUUID } from "node:crypto";+import { BuildMachine } from "@hypit/core";+import { isStreamingResourceStore } from "@hypit/runtime";+import type {+ BuildExecutionSnapshot,+ BuildSnapshot,+ OperationSnapshot,+} from "@hypit/runtime";+import type { CommandResult } from "@hypit/protocol";+import type { BuildResultWriter } from "@hypit/build-result";++import type {+ CreateLocalResultWriterOptions,+ LocalResultWriter,+} from "./types.js";++function assert(condition: unknown, message: string): asserts condition {+ if (!condition) throw new Error(message);+}++function operationEvent(operation: OperationSnapshot): CommandResult | undefined {+ if (operation.status === "pending") return undefined;+ if (operation.status === "completed") {+ assert(operation.completion !== undefined, `Operation ${operation.id} has no completion`);+ return {+ kind: "need-fulfilled",+ command: operation.command,+ value: operation.completion.value,+ };+ }+ if (operation.status === "failed") {+ assert(operation.failure !== undefined, `Operation ${operation.id} has no failure`);+ return {+ kind: "command-failed",+ command: operation.command,+ code: operation.failure.code,+ message: operation.failure.message,+ };+ }+ return {+ kind: "command-failed",+ command: operation.command,+ code: "CANCELLED",+ message: `Operation ${operation.id} was cancelled by the Runtime pool`,+ };+}++/**+ * Result writing only consumes already accepted execution facts and transient bytes. It cannot load+ * Producers or Endpoints and it never changes the frozen execution decision.+ */+export function createLocalResultWriter(+ options: CreateLocalResultWriterOptions,+): LocalResultWriter {+ const owner = randomUUID();+ const openWriter = async (execution: BuildExecutionSnapshot): Promise<{+ readonly writer: BuildResultWriter;+ readonly manifest: import("@hypit/build-result").BuildResultManifest;+ close(): Promise<void>;+ }> => {+ const opened = await options.openBuildResultRepository(execution.result);+ try {+ const [writer, manifest] = await Promise.all([+ opened.repository.openWriter(execution.build),+ opened.repository.read(execution.build),+ ]);+ assert(writer !== undefined && manifest !== undefined, `Build ${execution.build} has no Result draft`);+ return {+ writer,+ manifest,+ close: async () => await opened.close?.(),+ };+ } catch (error) {+ await opened.close?.();+ throw error;+ }+ };++ const acceptStoredResults = async (build: string): Promise<BuildSnapshot> => {+ const snapshot = await options.buildStore.read(build);+ assert(snapshot !== undefined, `Build ${build} has no durable execution state`);+ const machine = new BuildMachine(snapshot.definition, snapshot.facts);+ const accept = async (event: CommandResult): Promise<void> => {+ if (!machine.view().outstanding.some((command) => command.id === event.command)) return;+ const fact = machine.evaluate(event);+ if (fact === undefined) return;+ await options.buildStore.append(build, fact);+ machine.commit();+ };+ for (const receipt of await options.commandExecutionStore.list(build)) {+ if (receipt.status === "completed" && receipt.event !== undefined) await accept(receipt.event);+ }+ for (const operation of await options.operationStore.list({ build })) {+ const event = operationEvent(operation);+ if (event !== undefined) await accept(event);+ }+ const accepted = await options.buildStore.read(build);+ assert(accepted !== undefined, `Build ${build} disappeared while accepting stored results`);+ return accepted;+ };++ const syncResult = async (+ execution: BuildExecutionSnapshot,+ state: import("@hypit/protocol").BuildState,+ ): Promise<void> => {+ const result = await openWriter(execution);+ try {+ if (result.manifest.outcome !== undefined) return;+ const resources = options.resourceStoreForBuild?.(execution.build) ?? options.resourceStore;+ await result.writer.sync({+ state,+ resources: {+ open: async (artifact) => {+ if (isStreamingResourceStore(resources)) return await resources.open(artifact.resource);+ const bytes = await resources.get(artifact.resource);+ return bytes === undefined ? undefined : (async function* () { yield bytes; })();+ },+ },+ });+ } finally {+ await result.close();+ }+ };++ const finishResult = async (execution: BuildExecutionSnapshot): Promise<void> => {+ assert(execution.decision !== undefined, `Execution ${execution.build} has no decision`);+ const opened = await openWriter(execution);+ let closed = false;+ try {+ if (opened.manifest.outcome === undefined) {+ await opened.close();+ closed = true;+ const snapshot = await acceptStoredResults(execution.build);+ await syncResult(execution, snapshot.state);+ const reopened = await openWriter(execution);+ try {+ await reopened.writer.finish({+ outcome: execution.decision.outcome,+ ...(execution.decision.reason === undefined ? {} : { failure: execution.decision.reason }),+ });+ } finally {+ await reopened.close();+ }+ return;+ }+ await opened.writer.finish({+ outcome: execution.decision.outcome,+ ...(execution.decision.reason === undefined ? {} : { failure: execution.decision.reason }),+ });+ } finally {+ if (!closed) await opened.close();+ }+ };++ const writeResultAndCleanup = async (execution: BuildExecutionSnapshot) => {+ assert(execution.decision !== undefined, `Execution ${execution.build} has no decision`);+ assert(execution.resultWrite?.owner === owner,+ `Execution ${execution.build} Result writer is not owned by this process`);+ let step: "result" | "cleanup" = "result";+ try {+ await finishResult(execution);+ step = "cleanup";+ await Promise.resolve(options.clearBuildResources?.(execution.build));+ return await options.removeActiveBuild(execution.build);+ } catch (error) {+ const reason = error instanceof Error ? error.message : String(error);+ try {+ await options.executionStore.setAttention(execution.build, { step, error: reason });+ } catch (attentionError) {+ await options.executionStore.releaseResultWrite(execution.build, owner).catch(() => undefined);+ throw attentionError;+ }+ return await options.executionStore.releaseResultWrite(execution.build, owner);+ }+ };++ const claimResultWrite = async (build: string): Promise<BuildExecutionSnapshot> => {+ const claimed = await options.executionStore.claimResultWrite(build, owner);+ if (claimed !== undefined) return claimed;+ const current = await options.executionStore.read(build);+ assert(current !== undefined, `Execution ${build} does not exist`);+ assert(current.decision !== undefined, `Execution ${build} has no decision`);+ assert(current.resultWrite === undefined,+ `Execution ${build} Result write is already owned by another process`);+ throw new Error(`Execution ${build} could not be claimed for Result writing`);+ };++ const completeResult = async (initial: BuildExecutionSnapshot) =>+ await writeResultAndCleanup(await claimResultWrite(initial.build));++ const discardSubmission = async (build: string): Promise<boolean> => {+ const submission = await options.submissionStore.read(build);+ if (submission === undefined) return false;+ const opened = await options.openBuildResultRepository(submission.result);+ try {+ await opened.repository.remove(build);+ } finally {+ await opened.close?.();+ }+ await Promise.resolve(options.clearBuildResources?.(build));+ await options.submissionStore.discard(build);+ return true;+ };++ return {+ sync: syncResult,+ async finishResult(build) {+ const execution = await options.executionStore.read(build);+ if (execution === undefined) return undefined;+ assert(execution.decision !== undefined,+ `Build ${build} is still executing; its Result cannot be finished yet`);+ const finished = await writeResultAndCleanup(await claimResultWrite(build));+ return "createdAt" in finished+ ? {+ id: build,+ outcome: finished.decision!.outcome,+ ...(finished.attention === undefined ? {} : {+ issue: { scope: finished.attention.step, message: finished.attention.error },+ }),+ }+ : { id: build, outcome: finished.outcome };+ },+ discardSubmission,+ completeResult,+ close() {+ return options.close?.();+ },+ };+}diff --git a/packages/runtime-local/src/runtime.ts b/packages/runtime-local/src/runtime.tsindex 6c591eae..705f613a 100644--- a/packages/runtime-local/src/runtime.ts+++ b/packages/runtime-local/src/runtime.ts@@ -1,3 +1,5 @@+import { isAbsolute, relative, resolve, sep } from "node:path";+import {registerProducerFacets,registerTypeValidatorFacets,@@ -10,10 +12,13 @@ import {import {isStreamingResourceStore,} from "@hypit/runtime";+import { assertOrderedBuildId } from "@hypit/protocol";+import type { BlobRef, BuildDefinition } from "@hypit/protocol";import { TypeValidatorRegistry } from "@hypit/validation";-import { createLocalRuntimeArchiveControl, createLocalRuntimeResourceAccess } from "./control.js";+import { createLocalRuntimeControl } from "./control.js";import { createLocalCredentialControl } from "./credentials.js";+import { createLocalResultWriter } from "./result-writer.js";import { createDurableLocalWorker } from "./worker.js";import type {CreateLocalRuntimeOptions,@@ -32,6 +37,46 @@ function nonNegativeInteger(value: number, subject: string): number {return value;}+function projectPath(root: string, path: string): string {+ const absolute = isAbsolute(path) ? resolve(path) : resolve(root, path);+ const relation = relative(resolve(root), absolute);+ assert(relation === "" || (!relation.startsWith("..") && !isAbsolute(relation)),+ `Build Result source ${path} is outside project ${resolve(root)}`);+ return (relation || ".").split(sep).join("/");+}++function requiredInitialResources(request: LocalBuildRequest): ReadonlySet<string> {+ const definition = request.definition;+ const forwarded = new Set(request.result.forwards?.map((item) => item.output) ?? []);+ const publicOwnedRecords = request.catalog.publishedOutputs.flatMap((published) => {+ if (forwarded.has(published.ref.id)) return [];+ const binding = definition.plan.outputBindings.find((item) => item.output === published.ref.id);+ return binding === undefined ? [] : [binding.record];+ });+ const recordIds = new Set([+ ...publicOwnedRecords,+ ...definition.plan.steps.flatMap((step) => Object.values(step.inputs)),+ ]);+ const resources = new Set<string>();+ const visit = (value: unknown): void => {+ if (value === null || typeof value !== "object") return;+ if (Array.isArray(value)) {+ value.forEach(visit);+ return;+ }+ const item = value as Readonly<Record<string, unknown>>;+ if (item.kind === "blob" && typeof item.resource === "string") {+ resources.add((item as unknown as BlobRef).resource);+ return;+ }+ Object.values(item).forEach(visit);+ };+ [...definition.program.records, ...definition.initialRecords]+ .filter((record) => recordIds.has(record.id))+ .forEach((record) => visit(record.value));+ return resources;+}+async function wait(delayMs: number, signal: AbortSignal | undefined): Promise<void> {if (signal?.aborted === true) throw signal.reason ?? new Error("Local Runtime follow was aborted");await new Promise<void>((resolveWait, reject) => {@@ -92,38 +137,48 @@ export async function createLocalRuntime(operations: options.operationStore,validators,});+ const resultWriter = createLocalResultWriter({+ buildStore: options.buildStore,+ operationStore: options.operationStore,+ commandExecutionStore: options.commandExecutionStore,+ executionStore: options.executionStore,+ removeActiveBuild: options.removeActiveBuild,+ submissionStore: options.submissionStore,+ resourceStore: options.resourceStore,+ ...(options.resourceStoreForBuild === undefined ? {} : { resourceStoreForBuild: options.resourceStoreForBuild }),+ ...(options.clearBuildResources === undefined ? {} : { clearBuildResources: options.clearBuildResources }),+ openBuildResultRepository,+ });const worker = createDurableLocalWorker(driver, {stores: {builds: options.buildStore,- ...(buildCatalog === undefined ? {} : { catalog: buildCatalog }),operations: options.operationStore,- dispatch: options.dispatchStore,+ executions: options.commandExecutionStore,+ execution: options.executionStore,},resourceStore: options.resourceStore,...(options.resourceStoreForBuild === undefined ? {} : { resourceStoreForBuild: options.resourceStoreForBuild }),- ...(options.clearBuildResources === undefined ? {} : { clearBuildResources: options.clearBuildResources }),- openBuildResultRepository: async (location) => {- assert(openBuildResultRepository !== undefined, "this Runtime cannot open Build Result Repositories");- return await openBuildResultRepository(location);- },+ openBuildResultRepository,+ ...(options.assertEnvironment === undefined ? {} : { assertEnvironment: options.assertEnvironment }),installComponentPackages,+ resultWriter,});const credentialControl = createLocalCredentialControl({credentialStore: options.credentialStore,endpoints: options.endpoints ?? [],});- const archive = createLocalRuntimeArchiveControl({+ const control = createLocalRuntimeControl({buildStore: options.buildStore,- ...(buildCatalog === undefined ? {} : { buildCatalog }),+ buildCatalog,operationStore: options.operationStore,- dispatchStore: options.dispatchStore,- });- const resources = createLocalRuntimeResourceAccess({- resourceStore: options.resourceStore,+ executionStore: options.executionStore,+ submissionStore: options.submissionStore,});const stageAttachments = async (request: LocalBuildRequest): Promise<void> => {const resourceStore = options.resourceStoreForBuild?.(request.id) ?? options.resourceStore;- for (const item of request.attachments ?? []) {+ const required = requiredInitialResources(request);+ for (const item of (request.attachments ?? []).filter((attachment) =>+ required.has(attachment.artifact.resource))) {if (await resourceStore.has(item.artifact.resource)) continue;const stream = await item.open();if (isStreamingResourceStore(resourceStore)) {@@ -147,60 +202,94 @@ export async function createLocalRuntime(}}};- const presentation = async (build: string, previousState?: LocalBuildSubmission["state"]): Promise<LocalBuildSubmission> => {- const [snapshot, dispatch] = await Promise.all([+ const presentation = async (+ build: string,+ resultLocation: LocalBuildRequest["result"]["repository"],+ previousState?: LocalBuildSubmission["state"],+ ): Promise<LocalBuildSubmission> => {+ const [snapshot, execution] = await Promise.all([options.buildStore.read(build),- options.dispatchStore.read(build),+ options.executionStore.read(build),]);- assert(dispatch !== undefined, `Build ${build} has no Runtime dispatch`);const state = snapshot?.state ?? previousState;assert(state !== undefined, `Build ${build} has no execution state`);- const status: LocalBuildSubmission["status"] = dispatch.phase === "terminal"- ? dispatch.terminal!- : dispatch.phase;- return { id: build, state, status, dispatch };+ if (execution !== undefined) {+ const view = await control.inspect(build);+ assert(view !== undefined, `Build ${build} has no active Runtime view`);+ return { id: build, state, view };+ }+ const opened = await openBuildResultRepository(resultLocation);+ try {+ const result = await opened.repository.read(build);+ assert(result?.outcome !== undefined, `Build ${build} has neither active execution nor a finished Result`);+ return {+ id: build,+ state,+ completion: {+ build,+ outcome: result.outcome,+ ...(result.failure === undefined ? {} : { reason: result.failure }),+ },+ };+ } finally {+ await opened.close?.();+ }};const submit = async (request: LocalBuildRequest): Promise<LocalBuildSubmission> => {- assert(request.id.trim().length > 0 && !request.id.includes("/") && !request.id.includes("\\"),- "Build id must be one directory-safe name");- if (request.catalog !== undefined) {- assert(buildCatalog !== undefined, "Build supplied Host catalog metadata but no BuildCatalog was selected");- }- await stageAttachments(request);- await options.buildStore.create(request.id, request.definition);+ assertOrderedBuildId(request.id);const resultRequest = request.result;- if (resultRequest !== undefined) {- assert(openBuildResultRepository !== undefined, "this Runtime cannot open Build Result Repositories");+ const executionRequest = {+ build: request.id,+ componentPackages: [...new Set(request.componentPackages ?? [])].sort(),+ result: resultRequest.repository,+ } as const;+ let prepared = false;+ try {+ await options.submissionStore.prepare(executionRequest);+ prepared = true;+ await stageAttachments(request);const opened = await openBuildResultRepository(resultRequest.repository);try {- assert(request.catalog !== undefined, "Build Result requires Author catalog names");- const aliases = request.catalog.aliases.flatMap((alias) => alias.ref.kind === "logical-output"- ? [{ name: alias.name, output: alias.ref.id }]- : []);- const names = new Map(aliases.map((alias) => [alias.output, alias.name]));+ const publishedOutputs = request.catalog.publishedOutputs.map((published) => ({+ name: published.name,+ output: published.ref.id,+ }));+ const names = new Map<string, string>();+ for (const published of publishedOutputs) {+ assert(!names.has(published.output),+ `Logical Output ${published.output} has more than one public name`);+ names.set(published.output, published.name);+ }+ const targets = request.definition.targets.map((target) => {+ const name = names.get(target.output);+ assert(name !== undefined, `Target ${target.output} is not a published Author Output`);+ return name;+ });await opened.repository.create({id: request.id,- ...(resultRequest.name === undefined ? {} : { name: resultRequest.name }),- source: request.catalog.source,- ...(request.catalog.run === undefined ? {} : { run: request.catalog.run }),- targets: request.definition.request.targets.map((target) => names.get(target.output) ?? target.output),- aliases,- ...(resultRequest.reuses === undefined ? {} : { reuses: resultRequest.reuses }),+ ...(resultRequest.title === undefined ? {} : { title: resultRequest.title }),+ source: { path: projectPath(resultRequest.repository.root, request.catalog.source.path) },+ ...(request.catalog.run === undefined ? {} : {+ run: { path: projectPath(resultRequest.repository.root, request.catalog.run.path) },+ }),+ targets,+ publishedOutputs,+ ...(resultRequest.forwards === undefined ? {} : { forwards: resultRequest.forwards }),});} finally {await opened.close?.();}+ await options.submissionStore.commit({+ ...executionRequest,+ definition: request.definition,+ catalog: request.catalog,+ });+ return await presentation(request.id, resultRequest.repository);+ } catch (error) {+ if (prepared) await resultWriter.discardSubmission(request.id).catch(() => undefined);+ throw error;}- await options.dispatchStore.create({- build: request.id,- componentPackages: [...new Set(request.componentPackages ?? [])].sort(),- ...(resultRequest === undefined ? {} : { result: resultRequest.repository }),- });- if (request.catalog !== undefined) {- await buildCatalog!.record(request.id, request.catalog);- }- return await presentation(request.id);};const runBuild = async (@@ -213,17 +302,17 @@ export async function createLocalRuntime(const maxWaitMs = follow.maxWaitMs === undefined? undefined: nonNegativeInteger(follow.maxWaitMs, "maxWaitMs");- while (follow.follow === true && !["complete", "failed", "cancelled"].includes(result.status)) {+ while (follow.follow === true && "view" in result && result.view.issue === undefined) {if (maxWaitMs !== undefined && Date.now() - startedAt + pollIntervalMs > maxWaitMs) return result;await wait(pollIntervalMs, follow.signal);- result = await presentation(request.id, result.state);+ result = await presentation(request.id, request.result.repository, result.state);}return result;};return {- ...archive,- ...resources,+ ...control,...credentialControl,+ ...resultWriter,build: runBuild,async workOnce() {return await worker.runOnce();diff --git a/packages/runtime-local/src/types.ts b/packages/runtime-local/src/types.tsindex 070e1693..0d52cbb6 100644--- a/packages/runtime-local/src/types.ts+++ b/packages/runtime-local/src/types.ts@@ -4,33 +4,40 @@ import type { LoadedComponentPackage } from "@hypit/package-loader-node";import type { BuildResultRepositoryLocation, BuildResultRepositoryOpened } from "@hypit/build-result-kit";import type {ResourceStore,+ BuildCompletion,BuildCatalog,BuildStore,- BuildDispatchStore,- BuildDispatchSnapshot,+ BuildExecutionStore,+ BuildExecutionSnapshot,CredentialStore,OperationStore,} from "@hypit/runtime";import type {- RuntimeHostArchive,- RuntimeHostResourceAccess,+ RuntimeHostControl,RuntimeHostBuildSubmission,RuntimeHostCredentialControl,RuntimeHostExecution,+ RuntimeHostResultControl,} from "@hypit/runtime-host-node";export type CreateLocalRuntimeOptions = {readonly buildStore: BuildStore;/** Host presentation metadata only; never part of Core state. */- readonly buildCatalog?: BuildCatalog;+ readonly buildCatalog: BuildCatalog;readonly operationStore: OperationStore;- readonly dispatchStore: import("@hypit/runtime").BuildDispatchStore;+ /** Durable receipt boundary: one immediate Command is never invoked twice for one Build. */+ readonly commandExecutionStore: import("@hypit/runtime").CommandExecutionStore;+ readonly assertEnvironment?: () => Awaitable<void>;+ readonly executionStore: import("@hypit/runtime").BuildExecutionStore;+ readonly removeActiveBuild: (build: string) => Awaitable<BuildCompletion>;+ /** Atomic submission boundary: external preparation is never a claimable partial Build. */+ readonly submissionStore: import("@hypit/runtime").PendingBuildStore;readonly resourceStore: ResourceStore;/** Optional Build-local transient byte area used by Provider execution and Result writing. */readonly resourceStoreForBuild?: (build: string) => ResourceStore;- /** Called only after a terminal Build Result has accepted every public Output completed so far. */+ /** Called only after a finished Build Result has accepted every public Output completed so far. */readonly clearBuildResources?: (build: string) => Awaitable<void>;- readonly openBuildResultRepository?: (location: BuildResultRepositoryLocation) => Awaitable<BuildResultRepositoryOpened>;+ readonly openBuildResultRepository: (location: BuildResultRepositoryLocation) => Awaitable<BuildResultRepositoryOpened>;readonly credentialStore: CredentialStore;readonly components?: readonly ComponentPackage[];/** Load the complete physical package closure named by a claimed Build. */@@ -39,18 +46,27 @@ export type CreateLocalRuntimeOptions = {readonly close?: () => Awaitable<void>;};-export type CreateLocalRuntimeArchiveControlOptions = {+export type CreateLocalRuntimeControlOptions = {readonly buildStore: BuildStore;readonly buildCatalog?: BuildCatalog;readonly operationStore: OperationStore;- readonly dispatchStore: BuildDispatchStore;+ readonly executionStore: BuildExecutionStore;+ readonly submissionStore: import("@hypit/runtime").PendingBuildStore;/** Optional owner supplied by the Runtime assembly. */readonly close?: () => Awaitable<void>;};-export type CreateLocalRuntimeResourceAccessOptions = {+export type CreateLocalResultWriterOptions = {+ readonly buildStore: BuildStore;+ readonly operationStore: OperationStore;+ readonly commandExecutionStore: import("@hypit/runtime").CommandExecutionStore;+ readonly executionStore: BuildExecutionStore;+ readonly removeActiveBuild: (build: string) => Awaitable<BuildCompletion>;+ readonly submissionStore: import("@hypit/runtime").PendingBuildStore;readonly resourceStore: ResourceStore;- /** Optional owner supplied by the Runtime assembly. */+ readonly resourceStoreForBuild?: (build: string) => ResourceStore;+ readonly clearBuildResources?: (build: string) => Awaitable<void>;+ readonly openBuildResultRepository: (location: BuildResultRepositoryLocation) => Awaitable<BuildResultRepositoryOpened>;readonly close?: () => Awaitable<void>;};@@ -65,14 +81,18 @@ export type LocalBuildOptions = Parameters<RuntimeHostExecution["build"]>[1];export type LocalBuildSubmission = RuntimeHostBuildSubmission;export type LocalRuntime = RuntimeHostExecution & {- workOnce(): Promise<BuildDispatchSnapshot | undefined>;+ workOnce(): Promise<BuildExecutionSnapshot | BuildCompletion | undefined>;};-/** Durable execution-state archive that never opens the selected ResourceStore. */-export type LocalRuntimeArchiveControl = RuntimeHostArchive;+/** Active execution control that never opens the selected ResourceStore. */+export type LocalRuntimeControl = RuntimeHostControl;-/** Explicit Artifact byte access that never opens Build, Operation or Dispatch state. */-export type LocalRuntimeResourceAccess = RuntimeHostResourceAccess;+export type LocalResultWriter = RuntimeHostResultControl & {+ /** Incrementally accept public Outputs already completed during execution. */+ sync(execution: BuildExecutionSnapshot, state: import("@hypit/protocol").BuildState): Promise<void>;+ /** Persist the outcome just frozen by the execution Worker, then remove active Runtime state. */+ completeResult(execution: BuildExecutionSnapshot): Promise<BuildExecutionSnapshot | BuildCompletion>;+};/** Credential control for one or more exact Endpoint declarations; no execution state is opened. */export type LocalCredentialControl = RuntimeHostCredentialControl;diff --git a/packages/runtime-local/src/worker-process.ts b/packages/runtime-local/src/worker-process.tsindex c6caab68..6966831a 100644--- a/packages/runtime-local/src/worker-process.ts+++ b/packages/runtime-local/src/worker-process.ts@@ -1,7 +1,11 @@import { spawn } from "node:child_process";+import { randomUUID } from "node:crypto";import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";import { dirname, join, resolve } from "node:path";+import { SqliteRuntimeState } from "@hypit/store-sqlite";+import { canonicalStringify } from "@hypit/protocol";+import { processAlive, stopProcessTree } from "./process-control.js";export type RuntimeWorkerLaunch = {@@ -12,6 +16,7 @@ export type RuntimeWorkerLaunch = {export type RuntimeProcessState = {readonly state: "running" | "stopped";+ readonly configuration?: "current" | "changed";readonly profile: string;readonly pid?: number;readonly startedAt?: number;@@ -20,6 +25,13 @@ export type RuntimeProcessState = {type ProcessRecord = {readonly profile: string;+ readonly profileConfig: string;+ readonly owner: string;+ readonly pid: number;+ readonly startedAt: number;+};++type LaunchRecord = {readonly pid: number;readonly startedAt: number;};@@ -37,6 +49,7 @@ function paths(dataRoot: string) {root,pid: join(root, "worker.json"),ready: join(root, "ready"),+ launch: join(root, "launch.lock"),log: join(root, "worker.log"),};}@@ -69,6 +82,8 @@ async function record(profile: string, dataRoot: string): Promise<ProcessRecordtry {const value = JSON.parse(await readFile(path, "utf8")) as ProcessRecord;if (value.profile !== resolve(profile)+ || typeof value.profileConfig !== "string" || value.profileConfig.length === 0+ || typeof value.owner !== "string" || value.owner.length === 0|| !Number.isSafeInteger(value.pid) || value.pid < 1|| !Number.isSafeInteger(value.startedAt) || value.startedAt < 0) {throw new Error(`Runtime Worker record is invalid: ${path}`);@@ -80,17 +95,57 @@ async function record(profile: string, dataRoot: string): Promise<ProcessRecord}}+async function profileConfig(profile: string): Promise<string> {+ return canonicalStringify(JSON.parse(await readFile(resolve(profile), "utf8")));+}++async function activeLease(dataRoot: string) {+ const state = new SqliteRuntimeState(join(resolve(dataRoot), "runtime.sqlite"), { readOnly: true });+ try {+ return await state.workerLease.read();+ } catch (error) {+ if (error instanceof Error && error.message.includes("no such table: hypit_worker_lease")) return undefined;+ throw error;+ } finally {+ state.close();+ }+}++async function releaseLease(dataRoot: string, owner: string, pid: number): Promise<void> {+ const state = new SqliteRuntimeState(join(resolve(dataRoot), "runtime.sqlite"));+ try {+ await state.workerLease.release(owner, pid);+ } finally {+ state.close();+ }+}++async function readyOwner(path: string): Promise<string | undefined> {+ try {+ const value = (await readFile(path, "utf8")).trim();+ return value.length === 0 ? undefined : value;+ } catch (error) {+ if (nodeError(error, "ENOENT")) return undefined;+ throw error;+ }+}+export async function runtimeProcessStatus(profile: string,dataRoot: string,): Promise<RuntimeProcessState> {const location = paths(dataRoot);const current = await record(profile, dataRoot);- if (current === undefined || !processAlive(current.pid)) {+ const lease = current === undefined ? undefined : await activeLease(dataRoot);+ const ready = current === undefined ? undefined : await readyOwner(location.ready);+ if (current === undefined || !processAlive(current.pid)+ || lease?.owner !== current.owner || lease.pid !== current.pid || lease.expiresAt <= Date.now()+ || ready !== current.owner) {return { state: "stopped", profile: resolve(profile), logPath: location.log };}return {state: "running",+ configuration: current.profileConfig === await profileConfig(profile) ? "current" : "changed",profile: current.profile,pid: current.pid,startedAt: current.startedAt,@@ -98,6 +153,37 @@ export async function runtimeProcessStatus(};}+async function acquireLaunch(path: string, timeoutMs: number): Promise<() => Promise<void>> {+ const deadline = Date.now() + timeoutMs;+ while (true) {+ try {+ const file = await open(path, "wx");+ await file.writeFile(JSON.stringify({ pid: process.pid, startedAt: Date.now() } satisfies LaunchRecord));+ await file.close();+ return async () => await rm(path, { force: true });+ } catch (error) {+ if (!nodeError(error, "EEXIST")) throw error;+ let owner: LaunchRecord | undefined;+ try {+ owner = JSON.parse(await readFile(path, "utf8")) as LaunchRecord;+ } catch (readError) {+ if (readError instanceof SyntaxError) {+ if (Date.now() > deadline) throw new Error("Runtime Worker launch lock remained incomplete");+ await new Promise((resolveWait) => setTimeout(resolveWait, 20));+ continue;+ }+ if (!nodeError(readError, "ENOENT")) throw readError;+ }+ if (owner !== undefined && Number.isSafeInteger(owner.pid) && owner.pid > 0 && processAlive(owner.pid)) {+ if (Date.now() > deadline) throw new Error("another Runtime Worker launch did not finish in time");+ await new Promise((resolveWait) => setTimeout(resolveWait, 20));+ continue;+ }+ await rm(path, { force: true });+ }+ }+}+async function waitForReady(profile: string,dataRoot: string,@@ -106,8 +192,8 @@ async function waitForReady(const location = paths(dataRoot);const deadline = Date.now() + timeoutMs;while (Date.now() <= deadline) {- const state = await runtimeProcessStatus(profile, dataRoot);- if (state.state === "stopped") {+ const current = await record(profile, dataRoot);+ if (current === undefined || !processAlive(current.pid)) {let log = "";try {log = await readFile(location.log, "utf8");@@ -116,7 +202,10 @@ async function waitForReady(}throw new Error(`Runtime Worker exited before becoming ready${log.length === 0 ? "" : `: ${log.trim().split("\n").at(-1)}`}`);}- if (await exists(location.ready)) return state;+ if (await exists(location.ready)) {+ const state = await runtimeProcessStatus(profile, dataRoot);+ if (state.state === "running") return state;+ }await new Promise((resolveWait) => setTimeout(resolveWait, 10));}throw new Error(`Runtime Worker did not become ready within ${timeoutMs}ms; log: ${location.log}`);@@ -129,45 +218,100 @@ export async function ensureRuntimeProcess(timeoutMs = 10_000,): Promise<RuntimeProcessState> {const current = await runtimeProcessStatus(profile, dataRoot);- if (current.state === "running") return current;+ if (current.state === "running") {+ if (current.configuration === "changed") {+ throw new Error("Runtime Profile changed while its Worker is running; stop and start the Worker to activate it");+ }+ return current;+ }const absolute = resolve(profile);const location = paths(dataRoot);await mkdir(location.root, { recursive: true });- await rm(location.ready, { force: true });- await rotateLog(location.log);- const log = await open(location.log, "a");- const child = spawn(launch.command, [- ...launch.args,- "_worker",- absolute,- "--ready-file",- location.ready,- ...(launch.workerArgs ?? []),- ], {- cwd: process.cwd(),- // See the managed program start in `programs.ts`: on Windows, detaching costs the console and- // every console descendant then gets a window of its own.- detached: process.platform !== "win32",- windowsHide: true,- stdio: ["ignore", log.fd, log.fd],- env: process.env,- });- if (child.pid === undefined) throw new Error("Runtime Worker process has no pid");- const startedAt = Date.now();- await writeFile(location.pid, JSON.stringify({- profile: absolute,- pid: child.pid,- startedAt,- } satisfies ProcessRecord), "utf8");- child.unref();- await log.close();- return await waitForReady(absolute, dataRoot, timeoutMs);+ const releaseLaunch = await acquireLaunch(location.launch, timeoutMs);+ try {+ const raced = await runtimeProcessStatus(profile, dataRoot);+ if (raced.state === "running") {+ if (raced.configuration === "changed") {+ throw new Error("Runtime Profile changed while its Worker is running; stop and start the Worker to activate it");+ }+ return raced;+ }+ const stale = await record(profile, dataRoot).catch(() => undefined);+ if (stale !== undefined && !processAlive(stale.pid)) {+ await releaseLease(dataRoot, stale.owner, stale.pid).catch(() => undefined);+ await rm(location.pid, { force: true });+ await rm(location.ready, { force: true });+ }+ const owner = `worker_${randomUUID()}`;+ const activeProfileConfig = await profileConfig(absolute);+ await rm(location.ready, { force: true });+ await rotateLog(location.log);+ const log = await open(location.log, "a");+ let child;+ try {+ child = spawn(launch.command, [+ ...launch.args,+ "_worker",+ absolute,+ "--ready-file",+ location.ready,+ "--worker-owner",+ owner,+ ...(launch.workerArgs ?? []),+ ], {+ cwd: process.cwd(),+ // See the managed program start in `programs.ts`: on Windows, detaching costs the console and+ // every console descendant then gets a window of its own.+ detached: process.platform !== "win32",+ windowsHide: true,+ stdio: ["ignore", log.fd, log.fd],+ env: process.env,+ });+ if (child.pid === undefined) throw new Error("Runtime Worker process has no pid");+ const startedAt = Date.now();+ await writeFile(location.pid, JSON.stringify({+ profile: absolute,+ profileConfig: activeProfileConfig,+ owner,+ pid: child.pid,+ startedAt,+ } satisfies ProcessRecord), "utf8");+ child.unref();+ try {+ return await waitForReady(absolute, dataRoot, timeoutMs);+ } catch (error) {+ await stopProcessTree(child.pid, true).catch(() => "gone");+ await releaseLease(dataRoot, owner, child.pid).catch(() => undefined);+ const saved = await record(profile, dataRoot).catch(() => undefined);+ if (saved?.owner === owner) {+ await rm(location.pid, { force: true });+ await rm(location.ready, { force: true });+ }+ throw error;+ }+ } finally {+ await log.close();+ }+ } finally {+ await releaseLaunch();+ }+}++export async function runtimeProcessOwnsCurrentProfile(+ profile: string,+ dataRoot: string,+ owner: string,+): Promise<boolean> {+ const current = await record(profile, dataRoot);+ return current?.owner === owner && current.profileConfig === await profileConfig(profile);}async function stopRuntimeProcessUnlocked(profile: string, dataRoot: string, timeoutMs: number): Promise<RuntimeProcessState> {const current = await record(profile, dataRoot);const location = paths(dataRoot);- if (current === undefined || !processAlive(current.pid)) {+ const lease = current === undefined ? undefined : await activeLease(dataRoot);+ if (current === undefined || !processAlive(current.pid)+ || lease?.owner !== current.owner || lease.pid !== current.pid) {await rm(location.pid, { force: true });await rm(location.ready, { force: true });return { state: "stopped", profile: resolve(profile), logPath: location.log };@@ -195,6 +339,7 @@ async function stopRuntimeProcessUnlocked(profile: string, dataRoot: string, tim}await rm(location.pid, { force: true });await rm(location.ready, { force: true });+ await releaseLease(dataRoot, current.owner, current.pid).catch(() => undefined);return { state: "stopped", profile: resolve(profile), logPath: location.log };}@@ -220,7 +365,7 @@ export async function runtimeProcessLogs(dataRoot: string): Promise<{ readonly p}}-export async function markRuntimeProcessReady(path: string): Promise<void> {+export async function markRuntimeProcessReady(path: string, owner: string): Promise<void> {await mkdir(dirname(resolve(path)), { recursive: true });- await writeFile(resolve(path), "", "utf8");+ await writeFile(resolve(path), `${owner}\n`, "utf8");}diff --git a/packages/runtime-local/src/worker.ts b/packages/runtime-local/src/worker.tsindex 26f89b8f..daadaa5a 100644--- a/packages/runtime-local/src/worker.ts+++ b/packages/runtime-local/src/worker.ts@@ -1,8 +1,9 @@+import { randomUUID } from "node:crypto";import type { BuildState } from "@hypit/protocol";-import type { BuildResultWriter } from "@hypit/build-result";import type {ResourceStore,- BuildDispatchSnapshot,+ BuildCompletion,+ BuildExecutionSnapshot,RuntimeCommandExecutor,RuntimeExecutionResult,RuntimePreparation,@@ -10,22 +11,25 @@ import type {ScheduledBuildResult,RuntimeWorkerRunOptions,} from "@hypit/runtime";-import { isStreamingResourceStore, LocalBuildScheduler } from "@hypit/runtime";+import { LocalBuildScheduler } from "@hypit/runtime";type LocalWorkerOptions = {readonly stores: {readonly builds: import("@hypit/runtime").BuildStore;- readonly catalog?: import("@hypit/runtime").BuildCatalog;readonly operations: import("@hypit/runtime").OperationStore;- readonly dispatch: import("@hypit/runtime").BuildDispatchStore;+ readonly executions: import("@hypit/runtime").CommandExecutionStore;+ readonly execution: import("@hypit/runtime").BuildExecutionStore;};readonly resourceStore: ResourceStore;readonly resourceStoreForBuild?: (build: string) => ResourceStore;- readonly clearBuildResources?: (build: string) => Promise<void> | void;readonly openBuildResultRepository: NonNullable<import("./types.js").CreateLocalRuntimeOptions["openBuildResultRepository"]>;+ readonly assertEnvironment?: () => Promise<void> | void;readonly installComponentPackages: (specifiers: readonly string[]) => Promise<void>;+ readonly resultWriter: import("./types.js").LocalResultWriter;};+type WorkerTurnResult = BuildExecutionSnapshot | BuildCompletion;+function assert(condition: unknown, message: string): asserts condition {if (!condition) throw new Error(message);}@@ -56,10 +60,12 @@ async function pause(ms: number, signal?: AbortSignal): Promise<void> {class CapacityExecutor implements RuntimeCommandExecutor {readonly #delegate: RuntimeCommandExecutor;readonly #options: LocalWorkerOptions;+ readonly #owner: string;- constructor(delegate: RuntimeCommandExecutor, options: LocalWorkerOptions) {+ constructor(delegate: RuntimeCommandExecutor, options: LocalWorkerOptions, owner: string) {this.#delegate = delegate;this.#options = options;+ this.#owner = owner;}prepare(state: BuildState): RuntimePreparation {@@ -67,9 +73,51 @@ class CapacityExecutor implements RuntimeCommandExecutor {}async #assertRunning(build: string): Promise<void> {- const dispatch = await this.#options.stores.dispatch.read(build);- assert(dispatch?.phase === "running", `Build ${build} is not owned by the Worker`);- assert(dispatch.cancellation === undefined, `Build ${build} is being cancelled`);+ const execution = await this.#options.stores.execution.read(build);+ assert(execution?.turn?.owner === this.#owner && execution.decision === undefined,+ `Build ${build} is not owned by this Worker turn`);+ assert(execution.cancellation === undefined, `Build ${build} is being cancelled`);+ }++ async #executeOnce(+ state: BuildState,+ descriptor: RuntimeRunnableCommand,+ context: { readonly build: string },+ ): Promise<RuntimeExecutionResult> {+ const store = this.#options.stores.executions;+ if (descriptor.capacityMode === "asynchronous") {+ return await this.#delegate.executeCommand(state, descriptor, context);+ }+ const begun = await store.begin(context.build, descriptor.command.id);+ if (!begun.created) {+ if (begun.receipt.status === "completed" && begun.receipt.event !== undefined) {+ return { status: "completed", event: begun.receipt.event };+ }+ const event = {+ kind: "command-failed",+ command: descriptor.command.id,+ code: "EXECUTION_UNKNOWN",+ message: `Command ${descriptor.command.id} stopped before its result was stored; the same Build will not run it again`,+ } as const;+ await store.complete(context.build, descriptor.command.id, event);+ return { status: "completed", event };+ }+ try {+ const result = await this.#delegate.executeCommand(state, descriptor, context);+ assert(result.status === "completed",+ `Immediate Command ${descriptor.command.id} returned ${result.status}`);+ await store.complete(context.build, descriptor.command.id, result.event);+ return result;+ } catch (error) {+ const event = {+ kind: "command-failed",+ command: descriptor.command.id,+ code: "EXECUTION_UNKNOWN",+ message: `Command ${descriptor.command.id} ended without a stored result: ${error instanceof Error ? error.message : String(error)}`,+ } as const;+ await store.complete(context.build, descriptor.command.id, event);+ return { status: "completed", event };+ }}async executeCommand(@@ -80,22 +128,22 @@ class CapacityExecutor implements RuntimeCommandExecutor {const resources = descriptor.resources;await this.#assertRunning(context.build);if (resources.length === 0) {- return await this.#delegate.executeCommand(state, descriptor, context);+ return await this.#executeOnce(state, descriptor, context);}// An asynchronous command keeps its capacity reservation while it is// being polled. Do not count that same build/command against itself on a- // later dispatch turn; the reservation is intentionally retained until+ // later execution turn; the reservation is intentionally retained until// the Operation reaches a terminal state.- const reservation = (await this.#options.stores.dispatch.listCapacity())+ const reservation = (await this.#options.stores.execution.listCapacity()).find((item) => item.build === context.build && item.command === descriptor.command.id);if (reservation !== undefined) {- const result = await this.#delegate.executeCommand(state, descriptor, context);+ const result = await this.#executeOnce(state, descriptor, context);if (result.status !== "pending") {- await this.#options.stores.dispatch.releaseCapacity(context.build, descriptor.command.id);+ await this.#options.stores.execution.releaseCapacity(context.build, descriptor.command.id);}return result;}- const acquired = await this.#options.stores.dispatch.acquireCapacity({+ const acquired = await this.#options.stores.execution.acquireCapacity({build: context.build,command: descriptor.command.id,resources,@@ -110,16 +158,16 @@ class CapacityExecutor implements RuntimeCommandExecutor {};}try {- const result = await this.#delegate.executeCommand(state, descriptor, context);+ const result = await this.#executeOnce(state, descriptor, context);if (result.status !== "pending") {- await this.#options.stores.dispatch.releaseCapacity(+ await this.#options.stores.execution.releaseCapacity(acquired.reservation.build,acquired.reservation.command,);}return result;} catch (error) {- await this.#options.stores.dispatch.releaseCapacity(+ await this.#options.stores.execution.releaseCapacity(acquired.reservation.build,acquired.reservation.command,).catch(() => undefined);@@ -140,85 +188,20 @@ class DurableLocalWorker {readonly #executor: RuntimeCommandExecutor;readonly #options: LocalWorkerOptions;readonly #executorWithCapacity: CapacityExecutor;+ readonly #owner = randomUUID();constructor(executor: RuntimeCommandExecutor, options: LocalWorkerOptions) {this.#executor = executor;this.#options = options;- this.#executorWithCapacity = new CapacityExecutor(executor, options);- }-- async #openResult(dispatch: BuildDispatchSnapshot): Promise<{- readonly writer: BuildResultWriter;- close(): Promise<void>;- } | undefined> {- if (dispatch.result === undefined) return undefined;- const opened = await this.#options.openBuildResultRepository(dispatch.result);- try {- const writer = await opened.repository.openWriter(dispatch.build);- assert(writer !== undefined, `Build ${dispatch.build} has no Build Result`);- return {- writer,- close: async () => {- await opened.close?.();- },- };- } catch (error) {- await opened.close?.();- throw error;- }- }-- async #syncResult(dispatch: BuildDispatchSnapshot, state: BuildState): Promise<void> {- const result = await this.#openResult(dispatch);- if (result === undefined) return;- try {- const resourceStore = this.#options.resourceStoreForBuild?.(dispatch.build) ?? this.#options.resourceStore;- await result.writer.sync({- state,- resources: {- open: async (artifact) => {- if (isStreamingResourceStore(resourceStore)) {- return await resourceStore.open(artifact.resource);- }- const bytes = await resourceStore.get(artifact.resource);- return bytes === undefined ? undefined : (async function* () { yield bytes; })();- },- },- });- } finally {- await result.close();- }+ this.#executorWithCapacity = new CapacityExecutor(executor, options, this.#owner);}- async #finishResult(- dispatch: BuildDispatchSnapshot,- status: "complete" | "failed" | "cancelled",- failure?: string,- ): Promise<boolean> {- const result = await this.#openResult(dispatch);- if (result === undefined) return false;- try {- await result.writer.finish({ status, ...(failure === undefined ? {} : { failure }) });- return true;- } finally {- await result.close();- }- }-- async #retireExecution(build: string): Promise<void> {- await Promise.allSettled([- this.#options.clearBuildResources?.(build),- this.#options.stores.operations.removeBuild?.(build),- this.#options.stores.builds.remove?.(build),- this.#options.stores.catalog?.remove?.(build),- ].filter((task): task is Promise<void> => task !== undefined));- }-- async #cancel(dispatch: BuildDispatchSnapshot): Promise<BuildDispatchSnapshot> {- const snapshot = await this.#options.stores.builds.read(dispatch.build);- assert(snapshot !== undefined, `Build ${dispatch.build} has no durable state`);- const active = (await this.#options.stores.operations.list({ build: dispatch.build }))- .filter((item) => item.status === "pending");+ async #cancel(execution: BuildExecutionSnapshot): Promise<WorkerTurnResult> {+ const snapshot = await this.#options.stores.builds.read(execution.build);+ assert(snapshot !== undefined, `Build ${execution.build} has no durable execution state`);+ const operations = await this.#options.stores.operations.list({ build: execution.build });+ const active = operations+ .filter((item) => item.status === "pending" && item.handle !== undefined);for (const operation of active) {if (this.#executor.cancelOperation !== undefined) {await this.#executor.cancelOperation(snapshot.state, operation).catch(() => undefined);@@ -226,136 +209,142 @@ class DurableLocalWorker {await this.#options.stores.operations.update(operation.id, { status: "cancelled" });}}- await this.#options.stores.dispatch.releaseBuildCapacity(dispatch.build);- const persisted = await this.#finishResult(dispatch, "cancelled", dispatch.cancellation?.reason ?? "cancelled by Runtime");- const finished = await this.#options.stores.dispatch.finish(- dispatch.build,+ await this.#options.stores.execution.releaseBuildCapacity(execution.build);+ const decided = await this.#options.stores.execution.decide(+ execution.build,+ this.#owner,"cancelled",- dispatch.cancellation?.reason ?? "cancelled by Runtime",+ execution.cancellation?.reason ?? "cancelled by Runtime",);- if (persisted) await this.#retireExecution(dispatch.build);- return finished;+ return await this.#options.resultWriter.completeResult(decided);}- async #finish(dispatch: BuildDispatchSnapshot, result: ScheduledBuildResult): Promise<BuildDispatchSnapshot> {- const current = await this.#options.stores.dispatch.read(dispatch.build);- assert(current?.phase === "running", `Dispatch ${dispatch.build} is no longer running`);+ async #finish(execution: BuildExecutionSnapshot, result: ScheduledBuildResult): Promise<WorkerTurnResult> {+ const current = await this.#options.stores.execution.read(execution.build);+ assert(current?.turn?.owner === this.#owner && current.decision === undefined,+ `Execution ${execution.build} is no longer owned by this Worker turn`);if (current.cancellation !== undefined) return await this.#cancel(current);if (result.status === "complete") {- await this.#options.stores.dispatch.releaseBuildCapacity(dispatch.build);- const persisted = await this.#finishResult(dispatch, "complete");- const finished = await this.#options.stores.dispatch.finish(dispatch.build, "complete");- if (persisted) await this.#retireExecution(dispatch.build);- return finished;+ await this.#options.stores.execution.releaseBuildCapacity(execution.build);+ const decided = await this.#options.stores.execution.decide(execution.build, this.#owner, "complete");+ return await this.#options.resultWriter.completeResult(decided);}if (result.status === "failed" || result.outcomes.some((item) => item.status === "error")) {const reason = result.outcomes.find((item) => item.status === "error")?.message?? result.state.diagnostics.at(-1)?.message?? "Core Build failed";- await this.#options.stores.dispatch.releaseBuildCapacity(dispatch.build);- const persisted = await this.#finishResult(dispatch, "failed", reason);- const finished = await this.#options.stores.dispatch.finish(dispatch.build, "failed", reason);- if (persisted) await this.#retireExecution(dispatch.build);- return finished;+ await this.#options.stores.execution.releaseBuildCapacity(execution.build);+ const decided = await this.#options.stores.execution.decide(execution.build, this.#owner, "failed", reason);+ return await this.#options.resultWriter.completeResult(decided);}const pending = result.outcomes.filter((item) => item.status === "pending");const deferred = result.outcomes.filter((item) => item.status === "deferred");if (pending.length === 0 && deferred.length === 0 && result.blocked.length > 0) {const reason = result.blocked.map((item) => `${item.reason}: ${item.subject}`).join(", ");- await this.#options.stores.dispatch.releaseBuildCapacity(dispatch.build);- const persisted = await this.#finishResult(dispatch, "failed", reason);- const finished = await this.#options.stores.dispatch.finish(dispatch.build, "failed", reason);- if (persisted) await this.#retireExecution(dispatch.build);- return finished;+ await this.#options.stores.execution.releaseBuildCapacity(execution.build);+ const decided = await this.#options.stores.execution.decide(execution.build, this.#owner, "failed", reason);+ return await this.#options.resultWriter.completeResult(decided);}const now = Date.now();const wakeAt = Math.min(...[...pending.map((item) => item.wakeAt ?? now + 1_000),...deferred.map((item) => item.wakeAt ?? now + 1_000),]);- const released = await this.#options.stores.dispatch.release(dispatch.build, {- phase: pending.length > 0 ? "waiting" : "queued",- availableAt: Number.isFinite(wakeAt) ? wakeAt : now,- });+ const released = await this.#options.stores.execution.releaseTurn(+ execution.build,+ this.#owner,+ Number.isFinite(wakeAt) ? wakeAt : now,+ );return released.cancellation === undefined ? released : await this.#cancel(released);}- async #fail(dispatch: BuildDispatchSnapshot, error: unknown): Promise<BuildDispatchSnapshot> {- const current = await this.#options.stores.dispatch.read(dispatch.build);+ async #fail(execution: BuildExecutionSnapshot, error: unknown): Promise<WorkerTurnResult> {+ const current = await this.#options.stores.execution.read(execution.build);if (current?.cancellation !== undefined) return await this.#cancel(current);const reason = error instanceof Error ? error.message : String(error);- await this.#options.stores.dispatch.releaseBuildCapacity(dispatch.build);- await this.#finishResult(dispatch, "failed", reason).catch(() => false);- const finished = await this.#options.stores.dispatch.finish(dispatch.build, "failed", reason);- // An infrastructure failure may be the Result writer itself. Keep execution bytes and facts so- // a local repair can recover already accepted public Outputs instead of deleting their source.- return finished;+ await this.#options.stores.execution.releaseBuildCapacity(execution.build);+ const decided = await this.#options.stores.execution.decide(execution.build, this.#owner, "failed", reason);+ return await this.#options.resultWriter.completeResult(decided);}- async #runClaimed(dispatches: readonly BuildDispatchSnapshot[]): Promise<readonly BuildDispatchSnapshot[]> {- const finished: BuildDispatchSnapshot[] = [];- const runnable: { readonly dispatch: BuildDispatchSnapshot; readonly snapshot: import("@hypit/runtime").BuildSnapshot }[] = [];- for (const dispatch of dispatches) {- if (dispatch.cancellation !== undefined) {- finished.push(await this.#cancel(dispatch));+ async #runClaimed(executions: readonly BuildExecutionSnapshot[]): Promise<readonly WorkerTurnResult[]> {+ const finished: WorkerTurnResult[] = [];+ const runnable: { readonly execution: BuildExecutionSnapshot; readonly snapshot: import("@hypit/runtime").BuildSnapshot }[] = [];+ for (const execution of executions) {+ assert(execution.turn?.owner === this.#owner && execution.decision === undefined,+ `Execution ${execution.build} was not claimed by this Worker turn`);+ if (execution.cancellation !== undefined) {+ finished.push(await this.#cancel(execution));continue;}try {- await this.#options.installComponentPackages(dispatch.componentPackages);- const snapshot = await this.#options.stores.builds.read(dispatch.build);- assert(snapshot !== undefined, `Dispatch ${dispatch.build} has no Build Definition`);- await this.#syncResult(dispatch, snapshot.state);- runnable.push({ dispatch, snapshot });+ await this.#options.installComponentPackages(execution.componentPackages);+ const snapshot = await this.#options.stores.builds.read(execution.build);+ assert(snapshot !== undefined, `Execution ${execution.build} has no Build Definition`);+ runnable.push({ execution, snapshot });} catch (error) {- finished.push(await this.#fail(dispatch, error));+ finished.push(await this.#fail(execution, error));}}if (runnable.length === 0) return finished;const scheduler = new LocalBuildScheduler(this.#executorWithCapacity, {buildStore: this.#options.stores.builds,onStateChange: async (build, state) => {- const item = runnable.find((candidate) => candidate.dispatch.build === build);+ const item = runnable.find((candidate) => candidate.execution.build === build);assert(item !== undefined, `Result update refers to unknown Build ${build}`);- await this.#syncResult(item.dispatch, state);+ await this.#options.resultWriter.sync(item.execution, state).catch(() => undefined);},});try {- const results = await scheduler.run(runnable.map(({ dispatch, snapshot }) => ({- id: dispatch.build,+ const results = await scheduler.run(runnable.map(({ execution, snapshot }) => ({+ id: execution.build,snapshot,})));- const byBuild = new Map(runnable.map((item) => [item.dispatch.build, item]));+ const byBuild = new Map(runnable.map((item) => [item.execution.build, item]));for (const result of results) {const item = byBuild.get(result.id);assert(item !== undefined, `Scheduler returned unknown Build ${result.id}`);- finished.push(await this.#finish(item.dispatch, result));+ finished.push(await this.#finish(item.execution, result));}} catch (error) {- for (const item of runnable) finished.push(await this.#fail(item.dispatch, error));+ for (const item of runnable) finished.push(await this.#fail(item.execution, error));}return finished;}- async runOnce(): Promise<BuildDispatchSnapshot | undefined> {- const dispatch = await this.#options.stores.dispatch.claim(Date.now());- if (dispatch === undefined) return undefined;- const [result] = await this.#runClaimed([dispatch]);+ async runOnce(): Promise<WorkerTurnResult | undefined> {+ await this.#options.assertEnvironment?.();+ const execution = await this.#options.stores.execution.claim(this.#owner, Date.now());+ if (execution === undefined) return undefined;+ const [result] = await this.#runClaimed([execution]);return result;}async run(options: RuntimeWorkerRunOptions): Promise<void> {positive(options.idlePollMs, "Worker idlePollMs");const active = new Set<Promise<void>>();- // A Worker that went away mid-Dispatch left it `running` and holding its lane. This Worker owns- // the Runtime, so nothing else can be executing those: take them back before claiming anything.- await this.#options.stores.dispatch.reclaimAbandoned(Date.now());+ // The Runtime Host admits one Worker process. Any stored turn owner therefore belongs to the+ // previous process; clearing it changes no external fact and performs no Result action.+ await this.#options.assertEnvironment?.();+ await this.#options.stores.execution.reclaimTurns(Date.now());+ await this.#options.stores.execution.reclaimResultWrites();+ for (const execution of await this.#options.stores.execution.list()) {+ if (execution.decision !== undefined && execution.attention === undefined) {+ await this.#options.stores.execution.setAttention(execution.build, {+ step: "result",+ error: "Result writing was interrupted; run `hypit result finish <build-id>`",+ });+ }+ }+ await options.ready?.();try {while (options.signal?.aborted !== true) {+ await this.#options.assertEnvironment?.();while (true) {- const dispatch = await this.#options.stores.dispatch.claim(Date.now());- if (dispatch === undefined) break;+ const execution = await this.#options.stores.execution.claim(this.#owner, Date.now());+ if (execution === undefined) break;let task: Promise<void>;- task = this.#runClaimed([dispatch])+ task = this.#runClaimed([execution]).then(() => undefined).finally(() => active.delete(task));active.add(task);diff --git a/packages/runtime-local/test/config.test.ts b/packages/runtime-local/test/config.test.tsindex da9b4a8b..009ccaf1 100644--- a/packages/runtime-local/test/config.test.ts+++ b/packages/runtime-local/test/config.test.ts@@ -1,5 +1,5 @@import assert from "node:assert/strict";-import { mkdtemp, rm, writeFile } from "node:fs/promises";+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";import { tmpdir } from "node:os";import { join } from "node:path";import test from "node:test";@@ -16,17 +16,17 @@ import {import { FileBuildResultRepository } from "@hypit/build-result";import { SqliteRuntimeState } from "@hypit/store-sqlite";import {- createRuntimeArchiveFromConfig,- createRuntimeResourceAccessFromConfig,+ createRuntimeControlFromConfig,+ createRuntimeFromConfig,+ createRuntimeResultControlFromConfig,+ doctorProjectBuildResultRepository,doctorRuntimeConfig,- openBuildResultRepositoryFromConfig,+ openProjectBuildResultRepository,parseRuntimeConfig,preflightRuntimeConfig,} from "@hypit/runtime-local";-function profile(config: {readonly dataRoot?: string;- readonly results?: Readonly<Record<string, unknown>>;readonly credentials?: Readonly<Record<string, unknown>>;readonly endpoints?: Readonly<Record<string, unknown>>;} = {}) {@@ -36,7 +36,6 @@ function profile(config: {use: "@hypit/runtime-local",config: {dataRoot: config.dataRoot ?? ".hypit/runtimes/local",- ...(config.results === undefined ? {} : { results: config.results }),credentials: config.credentials ?? {},endpoints: config.endpoints ?? {},},@@ -44,38 +43,35 @@ function profile(config: {};}-test("Runtime Profile names the result repository, credentials and Endpoints", () => {+test("Runtime Profile names credentials and Endpoints, not project result storage", () => {const parsed = parseRuntimeConfig(profile({- results: { use: "example.results", config: { bucket: "project" } },credentials: { secrets: { use: "example.credentials" } },endpoints: { generation: { use: "example.provider", pool: "shared" } },}));assert.equal(parsed.dataRoot, ".hypit/runtimes/local");- assert.deepEqual(parsed.results, {- use: "example.results",- instance: "results",- config: { bucket: "project" },- });assert.deepEqual(parsed.credentials, [{ use: "example.credentials", instance: "secrets" }]);assert.deepEqual(parsed.endpoints, [{ use: "example.provider", instance: "generation", pool: "shared" }]);});test("Build Result repositories default to the project path and can be selected explicitly", async () => {const root = await mkdtemp(join(tmpdir(), "hypit-runtime-results-"));- const defaultProfile = join(root, "default.runtime.json");- const selectedProfile = join(root, "selected.runtime.json");- const defaultRoot = join(root, "project", ".hypit", "results");- await writeFile(defaultProfile, JSON.stringify(profile()));+ const defaultProject = join(root, "default-project");+ const selectedProject = join(root, "selected-project");+ await Promise.all([+ mkdir(defaultProject, { recursive: true }),+ mkdir(selectedProject, { recursive: true }),+ ]);await writeFile(- selectedProfile,- JSON.stringify(- profile({- results: { use: "example.results", config: { name: "episode-12" } },- }),- ),+ join(selectedProject, "hypit.results.json"),+ JSON.stringify({+ format: "hypit.build-results@1",+ use: "example.results",+ config: { name: "episode-12" },+ }),);const registry = new BuildResultRepositoryRegistry();let openedContext: unknown;+ let diagnosedContext: unknown;registry.registerFacet(createBuildResultRepositoryHostFacet({use: "example.results",@@ -88,30 +84,42 @@ test("Build Result repositories default to the project path and can be selectedrepository: new FileBuildResultRepository(join(root, "remote-fixture")),};},+ doctor(context) {+ diagnosedContext = context;+ return [];+ },}),);try {- const local = await openBuildResultRepositoryFromConfig(defaultProfile, defaultRoot, {+ const local = await openProjectBuildResultRepository(defaultProject, {packageRoot: process.cwd(),});assert.ok(local.repository instanceof FileBuildResultRepository);- assert.equal(local.location.root, defaultRoot);+ assert.equal(local.location.root, defaultProject);assert.deepEqual(local.location.selection, {use: "@hypit/build-result-fs",- config: { path: "." },+ config: { path: ".hypit/results" },});- const selected = await openBuildResultRepositoryFromConfig(selectedProfile, defaultRoot, {+ const selected = await openProjectBuildResultRepository(selectedProject, {resultRegistry: registry,});assert.deepEqual(openedContext, {- root,+ root: selectedProject,config: { name: "episode-12" },});assert.deepEqual(selected.location, {- root,+ root: selectedProject,selection: { use: "example.results", config: { name: "episode-12" } },});+ const diagnosed = await doctorProjectBuildResultRepository(selectedProject, {+ resultRegistry: registry,+ });+ assert.deepEqual(diagnosed.diagnostics, []);+ assert.deepEqual(diagnosedContext, {+ root: selectedProject,+ config: { name: "episode-12" },+ });} finally {await rm(root, { recursive: true, force: true });}@@ -121,7 +129,7 @@ test("Runtime Profile rejects source ownership fields", () => {assert.throws(() => parseRuntimeConfig({ ...profile(), root: "." }), /does not accept root/u);});-test("archive inspection and working Resource access require no selected ResourceStore", async () => {+test("active Build inspection requires no selected ResourceStore", async () => {const root = await mkdtemp(join(tmpdir(), "hypit-runtime-slice-"));const path = join(root, "hypit.runtime.json");await writeFile(path, JSON.stringify(profile({ dataRoot: "." })));@@ -129,12 +137,26 @@ test("archive inspection and working Resource access require no selected Resourcstate.close();const registry = new RuntimeAdapterRegistry();try {- const archive = await createRuntimeArchiveFromConfig(path, { registry, readOnly: true });- assert.equal((await archive.status("missing")).build, undefined);- await archive.close();- const artifacts = await createRuntimeResourceAccessFromConfig(path, { registry });- assert.equal(await artifacts.readResource("res_missing"), undefined);- await artifacts.close();+ const control = await createRuntimeControlFromConfig(path, { registry, readOnly: true });+ assert.equal(await control.inspect("missing"), undefined);+ await control.close();+ } finally {+ await rm(root, { recursive: true, force: true });+ }+});++test("Result control opens without loading the Runtime Profile's Endpoint adapters", async () => {+ const root = await mkdtemp(join(tmpdir(), "hypit-runtime-result-control-"));+ const path = join(root, "hypit.runtime.json");+ await writeFile(path, JSON.stringify(profile({+ dataRoot: ".",+ endpoints: { unavailable: { use: "package.that.must.not.load" } },+ })));+ try {+ const resultControl = await createRuntimeResultControlFromConfig(path, {+ registry: new RuntimeAdapterRegistry(),+ });+ await resultControl.close();} finally {await rm(root, { recursive: true, force: true });}diff --git a/packages/runtime-local/test/local.test.ts b/packages/runtime-local/test/local.test.tsindex cbdcc5cb..05df30e4 100644--- a/packages/runtime-local/test/local.test.ts+++ b/packages/runtime-local/test/local.test.ts@@ -13,18 +13,19 @@ import test from "node:test";import { FileResourceStore } from "@hypit/resource-store-fs";import { FileBuildResultRepository, readBuildResult } from "@hypit/build-result";+import type { BuildResultRepository } from "@hypit/build-result";import { EnvironmentCredentialStore } from "@hypit/credential-store-env";import { defineEndpointPackage } from "@hypit/endpoint-kit";import type { AsyncEndpoint, EndpointPackage } from "@hypit/endpoint-kit";import type { ComponentPackage } from "@hypit/component-kit";import { createLocalRuntime } from "@hypit/runtime-local";-import { defineBuild, sealBuildRequest } from "@hypit/core";+import { defineBuild } from "@hypit/core";import {collectLoadedNodePackageComponents,loadNodePackageSelection,} from "@hypit/package-loader-node";-import { credentialRef } from "@hypit/runtime";-import type { CredentialValue, WritableCredentialStore } from "@hypit/runtime";+import { buildExecutionActivity, credentialRef } from "@hypit/runtime";+import type { BuildCompletion, CredentialValue, WritableCredentialStore } from "@hypit/runtime";import { SqliteRuntimeState } from "@hypit/store-sqlite";import {@@ -37,8 +38,14 @@ import {const providerModule = { name: "example.local-endpoint", version: "1" } as const;-function definition(state: ReturnType<typeof createGreetingBuild>) {- return defineBuild(state.program, state.graph, state.request);+function definition(state: ReturnType<typeof createGreetingBuild>, program = state.program) {+ const authored = new Set(state.program.records.map((record) => record.id));+ return defineBuild({+ program,+ initialRecords: state.records.filter((record) => !authored.has(record.id)),+ plan: state.plan,+ targets: state.targets,+ });}function projectRuntimeFixture(directory: string) {@@ -48,7 +55,10 @@ function projectRuntimeFixture(directory: string) {buildStore: state.builds,buildCatalog: state.catalog,operationStore: state.operations,- dispatchStore: state.dispatch,+ commandExecutionStore: state.commandExecutions,+ executionStore: state.execution,+ removeActiveBuild: async (build: string) => await state.removeActiveBuild(build),+ submissionStore: state.submissions,resourceStore: new FileResourceStore(join(directory, ".hypit", "artifacts")),resourceStoreForBuild: (build: string) => new FileResourceStore(join(work, build)),clearBuildResources: async (build: string) => {@@ -56,7 +66,8 @@ function projectRuntimeFixture(directory: string) {},openBuildResultRepository: async (location: import("@hypit/build-result-kit").BuildResultRepositoryLocation) => {assert.equal(location.selection.use, "@hypit/build-result-fs");- return { repository: new FileBuildResultRepository(location.root) };+ const config = location.selection.config as { readonly path?: string } | undefined;+ return { repository: new FileBuildResultRepository(join(location.root, config?.path ?? ".hypit/results")) };},credentialStore: new EnvironmentCredentialStore(),close: () => state.close(),@@ -66,12 +77,64 @@ function projectRuntimeFixture(directory: string) {function resultDestination(directory: string) {return {repository: {- root: join(directory, "results"),- selection: { use: "@hypit/build-result-fs" },+ root: directory,+ selection: { use: "@hypit/build-result-fs", config: { path: "results" } },+ },+ } as const;+}++function durableBuildRequest(+ directory: string,+ id: string,+ initial: ReturnType<typeof createGreetingBuild>,+) {+ return {+ id,+ definition: definition(initial),+ catalog: {+ source: { path: join(directory, "main.svml") },+ publishedOutputs: initial.targets.map((target, index) => ({+ name: `target.${index + 1}`,+ ref: { kind: "logical-output" as const, id: target.output },+ })),},+ result: resultDestination(directory),} as const;}+test("a Worker that lost Runtime ownership cannot claim a ready Build", async () => {+ const directory = await mkdtemp(join(tmpdir(), "hypit-local-worker-owner-"));+ const initial = createGreetingBuild();+ try {+ const runtime = await createLocalRuntime({+ ...projectRuntimeFixture(directory),+ assertEnvironment: () => {+ throw new Error("Runtime Worker no longer owns this Runtime");+ },+ });+ await runtime.build(durableBuildRequest(directory, "bld_20260902T120000000Z_0000000001", initial));++ await assert.rejects(runtime.workOnce(), /no longer owns this Runtime/u);+ const status = await runtime.inspect("bld_20260902T120000000Z_0000000001");+ assert.equal(status?.activity, "ready");+ await runtime.close();+ } finally {+ await rm(directory, { recursive: true, force: true });+ }+});++async function finishClaimedBuild(+ runtime: Awaited<ReturnType<typeof createLocalRuntime>>,+): Promise<BuildCompletion> {+ let snapshot;+ for (let index = 0; index < 4; index += 1) {+ snapshot = await runtime.workOnce();+ if (snapshot !== undefined && "outcome" in snapshot) return snapshot;+ }+ throw new Error(`Build did not finish; last activity was ${snapshot === undefined+ ? "none" : "wakeAt" in snapshot ? buildExecutionActivity(snapshot) : "removed"}`);+}+test("Endpoint-declared credentials use the selected writable Store without a Provider switch", async () => {const directory = await mkdtemp(join(tmpdir(), "hypit-local-auth-"));const values = new Map<string, CredentialValue>();@@ -118,14 +181,14 @@ test("Endpoint-declared credentials use the selected writable Store without a Pr}});-test("project local runtime queues, polls and cancels work with replaceable packages", async () => {+test("project local Runtime advances, polls and cancels work with replaceable packages", async () => {const directory = await mkdtemp(join(tmpdir(), "hypit-local-"));const initial = createGreetingBuild();const catalog = {source: { path: join(directory, "main.svml") },- aliases: [{+ publishedOutputs: [{name: "final.document",- ref: { kind: "logical-output" as const, id: initial.request.targets[0]!.output },+ ref: { kind: "logical-output" as const, id: initial.targets[0]!.output },}, {name: "prompt.text",ref: { kind: "logical-output" as const, id: "prompt" },@@ -221,30 +284,30 @@ test("project local runtime queues, polls and cancels work with replaceable packendpoints: [endpointPackage],});const first = await firstRuntime.build({- id: "greeting-build",+ id: "bld_20260902T120000001Z_0000000001",definition: definition(initial),catalog,result: resultDestination(directory),});- assert.equal(first.status, "queued");- assert.equal((await firstRuntime.workOnce())?.phase, "waiting");+ assert("view" in first);+ assert.equal(first.view.activity, "ready");+ const firstTurn = await firstRuntime.workOnce();+ assert(firstTurn !== undefined && "wakeAt" in firstTurn);+ assert.equal(buildExecutionActivity(firstTurn), "ready");assert.equal(starts, 1);assert.equal(polls, 0);- const second = await firstRuntime.status("greeting-build");- assert.equal(second.dispatch?.phase, "waiting");- assert.equal((await firstRuntime.workOnce())?.terminal, "complete");+ const second = await firstRuntime.inspect("bld_20260902T120000001Z_0000000001");+ assert.equal(second?.activity, "ready");+ assert.equal((await finishClaimedBuild(firstRuntime)).outcome, "complete");assert.equal(starts, 1);assert.equal(polls, 1);assert.equal(promptCalls, 1, "persisted Core facts stop deterministic upstream replay");assert.equal(requestCalls, 1, "the Need request Producer is also persisted");assert.equal(assembleCalls, 1);- const clientStatus = await firstRuntime.status("greeting-build");- assert.equal(clientStatus.build, undefined);- assert.equal(clientStatus.catalog, undefined);- assert.deepEqual(clientStatus.operations, []);- assert.equal(clientStatus.dispatch?.terminal, "complete");- assert.deepEqual(await firstRuntime.builds(), []);- const buildResult = await readBuildResult(join(directory, "results", "greeting-build"));+ const clientStatus = await firstRuntime.inspect("bld_20260902T120000001Z_0000000001");+ assert.equal(clientStatus, undefined);+ assert.deepEqual((await firstRuntime.activity()).builds, []);+ const buildResult = await readBuildResult(join(directory, "results", "bld_20260902T120000001Z_0000000001"));assert.deepEqual(Object.keys(buildResult?.outputs ?? {}).sort(), ["final.document","generated.text",@@ -252,24 +315,24 @@ test("project local runtime queues, polls and cancels work with replaceable pack]);assert.deepEqual(buildResult?.targets, ["final.document"]);- await firstRuntime.build({ id: "greeting-follow", definition: definition(createGreetingBuild()) });+ await firstRuntime.build(durableBuildRequest(directory, "bld_20260902T120000002Z_0000000001", createGreetingBuild()));await firstRuntime.workOnce();- await firstRuntime.workOnce();- const followed = await firstRuntime.status("greeting-follow");- assert.equal(followed.dispatch?.terminal, "complete");+ await finishClaimedBuild(firstRuntime);+ const followed = await firstRuntime.inspect("bld_20260902T120000002Z_0000000001");+ assert.equal(followed, undefined);assert.equal(starts, 2);assert.equal(polls, 2);- const followedStatus = await firstRuntime.status("greeting-follow");- assert.equal(followedStatus.build?.state.status, "complete");- assert.equal(followedStatus.operations.length, 1);+ const followedStatus = await firstRuntime.inspect("bld_20260902T120000002Z_0000000001");+ assert.equal(followedStatus, undefined);- const waiting = await firstRuntime.build({ id: "greeting-cancel", definition: definition(createGreetingBuild()) });- assert.equal(waiting.status, "queued");+ const waiting = await firstRuntime.build(durableBuildRequest(directory, "bld_20260902T120000003Z_0000000001", createGreetingBuild()));+ assert("view" in waiting);+ assert.equal(waiting.view.activity, "ready");await firstRuntime.workOnce();- const requested = await firstRuntime.cancel("greeting-cancel");- assert.notEqual(requested?.cancellation, undefined);- const cancelled = await firstRuntime.workOnce();- assert.equal(cancelled?.terminal, "cancelled");+ const requested = await firstRuntime.cancel("bld_20260902T120000003Z_0000000001");+ assert.equal(requested?.cancellationRequested, true);+ const cancelled = await finishClaimedBuild(firstRuntime);+ assert.equal(cancelled.outcome, "cancelled");assert.equal(cancels, 1);await firstRuntime.close();} finally {@@ -279,12 +342,10 @@ test("project local runtime queues, polls and cancels work with replaceable packtest("a completed public file moves into its Build Result and leaves no Runtime working copy", async () => {const directory = await mkdtemp(join(tmpdir(), "hypit-local-result-file-"));- const id = "public-file-result";+ const id = "bld_20260902T120000004Z_0000000001";const workStore = new FileResourceStore(join(directory, ".hypit", "work", id));- const initial = createGreetingBuild({ generationRealization: "placeholder" });- const buildDefinition = defineBuild(initial.program, initial.graph, sealBuildRequest({- targets: [{ output: "generated" }],- }));+ const initial = createGreetingBuild({ generationRealization: "placeholder", targetOutputs: ["generated"] });+ const buildDefinition = definition(initial);const components: ComponentPackage = {producers: [{producer: producers.makePrompt,@@ -307,14 +368,14 @@ test("a completed public file moves into its Build Result and leaves no Runtimedefinition: buildDefinition,catalog: {source: { path: join(directory, "main.svml") },- aliases: [{ name: "clip.video", ref: { kind: "logical-output", id: "generated" } }],+ publishedOutputs: [{ name: "clip.video", ref: { kind: "logical-output", id: "generated" } }],},result: resultDestination(directory),});- assert.equal((await runtime.workOnce())?.terminal, "complete");+ assert.equal((await finishClaimedBuild(runtime)).outcome, "complete");const result = await readBuildResult(join(directory, "results", id));assert.equal(result?.outputs["clip.video"]?.value.kind, "build-file");- assert.equal(await readFile(join(directory, "results", id, "files", "clip.video.mp4"), "utf8"), "video bytes");+ assert.equal(await readFile(join(directory, "results", id, "files", "file-0001.mp4"), "utf8"), "video bytes");assert.equal(await stat(join(directory, ".hypit", "work", id)).then(() => true, () => false), false);await runtime.close();} finally {@@ -322,8 +383,8 @@ test("a completed public file moves into its Build Result and leaves no Runtime}});-test("a failed Build keeps public Outputs completed before the failure and retires execution state", async () => {- const directory = await mkdtemp(join(tmpdir(), "hypit-local-partial-result-"));+test("a failed Build keeps public Outputs completed before removing active Runtime state", async () => {+ const directory = await mkdtemp(join(tmpdir(), "hypit-local-bld_20260902T120000005Z_0000000001-"));const initial = createGreetingBuild();const components: ComponentPackage = {producers: [{@@ -359,11 +420,11 @@ test("a failed Build keeps public Outputs completed before the failure and retirendpoints: [endpoint],});await runtime.build({- id: "partial-result",+ id: "bld_20260902T120000005Z_0000000001",definition: definition(initial),catalog: {source: { path: join(directory, "main.svml") },- aliases: [{ name: "prompt.text", ref: { kind: "logical-output", id: "prompt" } }, {+ publishedOutputs: [{ name: "prompt.text", ref: { kind: "logical-output", id: "prompt" } }, {name: "generated.text", ref: { kind: "logical-output", id: "generated" },}, {name: "final.document", ref: { kind: "logical-output", id: "document" },@@ -371,16 +432,270 @@ test("a failed Build keeps public Outputs completed before the failure and retir},result: resultDestination(directory),});- assert.equal((await runtime.workOnce())?.terminal, "failed");- const result = await readBuildResult(join(directory, "results", "partial-result"));- assert.equal(result?.status, "failed");+ assert.equal((await finishClaimedBuild(runtime)).outcome, "failed");+ const result = await readBuildResult(join(directory, "results", "bld_20260902T120000005Z_0000000001"));+ assert.equal(result?.outcome, "failed");assert.equal(result?.failure, "generation failed");assert.deepEqual(Object.keys(result?.outputs ?? {}), ["prompt.text"]);assert.deepEqual(result?.outputs["prompt.text"]?.value, { kind: "inline", value: "Greet Ada" });- const status = await runtime.status("partial-result");- assert.equal(status.build, undefined);- assert.deepEqual(status.operations, []);- assert.equal(status.dispatch?.terminal, "failed");+ const status = await runtime.inspect("bld_20260902T120000005Z_0000000001");+ assert.equal(status, undefined);+ await runtime.close();+ } finally {+ await rm(directory, { recursive: true, force: true });+ }+});++test("an interrupted Result write finishes explicitly without rerunning the Build", async () => {+ const directory = await mkdtemp(join(tmpdir(), "hypit-local-result-retry-"));+ const initial = createGreetingBuild({ generationRealization: "placeholder" });+ let generationCalls = 0;+ let rejectSync = true;+ const components: ComponentPackage = {+ producers: [{+ producer: producers.makePrompt,+ handler: () => ({ outputs: { prompt: { kind: "inline", value: "Greet Ada" } }, needs: {} }),+ }, {+ producer: producers.placeholderText,+ handler: () => {+ generationCalls += 1;+ return { outputs: { generated: { kind: "inline", value: "Hello" } }, needs: {} };+ },+ }, {+ producer: producers.assemble,+ handler: ({ inputs }) => {+ const generated = inputs.generated?.value;+ assert.equal(generated?.kind, "inline");+ return {+ outputs: { document: { kind: "inline", value: { text: generated.value } } },+ needs: {},+ };+ },+ }],+ };+ const fixture = projectRuntimeFixture(directory);+ const openRepository = async (+ location: import("@hypit/build-result-kit").BuildResultRepositoryLocation,+ ) => {+ const path = (location.selection.config as { readonly path?: string } | undefined)?.path ?? ".hypit/results";+ const base = new FileBuildResultRepository(join(location.root, path));+ const repository: BuildResultRepository = {+ create: async (seed) => await base.create(seed),+ async openWriter(build) {+ const writer = await base.openWriter(build);+ if (writer === undefined) return undefined;+ return {+ read: async () => await writer.read(),+ sync: async (input) => {+ if (rejectSync) throw new Error("result store unavailable");+ return await writer.sync(input);+ },+ finish: async (input) => await writer.finish(input),+ };+ },+ remove: async (build) => await base.remove(build),+ read: async (build) => await base.read(build),+ updatePresentation: async (build, update) => await base.updatePresentation(build, update),+ browse: async (request) => await base.browse(request),+ resolve: async (build, output) => await base.resolve(build, output),+ openFile: async (build, file) => await base.openFile(build, file),+ };+ return { repository };+ };+ try {+ const runtime = await createLocalRuntime({+ ...fixture,+ openBuildResultRepository: openRepository,+ components: [components],+ });+ await runtime.build({+ id: "bld_20260902T120000006Z_0000000001",+ definition: definition(initial),+ catalog: {+ source: { path: join(directory, "main.svml") },+ publishedOutputs: [{ name: "final.document", ref: { kind: "logical-output", id: "document" } }],+ },+ result: resultDestination(directory),+ });+ const blocked = await runtime.workOnce();+ assert(blocked !== undefined && "decision" in blocked);+ assert.deepEqual(blocked.attention, { step: "result", error: "result store unavailable" });+ assert.equal(generationCalls, 1);+ assert.equal(await runtime.workOnce(), undefined);++ rejectSync = false;+ const completed = await runtime.finishResult("bld_20260902T120000006Z_0000000001");+ assert(completed !== undefined);+ assert.equal(completed.outcome, "complete");+ assert.equal(generationCalls, 1);+ await runtime.close();+ } finally {+ await rm(directory, { recursive: true, force: true });+ }+});++test("a failed Result creation leaves no active Build", async () => {+ const directory = await mkdtemp(join(tmpdir(), "hypit-local-submit-rollback-"));+ const initial = createGreetingBuild({ generationRealization: "placeholder" });+ const fixture = projectRuntimeFixture(directory);+ const unavailable: BuildResultRepository = {+ async create() { throw new Error("result repository refused creation"); },+ async openWriter() { return undefined; },+ async remove() {},+ async read() { return undefined; },+ async updatePresentation() { throw new Error("result repository refused update"); },+ async browse() { return { results: [] }; },+ async resolve() { return undefined; },+ async openFile() { return undefined; },+ };+ try {+ const runtime = await createLocalRuntime({+ ...fixture,+ openBuildResultRepository: async () => ({ repository: unavailable }),+ });+ await assert.rejects(runtime.build({+ id: "bld_20260902T120000007Z_0000000001",+ definition: definition(initial),+ catalog: {+ source: { path: join(directory, "main.svml") },+ publishedOutputs: [{ name: "final.document", ref: { kind: "logical-output", id: "document" } }],+ },+ result: resultDestination(directory),+ }), /result repository refused creation/u);+ const status = await runtime.inspect("bld_20260902T120000007Z_0000000001");+ assert.equal(status, undefined);+ assert.equal(await runtime.workOnce(), undefined);+ await runtime.close();+ } finally {+ await rm(directory, { recursive: true, force: true });+ }+});++test("an immediate Command left in started state fails its Build without invoking the Producer again", async () => {+ const directory = await mkdtemp(join(tmpdir(), "hypit-local-command-receipt-"));+ const initial = createGreetingBuild({ generationRealization: "placeholder" });+ let calls = 0;+ const components: ComponentPackage = {+ producers: [{+ producer: producers.makePrompt,+ handler: () => {+ calls += 1;+ return { outputs: { prompt: { kind: "inline", value: "must not run" } }, needs: {} };+ },+ }],+ };+ try {+ const runtime = await createLocalRuntime({+ ...projectRuntimeFixture(directory),+ components: [components],+ });+ const submitted = await runtime.build(durableBuildRequest(directory, "bld_20260902T120000008Z_0000000001", initial));+ const command = submitted.state.outstanding[0];+ assert.ok(command);+ const state = new SqliteRuntimeState(join(directory, ".hypit", "runtime.sqlite"));+ await state.commandExecutions.begin("bld_20260902T120000008Z_0000000001", command.id);+ state.close();++ const terminal = await finishClaimedBuild(runtime);+ assert.equal(terminal.outcome, "failed");+ assert.equal(calls, 0);+ const failed = await readBuildResult(join(directory, "results", "bld_20260902T120000008Z_0000000001"));+ assert.equal(failed?.outcome, "failed");+ assert.match(failed?.failure ?? "", /stopped before its result was stored/u);+ await runtime.close();+ } finally {+ await rm(directory, { recursive: true, force: true });+ }+});++test("a selected historical file is staged once before its Build becomes active", async () => {+ const directory = await mkdtemp(join(tmpdir(), "hypit-local-bld_20260902T120000009Z_0000000001-"));+ const initial = createGreetingBuild();+ const bytes = new Uint8Array([4, 3, 2, 1]);+ const historical = {+ kind: "blob" as const,+ resource: "res_historical_input" as const,+ size: bytes.byteLength,+ mediaType: "image/png",+ };+ const program = {+ ...initial.program,+ records: initial.program.records.filter((record) => record.id !== "intent:root"),+ };+ const intent = initial.records.find((record) => record.id === "intent:root")!;+ const buildDefinition = defineBuild({+ program,+ initialRecords: [{ ...intent, value: historical }],+ plan: initial.plan,+ targets: initial.targets,+ });+ let attachmentOpens = 0;+ let endpointCalls = 0;+ const components: ComponentPackage = {+ producers: [{+ producer: producers.makePrompt,+ handler: ({ inputs }) => ({ outputs: { prompt: inputs.intent!.value }, needs: {} }),+ }, {+ producer: producers.requestText,+ handler: ({ inputs }) => ({ outputs: {}, needs: { generation: { source: inputs.prompt!.value } } }),+ }, {+ producer: producers.assemble,+ handler: ({ inputs }) => ({+ outputs: { document: { kind: "inline", value: { text: inputs.generated!.id } } },+ needs: {},+ }),+ }],+ };+ const endpoint = defineEndpointPackage({+ module: providerModule,+ facet: "generation",+ instance: "generation.bld_20260902T120000009Z_0000000001",+ pool: "generation.bld_20260902T120000009Z_0000000001",+ capabilities: [{+ lifecycle: "immediate",+ capability: capabilities.generation,+ returns: types.generated,+ handler: async ({ need, resources }) => {+ endpointCalls += 1;+ const source = (need.constraints as { readonly source: typeof historical }).source;+ assert.equal(await resources.has(source.resource), true);+ assert.deepEqual(await resources.get(source.resource), bytes);+ return { value: { kind: "inline", value: "generated from history" } };+ },+ }],+ });+ try {+ const runtime = await createLocalRuntime({+ ...projectRuntimeFixture(directory),+ components: [components],+ endpoints: [endpoint],+ });+ await runtime.build({+ id: "bld_20260902T120000009Z_0000000001",+ definition: buildDefinition,+ catalog: {+ source: { path: join(directory, "main.svml") },+ publishedOutputs: [{ name: "final.document", ref: { kind: "logical-output", id: "document" } }],+ },+ attachments: [{+ artifact: historical,+ async open() {+ attachmentOpens += 1;+ return (async function* () { yield bytes; })();+ },+ }],+ result: resultDestination(directory),+ });+ assert.equal(attachmentOpens, 1);+ const work = new FileResourceStore(join(directory, ".hypit", "work", "bld_20260902T120000009Z_0000000001"));+ assert.equal(await work.has(historical.resource), true);++ const completed = await runtime.workOnce();+ assert(completed !== undefined && "outcome" in completed);+ assert.equal(completed.outcome, "complete");+ assert.equal(endpointCalls, 1);+ assert.equal(attachmentOpens, 1);+ assert.equal(await work.has(historical.resource), false);await runtime.close();} finally {await rm(directory, { recursive: true, force: true });@@ -388,7 +703,7 @@ test("a failed Build keeps public Outputs completed before the failure and retir});test("one local Worker admits later Builds while preserving shared Endpoint capacity", async () => {- const directory = await mkdtemp(join(tmpdir(), "hypit-local-parallel-builds-"));+ const directory = await mkdtemp(join(tmpdir(), "hypit-local-bld_20260902T120000011Z_0000000001uilds-"));let unrestrictedActive = 0;let mostUnrestricted = 0;let limitedActive = 0;@@ -458,21 +773,15 @@ test("one local Worker admits later Builds while preserving shared Endpoint capacomponents: [components],endpoints: [endpoint],});- await runtime.build({- id: "parallel-a",- definition: definition(createGreetingBuild()),- });+ await runtime.build(durableBuildRequest(directory, "bld_20260902T120000010Z_0000000001", createGreetingBuild()));const controller = new AbortController();const work = runtime.work({ idlePollMs: 5, signal: controller.signal });await firstStarted;- await runtime.build({- id: "parallel-b",- definition: definition(createGreetingBuild()),- });+ await runtime.build(durableBuildRequest(directory, "bld_20260902T120000011Z_0000000001", createGreetingBuild()));while (true) {- const states = await Promise.all(["parallel-a", "parallel-b"].map(async (id) =>- (await runtime.status(id)).dispatch?.terminal));- if (states.every((state) => state === "complete")) break;+ const outcomes = await Promise.all(["bld_20260902T120000010Z_0000000001", "bld_20260902T120000011Z_0000000001"].map(async (id) =>+ (await readBuildResult(join(directory, "results", id)))?.outcome));+ if (outcomes.every((outcome) => outcome === "complete")) break;await new Promise((resolve) => setTimeout(resolve, 5));}controller.abort();@@ -540,18 +849,16 @@ test("project local runtime accepts components loaded from an installed package"return collectLoadedNodePackageComponents(loaded);},});+ const selected = createGreetingBuild({ generationRealization: "placeholder" });const result = await runtime.build({- id: "selected-preview",- definition: definition(createGreetingBuild({- generationRealization: "placeholder",- })),+ ...durableBuildRequest(runtimeRoot, "bld_20260902T120000012Z_0000000001", selected),componentPackages: ["example-greeting-components"],});- assert.equal(result.status, "queued");- const completed = await runtime.workOnce();- assert.equal(completed?.terminal, "complete");- assert.equal((await runtime.status("selected-preview")).build?.state.records- .some((record) => record.id === "document:root"), true);+ assert("view" in result);+ assert.equal(result.view.activity, "ready");+ const completed = await finishClaimedBuild(runtime);+ assert.equal(completed.outcome, "complete");+ assert.equal((await readBuildResult(join(runtimeRoot, "results", "bld_20260902T120000012Z_0000000001")))?.outcome, "complete");await runtime.close();} finally {await rm(directory, { recursive: true, force: true });@@ -601,17 +908,17 @@ test("project local runtime remembers the complete package closure across increm});try {for (const [id, specifier] of [- ["component-closure-a", "example-feature-a"],- ["component-closure-b", "example-feature-b"],- ["component-closure-shared", "example-shared-components"],+ ["bld_20260902T120000013Z_0000000001", "example-feature-a"],+ ["bld_20260902T120000014Z_0000000001", "example-feature-b"],+ ["bld_20260902T120000015Z_0000000001", "example-shared-components"],] as const) {+ const initial = createGreetingBuild({ generationRealization: "placeholder" });await runtime.build({- id,- definition: definition(createGreetingBuild({ generationRealization: "placeholder" })),+ ...durableBuildRequest(directory, id, initial),componentPackages: [specifier],});- const completed = await runtime.workOnce();- assert.equal(completed?.terminal, "complete");+ const completed = await finishClaimedBuild(runtime);+ assert.equal(completed.outcome, "complete");}assert.deepEqual(loadedSelections, [["example-feature-a"],diff --git a/packages/runtime-local/test/worker-process.test.ts b/packages/runtime-local/test/worker-process.test.tsindex 1e936caa..ed5285a3 100644--- a/packages/runtime-local/test/worker-process.test.ts+++ b/packages/runtime-local/test/worker-process.test.ts@@ -21,25 +21,48 @@ test("one detached Runtime Worker can be started, observed and stopped", async (const program = `const fs = require("node:fs");const path = require("node:path");+ const { DatabaseSync } = require("node:sqlite");const index = process.argv.indexOf("--ready-file");const ready = process.argv[index + 1];+ const ownerIndex = process.argv.indexOf("--worker-owner");+ const owner = process.argv[ownerIndex + 1];+ const databasePath = ${JSON.stringify(join(dataRoot, "runtime.sqlite"))};+ fs.mkdirSync(path.dirname(databasePath), { recursive: true });+ const database = new DatabaseSync(databasePath);+ database.exec("CREATE TABLE IF NOT EXISTS hypit_worker_lease (singleton INTEGER PRIMARY KEY CHECK (singleton = 1), owner_id TEXT NOT NULL, pid INTEGER NOT NULL, acquired_at INTEGER NOT NULL, expires_at INTEGER NOT NULL) STRICT");+ const now = Date.now();+ database.prepare("INSERT OR REPLACE INTO hypit_worker_lease (singleton, owner_id, pid, acquired_at, expires_at) VALUES (1, ?, ?, ?, ?)").run(owner, process.pid, now, now + 60000);fs.mkdirSync(path.dirname(ready), { recursive: true });// Say it in the log before claiming to be ready. The ready file is what the parent waits on,// so anything written after it is a race the parent can win.process.stdout.write("worker-ready\\n");- fs.writeFileSync(ready, String(process.pid));- process.on("SIGTERM", () => process.exit(0));- setInterval(() => {}, 1000);+ fs.writeFileSync(ready, owner);+ const heartbeat = setInterval(() => database.prepare("UPDATE hypit_worker_lease SET expires_at = ? WHERE singleton = 1 AND owner_id = ? AND pid = ?").run(Date.now() + 60000, owner, process.pid), 1000);+ process.on("SIGTERM", () => {+ clearInterval(heartbeat);+ database.prepare("DELETE FROM hypit_worker_lease WHERE singleton = 1 AND owner_id = ? AND pid = ?").run(owner, process.pid);+ database.close();+ process.exit(0);+ });`;try {- const first = await ensureRuntimeProcess(- profile,- dataRoot,- { command: process.execPath, args: ["-e", program] },- 5_000,- );+ const [first, concurrent] = await Promise.all([+ ensureRuntimeProcess(+ profile,+ dataRoot,+ { command: process.execPath, args: ["-e", program] },+ 5_000,+ ),+ ensureRuntimeProcess(+ profile,+ dataRoot,+ { command: process.execPath, args: ["-e", program] },+ 5_000,+ ),+ ]);assert.equal(first.state, "running");assert.ok(first.pid);+ assert.equal(concurrent.pid, first.pid);assert.equal(await readFile(join(root, ".hypit", "runtime"), "utf8"), "runtime.json\n");const second = await ensureRuntimeProcess(@@ -52,6 +75,13 @@ test("one detached Runtime Worker can be started, observed and stopped", async (assert.equal((await runtimeProcessStatus(profile, dataRoot)).state, "running");assert.match((await runtimeProcessLogs(dataRoot)).text, /worker-ready/u);+ await writeFile(profile, JSON.stringify({ format: "hypit.runtime-profile@1", changed: true }), "utf8");+ assert.equal((await runtimeProcessStatus(profile, dataRoot)).configuration, "changed");+ await assert.rejects(+ ensureRuntimeProcess(profile, dataRoot, { command: "must-not-run", args: [] }, 5_000),+ /Runtime Profile changed/u,+ );+assert.equal((await stopRuntimeProcess(profile, dataRoot, 5_000)).state, "stopped");assert.equal((await runtimeProcessStatus(profile, dataRoot)).state, "stopped");} finally {diff --git a/packages/runtime/README.md b/packages/runtime/README.mdindex f486762e..46670f9e 100644--- a/packages/runtime/README.md+++ b/packages/runtime/README.md@@ -4,9 +4,10 @@ Environment neutral execution contracts around Core.The package defines the small ports used by a runtime:-* `BuildStore` keeps one active Build definition and its accepted facts until its Result is terminal.+* `BuildStore` keeps one active Build definition and its accepted facts until the Result is saved and active state is removed.* `OperationStore` keeps asynchronous external work only while the owning Build is active.-* `BuildDispatchStore` holds the local build queue and shared capacity reservations.+* `PendingBuildStore` owns the short submission transaction before the Build becomes active.+* `BuildExecutionStore` owns active scheduling facts, the immutable decision, attention and shared capacity reservations.* `ResourceStore` is the transient byte gateway used during Provider execution.* `CredentialStore` resolves secrets outside source and build state.* `RuntimeCommandExecutor` turns the commands regenerated by Core into component or endpoint calls.diff --git a/packages/runtime/src/capacity.ts b/packages/runtime/src/capacity.tsnew file mode 100644index 00000000..46bb0348--- /dev/null+++ b/packages/runtime/src/capacity.ts@@ -0,0 +1,34 @@+/** Provider capacity belongs to active Runtime execution, not to a Build lifecycle. */+export type CapacityResourceClaim = {+ readonly id: string;+ readonly limit: number;+};++/** One asynchronous external Operation that currently occupies Provider capacity. */+export type CapacityReservation = {+ readonly build: string;+ readonly command: string;+ readonly resources: readonly CapacityResourceClaim[];+ readonly queue?: {+ readonly pool: string;+ readonly lane: string;+ };+ readonly createdAt: number;+};++export type CapacityAcquireRequest = {+ readonly build: string;+ readonly command: string;+ readonly resources: readonly CapacityResourceClaim[];+ readonly queue?: CapacityReservation["queue"];+ readonly now: number;+};++export type CapacityAcquire =+ | { readonly status: "acquired"; readonly reservation: CapacityReservation }+ | {+ readonly status: "blocked";+ readonly availableAt: number;+ readonly reason: "resource-in-flight";+ readonly resource: string;+ };diff --git a/packages/runtime/src/catalog.ts b/packages/runtime/src/catalog.tsindex 38384c61..706f48fc 100644--- a/packages/runtime/src/catalog.ts+++ b/packages/runtime/src/catalog.ts@@ -1,11 +1,10 @@import type {LogicalOutputRef,- RecordRef,} from "@hypit/protocol";-export type BuildCatalogAlias = {+export type BuildPublishedOutput = {readonly name: string;- readonly ref: RecordRef | LogicalOutputRef;+ readonly ref: LogicalOutputRef;};export type BuildCatalogDescriptor = {@@ -15,19 +14,17 @@ export type BuildCatalogDescriptor = {readonly run?: {readonly path: string;};- readonly aliases: readonly BuildCatalogAlias[];+ readonly publishedOutputs: readonly BuildPublishedOutput[];};export type BuildCatalogEntry = BuildCatalogDescriptor & {readonly build: string;- readonly createdAt: number;};/** Host presentation index only. It is never Build truth. */export type BuildCatalog = {record(build: string, descriptor: BuildCatalogDescriptor): Promise<BuildCatalogEntry>;read(build: string): Promise<BuildCatalogEntry | undefined>;- list(): Promise<readonly BuildCatalogEntry[]>;- /** Result manifests own terminal presentation; Runtime Catalog covers active execution only. */+ /** Result manifests own finished presentation; Runtime Catalog covers active execution only. */remove?(build: string): Promise<void>;};diff --git a/packages/runtime/src/dispatch.ts b/packages/runtime/src/dispatch.tsdeleted file mode 100644index e4b04ad4..00000000--- a/packages/runtime/src/dispatch.ts+++ /dev/null@@ -1,96 +0,0 @@-import type { BuildResultRepositoryLocation } from "@hypit/build-result-kit";--export type DispatchPhase = "queued" | "running" | "waiting" | "terminal";-export type DispatchTerminal = "complete" | "failed" | "cancelled";--export type BuildDispatchRequest = {- readonly build: string;- /** Installed component packages loaded when a Worker claims this Build. */- readonly componentPackages: readonly string[];- /** Exact project Repository selected before this Build was queued. */- readonly result?: BuildResultRepositoryLocation;-};--export type BuildDispatchSnapshot = BuildDispatchRequest & {- readonly createdAt: number;- readonly availableAt: number;- readonly phase: DispatchPhase;- readonly reason?: string;- readonly cancellation?: {- readonly reason?: string;- };- readonly terminal?: DispatchTerminal;-};--export type BuildDispatchRelease = {- readonly phase: "queued" | "waiting";- readonly availableAt: number;- readonly reason?: string;-};--export type DispatchQuery = {- readonly phases?: readonly DispatchPhase[];-};--export type CapacityResourceClaim = {- readonly id: string;- readonly maxActive: number;- readonly maxInFlight: number;-};--/** One asynchronous external Operation that currently occupies Provider capacity. */-export type CapacityReservation = {- readonly build: string;- readonly command: string;- readonly resources: readonly CapacityResourceClaim[];- readonly queue?: {- readonly pool: string;- readonly lane: string;- };- readonly createdAt: number;-};--export type CapacityAcquireRequest = {- readonly build: string;- readonly command: string;- readonly resources: readonly CapacityResourceClaim[];- readonly queue?: CapacityReservation["queue"];- readonly now: number;-};--export type CapacityAcquire =- | { readonly status: "acquired"; readonly reservation: CapacityReservation }- | {- readonly status: "blocked";- readonly availableAt: number;- readonly reason: "resource-in-flight";- readonly resource: string;- };--/** Durable queue state. Process ownership belongs to the Runtime Host, not each Build row. */-export type BuildDispatchStore = {- create(request: BuildDispatchRequest, options?: {- readonly now?: number;- }): Promise<BuildDispatchSnapshot>;- read(build: string): Promise<BuildDispatchSnapshot | undefined>;- list(query?: DispatchQuery): Promise<readonly BuildDispatchSnapshot[]>;- claim(now?: number): Promise<BuildDispatchSnapshot | undefined>;- /**- * Return Dispatches abandoned mid-run to the claimable set and release the capacity they hold.- *- * `claim` only takes `queued` and `waiting` Dispatches, and nothing distinguishes a `running` one- * whose Worker is alive from one whose Worker is gone. A Worker that stops between claiming a- * Dispatch and finishing it therefore strands both the Dispatch and its lane reservation for good:- * later Builds queue behind a slot nobody holds, and a cancellation never runs because cancelling- * happens on a claimed Dispatch. One Worker owns a Runtime, so every `running` Dispatch at startup- * is abandoned by construction.- */- reclaimAbandoned(now?: number): Promise<readonly string[]>;- release(build: string, update: BuildDispatchRelease): Promise<BuildDispatchSnapshot>;- finish(build: string, terminal: DispatchTerminal, reason?: string): Promise<BuildDispatchSnapshot>;- requestCancellation(build: string, reason?: string): Promise<BuildDispatchSnapshot>;- acquireCapacity(request: CapacityAcquireRequest): Promise<CapacityAcquire>;- releaseCapacity(build: string, command: string): Promise<void>;- releaseBuildCapacity(build: string): Promise<void>;- listCapacity(): Promise<readonly CapacityReservation[]>;-};diff --git a/packages/runtime/src/environment.ts b/packages/runtime/src/environment.tsnew file mode 100644index 00000000..39cbc8db--- /dev/null+++ b/packages/runtime/src/environment.ts@@ -0,0 +1,6 @@+export type RuntimeEnvironmentStore = {+ /** Select this literal normalized configuration, changing it only when no Runtime work is active. */+ use(config: string): Promise<void>;+ /** Refuse work when this Runtime instance was assembled from a different active configuration. */+ assert(config: string): Promise<void>;+};diff --git a/packages/runtime/src/execution.ts b/packages/runtime/src/execution.tsnew file mode 100644index 00000000..a29de4aa--- /dev/null+++ b/packages/runtime/src/execution.ts@@ -0,0 +1,112 @@+import type { BuildResultRepositoryLocation } from "@hypit/build-result-kit";+import type { CommandResult } from "@hypit/protocol";+import type {+ CapacityAcquire,+ CapacityAcquireRequest,+ CapacityReservation,+} from "./capacity.js";++export type BuildOutcome = "complete" | "failed" | "cancelled";++export type BuildExecutionRequest = {+ readonly build: string;+ /** Installed component packages loaded when a Worker takes an execution turn. */+ readonly componentPackages: readonly string[];+ /** Exact project Result Repository selected at submission. */+ readonly result: BuildResultRepositoryLocation;+};++export type BuildExecutionDecision = {+ readonly outcome: BuildOutcome;+ readonly reason?: string;+};++export type BuildExecutionAttention = {+ readonly step: "result" | "cleanup";+ readonly error: string;+};++export type BuildExecutionTurn = {+ readonly owner: string;+ readonly acquiredAt: number;+};++export type BuildResultWriteLease = BuildExecutionTurn;++/**+ * The complete active Runtime root for one Build.+ *+ * It has no persisted lifecycle phase. Scheduling is derived from `wakeAt` and `turn`; the one+ * immutable execution conclusion is `decision`; operator attention is an independent fact.+ */+export type BuildExecutionSnapshot = BuildExecutionRequest & {+ readonly createdAt: number;+ readonly wakeAt: number;+ readonly turn?: BuildExecutionTurn;+ readonly resultWrite?: BuildResultWriteLease;+ readonly cancellation?: { readonly reason?: string };+ readonly decision?: BuildExecutionDecision;+ readonly attention?: BuildExecutionAttention;+};++export type BuildExecutionActivity = "ready" | "running" | "waiting" | "saving-result";++export function buildExecutionActivity(+ execution: BuildExecutionSnapshot,+ now = Date.now(),+): BuildExecutionActivity {+ if (execution.decision !== undefined) return "saving-result";+ if (execution.turn !== undefined) return "running";+ return execution.wakeAt > now ? "waiting" : "ready";+}++/** Ephemeral acknowledgement returned after active Runtime state has been removed. */+export type BuildCompletion = BuildExecutionDecision & {+ readonly build: string;+};++export type BuildExecutionStore = {+ create(request: BuildExecutionRequest, options?: { readonly now?: number }): Promise<BuildExecutionSnapshot>;+ read(build: string): Promise<BuildExecutionSnapshot | undefined>;+ list(): Promise<readonly BuildExecutionSnapshot[]>;+ /** Atomically take one ready, undecided execution turn for this Worker owner. */+ claim(owner: string, now?: number): Promise<BuildExecutionSnapshot | undefined>;+ /** A new owning Worker clears turns left by the previous process; no external action is repeated here. */+ reclaimTurns(now?: number): Promise<readonly string[]>;+ releaseTurn(build: string, owner: string, wakeAt: number): Promise<BuildExecutionSnapshot>;+ /** Freeze the one conclusion. An execution with a decision can never be claimed again. */+ decide(build: string, owner: string, outcome: BuildOutcome, reason?: string): Promise<BuildExecutionSnapshot>;+ requestCancellation(build: string, reason?: string): Promise<BuildExecutionSnapshot>;+ setAttention(build: string, attention: BuildExecutionAttention | undefined): Promise<BuildExecutionSnapshot>;+ claimResultWrite(build: string, owner: string, now?: number): Promise<BuildExecutionSnapshot | undefined>;+ releaseResultWrite(build: string, owner: string): Promise<BuildExecutionSnapshot>;+ /** Clear only Result-writer ownership left by the previous Runtime process and record attention. */+ reclaimResultWrites(): Promise<readonly string[]>;+ acquireCapacity(request: CapacityAcquireRequest): Promise<CapacityAcquire>;+ releaseCapacity(build: string, command: string): Promise<void>;+ releaseBuildCapacity(build: string): Promise<void>;+ listCapacity(): Promise<readonly CapacityReservation[]>;+};++export type CommandExecutionReceipt = {+ readonly build: string;+ readonly command: string;+ readonly status: "started" | "completed";+ readonly event?: CommandResult;+};++export type CommandExecutionBegin = {+ readonly created: boolean;+ readonly receipt: CommandExecutionReceipt;+};++/**+ * Live handoff for commands that complete in one call. It prevents the same Build from invoking+ * an immediate Producer or Endpoint again after the process stops between execution and Core fact.+ */+export type CommandExecutionStore = {+ begin(build: string, command: string): Promise<CommandExecutionBegin>;+ complete(build: string, command: string, event: CommandResult): Promise<CommandExecutionReceipt>;+ list(build: string): Promise<readonly CommandExecutionReceipt[]>;+ removeBuild(build: string): Promise<void>;+};diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.tsindex 6cadee4d..f4d4d827 100644--- a/packages/runtime/src/index.ts+++ b/packages/runtime/src/index.ts@@ -8,10 +8,15 @@ export {verifyCredentialRef,} from "./credentials.js";export type * from "./credentials.js";-export type * from "./dispatch.js";+export type * from "./capacity.js";+export { buildExecutionActivity } from "./execution.js";+export type * from "./execution.js";+export type * from "./environment.js";export type * from "./operations.js";export { LocalBuildScheduler } from "./scheduler.js";+export type * from "./submission.js";export {isStreamingResourceStore,} from "./types.js";export type * from "./types.js";+export type * from "./worker.js";diff --git a/packages/runtime/src/operations.ts b/packages/runtime/src/operations.tsindex 232dec41..b4e3943c 100644--- a/packages/runtime/src/operations.ts+++ b/packages/runtime/src/operations.ts@@ -70,6 +70,6 @@ export type OperationStore = {list(query: OperationQuery): Promise<readonly OperationSnapshot[]>;/** One local Worker owns execution. A terminal Operation is returned unchanged. */update(id: string, update: OperationUpdate): Promise<OperationSnapshot>;- /** Drop Provider execution payloads after the owning Build Result is terminal. */+ /** Drop Provider execution payloads after the owning Build Result has an outcome. */removeBuild?(build: string): Promise<void>;};diff --git a/packages/runtime/src/scheduler.ts b/packages/runtime/src/scheduler.tsindex 5a6b9d8f..1fe0bdae 100644--- a/packages/runtime/src/scheduler.ts+++ b/packages/runtime/src/scheduler.ts@@ -96,7 +96,7 @@ export class LocalBuildScheduler {let cursor = 0;const resourceLimit = (resource: RuntimeRunnableCommand["resources"][number]): number => {- const proposed = positiveInteger(resource.maxActive, `resource ${resource.id} default`);+ const proposed = positiveInteger(resource.limit, `resource ${resource.id} limit`);const previous = resourceDefaults.get(resource.id);if (previous !== undefined && previous !== proposed) {throw new Error(`resource ${resource.id} has conflicting default concurrency ${previous} and ${proposed}`);diff --git a/packages/runtime/src/submission.ts b/packages/runtime/src/submission.tsnew file mode 100644index 00000000..12ab235e--- /dev/null+++ b/packages/runtime/src/submission.ts@@ -0,0 +1,24 @@+import type { BuildDefinition } from "@hypit/protocol";+import type { BuildCatalogDescriptor } from "./catalog.js";+import type { BuildExecutionRequest, BuildExecutionSnapshot } from "./execution.js";++export type PendingBuildSubmission = BuildExecutionRequest & {+ readonly createdAt: number;+};++export type PendingBuildCommit = BuildExecutionRequest & {+ readonly definition: BuildDefinition;+ readonly catalog: BuildCatalogDescriptor;+};++/**+ * One exact cross-store submission transaction. A pending submission is not schedulable and can+ * only become active execution or be explicitly discarded with its Result draft and temporary resources.+ */+export type PendingBuildStore = {+ prepare(request: BuildExecutionRequest, options?: { readonly now?: number }): Promise<PendingBuildSubmission>;+ read(build: string): Promise<PendingBuildSubmission | undefined>;+ list(): Promise<readonly PendingBuildSubmission[]>;+ commit(request: PendingBuildCommit): Promise<BuildExecutionSnapshot>;+ discard(build: string): Promise<void>;+};diff --git a/packages/runtime/src/types.ts b/packages/runtime/src/types.tsindex f61ef915..88d6ec91 100644--- a/packages/runtime/src/types.ts+++ b/packages/runtime/src/types.ts@@ -26,8 +26,7 @@ export type RuntimeRunnableCommand = {export type RuntimeResourceClaim = {readonly id: string;- readonly maxActive: number;- readonly maxInFlight: number;+ readonly limit: number;};export type RuntimeQueueLane = {@@ -38,6 +37,8 @@ export type RuntimeQueueLane = {export type RuntimeWorkerRunOptions = {readonly idlePollMs: number;readonly signal?: AbortSignal;+ /** Called after abandoned work is claimable and immediately before the claim loop starts. */+ readonly ready?: () => void | Promise<void>;};export type RuntimePreparation = {diff --git a/packages/runtime/src/worker.ts b/packages/runtime/src/worker.tsnew file mode 100644index 00000000..b28157e5--- /dev/null+++ b/packages/runtime/src/worker.ts@@ -0,0 +1,16 @@+export type RuntimeWorkerLease = {+ readonly owner: string;+ readonly pid: number;+ readonly acquiredAt: number;+ readonly expiresAt: number;+};++export type RuntimeWorkerLeaseStore = {+ read(): Promise<RuntimeWorkerLease | undefined>;+ /** Acquire the one live Runtime worker slot, replacing only an expired lease. */+ acquire(request: RuntimeWorkerLease): Promise<boolean>;+ /** Renew only the lease held by this exact owner and process. */+ renew(owner: string, pid: number, expiresAt: number): Promise<boolean>;+ /** Release only the caller's own lease. */+ release(owner: string, pid: number): Promise<void>;+};diff --git a/packages/script/test/markup-integration.test.ts b/packages/script/test/markup-integration.test.tsindex a2a3815b..afae9d1f 100644--- a/packages/script/test/markup-integration.test.ts+++ b/packages/script/test/markup-integration.test.ts@@ -67,33 +67,6 @@ test("Script teaches Markup <script> only through its imported Manifest", asyncassert.deepEqual(result.identities, [{ namespace: narrativeType, id: "story" }]);});-test("the same Script meaning has the same authored Record digest across reflow", async () => {- const compact = await decodeMarkup(- {- name: "compact.svml",- text: `<svml><import from="@hypit/script@1"/><script id="story"><opening><ALICE>Hello.<BOB>Hi.</opening></script></svml>`,- },- scriptContext(),- );- const multiline = await decodeMarkup(- {- name: "multiline.svml",- text: `<svml>- <import from="@hypit/script@1"/>- <script id="story">- <opening>- <ALICE>Hello.- <BOB>Hi.- </opening>- </script>- </svml>`,- },- scriptContext(),- );-- assert.deepEqual(compact.records, multiline.records);-});-test("without the import, Markup has no hard-coded knowledge of Script", async () => {await assert.rejects(decodeMarkup(diff --git a/packages/seedance-kits/test/kits.test.ts b/packages/seedance-kits/test/kits.test.tsindex 16f6e6dd..0f2a693a 100644--- a/packages/seedance-kits/test/kits.test.ts+++ b/packages/seedance-kits/test/kits.test.ts@@ -23,16 +23,3 @@ test("Seedance Kits are finite data programs with distinct rendered semantics",assert.match(output.value, new RegExp(item.marker, "u"), item.file);}});--test("official Seedance Kits select semantics by file and explicit axes, never inferred branches", () => {- for (const item of cases) {- const source = readFileSync(new URL(`../kits/${item.file}`, import.meta.url), "utf8");- assert.doesNotMatch(source, /kind:\s*variant|when-(?:param|select)-/u, item.file);- assert.doesNotMatch(source, /slot:\s*extra/u, item.file);- }- const broll = readFileSync(new URL("../kits/broll-v1.svs", import.meta.url), "utf8");- assert.doesNotMatch(broll, /reference-plan/u);- const speaker = readFileSync(new URL("../kits/speaker-v1.svs", import.meta.url), "utf8");- assert.match(speaker, /slot:\s*dialogue/u);- assert.match(speaker, /slot:\s*action/u);-});diff --git a/packages/store-sqlite/src/store.ts b/packages/store-sqlite/src/store.tsindex 7b15d9f9..e26b2ef5 100644--- a/packages/store-sqlite/src/store.ts+++ b/packages/store-sqlite/src/store.ts@@ -6,12 +6,16 @@ import { materializeBuild } from "@hypit/core";import type {BuildDefinition,BuildFact,+ CommandResult,} from "@hypit/protocol";+import { assertBuildId } from "@hypit/protocol";import type {- BuildDispatchRequest,- BuildDispatchRelease,- BuildDispatchSnapshot,- BuildDispatchStore,+ PendingBuildCommit,+ PendingBuildSubmission,+ PendingBuildStore,+ BuildExecutionRequest,+ BuildExecutionSnapshot,+ BuildExecutionStore,BuildCatalog,BuildCatalogDescriptor,BuildCatalogEntry,@@ -20,17 +24,22 @@ import type {CapacityAcquire,CapacityAcquireRequest,CapacityReservation,- DispatchQuery,+ CommandExecutionBegin,+ CommandExecutionReceipt,+ CommandExecutionStore,OperationIdentity,OperationQuery,OperationSnapshot,OperationStore,OperationUpdate,+ RuntimeWorkerLease,+ RuntimeWorkerLeaseStore,+ RuntimeEnvironmentStore,} from "@hypit/runtime";export type SqliteRuntimeStateOptions = {readonly busyTimeoutMs?: number;- /** Open an existing archive without creating files or schema. */+ /** Open an existing Runtime database without creating files or schema. */readonly readOnly?: boolean;};@@ -140,7 +149,7 @@ class SqliteBuildStore implements BuildStore {}async create(build: string, definition: BuildDefinition): Promise<BuildSnapshot> {- assert(build.trim().length > 0, "build id must not be empty");+ assertBuildId(build);const result = this.#database.prepare(`INSERT OR IGNORE INTO hypit_builds (build_id, definition_json)VALUES (?, ?)@@ -180,13 +189,11 @@ class SqliteBuildStore implements BuildStore {function parseCatalogEntry(row: Row): BuildCatalogEntry {assert(typeof row.build_id === "string", "SQLite Build Catalog row has no build id");- assert(typeof row.created_at === "number", "SQLite Build Catalog row has no creation time");assert(typeof row.descriptor_json === "string", "SQLite Build Catalog row has no descriptor");const descriptor = JSON.parse(row.descriptor_json) as BuildCatalogDescriptor;return {...descriptor,build: row.build_id,- createdAt: row.created_at,};}@@ -198,14 +205,14 @@ class SqliteBuildCatalog implements BuildCatalog {}async record(build: string, descriptor: BuildCatalogDescriptor): Promise<BuildCatalogEntry> {- assert(build.trim().length > 0, "Build Catalog build id must not be empty");+ assertBuildId(build);const now = Date.now();this.#database.prepare(`INSERT INTO hypit_build_catalog (build_id, created_at, descriptor_json) VALUES (?, ?, ?)`).run(build, now, JSON.stringify(descriptor));- return { ...copy(descriptor), build, createdAt: now };+ return { ...copy(descriptor), build };}async read(build: string): Promise<BuildCatalogEntry | undefined> {@@ -217,20 +224,133 @@ class SqliteBuildCatalog implements BuildCatalog {return row === undefined ? undefined : parseCatalogEntry(row);}- async list(): Promise<readonly BuildCatalogEntry[]> {- const rows = this.#database.prepare(`- SELECT build_id, created_at, descriptor_json- FROM hypit_build_catalog- ORDER BY created_at DESC, build_id ASC- `).all() as Row[];- return rows.map(parseCatalogEntry);- }-async remove(build: string): Promise<void> {this.#database.prepare("DELETE FROM hypit_build_catalog WHERE build_id = ?").run(build);}}+function parseExecutionRequest(row: Row, subject: string): BuildExecutionRequest {+ assert(typeof row.build_id === "string", `SQLite ${subject} row has no Build id`);+ assert(typeof row.component_packages_json === "string", `SQLite ${subject} row has no component packages`);+ assert(typeof row.result_location_json === "string", `SQLite ${subject} row has no Result location`);+ const componentPackages = JSON.parse(row.component_packages_json) as unknown;+ assert(Array.isArray(componentPackages) && componentPackages.every((item) => typeof item === "string"),+ `SQLite ${subject} component packages are invalid`);+ const result = JSON.parse(row.result_location_json) as Partial<BuildExecutionRequest["result"]>;+ assert(typeof result.root === "string" && typeof result.selection?.use === "string",+ `SQLite ${subject} Result location is invalid`);+ return {+ build: row.build_id,+ componentPackages,+ result: result as BuildExecutionRequest["result"],+ };+}++function parsePendingBuildSubmission(row: Row): PendingBuildSubmission {+ assert(typeof row.created_at === "number", "SQLite pending-submission creation time is invalid");+ return { ...parseExecutionRequest(row, "pending submission"), createdAt: row.created_at };+}++class SqlitePendingBuildStore implements PendingBuildStore {+ readonly #database: DatabaseSync;++ constructor(database: DatabaseSync) {+ this.#database = database;+ }++ async prepare(+ request: BuildExecutionRequest,+ options: { readonly now?: number } = {},+ ): Promise<PendingBuildSubmission> {+ assertBuildId(request.build);+ const now = options.now ?? Date.now();+ nonNegativeInteger(now, "Build submission preparation time");+ return transaction(this.#database, () => {+ const occupied = this.#database.prepare(`+ SELECT 1 AS occupied FROM hypit_submissions WHERE build_id = ?+ UNION ALL SELECT 1 FROM hypit_executions WHERE build_id = ?+ UNION ALL SELECT 1 FROM hypit_builds WHERE build_id = ?+ UNION ALL SELECT 1 FROM hypit_build_catalog WHERE build_id = ?+ UNION ALL SELECT 1 FROM hypit_operations WHERE build_id = ?+ UNION ALL SELECT 1 FROM hypit_command_executions WHERE build_id = ?+ UNION ALL SELECT 1 FROM hypit_build_facts WHERE build_id = ?+ UNION ALL SELECT 1 FROM hypit_capacity WHERE build_id = ?+ LIMIT 1+ `).get(request.build, request.build, request.build, request.build, request.build, request.build, request.build, request.build);+ assert(occupied === undefined, `Build ${request.build} already has Runtime state`);+ this.#database.prepare(`+ INSERT INTO hypit_submissions (+ build_id, component_packages_json, result_location_json, created_at+ ) VALUES (?, ?, ?, ?)+ `).run(+ request.build,+ JSON.stringify(request.componentPackages),+ JSON.stringify(request.result),+ now,+ );+ return parsePendingBuildSubmission(+ this.#database.prepare("SELECT * FROM hypit_submissions WHERE build_id = ?").get(request.build) as Row,+ );+ });+ }++ async read(build: string): Promise<PendingBuildSubmission | undefined> {+ const row = this.#database.prepare("SELECT * FROM hypit_submissions WHERE build_id = ?").get(build) as Row | undefined;+ return row === undefined ? undefined : parsePendingBuildSubmission(row);+ }++ async list(): Promise<readonly PendingBuildSubmission[]> {+ return (this.#database.prepare(+ "SELECT * FROM hypit_submissions ORDER BY created_at ASC, build_id ASC",+ ).all() as Row[]).map(parsePendingBuildSubmission);+ }++ async commit(request: PendingBuildCommit): Promise<BuildExecutionSnapshot> {+ assertBuildId(request.build);+ return transaction(this.#database, () => {+ const row = this.#database.prepare("SELECT * FROM hypit_submissions WHERE build_id = ?").get(request.build) as Row | undefined;+ if (row === undefined) throw new Error(`Build submission ${request.build} was not prepared`);+ const submission = parsePendingBuildSubmission(row);+ assert(JSON.stringify(submission.componentPackages) === JSON.stringify(request.componentPackages)+ && JSON.stringify(submission.result) === JSON.stringify(request.result),+ `Build submission ${request.build} does not match its prepared state`);+ this.#database.prepare(`+ INSERT INTO hypit_builds (build_id, definition_json) VALUES (?, ?)+ `).run(request.build, JSON.stringify(request.definition));+ this.#database.prepare(`+ INSERT INTO hypit_build_catalog (build_id, created_at, descriptor_json) VALUES (?, ?, ?)+ `).run(request.build, Date.now(), JSON.stringify(request.catalog));+ this.#database.prepare(`+ INSERT INTO hypit_executions (+ build_id, component_packages_json, result_location_json, created_at, wake_at,+ turn_owner, turn_acquired_at, result_writer_owner, result_writer_acquired_at,+ cancel_requested, cancellation_reason,+ decision_outcome, decision_reason, attention_step, attention_error+ ) VALUES (?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, 0, NULL, NULL, NULL, NULL, NULL)+ `).run(+ request.build,+ JSON.stringify(request.componentPackages),+ JSON.stringify(request.result),+ submission.createdAt,+ Date.now(),+ );+ this.#database.prepare("DELETE FROM hypit_submissions WHERE build_id = ?").run(request.build);+ return parseExecutionSnapshot(+ this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(request.build) as Row,+ );+ });+ }++ async discard(build: string): Promise<void> {+ assertBuildId(build);+ transaction(this.#database, () => {+ const row = this.#database.prepare("SELECT build_id FROM hypit_submissions WHERE build_id = ?").get(build) as Row | undefined;+ if (row === undefined) return;+ this.#database.prepare("DELETE FROM hypit_submissions WHERE build_id = ?").run(build);+ });+ }+}+class SqliteOperationStore implements OperationStore {readonly #database: DatabaseSync;@@ -332,53 +452,229 @@ class SqliteOperationStore implements OperationStore {}}+function parseCommandExecution(row: Row): CommandExecutionReceipt {+ assert(typeof row.build_id === "string" && typeof row.command_id === "string",+ "SQLite Command execution has no identity");+ assert(row.status === "started" || row.status === "completed",+ "SQLite Command execution has an invalid status");+ const event = typeof row.event_json === "string"+ ? JSON.parse(row.event_json) as CommandResult+ : undefined;+ if (row.status === "completed") {+ assert(event !== undefined, `SQLite Command execution ${row.command_id} has no result`);+ }+ return {+ build: row.build_id,+ command: row.command_id,+ status: row.status,+ ...(event === undefined ? {} : { event }),+ };+}-function parseDispatchSnapshot(row: Row): BuildDispatchSnapshot {- assert(typeof row.build_id === "string", "SQLite Dispatch row has no Build id");- assert(typeof row.component_packages_json === "string", "SQLite Dispatch row has no component packages");- assert(typeof row.created_at === "number", "SQLite Dispatch time is invalid");- assert(typeof row.available_at === "number", "SQLite Dispatch schedule is invalid");- assert(typeof row.phase === "string", "SQLite Dispatch state is invalid");- const componentPackages = JSON.parse(row.component_packages_json) as readonly string[];- const cancellation = row.cancel_requested === 1- ? {- cancellation: {- ...(typeof row.reason === "string" ? { reason: row.reason } : {}),- },+class SqliteCommandExecutionStore implements CommandExecutionStore {+ readonly #database: DatabaseSync;++ constructor(database: DatabaseSync) {+ this.#database = database;+ }++ async begin(build: string, command: string): Promise<CommandExecutionBegin> {+ return transaction(this.#database, () => {+ const inserted = this.#database.prepare(`+ INSERT OR IGNORE INTO hypit_command_executions (build_id, command_id, status, event_json)+ VALUES (?, ?, 'started', NULL)+ `).run(build, command);+ const row = this.#database.prepare(`+ SELECT * FROM hypit_command_executions WHERE build_id = ? AND command_id = ?+ `).get(build, command) as Row;+ return { created: inserted.changes === 1, receipt: parseCommandExecution(row) };+ });+ }++ async complete(build: string, command: string, event: CommandResult): Promise<CommandExecutionReceipt> {+ return transaction(this.#database, () => {+ const row = this.#database.prepare(`+ SELECT * FROM hypit_command_executions WHERE build_id = ? AND command_id = ?+ `).get(build, command) as Row | undefined;+ if (row === undefined) throw new Error(`Command execution ${build}/${command} was not started`);+ const current = parseCommandExecution(row);+ if (current.status === "completed") return current;+ this.#database.prepare(`+ UPDATE hypit_command_executions SET status = 'completed', event_json = ?+ WHERE build_id = ? AND command_id = ? AND status = 'started'+ `).run(JSON.stringify(event), build, command);+ return parseCommandExecution(this.#database.prepare(`+ SELECT * FROM hypit_command_executions WHERE build_id = ? AND command_id = ?+ `).get(build, command) as Row);+ });+ }++ async list(build: string): Promise<readonly CommandExecutionReceipt[]> {+ return (this.#database.prepare(`+ SELECT * FROM hypit_command_executions WHERE build_id = ? ORDER BY command_id ASC+ `).all(build) as Row[]).map(parseCommandExecution);+ }++ async removeBuild(build: string): Promise<void> {+ this.#database.prepare("DELETE FROM hypit_command_executions WHERE build_id = ?").run(build);+ }+}++class SqliteRuntimeWorkerLeaseStore implements RuntimeWorkerLeaseStore {+ readonly #database: DatabaseSync;++ constructor(database: DatabaseSync) {+ this.#database = database;+ }++ async read(): Promise<RuntimeWorkerLease | undefined> {+ const row = this.#database.prepare("SELECT * FROM hypit_worker_lease WHERE singleton = 1").get() as Row | undefined;+ if (row === undefined) return undefined;+ assert(typeof row.owner_id === "string" && typeof row.pid === "number"+ && typeof row.acquired_at === "number" && typeof row.expires_at === "number",+ "SQLite Runtime Worker lease is invalid");+ return {+ owner: row.owner_id,+ pid: row.pid,+ acquiredAt: row.acquired_at,+ expiresAt: row.expires_at,+ };+ }++ async acquire(request: RuntimeWorkerLease): Promise<boolean> {+ positiveInteger(request.pid, "Runtime Worker pid");+ nonNegativeInteger(request.acquiredAt, "Runtime Worker acquisition time");+ assert(request.owner.trim().length > 0, "Runtime Worker owner is empty");+ assert(Number.isSafeInteger(request.expiresAt) && request.expiresAt > request.acquiredAt,+ "Runtime Worker lease expiration is invalid");+ return transaction(this.#database, () => {+ const row = this.#database.prepare(+ "SELECT owner_id, pid, expires_at FROM hypit_worker_lease WHERE singleton = 1",+ ).get() as Row | undefined;+ if (row !== undefined) {+ assert(typeof row.owner_id === "string" && typeof row.pid === "number"+ && typeof row.expires_at === "number", "SQLite Runtime Worker lease is invalid");+ if (row.owner_id === request.owner && row.pid === request.pid) return true;+ if (row.expires_at > request.acquiredAt) return false;}- : {};- const result = typeof row.result_directory !== "string"- ? undefined- : (() => {- try {- const parsed = JSON.parse(row.result_directory) as Partial<NonNullable<BuildDispatchSnapshot["result"]>>;- if (typeof parsed.root === "string" && parsed.selection !== undefined- && typeof parsed.selection.use === "string") {- return parsed as NonNullable<BuildDispatchSnapshot["result"]>;- }- } catch {- // Dispatches queued by the previous filesystem-only implementation stored one directory.- }- return {- root: dirname(row.result_directory),- selection: { use: "@hypit/build-result-fs", config: { path: "." } },- } satisfies NonNullable<BuildDispatchSnapshot["result"]>;- })();- const snapshot = {- build: row.build_id,- componentPackages,- ...(result === undefined ? {} : { result }),+ this.#database.prepare(`+ INSERT INTO hypit_worker_lease (singleton, owner_id, pid, acquired_at, expires_at)+ VALUES (1, ?, ?, ?, ?)+ ON CONFLICT(singleton) DO UPDATE SET+ owner_id = excluded.owner_id,+ pid = excluded.pid,+ acquired_at = excluded.acquired_at,+ expires_at = excluded.expires_at+ `).run(request.owner, request.pid, request.acquiredAt, request.expiresAt);+ return true;+ });+ }++ async renew(owner: string, pid: number, expiresAt: number): Promise<boolean> {+ const result = this.#database.prepare(`+ UPDATE hypit_worker_lease SET expires_at = ?+ WHERE singleton = 1 AND owner_id = ? AND pid = ?+ `).run(expiresAt, owner, pid);+ return result.changes === 1;+ }++ async release(owner: string, pid: number): Promise<void> {+ this.#database.prepare(+ "DELETE FROM hypit_worker_lease WHERE singleton = 1 AND owner_id = ? AND pid = ?",+ ).run(owner, pid);+ }+}++class SqliteRuntimeEnvironmentStore implements RuntimeEnvironmentStore {+ readonly #database: DatabaseSync;++ constructor(database: DatabaseSync) {+ this.#database = database;+ }++ async use(config: string): Promise<void> {+ assert(config.length > 0, "Runtime environment configuration is empty");+ transaction(this.#database, () => {+ const active = this.#database.prepare(+ `SELECT+ (SELECT COUNT(*) FROM hypit_submissions)+ + (SELECT COUNT(*) FROM hypit_executions) AS count`,+ ).get() as Row;+ assert(typeof active.count === "number", "SQLite active Runtime work count is invalid");+ const row = this.#database.prepare(+ "SELECT config_json FROM hypit_runtime_environment WHERE singleton = 1",+ ).get() as Row | undefined;+ if (active.count > 0) {+ assert(typeof row?.config_json === "string",+ "Active Runtime work has no recorded environment; use its original Profile or resolve it explicitly");+ assert(row.config_json === config,+ "Runtime Profile differs from the environment pinned by active Builds");+ return;+ }+ this.#database.prepare(`+ INSERT INTO hypit_runtime_environment (singleton, config_json) VALUES (1, ?)+ ON CONFLICT(singleton) DO UPDATE SET config_json = excluded.config_json+ `).run(config);+ });+ }++ async assert(config: string): Promise<void> {+ const row = this.#database.prepare(+ "SELECT config_json FROM hypit_runtime_environment WHERE singleton = 1",+ ).get() as Row | undefined;+ assert(typeof row?.config_json === "string" && row.config_json === config,+ "Runtime Profile no longer matches this Worker's active environment");+ }+}+++function parseExecutionSnapshot(row: Row): BuildExecutionSnapshot {+ assert(typeof row.created_at === "number", "SQLite Execution creation time is invalid");+ assert(typeof row.wake_at === "number", "SQLite Execution wake time is invalid");+ assert((row.turn_owner === null && row.turn_acquired_at === null)+ || (typeof row.turn_owner === "string" && typeof row.turn_acquired_at === "number"),+ "SQLite Execution turn is invalid");+ assert((row.result_writer_owner === null && row.result_writer_acquired_at === null)+ || (typeof row.result_writer_owner === "string" && typeof row.result_writer_acquired_at === "number"),+ "SQLite Result-writer lease is invalid");+ assert((row.decision_outcome === null && row.decision_reason === null)+ || (row.decision_outcome === "complete" || row.decision_outcome === "failed" || row.decision_outcome === "cancelled"),+ "SQLite Execution decision is invalid");+ assert((row.attention_step === null && row.attention_error === null)+ || ((row.attention_step === "result" || row.attention_step === "cleanup")+ && typeof row.attention_error === "string"),+ "SQLite Execution attention is invalid");+ return {+ ...parseExecutionRequest(row, "Execution"),createdAt: row.created_at,- availableAt: row.available_at,- phase: row.phase,- ...(typeof row.reason === "string" ? { reason: row.reason } : {}),- ...cancellation,- ...(typeof row.terminal === "string" ? { terminal: row.terminal } : {}),- } as BuildDispatchSnapshot;- return snapshot;+ wakeAt: row.wake_at,+ ...(typeof row.turn_owner === "string" ? {+ turn: { owner: row.turn_owner, acquiredAt: row.turn_acquired_at as number },+ } : {}),+ ...(typeof row.result_writer_owner === "string" ? {+ resultWrite: { owner: row.result_writer_owner, acquiredAt: row.result_writer_acquired_at as number },+ } : {}),+ ...(row.cancel_requested === 1 ? {+ cancellation: {+ ...(typeof row.cancellation_reason === "string" ? { reason: row.cancellation_reason } : {}),+ },+ } : {}),+ ...(typeof row.decision_outcome === "string" ? {+ decision: {+ outcome: row.decision_outcome as "complete" | "failed" | "cancelled",+ ...(typeof row.decision_reason === "string" ? { reason: row.decision_reason } : {}),+ },+ } : {}),+ ...(typeof row.attention_step === "string" ? {+ attention: {+ step: row.attention_step as "result" | "cleanup",+ error: row.attention_error as string,+ },+ } : {}),+ };}-class SqliteBuildDispatchStore implements BuildDispatchStore {+class SqliteBuildExecutionStore implements BuildExecutionStore {readonly #database: DatabaseSync;constructor(database: DatabaseSync) {@@ -386,131 +682,208 @@ class SqliteBuildDispatchStore implements BuildDispatchStore {}async create(- request: BuildDispatchRequest,+ request: BuildExecutionRequest,options: { readonly now?: number } = {},- ): Promise<BuildDispatchSnapshot> {+ ): Promise<BuildExecutionSnapshot> {const now = options.now ?? Date.now();- nonNegativeInteger(now, "Dispatch creation time");+ nonNegativeInteger(now, "Execution creation time");this.#database.prepare(`- INSERT INTO hypit_dispatches (- build_id, component_packages_json, result_directory, created_at, available_at,- phase, reason, cancel_requested, terminal- ) VALUES (?, ?, ?, ?, ?, 'queued', NULL, 0, NULL)- `).run(request.build, JSON.stringify(request.componentPackages), request.result === undefined ? null : JSON.stringify(request.result), now, now);+ INSERT INTO hypit_executions (+ build_id, component_packages_json, result_location_json, created_at, wake_at,+ turn_owner, turn_acquired_at, result_writer_owner, result_writer_acquired_at,+ cancel_requested, cancellation_reason,+ decision_outcome, decision_reason, attention_step, attention_error+ ) VALUES (?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, 0, NULL, NULL, NULL, NULL, NULL)+ `).run(request.build, JSON.stringify(request.componentPackages), JSON.stringify(request.result), now, now);return {...copy(request),createdAt: now,- availableAt: now,- phase: "queued",+ wakeAt: now,};}- async read(build: string): Promise<BuildDispatchSnapshot | undefined> {- const row = this.#database.prepare("SELECT * FROM hypit_dispatches WHERE build_id = ?").get(build) as Row | undefined;- return row === undefined ? undefined : parseDispatchSnapshot(row);+ async read(build: string): Promise<BuildExecutionSnapshot | undefined> {+ const row = this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row | undefined;+ return row === undefined ? undefined : parseExecutionSnapshot(row);}- async list(query: DispatchQuery = {}): Promise<readonly BuildDispatchSnapshot[]> {+ async list(): Promise<readonly BuildExecutionSnapshot[]> {const rows = this.#database.prepare(`- SELECT * FROM hypit_dispatches+ SELECT * FROM hypit_executionsORDER BY created_at ASC, build_id ASC`).all() as Row[];- return rows.map(parseDispatchSnapshot)- .filter((item) => query.phases === undefined || query.phases.includes(item.phase));+ return rows.map(parseExecutionSnapshot);}- async claim(now = Date.now()): Promise<BuildDispatchSnapshot | undefined> {- nonNegativeInteger(now, "Dispatch claim time");+ async claim(owner: string, now = Date.now()): Promise<BuildExecutionSnapshot | undefined> {+ assert(owner.trim().length > 0, "Execution turn owner is empty");+ nonNegativeInteger(now, "Execution claim time");return transaction(this.#database, () => {const row = this.#database.prepare(`- SELECT build_id FROM hypit_dispatches- WHERE phase IN ('queued', 'waiting') AND available_at <= ?- ORDER BY available_at ASC, created_at ASC, build_id ASC+ SELECT build_id FROM hypit_executions+ WHERE decision_outcome IS NULL AND turn_owner IS NULL AND wake_at <= ?+ ORDER BY wake_at ASC, created_at ASC, build_id ASCLIMIT 1`).get(now) as Row | undefined;if (row === undefined) return undefined;- assert(typeof row.build_id === "string", "SQLite ready Dispatch has no Build id");+ assert(typeof row.build_id === "string", "SQLite ready Execution has no Build id");const updated = this.#database.prepare(`- UPDATE hypit_dispatches- SET phase = 'running'- WHERE build_id = ? AND phase IN ('queued', 'waiting') AND available_at <= ?- `).run(row.build_id, now);+ UPDATE hypit_executions+ SET turn_owner = ?, turn_acquired_at = ?+ WHERE build_id = ? AND decision_outcome IS NULL AND turn_owner IS NULL AND wake_at <= ?+ `).run(owner, now, row.build_id, now);if (updated.changes !== 1) return undefined;- return parseDispatchSnapshot(- this.#database.prepare("SELECT * FROM hypit_dispatches WHERE build_id = ?").get(row.build_id) as Row,+ return parseExecutionSnapshot(+ this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(row.build_id) as Row,);});}- async release(build: string, update: BuildDispatchRelease): Promise<BuildDispatchSnapshot> {- nonNegativeInteger(update.availableAt, "Dispatch release availableAt");+ async releaseTurn(build: string, owner: string, wakeAt: number): Promise<BuildExecutionSnapshot> {+ nonNegativeInteger(wakeAt, "Execution wakeAt");return transaction(this.#database, () => {- const row = this.#database.prepare("SELECT * FROM hypit_dispatches WHERE build_id = ?").get(build) as Row | undefined;- if (row === undefined) throw new Error(`Dispatch ${build} does not exist`);- const current = parseDispatchSnapshot(row);- if (current.phase === "terminal") return current;+ const row = this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row | undefined;+ if (row === undefined) throw new Error(`Execution ${build} does not exist`);+ const current = parseExecutionSnapshot(row);+ assert(current.decision === undefined, `Execution ${build} already has a decision`);+ assert(current.turn?.owner === owner, `Execution ${build} is not owned by ${owner}`);if (current.cancellation !== undefined) return current;- assert(current.phase === "running", `Dispatch ${build} is not running`);this.#database.prepare(`- UPDATE hypit_dispatches- SET phase = ?, available_at = ?, reason = ?- WHERE build_id = ?- `).run(update.phase, update.availableAt, update.reason ?? null, build);- return parseDispatchSnapshot(- this.#database.prepare("SELECT * FROM hypit_dispatches WHERE build_id = ?").get(build) as Row,+ UPDATE hypit_executions+ SET turn_owner = NULL, turn_acquired_at = NULL, wake_at = ?+ WHERE build_id = ? AND turn_owner = ?+ `).run(wakeAt, build, owner);+ return parseExecutionSnapshot(+ this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row,);});}- async finish(+ async decide(build: string,- terminal: "complete" | "failed" | "cancelled",+ owner: string,+ outcome: "complete" | "failed" | "cancelled",reason?: string,- ): Promise<BuildDispatchSnapshot> {+ ): Promise<BuildExecutionSnapshot> {return transaction(this.#database, () => {- const row = this.#database.prepare("SELECT * FROM hypit_dispatches WHERE build_id = ?").get(build) as Row | undefined;- if (row === undefined) throw new Error(`Dispatch ${build} does not exist`);- const current = parseDispatchSnapshot(row);- if (current.phase === "terminal") return current;- const effective = current.cancellation === undefined ? terminal : "cancelled";+ const row = this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row | undefined;+ if (row === undefined) throw new Error(`Execution ${build} does not exist`);+ const current = parseExecutionSnapshot(row);+ const effective = current.cancellation === undefined ? outcome : "cancelled";+ const effectiveReason = effective === "cancelled"+ ? current.cancellation?.reason ?? reason+ : reason;+ if (current.decision !== undefined) {+ assert(current.decision.outcome === effective && current.decision.reason === effectiveReason,+ `Execution ${build} already has a different decision`);+ return current;+ }+ assert(current.turn?.owner === owner, `Execution ${build} is not owned by ${owner}`);this.#database.prepare(`- UPDATE hypit_dispatches- SET phase = 'terminal', terminal = ?, reason = ?,- component_packages_json = '[]', result_directory = NULL+ UPDATE hypit_executions+ SET decision_outcome = ?, decision_reason = ?, turn_owner = NULL, turn_acquired_at = NULL,+ attention_step = NULL, attention_error = NULL+ WHERE build_id = ? AND turn_owner = ? AND decision_outcome IS NULL+ `).run(effective, effectiveReason ?? null, build, owner);+ return parseExecutionSnapshot(+ this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row,+ );+ });+ }++ async setAttention(+ build: string,+ attention: BuildExecutionSnapshot["attention"],+ ): Promise<BuildExecutionSnapshot> {+ return transaction(this.#database, () => {+ const row = this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row | undefined;+ if (row === undefined) throw new Error(`Execution ${build} does not exist`);+ const current = parseExecutionSnapshot(row);+ assert(current.decision !== undefined, `Execution ${build} has no decision`);+ this.#database.prepare(`+ UPDATE hypit_executions+ SET attention_step = ?, attention_error = ?WHERE build_id = ?- `).run(effective, reason ?? current.cancellation?.reason ?? null, build);- return parseDispatchSnapshot(- this.#database.prepare("SELECT * FROM hypit_dispatches WHERE build_id = ?").get(build) as Row,+ `).run(attention?.step ?? null, attention?.error ?? null, build);+ return parseExecutionSnapshot(+ this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row,);});}- async requestCancellation(build: string, reason?: string): Promise<BuildDispatchSnapshot> {- const now = Date.now();+ async claimResultWrite(+ build: string,+ owner: string,+ now = Date.now(),+ ): Promise<BuildExecutionSnapshot | undefined> {+ assert(owner.trim().length > 0, "Result-writer owner is empty");+ nonNegativeInteger(now, "Result-writer acquisition time");return transaction(this.#database, () => {- const row = this.#database.prepare("SELECT * FROM hypit_dispatches WHERE build_id = ?").get(build) as Row | undefined;- if (row === undefined) throw new Error(`Dispatch ${build} does not exist`);- const current = parseDispatchSnapshot(row);- if (current.phase === "terminal") return current;- if (current.cancellation !== undefined) return current;- if (current.phase === "queued") {- this.#database.prepare(`- UPDATE hypit_dispatches- SET phase = 'terminal', terminal = 'cancelled',- reason = ?, cancel_requested = 1- WHERE build_id = ?- `).run(reason ?? "cancelled before execution", build);- } else {+ const updated = this.#database.prepare(`+ UPDATE hypit_executions+ SET result_writer_owner = ?, result_writer_acquired_at = ?,+ attention_step = NULL, attention_error = NULL+ WHERE build_id = ? AND decision_outcome IS NOT NULL AND result_writer_owner IS NULL+ `).run(owner, now, build);+ if (updated.changes !== 1) return undefined;+ return parseExecutionSnapshot(+ this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row,+ );+ });+ }++ async releaseResultWrite(build: string, owner: string): Promise<BuildExecutionSnapshot> {+ return transaction(this.#database, () => {+ const updated = this.#database.prepare(`+ UPDATE hypit_executions+ SET result_writer_owner = NULL, result_writer_acquired_at = NULL+ WHERE build_id = ? AND result_writer_owner = ?+ `).run(build, owner);+ assert(updated.changes === 1, `Execution ${build} Result writer is not owned by ${owner}`);+ return parseExecutionSnapshot(+ this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row,+ );+ });+ }++ async reclaimResultWrites(): Promise<readonly string[]> {+ return transaction(this.#database, () => {+ const rows = this.#database.prepare(+ "SELECT build_id FROM hypit_executions WHERE result_writer_owner IS NOT NULL",+ ).all() as Row[];+ const builds = rows.map((row) => {+ assert(typeof row.build_id === "string", "SQLite Result-writer lease has no Build id");+ return row.build_id;+ });+ for (const build of builds) {this.#database.prepare(`- UPDATE hypit_dispatches- SET phase = CASE WHEN phase = 'running' THEN phase ELSE 'queued' END,- available_at = CASE WHEN phase = 'running' THEN available_at ELSE ? END,- reason = ?, cancel_requested = 1- WHERE build_id = ?- `).run(now, reason ?? "cancellation requested", build);+ UPDATE hypit_executions+ SET result_writer_owner = NULL, result_writer_acquired_at = NULL,+ attention_step = 'result',+ attention_error = 'Result writing was interrupted; run hypit result finish <build-id>'+ WHERE build_id = ? AND result_writer_owner IS NOT NULL+ `).run(build);}- return parseDispatchSnapshot(- this.#database.prepare("SELECT * FROM hypit_dispatches WHERE build_id = ?").get(build) as Row,+ return builds;+ });+ }++ async requestCancellation(build: string, reason?: string): Promise<BuildExecutionSnapshot> {+ const now = Date.now();+ return transaction(this.#database, () => {+ const row = this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row | undefined;+ if (row === undefined) throw new Error(`Execution ${build} does not exist`);+ const current = parseExecutionSnapshot(row);+ if (current.cancellation !== undefined) return current;+ if (current.decision !== undefined) return current;+ this.#database.prepare(`+ UPDATE hypit_executions+ SET wake_at = CASE WHEN turn_owner IS NULL THEN ? ELSE wake_at END,+ cancellation_reason = ?, cancel_requested = 1+ WHERE build_id = ?+ `).run(now, reason ?? null, build);+ return parseExecutionSnapshot(+ this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row,);});}@@ -540,7 +913,7 @@ class SqliteBuildDispatchStore implements BuildDispatchStore {WHERE json_extract(claim.value, '$.id') = ?`).get(resource.id) as Row;assert(typeof count.count === "number", `SQLite Capacity count for ${resource.id} is invalid`);- if (count.count >= resource.maxInFlight) {+ if (count.count >= resource.limit) {return {status: "blocked",availableAt: request.now + 250,@@ -574,24 +947,23 @@ class SqliteBuildDispatchStore implements BuildDispatchStore {this.#database.prepare("DELETE FROM hypit_capacity WHERE build_id = ?").run(build);}- async reclaimAbandoned(now = Date.now()): Promise<readonly string[]> {- nonNegativeInteger(now, "Dispatch reclaim time");+ async reclaimTurns(now = Date.now()): Promise<readonly string[]> {+ nonNegativeInteger(now, "Execution turn reclaim time");return transaction(this.#database, () => {const rows = this.#database.prepare(- "SELECT build_id FROM hypit_dispatches WHERE phase = 'running'",+ "SELECT build_id FROM hypit_executions WHERE turn_owner IS NOT NULL AND decision_outcome IS NULL",).all() as Row[];const builds = rows.map((row) => {- assert(typeof row.build_id === "string", "SQLite running Dispatch has no Build id");+ assert(typeof row.build_id === "string", "SQLite owned Execution has no Build id");return row.build_id;});- for (const build of builds) {- // The reservation outlived the process that would have released it, and the lane it holds- // is counted against every later Build. Drop it, then make the Dispatch claimable again so- // the work — or its cancellation — can actually be carried out.- this.#database.prepare("DELETE FROM hypit_capacity WHERE build_id = ?").run(build);- this.#database.prepare(- "UPDATE hypit_dispatches SET phase = 'queued', available_at = ? WHERE build_id = ?",- ).run(now, build);+ for (const row of rows) {+ assert(typeof row.build_id === "string", "SQLite active Execution is invalid");+ this.#database.prepare(`+ UPDATE hypit_executions+ SET turn_owner = NULL, turn_acquired_at = NULL, wake_at = ?+ WHERE build_id = ? AND decision_outcome IS NULL+ `).run(now, row.build_id);}return builds;});@@ -608,10 +980,16 @@ function parseCapacityReservation(row: Row): CapacityReservation {assert(typeof row.build_id === "string" && typeof row.command_id === "string"&& typeof row.resources_json === "string"&& typeof row.created_at === "number", "SQLite Capacity row is invalid");+ const storedResources = JSON.parse(row.resources_json) as readonly Readonly<Record<string, unknown>>[];+ const resources = storedResources.map((resource) => {+ assert(typeof resource.id === "string", "SQLite Capacity resource has no id");+ assert(typeof resource.limit === "number", `SQLite Capacity resource ${resource.id} has no limit`);+ return { id: resource.id, limit: positiveInteger(resource.limit, `resource ${resource.id} limit`) };+ });const value = {build: row.build_id,command: row.command_id,- resources: JSON.parse(row.resources_json) as CapacityReservation["resources"],+ resources,...(typeof row.queue_json === "string"? { queue: JSON.parse(row.queue_json) as NonNullable<CapacityReservation["queue"]> }: {}),@@ -624,8 +1002,12 @@ export class SqliteRuntimeState {readonly path: string;readonly builds: BuildStore;readonly operations: OperationStore;- readonly dispatch: BuildDispatchStore;+ readonly commandExecutions: CommandExecutionStore;+ readonly execution: BuildExecutionStore;readonly catalog: BuildCatalog;+ readonly workerLease: RuntimeWorkerLeaseStore;+ readonly environment: RuntimeEnvironmentStore;+ readonly submissions: PendingBuildStore;readonly #database: DatabaseSync;constructor(path: string, options: SqliteRuntimeStateOptions = {}) {@@ -667,24 +1049,48 @@ export class SqliteRuntimeState {status TEXT NOT NULL CHECK (status IN ('pending', 'completed', 'failed', 'cancelled')),payload_json TEXT) STRICT;+ CREATE TABLE IF NOT EXISTS hypit_command_executions (+ build_id TEXT NOT NULL,+ command_id TEXT NOT NULL,+ status TEXT NOT NULL CHECK (status IN ('started', 'completed')),+ event_json TEXT,+ PRIMARY KEY (build_id, command_id)+ ) STRICT;CREATE TABLE IF NOT EXISTS hypit_build_catalog (build_id TEXT PRIMARY KEY,created_at INTEGER NOT NULL,descriptor_json TEXT NOT NULL) STRICT;- CREATE TABLE IF NOT EXISTS hypit_dispatches (+ CREATE TABLE IF NOT EXISTS hypit_submissions (+ build_id TEXT PRIMARY KEY,+ component_packages_json TEXT NOT NULL,+ result_location_json TEXT NOT NULL,+ created_at INTEGER NOT NULL+ ) STRICT;+ CREATE TABLE IF NOT EXISTS hypit_executions (build_id TEXT PRIMARY KEY,component_packages_json TEXT NOT NULL,- result_directory TEXT,+ result_location_json TEXT NOT NULL,created_at INTEGER NOT NULL,- available_at INTEGER NOT NULL,- phase TEXT NOT NULL CHECK (phase IN ('queued', 'running', 'waiting', 'terminal')),- reason TEXT,+ wake_at INTEGER NOT NULL,+ turn_owner TEXT,+ turn_acquired_at INTEGER,+ result_writer_owner TEXT,+ result_writer_acquired_at INTEGER,cancel_requested INTEGER NOT NULL DEFAULT 0 CHECK (cancel_requested IN (0, 1)),- terminal TEXT CHECK (terminal IS NULL OR terminal IN ('complete', 'failed', 'cancelled'))+ cancellation_reason TEXT,+ decision_outcome TEXT CHECK (+ decision_outcome IS NULL OR decision_outcome IN ('complete', 'failed', 'cancelled')+ ),+ decision_reason TEXT,+ attention_step TEXT CHECK (attention_step IS NULL OR attention_step IN ('result', 'cleanup')),+ attention_error TEXT,+ CHECK ((turn_owner IS NULL) = (turn_acquired_at IS NULL)),+ CHECK ((result_writer_owner IS NULL) = (result_writer_acquired_at IS NULL)),+ CHECK ((attention_step IS NULL) = (attention_error IS NULL))) STRICT;- CREATE INDEX IF NOT EXISTS hypit_dispatch_ready- ON hypit_dispatches (phase, available_at);+ CREATE INDEX IF NOT EXISTS hypit_execution_ready+ ON hypit_executions (decision_outcome, turn_owner, wake_at);CREATE TABLE IF NOT EXISTS hypit_capacity (build_id TEXT NOT NULL,command_id TEXT NOT NULL,@@ -693,18 +1099,52 @@ export class SqliteRuntimeState {created_at INTEGER NOT NULL,PRIMARY KEY (build_id, command_id)) STRICT;+ CREATE TABLE IF NOT EXISTS hypit_worker_lease (+ singleton INTEGER PRIMARY KEY CHECK (singleton = 1),+ owner_id TEXT NOT NULL,+ pid INTEGER NOT NULL,+ acquired_at INTEGER NOT NULL,+ expires_at INTEGER NOT NULL+ ) STRICT;+ CREATE TABLE IF NOT EXISTS hypit_runtime_environment (+ singleton INTEGER PRIMARY KEY CHECK (singleton = 1),+ config_json TEXT NOT NULL+ ) STRICT;`);- if (!options.readOnly || emptyReadOnly) {- const dispatchColumns = new Set((this.#database.prepare("PRAGMA table_info(hypit_dispatches)").all() as Row[])- .flatMap((row) => typeof row.name === "string" ? [row.name] : []));- if (!dispatchColumns.has("result_directory")) {- this.#database.exec("ALTER TABLE hypit_dispatches ADD COLUMN result_directory TEXT");- }- }this.builds = new SqliteBuildStore(database);this.operations = new SqliteOperationStore(database);- this.dispatch = new SqliteBuildDispatchStore(database);+ const legacy = this.#database.prepare(+ "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'hypit_dispatches'",+ ).get() as Row | undefined;+ if (legacy !== undefined) {+ const count = this.#database.prepare("SELECT COUNT(*) AS count FROM hypit_dispatches").get() as Row;+ assert(count.count === 0,+ "This Runtime contains legacy Dispatch rows; they require an explicit project migration");+ }+ this.commandExecutions = new SqliteCommandExecutionStore(database);+ this.execution = new SqliteBuildExecutionStore(database);this.catalog = new SqliteBuildCatalog(database);+ this.workerLease = new SqliteRuntimeWorkerLeaseStore(database);+ this.environment = new SqliteRuntimeEnvironmentStore(database);+ this.submissions = new SqlitePendingBuildStore(database);+ }++ /** Remove the complete active Runtime aggregate in one transaction, deleting its root last. */+ async removeActiveBuild(build: string): Promise<import("@hypit/runtime").BuildCompletion> {+ return transaction(this.#database, () => {+ const row = this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row | undefined;+ if (row === undefined) throw new Error(`Execution ${build} does not exist`);+ const current = parseExecutionSnapshot(row);+ assert(current.decision !== undefined, `Execution ${build} has no decision`);+ this.#database.prepare("DELETE FROM hypit_capacity WHERE build_id = ?").run(build);+ this.#database.prepare("DELETE FROM hypit_operations WHERE build_id = ?").run(build);+ this.#database.prepare("DELETE FROM hypit_command_executions WHERE build_id = ?").run(build);+ this.#database.prepare("DELETE FROM hypit_build_facts WHERE build_id = ?").run(build);+ this.#database.prepare("DELETE FROM hypit_build_catalog WHERE build_id = ?").run(build);+ this.#database.prepare("DELETE FROM hypit_builds WHERE build_id = ?").run(build);+ this.#database.prepare("DELETE FROM hypit_executions WHERE build_id = ?").run(build);+ return { build, ...current.decision };+ });}close(): void {diff --git a/packages/store-sqlite/test/store.test.ts b/packages/store-sqlite/test/store.test.tsindex 241a6228..64f30e3e 100644--- a/packages/store-sqlite/test/store.test.ts+++ b/packages/store-sqlite/test/store.test.ts@@ -8,13 +8,29 @@ import { SqliteRuntimeState } from "@hypit/store-sqlite";import { createGreetingBuild } from "../../core/test/greeting-fixture.js";-test("read-only SQLite observation of an absent archive creates no file", async () => {+const resultLocation = {+ root: "/project",+ selection: { use: "@hypit/build-result-fs", config: { path: ".hypit/results" } },+} as const;++function definition(state: ReturnType<typeof createGreetingBuild>) {+ const authored = new Set(state.program.records.map((record) => record.id));+ return defineBuild({+ program: state.program,+ initialRecords: state.records.filter((record) => !authored.has(record.id)),+ plan: state.plan,+ targets: state.targets,+ });+}++test("read-only SQLite observation of an absent Runtime creates no file", async () => {const directory = await mkdtemp(join(tmpdir(), "hypit-sqlite-read-only-"));const path = join(directory, ".hypit", "runtime.sqlite");try {const state = new SqliteRuntimeState(path, { readOnly: true });assert.equal(await state.builds.read("missing"), undefined);- assert.deepEqual(await state.dispatch.list(), []);+ assert.deepEqual(await state.execution.list(), []);+ assert.deepEqual(await state.submissions.list(), []);state.close();await assert.rejects(stat(path), (error: unknown) =>error instanceof Error && "code" in error && error.code === "ENOENT");@@ -22,23 +38,24 @@ test("read-only SQLite observation of an absent archive creates no file", asyncawait rm(directory, { recursive: true, force: true });}});+test("SQLite stores verified Build facts and Operation handles across reopen", async () => {const directory = await mkdtemp(join(tmpdir(), "hypit-sqlite-"));const path = join(directory, "runtime.sqlite");try {const first = new SqliteRuntimeState(path);const initial = createGreetingBuild();- const definition = defineBuild(initial.program, initial.graph, initial.request);- await first.builds.create("video", definition);+ const buildDefinition = definition(initial);+ await first.builds.create("video", buildDefinition);const catalog = {source: { path: "/project/main.svml" },- aliases: [{+ publishedOutputs: [{name: "final.video",- ref: { kind: "logical-output", id: initial.request.targets[0]!.output },+ ref: { kind: "logical-output", id: initial.targets[0]!.output },}],} as const;await first.catalog.record("video", catalog);- assert.equal((await first.catalog.read("video"))?.aliases[0]?.name, "final.video");+ assert.equal((await first.catalog.read("video"))?.publishedOutputs[0]?.name, "final.video");const operation = {id: "operation:generation",build: "video",@@ -58,8 +75,7 @@ test("SQLite stores verified Build facts and Operation handles across reopen", aconst second = new SqliteRuntimeState(path);assert.equal((await second.builds.read("video"))?.state.status, initial.status);- assert.equal((await second.catalog.read("video"))?.aliases[0]?.name, "final.video");- assert.deepEqual((await second.catalog.list()).map((item) => item.build), ["video"]);+ assert.equal((await second.catalog.read("video"))?.publishedOutputs[0]?.name, "final.video");const restoredOperation = await second.operations.read(operation.id);assert.equal(restoredOperation?.status, "pending");assert.deepEqual(restoredOperation?.handle, { remoteJob: "job-1" });@@ -67,7 +83,7 @@ test("SQLite stores verified Build facts and Operation handles across reopen", aassert.deepEqual(restoredOperation?.progress, { phase: "generating" });assert.deepEqual((await second.operations.list({ build: "video" })).map((item) => item.id), [operation.id]);- const machine = new BuildMachine(definition);+ const machine = new BuildMachine(buildDefinition);const command = machine.commands()[0]!;const content = { kind: "command-failed", command: command.id, code: "TEST", message: "test" } as const;const fact = machine.evaluate(content)!;@@ -108,28 +124,37 @@ test("SQLite Operation updates preserve a terminal completion", async () => {await rm(directory, { recursive: true, force: true });}});-test("cancelling a never-claimed Build atomically withdraws it from dispatch", async () => {- const directory = await mkdtemp(join(tmpdir(), "hypit-sqlite-cancel-queued-"));++test("Submission is separate from execution and only commit or exact discard removes it", async () => {+ const directory = await mkdtemp(join(tmpdir(), "hypit-sqlite-submission-owner-"));try {const state = new SqliteRuntimeState(join(directory, "runtime.sqlite"));- await state.dispatch.create({ build: "queued-build", componentPackages: [] }, { now: 100 });+ const initial = createGreetingBuild();+ await state.builds.create("existing-build", definition(initial));- const cancelled = await state.dispatch.requestCancellation("queued-build", "no longer needed");- assert.equal(cancelled.phase, "terminal");- assert.equal(cancelled.terminal, "cancelled");- assert.equal(cancelled.cancellation?.reason, "no longer needed");- assert.equal(await state.dispatch.claim(102), undefined);- assert.deepEqual(await state.dispatch.list({ phases: ["queued", "running", "waiting"] }), []);+ await assert.rejects(+ state.submissions.prepare({ build: "existing-build", componentPackages: [], result: resultLocation }),+ /already has Runtime state/u,+ );+ await state.submissions.discard("existing-build");+ assert.notEqual(await state.builds.read("existing-build"), undefined);- const repeated = await state.dispatch.requestCancellation("queued-build", "second reason");- assert.deepEqual(repeated, cancelled);+ const submission = await state.submissions.prepare({+ build: "new-build",+ componentPackages: ["example.component@1"],+ result: resultLocation,+ }, { now: 100 });+ assert.equal(submission.createdAt, 100);+ assert.equal(await state.execution.read("new-build"), undefined);+ await state.submissions.discard("new-build");+ assert.equal(await state.submissions.read("new-build"), undefined);state.close();} finally {await rm(directory, { recursive: true, force: true });}});-test("a queued Build retains its exact Build Result repository selection", async () => {+test("Execution stores scheduling facts, one decision and independent operator attention", async () => {const directory = await mkdtemp(join(tmpdir(), "hypit-sqlite-result-location-"));try {const state = new SqliteRuntimeState(join(directory, "runtime.sqlite"));@@ -140,15 +165,89 @@ test("a queued Build retains its exact Build Result repository selection", asyncconfig: { bucket: "video-results", prefix: "projects/episode-12" },},} as const;- await state.dispatch.create(- {- build: "queued-build",- componentPackages: ["example.component@1"],- result,- },- { now: 100 },+ const initial = createGreetingBuild();+ const buildDefinition = definition(initial);+ const request = { build: "queued-build", componentPackages: ["example.component@1"], result } as const;+ await state.submissions.prepare(request, { now: 100 });+ await state.submissions.commit({+ ...request,+ definition: buildDefinition,+ catalog: { source: { path: "/project/main.svml" }, publishedOutputs: [] },+ });+ assert.equal(await state.submissions.read("queued-build"), undefined);+ assert.deepEqual((await state.execution.read("queued-build"))?.result, result);++ const cancelling = await state.execution.requestCancellation("queued-build", "no longer needed");+ assert.equal(cancelling.cancellation?.reason, "no longer needed");+ const claimed = await state.execution.claim("worker-a", Date.now());+ assert.equal(claimed?.turn?.owner, "worker-a");+ const decided = await state.execution.decide("queued-build", "worker-a", "cancelled", "no longer needed");+ assert.deepEqual(decided.decision, { outcome: "cancelled", reason: "no longer needed" });+ assert.equal(await state.execution.claim("worker-b", Date.now() + 60_000), undefined);++ const writing = await state.execution.claimResultWrite("queued-build", "result-writer-a", 200);+ assert.equal(writing?.resultWrite?.owner, "result-writer-a");+ assert.equal(await state.execution.claimResultWrite("queued-build", "result-writer-b", 201), undefined);+ assert.equal((await state.execution.releaseResultWrite("queued-build", "result-writer-a")).resultWrite, undefined);++ const attention = await state.execution.setAttention("queued-build", {+ step: "result",+ error: "store unavailable",+ });+ assert.deepEqual(attention.attention, { step: "result", error: "store unavailable" });+ const completion = await state.removeActiveBuild("queued-build");+ assert.deepEqual(completion, { build: "queued-build", outcome: "cancelled", reason: "no longer needed" });+ assert.equal(await state.execution.read("queued-build"), undefined);+ assert.equal(await state.builds.read("queued-build"), undefined);+ assert.equal(await state.catalog.read("queued-build"), undefined);+ state.close();+ } finally {+ await rm(directory, { recursive: true, force: true });+ }+});++test("Submissions and Executions pin the literal Runtime environment", async () => {+ const directory = await mkdtemp(join(tmpdir(), "hypit-sqlite-environment-"));+ try {+ const state = new SqliteRuntimeState(join(directory, "runtime.sqlite"));+ await state.environment.use('{"endpoints":{"kie":{"region":"us"}}}');+ await state.submissions.prepare({ build: "active-build", componentPackages: [], result: resultLocation }, { now: 100 });+ await assert.rejects(+ state.environment.use('{"endpoints":{"kie":{"region":"eu"}}}'),+ /pinned by active Builds/u,+ );+ await state.environment.assert('{"endpoints":{"kie":{"region":"us"}}}');+ await assert.rejects(+ state.environment.assert('{"endpoints":{"kie":{"region":"eu"}}}'),+ /no longer matches/u,+ );+ state.close();+ } finally {+ await rm(directory, { recursive: true, force: true });+ }+});++test("a new Worker reclaims abandoned turns and Result-writer leases without external work", async () => {+ const directory = await mkdtemp(join(tmpdir(), "hypit-sqlite-turn-reclaim-"));+ try {+ const state = new SqliteRuntimeState(join(directory, "runtime.sqlite"));+ await state.execution.create({ build: "interrupted", componentPackages: [], result: resultLocation }, { now: 100 });+ assert.equal((await state.execution.claim("old-worker", 100))?.turn?.owner, "old-worker");+ assert.deepEqual(await state.execution.reclaimTurns(200), ["interrupted"]);+ assert.equal((await state.execution.read("interrupted"))?.turn, undefined);+ assert.equal((await state.execution.claim("new-worker", 200))?.turn?.owner, "new-worker");+ await state.execution.decide("interrupted", "new-worker", "failed", "provider stopped");+ assert.equal(+ (await state.execution.claimResultWrite("interrupted", "old-result-writer", 201))?.resultWrite?.owner,+ "old-result-writer",);- assert.deepEqual((await state.dispatch.read("queued-build"))?.result, result);+ assert.deepEqual(await state.execution.reclaimResultWrites(), ["interrupted"]);+ const interrupted = await state.execution.read("interrupted");+ assert.equal(interrupted?.resultWrite, undefined);+ assert.deepEqual(interrupted?.attention, {+ step: "result",+ error: "Result writing was interrupted; run hypit result finish <build-id>",+ });state.close();} finally {await rm(directory, { recursive: true, force: true });@@ -159,11 +258,11 @@ test("Pool and Lane limits count only asynchronous Operations still in flight",const directory = await mkdtemp(join(tmpdir(), "hypit-sqlite-hierarchy-"));try {const state = new SqliteRuntimeState(join(directory, "runtime.sqlite"));- const pool = { id: "pool:kie.main", maxActive: 2, maxInFlight: 2 };- const seedance = { id: "lane:kie.main/seedance-2-mini", maxActive: 1, maxInFlight: 1 };- const minimax = { id: "lane:kie.main/minimax-h3", maxActive: 2, maxInFlight: 2 };+ const pool = { id: "pool:kie.main", limit: 2 };+ const seedance = { id: "lane:kie.main/seedance-2-mini", limit: 1 };+ const minimax = { id: "lane:kie.main/minimax-h3", limit: 2 };- const first = await state.dispatch.acquireCapacity({+ const first = await state.execution.acquireCapacity({build: "seedance-a",command: "generate:a",resources: [pool, seedance],@@ -172,7 +271,7 @@ test("Pool and Lane limits count only asynchronous Operations still in flight",});assert.equal(first.status, "acquired");- const sameRoute = await state.dispatch.acquireCapacity({+ const sameRoute = await state.execution.acquireCapacity({build: "seedance-b",command: "generate:b",resources: [pool, seedance],@@ -186,7 +285,7 @@ test("Pool and Lane limits count only asynchronous Operations still in flight",resource: seedance.id,});- const otherRoute = await state.dispatch.acquireCapacity({+ const otherRoute = await state.execution.acquireCapacity({build: "minimax-a",command: "generate:c",resources: [pool, minimax],@@ -196,9 +295,9 @@ test("Pool and Lane limits count only asynchronous Operations still in flight",assert.equal(otherRoute.status, "acquired");if (first.status === "acquired") {- await state.dispatch.releaseCapacity(first.reservation.build, first.reservation.command);+ await state.execution.releaseCapacity(first.reservation.build, first.reservation.command);}- const retried = await state.dispatch.acquireCapacity({+ const retried = await state.execution.acquireCapacity({build: "seedance-b",command: "generate:b",resources: [pool, seedance],diff --git a/packages/studio/README.md b/packages/studio/README.mdindex e81fe00f..e8f1c2f5 100644--- a/packages/studio/README.md+++ b/packages/studio/README.md@@ -15,12 +15,12 @@ When `--runtime` is omitted, Studio uses the nearest Runtime selection made byboundary. The upper-left library is intentionally not a filesystem browser:- Source is the exact Run + Author closure and writes back only the selected file;-- Tasks are read-only Build Catalog/Archive/Dispatch/Operation views;+- Tasks combine finished project Results with read-only active `BuildView` and Operation information;- Artifacts are public files exposed by project Build Results.No project manifest, Studio database, output-directory scan or inferred campaign-folder structure is involved. With no selected Runtime, Source and Preview still-work while Tasks and Artifacts stay explicitly unavailable.+folder structure is involved. With no selected Runtime, Source, Preview, finished+Result tasks and Artifacts still work; only active execution status is unavailable.Studio is an application boundary. Core and domain packages do not import it orregister UI metadata. The installed Distribution explicitly selects one independentdiff --git a/packages/studio/preview-check.ts b/packages/studio/preview-check.tsindex c1d1c960..d95de0f0 100644--- a/packages/studio/preview-check.ts+++ b/packages/studio/preview-check.ts@@ -4,7 +4,7 @@ import { dirname, join, resolve } from "node:path";import { videoCliDistribution } from "@hypit/video-cli";-import { openStudioArchive } from "./src/archive.js";+import { openStudioBuildLibrary } from "./src/build-library.js";import { loadStudioCompanionRegistry } from "./src/companion-profile.js";import { loadStudioDomain } from "./src/domain.js";import { loadStudioRun } from "./src/run.js";@@ -62,7 +62,7 @@ if (runArgument === undefined) {const registry = await loadStudioCompanionRegistry({ workspaceRoot, packageRoot, distributionPackageRoot });const domain = await loadStudioDomain({ run: runPath, workspaceRoot, packageRoot });- const archive = await openStudioArchive(runtimePath, packageRoot, workspaceRoot, distributionPackageRoot);+ const buildLibrary = await openStudioBuildLibrary(runtimePath, packageRoot, workspaceRoot, distributionPackageRoot);const awaitingPrefix = "the Studio projection closure requires unresolved capabilities:";let session: Awaited<ReturnType<typeof readStudioSession>> | undefined;@@ -73,7 +73,7 @@ if (runArgument === undefined) {run: runPath,domain,registry,- ...(archive === undefined ? {} : { archive }),+ ...(buildLibrary === undefined ? {} : { buildLibrary }),});inspectStudioRun(registry, run.source, run);session = await readStudioSession({@@ -81,7 +81,6 @@ if (runArgument === undefined) {registry,run,workspaceRoot,- ...(archive === undefined ? {} : { archive }),revision: 0,});} catch (error) {@@ -93,7 +92,7 @@ if (runArgument === undefined) {refusal = error instanceof Error ? error.message : String(error);}} finally {- await archive?.close();+ await buildLibrary?.close();}if (refusal !== undefined) {diff --git a/packages/studio/src/archive.ts b/packages/studio/src/archive.tsdeleted file mode 100644index 2293bdd8..00000000--- a/packages/studio/src/archive.ts+++ /dev/null@@ -1,243 +0,0 @@-import { isAbsolute, join, relative, resolve, sep } from "node:path";--import type { BuildCatalogEntry } from "@hypit/runtime";-import type { NodeRuntimeHost, RuntimeHostStatus } from "@hypit/runtime-host-node";-import type { StoredValue, TypeRef } from "@hypit/protocol";-import { FileBuildResultRepository } from "@hypit/build-result";-import type {- BuildResultFileRef,- BuildResultJsonValue,- BuildResultRepository,- RepositoryBuildResultOutput,-} from "@hypit/build-result";--import { resolveBuildResultRecord } from "@hypit/cli";-import { videoCliDistribution } from "@hypit/video-cli";--import type { StudioArtifactView, StudioLibraryView, StudioTaskView } from "./shared.js";--type RuntimeArchive = Awaited<ReturnType<NodeRuntimeHost["openArchive"]>>;--export type StudioArchive = {- readonly profile?: string;- readonly runtime?: Pick<RuntimeArchive, "status">;- readonly library: () => Promise<StudioLibraryView>;- readonly resolveBuildRecord: (- build: string,- output: string,- ) => Promise<{- readonly type: TypeRef;- readonly value: StoredValue;- readonly attachments?: readonly import("@hypit/workspace").ArtifactAttachment[];- } | undefined>;- readonly openArtifact: (- build: string,- output: string,- valuePath: string,- ) => Promise<{ readonly mediaType: string; readonly bytes: Uint8Array } | undefined>;- readonly close: () => Promise<void>;-};--function isWithin(root: string, path: string): boolean {- const rel = relative(resolve(root), resolve(path));- return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));-}--/**- * A path inside the project reads the same on every platform, so the Studio library shows one Run- * under one name wherever it is opened. A path outside the project is the machine's own, and stays- * in that machine's form.- */-function presentedPath(root: string, path: string): string {- if (!isWithin(root, path)) return resolve(path);- return (relative(resolve(root), resolve(path)) || ".").split(sep).join("/");-}--function buildBelongsTo(root: string, entry: BuildCatalogEntry): boolean {- return isWithin(root, entry.run?.path ?? entry.source.path) || isWithin(root, entry.source.path);-}--function taskStatus(status: RuntimeHostStatus): StudioTaskView["status"] {- if (status.dispatch !== undefined) {- if (status.dispatch.phase === "terminal") return status.dispatch.terminal ?? "unknown";- return status.dispatch.phase;- }- return status.build?.state.status ?? "unknown";-}--function targetNames(entry: BuildCatalogEntry, status: RuntimeHostStatus): readonly string[] {- const state = status.build?.state;- if (state === undefined) return [];- const names = new Map(entry.aliases.flatMap((alias) => alias.ref.kind === "logical-output"- ? [[alias.ref.id, alias.name] as const]- : []));- return state.request.targets.map((target) => names.get(target.output) ?? target.output);-}--function taskView(root: string, entry: BuildCatalogEntry, status: RuntimeHostStatus): StudioTaskView {- const state = status.build?.state;- return {- id: entry.build,- createdAt: entry.createdAt,- status: taskStatus(status),- source: presentedPath(root, entry.source.path),- ...(entry.run === undefined ? {} : { run: presentedPath(root, entry.run.path) }),- targets: targetNames(entry, status),- acceptedRecords: state?.records.length ?? 0,- outstandingCommands: state?.outstanding.length ?? 0,- operations: status.operations.map((operation) => ({- status: operation.status,- ...(operation.progress?.phase === undefined ? {} : { phase: operation.progress.phase }),- ...(operation.progress?.completed === undefined ? {} : { completed: operation.progress.completed }),- ...(operation.progress?.total === undefined ? {} : { total: operation.progress.total }),- ...(operation.progress?.unit === undefined ? {} : { unit: operation.progress.unit }),- })),- };-}--function isResultFile(value: BuildResultJsonValue): value is BuildResultFileRef {- if (value === null || Array.isArray(value) || typeof value !== "object") return false;- const item = value as Readonly<Record<string, unknown>>;- return item.kind === "build-file" && typeof item.path === "string"- && typeof item.size === "number" && typeof item.mediaType === "string";-}--function filesInResultValue(- value: BuildResultJsonValue,- valuePath = "$",-): readonly { readonly valuePath: string; readonly file: BuildResultFileRef }[] {- if (isResultFile(value)) {- return [{ valuePath, file: value }];- }- if (Array.isArray(value)) {- return value.flatMap((item, index) => filesInResultValue(item, `${valuePath}[${index}]`));- }- if (value !== null && typeof value === "object") {- return Object.entries(value).flatMap(([key, item]) => filesInResultValue(item, `${valuePath}.${key}`));- }- return [];-}--function filesInResolvedOutput(resolved: RepositoryBuildResultOutput): readonly {- readonly valuePath: string;- readonly file: BuildResultFileRef;-}[] {- if (resolved.value.kind === "build-file") return [{ valuePath: "$", file: resolved.value }];- if (resolved.value.kind === "json") return filesInResultValue(resolved.value.value);- return [];-}--async function artifactsForResults(- root: string,- repository: BuildResultRepository,-): Promise<readonly StudioArtifactView[]> {- const manifests = (await repository.list()).filter((manifest) =>- isWithin(root, manifest.run?.path ?? manifest.source.path) || isWithin(root, manifest.source.path));- const nested = await Promise.all(manifests.flatMap((manifest) =>- Object.keys(manifest.outputs).map(async (output) => {- const resolved = await repository.resolve(manifest.id, output);- if (resolved === undefined) return [];- return filesInResolvedOutput(resolved).map(({ valuePath, file }) => ({- id: `${manifest.id}:${output}:${valuePath}`,- build: manifest.id,- createdAt: manifest.startedAt,- output,- valuePath,- ownerBuild: file.build ?? resolved.build,- ownerOutput: resolved.output,- filePath: file.path,- size: file.size,- mediaType: file.mediaType,- source: presentedPath(root, manifest.source.path),- ...(manifest.run === undefined ? {} : { run: presentedPath(root, manifest.run.path) }),- }));- })));- return nested.flat().sort((left, right) =>- right.createdAt - left.createdAt- || left.output.localeCompare(right.output)- || left.valuePath.localeCompare(right.valuePath));-}--/** Build the Studio library from execution status and project-owned Build Results. */-export async function readStudioLibrary(input: {- readonly profile?: string;- readonly workspaceRoot: string;- readonly runtime?: Pick<RuntimeArchive, "builds" | "status">;- readonly results: BuildResultRepository;-}): Promise<StudioLibraryView> {- const entries = (await input.runtime?.builds() ?? [])- .filter((entry) => buildBelongsTo(input.workspaceRoot, entry));- const statuses = await Promise.all(entries.map(async (entry) => ({- entry,- status: await input.runtime!.status(entry.build),- })));- return {- environment: resolve(input.workspaceRoot),- ...(input.profile === undefined ? {} : { runtime: resolve(input.profile) }),- tasks: statuses.map(({ entry, status }) => taskView(input.workspaceRoot, entry, status)),- artifacts: await artifactsForResults(input.workspaceRoot, input.results),- };-}--/** Open a Runtime profile read-only; Studio never creates or mutates a Build. */-export async function openStudioArchive(- profile: string | undefined,- packageRoot: string,- workspaceRoot: string,- distributionPackageRoot?: string,-): Promise<StudioArchive | undefined> {- const resolvedProfile = profile === undefined ? undefined : resolve(profile);- const host = resolvedProfile === undefined- ? undefined- : await videoCliDistribution.openRuntimeHost(resolvedProfile, {- packageRoot,- ...(distributionPackageRoot === undefined ? {} : { distributionPackageRoot }),- });- const runtime = await host?.openArchive({ readOnly: true });- const defaultResultRoot = join(workspaceRoot, ".hypit", "results");- const openedResults = host?.openResults === undefined- ? undefined- : await host.openResults(defaultResultRoot);- const results = openedResults?.repository ?? new FileBuildResultRepository(defaultResultRoot);- return {- ...(resolvedProfile === undefined ? {} : { profile: resolvedProfile }),- ...(runtime === undefined ? {} : { runtime }),- async library() {- return await readStudioLibrary({- ...(resolvedProfile === undefined ? {} : { profile: resolvedProfile }),- workspaceRoot,- ...(runtime === undefined ? {} : { runtime }),- results,- });- },- async resolveBuildRecord(build, output) {- return await resolveBuildResultRecord(results, build, output);- },- async openArtifact(build, output, valuePath) {- const resolved = await results.resolve(build, output);- if (resolved === undefined) return undefined;- const match = filesInResolvedOutput(resolved).find((item) => item.valuePath === valuePath);- if (match === undefined) return undefined;- const stream = await results.openFile(resolved.build, match.file);- if (stream === undefined) return undefined;- const chunks: Uint8Array[] = [];- let size = 0;- for await (const chunk of stream) {- const copy = Uint8Array.from(chunk);- chunks.push(copy);- size += copy.byteLength;- }- const bytes = new Uint8Array(size);- let offset = 0;- for (const chunk of chunks) {- bytes.set(chunk, offset);- offset += chunk.byteLength;- }- return { mediaType: match.file.mediaType, bytes };- },- async close() {- await openedResults?.close();- await runtime?.close();- },- };-}diff --git a/packages/studio/src/build-library.ts b/packages/studio/src/build-library.tsnew file mode 100644index 00000000..6480cf75--- /dev/null+++ b/packages/studio/src/build-library.ts@@ -0,0 +1,263 @@+import { isAbsolute, join, relative, resolve, sep } from "node:path";++import { buildIdCreatedAt } from "@hypit/protocol";+import type { BuildView, NodeRuntimeHost } from "@hypit/runtime-host-node";+import type { StoredValue, TypeRef } from "@hypit/protocol";+import { FileBuildResultRepository } from "@hypit/build-result";+import type {+ BuildResultFileRange,+ BuildResultFileRef,+ BuildResultManifest,+ BuildResultRepository,+ FinishedBuildResultManifest,+ RepositoryBuildResultOutput,+} from "@hypit/build-result";++import { resolveBuildResultValue } from "@hypit/cli";+import { videoCliDistribution } from "@hypit/video-cli";++import type { StudioArtifactView, StudioLibraryView, StudioTaskView } from "./shared.js";++type RuntimeControl = Awaited<ReturnType<NodeRuntimeHost["openControl"]>>;++export type StudioBuildLibrary = {+ readonly profile?: string;+ readonly runtime?: Pick<RuntimeControl, "activity">;+ readonly library: () => Promise<StudioLibraryView>;+ readonly resolveHistoricalOutput: (+ build: string,+ output: string,+ ) => Promise<{+ readonly type: TypeRef;+ readonly value: StoredValue;+ readonly attachments?: readonly import("@hypit/workspace").ArtifactAttachment[];+ } | undefined>;+ readonly openArtifact: (+ build: string,+ output: string,+ valuePath: string,+ ) => Promise<{+ readonly mediaType: string;+ readonly size: number;+ open(range?: BuildResultFileRange): Promise<AsyncIterable<Uint8Array> | undefined>;+ } | undefined>;+ readonly close: () => Promise<void>;+};++function projectPath(root: string, path: string): string {+ return isAbsolute(path) ? resolve(path) : resolve(root, path);+}++function isWithin(root: string, path: string): boolean {+ const rel = relative(resolve(root), projectPath(root, path));+ return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));+}++/**+ * A path inside the project reads the same on every platform, so the Studio library shows one Run+ * under one name wherever it is opened. A path outside the project is the machine's own, and stays+ * in that machine's form.+ */+function presentedPath(root: string, path: string): string {+ const absolute = projectPath(root, path);+ if (!isWithin(root, path)) return absolute;+ return (relative(resolve(root), absolute) || ".").split(sep).join("/");+}++function buildBelongsTo(root: string, view: BuildView): boolean {+ return view.source !== undefined+ && (isWithin(root, view.run?.path ?? view.source.path) || isWithin(root, view.source.path));+}++function taskStatus(view: BuildView): StudioTaskView["status"] {+ if (view.issue !== undefined) return "blocked";+ if (view.activity === "submitting" || view.activity === "ready") return "queued";+ if (view.activity === "saving-result") return "active";+ return view.activity;+}++function taskView(+ root: string,+ view: BuildView,+ result?: BuildResultManifest,+): StudioTaskView {+ if (view.source === undefined) throw new Error(`Active Build ${view.id} has no source`);+ return {+ id: view.id,+ ...(result?.title === undefined ? {} : { title: result.title }),+ ...(result?.note === undefined ? {} : { note: result.note }),+ ...(result?.highlightedOutputs === undefined ? {} : { highlightedOutputs: result.highlightedOutputs }),+ createdAt: view.createdAt,+ status: taskStatus(view),+ source: presentedPath(root, view.source.path),+ ...(view.run === undefined ? {} : { run: presentedPath(root, view.run.path) }),+ targets: result?.targets ?? view.targets,+ acceptedRecords: view.acceptedRecords,+ outstandingCommands: view.outstandingCommands,+ operations: view.operations.map((operation) => ({+ status: operation.status,+ ...(operation.progress?.phase === undefined ? {} : { phase: operation.progress.phase }),+ ...(operation.progress?.completed === undefined ? {} : { completed: operation.progress.completed }),+ ...(operation.progress?.total === undefined ? {} : { total: operation.progress.total }),+ ...(operation.progress?.unit === undefined ? {} : { unit: operation.progress.unit }),+ })),+ };+}++function resultTaskView(root: string, result: FinishedBuildResultManifest): StudioTaskView {+ return {+ id: result.id,+ ...(result.title === undefined ? {} : { title: result.title }),+ ...(result.note === undefined ? {} : { note: result.note }),+ ...(result.highlightedOutputs === undefined ? {} : { highlightedOutputs: result.highlightedOutputs }),+ createdAt: buildIdCreatedAt(result.id)!,+ status: result.outcome,+ source: presentedPath(root, result.source.path),+ ...(result.run === undefined ? {} : { run: presentedPath(root, result.run.path) }),+ targets: result.targets,+ acceptedRecords: Object.keys(result.outputs).length,+ outstandingCommands: 0,+ operations: [],+ };+}++function presentedValuePath(path: readonly (string | number)[]): string {+ return path.reduce<string>((current, segment) => typeof segment === "number"+ ? `${current}[${segment}]`+ : /^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(segment)+ ? `${current}.${segment}`+ : `${current}[${JSON.stringify(segment)}]`, "$");+}++function filesInResolvedOutput(resolved: RepositoryBuildResultOutput): readonly {+ readonly valuePath: string;+ readonly file: BuildResultFileRef;+}[] {+ if (resolved.value.kind === "build-file") return [{ valuePath: "$", file: resolved.value }];+ if (resolved.value.kind === "value") {+ return resolved.value.document.resources.map((binding) => ({+ valuePath: presentedValuePath(binding.at),+ file: binding.file,+ }));+ }+ return [];+}++async function artifactsForResults(+ root: string,+ repository: BuildResultRepository,+ manifests: readonly BuildResultManifest[],+): Promise<readonly StudioArtifactView[]> {+ const nested = await Promise.all(manifests.flatMap((manifest) =>+ Object.keys(manifest.outputs).map(async (output) => {+ const resolved = await repository.resolve(manifest.id, output);+ if (resolved === undefined) return [];+ return filesInResolvedOutput(resolved).map(({ valuePath, file }) => ({+ id: `${manifest.id}:${output}:${valuePath}`,+ build: manifest.id,+ createdAt: buildIdCreatedAt(manifest.id)!,+ output,+ highlighted: manifest.highlightedOutputs?.includes(output) === true,+ ...(manifest.title === undefined ? {} : { buildTitle: manifest.title }),+ ...(manifest.note === undefined ? {} : { buildNote: manifest.note }),+ valuePath,+ ownerBuild: resolved.build,+ ownerOutput: resolved.output,+ filePath: file.path,+ size: file.size,+ mediaType: file.mediaType,+ source: presentedPath(root, manifest.source.path),+ ...(manifest.run === undefined ? {} : { run: presentedPath(root, manifest.run.path) }),+ }));+ })));+ return nested.flat().sort((left, right) =>+ Number(right.highlighted) - Number(left.highlighted)+ || right.createdAt - left.createdAt+ || left.output.localeCompare(right.output)+ || left.valuePath.localeCompare(right.valuePath));+}++/** Build the Studio library from execution status and project-owned Build Results. */+export async function readStudioLibrary(input: {+ readonly profile?: string;+ readonly workspaceRoot: string;+ readonly runtime?: Pick<RuntimeControl, "activity">;+ readonly results: BuildResultRepository;+}): Promise<StudioLibraryView> {+ const manifests = (await input.results.browse({ limit: 100 })).results.filter((manifest) =>+ isWithin(input.workspaceRoot, manifest.run?.path ?? manifest.source.path)+ || isWithin(input.workspaceRoot, manifest.source.path));+ const resultsByBuild = new Map(manifests.map((manifest) => [manifest.id, manifest]));+ const active = input.runtime === undefined ? [] : (await input.runtime.activity()).builds;+ const views = active.filter((view) => buildBelongsTo(input.workspaceRoot, view));+ return {+ environment: resolve(input.workspaceRoot),+ ...(input.profile === undefined ? {} : { runtime: resolve(input.profile) }),+ tasks: [+ ...views.map((view) => taskView(+ input.workspaceRoot,+ view,+ resultsByBuild.get(view.id),+ )),+ ...manifests+ .filter((manifest) => !views.some((view) => view.id === manifest.id))+ .map((manifest) => resultTaskView(input.workspaceRoot, manifest)),+ ].sort((left, right) => right.createdAt - left.createdAt || left.id.localeCompare(right.id)),+ artifacts: await artifactsForResults(input.workspaceRoot, input.results, manifests),+ };+}++/** Open a Runtime profile read-only; Studio never creates or mutates a Build. */+export async function openStudioBuildLibrary(+ profile: string | undefined,+ packageRoot: string,+ workspaceRoot: string,+ distributionPackageRoot?: string,+): Promise<StudioBuildLibrary | undefined> {+ const resolvedProfile = profile === undefined ? undefined : resolve(profile);+ const host = resolvedProfile === undefined+ ? undefined+ : await videoCliDistribution.openRuntimeHost(resolvedProfile, {+ packageRoot,+ ...(distributionPackageRoot === undefined ? {} : { distributionPackageRoot }),+ });+ const runtime = await host?.openControl({ readOnly: true });+ const defaultResultRoot = join(workspaceRoot, ".hypit", "results");+ const openedResults = videoCliDistribution.openProjectResults === undefined+ ? undefined+ : await videoCliDistribution.openProjectResults(workspaceRoot, {+ packageRoot,+ ...(distributionPackageRoot === undefined ? {} : { distributionPackageRoot }),+ });+ const results = openedResults?.repository ?? new FileBuildResultRepository(defaultResultRoot);+ return {+ ...(resolvedProfile === undefined ? {} : { profile: resolvedProfile }),+ ...(runtime === undefined ? {} : { runtime }),+ async library() {+ return await readStudioLibrary({+ ...(resolvedProfile === undefined ? {} : { profile: resolvedProfile }),+ workspaceRoot,+ ...(runtime === undefined ? {} : { runtime }),+ results,+ });+ },+ async resolveHistoricalOutput(build, output) {+ return await resolveBuildResultValue(results, build, output);+ },+ async openArtifact(build, output, valuePath) {+ const resolved = await results.resolve(build, output);+ if (resolved === undefined) return undefined;+ const match = filesInResolvedOutput(resolved).find((item) => item.valuePath === valuePath);+ if (match === undefined) return undefined;+ return {+ mediaType: match.file.mediaType,+ size: match.file.size,+ open: async (range) => await results.openFile(resolved.build, match.file, range),+ };+ },+ async close() {+ await openedResults?.close();+ await runtime?.close();+ },+ };+}diff --git a/packages/studio/src/programme.ts b/packages/studio/src/programme.tsindex 21b79bd8..26c5cf39 100644--- a/packages/studio/src/programme.ts+++ b/packages/studio/src/programme.ts@@ -13,7 +13,6 @@ import { semanticTrackTypes } from "@hypit/semantic-track";import type { ProgramSpace } from "@hypit/program-space";import type { StudioResolvedTrack, StudioTemporalBinding } from "@hypit/studio-adapter";-import type { StudioArchive } from "./archive.js";import type { CompiledSource, ServedFile } from "./compile.js";import type { StudioDomain } from "./domain.js";import { executeDeterministic, MemoryResourceStore } from "./execute.js";@@ -75,7 +74,7 @@ function selectedValue(state: ExecutionState,output: string,): StoredValue | undefined {- const selection = state.plan.selections.find((item) => item.output === output);+ const selection = state.plan.outputBindings.find((item) => item.output === output);if (selection === undefined) return undefined;const executed = state.records.find((item) => item.id === selection.record)?.value;if (executed !== undefined) return executed;@@ -111,7 +110,6 @@ export async function preview(input: {readonly outputRefs: readonly string[];readonly compositionRef: string;readonly projections: readonly StudioViewRequirement[];- readonly archive?: StudioArchive;/** Preview-only endpoint set. Production Studio passes none; preview-mock may pass only local mock media. */readonly endpoints?: EndpointRegistry;}): Promise<Preview> {diff --git a/packages/studio/src/run.ts b/packages/studio/src/run.tsindex b98130f4..b4acedcc 100644--- a/packages/studio/src/run.ts+++ b/packages/studio/src/run.ts@@ -9,7 +9,7 @@ import {RunFrontendRegistry,} from "@hypit/run";-import type { StudioArchive } from "./archive.js";+import type { StudioBuildLibrary } from "./build-library.js";import { observedCompiledSource } from "./compile.js";import type { CompiledSource } from "./compile.js";import type { StudioDomain } from "./domain.js";@@ -40,7 +40,7 @@ export async function loadStudioRun(input: {readonly run: string;readonly domain: StudioDomain;readonly registry: import("./studio-registry.js").StudioCompanionRegistry;- readonly archive?: StudioArchive;+ readonly buildLibrary?: StudioBuildLibrary;}): Promise<RunPlan> {const fragments = new RunFragmentRegistry();const frontends = new RunFrontendRegistry();@@ -55,8 +55,8 @@ export async function loadStudioRun(input: {authorCompiler: input.domain.createCompiler(observer.surfaces),fragments,frontends,- ...(input.archive === undefined ? {} : {- resolveBuildRecord: input.archive.resolveBuildRecord,+ ...(input.buildLibrary === undefined ? {} : {+ resolveHistoricalOutput: input.buildLibrary.resolveHistoricalOutput,}),});const compiled = await compiler.compileFile(input.run);diff --git a/packages/studio/src/server.ts b/packages/studio/src/server.tsindex 5c47beb9..136b30de 100644--- a/packages/studio/src/server.ts+++ b/packages/studio/src/server.ts@@ -3,12 +3,15 @@ import type { FSWatcher } from "node:fs";import { existsSync } from "node:fs";import { readFile } from "node:fs/promises";import { dirname, isAbsolute, relative, resolve } from "node:path";+import { Readable } from "node:stream";+import { pipeline } from "node:stream/promises";import type { Plugin, ViteDevServer } from "vite";+import type { BuildResultFileRange } from "@hypit/build-result";import type { StudioTemporalInstantProjection } from "@hypit/studio-adapter";import type { EndpointRegistry } from "@hypit/driver-node";-import type { StudioArchive } from "./archive.js";+import type { StudioBuildLibrary } from "./build-library.js";import type { ServedFile } from "./compile.js";import type { StudioDomain } from "./domain.js";import type { StudioCompanionRegistry } from "./studio-registry.js";@@ -27,7 +30,7 @@ export type StudioPluginOptions = {readonly domain: StudioDomain;readonly registry: StudioCompanionRegistry;readonly workspaceRoot: string;- readonly archive?: StudioArchive;+ readonly buildLibrary?: StudioBuildLibrary;readonly endpoints?: EndpointRegistry;};@@ -38,6 +41,26 @@ function json(response: import("node:http").ServerResponse, status: number, valuresponse.end(`${JSON.stringify(value)}\n`);}+function requestedByteRange(value: string | undefined, size: number): BuildResultFileRange | undefined {+ if (value === undefined) return undefined;+ const match = /^bytes=(\d*)-(\d*)$/u.exec(value.trim());+ if (match === null || (match[1]!.length === 0 && match[2]!.length === 0) || size === 0) {+ throw new RangeError("requested byte range is not satisfiable");+ }+ if (match[1]!.length === 0) {+ const suffix = Number(match[2]);+ if (!Number.isSafeInteger(suffix) || suffix <= 0) throw new RangeError("requested byte range is not satisfiable");+ return { start: Math.max(0, size - suffix), endExclusive: size };+ }+ const start = Number(match[1]);+ const requestedEnd = match[2]!.length === 0 ? size - 1 : Number(match[2]);+ if (!Number.isSafeInteger(start) || !Number.isSafeInteger(requestedEnd) || start < 0+ || start >= size || requestedEnd < start) {+ throw new RangeError("requested byte range is not satisfiable");+ }+ return { start, endExclusive: Math.min(size, requestedEnd + 1) };+}+function rangeOf(error: unknown): Range | undefined {if (typeof error !== "object" || error === null) return undefined;const range = (error as { readonly range?: unknown }).range;@@ -74,7 +97,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {const storyboards = new Map<string, Promise<StudioStoryboard>>();const readLibrary = async (): Promise<StudioLibraryView> => {- const next = await options.archive?.library() ?? {+ const next = await options.buildLibrary?.library() ?? {environment: options.workspaceRoot,tasks: [],artifacts: [],@@ -114,7 +137,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {run: options.runPath,domain: options.domain,registry: options.registry,- ...(options.archive === undefined ? {} : { archive: options.archive }),+ ...(options.buildLibrary === undefined ? {} : { buildLibrary: options.buildLibrary }),...(options.endpoints === undefined ? {} : { endpoints: options.endpoints }),});currentSource = run.authorSource;@@ -129,7 +152,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {domain: options.domain,registry: options.registry,run,- ...(options.archive === undefined ? {} : { archive: options.archive }),+ ...(options.buildLibrary === undefined ? {} : { buildLibrary: options.buildLibrary }),...(options.endpoints === undefined ? {} : { endpoints: options.endpoints }),revision: attempt,sourcePath: relative(options.workspaceRoot, run.authorSource),@@ -644,25 +667,53 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {const build = url.searchParams.get("build");const output = url.searchParams.get("output");const valuePath = url.searchParams.get("path");- if (build === null || output === null || valuePath === null || options.archive === undefined) {+ if (build === null || output === null || valuePath === null || options.buildLibrary === undefined) {response.statusCode = 404;response.end();return;}- const artifact = await options.archive.openArtifact(build, output, valuePath);+ const artifact = await options.buildLibrary.openArtifact(build, output, valuePath);if (artifact === undefined) {response.statusCode = 404;response.end();return;}- response.statusCode = 200;+ let range: BuildResultFileRange | undefined;+ try {+ range = requestedByteRange(request.headers.range, artifact.size);+ } catch (error) {+ if (!(error instanceof RangeError)) throw error;+ response.statusCode = 416;+ response.setHeader("content-range", `bytes */${artifact.size}`);+ response.end();+ return;+ }+ response.statusCode = range === undefined ? 200 : 206;response.setHeader("content-type", artifact.mediaType);- response.setHeader("content-length", String(artifact.bytes.byteLength));+ response.setHeader("content-length", String(range === undefined+ ? artifact.size+ : range.endExclusive - range.start));response.setHeader("cache-control", "private, no-store");- if (request.method === "HEAD") response.end();- else response.end(Buffer.from(artifact.bytes));+ response.setHeader("accept-ranges", "bytes");+ if (range !== undefined) {+ response.setHeader("content-range", `bytes ${range.start}-${range.endExclusive - 1}/${artifact.size}`);+ }+ if (request.method === "HEAD") {+ response.end();+ return;+ }+ const stream = await artifact.open(range);+ if (stream === undefined) {+ response.statusCode = 404;+ response.removeHeader("content-length");+ response.removeHeader("content-range");+ response.end();+ return;+ }+ await pipeline(Readable.from(stream), response);})().catch((error) => {- json(response, 500, { error: error instanceof Error ? error.message : String(error) });+ if (response.headersSent) response.destroy(error instanceof Error ? error : new Error(String(error)));+ else json(response, 500, { error: error instanceof Error ? error.message : String(error) });});return;}@@ -672,7 +723,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {async closeBundle() {for (const watcher of watched.values()) watcher.close();watched.clear();- await options.archive?.close();+ await options.buildLibrary?.close();},};}diff --git a/packages/studio/src/session.ts b/packages/studio/src/session.tsindex 51c81c92..2a250084 100644--- a/packages/studio/src/session.ts+++ b/packages/studio/src/session.ts@@ -5,7 +5,6 @@ import type { EndpointRegistry } from "@hypit/driver-node";import { markupAuthorFrontendId } from "@hypit/markup";import { svsFrontendId } from "@hypit/svs";-import type { StudioArchive } from "./archive.js";import type { ServedFile } from "./compile.js";import type { StudioDomain } from "./domain.js";import type { Observations } from "./observe.js";@@ -57,7 +56,6 @@ export async function readStudioSession(input: {readonly domain: StudioDomain;readonly registry: StudioCompanionRegistry;readonly run: RunPlan;- readonly archive?: StudioArchive;readonly revision: number;readonly sourcePath?: string;readonly workspaceRoot: string;@@ -80,7 +78,6 @@ export async function readStudioSession(input: {outputRefs,compositionRef: inspection.filmComposition,projections: inspection.projections,- ...(input.archive === undefined ? {} : { archive: input.archive }),...(input.endpoints === undefined ? {} : { endpoints: input.endpoints }),});const rendered = renderPreview({diff --git a/packages/studio/src/shared.ts b/packages/studio/src/shared.tsindex 4d82679c..a484714f 100644--- a/packages/studio/src/shared.ts+++ b/packages/studio/src/shared.ts@@ -186,8 +186,11 @@ export type StudioSourceView = {export type StudioTaskView = {readonly id: string;+ readonly title?: string;+ readonly note?: string;+ readonly highlightedOutputs?: readonly string[];readonly createdAt: number;- readonly status: "queued" | "running" | "waiting" | "complete" | "failed" | "cancelled" | "active" | "unknown";+ readonly status: "queued" | "running" | "waiting" | "complete" | "failed" | "cancelled" | "active" | "blocked" | "unknown";readonly source: string;readonly run?: string;readonly targets: readonly string[];@@ -208,6 +211,9 @@ export type StudioArtifactView = {readonly build: string;readonly createdAt: number;readonly output: string;+ readonly highlighted: boolean;+ readonly buildTitle?: string;+ readonly buildNote?: string;readonly valuePath: string;readonly ownerBuild: string;readonly ownerOutput: string;diff --git a/packages/studio/src/style.css b/packages/studio/src/style.cssindex 8e46ac43..ef167de8 100644--- a/packages/studio/src/style.css+++ b/packages/studio/src/style.css@@ -399,14 +399,14 @@ button:focus-visible, textarea:focus-visible {.task-state span { width: 8px; height: 8px; border-radius: 50%; background: #686d76; box-shadow: 0 0 0 3px rgba(104, 109, 118, .1); }.task-running .task-state span, .task-queued .task-state span, .task-waiting .task-state span, .task-active .task-state span { background: #49b9d0; box-shadow: 0 0 0 3px rgba(73, 185, 208, .11), 0 0 10px rgba(73, 185, 208, .18); }.task-complete .task-state span { background: var(--ok); box-shadow: 0 0 0 3px rgba(100, 201, 154, .1); }-.task-failed .task-state span, .task-cancelled .task-state span { background: #d8646d; box-shadow: 0 0 0 3px rgba(216, 100, 109, .1); }+.task-failed .task-state span, .task-cancelled .task-state span, .task-blocked .task-state span { background: #d8646d; box-shadow: 0 0 0 3px rgba(216, 100, 109, .1); }.task-copy { min-width: 0; }.task-title { min-width: 0; display: flex; align-items: center; gap: 7px; }.task-title strong { min-width: 0; flex: 1; overflow: hidden; color: #dfe1e5; font-size: 11px; font-weight: 600; text-overflow: ellipsis; white-space: nowrap; }.task-status { flex: none; padding: 2px 5px; border-radius: 8px; background: #292c31; color: #9297a1; font: 600 8px/1.2 var(--font-ui); text-transform: uppercase; }.task-running .task-status, .task-queued .task-status, .task-waiting .task-status, .task-active .task-status { background: rgba(73, 185, 208, .12); color: #79d1e2; }.task-complete .task-status { background: rgba(100, 201, 154, .11); color: #86d7b1; }-.task-failed .task-status, .task-cancelled .task-status { background: rgba(216, 100, 109, .1); color: #e58b92; }+.task-failed .task-status, .task-cancelled .task-status, .task-blocked .task-status { background: rgba(216, 100, 109, .1); color: #e58b92; }.task-source { margin: 3px 0 6px; overflow: hidden; color: #6f747d; font: 9px/1.25 var(--font-mono); text-overflow: ellipsis; white-space: nowrap; }.task-facts { min-width: 0; display: flex; align-items: center; gap: 5px; overflow: hidden; }.task-facts span { min-width: 0; overflow: hidden; color: #686d76; font-size: 9px; text-overflow: ellipsis; white-space: nowrap; }@@ -419,6 +419,7 @@ button:focus-visible, textarea:focus-visible {.artifact-filters button.active { background: #2a2c31; color: #eef0f3; }.artifact-grid { flex: 1; min-height: 0; overflow: auto; display: grid; grid-template-columns: repeat(auto-fill, minmax(142px, 1fr)); align-content: start; gap: 9px; padding: 10px 10px 30px; background: #121316; }.artifact-card { height: 190px; min-width: 0; overflow: hidden; display: flex; flex-direction: column; border: 1px solid #292b31; border-radius: 7px; background: #1a1c20; color: inherit; text-decoration: none; box-shadow: 0 7px 18px rgba(0, 0, 0, .09); transition: border-color 120ms ease, transform 120ms ease, box-shadow 120ms ease; }+.artifact-card.artifact-highlighted { border-color: rgba(237, 152, 185, .55); box-shadow: 0 0 0 1px rgba(237, 152, 185, .08), 0 9px 22px rgba(0, 0, 0, .14); }.artifact-card:hover { border-color: #454952; transform: translateY(-2px); box-shadow: 0 10px 22px rgba(0, 0, 0, .17); }.artifact-preview { position: relative; flex: 1 1 auto; min-height: 0; overflow: hidden; display: grid; place-items: center; border-bottom: 1px solid rgba(255, 255, 255, .055); background: radial-gradient(circle at 35% 24%, #30343c, #202228 58%, #1a1b1f); }.artifact-preview::after { content: ""; position: absolute; inset: 0; background: linear-gradient(180deg, transparent 54%, rgba(8, 9, 11, .32)); pointer-events: none; }@@ -430,6 +431,7 @@ button:focus-visible, textarea:focus-visible {.artifact-video .artifact-glyph { color: #75badf; }.artifact-audio .artifact-glyph { color: #83cf9d; }.artifact-type { position: absolute; z-index: 2; right: 6px; bottom: 5px; padding: 2px 5px; border-radius: 4px; background: rgba(10, 11, 13, .62); color: #d2d5da; font: 600 8px/1.2 var(--font-ui); backdrop-filter: blur(6px); }+.artifact-highlight { position: absolute; z-index: 2; left: 6px; top: 6px; padding: 3px 6px; border-radius: 4px; background: rgba(77, 38, 55, .82); color: #f1abc5; font: 600 8px/1 var(--font-ui); letter-spacing: .02em; }.artifact-copy { min-width: 0; flex: none; min-height: 45px; padding: 8px 9px 9px; }.artifact-copy strong, .artifact-copy span { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }.artifact-copy strong { color: #d8dae0; font-size: 10px; font-weight: 600; }diff --git a/packages/studio/src/temporal-graph.ts b/packages/studio/src/temporal-graph.tsindex a4c938f2..fd6c6e19 100644--- a/packages/studio/src/temporal-graph.ts+++ b/packages/studio/src/temporal-graph.ts@@ -158,7 +158,7 @@ function producingSteps(state: BuildState): ReadonlyMap<string, ProducerStep> {}function closure(state: BuildState, output: string): ReadonlySet<string> {- const selected = state.plan.selections.find((selection) => selection.output === output);+ const selected = state.plan.outputBindings.find((selection) => selection.output === output);if (selected === undefined) return new Set();const producers = producingSteps(state);const steps = new Set<string>();diff --git a/packages/studio/src/ui/icons.ts b/packages/studio/src/ui/icons.tsindex d3ec57db..fa060a21 100644--- a/packages/studio/src/ui/icons.ts+++ b/packages/studio/src/ui/icons.ts@@ -11,7 +11,7 @@ const paths: Readonly<Record<string, string>> = {chevron: '<path d="m7 9 5 5 5-5"/>',select: '<path d="M5 3v15l4-4 3 6 3-1.5-3-6h6L5 3Z"/>',tasks: '<path d="M10 6h10M10 12h10M10 18h10"/><path d="m3.5 6 1.5 1.5L7.5 4.5M3.5 12 5 13.5l2.5-3M3.5 18 5 19.5l2.5-3"/>',- archive: '<path d="M4 8v12h16V8M3 4h18v4H3zM9 12h6"/>',+ results: '<path d="M4 8v12h16V8M3 4h18v4H3zM9 12h6"/>',run: '<circle cx="12" cy="12" r="9"/><path d="m10 8 6 4-6 4V8Z"/>',image: '<rect x="3" y="4" width="18" height="16" rx="2"/><circle cx="8.5" cy="9" r="2"/><path d="m4 18 5-5 3 3 3-4 5 6"/>',sidebarCollapse: '<rect x="3" y="4" width="18" height="16" rx="2"/><path d="M8 4v16m7-11-3 3 3 3"/>',diff --git a/packages/studio/src/ui/library.ts b/packages/studio/src/ui/library.tsindex ca2d83dc..9a197d1b 100644--- a/packages/studio/src/ui/library.ts+++ b/packages/studio/src/ui/library.ts@@ -66,7 +66,7 @@ function taskProgress(task: StudioTaskView): string | undefined {function taskCard(task: StudioTaskView): HTMLElement {const node = document.createElement("article");node.className = `task-card task-${task.status}`;- const title = task.targets.length === 0 ? leaf(task.run ?? task.source) : task.targets.join(", ");+ const title = task.title ?? (task.targets.length === 0 ? leaf(task.run ?? task.source) : task.targets.join(", "));const progress = taskProgress(task);node.innerHTML = `<div class="task-state"><span></span></div>@@ -89,7 +89,7 @@ function taskCard(task: StudioTaskView): HTMLElement {const progressNode = node.querySelector<HTMLElement>("[data-progress]")!;if (progress === undefined) progressNode.remove();else progressNode.textContent = progress;- node.title = `${task.id}\n${source}`;+ node.title = [title, task.id, source, task.note].filter((item) => item !== undefined).join("\n");return node;}@@ -103,7 +103,7 @@ function artifactKind(mediaType: string): { readonly label: string; readonly icofunction artifactCard(artifact: StudioArtifactView): HTMLElement {const kind = artifactKind(artifact.mediaType);const link = document.createElement("a");- link.className = `artifact-card artifact-${kind.label.toLowerCase()}`;+ link.className = `artifact-card artifact-${kind.label.toLowerCase()}${artifact.highlighted ? " artifact-highlighted" : ""}`;const query = new URLSearchParams({build: artifact.build,output: artifact.output,@@ -117,6 +117,7 @@ function artifactCard(artifact: StudioArtifactView): HTMLElement {<div class="artifact-preview"><span class="artifact-glyph">${icon(kind.icon)}</span><span class="artifact-type"></span>+ ${artifact.highlighted ? '<span class="artifact-highlight">Highlighted</span>' : ""}</div><div class="artifact-copy"><strong></strong>@@ -124,7 +125,11 @@ function artifactCard(artifact: StudioArtifactView): HTMLElement {</div>`;link.querySelector<HTMLElement>(".artifact-type")!.textContent = kind.label;link.querySelector("strong")!.textContent = title;- link.querySelector<HTMLElement>(".artifact-meta")!.textContent = `${formatBytes(artifact.size)} · ${date.format(artifact.createdAt)}`;+ link.querySelector<HTMLElement>(".artifact-meta")!.textContent = [+ artifact.buildTitle,+ formatBytes(artifact.size),+ date.format(artifact.createdAt),+ ].filter((item) => item !== undefined).join(" · ");if (artifact.mediaType.startsWith("image/")) {const image = document.createElement("img");image.src = link.href;@@ -137,7 +142,8 @@ function artifactCard(artifact: StudioArtifactView): HTMLElement {artifact.mediaType,`${artifact.ownerBuild}/${artifact.ownerOutput}/${artifact.filePath}`,artifact.run ?? artifact.source,- ].join("\n");+ artifact.buildNote,+ ].filter((item) => item !== undefined).join("\n");return link;}@@ -153,7 +159,7 @@ export function createLibraryPane(code: CodePane): LibraryPane {<span>${icon("tasks")}</span><strong>Tasks</strong></button><button type="button" class="library-tab" data-library-tab="artifacts" role="tab" aria-selected="false">- <span>${icon("archive")}</span><strong>Artifacts</strong>+ <span>${icon("results")}</span><strong>Artifacts</strong></button></div><section class="library-view active" data-library-view="source">@@ -168,7 +174,7 @@ export function createLibraryPane(code: CodePane): LibraryPane {</section><section class="library-view" data-library-view="tasks"><div class="library-toolbar">- <div><strong>Build archive</strong><small data-task-count></small></div>+ <div><strong>Build Results</strong><small data-task-count></small></div><button type="button" class="library-refresh" data-library-refresh aria-label="Refresh tasks" title="Refresh">${icon("refresh")}</button></div><div class="library-context-row" data-runtime-context></div>@@ -266,7 +272,7 @@ export function createLibraryPane(code: CodePane): LibraryPane {? artifacts: artifacts.filter((artifact) => artifact.mediaType.startsWith(`${artifactFilter}/`));if (shown.length === 0) {- artifactGrid.replaceChildren(emptyState("archive",+ artifactGrid.replaceChildren(emptyState("results",artifacts.length === 0 ? "No accepted artifacts" : `No ${artifactFilter} artifacts`,"Public files appear here when a Build Result contains them."));return;@@ -304,8 +310,8 @@ export function createLibraryPane(code: CodePane): LibraryPane {renderArtifacts();} catch (error) {const detail = error instanceof Error ? error.message : String(error);- if (active === "tasks") taskList.replaceChildren(emptyState("tasks", "Archive unavailable", detail));- if (active === "artifacts") artifactGrid.replaceChildren(emptyState("archive", "Build Results unavailable", detail));+ if (active === "tasks") taskList.replaceChildren(emptyState("tasks", "Build Results unavailable", detail));+ if (active === "artifacts") artifactGrid.replaceChildren(emptyState("results", "Build Results unavailable", detail));} finally {refreshing = false;element.classList.remove("is-refreshing");diff --git a/packages/studio/start.ts b/packages/studio/start.tsindex 2586a65a..b275fff1 100644--- a/packages/studio/start.ts+++ b/packages/studio/start.ts@@ -7,7 +7,7 @@ import { videoCliDistribution } from "@hypit/video-cli";import { EndpointRegistry } from "@hypit/driver-node";import { createLocalMediaProvider } from "@hypit/provider-media-local";-import { openStudioArchive } from "./src/archive.js";+import { openStudioBuildLibrary } from "./src/build-library.js";import { loadStudioCompanionRegistry } from "./src/companion-profile.js";import { loadStudioDomain } from "./src/domain.js";import { loadStudioRun } from "./src/run.js";@@ -79,17 +79,17 @@ const registry = await loadStudioCompanionRegistry({...(studioProfilePath === undefined ? {} : { profile: studioProfilePath }),});const domain = await loadStudioDomain({ run: runPath, workspaceRoot, packageRoot });-const archive = await openStudioArchive(runtimePath, packageRoot, workspaceRoot, distributionPackageRoot);+const buildLibrary = await openStudioBuildLibrary(runtimePath, packageRoot, workspaceRoot, distributionPackageRoot);let run;try {run = await loadStudioRun({run: runPath,domain,registry,- ...(archive === undefined ? {} : { archive }),+ ...(buildLibrary === undefined ? {} : { buildLibrary }),});} catch (error) {- await archive?.close();+ await buildLibrary?.close();throw error;}const source = run.authorSource;@@ -102,7 +102,7 @@ if (endpoints !== undefined) await createLocalMediaProvider({}).install(endpointtry {inspectStudioRun(registry, run.source, run, previewOnly ? PREVIEW_LOCAL_MEDIA_CAPABILITIES : undefined);} catch (error) {- await archive?.close();+ await buildLibrary?.close();throw error;}const server = await createServer({@@ -122,7 +122,7 @@ const server = await createServer({workspaceRoot,domain,registry,- ...(archive === undefined ? {} : { archive }),+ ...(buildLibrary === undefined ? {} : { buildLibrary }),...(endpoints === undefined ? {} : { endpoints }),})],});diff --git a/packages/studio/test/archive.test.ts b/packages/studio/test/build-library.test.tssimilarity index 54%rename from packages/studio/test/archive.test.tsrename to packages/studio/test/build-library.test.tsindex 87b8cdfe..f578c297 100644--- a/packages/studio/test/archive.test.ts+++ b/packages/studio/test/build-library.test.ts@@ -4,76 +4,38 @@ import { tmpdir } from "node:os";import { join } from "node:path";import test from "node:test";-import type { BuildState, ResourceId } from "@hypit/protocol";import type { BuildResultRepository } from "@hypit/build-result";-import type { BuildCatalogEntry } from "@hypit/runtime";-import type { RuntimeHostStatus } from "@hypit/runtime-host-node";+import type { BuildView } from "@hypit/runtime-host-node";-import { openStudioArchive, readStudioLibrary } from "../src/archive.js";+import { openStudioBuildLibrary, readStudioLibrary } from "../src/build-library.js";-const resource = "res_studio-archive" as ResourceId;--function state(): BuildState {- return {- format: "hypit.build@1",- program: { closure: { format: "hypit.closure@1", modules: [] }, records: [] },- graph: { format: "hypit.graph@1", outputs: [], candidates: [], operations: [] },- request: { format: "hypit.build-request@1", targets: [{ output: "final-output" }] },- plan: {- format: "hypit.plan@1",- steps: [],- goals: [{ record: "final-record", type: { module: { name: "example", version: "1" }, name: "Video" } }],- selections: [{ output: "final-output", candidate: "render", record: "final-record" }],- },- status: "complete",- records: [{- id: "final-record",- type: { module: { name: "example", version: "1" }, name: "Video" },- value: { kind: "blob", resource, size: 42, mediaType: "video/mp4" },- }],- steps: [],- needs: [],- outstanding: [],- diagnostics: [],- };-}--function catalog(build: string, root: string): BuildCatalogEntry {+function activeBuild(id: string, root: string): BuildView {return {- build,+ id,createdAt: 100,+ activity: "saving-result",+ outcome: "complete",+ cancellationRequested: false,source: { path: `${root}/author/main.svml` },run: { path: `${root}/runs/build.svrun` },- aliases: [{ name: "final.video", ref: { kind: "logical-output", id: "final-output" } }],+ targets: ["final.video"],+ acceptedRecords: 1,+ outstandingCommands: 0,+ operations: [],};}test("Studio library joins this environment's Builds with project Build Result files", async () => {- const relevant = catalog("build-inside", "/project");- const unrelated = catalog("build-outside", "/another-project");- const status: RuntimeHostStatus = {- build: { build: relevant.build, definition: {} as never, facts: [], state: state() },- catalog: relevant,- operations: [],- dispatch: {- build: relevant.build,- componentPackages: [],- createdAt: 100,- availableAt: 100,- phase: "terminal",- terminal: "complete",- },- };+ const relevant = activeBuild("bld_20260902T130000000Z_0000000001", "/project");+ const unrelated = activeBuild("bld_20260902T130000001Z_0000000001", "/another-project");const manifests = [relevant, unrelated].map((entry) => ({- format: "hypit.build-result@1" as const,- id: entry.build,- source: entry.source,+ format: "hypit.build-result@2" as const,+ id: entry.id,+ source: entry.source!,...(entry.run === undefined ? {} : { run: entry.run }),targets: ["final.video"],- startedAt: entry.createdAt,- updatedAt: entry.createdAt,finishedAt: entry.createdAt,- status: "complete" as const,+ outcome: "complete" as const,outputs: {"final.video": {type: { module: { name: "example", version: "1" }, name: "Video" },@@ -84,8 +46,10 @@ test("Studio library joins this environment's Builds with project Build Result fconst results: BuildResultRepository = {async create() { throw new Error("not used"); },async openWriter() { return undefined; },+ async remove() {},+ async updatePresentation() { throw new Error("read-only fixture"); },async read(build) { return manifests.find((item) => item.id === build); },- async list() { return manifests; },+ async browse() { return { results: manifests }; },async resolve(build, output) {const manifest = manifests.find((item) => item.id === build);const value = manifest?.outputs[output as "final.video"];@@ -97,10 +61,8 @@ test("Studio library joins this environment's Builds with project Build Result fprofile: "/project/hypit.runtime.json",workspaceRoot: "/project",runtime: {- async builds() { return [relevant, unrelated]; },- async status(build) {- assert.equal(build, relevant.build);- return status;+ async activity() {+ return { builds: [relevant, unrelated], capacity: [] };},},results,@@ -113,8 +75,8 @@ test("Studio library joins this environment's Builds with project Build Result frun: task.run,targets: task.targets,})), [{- id: "build-inside",- status: "complete",+ id: "bld_20260902T130000000Z_0000000001",+ status: "active",source: "author/main.svml",run: "runs/build.svrun",targets: ["final.video"],@@ -126,7 +88,7 @@ test("Studio library joins this environment's Builds with project Build Result ffilePath: artifact.filePath,mediaType: artifact.mediaType,})), [{- build: "build-inside",+ build: "bld_20260902T130000000Z_0000000001",output: "final.video",valuePath: "$",filePath: "files/final.video.mp4",@@ -136,22 +98,21 @@ test("Studio library joins this environment's Builds with project Build Result ftest("Studio opens project Build Results without a Runtime or ResourceStore", async () => {const root = await mkdtemp(join(tmpdir(), "hypit-studio-results-"));- const directory = join(root, ".hypit", "results", "build-one");+ const build = "bld_20260902T130000002Z_0000000001";+ const directory = join(root, ".hypit", "results", build);const bytes = new TextEncoder().encode("finished-video");try {await mkdir(join(directory, "files"), { recursive: true });await writeFile(join(directory, "files", "final.mp4"), bytes);await writeFile(join(directory, "result.json"), `${JSON.stringify({- format: "hypit.build-result@1",- id: "build-one",- name: "First cut",+ format: "hypit.build-result@2",+ id: build,+ title: "First cut",source: { path: join(root, "main.svml") },run: { path: join(root, "build.svrun") },targets: ["final.video"],- startedAt: 100,- updatedAt: 200,finishedAt: 200,- status: "complete",+ outcome: "complete",outputs: {"final.video": {type: { module: { name: "example", version: "1" }, name: "Video" },@@ -160,18 +121,27 @@ test("Studio opens project Build Results without a Runtime or ResourceStore", as},}, null, 2)}\n`, "utf8");- const archive = await openStudioArchive(undefined, root, root);- assert(archive !== undefined);- const view = await archive.library();+ const buildLibrary = await openStudioBuildLibrary(undefined, root, root);+ assert(buildLibrary !== undefined);+ const view = await buildLibrary.library();assert.equal(view.runtime, undefined);+ assert.deepEqual(view.tasks.map((item) => [item.id, item.title, item.status]), [+ [build, "First cut", "complete"],+ ]);assert.deepEqual(view.artifacts.map((item) => [item.build, item.output, item.valuePath]), [- ["build-one", "final.video", "$"],+ [build, "final.video", "$"],]);- assert.deepEqual((await archive.openArtifact("build-one", "final.video", "$"))?.bytes, bytes);- const record = await archive.resolveBuildRecord("build-one", "final.video");+ const artifact = await buildLibrary.openArtifact(build, "final.video", "$");+ assert.notEqual(artifact, undefined);+ const stream = await artifact!.open({ start: 2, endExclusive: 8 });+ assert.notEqual(stream, undefined);+ const opened: number[] = [];+ for await (const chunk of stream!) opened.push(...chunk);+ assert.deepEqual(Uint8Array.from(opened), bytes.slice(2, 8));+ const record = await buildLibrary.resolveHistoricalOutput(build, "final.video");assert.equal(record?.value.kind, "blob");assert.equal(record?.attachments?.length, 1);- await archive.close();+ await buildLibrary.close();} finally {await rm(root, { recursive: true, force: true });}diff --git a/packages/studio/test/temporal-graph.test.ts b/packages/studio/test/temporal-graph.test.tsindex 53ab17a5..7b90abb2 100644--- a/packages/studio/test/temporal-graph.test.ts+++ b/packages/studio/test/temporal-graph.test.ts@@ -44,11 +44,10 @@ test("Studio reads Instant lineage and author authority from executed graph edgeconst state = {format: "hypit.build@1",program: { closure: { modules: [] }, records: program },- graph: { format: "hypit.graph@1", outputs: [], candidates: [], operations: [] },- request: { format: "hypit.build-request@1", targets: [{ output: "visual" }] },+ targets: [{ output: "visual" }],plan: {format: "hypit.plan@1", steps, goals: [{ record: "track", type: type("@hypit/composition", "VisualTrack") }],- selections: [{ output: "visual", candidate: "visual-candidate", record: "track" }],+ outputBindings: [{ output: "visual", record: "track", type: type("@hypit/composition", "VisualTrack") }],},status: "complete", records: executed, steps: steps.map(({ id }) => ({ id, status: "complete" as const })),needs: [], outstanding: [], diagnostics: [],diff --git a/packages/video-cli/README.md b/packages/video-cli/README.mdindex a1605382..caf65e4f 100644--- a/packages/video-cli/README.md+++ b/packages/video-cli/README.md@@ -16,10 +16,11 @@ hypit check main.svmlhypit plan build.svrunhypit build build.svrun --followhypit status <build-id> --watch+hypit activityhypit buildshypit history [source-output-name] [--source ./main.svml] [--pin] [--exclude-targets]hypit inspect <build-id>-hypit get <build-id> --name final.video --to ./final.mp4+hypit get <build-id> --output final.video --to ./final.mp4hypit cancel <build-id>hypit doctorhypit gc@@ -42,37 +43,32 @@ the Script-owned deterministic CaptionDocument alongside real local/remote Endpofabricates a Target, Candidate or missing fact.`build` compiles one immutable Build Definition and passes it to the selected Runtime Profile with a fresh,-automatically assigned execution id. Source or Plan identity never reclaims an earlier Build; reuse+automatically assigned Build id. The id begins with its UTC creation time, so repository order is both+stable and visible; its random suffix prevents same-millisecond collisions and says nothing about content.+Source or Plan identity never reclaims an earlier Build; reuseacross Builds exists only through explicit Run Source Candidates. JSON Profiles resolve only adapters in their separatelyselected `use` fields and contain no executable callback. The CLI imports no Provider. A TypeScript configmodule remains trusted deployment code with normal Node authority. Neither form is discovered froma source import.Without `--follow`, `build` returns after durable submission and the detached Worker continues.-With `--follow`, the CLI observes dispatch and Operation facts until terminal state or+With `--follow`, the CLI observes Build activity and Operation facts until a Result outcome or`--max-wait-ms`; Ctrl-C only detaches that observer. `status` reads durable verified state, and`status --watch` reattaches the same kind of observer to an existing Build. The CLIcontrols Builds, not individual Operations. Cancelling a Build atomically withdraws it before claim,or marks running work for one best-effort Provider cancellation call after claim. It never selectsanother Candidate. None of these commands creates or stores a ready-Command queue.-`build` archives every accepted Record in the demanded closure and every referenced byte Artifact,-whether or not the user wants a conventional filesystem copy. `inspect` lists Targets, demanded-Logical Outputs, accepted Records and their Artifact references. `get` reads one accepted Record;-without a selector it requires one distinct target, while `--name`, `--record` and `--output` select-a source output alias, accepted Record or demanded Logical Output. `--artifact` selects any nested-BlobRef that the Build actually references. `--to` copies an Artifact or writes an inline structured-value as JSON. It is Host egress only and never changes Build identity or retention.-Blob egress uses the Store's streaming facet, verifies the declared size and content digest while-writing a temporary file, then atomically replaces the requested destination. A large video is not-loaded into CLI memory and a corrupt stream cannot overwrite an existing export.+The Result saves every public Author Output completed on the demanded route, including structured+values such as semantic takes. Each Logical Output has exactly one public name in `publishedOutputs`;+there are no Record, Artifact or alias selectors. `inspect` shows those Outputs, and `get --output`+reads one exact name. `--to` copies a file or writes an inline structured value as JSON. This is Host+egress only and never changes Build identity or retention. File streaming writes a temporary file and+then atomically replaces the destination, so large video need not be loaded into CLI memory.-`builds` and source aliases come from an optional Host `BuildCatalog`. The Catalog contains paths-and presentation names only. It is not Core truth; `inspect` and `get`-always resolve the alias back through the verified BuildState before accepting it.-`history` searches those frozen Catalog names across Builds, but reports only Logical Outputs whose-selected Record is present in the reconstructed Build view. It neither infers renames nor lists unbuilt-aliases; an old Catalog name and a current output name are connected explicitly in the Run Source.+`builds` and `history` browse project-owned Result manifests newest first. `--before <build-id>` moves+the cursor to older Results without a central history table. Presentation titles, notes and highlights+live in the Result manifest and may be edited without changing the Build id or the saved Outputs.Historical Records, fixed files and generated previews are declared as ordinary Candidates in theRun Source and selected by explicit Satisfaction edges. The Host verifies a referenced prior Builddiff --git a/packages/video-cli/src/distribution.ts b/packages/video-cli/src/distribution.tsindex f8f10f9e..589fe4e6 100644--- a/packages/video-cli/src/distribution.ts+++ b/packages/video-cli/src/distribution.ts@@ -1,5 +1,9 @@import type { CliDistribution } from "@hypit/cli";-import { openLocalRuntimeHost } from "@hypit/runtime-local";+import {+ doctorProjectBuildResultRepository,+ openLocalRuntimeHost,+ openProjectBuildResultRepository,+} from "@hypit/runtime-local";import { fileURLToPath } from "node:url";import { resolve } from "node:path";import {@@ -41,4 +45,14 @@ export const videoCliDistribution: CliDistribution = {: [installedLauncher],},}),+ openProjectResults: async (projectRoot, options) => {+ const opened = await openProjectBuildResultRepository(projectRoot, options);+ return {+ location: opened.location,+ repository: opened.repository,+ close: async () => await opened.close?.(),+ };+ },+ diagnoseProjectResults: async (projectRoot, options) =>+ await doctorProjectBuildResultRepository(projectRoot, options),};diff --git a/packages/video-cli/src/index.ts b/packages/video-cli/src/index.tsindex efea0791..e2164ff7 100644--- a/packages/video-cli/src/index.ts+++ b/packages/video-cli/src/index.ts@@ -1,8 +1,4 @@-import {- materializeArtifact,- materializeRecord,- runCli,-} from "@hypit/cli";+import { runCli } from "@hypit/cli";import type { CliIo } from "@hypit/cli";import {installDistributionPackageResolution,@@ -13,7 +9,6 @@ import type { LoadedPackage } from "@hypit/package-loader-node";import { videoCliDistribution } from "./distribution.js";-export { materializeArtifact, materializeRecord };export {createVideoCompiler,} from "./compiler.js";diff --git a/packages/video-cli/test/cli.test.ts b/packages/video-cli/test/cli.test.tsindex e146a509..08112369 100644--- a/packages/video-cli/test/cli.test.ts+++ b/packages/video-cli/test/cli.test.ts@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";import { join } from "node:path";import test from "node:test";-import { materializeRecord, runVideoCli, videoCliDistribution } from "@hypit/video-cli";+import { runVideoCli, videoCliDistribution } from "@hypit/video-cli";import { videoTestPackages } from "./packages.js";@@ -130,31 +130,3 @@ test("image writes one picture file with no Source, Build, Record or Runtime Proawait rm(root, { recursive: true, force: true });}});--test("materializeRecord copies an archived Artifact without rerunning a Build", async () => {- const root = await mkdtemp(join(tmpdir(), "hypit-cli-get-"));- try {- const bytes = Buffer.from("final-video-bytes");- const artifactResource = "res_archived-final-video";- const output = join(root, "final.mp4");- const runtime = {- async openResource(resource: string) {- return resource === artifactResource ? (async function* () { yield bytes; })() : undefined;- },- } as Parameters<typeof materializeRecord>[0];- const record = {- id: "final.video",- value: { kind: "inline", value: { resource: artifactResource, size: bytes.byteLength, mediaType: "video/mp4" } },- } as unknown as Parameters<typeof materializeRecord>[1];- const result = await materializeRecord(runtime, record, output);- assert.deepEqual(result, {- kind: "artifact",- resource: artifactResource,- mediaType: "video/mp4",- size: bytes.byteLength,- path: output,- });- } finally {- await rm(root, { recursive: true, force: true });- }-});diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 3879bdf9..de3e665c 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -561,6 +561,9 @@ importers:'@hypit/build-result':specifier: workspace:*version: link:../build-result+ '@hypit/build-result-kit':+ specifier: workspace:*+ version: link:../build-result-kit'@hypit/compiler-node':specifier: workspace:*version: link:../compiler-node@@ -2662,6 +2665,9 @@ importers:'@hypit/component-kit':specifier: workspace:*version: link:../component-kit+ '@hypit/core':+ specifier: workspace:*+ version: link:../core'@hypit/driver-node':specifier: workspace:*version: link:../driver-node@@ -2693,9 +2699,6 @@ importers:specifier: workspace:*version: link:../validationdevDependencies:- '@hypit/core':- specifier: workspace:*- version: link:../core'@hypit/credential-store-env':specifier: workspace:*version: link:../credential-store-envdiff --git a/test/lockfile-refresh.mjs b/test/lockfile-refresh.mjsindex a477a261..c33117de 100644--- a/test/lockfile-refresh.mjs+++ b/test/lockfile-refresh.mjs@@ -10,8 +10,7 @@* So the lockfile is written with that directory set aside, and put back afterwards. Dependencies* declared inside `packages/` resolve identically either way; only the importers differ.*- * Run this after changing any package's dependencies. `repository-hygiene.test.mjs` refuses a- * lockfile written without it.+ * Run this after changing package dependencies to keep the committed lockfile reproducible.*/import { rename } from "node:fs/promises";import { existsSync } from "node:fs";diff --git a/test/repository-hygiene.test.mjs b/test/repository-hygiene.test.mjsdeleted file mode 100644index 2ba2e1a4..00000000--- a/test/repository-hygiene.test.mjs+++ /dev/null@@ -1,352 +0,0 @@-import assert from "node:assert/strict";-import { readdir, readFile, stat } from "node:fs/promises";-import { extname, relative, sep } from "node:path";-import test from "node:test";-import { fileURLToPath } from "node:url";-import ts from "typescript";--const repositoryRoot = new URL("../", import.meta.url);-const repositoryRootPath = fileURLToPath(repositoryRoot);-const scanRoots = ["docs", "examples", "packages", "services", "test"];-const rootTextFiles = ["README.md", "package.json", "pnpm-workspace.yaml", "tsconfig.json"];-const ignoredDirectories = new Set(["node_modules", "build", "dist", "output", ".hypit", ".svml", ".vitepress"]);-const textExtensions = new Set([- ".css", ".html", ".js", ".json", ".jsx", ".md", ".mjs", ".sh", ".svml", ".svrun",- ".svs", ".ts", ".tsx", ".txt", ".yaml", ".yml",-]);--async function repositoryEntries() {- const entries = [];- const visit = async (url) => {- for (const entry of await readdir(url, { withFileTypes: true })) {- if (entry.name.startsWith(".") || ignoredDirectories.has(entry.name)) continue;- const child = new URL(`./${entry.name}${entry.isDirectory() ? "/" : ""}`, url);- // Every rule below matches this path with a forward-slash pattern, so it has to be spelled- // one way on every platform. `URL.pathname` is neither: on Windows it carries a leading- // slash before the drive letter, and it percent-encodes a name containing a space.- const path = relative(repositoryRootPath, fileURLToPath(child)).split(sep).join("/");- entries.push({ path, child, isFile: entry.isFile() });- if (entry.isDirectory()) await visit(child);- }- };- for (const root of scanRoots) await visit(new URL(`./${root}/`, repositoryRoot));- return entries;-}--async function repositoryTextEntries() {- const entries = (await repositoryEntries()).filter((entry) =>- entry.isFile && textExtensions.has(extname(entry.path)));- for (const path of rootTextFiles) {- entries.push({ path, child: new URL(`../${path}`, import.meta.url), isFile: true });- }- return entries;-}--function lineOf(source, offset) {- return source.slice(0, offset).split("\n").length;-}--/**- * Every rule below filters `entry.path` against a forward-slash pattern. A scan that yields- * platform-shaped paths, or reaches the wrong tree, or reaches nothing at all, turns each of- * them into a loop that never enters its body — which reports exactly what a clean repository- * reports. This test is what makes the others mean anything.- */-test("the repository scan reaches the repository", async () => {- const entries = await repositoryEntries();- const paths = new Set(entries.map((entry) => entry.path));- assert.ok(paths.has("test/repository-hygiene.test.mjs"), "the scan must reach this file");- assert.deepEqual(entries.filter((entry) => entry.path.includes("\\")).map((entry) => entry.path).slice(0, 5), [],- "entry paths are repository-relative and separated by forward slashes");- const sources = entries.filter((entry) => /^packages\/[^/]+\/src\/.*\.ts$/u.test(entry.path));- assert.ok(sources.length > 300, `expected the package sources, found ${sources.length}`);- const manifests = entries.filter((entry) => /^packages\/[^/]+\/package\.json$/u.test(entry.path));- assert.ok(manifests.length > 50, `expected the package manifests, found ${manifests.length}`);-});--test("public repository contains no workstation paths or high-confidence secret bytes", async () => {- const workstationPath = /(?:\/Users\/[A-Za-z0-9._-]+\/|\/home\/[A-Za-z0-9._-]+\/|[A-Za-z]:\\Users\\[^\\]+\\)/gu;- const secretBytes = /(?:AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z_-]{30,}|-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----)/gu;- const failures = [];- for (const entry of await repositoryTextEntries()) {- const source = await readFile(entry.child, "utf8");- for (const match of source.matchAll(workstationPath)) {- failures.push(`${entry.path}:${lineOf(source, match.index)} (workstation path)`);- }- for (const match of source.matchAll(secretBytes)) {- failures.push(`${entry.path}:${lineOf(source, match.index)} (secret bytes)`);- }- }- assert.deepEqual(failures, [], `private repository residue found:\n${failures.join("\n")}`);-});--test("pre-release project-owned major identities remain at one", async () => {- const identity = /(?:\bsvml\.[a-z0-9._/-]+|@hypit\/[a-z0-9._/${}-]+)@([0-9]+)(?![.0-9])/giu;- const failures = [];- for (const entry of await repositoryEntries()) {- if (!entry.isFile || !textExtensions.has(extname(entry.path))) continue;- const source = await readFile(entry.child, "utf8");- for (const match of source.matchAll(identity)) {- if (match[1] !== "1") failures.push(`${entry.path}:${lineOf(source, match.index)} (${match[0]})`);- }- }- assert.deepEqual(failures, [], `non-@1 project identity found:\n${failures.join("\n")}`);-});--function propertyName(node) {- if (ts.isIdentifier(node) || ts.isStringLiteralLike(node)) return node.text;- return undefined;-}--function projectIdentityObject(node) {- const properties = new Map();- for (const property of node.properties) {- if (!ts.isPropertyAssignment(property)) continue;- const name = propertyName(property.name);- if (name !== undefined) properties.set(name, property.initializer);- }- const owner = properties.get("name") ?? properties.get("module");- return owner !== undefined- && ts.isStringLiteralLike(owner)- && owner.text.startsWith("@hypit/")- && properties.has("version")- ? properties.get("version")- : undefined;-}--test("project-owned production Module and Frontend identities use literal version one", async () => {- const failures = [];- for (const entry of await repositoryEntries()) {- if (!entry.isFile || !/^packages\/[^/]+\/src\/.*\.(?:ts|tsx)$/u.test(entry.path)) continue;- const source = await readFile(entry.child, "utf8");- const file = ts.createSourceFile(entry.path, source, ts.ScriptTarget.Latest, true,- entry.path.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);- const visit = (node) => {- if (ts.isObjectLiteralExpression(node)) {- const version = projectIdentityObject(node);- if (version !== undefined && (!ts.isStringLiteralLike(version) || version.text !== "1")) {- const { line } = file.getLineAndCharacterOfPosition(version.getStart(file));- failures.push(`${entry.path}:${line + 1} (${version.getText(file)})`);- }- }- ts.forEachChild(node, visit);- };- visit(file);- }- assert.deepEqual(failures, [],- `project-owned logical identities must use literal version \"1\":\n${failures.join("\n")}`);-});--/**- * Module specifiers this file really imports.- *- * Read from the syntax tree rather than the text: a template that generates a package writes the- * imports that package will have, and matching those would demand the generator depend on- * everything it can generate.- */-function packageImports(path, source) {- const file = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true,- path.endsWith(".tsx") ? ts.ScriptKind.TSX : path.endsWith(".mjs") ? ts.ScriptKind.JS : ts.ScriptKind.TS);- const found = [];- const take = (node) => {- if (node !== undefined && ts.isStringLiteralLike(node)) {- const match = /^(@hypit\/[a-z0-9-]+)(?:\/.*)?$/u.exec(node.text);- if (match !== null) found.push(match[1]);- }- };- const visit = (node) => {- if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) take(node.moduleSpecifier);- if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) take(node.arguments[0]);- ts.forEachChild(node, visit);- };- visit(file);- return found;-}--test("production imports belong to each package while the root owns repository tests", async () => {- const entries = await repositoryEntries();- const rootManifest = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));- const rootTestDependencies = new Set([- ...Object.keys(rootManifest.dependencies ?? {}),- ...Object.keys(rootManifest.devDependencies ?? {}),- ]);- const manifests = new Map();- for (const entry of entries) {- const match = /^packages\/([^/]+)\/package\.json$/u.exec(entry.path);- if (match === null) continue;- manifests.set(match[1], JSON.parse(await readFile(entry.child, "utf8")));- }- const failures = [];- for (const entry of entries) {- const match = /^packages\/([^/]+)\/(src|test)\/.*\.(?:ts|tsx|mts|cts|mjs)$/u.exec(entry.path);- if (match === null) continue;- const [directory, area] = [match[1], match[2]];- const manifest = manifests.get(directory);- if (manifest === undefined) {- failures.push(`${entry.path} (package has no package.json)`);- continue;- }- const allowed = new Set([- ...Object.keys(manifest.dependencies ?? {}),- ...(area === "test" ? [- ...Object.keys(manifest.devDependencies ?? {}),- ...rootTestDependencies,- ] : []),- ]);- const source = await readFile(entry.child, "utf8");- for (const dependency of new Set(packageImports(entry.path, source))) {- if (dependency !== manifest.name && !allowed.has(dependency)) {- failures.push(`${entry.path} (${dependency})`);- }- }- }- assert.deepEqual(failures, [], `undeclared package imports found:\n${failures.join("\n")}`);-});--function objectProperties(node) {- const properties = new Map();- for (const property of node.properties) {- if (!ts.isPropertyAssignment(property)) continue;- const name = propertyName(property.name);- if (name !== undefined) properties.set(name, property.initializer);- }- return properties;-}--/** A Surface declaration that publishes a VisualTrack draws something a reader has to see. */-function visualSurfaceTag(node) {- const properties = objectProperties(node);- const tag = properties.get("tag");- const outputs = properties.get("outputs");- if (tag === undefined || outputs === undefined || !ts.isArrayLiteralExpression(outputs)) return undefined;- const visual = outputs.elements.some((element) => element.getText().includes("visualTrack"));- if (!visual || !ts.isStringLiteralLike(tag)) return undefined;- const vocabulary = properties.get("vocabulary");- const declaresPreview = vocabulary !== undefined- && ts.isObjectLiteralExpression(vocabulary)- && objectProperties(vocabulary).has("preview");- return declaresPreview ? undefined : tag.text;-}--test("a Surface that draws declares a preview at all", async () => {- // The check below only fires once a preview is declared, so a package that skips the declaration- // escapes it entirely — and a component that cannot draw itself is exactly the one whose author- // never got a preview out of it. Publishing a VisualTrack is the structural signal, independent- // of whether anyone remembered to promise a picture.- const entries = await repositoryEntries();- const failures = [];- for (const entry of entries) {- if (!entry.isFile || !/^((?:examples\/[^/]+\/)?packages\/[^/]+)\/src\/.*\.ts$/u.test(entry.path)) continue;- const source = await readFile(entry.child, "utf8");- if (!source.includes("visualTrack")) continue;- const file = ts.createSourceFile(entry.path, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);- const visit = (node) => {- if (ts.isObjectLiteralExpression(node)) {- const tag = visualSurfaceTag(node);- if (tag !== undefined) failures.push(`${entry.path} declares ${tag}, which publishes a VisualTrack and promises no preview`);- }- ts.forEachChild(node, visit);- };- visit(file);- }- assert.deepEqual(failures, [], `drawing Surfaces without a preview:\n${failures.join("\n")}`);-});--test("a declared Surface preview names a picture that exists", async () => {- // A component that cannot draw itself cannot produce a preview image. Declaring one and shipping- // nothing is how that goes unnoticed: the declaration reads as evidence the component renders.- const entries = await repositoryEntries();- const failures = [];- for (const entry of entries) {- const match = /^((?:examples\/[^/]+\/)?packages\/[^/]+)\/src\/.*\.ts$/u.exec(entry.path);- if (match === null || !entry.isFile) continue;- const source = await readFile(entry.child, "utf8");- // Read the syntax tree, not the text: a template that generates a package writes the preview- // call that package will have, and its filename is an interpolation rather than a path.- const parsed = ts.createSourceFile(entry.path, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);- const declaredNames = [];- const collect = (node) => {- if (ts.isCallExpression(node)- && ts.isIdentifier(node.expression)- && node.expression.text === "previewImage"- && node.arguments.length === 1- && ts.isStringLiteral(node.arguments[0])) {- declaredNames.push(node.arguments[0].text);- }- ts.forEachChild(node, collect);- };- collect(parsed);- for (const declared of declaredNames.map((name) => [undefined, name])) {- const file = new URL(`./${match[1]}/preview/${declared[1]}`, repositoryRoot);- const size = await stat(file).then((item) => item.size, () => undefined);- if (size === undefined) failures.push(`${entry.path} declares preview/${declared[1]}, which does not exist`);- else if (size === 0) failures.push(`${entry.path} declares preview/${declared[1]}, which is empty`);- }- }- assert.deepEqual(failures, [], `declared previews without a picture:\n${failures.join("\n")}`);-});--/** The `child_process` entry points that start a program, and where each one takes its options. */-const PROCESS_STARTERS = new Map([- ["spawn", 2], ["spawnSync", 2], ["execFile", 2], ["execFileSync", 2], ["fork", 2],- ["exec", 1], ["execSync", 1],-]);--test("every child process is started with its console window hidden", async () => {- // On Windows a console program started without `windowsHide` is given a window, and the window- // is shown. A render is a tree of them — ffmpeg per Need, a browser, a transcriber that re-execs- // Python, which opens a pool of workers — so the flag being absent is not one window but dozens,- // opening and closing over whatever the author was doing. There is no call here that wants one.- const entries = await repositoryEntries();- const failures = [];- for (const entry of entries) {- if (!entry.isFile || !/\.(?:ts|tsx|mts|cts|mjs)$/u.test(entry.path)) continue;- const source = await readFile(entry.child, "utf8");- if (![...PROCESS_STARTERS.keys()].some((name) => source.includes(name))) continue;- const file = ts.createSourceFile(entry.path, source, ts.ScriptTarget.Latest, true,- entry.path.endsWith(".tsx") ? ts.ScriptKind.TSX- : entry.path.endsWith(".mjs") ? ts.ScriptKind.JS : ts.ScriptKind.TS);- const visit = (node) => {- if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {- const at = PROCESS_STARTERS.get(node.expression.text);- const options = at === undefined ? undefined : node.arguments[at];- // Only a literal can be read here. A call that passes its options along has none to check,- // and is answered where the object it passes was written.- if (options !== undefined && ts.isObjectLiteralExpression(options)- && !objectProperties(options).has("windowsHide")) {- const { line } = file.getLineAndCharacterOfPosition(options.getStart(file));- failures.push(`${entry.path}:${line + 1} (${node.expression.text})`);- }- }- ts.forEachChild(node, visit);- };- visit(file);- }- assert.deepEqual(failures, [], `child processes started with a visible console:\n${failures.join("\n")}`);-});--/**- * `pnpm-workspace.yaml` reaches into `projects/`, which `.gitignore` excludes, so a local install- * writes an importer for every project-local package into a file the repository commits. A clone has- * no such directory, so `pnpm install --frozen-lockfile` — what CI runs — refuses a lockfile carrying- * one.- *- * The failure that made this worth checking was not the importer itself. It was that the lockfile is- * dirty after every local install, so its diff stops being read, and a real dependency added to a- * package goes in without it. That shipped three times.- *- * `pnpm lockfile:refresh` writes a lockfile this accepts.- */-test("the lockfile names no importer git does not track", async () => {- const lockfile = await readFile(new URL("./pnpm-lock.yaml", repositoryRoot), "utf8");- const ignored = (await readFile(new URL("./.gitignore", repositoryRoot), "utf8"))- .split("\n").map((line) => line.trim())- .filter((line) => line.length > 0 && !line.startsWith("#") && !line.startsWith("!"))- .map((line) => line.replace(/^\/+/u, "").replace(/\/+$/u, ""))- .filter((line) => !line.includes("*") && line.length > 0);- const importers = [...lockfile.matchAll(/^ {2}([^\s:][^:]*):$/gmu)].map((match) => match[1]);- const carried = importers.filter((importer) =>- ignored.some((entry) => importer === entry || importer.startsWith(`${entry}/`)));- assert.deepEqual(carried, [],- `the lockfile carries importers under a path git ignores:\n${carried.join("\n")}\n\nrun: pnpm lockfile:refresh`);-});diff --git a/test/run.mjs b/test/run.mjsindex cdacad13..d21465e9 100644--- a/test/run.mjs+++ b/test/run.mjs@@ -12,7 +12,6 @@* checked.** node test/run.mjs every unit test- * node test/run.mjs browser-visual the browser suite, which needs a browser and ffmpeg* node test/run.mjs image-opencv the OpenCV suite, which needs the service's interpreter*/import { spawnSync } from "node:child_process";@@ -43,10 +42,6 @@ function managedPython(project) {}const suites = {- "browser-visual": {- files: ["packages/hyperframes/test/browser-visual.test.ts"],- env: { HYPIT_BROWSER_TESTS: "1" },- },"image-opencv": {files: ["packages/provider-image-opencv-local/test/provider.test.ts"],env: {