Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

feat: make runtime execution observable

kashorin8e01877a3eed
diff --git a/.agents/skills/narratage/SKILL.md b/.agents/skills/narratage/SKILL.md
index f9449d08..a9e112a5 100644
--- a/.agents/skills/narratage/SKILL.md
+++ b/.agents/skills/narratage/SKILL.md
@@ -29,20 +29,25 @@ Source, and the declarative `svml.runtime.json` Runtime Profile separate.
## Ordinary loop
```bash
-node --run narratage -- plan path/to/build.svrun --runtime path/to/svml.runtime.json
-node --run narratage -- build path/to/build.svrun --runtime path/to/svml.runtime.json \
- --build-id my-build-001 --follow
-node --run narratage -- inspect my-build-001 --runtime path/to/svml.runtime.json
-node --run narratage -- get my-build-001 --runtime path/to/svml.runtime.json \
- --name final.video --to path/to/output/final.mp4
+cd path/to/project
+node --run narratage -- runtime use svml.runtime.json
+node --run narratage -- plan build.svrun
+node --run narratage -- build build.svrun --follow
+node --run narratage -- inspect <build-id>
+node --run narratage -- get <build-id> \
+ --name final.video --to output/final.mp4
```
Run `packages sync` after import or Runtime package selections change. Use `check` while editing and
`doctor` for deployment setup or diagnosis; do not impose either as ceremony before every Build.
Treat `--follow` as an observer: stopping it does not stop the durable Build. Use `runtime down`
-only to stop the Worker and Runtime-owned programs; it does not cancel Builds or remote Provider
-work.
+to stop only the Worker; use `services down` separately when external programs should also stop.
+Neither command cancels Builds or remote Provider work.
+
+Every `build` invocation receives a fresh automatic Build id. Never try to reclaim a prior Build by
+restoring Source bytes or choosing an id. Cross-Build reuse exists only through explicit
+`build-record` Candidates in a new Run Source.
Reuse any accepted generated image or take in the next `.svrun` with `build-record` plus `satisfy`,
then review the frozen plan before paid downstream work. Candidate selection has no Pin state or
diff --git a/.agents/skills/narratage/references/credentials.md b/.agents/skills/narratage/references/credentials.md
index 943babc3..2b704f6f 100644
--- a/.agents/skills/narratage/references/credentials.md
+++ b/.agents/skills/narratage/references/credentials.md
@@ -38,5 +38,5 @@ values with, for example,
An Endpoint whose Runtime Profile points at the read-only `env` CredentialStore must be configured
by setting its exact environment variable. `narratage auth login` deliberately refuses to prompt in
that case. For an interactive workstation, select the writable macOS Keychain CredentialStore in
-the Runtime Profile; then `narratage auth login <endpoint> --runtime <profile>` can store the secret.
+the Runtime Profile; after `runtime use`, `narratage auth login <endpoint>` can store the secret.
This is an explicit deployment choice, not a Provider-specific CLI branch.
diff --git a/.agents/skills/narratage/references/environment.md b/.agents/skills/narratage/references/environment.md
index b9802438..ad2a05a7 100644
--- a/.agents/skills/narratage/references/environment.md
+++ b/.agents/skills/narratage/references/environment.md
@@ -33,9 +33,10 @@ uv python install 3.13
uv sync --project services/whisperx --frozen
uv sync --project services/image-opencv --frozen
uv run --project services/whisperx --frozen svml-whisperx-prepare
-node --run narratage -- doctor svml.runtime.json
-node --run narratage -- runtime up svml.runtime.json
-node --run narratage -- runtime status svml.runtime.json
+node --run narratage -- runtime use svml.runtime.json
+node --run narratage -- doctor
+node --run narratage -- runtime up
+node --run narratage -- runtime status
```
Use `runtime up` for normal Build preparation: it owns the detached durable Worker and the external
@@ -46,7 +47,8 @@ After intentionally installing, removing or changing selected packages, refresh
project locks in one reviewed action:
```text
-node --run narratage -- packages sync build.svrun --runtime svml.runtime.json
+node --run narratage -- runtime use svml.runtime.json
+node --run narratage -- packages sync build.svrun
```
This command derives Author roots from that Run/Author Source closure and Runtime roots from the
diff --git a/.agents/skills/narratage/references/runtime.md b/.agents/skills/narratage/references/runtime.md
index 9aa931c5..626c02ed 100644
--- a/.agents/skills/narratage/references/runtime.md
+++ b/.agents/skills/narratage/references/runtime.md
@@ -6,26 +6,25 @@ Build, retrieval, and reuse syntax. Use this file as the operational checklist.
## Execute the lifecycle
```bash
-node --run narratage -- plan path/to/build.svrun \
- --runtime path/to/svml.runtime.json
+cd path/to/project
+node --run narratage -- runtime use svml.runtime.json
-node --run narratage -- build path/to/build.svrun \
- --runtime path/to/svml.runtime.json \
- --build-id my-build-001 --follow
+node --run narratage -- plan build.svrun
-node --run narratage -- inspect my-build-001 --runtime path/to/svml.runtime.json
-node --run narratage -- get my-build-001 \
- --runtime path/to/svml.runtime.json \
- --name final.video --to path/to/output/final.mp4
+node --run narratage -- build build.svrun --follow
+
+node --run narratage -- inspect <build-id>
+node --run narratage -- get <build-id> \
+ --name final.video --to output/final.mp4
```
Use `packages sync` only after package selection changes. Use `check` during authoring and `doctor`
or `runtime status` when diagnosing the deployment. `build` already ensures the detached Worker
and demanded managed services are available.
-Use `runtime logs` to diagnose the Worker and managed programs. Use `runtime down` for an orderly
-stop. It stops the Worker from claiming more leases and stops Runtime-owned programs, but preserves
-durable Builds and does not cancel remote Provider work.
+Use `runtime logs` to diagnose the Worker. Use `runtime down` to stop it from claiming more leases.
+External programs are intentionally independent; stop them only with `services down`. Durable
+Builds remain archived and neither command cancels remote Provider work.
## Preserve durable semantics
@@ -35,6 +34,8 @@ durable Builds and does not cancel remote Provider work.
bootstrap because it does not own the Worker lifecycle.
- A Build continues after durable submission. `--follow` only observes progress; interrupting the
terminal does not stop the Build.
+- Every `build` invocation creates a fresh automatic Build id. Source identity never reclaims an
+ earlier 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.
- There is no implicit cache or Pin state. Reuse Records through a new `.svrun` containing
diff --git a/docs/guide/runtime-profile.md b/docs/guide/runtime-profile.md
index dbc4036b..928f29f6 100644
--- a/docs/guide/runtime-profile.md
+++ b/docs/guide/runtime-profile.md
@@ -9,6 +9,16 @@ The Runtime Profile declares *where* a frozen Build executes: the Scheduler and
Stores, Endpoints, credentials and concurrency. It is deployment configuration, not
creative content—it never enters Author or Run graph identity.
+Select it once for the project:
+
+```bash
+narratage runtime use svml.runtime.json
+```
+
+The CLI stores only a relative pointer in `.svml/runtime`. The Profile remains authoritative for
+its root, both package-lock paths, Stores, Endpoints and scheduling. `runtime unset` removes the
+pointer without stopping work or deleting state. `--runtime <profile>` is a one-command override.
+
## Declarative JSON
```json
@@ -106,10 +116,12 @@ Neither value enters Author or Run graph identity.
### Scheduling
-`maxConcurrency` caps admitted Operations across all Workers sharing the DispatchStore. Provider
-packages contribute an Authority resource and an exact capability Route resource; the Store
-acquires both atomically. Optional `resources` overrides address those opaque ids. Capacity tickets
-are durable and fenced by the Build lease rather than process-local counters.
+`maxConcurrency` caps admitted Operations across all Workers sharing the DispatchStore. Each
+configured Provider contributes one total Authority limit plus its own route limits for actual model
+or API lanes. The Store acquires both for one task atomically; work is not copied through two queues.
+Routes are Provider-local, so KIE Seedance and another Provider's Seedance never share a hidden
+family counter. Capacity tickets are durable and fenced by the Build lease rather than process-local
+counters.
### Trust boundary
@@ -132,7 +144,7 @@ roles directly through `@narratage/local`.
Checks the Runtime Profile without running a Build or making paid requests:
```bash
-node --run narratage -- doctor svml.runtime.json
+node --run narratage -- doctor
```
Validates:
@@ -161,10 +173,10 @@ Build database or an unrelated Vertex configuration.
## Runtime lifecycle
```bash
-node --run narratage -- runtime up svml.runtime.json
-node --run narratage -- runtime status svml.runtime.json
-node --run narratage -- runtime logs svml.runtime.json
-node --run narratage -- runtime down svml.runtime.json
+node --run narratage -- runtime up
+node --run narratage -- runtime status
+node --run narratage -- runtime logs
+node --run narratage -- runtime down
```
`runtime up` owns the detached Worker plus declared external programs. `services` remains a narrow
@@ -180,8 +192,8 @@ refusal.
### gc (garbage collection)
```bash
-node --run narratage -- gc svml.runtime.json # dry-run
-node --run narratage -- gc svml.runtime.json --apply # delete unreachable Artifacts
+node --run narratage -- gc # dry-run
+node --run narratage -- gc --apply # delete unreachable Artifacts
```
Walks every retained BuildState and Operation, computes reachable Artifact digests, and reports
@@ -195,13 +207,13 @@ Every Build archives all accepted Records and referenced Artifacts durably, inde
### List Builds
```bash
-node --run narratage -- builds --runtime svml.runtime.json
+node --run narratage -- builds
```
### Inspect
```bash
-node --run narratage -- inspect <build-id> --runtime svml.runtime.json
+node --run narratage -- inspect <build-id>
```
Shows target bindings, demanded Logical Outputs, every accepted Record and Operation status.
@@ -210,19 +222,19 @@ Shows target bindings, demanded Logical Outputs, every accepted Record and Opera
```bash
# By source output name
-node --run narratage -- get <build-id> --runtime svml.runtime.json \
+node --run narratage -- get <build-id> \
--name final.video --to output.mp4
# By Record id
-node --run narratage -- get <build-id> --runtime svml.runtime.json \
+node --run narratage -- get <build-id> \
--record <record-id> --to output.json
# By Logical Output id
-node --run narratage -- get <build-id> --runtime svml.runtime.json \
+node --run narratage -- get <build-id> \
--output <output-id>
# By Artifact digest
-node --run narratage -- get <build-id> --runtime svml.runtime.json \
+node --run narratage -- get <build-id> \
--artifact <sha256:...> --to file.bin
```
diff --git a/docs/guide/services.md b/docs/guide/services.md
index 6a833867..36a00f6c 100644
--- a/docs/guide/services.md
+++ b/docs/guide/services.md
@@ -10,10 +10,11 @@ Two lifecycle scopes are deliberately separate.
## Runtime execution domain
```bash
-node --run narratage -- runtime up svml.runtime.json
-node --run narratage -- runtime status svml.runtime.json
-node --run narratage -- runtime logs svml.runtime.json
-node --run narratage -- runtime down svml.runtime.json
+node --run narratage -- runtime use svml.runtime.json
+node --run narratage -- runtime up
+node --run narratage -- runtime status
+node --run narratage -- runtime logs
+node --run narratage -- runtime down
```
`runtime up` starts or reuses the detached fenced Worker and also prepares/starts the external
@@ -42,9 +43,9 @@ same Profile path or regenerating either lock therefore makes the official Worke
old revision rejects the new revision without stopping the old Worker or starting external
programs. Once old work is terminal, replacement is allowed.
-`runtime down` asks the Worker to stop and then stops programs that the Profile owns. It does not
-cancel Builds or remote Provider jobs. Queued Builds remain durable and continue after the Runtime
-is brought up again.
+`runtime down` stops only the Worker. It deliberately leaves external programs alone because another
+Runtime Profile may share them. Use `services down` when the programs themselves should stop.
+Neither command cancels Builds or remote Provider jobs; queued Builds remain durable.
## External programs only
@@ -71,8 +72,8 @@ successful command. Readiness remains explicit in its structured `ready` field.
## Build relationship
```bash
-node --run narratage -- build build.svrun --runtime svml.runtime.json
-node --run narratage -- build build.svrun --runtime svml.runtime.json --follow
+node --run narratage -- build build.svrun
+node --run narratage -- build build.svrun --follow
```
Before submission, `build` derives the capabilities declared by the selected Producer steps and
@@ -95,11 +96,11 @@ the deployment, not one Build.
## Visibility
```bash
-node --run narratage -- queue --runtime svml.runtime.json
-node --run narratage -- queue --runtime svml.runtime.json --watch
-node --run narratage -- status <build-id> --runtime svml.runtime.json
-node --run narratage -- operations <build-id> --runtime svml.runtime.json
-node --run narratage -- operation <operation-id> --runtime svml.runtime.json
+node --run narratage -- queue
+node --run narratage -- queue --watch
+node --run narratage -- status <build-id>
+node --run narratage -- inspect <build-id>
+node --run narratage -- cancel <build-id>
```
These views expose the active durable dispatch set, Worker state, lease/capacity facts, Operation
@@ -107,6 +108,13 @@ attempts, generic Endpoint progress, checkpoints and cancellation state. They do
secret second graph or ask a Provider for creative
routing.
+The public control unit is the Build. `cancel` atomically withdraws a queued Build that no Worker
+has claimed, or closes admission and reconciles already-submitted Provider work for a running
+Build. Individual Operations remain visible inside Build status but are not independently
+controlled by the CLI. A terminal Build is never reopened; running the same `.svrun` submits a new
+Build. Endpoint checkpoint recovery only continues the same already-paid external task after a
+Worker restart.
+
Use `--json` for one versioned result and `--jsonl` for a watch stream. `queue --watch` emits the
first snapshot and later changes; it does not print an identical block every second while a remote
job remains in the same state.
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 8e8d87ee..bb4ac071 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -118,15 +118,16 @@ lightweight `narratage` launcher from your project directory:
```bash
cd /path/to/my-video
-/path/to/narratage/narratage packages sync build.svrun \
- --runtime svml.runtime.json
+/path/to/narratage/narratage runtime use svml.runtime.json
-/path/to/narratage/narratage plan build.svrun \
- --runtime svml.runtime.json
+/path/to/narratage/narratage packages sync build.svrun
+/path/to/narratage/narratage plan build.svrun
```
The launcher uses dependencies installed in the Narratage checkout, but Source, SQLite state,
-Artifacts and outputs remain inside your project. `packages sync` adds or refreshes the current
+Artifacts and outputs remain inside your project. `runtime use` stores only a local pointer at
+`.svml/runtime`; the selected Profile remains the single source for both lock paths and the
+execution environment. `packages sync` adds or refreshes the current
Run and Runtime selections in the two project package inventories; it does not remove another
Run's packages.
@@ -139,27 +140,22 @@ and credentials with your own.
After reviewing the plan:
```bash
-/path/to/narratage/narratage build build.svrun \
- --runtime svml.runtime.json \
- --build-id my-video-001 \
- --follow
+/path/to/narratage/narratage build build.svrun --follow
```
-`build` stores the Build, ensures its Worker is available, and starts only the external programs
-declared by the selected endpoints. `--follow` is an observer; closing it does not stop the Build.
+`build` assigns and prints a fresh Build id, stores the Build, ensures its Worker is available, and
+starts only the external programs declared by the selected endpoints. `--follow` is an observer;
+closing it does not stop the Build.
Use `check` while editing a source. Use `doctor` to diagnose a new or broken deployment. They are
safe, but neither is required as a repetitive pre-Build ceremony.
```bash
-/path/to/narratage/narratage status my-video-001 \
- --runtime svml.runtime.json
+/path/to/narratage/narratage status <build-id>
-/path/to/narratage/narratage queue \
- --runtime svml.runtime.json --watch
+/path/to/narratage/narratage queue --watch
-/path/to/narratage/narratage get my-video-001 \
- --runtime svml.runtime.json \
+/path/to/narratage/narratage get <build-id> \
--name final.video \
--to output/final.mp4
```
diff --git a/docs/quickstart/run.md b/docs/quickstart/run.md
index a105435e..2acfe5a7 100644
--- a/docs/quickstart/run.md
+++ b/docs/quickstart/run.md
@@ -9,18 +9,19 @@ The Author Source defines the video. A Run Source chooses which of its public ou
which explicit Candidates, if any, should satisfy them. The Runtime Profile chooses the machine,
stores and Provider endpoints that execute the resulting plan.
-Package trust is synchronized once after package selections change:
+Select the project Runtime once, then synchronize package trust after package selections change:
```bash
-narratage packages sync build.svrun --runtime svml.runtime.json
+narratage runtime use svml.runtime.json
+narratage packages sync build.svrun
```
Ordinary work then follows the short path:
```bash
-narratage plan build.svrun --runtime svml.runtime.json
-narratage build build.svrun --runtime svml.runtime.json --build-id my-video-001 --follow
-narratage get my-video-001 --runtime svml.runtime.json --name final.video --to output/final.mp4
+narratage plan build.svrun
+narratage build build.svrun --follow
+narratage get <build-id> --name final.video --to output/final.mp4
```
The checked-in source launcher is `/path/to/narratage/narratage`; commands written as `narratage`
@@ -99,13 +100,13 @@ Core has no Pin state or fidelity label.
<target output="final.video"/>
<build-record id="hook-video"
- build="my-film-001" output="hook-take.video"/>
+ build="bld_01234567-89ab-cdef-0123-456789abcdef" output="hook-take.video"/>
<build-record id="meeting-video"
- build="my-film-001" output="meeting-take.video"/>
+ build="bld_01234567-89ab-cdef-0123-456789abcdef" output="meeting-take.video"/>
<build-record id="evidence-video"
- build="my-film-001" output="evidence-take.video"/>
+ build="bld_01234567-89ab-cdef-0123-456789abcdef" output="evidence-take.video"/>
<build-record id="payoff-video"
- build="my-film-001" output="payoff-take.video"/>
+ build="bld_01234567-89ab-cdef-0123-456789abcdef" output="payoff-take.video"/>
<satisfy output="hook-take.video" candidate="hook-video"/>
<satisfy output="meeting-take.video" candidate="meeting-video"/>
@@ -140,13 +141,13 @@ current name on `<satisfy>`:
```svml
<build-record id="approved-opening"
- build="my-film-001" output="hook-take.video"/>
+ build="bld_01234567-89ab-cdef-0123-456789abcdef" output="hook-take.video"/>
<satisfy output="opening-shot.video" candidate="approved-opening"/>
```
-Narratage never infers that two names mean the same author intent. A human-readable build-id such
-as `my-film-001` is supplied with `build --build-id`; omitting it uses the immutable compiled Core
-Build digest. Reusing one explicit build-id for different compiled Author or Run intent is rejected.
+Narratage never infers that two names mean the same author intent. Every `build` invocation receives
+a fresh Build id, which the CLI prints and the Runtime archives. Source identity never reclaims an
+earlier Build. A later Run reuses an accepted result only by naming that historical Build id here.
### build-record
@@ -155,7 +156,7 @@ Declares a zero-input Candidate backed by a historical Record from a previous Bu
| Attribute | Description |
|---|---|
| `id` | Local Candidate id within this Run Source |
-| `build` | The build-id of the previous Build |
+| `build` | The automatically assigned id of the previous Build |
| `output` | The Logical Output name from that Build |
### satisfy
@@ -197,6 +198,12 @@ Distribution instead of assigning semantics from the filename suffix. Applicatio
Narratage may assemble the same Runtime roles through `@narratage/local`. See the complete
[Runtime Profile guide](../guide/runtime-profile.md).
+`narratage runtime use <profile>` stores only a project-local pointer in `.svml/runtime`. It does
+not copy the Profile, start anything or generate locks. Commands resolve the Profile through that
+pointer; the Profile then names both lock files. An explicit `--runtime <profile>` remains a
+one-command override and never changes the saved selection. Source commands search upward from the
+entry Source; Runtime and archive commands search upward from the current directory.
+
```json
{
"format": "svml.runtime-config@1",
@@ -346,13 +353,11 @@ Author files do not have to live under this repository. For example, keep a proj
`/work/my-film` while using packages installed in `/opt/narratage`:
```bash
-cd /opt/narratage
-
-node --run narratage -- packages sync /work/my-film/build.svrun \
- --runtime /work/my-film/svml.runtime.json
+cd /work/my-film
-node --run narratage -- plan /work/my-film/build.svrun \
- --runtime /work/my-film/svml.runtime.json
+/opt/narratage/narratage runtime use svml.runtime.json
+/opt/narratage/narratage packages sync build.svrun
+/opt/narratage/narratage plan build.svrun
```
When a Runtime Profile is selected, its `root` (or its own directory when `root` is omitted) is the
@@ -426,9 +431,9 @@ other than the CLI installation.
After installing or updating packages, synchronize the project inventories:
```bash
-node --run narratage -- packages sync examples/talking-head-aroll/build.svrun \
- --runtime examples/talking-head-aroll/svml.runtime.json \
- --root .
+cd examples/talking-head-aroll
+node --run narratage -- runtime use svml.runtime.json
+node --run narratage -- packages sync build.svrun
```
The current Author and Run sources choose author packages. The Runtime Profile chooses environment
@@ -440,33 +445,29 @@ scans the project, starts a Provider or generates media.
### 2. Diagnose the environment
```bash
-node --run narratage -- doctor examples/talking-head-aroll/svml.runtime.json
+node --run narratage -- doctor
```
Doctor validates both locks, every selected Runtime role, Endpoint configuration, credential
presence and bounded environment probes. It never starts the Worker or performs a paid request.
Doctor is intentionally a **full profile audit**. For the environment required by one Run, use
-`plan --runtime`: it checks only capabilities demanded by that finite plan. A valid plan remains a
+`plan`: it checks only capabilities demanded by that finite plan. A valid plan remains a
successful command even when `preflight.ok` is false; `doctor` or `build` enforces deployment
readiness.
### 3. Check source and inspect the plan
```bash
-node --run narratage -- check examples/talking-head-aroll/main.svml \
- --runtime examples/talking-head-aroll/svml.runtime.json \
- --root .
+node --run narratage -- check main.svml
```
```bash
-node --run narratage -- plan examples/talking-head-aroll/build.svrun \
- --runtime examples/talking-head-aroll/svml.runtime.json \
- --root .
+node --run narratage -- plan build.svrun
```
Review the frozen BuildPlan before spending money. The plan shows every Operation and Needs the
-Scheduler would issue. With `--runtime`, it also reports only the relevant Endpoint, credential and
+Scheduler would issue. With a selected Runtime, it also reports only the relevant Endpoint, credential and
external-program diagnostics. It never starts external work.
`build` starts or reuses the detached Runtime automatically. Use `runtime up` only when you want to
@@ -476,11 +477,7 @@ commands manage external programs only and do not own the Worker lifecycle.
### 4. Submit the Build
```bash
-node --run narratage -- build examples/talking-head-aroll/build.svrun \
- --runtime examples/talking-head-aroll/svml.runtime.json \
- --root . \
- --build-id my-film-001 \
- --follow
+node --run narratage -- build build.svrun --follow
```
Without `--follow`, `build` returns after durable submission. The detached Worker continues. With
@@ -489,33 +486,28 @@ interrupting it leaves the Build running.
| Flag | Description |
|---|---|
-| `--runtime` | Path to the Runtime Profile |
+| `--runtime` | One-command Runtime Profile override; normally select it once with `runtime use` |
| `--package-lock` | Standalone compilation lock when no Runtime Profile is supplied; a JSON Profile single-sources it for `check`, `plan` and `build` |
| `--package-root` | Host directory containing the installed packages named by the lock |
| `--root` | Optional Source Workspace override; otherwise the Runtime Profile root, package-lock directory, or entry Source directory is used in that order |
-| `--build-id` | User-chosen identifier for this Build (used for retrieval and reuse) |
| `--follow` | Wait for terminal state as an observer; durable execution remains with the Worker |
-Without `--build-id`, identity is derived from the compiled Author and Run intent: repeating the
-same command addresses the same durable Build and does not silently buy another generation. An
-unfinished Build continues from accepted Records and recoverable Endpoint checkpoints; a completed,
-failed or cancelled Build remains terminal and is only reported. Use a new explicit id when the same
-unchanged prompt intentionally needs another stochastic take. Reusing an explicit id for different
-compiled intent is rejected with both repair choices.
+Each invocation creates a fresh Build id, even when the Author and Run Sources are unchanged. That
+is necessary for non-deterministic generation: cross-Build reuse belongs only to explicit Candidates
+in a Run Source. Once submitted, that one Build is durable. A Worker restart continues its accepted
+Records and the same external task checkpoints; it never turns another invocation into that Build.
### 5. Inspect and retrieve results
```bash
-node --run narratage -- inspect my-film-001 \
- --runtime examples/talking-head-aroll/svml.runtime.json
+node --run narratage -- inspect <build-id>
```
`inspect` reports durable Build state, demanded outputs, and accepted Records. Retrieve the selected
archived Artifact only after those facts are correct:
```bash
-node --run narratage -- get my-film-001 \
- --runtime examples/talking-head-aroll/svml.runtime.json \
+node --run narratage -- get <build-id> \
--name final.video \
--to examples/talking-head-aroll/output/final.mp4
```
@@ -534,18 +526,16 @@ Create a new `.svrun` file that references the completed Build's Records (see [R
above), then submit it:
```bash
-node --run narratage -- build examples/talking-head-aroll/reuse-generated.svrun \
- --runtime examples/talking-head-aroll/svml.runtime.json \
- --build-id my-film-reuse-001 --follow
+node --run narratage -- build reuse-generated.svrun --follow
```
### 7. Diagnose or stop the local Runtime
```bash
-node --run narratage -- runtime logs examples/talking-head-aroll/svml.runtime.json
-node --run narratage -- runtime down examples/talking-head-aroll/svml.runtime.json
+node --run narratage -- runtime logs
+node --run narratage -- runtime down
```
-`runtime down` stops the Worker from claiming more leases and stops Runtime-owned programs. It does
-not cancel durable Builds or remote Provider work. Start the same Profile again to resume local
-execution.
+`runtime down` stops the Worker from claiming more leases but leaves external programs running.
+Use `services down` only when those programs should also stop. Neither command cancels durable
+Builds or remote Provider work. Starting the same Profile again continues unfinished dispatches.
diff --git a/docs/zh/guide/runtime-profile.md b/docs/zh/guide/runtime-profile.md
index 0df066b9..14ce76d5 100644
--- a/docs/zh/guide/runtime-profile.md
+++ b/docs/zh/guide/runtime-profile.md
@@ -7,6 +7,16 @@ description: 显式配置 Build 的执行环境、状态存储、凭据与并发
Runtime Profile 声明冻结后的 Build *在哪里*执行:Scheduler、Worker、全部 Store、Endpoint、凭据和并发。它属于部署配置,绝不进入 Author Graph 或 Run Graph 身份。
+每个项目只需选择一次:
+
+```bash
+narratage runtime use svml.runtime.json
+```
+
+CLI 只在 `.svml/runtime` 保存一个相对路径指针。Profile 仍然唯一决定项目根、两份 package
+lock、Store、Endpoint 与调度。`runtime unset` 只删除该指针,不停止任务、不删除状态;
+`--runtime <profile>` 则是单次命令覆盖。
+
## 声明式 Profile
```json
@@ -65,7 +75,7 @@ Narratage 安装目录加载校验后的包。
## 并发与信任边界
-`maxConcurrency`、Provider Authority 与精确 Capability Route 的上限由 DispatchStore 在所有共享 Worker 之间执行,不是某个 CLI 进程里的计数器。容量租约跟随 Build 的 fenced lease;过期 Worker 不能继续准入结果。
+`maxConcurrency`、每个 Provider 的总 Authority 上限与其内部实际模型/API route 上限,由 DispatchStore 在所有共享 Worker 之间执行。一次任务原子领取 Provider 与 route 两份容量,不会在父子队列间复制。Route 是 Provider 本地概念;KIE Seedance 与另一个 Provider 的 Seedance 不共享隐藏的家族计数器。容量租约跟随 Build 的 fenced lease;过期 Worker 不能继续准入结果。
Runtime Adapter 当前是可信本地代码。开放任意第三方 Adapter 之前,需要真正的进程或 Wasm
隔离;字符串 allowlist 不能限制同一 Node 进程里的代码。
@@ -79,11 +89,11 @@ KIE 不会被旧 Build 数据库或无关的 Vertex 配置拦住。
## 生命周期
```bash
-node --run narratage -- doctor svml.runtime.json
-node --run narratage -- runtime up svml.runtime.json
-node --run narratage -- runtime status svml.runtime.json
-node --run narratage -- runtime logs svml.runtime.json
-node --run narratage -- runtime down svml.runtime.json
+node --run narratage -- doctor
+node --run narratage -- runtime up
+node --run narratage -- runtime status
+node --run narratage -- runtime logs
+node --run narratage -- runtime down
```
`runtime up` 管理耐久 Worker 与声明的外部程序。`services up/status/down` 只管理外部程序,不会启动 Worker。`build` 会确保 Runtime 已启动,但 Build 所在终端从不拥有执行权。Distribution 提供一个不透明 Runtime 修订;官方 JSON Profile 让它覆盖 Profile 与两份 package lock,通用 CLI 不解释其语法。任一文件变化后状态变为
@@ -99,14 +109,12 @@ CredentialStore 来解析引用,完成后立即关闭,并可执行显式声
## Build、队列与归档
```bash
-node --run narratage -- build build.svrun --runtime svml.runtime.json
-node --run narratage -- build build.svrun --runtime svml.runtime.json --follow
-node --run narratage -- queue --runtime svml.runtime.json --watch
-node --run narratage -- status <build-id> --runtime svml.runtime.json
-node --run narratage -- operations <build-id> --runtime svml.runtime.json
-node --run narratage -- operation <operation-id> --runtime svml.runtime.json
-node --run narratage -- inspect <build-id> --runtime svml.runtime.json
-node --run narratage -- get <build-id> --runtime svml.runtime.json --name final.video --to output.mp4
+node --run narratage -- build build.svrun
+node --run narratage -- build build.svrun --follow
+node --run narratage -- queue --watch
+node --run narratage -- status <build-id>
+node --run narratage -- inspect <build-id>
+node --run narratage -- get <build-id> --name final.video --to output.mp4
```
不带 `--follow` 时,`build` 在耐久提交后退出;Worker 继续执行。`--follow` 只是观察,Ctrl-C
@@ -115,11 +123,10 @@ node --run narratage -- get <build-id> --runtime svml.runtime.json --name final.
## 取消
```bash
-node --run narratage -- cancel build <build-id> --runtime svml.runtime.json
-node --run narratage -- cancel operation <operation-id> --runtime svml.runtime.json
+node --run narratage -- cancel <build-id>
```
-Build 取消先关闭准入;Operation 取消只抑制那个精确实现。`accepted` 只是远端接受停止请求,不等于已停止;系统继续协调到 `confirmed`、`unsupported`、`too-late` 或自然结束。迟到的付费产物继续归档,但不能进入被抑制的 Core 分支。Runtime 不会因此偷偷换 Candidate 或 Provider。
+CLI 唯一控制单位是 Build。尚未被 Worker 领取的排队 Build 会在 Store 中原子撤回;已经运行的 Build 会先关闭后续准入,再尽力取消已提交的 Provider 工作。`accepted` 只是远端接受停止请求,不等于已经停止;系统继续协调到 `confirmed`、`unsupported`、`too-late` 或自然结束。Operation 仍会作为 Build 详情显示,但不能被 CLI 单独控制。终态 Build 不会重新打开;再次运行同一 `.svrun` 会创建新 Build。Endpoint 的 checkpoint 恢复只用于 Worker 重启后续接同一个已提交外部任务,避免重复付费。
## 嵌入 API
diff --git a/docs/zh/guide/services.md b/docs/zh/guide/services.md
index 091d9201..080d285a 100644
--- a/docs/zh/guide/services.md
+++ b/docs/zh/guide/services.md
@@ -10,10 +10,11 @@ description: 管理耐久 Worker 与 Profile 明确选择的本地程序。
## 整个执行域
```bash
-node --run narratage -- runtime up svml.runtime.json
-node --run narratage -- runtime status svml.runtime.json
-node --run narratage -- runtime logs svml.runtime.json
-node --run narratage -- runtime down svml.runtime.json
+node --run narratage -- runtime use svml.runtime.json
+node --run narratage -- runtime up
+node --run narratage -- runtime status
+node --run narratage -- runtime logs
+node --run narratage -- runtime down
```
`runtime up` 启动或复用当前 Profile 的后台 Worker,并准备、启动该 Profile 声明的外部程序。重复执行不会创建第二个同域 Worker。`runtime status` 同时展示 Worker、耐久队列、共享容量和外部程序健康状态。
@@ -23,8 +24,9 @@ node --run narratage -- runtime down svml.runtime.json
后台进程同时绑定 Profile 路径与 Distribution 提供的不透明修订值。官方 JSON Profile 的实现让该修订覆盖 Profile 与两份 package lock;通用 CLI 不解析配置文档,也不假定哪些文件属于修订。任一文件变化后,官方 Worker 会显示为 `stale`;下一次 `runtime up` 或 `build` 会先替换旧进程,不会让新 Dispatch 偷偷进入旧执行闭包。
-`runtime down` 停止 Worker 和由该 Profile 管理的程序,但不会取消 Build 或远端 Provider
-任务。队列仍在 Store 中,下次启动后继续。
+`runtime down` 只停止 Worker,并故意保留外部程序,因为其他 Runtime Profile 可能正在共用
+它们。只有确实要停止这些程序时才执行 `services down`。两条命令都不会取消 Build 或远端
+Provider 任务,队列仍在 Store 中,下次启动后继续。
## 只管理外部程序
@@ -58,15 +60,18 @@ Operation 数量变化时输出一行。中断观察终端不会中断 Worker。
## 可见性
```bash
-node --run narratage -- queue --runtime svml.runtime.json --watch
-node --run narratage -- status <build-id> --runtime svml.runtime.json
-node --run narratage -- operations <build-id> --runtime svml.runtime.json
-node --run narratage -- operation <operation-id> --runtime svml.runtime.json
+node --run narratage -- queue --watch
+node --run narratage -- status <build-id>
+node --run narratage -- inspect <build-id>
+node --run narratage -- cancel <build-id>
```
这些命令展示活跃 dispatch、Worker 状态、租约/容量、Operation 的通用进度、checkpoint 和取消状态。并发启动按 Profile 串行化,只会复用一个 Worker 和每个受管外部服务的一个实例;
`--follow` 若发现 Worker 已停止会明确报出重启命令,不会无限等待。`--json` 输出一次结构化结果,watch 命令可用 `--jsonl`。`queue --watch` 只输出第一份快照和后续变化,不会在远端任务状态没变时每秒重复刷同一个块。
+CLI 的公开控制单位只有 Build。未被 Worker 领取的排队 Build 会被原子撤回;已运行的 Build
+会关闭后续准入并协调已经提交的 Provider 工作。Operation 仍显示在 Build 详情中,但不能单独控制。终态 Build 不会重新打开;再次运行同一 `.svrun` 会创建新 Build。Endpoint checkpoint 只用于 Worker 重启后续接同一个已提交的外部任务,避免重复付费。
+
## WhisperX
`@narratage/provider-whisperx-local` 声明热服务及健康探测,锁定协议、包版本、模型、设备、计算类型和 batch size。服务只读取允许目录下的规范证据 WAV。Runtime Route 资源避免无意义的并发 `BUSY`。
diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md
index b012fd54..a75c984a 100644
--- a/docs/zh/quickstart.md
+++ b/docs/zh/quickstart.md
@@ -114,15 +114,15 @@ Runtime Profile 说明在哪里做。
```bash
cd /path/to/my-video
-/path/to/narratage/narratage packages sync build.svrun \
- --runtime svml.runtime.json
+/path/to/narratage/narratage runtime use svml.runtime.json
-/path/to/narratage/narratage plan build.svrun \
- --runtime svml.runtime.json
+/path/to/narratage/narratage packages sync build.svrun
+/path/to/narratage/narratage plan build.svrun
```
启动器使用 Narratage 仓库已经安装好的依赖,但源码、SQLite 状态、Artifact 和输出都会留在你的项目里。
-`packages sync` 把当前 Run 与 Runtime 选择加入或刷新到两份项目包库存中,不会删除其他 Run 的包。
+`runtime use` 只在 `.svml/runtime` 保存一个本地指针;所选 Profile 仍然是两份 lock 路径和执行环境的
+唯一来源。`packages sync` 把当前 Run 与 Runtime 选择加入或刷新到两份项目包库存中,不会删除其他 Run 的包。
需要完整 Runtime Profile 时,从
[`examples/talking-film-live`](https://github.com/hypit-ai/narratage/tree/main/examples/talking-film-live) 的结构开始:复制文件结构,
@@ -133,27 +133,21 @@ cd /path/to/my-video
检查并确认计划之后:
```bash
-/path/to/narratage/narratage build build.svrun \
- --runtime svml.runtime.json \
- --build-id my-video-001 \
- --follow
+/path/to/narratage/narratage build build.svrun --follow
```
-`build` 会持久化这次 Build、确保对应 Worker 可用,并只启动所选 Endpoint 声明的外部程序。
-`--follow` 只是观察器;关掉它不会停止 Build。
+`build` 会自动分配并打印一个新的 Build id、持久化这次 Build、确保对应 Worker 可用,并只启动
+所选 Endpoint 声明的外部程序。`--follow` 只是观察器;关掉它不会停止 Build。
编辑源码时使用 `check`;配置或排查部署时使用 `doctor`。它们都不会提交工作,但也不是每次
Build 前必须重复的仪式。
```bash
-/path/to/narratage/narratage status my-video-001 \
- --runtime svml.runtime.json
+/path/to/narratage/narratage status <build-id>
-/path/to/narratage/narratage queue \
- --runtime svml.runtime.json --watch
+/path/to/narratage/narratage queue --watch
-/path/to/narratage/narratage get my-video-001 \
- --runtime svml.runtime.json \
+/path/to/narratage/narratage get <build-id> \
--name final.video \
--to output/final.mp4
```
diff --git a/docs/zh/quickstart/run.md b/docs/zh/quickstart/run.md
index 55f22e07..4e3e19b5 100644
--- a/docs/zh/quickstart/run.md
+++ b/docs/zh/quickstart/run.md
@@ -7,18 +7,19 @@ description: 声明 Build 目标、复用结果以及配置运行时环境。
Author Source 定义视频本身。Run Source 从中挑选要产出哪些公开输出,以及是否用明确的 Candidate 来满足它们。Runtime Profile 则选择执行这份计划的机器、Store 与 Provider endpoint。
-包选择变化后,只需同步一次包信任:
+先为项目选择一次 Runtime;之后只在包选择变化时同步包信任:
```bash
-narratage packages sync build.svrun --runtime svml.runtime.json
+narratage runtime use svml.runtime.json
+narratage packages sync build.svrun
```
日常制作只需要这条短路径:
```bash
-narratage plan build.svrun --runtime svml.runtime.json
-narratage build build.svrun --runtime svml.runtime.json --build-id my-video-001 --follow
-narratage get my-video-001 --runtime svml.runtime.json --name final.video --to output/final.mp4
+narratage plan build.svrun
+narratage build build.svrun --follow
+narratage get <build-id> --name final.video --to output/final.mp4
```
仓库内的源码启动器是 `/path/to/narratage/narratage`;本页写作 `narratage` 的命令,指的是这个启动器,或将来安装好的 CLI。
@@ -87,13 +88,13 @@ Narratage 没有隐式缓存。复用结果是显式的运行图编写——你
<target output="final.video"/>
<build-record id="hook-video"
- build="my-film-001" output="hook-take.video"/>
+ build="bld_01234567-89ab-cdef-0123-456789abcdef" output="hook-take.video"/>
<build-record id="meeting-video"
- build="my-film-001" output="meeting-take.video"/>
+ build="bld_01234567-89ab-cdef-0123-456789abcdef" output="meeting-take.video"/>
<build-record id="evidence-video"
- build="my-film-001" output="evidence-take.video"/>
+ build="bld_01234567-89ab-cdef-0123-456789abcdef" output="evidence-take.video"/>
<build-record id="payoff-video"
- build="my-film-001" output="payoff-take.video"/>
+ build="bld_01234567-89ab-cdef-0123-456789abcdef" output="payoff-take.video"/>
<satisfy output="hook-take.video" candidate="hook-video"/>
<satisfy output="meeting-take.video" candidate="meeting-video"/>
@@ -124,13 +125,13 @@ Build、Logical Output 和 Record 摘要共同确定。假如当前源码把 `ho
```svml
<build-record id="approved-opening"
- build="my-film-001" output="hook-take.video"/>
+ build="bld_01234567-89ab-cdef-0123-456789abcdef" output="hook-take.video"/>
<satisfy output="opening-shot.video" candidate="approved-opening"/>
```
-Narratage 永远不会猜测两个名字代表同一份作者意图。`my-film-001` 这样的可读 build-id 由
-`build --build-id` 提供;省略时使用不可变的编译后 Core Build 摘要。已经绑定的显式 build-id
-不能再用于另一份作者意图或运行意图。
+Narratage 永远不会猜测两个名字代表同一份作者意图。每次执行 `build` 都会得到一个新的
+Build id,由 CLI 打印并由 Runtime 归档。源码身份绝不会重新认领旧 Build;后续 Run 只有在
+这里明确写出历史 Build id 时,才会复用它已经接受的结果。
### build-record
@@ -139,7 +140,7 @@ Narratage 永远不会猜测两个名字代表同一份作者意图。`my-film-0
| 属性 | 说明 |
|---|---|
| `id` | 此 Run Source 内的本地 Candidate 标识符 |
-| `build` | 先前 Build 的 build-id |
+| `build` | 先前 Build 自动分配的 id |
| `output` | 该 Build 中的逻辑输出名 |
### satisfy
@@ -175,6 +176,11 @@ Runtime Profile(`svml.runtime.json`)告诉系统**在哪里**执行每种类
相同的 Runtime 角色。完整说明见
[Runtime Profile 指南](../guide/runtime-profile.md)。
+`narratage runtime use <profile>` 只在 `.svml/runtime` 保存一个项目本地指针,不复制 Profile、
+不启动环境,也不生成 lock。后续命令先通过该指针找到 Profile,再由 Profile 指定两份 lock。
+显式 `--runtime <profile>` 仍可作为单次覆盖,并且不会改变已经保存的选择。源码命令从入口
+Source 所在目录向上查找;Runtime 与归档命令则从当前目录向上查找。
+
```json
{
"format": "svml.runtime-config@1",
@@ -318,13 +324,11 @@ Worker。
`/opt/narratage` 中已安装的包:
```bash
-cd /opt/narratage
-
-node --run narratage -- packages sync /work/my-film/build.svrun \
- --runtime /work/my-film/svml.runtime.json
+cd /work/my-film
-node --run narratage -- plan /work/my-film/build.svrun \
- --runtime /work/my-film/svml.runtime.json
+/opt/narratage/narratage runtime use svml.runtime.json
+/opt/narratage/narratage packages sync build.svrun
+/opt/narratage/narratage plan build.svrun
```
选择 Runtime Profile 时,Profile 的 `root`(未写则为 Profile 所在目录)是该项目所有
@@ -390,9 +394,9 @@ Runtime 状态、归档 Artifact 和 lock 仍全部留在 `/work/my-film`。只
安装或更新包后,用一条显式命令同步两份项目包库存:
```bash
-node --run narratage -- packages sync examples/talking-head-aroll/build.svrun \
- --runtime examples/talking-head-aroll/svml.runtime.json \
- --root .
+cd examples/talking-head-aroll
+node --run narratage -- runtime use svml.runtime.json
+node --run narratage -- packages sync build.svrun
```
当前 Author/Run Source 选择作者包,Runtime Profile 选择环境包。`packages sync` 只把本次
@@ -403,31 +407,27 @@ Provider,也不生成媒体。
### 2. 诊断环境
```bash
-node --run narratage -- doctor examples/talking-head-aroll/svml.runtime.json
+node --run narratage -- doctor
```
Doctor 校验两份 lock、全部显式 Runtime 角色、Endpoint 配置、凭据是否存在和有界环境探测;它不启动 Worker,也不发付费请求。
`doctor` 有意检查完整 Runtime Profile。若只想检查某次 Run 真正需要的环境,请使用带
-`--runtime` 的 `plan`。只要计划本身有效,命令就成功;凭据或服务未就绪会写在
+所选 Runtime 下的 `plan`。只要计划本身有效,命令就成功;凭据或服务未就绪会写在
`preflight.ok` 中,由 `doctor` 或 `build` 在部署阶段严格处理。
### 3. 检查 Source 与计划
```bash
-node --run narratage -- check examples/talking-head-aroll/main.svml \
- --runtime examples/talking-head-aroll/svml.runtime.json \
- --root .
+node --run narratage -- check main.svml
```
```bash
-node --run narratage -- plan examples/talking-head-aroll/build.svrun \
- --runtime examples/talking-head-aroll/svml.runtime.json \
- --root .
+node --run narratage -- plan build.svrun
```
-在花费资金之前审查冻结的 BuildPlan。该计划展示调度器将发出的每个 Operation 和 Needs;带
-`--runtime` 时只预检这次计划真正需要的 Endpoint、凭据和外部程序,不启动任何外部工作。
+在花费资金之前审查冻结的 BuildPlan。该计划展示调度器将发出的每个 Operation 和 Needs;选择
+Runtime 后只预检这次计划真正需要的 Endpoint、凭据和外部程序,不启动任何外部工作。
`build` 会自动启动或复用后台 Runtime。只有希望提交前预热时才需要显式执行 `runtime up`;
`runtime status` 用于观察。范围更窄的 `services up|status|down` 只管理外部程序,不负责 Worker。
@@ -435,39 +435,34 @@ node --run narratage -- plan examples/talking-head-aroll/build.svrun \
### 4. 提交 Build
```bash
-node --run narratage -- build examples/talking-head-aroll/build.svrun \
- --runtime examples/talking-head-aroll/svml.runtime.json \
- --root . \
- --build-id my-film-001 \
- --follow
+node --run narratage -- build build.svrun --follow
```
不带 `--follow` 时,Build 在耐久提交后退出,后台 Worker 继续。带 `--follow` 时终端也只是观察者,并会报告 phase / Operation 数量变化;Ctrl-C 不会取消任务。
| 标志 | 说明 |
|---|---|
-| `--runtime` | Runtime Profile 的路径 |
+| `--runtime` | 单次命令的 Runtime Profile 覆盖;通常用 `runtime use` 选择一次即可 |
| `--package-lock` | 包锁定文件的路径 |
| `--package-root` | 存放 lock 所列已安装包的 Host 目录 |
| `--root` | 可选的 Source Workspace 覆盖项;未传时依次使用 Runtime Profile 根、package lock 目录或入口 Source 目录 |
-| `--build-id` | 用户为此 Build 选择的标识符(用于检索和复用) |
| `--follow` | 将 Build 进度流式输出到终端 |
-不传 `--build-id` 时,身份由编译后的作者意图和运行意图派生;重复同一条命令只会寻址同一个耐久 Build,不会偷偷再买一次生成。未完成的 Build 从已验收 Record 和可恢复 Endpoint checkpoint
-继续;已完成、失败或取消的 Build 保持终态,只返回状态。相同 prompt 明确需要另一份随机结果时,使用新的显式 id。把已有显式 id 用到另一份编译意图上会被拒绝,并同时提示“换 id”或“恢复原 Source”。
+每次执行都会创建新的 Build id,即使 Author Source 和 Run Source 完全没变。这是非确定性生成
+所要求的边界:跨 Build 复用只能由 Run Source 里的显式 Candidate 决定。一次 Build 提交后
+具有耐久性;Worker 重启会继续它已经接受的 Record 和同一外部任务的 checkpoint,但不会让
+另一次命令变成这个 Build。
### 5. 检查并获取结果
```bash
-node --run narratage -- inspect my-film-001 \
- --runtime examples/talking-head-aroll/svml.runtime.json
+node --run narratage -- inspect <build-id>
```
`inspect` 会显示耐久 Build 状态、所需输出与已接受的 Record。确认这些事实正确后,再获取所选归档 Artifact:
```bash
-node --run narratage -- get my-film-001 \
- --runtime examples/talking-head-aroll/svml.runtime.json \
+node --run narratage -- get <build-id> \
--name final.video \
--to examples/talking-head-aroll/output/final.mp4
```
@@ -482,17 +477,16 @@ Build 的最终输出会为每个目标别名打印精确的 `get --name …`
创建一个引用已完成 Build 的 Record 的新 `.svrun` 文件(参见上文 [复用结果](#复用结果)),然后提交:
```bash
-node --run narratage -- build examples/talking-head-aroll/reuse-generated.svrun \
- --runtime examples/talking-head-aroll/svml.runtime.json \
- --build-id my-film-reuse-001 --follow
+node --run narratage -- build reuse-generated.svrun --follow
```
### 7. 诊断或停止本地 Runtime
```bash
-node --run narratage -- runtime logs examples/talking-head-aroll/svml.runtime.json
-node --run narratage -- runtime down examples/talking-head-aroll/svml.runtime.json
+node --run narratage -- runtime logs
+node --run narratage -- runtime down
```
-`runtime down` 会让 Worker 停止领取新 lease,并停止 Runtime 管理的程序;它不会取消耐久
-Build 或远程 Provider 工作。再次启动同一 Profile 即可恢复本地执行。
+`runtime down` 只会让 Worker 停止领取新 lease,并保留外部程序;只有确实要停掉这些程序时
+才执行 `services down`。两条命令都不会取消耐久 Build 或远程 Provider 工作。再次启动同一
+Profile 后,会继续其中尚未完成的 dispatch。
diff --git a/examples/all-components-preview/fixtures/card.svg b/examples/all-components-preview/fixtures/card.svg
new file mode 100644
index 00000000..d40a5b5c
--- /dev/null
+++ b/examples/all-components-preview/fixtures/card.svg
@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="540" height="960" viewBox="0 0 540 960">
+ <rect width="540" height="960" rx="48" fill="#10131a"/>
+ <rect x="36" y="36" width="468" height="888" rx="32" fill="#edf2ff"/>
+ <circle cx="270" cy="330" r="132" fill="#725cff"/>
+ <path d="M206 330h128M270 266v128" stroke="#fff" stroke-width="28" stroke-linecap="round"/>
+ <rect x="96" y="540" width="348" height="36" rx="18" fill="#10131a"/>
+ <rect x="136" y="608" width="268" height="24" rx="12" fill="#697386"/>
+ <rect x="166" y="660" width="208" height="24" rx="12" fill="#9aa4b5"/>
+</svg>
diff --git a/examples/all-components-preview/fixtures/icon.svg b/examples/all-components-preview/fixtures/icon.svg
new file mode 100644
index 00000000..e6498bed
--- /dev/null
+++ b/examples/all-components-preview/fixtures/icon.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="192" height="192" viewBox="0 0 192 192">
+ <rect width="192" height="192" rx="42" fill="#725cff"/>
+ <circle cx="96" cy="96" r="52" fill="none" stroke="#fff" stroke-width="16"/>
+ <circle cx="96" cy="96" r="13" fill="#fff"/>
+</svg>
diff --git a/examples/all-components-preview/main.svml b/examples/all-components-preview/main.svml
index 08e929a6..407d348b 100644
--- a/examples/all-components-preview/main.svml
+++ b/examples/all-components-preview/main.svml
@@ -63,11 +63,11 @@
</seedance:ReferenceVideo>
<!-- Pictures on disk, so the Media Track and the board have real material. -->
- <media:Image id="card-shot" src="./assets/card.webp"/>
- <media:Image id="icon-spatial" src="./assets/icon-1.webp"/>
- <media:Image id="icon-type" src="./assets/icon-2.webp"/>
- <media:Image id="icon-ranking" src="./assets/icon-3.webp"/>
- <media:Image id="icon-caption" src="./assets/icon-4.webp"/>
+ <media:Image id="card-shot" src="./fixtures/card.svg" media-type="image/svg+xml"/>
+ <media:Image id="icon-spatial" src="./fixtures/icon.svg" media-type="image/svg+xml"/>
+ <media:Image id="icon-type" src="./fixtures/icon.svg" media-type="image/svg+xml"/>
+ <media:Image id="icon-ranking" src="./fixtures/icon.svg" media-type="image/svg+xml"/>
+ <media:Image id="icon-caption" src="./fixtures/icon.svg" media-type="image/svg+xml"/>
<space:Extent id="portrait" width="540" height="960"/>
<space:Extent id="square" width="192" height="192"/>
diff --git a/examples/all-components-preview/svml.packages.lock b/examples/all-components-preview/svml.packages.lock
index ef46b14f..b2b49e07 100644
--- a/examples/all-components-preview/svml.packages.lock
+++ b/examples/all-components-preview/svml.packages.lock
@@ -6,6 +6,7 @@
"@narratage/caption-fine",
"@narratage/caption-gemini",
"@narratage/composition",
+ "@narratage/deck-track",
"@narratage/film",
"@narratage/fonts-open",
"@narratage/generation",
@@ -619,6 +620,11 @@
"version": "0.0.0-dev",
"digest": "sha256:1262fed3211025ac608b60c4f7f47c9d493473cb05307ade3671ebafb79f5fe0"
},
+ {
+ "name": "@narratage/deck-track",
+ "version": "0.0.0-dev",
+ "digest": "sha256:e3b3be48960c16775ce0c86aac74c183ede8df5c9881c3e890e0f3f981c7e979"
+ },
{
"name": "@narratage/elaborator",
"version": "0.0.0-dev",
@@ -881,6 +887,20 @@
"facetsDigest": "sha256:05c22bda8c301365c1cfff2c0afa80067f3d2a0fba167a57ebf923af720a5c34",
"closureDigest": "sha256:8d42e7b295199f7775430131f7df5f3753474a44ff579ede2b8b36ae5a653e19"
},
+ {
+ "package": {
+ "name": "@narratage/deck-track",
+ "version": "0.0.0-dev"
+ },
+ "offers": [
+ {
+ "abi": "svml.module@1",
+ "name": "@narratage/deck-track@1"
+ }
+ ],
+ "facetsDigest": "sha256:a969929d929b22148363dc0dd12bc60d2e61f6e186d146554f1bcf51f55f7845",
+ "closureDigest": "sha256:0f7019ec7bf0e4d20f8c22c8c7d75423285069c54c19c44b968bbb38c8735c46"
+ },
{
"package": {
"name": "@narratage/film",
@@ -1328,5 +1348,5 @@
"closureDigest": "sha256:57cd991e800c5c55bcbb38931b6b81a67fe32cb532f9832784d219126f11fea8"
}
],
- "digest": "sha256:9842bc525ac90b2871aef022019ce7bf603900fa7658f5c79cf2d94f75f07746"
+ "digest": "sha256:be4bfc34df7f94b0bcd73ff8ae5aa6ffee4c80a789cd151595819d3bb9738345"
}
diff --git a/examples/all-components-preview/svml.runtime-packages.lock b/examples/all-components-preview/svml.runtime-packages.lock
index 23b91abb..4f15e02e 100644
--- a/examples/all-components-preview/svml.runtime-packages.lock
+++ b/examples/all-components-preview/svml.runtime-packages.lock
@@ -85,7 +85,7 @@
{
"name": "@narratage/driver-node",
"version": "0.0.0-dev",
- "digest": "sha256:2f8cc8620e90e16f69fc97fd6c641d84b2d08031f0f9c0e82e513b7fd6526aed"
+ "digest": "sha256:22cd089084eb82ca73f08d8e768a480327106f705dffd14b26381d36ea1e08cf"
},
{
"name": "@narratage/elaborator",
@@ -95,7 +95,7 @@
{
"name": "@narratage/endpoint-kit",
"version": "0.0.0-dev",
- "digest": "sha256:362d99c7ec0bd92d2350e455061ee835f1fef7281c8461ac210266e0433bdd72"
+ "digest": "sha256:89eeade4f411bc5c1095647a07502b3912efff590099fd00b998901a755e59c4"
},
{
"name": "@narratage/generation",
@@ -115,7 +115,7 @@
{
"name": "@narratage/local",
"version": "0.0.0-dev",
- "digest": "sha256:327eeebd78d3fc40b5b3ab498206b6f162df3871dc7a7c935de5182a5e57a107"
+ "digest": "sha256:53bfb88dfb3cb16a1747f7dfa9d92864fd5385c45584491577cf2f714d2d4c27"
},
{
"name": "@narratage/markup",
@@ -170,7 +170,7 @@
{
"name": "@narratage/provider-kie",
"version": "0.0.0-dev",
- "digest": "sha256:fd20bf5ea9611ff5f5b624871953b0cc39c02441d34ae314bcca0bf8950afbe7"
+ "digest": "sha256:c67139c64f5b841d73d245d190ac8134591d58e363e13a26d9370040f79d1eed"
},
{
"name": "@narratage/provider-media-local",
@@ -200,7 +200,7 @@
{
"name": "@narratage/runtime",
"version": "0.0.0-dev",
- "digest": "sha256:9e8625deb9d5f75efc404f6854708cbf777b982073ed49328febc8736b74a4de"
+ "digest": "sha256:7fed643f688774621b28eb846d68bc4e70ca98a0b04a5d0cc3a521152e50a5c6"
},
{
"name": "@narratage/semantic-map",
@@ -235,7 +235,7 @@
{
"name": "@narratage/store-sqlite",
"version": "0.0.0-dev",
- "digest": "sha256:66d118fc1f81b0fa02403ccce0e3d652feb9e6065b5fed93783e9853dff090f8"
+ "digest": "sha256:a277e24e32632a113b4b4713d3d3bce9eaef289ccc30a5f889c6fef935cb228a"
},
{
"name": "@narratage/svs",
@@ -495,7 +495,7 @@
{
"name": "esbuild",
"version": "0.25.12",
- "digest": "sha256:58ef98602a2a5a155d726d179960fe0db6963873d4ce384214c6356f99af465d"
+ "digest": "sha256:be6c7e2b09ea76a30532597e0171955e4588e7d4b984cb451f48f6cd3792240c"
},
{
"name": "escalade",
@@ -921,7 +921,7 @@
}
],
"facetsDigest": "sha256:89812ac838e22ffcec73619ddb033f6f9150c916e0a52693ec920cb9f41f13ff",
- "closureDigest": "sha256:2449713b84436330832c5288e3c57a76f6324641e28e2c00d811d80d040bc7e1"
+ "closureDigest": "sha256:7a9bdee0c11fb6412e9a7ce176a3af25ff0fb0b2c40cfbd46f223e6b00cb8003"
},
{
"package": {
@@ -935,7 +935,7 @@
}
],
"facetsDigest": "sha256:b2a771b23ea9dcdada76501804c717cc4509579244acbb09babc0807cb26401a",
- "closureDigest": "sha256:3d75084d4f3ca34a2ed62fecfc062f525789cea3b661280785c3664ea6fc8b48"
+ "closureDigest": "sha256:24df31243ffc21fe8429a5c3f2584de75cf3189727a7c27e773bd81ca9e0af30"
},
{
"package": {
@@ -949,7 +949,7 @@
}
],
"facetsDigest": "sha256:bacc2fe27612f029aeef34236fd5fa687259e08c980c310adc8118be2cceeaba",
- "closureDigest": "sha256:995fa51ec3356b388006d89dc93268255976196dfa693875acb884f888637adc"
+ "closureDigest": "sha256:5019f5018c2a8b746382a8ba838c57855af0bbf155e82c2a3b6ac87aa37f4390"
},
{
"package": {
@@ -963,7 +963,7 @@
}
],
"facetsDigest": "sha256:485fc29d1efcdaeb4e395980975b35090ea6aef0f78d02108d3bd9b3f11aeb91",
- "closureDigest": "sha256:db9863c925ba36f4772a15bf785afd1a56ec3811d6780e9930b9b1d0b7140816"
+ "closureDigest": "sha256:ccd1e3307e9ebffceb5e0cf98e03868b9e2484b364d16f8f19eefbe234d36105"
},
{
"package": {
@@ -977,7 +977,7 @@
}
],
"facetsDigest": "sha256:e08dde3e4d38b167dca29cdc54eb2bb5e9ebc294e0e42b371099d53d6c44b402",
- "closureDigest": "sha256:6c66fe2c9303b9a0c239ad2c482b0479682d46d7512c102782c7399425079020"
+ "closureDigest": "sha256:cfadfcd967b2a7b5d51c6852d1f1045167734609dbcdd05a83de8eeff34f2f6d"
},
{
"package": {
@@ -991,7 +991,7 @@
}
],
"facetsDigest": "sha256:110648301d69b5b49ea553d285a27626f6fb74ebc74ee67175f688f914d7d74b",
- "closureDigest": "sha256:e6badc196393ed5b9fa8c897c9b39e57a160c6ee350b3f8c654b61dee2c3c730"
+ "closureDigest": "sha256:c6105b8f3a5583f35e48ba3e9882f6a4a76adfc9f19a31877c3c6c7f8957bbc8"
},
{
"package": {
@@ -1005,7 +1005,7 @@
}
],
"facetsDigest": "sha256:998de772acb283828fee16310e77922bf43597bca1efa768e8398166a90af27d",
- "closureDigest": "sha256:0cb531d106ed7b47abcf04eb8c68ee19e90e37d765b14ccfe3f3b87090b865a5"
+ "closureDigest": "sha256:c59d8d31a59a5f26b9a064789e16e6db9505d26e170eb21350ee3104922a737d"
},
{
"package": {
@@ -1019,7 +1019,7 @@
}
],
"facetsDigest": "sha256:e7d4f1e2fd56f2bcb5dbc36e1faae48d2680bb839aed4a43eb0cb23207ffbe1d",
- "closureDigest": "sha256:1a9c745c15014c5840993d433a807955f467ae088e2bd7ad2151b2b4ff268779"
+ "closureDigest": "sha256:75c92b5ae14e4672ceba48b91376363f6648574f7d3655329deae60ba9c20807"
},
{
"package": {
@@ -1033,8 +1033,8 @@
}
],
"facetsDigest": "sha256:eb9df1ee7597620bc2e80c168971e020f77cd0880608957ca3048cac7c559c28",
- "closureDigest": "sha256:45b1993d829b4be41c40379061bb063cdc41492337390b123a28f5f3238a948d"
+ "closureDigest": "sha256:e7ab56c71e2fc2b11fccdfadc2c95fb0929e6a3bd4af1bf28577bff4758ea73c"
}
],
- "digest": "sha256:8c972b5fd9b252ed41394bcaf2dcb5797fe8716093a5cec2bf3cb91476f7fba7"
+ "digest": "sha256:6984ff6c3e2d79950e3fae3f486718ebad0f4fab8376e4322e1bc2c90b5039e6"
}
diff --git a/examples/talking-film-live/README.md b/examples/talking-film-live/README.md
index 1ca57bdd..a9771ea6 100644
--- a/examples/talking-film-live/README.md
+++ b/examples/talking-film-live/README.md
@@ -38,24 +38,21 @@ Artifacts, environment credentials, KIE, local media, local WhisperX, Vertex and
adapters; adding another implementation does not change the CLI.
```bash
-node --run narratage -- runtime up examples/talking-film-live/svml.runtime.json
+cd examples/talking-film-live
+../../narratage runtime use svml.runtime.json
+../../narratage runtime up
-node --run narratage -- build examples/talking-film-live/build.svrun \
- --runtime examples/talking-film-live/svml.runtime.json \
- --build-id talking-film-live \
- --follow
+../../narratage build build.svrun --follow
-node --run narratage -- inspect talking-film-live \
- --runtime examples/talking-film-live/svml.runtime.json
+../../narratage inspect <build-id>
-node --run narratage -- get talking-film-live \
- --runtime examples/talking-film-live/svml.runtime.json \
+../../narratage get <build-id> \
--name final.video \
- --to examples/talking-film-live/output/final.mp4
+ --to output/final.mp4
```
-`build` is a durable submission. `--follow` only observes the detached Worker; closing this terminal
-does not cancel the Build.
+`build` prints the fresh automatic Build id assigned to this durable submission. `--follow` only
+observes the detached Worker; closing this terminal does not cancel the Build.
`build.svrun` owns the Targets and any explicit Candidate selections. `svml.runtime.json` owns Provider instances,
credentials and concurrency. The Build archives all accepted intermediate Records and referenced
diff --git a/examples/talking-film-live/svml.runtime-packages.lock b/examples/talking-film-live/svml.runtime-packages.lock
index 6e821693..4f15e02e 100644
--- a/examples/talking-film-live/svml.runtime-packages.lock
+++ b/examples/talking-film-live/svml.runtime-packages.lock
@@ -85,7 +85,7 @@
{
"name": "@narratage/driver-node",
"version": "0.0.0-dev",
- "digest": "sha256:2f8cc8620e90e16f69fc97fd6c641d84b2d08031f0f9c0e82e513b7fd6526aed"
+ "digest": "sha256:22cd089084eb82ca73f08d8e768a480327106f705dffd14b26381d36ea1e08cf"
},
{
"name": "@narratage/elaborator",
@@ -95,7 +95,7 @@
{
"name": "@narratage/endpoint-kit",
"version": "0.0.0-dev",
- "digest": "sha256:362d99c7ec0bd92d2350e455061ee835f1fef7281c8461ac210266e0433bdd72"
+ "digest": "sha256:89eeade4f411bc5c1095647a07502b3912efff590099fd00b998901a755e59c4"
},
{
"name": "@narratage/generation",
@@ -115,7 +115,7 @@
{
"name": "@narratage/local",
"version": "0.0.0-dev",
- "digest": "sha256:327eeebd78d3fc40b5b3ab498206b6f162df3871dc7a7c935de5182a5e57a107"
+ "digest": "sha256:53bfb88dfb3cb16a1747f7dfa9d92864fd5385c45584491577cf2f714d2d4c27"
},
{
"name": "@narratage/markup",
@@ -170,7 +170,7 @@
{
"name": "@narratage/provider-kie",
"version": "0.0.0-dev",
- "digest": "sha256:fd20bf5ea9611ff5f5b624871953b0cc39c02441d34ae314bcca0bf8950afbe7"
+ "digest": "sha256:c67139c64f5b841d73d245d190ac8134591d58e363e13a26d9370040f79d1eed"
},
{
"name": "@narratage/provider-media-local",
@@ -200,7 +200,7 @@
{
"name": "@narratage/runtime",
"version": "0.0.0-dev",
- "digest": "sha256:9e8625deb9d5f75efc404f6854708cbf777b982073ed49328febc8736b74a4de"
+ "digest": "sha256:7fed643f688774621b28eb846d68bc4e70ca98a0b04a5d0cc3a521152e50a5c6"
},
{
"name": "@narratage/semantic-map",
@@ -235,7 +235,7 @@
{
"name": "@narratage/store-sqlite",
"version": "0.0.0-dev",
- "digest": "sha256:66d118fc1f81b0fa02403ccce0e3d652feb9e6065b5fed93783e9853dff090f8"
+ "digest": "sha256:a277e24e32632a113b4b4713d3d3bce9eaef289ccc30a5f889c6fef935cb228a"
},
{
"name": "@narratage/svs",
@@ -921,7 +921,7 @@
}
],
"facetsDigest": "sha256:89812ac838e22ffcec73619ddb033f6f9150c916e0a52693ec920cb9f41f13ff",
- "closureDigest": "sha256:2449713b84436330832c5288e3c57a76f6324641e28e2c00d811d80d040bc7e1"
+ "closureDigest": "sha256:7a9bdee0c11fb6412e9a7ce176a3af25ff0fb0b2c40cfbd46f223e6b00cb8003"
},
{
"package": {
@@ -935,7 +935,7 @@
}
],
"facetsDigest": "sha256:b2a771b23ea9dcdada76501804c717cc4509579244acbb09babc0807cb26401a",
- "closureDigest": "sha256:3d75084d4f3ca34a2ed62fecfc062f525789cea3b661280785c3664ea6fc8b48"
+ "closureDigest": "sha256:24df31243ffc21fe8429a5c3f2584de75cf3189727a7c27e773bd81ca9e0af30"
},
{
"package": {
@@ -949,7 +949,7 @@
}
],
"facetsDigest": "sha256:bacc2fe27612f029aeef34236fd5fa687259e08c980c310adc8118be2cceeaba",
- "closureDigest": "sha256:995fa51ec3356b388006d89dc93268255976196dfa693875acb884f888637adc"
+ "closureDigest": "sha256:5019f5018c2a8b746382a8ba838c57855af0bbf155e82c2a3b6ac87aa37f4390"
},
{
"package": {
@@ -963,7 +963,7 @@
}
],
"facetsDigest": "sha256:485fc29d1efcdaeb4e395980975b35090ea6aef0f78d02108d3bd9b3f11aeb91",
- "closureDigest": "sha256:db9863c925ba36f4772a15bf785afd1a56ec3811d6780e9930b9b1d0b7140816"
+ "closureDigest": "sha256:ccd1e3307e9ebffceb5e0cf98e03868b9e2484b364d16f8f19eefbe234d36105"
},
{
"package": {
@@ -977,7 +977,7 @@
}
],
"facetsDigest": "sha256:e08dde3e4d38b167dca29cdc54eb2bb5e9ebc294e0e42b371099d53d6c44b402",
- "closureDigest": "sha256:971572ad4620ef234572dc565f65c3ad9ad237964b635a9f7050b50b0f8831b7"
+ "closureDigest": "sha256:cfadfcd967b2a7b5d51c6852d1f1045167734609dbcdd05a83de8eeff34f2f6d"
},
{
"package": {
@@ -991,7 +991,7 @@
}
],
"facetsDigest": "sha256:110648301d69b5b49ea553d285a27626f6fb74ebc74ee67175f688f914d7d74b",
- "closureDigest": "sha256:e6badc196393ed5b9fa8c897c9b39e57a160c6ee350b3f8c654b61dee2c3c730"
+ "closureDigest": "sha256:c6105b8f3a5583f35e48ba3e9882f6a4a76adfc9f19a31877c3c6c7f8957bbc8"
},
{
"package": {
@@ -1005,7 +1005,7 @@
}
],
"facetsDigest": "sha256:998de772acb283828fee16310e77922bf43597bca1efa768e8398166a90af27d",
- "closureDigest": "sha256:0cb531d106ed7b47abcf04eb8c68ee19e90e37d765b14ccfe3f3b87090b865a5"
+ "closureDigest": "sha256:c59d8d31a59a5f26b9a064789e16e6db9505d26e170eb21350ee3104922a737d"
},
{
"package": {
@@ -1019,7 +1019,7 @@
}
],
"facetsDigest": "sha256:e7d4f1e2fd56f2bcb5dbc36e1faae48d2680bb839aed4a43eb0cb23207ffbe1d",
- "closureDigest": "sha256:1a9c745c15014c5840993d433a807955f467ae088e2bd7ad2151b2b4ff268779"
+ "closureDigest": "sha256:75c92b5ae14e4672ceba48b91376363f6648574f7d3655329deae60ba9c20807"
},
{
"package": {
@@ -1033,8 +1033,8 @@
}
],
"facetsDigest": "sha256:eb9df1ee7597620bc2e80c168971e020f77cd0880608957ca3048cac7c559c28",
- "closureDigest": "sha256:45b1993d829b4be41c40379061bb063cdc41492337390b123a28f5f3238a948d"
+ "closureDigest": "sha256:e7ab56c71e2fc2b11fccdfadc2c95fb0929e6a3bd4af1bf28577bff4758ea73c"
}
],
- "digest": "sha256:4227546a3ea1b78111b0223943fa8e0c3fcf4b7e393fb98bc5541145a739c4a6"
+ "digest": "sha256:6984ff6c3e2d79950e3fae3f486718ebad0f4fab8376e4322e1bc2c90b5039e6"
}
diff --git a/examples/talking-head-aroll/README.md b/examples/talking-head-aroll/README.md
index 4b89f5e4..49b1b20e 100644
--- a/examples/talking-head-aroll/README.md
+++ b/examples/talking-head-aroll/README.md
@@ -26,43 +26,34 @@ take at Seedance's 15-second request limit.
Synchronize both package locks from the Run Source and Runtime Profile:
```sh
-node --run narratage -- packages sync examples/talking-head-aroll/build.svrun \
- --runtime examples/talking-head-aroll/svml.runtime.json \
- --root .
+cd examples/talking-head-aroll
+../../narratage runtime use svml.runtime.json
+../../narratage packages sync build.svrun
```
Inspect the authored graph—including the visible `*.prompt` Text output and `*.program`—without a paid call:
```sh
-node --run narratage -- check examples/talking-head-aroll/main.svml \
- --runtime examples/talking-head-aroll/svml.runtime.json \
- --root .
+../../narratage check main.svml
```
Inspect the exact paid plan before submitting it:
```sh
-node --run narratage -- plan examples/talking-head-aroll/build.svrun \
- --runtime examples/talking-head-aroll/svml.runtime.json \
- --root .
+../../narratage plan build.svrun
```
Build the complete film after preparing the managed local WhisperX service and exposing `KIE_API_KEY`,
`GOOGLE_CLOUD_PROJECT` and `GOOGLE_APPLICATION_CREDENTIALS_JSON`:
```sh
-node --run narratage -- runtime up examples/talking-head-aroll/svml.runtime.json
+../../narratage runtime up
-node --run narratage -- build examples/talking-head-aroll/build.svrun \
- --runtime examples/talking-head-aroll/svml.runtime.json \
- --root . \
- --build-id talking-head-film-001 \
- --follow
+../../narratage build build.svrun --follow
-node --run narratage -- get talking-head-film-001 \
- --runtime examples/talking-head-aroll/svml.runtime.json \
+../../narratage get <build-id> \
--name final.video \
- --to examples/talking-head-aroll/output/final.mp4
+ --to output/final.mp4
```
`build` returns after durable submission unless `--follow` is present. Even with `--follow`, the
@@ -72,16 +63,13 @@ Run the same downstream film from the four archived generated shots without anot
submission:
```sh
-node --run narratage -- build examples/talking-head-aroll/reuse-generated.svrun \
- --runtime examples/talking-head-aroll/svml.runtime.json \
- --root . \
- --build-id talking-head-film-reuse-001 \
- --follow
+../../narratage build reuse-generated.svrun --follow
```
-`reuse-generated.svrun` names four shot aliases from `talking-head-film-001`, exposes each
-verified Record as a zero-input Candidate and explicitly satisfies the corresponding
-logical output as `substitute`. Reverse demand therefore removes all four Seedance branches while
+Before this second command, replace `REPLACE_WITH_BUILD_ID` in `reuse-generated.svrun` with the
+automatic id printed by the first Build. The Run exposes four shot aliases from that exact Build,
+each as a zero-input Candidate, and explicitly satisfies the corresponding logical output. Reverse
+demand therefore removes all four Seedance branches while
keeping media normalization, WhisperX, Gemini planning, Film and rendering reachable. This is a new
Build, not a continuation or automatic cache hit.
diff --git a/examples/talking-head-aroll/kits/speaker-v1.svs b/examples/talking-head-aroll/kits/speaker-v1.svs
new file mode 100644
index 00000000..c06ca8b1
--- /dev/null
+++ b/examples/talking-head-aroll/kits/speaker-v1.svs
@@ -0,0 +1,136 @@
+<?svml using="@narratage/text/svs@1"?>
+
+<sheet version="1" id="speaker-v1">
+ text-template.speaker-v1 {
+ separator: paragraph;
+ default-composition-stability: soft-locked;
+ default-camera-motion: none;
+ default-edit-rhythm: continuous-take;
+ default-performance: natural-explainer;
+ default-gesture: natural;
+ }
+
+ text-template.speaker-v1.block.base {
+ kind: fixed;
+ order: 10;
+ text: "Create a realistic vertical phone-shot talking-head video. @image1 is the visible speaker and scene reference. Preserve the person's identity, face, outfit, setting, lighting, lens feel, and broad composition. @audio1 is the speaker's voice-timbre reference.";
+ }
+
+ text-template.speaker-v1.block.script-contract {
+ kind: fixed;
+ order: 20;
+ text: "Deliver the supplied script exactly in order with clear lip-sync. The visible person speaks every line. Do not rewrite, summarize, add, remove, or reorder words.";
+ }
+
+ text-template.speaker-v1.block.composition-stability {
+ kind: axis;
+ order: 30;
+ parameter: composition-stability;
+ }
+
+ text-template.speaker-v1.choice.composition-stability.flexible-ugc {
+ text: "COMPOSITION: preserve the reference person and setup while allowing normal lively creator-video framing variation.";
+ }
+
+ text-template.speaker-v1.choice.composition-stability.soft-locked {
+ text: "COMPOSITION: keep the speaker in the same general region and preserve the reference composition, allowing natural posture changes and tiny crop or scale breathing.";
+ }
+
+ text-template.speaker-v1.choice.composition-stability.strict-locked {
+ text: "COMPOSITION: preserve subject placement, perspective, left-right orientation, background relationship, and framing envelope throughout the shot.";
+ }
+
+ text-template.speaker-v1.block.camera-motion {
+ kind: axis;
+ order: 40;
+ parameter: camera-motion;
+ }
+
+ text-template.speaker-v1.choice.camera-motion.none {
+ text: "CAMERA: hold a steady fixed framing.";
+ }
+
+ text-template.speaker-v1.choice.camera-motion.subtle-punch-in-return {
+ text: "CAMERA: use one subtle push-in on the most important phrase, then return smoothly to the original framing.";
+ }
+
+ text-template.speaker-v1.block.edit-rhythm {
+ kind: axis;
+ order: 50;
+ parameter: edit-rhythm;
+ }
+
+ text-template.speaker-v1.choice.edit-rhythm.continuous-take {
+ text: "EDIT RHYTHM: one continuous creator explanation with natural breath timing.";
+ }
+
+ text-template.speaker-v1.choice.edit-rhythm.pause-trim-jump-cuts {
+ text: "EDIT RHYTHM: polished pause-trim jump cuts at phrase boundaries while keeping the framing coherent.";
+ }
+
+ text-template.speaker-v1.block.performance {
+ kind: axis;
+ order: 60;
+ parameter: performance;
+ }
+
+ text-template.speaker-v1.choice.performance.natural-explainer {
+ text: "PERFORMANCE: natural explainer energy with clear eye focus, expressive eyebrows, small nods, and a friendly conversational rhythm.";
+ }
+
+ text-template.speaker-v1.choice.performance.high-energy-ugc {
+ text: "PERFORMANCE: vivid high-energy short-form delivery with expressive face changes on key words.";
+ }
+
+ text-template.speaker-v1.choice.performance.calm-authority {
+ text: "PERFORMANCE: composed, confident, precise, and trustworthy, with deliberate emphasis.";
+ }
+
+ text-template.speaker-v1.choice.performance.reactive-playful {
+ text: "PERFORMANCE: playful and reactive, with amused looks, quick smiles, skeptical eyebrows, and lively timing.";
+ }
+
+ text-template.speaker-v1.block.gesture {
+ kind: axis;
+ order: 70;
+ parameter: gesture;
+ }
+
+ text-template.speaker-v1.choice.gesture.restrained {
+ text: "GESTURE: restrained body language; let face, eyes, and voice carry the meaning.";
+ }
+
+ text-template.speaker-v1.choice.gesture.compact {
+ text: "GESTURE: compact explanatory hand movement close to the torso and inside the frame.";
+ }
+
+ text-template.speaker-v1.choice.gesture.natural {
+ text: "GESTURE: natural creator gestures such as open palms, small pointing beats, nods, and posture shifts where the script calls for them.";
+ }
+
+ text-template.speaker-v1.choice.gesture.expressive {
+ text: "GESTURE: richer hand, shoulder, and posture changes that support the spoken idea while remaining physically coherent.";
+ }
+
+ text-template.speaker-v1.block.hygiene {
+ kind: fixed;
+ order: 80;
+ text: "Keep face, hands, skin texture, lighting, and motion photoreal and stable. Add no subtitles, captions, labels, logos, UI text, floating words, or other readable on-screen text.";
+ }
+
+ text-template.speaker-v1.block.dialogue {
+ kind: slot;
+ order: 90;
+ slot: dialogue;
+ optional: false;
+ label: "SCRIPT TO DELIVER:";
+ }
+
+ text-template.speaker-v1.block.action {
+ kind: slot;
+ order: 100;
+ slot: action;
+ optional: true;
+ label: "ACTION DIRECTION:";
+ }
+</sheet>
diff --git a/examples/talking-head-aroll/main.svml b/examples/talking-head-aroll/main.svml
index f3465ca4..68fbd589 100644
--- a/examples/talking-head-aroll/main.svml
+++ b/examples/talking-head-aroll/main.svml
@@ -16,7 +16,7 @@
<import as="film" from="@narratage/film@1"/>
<import as="render" from="@narratage/render-hyperframes@1"/>
<import as="studio" source="./studio.svs"/>
- <import as="speaker-kit" source="../../packages/seedance-kits/kits/speaker-v1.svs"/>
+ <import as="speaker-kit" source="./kits/speaker-v1.svs"/>
<script id="story">
<hook>
diff --git a/examples/talking-head-aroll/reuse-generated.svrun b/examples/talking-head-aroll/reuse-generated.svrun
index 5e238d21..6db314da 100644
--- a/examples/talking-head-aroll/reuse-generated.svrun
+++ b/examples/talking-head-aroll/reuse-generated.svrun
@@ -4,10 +4,10 @@
<target output="final.video"/>
- <build-record id="hook-video" build="talking-head-film-001" output="hook-take.video"/>
- <build-record id="meeting-video" build="talking-head-film-001" output="meeting-take.video"/>
- <build-record id="evidence-video" build="talking-head-film-001" output="evidence-take.video"/>
- <build-record id="payoff-video" build="talking-head-film-001" output="payoff-take.video"/>
+ <build-record id="hook-video" build="REPLACE_WITH_BUILD_ID" output="hook-take.video"/>
+ <build-record id="meeting-video" build="REPLACE_WITH_BUILD_ID" output="meeting-take.video"/>
+ <build-record id="evidence-video" build="REPLACE_WITH_BUILD_ID" output="evidence-take.video"/>
+ <build-record id="payoff-video" build="REPLACE_WITH_BUILD_ID" output="payoff-take.video"/>
<satisfy output="hook-take.video" candidate="hook-video"/>
<satisfy output="meeting-take.video" candidate="meeting-video"/>
diff --git a/examples/talking-head-aroll/svml.runtime-packages.lock b/examples/talking-head-aroll/svml.runtime-packages.lock
index 6e821693..4f15e02e 100644
--- a/examples/talking-head-aroll/svml.runtime-packages.lock
+++ b/examples/talking-head-aroll/svml.runtime-packages.lock
@@ -85,7 +85,7 @@
{
"name": "@narratage/driver-node",
"version": "0.0.0-dev",
- "digest": "sha256:2f8cc8620e90e16f69fc97fd6c641d84b2d08031f0f9c0e82e513b7fd6526aed"
+ "digest": "sha256:22cd089084eb82ca73f08d8e768a480327106f705dffd14b26381d36ea1e08cf"
},
{
"name": "@narratage/elaborator",
@@ -95,7 +95,7 @@
{
"name": "@narratage/endpoint-kit",
"version": "0.0.0-dev",
- "digest": "sha256:362d99c7ec0bd92d2350e455061ee835f1fef7281c8461ac210266e0433bdd72"
+ "digest": "sha256:89eeade4f411bc5c1095647a07502b3912efff590099fd00b998901a755e59c4"
},
{
"name": "@narratage/generation",
@@ -115,7 +115,7 @@
{
"name": "@narratage/local",
"version": "0.0.0-dev",
- "digest": "sha256:327eeebd78d3fc40b5b3ab498206b6f162df3871dc7a7c935de5182a5e57a107"
+ "digest": "sha256:53bfb88dfb3cb16a1747f7dfa9d92864fd5385c45584491577cf2f714d2d4c27"
},
{
"name": "@narratage/markup",
@@ -170,7 +170,7 @@
{
"name": "@narratage/provider-kie",
"version": "0.0.0-dev",
- "digest": "sha256:fd20bf5ea9611ff5f5b624871953b0cc39c02441d34ae314bcca0bf8950afbe7"
+ "digest": "sha256:c67139c64f5b841d73d245d190ac8134591d58e363e13a26d9370040f79d1eed"
},
{
"name": "@narratage/provider-media-local",
@@ -200,7 +200,7 @@
{
"name": "@narratage/runtime",
"version": "0.0.0-dev",
- "digest": "sha256:9e8625deb9d5f75efc404f6854708cbf777b982073ed49328febc8736b74a4de"
+ "digest": "sha256:7fed643f688774621b28eb846d68bc4e70ca98a0b04a5d0cc3a521152e50a5c6"
},
{
"name": "@narratage/semantic-map",
@@ -235,7 +235,7 @@
{
"name": "@narratage/store-sqlite",
"version": "0.0.0-dev",
- "digest": "sha256:66d118fc1f81b0fa02403ccce0e3d652feb9e6065b5fed93783e9853dff090f8"
+ "digest": "sha256:a277e24e32632a113b4b4713d3d3bce9eaef289ccc30a5f889c6fef935cb228a"
},
{
"name": "@narratage/svs",
@@ -921,7 +921,7 @@
}
],
"facetsDigest": "sha256:89812ac838e22ffcec73619ddb033f6f9150c916e0a52693ec920cb9f41f13ff",
- "closureDigest": "sha256:2449713b84436330832c5288e3c57a76f6324641e28e2c00d811d80d040bc7e1"
+ "closureDigest": "sha256:7a9bdee0c11fb6412e9a7ce176a3af25ff0fb0b2c40cfbd46f223e6b00cb8003"
},
{
"package": {
@@ -935,7 +935,7 @@
}
],
"facetsDigest": "sha256:b2a771b23ea9dcdada76501804c717cc4509579244acbb09babc0807cb26401a",
- "closureDigest": "sha256:3d75084d4f3ca34a2ed62fecfc062f525789cea3b661280785c3664ea6fc8b48"
+ "closureDigest": "sha256:24df31243ffc21fe8429a5c3f2584de75cf3189727a7c27e773bd81ca9e0af30"
},
{
"package": {
@@ -949,7 +949,7 @@
}
],
"facetsDigest": "sha256:bacc2fe27612f029aeef34236fd5fa687259e08c980c310adc8118be2cceeaba",
- "closureDigest": "sha256:995fa51ec3356b388006d89dc93268255976196dfa693875acb884f888637adc"
+ "closureDigest": "sha256:5019f5018c2a8b746382a8ba838c57855af0bbf155e82c2a3b6ac87aa37f4390"
},
{
"package": {
@@ -963,7 +963,7 @@
}
],
"facetsDigest": "sha256:485fc29d1efcdaeb4e395980975b35090ea6aef0f78d02108d3bd9b3f11aeb91",
- "closureDigest": "sha256:db9863c925ba36f4772a15bf785afd1a56ec3811d6780e9930b9b1d0b7140816"
+ "closureDigest": "sha256:ccd1e3307e9ebffceb5e0cf98e03868b9e2484b364d16f8f19eefbe234d36105"
},
{
"package": {
@@ -977,7 +977,7 @@
}
],
"facetsDigest": "sha256:e08dde3e4d38b167dca29cdc54eb2bb5e9ebc294e0e42b371099d53d6c44b402",
- "closureDigest": "sha256:971572ad4620ef234572dc565f65c3ad9ad237964b635a9f7050b50b0f8831b7"
+ "closureDigest": "sha256:cfadfcd967b2a7b5d51c6852d1f1045167734609dbcdd05a83de8eeff34f2f6d"
},
{
"package": {
@@ -991,7 +991,7 @@
}
],
"facetsDigest": "sha256:110648301d69b5b49ea553d285a27626f6fb74ebc74ee67175f688f914d7d74b",
- "closureDigest": "sha256:e6badc196393ed5b9fa8c897c9b39e57a160c6ee350b3f8c654b61dee2c3c730"
+ "closureDigest": "sha256:c6105b8f3a5583f35e48ba3e9882f6a4a76adfc9f19a31877c3c6c7f8957bbc8"
},
{
"package": {
@@ -1005,7 +1005,7 @@
}
],
"facetsDigest": "sha256:998de772acb283828fee16310e77922bf43597bca1efa768e8398166a90af27d",
- "closureDigest": "sha256:0cb531d106ed7b47abcf04eb8c68ee19e90e37d765b14ccfe3f3b87090b865a5"
+ "closureDigest": "sha256:c59d8d31a59a5f26b9a064789e16e6db9505d26e170eb21350ee3104922a737d"
},
{
"package": {
@@ -1019,7 +1019,7 @@
}
],
"facetsDigest": "sha256:e7d4f1e2fd56f2bcb5dbc36e1faae48d2680bb839aed4a43eb0cb23207ffbe1d",
- "closureDigest": "sha256:1a9c745c15014c5840993d433a807955f467ae088e2bd7ad2151b2b4ff268779"
+ "closureDigest": "sha256:75c92b5ae14e4672ceba48b91376363f6648574f7d3655329deae60ba9c20807"
},
{
"package": {
@@ -1033,8 +1033,8 @@
}
],
"facetsDigest": "sha256:eb9df1ee7597620bc2e80c168971e020f77cd0880608957ca3048cac7c559c28",
- "closureDigest": "sha256:45b1993d829b4be41c40379061bb063cdc41492337390b123a28f5f3238a948d"
+ "closureDigest": "sha256:e7ab56c71e2fc2b11fccdfadc2c95fb0929e6a3bd4af1bf28577bff4758ea73c"
}
],
- "digest": "sha256:4227546a3ea1b78111b0223943fa8e0c3fcf4b7e393fb98bc5541145a739c4a6"
+ "digest": "sha256:6984ff6c3e2d79950e3fae3f486718ebad0f4fab8376e4322e1bc2c90b5039e6"
}
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index 77f326a8..ad3745bb 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -1,10 +1,10 @@
-import { dirname, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
import { readFile } from "node:fs/promises";
import type { NodeCompiledSourceClosure } from "@narratage/compiler-node";
-import { plannedNeeds, sameBuildCatalogDescriptor } from "@narratage/runtime";
+import { plannedNeeds } from "@narratage/runtime";
import type { BuildCatalogDescriptor, CapacityReservation, OperationProgress } from "@narratage/runtime";
-import { isDigest } from "@narratage/protocol";
import type { BuildState, CapabilityRef, TypeRef } from "@narratage/protocol";
import { parseSourceHeader } from "@narratage/source";
import {
@@ -52,6 +52,11 @@ import {
runtimeProcessStatus,
stopRuntimeProcess,
} from "./runtime-process.js";
+import {
+ clearRuntimeProfile,
+ findRuntimeProfile,
+ selectRuntimeProfile,
+} from "./runtime-selection.js";
type ParsedArgs = {
readonly command: string | undefined;
@@ -64,7 +69,6 @@ type ParsedArgs = {
/** Host directory whose node_modules contains the packages named by a package lock. */
readonly packageRoot: string | undefined;
readonly runtime: string | undefined;
- readonly buildId: string | undefined;
readonly follow: boolean;
readonly maxWaitMs: number | undefined;
readonly packageLock: string | undefined;
@@ -98,7 +102,7 @@ type ParsedArgs = {
function parseArgs(argv: readonly string[]): ParsedArgs {
const [command, ...tail] = argv;
- const scoped = command === "services" || command === "runtime" || command === "cancel" || command === "auth"
+ const scoped = command === "services" || command === "runtime" || command === "auth"
|| command === "packages";
const action = scoped ? tail[0] : undefined;
const positional = scoped ? tail.slice(1) : tail;
@@ -110,7 +114,6 @@ function parseArgs(argv: readonly string[]): ParsedArgs {
const assetRoots: string[] = [];
let packageRoot: string | undefined;
let runtime: string | undefined;
- let buildId: string | undefined;
let follow = false;
let maxWaitMs: number | undefined;
let packageLock: string | undefined;
@@ -281,13 +284,6 @@ function parseArgs(argv: readonly string[]): ParsedArgs {
index += 1;
continue;
}
- if (item === "--build-id") {
- const value = rest[index + 1];
- if (value === undefined || value.startsWith("--")) throw new Error("--build-id requires a stable identity");
- buildId = value;
- index += 1;
- continue;
- }
if (item === "--follow") {
follow = true;
continue;
@@ -355,7 +351,6 @@ function parseArgs(argv: readonly string[]): ParsedArgs {
assetRoots,
packageRoot,
runtime,
- buildId,
follow,
maxWaitMs,
packageLock,
@@ -425,8 +420,6 @@ function assertCommandOptions(args: ParsedArgs): void {
case "builds":
case "history":
case "inspect":
- case "operations":
- case "operation":
add("--runtime");
if (args.command === "history") add("--source");
break;
@@ -435,7 +428,7 @@ function assertCommandOptions(args: ParsedArgs): void {
add("--runtime", "--package-lock", "--package-root", "--root", "--asset-root");
break;
case "build":
- add("--runtime", "--package-lock", "--package-root", "--root", "--asset-root", "--build-id", "--follow",
+ add("--runtime", "--package-lock", "--package-root", "--root", "--asset-root", "--follow",
"--max-wait-ms", "--no-services");
break;
}
@@ -458,25 +451,24 @@ function usage(): string {
" narratage lock-packages <lock> --package name [...] [--package-root directory] # exact create/replace",
" narratage lock-packages <lock> (--add name [...] | --remove name [...]) [--package-root directory]",
" narratage lock-packages <lock> (--refresh | --verify) [--package-root directory]",
- " narratage packages sync <run-source> --runtime <runtime-profile> [--root workspace]",
- " narratage doctor <runtime-profile>",
- " narratage services up|down|status <runtime-profile> [--max-wait-ms milliseconds]",
- " narratage runtime up|status|logs|down <runtime-profile>",
- " narratage queue --runtime profile.json [--watch]",
- " narratage gc <runtime-profile> [--apply]",
+ " narratage packages sync <run-source> [--runtime <runtime-profile>] [--root workspace]",
+ " narratage doctor [<runtime-profile>]",
+ " narratage services up|down|status [<runtime-profile>] [--max-wait-ms milliseconds]",
+ " narratage runtime use <runtime-profile>",
+ " narratage runtime unset",
+ " narratage runtime up|status|logs|down [<runtime-profile>]",
+ " narratage queue [--runtime profile.json] [--watch]",
+ " narratage gc [<runtime-profile>] [--apply]",
" narratage check <self-described-source> [--runtime profile.json] [--package-lock file] [--root workspace] [--asset-root directory]",
" narratage plan <run-source> [--runtime profile.json] [--package-lock file] [--root workspace] [--asset-root directory]",
- " narratage build <run-source> --runtime profile.json [--root workspace] [--asset-root directory] [--follow] [--no-services]",
- " narratage status <build-id> --runtime profile.json",
- " narratage builds --runtime profile.json",
- " narratage history [source-output-name] --runtime profile.json [--source author.svml]",
- " narratage inspect <build-id> --runtime profile.json",
- " narratage get <build-id> --runtime profile.json [--name source-name|--record record-id|--output logical-output-id|--artifact digest] [--to path]",
- " narratage operations <build-id> --runtime profile.json",
- " narratage operation <operation-id> --runtime profile.json",
- " narratage cancel build <build-id> --runtime profile.json [--reason text]",
- " narratage cancel operation <operation-id> --runtime profile.json [--reason text]",
- " narratage auth status|login|logout <endpoint-instance> --runtime profile.json [--slot name] [--from secret-file]",
+ " narratage build <run-source> [--runtime profile.json] [--root workspace] [--asset-root directory] [--follow] [--no-services]",
+ " narratage status <build-id> [--runtime profile.json]",
+ " narratage builds [--runtime profile.json]",
+ " narratage history [source-output-name] [--runtime profile.json] [--source author.svml]",
+ " narratage inspect <build-id> [--runtime profile.json]",
+ " narratage get <build-id> [--runtime profile.json] [--name source-name|--record record-id|--output logical-output-id|--artifact digest] [--to path]",
+ " narratage cancel <build-id> [--runtime profile.json] [--reason text]",
+ " narratage auth status|login|logout <endpoint-instance> [--runtime profile.json] [--slot name] [--from secret-file]",
"",
"output:",
" --json --verbose --color auto|always|never --no-color --debug",
@@ -690,7 +682,9 @@ function externalServiceLine(service: CliExternalServiceReport): string {
const action = service.action === undefined ? "" : ` · ${service.action}`;
const detail = service.detail === undefined ? "" : ` · ${service.detail}`;
const instances = service.instances.length === 0 ? "" : ` · ${service.instances.join(", ")}`;
- return `${service.id}: ${service.state.state}${stateDetail}${action}${detail}${instances}`;
+ const pid = service.pid === undefined ? "" : ` · pid ${service.pid}`;
+ const log = service.logPath === undefined ? "" : ` · log ${service.logPath}`;
+ return `${service.id}: ${service.state.state}${stateDetail}${action}${detail}${instances}${pid}${log}`;
}
function inlineValuePreview(value: unknown, limit = 240): string {
@@ -834,7 +828,7 @@ export async function runCli(
writeCliHelp(io, topic);
return;
}
- const args = parseArgs(argv);
+ let args = parseArgs(argv);
const writeOperational = (
machine: unknown,
title: string,
@@ -881,16 +875,79 @@ export async function runCli(
}
return;
}
+ if (args.command === "runtime" && args.action === "use") {
+ if (args.runtime !== undefined) {
+ throw new Error("runtime use takes the Runtime Profile positionally, not through --runtime");
+ }
+ if (args.file === undefined) throw new Error("runtime use requires a Runtime Profile");
+ assertCommandOptions(args);
+ const profile = resolve(args.file);
+ const packageSelection = await distribution.resolveCompilationPackages?.(profile);
+ const selected = await selectRuntimeProfile(packageSelection?.root ?? dirname(profile), profile);
+ writeOperational({
+ format: "narratage.cli-runtime-selection@1",
+ profile: selected.profile,
+ root: selected.projectRoot,
+ selectionFile: selected.selectionFile,
+ authorPackageLock: packageSelection?.packageLock,
+ runtimePackageLock: packageSelection?.runtimePackageLock,
+ }, "Runtime selected", "success", [
+ ["Profile", selected.profile],
+ ["Project", selected.projectRoot],
+ ...(packageSelection?.packageLock === undefined
+ ? []
+ : [["Author lock", packageSelection.packageLock] as const]),
+ ...(packageSelection?.runtimePackageLock === undefined
+ ? []
+ : [["Runtime lock", packageSelection.runtimePackageLock] as const]),
+ ]);
+ return;
+ }
+ if (args.command === "runtime" && args.action === "unset") {
+ if (args.file !== undefined || args.runtime !== undefined) {
+ throw new Error("runtime unset does not take a Runtime Profile");
+ }
+ assertCommandOptions(args);
+ const cleared = await clearRuntimeProfile(process.cwd());
+ writeOperational({
+ format: "narratage.cli-runtime-selection@1",
+ selected: false,
+ removed: cleared !== undefined,
+ profile: cleared?.profile,
+ root: cleared?.projectRoot,
+ }, cleared === undefined ? "No Runtime was selected" : "Runtime selection removed",
+ cleared === undefined ? "info" : "success", cleared === undefined ? [] : [
+ ["Profile", cleared.profile], ["Project", cleared.projectRoot],
+ ]);
+ return;
+ }
+
+ const positionalRuntime = (args.command === "runtime" || args.command === "services"
+ || args.command === "doctor" || args.command === "gc") && args.file !== undefined;
+ const runtimeWasExplicit = args.runtime !== undefined || positionalRuntime;
+ let runtimeNeedsHint = runtimeWasExplicit;
+ if (args.runtime === undefined && !positionalRuntime) {
+ const sourceScoped = args.command === "check" || args.command === "plan" || args.command === "build"
+ || args.command === "packages";
+ const start = sourceScoped && args.file !== undefined ? dirname(resolve(args.file)) : process.cwd();
+ const selected = await findRuntimeProfile(start);
+ if (selected !== undefined) {
+ args = { ...args, runtime: selected.profile };
+ const cwdFromProject = relative(selected.projectRoot, resolve(process.cwd()));
+ runtimeNeedsHint = cwdFromProject === ".." || cwdFromProject.startsWith(`..${sep}`)
+ || isAbsolute(cwdFromProject);
+ }
+ }
const known = args.command === "lock-packages" || args.command === "packages" || args.command === "check" || args.command === "plan"
|| args.command === "build" || args.command === "status" || args.command === "builds"
|| args.command === "history"
|| args.command === "inspect" || args.command === "get" || args.command === "cancel"
|| args.command === "doctor" || args.command === "gc" || args.command === "services"
- || args.command === "runtime" || args.command === "queue" || args.command === "operations"
- || args.command === "operation";
+ || args.command === "runtime" || args.command === "queue";
const operational = known || args.command === "auth";
const fileOptional = args.command === "builds" || args.command === "history" || args.command === "queue"
- || ((args.command === "services" || args.command === "runtime") && args.runtime !== undefined);
+ || args.command === "services" || args.command === "runtime" || args.command === "doctor"
+ || args.command === "gc";
if (!operational || (!fileOptional && args.file === undefined)) {
throw new Error(usage());
}
@@ -1040,10 +1097,12 @@ export async function runCli(
}
if (args.command === "packages") {
if (args.action !== "sync") {
- throw new Error("packages takes one action: packages sync <run-source> --runtime <runtime-profile>");
+ throw new Error("packages takes one action: packages sync <run-source>");
}
if (args.runtime === undefined) {
- throw new Error("packages sync requires --runtime <runtime-profile>");
+ throw new Error(
+ "packages sync requires a Runtime; run narratage runtime use <profile> or pass --runtime <profile>",
+ );
}
const source = resolve(args.file!);
const profile = resolve(args.runtime);
@@ -1151,11 +1210,14 @@ export async function runCli(
return;
}
if (args.command === "doctor") {
- if (args.runtime !== undefined || args.packageLock !== undefined || args.packageRoot !== undefined
- || args.packages.length > 0 || args.apply) {
+ if (args.packageLock !== undefined || args.packageRoot !== undefined || args.packages.length > 0 || args.apply) {
throw new Error("doctor reads all deployment selection from the Runtime Profile itself");
}
- const profile = resolve(args.file!);
+ const profileInput = args.runtime ?? args.file;
+ if (profileInput === undefined) {
+ throw new Error("doctor requires a Runtime Profile; run narratage runtime use <profile> or provide it positionally");
+ }
+ const profile = resolve(profileInput);
const result = await distribution.doctorRuntimeConfig(profile);
const machine = {
format: "narratage.cli-doctor@1" as const,
@@ -1265,11 +1327,9 @@ export async function runCli(
}
if (args.action === "down") {
const worker = await stopRuntimeProcess(profile, args.maxWaitMs ?? 10_000);
- const external = await distribution.externalServices.down(profile);
- writeOperational({ ok: true, worker, services: external.services }, "Runtime is down", "success", [
+ writeOperational({ ok: true, worker }, "Runtime Worker is down", "success", [
["Worker", worker.state],
- ["External services", String(external.services.length)],
- ]);
+ ], ["External programs were left running. Stop them explicitly with narratage services down."]);
return;
}
// These are independent views over one Profile. Load them concurrently without inventing a
@@ -1322,11 +1382,14 @@ export async function runCli(
return;
}
if (args.command === "gc") {
- if (args.runtime !== undefined || args.packageLock !== undefined || args.packageRoot !== undefined
- || args.packages.length > 0) {
+ if (args.packageLock !== undefined || args.packageRoot !== undefined || args.packages.length > 0) {
throw new Error("gc reads all deployment selection from the Runtime Profile itself");
}
- const runtime = await loadRuntimeMaintenance(resolve(args.file!), distribution, !args.apply);
+ const profileInput = args.runtime ?? args.file;
+ if (profileInput === undefined) {
+ throw new Error("gc requires a Runtime Profile; run narratage runtime use <profile> or provide it positionally");
+ }
+ const runtime = await loadRuntimeMaintenance(resolve(profileInput), distribution, !args.apply);
try {
const report = await runtime.garbageCollectArtifacts({ apply: args.apply });
const machine = {
@@ -1350,7 +1413,9 @@ export async function runCli(
if (args.action !== "status" && args.action !== "login" && args.action !== "logout") {
throw new Error("auth takes status, login or logout");
}
- if (args.runtime === undefined) throw new Error("auth requires --runtime");
+ if (args.runtime === undefined) {
+ throw new Error("auth requires a Runtime; run narratage runtime use <profile> or pass --runtime <profile>");
+ }
if (args.from !== undefined && args.action !== "login") throw new Error("--from applies only to auth login");
const runtime = await distribution.createRuntimeCredentialsFromConfig(args.runtime, args.file!);
try {
@@ -1419,8 +1484,12 @@ export async function runCli(
}
if (args.command === "status" || args.command === "builds" || args.command === "inspect"
|| args.command === "history" || args.command === "get" || args.command === "cancel" || args.command === "queue"
- || args.command === "operations" || args.command === "operation") {
- if (args.runtime === undefined) throw new Error(`${args.command} requires --runtime`);
+ ) {
+ if (args.runtime === undefined) {
+ throw new Error(
+ `${args.command} requires a Runtime; run narratage runtime use <profile> or pass --runtime <profile>`,
+ );
+ }
const runtime = await loadRuntimeArchive(args.runtime, distribution, args.command !== "cancel");
try {
if (args.command === "queue") {
@@ -1497,28 +1566,6 @@ export async function runCli(
await writeQueue();
await new Promise((resolveWait) => setTimeout(resolveWait, 1_000));
}
- } else if (args.command === "operations") {
- const status = await runtime.status(args.file!);
- const machine = { build: args.file, operations: status.operations };
- writeOperational(machine, "Build operations", "info", [
- ["Build", args.file!], ["Operations", String(status.operations.length)],
- ], status.operations.map((item) => `${item.id}: ${item.status} · ${item.authority} → ${item.route}`
- + `${item.progress === undefined ? "" : ` · ${formatOperationProgress(item.progress)}`}`
- + `${item.failure === undefined ? "" : ` · ${item.failure.code}: ${item.failure.message}`}`
- + `${item.cancellation === undefined ? "" : ` · cancellation ${item.cancellation.status}`}`));
- } else if (args.command === "operation") {
- if (!isDigest(args.file!)) throw new Error("operation id must be a content digest");
- const operation = await runtime.operation(args.file!);
- writeOperational({ operation }, operation === undefined ? "Operation not found" : "Operation detail",
- operation === undefined ? "warning" : "info", operation === undefined ? [] : [
- ["Operation", operation.id], ["Status", operation.status], ["Endpoint", operation.endpoint],
- ["Authority", operation.authority], ["Route", operation.route],
- ["Attempt", String(operation.attempt)],
- ...(operation.progress === undefined ? [] : [["Progress", formatOperationProgress(operation.progress)] as const]),
- ], operation?.failure === undefined ? [] : [
- `${operation.failure.code}: ${operation.failure.message}`,
- ]);
- if (operation === undefined) io.setExitCode?.(1);
} else if (args.command === "builds") {
const entries = await runtime.builds();
const inspected = args.json || args.verbose ? entries : entries.slice(0, 20);
@@ -1581,12 +1628,16 @@ export async function runCli(
}));
} else if (args.command === "status") {
const status = await runtime.status(args.file!);
+ const effectiveStatus = status.dispatch === undefined
+ ? status.build?.state.status
+ : submissionStatus(status.dispatch);
const machine = {
build: status.build === undefined ? undefined : {
id: status.build.build,
revision: status.build.revision,
core: status.build.state.id,
- status: status.build.state.status,
+ status: effectiveStatus,
+ coreStatus: status.build.state.status,
diagnostics: status.build.state.diagnostics,
},
catalog: status.catalog === undefined
@@ -1612,7 +1663,10 @@ export async function runCli(
writeOperational(machine, status.build === undefined ? "Build not found" : "Build status",
status.build === undefined ? "warning" : status.dispatch?.terminal === "failed" ? "error" : "info", [
["Build", args.file!],
- ["Core", status.build?.state.status ?? "missing"],
+ ["Status", effectiveStatus ?? "missing"],
+ ...(status.build === undefined || 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
@@ -1755,52 +1809,29 @@ export async function runCli(
]);
}
} else {
- if (args.action === "build") {
- const result = await runtime.cancel(args.file!, args.reason);
- const machine = {
- scope: "build",
- build: args.file,
- requested: result !== undefined,
- phase: result?.phase,
- admission: result?.admission,
- terminal: result?.terminal,
- };
- const title = result === undefined
- ? "Build not found"
- : result.terminal === "cancelled"
- ? "Build cancelled"
- : result.phase === "terminal"
- ? "Build already finished"
- : "Build cancellation requested";
- writeOperational(machine, title,
- result === undefined ? "warning" : result.phase === "terminal" && result.terminal !== "cancelled" ? "info" : "success", [
- ["Build", args.file!], ["Admission", result?.admission ?? "missing"], ["Phase", result?.phase ?? "missing"],
- ], result?.phase === "terminal" && result.terminal !== "cancelled"
- ? [`No running work was changed; this Build is already ${result.terminal}.`]
- : []);
- if (result === undefined) io.setExitCode?.(1);
- } else if (args.action === "operation") {
- if (args.file === undefined || !isDigest(args.file)) {
- throw new Error("cancel operation requires an Operation digest");
- }
- const result = await runtime.cancelOperation(args.file!, args.reason);
- const machine = {
- scope: "operation",
- operation: args.file,
- requested: result !== undefined,
- build: result?.build,
- execution: result?.status,
- control: result?.cancellation?.status,
- };
- writeOperational(machine, result === undefined ? "Operation not found" : "Operation cancellation requested",
- result === undefined ? "warning" : "success", [
- ["Operation", args.file!], ["Build", result?.build ?? "missing"],
- ["Execution", result?.status ?? "missing"], ["Control", result?.cancellation?.status ?? "missing"],
- ]);
- if (result === undefined) io.setExitCode?.(1);
- } else {
- throw new Error("cancel must name its scope: cancel build <build-id> or cancel operation <operation-id>");
- }
+ const result = await runtime.cancel(args.file!, args.reason);
+ const machine = {
+ build: args.file,
+ requested: result !== undefined
+ && (result.phase !== "terminal" || result.terminal === "cancelled"),
+ phase: result?.phase,
+ admission: result?.admission,
+ terminal: result?.terminal,
+ };
+ const title = result === undefined
+ ? "Build not found"
+ : result.terminal === "cancelled"
+ ? "Build cancelled"
+ : result.phase === "terminal"
+ ? "Build already finished"
+ : "Build cancellation requested";
+ writeOperational(machine, title,
+ result === undefined ? "warning" : result.phase === "terminal" && result.terminal !== "cancelled" ? "info" : "success", [
+ ["Build", args.file!], ["Admission", result?.admission ?? "missing"], ["Phase", result?.phase ?? "missing"],
+ ], result?.phase === "terminal" && result.terminal !== "cancelled"
+ ? [`No running work was changed; this Build is already ${result.terminal}.`]
+ : []);
+ if (result === undefined) io.setExitCode?.(1);
}
} finally {
await runtime.close();
@@ -1855,7 +1886,7 @@ export async function runCli(
? `Frontend ${sourceHeader.using} is ambiguously registered as Author and Run`
: `No trusted Author or Run compiler accepts Frontend ${sourceHeader.using}`;
throw new Error(effectivePackageLock === undefined && !runMode
- ? `${message}; select the project's package inventory with --runtime <profile> or --package-lock <lock>`
+ ? `${message}; run narratage runtime use <profile>, or pass --runtime <profile> or --package-lock <lock>`
: message);
}
if ((args.command === "plan" || args.command === "build") && !runMode) {
@@ -1916,7 +1947,9 @@ export async function runCli(
}
}
if (args.command === "build") {
- if (args.runtime === undefined) throw new Error("build requires --runtime with a Runtime Profile");
+ if (args.runtime === undefined) {
+ throw new Error("build requires a Runtime; run narratage runtime use <profile> or pass --runtime <profile>");
+ }
const archive = lazyRuntimeArchive(args.runtime, distribution);
let loadedRun;
try {
@@ -1931,13 +1964,6 @@ export async function runCli(
await archive.close();
}
const result = loadedRun.compiler.planCompilation(loadedRun, loadedPackageSet?.lock.digest);
- const runtimeArchive = await loadRuntimeArchive(args.runtime, distribution);
- let archived;
- try {
- archived = await runtimeArchive.status(args.buildId ?? result.state.id);
- } finally {
- await runtimeArchive.close();
- }
let runtime: CliRuntime | undefined;
try {
const catalog = createCatalogDescriptor({
@@ -1949,61 +1975,39 @@ export async function runCli(
},
});
const request = {
- id: args.buildId ?? result.state.id,
+ // One CLI invocation is one execution instance. Source and Plan identity
+ // remain in Core; they never reclaim a previous Build.
+ id: `bld_${randomUUID()}`,
state: result.state,
catalog,
attachments: result.compilation.attachments,
} as const;
const workerProfileDigest = await distribution.runtimeProfileRevision(args.runtime);
- const terminalArchive = archived.build !== undefined
- && archived.dispatch?.phase === "terminal";
- if (archived.build !== undefined && archived.build.state.id !== request.state.id) {
- throw new Error(
- `Build ${request.id} already names another Core Build. Choose a new --build-id for a new Run, `
- + "or restore the original Author/Run Sources to resume this Build",
- );
- }
- if (archived.catalog !== undefined && !sameBuildCatalogDescriptor(archived.catalog, request.catalog)) {
- throw new Error(
- `Build ${request.id} already has another source, Run Source or output naming. `
- + "Choose a new --build-id instead of changing the presentation of an existing Build",
- );
- }
let services: Awaited<ReturnType<typeof startDeclaredServices>> | undefined;
let worker = await runtimeProcessStatus(args.runtime, workerProfileDigest);
- let built: CliBuildSubmission;
- if (terminalArchive) {
- built = {
- id: request.id,
- state: archived.build!.state,
- status: submissionStatus(archived.dispatch!),
- dispatch: archived.dispatch!,
- };
- } else {
- const preflight = await preflightPlan(args.runtime, distribution, result.state, loadedPackageSet);
- // A managed program being down is repairable after Runtime validation;
- // every other deployment error fails before we construct execution or
- // start anything. With --no-services, readiness errors remain fatal.
- assertPreflight(preflight, args.noServices
- ? new Set()
- : new Set(["EXTERNAL_SERVICE_DOWN", "EXTERNAL_SERVICE_MISMATCH"]));
- services = args.noServices
- ? undefined
- : await startDeclaredServices(
- args.runtime,
- distribution,
- demandedCapabilities(result.state),
- reportServiceProgress,
- );
- runtime = await loadRuntime(args.runtime, distribution, loadedPackageSet);
- worker = await ensureRuntimeProcess(
- args.runtime,
- distribution.runtimeWorkerLaunch(),
- workerProfileDigest,
- args.maxWaitMs ?? 10_000,
- );
- built = await runtime.build(request);
- }
+ const preflight = await preflightPlan(args.runtime, distribution, result.state, loadedPackageSet);
+ // A managed program being down is repairable after Runtime validation;
+ // every other deployment error fails before we construct execution or
+ // start anything. With --no-services, readiness errors remain fatal.
+ assertPreflight(preflight, args.noServices
+ ? new Set()
+ : new Set(["EXTERNAL_SERVICE_DOWN", "EXTERNAL_SERVICE_MISMATCH"]));
+ services = args.noServices
+ ? undefined
+ : await startDeclaredServices(
+ args.runtime,
+ distribution,
+ demandedCapabilities(result.state),
+ reportServiceProgress,
+ );
+ runtime = await loadRuntime(args.runtime, distribution, loadedPackageSet);
+ worker = await ensureRuntimeProcess(
+ args.runtime,
+ distribution.runtimeWorkerLaunch(),
+ workerProfileDigest,
+ args.maxWaitMs ?? 10_000,
+ );
+ let built = await runtime.build(request);
if (args.follow && runtime !== undefined) {
built = await observeBuild(runtime, built, {
...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),
@@ -2022,7 +2026,7 @@ export async function runCli(
});
}
const targetOutputs = new Set(built.state.request.targets.map((target) => target.output));
- const presentation = archived.catalog ?? catalog;
+ const presentation = catalog;
const targetAliases = presentation.aliases.filter((alias) =>
alias.ref.kind === "logical-output" && targetOutputs.has(alias.ref.id));
const targetPresentations = targetAliases.flatMap((alias) => {
@@ -2061,14 +2065,15 @@ export async function runCli(
...(built.dispatch.reason === undefined ? {} : { reason: built.dispatch.reason }),
},
};
+ const runtimeHint = runtimeNeedsHint ? ` --runtime ${args.runtime}` : "";
const terminalLines = targetPresentations.length === 0
? [
...(built.dispatch.reason === undefined ? [] : [`Reason ${built.dispatch.reason}`]),
- `Inspect narratage inspect ${built.id} --runtime ${args.runtime}`,
+ `Inspect narratage inspect ${built.id}${runtimeHint}`,
]
: [
...(built.dispatch.reason === undefined ? [] : [`Reason ${built.dispatch.reason}`]),
- `Inspect narratage inspect ${built.id} --runtime ${args.runtime}`,
+ `Inspect narratage inspect ${built.id}${runtimeHint}`,
...targetPresentations
.filter((item) => item.inline !== undefined)
.slice(0, args.verbose ? undefined : 8)
@@ -2077,7 +2082,7 @@ export async function runCli(
.filter((item) => item.inline === undefined)
.slice(0, args.verbose ? undefined : 4)
.map((item) =>
- `Export narratage get ${built.id} --runtime ${args.runtime} --name ${item.alias.name} --to <path>`),
+ `Export narratage get ${built.id}${runtimeHint} --name ${item.alias.name} --to <path>`),
];
const terminal = built.dispatch.phase === "terminal";
writeOperational(machine, args.follow
@@ -2090,9 +2095,9 @@ export async function runCli(
["Worker", worker.state === "running" ? String(worker.pid) : worker.state],
["Goals", String(machine.goals.length)],
], terminal ? terminalLines : [
- `Status narratage status ${built.id} --runtime ${args.runtime}`,
- `Watch narratage queue --runtime ${args.runtime} --watch`,
- `Cancel narratage cancel build ${built.id} --runtime ${args.runtime}`,
+ `Status narratage status ${built.id}${runtimeHint}`,
+ `Watch narratage queue${runtimeHint} --watch`,
+ `Cancel narratage cancel ${built.id}${runtimeHint}`,
]);
if (built.status === "failed") io.setExitCode?.(1);
} finally {
diff --git a/packages/cli/src/output.ts b/packages/cli/src/output.ts
index 8c5055a5..ed6d51cd 100644
--- a/packages/cli/src/output.ts
+++ b/packages/cli/src/output.ts
@@ -454,7 +454,7 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
colors.accent(colors.strong("narratage doctor")),
colors.dim("Diagnose one complete declarative Runtime Profile without submitting work."),
"",
- " narratage doctor <runtime-profile>",
+ " narratage doctor [<runtime-profile>]",
],
plan: [
colors.accent(colors.strong("narratage plan")),
@@ -469,7 +469,7 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
colors.accent(colors.strong("narratage build")),
colors.dim("Submit one durable Build and ensure its selected Runtime Worker is available."),
"",
- " narratage build <run-source> --runtime <profile> [--asset-root <directory>] [--build-id <id>] [--follow] [--no-services]",
+ " narratage build <run-source> [--runtime <profile>] [--asset-root <directory>] [--follow] [--no-services]",
"",
" --follow observe the Build; the Worker still owns execution",
" --no-services do not start declared external programs",
@@ -477,97 +477,86 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
],
runtime: [
colors.accent(colors.strong("narratage runtime")),
- colors.dim("Operate the Worker selected by one Runtime Profile."),
+ colors.dim("Select a project Runtime Profile, then operate its durable Worker."),
"",
- " narratage runtime up <profile> validate the Runtime Closure, start services and Worker",
- " narratage runtime status <profile> inspect Worker, queue capacity and declared services",
- " narratage runtime logs <profile> read Worker logs",
- " narratage runtime down <profile> stop the owned Worker and external programs",
+ " narratage runtime use <profile> select the Profile for this project",
+ " narratage runtime unset remove only the local selection",
+ " narratage runtime up [<profile>] validate the Runtime Closure, start services and Worker",
+ " narratage runtime status [<profile>] inspect Worker, queue capacity and declared services",
+ " narratage runtime logs [<profile>] read Worker logs",
+ " narratage runtime down [<profile>] stop the Worker; external programs keep running",
],
services: [
colors.accent(colors.strong("narratage services")),
colors.dim("Operate only the external programs declared by Endpoints in one Runtime Profile."),
"",
- " narratage services up <profile> [--max-wait-ms <ms>]",
- " narratage services status <profile>",
- " narratage services down <profile>",
+ " narratage services up [<profile>] [--max-wait-ms <ms>]",
+ " narratage services status [<profile>]",
+ " narratage services down [<profile>]",
],
queue: [
colors.accent(colors.strong("narratage queue")),
colors.dim("Inspect durable Build dispatch and Provider-authority capacity."),
"",
- " narratage queue --runtime <profile> [--watch]",
- " narratage queue --runtime <profile> --watch --jsonl",
+ " narratage queue [--runtime <profile>] [--watch]",
+ " narratage queue [--runtime <profile>] --watch --jsonl",
],
builds: [
colors.accent(colors.strong("narratage builds")),
colors.dim("List Builds archived by one Runtime Profile."),
"",
- " narratage builds --runtime <profile>",
+ " narratage builds [--runtime <profile>]",
],
status: [
colors.accent(colors.strong("narratage status")),
colors.dim("Show the current state of one Build and its notable external Operations."),
"",
- " narratage status <build-id> --runtime <profile>",
+ " narratage status <build-id> [--runtime <profile>]",
],
inspect: [
colors.accent(colors.strong("narratage inspect")),
colors.dim("Inspect one Build's targets and accepted archive."),
"",
- " narratage inspect <build-id> --runtime <profile>",
+ " narratage inspect <build-id> [--runtime <profile>]",
],
get: [
colors.accent(colors.strong("narratage get")),
colors.dim("Read or copy one archived result; copying never reruns work."),
"",
- " narratage get <build-id> --runtime <profile> [--name <source-name>|--record <id>|--output <id>|--artifact <digest>] [--to <path>]",
+ " narratage get <build-id> [--runtime <profile>] [--name <source-name>|--record <id>|--output <id>|--artifact <digest>] [--to <path>]",
],
history: [
colors.accent(colors.strong("narratage history")),
colors.dim("Find accepted historical Logical Outputs without selecting them for a new Run."),
"",
- " narratage history <output-name> --runtime <profile> [--source <author-source>]",
- " narratage history --source <author-source> --runtime <profile>",
- ],
- operations: [
- colors.accent(colors.strong("narratage operations")),
- colors.dim("List external Operation attempts belonging to one Build."),
- "",
- " narratage operations <build-id> --runtime <profile>",
- ],
- operation: [
- colors.accent(colors.strong("narratage operation")),
- colors.dim("Inspect one exact external Operation realization."),
- "",
- " narratage operation <operation-digest> --runtime <profile>",
+ " narratage history <output-name> [--runtime <profile>] [--source <author-source>]",
+ " narratage history --source <author-source> [--runtime <profile>]",
],
cancel: [
colors.accent(colors.strong("narratage cancel")),
- colors.dim("Request cancellation without pretending an external Provider stopped instantly."),
+ colors.dim("Withdraw one Build and honestly reconcile work already submitted to Providers."),
"",
- " narratage cancel build <build-id> --runtime <profile> [--reason <text>]",
- " narratage cancel operation <operation-digest> --runtime <profile> [--reason <text>]",
+ " narratage cancel <build-id> [--runtime <profile>] [--reason <text>]",
],
auth: [
colors.accent(colors.strong("narratage auth")),
colors.dim("Manage credentials required by one declared Endpoint instance."),
"",
- " narratage auth status <endpoint-instance> --runtime <profile> [--slot <name>]",
- " narratage auth login <endpoint-instance> --runtime <profile> [--slot <name>] [--from <secret-file>]",
- " narratage auth logout <endpoint-instance> --runtime <profile> [--slot <name>]",
+ " narratage auth status <endpoint-instance> [--runtime <profile>] [--slot <name>]",
+ " narratage auth login <endpoint-instance> [--runtime <profile>] [--slot <name>] [--from <secret-file>]",
+ " narratage auth logout <endpoint-instance> [--runtime <profile>] [--slot <name>]",
],
gc: [
colors.accent(colors.strong("narratage gc")),
colors.dim("Report unreachable archived Artifacts; delete them only with --apply."),
"",
- " narratage gc <profile> [--apply]",
+ " narratage gc [<profile>] [--apply]",
],
packages: [
colors.accent(colors.strong("narratage packages")),
colors.dim("Derive both package locks from one Run Source and Runtime Profile."),
"",
- " narratage packages sync <run-source> --runtime <profile> [--root <workspace>]",
+ " narratage packages sync <run-source> [--runtime <profile>] [--root <workspace>]",
"",
"The sources select author packages; the Profile selects Runtime packages.",
"This never installs packages or runs Providers.",
@@ -591,9 +580,10 @@ export function writeCliHelp(io: CliIo, topic?: string): void {
colors.dim('"First, there was narration. Then, there were montages."'),
"",
colors.strong("Typical flow"),
- " plan <run-source> --runtime <profile> see exactly what this Run will demand",
- " build <run-source> --runtime <profile> submit durable work; add --follow to watch",
- " get <build-id> --runtime <profile> read or copy an archived result",
+ " runtime use <profile> select this project's execution environment",
+ " plan <run-source> see exactly what this Run will demand",
+ " build <run-source> submit durable work; add --follow to watch",
+ " get <build-id> read or copy an archived result",
" packages sync ... setup step after package selection changes",
" doctor <profile> diagnose deployment setup when needed",
"",
@@ -608,21 +598,19 @@ export function writeCliHelp(io: CliIo, topic?: string): void {
" status <build-id> show Build and Operation status",
" inspect <build-id> inspect accepted Records and demanded outputs",
" get <build-id> read or materialize one archived result",
- " cancel build <build-id> close admission and request honest cancellation",
- " cancel operation <digest> suppress one exact Operation realization",
- " operations <build-id> inspect external Operation facts",
- " operation <digest> inspect one external Operation",
+ " cancel <build-id> withdraw one Build and reconcile submitted work",
"",
colors.strong("Runtime"),
" doctor <profile> validate deployment without executing",
- " runtime up|status|logs|down manage the durable Worker and dependencies",
+ " runtime use|unset select this project's Runtime Profile",
+ " runtime up|status|logs|down manage the durable Worker",
" services up|status|down manage declared external programs only",
" queue [--watch] inspect durable dispatch and shared capacity",
" auth status|login|logout manage Endpoint-declared credential references",
" gc <profile> report unreachable Artifacts; --apply deletes",
"",
colors.strong("Packages"),
- " packages sync <run> --runtime <profile> derive both project locks",
+ " packages sync <run> derive both project locks",
" lock-packages <file> set, add, remove, refresh or verify local package trust",
"",
colors.strong("Output"),
diff --git a/packages/cli/src/runtime-port.ts b/packages/cli/src/runtime-port.ts
index 48aa92b9..69aed02c 100644
--- a/packages/cli/src/runtime-port.ts
+++ b/packages/cli/src/runtime-port.ts
@@ -52,10 +52,8 @@ export type CliRuntimeArchiveControl = {
readonly capacity: readonly CapacityReservation[];
readonly operations: readonly OperationSnapshot[];
}>;
- operation(id: Digest): Promise<OperationSnapshot | undefined>;
builds(): Promise<readonly BuildCatalogEntry[]>;
cancel(build: string, reason?: string): Promise<BuildDispatchSnapshot | undefined>;
- cancelOperation(id: Digest, reason?: string): Promise<OperationSnapshot | undefined>;
close(): void | Promise<void>;
};
diff --git a/packages/cli/src/runtime-process.ts b/packages/cli/src/runtime-process.ts
index 5ee704a9..21e0c051 100644
--- a/packages/cli/src/runtime-process.ts
+++ b/packages/cli/src/runtime-process.ts
@@ -32,7 +32,9 @@ const LOG_ROTATE_BYTES = 10 * 1024 * 1024;
function paths(profile: string) {
const absolute = resolve(profile);
const id = createHash("sha256").update(absolute).digest("hex").slice(0, 16);
- const root = join(dirname(absolute), ".svml", "runtime", id);
+ // `.svml/runtime` is the project-local active Profile pointer. Worker process
+ // state is independent and must never compete with that file for the same path.
+ const root = join(dirname(absolute), ".svml", "workers", id);
return {
root,
pid: join(root, "worker.json"),
@@ -56,8 +58,11 @@ function alive(pid: number): boolean {
try {
process.kill(pid, 0);
return true;
- } catch {
- return false;
+ } catch (error) {
+ // POSIX uses EPERM when the process exists but the caller may not signal it.
+ // Treat only an absent process as stopped; otherwise a restricted shell can
+ // make every CLI invocation launch another Worker for the same Profile.
+ return error instanceof Error && "code" in error && error.code === "EPERM";
}
}
@@ -217,7 +222,16 @@ async function stopRuntimeProcessUnlocked(profile: string, timeoutMs: number): P
await unlink(location.ready).catch(() => undefined);
return { state: "stopped", profile: resolve(profile), logPath: location.log };
}
- process.kill(current.pid, "SIGTERM");
+ try {
+ process.kill(current.pid, "SIGTERM");
+ } catch (error) {
+ if (error instanceof Error && "code" in error && error.code === "EPERM") {
+ throw new Error(
+ `Runtime Worker ${current.pid} is running but this environment cannot stop it; profile: ${resolve(profile)}`,
+ );
+ }
+ if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) throw error;
+ }
const deadline = Date.now() + timeoutMs;
while (Date.now() <= deadline && alive(current.pid)) {
await new Promise((resolveWait) => setTimeout(resolveWait, 50));
diff --git a/packages/cli/src/runtime-selection.ts b/packages/cli/src/runtime-selection.ts
new file mode 100644
index 00000000..f8210b76
--- /dev/null
+++ b/packages/cli/src/runtime-selection.ts
@@ -0,0 +1,98 @@
+import { mkdir, readFile, realpath, unlink, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve } from "node:path";
+
+const stateDirectoryName = ".svml";
+const selectionFileName = "runtime";
+
+export type RuntimeProfileSelection = {
+ readonly profile: string;
+ readonly projectRoot: string;
+ readonly selectionFile: string;
+};
+
+function errorCode(error: unknown): string | undefined {
+ return error !== null && typeof error === "object" && "code" in error
+ ? String((error as { readonly code?: unknown }).code)
+ : undefined;
+}
+
+async function readSelectionFile(start: string): Promise<{
+ readonly projectRoot: string;
+ readonly selectionFile: string;
+ readonly value: string;
+} | undefined> {
+ let directory = resolve(start);
+ while (true) {
+ const selectionFile = resolve(directory, stateDirectoryName, selectionFileName);
+ try {
+ return {
+ projectRoot: directory,
+ selectionFile,
+ value: (await readFile(selectionFile, "utf8")).trim(),
+ };
+ } catch (error) {
+ if (errorCode(error) !== "ENOENT") throw error;
+ }
+ const parent = dirname(directory);
+ if (parent === directory) return undefined;
+ directory = parent;
+ }
+}
+
+/**
+ * Remember one Runtime Profile for a project. This is local CLI context, not
+ * Author Source, Run Source, package selection or Core state.
+ */
+export async function selectRuntimeProfile(projectRoot: string, profile: string): Promise<RuntimeProfileSelection> {
+ const root = await realpath(resolve(projectRoot));
+ const selectedProfile = await realpath(resolve(profile));
+ const stateDirectory = resolve(root, stateDirectoryName);
+ const selectionFile = resolve(stateDirectory, selectionFileName);
+ await mkdir(stateDirectory, { recursive: true });
+ try {
+ await writeFile(resolve(stateDirectory, ".gitignore"), "*\n", { encoding: "utf8", flag: "wx" });
+ } catch (error) {
+ if (errorCode(error) !== "EEXIST") throw error;
+ }
+ const stored = relative(root, selectedProfile) || ".";
+ await writeFile(selectionFile, `${stored}\n`, "utf8");
+ return { profile: selectedProfile, projectRoot: root, selectionFile };
+}
+
+/** Find the nearest project-local Runtime selection, starting at a file's directory or cwd. */
+export async function findRuntimeProfile(start: string): Promise<RuntimeProfileSelection | undefined> {
+ const selected = await readSelectionFile(start);
+ if (selected === undefined) return undefined;
+ if (selected.value.length === 0) {
+ throw new Error(`Runtime selection is empty: ${selected.selectionFile}; run narratage runtime use <profile>`);
+ }
+ const projectRoot = await realpath(selected.projectRoot);
+ const candidate = resolve(projectRoot, selected.value);
+ try {
+ return {
+ profile: await realpath(candidate),
+ projectRoot,
+ selectionFile: selected.selectionFile,
+ };
+ } catch (error) {
+ if (errorCode(error) === "ENOENT") {
+ throw new Error(
+ `Selected Runtime Profile no longer exists: ${candidate}; run narratage runtime use <profile>`,
+ );
+ }
+ throw error;
+ }
+}
+
+/** Remove only the local pointer. Runtime state, locks, services and Builds are untouched. */
+export async function clearRuntimeProfile(start: string): Promise<RuntimeProfileSelection | undefined> {
+ const selected = await readSelectionFile(start);
+ if (selected === undefined) return undefined;
+ const profile = resolve(selected.projectRoot, selected.value);
+ await unlink(selected.selectionFile);
+ return {
+ profile,
+ projectRoot: selected.projectRoot,
+ selectionFile: selected.selectionFile,
+ };
+}
diff --git a/packages/cli/test/control-commands.test.ts b/packages/cli/test/control-commands.test.ts
index 11b676fc..9ee05824 100644
--- a/packages/cli/test/control-commands.test.ts
+++ b/packages/cli/test/control-commands.test.ts
@@ -69,6 +69,12 @@ test("command options fail closed instead of being silently ignored", async () =
], 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", "--root", "/tmp",
@@ -160,3 +166,33 @@ test("auth login rejects a read-only CredentialStore before asking for a secret"
assert.equal(prompted, false);
assert.equal(closed, true);
});
+
+test("cancelling a completed Build reports that no cancellation was requested", async () => {
+ const control = {
+ async cancel() {
+ return {
+ build: "build-complete",
+ phase: "terminal",
+ admission: "closed",
+ terminal: "complete",
+ };
+ },
+ async close() {},
+ } as unknown as CliRuntimeArchiveControl;
+ const distribution = {
+ createRuntimeArchiveFromConfig: async () => control,
+ } as unknown as CliDistribution;
+ let output = "";
+
+ await runCli([
+ "cancel", "build-complete", "--runtime", "/tmp/runtime.json", "--json",
+ ], { write: (text) => { output += text; } }, distribution);
+
+ assert.deepEqual(JSON.parse(output), {
+ build: "build-complete",
+ requested: false,
+ phase: "terminal",
+ admission: "closed",
+ terminal: "complete",
+ });
+});
diff --git a/packages/cli/test/runtime-build-process.test.ts b/packages/cli/test/runtime-build-process.test.ts
index cdef9056..834462d7 100644
--- a/packages/cli/test/runtime-build-process.test.ts
+++ b/packages/cli/test/runtime-build-process.test.ts
@@ -1,5 +1,5 @@
import assert from "node:assert/strict";
-import { execFile, spawn } from "node:child_process";
+import { execFile } from "node:child_process";
import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -81,7 +81,6 @@ test("CLI exits after durable submission and a restarted detached Worker complet
const profile = join(project, "svml.runtime.json");
const source = join(project, "main.svml");
const run = join(project, "build.svrun");
- const build = "process-recovery-build";
try {
await writeNodePackageLock(authorLockPath, await createNodePackageLock([
"@narratage/run-markup",
@@ -154,41 +153,18 @@ test("CLI exits after durable submission and a restarted detached Worker complet
}, await runtimeConfigRevision(profile), 5_000);
const submitted = await cli(project, [
"build", run,
- "--build-id", build,
"--runtime", profile,
"--root", project,
"--no-services",
]);
+ const build = String(submitted.build);
+ assert.match(build, /^bld_[0-9a-f-]{36}$/u);
assert.equal(submitted.status, "queued", "the foreground CLI reports durable admission, not execution ownership");
assert.equal((submitted.dispatch as { readonly phase?: string }).phase, "queued");
const originalProcess = await runtimeProcessStatus(profile, await runtimeConfigRevision(profile));
assert.equal(originalProcess.state, "running", "the detached Runtime process outlives the submitting CLI process");
assert.equal(originalProcess.pid, parked.pid, "build reuses one profile-scoped Runtime process");
- const follower = spawn(process.execPath, [
- "--import", tsxImport, cliEntry,
- "build", run,
- "--build-id", build,
- "--runtime", profile,
- "--root", project,
- "--no-services",
- "--follow",
- "--json",
- ], { cwd: project, stdio: "ignore" });
- let followerEnded = false;
- const followerExit = new Promise<void>((resolve, reject) => {
- follower.once("exit", () => { followerEnded = true; resolve(); });
- follower.once("error", (error) => { followerEnded = true; reject(error); });
- });
- void followerExit.catch(() => {});
- await new Promise((resolve) => setTimeout(resolve, 500));
- assert.equal(followerEnded, false, "--follow is observing the still-queued Build");
- follower.kill("SIGINT");
- await followerExit;
- const afterInterrupt = await cli(project, ["status", build, "--runtime", profile]);
- assert.equal((afterInterrupt.dispatch as { readonly admission?: string }).admission, "open",
- "interrupting --follow does not translate into Build cancellation");
-
await stopRuntimeProcess(profile, 10_000);
const interrupted = await cli(project, ["status", build, "--runtime", profile]);
assert.notEqual((interrupted.dispatch as { readonly phase?: string }).phase, "terminal",
@@ -221,17 +197,16 @@ test("CLI exits after durable submission and a restarted detached Worker complet
assert.notEqual(JSON.parse(await readFile(exported, "utf8")), undefined);
await stopRuntimeProcess(profile, 10_000);
- const replayed = await cli(project, [
+ const repeated = await cli(project, [
"build", run,
- "--build-id", build,
"--runtime", profile,
"--root", project,
"--no-services",
"--follow",
]);
- assert.equal(replayed.status, "complete");
- assert.equal((replayed.worker as { readonly state?: string }).state, "stopped",
- "replaying a terminal Build reads its durable result without starting a Worker");
+ assert.equal(repeated.status, "complete");
+ assert.notEqual(repeated.build, build,
+ "repeating the same Run Source creates a fresh Build instead of reclaiming source-derived state");
} finally {
await stopRuntimeProcess(profile, 10_000).catch(() => undefined);
await rm(project, { recursive: true, force: true });
diff --git a/packages/cli/test/runtime-process.test.ts b/packages/cli/test/runtime-process.test.ts
index 9c1894ef..855fe410 100644
--- a/packages/cli/test/runtime-process.test.ts
+++ b/packages/cli/test/runtime-process.test.ts
@@ -1,5 +1,5 @@
import assert from "node:assert/strict";
-import { appendFile, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import test from "node:test";
@@ -22,6 +22,8 @@ test("one detached Runtime Worker is observable, reusable and explicitly stoppab
packageLock: "./author.lock",
runtimePackageLock: "./runtime.lock",
}), "utf8");
+ await mkdir(join(root, ".svml"), { recursive: true });
+ await writeFile(join(root, ".svml", "runtime"), "runtime.json\n", "utf8");
const program = `
const fs = require("node:fs");
const path = require("node:path");
@@ -38,6 +40,8 @@ test("one detached Runtime Worker is observable, reusable and explicitly stoppab
profile, { command: process.execPath, args: ["-e", program] }, "revision-1", 5_000);
assert.equal(first.state, "running");
assert.ok(first.pid);
+ assert.equal(await readFile(join(root, ".svml", "runtime"), "utf8"), "runtime.json\n",
+ "Worker state must not overwrite or descend through the active Runtime Profile pointer");
const second = await ensureRuntimeProcess(profile, { command: "must-not-run", args: [] }, "revision-1", 5_000);
assert.equal(second.pid, first.pid);
const concurrent = await Promise.all(Array.from({ length: 8 }, async () =>
diff --git a/packages/cli/test/runtime-selection.test.ts b/packages/cli/test/runtime-selection.test.ts
new file mode 100644
index 00000000..d105c269
--- /dev/null
+++ b/packages/cli/test/runtime-selection.test.ts
@@ -0,0 +1,93 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+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 { findRuntimeProfile, selectRuntimeProfile } from "../src/runtime-selection.js";
+
+test("project Runtime selection is a relative local pointer discovered from nested sources", async () => {
+ const root = await mkdtemp(join(tmpdir(), "narratage-runtime-selection-"));
+ try {
+ const nested = join(root, "sources", "chapter");
+ const profile = join(root, "runtime", "local.json");
+ await mkdir(nested, { recursive: true });
+ await mkdir(join(root, "runtime"), { recursive: true });
+ await writeFile(profile, "{}\n", "utf8");
+
+ const selected = await selectRuntimeProfile(root, profile);
+ assert.equal(selected.profile, await realpath(profile));
+ assert.equal((await readFile(join(root, ".svml", "runtime"), "utf8")).trim(), join("runtime", "local.json"));
+
+ const found = await findRuntimeProfile(nested);
+ assert.equal(found?.profile, selected.profile);
+ assert.equal(await realpath(found!.projectRoot), selected.projectRoot);
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+});
+
+test("runtime use lets later CLI commands reuse the selected Profile", async () => {
+ const root = await mkdtemp(join(tmpdir(), "narratage-runtime-cli-"));
+ const previous = process.cwd();
+ try {
+ const profile = join(root, "svml.runtime.json");
+ const otherProfile = join(root, "other.runtime.json");
+ await writeFile(profile, "{}\n", "utf8");
+ await writeFile(otherProfile, "{}\n", "utf8");
+ const calls: string[] = [];
+ const control = {
+ async queue() { return { dispatches: [], capacity: [], operations: [] }; },
+ async close() {},
+ } as unknown as CliRuntimeArchiveControl;
+ const distribution = {
+ resolveCompilationPackages: async (path: string) => {
+ calls.push(`select:${resolve(path)}`);
+ return {
+ root,
+ packageLock: join(root, "svml.packages.lock"),
+ runtimePackageLock: join(root, "svml.runtime-packages.lock"),
+ };
+ },
+ createRuntimeArchiveFromConfig: async (path: string) => {
+ calls.push(`queue:${resolve(path)}`);
+ return control;
+ },
+ runtimeProfileRevision: async () => "runtime-selection-test",
+ } as unknown as CliDistribution;
+ 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(["runtime", "unset", "--json"], { write() {} }, distribution);
+
+ assert.deepEqual(calls, [
+ `select:${profile}`,
+ `queue:${await realpath(profile)}`,
+ `queue:${otherProfile}`,
+ ]);
+ assert.equal(await findRuntimeProfile(root), undefined);
+ } finally {
+ process.chdir(previous);
+ await rm(root, { recursive: true, force: true });
+ }
+});
+
+test("runtime status without a selected Profile reports the missing context instead of generic usage", async () => {
+ const root = await mkdtemp(join(tmpdir(), "narratage-runtime-missing-"));
+ const previous = process.cwd();
+ try {
+ process.chdir(root);
+ await assert.rejects(
+ async () => await runCli(["runtime", "status"], { write() {} }, {} as CliDistribution),
+ /runtime requires a Runtime Profile/u,
+ );
+ } finally {
+ process.chdir(previous);
+ await rm(root, { recursive: true, force: true });
+ }
+});
diff --git a/packages/cli/test/services-command.test.ts b/packages/cli/test/services-command.test.ts
index 45740f73..47af2549 100644
--- a/packages/cli/test/services-command.test.ts
+++ b/packages/cli/test/services-command.test.ts
@@ -1,4 +1,7 @@
import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
import test from "node:test";
import { runCli } from "../src/main.js";
@@ -121,3 +124,14 @@ test("an idle stopped Runtime is status data, not a command failure", async () =
assert.match(output, /Runtime status/u);
assert.match(output, /Worker\s+stopped/u);
});
+
+test("runtime down stops only its Worker and never an external program shared by another Profile", async () => {
+ const root = await mkdtemp(join(tmpdir(), "narratage-runtime-down-"));
+ const calls: string[] = [];
+ try {
+ await runCli(["runtime", "down", join(root, "svml.runtime.json")], io, distribution(calls));
+ assert.deepEqual(calls, []);
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+});
diff --git a/packages/driver-node/src/registry.ts b/packages/driver-node/src/registry.ts
index 728cc1bc..83f2fa3d 100644
--- a/packages/driver-node/src/registry.ts
+++ b/packages/driver-node/src/registry.ts
@@ -205,30 +205,28 @@ export class EndpointRegistry implements EndpointRegistrar {
if (JSON.stringify(credentialSlots) !== JSON.stringify(endpoint.credentialSlots)) {
throw new Error(`Endpoint ${endpoint.id} credential slots do not match the Runtime Closure`);
}
- const route = endpointCapabilityKey(binding.capability);
- const declaredRoute = registration.scheduling?.queue;
- if (declaredRoute !== undefined
- && (declaredRoute.authority !== endpoint.authority || declaredRoute.route !== route)) {
- throw new Error(`Endpoint ${endpoint.id} scheduling route differs from the Runtime Closure`);
- }
+ const route = endpoint.routes.find((item) =>
+ sameRef(item.capability, binding.capability) && sameRef(item.returns, binding.returns));
+ if (route === undefined) throw new Error(`Endpoint ${endpoint.id} has no locked scheduling route`);
+ const scheduling = {
+ queue: { authority: endpoint.authority, route: route.route },
+ resources: [
+ {
+ id: `authority:${endpoint.authority}`,
+ maxActive: endpoint.maxConcurrency,
+ maxInFlight: endpoint.maxConcurrency,
+ },
+ {
+ id: `route:${endpoint.authority}/${route.route}`,
+ maxActive: route.maxConcurrency,
+ maxInFlight: route.maxConcurrency,
+ },
+ ],
+ };
pending.push({
key: endpointCapabilityKey(binding.capability),
endpoint: endpoint.id,
- scheduling: {
- queue: { authority: endpoint.authority, route },
- resources: [
- {
- id: `authority:${endpoint.authority}`,
- maxActive: endpoint.maxConcurrency,
- maxInFlight: endpoint.maxConcurrency,
- },
- {
- id: `route:${endpoint.authority}/${route}`,
- maxActive: endpoint.maxConcurrency,
- maxInFlight: endpoint.maxConcurrency,
- },
- ],
- },
+ scheduling,
});
}
for (const item of pending) {
diff --git a/packages/endpoint-kit/src/index.ts b/packages/endpoint-kit/src/index.ts
index 4c81882a..7b716fee 100644
--- a/packages/endpoint-kit/src/index.ts
+++ b/packages/endpoint-kit/src/index.ts
@@ -153,6 +153,10 @@ type EndpointCapabilityBase = {
readonly capability: CapabilityRef;
readonly returns: TypeRef;
readonly supports?: (need: Need) => boolean;
+ /** Stable Provider-local queue lane. Defaults to the capability name. */
+ readonly route?: string;
+ /** Route capacity; the Provider authority keeps its independent total capacity. */
+ readonly maxConcurrency?: number;
};
export type ImmediateEndpointCapability = EndpointCapabilityBase & {
@@ -184,6 +188,7 @@ export type DefineEndpointPackageOptions = {
readonly label: string;
readonly kind?: "secret" | "json";
}>>;
+ /** Total capacity shared by every route under this configured Provider authority. */
readonly defaultConcurrency?: number;
readonly capabilities: readonly EndpointCapability[];
};
@@ -215,6 +220,20 @@ export function defineEndpointPackage(options: DefineEndpointPackageOptions): En
"one Endpoint facet cannot mix immediate and recoverable lifecycles");
const keys = options.capabilities.map((item) => refKey(item.capability));
assert(new Set(keys).size === keys.length, "Endpoint package repeats a capability");
+ const routes = options.capabilities.map((item) => item.route ?? item.capability.name);
+ assert(routes.every((route) => route.trim().length > 0), "Endpoint package route is empty");
+ const routeConcurrency = new Map<string, number>();
+ for (const capability of options.capabilities) {
+ const route = capability.route ?? capability.capability.name;
+ const concurrency = positiveInteger(
+ capability.maxConcurrency ?? options.defaultConcurrency ?? 1,
+ `${capability.capability.name} maxConcurrency`,
+ );
+ const previous = routeConcurrency.get(route);
+ assert(previous === undefined || previous === concurrency,
+ `Endpoint package route ${route} has conflicting concurrency limits`);
+ routeConcurrency.set(route, concurrency);
+ }
const credentials = Object.fromEntries(Object.entries(options.credentials ?? {})
.sort(([left], [right]) => left.localeCompare(right))
.map(([slot, ref]) => {
@@ -243,6 +262,11 @@ export function defineEndpointPackage(options: DefineEndpointPackageOptions): En
const configuration = canonicalize(options.configuration ?? null);
const executionPolicy = options.capabilities.map((capability) => ({
capability: refKey(capability.capability),
+ route: capability.route ?? capability.capability.name,
+ maxConcurrency: positiveInteger(
+ capability.maxConcurrency ?? options.defaultConcurrency ?? 1,
+ `${capability.capability.name} maxConcurrency`,
+ ),
lifecycle: capability.lifecycle,
...(capability.lifecycle === "recoverable" && capability.retry !== undefined
? { retry: { maxAttempts: capability.retry.maxAttempts } }
@@ -266,6 +290,15 @@ export function defineEndpointPackage(options: DefineEndpointPackageOptions): En
fulfills,
lifecycle,
defaultConcurrency: positiveInteger(options.defaultConcurrency ?? 1, "defaultConcurrency"),
+ routes: options.capabilities.map((capability) => ({
+ capability: structuredClone(capability.capability),
+ returns: structuredClone(capability.returns),
+ route: capability.route ?? capability.capability.name,
+ maxConcurrency: positiveInteger(
+ capability.maxConcurrency ?? options.defaultConcurrency ?? 1,
+ `${capability.capability.name} maxConcurrency`,
+ ),
+ })),
credentialSlots: Object.keys(credentials),
}],
};
@@ -286,8 +319,12 @@ export function defineEndpointPackage(options: DefineEndpointPackageOptions): En
credentials: credentialDescriptions,
install(registry) {
for (const capability of options.capabilities) {
- const route = refKey(capability.capability);
- const concurrency = positiveInteger(options.defaultConcurrency ?? 1, "defaultConcurrency");
+ const route = capability.route ?? capability.capability.name;
+ const authorityConcurrency = positiveInteger(options.defaultConcurrency ?? 1, "defaultConcurrency");
+ const routeConcurrency = positiveInteger(
+ capability.maxConcurrency ?? authorityConcurrency,
+ `${route} maxConcurrency`,
+ );
const common: EndpointRegistrationOptions = {
...(capability.supports === undefined ? {} : { supports: capability.supports }),
runtimeImplementation: {
@@ -301,13 +338,13 @@ export function defineEndpointPackage(options: DefineEndpointPackageOptions): En
resources: [
{
id: `authority:${options.authority}`,
- maxActive: concurrency,
- maxInFlight: concurrency,
+ maxActive: authorityConcurrency,
+ maxInFlight: authorityConcurrency,
},
{
id: `route:${options.authority}/${route}`,
- maxActive: concurrency,
- maxInFlight: concurrency,
+ maxActive: routeConcurrency,
+ maxInFlight: routeConcurrency,
},
],
},
diff --git a/packages/endpoint-kit/test/endpoint.test.ts b/packages/endpoint-kit/test/endpoint.test.ts
index 45b3bb9d..889e3e65 100644
--- a/packages/endpoint-kit/test/endpoint.test.ts
+++ b/packages/endpoint-kit/test/endpoint.test.ts
@@ -54,6 +54,8 @@ test("one Endpoint definition generates Manifest, instance, bindings and host-ne
lifecycle: "immediate",
capability: capabilities.generation,
returns: types.generated,
+ route: "text-generation",
+ maxConcurrency: 1,
handler: () => ({
value: { kind: "inline", value: "generated" },
}),
@@ -80,6 +82,13 @@ test("one Endpoint definition generates Manifest, instance, bindings and host-ne
registrations[0]?.options.runtimeImplementation?.configurationDigest,
endpoint.instance.configurationDigest,
);
+ assert.deepEqual(registrations[0]?.options.scheduling, {
+ queue: { authority: "example.personal", route: "text-generation" },
+ resources: [
+ { id: "authority:example.personal", maxActive: 3, maxInFlight: 3 },
+ { id: "route:example.personal/text-generation", maxActive: 1, maxInFlight: 1 },
+ ],
+ });
});
test("non-secret Endpoint configuration and credential references change instance identity", () => {
diff --git a/packages/local/README.md b/packages/local/README.md
index 54c16fb8..8557b18f 100644
--- a/packages/local/README.md
+++ b/packages/local/README.md
@@ -52,9 +52,12 @@ asks the selected Scheduler to regenerate the current commands. Recoverable Prov
remain in `OperationStore`; dispatch lease, heartbeat, admission and shared resource capacity remain in
`BuildDispatchStore`. Queue and cancellation inspection read those authoritative stores directly.
-Cancellation first closes admission. Existing Operations keep their own execution fact and a
+Cancellation is Build-scoped. A queued Build that no Worker has claimed becomes terminal atomically;
+an active Build first closes admission. Existing Operations keep their own execution fact and a
separate cancellation-control fact. Provider acceptance is not reported as cancellation; unsupported
or too-late requests continue reconciling the same Operation and never select another Candidate.
+Endpoint checkpoint recovery continues the same in-flight task after Worker failure; it is not a way
+to reopen a terminal Build.
## Boundaries
diff --git a/packages/local/src/external-services.ts b/packages/local/src/external-services.ts
index 3b97585c..6ac364ac 100644
--- a/packages/local/src/external-services.ts
+++ b/packages/local/src/external-services.ts
@@ -122,8 +122,19 @@ function alive(pid: number): boolean {
try {
process.kill(pid, 0);
return true;
- } catch {
- return false;
+ } catch (error) {
+ return error instanceof Error && "code" in error && error.code === "EPERM";
+ }
+}
+
+function signal(pid: number, name: NodeJS.Signals): "sent" | "gone" | "denied" {
+ try {
+ process.kill(pid, name);
+ return "sent";
+ } catch (error) {
+ if (error instanceof Error && "code" in error && error.code === "ESRCH") return "gone";
+ if (error instanceof Error && "code" in error && error.code === "EPERM") return "denied";
+ throw error;
}
}
@@ -254,10 +265,34 @@ export async function takeExternalServicesDown(
// command's business; saying so is.
: { ...base, action: "not-ours", state, detail: `${service.id} is running but this project did not start it` };
}
- process.kill(pid, "SIGTERM");
+ const term = signal(pid, "SIGTERM");
+ if (term === "denied") {
+ return {
+ ...base,
+ action: "unchanged",
+ state: await service.probe(),
+ pid,
+ detail: `process ${pid} is running but this environment cannot stop it`,
+ };
+ }
+ if (term === "gone") {
+ await rm(join(directory(root), `${service.id}.pid`), { force: true });
+ const state = await service.probe();
+ return state.state === "down"
+ ? { ...base, action: "nothing-to-stop", state }
+ : { ...base, action: "not-ours", state, detail: `${service.id} is now served by another process` };
+ }
const deadline = Date.now() + 15_000;
while (alive(pid) && Date.now() < deadline) await sleep(200);
- if (alive(pid)) process.kill(pid, "SIGKILL");
+ if (alive(pid) && signal(pid, "SIGKILL") === "denied") {
+ return {
+ ...base,
+ action: "unchanged",
+ state: await service.probe(),
+ pid,
+ detail: `process ${pid} ignored SIGTERM and this environment cannot force-stop it`,
+ };
+ }
await rm(join(directory(root), `${service.id}.pid`), { force: true });
return { ...base, action: "stopped", state: await service.probe(), pid };
})));
@@ -273,11 +308,14 @@ export async function reportExternalServices(
const reports = await Promise.all(distinct(services).map(async ({ service, instances }): Promise<ExternalServiceReport> => {
const state = await service.probe();
const pid = await readPid(root, service.id);
+ const logPath = join(directory(root), `${service.id}.log`);
+ const hasLog = await stat(logPath).then(() => true).catch(() => false);
return {
id: service.id,
instances,
state,
...(pid !== undefined && alive(pid) ? { pid } : {}),
+ ...(hasLog ? { logPath } : {}),
};
}));
return { root, services: reports };
diff --git a/packages/local/src/runtime.ts b/packages/local/src/runtime.ts
index 720c9cb7..16ab05b6 100644
--- a/packages/local/src/runtime.ts
+++ b/packages/local/src/runtime.ts
@@ -223,6 +223,9 @@ export async function createLocalRuntime(
`Build Catalog ${request.id} already has another source, Run Source or output naming`);
}
await stageAttachments(request);
+ // The Host creates a fresh id for every Build. Reading an exact duplicate
+ // here only closes the crash window between durable Store writes; it is not
+ // a Source-based lookup and is not exposed as a way to reopen an old Build.
let stored = await options.buildStore.read(request.id);
if (stored === undefined) {
try {
@@ -233,8 +236,7 @@ export async function createLocalRuntime(
}
}
assert(stored.state.id === request.state.id,
- `Build ${request.id} already names another Core Build. Choose a new --build-id for a new Run, `
- + "or restore the original Author/Run Sources to resume this Build");
+ `Build submission ${request.id} conflicts with another Core state`);
const created = await options.dispatchStore.create(createBuildDispatchIdentity({
build: request.id,
core: request.state.id,
diff --git a/packages/local/src/types.ts b/packages/local/src/types.ts
index 74d4eac6..e5a71113 100644
--- a/packages/local/src/types.ts
+++ b/packages/local/src/types.ts
@@ -111,7 +111,7 @@ export type ProjectLocalRuntimeArtifactAccessOptions = ProjectLocalRuntimeArchiv
export type ProjectLocalRuntimeControlOptions = ProjectLocalRuntimeArchiveControlOptions;
export type LocalBuildRequest = {
- /** Stable user/run identity. Reusing it resumes only the same Core Build identity. */
+ /** Caller-generated identity for one submission; Source identity is separate. */
readonly id: string;
readonly state: BuildState;
/** Source aliases and paths for Host inspection. Not trusted Build input. */
diff --git a/packages/local/src/worker.ts b/packages/local/src/worker.ts
index 43bcdb75..68eb1cd9 100644
--- a/packages/local/src/worker.ts
+++ b/packages/local/src/worker.ts
@@ -238,6 +238,15 @@ class DurableLocalWorker implements RuntimeWorker {
reason: "cancellation is awaiting remote terminal facts",
});
}
+ const stranded = (await this.#options.stores.dispatch.listCapacity())
+ .filter((reservation) => reservation.build === dispatch.build);
+ for (const reservation of stranded) {
+ await this.#options.stores.dispatch.clearCapacity(
+ reservation.id,
+ dispatch.build,
+ lease,
+ );
+ }
return await this.#options.stores.dispatch.finish(
dispatch.build,
lease,
diff --git a/packages/local/test/external-services.test.ts b/packages/local/test/external-services.test.ts
index fd490198..9c70456b 100644
--- a/packages/local/test/external-services.test.ts
+++ b/packages/local/test/external-services.test.ts
@@ -147,6 +147,10 @@ test("up starts the program once for every Endpoint that drives it, and down sto
assert.equal(again.services[0]!.action, "already-running");
assert.equal(again.services[0]!.pid, undefined, "nothing was started, so no pid is claimed");
+ const status = await reportExternalServices(path, options);
+ assert.equal(status.services[0]!.pid, pid);
+ assert.equal(status.services[0]!.logPath, join(root, ".svml", "services", "example.log"));
+
await rm(marker, { force: true });
const stopped = await takeExternalServicesDown(path, options);
assert.equal(stopped.services[0]!.action, "stopped");
diff --git a/packages/provider-kie/README.md b/packages/provider-kie/README.md
index 1a2d344b..97eb9276 100644
--- a/packages/provider-kie/README.md
+++ b/packages/provider-kie/README.md
@@ -44,7 +44,11 @@ Declarative activation names an ordinary CredentialRef, not an environment-speci
"instance": "kie.personal",
"config": {
"apiKey": { "store": "keychain", "key": "kie.api-key" },
- "defaultConcurrency": 2
+ "defaultConcurrency": 8,
+ "routeConcurrency": {
+ "seedance-2.5": 4,
+ "gpt-image-2": 3
+ }
}
}
```
@@ -60,10 +64,20 @@ import { credentialRef } from "@narratage/runtime";
const kie = createKieProvider({
instance: "kie.personal",
apiKey: credentialRef("env", "KIE_API_KEY"),
- defaultConcurrency: 2,
+ defaultConcurrency: 8,
+ routeConcurrency: {
+ "seedance-2.5": 4,
+ "gpt-image-2": 3,
+ },
});
```
+`defaultConcurrency` is the total KIE authority capacity shared by all Builds. Each optional
+`routeConcurrency` entry limits one exact KIE model route inside that total. There is no cross-Provider
+`seedance` family queue: another Provider owns another authority and its own independently named
+routes. A task acquires its Provider and route capacity together, so it is queued once rather than
+copied between parent and child queues.
+
An advanced embedding adds `kie` to its Endpoint list beside a complete, explicit set of Runtime
service packages and selections. A reproducible project normally activates deterministic model
components through `packageLock`. The `.svml` Module Closure separately contains only the model
@@ -75,7 +89,7 @@ Manifests actually imported by the author document; installing KIE does not add
stream API. KIE temporary URLs never enter author source or generated Product identity.
2. `createTask` is persisted as one recoverable Operation. Because KIE does not document an
idempotency key, an ambiguous network/5xx submission is not automatically retried.
-3. Once a `taskId` exists, restart resumes only that task. Poll/download errors cannot create a new
+3. Once a `taskId` exists, Worker recovery resumes only that same task. Poll/download errors cannot create a new
paid generation.
4. Successful result URLs are converted to short-lived download URLs, bounded while streaming,
immediately written to the configured content-addressed ArtifactStore, and removed from durable
diff --git a/packages/provider-kie/src/activation.ts b/packages/provider-kie/src/activation.ts
index 3296356a..8cddfd81 100644
--- a/packages/provider-kie/src/activation.ts
+++ b/packages/provider-kie/src/activation.ts
@@ -16,7 +16,7 @@ const kieRuntimeAdapter = createRuntimeEndpointAdapterFacet({
const config = runtimeConfigObject(context.config, "KIE");
runtimeConfigExact(config, [
"apiBaseUrl", "uploadBaseUrl", "apiKey", "defaultConcurrency", "pollIntervalMs",
- "submissionIntervalMs", "requestTimeoutMs", "maxOperationMs", "maxArtifactBytes",
+ "routeConcurrency", "submissionIntervalMs", "requestTimeoutMs", "maxOperationMs", "maxArtifactBytes",
], "KIE");
const apiBaseUrl = runtimeConfigString(config.apiBaseUrl, "KIE apiBaseUrl");
const uploadBaseUrl = runtimeConfigString(config.uploadBaseUrl, "KIE uploadBaseUrl");
@@ -30,6 +30,14 @@ const kieRuntimeAdapter = createRuntimeEndpointAdapterFacet({
const apiKey = runtimeConfigCredentialRef(config.apiKey, "KIE apiKey");
if (apiKey === undefined) throw new Error("KIE apiKey CredentialRef is required");
const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "KIE defaultConcurrency");
+ const routeConcurrency = config.routeConcurrency === undefined
+ ? undefined
+ : Object.fromEntries(Object.entries(runtimeConfigObject(config.routeConcurrency, "KIE routeConcurrency"))
+ .map(([route, value]) => {
+ const concurrency = runtimeConfigPositiveInteger(value, `KIE routeConcurrency.${route}`);
+ if (concurrency === undefined) throw new Error(`KIE routeConcurrency.${route} is required`);
+ return [route, concurrency];
+ }));
const pollIntervalMs = runtimeConfigPositiveInteger(config.pollIntervalMs, "KIE pollIntervalMs");
const submissionIntervalMs = runtimeConfigPositiveInteger(config.submissionIntervalMs, "KIE submissionIntervalMs");
const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "KIE requestTimeoutMs");
@@ -43,6 +51,7 @@ const kieRuntimeAdapter = createRuntimeEndpointAdapterFacet({
...(uploadBaseUrl === undefined ? {} : { uploadBaseUrl }),
apiKey,
...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
+ ...(routeConcurrency === undefined ? {} : { routeConcurrency }),
...(pollIntervalMs === undefined ? {} : { pollIntervalMs }),
...(submissionIntervalMs === undefined ? {} : { submissionIntervalMs }),
...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),
diff --git a/packages/provider-kie/src/provider.ts b/packages/provider-kie/src/provider.ts
index b831e2d4..4f4c37f4 100644
--- a/packages/provider-kie/src/provider.ts
+++ b/packages/provider-kie/src/provider.ts
@@ -39,7 +39,10 @@ export type CreateKieProviderOptions = {
readonly apiBaseUrl?: string;
readonly uploadBaseUrl?: string;
readonly apiKey?: CredentialRef;
+ /** Total in-flight capacity shared by every KIE route. */
readonly defaultConcurrency?: number;
+ /** Optional KIE route limits keyed by capability name, for example seedance-2.5. */
+ readonly routeConcurrency?: Readonly<Record<string, number>>;
readonly pollIntervalMs?: number;
readonly submissionIntervalMs?: number;
readonly requestTimeoutMs?: number;
@@ -597,6 +600,11 @@ function endpoint(options: {
export function createKieProvider(config: CreateKieProviderOptions) {
verifyKieRoutes();
+ const routeNames = new Set(kieRoutes.map((route) => route.capability.name));
+ const routeConcurrency = Object.fromEntries(Object.entries(config.routeConcurrency ?? {}).map(([route, limit]) => {
+ if (!routeNames.has(route)) throw new Error(`unknown KIE concurrency route ${route}`);
+ return [route, positiveInteger(limit, `${route} routeConcurrency`)];
+ }));
const apiBaseUrl = baseUrl(config.apiBaseUrl ?? "https://api.kie.ai", "apiBaseUrl");
const uploadBaseUrl = baseUrl(config.uploadBaseUrl ?? "https://kieai.redpandaai.co", "uploadBaseUrl");
const pollIntervalMs = nonNegativeInteger(config.pollIntervalMs ?? 3_000, "pollIntervalMs");
@@ -651,6 +659,10 @@ export function createKieProvider(config: CreateKieProviderOptions) {
capabilities: kieRoutes.map((route) => ({
capability: route.capability,
returns: route.returns,
+ route: route.capability.name,
+ ...(routeConcurrency[route.capability.name] === undefined
+ ? {}
+ : { maxConcurrency: routeConcurrency[route.capability.name] }),
lifecycle: "recoverable" as const,
endpoint: providerEndpoint,
retry: { maxAttempts: 3 },
diff --git a/packages/provider-kie/test/live-smoke.ts b/packages/provider-kie/test/live-smoke.ts
index dd0437b4..c5a2b5b6 100644
--- a/packages/provider-kie/test/live-smoke.ts
+++ b/packages/provider-kie/test/live-smoke.ts
@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
@@ -158,7 +159,6 @@ function resultExtension(mediaType: string): string {
function caseIds(key: string, media: "image" | "video"): SmokeCase["ids"] {
if (key === "gpt-image-2") {
- // Preserve the identity of the first live Build so rerunning the suite resumes/reuses it.
return {
request: "request:gpt-image-2-live",
source: "@narratage/provider-kie/live-smoke/gpt-image-2@1",
@@ -453,7 +453,7 @@ async function main(): Promise<void> {
try {
const state = await createBuild(item);
const build = await runtime.build(
- { id: `kie-live-${state.request.digest.slice("sha256:".length, "sha256:".length + 16)}`, state },
+ { id: `bld_${randomUUID()}`, state },
{ follow: true, pollIntervalMs: 1_000, maxWaitMs: 20 * 60_000 },
);
if (build.status !== "complete") throw new Error(failureMessage(item, build));
diff --git a/packages/provider-kie/test/provider.test.ts b/packages/provider-kie/test/provider.test.ts
index d8ee4dea..8b54e7d9 100644
--- a/packages/provider-kie/test/provider.test.ts
+++ b/packages/provider-kie/test/provider.test.ts
@@ -76,6 +76,8 @@ test("all KIE capabilities share one recoverable task engine and differ only by
const provider = createKieProvider({
fetch: async () => { throw new Error("no request expected"); },
fetchImplementationDigest: digestOf("provider-kie:route-registry-test"),
+ defaultConcurrency: 8,
+ routeConcurrency: { "seedance-2-mini": 4 },
});
assert.equal(provider.bindings.length, 13);
const registry = new EndpointRegistry();
@@ -93,6 +95,13 @@ test("all KIE capabilities share one recoverable task engine and differ only by
assert.equal(seedResolution.registration.kind, "recoverable");
assert.equal(removalResolution.registration.kind, "recoverable");
assert.equal(seedResolution.registration.endpoint, removalResolution.registration.endpoint);
+ assert.deepEqual(seedResolution.registration.scheduling, {
+ queue: { authority: "kie.default", route: "seedance-2-mini" },
+ resources: [
+ { id: "authority:kie.default", maxActive: 8, maxInFlight: 8 },
+ { id: "route:kie.default/seedance-2-mini", maxActive: 4, maxInFlight: 4 },
+ ],
+ });
});
test("KIE uploads content-addressed references, resumes one task, and persists generated bytes", async () => {
diff --git a/packages/runtime/src/dispatch.ts b/packages/runtime/src/dispatch.ts
index e98eb3c8..c18756f9 100644
--- a/packages/runtime/src/dispatch.ts
+++ b/packages/runtime/src/dispatch.ts
@@ -138,6 +138,10 @@ export type BuildDispatchStore = {
heartbeat(build: string, lease: DispatchLease, now: number, leaseMs: number): Promise<BuildDispatchSnapshot>;
release(build: string, lease: DispatchLease, update: BuildDispatchRelease, now?: number): Promise<BuildDispatchSnapshot>;
finish(build: string, lease: DispatchLease, terminal: DispatchTerminal, reason?: string, now?: number): Promise<BuildDispatchSnapshot>;
+ /**
+ * Close future admission for one Build. A never-claimed queued Build becomes cancelled in the
+ * same atomic store transaction; an already-claimed Build is reconciled by its fenced Worker.
+ */
requestCancellation(build: string, reason?: string, now?: number): Promise<BuildDispatchSnapshot>;
/** Make non-terminal work immediately claimable without changing admission or creative intent. */
wake(build: string, now?: number): Promise<BuildDispatchSnapshot>;
diff --git a/packages/runtime/src/profile.ts b/packages/runtime/src/profile.ts
index 7d3e37a8..a4c01c68 100644
--- a/packages/runtime/src/profile.ts
+++ b/packages/runtime/src/profile.ts
@@ -47,6 +47,11 @@ export type RuntimeEndpointFacet = {
readonly fulfills: readonly RuntimeCapability[];
readonly lifecycle: "immediate" | "recoverable";
readonly defaultConcurrency: number;
+ /** Provider-local lanes. When omitted, each capability inherits the Provider total. */
+ readonly routes?: readonly (RuntimeCapability & {
+ readonly route: string;
+ readonly maxConcurrency: number;
+ })[];
/** Named secret inputs. Values are resolved by the selected CredentialStore only at invocation. */
readonly credentialSlots?: readonly string[];
};
@@ -112,6 +117,10 @@ export type ResolvedRuntimeEndpoint = {
readonly credentialSlots: readonly string[];
readonly authority: string;
readonly maxConcurrency: number;
+ readonly routes: readonly (RuntimeCapability & {
+ readonly route: string;
+ readonly maxConcurrency: number;
+ })[];
};
export type ResolvedRuntimeInstance = ResolvedRuntimeService | ResolvedRuntimeEndpoint;
@@ -214,12 +223,33 @@ function normalizeFacet(facet: RuntimeFacet): RuntimeFacet {
assert(fulfills.length > 0, `${facet.name} must fulfill at least one exact capability`);
assert(new Set(fulfills.map(bindingKey)).size === fulfills.length, `${facet.name} repeats a capability binding`);
assert(facet.lifecycle === "immediate" || facet.lifecycle === "recoverable", `${facet.name} lifecycle is invalid`);
+ const defaultConcurrency = positiveInteger(facet.defaultConcurrency, `${facet.name} defaultConcurrency`);
+ const routes = (facet.routes ?? fulfills.map((item) => ({
+ ...item,
+ route: capabilityKey(item.capability),
+ maxConcurrency: defaultConcurrency,
+ }))).map((item) => ({
+ ...normalizeCapability(item),
+ route: item.route,
+ maxConcurrency: positiveInteger(item.maxConcurrency, `${facet.name} route ${item.route}`),
+ })).sort((left, right) => bindingKey(left).localeCompare(bindingKey(right)));
+ assert(routes.every((item) => item.route.trim().length > 0), `${facet.name} has an empty route`);
+ assert(JSON.stringify(routes.map(bindingKey)) === JSON.stringify(fulfills.map(bindingKey)),
+ `${facet.name} routes must cover every fulfilled capability exactly once`);
+ const routeConcurrency = new Map<string, number>();
+ for (const item of routes) {
+ const previous = routeConcurrency.get(item.route);
+ assert(previous === undefined || previous === item.maxConcurrency,
+ `${facet.name} route ${item.route} has conflicting concurrency limits`);
+ routeConcurrency.set(item.route, item.maxConcurrency);
+ }
return {
...common,
role: "capability-endpoint",
fulfills,
lifecycle: facet.lifecycle,
- defaultConcurrency: positiveInteger(facet.defaultConcurrency, `${facet.name} defaultConcurrency`),
+ defaultConcurrency,
+ routes,
credentialSlots: sortedUniqueStrings(facet.credentialSlots ?? [], `${facet.name} credential slots`),
};
}
@@ -274,6 +304,8 @@ export class RuntimeModuleRegistry {
=== JSON.stringify(resolved.facet.fulfills.map(bindingKey)), `${instance.id} Endpoint capabilities differ`);
assert(instance.maxConcurrency === resolved.facet.defaultConcurrency,
`${instance.id} Endpoint concurrency differs`);
+ assert(JSON.stringify(instance.routes) === JSON.stringify(resolved.facet.routes),
+ `${instance.id} Endpoint routes differ`);
}
}
}
@@ -410,6 +442,19 @@ export function verifyRuntimeClosure(closure: RuntimeClosure): void {
assert(instance.fulfills.length > 0, `${instance.id} Endpoint fulfills nothing`);
assert(new Set(instance.fulfills.map(bindingKey)).size === instance.fulfills.length,
`${instance.id} Endpoint repeats a capability`);
+ assert(instance.routes.length === instance.fulfills.length,
+ `${instance.id} Endpoint routes differ from capabilities`);
+ const routeConcurrency = new Map<string, number>();
+ for (const route of instance.routes) {
+ assert(route.route.trim().length > 0, `${instance.id} Endpoint route is empty`);
+ positiveInteger(route.maxConcurrency, `${instance.id} Endpoint route ${route.route}`);
+ assert(instance.fulfills.some((item) => bindingKey(item) === bindingKey(route)),
+ `${instance.id} Endpoint route is outside its capabilities`);
+ const previous = routeConcurrency.get(route.route);
+ assert(previous === undefined || previous === route.maxConcurrency,
+ `${instance.id} Endpoint route ${route.route} has conflicting concurrency limits`);
+ routeConcurrency.set(route.route, route.maxConcurrency);
+ }
sortedUniqueStrings(instance.credentialSlots, `${instance.id} Endpoint credential slots`);
}
instances.set(instance.id, instance);
@@ -472,6 +517,7 @@ export function resolveRuntimeProfile(
credentialSlots: [...(resolved.facet.credentialSlots ?? [])],
authority: instance.authority,
maxConcurrency: resolved.facet.defaultConcurrency,
+ routes: structuredClone(resolved.facet.routes ?? []),
};
});
const draft: Omit<RuntimeClosure, "digest"> = {
diff --git a/packages/store-sqlite/README.md b/packages/store-sqlite/README.md
index bc48edd8..20f97d26 100644
--- a/packages/store-sqlite/README.md
+++ b/packages/store-sqlite/README.md
@@ -19,4 +19,4 @@ rejected and recreated explicitly instead of carrying migration code before the
execution services plus a Host-only `catalog` handle. They share one connection and one close
lifecycle. The catalog is deliberately absent from the Runtime service Manifest and Runtime
Closure; changing the Host-only catalog table therefore cannot change the identity under which an
-active Build resumes.
+active Build continues.
diff --git a/packages/store-sqlite/src/store.ts b/packages/store-sqlite/src/store.ts
index 952026dc..4af50240 100644
--- a/packages/store-sqlite/src/store.ts
+++ b/packages/store-sqlite/src/store.ts
@@ -657,21 +657,44 @@ class SqliteBuildDispatchStore implements BuildDispatchStore {
async requestCancellation(build: string, reason?: string, now = Date.now()): Promise<BuildDispatchSnapshot> {
nonNegativeInteger(now, "cancellation request time");
- const updated = this.#database.prepare(`
- UPDATE svml_dispatches
- SET revision = revision + 1, updated_at = ?, admission = 'closing',
- cancel_requested_at = COALESCE(cancel_requested_at, ?),
- cancel_reason = COALESCE(cancel_reason, ?),
- available_at = CASE WHEN phase = 'leased' THEN available_at ELSE MIN(available_at, ?) END,
- wake_at = CASE WHEN phase = 'leased' THEN MIN(COALESCE(wake_at, ?), ?) ELSE wake_at END
- WHERE build_id = ? AND phase != 'terminal'
- `).run(now, now, reason ?? null, now, now, now, build);
- if (updated.changes === 0) {
- const current = await this.read(build);
- if (current === undefined) throw new Error(`Dispatch ${build} does not exist`);
- return current;
- }
- return (await this.read(build))!;
+ return transaction(this.#database, () => {
+ const row = this.#database.prepare(
+ "SELECT * FROM svml_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;
+
+ // A zero fence proves that no Worker has ever owned this Build. Cancellation is therefore
+ // pure queue withdrawal: no Core command, capacity reservation or Provider Operation can
+ // exist. Resolve it in this same transaction so a racing claim has exactly one winner.
+ if (current.phase === "queued" && row.lease_fence === 0 && row.lease_owner === null) {
+ const updated = this.#database.prepare(`
+ UPDATE svml_dispatches
+ SET revision = revision + 1, updated_at = ?, admission = 'closed', phase = 'terminal',
+ terminal = 'cancelled', reason = ?, cancel_requested_at = ?, cancel_reason = ?,
+ wake_at = NULL, lease_owner = NULL, lease_token = NULL, lease_expires_at = NULL
+ WHERE build_id = ? AND phase = 'queued' AND lease_fence = 0 AND lease_owner IS NULL
+ `).run(now, reason ?? "cancelled before dispatch", now, reason ?? null, build);
+ assert(updated.changes === 1, `Dispatch ${build} cancellation lost its transaction`);
+ } else {
+ const updated = this.#database.prepare(`
+ UPDATE svml_dispatches
+ SET revision = revision + 1, updated_at = ?, admission = 'closing',
+ cancel_requested_at = COALESCE(cancel_requested_at, ?),
+ cancel_reason = COALESCE(cancel_reason, ?),
+ available_at = CASE WHEN phase = 'leased' THEN available_at ELSE MIN(available_at, ?) END,
+ wake_at = CASE WHEN phase = 'leased' THEN MIN(COALESCE(wake_at, ?), ?) ELSE wake_at END
+ WHERE build_id = ? AND phase != 'terminal'
+ `).run(now, now, reason ?? null, now, now, now, build);
+ assert(updated.changes === 1, `Dispatch ${build} cancellation lost its transaction`);
+ }
+ const result = this.#database.prepare(
+ "SELECT * FROM svml_dispatches WHERE build_id = ?",
+ ).get(build) as Row | undefined;
+ assert(result !== undefined, `Dispatch ${build} disappeared after cancellation`);
+ return parseDispatchSnapshot(result);
+ });
}
async wake(build: string, now = Date.now()): Promise<BuildDispatchSnapshot> {
diff --git a/packages/store-sqlite/test/store.test.ts b/packages/store-sqlite/test/store.test.ts
index c6439d2d..2c354bd3 100644
--- a/packages/store-sqlite/test/store.test.ts
+++ b/packages/store-sqlite/test/store.test.ts
@@ -7,6 +7,7 @@ import test from "node:test";
import { digestOf } from "@narratage/core";
import {
createBuildDispatchIdentity,
+ nonTerminalDispatchPhases,
operationCancellationRequestId,
sealOperationIdentity,
} from "@narratage/runtime";
@@ -265,6 +266,40 @@ test("SQLite fences expired Workers and shares capacity across Build dispatches"
}
});
+test("cancelling a never-claimed Build atomically withdraws it from dispatch", async () => {
+ const directory = await mkdtemp(join(tmpdir(), "svml-sqlite-cancel-queued-"));
+ try {
+ const state = new SqliteRuntimeState(join(directory, "runtime.sqlite"));
+ const closure = digestOf("runtime:cancel-queued");
+ await state.dispatch.create(createBuildDispatchIdentity({
+ build: "queued-build",
+ core: digestOf("core:queued-build"),
+ runtimeClosure: closure,
+ }), { now: 100 });
+
+ const cancelled = await state.dispatch.requestCancellation("queued-build", "no longer needed", 101);
+ assert.equal(cancelled.phase, "terminal");
+ assert.equal(cancelled.admission, "closed");
+ assert.equal(cancelled.terminal, "cancelled");
+ assert.equal(cancelled.cancellation?.requestedAt, 101);
+ assert.equal(cancelled.cancellation?.reason, "no longer needed");
+ assert.equal(await state.dispatch.claim({
+ runtimeClosure: closure,
+ owner: "worker",
+ token: "lease",
+ now: 102,
+ leaseMs: 1_000,
+ }), undefined, "a cancelled queued Build can never be claimed");
+ assert.deepEqual(await state.dispatch.list({ phases: nonTerminalDispatchPhases }), []);
+
+ const repeated = await state.dispatch.requestCancellation("queued-build", "second reason", 103);
+ assert.deepEqual(repeated, cancelled, "terminal cancellation is idempotent");
+ state.close();
+ } finally {
+ await rm(directory, { recursive: true, force: true });
+ }
+});
+
test("one SQLite execution domain rejects a second Runtime Closure until prior work is terminal", async () => {
const directory = await mkdtemp(join(tmpdir(), "svml-sqlite-revision-gate-"));
try {
diff --git a/packages/video-cli/README.md b/packages/video-cli/README.md
index 62215f04..e5c8f5ba 100644
--- a/packages/video-cli/README.md
+++ b/packages/video-cli/README.md
@@ -11,21 +11,20 @@ the corresponding physical package. They never grant network, credential or proc
From the repository:
```bash
-node --run narratage -- packages sync path/to/build.svrun \
- --runtime ./svml.runtime.json --root .
-node --run narratage -- check path/to/main.svml --runtime ./svml.runtime.json --root .
-node --run narratage -- plan path/to/build.svrun --runtime ./svml.runtime.json --root .
-node --run narratage -- build path/to/build.svrun \
- --runtime ./svml.runtime.json --build-id delivery-01 --follow --root .
-node --run narratage -- status <build-id> --runtime ./svml.runtime.json
-node --run narratage -- builds --runtime ./svml.runtime.json
-node --run narratage -- history [source-output-name] --runtime ./svml.runtime.json [--source ./main.svml]
-node --run narratage -- inspect <build-id> --runtime ./svml.runtime.json
-node --run narratage -- get <build-id> --name final.video --runtime ./svml.runtime.json --to ./final.mp4
-node --run narratage -- cancel build <build-id> --runtime ./svml.runtime.json
-node --run narratage -- cancel operation <operation-id> --runtime ./svml.runtime.json
-node --run narratage -- doctor ./svml.runtime.json
-node --run narratage -- gc ./svml.runtime.json
+cd path/to/project
+/path/to/narratage/narratage runtime use svml.runtime.json
+/path/to/narratage/narratage packages sync build.svrun
+/path/to/narratage/narratage check main.svml
+/path/to/narratage/narratage plan build.svrun
+/path/to/narratage/narratage build build.svrun --follow
+/path/to/narratage/narratage status <build-id>
+/path/to/narratage/narratage builds
+/path/to/narratage/narratage history [source-output-name] [--source ./main.svml]
+/path/to/narratage/narratage inspect <build-id>
+/path/to/narratage/narratage get <build-id> --name final.video --to ./final.mp4
+/path/to/narratage/narratage cancel <build-id>
+/path/to/narratage/narratage doctor
+/path/to/narratage/narratage gc
```
From a separate project directory during source development, run
@@ -47,9 +46,9 @@ Source because an Author Graph without execution intent is not a Build. The live
the explicit Vertex Gemini Caption package and real local/remote Endpoints; the CLI never
fabricates a Target, Candidate or missing fact.
-`build` compiles the same locked BuildState and passes it to a trusted local Runtime Profile.
-The default Build identity is content-derived, so the same invocation resumes durable local state;
-`--build-id take-02` names an explicit take. JSON Profiles resolve only adapters in their separately
+`build` compiles the locked BuildState and passes it to a trusted local Runtime Profile with a fresh,
+automatically assigned execution id. Source or Plan identity never reclaims an earlier Build; reuse
+across Builds exists only through explicit Run Source Candidates. JSON Profiles resolve only adapters in their separately
verified `runtimePackageLock` and contain no executable callback. The CLI imports no Provider;
loaded Runtime implementation identity is rebound to the actual package bytes. A TypeScript config
module remains trusted deployment code with normal Node authority. Neither form is discovered from
@@ -57,10 +56,10 @@ a 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
-`--max-wait-ms`; Ctrl-C only detaches that observer. `status` reads durable verified state. Scoped
-Build/Operation cancellation records control separately from execution, continues reconciliation
-after `accepted` or `unsupported`, and never selects another Candidate. None of these commands
-creates or stores a ready-Command queue.
+`--max-wait-ms`; Ctrl-C only detaches that observer. `status` reads durable verified state. The CLI
+controls Builds, not individual Operations. Cancelling a Build atomically withdraws it before claim,
+or closes admission and continues Provider cancellation reconciliation after claim. It never selects
+another 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
diff --git a/packages/video-cli/test/cli.test.ts b/packages/video-cli/test/cli.test.ts
index cd9b3bdc..fb5d74be 100644
--- a/packages/video-cli/test/cli.test.ts
+++ b/packages/video-cli/test/cli.test.ts
@@ -434,7 +434,6 @@ test("one locked provider-free Build executes the checked-in Frame graph", async
await runVideoCli([
"build", join(fixture, "frame-smoke.svrun"),
"--runtime", profile,
- "--build-id", "frame-smoke",
"--follow",
"--max-wait-ms", "15000",
"--json",
@@ -804,10 +803,6 @@ test("CLI inspect and get read the durable Build archive independently of build
const control = {
async builds() { return [catalog]; },
async queue() { return { dispatches: [dispatch], capacity: [], operations: [] }; },
- async operation(id: string) { return id === operation.id ? operation : undefined; },
- async cancelOperation(id: string) {
- return id === operation.id ? { ...operation, cancellation: { status: "requested" } } : undefined;
- },
async cancel(id: string) {
return id === "archive-1"
? { build: id, phase: "terminal", admission: "closed", terminal: "complete" }
@@ -924,8 +919,11 @@ test("CLI inspect and get read the durable Build archive independently of build
write: (text) => { statusOutput += text; },
});
const status = JSON.parse(statusOutput) as {
+ readonly build: { readonly status: string; readonly coreStatus: string };
readonly catalog: { readonly aliasCount: number; readonly targets: readonly string[] };
};
+ assert.equal(status.build.status, "waiting");
+ assert.equal(status.build.coreStatus, "active");
assert.deepEqual(status.catalog, {
source: catalog.source,
run: catalog.run,
@@ -938,12 +936,6 @@ test("CLI inspect and get read the durable Build archive independently of build
const queue = JSON.parse(queueOutput) as { readonly dispatches: readonly { readonly phase: string }[] };
assert.equal(queue.dispatches[0]?.phase, "waiting");
- let operationOutput = "";
- await runArchiveCli(["operation", operationId, "--runtime", runtimePath], {
- write: (text) => { operationOutput += text; },
- });
- assert.equal((JSON.parse(operationOutput) as { readonly operation?: { readonly id: string } }).operation?.id, operationId);
-
let getOutput = "";
await runArchiveCli([
"get", "archive-1", "--runtime", runtimePath,
@@ -960,26 +952,6 @@ test("CLI inspect and get read the durable Build archive independently of build
], { write() {} });
assert.deepEqual(await readFile(rawDestination), rawBytes);
- let cancellationOutput = "";
- await runArchiveCli([
- "cancel", "operation", operationId, "--runtime", runtimePath,
- "--reason", "stop this attempt",
- ], { write: (text) => { cancellationOutput += text; } });
- const cancellation = JSON.parse(cancellationOutput) as {
- readonly scope: string;
- readonly requested: boolean;
- readonly build: string;
- readonly control: string;
- };
- assert.deepEqual(cancellation, {
- scope: "operation",
- operation: operationId,
- requested: true,
- build: "archive-1",
- execution: "pending",
- control: "requested",
- });
-
const human = async (argv: readonly string[]) => {
let output = "";
await runCoreCli([...argv, "--color", "never"], { write: (text) => { output += text; } }, selected);
@@ -989,10 +961,7 @@ test("CLI inspect and get read the durable Build archive independently of build
assert.match(await human(["status", "archive-1", "--runtime", runtimePath]), /Build status[\s\S]*Dispatch\s+waiting/u);
assert.match(await human(["inspect", "archive-1", "--runtime", runtimePath]),
/Build archive detail[\s\S]*Target\s+final\.video[\s\S]*example@1\/Artifact/u);
- assert.match(await human(["operation", operationId, "--runtime", runtimePath]), /Operation detail[\s\S]*Status\s+pending/u);
- assert.match(await human(["cancel", "operation", operationId, "--runtime", runtimePath]),
- /Operation cancellation requested[\s\S]*Control\s+requested/u);
- assert.match(await human(["cancel", "build", "archive-1", "--runtime", runtimePath]),
+ assert.match(await human(["cancel", "archive-1", "--runtime", runtimePath]),
/Build already finished[\s\S]*No running work was changed; this Build is already complete/u);
await assert.rejects(
runArchiveCli(["status", "archive-1", "--runtime", runtimePath, "--watch"], { write() {} }),