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.

docs: align local developer workflows

kashorin9238ad24160c
diff --git a/README.md b/README.md
index c3f84fa9..29f5814d 100644
--- a/README.md
+++ b/README.md
@@ -95,7 +95,7 @@ Details and current gaps are maintained in
Requirements:
- Node.js 22+
-- pnpm
+- pnpm for installing and testing this source workspace
- Python 3.10–3.13 only when running the local WhisperX service
```bash
@@ -104,27 +104,38 @@ pnpm install --frozen-lockfile
pnpm check
pnpm test
+# `node --run` avoids launching pnpm for every CLI command.
# Compile a complete provider-free author graph.
-pnpm narratage check examples/talking-film-graph-check/main.svml \
+node --run narratage -- check examples/talking-film-graph-check/main.svml \
--package-lock examples/talking-film-graph-check/svml.packages.lock --root .
# Compile the self-described Run Graph and inspect its finite plan.
-pnpm narratage plan examples/talking-film-graph-check/build.svrun \
+node --run narratage -- plan examples/talking-film-graph-check/build.svrun \
--package-lock examples/talking-film-graph-check/svml.packages.lock --root .
```
+`node --run narratage -- ...` is the short form inside this checkout. To keep a real video project
+in a completely separate directory, invoke the checkout's lightweight launcher from that project:
+
+```bash
+cd /path/to/my-video
+/path/to/svml/narratage check main.svml \
+ --package-lock svml.packages.lock --package-root /path/to/svml --root .
+```
+
+The launcher does not run pnpm and does not move source, state or outputs into this repository.
+
The live example uses an explicit Run Graph, declarative local Runtime Profile and external
credentials:
```bash
-pnpm narratage build examples/talking-film-live/build.svrun \
+node --run narratage -- build examples/talking-film-live/build.svrun \
--runtime examples/talking-film-live/svml.runtime.json \
- --package-lock examples/talking-film-live/svml.packages.lock \
--root . \
--build-id talking-film-live \
--follow
-pnpm narratage get talking-film-live \
+node --run narratage -- get talking-film-live \
--name final.video \
--runtime examples/talking-film-live/svml.runtime.json \
--to examples/talking-film-live/output/final.mp4
diff --git a/docs/README.md b/docs/README.md
index 5cbfe888..bf50038f 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -32,6 +32,8 @@ the working tree contains only documents that should inform current implementati
command hierarchy, visual language and decentralized Endpoint authentication.
- [`runtime-adapter-loading.md`](./runtime-adapter-loading.md) — separately locked Provider
and Store activation, physical-code identity, diagnostics and explicit Artifact maintenance.
+- [`validation-boundaries.md`](./validation-boundaries.md) — the single-owner validation gates;
+ what is mandatory, what stays optional and what must never be revalidated downstream.
- [`build-archive-and-egress.md`](./build-archive-and-egress.md) — Targets, durable Records,
Artifact retention and optional Host materialization as four separate concerns.
- [`speech-alignment.md`](./speech-alignment.md) — the Script and the recording as two
diff --git a/docs/guide/author-packages.md b/docs/guide/author-packages.md
index 1ca4ae6e..2e0c69b7 100644
--- a/docs/guide/author-packages.md
+++ b/docs/guide/author-packages.md
@@ -131,7 +131,7 @@ Add the path mapping so TypeScript resolves `@narratage/my-component` to source:
```bash
pnpm install --frozen-lockfile
-pnpm narratage lock-packages <lock-file> \
+node --run narratage -- lock-packages <lock-file> \
--package @narratage/my-component \
[--package @narratage/other-direct-package ...] \
--package-root .
@@ -141,6 +141,18 @@ Only name direct packages you chose. Exact logical Module dependencies declared
are added from the installed physical dependency closure automatically; missing or ambiguous
providers make lock creation fail.
+For an existing lock, add only this direct package without repeating the other selections:
+
+```bash
+node --run narratage -- lock-packages <lock-file> \
+ --add @narratage/my-component \
+ --package-root .
+```
+
+Use `--remove` for an explicit revocation, `--refresh` to accept changed bytes for the unchanged
+selection, and `--verify` for a read-only closure check. Repeated `--package` always means the exact
+complete direct selection.
+
## 8. Use in Author Source
```xml
diff --git a/docs/guide/providers.md b/docs/guide/providers.md
index b3d46d5a..27b63785 100644
--- a/docs/guide/providers.md
+++ b/docs/guide/providers.md
@@ -90,26 +90,20 @@ import { createMyServiceProvider } from "./provider.js";
const adapter = createRuntimeEndpointAdapterFacet({
use: "@narratage/provider-my-service",
- validate(context) {
+ activate(context) {
const config = runtimeConfigObject(context.config, "MyService");
runtimeConfigExact(config, ["apiKey", "defaultConcurrency"], "MyService");
- if (runtimeConfigCredentialRef(config.apiKey, "MyService apiKey") === undefined) {
- throw new Error("MyService apiKey CredentialRef is required");
- }
- runtimeConfigPositiveInteger(config.defaultConcurrency, "concurrency");
- },
-
- create(context) {
- const config = runtimeConfigObject(context.config, "MyService");
const apiKey = runtimeConfigCredentialRef(config.apiKey, "MyService apiKey");
if (apiKey === undefined) throw new Error("MyService apiKey CredentialRef is required");
- return createMyServiceProvider({
- instance: context.instance,
- lane: context.lane,
- apiKey,
- ...(runtimeConfigPositiveInteger(config.defaultConcurrency, "concurrency") === undefined
- ? {} : { defaultConcurrency: config.defaultConcurrency as number }),
- });
+ const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "concurrency");
+ return {
+ endpoint: createMyServiceProvider({
+ instance: context.instance,
+ lane: context.lane,
+ apiKey,
+ ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
+ }),
+ };
},
});
@@ -122,9 +116,12 @@ export const svmlPackage = {
export default svmlPackage;
```
-`validate` is pure and runs before authority is granted. `create` constructs the Endpoint only
-after the profile, lock and permissions pass. Credential presence is diagnosed through the generic
-CredentialStore/Endpoint description path; a Provider must not special-case environment variables.
+`activate` is the one pure deployment declaration. The Endpoint it returns owns the credential
+references, permissions, capabilities and scheduling facts used by both `doctor` and execution.
+Activation must not resolve secrets or environment-sourced deployment values, access the network or
+start work. It keeps environment names as references until a matching Need is handled. Credential
+presence is diagnosed through the generic CredentialStore path; a Provider must not special-case
+environment variables as a secret Store.
## 5. Declare an external service (if needed)
@@ -148,19 +145,24 @@ export function createMyExternalService(): RuntimeExternalService {
}
```
-Wire it into the activation descriptor by passing `service` to `createRuntimeEndpointAdapterFacet`:
+Return it beside the Endpoint from the same activation:
```typescript
const adapter = createRuntimeEndpointAdapterFacet({
use: "@narratage/provider-my-service",
- service: createMyExternalService,
- // create, doctor …
+ activate(context) {
+ return {
+ endpoint: createMyServiceProvider(/* parsed config */),
+ externalService: createMyExternalService(),
+ };
+ },
});
```
`narratage runtime up` prepares, starts and probes declared external programs before starting the
-durable Worker. `build` ensures that Runtime is running before submission. Providers that call only
-remote APIs omit this step entirely—leave `"service"` out of `package.json`.
+durable Worker. `build` starts only services backing capabilities declared by its selected Producer
+steps. Providers that call only remote APIs omit this step entirely—leave `"service"` out of
+`package.json`.
## 6. Register and lock
@@ -173,11 +175,15 @@ Add the path mapping to `tsconfig.json`:
Lock into a Runtime package lock:
```bash
-pnpm narratage lock-packages <runtime-lock> \
+node --run narratage -- lock-packages <runtime-lock> \
--package @narratage/provider-my-service \
--package-root .
```
+If the Runtime lock already exists, use `--add @narratage/provider-my-service` instead. This changes
+only the local trust selection; the package remains inert until the Runtime Profile explicitly
+instantiates its `use` id.
+
## 7. Reference from svml.runtime.json
```json
@@ -202,7 +208,7 @@ pnpm narratage lock-packages <runtime-lock> \
Verify the configuration:
```bash
-pnpm narratage doctor svml.runtime.json
+node --run narratage -- doctor svml.runtime.json
```
## Existing Providers to study
diff --git a/docs/guide/runtime-profile.md b/docs/guide/runtime-profile.md
index fa6c67f7..30d38a5a 100644
--- a/docs/guide/runtime-profile.md
+++ b/docs/guide/runtime-profile.md
@@ -224,8 +224,8 @@ export default async function createRuntime() {
Pass either form to `--runtime`:
```bash
-pnpm narratage build build.svrun --runtime ./svml.runtime.json
-pnpm narratage build build.svrun --runtime ./svml.runtime.ts
+node --run narratage -- build build.svrun --runtime ./svml.runtime.json
+node --run narratage -- build build.svrun --runtime ./svml.runtime.ts
```
Both forms describe the same explicit assembly. The TypeScript form is trusted embedding code, not
@@ -238,7 +238,7 @@ a source-language escape hatch or a place for author intent.
Checks the Runtime Profile without running a Build or making paid requests:
```bash
-pnpm narratage doctor svml.runtime.json
+node --run narratage -- doctor svml.runtime.json
```
Validates:
@@ -249,30 +249,45 @@ Validates:
- Required executables (ffmpeg, ffprobe, chrome) are found
- Declared external services are reachable and match the selected profile
-Runtime Adapter Host ABI `@1` separates a required pure configuration validator from the adapter
-factory. `doctor` never constructs an Endpoint or Store, starts a service, writes Runtime state or
-submits work. After configuration passes it may make bounded read-only environment probes. The first
-configuration or prerequisite failure for one instance suppresses diagnostics that merely result
-from that same failure.
+Runtime Adapter Host ABI `@1` gives each Endpoint one pure activation declaration. `doctor` evaluates
+that declaration and reads credentials, permissions and prerequisites from the resulting Endpoint
+package; there is no diagnostic-only credential mirror. Activation may construct handlers but may
+not resolve credentials, access the network, start a process or mutate durable state. `doctor` never
+constructs a Scheduler, Worker, Build Store or author package, starts a service, writes Runtime state
+or submits work. It opens only the CredentialStore adapters selected by the Profile, then closes
+them, and may run explicitly declared bounded read-only probes.
+
+### Credential control is not Runtime execution
+
+`auth status|login|logout <endpoint-instance>` constructs only that exact Endpoint declaration and
+the CredentialStores selected by the Profile. It does not open SQLite, start a Worker, load author
+packages or construct unrelated Providers. Logging into KIE therefore cannot be blocked by an old
+Build database or an unrelated Vertex configuration.
## Runtime lifecycle
```bash
-pnpm narratage runtime up svml.runtime.json
-pnpm narratage runtime status svml.runtime.json
-pnpm narratage runtime logs svml.runtime.json
-pnpm narratage runtime down 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
```
`runtime up` owns the detached Worker plus declared external programs. `services` remains a narrow
expert command for those external programs only. A Build submission ensures the Runtime is up, but
the Build terminal never owns execution.
+During the pre-release period SQLite execution schemas are intentionally not migrated in place.
+If a development database predates the selected Store implementation, the CLI names the exact path
+and asks the operator to archive that database (including its WAL companions) or select a new path.
+Artifact bytes live in the independently selected ArtifactStore and are never deleted by this
+refusal.
+
### gc (garbage collection)
```bash
-pnpm narratage gc svml.runtime.json # dry-run
-pnpm narratage gc svml.runtime.json --apply # delete unreachable Artifacts
+node --run narratage -- gc svml.runtime.json # dry-run
+node --run narratage -- gc svml.runtime.json --apply # delete unreachable Artifacts
```
Walks every retained BuildState and Operation, computes reachable Artifact digests, and reports
@@ -286,13 +301,13 @@ Every Build archives all accepted Records and referenced Artifacts durably, inde
### List Builds
```bash
-pnpm narratage builds --runtime svml.runtime.json
+node --run narratage -- builds --runtime svml.runtime.json
```
### Inspect
```bash
-pnpm narratage inspect <build-id> --runtime svml.runtime.json
+node --run narratage -- inspect <build-id> --runtime svml.runtime.json
```
Shows target bindings, demanded Logical Outputs, every accepted Record and Operation status.
@@ -301,19 +316,19 @@ Shows target bindings, demanded Logical Outputs, every accepted Record and Opera
```bash
# By source output name
-pnpm narratage get <build-id> --runtime svml.runtime.json \
+node --run narratage -- get <build-id> --runtime svml.runtime.json \
--name final.video --to output.mp4
# By Record id
-pnpm narratage get <build-id> --runtime svml.runtime.json \
+node --run narratage -- get <build-id> --runtime svml.runtime.json \
--record <record-id> --to output.json
# By Logical Output id
-pnpm narratage get <build-id> --runtime svml.runtime.json \
+node --run narratage -- get <build-id> --runtime svml.runtime.json \
--output <output-id>
# By Artifact digest
-pnpm narratage get <build-id> --runtime svml.runtime.json \
+node --run narratage -- get <build-id> --runtime svml.runtime.json \
--artifact <sha256:...> --to file.bin
```
diff --git a/docs/guide/services.md b/docs/guide/services.md
index 3ae5c303..6681a9fa 100644
--- a/docs/guide/services.md
+++ b/docs/guide/services.md
@@ -10,15 +10,19 @@ Two lifecycle scopes are deliberately separate.
## Runtime execution domain
```bash
-pnpm narratage runtime up svml.runtime.json
-pnpm narratage runtime status svml.runtime.json
-pnpm narratage runtime logs svml.runtime.json
-pnpm narratage runtime down 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
```
`runtime up` starts or reuses the detached fenced Worker and also prepares/starts the external
programs declared by selected adapters. The process identity, profile digest and log path are
project-scoped. Repeating `runtime up` does not create a second Worker for the same domain.
+Independent external programs are prepared concurrently. The human CLI prints each bounded phase
+(`Checking`, `Preparing`, `Starting`, `Waiting`, `Ready`) so a first WhisperX model preparation or
+browser installation is visible instead of looking like a frozen command. JSON output remains one
+clean final document.
`runtime status` combines:
@@ -38,9 +42,9 @@ is brought up again.
## External programs only
```bash
-pnpm narratage services up svml.runtime.json
-pnpm narratage services status svml.runtime.json
-pnpm narratage services down svml.runtime.json
+node --run narratage -- services up svml.runtime.json
+node --run narratage -- services status svml.runtime.json
+node --run narratage -- services down svml.runtime.json
```
`services` is an expert/debugging command. It never starts the Worker and never reads or mutates a
@@ -56,33 +60,45 @@ Remote-only Endpoints such as KIE have no local service.
## Build relationship
```bash
-pnpm narratage build build.svrun --runtime svml.runtime.json
-pnpm narratage build build.svrun --runtime svml.runtime.json --follow
+node --run narratage -- build build.svrun --runtime svml.runtime.json
+node --run narratage -- build build.svrun --runtime svml.runtime.json --follow
```
-Before submission, `build` validates the profile and ensures its Runtime is up. The Build command
+Before submission, `build` derives the capabilities declared by the selected Producer steps and
+prepares only external programs backing those capabilities. A text-only or Estimate-only Target
+therefore does not load WhisperX merely because the Profile also offers it. This selection changes
+no graph edge and does not route Providers; it only avoids starting unrelated deployment programs.
+Concurrent launches are serialized per Profile, so they share one Worker and one managed instance
+of each demanded external service. The Build command
then stores one verified Build plus dispatch ticket. Without `--follow` it exits immediately after
-submission. `--follow` observes durable state only; Ctrl-C detaches the observer and leaves the
-Worker running.
+submission. `--follow` observes durable state only and prints a line when the Build phase or
+Operation revision/progress changes; if that Worker stops, it fails with a restart command instead
+of waiting forever. Ctrl-C detaches the observer and leaves the Worker running.
`--no-services` skips automatic external-program startup for an operator who already owns those
programs, but it does not create implicit Runtime services or move execution back into the CLI.
+Explicit `runtime up` and `services up` still operate the complete Profile because their subject is
+the deployment, not one Build.
+
## Visibility
```bash
-pnpm narratage queue --runtime svml.runtime.json
-pnpm narratage queue --runtime svml.runtime.json --watch
-pnpm narratage status <build-id> --runtime svml.runtime.json
-pnpm narratage operations <build-id> --runtime svml.runtime.json
-pnpm narratage operation <operation-id> --runtime svml.runtime.json
+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
```
-These views expose durable dispatch phase, lease/capacity facts, Operation attempts, checkpoints and
-cancellation state. They do not reconstruct a secret second graph or ask a Provider for creative
+These views expose the active durable dispatch set, Worker state, lease/capacity facts, Operation
+attempts, generic Endpoint progress, checkpoints and cancellation state. They do not reconstruct a
+secret second graph or ask a Provider for creative
routing.
-Use `--json` for one versioned result and `--jsonl` for a watch stream.
+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.
## WhisperX
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 6c3f922c..cdf40587 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -18,7 +18,8 @@ been published to npm yet.
## Install
-Requires Node.js 22+ and pnpm.
+Requires Node.js 22+ and pnpm for installing/testing this source workspace. The ordinary CLI
+examples use Node's built-in script runner so each command does not launch pnpm again.
```bash
corepack enable
@@ -27,6 +28,11 @@ pnpm check
pnpm test
```
+Inside the source checkout, commands use `node --run narratage -- ...`. A project outside this
+repository uses `/path/to/svml/narratage ...` plus `--package-root /path/to/svml`; the checked-in
+launcher starts the same CLI directly without pnpm, and all project state stays under that external
+project's Runtime Profile root.
+
## Three inputs
Every Build takes three separate inputs:
@@ -45,10 +51,10 @@ The `talking-film-graph-check` example compiles a complete video graph — Scrip
WhisperX, Gemini Caption, Media Track, Text, Film, HyperFrames — without calling any external service.
```bash
-pnpm narratage check examples/talking-film-graph-check/main.svml \
+node --run narratage -- check examples/talking-film-graph-check/main.svml \
--package-lock examples/talking-film-graph-check/svml.packages.lock --root .
-pnpm narratage plan examples/talking-film-graph-check/build.svrun \
+node --run narratage -- plan examples/talking-film-graph-check/build.svrun \
--package-lock examples/talking-film-graph-check/svml.packages.lock --root .
```
diff --git a/docs/quickstart/composition.md b/docs/quickstart/composition.md
index bbd514b6..a75409dc 100644
--- a/docs/quickstart/composition.md
+++ b/docs/quickstart/composition.md
@@ -242,10 +242,10 @@ The complete data flow from Script to rendered video. This example is based on
### Compile and verify
```bash
-pnpm narratage check examples/talking-film-graph-check/main.svml \
+node --run narratage -- check examples/talking-film-graph-check/main.svml \
--package-lock examples/talking-film-graph-check/svml.packages.lock --root .
-pnpm narratage plan examples/talking-film-graph-check/build.svrun \
+node --run narratage -- plan examples/talking-film-graph-check/build.svrun \
--package-lock examples/talking-film-graph-check/svml.packages.lock --root .
```
diff --git a/docs/quickstart/run.md b/docs/quickstart/run.md
index 85f9a028..6ee2a27f 100644
--- a/docs/quickstart/run.md
+++ b/docs/quickstart/run.md
@@ -114,6 +114,41 @@ historical Records as zero-input Candidates and connect them through Satisfactio
</svrun>
```
+### Finding reusable output
+
+Query an output name as it appeared in each historical Build's frozen Host Catalog:
+
+```bash
+node --run narratage -- history hook-take.video \
+ --runtime ./svml.runtime.json
+```
+
+`history` reports only public Logical Outputs that the Build actually selected and accepted. It
+does not list merely declared-but-unbuilt aliases or authored Record aliases that cannot back a
+`build-record` Candidate. If the old name is unknown, list accepted output names from Builds whose
+Catalog recorded an exact source path:
+
+```bash
+node --run narratage -- history --source ./main.svml \
+ --runtime ./svml.runtime.json
+```
+
+An output name is a human locator inside one immutable historical Catalog, not its identity. The
+historical Core Build, Logical Output and Record digests carry identity. If the current source
+renames `hook-take.video` to `opening-shot.video`, keep the old name on `<build-record>` and use the
+current name on `<satisfy>`:
+
+```svml
+<build-record id="approved-opening"
+ build="my-film-001" output="hook-take.video"/>
+<satisfy output="opening-shot.video"
+ candidate="approved-opening" fidelity="substitute"/>
+```
+
+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.
+
### build-record
Declares a zero-input Candidate backed by a historical Record from a previous Build:
@@ -272,9 +307,11 @@ prevent one type of work from starving others.
pnpm install
```
-This installs Node dependencies **and** prepares the Python services (WhisperX, OpenCV) that local
-Builds need. When `uv` is not on your PATH the Python step is skipped with a warning — install
-[uv](https://docs.astral.sh/uv/) first if you need local alignment or image processing.
+This installs only the JavaScript workspace. It does not download Python models or prepare every
+Provider found in the repository. `runtime up` / `services up` reads the selected Runtime Profile
+and prepares only the external programs its chosen Endpoints declare. Install
+[uv](https://docs.astral.sh/uv/) first only when that Profile selects a local Python service such as
+WhisperX or OpenCV.
`narratage runtime up` starts the durable Worker and the external programs declared by the selected
adapters. `build` also ensures that execution domain is running before it submits, but never owns
@@ -288,12 +325,12 @@ Author files do not have to live under this repository. For example, keep a proj
```bash
cd /opt/narratage
-pnpm narratage lock-packages /work/my-film/svml.packages.lock \
+node --run narratage -- lock-packages /work/my-film/svml.packages.lock \
--package @narratage/script \
--package @narratage/estimate
-pnpm narratage plan /work/my-film/build.svrun \
- --package-lock /work/my-film/svml.packages.lock
+node --run narratage -- plan /work/my-film/build.svrun \
+ --runtime /work/my-film/svml.runtime.json
```
The Source Workspace defaults to the directory containing `build.svrun`; its relative Author
@@ -343,7 +380,7 @@ other than the CLI installation.
### 1. Diagnose the environment
```bash
-pnpm narratage doctor examples/talking-head-aroll/svml.runtime.json
+node --run narratage -- doctor examples/talking-head-aroll/svml.runtime.json
```
Doctor validates both locks, every selected Runtime role, Endpoint configuration, credential
@@ -352,8 +389,8 @@ presence and bounded environment probes. It never starts the Worker or performs
### 2. Inspect the plan
```bash
-pnpm narratage plan examples/talking-head-aroll/build.svrun \
- --package-lock examples/talking-head-aroll/svml.packages.lock --root .
+node --run narratage -- plan examples/talking-head-aroll/build.svrun \
+ --runtime examples/talking-head-aroll/svml.runtime.json --root .
```
Review the frozen BuildPlan before spending money. The plan shows every Operation and Needs the
@@ -362,37 +399,49 @@ Scheduler would issue.
### 3. Submit the Build
```bash
-pnpm narratage build examples/talking-head-aroll/build.svrun \
+node --run narratage -- build examples/talking-head-aroll/build.svrun \
--runtime examples/talking-head-aroll/svml.runtime.json \
- --package-lock examples/talking-head-aroll/svml.packages.lock \
--root . \
--build-id my-film-001 \
--follow
```
Without `--follow`, `build` returns after durable submission. The detached Worker continues. With
-`--follow`, the terminal is only an observer; interrupting it leaves the Build running.
+`--follow`, the terminal is only an observer; it reports durable phase/Operation-count changes and
+interrupting it leaves the Build running.
| Flag | Description |
|---|---|
| `--runtime` | Path to the Runtime Profile |
-| `--package-lock` | Path to the package lock file |
+| `--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 boundary; defaults to the entry Source directory |
| `--build-id` | User-chosen identifier for this Build (used for retrieval and reuse) |
-| `--follow` | Stream Build progress to the terminal |
+| `--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.
### 4. Retrieve results
```bash
-pnpm narratage get my-film-001 \
+node --run narratage -- get my-film-001 \
--runtime examples/talking-head-aroll/svml.runtime.json \
--name final.video \
--to examples/talking-head-aroll/output/final.mp4
```
Every accepted intermediate Record and Artifact is archived before the Build completes. `get` makes
-a copy of an already durable Record.
+a copy of an already durable Record. Blob Artifacts are streamed from the selected Store, checked
+against their declared size and SHA-256 digest, and only then atomically replace the destination;
+exporting a large MP4 does not buffer the complete file in CLI memory.
+
+The terminal Build result prints the exact `get --name …` command for every targeted source alias;
+there is no need to inspect opaque Record ids just to export `final.video`.
### 5. Reuse in a new Build
@@ -400,8 +449,7 @@ Create a new `.svrun` file that references the completed Build's Records (see [R
above), then submit it:
```bash
-pnpm narratage build examples/talking-head-aroll/reuse-generated.svrun \
+node --run narratage -- build examples/talking-head-aroll/reuse-generated.svrun \
--runtime examples/talking-head-aroll/svml.runtime.json \
- --package-lock examples/talking-head-aroll/svml.packages.lock \
--root . --build-id my-film-reuse-001 --follow
```
diff --git a/docs/zh/guide/author-packages.md b/docs/zh/guide/author-packages.md
index b549ce6c..a9ba622d 100644
--- a/docs/zh/guide/author-packages.md
+++ b/docs/zh/guide/author-packages.md
@@ -126,7 +126,7 @@ export default svmlPackage;
```bash
pnpm install --frozen-lockfile
-pnpm narratage lock-packages <lock-file> \
+node --run narratage -- lock-packages <lock-file> \
--package @narratage/my-component \
[--package @narratage/other-direct-package ...] \
--package-root .
@@ -135,6 +135,17 @@ pnpm narratage lock-packages <lock-file> \
这里只列出你直接选择的包。它们的 Manifest 声明的精确逻辑 Module 依赖,会从已安装的
物理依赖闭包中自动加入;缺失、摘要不匹配或存在多个候选时,建锁会直接失败。
+已有锁只需增加这个直接包时,不必重写其他选择:
+
+```bash
+node --run narratage -- lock-packages <lock-file> \
+ --add @narratage/my-component \
+ --package-root .
+```
+
+`--remove` 明确撤销一个直接选择,`--refresh` 在选择不变时接受当前安装字节,`--verify`
+只读验证闭包。重复的 `--package` 始终表示一份完整、精确的直接选择,而不是增量添加。
+
## 8. 在 Author Source 中使用
```xml
diff --git a/docs/zh/guide/providers.md b/docs/zh/guide/providers.md
index abe963b5..72a50018 100644
--- a/docs/zh/guide/providers.md
+++ b/docs/zh/guide/providers.md
@@ -86,26 +86,20 @@ import { createMyServiceProvider } from "./provider.js";
const adapter = createRuntimeEndpointAdapterFacet({
use: "@narratage/provider-my-service",
- validate(context) {
+ activate(context) {
const config = runtimeConfigObject(context.config, "MyService");
runtimeConfigExact(config, ["apiKey", "defaultConcurrency"], "MyService");
- if (runtimeConfigCredentialRef(config.apiKey, "MyService apiKey") === undefined) {
- throw new Error("MyService apiKey CredentialRef is required");
- }
- runtimeConfigPositiveInteger(config.defaultConcurrency, "concurrency");
- },
-
- create(context) {
- const config = runtimeConfigObject(context.config, "MyService");
const apiKey = runtimeConfigCredentialRef(config.apiKey, "MyService apiKey");
if (apiKey === undefined) throw new Error("MyService apiKey CredentialRef is required");
- return createMyServiceProvider({
- instance: context.instance,
- lane: context.lane,
- apiKey,
- ...(runtimeConfigPositiveInteger(config.defaultConcurrency, "concurrency") === undefined
- ? {} : { defaultConcurrency: config.defaultConcurrency as number }),
- });
+ const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "concurrency");
+ return {
+ endpoint: createMyServiceProvider({
+ instance: context.instance,
+ lane: context.lane,
+ apiKey,
+ ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
+ }),
+ };
},
});
@@ -118,8 +112,10 @@ export const svmlPackage = {
export default svmlPackage;
```
-`validate` 是无副作用的纯校验;通过 Profile、lock 与权限校验后才会调用 `create`。凭据是否
-存在由通用 CredentialStore 与 Endpoint 描述路径诊断,Provider 不得硬编码环境变量 Store。
+`activate` 是唯一的纯部署声明。它返回的 Endpoint 同时拥有供 `doctor` 与执行使用的凭据引用、
+权限、capability 和调度事实。Activation 不得解析密钥或环境来源的部署值、访问网络或启动任务;
+环境变量名会作为引用保留到真正处理匹配 Need 时。凭据是否存在由通用 CredentialStore 路径诊断,
+Provider 不得把环境变量硬编码成特殊的密钥 Store。
## 5. 声明外部服务(如需要)
@@ -142,18 +138,22 @@ export function createMyExternalService(): RuntimeExternalService {
}
```
-在 activation 描述符中通过 `service` 参数接入:
+在同一个 activation 中把它与 Endpoint 一起返回:
```typescript
const adapter = createRuntimeEndpointAdapterFacet({
use: "@narratage/provider-my-service",
- service: createMyExternalService,
- // create, doctor …
+ activate(context) {
+ return {
+ endpoint: createMyServiceProvider(/* 已解析配置 */),
+ externalService: createMyExternalService(),
+ };
+ },
});
```
-`narratage runtime up` 会准备、启动并探测外部程序,然后启动耐久 Worker。`build` 会确保
-Runtime 已运行。只调用远程 API 的 Provider 不声明 service。
+`narratage runtime up` 会准备、启动并探测外部程序,然后启动耐久 Worker。`build` 只启动
+所选 Producer steps 声明的 capability 所需服务。只调用远程 API 的 Provider 不声明 service。
## 6. 注册并锁定
@@ -166,11 +166,14 @@ Runtime 已运行。只调用远程 API 的 Provider 不声明 service。
锁定进 Runtime 包锁文件:
```bash
-pnpm narratage lock-packages <runtime-lock> \
+node --run narratage -- lock-packages <runtime-lock> \
--package @narratage/provider-my-service \
--package-root .
```
+如果 Runtime 包锁已经存在,改用 `--add @narratage/provider-my-service`。这一步只改变本地
+信任选择;在 Runtime Profile 用 `use` 显式实例化之前,这个包仍然不会运行。
+
## 7. 在 svml.runtime.json 中引用
```json
@@ -195,7 +198,7 @@ pnpm narratage lock-packages <runtime-lock> \
验证配置:
```bash
-pnpm narratage doctor svml.runtime.json
+node --run narratage -- doctor svml.runtime.json
```
## 可供研究的现有 Provider
diff --git a/docs/zh/guide/runtime-profile.md b/docs/zh/guide/runtime-profile.md
index fd8b1618..a33cfd38 100644
--- a/docs/zh/guide/runtime-profile.md
+++ b/docs/zh/guide/runtime-profile.md
@@ -85,14 +85,20 @@ CLI 进程里的计数器。容量租约跟随 Build 的 fenced lease;过期 W
权限仍是显式 allowlist,例如 `network:<host>`、`filesystem:<scope>`、`process:<name>`。
+## 凭据控制不是 Runtime 执行
+
+`auth status|login|logout <endpoint-instance>` 只构造该 Endpoint 的声明和 Profile 明确选择的
+CredentialStore,不会打开 SQLite、启动 Worker、加载作者包或构造其他 Provider。因此登录
+KIE 不会被旧 Build 数据库或无关的 Vertex 配置拦住。
+
## 生命周期
```bash
-pnpm narratage doctor svml.runtime.json
-pnpm narratage runtime up svml.runtime.json
-pnpm narratage runtime status svml.runtime.json
-pnpm narratage runtime logs svml.runtime.json
-pnpm narratage runtime down svml.runtime.json
+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
```
`runtime up` 管理耐久 Worker 与声明的外部程序。`services up/status/down` 只管理外部程序,
@@ -100,17 +106,27 @@ pnpm narratage runtime down svml.runtime.json
后台进程绑定覆盖 Profile 与两份 package lock 的有效修订摘要;任一文件变化后状态变为
`stale`,下一次启动或提交会按新执行闭包替换进程,而不是继续复用旧装配。
+`doctor` 会求值 Endpoint Adapter 唯一的纯 `activate()` 声明,并直接从产生的 Endpoint package
+读取凭据、权限和前置条件;不存在另一份仅供诊断使用的凭据镜像。Activation 可以构造 handler,
+但不得解析密钥、访问网络、启动进程或修改持久状态。`doctor` 不构造 Scheduler、Worker、Build
+Store 或作者包,不会启动服务、写入 Runtime 状态或提交任务;它只打开 Profile 明确选择的
+CredentialStore 来解析引用,完成后立即关闭,并可执行显式声明的有界只读探测。
+
+预发布阶段不会原地迁移 SQLite 执行 schema。遇到更早的开发数据库时,CLI 会指出精确路径,
+要求把数据库连同 WAL 文件归档,或在 Profile 选择新路径。ArtifactStore 是独立选择的;该
+拒绝不会删除任何产物字节。
+
## Build、队列与归档
```bash
-pnpm narratage build build.svrun --runtime svml.runtime.json
-pnpm narratage build build.svrun --runtime svml.runtime.json --follow
-pnpm narratage queue --runtime svml.runtime.json --watch
-pnpm narratage status <build-id> --runtime svml.runtime.json
-pnpm narratage operations <build-id> --runtime svml.runtime.json
-pnpm narratage operation <operation-id> --runtime svml.runtime.json
-pnpm narratage inspect <build-id> --runtime svml.runtime.json
-pnpm narratage get <build-id> --runtime svml.runtime.json --name final.video --to output.mp4
+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
```
不带 `--follow` 时,`build` 在耐久提交后退出;Worker 继续执行。`--follow` 只是观察,Ctrl-C
@@ -119,8 +135,8 @@ pnpm narratage get <build-id> --runtime svml.runtime.json --name final.video --t
## 取消
```bash
-pnpm narratage cancel build <build-id> --runtime svml.runtime.json
-pnpm narratage cancel operation <operation-id> --runtime svml.runtime.json
+node --run narratage -- cancel build <build-id> --runtime svml.runtime.json
+node --run narratage -- cancel operation <operation-id> --runtime svml.runtime.json
```
Build 取消先关闭准入;Operation 取消只抑制那个精确实现。`accepted` 只是远端接受停止请求,
diff --git a/docs/zh/guide/services.md b/docs/zh/guide/services.md
index 134b292f..2fe2d7da 100644
--- a/docs/zh/guide/services.md
+++ b/docs/zh/guide/services.md
@@ -10,16 +10,20 @@ description: 管理耐久 Worker 与 Profile 明确选择的本地程序。
## 整个执行域
```bash
-pnpm narratage runtime up svml.runtime.json
-pnpm narratage runtime status svml.runtime.json
-pnpm narratage runtime logs svml.runtime.json
-pnpm narratage runtime down 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
```
`runtime up` 启动或复用当前 Profile 的后台 Worker,并准备、启动该 Profile 声明的外部程序。
重复执行不会创建第二个同域 Worker。`runtime status` 同时展示 Worker、耐久队列、共享容量和
外部程序健康状态。
+彼此独立的外部程序会并行准备。人类可读输出会显示 `Checking`、`Preparing`、`Starting`、
+`Waiting`、`Ready`,首次准备 WhisperX 模型或浏览器时不会像命令卡死;JSON 模式仍只输出
+一份干净的最终文档。
+
后台进程同时绑定 Profile 路径,以及覆盖 Profile 与两份 package lock 的有效修订摘要。
任一文件变化后,旧进程会显示为 `stale`;下一次 `runtime up` 或 `build` 会先替换旧进程,
不会让新 Dispatch 偷偷进入旧执行闭包。
@@ -30,9 +34,9 @@ pnpm narratage runtime down svml.runtime.json
## 只管理外部程序
```bash
-pnpm narratage services up svml.runtime.json
-pnpm narratage services status svml.runtime.json
-pnpm narratage services down svml.runtime.json
+node --run narratage -- services up svml.runtime.json
+node --run narratage -- services status svml.runtime.json
+node --run narratage -- services down svml.runtime.json
```
`services` 是调试/运维命令,只处理 Adapter 声明的程序,不启动 Worker、不读取或修改 Build
@@ -47,23 +51,31 @@ KIE 这种纯远端 API Endpoint 没有本地 service。
## 与 Build 的关系
-`build` 会先验证并确保 Runtime 正在运行,然后耐久写入 Build 与 Dispatch ticket。无
-`--follow` 时立刻退出;`--follow` 只观察。中断观察终端不会中断 Worker。
+`build` 会先从选中 Producer steps 推导其声明的 capability,只准备承载这些 capability 的
+外部程序。纯文本或纯 Estimate Target 不会仅仅因为 Profile 里也提供 WhisperX 就加载几 GB
+模型;这不改变图、不替作者路由 Provider,只避免启动无关部署程序。之后 Build 与 Dispatch
+ticket 会被耐久写入。无 `--follow` 时立刻退出;`--follow` 只观察,并在 Build phase 或
+Operation 数量变化时输出一行。中断观察终端不会中断 Worker。
`--no-services` 只表示外部程序由部署者另行维护,不会把执行塞回 CLI,也不会恢复任何
隐式 Runtime 默认。
+显式 `runtime up` 与 `services up` 仍管理整个 Profile,因为它们的对象是部署而非某次 Build。
+
## 可见性
```bash
-pnpm narratage queue --runtime svml.runtime.json --watch
-pnpm narratage status <build-id> --runtime svml.runtime.json
-pnpm narratage operations <build-id> --runtime svml.runtime.json
-pnpm narratage operation <operation-id> --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
```
-这些命令展示 dispatch phase、租约/容量、Operation checkpoint 和取消状态。`--json` 输出
-一次结构化结果,watch 命令可用 `--jsonl`。
+这些命令展示活跃 dispatch、Worker 状态、租约/容量、Operation 的通用进度、checkpoint 和
+取消状态。并发启动按 Profile 串行化,只会复用一个 Worker 和每个受管外部服务的一个实例;
+`--follow` 若发现 Worker 已停止会明确报出重启命令,不会无限等待。`--json` 输出
+一次结构化结果,watch 命令可用 `--jsonl`。`queue --watch` 只输出第一份快照和后续变化,
+不会在远端任务状态没变时每秒重复刷同一个块。
## WhisperX
diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md
index c2d7df65..e2166ad5 100644
--- a/docs/zh/quickstart.md
+++ b/docs/zh/quickstart.md
@@ -24,6 +24,10 @@ pnpm check
pnpm test
```
+在源码仓库内可使用 `node --run narratage -- ...`。仓库外的视频项目直接执行
+`/path/to/svml/narratage ... --package-root /path/to/svml`;这个轻量入口不再启动 pnpm,源码、
+SQLite、Artifact 和输出仍全部留在外部项目的 Runtime Profile root 下。
+
## 三份输入
每一次 Build 都接受三份彼此独立的输入:
@@ -42,10 +46,10 @@ Author Source 说明*做什么*。Run Source 说明*要哪些*。Runtime Profile
WhisperX、Gemini Caption、B-roll、Text、Film、HyperFrames —— 全程不调用任何外部服务。
```bash
-pnpm narratage check examples/talking-film-graph-check/main.svml \
+node --run narratage -- check examples/talking-film-graph-check/main.svml \
--package-lock examples/talking-film-graph-check/svml.packages.lock --root .
-pnpm narratage plan examples/talking-film-graph-check/build.svrun \
+node --run narratage -- plan examples/talking-film-graph-check/build.svrun \
--package-lock examples/talking-film-graph-check/svml.packages.lock --root .
```
diff --git a/docs/zh/quickstart/composition.md b/docs/zh/quickstart/composition.md
index 1821ab46..e0820c47 100644
--- a/docs/zh/quickstart/composition.md
+++ b/docs/zh/quickstart/composition.md
@@ -238,10 +238,10 @@ Build Target,也可以直接接到媒体裁切、音频/帧提取或模型参
### 编译与验证
```bash
-pnpm narratage check examples/talking-film-graph-check/main.svml \
+node --run narratage -- check examples/talking-film-graph-check/main.svml \
--package-lock examples/talking-film-graph-check/svml.packages.lock --root .
-pnpm narratage plan examples/talking-film-graph-check/build.svrun \
+node --run narratage -- plan examples/talking-film-graph-check/build.svrun \
--package-lock examples/talking-film-graph-check/svml.packages.lock --root .
```
diff --git a/docs/zh/quickstart/run.md b/docs/zh/quickstart/run.md
index 3079bf03..8cb23683 100644
--- a/docs/zh/quickstart/run.md
+++ b/docs/zh/quickstart/run.md
@@ -108,6 +108,39 @@ Narratage 没有隐式缓存。复用结果是显式的运行图编写——你
</svrun>
```
+### 查找可复用输出
+
+按照输出在各个历史 Build 冻结 Catalog 中的旧名字查询:
+
+```bash
+node --run narratage -- history hook-take.video \
+ --runtime ./svml.runtime.json
+```
+
+`history` 只列出该 Build 确实选择并验收过的公开 Logical Output。仅仅在源码中声明但没有
+运行出来的别名,以及不能作为 `build-record` Candidate 的 authored Record 别名,都不会混入
+结果。如果忘了旧名字,可以按 Catalog 当时记录的精确源码路径列出真正验收过的输出名:
+
+```bash
+node --run narratage -- history --source ./main.svml \
+ --runtime ./svml.runtime.json
+```
+
+输出名只是某个不可变历史 Catalog 内供人查找的名字,不是产物身份。真正身份由历史 Core
+Build、Logical Output 和 Record 摘要共同确定。假如当前源码把 `hook-take.video` 改名为
+`opening-shot.video`,`<build-record>` 仍写历史旧名,`<satisfy>` 写当前新名:
+
+```svml
+<build-record id="approved-opening"
+ build="my-film-001" output="hook-take.video"/>
+<satisfy output="opening-shot.video"
+ candidate="approved-opening" fidelity="substitute"/>
+```
+
+Narratage 永远不会猜测两个名字代表同一份作者意图。`my-film-001` 这样的可读 build-id 由
+`build --build-id` 提供;省略时使用不可变的编译后 Core Build 摘要。已经绑定的显式 build-id
+不能再用于另一份作者意图或运行意图。
+
### build-record
声明一个由先前 Build 的历史 Record 支持的零输入 Candidate:
@@ -275,11 +308,11 @@ Worker。
```bash
cd /opt/narratage
-pnpm narratage lock-packages /work/my-film/svml.packages.lock \
+node --run narratage -- lock-packages /work/my-film/svml.packages.lock \
--package @narratage/script \
--package @narratage/estimate
-pnpm narratage plan /work/my-film/build.svrun \
+node --run narratage -- plan /work/my-film/build.svrun \
--package-lock /work/my-film/svml.packages.lock
```
@@ -326,7 +359,7 @@ Runtime 状态、归档 Artifact 和 lock 仍全部留在 `/work/my-film`。只
### 1. 诊断环境
```bash
-pnpm narratage doctor examples/talking-head-aroll/svml.runtime.json
+node --run narratage -- doctor examples/talking-head-aroll/svml.runtime.json
```
Doctor 校验两份 lock、全部显式 Runtime 角色、Endpoint 配置、凭据是否存在和有界环境探测;
@@ -335,8 +368,8 @@ Doctor 校验两份 lock、全部显式 Runtime 角色、Endpoint 配置、凭
### 2. 检查计划
```bash
-pnpm narratage plan examples/talking-head-aroll/build.svrun \
- --package-lock examples/talking-head-aroll/svml.packages.lock --root .
+node --run narratage -- plan examples/talking-head-aroll/build.svrun \
+ --runtime examples/talking-head-aroll/svml.runtime.json
```
在花费资金之前审查冻结的 BuildPlan。该计划展示调度器将发出的每个 Operation 和 Needs。
@@ -344,16 +377,14 @@ pnpm narratage plan examples/talking-head-aroll/build.svrun \
### 3. 提交 Build
```bash
-pnpm narratage build examples/talking-head-aroll/build.svrun \
+node --run narratage -- build examples/talking-head-aroll/build.svrun \
--runtime examples/talking-head-aroll/svml.runtime.json \
- --package-lock examples/talking-head-aroll/svml.packages.lock \
- --root . \
--build-id my-film-001 \
--follow
```
不带 `--follow` 时,Build 在耐久提交后退出,后台 Worker 继续。带 `--follow` 时终端也只是
-观察者;Ctrl-C 不会取消任务。
+观察者,并会报告 phase / Operation 数量变化;Ctrl-C 不会取消任务。
| 标志 | 说明 |
|---|---|
@@ -364,24 +395,32 @@ pnpm narratage build examples/talking-head-aroll/build.svrun \
| `--build-id` | 用户为此 Build 选择的标识符(用于检索和复用) |
| `--follow` | 将 Build 进度流式输出到终端 |
+不传 `--build-id` 时,身份由编译后的作者意图和运行意图派生;重复同一条命令只会寻址同一个
+耐久 Build,不会偷偷再买一次生成。未完成的 Build 从已验收 Record 和可恢复 Endpoint checkpoint
+继续;已完成、失败或取消的 Build 保持终态,只返回状态。相同 prompt 明确需要另一份随机结果时,
+使用新的显式 id。把已有显式 id 用到另一份编译意图上会被拒绝,并同时提示“换 id”或“恢复原 Source”。
+
### 4. 获取结果
```bash
-pnpm narratage get my-film-001 \
+node --run narratage -- get my-film-001 \
--runtime examples/talking-head-aroll/svml.runtime.json \
--name final.video \
--to examples/talking-head-aroll/output/final.mp4
```
-每个被接受的中间 Record 和 Artifact 在 Build 完成前都会被归档。`get` 会复制一份已持久化的 Record。
+每个被接受的中间 Record 和 Artifact 在 Build 完成前都会被归档。`get` 会复制一份已持久化的
+Record。Blob Artifact 会从所选 Store 流式读取,逐步校验长度与 SHA-256,完整通过后才原子替换
+目标路径;导出大 MP4 不会把整段视频塞进 CLI 内存。
+Build 的最终输出会为每个目标别名打印精确的 `get --name …` 命令,不必为了导出
+`final.video` 去查不透明的 Record id。
### 5. 在新 Build 中复用
创建一个引用已完成 Build 的 Record 的新 `.svrun` 文件(参见上文[复用结果](#复用结果)),然后提交:
```bash
-pnpm narratage build examples/talking-head-aroll/reuse-generated.svrun \
+node --run narratage -- build examples/talking-head-aroll/reuse-generated.svrun \
--runtime examples/talking-head-aroll/svml.runtime.json \
- --package-lock examples/talking-head-aroll/svml.packages.lock \
- --root . --build-id my-film-reuse-001 --follow
+ --build-id my-film-reuse-001 --follow
```
diff --git a/examples/bootstrap/README.md b/examples/bootstrap/README.md
index cfd5f5ec..c41746ac 100644
--- a/examples/bootstrap/README.md
+++ b/examples/bootstrap/README.md
@@ -5,7 +5,7 @@ self-described Markup entry source can import the Script Surface and recursively
source selected by another Header. There is no built-in video prelude or suffix-selected parser:
```bash
-pnpm narratage check examples/bootstrap/main.svml \
+node --run narratage -- check examples/bootstrap/main.svml \
--package-lock examples/talking-film-graph-check/svml.packages.lock --root .
```
diff --git a/examples/talking-film-graph-check/README.md b/examples/talking-film-graph-check/README.md
index ff179e35..31d69835 100644
--- a/examples/talking-film-graph-check/README.md
+++ b/examples/talking-film-graph-check/README.md
@@ -6,11 +6,11 @@ explicit HyperFrames rendering. `check` and `plan` do not invoke Seedance, Whisp
HyperFrames.
```bash
-pnpm narratage check examples/talking-film-graph-check/main.svml \
+node --run narratage -- check examples/talking-film-graph-check/main.svml \
--package-lock examples/talking-film-graph-check/svml.packages.lock --root .
-pnpm narratage check examples/talking-film-graph-check/build.svrun \
+node --run narratage -- check examples/talking-film-graph-check/build.svrun \
--package-lock examples/talking-film-graph-check/svml.packages.lock --root .
-pnpm narratage plan examples/talking-film-graph-check/build.svrun \
+node --run narratage -- plan examples/talking-film-graph-check/build.svrun \
--package-lock examples/talking-film-graph-check/svml.packages.lock --root .
```
diff --git a/examples/talking-film-live/README.md b/examples/talking-film-live/README.md
index 10ad16b3..18919480 100644
--- a/examples/talking-film-live/README.md
+++ b/examples/talking-film-live/README.md
@@ -23,32 +23,32 @@ Prerequisites for the exact checked-in Runtime Profile:
Prepare and health-check WhisperX as described in
[`../../services/whisperx/README.md`](../../services/whisperx/README.md). `narratage check` validates
-source, Run Graph and exact Runtime capability coverage before scheduling, but it does not make a
-paid Provider request or promise that remote credentials and service health are valid.
+the source and Run Graph without making a paid Provider request. `narratage build` assembles the
+selected Runtime and rejects missing capability coverage before scheduling external work; neither
+command promises that remote credentials and service health are valid.
Run the complete graph through the explicit Run Graph and declarative local Runtime Profile:
The checked-in `svml.packages.lock` selects each author, Run and deterministic compute package
-independently; there is no implicit video bundle. Regenerate it after changing one of those package
-implementations with the package list documented in the lock file.
+independently; there is no implicit video bundle. After changing a selected package implementation,
+refresh its already explicit selection with
+`node --run narratage -- lock-packages examples/talking-film-live/svml.packages.lock --refresh`.
The independent `svml.runtime-packages.lock` selects Local execution, SQLite state, filesystem
Artifacts, environment credentials, KIE, local media, local WhisperX, Vertex and local HyperFrames
adapters; adding another implementation does not change the CLI.
```bash
-pnpm narratage runtime up examples/talking-film-live/svml.runtime.json
+node --run narratage -- runtime up examples/talking-film-live/svml.runtime.json
-pnpm narratage build examples/talking-film-live/build.svrun \
+node --run narratage -- build examples/talking-film-live/build.svrun \
--runtime examples/talking-film-live/svml.runtime.json \
- --package-lock examples/talking-film-live/svml.packages.lock \
- --root . \
--build-id talking-film-live \
--follow
-pnpm narratage inspect talking-film-live \
+node --run narratage -- inspect talking-film-live \
--runtime examples/talking-film-live/svml.runtime.json
-pnpm narratage get talking-film-live \
+node --run narratage -- get talking-film-live \
--runtime examples/talking-film-live/svml.runtime.json \
--name final.video \
--to examples/talking-film-live/output/final.mp4
diff --git a/examples/talking-head-aroll/README.md b/examples/talking-head-aroll/README.md
index 12fda6ab..0bd21378 100644
--- a/examples/talking-head-aroll/README.md
+++ b/examples/talking-head-aroll/README.md
@@ -26,7 +26,7 @@ take at Seedance's 15-second request limit.
Create the explicit package lock used by this development-workspace example:
```sh
-pnpm narratage lock-packages examples/talking-head-aroll/svml.packages.lock \
+node --run narratage -- lock-packages examples/talking-head-aroll/svml.packages.lock \
--package @narratage/artifact \
--package @narratage/narrative \
--package @narratage/media \
@@ -58,7 +58,7 @@ pnpm narratage lock-packages examples/talking-head-aroll/svml.packages.lock \
--package @narratage/run-markup \
--package-root .
-pnpm narratage lock-packages examples/talking-head-aroll/svml.runtime-packages.lock \
+node --run narratage -- lock-packages examples/talking-head-aroll/svml.runtime-packages.lock \
--package @narratage/local \
--package @narratage/store-sqlite \
--package @narratage/artifact-store-fs \
@@ -71,36 +71,40 @@ pnpm narratage lock-packages examples/talking-head-aroll/svml.runtime-packages.l
--package-root .
```
+After package implementation changes, retain these explicit selections without repeating the long
+list:
+
+```sh
+node --run narratage -- lock-packages examples/talking-head-aroll/svml.packages.lock --refresh
+node --run narratage -- lock-packages examples/talking-head-aroll/svml.runtime-packages.lock --refresh
+```
+
Inspect the authored graph—including the visible `*.prompt` Text output and `*.program`—without a paid call:
```sh
-pnpm narratage check examples/talking-head-aroll/main.svml \
- --package-lock examples/talking-head-aroll/svml.packages.lock \
- --root .
+node --run narratage -- check examples/talking-head-aroll/main.svml \
+ --runtime examples/talking-head-aroll/svml.runtime.json
```
Inspect the exact paid plan before submitting it:
```sh
-pnpm narratage plan examples/talking-head-aroll/build.svrun \
- --package-lock examples/talking-head-aroll/svml.packages.lock \
- --root .
+node --run narratage -- plan examples/talking-head-aroll/build.svrun \
+ --runtime examples/talking-head-aroll/svml.runtime.json
```
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
-pnpm narratage runtime up examples/talking-head-aroll/svml.runtime.json
+node --run narratage -- runtime up examples/talking-head-aroll/svml.runtime.json
-pnpm narratage build examples/talking-head-aroll/build.svrun \
+node --run narratage -- build examples/talking-head-aroll/build.svrun \
--runtime examples/talking-head-aroll/svml.runtime.json \
- --package-lock examples/talking-head-aroll/svml.packages.lock \
- --root . \
--build-id talking-head-film-001 \
--follow
-pnpm narratage get talking-head-film-001 \
+node --run narratage -- get talking-head-film-001 \
--runtime examples/talking-head-aroll/svml.runtime.json \
--name final.video \
--to examples/talking-head-aroll/output/final.mp4
@@ -113,10 +117,8 @@ Run the same downstream film from the four archived generated shots without anot
submission:
```sh
-pnpm narratage build examples/talking-head-aroll/reuse-generated.svrun \
+node --run narratage -- build examples/talking-head-aroll/reuse-generated.svrun \
--runtime examples/talking-head-aroll/svml.runtime.json \
- --package-lock examples/talking-head-aroll/svml.packages.lock \
- --root . \
--build-id talking-head-film-reuse-001 \
--follow
```