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: streamline project authoring and runtime guidance

kashorin28bb464f2534
diff --git a/.agents/skills/narratage/SKILL.md b/.agents/skills/narratage/SKILL.md
index 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.json
node --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. Us
only to stop the Worker and Runtime-owned programs; it does not cancel Builds or remote Provider
work.
-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.md
index 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 presence
values 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.md
index 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 Work
programs 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.md
index 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 image
itself. 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.md
index 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 topolog
then 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 grammar
diff --git a/.agents/skills/narratage/references/playbooks/formats/two-person-podcast.md b/.agents/skills/narratage/references/playbooks/formats/two-person-podcast.md
index 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-font
Captions, 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 cuts
diff --git a/.agents/skills/narratage/references/playbooks/index.md b/.agents/skills/narratage/references/playbooks/index.md
index 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. Never
invent 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.md
index 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`; put
editorial text on `typo:Track`; then assemble with `film:Film`, render with `render:Video`, and
demand 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 reuse
each 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.md
index 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.json
node --run narratage -- runtime up path/to/svml.runtime.json
node --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 the
requested 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 distinct
diff --git a/README.md b/README.md
index 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; separate
instances execute separately even when their parameters match.
@@ -119,11 +119,14 @@ in a completely separate directory, invoke the checkout's lightweight launcher f
```bash
cd /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 external
credentials:
diff --git a/docs/guide/providers.md b/docs/guide/providers.md
index 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 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
@@ -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.md
index 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 Profile
The 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, not
creative 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 resource
acquires both atomically. Optional `resources` overrides address those opaque ids. Capacity tickets
are durable and fenced by the Build lease rather than process-local counters.
-### 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 profile
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
+that declaration and reads credentials 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
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 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.md
index 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.md
index 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 a
Target. The compiler only executes Operations needed to satisfy the demanded Targets — everything
else 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 results
Narratage has no implicit cache. Reusing a result is explicit Run Graph authoring — you declare
historical 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. 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:
@@ -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 a
new 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
```bash
cd /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.json
node --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 Workspace
Source directory. Do not symlink a project into this repository: canonical-path containment
intentionally 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's
Runtime 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 somewhere
other 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 Build
diff --git a/docs/zh/guide/packages.md b/docs/zh/guide/packages.md
index 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.md
index 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.md
index 95adfd78..68b3b510 100644
--- a/docs/zh/guide/runtime-profile.md
+++ b/docs/zh/guide/runtime-profile.md
@@ -6,7 +6,7 @@ description: 显式配置 Build 的执行环境、状态存储、凭据与并发
# Runtime Profile
Runtime 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、Build
Store 或作者包,不会启动服务、写入 Runtime 状态或提交任务;它只打开 Profile 明确选择的
CredentialStore 来解析引用,完成后立即关闭,并可执行显式声明的有界只读探测。
diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md
index 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.md
index 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.md
index 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。
```bash
cd /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.json
node --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 S
Runtime 状态、归档 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. 提交 Build
diff --git a/spec/core-kernel.md b/spec/core-kernel.md
index 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 atomic
Operations 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 authoring
happen 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 laws
1. 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 are
never 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 fail
before 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 and
BuildRequest.
## Execution laws
1. Core emits Commands from the frozen BuildPlan. Driver and Runtime cannot change Candidate
selection, 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 and
the 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 old
commands 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 laws
1. 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 needs
a 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 external
fulfillment provenance.
## Boundary