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: update guides for the single-version, @narratage naming
rpone3fb63600bd81
diff --git a/docs/guide/author-packages.md b/docs/guide/author-packages.mdindex 778a0555..d67c12e5 100644--- a/docs/guide/author-packages.md+++ b/docs/guide/author-packages.md@@ -19,7 +19,7 @@ mkdir -p packages/my-component/src packages/my-component/test```json{- "name": "@svml/my-component",+ "name": "@narratage/my-component","version": "0.0.0-dev","private": true,"type": "module",@@ -30,9 +30,9 @@ mkdir -p packages/my-component/src packages/my-component/test"activation": "./src/activation.ts"},"dependencies": {- "@svml/protocol": "workspace:*",- "@svml/elaborator": "workspace:*",- "@svml/text": "workspace:*"+ "@narratage/protocol": "workspace:*",+ "@narratage/elaborator": "workspace:*",+ "@narratage/text": "workspace:*"}}```@@ -45,10 +45,10 @@ Add only the dependencies your package actually imports. SeeIn `src/index.ts`, declare your Module's identity, Types and Producers:```typescript-import type { ModuleManifest, ModuleRef } from "@svml/protocol";+import type { ModuleManifest, ModuleRef } from "@narratage/protocol";export const myComponentModuleRef: ModuleRef = {- name: "@svml/my-component",+ name: "@narratage/my-component",version: 1,};@@ -68,7 +68,7 @@ The Surface handler decodes the Text Frontend's XML elements into typed author d```typescript// src/surface.ts-import type { TextSurfaceDecoder } from "@svml/text";+import type { TextSurfaceDecoder } from "@narratage/text";export const decodeMyComponentSurface: TextSurfaceDecoder = (element, context) => {// Read attributes and children from the XML element@@ -87,7 +87,7 @@ Look at existing Surface implementations for reference:```typescript// src/activation.ts-import { createTextSurfaceHostFacet } from "@svml/text";+import { createTextSurfaceHostFacet } from "@narratage/text";import {myComponentManifest,myComponentModuleRef,@@ -96,10 +96,10 @@ import {export const svmlPackage = {format: "svml.node-package@1" as const,- name: "@svml/my-component",+ name: "@narratage/my-component",modules: [{manifest: myComponentManifest,- specifiers: ["@svml/my-component", "@svml/my-component@1"],+ specifiers: ["@narratage/my-component", "@narratage/my-component@1"],}],hostFacets: [createTextSurfaceHostFacet({@@ -118,12 +118,12 @@ export default svmlPackage;The `specifiers` array lists the strings that an `<import from="..."/>` will match against. The`surface` string determines the XML element prefix (`<mine:my-widget>` when imported as `mine`).-## 6. Register in tsconfig.v2.json+## 6. Register in tsconfig.json-Add the path mapping so TypeScript resolves `@svml/my-component` to source:+Add the path mapping so TypeScript resolves `@narratage/my-component` to source:```json-"@svml/my-component": ["packages/my-component/src/index.ts"]+"@narratage/my-component": ["packages/my-component/src/index.ts"]```## 7. Install and lock@@ -131,18 +131,18 @@ Add the path mapping so TypeScript resolves `@svml/my-component` to source:```bashpnpm install-pnpm svml:v2 lock-packages <lock-file> \- --package @svml/my-component \- [--package @svml/other-dep ...] \+pnpm narratage lock-packages <lock-file> \+ --package @narratage/my-component \+ [--package @narratage/other-dep ...] \--root .```## 8. Use in Author Source```xml-<?svml using="@svml/text@1"?>+<?svml using="@narratage/text@1"?><svml>- <import as="mine" from="@svml/my-component@1"/>+ <import as="mine" from="@narratage/my-component@1"/><mine:Widget id="demo" during={story.selection.example}/></svml>diff --git a/docs/guide/conventions.md b/docs/guide/conventions.mdindex 2a397baf..d6f7af8a 100644--- a/docs/guide/conventions.md+++ b/docs/guide/conventions.md@@ -10,8 +10,8 @@ description: Naming, module boundaries, TypeScript configuration and wire data.| Thing | Convention | Example ||---|---|---|| Package directory | kebab-case | `packages/speech-align/` |-| Package name | `@svml/` scope | `@svml/speech-align` |-| Provider package | `provider-` prefix | `@svml/provider-kie` |+| Package name | `@narratage/` scope | `@narratage/speech-align` |+| Provider package | `provider-` prefix | `@narratage/provider-kie` || TypeScript file | kebab-case | `speech-align.ts` || Exported type | PascalCase | `SpeechAlignment` || Exported function | camelCase | `createSpeechAlignment` |@@ -20,12 +20,12 @@ description: Naming, module boundaries, TypeScript configuration and wire data.- Each package has exactly one public entry point: `src/index.ts`.- Internal modules use explicit `.js` extensions (NodeNext resolution).-- Cross-package imports use `@svml/*`, never relative paths across package boundaries.+- Cross-package imports use `@narratage/*`, never relative paths across package boundaries.- Circular dependencies are forbidden (enforced by `tools/package-boundaries.test.mjs`).## TypeScript configuration-`tsconfig.v2.json` extends `tsconfig.json` and adds `paths` mappings for all `@svml/*` packages.+`tsconfig.json` extends `tsconfig.json` and adds `paths` mappings for all `@narratage/*` packages.| Setting | Value ||---|---|@@ -36,16 +36,16 @@ description: Naming, module boundaries, TypeScript configuration and wire data.| `noUncheckedIndexedAccess` | `true` — indexed access returns `T \| undefined` || `exactOptionalPropertyTypes` | `true` — `undefined` must be explicit |-When adding a new package, add its path mapping to `tsconfig.v2.json`:+When adding a new package, add its path mapping to `tsconfig.json`:```json-"@svml/my-package": ["packages/my-package/src/index.ts"]+"@narratage/my-package": ["packages/my-package/src/index.ts"]```## Wire data-- All persisted data uses the `@2` wire format version.-- Wire types are defined in `@svml/protocol` and are immutable.+- All persisted data uses the `@1` wire format version.+- Wire types are defined in `@narratage/protocol` and are immutable.- Nominal Types are owned by Modules, not registered in a central union.- Type schemas use JSON-compatible structures, not TypeScript interfaces.diff --git a/docs/guide/develop.md b/docs/guide/develop.mdindex 6699fc74..bf24d868 100644--- a/docs/guide/develop.md+++ b/docs/guide/develop.md@@ -22,41 +22,32 @@ Node.js and pnpm are the only hard requirements. The rest are needed only for li```bashpnpm install # after pulling or changing dependencies-pnpm check # TypeScript type-check: v1 + v2-pnpm test # full test suite: v1 + v2+pnpm check # TypeScript type-check+pnpm test # full test suite```| Command | What it runs ||---|---|-| `pnpm check:v1` | `tsc -p tsconfig.json --noEmit` — retained v1 research oracle |-| `pnpm check:v2` | `tsc -p tsconfig.v2.json --noEmit` — all v2 workspace packages |-| `pnpm test:v1` | `node --import tsx --test 'test/**/*.test.ts'` |-| `pnpm test:v2` | `node --import tsx --test 'packages/*/test/**/*.test.ts' 'tools/*.test.mjs'` |+| `pnpm check` | `tsc -p tsconfig.json --noEmit` |+| `pnpm test` | `node --import tsx --test 'packages/*/test/**/*.test.ts' 'tools/*.test.mjs'` |See [Testing](./testing.md) for environment-gated tests and test patterns.## Repository layout```text-svml/-├── packages/ 64 v2 workspace packages (the active system)+narratage/+├── packages/ 78 workspace packages├── spec/ 7 normative specification documents├── docs/ VitePress documentation site-├── examples/ v2 examples and v1 regression fixtures+├── examples/ runnable example sources├── services/ Python sidecar services (whisperx, image-opencv)-├── src/ v1 legacy source (regression evidence only)-├── stdlib/ v1 kernel definitions and runtime-├── test/ v1 test suite├── tools/ boundary tests and build scripts├── package.json root workspace manifest├── pnpm-workspace.yaml workspace: [packages/*]-├── tsconfig.json v1 TypeScript config-└── tsconfig.v2.json v2 TypeScript config+└── tsconfig.json TypeScript config```-`src/`, `stdlib/` and `test/` are the v1 research oracle, retained as regression evidence. They-are not the v2 API.-## Guide contents| Guide | Topic |diff --git a/docs/guide/packages.md b/docs/guide/packages.mdindex c0d61bf4..e321cf59 100644--- a/docs/guide/packages.md+++ b/docs/guide/packages.md@@ -5,7 +5,7 @@ description: The four layers, dependency boundaries, package anatomy and facets.# Package Architecture-The 64+ workspace packages under `packages/` are organized into four architectural layers. Each+The 78 workspace packages under `packages/` are organized into four architectural layers. Eachlayer has strict dependency rules enforced by tests on every commit.## The four layers@@ -17,32 +17,32 @@ Runtime ports. They are reusable by any domain — not just video — and have nScript, Seedance, Film or any video concept.```text-@svml/protocol immutable wire contracts-@svml/artifact domain-neutral content-addressed byte type-@svml/core Demand compiler and Build state machine-@svml/source mandatory Source Header-@svml/elaborator author declarations and Fragment expansion-@svml/realization typed realization overlays-@svml/run syntax-neutral Run Graph-@svml/validation semantic admission-@svml/host Host-facing interfaces-@svml/compiler-node reference Node compiler Host-@svml/workspace-fs-node workspace filesystem abstraction-@svml/component-kit Producer/validator registration-@svml/runtime Scheduler and Store ports-@svml/runtime-adapter deployment-adapter ABI-@svml/runtime-adapter-node project-root resolution-@svml/endpoint-kit Endpoint registration-@svml/driver-node trusted Node command executor-@svml/package-loader-node byte-locked package loading-@svml/store-sqlite SQLite Build/Operation stores-@svml/artifact-store-fs filesystem Artifact store-@svml/artifact-store-s3 S3 Artifact store-@svml/credential-store-env environment credentials-@svml/transport invocation seams-@svml/transport-process local process transport-@svml/transport-aws-lambda Lambda transport-@svml/local SQLite/filesystem developer assembly+@narratage/protocol immutable wire contracts+@narratage/artifact domain-neutral content-addressed byte type+@narratage/core Demand compiler and Build state machine+@narratage/source mandatory Source Header+@narratage/elaborator author declarations and Fragment expansion+@narratage/realization typed realization overlays+@narratage/run syntax-neutral Run Graph+@narratage/validation semantic admission+@narratage/host Host-facing interfaces+@narratage/compiler-node reference Node compiler Host+@narratage/workspace-fs-node workspace filesystem abstraction+@narratage/component-kit Producer/validator registration+@narratage/runtime Scheduler and Store ports+@narratage/runtime-adapter deployment-adapter ABI+@narratage/runtime-adapter-node project-root resolution+@narratage/endpoint-kit Endpoint registration+@narratage/driver-node trusted Node command executor+@narratage/package-loader-node byte-locked package loading+@narratage/store-sqlite SQLite Build/Operation stores+@narratage/artifact-store-fs filesystem Artifact store+@narratage/artifact-store-s3 S3 Artifact store+@narratage/credential-store-env environment credentials+@narratage/transport invocation seams+@narratage/transport-process local process transport+@narratage/transport-aws-lambda Lambda transport+@narratage/local SQLite/filesystem developer assembly```### Layer 2: Author language@@ -51,12 +51,12 @@ Author-facing vocabulary: the text Frontend, Script Surface, SVS Recipes, Run tereusable compilation libraries.```text-@svml/text official .svml markup Frontend-@svml/script Script Surface-@svml/svs SVS Recipe Frontend-@svml/run-text official .svrun Frontend-@svml/prompt-kit declarative prompt compilation-@svml/compiler-text-node Text Frontend + Surface Host assembly+@narratage/text official .svml markup Frontend+@narratage/script Script Surface+@narratage/svs SVS Recipe Frontend+@narratage/run-text official .svrun Frontend+@narratage/prompt-kit declarative prompt compilation+@narratage/compiler-text-node Text Frontend + Surface Host assembly```### Layer 3: Video domain@@ -65,32 +65,32 @@ Video-specific types, generation model families, speech/caption/track contractsDepends on Layer 1 and 2 but not on any Provider.```text-@svml/contracts Narrative, Track, Composition contracts-@svml/media media types-@svml/generation image/video product contracts-@svml/model-kit model family abstractions-@svml/seedance Seedance model family + author Surface-@svml/seedance-speaker Seedance Speaker binding-@svml/minimax-h3 MiniMax H3 model family-@svml/gemini-omni Gemini Omni model family-@svml/grok-imagine Grok Imagine model family-@svml/gpt-image GPT Image model family-@svml/nano-banana Nano Banana model family-@svml/seedream Seedream model family-@svml/estimate duration estimation-@svml/speech-program speech program compilation-@svml/speech-take atomic speech take-@svml/speech-align speech alignment-@svml/whisperx WhisperX component-@svml/caption caption planning and Track-@svml/caption-gemini Gemini caption planner-@svml/broll B-roll Track-@svml/text-track text overlay Track-@svml/film Film composition-@svml/hyperframes HyperFrames Visual IR-@svml/hyperframes-render HyperFrames rendering component-@svml/image-transform image processing component-@svml/media-pipeline media inspection/normalization+@narratage/contracts Narrative, Track, Composition contracts+@narratage/media media types+@narratage/generation image/video product contracts+@narratage/model-kit model family abstractions+@narratage/seedance Seedance model family + author Surface+@narratage/seedance-speaker Seedance Speaker binding+@narratage/minimax-h3 MiniMax H3 model family+@narratage/gemini-omni Gemini Omni model family+@narratage/grok-imagine Grok Imagine model family+@narratage/gpt-image GPT Image model family+@narratage/nano-banana Nano Banana model family+@narratage/seedream Seedream model family+@narratage/estimate duration estimation+@narratage/speech-program speech program compilation+@narratage/speech-take atomic speech take+@narratage/speech-align speech alignment+@narratage/whisperx WhisperX component+@narratage/caption caption planning and Track+@narratage/caption-gemini Gemini caption planner+@narratage/broll B-roll Track+@narratage/text-track text overlay Track+@narratage/film Film composition+@narratage/hyperframes HyperFrames Visual IR+@narratage/hyperframes-render HyperFrames rendering component+@narratage/image-transform image processing component+@narratage/media-pipeline media inspection/normalization```### Layer 4: Provider (Endpoint) packages@@ -99,33 +99,33 @@ Privileged external capabilities. Depend on Runtime ports and the model familieson the CLI.```text-@svml/provider-kie KIE generation (16 model capabilities)-@svml/provider-media-local local ffprobe/ffmpeg-@svml/provider-whisperx-local local WhisperX sidecar-@svml/provider-google-vertex Vertex Gemini caption planning-@svml/provider-hyperframes-local local Chrome rendering-@svml/provider-image-opencv-local local OpenCV image transforms+@narratage/provider-kie KIE generation (16 model capabilities)+@narratage/provider-media-local local ffprobe/ffmpeg+@narratage/provider-whisperx-local local WhisperX sidecar+@narratage/provider-google-vertex Vertex Gemini caption planning+@narratage/provider-hyperframes-local local Chrome rendering+@narratage/provider-image-opencv-local local OpenCV image transforms```### Application layer```text-@svml/cli generic command engine (requires explicit Distribution)-@svml/video-cli video command application (selects Text compiler, no built-in author packages)+@narratage/cli generic command engine (requires explicit Distribution)+@narratage/video-cli video command application (selects Text compiler, no built-in author packages)```## Dependency rules`tools/package-boundaries.test.mjs` enforces three invariants on every commit:-1. **Acyclic production graph.** No dependency cycle among any `@svml/*` packages.+1. **Acyclic production graph.** No dependency cycle among any `@narratage/*` packages.2. **Domain-neutral closure.** Every Layer 1 package's transitive closure contains only Layer 1- packages. `@svml/core` depends only on `@svml/protocol`.+ packages. `@narratage/core` depends only on `@narratage/protocol`.-3. **CLI independence.** Neither `@svml/cli` nor `@svml/video-cli` transitively depends on any+3. **CLI independence.** Neither `@narratage/cli` nor `@narratage/video-cli` transitively depends on anyProvider package. The video CLI also does not depend on any author-level video package- (`@svml/script`, `@svml/seedance-speaker`, `@svml/broll`, `@svml/text-track`, `@svml/film`).+ (`@narratage/script`, `@narratage/seedance-speaker`, `@narratage/broll`, `@narratage/text-track`, `@narratage/film`).Author packages are activated through the explicit package lock, not compile-time CLIdependencies.@@ -147,7 +147,7 @@ packages/example/```json{- "name": "@svml/example",+ "name": "@narratage/example","version": "0.0.0-dev","private": true,"type": "module",@@ -158,13 +158,13 @@ packages/example/"activation": "./src/activation.ts"},"dependencies": {- "@svml/protocol": "workspace:*"+ "@narratage/protocol": "workspace:*"}}```-- `"exports"` points to TypeScript source directly. The workspace `tsconfig.v2.json` maps- `@svml/*` imports to source entry points via `paths`.+- `"exports"` points to TypeScript source directly. The workspace `tsconfig.json` maps+ `@narratage/*` imports to source entry points via `paths`.- `"svml.activation"` is the entry point that the Package Loader reads when this package isbyte-locked. It must default-export a `NodePackageContribution`.@@ -199,7 +199,7 @@ SHA-256 digest:"format": "svml.node-package-lock@1","artifacts": [{- "name": "@svml/seedance",+ "name": "@narratage/seedance","version": "0.0.0-dev","digest": "sha256:abc123..."}diff --git a/docs/guide/providers.md b/docs/guide/providers.mdindex 10450a96..68741eb8 100644--- a/docs/guide/providers.md+++ b/docs/guide/providers.md@@ -23,7 +23,7 @@ Provider packages depend on Runtime ports and the model families they serve, nev```json{- "name": "@svml/provider-my-service",+ "name": "@narratage/provider-my-service","version": "0.0.0-dev","private": true,"type": "module",@@ -32,12 +32,12 @@ Provider packages depend on Runtime ports and the model families they serve, nev},"svml": { "activation": "./src/activation.ts" },"dependencies": {- "@svml/endpoint-kit": "workspace:*",- "@svml/protocol": "workspace:*",- "@svml/runtime": "workspace:*",- "@svml/runtime-adapter": "workspace:*",- "@svml/runtime-adapter-node": "workspace:*",- "@svml/seedance": "workspace:*"+ "@narratage/endpoint-kit": "workspace:*",+ "@narratage/protocol": "workspace:*",+ "@narratage/runtime": "workspace:*",+ "@narratage/runtime-adapter": "workspace:*",+ "@narratage/runtime-adapter-node": "workspace:*",+ "@narratage/seedance": "workspace:*"}}```@@ -49,7 +49,7 @@ ArtifactStore persistence.```typescript// src/provider.ts-import type { EndpointManifest } from "@svml/endpoint-kit";+import type { EndpointManifest } from "@narratage/endpoint-kit";export function createMyServiceProvider(options: {instance: string;@@ -79,12 +79,12 @@ import {runtimeConfigObject,runtimeConfigString,runtimeConfigPositiveInteger,-} from "@svml/runtime-adapter";-import { diagnoseRuntimeEnvironmentCredential } from "@svml/runtime-adapter-node";+} from "@narratage/runtime-adapter";+import { diagnoseRuntimeEnvironmentCredential } from "@narratage/runtime-adapter-node";import { createMyServiceProvider } from "./provider.js";const adapter = createRuntimeEndpointAdapterFacet({- use: "@svml/provider-my-service",+ use: "@narratage/provider-my-service",create(context) {const config = runtimeConfigObject(context.config, "MyService");@@ -108,7 +108,7 @@ const adapter = createRuntimeEndpointAdapterFacet({export const svmlPackage = {format: "svml.node-package@1" as const,- name: "@svml/provider-my-service",+ name: "@narratage/provider-my-service",hostFacets: [adapter],};@@ -121,17 +121,17 @@ anything.## 5. Register and lock-Add the path mapping to `tsconfig.v2.json`:+Add the path mapping to `tsconfig.json`:```json-"@svml/provider-my-service": ["packages/provider-my-service/src/index.ts"]+"@narratage/provider-my-service": ["packages/provider-my-service/src/index.ts"]```Lock into a Runtime package lock:```bash-pnpm svml:v2 lock-packages <runtime-lock> \- --package @svml/provider-my-service \+pnpm narratage lock-packages <runtime-lock> \+ --package @narratage/provider-my-service \--root .```@@ -141,7 +141,7 @@ pnpm svml:v2 lock-packages <runtime-lock> \{"endpoints": [{- "use": "@svml/provider-my-service",+ "use": "@narratage/provider-my-service","instance": "my-service.project","lane": "generation","config": {@@ -159,7 +159,7 @@ pnpm svml:v2 lock-packages <runtime-lock> \Verify the configuration:```bash-pnpm svml:v2 doctor svml.runtime.json+pnpm narratage doctor svml.runtime.json```## Existing Providers to studydiff --git a/docs/guide/runtime-profile.md b/docs/guide/runtime-profile.mdindex e2d88857..46fc3d90 100644--- a/docs/guide/runtime-profile.md+++ b/docs/guide/runtime-profile.md@@ -26,7 +26,7 @@ Two forms are supported:"services": [],"endpoints": [{- "use": "@svml/provider-kie",+ "use": "@narratage/provider-kie","instance": "kie.production","lane": "generation","config": {@@ -35,19 +35,19 @@ Two forms are supported:}},{- "use": "@svml/provider-media-local",+ "use": "@narratage/provider-media-local","instance": "media.local","lane": "media","config": { "defaultConcurrency": 2 }},{- "use": "@svml/provider-whisperx-local",+ "use": "@narratage/provider-whisperx-local","instance": "whisperx.local","lane": "alignment","config": { "defaultConcurrency": 1 }},{- "use": "@svml/provider-google-vertex",+ "use": "@narratage/provider-google-vertex","instance": "vertex.local","lane": "planning","config": {@@ -57,7 +57,7 @@ Two forms are supported:}},{- "use": "@svml/provider-hyperframes-local",+ "use": "@narratage/provider-hyperframes-local","instance": "hyperframes.local","lane": "render","config": { "workers": 2, "quality": "standard", "defaultConcurrency": 1 }@@ -113,9 +113,9 @@ Each permission string grants one specific authority to the locked Endpoints:For advanced embedding, construct the Runtime programmatically:```typescript-import { createProjectLocalRuntime } from "@svml/local";-import { createKieProvider } from "@svml/provider-kie";-import { createLocalMediaProvider } from "@svml/provider-media-local";+import { createProjectLocalRuntime } from "@narratage/local";+import { createKieProvider } from "@narratage/provider-kie";+import { createLocalMediaProvider } from "@narratage/provider-media-local";export default async function createRuntime() {const endpoints = [@@ -148,8 +148,8 @@ export default async function createRuntime() {Pass either form to `--runtime`:```bash-pnpm svml:v2 build build.svrun --runtime ./svml.runtime.json-pnpm svml:v2 build build.svrun --runtime ./svml.runtime.ts+pnpm narratage build build.svrun --runtime ./svml.runtime.json+pnpm narratage build build.svrun --runtime ./svml.runtime.ts```## Diagnostics@@ -159,7 +159,7 @@ pnpm svml:v2 build build.svrun --runtime ./svml.runtime.tsChecks the Runtime Profile without running a Build or making paid requests:```bash-pnpm svml:v2 doctor svml.runtime.json+pnpm narratage doctor svml.runtime.json```Validates:@@ -172,8 +172,8 @@ Validates:### gc (garbage collection)```bash-pnpm svml:v2 gc svml.runtime.json # dry-run-pnpm svml:v2 gc svml.runtime.json --apply # delete unreachable Artifacts+pnpm narratage gc svml.runtime.json # dry-run+pnpm narratage gc svml.runtime.json --apply # delete unreachable Artifacts```Walks every retained BuildState and Operation, computes reachable Artifact digests, and reports@@ -187,13 +187,13 @@ Every Build archives all accepted Records and referenced Artifacts durably, inde### List Builds```bash-pnpm svml:v2 builds --runtime svml.runtime.json+pnpm narratage builds --runtime svml.runtime.json```### Inspect```bash-pnpm svml:v2 inspect <build-id> --runtime svml.runtime.json+pnpm narratage inspect <build-id> --runtime svml.runtime.json```Shows target bindings, demanded Logical Outputs, every accepted Record and Operation status.@@ -202,19 +202,19 @@ Shows target bindings, demanded Logical Outputs, every accepted Record and Opera```bash# By source output name-pnpm svml:v2 get <build-id> --runtime svml.runtime.json \+pnpm narratage get <build-id> --runtime svml.runtime.json \--name final.video --to output.mp4# By Record id-pnpm svml:v2 get <build-id> --runtime svml.runtime.json \+pnpm narratage get <build-id> --runtime svml.runtime.json \--record <record-id> --to output.json# By Logical Output id-pnpm svml:v2 get <build-id> --runtime svml.runtime.json \+pnpm narratage get <build-id> --runtime svml.runtime.json \--output <output-id># By Artifact digest-pnpm svml:v2 get <build-id> --runtime svml.runtime.json \+pnpm narratage get <build-id> --runtime svml.runtime.json \--artifact <sha256:...> --to file.bin```diff --git a/docs/guide/services.md b/docs/guide/services.mdindex 6b58357c..506be07e 100644--- a/docs/guide/services.md+++ b/docs/guide/services.md@@ -54,10 +54,10 @@ curl http://127.0.0.1:8765/health### ConcurrencyThe service admits exactly one inference at a time. A second request receives `503 BUSY`.-Concurrency is governed by the SVML Runtime Scheduler's lane configuration, not the service+Concurrency is governed by the Narratage Runtime Scheduler's lane configuration, not the serviceitself.-The Node Provider (`@svml/provider-whisperx-local`) must be configured with matching model,+The Node Provider (`@narratage/provider-whisperx-local`) must be configured with matching model,device, compute and batch size. A mismatch fails before results are accepted.### Tests@@ -69,7 +69,7 @@ pnpm test:whisperx-service## OpenCV image serviceProvides bounded image transforms (e.g. the GPT Image YCrCb denoise preset) through-`@svml/provider-image-opencv-local`.+`@narratage/provider-image-opencv-local`.### Installdiff --git a/docs/guide/testing.md b/docs/guide/testing.mdindex 5d9f22ea..95809138 100644--- a/docs/guide/testing.md+++ b/docs/guide/testing.md@@ -7,12 +7,10 @@ description: Test runner, patterns and environment-gated tests.## Test runner-SVML uses the Node.js built-in test runner (`node:test`), not Jest, Vitest or Mocha.+Narratage uses the Node.js built-in test runner (`node:test`), not Jest, Vitest or Mocha.```bash-pnpm test # everything: v1 + v2-pnpm test:v1 # v1 regression tests-pnpm test:v2 # v2 package tests + boundary tests+pnpm test # package tests + boundary tests```Test files live in `packages/<name>/test/` with the `.test.ts` extension. They are discovered by@@ -24,7 +22,7 @@ the glob `packages/*/test/**/*.test.ts`.import assert from "node:assert/strict";import { describe, test } from "node:test";-import { someFunction } from "@svml/example";+import { someFunction } from "@narratage/example";describe("someFunction", () => {test("returns the expected result", () => {@@ -74,7 +72,7 @@ structural invariants across the entire workspace:- Domain-neutral closure contains only domain-neutral packages- CLI has no Provider or author-package dependency-These run as part of `pnpm test:v2` on every commit.+These run as part of `pnpm test` on every commit.## Environment-gated tests@@ -86,10 +84,10 @@ These run as part of `pnpm test:v2` on every commit.## Test fixtures-Test fixtures go in `packages/<name>/test/fixtures/` or `test/fixtures/` (v1). They are+Test fixtures go in `packages/<name>/test/fixtures/`. They areordinary `.svml`, `.svs` and `.svrun` files that exercise specific compilation paths.The `examples/` directory also serves as integration-level fixtures:-- `examples/v2-bootstrap/` — smallest source closure check+- `examples/bootstrap/` — smallest source closure check- `examples/talking-film-graph-check/` — complete graph compilation without Providers- `examples/echo-pro-aroll/` — live acceptance with explicit historical-Candidate reusediff --git a/docs/quickstart.md b/docs/quickstart.mdindex c8925c91..77c3d0ad 100644--- a/docs/quickstart.md+++ b/docs/quickstart.md@@ -12,7 +12,8 @@ a montage of scenes to match.That is exactly what this system does. The author writes a narrated Script with semantic anchors,and the compiler assembles generated video, captions, B-roll, text and audio into a finished film.-The internal package scope is `@svml` (Semantic Video Markup Language).+Author Sources are written in SVML (Semantic Video Markup Language) and carry the `.svml`+extension; the workspace packages are published under the `@narratage` scope.## Install@@ -43,11 +44,11 @@ WhisperX, Gemini Caption, B-roll, Text, Film, HyperFrames — without calling an```bash# Compile the Author Source.-pnpm svml:v2 check examples/talking-film-graph-check/main.svml \+pnpm narratage check examples/talking-film-graph-check/main.svml \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .# Compile the Run Source and inspect the frozen plan.-pnpm svml:v2 plan examples/talking-film-graph-check/build.svrun \+pnpm narratage plan examples/talking-film-graph-check/build.svrun \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .```@@ -68,10 +69,10 @@ Prerequisites:```bash# Diagnose the Runtime environment.-pnpm svml:v2 doctor examples/echo-pro-aroll/svml.runtime.json+pnpm narratage doctor examples/echo-pro-aroll/svml.runtime.json# Submit the Build.-pnpm svml:v2 build examples/echo-pro-aroll/build.svrun \+pnpm narratage build examples/echo-pro-aroll/build.svrun \--runtime examples/echo-pro-aroll/svml.runtime.json \--package-lock examples/echo-pro-aroll/svml.packages.lock \--root . \@@ -79,7 +80,7 @@ pnpm svml:v2 build examples/echo-pro-aroll/build.svrun \--follow# Retrieve the final video.-pnpm svml:v2 get echo-pro-film-001 \+pnpm narratage get echo-pro-film-001 \--runtime examples/echo-pro-aroll/svml.runtime.json \--name final.video \--to examples/echo-pro-aroll/output/final.mp4@@ -90,11 +91,11 @@ makes an optional copy of an already durable Record.## Reuse previous results-SVML has no implicit cache. Reusing a result is explicit Run Graph authoring — declare zero-input+Narratage has no implicit cache. Reusing a result is explicit Run Graph authoring — declare zero-inputCandidates backed by historical Records and connect them through Satisfaction edges:```xml-<?svml using="@svml/run-text@1"?>+<?svml using="@narratage/run-text@1"?><svrun version="1" targets="delivery"><author source="./main.svml"/><target-set id="delivery">@@ -112,7 +113,7 @@ The compiled plan prunes all upstream Operations that the substitute Candidatesnew Build, not a continuation.```bash-pnpm svml:v2 build examples/echo-pro-aroll/reuse-generated.svrun \+pnpm narratage build examples/echo-pro-aroll/reuse-generated.svrun \--runtime examples/echo-pro-aroll/svml.runtime.json \--package-lock examples/echo-pro-aroll/svml.packages.lock \--root . --build-id echo-pro-film-reuse-001 --follow@@ -121,17 +122,17 @@ pnpm svml:v2 build examples/echo-pro-aroll/reuse-generated.svrun \## CLI reference```text-svml-v2 lock-packages <lock> --package name [--package name ...] [--root dir]-svml-v2 doctor <runtime.json>-svml-v2 gc <runtime.json> [--apply]-svml-v2 check <source> [--package-lock file] [--root dir]-svml-v2 plan <run-source> [--package-lock file] [--root dir]-svml-v2 build <run-source> --runtime profile [--build-id id] [--follow]-svml-v2 status <build-id> --runtime profile-svml-v2 builds --runtime profile-svml-v2 inspect <build-id> --runtime profile-svml-v2 get <build-id> --runtime profile [--name x|--record x|--output x|--artifact x] [--to path]-svml-v2 cancel <build-id> --runtime profile+narratage lock-packages <lock> --package name [--package name ...] [--root dir]+narratage doctor <runtime.json>+narratage gc <runtime.json> [--apply]+narratage check <source> [--package-lock file] [--root dir]+narratage plan <run-source> [--package-lock file] [--root dir]+narratage build <run-source> --runtime profile [--build-id id] [--follow]+narratage status <build-id> --runtime profile+narratage builds --runtime profile+narratage inspect <build-id> --runtime profile+narratage get <build-id> --runtime profile [--name x|--record x|--output x|--artifact x] [--to path]+narratage cancel <build-id> --runtime profile```## Nextdiff --git a/docs/zh/guide/author-packages.md b/docs/zh/guide/author-packages.mdindex 7ffd0284..e28921c2 100644--- a/docs/zh/guide/author-packages.md+++ b/docs/zh/guide/author-packages.md@@ -17,7 +17,7 @@ mkdir -p packages/my-component/src packages/my-component/test```json{- "name": "@svml/my-component",+ "name": "@narratage/my-component","version": "0.0.0-dev","private": true,"type": "module",@@ -28,9 +28,9 @@ mkdir -p packages/my-component/src packages/my-component/test"activation": "./src/activation.ts"},"dependencies": {- "@svml/protocol": "workspace:*",- "@svml/elaborator": "workspace:*",- "@svml/text": "workspace:*"+ "@narratage/protocol": "workspace:*",+ "@narratage/elaborator": "workspace:*",+ "@narratage/text": "workspace:*"}}```@@ -42,10 +42,10 @@ mkdir -p packages/my-component/src packages/my-component/test在 `src/index.ts` 中声明你的 Module 的身份、Type 和 Producer:```typescript-import type { ModuleManifest, ModuleRef } from "@svml/protocol";+import type { ModuleManifest, ModuleRef } from "@narratage/protocol";export const myComponentModuleRef: ModuleRef = {- name: "@svml/my-component",+ name: "@narratage/my-component",version: 1,};@@ -64,7 +64,7 @@ Surface handler 把 Text Frontend 的 XML 元素解码成带类型的作者声```typescript// src/surface.ts-import type { TextSurfaceDecoder } from "@svml/text";+import type { TextSurfaceDecoder } from "@narratage/text";export const decodeMyComponentSurface: TextSurfaceDecoder = (element, context) => {// Read attributes and children from the XML element@@ -83,7 +83,7 @@ export const decodeMyComponentSurface: TextSurfaceDecoder = (element, context) =```typescript// src/activation.ts-import { createTextSurfaceHostFacet } from "@svml/text";+import { createTextSurfaceHostFacet } from "@narratage/text";import {myComponentManifest,myComponentModuleRef,@@ -92,10 +92,10 @@ import {export const svmlPackage = {format: "svml.node-package@1" as const,- name: "@svml/my-component",+ name: "@narratage/my-component",modules: [{manifest: myComponentManifest,- specifiers: ["@svml/my-component", "@svml/my-component@1"],+ specifiers: ["@narratage/my-component", "@narratage/my-component@1"],}],hostFacets: [createTextSurfaceHostFacet({@@ -113,12 +113,12 @@ export default svmlPackage;`specifiers` 数组列出了 `<import from="..."/>` 会去匹配的字符串。`surface` 字符串决定 XML 元素前缀(以 `mine` 导入时即为 `<mine:my-widget>`)。-## 6. 在 tsconfig.v2.json 中注册+## 6. 在 tsconfig.json 中注册-添加路径映射,让 TypeScript 把 `@svml/my-component` 解析到源码:+添加路径映射,让 TypeScript 把 `@narratage/my-component` 解析到源码:```json-"@svml/my-component": ["packages/my-component/src/index.ts"]+"@narratage/my-component": ["packages/my-component/src/index.ts"]```## 7. 安装并锁定@@ -126,18 +126,18 @@ export default svmlPackage;```bashpnpm install-pnpm svml:v2 lock-packages <lock-file> \- --package @svml/my-component \- [--package @svml/other-dep ...] \+pnpm narratage lock-packages <lock-file> \+ --package @narratage/my-component \+ [--package @narratage/other-dep ...] \--root .```## 8. 在 Author Source 中使用```xml-<?svml using="@svml/text@1"?>+<?svml using="@narratage/text@1"?><svml>- <import as="mine" from="@svml/my-component@1"/>+ <import as="mine" from="@narratage/my-component@1"/><mine:Widget id="demo" during={story.selection.example}/></svml>diff --git a/docs/zh/guide/conventions.md b/docs/zh/guide/conventions.mdindex b36c881e..7cf66b36 100644--- a/docs/zh/guide/conventions.md+++ b/docs/zh/guide/conventions.md@@ -10,8 +10,8 @@ description: 命名、模块边界、TypeScript 配置与 wire 数据。| 项目 | 约定 | 示例 ||---|---|---|| 包目录 | kebab-case | `packages/speech-align/` |-| 包名 | `@svml/` scope | `@svml/speech-align` |-| Provider 包 | `provider-` 前缀 | `@svml/provider-kie` |+| 包名 | `@narratage/` scope | `@narratage/speech-align` |+| Provider 包 | `provider-` 前缀 | `@narratage/provider-kie` || TypeScript 文件 | kebab-case | `speech-align.ts` || 导出类型 | PascalCase | `SpeechAlignment` || 导出函数 | camelCase | `createSpeechAlignment` |@@ -20,12 +20,12 @@ description: 命名、模块边界、TypeScript 配置与 wire 数据。- 每个包有且只有一个公开入口点:`src/index.ts`。- 内部模块使用显式的 `.js` 扩展名(NodeNext 解析)。-- 跨包导入使用 `@svml/*`,绝不跨包边界使用相对路径。+- 跨包导入使用 `@narratage/*`,绝不跨包边界使用相对路径。- 禁止循环依赖(由 `tools/package-boundaries.test.mjs` 强制执行)。## TypeScript 配置-`tsconfig.v2.json` 继承 `tsconfig.json`,并为所有 `@svml/*` 包添加 `paths` 映射。+`tsconfig.json` 继承 `tsconfig.json`,并为所有 `@narratage/*` 包添加 `paths` 映射。| 配置项 | 值 ||---|---|@@ -36,16 +36,16 @@ description: 命名、模块边界、TypeScript 配置与 wire 数据。| `noUncheckedIndexedAccess` | `true` — 索引访问返回 `T \| undefined` || `exactOptionalPropertyTypes` | `true` — `undefined` 必须显式写出 |-新增一个包时,要把它的路径映射加入 `tsconfig.v2.json`:+新增一个包时,要把它的路径映射加入 `tsconfig.json`:```json-"@svml/my-package": ["packages/my-package/src/index.ts"]+"@narratage/my-package": ["packages/my-package/src/index.ts"]```## wire 数据-- 所有持久化数据使用 `@2` wire 格式版本。-- wire 类型定义在 `@svml/protocol` 中,且不可变。+- 所有持久化数据使用 `@1` wire 格式版本。+- wire 类型定义在 `@narratage/protocol` 中,且不可变。- Nominal Type 由 Module 拥有,不在中心化的联合类型中注册。- 类型 schema 使用与 JSON 兼容的结构,而不是 TypeScript 接口。diff --git a/docs/zh/guide/develop.md b/docs/zh/guide/develop.mdindex 32065eea..fc6909a4 100644--- a/docs/zh/guide/develop.md+++ b/docs/zh/guide/develop.md@@ -22,40 +22,32 @@ description: 开始 Narratage 开发工作。```bashpnpm install # 拉取代码或改动依赖之后-pnpm check # TypeScript 类型检查:v1 + v2-pnpm test # 完整测试套件:v1 + v2+pnpm check # TypeScript 类型检查+pnpm test # 完整测试套件```| 命令 | 实际执行什么 ||---|---|-| `pnpm check:v1` | `tsc -p tsconfig.json --noEmit` —— 保留下来的 v1 research oracle |-| `pnpm check:v2` | `tsc -p tsconfig.v2.json --noEmit` —— 全部 v2 workspace 包 |-| `pnpm test:v1` | `node --import tsx --test 'test/**/*.test.ts'` |-| `pnpm test:v2` | `node --import tsx --test 'packages/*/test/**/*.test.ts' 'tools/*.test.mjs'` |+| `pnpm check` | `tsc -p tsconfig.json --noEmit` |+| `pnpm test` | `node --import tsx --test 'packages/*/test/**/*.test.ts' 'tools/*.test.mjs'` |-关于受环境开关控制的测试与测试写法,参见 [Testing](./testing.md)。+关于受环境开关控制的测试与测试写法,参见[测试](./testing.md)。## 仓库结构```text-svml/-├── packages/ 64 v2 workspace packages (the active system)+narratage/+├── packages/ 78 workspace packages├── spec/ 7 normative specification documents├── docs/ VitePress documentation site-├── examples/ v2 examples and v1 regression fixtures+├── examples/ runnable example sources├── services/ Python sidecar services (whisperx, image-opencv)-├── src/ v1 legacy source (regression evidence only)-├── stdlib/ v1 kernel definitions and runtime-├── test/ v1 test suite├── tools/ boundary tests and build scripts├── package.json root workspace manifest├── pnpm-workspace.yaml workspace: [packages/*]-├── tsconfig.json v1 TypeScript config-└── tsconfig.v2.json v2 TypeScript config+└── tsconfig.json TypeScript config```-`src/`、`stdlib/` 与 `test/` 是 v1 research oracle,作为回归证据保留下来。它们不是 v2 API。-## 指南目录| 指南 | 主题 |diff --git a/docs/zh/guide/packages.md b/docs/zh/guide/packages.mdindex da0f64bf..cbb9233e 100644--- a/docs/zh/guide/packages.md+++ b/docs/zh/guide/packages.md@@ -5,7 +5,7 @@ description: 四个分层、依赖边界、包的结构与 facet。# 包架构-`packages/` 下的 64 个以上工作区包被组织成四个架构分层。每一层都有严格的依赖规则,并由测试在每次提交时强制执行。+`packages/` 下的 78 个工作区包被组织成四个架构分层。每一层都有严格的依赖规则,并由测试在每次提交时强制执行。## 四个分层@@ -14,32 +14,32 @@ description: 四个分层、依赖边界、包的结构与 facet。这些包实现图语言、Build 状态机、编译器基础设施和 Runtime 端口。它们可以被任意领域复用 —— 不只是视频 —— 并且不依赖 Text、Script、Seedance、Film 或任何视频概念。```text-@svml/protocol immutable wire contracts-@svml/artifact domain-neutral content-addressed byte type-@svml/core Demand compiler and Build state machine-@svml/source mandatory Source Header-@svml/elaborator author declarations and Fragment expansion-@svml/realization typed realization overlays-@svml/run syntax-neutral Run Graph-@svml/validation semantic admission-@svml/host Host-facing interfaces-@svml/compiler-node reference Node compiler Host-@svml/workspace-fs-node workspace filesystem abstraction-@svml/component-kit Producer/validator registration-@svml/runtime Scheduler and Store ports-@svml/runtime-adapter deployment-adapter ABI-@svml/runtime-adapter-node project-root resolution-@svml/endpoint-kit Endpoint registration-@svml/driver-node trusted Node command executor-@svml/package-loader-node byte-locked package loading-@svml/store-sqlite SQLite Build/Operation stores-@svml/artifact-store-fs filesystem Artifact store-@svml/artifact-store-s3 S3 Artifact store-@svml/credential-store-env environment credentials-@svml/transport invocation seams-@svml/transport-process local process transport-@svml/transport-aws-lambda Lambda transport-@svml/local SQLite/filesystem developer assembly+@narratage/protocol immutable wire contracts+@narratage/artifact domain-neutral content-addressed byte type+@narratage/core Demand compiler and Build state machine+@narratage/source mandatory Source Header+@narratage/elaborator author declarations and Fragment expansion+@narratage/realization typed realization overlays+@narratage/run syntax-neutral Run Graph+@narratage/validation semantic admission+@narratage/host Host-facing interfaces+@narratage/compiler-node reference Node compiler Host+@narratage/workspace-fs-node workspace filesystem abstraction+@narratage/component-kit Producer/validator registration+@narratage/runtime Scheduler and Store ports+@narratage/runtime-adapter deployment-adapter ABI+@narratage/runtime-adapter-node project-root resolution+@narratage/endpoint-kit Endpoint registration+@narratage/driver-node trusted Node command executor+@narratage/package-loader-node byte-locked package loading+@narratage/store-sqlite SQLite Build/Operation stores+@narratage/artifact-store-fs filesystem Artifact store+@narratage/artifact-store-s3 S3 Artifact store+@narratage/credential-store-env environment credentials+@narratage/transport invocation seams+@narratage/transport-process local process transport+@narratage/transport-aws-lambda Lambda transport+@narratage/local SQLite/filesystem developer assembly```### Layer 2:作者语言层@@ -47,12 +47,12 @@ description: 四个分层、依赖边界、包的结构与 facet。面向作者的词汇:文本 Frontend、Script Surface、SVS Recipe、Run 文本 Frontend 以及可复用的编译库。```text-@svml/text official .svml markup Frontend-@svml/script Script Surface-@svml/svs SVS Recipe Frontend-@svml/run-text official .svrun Frontend-@svml/prompt-kit declarative prompt compilation-@svml/compiler-text-node Text Frontend + Surface Host assembly+@narratage/text official .svml markup Frontend+@narratage/script Script Surface+@narratage/svs SVS Recipe Frontend+@narratage/run-text official .svrun Frontend+@narratage/prompt-kit declarative prompt compilation+@narratage/compiler-text-node Text Frontend + Surface Host assembly```### Layer 3:视频领域层@@ -60,32 +60,32 @@ description: 四个分层、依赖边界、包的结构与 facet。视频专属类型、生成模型族、语音/字幕/轨道契约以及合成。依赖 Layer 1 和 Layer 2,但不依赖任何 Provider。```text-@svml/contracts Narrative, Track, Composition contracts-@svml/media media types-@svml/generation image/video product contracts-@svml/model-kit model family abstractions-@svml/seedance Seedance model family + author Surface-@svml/seedance-speaker Seedance Speaker binding-@svml/minimax-h3 MiniMax H3 model family-@svml/gemini-omni Gemini Omni model family-@svml/grok-imagine Grok Imagine model family-@svml/gpt-image GPT Image model family-@svml/nano-banana Nano Banana model family-@svml/seedream Seedream model family-@svml/estimate duration estimation-@svml/speech-program speech program compilation-@svml/speech-take atomic speech take-@svml/speech-align speech alignment-@svml/whisperx WhisperX component-@svml/caption caption planning and Track-@svml/caption-gemini Gemini caption planner-@svml/broll B-roll Track-@svml/text-track text overlay Track-@svml/film Film composition-@svml/hyperframes HyperFrames Visual IR-@svml/hyperframes-render HyperFrames rendering component-@svml/image-transform image processing component-@svml/media-pipeline media inspection/normalization+@narratage/contracts Narrative, Track, Composition contracts+@narratage/media media types+@narratage/generation image/video product contracts+@narratage/model-kit model family abstractions+@narratage/seedance Seedance model family + author Surface+@narratage/seedance-speaker Seedance Speaker binding+@narratage/minimax-h3 MiniMax H3 model family+@narratage/gemini-omni Gemini Omni model family+@narratage/grok-imagine Grok Imagine model family+@narratage/gpt-image GPT Image model family+@narratage/nano-banana Nano Banana model family+@narratage/seedream Seedream model family+@narratage/estimate duration estimation+@narratage/speech-program speech program compilation+@narratage/speech-take atomic speech take+@narratage/speech-align speech alignment+@narratage/whisperx WhisperX component+@narratage/caption caption planning and Track+@narratage/caption-gemini Gemini caption planner+@narratage/broll B-roll Track+@narratage/text-track text overlay Track+@narratage/film Film composition+@narratage/hyperframes HyperFrames Visual IR+@narratage/hyperframes-render HyperFrames rendering component+@narratage/image-transform image processing component+@narratage/media-pipeline media inspection/normalization```### Layer 4:Provider(Endpoint)包@@ -93,30 +93,30 @@ description: 四个分层、依赖边界、包的结构与 facet。具备特权的外部能力。依赖 Runtime 端口和它们所服务的模型族,绝不依赖 CLI。```text-@svml/provider-kie KIE generation (16 model capabilities)-@svml/provider-media-local local ffprobe/ffmpeg-@svml/provider-whisperx-local local WhisperX sidecar-@svml/provider-google-vertex Vertex Gemini caption planning-@svml/provider-hyperframes-local local Chrome rendering-@svml/provider-image-opencv-local local OpenCV image transforms+@narratage/provider-kie KIE generation (16 model capabilities)+@narratage/provider-media-local local ffprobe/ffmpeg+@narratage/provider-whisperx-local local WhisperX sidecar+@narratage/provider-google-vertex Vertex Gemini caption planning+@narratage/provider-hyperframes-local local Chrome rendering+@narratage/provider-image-opencv-local local OpenCV image transforms```### 应用层```text-@svml/cli generic command engine (requires explicit Distribution)-@svml/video-cli video command application (selects Text compiler, no built-in author packages)+@narratage/cli generic command engine (requires explicit Distribution)+@narratage/video-cli video command application (selects Text compiler, no built-in author packages)```## 依赖规则`tools/package-boundaries.test.mjs` 在每次提交时强制执行三条不变式:-1. **无环的生产依赖图。** 任何 `@svml/*` 包之间都不存在依赖环。+1. **无环的生产依赖图。** 任何 `@narratage/*` 包之间都不存在依赖环。-2. **领域无关闭包。** 每个 Layer 1 包的传递闭包只包含 Layer 1 的包。`@svml/core` 只依赖 `@svml/protocol`。+2. **领域无关闭包。** 每个 Layer 1 包的传递闭包只包含 Layer 1 的包。`@narratage/core` 只依赖 `@narratage/protocol`。-3. **CLI 独立性。** `@svml/cli` 和 `@svml/video-cli` 都不会传递依赖任何 Provider 包。video CLI 同样不依赖任何作者层的视频包(`@svml/script`、`@svml/seedance-speaker`、`@svml/broll`、`@svml/text-track`、`@svml/film`)。作者包通过显式的 package lock 被 activate,而不是通过编译期的 CLI 依赖。+3. **CLI 独立性。** `@narratage/cli` 和 `@narratage/video-cli` 都不会传递依赖任何 Provider 包。video CLI 同样不依赖任何作者层的视频包(`@narratage/script`、`@narratage/seedance-speaker`、`@narratage/broll`、`@narratage/text-track`、`@narratage/film`)。作者包通过显式的 package lock 被 activate,而不是通过编译期的 CLI 依赖。## 包的结构@@ -136,7 +136,7 @@ packages/example/```json{- "name": "@svml/example",+ "name": "@narratage/example","version": "0.0.0-dev","private": true,"type": "module",@@ -147,12 +147,12 @@ packages/example/"activation": "./src/activation.ts"},"dependencies": {- "@svml/protocol": "workspace:*"+ "@narratage/protocol": "workspace:*"}}```-- `"exports"` 直接指向 TypeScript 源码。工作区的 `tsconfig.v2.json` 通过 `paths` 把 `@svml/*` 导入映射到源码入口。+- `"exports"` 直接指向 TypeScript 源码。工作区的 `tsconfig.json` 通过 `paths` 把 `@narratage/*` 导入映射到源码入口。- `"svml.activation"` 是该包被 byte-locked 时 Package Loader 会读取的入口。它必须默认导出一个 `NodePackageContribution`。### activation.ts@@ -182,7 +182,7 @@ SVML 使用按字节锁定的受信任代码执行。加载器会记录每个包"format": "svml.node-package-lock@1","artifacts": [{- "name": "@svml/seedance",+ "name": "@narratage/seedance","version": "0.0.0-dev","digest": "sha256:abc123..."}diff --git a/docs/zh/guide/providers.md b/docs/zh/guide/providers.mdindex 51a68e65..2ed7324e 100644--- a/docs/zh/guide/providers.md+++ b/docs/zh/guide/providers.md@@ -21,7 +21,7 @@ Provider 包依赖 Runtime 端口以及它所服务的模型族,绝不依赖 C```json{- "name": "@svml/provider-my-service",+ "name": "@narratage/provider-my-service","version": "0.0.0-dev","private": true,"type": "module",@@ -30,12 +30,12 @@ Provider 包依赖 Runtime 端口以及它所服务的模型族,绝不依赖 C},"svml": { "activation": "./src/activation.ts" },"dependencies": {- "@svml/endpoint-kit": "workspace:*",- "@svml/protocol": "workspace:*",- "@svml/runtime": "workspace:*",- "@svml/runtime-adapter": "workspace:*",- "@svml/runtime-adapter-node": "workspace:*",- "@svml/seedance": "workspace:*"+ "@narratage/endpoint-kit": "workspace:*",+ "@narratage/protocol": "workspace:*",+ "@narratage/runtime": "workspace:*",+ "@narratage/runtime-adapter": "workspace:*",+ "@narratage/runtime-adapter-node": "workspace:*",+ "@narratage/seedance": "workspace:*"}}```@@ -46,7 +46,7 @@ Provider 处理来自 Scheduler 的 Command:提交请求、轮询、下载以```typescript// src/provider.ts-import type { EndpointManifest } from "@svml/endpoint-kit";+import type { EndpointManifest } from "@narratage/endpoint-kit";export function createMyServiceProvider(options: {instance: string;@@ -76,12 +76,12 @@ import {runtimeConfigObject,runtimeConfigString,runtimeConfigPositiveInteger,-} from "@svml/runtime-adapter";-import { diagnoseRuntimeEnvironmentCredential } from "@svml/runtime-adapter-node";+} from "@narratage/runtime-adapter";+import { diagnoseRuntimeEnvironmentCredential } from "@narratage/runtime-adapter-node";import { createMyServiceProvider } from "./provider.js";const adapter = createRuntimeEndpointAdapterFacet({- use: "@svml/provider-my-service",+ use: "@narratage/provider-my-service",create(context) {const config = runtimeConfigObject(context.config, "MyService");@@ -105,7 +105,7 @@ const adapter = createRuntimeEndpointAdapterFacet({export const svmlPackage = {format: "svml.node-package@1" as const,- name: "@svml/provider-my-service",+ name: "@narratage/provider-my-service",hostFacets: [adapter],};@@ -116,17 +116,17 @@ export default svmlPackage;## 5. 注册并锁定-在 `tsconfig.v2.json` 中添加路径映射:+在 `tsconfig.json` 中添加路径映射:```json-"@svml/provider-my-service": ["packages/provider-my-service/src/index.ts"]+"@narratage/provider-my-service": ["packages/provider-my-service/src/index.ts"]```锁定进 Runtime 包锁文件:```bash-pnpm svml:v2 lock-packages <runtime-lock> \- --package @svml/provider-my-service \+pnpm narratage lock-packages <runtime-lock> \+ --package @narratage/provider-my-service \--root .```@@ -136,7 +136,7 @@ pnpm svml:v2 lock-packages <runtime-lock> \{"endpoints": [{- "use": "@svml/provider-my-service",+ "use": "@narratage/provider-my-service","instance": "my-service.project","lane": "generation","config": {@@ -154,7 +154,7 @@ pnpm svml:v2 lock-packages <runtime-lock> \验证配置:```bash-pnpm svml:v2 doctor svml.runtime.json+pnpm narratage doctor svml.runtime.json```## 可供研究的现有 Providerdiff --git a/docs/zh/guide/runtime-profile.md b/docs/zh/guide/runtime-profile.mdindex eedcd944..34a06ece 100644--- a/docs/zh/guide/runtime-profile.md+++ b/docs/zh/guide/runtime-profile.md@@ -24,7 +24,7 @@ Runtime Profile 声明冻结后的 Build *在哪里*执行:Endpoint、凭据"services": [],"endpoints": [{- "use": "@svml/provider-kie",+ "use": "@narratage/provider-kie","instance": "kie.production","lane": "generation","config": {@@ -33,19 +33,19 @@ Runtime Profile 声明冻结后的 Build *在哪里*执行:Endpoint、凭据}},{- "use": "@svml/provider-media-local",+ "use": "@narratage/provider-media-local","instance": "media.local","lane": "media","config": { "defaultConcurrency": 2 }},{- "use": "@svml/provider-whisperx-local",+ "use": "@narratage/provider-whisperx-local","instance": "whisperx.local","lane": "alignment","config": { "defaultConcurrency": 1 }},{- "use": "@svml/provider-google-vertex",+ "use": "@narratage/provider-google-vertex","instance": "vertex.local","lane": "planning","config": {@@ -55,7 +55,7 @@ Runtime Profile 声明冻结后的 Build *在哪里*执行:Endpoint、凭据}},{- "use": "@svml/provider-hyperframes-local",+ "use": "@narratage/provider-hyperframes-local","instance": "hyperframes.local","lane": "render","config": { "workers": 2, "quality": "standard", "defaultConcurrency": 1 }@@ -110,9 +110,9 @@ Runtime Profile 声明冻结后的 Build *在哪里*执行:Endpoint、凭据用于高级嵌入场景,以编程方式构造 Runtime:```typescript-import { createProjectLocalRuntime } from "@svml/local";-import { createKieProvider } from "@svml/provider-kie";-import { createLocalMediaProvider } from "@svml/provider-media-local";+import { createProjectLocalRuntime } from "@narratage/local";+import { createKieProvider } from "@narratage/provider-kie";+import { createLocalMediaProvider } from "@narratage/provider-media-local";export default async function createRuntime() {const endpoints = [@@ -145,8 +145,8 @@ export default async function createRuntime() {两种形式都可以传给 `--runtime`:```bash-pnpm svml:v2 build build.svrun --runtime ./svml.runtime.json-pnpm svml:v2 build build.svrun --runtime ./svml.runtime.ts+pnpm narratage build build.svrun --runtime ./svml.runtime.json+pnpm narratage build build.svrun --runtime ./svml.runtime.ts```## 诊断@@ -156,7 +156,7 @@ pnpm svml:v2 build build.svrun --runtime ./svml.runtime.ts在不运行 Build、不发出付费请求的前提下检查 Runtime Profile:```bash-pnpm svml:v2 doctor svml.runtime.json+pnpm narratage doctor svml.runtime.json```校验内容:@@ -169,8 +169,8 @@ pnpm svml:v2 doctor svml.runtime.json### gc(垃圾回收)```bash-pnpm svml:v2 gc svml.runtime.json # dry-run-pnpm svml:v2 gc svml.runtime.json --apply # delete unreachable Artifacts+pnpm narratage gc svml.runtime.json # dry-run+pnpm narratage gc svml.runtime.json --apply # delete unreachable Artifacts```遍历每个保留的 BuildState 与 Operation,计算可达的 Artifact 摘要,并报告(或删除)不可达的孤儿对象。@@ -182,13 +182,13 @@ pnpm svml:v2 gc svml.runtime.json --apply # delete unreachable Artifacts### 列出 Build```bash-pnpm svml:v2 builds --runtime svml.runtime.json+pnpm narratage builds --runtime svml.runtime.json```### 检视```bash-pnpm svml:v2 inspect <build-id> --runtime svml.runtime.json+pnpm narratage inspect <build-id> --runtime svml.runtime.json```显示 target 绑定、被请求的 Logical Output、每个已接受的 Record 以及 Operation 状态。@@ -197,19 +197,19 @@ pnpm svml:v2 inspect <build-id> --runtime svml.runtime.json```bash# By source output name-pnpm svml:v2 get <build-id> --runtime svml.runtime.json \+pnpm narratage get <build-id> --runtime svml.runtime.json \--name final.video --to output.mp4# By Record id-pnpm svml:v2 get <build-id> --runtime svml.runtime.json \+pnpm narratage get <build-id> --runtime svml.runtime.json \--record <record-id> --to output.json# By Logical Output id-pnpm svml:v2 get <build-id> --runtime svml.runtime.json \+pnpm narratage get <build-id> --runtime svml.runtime.json \--output <output-id># By Artifact digest-pnpm svml:v2 get <build-id> --runtime svml.runtime.json \+pnpm narratage get <build-id> --runtime svml.runtime.json \--artifact <sha256:...> --to file.bin```diff --git a/docs/zh/guide/services.md b/docs/zh/guide/services.mdindex 09d7906c..01c93101 100644--- a/docs/zh/guide/services.md+++ b/docs/zh/guide/services.md@@ -49,9 +49,9 @@ curl http://127.0.0.1:8765/health### 并发-该服务同一时刻只接纳一次推理。第二个请求会收到 `503 BUSY`。并发由 SVML Runtime Scheduler 的 lane 配置管控,而不是由服务自身管控。+该服务同一时刻只接纳一次推理。第二个请求会收到 `503 BUSY`。并发由 Narratage Runtime Scheduler 的 lane 配置管控,而不是由服务自身管控。-Node Provider(`@svml/provider-whisperx-local`)必须配置与之匹配的模型、设备、计算类型和批大小。一旦不匹配,会在结果被接受之前失败。+Node Provider(`@narratage/provider-whisperx-local`)必须配置与之匹配的模型、设备、计算类型和批大小。一旦不匹配,会在结果被接受之前失败。### 测试@@ -61,7 +61,7 @@ pnpm test:whisperx-service## OpenCV 图像服务-通过 `@svml/provider-image-opencv-local` 提供有上界的图像变换(例如 GPT Image 的 YCrCb 降噪预设)。+通过 `@narratage/provider-image-opencv-local` 提供有上界的图像变换(例如 GPT Image 的 YCrCb 降噪预设)。### 安装diff --git a/docs/zh/guide/testing.md b/docs/zh/guide/testing.mdindex 473e8e55..9834e45e 100644--- a/docs/zh/guide/testing.md+++ b/docs/zh/guide/testing.md@@ -7,12 +7,10 @@ description: 测试运行器、测试模式与环境门控的测试。## 测试运行器-SVML 使用 Node.js 内置的测试运行器(`node:test`),而不是 Jest、Vitest 或 Mocha。+Narratage 使用 Node.js 内置的测试运行器(`node:test`),而不是 Jest、Vitest 或 Mocha。```bash-pnpm test # everything: v1 + v2-pnpm test:v1 # v1 regression tests-pnpm test:v2 # v2 package tests + boundary tests+pnpm test # 包测试 + boundary 测试```测试文件位于 `packages/<name>/test/`,扩展名为 `.test.ts`。它们通过 glob `packages/*/test/**/*.test.ts` 被发现。@@ -23,7 +21,7 @@ pnpm test:v2 # v2 package tests + boundary testsimport assert from "node:assert/strict";import { describe, test } from "node:test";-import { someFunction } from "@svml/example";+import { someFunction } from "@narratage/example";describe("someFunction", () => {test("returns the expected result", () => {@@ -70,7 +68,7 @@ test("generates a video", async (t) => {- 领域中立闭包中只包含领域中立的包- CLI 不依赖任何 Provider 或作者包-它们作为 `pnpm test:v2` 的一部分,在每次提交时运行。+它们作为 `pnpm test` 的一部分,在每次提交时运行。## 受环境开关控制的测试@@ -82,9 +80,9 @@ test("generates a video", async (t) => {## 测试 fixtures-测试夹具放在 `packages/<name>/test/fixtures/` 或 `test/fixtures/`(v1)。它们是普通的 `.svml`、`.svs` 和 `.svrun` 文件,用于覆盖特定的编译路径。+测试夹具放在 `packages/<name>/test/fixtures/`。它们是普通的 `.svml`、`.svs` 和 `.svrun` 文件,用于覆盖特定的编译路径。`examples/` 目录同时充当集成级别的夹具:-- `examples/v2-bootstrap/` — 最小源闭包检查+- `examples/bootstrap/` — 最小源闭包检查- `examples/talking-film-graph-check/` — 不含 Provider 的完整图编译- `examples/echo-pro-aroll/` — 显式复用历史 Candidate 的实时验收diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.mdindex 0b946d4c..76dec191 100644--- a/docs/zh/quickstart.md+++ b/docs/zh/quickstart.md@@ -10,7 +10,8 @@ Glory*》的一篇影评。那位影评人造出这个词,用来描述当时**Narration + Montage** —— 旁白的声音推动故事前进,同时画面组接出与之呼应的蒙太奇。这套系统做的正是这件事。作者写下带有语义锚点的口播 Script,编译器则把生成的视频、字幕、B-roll、-文字与音频组装成一部完成的影片。内部的包作用域是 `@svml`(Semantic Video Markup Language)。+文字与音频组装成一部完成的影片。Author Source 使用 SVML(Semantic Video Markup Language)编写,+扩展名为 `.svml`;工作区包则发布在 `@narratage` 作用域下。## 安装@@ -41,11 +42,11 @@ WhisperX、Gemini Caption、B-roll、Text、Film、HyperFrames —— 全程不```bash# 编译 Author Source。-pnpm svml:v2 check examples/talking-film-graph-check/main.svml \+pnpm narratage check examples/talking-film-graph-check/main.svml \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .# 编译 Run Source 并查看冻结后的 plan。-pnpm svml:v2 plan examples/talking-film-graph-check/build.svrun \+pnpm narratage plan examples/talking-film-graph-check/build.svrun \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .```@@ -65,10 +66,10 @@ pnpm svml:v2 plan examples/talking-film-graph-check/build.svrun \```bash# 诊断 Runtime 环境。-pnpm svml:v2 doctor examples/echo-pro-aroll/svml.runtime.json+pnpm narratage doctor examples/echo-pro-aroll/svml.runtime.json# 提交 Build。-pnpm svml:v2 build examples/echo-pro-aroll/build.svrun \+pnpm narratage build examples/echo-pro-aroll/build.svrun \--runtime examples/echo-pro-aroll/svml.runtime.json \--package-lock examples/echo-pro-aroll/svml.packages.lock \--root . \@@ -76,7 +77,7 @@ pnpm svml:v2 build examples/echo-pro-aroll/build.svrun \--follow# 取回最终视频。-pnpm svml:v2 get echo-pro-film-001 \+pnpm narratage get echo-pro-film-001 \--runtime examples/echo-pro-aroll/svml.runtime.json \--name final.video \--to examples/echo-pro-aroll/output/final.mp4@@ -91,7 +92,7 @@ SVML 没有隐式缓存。复用结果是显式的 Run Graph 编写工作 ——Candidates,再用 Satisfaction edges 把它们接起来:```xml-<?svml using="@svml/run-text@1"?>+<?svml using="@narratage/run-text@1"?><svrun version="1" targets="delivery"><author source="./main.svml"/><target-set id="delivery">@@ -109,7 +110,7 @@ Candidates,再用 Satisfaction edges 把它们接起来:而不是对上一次的续跑。```bash-pnpm svml:v2 build examples/echo-pro-aroll/reuse-generated.svrun \+pnpm narratage build examples/echo-pro-aroll/reuse-generated.svrun \--runtime examples/echo-pro-aroll/svml.runtime.json \--package-lock examples/echo-pro-aroll/svml.packages.lock \--root . --build-id echo-pro-film-reuse-001 --follow@@ -118,17 +119,17 @@ pnpm svml:v2 build examples/echo-pro-aroll/reuse-generated.svrun \## CLI 参考```text-svml-v2 lock-packages <lock> --package name [--package name ...] [--root dir]-svml-v2 doctor <runtime.json>-svml-v2 gc <runtime.json> [--apply]-svml-v2 check <source> [--package-lock file] [--root dir]-svml-v2 plan <run-source> [--package-lock file] [--root dir]-svml-v2 build <run-source> --runtime profile [--build-id id] [--follow]-svml-v2 status <build-id> --runtime profile-svml-v2 builds --runtime profile-svml-v2 inspect <build-id> --runtime profile-svml-v2 get <build-id> --runtime profile [--name x|--record x|--output x|--artifact x] [--to path]-svml-v2 cancel <build-id> --runtime profile+narratage lock-packages <lock> --package name [--package name ...] [--root dir]+narratage doctor <runtime.json>+narratage gc <runtime.json> [--apply]+narratage check <source> [--package-lock file] [--root dir]+narratage plan <run-source> [--package-lock file] [--root dir]+narratage build <run-source> --runtime profile [--build-id id] [--follow]+narratage status <build-id> --runtime profile+narratage builds --runtime profile+narratage inspect <build-id> --runtime profile+narratage get <build-id> --runtime profile [--name x|--record x|--output x|--artifact x] [--to path]+narratage cancel <build-id> --runtime profile```## 下一步