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
release: prepare 0.1.6 and align production guidance
kashorin4af8ae1b1e79
diff --git a/docs/guide/runtime.md b/docs/guide/runtime.mdindex 8c3f78fd..6c4c4bba 100644--- a/docs/guide/runtime.md+++ b/docs/guide/runtime.md@@ -1,274 +1,162 @@---title: Runtime-description: The execution boundary outside Hypit source and Core.+description: Select execution services, run independent Builds and keep their Results available.----Hypit keeps four decisions separate:+The Source describes the work. The Run chooses its Targets and Candidates. The Runtime executes+those choices using the selected services; the project keeps the resulting Outputs.-| Owner | Decides |-|---|---|-| Workspace | Which source files and local assets compilation may read |-| Runtime Profile | Which environmental packages may be used |-| Local Runtime | How active Builds are durably advanced and observed |-| Project Build Results | Which completed public Outputs belong to each Build |+| Owner | Responsibility |+| --- | --- |+| Project | Sources, assets, component packages and the selected Runtime Profile |+| Distribution | The installed executable, public SDKs and execution implementation |+| Runtime Profile | Provider Endpoints, credential references, bindings and shared capacity |+| Build | One execution attempt using the selected graph and configuration |+| Result repository | Completed public Outputs, outcome and retained execution evidence |-Core is a domain neutral state machine. It accepts facts, derives Commands and verifies returned-Records. It does not start processes, read credentials, choose Providers or know that a Build makes-video.+Core plans and advances dependencies without knowing that they make a video. A new component or+[Provider](./providers.md) supplies its behavior through the same package interfaces.-`@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.+## Select the project and Profile++Run commands from the video project, or select it explicitly with `--workspace`. Otherwise the+nearest `package.json` above the current directory establishes the project; when none exists, the+current directory is the project. Source filenames and Runtime configuration do not choose this boundary.++```bash+hypit paths+hypit runtime init+```++`runtime init` writes an editable starter `hypit.runtime.json` and selects it through the project's+`.hypit/runtime` file. It preserves an existing Profile and performs no installation, login or execution.+The starter offers HypiHub for hosted generation and WhisperX, with local media processing and rendering.+Choose the services that fit the work before preparing them. Local inference and project Providers can+use the same setup, including alongside HypiHub.++Use `hypit runtime use <profile>` to select an existing Profile. An explicit `--runtime <profile>`+overrides it for one invocation. Commands read only the selected project's pointer; they do not inherit+another project's selection. Relative command-line paths are relative to the current directory.## Runtime Profile-The Profile contains only environmental choices that genuinely vary:+A small local-processing Profile looks like this:```json{"format": "hypit.runtime-local@1","dataRoot": ".hypit/runtimes/local",- "credentials": {- "env": { "use": "@hypit/credential-store-env" }- },+ "credentials": {},"endpoints": {- "media": { "use": "@hypit/provider-media-local" }+ "media.local": { "use": "@hypit/provider-media-local" }},"bindings": {}}```-* `credentials` selects stores for explicit credential references.-* `endpoints` selects exact Provider implementations and their configuration.-* `bindings` says which Endpoint serves a capability that several selected Endpoints offer, keyed by- `name@version#capability` and naming an Endpoint instance. Providers never hide what they can do;- this is the deployment's decision, and `doctor` reports a contested capability that lacks one.--The official video Distribution selects the local Runtime before opening this file. The Profile-does not repeat a `runtime.use` selector that cannot make another choice. Another application may-provide a different Runtime Host at its Distribution assembly boundary without changing Core or-the generic CLI.+`dataRoot` locates active execution data and working files, separately from the `.hypit/runtime`+selection file. Each `endpoints` entry selects an installed Provider and its configuration. Credentials+use references into a selected store; secret values stay outside the Profile and Sources.-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:+A single compatible Endpoint can serve a capability without a binding. When several offer it, a+binding states which instance to use. For example, with an explicitly configured local WhisperX:```json-{- "format": "hypit.build-results@1",- "use": "@hypit/build-result-fs",- "config": { "path": ".hypit/results" }+"bindings": {+ "@hypit/whisperx@1#whisperx-alignment": "whisperx.local"}```-Installing a package only makes an implementation available. A Profile must select it. The Profile-contains no Workspace, author imports or creative routing.--## Local state--Selecting a Profile writes a project pointer. Execution data stays under `dataRoot`:--```text-.hypit/- runtime- runtimes/- local/- runtime.sqlite- work/- worker/- programs/- results/- <UTC-date>/- <build-id>/- result.json- files/- values/-```+Installing a package makes it available; selecting it gives it a role in this environment. The Model+owns request meaning, and the Provider owns support, service mapping and pricing. A failed service+request does not silently select another account. Read the chosen Provider's README for its settings.-`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 the-default repository, `.hypit/results/<UTC-date>/<build-id>/result.json` names final Targets and every public-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 repository-location 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:+## Prepare only the services needed now-```json-{- "format": "hypit.build-results@1",- "use": "@hypit/build-result-s3",- "config": {- "bucket": "my-video-results",- "prefix": "projects/episode-12",- "region": "us-east-1"- }-}+```bash+hypit auth status+hypit doctor --endpoint media.local+hypit runtime up --endpoint media.local+hypit runtime status```-The AWS SDK uses its normal credential chain. `endpoint` and `forcePathStyle` are available for-S3-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, Provider capacity or-an active Build's temporary Resources into the bucket.+Use the actual Endpoint names from the Profile; repeat `--endpoint` for several. Omission covers the+whole Profile. `doctor` reads configuration and performs the selected Providers' diagnostics without+submitting generation. Read warnings as well as errors: a stored credential or reachable catalogue+is not proof that every request will succeed. With no Runtime selected, doctor checks project Results only.-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 Repository as well as the Runtime;-the storage check performs only a bounded read-only listing and does not scan Result history.+`runtime up` prepares the selected local dependencies and Managed Programs, then starts the Worker.+It does not log into or start hosted services. `programs up|status|down` manages those local helpers+separately. Initial inference setup can require substantial downloads; compare that effort with hosted+execution and choose the route before starting preparation.-The Workspace is resolved independently from the explicit `--workspace`, the project containing the-Runtime pointer, or the entry source directory. Runtime configuration cannot widen source access.+`plan <run>` checks the work's demanded capabilities and cheap readiness. Provider discovery needs+installed package declarations; it may load other declared Endpoints when no explicit binding selects+a route. Unused services need not be running or logged in. `build` provisions nothing: it requires+its dependencies ready, starts an available Worker if necessary, and submits one Build.+[Runs and Builds](../quickstart/run.md) explains planning, prices, authorization and explicit reuse.-## Execution turns and concurrency+## Execute independently of the terminal-`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.+```bash+hypit build build.svrun --follow+hypit status <build-id> --watch+hypit logs <build-id> --lines 80+```-Each Endpoint instance is its own capacity pool by default. A Profile may give several Endpoint-instances the same `pool` only when they truly share one account, deployment or compute quota;-Endpoint packages may also apply a narrower exact-model limit. These are capacity claims, not queues.-Work from separate Builds shares only those exact resources. 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.+The Worker owns execution. `--follow` and `status --watch` observe it; closing that terminal or reaching+a watch timeout does not cancel the Build. To stop a specific attempt, use `hypit cancel <build-id>`.+Remote cancellation is best effort, and completed Outputs remain available.-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.+A failed attempt stays failed. A new Run can select its useful Outputs for a new Build. If execution+has finished but Result storage needs attention, `status` names `hypit result finish <build-id>`:+that completes the pending save, without executing generation again.-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.+Build logs retain Provider phases and diagnostics. `runtime logs` instead reads Worker startup and+process errors; installation and service logs belong to the selected Managed Program. A missing+terminal transcript does not imply missing execution evidence.-## Managed Programs+## Share capacity, retain independent work-An Endpoint may declare a long-lived helper such as a warm local WhisperX service. The Endpoint owns-its probe and optional start command; the local Runtime only supervises it.+Several Builds can progress together. Limits belong to the account, deployment or local compute+resource using them. Remote waiting does not reserve a whole-Build slot that blocks unrelated local+work. Providers can distinguish active tasks from short submit, poll and collect calls. Inspect+`hypit activity --verbose` for shared capacity alongside active work.-```bash-hypit programs status-hypit programs up-hypit programs down-```+Builds use independent loaded project implementations and selected configuration. Editing a project+component or Profile applies to the next Build; already started work keeps its loaded implementation.+Managed Programs have separate lifetimes, so a warm WhisperX model can serve multiple Builds.-`programs up` first prepares the selected Endpoint packages' upstream npm dependencies, then operates-their declared programs. The commands do not open SQLite or Credential Stores.+Distribution updates and changes to the Worker's inherited shell environment concern its process+lifetime. Inspect active work before restarting it: `runtime down` ends active execution contexts,+while `programs down` stops helpers separately. A lost executor ends its attempts; continuation uses+new Builds and explicit reuse. This is execution separation, not a security sandbox or a frozen copy+of files a component reads later.-## Lifecycle+## Keep products with the project-```bash-hypit runtime init-hypit runtime use hypit.runtime.json-hypit runtime up-hypit runtime status-hypit runtime logs-hypit runtime down+Without extra configuration, Results live in `.hypit/results`. A project can select another location+or repository through `hypit.results.json`, independently of its Runtime Profile:++```json+{+ "format": "hypit.build-results@1",+ "use": "@hypit/build-result-fs",+ "config": { "path": ".hypit/results" }+}```-`runtime init` writes the video Distribution's starter Profile to `hypit.runtime.json` and selects-it for the resolved project. It refuses to overwrite an existing file. This is a local file operation:-it installs no package, contacts no service, requests no credential and starts no Worker. The official-starter selects HypiHub for remote generation, WhisperX, plus local media processing and-HyperFrames rendering. This is a Distribution default, not a Core rule; edit the Profile or select a-different one when using BYOK or local Providers.--`runtime use` binds one explicit Profile to one already resolved project. The project comes from-`--workspace`, or from the current directory's declared package boundary; the selection never-defines that boundary. Commands read only `<project>/.hypit/runtime`: they do not scan for a-conventionally named Profile and do not inherit a selection from a parent project. Separate projects-therefore select separately, even when their Profiles declare equivalent external Endpoints.--`runtime up` asks npm to prepare the selected adapters' exact upstream packages in the shared-machine home, prepares declared **local** Managed Programs, then starts the local Worker. It does not-start, restart, log into or probe remote Endpoints such as HypiHub. `runtime down` stops only the-local Worker and its execution processes; separately managed local Programs remain available until `programs down`.--Use `--endpoint <instance>` on `runtime up`, `programs up|status|down`, or `doctor` to operate on a-chosen service; repeat it for several services. Omitting it covers the whole Profile. Build planning-checks the Endpoints actually selected for that work. Optional upstream package versions have separate-installations, so preparing one version does not replace another; npm retains its shared download cache.--`doctor` is the active read-only environment check. It resolves declared credentials and lets each-selected Endpoint verify its real environment; a remote Provider may therefore contact its bounded-catalog or capability endpoint. Login proves only that a credential exists, while a successful doctor-proves that the selected Endpoint's declared capabilities can be routed by that account at that moment.-Ordinary `check`, `plan` and Build preflight-never run these active probes and never turn environment inspection into a hidden network request.--`build` performs no provisioning: it runs cheap read-only preflight, submits work only when ready, and ensures the Worker-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. After a hard interruption, the coordinator-clears abandoned Result-writer leases. An already decided Build whose Result writing was interrupted retains attention-for `result finish`; a Build that lost its executor is concluded and its available facts are written to-Result. Missing bytes fail explicitly instead of being regenerated.-Reusing an earlier Result is an explicit Candidate in a new `.svrun`, not hidden Runtime behavior.--Each Build uses its own loaded project implementation and selected Provider configuration. Editing project components or changing Profile selections therefore applies to the next-Build while already started work keeps its loaded implementation. Managed Programs keep their own-lifetime, so a warm model remains available across Builds. Concurrent Builds share execution-infrastructure. Remote waiting does not reserve a whole-Build slot; declared resource limits apply-to the work using those resources.-The local Runtime can rotate execution processes as completed-work memory accumulates: existing Builds-finish in their current process while new Builds use another. Warm services stay available.--If an executor is lost, its affected attempts end with completed Outputs and available remote receipts;-it is not restarted with newly edited code. Continue through a new Build and explicit reuse. Files-read later by a component retain ordinary filesystem semantics. Distribution updates and changes to-the coordinator's inherited shell environment still require restarting that bootstrap process after-preserving active work.--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.+The S3 adapter can instead store Results in a bucket and project prefix. The selected adapter owns+access and credentials; changing Result storage does not move the active Runtime or upload external+file references automatically. A submitted Build retains its chosen destination, and changing that+selection does not migrate history.++Results publish completed public Outputs as they become available and retain the terminal outcome.+A new Output can reference an existing file, including within a composite; it does not necessarily+create new media bytes. Explicit local file references remain live. Keep dependencies available for+future reuse. `get` creates a separate export when a person or another tool needs those files.++`builds`, `history`, `inspect` and `get` read project Results without requiring the original Runtime.+For exact storage and execution interfaces, see the+[Result package](https://github.com/hypit-ai/hypit/blob/main/packages/build-result/README.md) and+[local Runtime package](https://github.com/hypit-ai/hypit/blob/main/packages/runtime-local/README.md).diff --git a/docs/guide/studio-companion-architecture.md b/docs/guide/studio-companion-architecture.mdindex 802b09e0..a6bed47b 100644--- a/docs/guide/studio-companion-architecture.md+++ b/docs/guide/studio-companion-architecture.md@@ -29,7 +29,7 @@ internal drawing value.Studio supplies the controls and interactions. A Companion selects scalar, list or record controlsand binds them to source values. A Film Companion identifies the Film's time source and Tracks;a Script Companion supports the source mapping needed to relocate Selection and Moment markers.-An authored ProgramSpace supports animation without a Script lane.+The same Timeline supports animation with no Takes or Script lane; its authored end defines the extent.## Make edits meaningfuldiff --git a/docs/guide/studio-temporal-windows.md b/docs/guide/studio-temporal-windows.mdindex 9e922f88..b4cba959 100644--- a/docs/guide/studio-temporal-windows.md+++ b/docs/guide/studio-temporal-windows.md@@ -32,8 +32,8 @@ The identity chain is author-visible rather than synthesized by Studio:- `<script id="story">` becomes `Narrative.id = story`; every Selection, Moment, Segment excerptand CaptionDocument from that Script carries `narrativeId = story`;-- the selected Timeline id becomes `ProgramSpace.id`; every terminal Track carries that exact- `programSpaceId`;+- every terminal Track's `programSpaceId` names the selected Timeline. `ProgramSpace` is the shared+ clock/range shape contained in Timeline, not a second author-declared time axis;- every projected Instant carries the space identity; semantic sources also carry the Narrativeidentity. Each includes the consumer's public domain identity (normally its SVML `id`) as `subjectId`.@@ -43,8 +43,9 @@ identity published by the component's public Program.These values are ordinary runtime provenance, not random hashes or Studio metadata. They let aconsumer and its inverse reject a same-named Selection from another Script or a Track projected on-another timeline. A Script id therefore names one Narrative across the active Source closure; if two-distinct Scripts declare the same id, Studio refuses the ambiguous inverse instead of choosing one.+another timeline. A Script id therefore names one Narrative across the active Source closure.+The Script Surface declares that identity, and compilation rejects duplicates before Studio needs+to choose a source.A `TemporalWindow` contains two complete Instants and a non-empty half-open span. Its endpoints mayhave different sources and different authorities, so a Window never pretends to have one source.@@ -88,7 +89,7 @@ Film and Script interpretation also remain outside Studio core. `film-studio` dereference supplies the time axis and which child references are terminal Tracks; `script-studio` ownsScript source observation and marker relocation. Studio selects the Script source map whose`narrativeId` exactly matches the active Timeline and delegates the edit back to that companion.-An authored Space supplies the physical timeline without a Script lane.+A zero-Take Timeline supplies the same physical time range without requiring a Script lane.The binding name is not used as a global address. Markup retains the exact author element and inputrange while decoding, Elaborator hygienizes that endpoint with its Source unit, and the compileddiff --git a/docs/quickstart/run.md b/docs/quickstart/run.mdindex e967984d..3cdb19cf 100644--- a/docs/quickstart/run.md+++ b/docs/quickstart/run.md@@ -174,7 +174,8 @@ older one, Result storage resolves that explicit path once and records the new Fthe finished Result that owns the value; no bytes are copied and no reverse index is maintained.Forwarding applies only to a complete public Output. Structured JSON cannot recursively point atanother Output; a historical value consumed inside a new Fragment is an ordinary input and the new-Fragment's Output belongs to the current Result.+Fragment's Output belongs to the current Result. Its nested media still references the original files;+new JSON structure does not require copying the existing images, video or audio.### build-record@@ -193,13 +194,15 @@ Connects a Candidate to a Logical Output:| Attribute | Description ||---|---|| `output` | The Logical Output to satisfy |-| `candidate` | The Candidate id (from `build-record`) |+| `candidate` | The Candidate id declared by `build-record`, `file`, `value` or a Fragment export |The Planner reads the complete Author Graph and Run Graph together. It prunes default Operationsthat selected Candidates replace while retaining any Author Outputs the selected Candidate itselfstill consumes. This is a-new Build, not a continuation of the old one. Downstream processing (normalization, WhisperX,-captioning, rendering) still runs against the reused media.+new Build, not a continuation of the old one. Reusing generated video leaves normalization and semantic+preparation downstream; reusing a prepared SemanticTake retains those results too. Caption, MG and+rendering recompute where they remain on the selected route. Choose the Output whose meaning matches+what should stay unchanged.Core does not label a Candidate as “exact” or “substitute”. Choosing a Candidate is the Runauthor's explicit implementation decision for that Build. Type compatibility is checked; creative@@ -216,8 +219,9 @@ to one current Logical Output:```The file is read relative to the `.svrun`. If it becomes a completed public Output on the Target-route, it is written into the Build Result like any generated media. There is no hidden history-lookup. A supplied image, recorded video or other compatible result uses the same mechanism.+route, the Result records an explicit external-file reference. It does not copy the file into each+new Result. The reference remains live: replacing the file changes subsequent reads, and removing it+makes that dependency unavailable. A supplied image or recorded video uses the same mechanism.## Runtime Profile@@ -342,7 +346,8 @@ Doctor always validates the project's selected Result Repository. When a Runtimepassed explicitly, it also validates every selected Runtime role, Endpoint configuration, credentialpresence and bounded environment probe. It never starts the Worker or performs a paid request.-When a Profile is present, Doctor intentionally performs a **full profile audit**. For the environment required by one Run, use+With a Profile, Doctor checks the whole Profile unless scoped with repeated `--endpoint <instance>`+flags. For the environment required by one Run, use`plan`: it checks only capabilities demanded by that finite plan. Missing readiness is returned in`preflight` and gives the command a non-zero exit status, while the frozen plan remains available inJSON for inspection.@@ -357,8 +362,9 @@ hypit check reference.svmlhypit plan reference.svrun```-Review the frozen BuildPlan before spending money. The plan shows every Operation and Needs the-Scheduler would issue. With a selected Runtime, it also reports only the relevant Endpoint, credential and+Review the selected work before spending money. The default plan shows Targets, demanded external+requests and their available parameters; `--verbose` adds graph and Candidate-selection details.+With a selected Runtime, it also reports the relevant Endpoint, credential andexternal-program diagnostics. It never starts external work.`plan` may run without a Runtime at all. Both `plan` and `build` may omit `--runtime` after@@ -413,8 +419,9 @@ receipts remain available, and further execution uses a new Build with explicithypit inspect <build-id>```-`inspect` reads the project-owned Result directly and shows its Targets plus a bounded list of-completed public Outputs. Use `--output <name>` for one exact Output or `--limit <count>` to show more:+`inspect` reads the project-owned Result directly and shows its Targets, highlighted Outputs and+failure evidence. Use `--output <name>` for one exact Output, or `--verbose` to browse the other Outputs+and execution receipts. `--limit <count>` expands that detailed list. Export a selected Output with:```bashhypit get <build-id> \diff --git a/docs/quickstart/styles.md b/docs/quickstart/styles.mdindex 3dfe5bd1..285727e7 100644--- a/docs/quickstart/styles.md+++ b/docs/quickstart/styles.md@@ -44,7 +44,7 @@ The prefix comes from the `as=` attribute; the path comes from `namespace.name`## FilmFilm appearance owns only the canvas clear color. Canvas dimensions are an explicit-`space:Canvas` graph value, while frame rate comes from ProgramSpace.+`space:Canvas` graph value, while frame rate comes from the Timeline's Clock.```svsfilm.vertical {diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.mdindex 44e1dc90..a12fd360 100644--- a/docs/quickstart/tracks.md+++ b/docs/quickstart/tracks.md@@ -283,8 +283,9 @@ places flowing text inside a `SpatialFrame`:| `placement` | yes | `SpatialPoint`, `SpatialFrame` or `SpatialPath`, matching the item form || `style` | yes | A `text:Style` compiled from an SVS Recipe plus exact font bytes |-The `during` attribute accepts either the literal string `"program"` for the complete ProgramSpace,-or a Selection reference for semantic timing:+The `during` attribute accepts the literal string `"program"` for the complete Timeline,+or a Selection or Segment reference for semantic timing. The same temporal interface also accepts+authored `start`/`end` windows and `at`/`for` events:```svml<text:Style id="callout-style" recipe={recipes.text.callout} font={title-font}/>@@ -387,8 +388,8 @@ same Frame and moves the whole stack.### deck:DepthStack-`id`, `canvas`, `frame` and `appearance` are required, together with `semantic` for performance time-or `space` for authored animation. `until` says+`id`, `timeline`, `canvas`, `frame` and `appearance` are required. The same Timeline supplies authored+times and any placed semantic anchors. `until` sayswhat ends the deck: a Moment, a Selection or Segment boundary, or an authored time such as `8s`.With a Selection or Segment, `until-boundary="start" | "end"` chooses its edge; the default is `end`.diff --git a/docs/zh/guide/runtime.md b/docs/zh/guide/runtime.mdindex d37416f2..f4ca3775 100644--- a/docs/zh/guide/runtime.md+++ b/docs/zh/guide/runtime.md@@ -1,241 +1,149 @@---title: Runtime-description: Hypit Source 与 Core 之外的执行边界。+description: 选择执行服务,独立运行 Build,并保留可持续使用的 Result。----Hypit 把四个决定分开:+Source 描述作品,Run 选择 Target 与 Candidate,Runtime 使用选定服务执行这些决定,+项目保留实际得到的 Output。-| 所有者 | 决定什么 |-|---|---|-| Workspace | 编译能读取哪些 Source 和本地素材 |-| Runtime Profile | 允许使用哪些环境包 |-| Local Runtime | 活跃 Build 如何持久推进和被观察 |-| 项目 Build Results | 每个 Build 实际完成了哪些公开 Output |+| 所有者 | 职责 |+| --- | --- |+| 项目 | Source、素材、组件包与选定的 Runtime Profile |+| Distribution | 安装的可执行程序、公共 SDK 与执行实现 |+| Runtime Profile | Provider Endpoint、凭据引用、路由与共享容量 |+| Build | 使用选定依赖图和配置的一次执行尝试 |+| Result 仓库 | 已完成的公开 Output、执行结果和保留的运行证据 |-Core 是领域无关的状态机。它接收事实、派生 Command、验证 Record,不启动进程、不读取凭证、-不选择 Provider,也不知道 Build 最终是不是视频。+Core 只规划和推进依赖,不需要知道作品是一条视频。新组件或+[Provider](./providers.md) 通过相同的包接口提供自己的行为。-`@hypit/runtime-local` 是默认执行环境。它自己拥有 Worker、调度器、待提交状态、活跃执行状态和 SQLite。-这些是同一个本地实现,不再伪装成需要用户逐项选择的组件。+## 先确定项目,再选择 Profile++从视频项目运行命令,或用 `--workspace` 明确指定项目。否则使用当前目录向上最近的+`package.json`;没有时,以当前目录为项目。Source 文件名和 Runtime 配置都不决定这个边界。++```bash+hypit paths+hypit runtime init+```++`runtime init` 写入可编辑的起始 `hypit.runtime.json`,通过项目的 `.hypit/runtime`+文件选择它。已有 Profile 会保留;此操作不安装、不登录、不执行。+起始配置提供 HypiHub 托管生成和 WhisperX,以及本地媒体处理、渲染。先按作品需要选择服务,+再准备它们。本地推理、项目 Provider 可以走同一条路径,也可以与 HypiHub 混合使用。++`hypit runtime use <profile>` 选择已有配置;`--runtime <profile>` 只覆盖当前命令。+命令只读取当前项目的选择,不继承其他项目的 Runtime。命令行相对路径以当前目录为基准。## Runtime Profile-Profile 只保留真正会随环境变化的选择:+一个只配置本地媒体处理的例子:```json{"format": "hypit.runtime-local@1","dataRoot": ".hypit/runtimes/local",- "credentials": {- "env": { "use": "@hypit/credential-store-env" }- },+ "credentials": {},"endpoints": {- "media": { "use": "@hypit/provider-media-local" }- }+ "media.local": { "use": "@hypit/provider-media-local" }+ },+ "bindings": {}}```-官方视频 Distribution 在打开文件前已经明确选择 Local Runtime,因此 Profile 不再重复一个无法产生第二种-选择的 `runtime.use`。另一种应用若确实拥有不同 Runtime Host,应在自己的 Distribution 组装边界提供它;-Core 与通用 CLI 都不需要知道具体实现,也不预建没有第二个实现验证过的 Host 插件注册表。--`credentials` 选择凭证存储,`endpoints` 选择明确的 Provider 实现。Result 仓库不属于执行环境,-因此不能放进 Runtime Profile。+`dataRoot` 放活跃执行数据和工作文件,与 `.hypit/runtime` 选择文件分开。+`endpoints` 选择已安装的 Provider 及其配置。凭据通过选定 Store 中的引用获取,+密钥值不写进 Profile 或 Source。-项目可以在根目录放置独立的 `hypit.results.json`:+只有一个兼容 Endpoint 时无需 binding;多个 Endpoint 都能提供同一能力时,用 binding+表达选择。例如已明确配置本地 WhisperX 后:```json-{- "format": "hypit.build-results@1",- "use": "@hypit/build-result-fs",- "config": { "path": ".hypit/results" }+"bindings": {+ "@hypit/whisperx@1#whisperx-alignment": "whisperx.local"}```-没有这个文件时使用同样的本地默认值。Runtime Profile 可以被多个项目复用,而每个项目仍拥有自己的-Result 地址。--安装包只增加一种可选实现,不会自动激活。Profile 不包含 Workspace、作者 import 或隐藏的-创作路由。--## 本地状态--选择 Profile 会写入项目指针,执行数据位于 `dataRoot`:--```text-.hypit/- runtime- runtimes/- local/- runtime.sqlite- work/- worker/- programs/- results/- <UTC-date>/- <build-id>/- result.json- files/- values/-```+安装包使实现可用,选择它才赋予它当前环境中的角色。Model 拥有请求含义,Provider 拥有+服务支持、接口映射和价格来源。请求失败不会偷偷改用另一个账户。具体配置看所选 Provider 的 README。-`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/<UTC-date>/<build-id>/result.json` 记录最终 Target,以及这条执行路线上真正完成的所有公开-Author Output;Resource 字节放在该 Result 的 `files/`,Composite Value Document 放在 `values/`,-领域数据与嵌套 Resource 的路径绑定彼此分开。`builds`、`history`、-`inspect`、`get` 和 `build-record` 都通过同一个仓库接口读取。提交给独立 Worker 的 Build 会带着-当时选定的项目仓库位置;之后修改项目配置或从别的目录查询,活跃 Build 仍使用该准确地址。--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-{- "format": "hypit.build-results@1",- "use": "@hypit/build-result-s3",- "config": {- "bucket": "my-video-results",- "prefix": "projects/episode-12",- "region": "us-east-1"- }-}+```bash+hypit auth status+hypit doctor --endpoint media.local+hypit runtime up --endpoint media.local+hypit runtime status```-AWS SDK 使用它通常的凭证链;兼容服务还可以配置 `endpoint` 与 `forcePathStyle`。`prefix` 是项目-边界,每个项目应使用自己的 prefix。S3 只改变完整 Build Result 的存放位置,不会把 Runtime-SQLite、Provider 容量或活跃 Build 的临时 Resource 搬进 bucket。+使用 Profile 里的实际 Endpoint 名称,可重复 `--endpoint` 选择多个;省略时覆盖整个 Profile。+`doctor` 读取配置、运行 Provider 的诊断,不提交生成。除了错误,也要阅读警告:有凭据或能读取+模型目录,不代表每种请求一定成功。没有选定 Runtime 时,doctor 只检查项目 Result。-S3 adapter 会把有序 Build id 可逆地映射成“最新优先”的物理 prefix,因此对象存储可以直接返回有界-的一页,不需要中央索引或重复 catalog。Result 文件支持按字节范围流式读取,因此 Studio 预览远端-视频或音频时,不会先把完整文件装进内存。`hypit doctor [profile] --workspace <project>` 会同时主动-检查 Runtime 和项目选择的 Result Repository;存储检查只做一次有上限的只读列表,不扫描历史 Result。+`runtime up` 准备所选本地依赖和 Managed Program,再启动 Worker;它不登录或启动托管服务。+`programs up|status|down` 单独管理这些本地助手。首次推理环境准备可能涉及大量下载,+应先比较本地准备成本和托管方式,再选择执行路径。-Workspace 独立由显式 `--workspace`、Runtime 指针所在项目或入口 Source 目录确定。Runtime 配置-不能扩大源码读取范围。+`plan <run>` 检查当前工作需要的能力和轻量就绪状态。发现 Provider 能力需要可加载的包声明;+没有明确 binding 时,可能需要加载其他已声明 Endpoint。未使用的服务不必启动或登录。+`build` 不做安装准备:依赖已就绪时,按需启动 Worker 并提交一次 Build。+[Run 与 Build](../quickstart/run.md) 说明规划、价格、付费授权和显式复用。-## Execution turn 与并发+## 执行独立于观察终端-`build` 保存一个全新 Build 后立即返回。SQLite 持久保存所有仍需要下一轮推进的 Build;Worker 只在推进-期间临时物化状态,并立即写回已经接受的 facts。没有 Build 并发配置,Build 身份也不是容量资源。+```bash+hypit build build.svrun --follow+hypit status <build-id> --watch+hypit logs <build-id> --lines 80+```-真正约束外部工作的容量只有 Endpoint 声明的 Provider 总池与其下面的模型 Lane。不同 Build 的 Command-共享这些真实容量。每项资源只有一个 `limit`:立即调用返回后释放,异步 Operation 则一直占用到终态;-互不冲突的 Build 与 Command 可以一起推进。+Worker 拥有执行。`--follow` 和 `status --watch` 只是观察;关闭终端或等待超时不会取消 Build。+停止某一次尝试用 `hypit cancel <build-id>`。远程取消尽力而为,已经完成的 Output 会保留。-异步 Endpoint 在调用 `start` 前先保存 Operation;立即 Producer/Endpoint 在调用前先保存 command-交接状态。进程若停在“已开始但结果未落盘”的窗口,该 Build 明确失败,同一个 command 不会再次调用。+失败的尝试保持失败。新 Run 可以选择已有 Output,开启新的 Build。如果执行已经结束,+只是 Result 保存需要处理,`status` 会指出 `hypit result finish <build-id>`:它只完成待保存工作,+不会重新生成素材。-取消是尽力而为:未开始的 Build 仍由 Worker 领取一次,但不会执行生成 Command,只写 Result-终态与清理;运行中的 Build 不再接收新 Command,Endpoint 可以尝试取消已经提交的外部 Operation。-已经完成并交接的 Output 保留,不做回滚。+Build 日志保留 Provider 阶段和诊断。`runtime logs` 查看 Worker 启动和进程错误;+安装、服务日志属于相应 Managed Program。终端记录丢失不意味着执行证据也丢失。-## Managed Programs+## 共享容量,独立推进-Endpoint 可以声明 WhisperX 这类需要常驻的辅助程序。Endpoint 提供探测和可选启动命令,本地-Runtime 只负责管理它。+多个 Build 可以同时推进。限制属于实际使用的账户、部署或本地计算资源。+远程等待不会占住一个整条 Build 的名额、阻止其他 Build 的本地工作。+Provider 可以分别声明任务容量和 submit、poll、collect 的短调用限制。+`hypit activity --verbose` 展示活跃工作和共享容量。-```bash-hypit programs status-hypit programs up-hypit programs down-```+每个 Build 使用独立加载的项目实现和选定配置。修改项目组件或 Profile 影响下一次 Build,+已开始的工作保留已加载的实现。Managed Program 有独立生命周期,预热好的 WhisperX 可以服务多个 Build。-`programs up` 会先准备所选 Endpoint 包的上游 npm 依赖,再操作其声明的程序。这些命令不打开-SQLite 或 Credential Store。+更新 Distribution 或改变 Worker 继承的 shell 环境,涉及进程生命周期。重启前检查活跃工作:+`runtime down` 会结束活跃执行上下文,`programs down` 单独停止助手。+执行器丢失会结束所属尝试,之后通过新 Build 显式复用。这种执行分离不是安全沙箱,+也不会冻结组件之后才读取的文件。-## 生命周期+## 产物留在项目里-```bash-hypit runtime init-hypit runtime use hypit.runtime.json-hypit runtime up-hypit runtime status-hypit runtime logs-hypit runtime down+默认 Result 位于 `.hypit/results`。项目通过独立的 `hypit.results.json` 选择位置或仓库,+不放进 Runtime Profile:++```json+{+ "format": "hypit.build-results@1",+ "use": "@hypit/build-result-fs",+ "config": { "path": ".hypit/results" }+}```-`runtime init` 会把视频 Distribution 提供的起始 Profile 写入 `hypit.runtime.json`,并为已经解析-出的项目选择它;已有文件一律拒绝覆盖。这只是本地文件操作:不安装包、不连接服务、不索取凭据,-也不启动 Worker。官方起始 Profile 使用 HypiHub 提供远程生成、WhisperX,使用本地-Endpoint 处理媒体并通过 HyperFrames 渲染。这是 Distribution 的开箱选择,不是 Core 规则;使用-BYOK 或本地 Provider 时可以编辑 Profile 或选择另一份 Profile。--`runtime use` 把一份显式 Profile 绑定到一个已经解析完成的项目。项目来自 `--workspace`,-或当前目录声明的 package 边界;Runtime 选择不能反过来定义项目。命令只读取-`<project>/.hypit/runtime`,不会扫描约定文件名,也不会继承父项目的选择。即使几个项目声明-了等价的外部 Endpoint,它们也必须分别完成选择。--`runtime up` 先让 npm 把所选 Adapter 的精确上游包准备到机器共享目录,再准备所选的**本地**-Managed Program 并启动本地 Worker。它不会启动、重启、登录或探测 HypiHub 这类远程 Endpoint。-`runtime down` 停止本地 Worker 和它的执行进程;由 Runtime 管理的本地 Program 会继续可用,直到显式运行-`programs down`。--`runtime up`、`programs up|status|down` 和 `doctor` 都可以用 `--endpoint <instance>` 只处理已选定的-服务;需要多个服务时可以重复这个参数。不传时处理整个 Profile。Build 规划则检查本次工作实际选中的-Endpoint。可选上游包按准确版本分别安装,准备一个版本不会替换另一个版本,npm 的下载缓存仍然共享。--`doctor` 才是主动但只读的环境检查。它解析已声明的凭据,并允许每个所选 Endpoint 检查真实-环境;远程 Provider 因而可以访问一次有界的模型目录或能力接口。登录成功只证明凭据存在,-doctor 成功才证明该账户此刻可以路由所选 Endpoint 声明的能力。普通 `check`、`plan` 和 Build 预检都不会运行这类-主动探测,也不会把环境检查偷换成隐藏网络请求。--`build` 不做部署:它执行便宜只读预检,只在就绪后提交,并确保-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。-硬中断后,协调进程撤销遗留的 Result writer lease。已有终态、但 Result 写入中断的 Build 保留 attention,-由 `result finish` 收尾;丢失执行进程的活跃 Build 则结束这次尝试,将已有事实写入 Result。-工作字节丢失会明确失败,不补生成。-已结束 Build 不恢复;复用以前的 Result 必须在新的 `.svrun` 中显式写 Candidate。--每次 Build 都使用独立加载的项目实现和选定的 Provider 配置。修改项目组件或-Profile 后,新的 Build 使用新实现,已经开始的工作继续使用它加载的实现。Managed Program 有独立-生命周期,本地模型可以继续保持就绪。并发 Build 共享执行基础设施,远程等待不占用整单执行名额;-具体工作的并发仍遵循其声明的资源额度。-本地 Runtime 可以在已完成工作的内存积累后轮换执行进程:已有 Build 留在原进程做完,新 Build 进入新进程,-已经就绪的常驻服务继续可用。--执行进程丢失会结束它承载的活跃 Build,并保留已完成的产物和已有的远程回执,不会用修改后的代码重新运行-同一次 Build。继续制作时创建新 Build 并显式复用。组件后来主动读取的文件仍遵循正常文件语义。-更新 Distribution 或修改协调进程继承的环境变量,仍需先保留活跃工作,再重启这一启动进程。--Runtime 包是本地可信部署代码,其安装版本由 npm 或 pnpm 管理。Hypit 只在显式 `runtime up` /-`packages install` 边界选择精确依赖并调用 npm,不维护第二份包锁,也不会把元数据冒充成沙箱。+S3 适配器可以把 Result 放进桶及项目专属前缀。适配器负责访问和凭据;更换 Result 存储不会+搬走活跃 Runtime,也不会自动上传外部文件引用。已提交 Build 保留提交时的目标位置,+修改选择不迁移历史。++Result 在公开 Output 完成时发布它们,最后保留终态。新 Output 可以引用已有文件,复合值内部也一样,+不意味着多一份素材。显式本地文件引用保持实时性;继续复用时需要保留它们的依赖。+需要交给人或其他工具的独立文件时,用 `get` 另行导出。++`builds`、`history`、`inspect`、`get` 读取项目 Result,不依赖原 Runtime。+精确存储和执行接口见+[Result 包](https://github.com/hypit-ai/hypit/blob/main/packages/build-result/README.md) 与+[本地 Runtime 包](https://github.com/hypit-ai/hypit/blob/main/packages/runtime-local/README.md)。diff --git a/docs/zh/guide/studio-companion-adapter-architecture.md b/docs/zh/guide/studio-companion-adapter-architecture.mdindex e040dfe2..49250a62 100644--- a/docs/zh/guide/studio-companion-adapter-architecture.md+++ b/docs/zh/guide/studio-companion-adapter-architecture.md@@ -15,7 +15,7 @@ Companion 是应用贡献。项目组件可以在同一个物理包中,以独Track Companion 匹配组件的终端 Type 与作者 Surface,使用组件公开值描述时间线实体、标签、素材预览和 Inspector 字段。图形可以公开外观、内容、位置和事件时间,而不必暴露每一个内部绘制数值。-控件与交互由 Studio 提供,Companion 选择标量、列表或记录控件,并将其绑定到 Source 值。Film Companion 指明 Film 的时间来源与 Track;Script Companion 支持移动 Selection、Moment 标记所需的源码映射。作者声明的 ProgramSpace 支持没有 Script 轨道的动画。+控件与交互由 Studio 提供,Companion 选择标量、列表或记录控件,并将其绑定到 Source 值。Film Companion 指明 Film 的 Timeline 与 Track;Script Companion 支持移动 Selection、Moment 标记所需的源码映射。同一种 Timeline 也支持没有 Take 和 Script 行的动画,其作者声明的结束时间定义完整范围。## 让编辑保留含义diff --git a/docs/zh/guide/studio-temporal-windows.md b/docs/zh/guide/studio-temporal-windows.mdindex ebddee1d..def5613e 100644--- a/docs/zh/guide/studio-temporal-windows.md+++ b/docs/zh/guide/studio-temporal-windows.md@@ -34,8 +34,8 @@ Script 的语义标尺包含 `2M + 2N + 2` 个点:Token 与 Segment 的首尾- `<script id="story">` 产生 `Narrative.id = story`,它派生出的 Selection、Moment、Segmentexcerpt 与 CaptionDocument 全部携带 `narrativeId = story`;-- 被 Film 选择的 Timeline 的 `id` 就是 `ProgramSpace.id`,所有终端 Track 都携带同一个- `programSpaceId`;+- 所有终端 Track 的 `programSpaceId` 指向 Film 选定的 Timeline。`ProgramSpace` 是 Timeline+ 内含的公共时钟与范围结构,不是另一种需要单独声明的时间线;- 每个 Instant 保留 Space 身份,来自语义的来源额外保留 Narrative 身份;消费者的公开领域身份(通常就是 SVML `id`)作为 `subjectId`。@@ -96,7 +96,7 @@ Semantic token evidence 得到只读 Cue 时间,不伪装成可拖动的 TempoFilm 与 Script 的解释也不留在 Studio 核心:`film-studio` 声明 Film 的时间来源和终端 Track引用规则;`script-studio` 拥有 Script Source map 与 marker 移动。Studio 只选择`narrativeId` 与当前 Timeline 一致的 Script,再把语义修改委托回该 Companion。-直接声明的 Space 提供物理时间线,不需要 Script 轨道。`at="2s"` 表示作者编排的事件时刻,+零 Take 的 Timeline 提供同样的物理时间范围,不需要 Script 轨道。`at="2s"` 表示作者编排的事件时刻,可以单独用于 Instant,也可以与 `for` 配合形成 Window;其时间修改回写 SVML。这里的 binding 名不是全局地址。Markup 在降低语法时保留作者元素和输入范围,Elaboratordiff --git a/docs/zh/quickstart/run.md b/docs/zh/quickstart/run.mdindex 39cd7f52..cfcb75b5 100644--- a/docs/zh/quickstart/run.md+++ b/docs/zh/quickstart/run.md@@ -150,7 +150,7 @@ hypit inspect <build-id>```Hypit 永远不会猜测两个名字代表同一份作者意图。每次执行 `build` 都会得到新的 Build id 和独立 Result 目录,即使源码完全没变。后续 Run 只有明确写出旧 Build id 与 Output 时才复用;若旧 Output 本身继续转发到更老的 Result,就沿显式关系向前解析,不把文件复制进新 Result。-转发只适用于完整的公开 Output;结构化 JSON 不能在内部递归指向另一个 Output。历史值若只是新 Fragment 的一项输入,Fragment 产生的新 Output 仍属于当前 Result。+转发只适用于完整的公开 Output;结构化 JSON 不能在内部递归指向另一个 Output。历史值若只是新 Fragment 的一项输入,Fragment 产生的新 Output 仍属于当前 Result,但其内部的媒体继续引用原文件;新 JSON 结构不要求复制已有图片、视频或音频。### build-record@@ -169,9 +169,9 @@ Hypit 永远不会猜测两个名字代表同一份作者意图。每次执行 `| 属性 | 说明 ||---|---|| `output` | 要满足的逻辑输出 |-| `candidate` | Candidate 标识符(来自 `build-record`) |+| `candidate` | 由 `build-record`、`file`、`value` 或 Fragment 导出声明的 Candidate 标识符 |-Planner 会同时读取完整 Author Graph 与 Run Graph:裁剪所选 Candidate 替代掉的默认 Operation,同时保留该 Candidate 自身仍然消费的 Author Output。这是一次新的 Build,而非旧 Build 的延续。下游处理(归一化、WhisperX、字幕生成、渲染)仍然会对复用的媒体执行。+Planner 会同时读取完整 Author Graph 与 Run Graph:裁剪所选 Candidate 替代掉的默认 Operation,同时保留该 Candidate 自身仍然消费的 Author Output。这是一次新的 Build,而非旧 Build 的延续。复用生成视频时,归一化和语义准备仍在下游;复用已经准备好的 SemanticTake 时,也保留这些结果。字幕、MG 和渲染只在仍被所选路线需要时计算。选择哪个 Output,取决于哪些内容应该保留不变。Core 不再给 Candidate 标注 `exact` 或 `substitute`。选择 Candidate 本身就是这次运行的明确实现决定。系统校验类型兼容性,但不猜测创作等价性,也不把这种判断作为冗余元信息沿整条图传播。@@ -184,7 +184,7 @@ Core 不再给 Candidate 标注 `exact` 或 `substitute`。选择 Candidate 本<satisfy output="opening-shot.video" candidate="approved-opening"/>```-文件相对于 `.svrun` 读取。如果它在 Target 路线上成为已经完成的公开 Output,就像生成媒体一样写入 Build Result。系统没有隐式历史查找;用户提供的图片、录制的视频和其他兼容产物也使用同一个机制。+文件相对于 `.svrun` 读取。如果它在 Target 路线上成为已完成的公开 Output,Result 保存明确的外部文件引用,不会为每次 Build 复制一份文件。引用保持实时性:替换文件会改变后续读取,删除文件会使依赖不可用。用户提供的图片、录制的视频使用相同机制。## Runtime Profile@@ -326,7 +326,8 @@ hypit doctorDoctor 总会校验项目选择的 Result Repository;存在已选或显式传入的 Runtime Profile 时,还会校验全部Runtime 角色、Endpoint 配置、凭据是否存在和有界环境探测。它不启动 Worker,也不发付费请求。-存在 Profile 时,`doctor` 有意检查完整 Runtime Profile。若只想检查某次 Run 真正需要的环境,请使用带+存在 Profile 时,`doctor` 默认检查整个 Profile,也可以重复 `--endpoint <instance>` 限定服务。+若只想检查某次 Run 真正需要的环境,请使用带所选 Runtime 的 `plan`。未就绪会写入 `preflight` 并令命令非零退出,但 JSON 中仍保留冻结计划供检查。@@ -340,8 +341,9 @@ hypit check reference.svmlhypit plan reference.svrun```-在花费资金之前审查冻结的 BuildPlan。该计划展示调度器将发出的每个 Operation 和 Needs;选择-Runtime 后只预检这次计划真正需要的 Endpoint、凭据和外部程序,不启动任何外部工作。+花费资金前审查所选工作。默认计划展示 Target、实际需要的外部请求及其已知参数;+`--verbose` 增加图和 Candidate 选择详情。选择 Runtime 后预检这次计划需要的 Endpoint、+凭据和外部程序,不启动任何外部工作。`plan` 可以完全不带 Runtime;执行过 `hypit runtime use` 后,`plan` 和 `build` 都不必再写`--runtime`。`build` 必须能找到所选或显式 Profile。@@ -387,8 +389,9 @@ Output 和记录下来的任务凭据会保留;后续执行通过新 Build 显hypit inspect <build-id>```-`inspect` 直接读取项目里的 Build Result,列出最终 Target 和一页实际完成的公开 Output;用-`--output <name>` 精确查看一个 Output,或用 `--limit <count>` 增加显示数量:+`inspect` 直接读取项目 Result,默认展示 Target、高亮 Output 和失败证据。+`--output <name>` 精确查看一个 Output;`--verbose` 浏览其他 Output 和任务回执,+`--limit <count>` 扩展这个详细列表。导出指定 Output 用:```bashhypit get <build-id> \diff --git a/docs/zh/quickstart/styles.md b/docs/zh/quickstart/styles.mdindex 042af264..d894a9b2 100644--- a/docs/zh/quickstart/styles.md+++ b/docs/zh/quickstart/styles.md@@ -40,8 +40,7 @@ SVS(`.svs`)文件使用类 CSS 语法定义可复用的类型化配置值。## Film-Film 外观只拥有画布清除颜色。画布尺寸是显式的 `space:Canvas` 图值,帧率来自-ProgramSpace。+Film 外观只拥有画布清除颜色。画布尺寸是显式的 `space:Canvas` 图值,帧率来自 Timeline 使用的 Clock。```svsfilm.vertical {diff --git a/docs/zh/quickstart/tracks.md b/docs/zh/quickstart/tracks.mdindex a1a31753..303c6555 100644--- a/docs/zh/quickstart/tracks.md+++ b/docs/zh/quickstart/tracks.md@@ -226,7 +226,7 @@ Track 都会作为独立输入进入 Film。输出 `{music-bed.audio}` 是普通| `placement` | 是 | 与 Item 形式匹配的 `SpatialPoint`、`SpatialFrame` 或 `SpatialPath` || `style` | 是 | 由 SVS Recipe 与精确字体字节共同编译出的 `text:Style` |-`during` 属性接受字面字符串 `"program"`(表示完整 ProgramSpace),或用于语义计时的 Selection 引用:+`during` 属性接受字面字符串 `"program"`(表示完整 Timeline),或用于语义计时的 Selection、Segment 引用。同一套时间接口也接受作者声明的 `start`/`end` 窗口和 `at`/`for` 事件:```svml<text:Style id="callout-style" recipe={recipes.text.callout} font={title-font}/>@@ -315,7 +315,7 @@ Run 时,继续使用内联 `P`/`Span`/`Break`。### deck:DepthStack-`id`、`semantic`、`canvas`、`frame` 与 `appearance` 全部必填,`until` 同样必填——它说明什么结束这叠卡片:字面量 `"program.end"`、一个 Moment,或一个 Selection。只有在指向 Selection 时才可以再加 `until-boundary="start" | "end"` 来选择用它的哪一端结束,默认是 `end`;在另外两种情况下给出这个属性会被拒绝,而不是被忽略。+`id`、`timeline`、`canvas`、`frame` 与 `appearance` 全部必填。同一份 Timeline 提供作者时间和已放置的语义锚点。`until` 同样必填,指定这叠卡片何时结束:Moment、Selection 或 Segment 的边界,或 `8s`、`program.end` 等作者时间。Selection 或 Segment 可以用 `until-boundary="start" | "end"` 选择首尾,默认是 `end`。### deck:Carddiff --git a/package.json b/package.jsonindex f4727525..5937f2ea 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "@hypit/hypit",- "version": "0.1.5",+ "version": "0.1.6","homepage": "https://hypit.ai","repository": {"type": "git",@@ -125,6 +125,8 @@"packages/*/README.md","packages/temporal-markup/EDITING.md","packages/studio/INSPECTOR.md",+ "packages/studio/LOCALIZATION.md",+ "packages/studio/locales/*.json","services/image-opencv/pyproject.toml","services/image-opencv/package.json","services/image-opencv/uv.lock",diff --git a/packages/runtime-local/README.md b/packages/runtime-local/README.mdindex 9c5ef806..b12174bb 100644--- a/packages/runtime-local/README.md+++ b/packages/runtime-local/README.md@@ -122,6 +122,12 @@ 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.+Endpoint scoping happens before activation when explicit instance IDs are supplied, or when every+requested capability has a binding. Otherwise discovery loads the Profile's Endpoint packages to+find eligible implementations. Thus unused service readiness is not required, but an uninstalled+declared package can still prevent unbound discovery. `scopedProfile` owns this distinction; package+names are not used to guess which capabilities they supply.+The lifecycle commands have deliberately narrow meanings:- `hypit runtime init` writes and selects the Distribution's starter Profile; it performs no setup ordiff --git a/skills/hypit/SKILL.md b/skills/hypit/SKILL.mdindex bb53e900..e32451b3 100644--- a/skills/hypit/SKILL.md+++ b/skills/hypit/SKILL.md@@ -44,15 +44,13 @@ authored animation. Space can contain independent contributions or a coordinatedinternal tree. [System relationships](references/production/system.md) explains this adaptiveorganization and connects it to materials and execution.-Choose component boundaries through shared behavior. An ordinary media presentation can use Media;-a playing video and a diagram exchanging space can share a scene that owns their layout and motion.-Independent Caption or overlays can remain peers. Use an existing component when its behavior fits;-create a project component when a new relationship deserves its own expression. A one-off scene is-normal production work. Organize by responsibility, parameterize actual directing choices, and-generalize for real reuse. These are separate decisions: a self-contained scene can have a fixed-design and few or no editable parameters. Before implementing a new visual system, read-[Component design](references/production/component-design.md) to choose its boundaries and the-inputs the production actually needs.+Choose component boundaries through shared behavior: coordinated layout and motion can share a+scene; independent contributions can remain peers. Use an existing component when its behavior fits,+or create a project component for a new relationship. A one-off scene is normal production work.+Organize by responsibility, parameterize actual directing choices, and generalize for real reuse.+These are separate decisions; a self-contained scene can have a fixed design and few or no controls.+Before implementing a new visual system, read [Component design](references/production/component-design.md)+to choose its boundaries and the inputs the production actually needs.For spoken work, prefer to author meaning in Script and let the accepted performance give it time.In a clone, discover what a cut, picture, reveal or sound responds to, then recreate that relationship@@ -70,8 +68,7 @@ choices, so a whole scene can respond to a Moment and separate components can sh## Direct the materialMaterial direction carries practical knowledge of how generation models respond to prompts and-references. Use that experience to turn the creative answer into effective requests. Composition-uses your understanding of the work to organize the resulting material into meaningful behavior.+references. Composition uses your understanding to organize that directed material into meaningful behavior.Keep the whole creative intention in view, then give each part the direction it can realize.Translate planned composition into the generated material's appearance, framing and performance;@@ -80,34 +77,21 @@ attitude remain useful when they describe what that material should look, sound[Direction and its inputs](references/production/system.md#give-each-part-the-direction-it-can-realize)explains this division.-For creator-led social video, favor compelling casting, a distinctive, appealing voice, and a-performance with a clear attitude toward the subject and listener. Outgoing or restrained, let that-relationship shape the voice, expression and timing, with a few decisive details. Give humor,-contrast or surprise an expression the audience can experience in the piece itself, and translate-the chosen idea into sensory and performable direction.--Before writing or adapting an image prompt, read-[Image direction](references/playbooks/craft/image-direction.md) and apply it to the intended picture,-including when starting from an existing project's prompt. UGC, podcast and street-interview images-usually share the Kit's fixed iPhone-video capture language. Follow it with Person, Shot and Setting:-strong, specific casting; a deliberate camera encounter; and a place with a considered palette.-The Craft owns the explicit appearance, proportion and reusable speaking-view guidance.-Before choosing, designing or changing a character's voice, read-[Voice direction](references/playbooks/craft/voice-direction.md). Before writing or adapting a video-prompt, performance Recipe or action, read [Video direction](references/playbooks/craft/video-direction.md)-and the selected Kit's wording and choices. For movement-led adaptation, that page also explains-letting a video reference carry dance, action or camera behavior. Apply these references when adapting earlier work as well.-For A-roll, B-roll, Caption, MG or sound relationships, read the Craft that owns what the work should-accomplish. Use installed vocabulary and package-local documentation for-the exact Surface, inputs and limits. Craft supplies directing judgment; package documentation-supplies the means to express it.-Treat existing project prompts and Recipes as earlier directing choices. Compare their assumptions-with the current Brief, Treatment and relevant Craft, and carry them forward while the same artistic-relationship still serves this work.--GPT Image 2 and Seedance 2 Mini at 720p are the usual starting points for generated pictures and-performances, balancing capability and cost. Choose for the actual work; the image and video-crafts explain resolution and duration choices.+For creator-led social video, favor compelling casting, an appealing voice and a clear attitude+toward the subject and listener. Let that relationship shape expression and timing. Humor, contrast+or surprise needs an expression the audience can experience in the work.++Before writing or adapting an image prompt, read [Image direction](references/playbooks/craft/image-direction.md).+Before choosing or changing a voice, read [Voice direction](references/playbooks/craft/voice-direction.md).+Before writing or adapting a video prompt, performance Recipe or action, read+[Video direction](references/playbooks/craft/video-direction.md) and the selected Kit's wording and choices.+These pages own capture language, casting, reference relationships and model-specific direction;+video direction also covers footage references for movement-led work. Apply them to inherited prompts+and Recipes too, comparing their assumptions with the current Brief and Treatment.++For A-roll, B-roll, Caption, MG or sound relationships, read the Craft that owns the directing question.+Craft supplies judgment and model-selection guidance; installed vocabulary, Kits and package-local+documentation supply the exact Surfaces, request wording, inputs and limits.## Prepare for the work at hand@@ -279,7 +263,7 @@ practical, revisit that choice and carry the improvement into the work and its n| drawing a component's elements, animation, resources or prepared surfaces | `references/production/component-visuals.md` || writing a Caption family with new word relationships, scheduling or layout | `references/production/caption-authoring.md` || `plan`, Provider pricing information, `build`, a retry or interrupted submission, following work, Results and exports | `references/production/builds.md` |-| showing the editable work before export: Comments, Studio timeline, parameters and timestamped feedback | `references/production/studio.md` |+| showing the editable work before export: Comments, Studio timeline, parameters, timestamped feedback and interface language | `references/production/studio.md` || giving a component useful timeline entities, picture selection and author controls | `references/production/studio-companions.md` || Film assembly, pure MG with authored time, picture and sound, final rendering or a selected frame interval | `references/production/rendering.md` || judging the preview or finished Result and deciding what to fix | `references/production/review.md` |diff --git a/skills/hypit/references/environment/profile.md b/skills/hypit/references/environment/profile.mdindex e614b33c..c7314942 100644--- a/skills/hypit/references/environment/profile.md+++ b/skills/hypit/references/environment/profile.md@@ -188,6 +188,12 @@ That Endpoint must actually be declared and support the capability. A single elineeds no binding; multiple unbound choices are an error. Use the Model and Provider READMEs and`plan` to establish actual support rather than inferring compatibility from similar model names.+Readiness and package discovery are separate. Explicit bindings let capability-scoped commands load+the named Endpoints directly. Without a binding, discovering which Provider can serve a capability+can require loading the Profile's Endpoint packages; a declared but uninstalled package can therefore+block discovery even when its service would not ultimately be used. Correct that declaration or make+the intended binding explicit. An unused account need not be logged in merely to resolve the work.+## Set capacity at the resource it describesThe Runtime Worker and HyperFrames `workers` are different things. The Worker schedules many Builds;diff --git a/skills/hypit/references/playbooks/craft/graphic-compositions.md b/skills/hypit/references/playbooks/craft/graphic-compositions.mdindex 580c336d..096e0f19 100644--- a/skills/hypit/references/playbooks/craft/graphic-compositions.md+++ b/skills/hypit/references/playbooks/craft/graphic-compositions.md@@ -73,16 +73,18 @@ composition already expresses the relationship. A new shared visual role can be[Component design](../../production/component-design.md) connects that visual idea to semantic behavior,useful author controls and its place in the actual composition.-The package owns reusable mechanics, default chrome and any bundled assets that belong to its-identity. Source and Recipe supply this work's text, media, palette, placement and events. A surface-may also accept an authored theme or background when customization is part of its design.+The component owns its visual behavior and design. Source and Recipe supply the content, media,+events and directing choices that belong outside it. A one-off scene can retain its illustrative+text, palette and detailed layout internally; a shared treatment can expose the variation its uses+actually need. Independence gives a responsibility an owner, without requiring every design choice+to become an input.## Expose meaningful control-A useful Surface offers the content and relationships an author needs: rows or slots, labels,-icons, a Frame, Styles, outer visibility, reveal Selections or Moments, and initial state where it-makes sense. Avoid hardcoding this video's number of answers, speaker side, product or palette into-reusable behavior. Expose a useful range rather than every internal pixel or animation calculation.+A useful Surface offers the content and relationships the production needs. Derive its inputs from+the decisions the author will supply or revise: these may include content, placement, visibility,+semantic events or a chosen treatment. For reuse, expose the variation shared uses demonstrate;+internal geometry and animation can continue to realize a coherent fixed design.`preset` means content already present in the initial state of a component that supports it. It isnot a substitute for a Style and not a generic timing escape. A reveal Window, a point activationdiff --git a/skills/hypit/references/playbooks/craft/video-direction.md b/skills/hypit/references/playbooks/craft/video-direction.mdindex a97d43cc..32b4e285 100644--- a/skills/hypit/references/playbooks/craft/video-direction.md+++ b/skills/hypit/references/playbooks/craft/video-direction.md@@ -158,6 +158,10 @@ performance.## Choose the generation relationship+Seedance 2 Mini at 720p is the usual starting point for generated performances, balancing capability+and cost. Choose for the intended shot and the user's available services; the selected model's+installed vocabulary owns supported resolutions, references and request lengths.+Generated-video models commonly expose some combination of three relationships:| Relationship | When it fits |diff --git a/skills/hypit/references/production/builds.md b/skills/hypit/references/production/builds.mdindex d11e2696..b05d709f 100644--- a/skills/hypit/references/production/builds.md+++ b/skills/hypit/references/production/builds.md@@ -63,9 +63,11 @@ asset as an ordinary project file and select it with `file` and `satisfy` in thethe file Output; downstream preparation and alignment still run when needed. A completed SemanticTakecan instead be reused directly through its existing Result Output.-Use `status <build-id> --verbose` for active task receipts and `inspect <build-id> --json` for the-finished Result's execution records. They include the Endpoint, Need identity, credential references,-known task ID, and the recorded error or last progress. Secret values stay in their Credential Store.+Use `status <build-id> --verbose` for task IDs, Endpoints and progress. Use+`inspect <build-id> --verbose --json` for the Result's full retained execution records, including+available credential references and receipts; increase `--limit` if the report lists omitted records.+Secret values stay in their Credential Store. `--json` changes encoding, while `--verbose` requests+these details.## Plan the selected Run@@ -182,7 +184,7 @@ hypit activityhypit runtime status```-`activity` shows active Builds and shared Provider capacity. The Worker may advance many unrelated+`activity` shows active Builds; `activity --verbose` also shows shared Provider capacity. The Worker may advance many unrelatedBuilds together. Capacity belongs to the exact Endpoint instances, real shared pools, and any narrowermodel limits declared by those Endpoints. Builds share only those actual resources, so unrelated workcan advance together.@@ -196,7 +198,7 @@ status remains evidence, rather than a condition the old Build must resolve befoProviders that expose `actionLimits` can separately limit asynchronous `submit`, `poll` and `collect`actions through `concurrency` and `rate: { limit, periodMs }`. These budgets share the Profile's pool.Task occupancy, overlapping network actions and starts permitted per time period are different quantities;-`activity --json` exposes the actual resource claims. Provider-local documentation owns available settings.+`activity --verbose --json` exposes the actual resource claims. Provider-local documentation owns available settings.## Separate active work from Result outcomediff --git a/skills/hypit/references/production/component-design.md b/skills/hypit/references/production/component-design.mdindex aba097a7..ee62b895 100644--- a/skills/hypit/references/production/component-design.md+++ b/skills/hypit/references/production/component-design.md@@ -69,6 +69,11 @@ several independent objects. Sharing a Moment does not by itself require a share## Keep implementation changes local+Use the work's revisions to check its boundaries: a change to one visual responsibility should+remain with its owner, while a shared change should flow through a shared dependency. When an edit+requires reconstructing the same decision across several scenes, consolidate that decision's source.+The aim is to make the relationship explicit, whether its owner is a fixed implementation or an author input.+Keep revisions local as the scene grows. Separate independently edited scene bodies, styling andframe evaluation into ordinary source modules while sharing their actual mechanics. A palette,typing function or media-sampling helper can be an ordinary project dependency; it needs no Surface@@ -78,8 +83,7 @@ own their realization, including any fixed design specific to this piece.Derive related geometry from one layout. A pointer's destination should come from the target itclicks; an attached badge should follow its pointer; two presentations of one playing source should-share their sampling. Then revising a layout changes its dependent motion with it. Repeatedly fixing-the same choice in several places is evidence that its ownership needs consolidating.+share their sampling. Then revising a layout changes its dependent motion with it.Choose visual grouping and timing independently. A combined scene can respond to spoken Moments;separate Tracks can share an authored event. What belongs together on the canvas does not decidediff --git a/skills/hypit/references/production/system.md b/skills/hypit/references/production/system.mdindex 65d15636..086a35f1 100644--- a/skills/hypit/references/production/system.md+++ b/skills/hypit/references/production/system.md@@ -177,6 +177,11 @@ Targets and Candidates. Visual grouping, paint order and execution dependency rerelationships: one scene can require several material requests, while one material can supplyseveral appearances.+These graphs have different jobs. The Author Graph offers the work's public Outputs and their+default computations. The Run Graph supplies Targets and explicit alternative Candidates. Planning+applies those choices, follows the selected dependencies and freezes one execution definition for+the Build. Runtime advances that selected work; it does not reconsider Candidates or rediscover reuse.+A **Run** selects which public Outputs to complete through **Targets**, and can choose a different**Candidate** for an Output. That Candidate might be a supplied file, a prior Result, or a computationprovided by a Run Fragment.@@ -186,6 +191,12 @@ already supplies the performance and its timing; the changed Caption and downstrwork to do. This separates revising the video from repeating media generation. The Run records thatreuse explicitly.+Selecting only the generated video instead leaves normalization and semantic preparation downstream.+Selecting the Take keeps those prepared relationships too; selecting the final composition would+also keep its earlier layout. Choose the boundary that preserves the material without preserving the+thing being edited. A new named Output can reference existing bytes, including inside a composite+value; a new Build does not by itself mean new media or another stored copy.+A submitted execution is a **Build**. Its **Result** retains completed public Outputs for inspection,delivery and future selection, including useful Outputs completed before a later failure.Runtime maintains the running work; Result files keep its products available independently of that