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: consolidate architecture and remove stale records
kashorin5282bc8555c3
diff --git a/README.md b/README.mdindex cb691fa3..450c37b6 100644--- a/README.md+++ b/README.md@@ -1,269 +1,192 @@# SVML-> **v2 bootstrap:** `packages/protocol`, `packages/core` and `packages/driver-node`-> implement the domain-free `LogicalOutput / Candidate / Operation / Target` kernel and an explicitly-> registered Node Host. A single Build Compiler resolves each demanded Logical Output, selects its-> Candidate from a `BuildRequest`, and memoizes the reverse closure by stable `OperationId` before the-> Build Machine executes anything. Reuse and product-level “Pin” UI actions are ordinary-> Existing-Value Candidates, not Core branches; Providers only execute already selected exact-> CapabilityRefs. Declarative affinity compares intrinsic identities such as ProgramSpace and the-> exact acoustic Blob; dependency and provenance truth stay in Graph, Derivation and Receipt.-> `packages/speech-take` proves atomic Product plus ordinary audio/visual Projection;-> `packages/elaborator` now links parser-independent Author Modules in two phases—predeclaring every-> component output before resolving forward references—and expands content-addressed static-> Fragments with hygienic instance identities;-> `packages/realization` attaches locked Existing-Value or Fragment Candidates without changing the-> author graph identity. These are executable reference layers outside Core, not new Kernel magic.-> `packages/speech-program` now owns the namespaced Speech Spine Surface and composes normalized-> generated Takes into one audio master, one ProgramSpace and peer Tracks. `packages/whisperx`-> owns the explicit alignment Surface; provider-neutral SemanticMap and Caption timing remain-> separately auditable Operations. Producer-declared affinity protects internal Fragment results before they enter state;-> Logical-Output affinity separately protects selected Candidates.-> `packages/broll` lowers provider-neutral B-roll Programs into independently stacked visual-> Presents and ordinary source-audio/SFX tracks. Local pop/fade/slide motion and push/page-turn-> handoffs stay package-owned; neither Composition nor HyperFrames learns what B-roll means.-> `packages/text-track` lowers persistent or timed editorial text into the same peer VisualTrack-> contract. `packages/film` folds any number of visual/audio Track references into Composition-> through ordinary fixed-port Operations; Film remains an optional Target and does not become a-> Core root. `packages/hyperframes-render` separately turns any Composition into an explicit exact-> render Need and a final MediaArtifact projection.-> The v2 composition waist is intentionally flat: captions, text, speech video, B-roll and overlay-> effects must become self-contained peer Tracks. Composition may layer them by time, space and z,-> but no Track may mutate or intersect a sibling Track.-> `packages/text` and `packages/script` now implement the first official authoring vertical:-> a minimal Text Frontend that learns raw/structured Surfaces from locked module manifests, plus-> an ordinary Script Surface package using named Segments such as `<opening>...</opening>`. Text-> Surfaces can now return inert Record, Author Component and Graph Fragment declarations; Text-> collects the complete document before Elaborator resolves forward references into a Core Graph.-> `packages/whisperx` declares the typed one-pass WhisperX Need;-> `packages/provider-whisperx-local` and the independently locked `services/whisperx` Python-> distribution implement the trusted local path. Hosted adapters remain Runtime packages outside-> this slice. `packages/elaborator` now compiles recursive Source Closures,-> while `packages/svs` implements a deliberately generic record-only Recipe Frontend; package-owned-> video Recipe validation is package-owned rather than built into SVS. `packages/compiler-node` now supplies the domain-free-> registered-manifest resolver, injected Workspace compiler and file-to-Graph/-> BuildPlan facade; `packages/cli` assembles the first trusted Text + Script + SVS + Film + Render-> command-line prelude. `packages/validation` now supplies package-owned semantic Type admission: authored,-> provided, Producer and Endpoint values use the same exact-Type validator gate while Core verifies-> only the locked receipt. `packages/runtime` now supplies the environment-neutral executor and-> BuildStore/OperationStore ports, static Runtime facets, sealed Profile/Closure resolution,-> in-memory CAS, and a queue-free local Scheduler whose concurrency lanes are shared across Builds-> and independent commands inside one Build. Recoverable Endpoints now journal a stable-> submission identity before `start`, persist pending checkpoints, and use `resume` after restart;-> completed operations are replayed into Core without another external call. Trusted installed-> author packages can now be activated from a byte-locked physical dependency closure without-> changing Core or the official CLI; automatic installation, untrusted parser/validator sandboxing,-> distributed leases and hosted WhisperX /-> HyperFrames Endpoint adapters are not implemented yet; the local WhisperX and HyperFrames-> Providers are. The KIE generation Provider and its seven explicit model families are implemented,-> as are display-only Gemini Caption planning and its Google Vertex Provider.-> `@svml/store-sqlite`, `@svml/artifact-store-fs` and-> `@svml/local` now provide the durable zero-service developer assembly.-> `@svml/endpoint-kit` and `@svml/credential-store-env` now bind static Endpoint identity,-> non-secret configuration, exact credential slots and recoverable wake/retry/cancel behavior;-> Runtime service packages now bind Scheduler and Store implementations through the same exact-> Manifest/instance selection law, so `@svml/local` no longer contains package-specific store-> registration;-> `@svml/artifact-store-s3` plus bounded Lambda/process transports provide replaceable external-> execution plumbing without claiming any video capability;-> `@svml/media-pipeline` and `@svml/provider-media-local` now provide all-stream ffprobe inspection,-> attached-picture-safe stream selection and shared-origin A/V normalization. Embedded AAC remains-> an ordinary media fact until an explicit Narrative-bound speech component promotes it;-> the v2 CLI exposes local follow, status, cancel and content-addressed final Artifact export without adding another authoritative queue. The existing-> root compiler and standard library remain the executable v1 research oracle during migration.--`@svml/component-kit` is the narrow compute-host port: deterministic model, media, WhisperX and-HyperFrames packages register Producers without importing `@svml/driver-node`. Their handler-interface provides only typed inputs and value/Need outputs—no ArtifactStore, credentials, network,-queue or store handle. The Node Driver is one implementation of that port; trusted in-process code-is not yet a security sandbox.--The reusable non-video stack is intentionally smaller than the video distribution:-`@svml/protocol + @svml/core` are the irreducible Kernel, `@svml/elaborator` is the normal optional-author-to-Graph compiler, `@svml/compiler-node` is the optional reference file/package-registration-Host, and a Driver/Runtime executes Commands. Text, Realization overlays and all video packages-remain optional. There is no privileged `@svml/author` package or required `.svk` suffix.-If a domain Type declares a semantic validator, the Host additionally uses `@svml/validation` (or-an equivalent implementation); the Type still does not enter Core.--Semantic Video Markup Language is a graph language for semantic, information-flow video. `.svml`-is the pleasant author notation; package Surfaces lower it into peer Logical Outputs, Candidates-and Operations. Script creates stable semantic addresses, while optional Film, Track and render-packages are ordinary graph regions rather than a mandatory one-way compiler pipeline.+SVML is a graph language and runtime for building expensive, recoverable creative workflows from+human-readable intent.++Its reference video distribution lets an author address a video with words rather than timecodes:+Script defines the semantic truth, generated speech supplies acoustic evidence, and independent+packages lower captions, B-roll, text and speech into peer Tracks.++SVML is currently a pre-release v2 rewrite. It has completed one real paid talking-video Build, but+its public package names and video authoring ABI are not frozen yet.++## Why a graph language++AIGC operations are slow, costly, fallible and non-deterministic. Their results frequently become+inputs to later compilation. A usable system must therefore distinguish:++- what the author requested;+- which implementation is used for this Run;+- which results are actually demanded;+- what has already been materialized;+- where an external capability executes;+- which facts and code produced every accepted result.++SVML compiles those decisions before execution:++```text+Author Graph + Run Graph + Satisfaction edges + Targets+ │+ ▼+ frozen BuildPlan+ │+ ▼+ recoverable verified execution+```++There is no privileged final-video root. Any public Logical Output can be a Target.++## Core model++- 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 **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.+- Core resolves the selected reverse closure and freezes a finite BuildPlan before any external+ command runs.++Product actions such as pinning a previous video, using a black preview or selecting an alternate+fragment are ordinary Run Graph authoring. Core contains no Pin, preview mode, automatic cache or+Provider fallback branch.++See [the architecture](docs/architecture.md) and+[Core Kernel specification](spec/core-kernel-v1.md).++## What works today++The repository implements:++- domain-neutral Protocol, Core, graph elaboration and Node compiler Host;+- official `.svml` markup, Script Surface and `.svs` Recipes;+- locked trusted package activation without package-specific Core registration;+- recoverable Runtime scheduling with concurrency lanes, retries and cancellation;+- SQLite Build/Operation stores and filesystem/S3 Artifact stores;+- exact Endpoint binding and scoped credentials;+- seven explicit image/video model families through the KIE Provider;+- local ffprobe/ffmpeg media processing;+- local pinned WhisperX service;+- Vertex Gemini display-only Caption planning;+- local frame-parallel HyperFrames rendering;+- Speech, Caption, Text, B-roll, Film, audio and final mux vertical slices.++The complete live path is:```text- ┌─> visual Track ───────────┐-.svml ─> typed Records + Graph ─> Take ├─> optional Composition ─> render- │ └─> audio ─> evidence ─> Map ─┘- ├────────────────────────────────────────────> any Map/Track Target- └─> another independent branch ──────────────> another Target+Script → Estimate → Seedance × 2 → media normalization → WhisperX → SemanticMap+ → Gemini CaptionPlan → peer Tracks → Film → HyperFrames → audio mix → MP4```-Reverse Demand starts from whichever Targets the user asks for, deduplicates shared Operations and-never grants final Film/render special status. Canvas and Timeline are views of the same source-closure, not additional authoring truths. Provider tasks, reused values, caches and queue state-belong to Graph realization or Runtime state and do not become hidden fields in the author source.--## Implemented v1 slice--The TypeScript compiler and local standard library implement the current v1-architecture end to end:--- readable Script with Role Cues, Dual Text, Slots, closed/disconnected- Selections and zero-width Moments;-- an exact `SemanticIndex` with independent word and Segment endpoints- (`2M + 2N` identities);-- replaceable `TemporalBasisProduction` and `CompleteSemanticMap` Components,- validated and bound before any Track lowering;-- direct monotonic many-to-many alignment from authoritative Script tokens to- noisy `SpeechTimingEvidence`, without a corrected-transcript stage;-- hard cut, gap and audio/visual crossfade joins with distinct source-to-program- maps;-- typed `.svc` content modules and `.svs` classes, including nested Component- fields;-- stable Plan identity, separate execution digests and a full temporal- `svml.lock`;-- isolated `.svk` projectors, verified offline capability artifacts and finite,- auditable `composite-v1` expansion;-- manifest-enforced temporal `one` / `each` / `set` consumption;-- a post-locate `CaptionPlan` that may group cues and add typed style annotations- but cannot rewrite Script text or timing;-- flat media, ranking, B-roll, caption, text and audio Tracks in one absolute- ProgramSpace;-- Film as the executable v1 slice's `Track[]` consumer and HyperFrames HTML as- its sole formal video compilation target. The v2 Kernel does not make Film or- final video the fixed root of every Build.--There is no live provider adapter in this repository. A reachable-`profile="capability-v1"` Component must be satisfied by an exact,-content-verified `svml.artifacts.v1` binding; compilation never falls back to a-provider call. Existing local `Image`, `Video`, `Audio` and Evidence values work-directly.--SVML has not been publicly released. There is no legacy v1 compatibility layer:-the current architecture and Script Surface are the only v1 target.+Details and current gaps are maintained in+[implementation status](docs/implementation-status.md).## Quick start-Requires Node.js 22 and pnpm.+Requirements:++- Node.js 22++- pnpm+- Python 3.10–3.13 only when running the local WhisperX service```bashpnpm installpnpm checkpnpm test-pnpm build--# Optional local WhisperX Runtime service (Python 3.10–3.13).-uv sync --project services/whisperx --frozen-uv run --project services/whisperx --frozen svml-whisperx-prepare-uv run --project services/whisperx --frozen svml-whisperx-check-uv run --project services/whisperx --frozen svml-whisperx-service--# v2: real Source Closure check through the trusted Text + Script + SVS prelude.-pnpm svml:v2 check examples/v2-bootstrap/main.svml--# v2: explicitly trust and activate an installed third-party author package.-pnpm svml:v2 lock-packages ./svml.packages.lock --package @example/cards --root .-pnpm svml:v2 check ./main.svml --package-lock ./svml.packages.lock --root .--pnpm svml check examples/regen-ranking/regen-ranking.svml-pnpm svml script examples/regen-ranking/regen-ranking.svml --out narrative.json-pnpm svml plan examples/regen-ranking/regen-ranking.svml --out plan.json-pnpm svml canvas examples/regen-ranking/regen-ranking.svml --out canvas.json-pnpm svml estimate examples/regen-ranking/regen-ranking.svml --out estimate.json-pnpm svml timeline examples/regen-ranking/regen-ranking.svml --out timeline.json--# Produce a full frozen lock, including the selected Basis, Map and Evidence.-pnpm svml lock examples/regen-ranking/regen-ranking.svml --out svml.lock--pnpm svml compile examples/regen-ranking/regen-ranking.svml \- --lock svml.lock \- --out build/index.html-pnpm svml render build/index.html --out build/video.mp4++# Compile a complete provider-free v2 author graph.+pnpm svml:v2 check examples/talking-film-graph-check/main.svml++# Inspect a named target without executing external capabilities.+pnpm svml:v2 plan examples/talking-film-graph-check/main.svml \+ --target final.video+```++The live example uses explicit local Runtime assembly and external credentials:++```bash+pnpm svml:v2 build examples/talking-film-live/main.svml \+ --target final.video \+ --runtime examples/talking-film-live/svml.runtime.ts \+ --follow \+ --out examples/talking-film-live/output/final.mp4```-`--artifacts` is required only when the reachable Plan contains capability-Components. Speech timing is an explicit typed value referenced by the Locator-in source; it is not an ambient CLI argument. `estimate` produces estimated-timing evidence and the same structurally complete `CompleteSemanticMap` type;-per-anchor quality records what was measured, derived or estimated.+Read its [deployment requirements](examples/talking-film-live/README.md) before running it. Paid+credentials, presenter assets, local databases and generated outputs are not committed.-`fmt` currently canonicalizes only the Script body and refuses a rewrite if the-reparsed semantic IR differs. `canvas` needs no materialized time evidence.-`timeline`, `compile` and `lock` execute the deterministic local Plan and validate-the selected Basis/Map pair.+## Author source versus execution environment-## Four source files+These inputs are separate by design:-| Suffix | Responsibility |+| Input | Owns ||---|---|-| `.svml` | One film's Script, local values, Component calls, Tracks and Composition |-| `.svk` | An importable Component vocabulary, public typed ABI and lowering |-| `.svs` | Typed parameter classes for public Component parameters and fields |-| `.svc` | Context-free reusable content values and content subgraphs |--The compiler owns universal language laws. Libraries own replaceable vocabulary-and algorithms. A Runtime Host owns effects, credentials, queues and storage.-Canvas owns only a human-readable view.--## Executable examples--- [`examples/regen-ranking/regen-ranking.svml`](examples/regen-ranking/regen-ranking.svml)- reconstructs a pinned production video with five ranking items, five B-roll- items, captions, title, BGM and sound effects. It compiles to 30 Plan nodes,- 35 typed edges and 1083 frames.-- [`examples/flat-track-launch/flat-track-launch.svml`](examples/flat-track-launch/flat-track-launch.svml)- is the comprehensive language fixture: explicit Basis/Locator, nested SVS,- overlapping Presents, manual ProgramSpans, a Moment, B-roll source audio and- transition SFX, disconnected caption styling and absolute z.-- [`examples/composite-speech-program/minimal.svml`](examples/composite-speech-program/minimal.svml)- proves that an author-facing `speech-program` can hide repetitive wiring while- expanding to separately auditable `voice::basis` and `voice::locator`- instances. The compiler has no special knowledge of that Component name.-- [`examples/media-basis`](test/fixtures/media-basis) proves that precomposed- media can implement the same Basis contract and reuse the same Locator and- Composition path.--The local media used by the examples are already-materialized artifacts; no-generation provider is invoked by tests or compilation.--## v2 authoring target--[`examples/talking-film-golden`](examples/talking-film-golden/README.md) preserves the implemented-Script Surface and specifies the complete namespaced author experience for two Seedance Mini speech-takes, Seedance B-roll, explicit WhisperX alignment, two speaker caption styles, editorial text,-peer Tracks, Film and Hyperframes rendering. Provider-free Speech, WhisperX, Caption, B-roll and-Text Surfaces now compile. Display-only Gemini planning, the ordered Caption Style cascade and the-Google Vertex Provider are also implemented;-[`examples/talking-film-graph-check`](examples/talking-film-graph-check/README.md) is the fully-checkable graph counterpart without production assets or paid execution.--## Specification and implementation record--Start with the [documentation map](docs/README.md) and-[current implementation status](docs/implementation-status.md). In particular, long architecture-records preserve rejected models and are not all normative.--- [Core Kernel v1](spec/core-kernel-v1.md) is the compact normative `@1` Kernel contract.-- [Intent-first modular compilation architecture](docs/intent-first-modular-compilation.md)- records the next architecture direction: SVML as author intent, source-selected- compilation modules, typed external requirements and provenance-preserving- fulfillment or substitution. The executable v1 documents below remain implementation- records until that migration is complete.-- [Kernel graph and build intent v2](docs/kernel-graph-build-intent-v2.md)- is the superseded `@0` Graph/Pin construction record.-- [Logical Output, Candidate, Build Compiler and Graph Fragment v2](docs/logical-output-realization-fragment-draft.md)- is the current `@1` Kernel construction authority and implementation record.-- [Script Surface v1](spec/script-surface-v1.md)-- [Source Architecture v1 draft](spec/source-architecture-draft.md)-- [Speech Program and Caption v1 target contract](docs/speech-program-caption-v1.md)-- [Compiler implementation record](docs/compiler-prototype.md)-- [External Runtime Host architecture](docs/runtime-host-architecture-draft.md)- is a historical pre-v2 audit record.-- [Runtime, package and execution topology v2](docs/runtime-package-topology-v2.md)- specifies the current package, Runtime Profile, Provider Binding and scheduler- boundaries.--VLM, bbox, face tracking and visual reverse-location are intentionally outside-SVML v1. They may be implemented later as explicit post-processing extensions;-the semantic audio timeline remains the language's locating foundation.+| `.svml` | author meaning, explicit model/component choices and graph references |+| `.svs` | reusable package-defined Recipe values |+| planned `.svrun` | Targets, Candidates and explicit Satisfaction edges for one reusable Run |+| Runtime Profile / `svml.runtime.ts` | Scheduler, Stores, credentials, Endpoints and concurrency |++Source imports activate author vocabulary only. They never authorize network, filesystem, process,+credential or queue access.++## Packages and extension++A physical package may expose separately locked facets:++```text+author Frontend, Surface, Graph Fragment+compute deterministic Producer or Type Validator+endpoint privileged local/remote capability implementation+runtime Scheduler or Store implementation+```++Packages communicate through nominal Types published by their owners. Core does not contain a+central union of Narrative, Track, Seedance or any other domain type. Installing a trusted package+can add a new component or Endpoint without republishing Core.++Current package execution is for explicitly installed, byte-locked trusted code. Arbitrary+community Parser/Producer/Validator execution still needs a real isolation and permission boundary.++## Repository map++```text+packages/protocol immutable wire contracts+packages/core domain-neutral Demand compiler and Build state machine+packages/elaborator author declarations and hygienic Fragment expansion+packages/compiler-node reference Node compiler Host+packages/runtime environment-neutral scheduling and Store ports+packages/driver-node trusted Node command execution+packages/local zero-service SQLite/filesystem developer assembly+packages/* optional Frontend, domain, Endpoint and adapter packages+services/whisperx pinned local WhisperX sidecar+spec current normative contracts+docs architecture, status, roadmap and focused implementation records+examples v2 checks/live witness plus retained v1 regression fixtures+```++Start with the [documentation map](docs/README.md) and [roadmap](docs/roadmap.md).++## Development++```bash+pnpm check # v1 research oracle + v2 TypeScript+pnpm test # v1 regression tests + v2 package tests+pnpm build # build the retained root v1 CLI during migration++pnpm test:whisperx-service+pnpm smoke:kie # opt-in paid Provider smoke test; requires credentials+```++The root `src/`, `stdlib/` and legacy examples remain executable regression evidence while v2 is+rewritten under `packages/`. They are not the public v2 package taxonomy or source contract.++## Current priorities++Work is intentionally focused on two layers:++1. domain-neutral `.svrun`, Runtime Profile usability, package lifecycle and inspection;+2. repeatable live acceptance and replaceable local/cloud Endpoint environments.++Broader Text, Caption, B-roll and Ranking visual behavior is deferred until those foundations are+clean. See the [roadmap](docs/roadmap.md).diff --git a/docs/README.md b/docs/README.mdindex 73c2b28b..40858f9f 100644--- a/docs/README.md+++ b/docs/README.md@@ -1,118 +1,56 @@-# SVML documentation map--SVML separates normative contracts, implementation status, architecture decisions and historical-evidence. A document's directory and the table below determine its authority; a newer-looking date-inside a historical design record does not make that record normative.--## Read this first--1. [`../README.md`](../README.md) — project purpose, supported commands and repository entrypoint.-2. [`implementation-status.md`](./implementation-status.md) — what the v2 rewrite actually- implements now and what remains planned.-3. [`../spec/core-kernel-v1.md`](../spec/core-kernel-v1.md) — current domain-free Kernel laws.-4. [`graph-first-value-boundary-v1.md`](./graph-first-value-boundary-v1.md) — the implemented law- that SVML lowers to a graph and that values contain intrinsic meaning while Graph, Derivation and- Receipt own relationships and lineage.-5. [`implementation-status.md#domain-neutral-package-boundary`](./implementation-status.md#domain-neutral-package-boundary)- — the minimal package stack for video and non-video domains.-6. [`../spec/script-surface-v1.md`](../spec/script-surface-v1.md) — current official Script Surface- target.-7. [`../spec/track-composition-v1.md`](../spec/track-composition-v1.md) — implemented flat Track and- Composition law and the generic HyperFrames lowering boundary.-8. [`../spec/track-expressiveness-v1.md`](../spec/track-expressiveness-v1.md) — executable freeze gate- for old-system Text, Caption, media-box, stacking and materialization behavior. It explains why- the current Track is a contract candidate rather than a public compatibility promise.-9. [`../spec/hyperframes-visual-ir-v1.md`](../spec/hyperframes-visual-ir-v1.md) — the one versioned,- closed terminal visual language shared by video components; not a Core or author-component API.-10. [`../spec/caption-program-v1.md`](../spec/caption-program-v1.md) — implemented total default- Style, ordered Role/Selection replacement, display-atom planner and timing-join laws.-11. [`../examples/talking-film-golden/README.md`](../examples/talking-film-golden/README.md) — the- canonical two-speaker v2 authoring target. Its Script projections, Caption Style cascade,- display-only Gemini planning and graph lowering are implemented; real assets and credentials- remain deployment inputs.-12. [`package-vocabulary-and-ownership-v1.md`](./package-vocabulary-and-ownership-v1.md) — target- naming and ownership for framework, video, Provider, Runtime, queues, stores and distributions.-13. [`../spec/author-surface-binding-v1.md`](../spec/author-surface-binding-v1.md) — implemented- package-owned binding from generic imported Records such as SVS Recipes into typed Programs,- AuthorComponents and Graph Fragments.-14. [`local-developer-runtime-v1.md`](./local-developer-runtime-v1.md) — implemented local- SQLite/filesystem Runtime assembly, trusted configuration, recovery law and environment swaps.-15. [`kie-generation-modules-v1.md`](./kie-generation-modules-v1.md) — implemented seven exact- generation model modules, shared generated-media Products and the recoverable KIE Provider.-16. [`kie-live-smoke-2026-08-06.md`](./kie-live-smoke-2026-08-06.md) — credential-free deployment- evidence from seven representative live model calls and one synthetic-reference upload.-17. [`media-inspection-and-normalization-v1.md`](./media-inspection-and-normalization-v1.md) —- implemented all-stream inspection, attached-picture-safe selection, shared-origin A/V- normalization and the boundary that prevents embedded AAC from becoming speech by inference.-18. [`media-execution-boundary-v1.md`](./media-execution-boundary-v1.md) — the implemented rule that- planning is ordinary code while probe/decode/mix/render/mux are explicit Provider Needs, plus- the visual/audio/mux split for final HyperFrames output, canonical WhisperX evidence-audio path- and implemented local Providers.-19. [`../services/whisperx/README.md`](../services/whisperx/README.md) — installation, runtime- identity, path confinement and queue boundary for the implemented warm local WhisperX service.-20. [`node-package-activation-v1.md`](./node-package-activation-v1.md) — implemented trusted author- and deterministic compute facet locking, with the exact boundary that keeps source imports away- from Provider and Runtime authority.-21. [`caption-gemini-provider-contract.md`](./caption-gemini-provider-contract.md) — implemented- display-atom planning boundary, old Vertex execution evidence and no-text-rewrite contract.--The executable v2 Node entrypoints are documented in-[`../packages/compiler-node/README.md`](../packages/compiler-node/README.md),-[`../packages/package-loader-node/README.md`](../packages/package-loader-node/README.md) and-[`../packages/cli/README.md`](../packages/cli/README.md). The former is domain-neutral compiler-host-infrastructure; the loader is the trusted installed-package boundary; the latter is the official-application assembly.--## Current architecture records--- [`logical-output-realization-fragment-draft.md`](./logical-output-realization-fragment-draft.md)- records why the `LogicalOutput / Candidate / Operation / BuildRequest` model replaced the earlier- Node/Pin model. It also contains the current implementation ledger. It is not a substitute for the- compact normative Kernel specification.-- [`runtime-package-topology-v2.md`](./runtime-package-topology-v2.md) defines the target separation- among Runtime Profile, one authoritative Build Scheduler, Provider Endpoints, queues, credentials- and stores. The environment-neutral executor, sealed Runtime Profile/Closure, in-memory- BuildStore/OperationStore CAS, queue-free local Scheduler and recoverable Endpoint lifecycle are- implemented. SQLite Build/Operation stores, filesystem/S3 artifacts and the `@svml/local`- developer assembly are now implemented together with the generic Runtime service-package ABI,- Endpoint Kit, environment credential- injection, bounded Lambda/process transports, wake/follow, retry, status and cancellation, plus- local KIE/media/HyperFrames/WhisperX execution packages; distributed leases and production hosted- endpoints are not. Its older example package- names are superseded by- [`package-vocabulary-and-ownership-v1.md`](./package-vocabulary-and-ownership-v1.md).-- [`intent-first-modular-compilation.md`](./intent-first-modular-compilation.md) records the language,- Frontend, Bootstrap, Surface and module-boundary reasoning. Its older Kernel terminology is- historical.--## Executable v1 research oracle--These files explain the root compiler and standard library that remain executable while v2 is-rebuilt. They are not the v2 Kernel contract:--- [`../spec/source-architecture-draft.md`](../spec/source-architecture-draft.md)-- [`compiler-prototype.md`](./compiler-prototype.md)-- [`speech-program-caption-v1.md`](./speech-program-caption-v1.md)-- [`../spec/core-kernel-v0.md`](../spec/core-kernel-v0.md)--## Superseded design records--- [`kernel-graph-build-intent-v2.md`](./kernel-graph-build-intent-v2.md) — historical `@0`- Graph/Alternative/Pin construction.-- [`runtime-host-architecture-draft.md`](./runtime-host-architecture-draft.md) — historical- ExecutionBundle/EffectRequest host design.--Historical documents stay in the repository because they explain rejected designs and migration-decisions. New implementation work must not copy an interface from them unless a current-specification explicitly adopts it.--## Documentation rule--- `spec/` states stable laws and public data contracts.-- `docs/implementation-status.md` states what exists now.-- current architecture records explain decisions and future boundaries.-- superseded records are evidence only.--Do not append a new design generation to an old document. Change a current specification when the-law changes, add a focused architecture decision when the reason matters, and update the status-page when implementation moves.+# Documentation++SVML documentation is intentionally split by authority. Git history preserves discarded designs;+the working tree contains only documents that should inform current implementation or public use.++## Start here++1. [`../README.md`](../README.md) — project overview and development entrypoint.+2. [`architecture.md`](./architecture.md) — current Author Graph, Run Graph, Satisfaction, Runtime+ and package boundaries.+3. [`implementation-status.md`](./implementation-status.md) — what actually executes today.+4. [`roadmap.md`](./roadmap.md) — active domain-neutral and environment/Provider work; deferred video+ work is separated explicitly.+5. [`../spec/core-kernel-v1.md`](../spec/core-kernel-v1.md) — compact normative Kernel laws for the+ current `@2` wire data.++## Domain-neutral implementation records++- [`graph-first-value-boundary-v1.md`](./graph-first-value-boundary-v1.md) — graph edges own+ dependency truth; values contain only intrinsic meaning.+- [`node-package-activation-v1.md`](./node-package-activation-v1.md) — trusted installed package+ locking and facet activation.+- [`local-developer-runtime-v1.md`](./local-developer-runtime-v1.md) — local SQLite/filesystem+ Runtime, recovery and environment replacement.+- package READMEs under [`../packages`](../packages) — executable APIs and ownership.++## Video-domain specifications++- [`../spec/script-surface-v1.md`](../spec/script-surface-v1.md)+- [`../spec/author-surface-binding-v1.md`](../spec/author-surface-binding-v1.md)+- [`../spec/caption-program-v1.md`](../spec/caption-program-v1.md)+- [`../spec/track-composition-v1.md`](../spec/track-composition-v1.md)+- [`../spec/track-expressiveness-v1.md`](../spec/track-expressiveness-v1.md)+- [`../spec/hyperframes-visual-ir-v1.md`](../spec/hyperframes-visual-ir-v1.md)++These video contracts are executable candidates, not yet an open-source compatibility freeze.++## Video execution records++- [`kie-generation-modules-v1.md`](./kie-generation-modules-v1.md)+- [`media-inspection-and-normalization-v1.md`](./media-inspection-and-normalization-v1.md)+- [`media-execution-boundary-v1.md`](./media-execution-boundary-v1.md)+- [`caption-gemini-provider-contract.md`](./caption-gemini-provider-contract.md)+- [`../services/whisperx/README.md`](../services/whisperx/README.md)+- [`../examples/talking-film-live/README.md`](../examples/talking-film-live/README.md)++## Documentation rules++- `spec/` states normative laws and versioned contracts.+- `docs/architecture.md` states current ownership and boundaries.+- `docs/implementation-status.md` states repository reality.+- `docs/roadmap.md` states planned work and non-goals.+- package and example READMEs explain one executable unit.++Do not preserve a superseded design in the current tree merely as a discussion log. Keep durable+decisions in the current architecture/specification, and rely on Git history for rejected drafts.diff --git a/examples/README.md b/examples/README.mdindex 21a4a0d2..f3014cb3 100644--- a/examples/README.md+++ b/examples/README.md@@ -1,27 +1,24 @@-# SVML examples+# Examples-The repository deliberately separates the executable v2 bootstrap, executable research fixtures-and the complete v2 authoring target.+## Current v2 examples-## Executable v2 bootstrap+- [`talking-film-graph-check`](./talking-film-graph-check/README.md) compiles the complete+ provider-free author graph through Speech, WhisperX, Caption, B-roll, Text, Film and final render+ requirements.+- [`talking-film-live`](./talking-film-live/README.md) executes the real paid two-take path with KIE,+ local media processing, local WhisperX, Vertex Caption planning and local HyperFrames rendering.+- [`talking-film-golden`](./talking-film-golden/README.md) is the larger authoring and visual design+ fixture used while video packages remain pre-freeze.+- [`v2-bootstrap`](./v2-bootstrap/README.md) is the smallest official Text/Script/SVS source-closure+ check.-- [`v2-bootstrap/main.svml`](./v2-bootstrap/main.svml) is accepted by `pnpm svml:v2 check`. It- exercises the real Node Source Host, official Text/Script prelude and recursive SVS Frontend. It- deliberately stops before package-owned Recipe consumption and component Graph construction.-- [`talking-film-graph-check/main.svml`](./talking-film-graph-check/main.svml) is the complete- provider-free author graph through Speech, WhisperX, B-roll, Caption, Text, Film and Render.+Generated assets, local Runtime databases and output media are ignored by Git.-## v2 authoring target+## Retained v1 regression fixtures-- [`talking-film-golden/main.svml`](./talking-film-golden/main.svml) is the canonical visual and- semantic target for two-speaker Gemini captions. Its author and paid Caption packages are- implemented; the adjacent README tracks real assets and deployment bindings.+- `flat-track-launch`+- `regen-ranking`+- `composite-speech-program`-## Executable v1 research fixtures--- `flat-track-launch` is the broad language/capability regression fixture.-- `regen-ranking` reconstructs a real pinned production edit.-- `composite-speech-program` proves that an author component can hide repeated internal wiring.--The v1 examples are evidence, not syntax that new v2 packages must preserve. The golden fixture is-a design target, not evidence that its missing Provider and Surface packages already exist.+These fixtures are still consumed by the root v1 test suite. They preserve behavior that the v2+rewrite can attack and re-prove, but they are not public v2 syntax or recommended starting points.diff --git a/open-source-prep.md b/open-source-prep.mddeleted file mode 100644index 96388b5e..00000000--- a/open-source-prep.md+++ /dev/null@@ -1,285 +0,0 @@-# SVML 开源准备:结论 + 问题清单--## 基本信息--- **仓库名:** svml-- **一句话:** Address with words, not timecodes.-- **Tagline(英文):** SVML — a markup language for talk video.-------## 我们做了什么--一门标记语言,把口播脚本编译成成品视频。--传统视频编辑的原子操作是时间码(`at: 01:02:03:15`)。SVML 的原子操作是语义地址(`during={script.selection.photoshop}`)。你在脚本里标注"说到这个词的时候显示这个图标",编译器拿到语音时间证据后,一次性把所有视觉元素钉死在时间线上,输出成品视频。--脚本就是程序,语音就是时钟。源码里没有任何时间码。--技术栈:TypeScript + Node.js 单依赖编译器。`.svml` 源码编译到 HyperFrames HTML,再录制为 MP4。-------## 目标用户是谁--三句话,三个客户群,同一个产品:--- **A high-level video language for developers.**-- **An editing-free production system for creative teams.**-- **A scalable marketing video engine for brands.**--这不是三个产品。就像 iPhone 同时是 iPod、手机和互联网通讯器。同一门语言,三个价值面。-------## 我们能做什么类型的视频--**Talk video(说片)** — 口播、街头采访、播客、产品测评、YouTube essay。--共同特征:有人在说话,说话驱动一切。说到哪个词,画面就跟到哪里。--| 类型 | 有东西要定位 | 有定位锚点(speech) | SVML 的价值 |-|---|---|---|---|-| 口播/街采/播客 | 有(图标、broll、排行榜、分屏) | 有(speech semantic address) | **满配** |-| 纯 AI 视频(短剧等) | 有(但只是顺序拼接) | 没有(prompt → clip,没有内部结构) | 杀鸡牛刀 |-| 纯代码视频(motion graphics) | 没有(全是绝对时间编排) | 没有(不需要 late binding) | 多此一举 |--我们不做的:纯 AI 短剧(没有内部结构需要定位),纯 motion graphics / launch video(没有不确定的时间需要 late bind)。当然严格来说都能做,但失去了意义。-------## 核心机制:time-responsive video--类比 responsive web design:--- 响应式网页:布局相对于语义结构书写 → 浏览器根据 viewport 解算成像素。你不写 `left: 347px`,你写 `margin: auto`。-- **响应式视频:** 视觉元素相对于语义脚本书写 → 编译器根据语音证据解算成帧。你不写 `at: 3.5s`,你写 `during={script.selection.photoshop}`。--同一份 `.svml`,换一个语速更快的人录,所有视觉元素自动重排——就像同一份 CSS 在手机和桌面上自动重排。这就是 time-responsive。--**Semantic addressing vs timecode addressing** — 这是范式区别,不是功能区别。传统剪辑用 timecode addressing(`01:02:03:15`),SVML 用 semantic addressing(`script.selection.photoshop`)。-------## SVML 不是什么--- **不是 "source code for videos"** — HyperFrames 已经占了这个位。SVML 编译到 HyperFrames,就像 C 编译到汇编。-- **不是 Twinit 节点图的文本序列化** — 虽然 Twinit 是第一个商业用户,但 SVML 是独立的语言。-- **不是 AI 视频生成器** — 编译器是纯确定性的,不调用任何 AI provider。AI 生成是 Runtime Host 的事,不是语言的事。-- **不是剪辑器** — 没有时间轴。时间轴是编译器算出来的,不是人拖出来的。-- **不是模板系统** — `.svml` 文件是完整的程序,不是填空题。但可以被模板系统用作底层。-------## 竞品坐标系--| 产品 | 本质 | 和 SVML 的关系 |-|---|---|---|-| CapCut / Premiere / DaVinci | 时间轴编辑器 | SVML 取消了时间轴。不竞争,不同范式 |-| Palmier / ChatCut | AI 辅助剪辑器 | 可能加 WhisperX 做辅助定位,但还是剪辑器。SVML 是编译器 |-| Flova / Higgsfield / LibTV | 模板生成器 | SVML 可以是它们的底层编译目标,不是竞争对手 |-| HyperFrames | 视频的 HTML | SVML 的编译目标,不是同层 |-| Remotion | 代码驱动视频(React) | 绝对时间编排,不做 speech-located。互补 |-| After Effects / Motion | 动效工具 | 纯代码视频领域,不需要 late binding |--SVML 没有直接竞品。最接近的描述是:视频领域的 LaTeX / CSS / Markdown——一门让非像素、非时间码的抽象方式成为可能的语言。-------## 和 Twinit 的关系--Twinit 是用 SVML 作为底层的商业视频工厂(canvas + AI provider + 渲染集群 + 操作员工作台),已有 B2B 客户(Cluely、Starot、Lessie AI、Megneta、MeetWhale 等)。--可能的关系模型:-- **类比 1:** Terraform HCL(开源语言)+ HashiCorp Cloud(商业平台)-- **类比 2:** Kubernetes(开源引擎)+ GKE/EKS(商业托管)-- **类比 3:** React(开源框架)+ Vercel(商业部署)--SVML 开源获取开发者社区和技术信任,Twinit 作为 "SVML 的最佳商业实现" 做 B2B 营收。-------## 开源目标--1. 开发者社区验证——证明 semantic addressing 这个范式有人认可-2. Star 和技术影响力——为融资和品牌背书-3. 生态贡献——第三方可以写 Component(stdlib 的 `.svk`)、Frontend、Provider adapter-4. Twinit 的技术护城河公开化——开源让客户信任底层不是黑盒-------## "说片"品类定义(中文场域)--说书 = 用嘴讲的书。说唱 = 用嘴讲的歌。**说片 = 用嘴讲的片子。**--口播、街采、播客、解说——抖音叫口播,B站叫解说,YouTube 叫 essay video。结构上它们是同一个东西:一个人在说话,画面跟着走。我们把它统一命名为"说片"。-------## Demo 素材--- `regen-ranking.svml`:170 行源码,编译出 36 秒成品视频。源码读起来像剧本,里面没有任何时间码。-- 已有编译产物视频(Downloads 里有 MP4)-------## 为什么天才创作者现在不想用--诚实的自我诊断:--1. **要手写 XML-like 标记语言** — 创作者的工具应该是低门槛的-2. **所有素材必须预先存在** — 没有 AI provider integration,不能写 intent 让 AI 生成-3. **没有即时反馈** — 写代码 → 编译 → 等结果,不是所见即所得-4. **stdlib 太窄** — 目前只能做排行榜口播视频这一种-5. **没有 GUI** — 纯 CLI,没有可视化编辑器--这些是产品层面的缺失,不是语言层面的问题。语言设计(Script Surface、semantic addressing、deterministic compilation)是对的。------------# 问题清单(按版块,重要→不重要)--## 一、定位与品类(最关键)--1. 我们做的品类叫 talk video / "说片",但这个品类名现在不存在。你之前陪跑的项目里,有没有需要**先建立品类认知**再做发布的?怎么处理的?-2. AFFiNE 可以说 "Notion alternative" 建坐标系。我们说不了 "X alternative",因为没有 X。开源项目没有竞品参照的时候怎么让人快速理解?-3. "Address with words, not timecodes" 作为 tagline,你觉得开发者第一眼看到能理解吗?需要配什么视觉才能秒懂?-4. 三句话定位(language / production system / engine)会不会让人困惑——到底是给谁用的?还是说这种多面定位反而有优势?-5. talk video 这个英文品类名足够清晰吗?开发者听到会不会以为是 video call?有没有更好的表达?-6. "说片"这个中文造词在中文开发者社区会不会太文艺、太抽象?要不要用"口播视频"这种大家已经懂的词?-7. 我们是应该把自己定位成一个"语言"还是一个"工具"?语言更长期但更难推,工具更容易理解但天花板低。你的经验是?-8. time-responsive video 这个概念有必要在 README 第一屏提吗?还是留给技术博客?--## 二、GitHub README--1. 我们开源的是一门语言和编译器,不是有 GUI 的产品。README 第一屏应该放什么?源码?编译出的视频?还是源码→视频的对比?-2. 你做过这么多万星项目,语言/编译器类项目(不是 app 类)的 README 有没有特别好的参考?-3. Demo 视频放 GitHub README 里最佳的格式是什么?GIF?内嵌视频?YouTube 链接?-4. Quick Start 部分——我们的 quick start 是 `pnpm install` 然后 `pnpm svml compile example.svml`,能在 5 分钟内跑通。但跑通之后用户只得到一个 HTML 文件,没有"哇"的时刻。怎么设计这个体验?-5. 需不需要在 README 里放竞品对比表?我们严格来说没有直接竞品。-6. README 里要不要提 Twinit?提了会不会让人觉得这只是一个公司的内部工具开源?-7. Star 请求放在哪里最有效?顶部?底部?行内?-8. 中英文 README 怎么处理?双语?分 repo?分文件?-9. Contributing guide 开源第一天就需要吗?还是等有人来了再写?-10. 需要 awesome-svml 这类生态 repo 吗?现在太早?--## 三、官网--1. 我们需要一个单独的官网吗?还是 README 就够了?-2. 如果做官网,第一版需要什么?landing page?文档站?playground?-3. 有没有低成本方案——比如直接用 GitHub Pages + 一个好的 landing page?-4. 官网需要放 pricing 吗?我们开源部分免费,Twinit 商业付费——怎么讲?-5. 官网域名建议?`svml.dev`?`svml.video`?`svml.io`?--## 四、开发者文档--1. 语言类项目的文档结构应该是什么样的?Tutorial vs Reference vs Explanation?-2. 我们有很完整的 spec 文档(script-surface-v1.md 等),但那是内部设计文档。需要重写成面向外部开发者的版本吗?-3. Interactive playground / REPL 对语言类开源项目有多重要?需要优先做吗?-4. 文档和 README 之间应该怎么分工?README 讲什么,文档讲什么?--## 五、PR 长文 / 发布文章--1. 开源发布的 PR 长文应该发在哪里?Medium?Dev.to?个人博客?公众号?-2. 长文的叙事结构应该是什么?问题→方案→demo→call to action?还是别的?-3. 需要一篇技术深度文章(讲 semantic addressing 的原理)和一篇大众文章(讲为什么剪辑器该死了)吗?还是合成一篇?-4. 中英文发布文章的发布顺序和内容差异?-5. 发布文章里该不该提 AI?"AI 时代的视频编程语言"会不会蹭热度但偏离本质?--## 六、内容素材包--1. 我们有一个天然优势:demo 就是视频。怎么最大化利用这个?-2. 需要一个 30 秒的 explainer video 吗?类似 "What is SVML?"-3. Logo 和视觉 identity 现在需要吗?开源第一天没有 logo 会不会显得不专业?-4. KOL 可以直接引用的短文案——英文和中文各需要几个版本?-5. 源码→视频的对比图/GIF 怎么做最有冲击力?--## 七、X (Twitter)--1. 发布推文的最佳格式?Thread?单条+视频?-2. 应该打哪些 tag?#opensource?#ai?#video?#devtools?-3. AI video 圈的 KOL 你有推荐吗?我们应该联系谁?-4. 发布时间——北京时间几点发对应美国开发者社区最活跃的时间?-5. 需要一个项目官方 X 账号还是用创始人个人账号?-6. 发布前需要预热吗?提前几天开始?发什么?--## 八、Reddit--1. 哪些 subreddit 适合我们?r/programming?r/opensource?r/videoediting?r/webdev?-2. Reddit self-promotion 规则现在多严格?我们需要提前联系 moderator 吗?-3. 发帖的角度——"Show HN" 式的技术展示?还是 "I built this" 式的个人故事?-4. Reddit 帖子的标题怎么写最有效?--## 九、Hacker News--1. HN 的标题风格——"Show HN: SVML – Address with words, not timecodes" 这样可以吗?-2. HN 社区对视频/创作者工具的接受度怎么样?会不会觉得太 niche?-3. 发布时间的策略——美东上午?周几最好?-4. 需要提前在 HN 上有活跃历史吗?--## 十、社区(Discord / Telegram)--1. 开源第一天就需要建 Discord 吗?还是等有一定 star 再建?-2. Discord vs Telegram——我们的目标用户更常用哪个?-3. 社区冷启动怎么做?前 100 个成员从哪里来?-4. 社区里需要什么 channel?general?showcase?help?-5. 谁来负责日常社区维护?需要多少时间?--## 十一、中文社群(V2EX / LinuxDO)--1. V2EX 的最佳发布节点是什么?创造?分享?程序员?-2. LinuxDO 适合我们吗?那里的用户画像是什么?-3. 中文开发者社区对"视频编程语言"这种概念的接受度?会不会太 niche?-4. 即刻适合吗?你在即刻上活跃吗?--## 十二、微信公众号--1. 需要一个公众号吗?还是借别人的号发?-2. 公众号文章的叙事和 Medium/Dev.to 文章应该有什么差异?-3. 需要做微信群吗?怎么管理?--## 十三、小红书 / B站 / 抖音--1. 这些平台适合开源项目推广吗?-2. B站做一个技术讲解视频有价值吗?-3. 小红书上开发者工具类内容有流量吗?--## 十四、TikTok / Instagram / Threads--1. 海外短视频平台适合推开源项目吗?-2. 有没有开发者工具在 TikTok 上做推广成功的案例?--## 十五、发布节奏与排期--1. 我们现在的准备程度——README 还没改,没有官网,没有文档站,没有社区——至少需要几周准备?-2. 你建议的发布日排期是什么?哪些渠道同一天打,哪些错开?-3. 发布前需要找 beta tester 吗?找几个?从哪找?-4. Product Hunt 应该和 GitHub 发布同一天还是错开?错开多久?-5. 需要预算吗?KOL 合作、域名、设计、视频制作——大概多少?--## 十六、发布后--1. 发布后第一周每天该做什么?-2. 怎么判断发布是否成功?哪些指标最重要?-3. 如果第一天 star 没达预期怎么办?-4. 如何把 star 转化成 contributor?-5. 如何把开发者关注转化成 Twinit 的 B2B 线索?-6. 开源项目的长期维护节奏——release cadence、changelog、roadmap 公开程度?--## 十七、商业模式--1. SVML 开源 + Twinit 商业化的 open core 模式,你做过 AFFiNE 有什么经验和坑?-2. 开源协议选什么?MIT?Apache 2.0?AGPL?对商业化有什么影响?-3. 开源项目拿投资,投资人最看什么指标?star?contributor?commercial traction?-4. AFFiNE 融资的时候,开源数据(star、fork、contributor)在融资中占多大比重?-5. 需要成立一个独立的 GitHub org 还是用个人账号?--## 十八、生态与长期--1. 怎么让第三方开发者为 SVML 写 Component(`.svk`)?-2. 需要一个 component marketplace / registry 吗?-3. SVML 作为语言,需要 LSP(Language Server Protocol)支持吗?VS Code 插件?-4. 什么时候该做 SVML playground(在线编辑器+预览)?-5. 能不能让 AI agent(Claude Code、Cursor 等)直接写 `.svml`?这是不是一个重要的增长渠道?diff --git a/packages/cli/README.md b/packages/cli/README.mdindex 53870ba6..a6e4df14 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -32,8 +32,8 @@ pnpm svml:v2 cancel <build-id> --runtime ./svml.runtime.ts`check` is usable for the complete provider-free author graph in`examples/talking-film-graph-check`. `plan` is fully implemented by the generic Node compiler. The-production golden still awaits the explicit Gemini Caption package and real assets; the CLI does-not fabricate those missing facts.+live example now executes the explicit Vertex Gemini Caption package and real local/remote+Endpoints; the CLI never fabricates missing facts.`build` compiles the same locked BuildState and passes it to a trusted local Runtime config module.The default Build identity is content-derived, so the same invocation resumes durable local state;@@ -50,14 +50,15 @@ these commands creates a second ready-command queue.selected Runtime ArtifactStore and writes the requested file. It does not treat a CAS path as apublic filename or bypass Record identity verification.-`--pin output=<prior-build-id>` is intentionally CLI language, not a Core primitive. The Host+`--pin output=<prior-build-id>` is temporary CLI compatibility language, not a Core primitive. The Hostverifies the prior Build only to extract a typed Record, attaches it as an ordinary zero-input-`substitute` Candidate, and adds an explicit binding to a newly compiled BuildRequest. It does not+`substitute` Candidate, and adds an explicit Satisfaction to a newly compiled BuildRequest. It does notprove that the old Graph, prompt or semantic meaning matches the current output. Consequently thecommand requires `--accept-substitute`. Upstream work behind that selected Candidate is notdemanded, while every unbound reachable output follows the ordinary graph. The prior artifact muststill exist in the ArtifactStore selected by the Runtime. This is a new Build with a new identity;-it never resumes or copies the prior Build's outstanding Commands.+it never resumes or copies the prior Build's outstanding Commands. The planned `.svrun` Frontend+will replace this narrow flag with the general Run Graph, Target and Satisfaction language.`@svml/package-loader-node` supports explicitly trusted installed implementation packages. Itverifies the complete physical dependency closure before executing an activation entry, then checksdiff --git a/packages/driver-node/README.md b/packages/driver-node/README.mdindex 162eb138..b8a832ae 100644--- a/packages/driver-node/README.md+++ b/packages/driver-node/README.md@@ -32,7 +32,7 @@ the prototype API.failure that Core accepts through its ordinary command-failed Event.- Preview, fallback and reuse are graph-level Candidates selected by BuildRequest, not Endpointmodes. A reused value is an Existing-Value Candidate; “Pin” is only the host UI action that selects- it. Candidate fidelity is sealed into the Core-derived plan before execution.+ it. Satisfaction fidelity is sealed into the Core-derived plan before execution.- Endpoint identity becomes the Receipt fulfiller; handlers return only value, conformance, delivery and metadata.- `TypeValidatorRegistry` is a separate exact-Type registry. Before an Event exists, the Driverstructurally checks every result, executes the Type owner's digest-locked validator when declared,diff --git a/packages/provider-kie/README.md b/packages/provider-kie/README.mdindex 74047050..4627de90 100644--- a/packages/provider-kie/README.md+++ b/packages/provider-kie/README.md@@ -99,5 +99,5 @@ that is explicitly approved for external upload.`KIE_BASE_URL` and `SVML_KIE_SMOKE_ROOT` are optional deployment overrides. The command printscredit usage, the content digest and a local inspection copy, but never prints or persists the key.-The checked-in 2026-08-06 representative results are recorded in-[`docs/kie-live-smoke-2026-08-06.md`](../../docs/kie-live-smoke-2026-08-06.md).+A representative run of all seven families and the optional upload case has passed. Generated+results are deployment evidence and are intentionally not committed as a dated transcript.diff --git a/packages/realization/README.md b/packages/realization/README.mdindex cac40aae..4660c563 100644--- a/packages/realization/README.md+++ b/packages/realization/README.md@@ -9,7 +9,7 @@ deterministically, retains the author source digest, records a separate Realizatand produces the graph universe consumed by Build Compiler.A Candidate is inert. It enters a finite BuildPlan only when a `BuildRequest` establishes an-explicit Satisfaction from a demanded Logical Output to that Candidate. The binding owns fidelity;+explicit Satisfaction from a demanded Logical Output to that Candidate. The Satisfaction owns fidelity;the Candidate owns only its Type and value/operation root. Product UI actions such as “Pin” createor locate an Existing-Value Candidate and then write an ordinary substitute Satisfaction; they donot mutate Core state or require a database.diff --git a/spec/core-kernel-v0.md b/spec/core-kernel-v0.mddeleted file mode 100644index bb7fb6a9..00000000--- a/spec/core-kernel-v0.md+++ /dev/null@@ -1,36 +0,0 @@-# SVML Core Kernel v0--Status: historical bootstrap contract; superseded by-[`core-kernel-v1.md`](./core-kernel-v1.md).--Core v0 is a domain-free verifier and deterministic state reducer. It does not parse source,-resolve package locations, execute implementations, access an artifact store, call providers,-or search the global producer set for a path to a goal.--## Laws--1. Every referenced module, type and producer belongs to one immutable resolved closure.-2. Records are immutable. Only a Frontend-created typed module may introduce authored origin;- producer and fulfillment events may append only derived or observed records.-3. Every missing external value is represented by a typed `Need` with explicit constraints and- an exact/substitute acceptance rule.-4. Every appended record has an origin that reaches an authored record, producer derivation or- fulfillment receipt.-5. A build executes only the finite steps in its explicit plan. Core never ranks or discovers- an undeclared producer.-6. State and events are canonical data. Replaying an accepted event is idempotent, and a paused- state can be serialized and resumed without semantic change.--## Boundary--Core owns linking, nominal type identity, structural value validation, plan validation,-state transitions and provenance verification.--The Node Driver owns manifest I/O, registered implementation execution, requirement handlers,-artifact bytes, journaling and pause/resume orchestration. Core emits commands; it never executes-them.--Frontend selection, `.svml`, `.svs`, Import Prologue and Surface Parser execution are explicitly-outside Core v0 and Driver v0. The data-only Protocol may declare a Surface in a Module Manifest,-and Core verifies its identity/mode/digest as ordinary closure data; this does not give Core any-source syntax or parser dispatch behavior.diff --git a/spec/core-kernel-v1.md b/spec/core-kernel-v1.mdindex 278415ae..30edc1cb 100644--- a/spec/core-kernel-v1.md+++ b/spec/core-kernel-v1.md@@ -1,79 +1,89 @@# SVML Core Kernel v1-Status: current executable v2 contract.+Status: current executable contract. The specification version is v1; current persisted Graph,+BuildRequest, Plan and BuildState wire formats are `@2`.-Core is a domain-free Build compiler and verified state machine. It does not parse `.svml`, know-video concepts, execute implementations, choose a Provider endpoint, access credentials or own a-queue.+Core is a domain-free graph-demand compiler and verified Build state machine. It does not parse+source, load packages, execute implementations, choose an Endpoint, access credentials, persist+artifacts or know video vocabulary.## Inputs-Core accepts immutable data:--- a resolved module closure and typed authored records;-- a complete `svml.graph@1` containing Logical Outputs, Candidates and atomic Operations;-- a `svml.build-request@1` containing one or more Targets and explicit non-primary Candidate- bindings.--Graph construction, package resolution, source parsing, static Fragment expansion and runtime-Candidate attachment happen outside Core. Core verifies their results before using them.--The reference construction path is deliberately layered: an optional Frontend produces typed-authored Records and parser-independent component declarations; `@svml/elaborator` resolves those-declarations and expands locked Graph Fragments; `@svml/realization` may attach explicitly selected-external Candidates. None of those reference packages is required by this Kernel contract.--## Laws--1. A Logical Output is the stable author-visible result identity. Every Candidate belongs to one- Logical Output and has exactly one root.-2. A Candidate root is either one immutable provided Value or one atomic Operation result. Core has- no Pin, preview or provider-fallback branch.-3. A BuildRequest selects a Candidate by id. An unbound output selects its declared primary- Candidate. Runtime state cannot silently change that choice.-4. Core compiles Demand backwards from all Targets. It resolves selected Candidates and their input- references in one traversal and memoizes every demanded Operation by stable OperationId.-5. An Existing-Value Candidate has no input edge, so Demand ends naturally. Multiple Targets and- multiple Candidates sharing one Operation demand that Operation once.-6. Every public Operation has one atomic result. Multi-value products are represented by one Product- result followed by deterministic Projection Operations.-7. Graph types, structural schemas and declared affinity constraints are verified without teaching- Core the meaning of a domain type.-8. A Type is nominally owned by its declaring module. Its structural Schema is always checked by- Core. The owner may additionally lock a semantic validator digest; if it does, every admitted- Record of that Type must carry a receipt bound to the exact Type, Record digest and validator- digest. The Host executes the validator; Core only verifies the declaration and receipt.-9. Exactness is monotonic. Candidate fidelity and the worst input conformance form a floor that no- later exact Producer or Provider response may improve.-10. Records, Needs, Commands, Events, Receipts and Derivations are content-bound immutable facts.- Derivations bind implementation, input/output digests, Need request digests and accepted event- digest.-11. Serialized outstanding Commands are not trusted. Resume verifies accepted state and regenerates- the next Command from that state.-12. A BuildPlan is a deterministic, finite derivative of the verified Graph and BuildRequest. A- Driver may schedule ready Commands, but cannot redefine Candidate selection or Demand.-13. A Build completes only when every Target's selected result exists with an accepted conformance.-14. The Graph is the only dependency truth. A domain Record contains only facts needed to interpret- that value; Derivation and Receipt contain lineage. Core affinity may compare intrinsic facts on- directly connected values, but must not require values to copy transitive ancestry.+Core accepts immutable, already linked data:-## Boundary+- a resolved module closure and typed authored Records;+- a complete `svml.graph@2` containing Logical Outputs, independent Candidates and atomic+ Operations from the Author and Run Graphs;+- a `svml.build-request@2` containing Targets and explicit Satisfaction edges.++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.+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.+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.+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+ before execution.+8. The resulting `svml.plan@2` is finite, deterministic and content-bound to the verified Graph and+ BuildRequest.-The data-only Protocol owns identities and wire shapes. Core owns their canonical verification,-Demand compilation and state transitions. Drivers own execution and persistence. Runtime Profiles-own scheduler placement, stores and credentials. Provider packages bind an already explicit-CapabilityRef to one exact endpoint. Domain contract packages own shared vocabulary such as-Narrative, ProgramSpace and Track.+## 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+ 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+ commands and deterministically regenerates the next commands.+8. A Build completes only when every Target Record exists with accepted conformance.++## Type and affinity 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+ fulfillment provenance.++## Boundary-Type validation does not centralize domain Types in Core. The declaring package owns the Schema and-optional validator identity; Producers and Consumers communicate only through the exact `TypeRef`.-The reference `@svml/validation` Host executes trusted validators and issues deterministic receipts.-Such a receipt proves consistency inside the trusted Host boundary, not execution safety or remote-authenticity of arbitrary plugin code. Sandboxing and attestation are Runtime concerns.+`@svml/protocol` owns wire data and identity. `@svml/core` owns verification, Demand compilation and+state transitions. Compiler packages own source and graph construction. Runtime owns scheduling,+persistence and placement. Endpoint packages fulfill exact Capabilities. Domain packages own shared+vocabulary and validators.-Neither a package suffix nor a TypeScript class grants Kernel privilege. A domain package can be-released after Core and participate through manifests, schemas and ordinary Operations without a-Core release.+Neither a file suffix, package name nor TypeScript class grants Kernel privilege. A domain package+released after Core can participate through manifests, nominal Types and ordinary Operations without+a Core release.-SVML source is one optional author-facing notation that lowers to this graph. The Kernel has no-canonical pipeline direction, privileged terminal output, Film root or single-output Build rule.+The Kernel has no privileged terminal output, Film root, video pipeline direction or single-Target+restriction.diff --git a/tools/analyze-highlight-transitions.mjs b/tools/analyze-highlight-transitions.mjsdeleted file mode 100644index 05fb5ff2..00000000--- a/tools/analyze-highlight-transitions.mjs+++ /dev/null@@ -1,100 +0,0 @@-#!/usr/bin/env node-import { spawn } from "node:child_process";--const [videoFile] = process.argv.slice(2);-if (!videoFile) {- throw new Error("usage: analyze-highlight-transitions.mjs <video.mp4>");-}--const width = 730;-const height = 130;-const bytesPerFrame = width * height * 3;-const ffmpeg = spawn("ffmpeg", [- "-hide_banner",- "-loglevel", "error",- "-i", videoFile,- "-vf", "crop=730:130:350:1010",- "-f", "rawvideo",- "-pix_fmt", "rgb24",- "-",-], { stdio: ["ignore", "pipe", "inherit"] });--let pending = Buffer.alloc(0);-let frame = 0;-let previous;--function highlightMask(buffer) {- const mask = new Uint8Array(width * height);- let count = 0;- let minX = width;- let maxX = -1;- let minY = height;- let maxY = -1;- for (let pixel = 0; pixel < mask.length; pixel += 1) {- const offset = pixel * 3;- const red = buffer[offset];- const green = buffer[offset + 1];- const blue = buffer[offset + 2];- const distance = (- (255 - red) ** 2- + (211 - green) ** 2- + (77 - blue) ** 2- );- if (distance > 1_800) continue;- mask[pixel] = 1;- count += 1;- const x = pixel % width;- const y = Math.floor(pixel / width);- minX = Math.min(minX, x);- maxX = Math.max(maxX, x);- minY = Math.min(minY, y);- maxY = Math.max(maxY, y);- }- return {- mask,- count,- box: count ? [minX, minY, maxX, maxY] : undefined,- };-}--function similarity(left, right) {- if (!left || !right) return 0;- let intersection = 0;- let union = 0;- for (let index = 0; index < left.mask.length; index += 1) {- const l = left.mask[index];- const r = right.mask[index];- if (l && r) intersection += 1;- if (l || r) union += 1;- }- return union ? intersection / union : 1;-}--ffmpeg.stdout.on("data", (chunk) => {- pending = Buffer.concat([pending, chunk]);- while (pending.length >= bytesPerFrame) {- const pixels = pending.subarray(0, bytesPerFrame);- pending = pending.subarray(bytesPerFrame);- const current = highlightMask(pixels);- const score = similarity(previous, current);- const appeared = current.count >= 40 && (!previous || previous.count < 40);- const disappeared = current.count < 40 && previous && previous.count >= 40;- if (appeared || disappeared || (current.count >= 40 && previous?.count >= 40 && score < 0.42)) {- process.stdout.write(- `${String(frame).padStart(4)} ${(frame / 30).toFixed(3)}s `- + `pixels=${String(current.count).padStart(4)} similarity=${score.toFixed(3)} `- + `box=${current.box?.join(",") ?? "-"}\n`,- );- }- previous = current;- frame += 1;- }-});--await new Promise((resolve, reject) => {- ffmpeg.on("error", reject);- ffmpeg.on("close", (code) => {- if (code === 0) resolve();- else reject(new Error(`ffmpeg exited ${code}`));- });-});diff --git a/tools/build-speech-timing.mjs b/tools/build-speech-timing.mjsdeleted file mode 100644index 836d21d2..00000000--- a/tools/build-speech-timing.mjs+++ /dev/null@@ -1,88 +0,0 @@-#!/usr/bin/env node-import { readFile, writeFile } from "node:fs/promises";-import { resolve } from "node:path";--const args = process.argv.slice(2);-function takeOption(name) {- const index = args.indexOf(name);- if (index < 0) return undefined;- const value = args[index + 1];- if (!value) throw new Error(`${name} requires a value.`);- args.splice(index, 2);- return value;-}--const timingOverrideFile = takeOption("--timing-overrides");-const fps = Number(takeOption("--fps") ?? 30);-const segmentFrames = Number(takeOption("--segment-frames") ?? 361);-const [scriptFile, outputFile, ...whisperFiles] = args;-if (!scriptFile || !outputFile || whisperFiles.length === 0) {- throw new Error(- "usage: build-speech-timing.mjs <script.json> <output.json> <whisper-1.json> ... "- + "[--fps 30] [--segment-frames 361] [--timing-overrides <overrides.json>]",- );-}-if (!Number.isFinite(fps) || fps <= 0 || !Number.isInteger(segmentFrames) || segmentFrames <= 0) {- throw new Error("fps and segment-frames must define a positive clock.");-}--const script = JSON.parse(await readFile(resolve(scriptFile), "utf8"));-if (!Array.isArray(script.segments) || script.segments.length !== whisperFiles.length) {- throw new Error("Script Segment count must match the supplied Whisper result count.");-}--const units = [];-for (const [segmentIndex, segment] of script.segments.entries()) {- const whisper = JSON.parse(await readFile(resolve(whisperFiles[segmentIndex]), "utf8"));- const offsetSec = segmentIndex * segmentFrames / fps;- const segmentEndSec = (segmentIndex + 1) * segmentFrames / fps;- for (const entry of whisper.transcription ?? []) {- const text = String(entry.text ?? "").trim();- if (!text) continue;- const startSec = Number(entry.offsets?.from) / 1000 + offsetSec;- const endSec = Number(entry.offsets?.to) / 1000 + offsetSec;- units.push({- text,- startSec: Math.max(offsetSec, Math.min(segmentEndSec, startSec)),- endSec: Math.max(offsetSec, Math.min(segmentEndSec, endSec)),- segmentId: segment.id,- });- }-}--const evidence = {- contract: "svml.speech-timing-evidence.v1",- durationSec: script.segments.length * segmentFrames / fps,- fps,- quality: "measured",- units,- segments: script.segments.map((segment, index) => ({- id: segment.id,- startSec: index * segmentFrames / fps,- endSec: (index + 1) * segmentFrames / fps,- })),- provenance: {- method: "whisper.cpp raw word timestamps",- source: "measured units are not corrected or projected to Script wording",- },-};--if (timingOverrideFile) {- const overrideDocument = JSON.parse(await readFile(resolve(timingOverrideFile), "utf8"));- if (!Array.isArray(overrideDocument.units)) {- throw new Error(`${timingOverrideFile} must contain a units array.`);- }- for (const override of overrideDocument.units) {- const index = Number(override.index);- const unit = evidence.units[index];- if (!Number.isInteger(index) || !unit) {- throw new Error(`${timingOverrideFile} contains invalid unit index ${String(override.index)}.`);- }- if (override.startSec !== undefined) unit.startSec = Number(override.startSec);- if (override.endSec !== undefined) unit.endSec = Number(override.endSec);- }- evidence.provenance.timingOverrides = overrideDocument.provenance- ?? "manual timing evidence correction";-}--await writeFile(resolve(outputFile), `${JSON.stringify(evidence, null, 2)}\n`);