Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
docs: streamline project authoring and runtime guidance
kashorin28bb464f2534
diff --git a/.agents/skills/narratage/SKILL.md b/.agents/skills/narratage/SKILL.mdindex 02cc79d0..a8159fd4 100644--- a/.agents/skills/narratage/SKILL.md+++ b/.agents/skills/narratage/SKILL.md@@ -27,8 +27,8 @@ Source, and `svml.runtime.json`/`.ts` Runtime Profile separate.## Required loop```bash+node --run narratage -- packages sync path/to/build.svrun --runtime path/to/svml.runtime.json --root .node --run narratage -- doctor path/to/svml.runtime.json-node --run narratage -- runtime up path/to/svml.runtime.jsonnode --run narratage -- check path/to/main.svml --runtime path/to/svml.runtime.json --root .node --run narratage -- plan path/to/build.svrun --runtime path/to/svml.runtime.json --root .node --run narratage -- build path/to/build.svrun --runtime path/to/svml.runtime.json \@@ -42,9 +42,9 @@ Treat `--follow` as an observer: stopping it does not stop the durable Build. Usonly to stop the Worker and Runtime-owned programs; it does not cancel Builds or remote Providerwork.-Pin and reuse every accepted generated image or take in the next `.svrun` with `build-record` plus-`satisfy`. Set the consuming Target to accept the declared fidelity, then review the frozen plan-before paid downstream work.+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+fidelity label.Preserve unrelated changes. Keep credentials, generated media, runtime state, and logs out of commits.The repository's docs remain the syntax authority.diff --git a/.agents/skills/narratage/references/credentials.md b/.agents/skills/narratage/references/credentials.mdindex a86b956e..943babc3 100644--- a/.agents/skills/narratage/references/credentials.md+++ b/.agents/skills/narratage/references/credentials.md@@ -34,3 +34,9 @@ Keep keys outside Author/Run/Runtime source and committed files. Verify presencevalues with, for example,`node .agents/skills/narratage/scripts/check-credentials.mjs KIE_API_KEY MIMO_API_KEY`, then run`node --run narratage -- doctor <profile>`.++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.+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.mdindex 591f6f88..62695a3e 100644--- a/.agents/skills/narratage/references/environment.md+++ b/.agents/skills/narratage/references/environment.md@@ -42,5 +42,16 @@ Use `runtime up` for normal Build preparation: it owns the detached durable Workprograms declared by the Runtime Profile. `services up/status/down` is only the narrow external-program view and does not manage the Worker. See `references/runtime.md` for the Build lifecycle.+After intentionally installing, removing or changing selected packages, refresh both explicit+project locks in one reviewed action:++```text+node --run narratage -- packages sync build.svrun --runtime svml.runtime.json --root .+```++This command derives Author roots from that Run/Author Source closure and Runtime roots from the+Profile's explicit `use` entries, then records the exact installed closures. It does not install+packages, discover a default set or mutate SVML/Run intent.+The repository owns skill discovery: `.agents/skills` is canonical, with repository-root`.codex/skills` and `.claude/skills` links. This is checkout layout, not a skill setup operation.diff --git a/.agents/skills/narratage/references/playbooks/craft/production-gates.md b/.agents/skills/narratage/references/playbooks/craft/production-gates.mdindex f8f91645..3abb7cb2 100644--- a/.agents/skills/narratage/references/playbooks/craft/production-gates.md+++ b/.agents/skills/narratage/references/playbooks/craft/production-gates.md@@ -13,14 +13,14 @@ Use staged Run Sources so unreviewed expensive outputs cannot silently feed late## Gate 1: build and review reference images-1. Create a narrow `.svrun` target-set that demands only the generated reference-image outputs.+1. Create a narrow `.svrun` containing Targets only for the generated reference-image outputs.2. Submit that Build, then use `inspect` and `get` to retrieve every candidate image.3. If the Agent can view images, open the actual full-resolution outputs and review every imageitself. Do not approve from prompts, metadata, filenames, or thumbnails alone.4. Reject and regenerate any failed image. Do not connect a failed image to Seedance, Media Track,image composition, or another downstream generator.-5. Pin accepted image Records with `.svrun` `build-record` and connect them to the next Build with- `satisfy`. Changing the target-set alone does not select those Records.+5. Reuse accepted image Records with `.svrun` `build-record` and connect them to the next Build with+ `satisfy`. Changing the Target list alone does not select those Records.Apply this checklist to every image:@@ -71,13 +71,11 @@ visual QA.Use explicit Run Source authoring for every accepted reuse:```svml-<target-set id="delivery">- <target output="final.video" accepts="substitute"/>-</target-set>+<target output="final.video"/><build-record id="accepted-take" build="reviewed-build-001"output="opening-take.video"/>-<satisfy output="opening-take.video" candidate="accepted-take"- fidelity="substitute"/>+<satisfy output="opening-take.video" candidate="accepted-take"/>```-Substitute fidelity propagates downstream. The demanded final Target must explicitly accept it.+The selected Candidate must supply the Logical Output's exact nominal Type. Core does not infer+creative equivalence or propagate a substitute-quality label downstream.diff --git a/.agents/skills/narratage/references/playbooks/formats/street-interview.md b/.agents/skills/narratage/references/playbooks/formats/street-interview.mdindex 8fc3ca02..c11ed09b 100644--- a/.agents/skills/narratage/references/playbooks/formats/street-interview.md+++ b/.agents/skills/narratage/references/playbooks/formats/street-interview.md@@ -16,8 +16,8 @@ make the active speaker readable without changing the location or camera topologthen call `seedance:ReferenceVideo generate-audio="true"` with the scene image and both voices.6. Assemble the accepted Segment takes with `speech:Spine`, align the complete Script with`whisperx:Alignment`, then add Caption, Media, Typography, and Audio Tracks as needed.-7. Assemble peer Tracks in `film:Film`, render with `render:Video`, and demand review or delivery- outputs through named `.svrun` target-sets.+7. Assemble peer Tracks in `film:Film`, render with `render:Video`, and use separate `.svrun`+ Sources with explicit Targets for review and delivery.## Preserve the street-interview grammardiff --git a/.agents/skills/narratage/references/playbooks/formats/two-person-podcast.md b/.agents/skills/narratage/references/playbooks/formats/two-person-podcast.mdindex 8be6f35b..7ac0bef7 100644--- a/.agents/skills/narratage/references/playbooks/formats/two-person-podcast.md+++ b/.agents/skills/narratage/references/playbooks/formats/two-person-podcast.md@@ -28,8 +28,8 @@ Draw the room and name camera positions A and B before generating either view.both voice references in the Kit's declared order.6. Assemble accepted takes through `speech:Spine`, run `whisperx:Alignment`, then add exact-fontCaptions, evidence Media, Typography, and optional Audio Tracks.-7. Assemble with `film:Film`, render with `render:Video`, and use `.svrun` target-sets for staged- review and delivery.+7. Assemble with `film:Film`, render with `render:Video`, and use separate `.svrun` Sources with+ explicit Targets for staged review and delivery.## Direct turns and cutsdiff --git a/.agents/skills/narratage/references/playbooks/index.md b/.agents/skills/narratage/references/playbooks/index.mdindex 73e42011..c6f82282 100644--- a/.agents/skills/narratage/references/playbooks/index.md+++ b/.agents/skills/narratage/references/playbooks/index.md@@ -28,7 +28,7 @@ needed for that craft or format.verified ProgramSpace Record in `.svrun`, author explicit timing, and omit WhisperX/Caption work.- Assemble peer Tracks with `film:Film`, render with `render:Video`, and demand outputs through a`.svrun` Target.-- Stage expensive work with narrow target-sets. Pin and reuse an accepted Record through+- Stage expensive work with narrow `.svrun` Targets. Explicitly reuse an accepted Record through`build-record` plus `satisfy`; Narratage has no implicit cache.- Use only elements and attributes documented by the current Quickstart or package README. Neverinvent a component or attribute to fill in missing syntax.diff --git a/.agents/skills/narratage/references/reference-vlm.md b/.agents/skills/narratage/references/reference-vlm.mdindex 06a1350c..d4d3e2bb 100644--- a/.agents/skills/narratage/references/reference-vlm.md+++ b/.agents/skills/narratage/references/reference-vlm.md@@ -20,7 +20,7 @@ Write `main.svml`, optional `studio.svs`, and `build.svrun` directly.`caption-fine:Style`, `caption:Program`, `caption-ai:Planner`, and `caption-fine:Track`; puteditorial text on `typo:Track`; then assemble with `film:Film`, render with `render:Video`, anddemand the desired outputs in `build.svrun`.-- Route every generated reference image through `playbooks/craft/production-gates.md`. Pin and reuse+- Route every generated reference image through `playbooks/craft/production-gates.md`. Explicitly reuseeach accepted image or take in the next Build with `.svrun` `build-record` and `satisfy`.Generated image prompt structure: an English reality contract matching the observed capture medium,diff --git a/.agents/skills/narratage/references/runtime.md b/.agents/skills/narratage/references/runtime.mdindex c7372148..935cce7c 100644--- a/.agents/skills/narratage/references/runtime.md+++ b/.agents/skills/narratage/references/runtime.md@@ -1,11 +1,13 @@# Durable Runtime and Build workflow-Read `docs/quickstart/run.md` as the authority for Run Source, Target, fidelity, Runtime Profile,+Read `docs/quickstart/run.md` as the authority for Run Source, Target, Candidate, Runtime Profile,Build, retrieval, and reuse syntax. Use this file as the operational checklist.## Execute the lifecycle```bash+node --run narratage -- packages sync path/to/build.svrun \+ --runtime path/to/svml.runtime.json --root .node --run narratage -- doctor path/to/svml.runtime.jsonnode --run narratage -- runtime up path/to/svml.runtime.jsonnode --run narratage -- runtime status path/to/svml.runtime.json@@ -39,8 +41,9 @@ durable Builds and does not cancel remote Provider work.terminal does not stop the Build.- `inspect` reads durable Build state and accepted Records. `get` copies an archived Artifact to therequested destination.-- There is no implicit cache. Pin and reuse Records through a new `.svrun` containing `build-record`- and `satisfy`, with the target accepting the resulting fidelity.+- There is no implicit cache or Pin state. Reuse Records through a new `.svrun` containing+ `build-record` and `satisfy`; the Candidate supplies the exact nominal Type required by the+ current Logical Output.## Keep project and package boundaries distinctdiff --git a/README.md b/README.mdindex 29f5814d..e8569876 100644--- a/README.md+++ b/README.md@@ -43,8 +43,8 @@ There is no privileged final-video root. Any public Logical Output can be a Targ- A **Logical Output** is an author-visible typed result promise.- A **Candidate** is an independent typed supply backed by a Provided Value or Operation result.-- A **Satisfaction** explicitly connects a Candidate to a Logical Output as `exact` or- `substitute`.+- A **Satisfaction** explicitly connects one compatible Candidate to a Logical Output. Core does+ not attach creative labels such as `exact`, `substitute` or `pin` to that edge.- A **Target** says which outputs this Build requires.- An **Operation** is one atomic execution instance. Shared identity means one execution; separateinstances execute separately even when their parameters match.@@ -119,11 +119,14 @@ in a completely separate directory, invoke the checkout's lightweight launcher f```bashcd /path/to/my-video-/path/to/svml/narratage check main.svml \- --package-lock svml.packages.lock --package-root /path/to/svml --root .+/path/to/svml/narratage packages sync build.svrun \+ --runtime svml.runtime.json --root .+/path/to/svml/narratage check main.svml --runtime svml.runtime.json --root .+/path/to/svml/narratage plan build.svrun --runtime svml.runtime.json --root .```-The launcher does not run pnpm and does not move source, state or outputs into this repository.+The Runtime Profile may point `packageRoot` at this checkout during source development. 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 externalcredentials:diff --git a/docs/guide/providers.md b/docs/guide/providers.mdindex 563916c0..3eec1c15 100644--- a/docs/guide/providers.md+++ b/docs/guide/providers.md@@ -117,7 +117,7 @@ export default svmlPackage;````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.+references, capabilities and scheduling facts used by both `doctor` and execution.Activation must not resolve secrets or environment-sourced deployment values, access the network orstart work. It keeps environment names as references until a matching Need is handled. Credentialpresence is diagnosed through the generic CredentialStore path; a Provider must not special-case@@ -198,9 +198,6 @@ instantiates its `use` id."defaultConcurrency": 2}}- ],- "permissions": [- "network:api.my-service.com"]}```diff --git a/docs/guide/runtime-profile.md b/docs/guide/runtime-profile.mdindex 1c9fb552..e2166179 100644--- a/docs/guide/runtime-profile.md+++ b/docs/guide/runtime-profile.md@@ -6,7 +6,7 @@ description: Configuring where Builds execute, diagnostics and Build archive.# Runtime ProfileThe Runtime Profile declares *where* a frozen Build executes: the Scheduler and Worker, all durable-Stores, Endpoints, credentials, concurrency and permissions. It is deployment configuration, not+Stores, Endpoints, credentials and concurrency. It is deployment configuration, notcreative content—it never enters Author or Run graph identity.Two forms are supported:@@ -45,7 +45,6 @@ Two forms are supported:{"use": "@narratage/provider-kie","instance": "kie.production",- "authority": "kie.production","config": {"apiKey": { "store": "keychain", "key": "kie.api-key" },"defaultConcurrency": 2@@ -54,19 +53,16 @@ Two forms are supported:{"use": "@narratage/provider-media-local","instance": "media.local",- "authority": "media.local","config": { "defaultConcurrency": 2 }},{"use": "@narratage/provider-whisperx-local","instance": "whisperx.local",- "authority": "whisperx.local","config": { "defaultConcurrency": 1 }},{"use": "@narratage/provider-google-vertex","instance": "vertex.local",- "authority": "vertex.local","config": {"projectEnv": "GOOGLE_CLOUD_PROJECT","credentials": { "store": "keychain", "key": "google.vertex-json" },@@ -76,21 +72,9 @@ Two forms are supported:{"use": "@narratage/provider-hyperframes-local","instance": "hyperframes.local",- "authority": "hyperframes.local","config": { "workers": 2, "quality": "standard", "defaultConcurrency": 1 }}],- "permissions": [- "process:keychain",- "filesystem:artifacts",- "filesystem:state",- "filesystem:whisperx-staging",- "network:aiplatform.googleapis.com",- "network:api.kie.ai",- "network:whisperx-loopback",- "process:hyperframes",- "process:media"- ],"scheduling": { "maxConcurrency": 4 }}```@@ -101,7 +85,7 @@ Two forms are supported:|---|---|| `use` | Adapter name, resolved from `runtimePackageLock` || `instance` | Unique identifier for this Endpoint instance |-| `authority` | Stable non-secret identity of the account, deployment or compute pool whose limits are shared |+| `authority` | Optional shared account/compute-pool identity; omitted instances use their own `instance` id || `config` | Adapter-specific non-secret configuration, CredentialRefs, concurrency and timeouts |Credentials are addressed as `{ "store": "…", "key": "…" }`; secret bytes never enter the@@ -135,13 +119,12 @@ packages contribute an Authority resource and an exact capability Route resourceacquires both atomically. Optional `resources` overrides address those opaque ids. Capacity ticketsare durable and fenced by the Build lease rather than process-local counters.-### Permissions--Each permission string grants one specific authority to the locked Endpoints:+### Trust boundary-- `network:<host>` — outbound HTTP to that host-- `filesystem:<scope>` — file access within a named scope-- `process:<name>` — local process execution+Runtime packages currently execute as trusted local code. Narratage does not pretend that a string+allowlist can restrict Node code that shares the Host process. Arbitrary community runtime packages+must wait for a real process/Wasm isolation boundary with enforceable filesystem, network, process+and resource controls.## Executable TypeScript@@ -201,10 +184,6 @@ export default async function createRuntime() {},},endpoints,- allowedPermissions: [- "environment:credentials", "filesystem:artifacts", "filesystem:state",- ...endpoints.flatMap(e => e.manifest.facets.flatMap(f => f.permissions)),- ],scheduling: {maxConcurrency: 4,},@@ -241,7 +220,7 @@ Validates:- Declared external services are reachable and match the selected profileRuntime 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+that declaration and reads credentials and prerequisites from the resulting Endpointpackage; there is no diagnostic-only credential mirror. Activation may construct handlers but maynot resolve credentials, access the network, start a process or mutate durable state. `doctor` neverconstructs a Scheduler, Worker, Build Store or author package, starts a service, writes Runtime statediff --git a/docs/quickstart.md b/docs/quickstart.mdindex 0355355a..265d613d 100644--- a/docs/quickstart.md+++ b/docs/quickstart.md@@ -76,7 +76,7 @@ Every Build takes three separate inputs:|---|---|---|| **Author Source** | script, model choices, track composition, output graph | `.svml` || **Run Source** | which outputs to target, alternate candidates, satisfaction edges | `.svrun` |-| **Runtime Profile** | endpoints, credentials, concurrency, permissions | `svml.runtime.json` |+| **Runtime Profile** | endpoints, credentials and concurrency | `svml.runtime.json` |Author Source says *what*. Run Source says *which*. Runtime Profile says *where*.diff --git a/docs/quickstart/composition.md b/docs/quickstart/composition.mdindex 9c4e7c4b..47300e69 100644--- a/docs/quickstart/composition.md+++ b/docs/quickstart/composition.md@@ -235,11 +235,9 @@ The complete data flow from Script to rendered video. This example is based on```svml<?svml using="@narratage/run-markup@1"?>-<svrun version="1" targets="delivery">+<svrun version="1"><author source="./main.svml"/>- <target-set id="delivery">- <target output="final.video" accepts="exact"/>- </target-set>+ <target output="final.video"/></svrun>```diff --git a/docs/quickstart/run.md b/docs/quickstart/run.mdindex 13ed657e..38fff225 100644--- a/docs/quickstart/run.md+++ b/docs/quickstart/run.md@@ -5,10 +5,9 @@ description: Declaring build targets, reusing results and configuring the runtim# Run Source & Builds-The Run Source (`.svrun`) declares **what to build** — which outputs to demand, what fidelity to-accept, and optionally how to reuse results from prior Builds. The Runtime Profile-(`svml.runtime.json`) declares **where to run** — endpoints, credentials, concurrency, and-permissions.+The Run Source (`.svrun`) declares **what to build** — which outputs to demand and which explicit+Candidates, if any, should replace their authored implementations. The Runtime Profile+(`svml.runtime.json`) declares **where to run** — endpoints, credentials and concurrency.Neither of these changes what the video **is**. That is the Author Source's job.@@ -25,28 +24,20 @@ Every `.svrun` file begins with its processing instruction:```svml<?svml using="@narratage/run-markup@1"?>-<svrun version="1" targets="delivery">+<svrun version="1"><author source="./main.svml"/>- <target-set id="delivery">- <target output="final.video" accepts="exact"/>- </target-set>+ <target output="final.video"/></svrun>```| Element | Description ||---|---|-| `<svrun>` | Root element. `version="1"`, `targets` names the active target-set |+| `<svrun>` | Root element. Its only attribute is `version="1"` || `<author>` | Mandatory. `source` points to the `.svml` Author Source |-| `<target-set>` | A named set of demanded outputs |-| `<target>` | One demanded output: `output` names a Logical Output, `accepts` sets fidelity |+| `<target>` | One demanded public Logical Output |### Targets-A **Target** names an output required by the Build and the worst fidelity it accepts:--- `accepts="exact"` — the output must be exactly what the author declared-- `accepts="substitute"` — an acceptable replacement is allowed (e.g. a prior generation)-There is no privileged "final video" root. Any public Logical Output from any component can be aTarget. The compiler only executes Operations needed to satisfy the demanded Targets — everythingelse is pruned.@@ -56,47 +47,29 @@ else is pruned.You can demand multiple outputs from one Build:```svml-<target-set id="delivery">- <target output="final.video" accepts="exact"/>- <target output="captions.track" accepts="exact"/>-</target-set>-```--Or define multiple target-sets and switch between them:--```svml-<svrun version="1" targets="preview">- <author source="./main.svml"/>-- <target-set id="preview">- <target output="captions.track" accepts="substitute"/>- </target-set>-- <target-set id="delivery">- <target output="final.video" accepts="exact"/>- </target-set>-</svrun>+<target output="final.video"/>+<target output="captions.track"/>```-The `targets` attribute on `<svrun>` selects which set is active.+Different build intentions should be separate `.svrun` files. They can point to the same Author+Source without duplicating it. For example, `images.svrun` may target image outputs while+`film.svrun` targets the final video.## Reusing resultsNarratage has no implicit cache. Reusing a result is explicit Run Graph authoring — you declarehistorical Records as zero-input Candidates and connect them through Satisfaction edges.-As soon as a generated image or take is accepted, pin it in the next `.svrun` with `build-record`-and `satisfy`, let the consuming Target accept the declared fidelity, and inspect the frozen plan-before starting paid downstream work.+As soon as a generated image or take is accepted, reuse it explicitly in the next `.svrun` with+`build-record` and `satisfy`, then inspect the frozen plan before starting paid downstream work.+Core has no Pin state or fidelity label.```svml<?svml using="@narratage/run-markup@1"?>-<svrun version="1" targets="delivery">+<svrun version="1"><author source="./main.svml"/>- <target-set id="delivery">- <target output="final.video" accepts="substitute"/>- </target-set>+ <target output="final.video"/><build-record id="hook-video"build="my-film-001" output="hook-take.video"/>@@ -107,14 +80,10 @@ before starting paid downstream work.<build-record id="payoff-video"build="my-film-001" output="payoff-take.video"/>- <satisfy output="hook-take.video"- candidate="hook-video" fidelity="substitute"/>- <satisfy output="meeting-take.video"- candidate="meeting-video" fidelity="substitute"/>- <satisfy output="evidence-take.video"- candidate="evidence-video" fidelity="substitute"/>- <satisfy output="payoff-take.video"- candidate="payoff-video" fidelity="substitute"/>+ <satisfy output="hook-take.video" candidate="hook-video"/>+ <satisfy output="meeting-take.video" candidate="meeting-video"/>+ <satisfy output="evidence-take.video" candidate="evidence-video"/>+ <satisfy output="payoff-take.video" candidate="payoff-video"/></svrun>```@@ -127,7 +96,7 @@ 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+`history` reports only public Logical Outputs that the Build actually produced. Itdoes 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 whoseCatalog recorded an exact source path:@@ -145,8 +114,7 @@ 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"/>+<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@@ -171,20 +139,28 @@ Connects a Candidate to a Logical Output:|---|---|| `output` | The Logical Output to satisfy || `candidate` | The Candidate id (from `build-record`) |-| `fidelity` | `exact` or `substitute` |-The compiled plan prunes all upstream Operations that the substitute Candidates replace. This is a+The compiled plan prunes all upstream Operations that the selected Candidates replace. This is anew Build, not a continuation of the old one. Downstream processing (normalization, WhisperX,captioning, rendering) still runs against the reused media.-### Fidelity model+Core does not label a Candidate as “exact” or “substitute”. Choosing a Candidate is the Run+author's explicit implementation decision for that Build. Type compatibility is checked; creative+equivalence is neither guessed nor carried as redundant metadata through the graph.++### Using an existing file++A local file is the simplest zero-input Candidate. The Run Source names the bytes and connects them+to one current Logical Output:-- **`exact`** — the Candidate precisely matches what the author declared-- **`substitute`** — the Candidate is an acceptable replacement+```svml+<file id="approved-opening" from="./approved-opening.mp4" media-type="video/mp4"/>+<satisfy output="opening-shot.video" candidate="approved-opening"/>+```-Substitute fidelity is **monotonic**: once a substitute enters the graph, it propagates downstream.-You cannot wash it back to exact. If the final target accepts `substitute`, downstream Operations-that consume substitute inputs produce substitute results.+The file is read relative to the `.svrun`, content-addressed and archived with the Build. There is+no special Pin state, filename cache or hidden history lookup. A black video, preview image or+human-supplied result uses the same mechanism.## Runtime Profile@@ -221,7 +197,6 @@ complete [Runtime Profile guide](../guide/runtime-profile.md).{"use": "@narratage/provider-kie","instance": "kie.main",- "authority": "kie.main","config": {"apiKey": { "store": "env", "key": "KIE_API_KEY" },"defaultConcurrency": 2@@ -230,19 +205,16 @@ complete [Runtime Profile guide](../guide/runtime-profile.md).{"use": "@narratage/provider-media-local","instance": "media.main",- "authority": "media.main","config": { "defaultConcurrency": 2 }},{"use": "@narratage/provider-whisperx-local","instance": "whisperx.main",- "authority": "whisperx.main","config": { "defaultConcurrency": 1 }},{"use": "@narratage/provider-google-vertex","instance": "vertex.main",- "authority": "vertex.main","config": {"projectEnv": "GOOGLE_CLOUD_PROJECT","credentials": { "store": "env", "key": "GOOGLE_APPLICATION_CREDENTIALS_JSON" },@@ -253,7 +225,6 @@ complete [Runtime Profile guide](../guide/runtime-profile.md).{"use": "@narratage/provider-hyperframes-local","instance": "hyperframes.main",- "authority": "hyperframes.main","config": {"workers": 2,"quality": "standard",@@ -261,18 +232,6 @@ complete [Runtime Profile guide](../guide/runtime-profile.md).}}],- "permissions": [- "environment:credentials",- "filesystem:artifacts",- "filesystem:state",- "filesystem:whisperx-staging",- "network:aiplatform.googleapis.com",- "network:api.kie.ai",- "network:kieai.redpandaai.co",- "network:whisperx-loopback",- "process:hyperframes",- "process:media"- ],"scheduling": { "maxConcurrency": 4 }}```@@ -285,13 +244,13 @@ Each endpoint binds a Provider package to a named instance and an explicit Provi|---|---|| `use` | Provider package name (e.g. `@narratage/provider-kie`) || `instance` | Unique instance identifier |-| `authority` | Stable non-secret identity of the account, deployment or compute pool whose limits are shared |+| `authority` | Optional shared account/compute-pool identity; omit it when this instance owns its own limits || `config` | Provider-specific non-secret configuration and ordinary CredentialRefs |-### Permissions+### Trust-Explicit grants for filesystem, network, and process access. The scheduler refuses Operations that-require permissions not listed here.+Runtime packages currently execute as trusted local code. A real process/Wasm sandbox is required+before arbitrary third-party runtime packages can be treated as untrusted.### Scheduling@@ -363,9 +322,8 @@ Author files do not have to live under this repository. For example, keep a proj```bashcd /opt/narratage-node --run narratage -- lock-packages /work/my-film/svml.packages.lock \- --package @narratage/script \- --package @narratage/estimate+node --run narratage -- packages sync /work/my-film/build.svrun \+ --runtime /work/my-film/svml.runtime.jsonnode --run narratage -- plan /work/my-film/build.svrun \--runtime /work/my-film/svml.runtime.json@@ -379,6 +337,18 @@ needed above. Use `--root` only when deliberately widening the Source WorkspaceSource directory. Do not symlink a project into this repository: canonical-path containmentintentionally rejects that escape.+For a shared read-only media library, keep Source imports inside the project and authorize only its+asset bytes explicitly:++```bash+node --run narratage -- plan /work/my-film/build.svrun \+ --runtime /work/my-film/svml.runtime.json \+ --asset-root /work/shared-media+```++`--asset-root` is repeatable. It never permits `.svml`/`.svs` source imports outside `--root`, and+it does not enter Author or Build identity; the exact bytes still enter as content-addressed assets.+The official CLI supplies the same installation location while reading the external project'sRuntime Profile, so the Profile remains portable:@@ -406,7 +376,6 @@ Runtime Profile, so the Profile remains portable:}},"endpoints": [],- "permissions": ["environment:credentials", "filesystem:artifacts", "filesystem:state"],"scheduling": { "maxConcurrency": 4 }}```@@ -415,25 +384,30 @@ Runtime state, archived Artifacts and the lock files remain under `/work/my-film`--package-root` or the Profile's `packageRoot` only when the packages intentionally live somewhereother than the CLI installation.-### 1. Diagnose the environment+### 1. Synchronize installed packages++After installing or updating packages, explicitly accept both declared closures:```bash-node --run narratage -- doctor examples/talking-head-aroll/svml.runtime.json+node --run narratage -- packages sync examples/talking-head-aroll/build.svrun \+ --runtime examples/talking-head-aroll/svml.runtime.json --root .```-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.+The Author and Run sources choose author packages. The Runtime Profile chooses environment+packages. `packages sync` closes and authenticates those two sets; it never scans the project,+starts a Provider or generates media.-### 2. Start or reuse the Runtime+### 2. Diagnose the environment```bash-node --run narratage -- runtime up examples/talking-head-aroll/svml.runtime.json-node --run narratage -- runtime status examples/talking-head-aroll/svml.runtime.json+node --run narratage -- doctor examples/talking-head-aroll/svml.runtime.json```-`runtime up` owns the detached durable Worker and every external program declared by the Profile.-The narrower `services up|status|down` commands manage only those external programs and do not own-the Worker lifecycle.+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.### 3. Check source and inspect the plan@@ -448,7 +422,12 @@ node --run narratage -- plan examples/talking-head-aroll/build.svrun \```Review the frozen BuildPlan before spending money. The plan shows every Operation and Needs the-Scheduler would issue.+Scheduler would issue. With `--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+prepare it before submission; `runtime status` observes it. The narrower `services up|status|down`+commands manage external programs only and do not own the Worker lifecycle.### 4. Submit the Builddiff --git a/docs/zh/guide/packages.md b/docs/zh/guide/packages.mdindex bf479a6b..6101b4af 100644--- a/docs/zh/guide/packages.md+++ b/docs/zh/guide/packages.md@@ -189,7 +189,7 @@ packages/example/一个物理包可以暴露多个可独立 activate 的 facet:-| Facet | ABI | 权限 | 由谁选择 |+| Facet | ABI | 能力边界 | 由谁选择 ||---|---|---|---|| `static` | Manifest 与身份 | 无 | 加载后始终可用 || `author` | Frontend、Surface、Graph Fragment | 仅作者词汇 | 源码中的 `<import>`,经由编译器 Host |@@ -216,7 +216,7 @@ SVML 使用按字节锁定的受信任代码执行。加载器会记录每个包}```-两个相互独立的 lock 闭包服务于不同的权限范围:+两个相互独立的 lock 闭包服务于不同的信任范围:| Lock 文件 | 包含内容 | 身份范围 ||---|---|---|diff --git a/docs/zh/guide/providers.md b/docs/zh/guide/providers.mdindex 0a2741fd..4aa2308b 100644--- a/docs/zh/guide/providers.md+++ b/docs/zh/guide/providers.md@@ -113,7 +113,7 @@ export default svmlPackage;````activate` 是唯一的纯部署声明。它返回的 Endpoint 同时拥有供 `doctor` 与执行使用的凭据引用、-权限、capability 和调度事实。Activation 不得解析密钥或环境来源的部署值、访问网络或启动任务;+capability 和调度事实。Activation 不得解析密钥或环境来源的部署值、访问网络或启动任务;环境变量名会作为引用保留到真正处理匹配 Need 时。凭据是否存在由通用 CredentialStore 路径诊断,Provider 不得把环境变量硬编码成特殊的密钥 Store。@@ -188,9 +188,6 @@ node --run narratage -- lock-packages <runtime-lock> \"defaultConcurrency": 2}}- ],- "permissions": [- "network:api.my-service.com"]}```diff --git a/docs/zh/guide/runtime-profile.md b/docs/zh/guide/runtime-profile.mdindex 95adfd78..68b3b510 100644--- a/docs/zh/guide/runtime-profile.md+++ b/docs/zh/guide/runtime-profile.md@@ -6,7 +6,7 @@ description: 显式配置 Build 的执行环境、状态存储、凭据与并发# Runtime ProfileRuntime Profile 声明冻结后的 Build *在哪里*执行:Scheduler、Worker、全部 Store、Endpoint、-凭据、并发和权限。它属于部署配置,绝不进入 Author Graph 或 Run Graph 身份。+凭据和并发。它属于部署配置,绝不进入 Author Graph 或 Run Graph 身份。## 声明式 Profile@@ -37,20 +37,12 @@ Runtime Profile 声明冻结后的 Build *在哪里*执行:Scheduler、Worker{"use": "@narratage/provider-kie","instance": "kie.production",- "authority": "kie.production","config": {"apiKey": { "store": "keychain", "key": "kie.api-key" },"defaultConcurrency": 2}}],- "permissions": [- "filesystem:artifacts",- "filesystem:state",- "process:keychain",- "network:api.kie.ai",- "network:kieai.redpandaai.co"- ],"scheduling": { "maxConcurrency": 4 }}```@@ -70,18 +62,19 @@ CredentialStore。不存在“因为只装了一个所以自动选中”,`@nar| `root` | Runtime 数据与相对 lock 的根目录;默认是 Profile 所在目录 || `packageRoot` | 提供已安装 `node_modules` 的 Host 位置;与项目数据目录无关 || `packageLock` | 确定性 Producer/Validator 包闭包 |-| `runtimePackageLock` | 有权限的 Runtime Adapter 包闭包 |+| `runtimePackageLock` | 可信 Runtime Adapter 包闭包 |外部项目可以把源文件、锁、SQLite 和 Artifact 全部留在自己的目录,同时从另一个Narratage 安装目录加载校验后的包。-## 并发与权限+## 并发与信任边界`maxConcurrency`、Provider Authority 与精确 Capability Route 的上限由 DispatchStore 在所有共享 Worker 之间执行,不是某个 CLI 进程里的计数器。容量租约跟随 Build 的 fenced lease;过期 Worker 不能继续准入结果。-权限仍是显式 allowlist,例如 `network:<host>`、`filesystem:<scope>`、`process:<name>`。+Runtime Adapter 当前是可信本地代码。开放任意第三方 Adapter 之前,需要真正的进程或 Wasm+隔离;字符串 allowlist 不能限制同一 Node 进程里的代码。## 凭据控制不是 Runtime 执行@@ -105,7 +98,7 @@ node --run narratage -- runtime down svml.runtime.json`stale`,下一次启动或提交会按新执行闭包替换进程,而不是继续复用旧装配。`doctor` 会求值 Endpoint Adapter 唯一的纯 `activate()` 声明,并直接从产生的 Endpoint package-读取凭据、权限和前置条件;不存在另一份仅供诊断使用的凭据镜像。Activation 可以构造 handler,+读取凭据和前置条件;不存在另一份仅供诊断使用的凭据镜像。Activation 可以构造 handler,但不得解析密钥、访问网络、启动进程或修改持久状态。`doctor` 不构造 Scheduler、Worker、BuildStore 或作者包,不会启动服务、写入 Runtime 状态或提交任务;它只打开 Profile 明确选择的CredentialStore 来解析引用,完成后立即关闭,并可执行显式声明的有界只读探测。diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.mdindex fe314611..e91cebb6 100644--- a/docs/zh/quickstart.md+++ b/docs/zh/quickstart.md@@ -71,7 +71,7 @@ SQLite、Artifact 和输出仍全部留在外部项目的 Runtime Profile root|---|---|---|| **Author Source** | 口播稿、模型选择、轨道构成、输出图 | `.svml` || **Run Source** | 要产出哪些输出、备选 candidates、satisfaction edges | `.svrun` |-| **Runtime Profile** | endpoints、凭据、并发、权限 | `svml.runtime.json` |+| **Runtime Profile** | endpoints、凭据、并发 | `svml.runtime.json` |Author Source 说明*做什么*。Run Source 说明*要哪些*。Runtime Profile 说明*在哪里做*。diff --git a/docs/zh/quickstart/composition.md b/docs/zh/quickstart/composition.mdindex b704166a..00489d3f 100644--- a/docs/zh/quickstart/composition.md+++ b/docs/zh/quickstart/composition.md@@ -231,11 +231,9 @@ Build Target,也可以直接接到媒体裁切、音频/帧提取或模型参```svml<?svml using="@narratage/run-markup@1"?>-<svrun version="1" targets="delivery">+<svrun version="1"><author source="./main.svml"/>- <target-set id="delivery">- <target output="final.video" accepts="exact"/>- </target-set>+ <target output="final.video"/></svrun>```diff --git a/docs/zh/quickstart/run.md b/docs/zh/quickstart/run.mdindex db9f74aa..7fff862a 100644--- a/docs/zh/quickstart/run.md+++ b/docs/zh/quickstart/run.md@@ -5,7 +5,7 @@ description: 声明 Build 目标、复用结果以及配置运行时环境。# Run Source 与 Build-Run Source(`.svrun`)声明**要构建什么**——需要哪些输出、接受什么保真度,以及可选地如何复用先前 Build 的结果。Runtime Profile(`svml.runtime.json`)声明**在哪里运行**——endpoint、凭证、并发数和权限。+Run Source(`.svrun`)声明**要构建什么**——需要哪些输出,以及是否明确选用某个 Candidate 替换作者图里的实现。Runtime Profile(`svml.runtime.json`)声明**在哪里运行**——endpoint、凭证和并发数。这两者都不会改变视频**是什么**。那是 Author Source 的职责。@@ -22,28 +22,20 @@ Run Source(`.svrun`)声明**要构建什么**——需要哪些输出、接```svml<?svml using="@narratage/run-markup@1"?>-<svrun version="1" targets="delivery">+<svrun version="1"><author source="./main.svml"/>- <target-set id="delivery">- <target output="final.video" accepts="exact"/>- </target-set>+ <target output="final.video"/></svrun>```| 元素 | 说明 ||---|---|-| `<svrun>` | 根元素。`version="1"`,`targets` 指定活跃的 target-set |+| `<svrun>` | 根元素,唯一属性是 `version="1"` || `<author>` | 必需。`source` 指向 `.svml` Author Source |-| `<target-set>` | 一组命名的需求输出集合 |-| `<target>` | 单个需求输出:`output` 指定逻辑输出名,`accepts` 设置保真度 |+| `<target>` | 一个需要得到的公开 Logical Output |### Target-**Target** 指定 Build 所需的输出及其可接受的最低保真度:--- `accepts="exact"` ——输出必须与作者声明的完全一致-- `accepts="substitute"` ——允许使用可接受的替代品(例如先前生成的结果)-不存在特权化的"最终视频"根节点。任何组件的任何公开逻辑输出都可以作为 Target。编译器仅执行满足所需 Target 所必要的 Operation——其余一切均被裁剪。### 多个 Target@@ -51,45 +43,26 @@ Run Source(`.svrun`)声明**要构建什么**——需要哪些输出、接可以在一次 Build 中请求多个输出:```svml-<target-set id="delivery">- <target output="final.video" accepts="exact"/>- <target output="captions.track" accepts="exact"/>-</target-set>-```--也可以定义多个 target-set 并在它们之间切换:--```svml-<svrun version="1" targets="preview">- <author source="./main.svml"/>-- <target-set id="preview">- <target output="captions.track" accepts="substitute"/>- </target-set>-- <target-set id="delivery">- <target output="final.video" accepts="exact"/>- </target-set>-</svrun>+<target output="final.video"/>+<target output="captions.track"/>```-`<svrun>` 上的 `targets` 属性选择当前活跃的集合。+不同的运行意图写成不同的 `.svrun` 文件即可,它们可以共同指向同一个 Author Source。+例如 `images.svrun` 只请求图片,`film.svrun` 请求最终视频,无需在文件内部再造一层集合。## 复用结果Narratage 没有隐式缓存。复用结果是显式的运行图编写——你将历史 Record 声明为零输入 Candidate,并通过 Satisfaction 边将它们连接起来。-生成图片或 Take 一经验收,就在下一份 `.svrun` 中用 `build-record` 与 `satisfy` 固定它;-消费它的 Target 要接受所声明的 fidelity,并在启动付费下游工作前检查冻结 plan。+生成图片或 Take 一经验收,就在下一份 `.svrun` 中用 `build-record` 与 `satisfy` 显式复用,+并在启动付费下游工作前检查冻结 plan。Core 没有 Pin 状态或 fidelity 标签。```svml<?svml using="@narratage/run-markup@1"?>-<svrun version="1" targets="delivery">+<svrun version="1"><author source="./main.svml"/>- <target-set id="delivery">- <target output="final.video" accepts="substitute"/>- </target-set>+ <target output="final.video"/><build-record id="hook-video"build="my-film-001" output="hook-take.video"/>@@ -100,14 +73,10 @@ Narratage 没有隐式缓存。复用结果是显式的运行图编写——你<build-record id="payoff-video"build="my-film-001" output="payoff-take.video"/>- <satisfy output="hook-take.video"- candidate="hook-video" fidelity="substitute"/>- <satisfy output="meeting-take.video"- candidate="meeting-video" fidelity="substitute"/>- <satisfy output="evidence-take.video"- candidate="evidence-video" fidelity="substitute"/>- <satisfy output="payoff-take.video"- candidate="payoff-video" fidelity="substitute"/>+ <satisfy output="hook-take.video" candidate="hook-video"/>+ <satisfy output="meeting-take.video" candidate="meeting-video"/>+ <satisfy output="evidence-take.video" candidate="evidence-video"/>+ <satisfy output="payoff-take.video" candidate="payoff-video"/></svrun>```@@ -120,7 +89,7 @@ node --run narratage -- history hook-take.video \--runtime ./svml.runtime.json```-`history` 只列出该 Build 确实选择并验收过的公开 Logical Output。仅仅在源码中声明但没有+`history` 只列出该 Build 确实产出过的公开 Logical Output。仅仅在源码中声明但没有运行出来的别名,以及不能作为 `build-record` Candidate 的 authored Record 别名,都不会混入结果。如果忘了旧名字,可以按 Catalog 当时记录的精确源码路径列出真正验收过的输出名:@@ -136,8 +105,7 @@ Build、Logical Output 和 Record 摘要共同确定。假如当前源码把 `ho```svml<build-record id="approved-opening"build="my-film-001" output="hook-take.video"/>-<satisfy output="opening-shot.video"- candidate="approved-opening" fidelity="substitute"/>+<satisfy output="opening-shot.video" candidate="approved-opening"/>```Narratage 永远不会猜测两个名字代表同一份作者意图。`my-film-001` 这样的可读 build-id 由@@ -162,16 +130,22 @@ Narratage 永远不会猜测两个名字代表同一份作者意图。`my-film-0|---|---|| `output` | 要满足的逻辑输出 || `candidate` | Candidate 标识符(来自 `build-record`) |-| `fidelity` | `exact` 或 `substitute` |-编译后的计划会裁剪所有被替代 Candidate 取代的上游 Operation。这是一次新的 Build,而非旧 Build 的延续。下游处理(归一化、WhisperX、字幕生成、渲染)仍然会对复用的媒体执行。+编译后的计划会裁剪所选 Candidate 取代的上游 Operation。这是一次新的 Build,而非旧 Build 的延续。下游处理(归一化、WhisperX、字幕生成、渲染)仍然会对复用的媒体执行。++Core 不再给 Candidate 标注 `exact` 或 `substitute`。选择 Candidate 本身就是这次运行的明确实现决定。系统校验类型兼容性,但不猜测创作等价性,也不把这种判断作为冗余元信息沿整条图传播。++### 使用已有文件-### 保真度模型+本地文件就是最简单的零输入 Candidate:-- **`exact`** ——Candidate 与作者声明的内容精确匹配-- **`substitute`** ——Candidate 是一个可接受的替代品+```svml+<file id="approved-opening" from="./approved-opening.mp4" media-type="video/mp4"/>+<satisfy output="opening-shot.video" candidate="approved-opening"/>+```-替代保真度是**单调的**:一旦替代品进入图中,它会向下游传播。你无法将其恢复为 exact。如果最终 Target 接受 `substitute`,那么消费替代输入的下游 Operation 也会产生替代结果。+文件相对于 `.svrun` 读取,按内容寻址,并随 Build 归档。系统没有额外的 Pin 状态、文件名缓存+或隐式历史查找;黑场、预览图与人工交付的产物也使用同一个机制。## Runtime Profile@@ -208,7 +182,6 @@ Runtime Profile(`svml.runtime.json`)告诉系统**在哪里**执行每种类{"use": "@narratage/provider-kie","instance": "kie.main",- "authority": "kie.main","config": {"apiKey": { "store": "env", "key": "KIE_API_KEY" },"defaultConcurrency": 2@@ -217,19 +190,16 @@ Runtime Profile(`svml.runtime.json`)告诉系统**在哪里**执行每种类{"use": "@narratage/provider-media-local","instance": "media.main",- "authority": "media.main","config": { "defaultConcurrency": 2 }},{"use": "@narratage/provider-whisperx-local","instance": "whisperx.main",- "authority": "whisperx.main","config": { "defaultConcurrency": 1 }},{"use": "@narratage/provider-google-vertex","instance": "vertex.main",- "authority": "vertex.main","config": {"projectEnv": "GOOGLE_CLOUD_PROJECT","credentials": { "store": "env", "key": "GOOGLE_APPLICATION_CREDENTIALS_JSON" },@@ -240,7 +210,6 @@ Runtime Profile(`svml.runtime.json`)告诉系统**在哪里**执行每种类{"use": "@narratage/provider-hyperframes-local","instance": "hyperframes.main",- "authority": "hyperframes.main","config": {"workers": 2,"quality": "standard",@@ -248,18 +217,6 @@ Runtime Profile(`svml.runtime.json`)告诉系统**在哪里**执行每种类}}],- "permissions": [- "environment:credentials",- "filesystem:artifacts",- "filesystem:state",- "filesystem:whisperx-staging",- "network:aiplatform.googleapis.com",- "network:api.kie.ai",- "network:kieai.redpandaai.co",- "network:whisperx-loopback",- "process:hyperframes",- "process:media"- ],"scheduling": { "maxConcurrency": 4 }}```@@ -272,12 +229,13 @@ Runtime Profile(`svml.runtime.json`)告诉系统**在哪里**执行每种类|---|---|| `use` | Provider 包名(例如 `@narratage/provider-kie`) || `instance` | 唯一的实例标识符 |-| `authority` | 共享外部容量的账号、部署或计算池的稳定非秘密标识 |+| `authority` | 可选的共享账号或计算池标识;实例独享容量时省略即可 || `config` | Provider 专属非秘密配置、CredentialRef 与并发数 |-### 权限+### 信任边界-对文件系统、网络和进程访问的显式授权。调度器会拒绝需要未在此列出的权限的 Operation。+Runtime 包目前作为可信本地代码执行。开放任意第三方 Runtime 包之前,需要真正的进程或+Wasm 隔离;字符串 allowlist 不能限制同一 Node 进程里的代码。### 调度@@ -345,12 +303,11 @@ Worker。```bashcd /opt/narratage-node --run narratage -- lock-packages /work/my-film/svml.packages.lock \- --package @narratage/script \- --package @narratage/estimate+node --run narratage -- packages sync /work/my-film/build.svrun \+ --runtime /work/my-film/svml.runtime.jsonnode --run narratage -- plan /work/my-film/build.svrun \- --package-lock /work/my-film/svml.packages.lock+ --runtime /work/my-film/svml.runtime.json```Source Workspace 默认是 `build.svrun` 所在目录;相对引用的 Author Source 与素材都必须留在@@ -359,6 +316,17 @@ Source Workspace 默认是 `build.svrun` 所在目录;相对引用的 Author S上面的命令无需填写包路径。只有需要主动扩大源码边界时才传 `--root`。不要把外部项目软链接进仓库;canonical path 的边界检查会有意拒绝这种逃逸。+共享只读素材库不必复制进项目,也不必放宽 Source 边界:++```bash+node --run narratage -- plan /work/my-film/build.svrun \+ --runtime /work/my-film/svml.runtime.json \+ --asset-root /work/shared-media+```++`--asset-root` 可重复使用,只授权读取素材字节,不允许从那里导入 `.svml/.svs` 源码。该 Host+选项不进入作者或 Build 身份;真正进入图的仍是素材内容摘要。+官方 CLI 读取外部项目的 Runtime Profile 时也会提供同一个安装位置,因此 Profile 仍可移植:```json@@ -385,7 +353,6 @@ Source Workspace 默认是 `build.svrun` 所在目录;相对引用的 Author S}},"endpoints": [],- "permissions": ["environment:credentials", "filesystem:artifacts", "filesystem:state"],"scheduling": { "maxConcurrency": 4 }}```@@ -393,24 +360,29 @@ Source Workspace 默认是 `build.svrun` 所在目录;相对引用的 Author SRuntime 状态、归档 Artifact 和 lock 仍全部留在 `/work/my-film`。只有包被有意安装在 CLI之外时,才使用 `--package-root` 或 Profile 的 `packageRoot` 覆盖位置。-### 1. 诊断环境+### 1. 同步已安装包++安装或更新包后,用一条显式命令接受两份声明闭包:```bash-node --run narratage -- doctor examples/talking-head-aroll/svml.runtime.json+node --run narratage -- packages sync examples/talking-head-aroll/build.svrun \+ --runtime examples/talking-head-aroll/svml.runtime.json --root .```-Doctor 校验两份 lock、全部显式 Runtime 角色、Endpoint 配置、凭据是否存在和有界环境探测;-它不启动 Worker,也不发付费请求。+Author/Run Source 选择作者包,Runtime Profile 选择环境包;该命令只闭包并锁定这两组声明,+不扫描目录、不启动 Provider,也不生成媒体。-### 2. 启动或复用 Runtime+### 2. 诊断环境```bash-node --run narratage -- runtime up examples/talking-head-aroll/svml.runtime.json-node --run narratage -- runtime status examples/talking-head-aroll/svml.runtime.json+node --run narratage -- doctor examples/talking-head-aroll/svml.runtime.json```-`runtime up` 负责后台耐久 Worker,以及 Profile 声明的全部外部程序。范围更窄的-`services up|status|down` 只管理这些外部程序,不负责 Worker 生命周期。+Doctor 校验两份 lock、全部显式 Runtime 角色、Endpoint 配置、凭据是否存在和有界环境探测;+它不启动 Worker,也不发付费请求。++`doctor` 有意检查完整 Runtime Profile。若只想检查某次 Run 真正需要的环境,请使用带+`--runtime` 的 `plan`。### 3. 检查 Source 与计划@@ -424,7 +396,11 @@ node --run narratage -- plan examples/talking-head-aroll/build.svrun \--runtime examples/talking-head-aroll/svml.runtime.json```-在花费资金之前审查冻结的 BuildPlan。该计划展示调度器将发出的每个 Operation 和 Needs。+在花费资金之前审查冻结的 BuildPlan。该计划展示调度器将发出的每个 Operation 和 Needs;带+`--runtime` 时只预检这次计划真正需要的 Endpoint、凭据和外部程序,不启动任何外部工作。++`build` 会自动启动或复用后台 Runtime。只有希望提交前预热时才需要显式执行 `runtime up`;+`runtime status` 用于观察。范围更窄的 `services up|status|down` 只管理外部程序,不负责 Worker。### 4. 提交 Builddiff --git a/spec/core-kernel.md b/spec/core-kernel.mdindex aa4529af..fbde85e7 100644--- a/spec/core-kernel.md+++ b/spec/core-kernel.md@@ -14,64 +14,57 @@ Core accepts immutable, already linked data:- a resolved module closure and typed authored Records;- a complete `svml.graph@1` containing Logical Outputs, independent Candidates and atomicOperations from the Author and Run Graphs;-- a `svml.build-request@1` containing Targets and explicit Satisfaction edges.+- a `svml.build-request@1` containing Targets.Graph construction, source parsing, package resolution, Fragment expansion and Run Graph authoringhappen outside Core. Core verifies the resulting data before deriving a plan.## Graph values-1. A `LogicalOutput` is a stable author-visible promise: identity, nominal Type, Primary Candidate,- semantic input envelope and optional affinity constraints.+1. A `LogicalOutput` is a stable author-visible promise: identity, nominal Type and Primary+ Candidate.2. A `Candidate` is an independent typed supply. Its root is one immutable Provided Value or one- atomic Operation result. It does not belong to an output and does not carry fidelity.-3. A `Satisfaction` connects one Logical Output to one Candidate with `exact` or `substitute`- fidelity. An output without an explicit Satisfaction uses its Primary Candidate as `exact`.-4. A `Target` names an output required by this Build and the worst conformance it accepts.+ atomic Operation result. It does not belong to an output.+3. The Run compiler applies each explicit `Satisfaction` by making its Candidate that output's+ Primary Candidate in the immutable realized graph. Core receives no second selection source.+4. A `Target` names an output required by this Build.5. An `Operation` has stable instance identity, declared typed inputs and exactly one atomic result.Multi-result components use one Product followed by deterministic Projection Operations.## Compilation laws1. Core derives Demand backwards from all Targets through selected Candidates and Operation inputs.-2. Selection and reachability are resolved together; an undemanded Satisfaction does not create- work.+2. Selection is already frozen into the graph; reachability alone determines work.3. One Operation instance referenced by several edges is included once. Different instances arenever content-deduplicated, even when implementation, parameters or input Records match.4. A Provided-Value Candidate has no input edge, so traversal stops naturally. Core has no Pin,preview, cache or historical-result branch.-5. A Candidate must produce the exact nominal Type required by every Satisfaction using it.-6. A Candidate's authored leaves must remain within that Logical Output's semantic input envelope.-7. Cycles, missing references, undeclared ports, duplicate identities and incompatible Types fail+5. A Candidate must produce the exact nominal Type required by the Logical Output using it.+6. Cycles, missing references, undeclared ports, duplicate identities and incompatible Types failbefore execution.-8. The resulting `svml.plan@1` is finite, deterministic and content-bound to the verified Graph and+7. The resulting `svml.plan@1` is finite, deterministic and content-bound to the verified Graph andBuildRequest.## Execution laws1. Core emits Commands from the frozen BuildPlan. Driver and Runtime cannot change Candidateselection, dependency topology or Target meaning.-2. Exactness is monotonic. Satisfaction fidelity, input conformance and external fulfillment form a- floor that no later exact Producer can improve.-3. A Target accepting only `exact` rejects a selected or inherited `substitute` before completion.-4. Records, Needs, Commands, Events, Receipts and Derivations are immutable content-bound facts.-5. A Derivation binds implementation identity, input and output digests, Need request digests and+2. Records, Needs, Commands, Events, Receipts and Derivations are immutable content-bound facts.+3. A Derivation binds implementation identity, input and output digests, Need request digests andthe accepted Event digest.-6. An external Receipt binds the exact Need, request digest, fulfillment implementation, output- digest, delivery mode, conformance and accepted Event.-7. Serialized outstanding Commands are not trusted. Resume verifies accepted state, discards old+4. An external Receipt binds the exact Need, request digest, fulfillment implementation, output+ digest and accepted Event.+5. Serialized outstanding Commands are not trusted. Resume verifies accepted state, discards oldcommands and deterministically regenerates the next commands.-8. A Build completes only when every Target Record exists with accepted conformance.+6. A Build completes only when every Target Record exists.-## Type and affinity laws+## Type laws1. Types are nominally owned by modules, not registered in a central Core union.2. Core checks the locked structural Schema for every admitted Record.3. A Type owner may lock a semantic validator digest. When present, every Record of that Type needsa receipt bound to the exact Type, value digest and validator implementation.-4. Core affinity is a domain-neutral declared equality between JSON Pointer values on directly- connected facts. It may not require every downstream value to copy transitive provenance.-5. The Graph owns dependencies, Derivation owns deterministic lineage and Receipt owns external+4. The Graph owns dependencies, Derivation owns deterministic lineage and Receipt owns externalfulfillment provenance.## Boundary