Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

feat: assemble modular v2 compiler and runtime

kashorin1320b2c77fff
diff --git a/README.md b/README.md
index 0b4da056..2478010c 100644
--- a/README.md
+++ b/README.md
@@ -9,24 +9,57 @@
> CapabilityRefs. Declarative affinity prevents exact media evidence or provided values from being
> attached to the wrong Narrative/Basis.
> `packages/speech-take` proves atomic Product plus ordinary audio/visual Projection;
-> `packages/elaborator` expands content-addressed static Fragments with hygienic instance identities;
+> `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/video-fragments` now composes the first real speech vertical from static Fragments:
+> `packages/speech-program` now composes the first real speech vertical from static Fragments:
> SpeechTake projections, one-pass WhisperX evidence, a provider-neutral SemanticMap and timed
> captions. Producer-declared affinity protects internal Fragment results before they enter state;
> Logical-Output affinity separately protects selected Candidates.
-> The next composition waist is intentionally flat: captions, text, speech video, B-roll and overlay
+> `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>`.
+> 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; concrete local/Hypit adapters remain
-> Runtime packages outside this slice. Third-party parser sandboxing,
-> source imports and `.svs` are not implemented yet. The existing
+> 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 remains undecided. `packages/compiler-node` now supplies the domain-free
+> registered-manifest resolver, root-confined/read-once filesystem Source Host 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 Provider 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 Provider 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. Automatic third-party
+> package installation, parser/validator sandboxing, durable stores, leases and production Endpoint
+> adapters are not implemented yet. The existing
> root compiler and standard library remain the executable v1 research oracle during migration.
+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 semantic source language for information-flow
video. Script creates stable semantic addresses. A Composition selects one
content-addressed `ProgramBasis` and one exact `SemanticMap`; flat Track
@@ -96,6 +129,9 @@ pnpm check
pnpm test
pnpm build
+# v2: real Source Closure check through the trusted Text + Script + SVS prelude.
+pnpm svml:v2 check examples/v2-bootstrap/main.svml
+
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
@@ -157,8 +193,22 @@ Canvas owns only a human-readable view.
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. Its README marks every implemented and missing lowering;
+Script, Film and Render are accepted by the current compiler, while the intervening generation,
+Speech and Track Surfaces remain a design target.
+
## 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
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..f5b7c268
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,83 @@
+# 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. [`implementation-status.md#domain-neutral-package-boundary`](./implementation-status.md#domain-neutral-package-boundary)
+ — the minimal package stack for video and non-video domains.
+5. [`../spec/script-surface-v1.md`](../spec/script-surface-v1.md) — current official Script Surface
+ target.
+6. [`../spec/track-composition-v1.md`](../spec/track-composition-v1.md) — implemented flat Track and
+ Composition law and the generic HyperFrames lowering boundary.
+7. [`../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.
+8. [`../examples/talking-film-golden/README.md`](../examples/talking-film-golden/README.md) — the
+ canonical v2 authoring target: implemented Script syntax surrounded by the Film, Seedance,
+ WhisperX, Caption, B-roll, Text, SVS and render Surfaces that must be built next.
+9. [`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.
+10. [`../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.
+
+The executable v2 Node entrypoints are documented in
+[`../packages/compiler-node/README.md`](../packages/compiler-node/README.md) and
+[`../packages/cli/README.md`](../packages/cli/README.md). The former is domain-neutral compiler-host
+infrastructure; the latter is the official trusted 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; durable adapters, leases and production 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.
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 00000000..bcd18b9c
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,25 @@
+# SVML examples
+
+The repository deliberately separates the executable v2 bootstrap, executable research fixtures
+and the complete v2 authoring target.
+
+## Executable v2 bootstrap
+
+- [`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.
+
+## v2 authoring target
+
+- [`talking-film-golden/main.svml`](./talking-film-golden/main.svml) is the canonical visual and
+ semantic target for the next author-facing Surfaces. Its Script syntax is implemented; its outer
+ package Surfaces are tracked line by line in the adjacent README and are not executable yet.
+
+## 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.
diff --git a/examples/talking-film-golden/README.md b/examples/talking-film-golden/README.md
new file mode 100644
index 00000000..73917961
--- /dev/null
+++ b/examples/talking-film-golden/README.md
@@ -0,0 +1,114 @@
+# Talking-film authoring golden fixture
+
+Status: **v2 authoring target, not executable end to end yet.** Script, Film, generic SVS and the
+explicit HyperFrames Render Surface are implemented. The intervening generation, Speech and Track
+components are the concrete package-local work remaining.
+
+This example replaces neither the executable v1 fixtures nor their regression value. In particular,
+`examples/flat-track-launch` remains the capability oracle for selections, moments, B-roll motion,
+caption styling, sound and absolute stacking. This directory answers a different question:
+
+> What should a normal author write after the v2 package architecture is hidden behind good
+> namespaced Surfaces?
+
+## What the source says—and does not say
+
+The source explicitly chooses:
+
+- two Seedance **Mini** speech generations, each with its own Script Segment, Prompt and reference;
+- one Seedance Mini B-roll generation;
+- one WhisperX measurement path;
+- the Gemini-backed official Caption package;
+- Hyperframes as the final rendering method.
+
+It does not contain API keys, endpoint URLs, queue names, database names or deployment topology.
+Those facts belong to a Runtime Profile. Runtime may bind `seedance.mini.*` to KIE, Volcengine or
+Hypit, but it may not reinterpret Seedance as Kling or silently replace Gemini cue planning with a
+different model family.
+
+Prompt declarations, media declarations and `.svs` recipes appear before their uses. The Script
+remains prose-first and contains no generation, styling or Track configuration.
+
+The outer namespaced `.svml` tags do not each require a custom parser. `@svml/text` reads them with
+one generic structured parser and validates them against the imported package Manifest; the owning
+package supplies its schema and lowerer. Only the prose-first Script body needs the imported raw
+Script Surface, while the CSS-like `.svs` source deliberately uses the separate `@svml/svs`
+Frontend named by `using`.
+
+## Author data flow
+
+```text
+Script ────────────────────────────────────────────────┐
+ ├─ Segment + Prompt + reference -> Seedance Speech ─┤
+ ├─ Segment + Prompt + reference -> Seedance Speech ─┤
+ │ ▼
+ │ Speech Spine
+ │ ┌──────────┴──────────┐
+ │ │ │
+ │ audio basis visual/audio Tracks
+ │ │
+ ├──────────────────────────────> WhisperX + speech-align
+ │ │
+ │ CompleteSemanticMap
+ │ ┌───────┴────────┐
+ │ │ │
+ │ Caption Track B-roll Track
+ │
+ └─ caption display projection
+
+Seedance B-roll + Text Track + every Track above
+ -> Film Composition
+ -> explicit Hyperframes compile + render component
+ -> final video Need
+```
+
+This is not a stored global workflow graph. The imported author packages lower these declarations
+into a finite Graph Fragment for this source unit. Core sees only typed Logical Outputs, selected
+Candidates and Operations.
+
+## Lowering ledger
+
+| Author syntax | Owning package | Lowered meaning | Repository state |
+|---|---|---|---|
+| `<script>` | `@svml/script` | authored `Narrative` and projections | implemented |
+| `media:Image` | `@svml/media` | content-addressed authored Artifact | package/Surface missing |
+| `seedance:Prompt` | `@svml/seedance` | package-private immutable direction value | missing |
+| `seedance:Speech model="mini"` | `@svml/seedance` | explicit Seedance Mini Need returning one speech clip Product | missing |
+| `speech:Spine` | `@svml/speech` | ordered clips -> one `SpeechBasis`, then ordinary projections | basis/projections implemented; author assembly missing |
+| `whisperx:Alignment` | `@svml/whisperx` | request -> normalize -> provider-neutral `@svml/speech-align` -> Map | Graph Fragment implemented; Surface/endpoint missing |
+| `seedance:Video model="mini"` | `@svml/seedance` | explicit Seedance Mini video Need | missing |
+| `broll:Track` | `@svml/broll` | semantic windows + media + recipe -> peer Visual/Audio Tracks | Program/lowering implemented; Surface missing |
+| `caption:Track` | `@svml/caption-gemini` | timed projection + Gemini cue grouping + role recipe -> VisualTrack | base timing/lowering implemented; Gemini/role Surface missing |
+| `text:Track` | `@svml/text-track` | package Program -> VisualTrack | Program/lowering implemented; Surface/exact-font use missing |
+| `film:Film` | `@svml/film` | finite TrackSet fold -> Composition | Graph Fragment and official Surface implemented |
+| `render:Video` | `@svml/hyperframes-render` | Composition -> HyperframesDocument -> explicit render Need -> final video Artifact + Receipt | Surface, Fragment, Need and Product projection implemented; real Providers missing |
+| `studio.svs` | `@svml/svs` | generic immutable Recipe Records; consuming packages must validate and lower them | parser and recursive source import implemented; video recipe consumers/exact font lowering missing |
+
+The missing work is intentionally package-local. None of these rows requires a new Core video type,
+a component-family registry in Core, a privileged Film root or another Track kind.
+
+## Expected Provider bindings
+
+A local developer profile could bind the exact capabilities as follows:
+
+```yaml
+bindings:
+ seedance.mini.speech-video@1: kie.seedance-mini
+ seedance.mini.video@1: kie.seedance-mini
+ whisperx.alignment-evidence@1: whisperx.local
+ google.gemini.structured-generation@1: gemini.api
+ hyperframes.render@1: hyperframes.local
+```
+
+A Hypit profile changes endpoint bindings, not `main.svml`. Existing Values, black frames and other
+preview realizations remain explicitly selected Candidates in a BuildRequest; they do not alter
+the author source or teach Runtime to guess a creative method.
+
+The intended final command is:
+
+```bash
+svml build main.svml --target final.video
+```
+
+Before the remaining Surfaces and Providers are implemented, tools must report that the complete
+file is a design fixture rather than pretending to compile it with the v1 engine.
diff --git a/examples/talking-film-golden/main.svml b/examples/talking-film-golden/main.svml
new file mode 100644
index 00000000..86508be1
--- /dev/null
+++ b/examples/talking-film-golden/main.svml
@@ -0,0 +1,130 @@
+<!--
+ SVML authoring golden fixture.
+ Script, Film and HyperFrames Render Surfaces are implemented. The intervening
+ generation, Speech and Track Surfaces remain the package-local design target.
+-->
+<svml>
+ <import from="@svml/script@1"/>
+ <import as="media" from="@svml/media@1"/>
+ <import as="seedance" from="@svml/seedance@1"/>
+ <import as="speech" from="@svml/speech@1"/>
+ <import as="whisperx" from="@svml/whisperx@1"/>
+ <import as="caption" from="@svml/caption-gemini@1"/>
+ <import as="broll" from="@svml/broll@1"/>
+ <import as="text" from="@svml/text-track@1"/>
+ <import as="film" from="@svml/film@1"/>
+ <import as="render" from="@svml/hyperframes-render@1"/>
+ <import as="studio" from="./studio.svs" using="@svml/svs@1"/>
+
+ <script>
+ @alice-shot
+ <opening>
+ <ALICE> What if a video could be edited by meaning instead of a timeline?
+ </opening>
+ @/alice-shot
+
+ @bob-shot
+ <answer>
+ <BOB> Then the script becomes the source. @product-demo
+ <SVML | semantic video markup language> lets every visual know why it is there
+ @/product-demo.
+ </answer>
+ @/bob-shot
+ </script>
+
+ <!-- Content and directions are declared once, before any generation uses them. -->
+ <media:Image id="alice-reference" src="./assets/alice.png"/>
+ <media:Image id="bob-reference" src="./assets/bob.png"/>
+ <media:Image id="product-reference" src="./assets/product.png"/>
+
+ <seedance:Prompt id="alice-direction">
+ Locked medium close-up. Alice speaks directly to camera in a quiet daylight studio.
+ Calm, curious delivery; natural breathing and restrained hand movement.
+ </seedance:Prompt>
+
+ <seedance:Prompt id="bob-direction">
+ Locked medium close-up. Bob answers from a warm editorial workspace.
+ Precise, assured delivery; hold eye contact and keep the background still.
+ </seedance:Prompt>
+
+ <seedance:Prompt id="product-direction">
+ A clean vertical product film: the written script becomes semantic regions, then those
+ regions assemble into a finished video. No readable UI text and no camera shake.
+ </seedance:Prompt>
+
+ <!-- The author explicitly chooses Seedance Mini. Runtime only binds a matching endpoint. -->
+ <seedance:Speech
+ id="alice-take"
+ model="mini"
+ script={script.segment.opening}
+ prompt={alice-direction}
+ >
+ <seedance:Reference image={alice-reference} role="character"/>
+ </seedance:Speech>
+
+ <seedance:Speech
+ id="bob-take"
+ model="mini"
+ script={script.segment.answer}
+ prompt={bob-direction}
+ >
+ <seedance:Reference image={bob-reference} role="character"/>
+ </seedance:Speech>
+
+ <!-- Ordered generated Takes become one audio basis plus its peer visual/audio Tracks. -->
+ <speech:Spine id="speech" narrative={script} appearance={studio.speech.full}>
+ <speech:Take source={alice-take}/>
+ <speech:Take source={bob-take}/>
+ </speech:Spine>
+
+ <!-- One explicit WhisperX path: request, normalize and deterministic Script alignment. -->
+ <whisperx:Alignment id="timing" narrative={script} audio={speech.audio}/>
+
+ <seedance:Video
+ id="product-motion"
+ model="mini"
+ prompt={product-direction}
+ >
+ <seedance:Reference image={product-reference} role="subject"/>
+ </seedance:Video>
+
+ <broll:Track id="product-broll" map={timing.map}>
+ <broll:Item
+ source={product-motion.video}
+ during={script.selection.product-demo}
+ appearance={studio.broll.product}
+ />
+ </broll:Track>
+
+ <!-- This imported package explicitly chooses Gemini cue planning; it cannot rewrite Script. -->
+ <caption:Track
+ id="captions"
+ narrative={script}
+ map={timing.map}
+ grouping={studio.caption.short-cues}
+ appearance={studio.caption.dialogue}
+ >
+ <caption:Role role="ALICE" appearance={studio.caption.alice}/>
+ <caption:Role role="BOB" appearance={studio.caption.bob}/>
+ </caption:Track>
+
+ <text:Track id="titles" space={speech.space}>
+ <text:Item
+ text="EDIT MEANING, NOT TIMELINES"
+ during="full"
+ appearance={studio.text.title}
+ />
+ </text:Track>
+
+ <!-- Child order is organizational. Every Present carries its own absolute stack position. -->
+ <film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+ <film:Track source={speech.visual}/>
+ <film:Track source={speech.audioTrack}/>
+ <film:Track source={product-broll.visual}/>
+ <film:Track source={captions.track}/>
+ <film:Track source={titles.track}/>
+ </film:Film>
+
+ <!-- Rendering is an explicit Hyperframes capability, not an implicit Film side effect. -->
+ <render:Video id="final" composition={main.composition}/>
+</svml>
diff --git a/examples/talking-film-golden/studio.svs b/examples/talking-film-golden/studio.svs
new file mode 100644
index 00000000..c9ec02ba
--- /dev/null
+++ b/examples/talking-film-golden/studio.svs
@@ -0,0 +1,87 @@
+<sheet version="1" id="studio">
+
+ /* Exact font bytes become FontArtifactRef values during author lowering. */
+ font.inter-semibold {
+ src: ./assets/Inter-SemiBold.woff2;
+ weight: 600;
+ style: normal;
+ }
+
+ font.inter-black {
+ src: ./assets/Inter-Black.woff2;
+ weight: 900;
+ style: normal;
+ }
+
+ film.vertical {
+ width: 1080;
+ height: 1920;
+ frame-rate: 30;
+ background: #09090B;
+ }
+
+ speech.full {
+ stack-order: 10;
+ x: 0;
+ y: 0;
+ width: 1;
+ height: 1;
+ fit: cover;
+ }
+
+ broll.product {
+ stack-order: 40;
+ x: 0.08;
+ y: 0.20;
+ width: 0.84;
+ height: 0.48;
+ fit: contain;
+ background: #111116;
+ radius: 28;
+ enter: slide-up 8f;
+ exit: fade 6f;
+ }
+
+ caption.short-cues {
+ model: gemini-2.5-flash;
+ max-words: 5;
+ max-lines: 2;
+ }
+
+ caption.dialogue {
+ stack-order: 70;
+ x: 0.08;
+ y: 0.76;
+ width: 0.84;
+ font: inter-semibold;
+ size: 58;
+ line-height: 0.96;
+ align: center;
+ fill: #FFFFFF;
+ background: #09090BCC;
+ padding: 16 24;
+ radius: 18;
+ }
+
+ caption.alice {
+ active-fill: #73FBD3;
+ }
+
+ caption.bob {
+ active-fill: #FFD166;
+ }
+
+ text.title {
+ stack-order: 90;
+ x: 0.06;
+ y: 0.06;
+ width: 0.88;
+ height: 0.10;
+ font: inter-black;
+ size: 64;
+ align: center;
+ fill: #FFFFFF;
+ tracking: -1;
+ }
+
+</sheet>
diff --git a/examples/v2-bootstrap/README.md b/examples/v2-bootstrap/README.md
new file mode 100644
index 00000000..f3abd3a4
--- /dev/null
+++ b/examples/v2-bootstrap/README.md
@@ -0,0 +1,13 @@
+# v2 bootstrap source example
+
+This is the smallest real-file example accepted by the current trusted v2 CLI prelude. It proves
+that the Text entry source can import the Script Surface and recursively compile an SVS source with
+another Frontend:
+
+```bash
+pnpm svml:v2 check examples/v2-bootstrap/main.svml
+```
+
+The Recipe is intentionally unused: package-owned Recipe consumption is the next author-language
+decision. This example therefore checks Source/Module Closure and authored Records but has no
+component Logical Output to `plan` or execute.
diff --git a/examples/v2-bootstrap/main.svml b/examples/v2-bootstrap/main.svml
new file mode 100644
index 00000000..0ae4fd98
--- /dev/null
+++ b/examples/v2-bootstrap/main.svml
@@ -0,0 +1,10 @@
+<svml>
+ <import from="@svml/script@1"/>
+ <import as="studio" from="./studio.svs" using="@svml/svs@1"/>
+
+ <script id="story">
+ <opening>
+ <ALICE>Meaning becomes the source, and packages decide how to understand it.
+ </opening>
+ </script>
+</svml>
diff --git a/examples/v2-bootstrap/studio.svs b/examples/v2-bootstrap/studio.svs
new file mode 100644
index 00000000..cbd83a5e
--- /dev/null
+++ b/examples/v2-bootstrap/studio.svs
@@ -0,0 +1,6 @@
+<sheet version="1" id="studio">
+ caption.host {
+ fill: #FFFFFF;
+ size: 72;
+ }
+</sheet>
diff --git a/open-source-prep.md b/open-source-prep.md
new file mode 100644
index 00000000..96388b5e
--- /dev/null
+++ b/open-source-prep.md
@@ -0,0 +1,285 @@
+# 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/package.json b/package.json
index e20f5714..920fab36 100644
--- a/package.json
+++ b/package.json
@@ -14,7 +14,8 @@
"test": "pnpm test:v1 && pnpm test:v2",
"test:v1": "node --import tsx --test 'test/**/*.test.ts'",
"test:v2": "node --import tsx --test 'packages/*/test/**/*.test.ts'",
- "svml": "node --import tsx src/cli.ts"
+ "svml": "node --import tsx src/cli.ts",
+ "svml:v2": "node --import tsx packages/cli/src/cli.ts"
},
"files": [
"dist/src",
diff --git a/packages/broll/README.md b/packages/broll/README.md
new file mode 100644
index 00000000..e996882d
--- /dev/null
+++ b/packages/broll/README.md
@@ -0,0 +1,9 @@
+# `@svml/broll`
+
+Official B-roll authoring and lowering package. It owns B-roll items, local
+entrance/exit motion, pair transitions, source audio and transition SFX. It
+emits ordinary `VisualTrack` and `AudioTrack` values whose Presents participate
+in Composition by their own absolute z.
+
+It does not generate media, select a Provider, read another Track, sample the
+accumulated lower composite or implement Base/Screen FX.
diff --git a/packages/broll/package.json b/packages/broll/package.json
new file mode 100644
index 00000000..92bc3d7d
--- /dev/null
+++ b/packages/broll/package.json
@@ -0,0 +1,16 @@
+{
+ "name": "@svml/broll",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "dependencies": {
+ "@svml/contracts": "workspace:*",
+ "@svml/protocol": "workspace:*"
+ },
+ "devDependencies": {
+ "@svml/hyperframes": "workspace:*"
+ }
+}
diff --git a/packages/broll/src/index.ts b/packages/broll/src/index.ts
new file mode 100644
index 00000000..b147f342
--- /dev/null
+++ b/packages/broll/src/index.ts
@@ -0,0 +1,23 @@
+export {
+ assertBrollProductIdentity,
+ assertBrollProgramIdentity,
+ compileBrollImplementationDigest,
+ compileBrollProduct,
+ computeBrollProductDigest,
+ computeBrollProgramDigest,
+ projectBrollAudio,
+ projectBrollAudioImplementationDigest,
+ projectBrollVisual,
+ projectBrollVisualImplementationDigest,
+ sealBrollProgram,
+} from "./program.js";
+export {
+ brollManifest,
+ brollManifestDigest,
+ brollModuleRef,
+ brollProductSchema,
+ brollProgramSchema,
+ brollProducers,
+ brollTypes,
+} from "./manifest.js";
+export type * from "./types.js";
diff --git a/packages/broll/src/manifest.ts b/packages/broll/src/manifest.ts
new file mode 100644
index 00000000..3858c8a1
--- /dev/null
+++ b/packages/broll/src/manifest.ts
@@ -0,0 +1,175 @@
+import {
+ audioTrackSchema,
+ contractTypes,
+ mediaArtifactSchema,
+ programSpaceSchema,
+ videoContractDependencies,
+ visualTrackSchema,
+} from "@svml/contracts";
+import { digestOf } from "@svml/protocol";
+import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@svml/protocol";
+
+import {
+ compileBrollImplementationDigest,
+ projectBrollAudioImplementationDigest,
+ projectBrollVisualImplementationDigest,
+} from "./program.js";
+
+export const brollModuleRef = { name: "@svml/broll", version: "0.0.0-dev" } as const;
+export const brollTypes = {
+ program: { module: brollModuleRef, name: "BrollProgram" },
+ product: { module: brollModuleRef, name: "BrollProduct" },
+} satisfies Record<string, TypeRef>;
+export const brollProducers = {
+ compile: { module: brollModuleRef, name: "compile-broll" },
+ projectVisual: { module: brollModuleRef, name: "project-broll-visual" },
+ projectAudio: { module: brollModuleRef, name: "project-broll-audio" },
+} satisfies Record<string, ProducerRef>;
+
+const string = { kind: "string", minLength: 1 } as const;
+const number = { kind: "number" } as const;
+const unsignedInteger = { kind: "number", integer: true, minimum: 0 } as const;
+const signedInteger = { kind: "number", integer: true } as const;
+const digest = { kind: "string", minLength: 71, maxLength: 71 } as const;
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({
+ kind: "object",
+ fields,
+});
+
+const frameSpan = object({
+ startFrame: { schema: unsignedInteger },
+ endFrameExclusive: { schema: unsignedInteger },
+});
+const box = object({
+ xPercent: { schema: number },
+ yPercent: { schema: number },
+ widthPercent: { schema: number },
+ heightPercent: { schema: number },
+});
+const motion = object({
+ operator: { schema: { kind: "string", enum: ["fade", "pop", "slide-up", "slide-down"] } },
+ durationFrames: { schema: unsignedInteger },
+ amount: { schema: number, optional: true },
+});
+const item = object({
+ id: { schema: string },
+ artifact: { schema: mediaArtifactSchema },
+ span: { schema: frameSpan },
+ z: { schema: signedInteger },
+ tieBreak: { schema: string },
+ box: { schema: box },
+ fit: { schema: { kind: "string", enum: ["contain", "cover"] } },
+ playback: { schema: { kind: "string", enum: ["freeze", "native", "loop", "stretch"] } },
+ mediaStartSec: { schema: number, optional: true },
+ includeAudio: { schema: { kind: "boolean" }, optional: true },
+ audioGain: { schema: number, optional: true },
+ enter: { schema: motion, optional: true },
+ exit: { schema: motion, optional: true },
+});
+const transition = object({
+ id: { schema: string },
+ fromItemId: { schema: string },
+ toItemId: { schema: string },
+ span: { schema: frameSpan },
+ operator: { schema: { kind: "string", enum: ["push", "page-turn"] } },
+ direction: { schema: { kind: "string", enum: ["left", "right", "up", "down"] } },
+ sfx: { schema: object({
+ artifact: { schema: mediaArtifactSchema },
+ gain: { schema: number, optional: true },
+ }), optional: true },
+});
+
+export const brollProgramSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.broll-program@1" } },
+ digest: { schema: digest },
+ id: { schema: string },
+ programSpaceDigest: { schema: digest },
+ items: { schema: { kind: "array", minItems: 1, items: item } },
+ transitions: { schema: { kind: "array", items: transition } },
+});
+
+export const brollProductSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.broll-product@1" } },
+ productDigest: { schema: digest },
+ programDigest: { schema: digest },
+ programSpace: { schema: programSpaceSchema },
+ visualTrack: { schema: visualTrackSchema },
+ audioTrack: { schema: audioTrackSchema },
+});
+
+export const brollManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: brollModuleRef.name,
+ version: brollModuleRef.version,
+ dependencies: [
+ videoContractDependencies.programSpace,
+ videoContractDependencies.composition,
+ ],
+ types: [
+ { name: brollTypes.program.name, schema: brollProgramSchema },
+ { name: brollTypes.product.name, schema: brollProductSchema },
+ ],
+ capabilities: [],
+ surfaces: [],
+ producers: [
+ {
+ name: brollProducers.compile.name,
+ inputs: [
+ { name: "space", type: contractTypes.programSpace },
+ { name: "program", type: brollTypes.program },
+ ],
+ outputs: [{
+ name: "product",
+ type: brollTypes.product,
+ affinity: [
+ { resultPointer: "/programDigest", input: "program", inputPointer: "/digest" },
+ { resultPointer: "/programSpace/digest", input: "space", inputPointer: "/digest" },
+ ],
+ }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "@svml/broll/compile",
+ digest: compileBrollImplementationDigest,
+ },
+ },
+ {
+ name: brollProducers.projectVisual.name,
+ inputs: [{ name: "product", type: brollTypes.product }],
+ outputs: [{
+ name: "visual",
+ type: contractTypes.visualTrack,
+ affinity: [
+ { resultPointer: "/programSpaceDigest", input: "product", inputPointer: "/programSpace/digest" },
+ { resultPointer: "/sources/0/digest", input: "product", inputPointer: "/programDigest" },
+ ],
+ }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "@svml/broll/project-visual",
+ digest: projectBrollVisualImplementationDigest,
+ },
+ },
+ {
+ name: brollProducers.projectAudio.name,
+ inputs: [{ name: "product", type: brollTypes.product }],
+ outputs: [{
+ name: "audio",
+ type: contractTypes.audioTrack,
+ affinity: [
+ { resultPointer: "/programSpaceDigest", input: "product", inputPointer: "/programSpace/digest" },
+ { resultPointer: "/sources/0/digest", input: "product", inputPointer: "/programDigest" },
+ ],
+ }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "@svml/broll/project-audio",
+ digest: projectBrollAudioImplementationDigest,
+ },
+ },
+ ],
+};
+
+export const brollManifestDigest = digestOf(brollManifest);
diff --git a/packages/broll/src/program.ts b/packages/broll/src/program.ts
new file mode 100644
index 00000000..eb33fa39
--- /dev/null
+++ b/packages/broll/src/program.ts
@@ -0,0 +1,468 @@
+import {
+ assertAudioTrackIdentity,
+ assertProgramSpaceIdentity,
+ assertVisualTrackIdentity,
+ programSpaceFrameCount,
+ sealAudioTrack,
+ sealVisualTrack,
+} from "@svml/contracts";
+import type {
+ AudioClip,
+ MediaArtifactRef,
+ ProgramSpace,
+ VisualAnimation,
+ VisualElement,
+ VisualStyleDeclaration,
+} from "@svml/contracts";
+import { digestOf, isDigest } from "@svml/protocol";
+import type { Digest } from "@svml/protocol";
+
+import type {
+ BrollItem,
+ BrollMotion,
+ BrollPairTransition,
+ BrollProduct,
+ BrollProgram,
+} from "./types.js";
+
+export const compileBrollImplementationDigest = digestOf("@svml/broll/compile@1");
+export const projectBrollVisualImplementationDigest = digestOf("@svml/broll/project-visual@1");
+export const projectBrollAudioImplementationDigest = digestOf("@svml/broll/project-audio@1");
+
+type MotionState = {
+ readonly opacity: number;
+ readonly transform: string;
+};
+
+type StateMark = MotionState & {
+ readonly atFrame: number;
+ readonly easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+};
+
+const STABLE: MotionState = { opacity: 1, transform: "translate3d(0%,0%,0) scale(1) rotateX(0deg) rotateY(0deg)" };
+
+function normalizeProgram(value: Omit<BrollProgram, "digest">): Omit<BrollProgram, "digest"> {
+ return {
+ contract: "svml.broll-program@1",
+ id: value.id,
+ programSpaceDigest: value.programSpaceDigest,
+ items: [...value.items].map((item) => structuredClone(item)).sort((left, right) => left.id.localeCompare(right.id)),
+ transitions: [...value.transitions].map((transition) => structuredClone(transition)).sort((left, right) => left.id.localeCompare(right.id)),
+ };
+}
+
+export function computeBrollProgramDigest(value: Omit<BrollProgram, "digest">): Digest {
+ return digestOf(normalizeProgram(value));
+}
+
+export function sealBrollProgram(value: Omit<BrollProgram, "digest">): BrollProgram {
+ const content = normalizeProgram(value);
+ return { ...content, digest: digestOf(content) };
+}
+
+function assertArtifact(artifact: MediaArtifactRef, label: string, kinds: readonly string[]): void {
+ if (
+ !isDigest(artifact.digest)
+ || !Number.isSafeInteger(artifact.size)
+ || artifact.size < 0
+ || !Number.isFinite(artifact.durationSec)
+ || artifact.durationSec < 0
+ || !kinds.some((kind) => artifact.mediaType.startsWith(`${kind}/`))
+ ) {
+ throw new Error(`${label} Artifact is invalid.`);
+ }
+}
+
+function assertSpan(item: { readonly startFrame: number; readonly endFrameExclusive: number }, totalFrames: number, label: string): void {
+ if (
+ !Number.isSafeInteger(item.startFrame)
+ || !Number.isSafeInteger(item.endFrameExclusive)
+ || item.startFrame < 0
+ || item.endFrameExclusive <= item.startFrame
+ || item.endFrameExclusive > totalFrames
+ ) throw new Error(`${label} span is outside ProgramSpace.`);
+}
+
+function assertMotion(motion: BrollMotion | undefined, itemFrames: number, label: string): void {
+ if (motion === undefined) return;
+ if (!Number.isSafeInteger(motion.durationFrames) || motion.durationFrames <= 0 || motion.durationFrames > itemFrames) {
+ throw new Error(`${label} duration is invalid.`);
+ }
+ if (!["fade", "pop", "slide-up", "slide-down"].includes(motion.operator)) {
+ throw new Error(`${label} operator is unsupported.`);
+ }
+ if (motion.amount !== undefined && (!Number.isFinite(motion.amount) || motion.amount <= 0 || motion.amount > 4)) {
+ throw new Error(`${label} amount is invalid.`);
+ }
+}
+
+function assertItem(item: BrollItem, totalFrames: number): void {
+ if (!item.id || !item.tieBreak) throw new Error("B-roll item identity must not be empty.");
+ assertArtifact(item.artifact, `B-roll item ${item.id}`, ["image", "video"]);
+ assertSpan(item.span, totalFrames, `B-roll item ${item.id}`);
+ if (!Number.isSafeInteger(item.z)) throw new Error(`B-roll item ${item.id} z is invalid.`);
+ for (const [name, value] of Object.entries(item.box)) {
+ if (!Number.isFinite(value)) throw new Error(`B-roll item ${item.id} ${name} is invalid.`);
+ }
+ if (item.box.widthPercent <= 0 || item.box.heightPercent <= 0) {
+ throw new Error(`B-roll item ${item.id} box must have positive size.`);
+ }
+ const isImage = item.artifact.mediaType.startsWith("image/");
+ if (isImage && item.playback !== "freeze") throw new Error(`B-roll image ${item.id} must use freeze playback.`);
+ if (!isImage && item.playback === "freeze") throw new Error(`B-roll video ${item.id} cannot use freeze playback.`);
+ if (item.mediaStartSec !== undefined && (!Number.isFinite(item.mediaStartSec) || item.mediaStartSec < 0)) {
+ throw new Error(`B-roll item ${item.id} mediaStartSec is invalid.`);
+ }
+ if (item.audioGain !== undefined && (!Number.isFinite(item.audioGain) || item.audioGain < 0)) {
+ throw new Error(`B-roll item ${item.id} audioGain is invalid.`);
+ }
+ if (item.includeAudio && isImage) throw new Error(`B-roll image ${item.id} cannot contribute source audio.`);
+ if (item.includeAudio && item.playback === "loop") {
+ throw new Error(`B-roll item ${item.id} cannot loop source audio in the v1 AudioTrack contract.`);
+ }
+ const duration = item.span.endFrameExclusive - item.span.startFrame;
+ assertMotion(item.enter, duration, `B-roll item ${item.id} enter motion`);
+ assertMotion(item.exit, duration, `B-roll item ${item.id} exit motion`);
+ if ((item.enter?.durationFrames ?? 0) + (item.exit?.durationFrames ?? 0) > duration) {
+ throw new Error(`B-roll item ${item.id} entrance and exit overlap.`);
+ }
+}
+
+function sameBox(left: BrollItem["box"], right: BrollItem["box"]): boolean {
+ return left.xPercent === right.xPercent
+ && left.yPercent === right.yPercent
+ && left.widthPercent === right.widthPercent
+ && left.heightPercent === right.heightPercent;
+}
+
+function transitionMaps(program: BrollProgram, totalFrames: number) {
+ const items = new Map(program.items.map((item) => [item.id, item]));
+ const incoming = new Map<string, BrollPairTransition>();
+ const outgoing = new Map<string, BrollPairTransition>();
+ const ids = new Set<string>();
+ for (const transition of program.transitions) {
+ if (!transition.id || ids.has(transition.id)) throw new Error(`B-roll transition id ${transition.id} is empty or duplicated.`);
+ ids.add(transition.id);
+ const from = items.get(transition.fromItemId);
+ const to = items.get(transition.toItemId);
+ if (!from || !to || from === to) throw new Error(`B-roll transition ${transition.id} has invalid endpoints.`);
+ assertSpan(transition.span, totalFrames, `B-roll transition ${transition.id}`);
+ if (
+ transition.span.endFrameExclusive !== from.span.endFrameExclusive
+ || transition.span.startFrame !== to.span.startFrame
+ || transition.span.startFrame < from.span.startFrame
+ || transition.span.endFrameExclusive > to.span.endFrameExclusive
+ ) {
+ throw new Error(`B-roll transition ${transition.id} must be the outgoing and incoming boundary of its two items.`);
+ }
+ if (!sameBox(from.box, to.box)) {
+ throw new Error(`B-roll transition ${transition.id} requires both items to share one presentation box.`);
+ }
+ if (from.exit || to.enter) throw new Error(`B-roll transition ${transition.id} conflicts with item edge motion.`);
+ if (outgoing.has(from.id) || incoming.has(to.id)) throw new Error(`B-roll transition ${transition.id} duplicates an item edge.`);
+ if (!["push", "page-turn"].includes(transition.operator)) throw new Error(`B-roll transition ${transition.id} operator is unsupported.`);
+ if (!["left", "right", "up", "down"].includes(transition.direction)) throw new Error(`B-roll transition ${transition.id} direction is unsupported.`);
+ if (transition.sfx) {
+ assertArtifact(transition.sfx.artifact, `B-roll transition ${transition.id} SFX`, ["audio"]);
+ if (transition.sfx.gain !== undefined && (!Number.isFinite(transition.sfx.gain) || transition.sfx.gain < 0)) {
+ throw new Error(`B-roll transition ${transition.id} SFX gain is invalid.`);
+ }
+ }
+ outgoing.set(from.id, transition);
+ incoming.set(to.id, transition);
+ }
+ for (const item of program.items) {
+ const before = incoming.get(item.id);
+ const after = outgoing.get(item.id);
+ if (before && after && before.span.endFrameExclusive > after.span.startFrame) {
+ throw new Error(`B-roll item ${item.id} has overlapping pair transitions.`);
+ }
+ }
+ return { incoming, outgoing };
+}
+
+export function assertBrollProgramIdentity(program: BrollProgram, programSpace: ProgramSpace): void {
+ assertProgramSpaceIdentity(programSpace);
+ if (program.contract !== "svml.broll-program@1") throw new Error("Unsupported BrollProgram contract.");
+ if (!program.id || program.programSpaceDigest !== programSpace.digest) throw new Error("BrollProgram identity or ProgramSpace affinity is invalid.");
+ const { digest: _digest, ...content } = program;
+ if (!isDigest(program.digest) || program.digest !== computeBrollProgramDigest(content)) {
+ throw new Error("BrollProgram digest does not match its contents.");
+ }
+ if (program.items.length === 0) throw new Error("BrollProgram must contain at least one item.");
+ const totalFrames = programSpaceFrameCount(programSpace);
+ const ids = new Set<string>();
+ for (const item of program.items) {
+ if (ids.has(item.id)) throw new Error(`BrollProgram contains duplicate item ${item.id}.`);
+ ids.add(item.id);
+ assertItem(item, totalFrames);
+ }
+ transitionMaps(program, totalFrames);
+}
+
+function motionState(motion: BrollMotion, channel: "enter" | "exit"): MotionState {
+ if (motion.operator === "fade") return { opacity: 0, transform: STABLE.transform };
+ if (motion.operator === "pop") {
+ const scale = motion.amount ?? 0.72;
+ return { opacity: 0, transform: `translate3d(0%,0%,0) scale(${scale}) rotateX(0deg) rotateY(0deg)` };
+ }
+ const distance = (motion.amount ?? 1) * 100;
+ if (motion.operator === "slide-down") {
+ const y = channel === "enter" ? -distance : distance;
+ return { opacity: 1, transform: `translate3d(0%,${y}%,0) scale(1) rotateX(0deg) rotateY(0deg)` };
+ }
+ const y = channel === "enter" ? distance : -distance;
+ return { opacity: 1, transform: `translate3d(0%,${y}%,0) scale(1) rotateX(0deg) rotateY(0deg)` };
+}
+
+function pairState(
+ transition: BrollPairTransition,
+ endpoint: "incoming" | "outgoing",
+): MotionState {
+ const incoming = endpoint === "incoming";
+ const sign = incoming ? -1 : 1;
+ if (transition.operator === "push") {
+ const vectors = {
+ left: [-100, 0],
+ right: [100, 0],
+ up: [0, -100],
+ down: [0, 100],
+ } as const;
+ const [x, y] = vectors[transition.direction];
+ return { opacity: 1, transform: `translate3d(${x * sign}%,${y * sign}%,0) scale(1) rotateX(0deg) rotateY(0deg)` };
+ }
+ const angle = (transition.direction === "left" || transition.direction === "up" ? -90 : 90) * sign;
+ const transform = transition.direction === "left" || transition.direction === "right"
+ ? `perspective(1200px) rotateY(${angle}deg)`
+ : `perspective(1200px) rotateX(${angle}deg)`;
+ return { opacity: incoming ? 0 : 0, transform };
+}
+
+function sameState(left: MotionState, right: MotionState): boolean {
+ return left.opacity === right.opacity && left.transform === right.transform;
+}
+
+function addMark(marks: Map<number, StateMark>, mark: StateMark, label: string): void {
+ const previous = marks.get(mark.atFrame);
+ if (previous && !sameState(previous, mark)) throw new Error(`${label} has conflicting animation states at frame ${mark.atFrame}.`);
+ marks.set(mark.atFrame, previous ? { ...previous, ...(mark.easing === undefined ? {} : { easing: mark.easing }) } : mark);
+}
+
+function itemAnimation(
+ item: BrollItem,
+ incoming: BrollPairTransition | undefined,
+ outgoing: BrollPairTransition | undefined,
+): VisualAnimation | undefined {
+ const duration = item.span.endFrameExclusive - item.span.startFrame;
+ const marks = new Map<number, StateMark>();
+ addMark(marks, { ...STABLE, atFrame: 0 }, item.id);
+ addMark(marks, { ...STABLE, atFrame: duration }, item.id);
+
+ if (item.enter) {
+ marks.set(0, { ...motionState(item.enter, "enter"), atFrame: 0, easing: "ease-out" });
+ addMark(marks, { ...STABLE, atFrame: item.enter.durationFrames }, item.id);
+ }
+ if (item.exit) {
+ const start = duration - item.exit.durationFrames;
+ addMark(marks, { ...STABLE, atFrame: start, easing: "ease-in" }, item.id);
+ marks.set(duration, { ...motionState(item.exit, "exit"), atFrame: duration });
+ }
+ if (incoming) {
+ const end = incoming.span.endFrameExclusive - item.span.startFrame;
+ marks.set(0, { ...pairState(incoming, "incoming"), atFrame: 0, easing: "ease-in-out" });
+ addMark(marks, { ...STABLE, atFrame: end }, item.id);
+ }
+ if (outgoing) {
+ const start = outgoing.span.startFrame - item.span.startFrame;
+ addMark(marks, { ...STABLE, atFrame: start, easing: "ease-in-out" }, item.id);
+ marks.set(duration, { ...pairState(outgoing, "outgoing"), atFrame: duration });
+ }
+
+ const ordered = [...marks.values()].sort((left, right) => left.atFrame - right.atFrame);
+ if (ordered.every((mark) => sameState(mark, STABLE))) return undefined;
+ return {
+ keyframes: ordered.map((mark) => ({
+ atFrame: mark.atFrame,
+ ...(mark.easing === undefined ? {} : { easing: mark.easing }),
+ style: [
+ { name: "opacity", value: mark.opacity },
+ { name: "transform", value: mark.transform },
+ ],
+ })),
+ };
+}
+
+function itemElements(
+ item: BrollItem,
+ animation: VisualAnimation | undefined,
+ programSpace: ProgramSpace,
+): readonly VisualElement[] {
+ const presentSeconds = (item.span.endFrameExclusive - item.span.startFrame)
+ * programSpace.frameRate.denominator / programSpace.frameRate.numerator;
+ const isImage = item.artifact.mediaType.startsWith("image/");
+ const playbackRate = item.playback === "stretch" && item.artifact.durationSec > 0
+ ? item.artifact.durationSec / presentSeconds
+ : undefined;
+ const rootStyle: VisualStyleDeclaration[] = [
+ { name: "height", value: `${item.box.heightPercent}%` },
+ { name: "left", value: `${item.box.xPercent}%` },
+ { name: "overflow", value: "hidden" },
+ { name: "position", value: "absolute" },
+ { name: "top", value: `${item.box.yPercent}%` },
+ { name: "transform-origin", value: "center center" },
+ { name: "width", value: `${item.box.widthPercent}%` },
+ ];
+ return [
+ {
+ id: "root",
+ order: 0,
+ kind: "box",
+ style: rootStyle,
+ ...(animation === undefined ? {} : { animation }),
+ },
+ {
+ id: "media",
+ parent: "root",
+ order: 1,
+ kind: isImage ? "image" : "video",
+ artifact: item.artifact,
+ style: [
+ { name: "height", value: "100%" },
+ { name: "object-fit", value: item.fit },
+ { name: "position", value: "absolute" },
+ { name: "width", value: "100%" },
+ ],
+ ...(item.mediaStartSec === undefined ? {} : { mediaStartSec: item.mediaStartSec }),
+ ...(playbackRate === undefined ? {} : { playbackRate }),
+ ...(!isImage && item.playback === "loop" ? { loop: true } : {}),
+ ...(!isImage ? { muted: item.includeAudio !== true } : {}),
+ },
+ ];
+}
+
+function audioClips(program: BrollProgram, programSpace: ProgramSpace): AudioClip[] {
+ const clips: AudioClip[] = program.items.flatMap((item) => {
+ if (!item.includeAudio) return [];
+ const presentSeconds = (item.span.endFrameExclusive - item.span.startFrame)
+ * programSpace.frameRate.denominator / programSpace.frameRate.numerator;
+ const playbackRate = item.playback === "stretch" && item.artifact.durationSec > 0
+ ? item.artifact.durationSec / presentSeconds
+ : undefined;
+ return [{
+ id: `source:${item.id}`,
+ span: { ...item.span },
+ artifact: item.artifact,
+ ...(item.mediaStartSec === undefined ? {} : { mediaStartSec: item.mediaStartSec }),
+ ...(playbackRate === undefined ? {} : { playbackRate }),
+ ...(item.audioGain === undefined ? {} : { gain: item.audioGain }),
+ bus: "source" as const,
+ }];
+ });
+ const totalFrames = programSpaceFrameCount(programSpace);
+ for (const transition of program.transitions) {
+ if (!transition.sfx) continue;
+ const durationFrames = Math.max(1, Math.round(
+ transition.sfx.artifact.durationSec
+ * programSpace.frameRate.numerator
+ / programSpace.frameRate.denominator,
+ ));
+ clips.push({
+ id: `transition:${transition.id}`,
+ span: {
+ startFrame: transition.span.startFrame,
+ endFrameExclusive: Math.min(totalFrames, transition.span.startFrame + durationFrames),
+ },
+ artifact: transition.sfx.artifact,
+ ...(transition.sfx.gain === undefined ? {} : { gain: transition.sfx.gain }),
+ bus: "sfx",
+ });
+ }
+ return clips;
+}
+
+function productContent(value: Omit<BrollProduct, "productDigest">): Omit<BrollProduct, "productDigest"> {
+ return {
+ contract: "svml.broll-product@1",
+ programDigest: value.programDigest,
+ programSpace: structuredClone(value.programSpace),
+ visualTrack: structuredClone(value.visualTrack),
+ audioTrack: structuredClone(value.audioTrack),
+ };
+}
+
+export function computeBrollProductDigest(value: Omit<BrollProduct, "productDigest">): Digest {
+ return digestOf(productContent(value));
+}
+
+export function compileBrollProduct(programSpace: ProgramSpace, program: BrollProgram): BrollProduct {
+ assertBrollProgramIdentity(program, programSpace);
+ const { incoming, outgoing } = transitionMaps(program, programSpaceFrameCount(programSpace));
+ const sources = [{ name: "program", digest: program.digest }];
+ const visualTrack = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: `${program.id}:visual`,
+ programSpaceDigest: programSpace.digest,
+ sources,
+ presents: program.items.map((item) => ({
+ id: item.id,
+ span: { ...item.span },
+ stacking: { order: item.z, tieBreak: item.tieBreak },
+ elements: itemElements(item, itemAnimation(item, incoming.get(item.id), outgoing.get(item.id)), programSpace),
+ })),
+ });
+ const audioTrack = sealAudioTrack({
+ contract: "svml.audio-track@1",
+ id: `${program.id}:audio`,
+ programSpaceDigest: programSpace.digest,
+ sources,
+ clips: audioClips(program, programSpace),
+ });
+ const content = productContent({
+ contract: "svml.broll-product@1",
+ programDigest: program.digest,
+ programSpace,
+ visualTrack,
+ audioTrack,
+ });
+ const product = { ...content, productDigest: digestOf(content) };
+ assertBrollProductIdentity(product, programSpace);
+ return product;
+}
+
+export function assertBrollProductIdentity(product: BrollProduct, programSpace: ProgramSpace): void {
+ assertProgramSpaceIdentity(programSpace);
+ assertProgramSpaceIdentity(product.programSpace);
+ if (product.contract !== "svml.broll-product@1") throw new Error("Unsupported BrollProduct contract.");
+ if (
+ !isDigest(product.programDigest)
+ || product.programSpace.digest !== programSpace.digest
+ || product.visualTrack.sources.find((source) => source.name === "program")?.digest !== product.programDigest
+ || product.audioTrack.sources.find((source) => source.name === "program")?.digest !== product.programDigest
+ ) throw new Error("BrollProduct affinity is invalid.");
+ const { productDigest: _digest, ...content } = product;
+ if (!isDigest(product.productDigest) || product.productDigest !== computeBrollProductDigest(content)) {
+ throw new Error("BrollProduct digest does not match its contents.");
+ }
+ assertVisualTrackIdentity(product.visualTrack, programSpace);
+ assertAudioTrackIdentity(product.audioTrack, programSpace);
+}
+
+function assertStandaloneProductDigest(product: BrollProduct): void {
+ const { productDigest: _digest, ...content } = product;
+ if (!isDigest(product.productDigest) || product.productDigest !== computeBrollProductDigest(content)) {
+ throw new Error("BrollProduct digest does not match its contents.");
+ }
+ assertProgramSpaceIdentity(product.programSpace);
+ assertVisualTrackIdentity(product.visualTrack, product.programSpace);
+ assertAudioTrackIdentity(product.audioTrack, product.programSpace);
+}
+
+export function projectBrollVisual(product: BrollProduct) {
+ assertStandaloneProductDigest(product);
+ return product.visualTrack;
+}
+
+export function projectBrollAudio(product: BrollProduct) {
+ assertStandaloneProductDigest(product);
+ return product.audioTrack;
+}
diff --git a/packages/broll/src/types.ts b/packages/broll/src/types.ts
new file mode 100644
index 00000000..5f073328
--- /dev/null
+++ b/packages/broll/src/types.ts
@@ -0,0 +1,73 @@
+import type {
+ AudioTrack,
+ FrameSpan,
+ MediaArtifactRef,
+ ProgramSpace,
+ VisualTrack,
+} from "@svml/contracts";
+import type { Digest } from "@svml/protocol";
+
+export type BrollBox = {
+ readonly xPercent: number;
+ readonly yPercent: number;
+ readonly widthPercent: number;
+ readonly heightPercent: number;
+};
+
+export type BrollMotionOperator = "fade" | "pop" | "slide-up" | "slide-down";
+
+export type BrollMotion = {
+ readonly operator: BrollMotionOperator;
+ readonly durationFrames: number;
+ /** Slide distance or pop start/end scale. Package-defined and deterministic. */
+ readonly amount?: number;
+};
+
+export type BrollItem = {
+ readonly id: string;
+ readonly artifact: MediaArtifactRef;
+ readonly span: FrameSpan;
+ readonly z: number;
+ readonly tieBreak: string;
+ readonly box: BrollBox;
+ readonly fit: "contain" | "cover";
+ readonly playback: "freeze" | "native" | "loop" | "stretch";
+ readonly mediaStartSec?: number;
+ readonly includeAudio?: boolean;
+ readonly audioGain?: number;
+ readonly enter?: BrollMotion;
+ readonly exit?: BrollMotion;
+};
+
+export type BrollPairTransition = {
+ readonly id: string;
+ readonly fromItemId: string;
+ readonly toItemId: string;
+ readonly span: FrameSpan;
+ readonly operator: "push" | "page-turn";
+ readonly direction: "left" | "right" | "up" | "down";
+ readonly sfx?: {
+ readonly artifact: MediaArtifactRef;
+ readonly gain?: number;
+ };
+};
+
+/** Official B-roll authoring/lowering value. It is not a Core contract. */
+export type BrollProgram = {
+ readonly contract: "svml.broll-program@1";
+ readonly digest: Digest;
+ readonly id: string;
+ readonly programSpaceDigest: Digest;
+ readonly items: readonly BrollItem[];
+ readonly transitions: readonly BrollPairTransition[];
+};
+
+/** One atomic compilation result followed by ordinary deterministic projections. */
+export type BrollProduct = {
+ readonly contract: "svml.broll-product@1";
+ readonly productDigest: Digest;
+ readonly programDigest: Digest;
+ readonly programSpace: ProgramSpace;
+ readonly visualTrack: VisualTrack;
+ readonly audioTrack: AudioTrack;
+};
diff --git a/packages/broll/test/broll.test.ts b/packages/broll/test/broll.test.ts
new file mode 100644
index 00000000..ef84d193
--- /dev/null
+++ b/packages/broll/test/broll.test.ts
@@ -0,0 +1,193 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ assertBrollProductIdentity,
+ assertBrollProgramIdentity,
+ compileBrollProduct,
+ computeBrollProductDigest,
+ projectBrollAudio,
+ projectBrollVisual,
+ sealBrollProgram,
+} from "@svml/broll";
+import {
+ sealComposition,
+ sealProgramSpace,
+ sealVisualTrack,
+} from "@svml/contracts";
+import type { MediaArtifactRef } from "@svml/contracts";
+import type { BrollItem, BrollPairTransition } from "@svml/broll";
+import { compileHyperframesDocument } from "@svml/hyperframes";
+import { digestOf } from "@svml/protocol";
+
+const programSpace = sealProgramSpace({
+ contract: "svml.program-space@0",
+ durationSec: 10,
+ frameRate: { numerator: 30, denominator: 1 },
+});
+
+function artifact(id: string, mediaType = "video/mp4", durationSec = 4): MediaArtifactRef {
+ return { digest: digestOf(`broll:${id}`), size: 100, mediaType, durationSec };
+}
+
+function item(overrides: Partial<BrollItem> & Pick<BrollItem, "id" | "span" | "z">): BrollItem {
+ return {
+ artifact: artifact(overrides.id),
+ tieBreak: overrides.id,
+ box: { xPercent: 0, yPercent: 0, widthPercent: 100, heightPercent: 100 },
+ fit: "cover",
+ playback: "native",
+ ...overrides,
+ };
+}
+
+function program(items: readonly BrollItem[], transitions: readonly BrollPairTransition[] = []) {
+ return sealBrollProgram({
+ contract: "svml.broll-program@1",
+ id: "story-broll",
+ programSpaceDigest: programSpace.digest,
+ items,
+ transitions,
+ });
+}
+
+test("B-roll owns local motion while every item remains an independently stacked Present", () => {
+ const authored = program([
+ item({
+ id: "board",
+ artifact: artifact("board", "image/png", 0),
+ span: { startFrame: 0, endFrameExclusive: 300 },
+ z: 30,
+ playback: "freeze",
+ enter: { operator: "pop", durationFrames: 15 },
+ exit: { operator: "fade", durationFrames: 15 },
+ }),
+ item({
+ id: "cutaway",
+ span: { startFrame: 30, endFrameExclusive: 150 },
+ z: 80,
+ enter: { operator: "slide-down", durationFrames: 12 },
+ exit: { operator: "slide-up", durationFrames: 12 },
+ includeAudio: true,
+ audioGain: 0.7,
+ }),
+ ]);
+ assert.doesNotThrow(() => assertBrollProgramIdentity(authored, programSpace));
+ const product = compileBrollProduct(programSpace, authored);
+ assert.doesNotThrow(() => assertBrollProductIdentity(product, programSpace));
+ const board = product.visualTrack.presents.find((present) => present.id === "board")!;
+ const cutaway = product.visualTrack.presents.find((present) => present.id === "cutaway")!;
+ assert.equal(board.stacking.order, 30);
+ assert.equal(cutaway.stacking.order, 80);
+ assert.deepEqual(board.elements[0]!.animation?.keyframes.map((keyframe) => keyframe.atFrame), [0, 15, 285, 300]);
+ assert.deepEqual(cutaway.elements[0]!.animation?.keyframes.map((keyframe) => keyframe.atFrame), [0, 12, 108, 120]);
+ assert.deepEqual(product.audioTrack.clips.map((clip) => clip.id), ["source:cutaway"]);
+
+ const middle = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "middle-overlay",
+ programSpaceDigest: programSpace.digest,
+ sources: [{ name: "request", digest: digestOf("middle-overlay") }],
+ presents: [{
+ id: "middle",
+ span: { startFrame: 0, endFrameExclusive: 300 },
+ stacking: { order: 50, tieBreak: "middle" },
+ elements: [{ id: "root", order: 0, kind: "box", style: [] }],
+ }],
+ });
+ const document = compileHyperframesDocument(sealComposition({
+ contract: "svml.composition@1",
+ id: "interleaved-broll",
+ programSpace,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [projectBrollVisual(product), middle, projectBrollAudio(product)],
+ }));
+ const boardAt = document.html.indexOf('data-svml-present-id="board"');
+ const middleAt = document.html.indexOf('data-svml-present-id="middle"');
+ const cutawayAt = document.html.indexOf('data-svml-present-id="cutaway"');
+ assert.ok(boardAt < middleAt && middleAt < cutawayAt, "Presents from one B-roll Track must interleave with peers by absolute z");
+});
+
+test("push is lowered into complementary animations inside one B-roll-owned handoff", () => {
+ const authored = program([
+ item({ id: "a", span: { startFrame: 0, endFrameExclusive: 120 }, z: 70 }),
+ item({ id: "b", span: { startFrame: 105, endFrameExclusive: 240 }, z: 71 }),
+ ], [{
+ id: "a-to-b",
+ fromItemId: "a",
+ toItemId: "b",
+ span: { startFrame: 105, endFrameExclusive: 120 },
+ operator: "push",
+ direction: "left",
+ }]);
+ const product = compileBrollProduct(programSpace, authored);
+ const from = product.visualTrack.presents.find((present) => present.id === "a")!;
+ const to = product.visualTrack.presents.find((present) => present.id === "b")!;
+ assert.deepEqual(from.elements[0]!.animation?.keyframes.map((keyframe) => keyframe.atFrame), [0, 105, 120]);
+ assert.deepEqual(to.elements[0]!.animation?.keyframes.map((keyframe) => keyframe.atFrame), [0, 15, 135]);
+ assert.match(String(from.elements[0]!.animation?.keyframes.at(-1)?.style[1]?.value), /translate3d\(-100%/u);
+ assert.match(String(to.elements[0]!.animation?.keyframes[0]?.style[1]?.value), /translate3d\(100%/u);
+});
+
+test("page-turn and transition SFX remain B-roll-owned and lower to generic visual/audio facts", () => {
+ const sfx = artifact("page-sfx", "audio/wav", 0.2);
+ const authored = program([
+ item({ id: "page-a", span: { startFrame: 0, endFrameExclusive: 90 }, z: 40 }),
+ item({ id: "page-b", span: { startFrame: 75, endFrameExclusive: 180 }, z: 41 }),
+ ], [{
+ id: "turn",
+ fromItemId: "page-a",
+ toItemId: "page-b",
+ span: { startFrame: 75, endFrameExclusive: 90 },
+ operator: "page-turn",
+ direction: "left",
+ sfx: { artifact: sfx, gain: 0.8 },
+ }]);
+ const product = compileBrollProduct(programSpace, authored);
+ assert.equal(product.audioTrack.clips[0]?.id, "transition:turn");
+ assert.deepEqual(product.audioTrack.clips[0]?.span, { startFrame: 75, endFrameExclusive: 81 });
+ const document = compileHyperframesDocument(sealComposition({
+ contract: "svml.composition@1",
+ id: "page-turn",
+ programSpace,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [product.visualTrack, product.audioTrack],
+ }));
+ assert.match(document.html, /perspective\(1200px\) rotateY/u);
+ assert.match(document.html, new RegExp(sfx.digest.slice("sha256:".length), "u"));
+});
+
+test("B-roll rejects a pair transition that is not both items' exact shared boundary", () => {
+ const authored = program([
+ item({ id: "a", span: { startFrame: 0, endFrameExclusive: 120 }, z: 70 }),
+ item({ id: "b", span: { startFrame: 105, endFrameExclusive: 240 }, z: 71 }),
+ ], [{
+ id: "invalid",
+ fromItemId: "a",
+ toItemId: "b",
+ span: { startFrame: 106, endFrameExclusive: 119 },
+ operator: "push",
+ direction: "down",
+ }]);
+ assert.throws(() => compileBrollProduct(programSpace, authored), /must be the outgoing and incoming boundary/);
+});
+
+test("an Existing BrollProduct cannot recompute its own digest around an out-of-space Present", () => {
+ const product = compileBrollProduct(programSpace, program([
+ item({ id: "bounded", span: { startFrame: 0, endFrameExclusive: 120 }, z: 20 }),
+ ]));
+ const present = product.visualTrack.presents[0]!;
+ const invalidVisual = sealVisualTrack({
+ ...product.visualTrack,
+ presents: [{ ...present, span: { startFrame: 0, endFrameExclusive: 301 } }],
+ });
+ const content = {
+ contract: product.contract,
+ programDigest: product.programDigest,
+ programSpace: product.programSpace,
+ visualTrack: invalidVisual,
+ audioTrack: product.audioTrack,
+ };
+ const tampered = { ...content, productDigest: computeBrollProductDigest(content) };
+ assert.throws(() => projectBrollVisual(tampered), /outside ProgramSpace/);
+});
diff --git a/packages/caption/package.json b/packages/caption/package.json
index 62e7aa5b..c8f37c02 100644
--- a/packages/caption/package.json
+++ b/packages/caption/package.json
@@ -8,7 +8,6 @@
},
"dependencies": {
"@svml/contracts": "workspace:*",
- "@svml/core": "workspace:*",
"@svml/protocol": "workspace:*"
},
"devDependencies": {
diff --git a/packages/caption/src/index.ts b/packages/caption/src/index.ts
index 039ccd7b..67465814 100644
--- a/packages/caption/src/index.ts
+++ b/packages/caption/src/index.ts
@@ -4,7 +4,18 @@ export {
captionManifest,
captionModuleRef,
captionProducers,
+ captionTrackProgramSchema,
+ captionTypes,
+ timedCaptionProjectionSchema,
} from "./manifest.js";
export { planCaptionPresentation } from "./presentation.js";
export { temporalizeCaption } from "./temporalize.js";
+export {
+ assertCaptionTrackProgram,
+ computeCaptionTrackProgramDigest,
+ defaultCaptionTrackProgram,
+ renderCaptionTrack,
+ renderCaptionTrackImplementationDigest,
+ sealCaptionTrackProgram,
+} from "./track.js";
export type * from "./types.js";
diff --git a/packages/caption/src/manifest.ts b/packages/caption/src/manifest.ts
index 03fb4797..1bca6b57 100644
--- a/packages/caption/src/manifest.ts
+++ b/packages/caption/src/manifest.ts
@@ -1,44 +1,148 @@
import {
contractTypes,
- contractsManifestDigest,
- contractsModuleRef,
+ programSpaceSchema,
+ videoContractDependencies,
} from "@svml/contracts";
-import { digestOf } from "@svml/core";
-import type { ModuleManifest, ProducerRef } from "@svml/protocol";
+import { digestOf } from "@svml/protocol";
+import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@svml/protocol";
+
+import { renderCaptionTrackImplementationDigest } from "./track.js";
export const captionModuleRef = { name: "@svml/caption", version: "0.0.0-dev" } as const;
export const captionProducers = {
temporalize: { module: captionModuleRef, name: "temporalize-caption" },
+ renderTrack: { module: captionModuleRef, name: "render-caption-track" },
} satisfies Record<string, ProducerRef>;
+export const captionTypes = {
+ timedProjection: { module: captionModuleRef, name: "TimedCaptionProjection" },
+ trackProgram: { module: captionModuleRef, name: "CaptionTrackProgram" },
+} satisfies Record<string, TypeRef>;
export const captionImplementationDigest = digestOf("@svml/caption/temporalize@1");
+const string = { kind: "string", minLength: 1 } as const;
+const number = { kind: "number", minimum: 0 } as const;
+const integer = { kind: "number", integer: true, minimum: 0 } as const;
+const digest = { kind: "string", minLength: 71, maxLength: 71 } as const;
+const object = (
+ fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>,
+): ValueSchema => ({ kind: "object", fields });
+
+const quality = { kind: "string", enum: ["measured", "derived", "estimated"] } as const;
+const timedCaptionRefinement = object({
+ id: { schema: string },
+ display: { schema: string },
+ displayStart: { schema: integer },
+ displayEnd: { schema: integer },
+ sourceTokenIds: { schema: { kind: "array", items: string } },
+ startSec: { schema: number },
+ endSec: { schema: number },
+ startQuality: { schema: quality },
+ endQuality: { schema: quality },
+ relation: { schema: { kind: "literal", value: "exact" } },
+});
+const timedCaptionRegion = object({
+ id: { schema: string },
+ display: { schema: { kind: "string" } },
+ segmentId: { schema: string },
+ kind: { schema: { kind: "string", enum: ["identity", "alias", "hidden"] } },
+ sourceTokenIds: { schema: { kind: "array", items: string } },
+ startSec: { schema: number },
+ endSec: { schema: number },
+ startQuality: { schema: quality },
+ endQuality: { schema: quality },
+ refinements: { schema: { kind: "array", items: timedCaptionRefinement } },
+});
+export const timedCaptionProjectionSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.timed-caption-projection@1" } },
+ semanticIndexDigest: { schema: digest },
+ speechTimeMapDigest: { schema: digest },
+ programSpace: { schema: programSpaceSchema },
+ text: { schema: { kind: "string" } },
+ regions: { schema: { kind: "array", items: timedCaptionRegion } },
+ projectionDigest: { schema: digest },
+});
+
+export const captionTrackProgramSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.caption-track-program@1" } },
+ digest: { schema: digest },
+ id: { schema: string },
+ mode: { schema: { kind: "string", enum: ["whole", "proportional-word", "character-flow"] } },
+ stacking: { schema: object({ order: { schema: integer }, tieBreak: { schema: string } }) },
+ style: { schema: object({
+ fontFamily: { schema: string },
+ fontSizePx: { schema: number },
+ fontWeight: { schema: number },
+ color: { schema: string },
+ backgroundColor: { schema: string, optional: true },
+ paddingXPx: { schema: number },
+ paddingYPx: { schema: number },
+ borderRadiusPx: { schema: number },
+ bottomPercent: { schema: number },
+ maxWidthPercent: { schema: number },
+ textAlign: { schema: { kind: "string", enum: ["left", "center", "right"] } },
+ }) },
+});
+
export const captionManifest: ModuleManifest = {
format: "svml.module@0",
name: captionModuleRef.name,
version: captionModuleRef.version,
- dependencies: [{ module: contractsModuleRef, digest: contractsManifestDigest }],
- types: [],
+ dependencies: [
+ videoContractDependencies.narrative,
+ videoContractDependencies.programSpace,
+ videoContractDependencies.semanticTime,
+ videoContractDependencies.composition,
+ ],
+ types: [
+ { name: captionTypes.timedProjection.name, schema: timedCaptionProjectionSchema },
+ { name: captionTypes.trackProgram.name, schema: captionTrackProgramSchema },
+ ],
capabilities: [],
surfaces: [],
- producers: [{
- name: captionProducers.temporalize.name,
- inputs: [
- { name: "narrative", type: contractTypes.narrative },
- { name: "map", type: contractTypes.completeSemanticMap },
- ],
- outputs: [{
- name: "caption",
- type: contractTypes.timedCaptionProjection,
- affinity: [
- { resultPointer: "/semanticIndexDigest", input: "narrative", inputPointer: "/semanticIndex/digest" },
- { resultPointer: "/speechTimeMapDigest", input: "map", inputPointer: "/mapDigest" },
+ producers: [
+ {
+ name: captionProducers.temporalize.name,
+ inputs: [
+ { name: "narrative", type: contractTypes.narrative },
+ { name: "map", type: contractTypes.completeSemanticMap },
+ ],
+ outputs: [{
+ name: "caption",
+ type: captionTypes.timedProjection,
+ affinity: [
+ { resultPointer: "/semanticIndexDigest", input: "narrative", inputPointer: "/semanticIndex/digest" },
+ { resultPointer: "/speechTimeMapDigest", input: "map", inputPointer: "/mapDigest" },
+ { resultPointer: "/programSpace/digest", input: "map", inputPointer: "/programSpace/digest" },
+ ],
+ }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "@svml/caption/temporalize",
+ digest: captionImplementationDigest,
+ },
+ },
+ {
+ name: captionProducers.renderTrack.name,
+ inputs: [
+ { name: "caption", type: captionTypes.timedProjection },
+ { name: "program", type: captionTypes.trackProgram },
],
- }],
- needs: [],
- implementation: {
- kind: "registered",
- locator: "@svml/caption/temporalize",
- digest: captionImplementationDigest,
+ outputs: [{
+ name: "track",
+ type: contractTypes.visualTrack,
+ affinity: [
+ { resultPointer: "/programSpaceDigest", input: "caption", inputPointer: "/programSpace/digest" },
+ { resultPointer: "/sources/0/digest", input: "program", inputPointer: "/digest" },
+ { resultPointer: "/sources/1/digest", input: "caption", inputPointer: "/projectionDigest" },
+ ],
+ }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "@svml/caption/render-track",
+ digest: renderCaptionTrackImplementationDigest,
+ },
},
- }],
+ ],
};
diff --git a/packages/caption/src/presentation.ts b/packages/caption/src/presentation.ts
index 2ac03d7e..83efdf38 100644
--- a/packages/caption/src/presentation.ts
+++ b/packages/caption/src/presentation.ts
@@ -1,4 +1,4 @@
-import { digestOf } from "@svml/core";
+import { digestOf } from "@svml/protocol";
import type { Digest } from "@svml/protocol";
import type {
@@ -6,7 +6,7 @@ import type {
CaptionPresentationPlan,
CaptionPresentationUnit,
TimedCaptionRegion,
-} from "@svml/contracts";
+} from "./types.js";
const DISPLAY_WORD = /[\p{L}\p{M}\p{N}]+(?:['’.-][\p{L}\p{M}\p{N}]+)*/gu;
diff --git a/packages/caption/src/temporalize.ts b/packages/caption/src/temporalize.ts
index fe2e7dee..89cbed70 100644
--- a/packages/caption/src/temporalize.ts
+++ b/packages/caption/src/temporalize.ts
@@ -1,4 +1,4 @@
-import { digestOf } from "@svml/core";
+import { digestOf } from "@svml/protocol";
import type { CompleteSemanticMap, Narrative, TimingQuality } from "@svml/contracts";
import { CaptionProjectionError } from "./error.js";
@@ -71,6 +71,7 @@ export function temporalizeCaption(
contract: "svml.timed-caption-projection@1" as const,
semanticIndexDigest: narrative.semanticIndex.digest,
speechTimeMapDigest: map.mapDigest,
+ programSpace: map.programSpace,
text: narrative.captionProjection.text,
regions,
};
diff --git a/packages/caption/src/track.ts b/packages/caption/src/track.ts
new file mode 100644
index 00000000..3c3f8033
--- /dev/null
+++ b/packages/caption/src/track.ts
@@ -0,0 +1,181 @@
+import {
+ assertProgramSpaceIdentity,
+ assertVisualTrackIdentity,
+ programSpaceFrameCount,
+ sealVisualTrack,
+} from "@svml/contracts";
+import type { VisualStyleDeclaration, VisualTrack } from "@svml/contracts";
+import { digestOf, isDigest } from "@svml/protocol";
+import type { Digest } from "@svml/protocol";
+
+import { planCaptionPresentation } from "./presentation.js";
+import type { TimedCaptionProjection } from "./types.js";
+import type { CaptionTrackProgram } from "./types.js";
+
+export const renderCaptionTrackImplementationDigest = digestOf("@svml/caption/render-track@1");
+
+function normalizedProgram(value: Omit<CaptionTrackProgram, "digest">): Omit<CaptionTrackProgram, "digest"> {
+ return {
+ contract: "svml.caption-track-program@1",
+ id: value.id,
+ mode: value.mode,
+ stacking: { ...value.stacking },
+ style: { ...value.style },
+ };
+}
+
+export function computeCaptionTrackProgramDigest(value: Omit<CaptionTrackProgram, "digest">): Digest {
+ return digestOf(normalizedProgram(value));
+}
+
+export function sealCaptionTrackProgram(value: Omit<CaptionTrackProgram, "digest">): CaptionTrackProgram {
+ const content = normalizedProgram(value);
+ return { ...content, digest: digestOf(content) };
+}
+
+export function defaultCaptionTrackProgram(id = "captions"): CaptionTrackProgram {
+ return sealCaptionTrackProgram({
+ contract: "svml.caption-track-program@1",
+ id,
+ mode: "whole",
+ stacking: { order: 100, tieBreak: id },
+ style: {
+ fontFamily: "Inter, sans-serif",
+ fontSizePx: 72,
+ fontWeight: 700,
+ color: "#ffffff",
+ backgroundColor: "#000000cc",
+ paddingXPx: 24,
+ paddingYPx: 12,
+ borderRadiusPx: 16,
+ bottomPercent: 10,
+ maxWidthPercent: 88,
+ textAlign: "center",
+ },
+ });
+}
+
+export function assertCaptionTrackProgram(program: CaptionTrackProgram): void {
+ if (program.contract !== "svml.caption-track-program@1") throw new Error("Unsupported CaptionTrackProgram contract.");
+ const { digest: _digest, ...content } = program;
+ if (!isDigest(program.digest) || program.digest !== computeCaptionTrackProgramDigest(content)) {
+ throw new Error("CaptionTrackProgram digest does not match its contents.");
+ }
+ if (!program.id || !program.stacking.tieBreak || !program.style.fontFamily) {
+ throw new Error("CaptionTrackProgram identity and font family must not be empty.");
+ }
+ if (!Number.isSafeInteger(program.stacking.order) || program.stacking.order < 0) {
+ throw new Error("CaptionTrackProgram stacking order is invalid.");
+ }
+ const numeric: Readonly<Record<string, number>> = {
+ fontSizePx: program.style.fontSizePx,
+ fontWeight: program.style.fontWeight,
+ paddingXPx: program.style.paddingXPx,
+ paddingYPx: program.style.paddingYPx,
+ borderRadiusPx: program.style.borderRadiusPx,
+ bottomPercent: program.style.bottomPercent,
+ maxWidthPercent: program.style.maxWidthPercent,
+ };
+ for (const [name, value] of Object.entries(numeric)) {
+ if (!Number.isFinite(value) || value < 0) throw new Error(`CaptionTrackProgram ${name} is invalid.`);
+ }
+ if (program.style.fontSizePx <= 0 || program.style.maxWidthPercent <= 0 || program.style.maxWidthPercent > 100) {
+ throw new Error("CaptionTrackProgram text size or width is invalid.");
+ }
+ if (program.style.bottomPercent > 100) throw new Error("CaptionTrackProgram bottomPercent is invalid.");
+ for (const color of [program.style.color, program.style.backgroundColor].filter((value): value is string => value !== undefined)) {
+ if (!/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/u.test(color)) throw new Error(`CaptionTrackProgram color ${color} is invalid.`);
+ }
+}
+
+function assertProjection(projection: TimedCaptionProjection): void {
+ if (projection.contract !== "svml.timed-caption-projection@1") {
+ throw new Error("Unsupported TimedCaptionProjection contract.");
+ }
+ assertProgramSpaceIdentity(projection.programSpace);
+ const { projectionDigest: _digest, ...content } = projection;
+ if (!isDigest(projection.projectionDigest) || projection.projectionDigest !== digestOf(content)) {
+ throw new Error("TimedCaptionProjection digest does not match its contents.");
+ }
+}
+
+function frameAt(projection: TimedCaptionProjection, seconds: number): number {
+ return Math.round(seconds
+ * projection.programSpace.frameRate.numerator
+ / projection.programSpace.frameRate.denominator);
+}
+
+function textStyle(program: CaptionTrackProgram): VisualStyleDeclaration[] {
+ return [
+ { name: "background", value: program.style.backgroundColor ?? "transparent" },
+ { name: "border-radius", value: `${program.style.borderRadiusPx}px` },
+ { name: "color", value: program.style.color },
+ { name: "font-family", value: program.style.fontFamily },
+ { name: "font-size", value: `${program.style.fontSizePx}px` },
+ { name: "font-weight", value: program.style.fontWeight },
+ { name: "padding", value: `${program.style.paddingYPx}px ${program.style.paddingXPx}px` },
+ { name: "text-align", value: program.style.textAlign },
+ { name: "white-space", value: "pre-wrap" },
+ ];
+}
+
+export function renderCaptionTrack(
+ projection: TimedCaptionProjection,
+ program: CaptionTrackProgram,
+): VisualTrack {
+ assertProjection(projection);
+ assertCaptionTrackProgram(program);
+ const totalFrames = programSpaceFrameCount(projection.programSpace);
+ const plan = planCaptionPresentation(projection, program.mode);
+ const track = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: program.id,
+ programSpaceDigest: projection.programSpace.digest,
+ sources: [
+ { name: "program", digest: program.digest },
+ { name: "projection", digest: projection.projectionDigest },
+ ],
+ presents: plan.units.flatMap((unit) => {
+ const startFrame = Math.max(0, frameAt(projection, unit.startSec));
+ const measuredEnd = Math.min(totalFrames, frameAt(projection, unit.endSec));
+ const endFrameExclusive = Math.min(totalFrames, Math.max(startFrame + 1, measuredEnd));
+ if (!unit.display || startFrame >= totalFrames || endFrameExclusive <= startFrame) return [];
+ return [{
+ id: unit.id,
+ span: { startFrame, endFrameExclusive },
+ stacking: { order: program.stacking.order, tieBreak: `${program.stacking.tieBreak}:${unit.id}` },
+ elements: [
+ {
+ id: "root",
+ order: 0,
+ kind: "box" as const,
+ style: [
+ { name: "align-items", value: "center" },
+ { name: "bottom", value: `${program.style.bottomPercent}%` },
+ { name: "display", value: "flex" },
+ { name: "justify-content", value: "center" },
+ { name: "left", value: "50%" },
+ { name: "max-width", value: `${program.style.maxWidthPercent}%` },
+ { name: "position", value: "absolute" },
+ { name: "transform", value: "translateX(-50%)" },
+ ],
+ },
+ {
+ id: "text",
+ parent: "root",
+ order: 1,
+ kind: "text" as const,
+ text: unit.display,
+ style: textStyle(program),
+ attributes: [
+ { name: "data-caption-basis", value: unit.basis },
+ { name: "data-caption-quality", value: unit.timingQuality },
+ ],
+ },
+ ],
+ }];
+ }),
+ });
+ assertVisualTrackIdentity(track, projection.programSpace);
+ return track;
+}
diff --git a/packages/caption/src/types.ts b/packages/caption/src/types.ts
index 1c24b64e..c167ccc3 100644
--- a/packages/caption/src/types.ts
+++ b/packages/caption/src/types.ts
@@ -1,8 +1,85 @@
-export type {
- CaptionPresentationMode,
- CaptionPresentationPlan,
- CaptionPresentationUnit,
- TimedCaptionProjection,
- TimedCaptionRefinement,
- TimedCaptionRegion,
-} from "@svml/contracts";
+import type { ProgramSpace, TimingQuality } from "@svml/contracts";
+import type { Digest } from "@svml/protocol";
+
+export type TimedCaptionRefinement = {
+ readonly id: string;
+ readonly display: string;
+ readonly displayStart: number;
+ readonly displayEnd: number;
+ readonly sourceTokenIds: readonly string[];
+ readonly startSec: number;
+ readonly endSec: number;
+ readonly startQuality: TimingQuality;
+ readonly endQuality: TimingQuality;
+ readonly relation: "exact";
+};
+
+export type TimedCaptionRegion = {
+ readonly id: string;
+ readonly display: string;
+ readonly segmentId: string;
+ readonly kind: "identity" | "alias" | "hidden";
+ readonly sourceTokenIds: readonly string[];
+ readonly startSec: number;
+ readonly endSec: number;
+ readonly startQuality: TimingQuality;
+ readonly endQuality: TimingQuality;
+ readonly refinements: readonly TimedCaptionRefinement[];
+};
+
+export type TimedCaptionProjection = {
+ readonly contract: "svml.timed-caption-projection@1";
+ readonly semanticIndexDigest: Digest;
+ readonly speechTimeMapDigest: Digest;
+ readonly programSpace: ProgramSpace;
+ readonly text: string;
+ readonly regions: readonly TimedCaptionRegion[];
+ readonly projectionDigest: Digest;
+};
+
+export type CaptionPresentationMode = "whole" | "proportional-word" | "character-flow";
+
+export type CaptionPresentationUnit = {
+ readonly id: string;
+ readonly regionId: string;
+ readonly display: string;
+ readonly displayStart: number;
+ readonly displayEnd: number;
+ readonly startSec: number;
+ readonly endSec: number;
+ readonly basis: "region-envelope" | "exact-correspondence" | "presentation-estimate";
+ readonly timingQuality: TimingQuality;
+};
+
+export type CaptionPresentationPlan = {
+ readonly contract: "svml.caption-presentation-plan@0";
+ readonly sourceProjectionDigest: Digest;
+ readonly mode: CaptionPresentationMode;
+ readonly units: readonly CaptionPresentationUnit[];
+ readonly planDigest: Digest;
+};
+
+/** Official caption package's author-facing lowering program, not a Core type. */
+export type CaptionTrackProgram = {
+ readonly contract: "svml.caption-track-program@1";
+ readonly digest: Digest;
+ readonly id: string;
+ readonly mode: CaptionPresentationMode;
+ readonly stacking: {
+ readonly order: number;
+ readonly tieBreak: string;
+ };
+ readonly style: {
+ readonly fontFamily: string;
+ readonly fontSizePx: number;
+ readonly fontWeight: number;
+ readonly color: string;
+ readonly backgroundColor?: string;
+ readonly paddingXPx: number;
+ readonly paddingYPx: number;
+ readonly borderRadiusPx: number;
+ readonly bottomPercent: number;
+ readonly maxWidthPercent: number;
+ readonly textAlign: "left" | "center" | "right";
+ };
+};
diff --git a/packages/caption/test/caption.test.ts b/packages/caption/test/caption.test.ts
index abc97f9f..35929bfc 100644
--- a/packages/caption/test/caption.test.ts
+++ b/packages/caption/test/caption.test.ts
@@ -1,14 +1,20 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { planCaptionPresentation, temporalizeCaption } from "@svml/caption";
+import {
+ defaultCaptionTrackProgram,
+ planCaptionPresentation,
+ renderCaptionTrack,
+ sealCaptionTrackProgram,
+ temporalizeCaption,
+} from "@svml/caption";
import {
sealAlignedTranscriptEvidence,
sealProgramSpace,
sealSpeechBasis,
} from "@svml/contracts";
import type { AlignedTranscriptSegment, Narrative, SpeechAudioBasis } from "@svml/contracts";
-import { digestOf } from "@svml/core";
+import { digestOf } from "@svml/protocol";
import { parseScript } from "@svml/script";
import { locateSpeechTiming } from "@svml/speech-align";
@@ -127,3 +133,55 @@ test("hidden speech owns time but emits no visible presentation unit", () => {
assert.deepEqual([hidden?.startSec, hidden?.endSec], [0.3, 0.4]);
assert.equal(planCaptionPresentation(timed).units.some((unit) => unit.regionId === hidden?.id), false);
});
+
+test("official caption styling lowers to an ordinary self-contained VisualTrack", () => {
+ const narrative = parseScript("track.svml", "<line>Hello world.</line>");
+ const map = locate(narrative, 1, [{
+ sourceSegmentId: "line",
+ startSec: 0,
+ endSec: 1,
+ words: [
+ { text: "Hello", startSec: 0.1, endSec: 0.35 },
+ { text: "world", startSec: 0.4, endSec: 0.75 },
+ ],
+ chars: [],
+ }]);
+ const projection = temporalizeCaption(narrative, map);
+ const program = defaultCaptionTrackProgram("primary-caption");
+ const track = renderCaptionTrack(projection, program);
+
+ assert.equal(track.contract, "svml.visual-track@1");
+ assert.equal(track.programSpaceDigest, map.programSpace.digest);
+ assert.deepEqual(track.sources.map((source) => source.name), ["program", "projection"]);
+ assert.equal(track.presents[0]?.elements.some((element) => element.kind === "text"), true);
+ assert.equal(
+ track.presents.flatMap((present) => present.elements).some((element) => "text" in element && element.text.includes("Hello")),
+ true,
+ );
+});
+
+test("two caption styles become two peer Tracks without mutating one another", () => {
+ const narrative = parseScript("two-tracks.svml", "<line>Hello world.</line>");
+ const projection = temporalizeCaption(narrative, locate(narrative, 1, [{
+ sourceSegmentId: "line",
+ startSec: 0,
+ endSec: 1,
+ words: [{ text: "Hello", startSec: 0.1, endSec: 0.35 }, { text: "world", startSec: 0.4, endSec: 0.75 }],
+ chars: [],
+ }]));
+ const first = defaultCaptionTrackProgram("speaker-a");
+ const second = sealCaptionTrackProgram({
+ ...first,
+ id: "speaker-b",
+ stacking: { order: 101, tieBreak: "speaker-b" },
+ style: { ...first.style, color: "#00ff00", bottomPercent: 20 },
+ });
+ const firstTrack = renderCaptionTrack(projection, first);
+ const secondTrack = renderCaptionTrack(projection, second);
+
+ assert.notEqual(firstTrack.digest, secondTrack.digest);
+ assert.equal(firstTrack.sources.find((source) => source.name === "projection")?.digest, projection.projectionDigest);
+ assert.equal(secondTrack.sources.find((source) => source.name === "projection")?.digest, projection.projectionDigest);
+ assert.equal(firstTrack.presents[0]?.stacking.order, 100);
+ assert.equal(secondTrack.presents[0]?.stacking.order, 101);
+});
diff --git a/packages/cli/README.md b/packages/cli/README.md
new file mode 100644
index 00000000..25410714
--- /dev/null
+++ b/packages/cli/README.md
@@ -0,0 +1,30 @@
+# `@svml/cli`
+
+Official v2 command-line assembly.
+
+Unlike `@svml/compiler-node`, this application is allowed to choose a trusted default prelude. The
+current prelude registers:
+
+- the official Text Frontend;
+- the Script raw Surface and its audiovisual Narrative contract dependency;
+- the SVS alternate Frontend and generic Recipe manifest;
+- the official Film and HyperFrames Render Structured Surfaces plus their exact static dependencies.
+
+It does not place these packages in Core and does not grant source imports network, credential or
+process permissions.
+
+From the repository:
+
+```bash
+pnpm svml:v2 check path/to/main.svml
+pnpm svml:v2 plan path/to/main.svml --target component.result
+```
+
+`check` is usable for the implemented Script, Film, Render and recursively imported `.svs` sources.
+`plan` is fully implemented by the generic Node compiler. A complete author video still awaits the
+generation, Speech and Track Surfaces that produce Film's inputs; the CLI does not fabricate those
+missing facts.
+
+Automatic installation/loading of arbitrary community packages is deliberately absent. The first
+CLI runs only trusted official code; a future lock-aware loader and isolated Worker must extend the
+Host without changing Core or the Source Closure ABI.
diff --git a/packages/cli/package.json b/packages/cli/package.json
new file mode 100644
index 00000000..5a3a820f
--- /dev/null
+++ b/packages/cli/package.json
@@ -0,0 +1,20 @@
+{
+ "name": "@svml/cli",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "dependencies": {
+ "@svml/compiler-node": "workspace:*",
+ "@svml/contracts": "workspace:*",
+ "@svml/elaborator": "workspace:*",
+ "@svml/film": "workspace:*",
+ "@svml/hyperframes": "workspace:*",
+ "@svml/hyperframes-render": "workspace:*",
+ "@svml/script": "workspace:*",
+ "@svml/svs": "workspace:*",
+ "@svml/text": "workspace:*"
+ }
+}
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
new file mode 100644
index 00000000..78f63156
--- /dev/null
+++ b/packages/cli/src/cli.ts
@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runCli } from "./main.js";
+
+runCli(process.argv.slice(2), { write: (text) => process.stdout.write(text) }).catch((error: unknown) => {
+ const message = error instanceof Error ? error.message : String(error);
+ process.stderr.write(`${message}\n`);
+ process.exitCode = 1;
+});
diff --git a/packages/cli/src/host.ts b/packages/cli/src/host.ts
new file mode 100644
index 00000000..8808fe59
--- /dev/null
+++ b/packages/cli/src/host.ts
@@ -0,0 +1,100 @@
+import {
+ ModulePackageRegistry,
+ NodeCompiler,
+ NodeCompilerError,
+} from "@svml/compiler-node";
+import { videoContractManifests } from "@svml/contracts";
+import { AuthorFrontendRegistry } from "@svml/elaborator";
+import {
+ decodeFilmSurface,
+ filmManifest,
+ filmModuleRef,
+ filmSurfaceImplementationDigest,
+} from "@svml/film";
+import { hyperframesManifest } from "@svml/hyperframes";
+import {
+ decodeHyperframesRenderSurface,
+ hyperframesRenderManifest,
+ hyperframesRenderModuleRef,
+ hyperframesRenderSurfaceImplementationDigest,
+} from "@svml/hyperframes-render";
+import {
+ decodeScriptSurface,
+ scriptManifest,
+ scriptModuleRef,
+ scriptSurfaceImplementationDigest,
+} from "@svml/script";
+import { svsFrontend, svsManifest } from "@svml/svs";
+import {
+ createTextAuthorFrontend,
+ TextSurfaceRegistry,
+ textAuthorFrontendId,
+} from "@svml/text";
+
+export type OfficialCompilerOptions = {
+ readonly root?: string;
+};
+
+/** The trusted official prelude used by the CLI. Core and Compiler Node know none of these packages. */
+export function createOfficialNodeCompiler(options: OfficialCompilerOptions = {}): NodeCompiler {
+ const modules = new ModulePackageRegistry();
+ for (const manifest of videoContractManifests) modules.register({ manifest });
+ modules.register({
+ manifest: scriptManifest,
+ specifiers: ["@svml/script", "@svml/script@1"],
+ });
+ modules.register({ manifest: svsManifest });
+ modules.register({ manifest: hyperframesManifest });
+ modules.register({
+ manifest: filmManifest,
+ specifiers: ["@svml/film", "@svml/film@1"],
+ });
+ modules.register({
+ manifest: hyperframesRenderManifest,
+ specifiers: ["@svml/hyperframes-render", "@svml/hyperframes-render@1"],
+ });
+
+ const surfaces = new TextSurfaceRegistry();
+ surfaces.registerRaw(
+ scriptModuleRef,
+ "script",
+ scriptSurfaceImplementationDigest,
+ decodeScriptSurface,
+ );
+ surfaces.registerStructured(
+ filmModuleRef,
+ "film",
+ filmSurfaceImplementationDigest,
+ decodeFilmSurface,
+ );
+ surfaces.registerStructured(
+ hyperframesRenderModuleRef,
+ "video",
+ hyperframesRenderSurfaceImplementationDigest,
+ decodeHyperframesRenderSurface,
+ );
+
+ const frontends = new AuthorFrontendRegistry();
+ frontends.register(createTextAuthorFrontend({
+ registry: surfaces,
+ resolveModule(request) {
+ const resolved = modules.resolve(request.from);
+ if (resolved === undefined) {
+ throw new NodeCompilerError(
+ "UNKNOWN_MODULE_IMPORT",
+ `No trusted CLI package satisfies ${request.from}`,
+ request.from,
+ );
+ }
+ return resolved;
+ },
+ }));
+ frontends.register(svsFrontend);
+
+ return new NodeCompiler({
+ modules,
+ frontends,
+ entryFrontend: textAuthorFrontendId,
+ ...(options.root === undefined ? {} : { root: options.root }),
+ });
+}
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
new file mode 100644
index 00000000..924cce86
--- /dev/null
+++ b/packages/cli/src/index.ts
@@ -0,0 +1,3 @@
+export { createOfficialNodeCompiler } from "./host.js";
+export type { OfficialCompilerOptions } from "./host.js";
+export { runCli } from "./main.js";
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
new file mode 100644
index 00000000..01f2808e
--- /dev/null
+++ b/packages/cli/src/main.ts
@@ -0,0 +1,79 @@
+import { resolve } from "node:path";
+
+import { createOfficialNodeCompiler } from "./host.js";
+
+type CliIo = {
+ readonly write: (text: string) => void;
+};
+
+type ParsedArgs = {
+ readonly command: string | undefined;
+ readonly file: string | undefined;
+ readonly root: string | undefined;
+ readonly targets: readonly string[];
+ readonly substitute: boolean;
+};
+
+function parseArgs(argv: readonly string[]): ParsedArgs {
+ const [command, file, ...rest] = argv;
+ const targets: string[] = [];
+ let root: string | undefined;
+ let substitute = false;
+ for (let index = 0; index < rest.length; index += 1) {
+ const item = rest[index];
+ if (item === "--target") {
+ const target = rest[index + 1];
+ if (target === undefined || target.startsWith("--")) throw new Error("--target requires an export name");
+ targets.push(target);
+ index += 1;
+ continue;
+ }
+ if (item === "--root") {
+ const value = rest[index + 1];
+ if (value === undefined || value.startsWith("--")) throw new Error("--root requires a directory");
+ root = resolve(value);
+ index += 1;
+ continue;
+ }
+ if (item === "--accept-substitute") {
+ substitute = true;
+ continue;
+ }
+ throw new Error(`unknown option ${item}`);
+ }
+ return { command, file, root, targets, substitute };
+}
+
+function usage(): string {
+ return [
+ "usage:",
+ " svml-v2 check <file.svml> [--root directory]",
+ " svml-v2 plan <file.svml> --target export [--target export] [--accept-substitute] [--root directory]",
+ ].join("\n");
+}
+
+export async function runCli(argv: readonly string[], io: CliIo): Promise<void> {
+ const args = parseArgs(argv);
+ if (args.file === undefined || (args.command !== "check" && args.command !== "plan")) {
+ throw new Error(usage());
+ }
+ const compiler = createOfficialNodeCompiler({ ...(args.root === undefined ? {} : { root: args.root }) });
+ if (args.command === "check") {
+ const result = await compiler.compileFile(args.file);
+ io.write(`${JSON.stringify({
+ ok: true,
+ sourceClosure: result.closure.id,
+ moduleClosure: result.program.closure.digest,
+ graph: result.elaboration.graph.id,
+ units: result.closure.units.length,
+ modules: result.program.closure.modules.map((item) => `${item.ref.name}@${item.ref.version}`),
+ exports: result.exports.map((item) => ({ name: item.name, type: item.type, kind: item.ref.kind })),
+ }, null, 2)}\n`);
+ return;
+ }
+ const result = await compiler.planFile(args.file, {
+ targets: args.targets,
+ accepts: args.substitute ? "substitute" : "exact",
+ });
+ io.write(`${JSON.stringify(result.plan, null, 2)}\n`);
+}
diff --git a/packages/cli/test/cli.test.ts b/packages/cli/test/cli.test.ts
new file mode 100644
index 00000000..a8dfe1a5
--- /dev/null
+++ b/packages/cli/test/cli.test.ts
@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import { runCli } from "@svml/cli";
+
+test("official v2 CLI checks a real Script source through the Node compiler host", async () => {
+ const root = await mkdtemp(join(tmpdir(), "svml-cli-"));
+ const file = join(root, "main.svml");
+ await writeFile(join(root, "studio.svs"), `<sheet version="1">
+ caption.host {
+ color: #ffffff;
+ font-size: 72;
+ }
+ </sheet>`, "utf8");
+ await writeFile(file, `<svml>
+ <import from="@svml/script@1"/>
+ <import as="studio" from="./studio.svs" using="@svml/svs@1"/>
+ <script id="story">
+ <opening>
+ <ALICE>Meaning becomes the source.
+ </opening>
+ </script>
+ </svml>`, "utf8");
+ let output = "";
+ await runCli(["check", file], { write: (text) => { output += text; } });
+ const result = JSON.parse(output) as {
+ readonly ok: boolean;
+ readonly units: number;
+ readonly modules: readonly string[];
+ readonly exports: readonly { readonly name: string; readonly kind: string }[];
+ };
+ assert.equal(result.ok, true);
+ assert.equal(result.units, 2);
+ assert.deepEqual([...result.modules].sort(), [
+ "@svml/svs@1",
+ ]);
+ assert.deepEqual(result.exports, [{ name: "story", type: {
+ module: { name: "@svml/narrative", version: "0.0.0-dev" },
+ name: "Narrative",
+ }, kind: "record" }]);
+});
+
+test("official v2 CLI closes the explicit HyperFrames render package without loading a Provider", async () => {
+ const root = await mkdtemp(join(tmpdir(), "svml-cli-render-"));
+ const file = join(root, "main.svml");
+ await writeFile(file, `<svml>
+ <import as="render" from="@svml/hyperframes-render@1"/>
+ </svml>`, "utf8");
+ let output = "";
+ await runCli(["check", file], { write: (text) => { output += text; } });
+ const result = JSON.parse(output) as {
+ readonly ok: boolean;
+ readonly modules: readonly string[];
+ readonly exports: readonly unknown[];
+ };
+ assert.equal(result.ok, true);
+ assert.deepEqual([...result.modules].sort(), [
+ ]);
+ assert.deepEqual(result.exports, []);
+});
diff --git a/packages/compiler-node/README.md b/packages/compiler-node/README.md
new file mode 100644
index 00000000..301f3f33
--- /dev/null
+++ b/packages/compiler-node/README.md
@@ -0,0 +1,36 @@
+# `@svml/compiler-node`
+
+Domain-neutral Node.js compiler host for v2.
+
+This package is outside Core. It owns the environmental work required to turn a real file into the
+already implemented compiler IR:
+
+```text
+file + registered Frontends + registered manifests
+ -> discovered Source/Module closure
+ -> typed Source Closure
+ -> Author Module + Graph
+ -> optional BuildPlan for named exports
+```
+
+`ModulePackageRegistry` maps author import spellings to exact, already trusted manifests and closes
+their digest-bound dependencies. It does not install npm packages or execute module code. An
+embedding application must register the manifests and matching Frontend/Surface implementations it
+has chosen to trust.
+
+`NodeSourceHost` is the filesystem authority. It accepts only relative recursive Source imports,
+canonicalizes real paths, confines reads to one declared root, rejects symlink escapes and locks
+each import edge to the first bytes read for the whole compilation. Source paths are diagnostics and
+cache keys; Source Closure semantic identity still depends on content rather than machine location.
+
+`NodeCompiler` runs a discovery pass first because Frontends must be known before source decoding,
+while the exact Module Closure must be known before typed Records can be verified. It then invokes
+the ordinary Elaborator Source Closure implementation. `planFile()` resolves author-facing export
+names to Logical Outputs and asks Core to derive the finite reverse-demand plan.
+
+The package contains no Script, video, Provider, queue, credentials or rendering knowledge. A
+non-video application can use it with only its own manifests, Frontends and Surfaces.
+
+Package installation, lockfile-based third-party code loading and sandbox execution remain Host
+features above this registry; treating an import string as permission to execute npm code would
+violate the trust boundary.
diff --git a/packages/compiler-node/package.json b/packages/compiler-node/package.json
new file mode 100644
index 00000000..d326d346
--- /dev/null
+++ b/packages/compiler-node/package.json
@@ -0,0 +1,18 @@
+{
+ "name": "@svml/compiler-node",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "dependencies": {
+ "@svml/core": "workspace:*",
+ "@svml/elaborator": "workspace:*",
+ "@svml/protocol": "workspace:*",
+ "@svml/validation": "workspace:*"
+ },
+ "devDependencies": {
+ "@svml/text": "workspace:*"
+ }
+}
diff --git a/packages/compiler-node/src/compiler.ts b/packages/compiler-node/src/compiler.ts
new file mode 100644
index 00000000..7f8ed56a
--- /dev/null
+++ b/packages/compiler-node/src/compiler.ts
@@ -0,0 +1,162 @@
+import { dirname, resolve } from "node:path";
+
+import {
+ compileBuild,
+ sealBuildRequest,
+} from "@svml/core";
+import {
+ compileSourceClosure,
+ resolveCompiledSourceExport,
+} from "@svml/elaborator";
+import type {
+ AuthorFrontendRegistryLike,
+ AuthorSourceDiscovery,
+ AuthorSourceUnit,
+ CompiledSourceClosure,
+ AuthorRecordAdmitter,
+} from "@svml/elaborator";
+import type {
+ BuildPlan,
+ CandidateBinding,
+ NeedAcceptance,
+} from "@svml/protocol";
+import {
+ TypeValidatorRegistry,
+ createRecordAdmitter,
+} from "@svml/validation";
+import type { TypeValidatorRegistryLike } from "@svml/validation";
+
+import { NodeCompilerError } from "./error.js";
+import type { ModulePackageRegistryLike } from "./modules.js";
+import { NodeSourceHost } from "./source.js";
+
+type DiscoveredUnit = {
+ readonly source: AuthorSourceUnit;
+ readonly frontend: string;
+ readonly discovery: AuthorSourceDiscovery;
+};
+
+async function discoverClosure(
+ entry: AuthorSourceUnit,
+ frontendId: string,
+ frontends: AuthorFrontendRegistryLike,
+ sources: NodeSourceHost,
+): Promise<readonly DiscoveredUnit[]> {
+ const units = new Map<string, DiscoveredUnit>();
+ const visiting = new Set<string>();
+ const visit = async (source: AuthorSourceUnit, selectedFrontend: string): Promise<void> => {
+ const key = `${source.id}\u0000${selectedFrontend}`;
+ if (units.has(key)) return;
+ if (visiting.has(key)) {
+ throw new NodeCompilerError("SOURCE_IMPORT_CYCLE", `Source imports cycle through ${source.name}`, source.id);
+ }
+ const frontend = frontends.resolve(selectedFrontend);
+ if (frontend === undefined) {
+ throw new NodeCompilerError("UNKNOWN_FRONTEND", `Frontend ${selectedFrontend} is not registered`, selectedFrontend);
+ }
+ visiting.add(key);
+ const discovery = await frontend.discover(source);
+ for (const request of discovery.sources) {
+ await visit(await sources.resolveSource(source, request), request.frontend);
+ }
+ visiting.delete(key);
+ units.set(key, { source, frontend: selectedFrontend, discovery });
+ };
+ await visit(entry, frontendId);
+ return [...units.values()];
+}
+
+export type NodeCompilerOptions = {
+ readonly modules: ModulePackageRegistryLike;
+ readonly frontends: AuthorFrontendRegistryLike;
+ readonly entryFrontend: string;
+ /** Files reachable through source imports must resolve inside this root. Defaults to entry dirname. */
+ readonly root?: string;
+ /** Trusted Type-owner validators used to admit authored Records before linking. */
+ readonly validators?: TypeValidatorRegistryLike;
+ /** Low-level Host hook for a sandboxed or remote admission implementation. */
+ readonly admitRecord?: AuthorRecordAdmitter;
+};
+
+export type PlanFileOptions = {
+ readonly targets: readonly string[];
+ readonly accepts?: NeedAcceptance;
+ readonly bindings?: readonly CandidateBinding[];
+};
+
+export type PlannedSource = {
+ readonly compilation: CompiledSourceClosure;
+ readonly plan: BuildPlan;
+};
+
+/** Domain-neutral Node facade from a real source file to a verified Source Closure or BuildPlan. */
+export class NodeCompiler {
+ readonly #options: NodeCompilerOptions;
+ readonly #admitRecord: AuthorRecordAdmitter;
+
+ constructor(options: NodeCompilerOptions) {
+ if (options.validators !== undefined && options.admitRecord !== undefined) {
+ throw new NodeCompilerError(
+ "AMBIGUOUS_RECORD_ADMISSION",
+ "NodeCompiler accepts validators or a custom Record admitter, not both",
+ );
+ }
+ this.#options = options;
+ this.#admitRecord = options.admitRecord
+ ?? createRecordAdmitter(options.validators ?? new TypeValidatorRegistry());
+ }
+
+ async compileFile(file: string): Promise<CompiledSourceClosure> {
+ const entryPath = resolve(file);
+ const sources = await NodeSourceHost.create(this.#options.root ?? dirname(entryPath));
+ const entry = await sources.load(entryPath);
+ const discovered = await discoverClosure(
+ entry,
+ this.#options.entryFrontend,
+ this.#options.frontends,
+ sources,
+ );
+ const closure = this.#options.modules.createClosure(
+ discovered.flatMap((unit) => unit.discovery.modules),
+ );
+ return await compileSourceClosure({
+ entry,
+ frontend: this.#options.entryFrontend,
+ closure,
+ frontends: this.#options.frontends,
+ resolveSource: sources.resolveSource,
+ admitRecord: this.#admitRecord,
+ });
+ }
+
+ async planFile(file: string, options: PlanFileOptions): Promise<PlannedSource> {
+ if (options.targets.length === 0) {
+ throw new NodeCompilerError("EMPTY_BUILD_TARGETS", "plan requires at least one public source export");
+ }
+ const compilation = await this.compileFile(file);
+ const targets = options.targets.map((name) => {
+ const exported = resolveCompiledSourceExport(compilation, name);
+ if (exported.ref.kind !== "logical-output") {
+ throw new NodeCompilerError(
+ "TARGET_IS_AUTHORED_RECORD",
+ `${name} is an authored Record, not a realizable component output`,
+ name,
+ );
+ }
+ return { output: exported.ref.id, accepts: options.accepts ?? "exact" } as const;
+ });
+ const request = sealBuildRequest({
+ graph: compilation.elaboration.graph.id,
+ targets,
+ bindings: options.bindings ?? [],
+ });
+ return {
+ compilation,
+ plan: compileBuild(
+ compilation.program,
+ compilation.elaboration.graph,
+ request,
+ ),
+ };
+ }
+}
diff --git a/packages/compiler-node/src/error.ts b/packages/compiler-node/src/error.ts
new file mode 100644
index 00000000..66f32602
--- /dev/null
+++ b/packages/compiler-node/src/error.ts
@@ -0,0 +1,11 @@
+export class NodeCompilerError extends Error {
+ readonly code: string;
+ readonly subject: string | undefined;
+
+ constructor(code: string, message: string, subject?: string) {
+ super(message);
+ this.name = "NodeCompilerError";
+ this.code = code;
+ this.subject = subject;
+ }
+}
diff --git a/packages/compiler-node/src/index.ts b/packages/compiler-node/src/index.ts
new file mode 100644
index 00000000..d0fb945c
--- /dev/null
+++ b/packages/compiler-node/src/index.ts
@@ -0,0 +1,15 @@
+export { NodeCompilerError } from "./error.js";
+export {
+ ModulePackageRegistry,
+} from "./modules.js";
+export type {
+ ModulePackageRegistryLike,
+ RegisteredModulePackage,
+} from "./modules.js";
+export { NodeSourceHost } from "./source.js";
+export { NodeCompiler } from "./compiler.js";
+export type {
+ NodeCompilerOptions,
+ PlannedSource,
+ PlanFileOptions,
+} from "./compiler.js";
diff --git a/packages/compiler-node/src/modules.ts b/packages/compiler-node/src/modules.ts
new file mode 100644
index 00000000..299adb37
--- /dev/null
+++ b/packages/compiler-node/src/modules.ts
@@ -0,0 +1,117 @@
+import {
+ computeModuleDigest,
+ createResolvedClosure,
+} from "@svml/core";
+import type {
+ ModuleManifest,
+ ModuleRef,
+ ResolvedModuleClosure,
+} from "@svml/protocol";
+
+import { NodeCompilerError } from "./error.js";
+
+function moduleKey(ref: ModuleRef): string {
+ return `${ref.name}@${ref.version}`;
+}
+
+function manifestRef(manifest: ModuleManifest): ModuleRef {
+ return { name: manifest.name, version: manifest.version };
+}
+
+export type RegisteredModulePackage = {
+ readonly manifest: ModuleManifest;
+ /** Additional author import spellings resolved to this exact manifest. */
+ readonly specifiers?: readonly string[];
+};
+
+export interface ModulePackageRegistryLike {
+ resolve(request: string): ModuleRef | undefined;
+ createClosure(requests: readonly string[]): ResolvedModuleClosure;
+}
+
+/**
+ * Deterministic registry of already trusted/installed module manifests.
+ *
+ * This is intentionally not an npm loader: locating and trusting executable package code belongs
+ * to the embedding Host. The registry only resolves an author import spelling to one immutable
+ * manifest and closes that manifest's declared dependencies.
+ */
+export class ModulePackageRegistry implements ModulePackageRegistryLike {
+ readonly #manifests = new Map<string, ModuleManifest>();
+ readonly #specifiers = new Map<string, string>();
+
+ register(value: RegisteredModulePackage): void {
+ const ref = manifestRef(value.manifest);
+ const key = moduleKey(ref);
+ const existing = this.#manifests.get(key);
+ if (existing !== undefined) {
+ throw new NodeCompilerError("DUPLICATE_MODULE_PACKAGE", `Module package ${key} is already registered`, key);
+ }
+ const specifiers = new Set([key, ...(value.specifiers ?? [])]);
+ for (const specifier of specifiers) {
+ if (specifier.length === 0) {
+ throw new NodeCompilerError("EMPTY_MODULE_SPECIFIER", `${key} declares an empty import specifier`, key);
+ }
+ const owner = this.#specifiers.get(specifier);
+ if (owner !== undefined) {
+ throw new NodeCompilerError(
+ "DUPLICATE_MODULE_SPECIFIER",
+ `Import ${specifier} is already bound to ${owner}`,
+ specifier,
+ );
+ }
+ }
+ this.#manifests.set(key, value.manifest);
+ for (const specifier of specifiers) this.#specifiers.set(specifier, key);
+ }
+
+ resolve(request: string): ModuleRef | undefined {
+ const key = this.#specifiers.get(request);
+ const manifest = key === undefined ? undefined : this.#manifests.get(key);
+ return manifest === undefined ? undefined : manifestRef(manifest);
+ }
+
+ createClosure(requests: readonly string[]): ResolvedModuleClosure {
+ const included = new Map<string, ModuleManifest>();
+ const visit = (key: string): void => {
+ if (included.has(key)) return;
+ const manifest = this.#manifests.get(key);
+ if (manifest === undefined) {
+ throw new NodeCompilerError("MISSING_MODULE_DEPENDENCY", `Module dependency ${key} is not registered`, key);
+ }
+ included.set(key, manifest);
+ for (const dependency of manifest.dependencies) {
+ const dependencyKey = moduleKey(dependency.module);
+ const resolved = this.#manifests.get(dependencyKey);
+ if (resolved === undefined) {
+ throw new NodeCompilerError(
+ "MISSING_MODULE_DEPENDENCY",
+ `${key} requires unregistered module ${dependencyKey}`,
+ dependencyKey,
+ );
+ }
+ if (computeModuleDigest(resolved) !== dependency.digest) {
+ throw new NodeCompilerError(
+ "MODULE_DEPENDENCY_DIGEST_MISMATCH",
+ `${key} requires another digest of ${dependencyKey}`,
+ dependencyKey,
+ );
+ }
+ visit(dependencyKey);
+ }
+ };
+
+ for (const request of [...new Set(requests)].sort()) {
+ const key = this.#specifiers.get(request);
+ if (key === undefined) {
+ throw new NodeCompilerError("UNKNOWN_MODULE_IMPORT", `No registered module satisfies ${request}`, request);
+ }
+ visit(key);
+ }
+ return createResolvedClosure(
+ [...included.values()].sort((left, right) =>
+ moduleKey(manifestRef(left)).localeCompare(moduleKey(manifestRef(right))),
+ ),
+ );
+ }
+}
diff --git a/packages/compiler-node/src/source.ts b/packages/compiler-node/src/source.ts
new file mode 100644
index 00000000..b198cf24
--- /dev/null
+++ b/packages/compiler-node/src/source.ts
@@ -0,0 +1,72 @@
+import { readFile, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+
+import type {
+ AuthorSourceImport,
+ AuthorSourceResolver,
+ AuthorSourceUnit,
+} from "@svml/elaborator";
+
+import { NodeCompilerError } from "./error.js";
+
+function isWithin(root: string, path: string): boolean {
+ const relation = relative(root, path);
+ return relation === "" || (!relation.startsWith("..") && !isAbsolute(relation));
+}
+
+/** One-build, read-once filesystem authority for SourceUnits. */
+export class NodeSourceHost {
+ readonly root: string;
+ readonly #cache = new Map<string, AuthorSourceUnit>();
+ readonly #edges = new Map<string, AuthorSourceUnit>();
+
+ private constructor(root: string) {
+ this.root = root;
+ }
+
+ static async create(root: string): Promise<NodeSourceHost> {
+ return new NodeSourceHost(await realpath(resolve(root)));
+ }
+
+ async load(path: string): Promise<AuthorSourceUnit> {
+ const canonical = await realpath(resolve(path));
+ if (!isWithin(this.root, canonical)) {
+ throw new NodeCompilerError(
+ "SOURCE_OUTSIDE_ROOT",
+ `Source ${canonical} is outside compiler root ${this.root}`,
+ canonical,
+ );
+ }
+ const cached = this.#cache.get(canonical);
+ if (cached !== undefined) return cached;
+ const unit: AuthorSourceUnit = {
+ id: canonical,
+ name: relative(this.root, canonical) || canonical.split("/").at(-1) || canonical,
+ text: await readFile(canonical, "utf8"),
+ };
+ this.#cache.set(canonical, unit);
+ return unit;
+ }
+
+ readonly resolveSource: AuthorSourceResolver = async (
+ importer: AuthorSourceUnit,
+ request: AuthorSourceImport,
+ ): Promise<AuthorSourceUnit> => {
+ if (!request.from.startsWith("./") && !request.from.startsWith("../")) {
+ throw new NodeCompilerError(
+ "UNSUPPORTED_SOURCE_IMPORT",
+ `Source import ${request.from} must be relative; package imports are module imports`,
+ request.from,
+ );
+ }
+ if (!isWithin(this.root, importer.id)) {
+ throw new NodeCompilerError("UNKNOWN_SOURCE_IMPORTER", `${importer.id} is outside this Source Host`, importer.id);
+ }
+ const edge = `${importer.id}\u0000${request.from}`;
+ const locked = this.#edges.get(edge);
+ if (locked !== undefined) return locked;
+ const loaded = await this.load(resolve(dirname(importer.id), request.from));
+ this.#edges.set(edge, loaded);
+ return loaded;
+ };
+}
diff --git a/packages/compiler-node/test/compiler.test.ts b/packages/compiler-node/test/compiler.test.ts
new file mode 100644
index 00000000..05d20d01
--- /dev/null
+++ b/packages/compiler-node/test/compiler.test.ts
@@ -0,0 +1,221 @@
+import assert from "node:assert/strict";
+import {
+ mkdtemp,
+ mkdir,
+ readFile,
+ symlink,
+ writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import {
+ ModulePackageRegistry,
+ NodeCompiler,
+ NodeCompilerError,
+ NodeSourceHost,
+} from "@svml/compiler-node";
+import {
+ computeModuleDigest,
+ digestOf,
+} from "@svml/core";
+import {
+ AuthorFrontendRegistry,
+ sealGraphFragment,
+} from "@svml/elaborator";
+import type {
+ ModuleManifest,
+ ModuleRef,
+ ProducerRef,
+ TypeRef,
+} from "@svml/protocol";
+import {
+ createTextAuthorFrontend,
+ TextSurfaceRegistry,
+ textAuthorFrontendId,
+} from "@svml/text";
+
+function emptyManifest(name: string, version = "1"): ModuleManifest {
+ return {
+ format: "svml.module@0",
+ name,
+ version,
+ dependencies: [],
+ types: [],
+ capabilities: [],
+ surfaces: [],
+ producers: [],
+ };
+}
+
+test("registered module imports close exact transitive manifest dependencies", () => {
+ const base = emptyManifest("example.base");
+ const feature: ModuleManifest = {
+ ...emptyManifest("example.feature"),
+ dependencies: [{
+ module: { name: base.name, version: base.version },
+ digest: computeModuleDigest(base),
+ }],
+ };
+ const modules = new ModulePackageRegistry();
+ modules.register({ manifest: base });
+ modules.register({ manifest: feature, specifiers: ["example.feature@stable"] });
+
+ assert.deepEqual(modules.resolve("example.feature@stable"), { name: feature.name, version: feature.version });
+ assert.deepEqual(
+ modules.createClosure(["example.feature@stable"]).modules.map((item) => item.ref.name).sort(),
+ ["example.base", "example.feature"],
+ );
+});
+
+test("module registration is atomic and dependency digests cannot drift", () => {
+ const first = emptyManifest("example.first");
+ const second = emptyManifest("example.second");
+ const modules = new ModulePackageRegistry();
+ modules.register({ manifest: first, specifiers: ["example.shared@1"] });
+ assert.throws(
+ () => modules.register({ manifest: second, specifiers: ["example.shared@1"] }),
+ (error: unknown) => error instanceof NodeCompilerError && error.code === "DUPLICATE_MODULE_SPECIFIER",
+ );
+ assert.equal(modules.resolve("example.second@1"), undefined);
+
+ const wrongDependency: ModuleManifest = {
+ ...emptyManifest("example.wrong"),
+ dependencies: [{
+ module: { name: first.name, version: first.version },
+ digest: digestOf("another implementation"),
+ }],
+ };
+ modules.register({ manifest: wrongDependency });
+ assert.throws(
+ () => modules.createClosure(["example.wrong@1"]),
+ (error: unknown) => error instanceof NodeCompilerError
+ && error.code === "MODULE_DEPENDENCY_DIGEST_MISMATCH",
+ );
+});
+
+const laboratory = { name: "example.compiler-lab", version: "1" } as const;
+const resultType = { module: laboratory, name: "Result" } satisfies TypeRef;
+const producer = { module: laboratory, name: "produce" } satisfies ProducerRef;
+const surfaceDigest = digestOf("example.compiler-lab/surface@1");
+const laboratoryManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: laboratory.name,
+ version: laboratory.version,
+ dependencies: [],
+ types: [{ name: resultType.name, schema: { kind: "string", minLength: 1 } }],
+ capabilities: [],
+ surfaces: [{
+ name: "result",
+ tag: "Result",
+ mode: "structured",
+ outputs: [],
+ implementation: {
+ kind: "trusted-frontend-surface",
+ locator: "example.compiler-lab/surface",
+ digest: surfaceDigest,
+ },
+ }],
+ producers: [{
+ name: producer.name,
+ inputs: [],
+ outputs: [{ name: "result", type: resultType }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.compiler-lab/produce",
+ digest: digestOf("example.compiler-lab/produce@1"),
+ },
+ }],
+};
+const fragment = sealGraphFragment({
+ name: "example.compiler-lab/result@1",
+ inputs: [],
+ operations: [{
+ id: "produce",
+ producer,
+ inputs: {},
+ result: { kind: "output", name: "result" },
+ }],
+ exports: [{
+ name: "result",
+ type: resultType,
+ root: { kind: "fragment-operation", operation: "produce" },
+ semanticInputs: [],
+ fidelity: "exact",
+ }],
+});
+
+function compiler(root: string): NodeCompiler {
+ const modules = new ModulePackageRegistry();
+ modules.register({ manifest: laboratoryManifest });
+ const surfaces = new TextSurfaceRegistry();
+ surfaces.registerStructured(laboratory, "result", surfaceDigest, ({ element }) => {
+ const id = element.attributes.id;
+ if (typeof id !== "string") throw new Error("Result id is required");
+ return {
+ records: [],
+ components: [{
+ id,
+ fragment: fragment.id,
+ inputs: {},
+ outputs: { result: `${id}.result` },
+ range: element.range,
+ }],
+ fragments: [fragment],
+ };
+ });
+ const frontends = new AuthorFrontendRegistry();
+ frontends.register(createTextAuthorFrontend({
+ registry: surfaces,
+ resolveModule(request): ModuleRef {
+ const resolved = modules.resolve(request.from);
+ if (resolved === undefined) throw new Error(`unknown module ${request.from}`);
+ return resolved;
+ },
+ }));
+ return new NodeCompiler({ modules, frontends, entryFrontend: textAuthorFrontendId, root });
+}
+
+test("Node Compiler discovers real imports and plans a named public export", async () => {
+ const root = await mkdtemp(join(tmpdir(), "svml-compiler-node-"));
+ const file = join(root, "main.svml");
+ await writeFile(file, `<svml>
+ <import as="lab" from="example.compiler-lab@1"/>
+ <lab:Result id="hello"/>
+ </svml>`, "utf8");
+
+ const compiled = await compiler(root).compileFile(file);
+ assert.equal(compiled.exports[0]?.name, "hello.result");
+ assert.equal(compiled.elaboration.graph.outputs.length, 1);
+
+ const planned = await compiler(root).planFile(file, { targets: ["hello.result"] });
+ assert.equal(planned.plan.steps.length, 1);
+ assert.equal(planned.plan.steps[0]?.producer.name, "produce");
+ assert.equal(planned.plan.goals.length, 1);
+});
+
+test("Node Source Host contains symlinks and reads each canonical source only once", async () => {
+ const parent = await mkdtemp(join(tmpdir(), "svml-source-host-"));
+ const root = join(parent, "project");
+ await mkdir(root);
+ const entryPath = join(root, "main.svml");
+ const outsidePath = join(parent, "outside.svs");
+ await writeFile(entryPath, "first", "utf8");
+ await writeFile(outsidePath, "outside", "utf8");
+ await symlink(outsidePath, join(root, "escaped.svs"));
+ const host = await NodeSourceHost.create(root);
+ const entry = await host.load(entryPath);
+ await writeFile(entryPath, "second", "utf8");
+ assert.equal((await host.load(entryPath)).text, "first");
+ assert.equal(await readFile(entryPath, "utf8"), "second");
+ await assert.rejects(
+ async () => await host.resolveSource(entry, {
+ from: "./escaped.svs",
+ alias: "escaped",
+ frontend: "example.frontend@1",
+ }),
+ (error: unknown) => error instanceof NodeCompilerError && error.code === "SOURCE_OUTSIDE_ROOT",
+ );
+});
diff --git a/packages/contracts/README.md b/packages/contracts/README.md
index 8d4e5bdb..c1aeb443 100644
--- a/packages/contracts/README.md
+++ b/packages/contracts/README.md
@@ -1,5 +1,30 @@
-# @svml/contracts
+# `@svml/contracts` physical video distribution
-Provider- and Frontend-neutral narrow-waist contracts for the official speech program. This
-package contains data contracts and static schemas only. It does not parse SVML, execute external
-services, align speech or render tracks.
+This transitional physical workspace package delivers six independently identified logical modules:
+
+- `@svml/narrative`;
+- `@svml/media`;
+- `@svml/program-space`;
+- `@svml/speech`;
+- `@svml/semantic-time`;
+- `@svml/composition`.
+
+Each has its own Manifest and digest. The physical package name is not a public nominal Type owner
+and may later become `@svml/video` without changing those logical identities. The distribution
+contains Provider- and Frontend-neutral data contracts, identity validators and static schemas
+only. It does not parse SVML, execute external services, align speech or render Tracks.
+
+`VisualTrack`, `AudioTrack` and `Composition` implement the flat composition law in
+[`../../spec/track-composition-v1.md`](../../spec/track-composition-v1.md). Caption, Speech and
+B-roll are upstream package concerns; the final Composition contract contains no family field.
+`VisualTrack` is an ownership/provenance aggregate, while each `VisualPresent` owns its own frame
+span and absolute z so Presents from different Tracks may interleave without cross-Track access.
+
+Two renderer-neutral terminal dependencies close otherwise leaky rendering assumptions:
+
+- `FontArtifactRef` binds an exact font face, weight and style to content-addressed bytes;
+- `CompositableSurfaceRef` binds a materialized visual's dimensions, sRGB color space, alpha mode
+ and still/frame timing to content-addressed bytes.
+
+These are public protocols, not author components and not Provider APIs. Text, Caption or any
+future visual component may emit them without registering its family with Core.
diff --git a/packages/contracts/src/caption.ts b/packages/contracts/src/caption.ts
deleted file mode 100644
index 88f78013..00000000
--- a/packages/contracts/src/caption.ts
+++ /dev/null
@@ -1,59 +0,0 @@
-import type { TimingQuality } from "./speech.js";
-import type { Digest } from "@svml/protocol";
-
-export type TimedCaptionRefinement = {
- readonly id: string;
- readonly display: string;
- readonly displayStart: number;
- readonly displayEnd: number;
- readonly sourceTokenIds: readonly string[];
- readonly startSec: number;
- readonly endSec: number;
- readonly startQuality: TimingQuality;
- readonly endQuality: TimingQuality;
- readonly relation: "exact";
-};
-
-export type TimedCaptionRegion = {
- readonly id: string;
- readonly display: string;
- readonly segmentId: string;
- readonly kind: "identity" | "alias" | "hidden";
- readonly sourceTokenIds: readonly string[];
- readonly startSec: number;
- readonly endSec: number;
- readonly startQuality: TimingQuality;
- readonly endQuality: TimingQuality;
- readonly refinements: readonly TimedCaptionRefinement[];
-};
-
-export type TimedCaptionProjection = {
- readonly contract: "svml.timed-caption-projection@1";
- readonly semanticIndexDigest: Digest;
- readonly speechTimeMapDigest: Digest;
- readonly text: string;
- readonly regions: readonly TimedCaptionRegion[];
- readonly projectionDigest: Digest;
-};
-
-export type CaptionPresentationMode = "whole" | "proportional-word" | "character-flow";
-
-export type CaptionPresentationUnit = {
- readonly id: string;
- readonly regionId: string;
- readonly display: string;
- readonly displayStart: number;
- readonly displayEnd: number;
- readonly startSec: number;
- readonly endSec: number;
- readonly basis: "region-envelope" | "exact-correspondence" | "presentation-estimate";
- readonly timingQuality: TimingQuality;
-};
-
-export type CaptionPresentationPlan = {
- readonly contract: "svml.caption-presentation-plan@0";
- readonly sourceProjectionDigest: Digest;
- readonly mode: CaptionPresentationMode;
- readonly units: readonly CaptionPresentationUnit[];
- readonly planDigest: Digest;
-};
diff --git a/packages/contracts/src/identity.ts b/packages/contracts/src/identity.ts
index 1c0dea44..28ce9a1a 100644
--- a/packages/contracts/src/identity.ts
+++ b/packages/contracts/src/identity.ts
@@ -26,6 +26,37 @@ export function sealProgramSpace(value: Omit<ProgramSpace, "digest">): ProgramSp
return { ...value, digest: computeProgramSpaceDigest(value) };
}
+export function programSpaceFrameCount(programSpace: ProgramSpace): number {
+ const frames = programSpace.durationSec
+ * programSpace.frameRate.numerator
+ / programSpace.frameRate.denominator;
+ const rounded = Math.round(frames);
+ if (!Number.isSafeInteger(rounded) || rounded < 1 || Math.abs(frames - rounded) > 1e-7) {
+ throw new Error("ProgramSpace duration must end on an exact frame boundary.");
+ }
+ return rounded;
+}
+
+export function assertProgramSpaceIdentity(programSpace: ProgramSpace): void {
+ if (programSpace.contract !== "svml.program-space@0") throw new Error("Unsupported ProgramSpace contract.");
+ const { digest: _digest, ...content } = programSpace;
+ if (!isDigest(programSpace.digest) || programSpace.digest !== computeProgramSpaceDigest(content)) {
+ throw new Error("ProgramSpace digest does not match its canonical contents.");
+ }
+ const { numerator, denominator } = programSpace.frameRate;
+ if (
+ !Number.isSafeInteger(numerator)
+ || numerator <= 0
+ || !Number.isSafeInteger(denominator)
+ || denominator <= 0
+ || !Number.isFinite(programSpace.durationSec)
+ || programSpace.durationSec <= 0
+ ) {
+ throw new Error("ProgramSpace is invalid.");
+ }
+ programSpaceFrameCount(programSpace);
+}
+
export function sealSpeechBasis(value: Omit<SpeechBasis, "basisDigest">): SpeechBasis {
return { ...value, basisDigest: computeSpeechBasisDigest(value) };
}
@@ -38,26 +69,11 @@ export function sealAlignedTranscriptEvidence(
export function assertSpeechBasisIdentity(basis: SpeechBasis): void {
if (basis.contract !== "svml.speech-basis@1") throw new Error("Unsupported SpeechBasis contract.");
- const { digest: _programDigest, ...programContent } = basis.programSpace;
- if (
- !isDigest(basis.programSpace.digest)
- || basis.programSpace.digest !== computeProgramSpaceDigest(programContent)
- ) {
- throw new Error("ProgramSpace digest does not match its canonical contents.");
- }
+ assertProgramSpaceIdentity(basis.programSpace);
const { basisDigest: _basisDigest, ...basisContent } = basis;
if (!isDigest(basis.basisDigest) || basis.basisDigest !== computeSpeechBasisDigest(basisContent)) {
throw new Error("SpeechBasis digest does not match its canonical contents.");
}
- const { numerator, denominator } = basis.programSpace.frameRate;
- if (
- !Number.isSafeInteger(numerator)
- || numerator <= 0
- || !Number.isSafeInteger(denominator)
- || denominator <= 0
- ) {
- throw new Error("ProgramSpace frame rate must be a positive rational number.");
- }
if (
!Number.isFinite(basis.programSpace.durationSec)
|| basis.programSpace.durationSec <= 0
@@ -82,22 +98,7 @@ export function assertSpeechAudioBasisIdentity(basis: SpeechAudioBasis): void {
if (!isDigest(basis.basisDigest) || !isDigest(basis.narrativeDigest)) {
throw new Error("SpeechAudioBasis identity digest is invalid.");
}
- const { digest: _programDigest, ...programContent } = basis.programSpace;
- if (
- !isDigest(basis.programSpace.digest)
- || basis.programSpace.digest !== computeProgramSpaceDigest(programContent)
- ) {
- throw new Error("ProgramSpace digest does not match its canonical contents.");
- }
- const { numerator, denominator } = basis.programSpace.frameRate;
- if (
- !Number.isSafeInteger(numerator)
- || numerator <= 0
- || !Number.isSafeInteger(denominator)
- || denominator <= 0
- ) {
- throw new Error("ProgramSpace frame rate must be a positive rational number.");
- }
+ assertProgramSpaceIdentity(basis.programSpace);
if (
!Number.isFinite(basis.programSpace.durationSec)
|| basis.programSpace.durationSec <= 0
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
index 783e68ef..5baebf8b 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -1,10 +1,11 @@
-export type * from "./caption.js";
export {
+ assertProgramSpaceIdentity,
assertSpeechAudioBasisIdentity,
assertSpeechBasisIdentity,
computeAlignedTranscriptEvidenceDigest,
computeProgramSpaceDigest,
computeSpeechBasisDigest,
+ programSpaceFrameCount,
sealAlignedTranscriptEvidence,
sealProgramSpace,
sealSpeechBasis,
@@ -13,15 +14,54 @@ export {
alignedTranscriptEvidenceFields,
alignedTranscriptEvidenceSchema,
completeSemanticMapSchema,
- contractsManifest,
- contractsManifestDigest,
- contractsModuleRef,
+ compositionManifest,
+ compositionManifestDigest,
+ compositionModuleRef,
contractTypes,
+ mediaManifest,
+ mediaManifestDigest,
+ mediaModuleRef,
+ narrativeManifest,
+ narrativeManifestDigest,
+ narrativeModuleRef,
+ programSpaceManifest,
+ programSpaceManifestDigest,
+ programSpaceModuleRef,
+ semanticTimeManifest,
+ semanticTimeManifestDigest,
+ semanticTimeModuleRef,
+ speechManifest,
+ speechManifestDigest,
+ speechModuleRef,
+ videoContractDependencies,
+ videoContractManifests,
+ mediaArtifactSchema,
narrativeSchema,
+ programSpaceSchema,
speechAudioBasisSchema,
speechBasisSchema,
- speechVisualTrackSchema,
- timedCaptionProjectionSchema,
+ visualTrackSchema,
+ audioTrackSchema,
+ compositionSchema,
+ compositableSurfaceSchema,
+ fontArtifactSchema,
} from "./manifest.js";
export type * from "./narrative.js";
+export {
+ assertCompositableSurfaceRef,
+ assertFontArtifactRef,
+} from "./render.js";
+export type * from "./render.js";
export type * from "./speech.js";
+export {
+ assertAudioTrackIdentity,
+ assertCompositionIdentity,
+ assertVisualTrackIdentity,
+ computeAudioTrackDigest,
+ computeCompositionDigest,
+ computeVisualTrackDigest,
+ sealAudioTrack,
+ sealComposition,
+ sealVisualTrack,
+} from "./track.js";
+export type * from "./track.js";
diff --git a/packages/contracts/src/manifest.ts b/packages/contracts/src/manifest.ts
index 2058eeb4..b45c12d5 100644
--- a/packages/contracts/src/manifest.ts
+++ b/packages/contracts/src/manifest.ts
@@ -1,21 +1,32 @@
import { digestOf } from "@svml/protocol";
import type { ModuleManifest, TypeRef, ValueSchema } from "@svml/protocol";
-export const contractsModuleRef = { name: "@svml/contracts", version: "0.0.0-dev" } as const;
+export const narrativeModuleRef = { name: "@svml/narrative", version: "0.0.0-dev" } as const;
+export const mediaModuleRef = { name: "@svml/media", version: "0.0.0-dev" } as const;
+export const programSpaceModuleRef = { name: "@svml/program-space", version: "0.0.0-dev" } as const;
+export const speechModuleRef = { name: "@svml/speech", version: "0.0.0-dev" } as const;
+export const semanticTimeModuleRef = { name: "@svml/semantic-time", version: "0.0.0-dev" } as const;
+export const compositionModuleRef = { name: "@svml/composition", version: "0.0.0-dev" } as const;
export const contractTypes = {
- narrative: { module: contractsModuleRef, name: "Narrative" },
- speechBasis: { module: contractsModuleRef, name: "SpeechBasis" },
- speechAudioBasis: { module: contractsModuleRef, name: "SpeechAudioBasis" },
- speechVisualTrack: { module: contractsModuleRef, name: "SpeechVisualTrack" },
- alignedTranscriptEvidence: { module: contractsModuleRef, name: "AlignedTranscriptEvidence" },
- completeSemanticMap: { module: contractsModuleRef, name: "CompleteSemanticMap" },
- timedCaptionProjection: { module: contractsModuleRef, name: "TimedCaptionProjection" },
+ narrative: { module: narrativeModuleRef, name: "Narrative" },
+ mediaArtifact: { module: mediaModuleRef, name: "MediaArtifactRef" },
+ fontArtifact: { module: mediaModuleRef, name: "FontArtifactRef" },
+ compositableSurface: { module: mediaModuleRef, name: "CompositableSurfaceRef" },
+ programSpace: { module: programSpaceModuleRef, name: "ProgramSpace" },
+ speechBasis: { module: speechModuleRef, name: "SpeechBasis" },
+ speechAudioBasis: { module: speechModuleRef, name: "SpeechAudioBasis" },
+ alignedTranscriptEvidence: { module: semanticTimeModuleRef, name: "AlignedTranscriptEvidence" },
+ completeSemanticMap: { module: semanticTimeModuleRef, name: "CompleteSemanticMap" },
+ visualTrack: { module: compositionModuleRef, name: "VisualTrack" },
+ audioTrack: { module: compositionModuleRef, name: "AudioTrack" },
+ composition: { module: compositionModuleRef, name: "Composition" },
} satisfies Record<string, TypeRef>;
const string = { kind: "string", minLength: 1 } as const;
const number = { kind: "number", minimum: 0 } as const;
const integer = { kind: "number", integer: true, minimum: 0 } as const;
+const signedInteger = { kind: "number", integer: true } as const;
const digest = { kind: "string", minLength: 71, maxLength: 71 } as const;
const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>, allowUnknown = false): ValueSchema => ({
kind: "object",
@@ -88,10 +99,42 @@ export const narrativeSchema: ValueSchema = object({
}) },
});
-const artifact = object({
+export const mediaArtifactSchema = object({
digest: { schema: digest }, size: { schema: integer }, mediaType: { schema: string }, durationSec: { schema: number },
});
-const programSpace = object({
+const blobArtifactSchema = (mediaTypes?: readonly string[]): ValueSchema => object({
+ kind: { schema: { kind: "literal", value: "blob" } },
+ digest: { schema: digest },
+ size: { schema: integer },
+ mediaType: { schema: mediaTypes === undefined ? string : { kind: "string", enum: mediaTypes } },
+});
+export const fontArtifactSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.font-artifact@1" } },
+ artifact: { schema: blobArtifactSchema(["font/otf", "font/ttf", "font/woff", "font/woff2"]) },
+ weight: { schema: { kind: "number", integer: true, minimum: 1, maximum: 1_000 } },
+ style: { schema: { kind: "string", enum: ["normal", "italic", "oblique"] } },
+});
+const surfaceTimingSchema: ValueSchema = {
+ kind: "oneOf",
+ variants: [
+ object({ kind: { schema: { kind: "literal", value: "still" } } }),
+ object({
+ kind: { schema: { kind: "literal", value: "frames" } },
+ frameRate: { schema: object({ numerator: { schema: integer }, denominator: { schema: integer } }) },
+ frameCount: { schema: { kind: "number", integer: true, minimum: 1 } },
+ }),
+ ],
+};
+export const compositableSurfaceSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.compositable-surface@1" } },
+ artifact: { schema: blobArtifactSchema() },
+ width: { schema: { kind: "number", integer: true, minimum: 1 } },
+ height: { schema: { kind: "number", integer: true, minimum: 1 } },
+ colorSpace: { schema: { kind: "literal", value: "srgb" } },
+ alphaMode: { schema: { kind: "string", enum: ["opaque", "straight"] } },
+ timing: { schema: surfaceTimingSchema },
+});
+export const programSpaceSchema = object({
contract: { schema: { kind: "literal", value: "svml.program-space@0" } },
digest: { schema: digest }, durationSec: { schema: number },
frameRate: { schema: object({ numerator: { schema: integer }, denominator: { schema: integer } }) },
@@ -104,9 +147,9 @@ const basisSegment = object({
export const speechBasisSchema: ValueSchema = object({
contract: { schema: { kind: "literal", value: "svml.speech-basis@1" } },
basisDigest: { schema: digest }, narrativeDigest: { schema: digest },
- programSpace: { schema: programSpace }, audio: { schema: artifact },
+ programSpace: { schema: programSpaceSchema }, audio: { schema: mediaArtifactSchema },
visualTrack: { schema: object({ clips: { schema: { kind: "array", items: object({
- segmentId: { schema: string }, artifact: { schema: artifact }, startSec: { schema: number }, endSec: { schema: number },
+ segmentId: { schema: string }, artifact: { schema: mediaArtifactSchema }, startSec: { schema: number }, endSec: { schema: number },
}) } } }) },
segments: { schema: { kind: "array", minItems: 1, items: basisSegment } },
});
@@ -114,18 +157,7 @@ export const speechBasisSchema: ValueSchema = object({
export const speechAudioBasisSchema: ValueSchema = object({
contract: { schema: { kind: "literal", value: "svml.speech-audio-basis@1" } },
basisDigest: { schema: digest }, narrativeDigest: { schema: digest },
- programSpace: { schema: programSpace }, audio: { schema: artifact },
- segments: { schema: { kind: "array", minItems: 1, items: basisSegment } },
-});
-
-export const speechVisualTrackSchema: ValueSchema = object({
- contract: { schema: { kind: "literal", value: "svml.speech-visual-track@1" } },
- basisDigest: { schema: digest }, narrativeDigest: { schema: digest },
- programSpace: { schema: programSpace },
- visualTrack: { schema: object({ clips: { schema: { kind: "array", items: object({
- segmentId: { schema: string }, artifact: { schema: artifact },
- startSec: { schema: number }, endSec: { schema: number },
- }) } } }) },
+ programSpace: { schema: programSpaceSchema }, audio: { schema: mediaArtifactSchema },
segments: { schema: { kind: "array", minItems: 1, items: basisSegment } },
});
@@ -179,7 +211,8 @@ const alignmentGroup = object({
export const completeSemanticMapSchema: ValueSchema = object({
contract: { schema: { kind: "literal", value: "svml.complete-semantic-map@1" } },
semanticIndexDigest: { schema: digest }, basisDigest: { schema: digest }, audioArtifactDigest: { schema: digest },
- programSpaceDigest: { schema: digest }, evidenceDigest: { schema: digest }, locatorDigest: { schema: digest },
+ programSpaceDigest: { schema: digest }, programSpace: { schema: programSpaceSchema },
+ evidenceDigest: { schema: digest }, locatorDigest: { schema: digest },
quantizationPolicy: { schema: { kind: "literal", value: "nearest-frame" } }, durationSec: { schema: number },
segments: { schema: { kind: "array", items: timedSegment } },
tokens: { schema: { kind: "array", items: timedToken } },
@@ -187,42 +220,218 @@ export const completeSemanticMapSchema: ValueSchema = object({
groups: { schema: { kind: "array", items: alignmentGroup } }, mapDigest: { schema: digest },
});
-const timedCaptionRefinement = object({
- id: { schema: string }, display: { schema: string }, displayStart: { schema: integer }, displayEnd: { schema: integer },
- sourceTokenIds: { schema: { kind: "array", items: string } }, startSec: { schema: number }, endSec: { schema: number },
- startQuality: { schema: quality }, endQuality: { schema: quality },
- relation: { schema: { kind: "literal", value: "exact" } },
+const styleDeclaration = object({
+ name: { schema: string },
+ value: { schema: { kind: "oneOf", variants: [{ kind: "string" }, { kind: "number" }] } },
});
-const timedCaptionRegion = object({
- id: { schema: string }, display: { schema: { kind: "string" } }, segmentId: { schema: string },
- kind: { schema: { kind: "string", enum: ["identity", "alias", "hidden"] } },
- sourceTokenIds: { schema: { kind: "array", items: string } }, startSec: { schema: number }, endSec: { schema: number },
- startQuality: { schema: quality }, endQuality: { schema: quality },
- refinements: { schema: { kind: "array", items: timedCaptionRefinement } },
+const visualAttribute = object({ name: { schema: string }, value: { schema: { kind: "string" } } });
+const visualKeyframe = object({
+ atFrame: { schema: integer },
+ easing: { schema: { kind: "string", enum: ["linear", "ease-in", "ease-out", "ease-in-out"] }, optional: true },
+ style: { schema: { kind: "array", minItems: 1, items: styleDeclaration } },
});
-export const timedCaptionProjectionSchema: ValueSchema = object({
- contract: { schema: { kind: "literal", value: "svml.timed-caption-projection@1" } },
- semanticIndexDigest: { schema: digest }, speechTimeMapDigest: { schema: digest }, text: { schema: { kind: "string" } },
- regions: { schema: { kind: "array", items: timedCaptionRegion } }, projectionDigest: { schema: digest },
+const visualAnimation = object({
+ keyframes: { schema: { kind: "array", minItems: 2, items: visualKeyframe } },
+});
+const visualBaseFields = {
+ id: { schema: string },
+ parent: { schema: string, optional: true },
+ order: { schema: integer },
+ style: { schema: { kind: "array", items: styleDeclaration } },
+ attributes: { schema: { kind: "array", items: visualAttribute }, optional: true },
+ animation: { schema: visualAnimation, optional: true },
+} as const satisfies Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>;
+const boxElement = object({ ...visualBaseFields, kind: { schema: { kind: "literal", value: "box" } } });
+const textElement = object({
+ ...visualBaseFields,
+ kind: { schema: { kind: "literal", value: "text" } },
+ text: { schema: { kind: "string" } },
+ fonts: { schema: { kind: "array", minItems: 1, items: fontArtifactSchema }, optional: true },
+});
+const mediaElement = (kind: "image" | "video") => object({
+ ...visualBaseFields,
+ kind: { schema: { kind: "literal", value: kind } },
+ artifact: { schema: mediaArtifactSchema },
+ mediaStartSec: { schema: number, optional: true },
+ playbackRate: { schema: number, optional: true },
+ loop: { schema: { kind: "boolean" }, optional: true },
+ muted: { schema: { kind: "boolean" }, optional: true },
+});
+const surfaceElement = object({
+ ...visualBaseFields,
+ kind: { schema: { kind: "literal", value: "surface" } },
+ surface: { schema: compositableSurfaceSchema },
+});
+const visualElement: ValueSchema = {
+ kind: "oneOf",
+ variants: [boxElement, textElement, mediaElement("image"), mediaElement("video"), surfaceElement],
+};
+const frameSpan = object({ startFrame: { schema: integer }, endFrameExclusive: { schema: integer } });
+const visualPresent = object({
+ id: { schema: string },
+ span: { schema: frameSpan },
+ stacking: { schema: object({ order: { schema: signedInteger }, tieBreak: { schema: string } }) },
+ elements: { schema: { kind: "array", minItems: 1, items: visualElement } },
});
+const trackSource = object({ name: { schema: string }, digest: { schema: digest } });
-export const contractsManifest: ModuleManifest = {
+export const visualTrackSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.visual-track@1" } },
+ digest: { schema: digest },
+ id: { schema: string },
+ programSpaceDigest: { schema: digest },
+ sources: { schema: { kind: "array", items: trackSource } },
+ presents: { schema: { kind: "array", items: visualPresent } },
+});
+
+const audioClip = object({
+ id: { schema: string },
+ span: { schema: frameSpan },
+ artifact: { schema: mediaArtifactSchema },
+ mediaStartSec: { schema: number, optional: true },
+ playbackRate: { schema: number, optional: true },
+ gain: { schema: number, optional: true },
+ fadeInSec: { schema: number, optional: true },
+ fadeOutSec: { schema: number, optional: true },
+ bus: { schema: { kind: "string", enum: ["speech", "music", "sfx", "source"] }, optional: true },
+});
+
+export const audioTrackSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.audio-track@1" } },
+ digest: { schema: digest },
+ id: { schema: string },
+ programSpaceDigest: { schema: digest },
+ sources: { schema: { kind: "array", items: trackSource } },
+ clips: { schema: { kind: "array", items: audioClip } },
+});
+
+export const compositionSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.composition@1" } },
+ digest: { schema: digest },
+ id: { schema: string },
+ programSpace: { schema: programSpaceSchema },
+ canvas: { schema: object({
+ width: { schema: integer },
+ height: { schema: integer },
+ clearColor: { schema: string },
+ }) },
+ tracks: { schema: { kind: "array", items: { kind: "oneOf", variants: [visualTrackSchema, audioTrackSchema] } } },
+});
+
+export const narrativeManifest: ModuleManifest = {
format: "svml.module@0",
- name: contractsModuleRef.name,
- version: contractsModuleRef.version,
+ name: narrativeModuleRef.name,
+ version: narrativeModuleRef.version,
+ dependencies: [],
+ types: [{ name: contractTypes.narrative.name, schema: narrativeSchema }],
+ capabilities: [],
+ surfaces: [],
+ producers: [],
+};
+
+export const mediaManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: mediaModuleRef.name,
+ version: mediaModuleRef.version,
dependencies: [],
types: [
- { name: contractTypes.narrative.name, schema: narrativeSchema },
+ { name: contractTypes.mediaArtifact.name, schema: mediaArtifactSchema },
+ { name: contractTypes.fontArtifact.name, schema: fontArtifactSchema },
+ { name: contractTypes.compositableSurface.name, schema: compositableSurfaceSchema },
+ ],
+ capabilities: [],
+ surfaces: [],
+ producers: [],
+};
+
+export const programSpaceManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: programSpaceModuleRef.name,
+ version: programSpaceModuleRef.version,
+ dependencies: [],
+ types: [{ name: contractTypes.programSpace.name, schema: programSpaceSchema }],
+ capabilities: [],
+ surfaces: [],
+ producers: [],
+};
+
+export const narrativeManifestDigest = digestOf(narrativeManifest);
+export const mediaManifestDigest = digestOf(mediaManifest);
+export const programSpaceManifestDigest = digestOf(programSpaceManifest);
+
+export const speechManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: speechModuleRef.name,
+ version: speechModuleRef.version,
+ dependencies: [
+ { module: narrativeModuleRef, digest: narrativeManifestDigest },
+ { module: mediaModuleRef, digest: mediaManifestDigest },
+ { module: programSpaceModuleRef, digest: programSpaceManifestDigest },
+ ],
+ types: [
{ name: contractTypes.speechBasis.name, schema: speechBasisSchema },
{ name: contractTypes.speechAudioBasis.name, schema: speechAudioBasisSchema },
- { name: contractTypes.speechVisualTrack.name, schema: speechVisualTrackSchema },
+ ],
+ capabilities: [],
+ surfaces: [],
+ producers: [],
+};
+
+export const speechManifestDigest = digestOf(speechManifest);
+
+export const semanticTimeManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: semanticTimeModuleRef.name,
+ version: semanticTimeModuleRef.version,
+ dependencies: [
+ { module: narrativeModuleRef, digest: narrativeManifestDigest },
+ { module: speechModuleRef, digest: speechManifestDigest },
+ { module: programSpaceModuleRef, digest: programSpaceManifestDigest },
+ ],
+ types: [
{ name: contractTypes.alignedTranscriptEvidence.name, schema: alignedTranscriptEvidenceSchema },
{ name: contractTypes.completeSemanticMap.name, schema: completeSemanticMapSchema },
- { name: contractTypes.timedCaptionProjection.name, schema: timedCaptionProjectionSchema },
],
capabilities: [],
surfaces: [],
producers: [],
};
-export const contractsManifestDigest = digestOf(contractsManifest);
+export const compositionManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: compositionModuleRef.name,
+ version: compositionModuleRef.version,
+ dependencies: [
+ { module: mediaModuleRef, digest: mediaManifestDigest },
+ { module: programSpaceModuleRef, digest: programSpaceManifestDigest },
+ ],
+ types: [
+ { name: contractTypes.visualTrack.name, schema: visualTrackSchema },
+ { name: contractTypes.audioTrack.name, schema: audioTrackSchema },
+ { name: contractTypes.composition.name, schema: compositionSchema },
+ ],
+ capabilities: [],
+ surfaces: [],
+ producers: [],
+};
+
+export const semanticTimeManifestDigest = digestOf(semanticTimeManifest);
+export const compositionManifestDigest = digestOf(compositionManifest);
+
+export const videoContractManifests = [
+ narrativeManifest,
+ mediaManifest,
+ programSpaceManifest,
+ speechManifest,
+ semanticTimeManifest,
+ compositionManifest,
+] as const;
+
+export const videoContractDependencies = {
+ narrative: { module: narrativeModuleRef, digest: narrativeManifestDigest },
+ media: { module: mediaModuleRef, digest: mediaManifestDigest },
+ programSpace: { module: programSpaceModuleRef, digest: programSpaceManifestDigest },
+ speech: { module: speechModuleRef, digest: speechManifestDigest },
+ semanticTime: { module: semanticTimeModuleRef, digest: semanticTimeManifestDigest },
+ composition: { module: compositionModuleRef, digest: compositionManifestDigest },
+} as const;
diff --git a/packages/contracts/src/render.ts b/packages/contracts/src/render.ts
new file mode 100644
index 00000000..20e4e81d
--- /dev/null
+++ b/packages/contracts/src/render.ts
@@ -0,0 +1,110 @@
+import { isDigest } from "@svml/protocol";
+import type { BlobRef } from "@svml/protocol";
+
+const FONT_MEDIA_TYPES = new Set([
+ "font/otf",
+ "font/ttf",
+ "font/woff",
+ "font/woff2",
+]);
+
+const ALPHA_SURFACE_MEDIA_TYPES = new Set([
+ "image/png",
+ "image/webp",
+ "video/webm",
+]);
+
+export type FontArtifactRef = {
+ readonly contract: "svml.font-artifact@1";
+ readonly artifact: BlobRef;
+ readonly weight: number;
+ readonly style: "normal" | "italic" | "oblique";
+};
+
+export type CompositableSurfaceRef = {
+ readonly contract: "svml.compositable-surface@1";
+ readonly artifact: BlobRef;
+ readonly width: number;
+ readonly height: number;
+ readonly colorSpace: "srgb";
+ readonly alphaMode: "opaque" | "straight";
+ readonly timing:
+ | { readonly kind: "still" }
+ | {
+ readonly kind: "frames";
+ readonly frameRate: {
+ readonly numerator: number;
+ readonly denominator: number;
+ };
+ readonly frameCount: number;
+ };
+};
+
+function assertBlobRef(value: BlobRef, label: string): void {
+ if (
+ value.kind !== "blob"
+ || !isDigest(value.digest)
+ || !Number.isSafeInteger(value.size)
+ || value.size < 0
+ || !value.mediaType
+ ) {
+ throw new Error(`${label} Artifact is invalid.`);
+ }
+}
+
+export function assertFontArtifactRef(value: FontArtifactRef, label = "FontArtifactRef"): void {
+ if (value.contract !== "svml.font-artifact@1") throw new Error(`${label} contract is unsupported.`);
+ assertBlobRef(value.artifact, label);
+ if (!FONT_MEDIA_TYPES.has(value.artifact.mediaType)) {
+ throw new Error(`${label} Artifact must use a supported font media type.`);
+ }
+ if (!Number.isSafeInteger(value.weight) || value.weight < 1 || value.weight > 1_000) {
+ throw new Error(`${label} weight is invalid.`);
+ }
+ if (!["normal", "italic", "oblique"].includes(value.style)) {
+ throw new Error(`${label} style is invalid.`);
+ }
+}
+
+export function assertCompositableSurfaceRef(
+ value: CompositableSurfaceRef,
+ label = "CompositableSurfaceRef",
+): void {
+ if (value.contract !== "svml.compositable-surface@1") throw new Error(`${label} contract is unsupported.`);
+ assertBlobRef(value.artifact, label);
+ if (
+ !Number.isSafeInteger(value.width)
+ || value.width <= 0
+ || !Number.isSafeInteger(value.height)
+ || value.height <= 0
+ ) {
+ throw new Error(`${label} dimensions are invalid.`);
+ }
+ if (value.colorSpace !== "srgb") throw new Error(`${label} colorSpace is unsupported.`);
+ if (value.alphaMode !== "opaque" && value.alphaMode !== "straight") {
+ throw new Error(`${label} alphaMode is unsupported.`);
+ }
+ if (value.alphaMode === "straight" && !ALPHA_SURFACE_MEDIA_TYPES.has(value.artifact.mediaType)) {
+ throw new Error(`${label} straight alpha requires PNG, WebP or WebM media.`);
+ }
+ if (value.timing.kind === "still") {
+ if (!value.artifact.mediaType.startsWith("image/")) {
+ throw new Error(`${label} still timing requires an image Artifact.`);
+ }
+ return;
+ }
+ if (value.timing.kind !== "frames") throw new Error(`${label} timing is unsupported.`);
+ if (!value.artifact.mediaType.startsWith("video/")) {
+ throw new Error(`${label} frame timing requires a video Artifact.`);
+ }
+ if (
+ !Number.isSafeInteger(value.timing.frameRate.numerator)
+ || value.timing.frameRate.numerator <= 0
+ || !Number.isSafeInteger(value.timing.frameRate.denominator)
+ || value.timing.frameRate.denominator <= 0
+ || !Number.isSafeInteger(value.timing.frameCount)
+ || value.timing.frameCount <= 0
+ ) {
+ throw new Error(`${label} frame timing is invalid.`);
+ }
+}
diff --git a/packages/contracts/src/speech.ts b/packages/contracts/src/speech.ts
index 9b98154a..0c0ac022 100644
--- a/packages/contracts/src/speech.ts
+++ b/packages/contracts/src/speech.ts
@@ -54,16 +54,6 @@ export type SpeechAudioBasis = {
readonly segments: readonly SpeechBasisSegment[];
};
-/** Deterministic visual projection of one atomic SpeechBasis/SpeechTake Product. */
-export type SpeechVisualTrack = {
- readonly contract: "svml.speech-visual-track@1";
- readonly basisDigest: Digest;
- readonly narrativeDigest: Digest;
- readonly programSpace: ProgramSpace;
- readonly visualTrack: SpeechBasis["visualTrack"];
- readonly segments: readonly SpeechBasisSegment[];
-};
-
export type SpeechWordEvidence = {
readonly text: string;
readonly startSec?: number;
@@ -155,6 +145,7 @@ export type CompleteSemanticMap = {
readonly basisDigest: Digest;
readonly audioArtifactDigest: Digest;
readonly programSpaceDigest: Digest;
+ readonly programSpace: ProgramSpace;
readonly evidenceDigest: Digest;
readonly locatorDigest: Digest;
readonly quantizationPolicy: "nearest-frame";
diff --git a/packages/contracts/src/track.ts b/packages/contracts/src/track.ts
new file mode 100644
index 00000000..5480977b
--- /dev/null
+++ b/packages/contracts/src/track.ts
@@ -0,0 +1,622 @@
+import { digestOf, isDigest } from "@svml/protocol";
+import type { Digest } from "@svml/protocol";
+
+import { assertProgramSpaceIdentity, programSpaceFrameCount } from "./identity.js";
+import { assertCompositableSurfaceRef, assertFontArtifactRef } from "./render.js";
+import type { CompositableSurfaceRef, FontArtifactRef } from "./render.js";
+import type { MediaArtifactRef, ProgramSpace } from "./speech.js";
+
+export type FrameSpan = {
+ readonly startFrame: number;
+ readonly endFrameExclusive: number;
+};
+
+/** One inline style declaration inside a Present-owned element tree. */
+export type VisualStyleDeclaration = {
+ readonly name: string;
+ readonly value: string | number;
+};
+
+export type VisualAttribute = {
+ readonly name: string;
+ readonly value: string;
+};
+
+export type VisualEasing = "linear" | "ease-in" | "ease-out" | "ease-in-out";
+
+/**
+ * A frame-exact, code-free animation owned by one element. Keyframe offsets
+ * are relative to the containing Present and therefore remain deterministic
+ * under local and hosted rendering.
+ */
+export type VisualKeyframe = {
+ readonly atFrame: number;
+ readonly easing?: VisualEasing;
+ readonly style: readonly VisualStyleDeclaration[];
+};
+
+export type VisualAnimation = {
+ readonly keyframes: readonly VisualKeyframe[];
+};
+
+type VisualElementBase = {
+ readonly id: string;
+ readonly parent?: string;
+ readonly order: number;
+ readonly style: readonly VisualStyleDeclaration[];
+ readonly attributes?: readonly VisualAttribute[];
+ readonly animation?: VisualAnimation;
+};
+
+export type VisualBoxElement = VisualElementBase & {
+ readonly kind: "box";
+};
+
+export type VisualTextElement = VisualElementBase & {
+ readonly kind: "text";
+ readonly text: string;
+ /** Exact ordered fallback faces. Omission remains a candidate-era, environment-bound path. */
+ readonly fonts?: readonly FontArtifactRef[];
+};
+
+export type VisualMediaElement = VisualElementBase & {
+ readonly kind: "image" | "video";
+ readonly artifact: MediaArtifactRef;
+ readonly mediaStartSec?: number;
+ readonly playbackRate?: number;
+ readonly loop?: boolean;
+ readonly muted?: boolean;
+};
+
+/** A package-materialized visual surface with content-bound compositing metadata, not an untyped media guess. */
+export type VisualSurfaceElement = VisualElementBase & {
+ readonly kind: "surface";
+ readonly surface: CompositableSurfaceRef;
+};
+
+/**
+ * Deliberately small, code-free HyperFrames rendering primitives.
+ *
+ * Elements may reference only parents in the same Present. They have no selector,
+ * script, sibling Track id or accumulated-composite input.
+ */
+export type VisualElement = VisualBoxElement | VisualTextElement | VisualMediaElement | VisualSurfaceElement;
+
+export type VisualPresent = {
+ readonly id: string;
+ readonly span: FrameSpan;
+ /** Absolute paint position for this Present, not for its authoring Track. */
+ readonly stacking: {
+ readonly order: number;
+ readonly tieBreak: string;
+ };
+ readonly elements: readonly VisualElement[];
+};
+
+export type TrackSource = {
+ readonly name: string;
+ readonly digest: Digest;
+};
+
+export type VisualTrack = {
+ readonly contract: "svml.visual-track@1";
+ readonly digest: Digest;
+ readonly id: string;
+ readonly programSpaceDigest: Digest;
+ /** Domain-neutral semantic commitments bound by Producer affinity declarations. */
+ readonly sources: readonly TrackSource[];
+ /** Author-owned contributions that Composition may interleave by absolute z. */
+ readonly presents: readonly VisualPresent[];
+};
+
+export type AudioClip = {
+ readonly id: string;
+ readonly span: FrameSpan;
+ readonly artifact: MediaArtifactRef;
+ readonly mediaStartSec?: number;
+ readonly playbackRate?: number;
+ readonly gain?: number;
+ readonly fadeInSec?: number;
+ readonly fadeOutSec?: number;
+ readonly bus?: "speech" | "music" | "sfx" | "source";
+};
+
+export type AudioTrack = {
+ readonly contract: "svml.audio-track@1";
+ readonly digest: Digest;
+ readonly id: string;
+ readonly programSpaceDigest: Digest;
+ readonly sources: readonly TrackSource[];
+ readonly clips: readonly AudioClip[];
+};
+
+export type Track = VisualTrack | AudioTrack;
+
+export type Composition = {
+ readonly contract: "svml.composition@1";
+ readonly digest: Digest;
+ readonly id: string;
+ readonly programSpace: ProgramSpace;
+ readonly canvas: {
+ readonly width: number;
+ readonly height: number;
+ /** Structural clear color beneath every VisualTrack. */
+ readonly clearColor: string;
+ };
+ readonly tracks: readonly Track[];
+};
+
+const FORBIDDEN_CROSS_TRACK_STYLES = new Set([
+ "backdrop-filter",
+ "mix-blend-mode",
+]);
+
+const ANIMATABLE_LOCAL_STYLES = new Set([
+ "clip-path",
+ "filter",
+ "opacity",
+ "transform",
+]);
+
+function assertNonEmpty(value: string, label: string): void {
+ if (!value) throw new Error(`${label} must not be empty.`);
+}
+
+function assertFrameSpan(span: FrameSpan, totalFrames: number, label: string): void {
+ if (
+ !Number.isSafeInteger(span.startFrame)
+ || !Number.isSafeInteger(span.endFrameExclusive)
+ || span.startFrame < 0
+ || span.endFrameExclusive <= span.startFrame
+ || span.endFrameExclusive > totalFrames
+ ) {
+ throw new Error(`${label} is outside ProgramSpace.`);
+ }
+}
+
+function assertArtifact(artifact: MediaArtifactRef, label: string): void {
+ if (
+ !isDigest(artifact.digest)
+ || !Number.isSafeInteger(artifact.size)
+ || artifact.size < 0
+ || !artifact.mediaType
+ || !Number.isFinite(artifact.durationSec)
+ || artifact.durationSec < 0
+ ) {
+ throw new Error(`${label} is invalid.`);
+ }
+}
+
+function assertStyle(style: readonly VisualStyleDeclaration[], label: string): void {
+ const names = new Set<string>();
+ for (const declaration of style) {
+ if (!/^(?:--)?[a-z][a-z0-9-]*$/u.test(declaration.name)) {
+ throw new Error(`${label} contains invalid style name ${declaration.name}.`);
+ }
+ if (names.has(declaration.name)) {
+ throw new Error(`${label} contains duplicate style ${declaration.name}.`);
+ }
+ names.add(declaration.name);
+ if (FORBIDDEN_CROSS_TRACK_STYLES.has(declaration.name)) {
+ throw new Error(`${label} contains cross-Track style ${declaration.name}.`);
+ }
+ if (typeof declaration.value === "string" && /url\s*\(/iu.test(declaration.value)) {
+ throw new Error(`${label} must use typed Artifact references instead of CSS url().`);
+ }
+ if (typeof declaration.value === "string" && /[;{}]/u.test(declaration.value)) {
+ throw new Error(`${label} contains a style value that escapes its declaration.`);
+ }
+ if (typeof declaration.value === "number" && !Number.isFinite(declaration.value)) {
+ throw new Error(`${label} contains a non-finite style value.`);
+ }
+ }
+}
+
+function assertSources(sources: readonly TrackSource[], label: string): void {
+ const names = new Set<string>();
+ for (const source of sources) {
+ assertNonEmpty(source.name, `${label} source name`);
+ if (names.has(source.name)) throw new Error(`${label} contains duplicate source ${source.name}.`);
+ names.add(source.name);
+ if (!isDigest(source.digest)) throw new Error(`${label}.${source.name} source digest is invalid.`);
+ }
+}
+
+function normalizeSources(sources: readonly TrackSource[]): TrackSource[] {
+ return [...sources]
+ .map((source) => ({ name: source.name, digest: source.digest }))
+ .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function assertAttributes(attributes: readonly VisualAttribute[] | undefined, label: string): void {
+ const names = new Set<string>();
+ for (const attribute of attributes ?? []) {
+ if (!/^(?:data-[a-z0-9-]+|aria-[a-z0-9-]+|role|title)$/u.test(attribute.name)) {
+ throw new Error(`${label} contains unsafe attribute ${attribute.name}.`);
+ }
+ if (names.has(attribute.name)) {
+ throw new Error(`${label} contains duplicate attribute ${attribute.name}.`);
+ }
+ names.add(attribute.name);
+ }
+}
+
+function assertAnimation(animation: VisualAnimation | undefined, durationFrames: number, label: string): void {
+ if (animation === undefined) return;
+ if (animation.keyframes.length < 2) throw new Error(`${label} animation must contain at least two keyframes.`);
+ let previous = -1;
+ for (const [index, keyframe] of animation.keyframes.entries()) {
+ if (
+ !Number.isSafeInteger(keyframe.atFrame)
+ || keyframe.atFrame < 0
+ || keyframe.atFrame > durationFrames
+ || keyframe.atFrame <= previous
+ ) {
+ throw new Error(`${label} animation keyframe ${index + 1} has an invalid frame offset.`);
+ }
+ if (
+ keyframe.easing !== undefined
+ && !["linear", "ease-in", "ease-out", "ease-in-out"].includes(keyframe.easing)
+ ) {
+ throw new Error(`${label} animation keyframe ${index + 1} has an invalid easing.`);
+ }
+ if (keyframe.style.length === 0) throw new Error(`${label} animation keyframe ${index + 1} has no style.`);
+ assertStyle(keyframe.style, `${label}.animation.${index + 1}`);
+ for (const declaration of keyframe.style) {
+ if (!ANIMATABLE_LOCAL_STYLES.has(declaration.name)) {
+ throw new Error(`${label} animation cannot change ${declaration.name}.`);
+ }
+ }
+ previous = keyframe.atFrame;
+ }
+ if (animation.keyframes[0]!.atFrame !== 0 || animation.keyframes.at(-1)!.atFrame !== durationFrames) {
+ throw new Error(`${label} animation must cover the complete Present span.`);
+ }
+}
+
+function assertPresent(present: VisualPresent, programSpace: ProgramSpace, trackId: string): void {
+ const totalFrames = programSpaceFrameCount(programSpace);
+ assertNonEmpty(present.id, `${trackId} Present id`);
+ assertFrameSpan(present.span, totalFrames, `${trackId}.${present.id}.span`);
+ assertNonEmpty(present.stacking.tieBreak, `${trackId}.${present.id} stacking tieBreak`);
+ if (!Number.isSafeInteger(present.stacking.order)) {
+ throw new Error(`${trackId}.${present.id} has invalid stacking order.`);
+ }
+ if (present.elements.length === 0) throw new Error(`${trackId}.${present.id} must contain an element.`);
+ const elements = new Map<string, VisualElement>();
+ const roots: VisualElement[] = [];
+ const orders = new Set<number>();
+ for (const element of present.elements) {
+ assertNonEmpty(element.id, `${trackId}.${present.id} element id`);
+ if (elements.has(element.id)) throw new Error(`${trackId}.${present.id} has duplicate element ${element.id}.`);
+ if (!Number.isSafeInteger(element.order) || element.order < 0 || orders.has(element.order)) {
+ throw new Error(`${trackId}.${present.id}.${element.id} has invalid or duplicate order.`);
+ }
+ orders.add(element.order);
+ elements.set(element.id, element);
+ if (element.parent === undefined) roots.push(element);
+ assertStyle(element.style, `${trackId}.${present.id}.${element.id}`);
+ assertAttributes(element.attributes, `${trackId}.${present.id}.${element.id}`);
+ assertAnimation(
+ element.animation,
+ present.span.endFrameExclusive - present.span.startFrame,
+ `${trackId}.${present.id}.${element.id}`,
+ );
+ if (element.kind === "image" || element.kind === "video") {
+ assertArtifact(element.artifact, `${trackId}.${present.id}.${element.id}.artifact`);
+ if (!element.artifact.mediaType.startsWith(`${element.kind}/`)) {
+ throw new Error(`${trackId}.${present.id}.${element.id} media kind does not match its Artifact.`);
+ }
+ if (element.mediaStartSec !== undefined && (!Number.isFinite(element.mediaStartSec) || element.mediaStartSec < 0)) {
+ throw new Error(`${trackId}.${present.id}.${element.id} has invalid mediaStartSec.`);
+ }
+ if (element.playbackRate !== undefined && (!Number.isFinite(element.playbackRate) || element.playbackRate <= 0)) {
+ throw new Error(`${trackId}.${present.id}.${element.id} has invalid playbackRate.`);
+ }
+ }
+ if (element.kind === "text" && element.fonts !== undefined) {
+ if (element.fonts.length === 0) throw new Error(`${trackId}.${present.id}.${element.id} has an empty font stack.`);
+ const faces = new Set<string>();
+ const requestedWeight = element.fonts[0]!.weight;
+ const requestedStyle = element.fonts[0]!.style;
+ for (const [index, font] of element.fonts.entries()) {
+ assertFontArtifactRef(font, `${trackId}.${present.id}.${element.id}.fonts.${index}`);
+ if (font.weight !== requestedWeight || font.style !== requestedStyle) {
+ throw new Error(`${trackId}.${present.id}.${element.id} fallback fonts must describe one requested face.`);
+ }
+ const face = `${font.artifact.digest}:${font.weight}:${font.style}`;
+ if (faces.has(face)) throw new Error(`${trackId}.${present.id}.${element.id} has a duplicate font face.`);
+ faces.add(face);
+ }
+ const ownedFontStyles = new Set(["font-family", "font-style", "font-synthesis", "font-weight"]);
+ if (element.style.some((declaration) => ownedFontStyles.has(declaration.name))) {
+ throw new Error(`${trackId}.${present.id}.${element.id} exact fonts conflict with a raw font style.`);
+ }
+ }
+ if (element.kind === "surface") {
+ assertCompositableSurfaceRef(element.surface, `${trackId}.${present.id}.${element.id}.surface`);
+ if (element.surface.timing.kind === "frames") {
+ const durationFrames = present.span.endFrameExclusive - present.span.startFrame;
+ if (
+ element.surface.timing.frameRate.numerator !== programSpace.frameRate.numerator
+ || element.surface.timing.frameRate.denominator !== programSpace.frameRate.denominator
+ || element.surface.timing.frameCount !== durationFrames
+ ) {
+ throw new Error(`${trackId}.${present.id}.${element.id} Surface must exactly match its Present frame domain.`);
+ }
+ }
+ }
+ }
+ if (roots.length !== 1) throw new Error(`${trackId}.${present.id} must contain exactly one root element.`);
+ for (const element of present.elements) {
+ if (element.parent !== undefined && !elements.has(element.parent)) {
+ throw new Error(`${trackId}.${present.id}.${element.id} references a foreign parent.`);
+ }
+ if (element.parent !== undefined && elements.get(element.parent)?.kind !== "box") {
+ throw new Error(`${trackId}.${present.id}.${element.id} must have a box parent.`);
+ }
+ const visited = new Set<string>();
+ let cursor: VisualElement | undefined = element;
+ while (cursor?.parent !== undefined) {
+ if (visited.has(cursor.id)) throw new Error(`${trackId}.${present.id} contains an element cycle.`);
+ visited.add(cursor.id);
+ cursor = elements.get(cursor.parent);
+ }
+ }
+}
+
+function normalizeStyle(style: readonly VisualStyleDeclaration[]): VisualStyleDeclaration[] {
+ return [...style]
+ .map((item) => ({ name: item.name, value: item.value }))
+ .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function normalizeAttributes(attributes: readonly VisualAttribute[]): readonly VisualAttribute[] {
+ return [...attributes]
+ .map((item) => ({ name: item.name, value: item.value }))
+ .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function normalizeAnimation(animation: VisualAnimation): VisualAnimation {
+ return {
+ keyframes: [...animation.keyframes]
+ .map((keyframe) => ({
+ atFrame: keyframe.atFrame,
+ ...(keyframe.easing === undefined ? {} : { easing: keyframe.easing }),
+ style: normalizeStyle(keyframe.style),
+ }))
+ .sort((left, right) => left.atFrame - right.atFrame),
+ };
+}
+
+function normalizeElement(element: VisualElement): VisualElement {
+ const common = {
+ id: element.id,
+ ...(element.parent === undefined ? {} : { parent: element.parent }),
+ order: element.order,
+ style: normalizeStyle(element.style),
+ ...(element.attributes === undefined ? {} : { attributes: normalizeAttributes(element.attributes) }),
+ ...(element.animation === undefined ? {} : { animation: normalizeAnimation(element.animation) }),
+ };
+ if (element.kind === "box") return { ...common, kind: "box" };
+ if (element.kind === "text") {
+ return {
+ ...common,
+ kind: "text",
+ text: element.text,
+ ...(element.fonts === undefined ? {} : {
+ fonts: element.fonts.map((font) => ({
+ contract: font.contract,
+ artifact: { ...font.artifact },
+ weight: font.weight,
+ style: font.style,
+ })),
+ }),
+ };
+ }
+ if (element.kind === "surface") {
+ return {
+ ...common,
+ kind: "surface",
+ surface: {
+ ...element.surface,
+ artifact: { ...element.surface.artifact },
+ timing: element.surface.timing.kind === "still"
+ ? { kind: "still" }
+ : { ...element.surface.timing, frameRate: { ...element.surface.timing.frameRate } },
+ },
+ };
+ }
+ return {
+ ...common,
+ kind: element.kind,
+ artifact: { ...element.artifact },
+ ...(element.mediaStartSec === undefined ? {} : { mediaStartSec: element.mediaStartSec }),
+ ...(element.playbackRate === undefined ? {} : { playbackRate: element.playbackRate }),
+ ...(element.loop === undefined ? {} : { loop: element.loop }),
+ ...(element.muted === undefined ? {} : { muted: element.muted }),
+ };
+}
+
+function visualTrackContent(value: Omit<VisualTrack, "digest">): Omit<VisualTrack, "digest"> {
+ return {
+ contract: "svml.visual-track@1",
+ id: value.id,
+ programSpaceDigest: value.programSpaceDigest,
+ sources: normalizeSources(value.sources),
+ presents: [...value.presents]
+ .map((present) => ({
+ id: present.id,
+ span: { ...present.span },
+ stacking: { ...present.stacking },
+ elements: [...present.elements].map(normalizeElement).sort((a, b) => a.order - b.order || a.id.localeCompare(b.id)),
+ }))
+ .sort((a, b) => a.span.startFrame - b.span.startFrame
+ || a.stacking.order - b.stacking.order
+ || a.stacking.tieBreak.localeCompare(b.stacking.tieBreak)
+ || a.id.localeCompare(b.id)),
+ };
+}
+
+function audioTrackContent(value: Omit<AudioTrack, "digest">): Omit<AudioTrack, "digest"> {
+ return {
+ contract: "svml.audio-track@1",
+ id: value.id,
+ programSpaceDigest: value.programSpaceDigest,
+ sources: normalizeSources(value.sources),
+ clips: [...value.clips]
+ .map((clip) => ({
+ id: clip.id,
+ span: { ...clip.span },
+ artifact: { ...clip.artifact },
+ ...(clip.mediaStartSec === undefined ? {} : { mediaStartSec: clip.mediaStartSec }),
+ ...(clip.playbackRate === undefined ? {} : { playbackRate: clip.playbackRate }),
+ ...(clip.gain === undefined ? {} : { gain: clip.gain }),
+ ...(clip.fadeInSec === undefined ? {} : { fadeInSec: clip.fadeInSec }),
+ ...(clip.fadeOutSec === undefined ? {} : { fadeOutSec: clip.fadeOutSec }),
+ ...(clip.bus === undefined ? {} : { bus: clip.bus }),
+ }))
+ .sort((a, b) => a.span.startFrame - b.span.startFrame || a.id.localeCompare(b.id)),
+ };
+}
+
+export function computeVisualTrackDigest(value: Omit<VisualTrack, "digest">): Digest {
+ return digestOf(visualTrackContent(value));
+}
+
+export function computeAudioTrackDigest(value: Omit<AudioTrack, "digest">): Digest {
+ return digestOf(audioTrackContent(value));
+}
+
+export function sealVisualTrack(value: Omit<VisualTrack, "digest">): VisualTrack {
+ const content = visualTrackContent(value);
+ return { ...content, digest: digestOf(content) };
+}
+
+export function sealAudioTrack(value: Omit<AudioTrack, "digest">): AudioTrack {
+ const content = audioTrackContent(value);
+ return { ...content, digest: digestOf(content) };
+}
+
+export function assertVisualTrackIdentity(track: VisualTrack, programSpace: ProgramSpace): void {
+ assertProgramSpaceIdentity(programSpace);
+ if (track.contract !== "svml.visual-track@1") throw new Error("Unsupported VisualTrack contract.");
+ assertNonEmpty(track.id, "VisualTrack id");
+ assertSources(track.sources, track.id);
+ if (track.programSpaceDigest !== programSpace.digest) throw new Error(`${track.id} belongs to another ProgramSpace.`);
+ const { digest: _digest, ...content } = track;
+ if (!isDigest(track.digest) || track.digest !== computeVisualTrackDigest(content)) {
+ throw new Error(`${track.id} VisualTrack digest does not match its contents.`);
+ }
+ const presentIds = new Set<string>();
+ for (const present of track.presents) {
+ if (presentIds.has(present.id)) throw new Error(`${track.id} has duplicate Present ${present.id}.`);
+ presentIds.add(present.id);
+ assertPresent(present, programSpace, track.id);
+ }
+}
+
+export function assertAudioTrackIdentity(track: AudioTrack, programSpace: ProgramSpace): void {
+ assertProgramSpaceIdentity(programSpace);
+ if (track.contract !== "svml.audio-track@1") throw new Error("Unsupported AudioTrack contract.");
+ assertNonEmpty(track.id, "AudioTrack id");
+ assertSources(track.sources, track.id);
+ if (track.programSpaceDigest !== programSpace.digest) throw new Error(`${track.id} belongs to another ProgramSpace.`);
+ const { digest: _digest, ...content } = track;
+ if (!isDigest(track.digest) || track.digest !== computeAudioTrackDigest(content)) {
+ throw new Error(`${track.id} AudioTrack digest does not match its contents.`);
+ }
+ const totalFrames = programSpaceFrameCount(programSpace);
+ const clipIds = new Set<string>();
+ for (const clip of track.clips) {
+ if (clipIds.has(clip.id)) throw new Error(`${track.id} has duplicate clip ${clip.id}.`);
+ clipIds.add(clip.id);
+ assertNonEmpty(clip.id, `${track.id} clip id`);
+ assertFrameSpan(clip.span, totalFrames, `${track.id}.${clip.id}.span`);
+ assertArtifact(clip.artifact, `${track.id}.${clip.id}.artifact`);
+ if (!clip.artifact.mediaType.startsWith("audio/") && !clip.artifact.mediaType.startsWith("video/")) {
+ throw new Error(`${track.id}.${clip.id} is not an audio-capable Artifact.`);
+ }
+ for (const [name, value] of Object.entries({
+ mediaStartSec: clip.mediaStartSec,
+ gain: clip.gain,
+ fadeInSec: clip.fadeInSec,
+ fadeOutSec: clip.fadeOutSec,
+ })) {
+ if (value !== undefined && (!Number.isFinite(value) || value < 0)) {
+ throw new Error(`${track.id}.${clip.id} has invalid ${name}.`);
+ }
+ }
+ if (clip.playbackRate !== undefined && (!Number.isFinite(clip.playbackRate) || clip.playbackRate <= 0)) {
+ throw new Error(`${track.id}.${clip.id} has invalid playbackRate.`);
+ }
+ }
+}
+
+function trackKey(track: Track): string {
+ return `${track.contract}\u0000${track.id}`;
+}
+
+function compositionContent(value: Omit<Composition, "digest">): Omit<Composition, "digest"> {
+ return {
+ contract: "svml.composition@1",
+ id: value.id,
+ programSpace: { ...value.programSpace, frameRate: { ...value.programSpace.frameRate } },
+ canvas: { ...value.canvas },
+ tracks: [...value.tracks].map((track) => structuredClone(track)).sort((a, b) => trackKey(a).localeCompare(trackKey(b))),
+ };
+}
+
+export function computeCompositionDigest(value: Omit<Composition, "digest">): Digest {
+ return digestOf(compositionContent(value));
+}
+
+export function sealComposition(value: Omit<Composition, "digest">): Composition {
+ const content = compositionContent(value);
+ return { ...content, digest: digestOf(content) };
+}
+
+export function assertCompositionIdentity(composition: Composition): void {
+ if (composition.contract !== "svml.composition@1") throw new Error("Unsupported Composition contract.");
+ assertNonEmpty(composition.id, "Composition id");
+ assertProgramSpaceIdentity(composition.programSpace);
+ const { digest: _digest, ...content } = composition;
+ if (!isDigest(composition.digest) || composition.digest !== computeCompositionDigest(content)) {
+ throw new Error("Composition digest does not match its contents.");
+ }
+ if (
+ !Number.isSafeInteger(composition.canvas.width)
+ || composition.canvas.width <= 0
+ || !Number.isSafeInteger(composition.canvas.height)
+ || composition.canvas.height <= 0
+ || !/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/u.test(composition.canvas.clearColor)
+ ) {
+ throw new Error("Composition canvas is invalid.");
+ }
+ const ids = new Set<string>();
+ const stacking = new Map<string, Array<{ readonly trackId: string; readonly present: VisualPresent }>>();
+ for (const track of composition.tracks) {
+ if (ids.has(track.id)) throw new Error(`Composition contains duplicate Track id ${track.id}.`);
+ ids.add(track.id);
+ if (track.contract === "svml.visual-track@1") {
+ assertVisualTrackIdentity(track, composition.programSpace);
+ for (const present of track.presents) {
+ const key = `${present.stacking.order}\u0000${present.stacking.tieBreak}`;
+ const peers = stacking.get(key) ?? [];
+ for (const peer of peers) {
+ const overlaps = present.span.startFrame < peer.present.span.endFrameExclusive
+ && peer.present.span.startFrame < present.span.endFrameExclusive;
+ if (overlaps) {
+ throw new Error(
+ `Composition contains overlapping visual stacking key ${key} in ${peer.trackId}.${peer.present.id} and ${track.id}.${present.id}.`,
+ );
+ }
+ }
+ peers.push({ trackId: track.id, present });
+ stacking.set(key, peers);
+ }
+ } else {
+ assertAudioTrackIdentity(track, composition.programSpace);
+ }
+ }
+}
diff --git a/packages/contracts/test/manifest.test.ts b/packages/contracts/test/manifest.test.ts
new file mode 100644
index 00000000..93e50b6c
--- /dev/null
+++ b/packages/contracts/test/manifest.test.ts
@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { digestOf } from "@svml/protocol";
+
+import {
+ compositionManifest,
+ contractTypes,
+ narrativeManifest,
+ narrativeManifestDigest,
+ videoContractManifests,
+} from "../src/index.js";
+
+test("the physical video distribution carries six independently identified logical modules", () => {
+ assert.deepEqual(videoContractManifests.map((manifest) => manifest.name), [
+ "@svml/narrative",
+ "@svml/media",
+ "@svml/program-space",
+ "@svml/speech",
+ "@svml/semantic-time",
+ "@svml/composition",
+ ]);
+ assert.equal(new Set(videoContractManifests.map((manifest) => digestOf(manifest))).size, 6);
+ assert.equal(narrativeManifestDigest, digestOf(narrativeManifest));
+});
+
+test("Narrative and Composition no longer share one invalidation identity", () => {
+ assert.equal(contractTypes.narrative.module.name, narrativeManifest.name);
+ assert.equal(contractTypes.visualTrack.module.name, compositionManifest.name);
+ assert.notEqual(contractTypes.narrative.module.name, contractTypes.visualTrack.module.name);
+ assert.equal(narrativeManifest.dependencies.length, 0);
+ assert.equal(compositionManifest.dependencies.some((dependency) =>
+ dependency.module.name === narrativeManifest.name), false);
+});
diff --git a/packages/contracts/test/render.test.ts b/packages/contracts/test/render.test.ts
new file mode 100644
index 00000000..cecd5e17
--- /dev/null
+++ b/packages/contracts/test/render.test.ts
@@ -0,0 +1,160 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ assertCompositableSurfaceRef,
+ assertCompositionIdentity,
+ assertFontArtifactRef,
+ sealComposition,
+ sealProgramSpace,
+ sealVisualTrack,
+} from "../src/index.js";
+import type {
+ CompositableSurfaceRef,
+ FontArtifactRef,
+ VisualTrack,
+} from "../src/index.js";
+import { digestOf } from "@svml/protocol";
+
+const space = sealProgramSpace({
+ contract: "svml.program-space@0",
+ durationSec: 2,
+ frameRate: { numerator: 30, denominator: 1 },
+});
+
+const font: FontArtifactRef = {
+ contract: "svml.font-artifact@1",
+ artifact: {
+ kind: "blob",
+ digest: digestOf("font:inter-bold"),
+ size: 1_024,
+ mediaType: "font/woff2",
+ },
+ weight: 700,
+ style: "normal",
+};
+
+const animatedSurface: CompositableSurfaceRef = {
+ contract: "svml.compositable-surface@1",
+ artifact: {
+ kind: "blob",
+ digest: digestOf("surface:alpha-webm"),
+ size: 2_048,
+ mediaType: "video/webm",
+ },
+ width: 1080,
+ height: 1920,
+ colorSpace: "srgb",
+ alphaMode: "straight",
+ timing: {
+ kind: "frames",
+ frameRate: { numerator: 30, denominator: 1 },
+ frameCount: 60,
+ },
+};
+
+test("FontArtifactRef binds one exact font face to a content-addressed Blob", () => {
+ assert.doesNotThrow(() => assertFontArtifactRef(font));
+ assert.throws(
+ () => assertFontArtifactRef({ ...font, artifact: { ...font.artifact, mediaType: "application/octet-stream" } }),
+ /supported font media type/u,
+ );
+ assert.throws(() => assertFontArtifactRef({ ...font, weight: 0 }), /weight/u);
+});
+
+test("CompositableSurfaceRef distinguishes a typed alpha surface from an ordinary media guess", () => {
+ assert.doesNotThrow(() => assertCompositableSurfaceRef(animatedSurface));
+ assert.throws(
+ () => assertCompositableSurfaceRef({
+ ...animatedSurface,
+ artifact: { ...animatedSurface.artifact, mediaType: "video/mp4" },
+ }),
+ /straight alpha requires/u,
+ );
+ assert.throws(
+ () => assertCompositableSurfaceRef({
+ ...animatedSurface,
+ artifact: { ...animatedSurface.artifact, mediaType: "image/png" },
+ }),
+ /frame timing requires a video/u,
+ );
+});
+
+test("exact fonts own font selection and cannot conflict with raw CSS font facts", () => {
+ const invalid = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "invalid-font-track",
+ programSpaceDigest: space.digest,
+ sources: [{ name: "fixture", digest: digestOf("invalid-font-track") }],
+ presents: [{
+ id: "title",
+ span: { startFrame: 0, endFrameExclusive: 60 },
+ stacking: { order: 1, tieBreak: "title" },
+ elements: [{
+ id: "title",
+ order: 0,
+ kind: "text",
+ text: "SVML",
+ fonts: [font],
+ style: [{ name: "font-family", value: "Inter" }],
+ }],
+ }],
+ });
+ assert.throws(
+ () => assertCompositionIdentity(sealComposition({
+ contract: "svml.composition@1",
+ id: "invalid-font-composition",
+ programSpace: space,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [invalid],
+ })),
+ /exact fonts conflict with a raw font style/u,
+ );
+});
+
+test("animated materialized Surfaces must exactly share the Present frame domain", () => {
+ const valid = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "surface-track",
+ programSpaceDigest: space.digest,
+ sources: [{ name: "receipt", digest: digestOf("surface-receipt") }],
+ presents: [{
+ id: "surface",
+ span: { startFrame: 0, endFrameExclusive: 60 },
+ stacking: { order: 1, tieBreak: "surface" },
+ elements: [{ id: "surface", order: 0, kind: "surface", surface: animatedSurface, style: [] }],
+ }],
+ });
+ assert.doesNotThrow(() => assertCompositionIdentity(sealComposition({
+ contract: "svml.composition@1",
+ id: "surface-composition",
+ programSpace: space,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [valid],
+ })));
+
+ const content = structuredClone(valid) as VisualTrack;
+ const surface = content.presents[0]!.elements[0]!;
+ assert(surface.kind === "surface");
+ const invalid = sealVisualTrack({
+ ...content,
+ presents: [{
+ ...content.presents[0]!,
+ span: { startFrame: 0, endFrameExclusive: 30 },
+ elements: [{
+ ...surface,
+ surface: {
+ ...surface.surface,
+ timing: { kind: "frames", frameRate: { numerator: 30, denominator: 1 }, frameCount: 60 },
+ },
+ }],
+ }],
+ });
+ assert.throws(() => assertCompositionIdentity(sealComposition({
+ contract: "svml.composition@1",
+ id: "invalid-surface-composition",
+ programSpace: space,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [invalid],
+ })), /must exactly match its Present frame domain/u);
+});
diff --git a/packages/contracts/test/track.test.ts b/packages/contracts/test/track.test.ts
new file mode 100644
index 00000000..4ed5f3ad
--- /dev/null
+++ b/packages/contracts/test/track.test.ts
@@ -0,0 +1,222 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { digestOf } from "@svml/protocol";
+
+import {
+ assertCompositionIdentity,
+ sealAudioTrack,
+ sealComposition,
+ sealProgramSpace,
+ sealVisualTrack,
+} from "../src/index.js";
+import type { MediaArtifactRef, VisualTrack } from "../src/index.js";
+
+const image: MediaArtifactRef = {
+ digest: digestOf("image"),
+ size: 12,
+ mediaType: "image/png",
+ durationSec: 0,
+};
+const audio: MediaArtifactRef = {
+ digest: digestOf("audio"),
+ size: 24,
+ mediaType: "audio/wav",
+ durationSec: 4,
+};
+
+function fixture() {
+ const programSpace = sealProgramSpace({
+ contract: "svml.program-space@0",
+ durationSec: 4,
+ frameRate: { numerator: 30, denominator: 1 },
+ });
+ const visual = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "caption",
+ programSpaceDigest: programSpace.digest,
+ sources: [{ name: "projection", digest: digestOf("caption-projection") }],
+ presents: [{
+ id: "cue-1",
+ span: { startFrame: 0, endFrameExclusive: 60 },
+ stacking: { order: 100, tieBreak: "caption" },
+ elements: [
+ { id: "root", order: 0, kind: "box", style: [{ name: "position", value: "absolute" }] },
+ { id: "text", parent: "root", order: 1, kind: "text", text: "Hello", style: [] },
+ ],
+ }],
+ });
+ const sound = sealAudioTrack({
+ contract: "svml.audio-track@1",
+ id: "speech",
+ programSpaceDigest: programSpace.digest,
+ sources: [{ name: "basis", digest: digestOf("speech-basis") }],
+ clips: [{ id: "speech", span: { startFrame: 0, endFrameExclusive: 120 }, artifact: audio, bus: "speech" }],
+ });
+ return { programSpace, visual, sound };
+}
+
+test("Composition accepts self-contained peer VisualTrack and AudioTrack values", () => {
+ const { programSpace, visual, sound } = fixture();
+ const composition = sealComposition({
+ contract: "svml.composition@1",
+ id: "main",
+ programSpace,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [sound, visual],
+ });
+ assert.doesNotThrow(() => assertCompositionIdentity(composition));
+ assert.deepEqual(composition.tracks.map((track) => track.id), ["speech", "caption"]);
+});
+
+test("VisualTrack rejects cross-Track pixel sampling styles", () => {
+ const { programSpace, visual, sound } = fixture();
+ const content = structuredClone(visual) as VisualTrack;
+ const first = content.presents[0]!.elements[0]!;
+ const invasive = sealVisualTrack({
+ ...content,
+ presents: [{
+ ...content.presents[0]!,
+ elements: [{ ...first, style: [{ name: "backdrop-filter", value: "blur(20px)" }] }],
+ }],
+ });
+ const composition = sealComposition({
+ contract: "svml.composition@1",
+ id: "invasive",
+ programSpace,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [sound, invasive],
+ });
+ assert.throws(() => assertCompositionIdentity(composition), /cross-Track style backdrop-filter/);
+});
+
+test("VisualTrack style values cannot smuggle a second declaration", () => {
+ const { programSpace, visual } = fixture();
+ const content = structuredClone(visual) as VisualTrack;
+ const first = content.presents[0]!.elements[0]!;
+ const smuggled = sealVisualTrack({
+ ...content,
+ presents: [{
+ ...content.presents[0]!,
+ elements: [{ ...first, style: [{ name: "color", value: "red;backdrop-filter:blur(20px)" }] }],
+ }],
+ });
+ assert.throws(
+ () => assertCompositionIdentity(sealComposition({
+ contract: "svml.composition@1",
+ id: "smuggled",
+ programSpace,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [smuggled],
+ })),
+ /escapes its declaration/,
+ );
+});
+
+test("Composition rejects a Track from another ProgramSpace even when its shape is valid", () => {
+ const { programSpace, visual } = fixture();
+ const foreign = sealProgramSpace({
+ contract: "svml.program-space@0",
+ durationSec: 4,
+ frameRate: { numerator: 24, denominator: 1 },
+ });
+ const composition = sealComposition({
+ contract: "svml.composition@1",
+ id: "foreign",
+ programSpace: foreign,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [visual],
+ });
+ assert.throws(() => assertCompositionIdentity(composition), /belongs to another ProgramSpace/);
+ assert.notEqual(programSpace.digest, foreign.digest);
+});
+
+test("Composition identity binds every Track digest and rejects tampering", () => {
+ const { programSpace, visual } = fixture();
+ const composition = sealComposition({
+ contract: "svml.composition@1",
+ id: "main",
+ programSpace,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [visual],
+ });
+ const tampered = structuredClone(composition);
+ (tampered.tracks[0] as { id: string }).id = "changed";
+ assert.throws(() => assertCompositionIdentity(tampered), /Composition digest does not match/);
+});
+
+test("one authoring Track may contribute independently stacked Presents", () => {
+ const { programSpace, visual } = fixture();
+ const content = structuredClone(visual) as VisualTrack;
+ const second = {
+ ...structuredClone(content.presents[0]!),
+ id: "cue-2",
+ stacking: { order: 30, tieBreak: "board" },
+ };
+ const interleaved = sealVisualTrack({
+ ...content,
+ presents: [
+ { ...content.presents[0]!, stacking: { order: 80, tieBreak: "icon" } },
+ second,
+ ],
+ });
+ const composition = sealComposition({
+ contract: "svml.composition@1",
+ id: "interleaved",
+ programSpace,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [interleaved],
+ });
+ assert.doesNotThrow(() => assertCompositionIdentity(composition));
+ assert.deepEqual(interleaved.presents.map((present) => present.stacking.order), [30, 80]);
+});
+
+test("Visual Present animations are frame-exact and cannot animate cross-Track styles", () => {
+ const { programSpace, visual } = fixture();
+ const present = visual.presents[0]!;
+ const root = present.elements[0]!;
+ const animated = sealVisualTrack({
+ ...visual,
+ presents: [{
+ ...present,
+ elements: [{
+ ...root,
+ animation: {
+ keyframes: [
+ { atFrame: 0, style: [{ name: "opacity", value: 0 }] },
+ { atFrame: 60, easing: "ease-out", style: [{ name: "opacity", value: 1 }] },
+ ],
+ },
+ }],
+ }],
+ });
+ assert.doesNotThrow(() => assertCompositionIdentity(sealComposition({
+ contract: "svml.composition@1",
+ id: "animated",
+ programSpace,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [animated],
+ })));
+ const invasive = sealVisualTrack({
+ ...visual,
+ presents: [{
+ ...present,
+ elements: [{
+ ...root,
+ animation: {
+ keyframes: [
+ { atFrame: 0, style: [{ name: "backdrop-filter", value: "blur(0px)" }] },
+ { atFrame: 60, style: [{ name: "backdrop-filter", value: "blur(20px)" }] },
+ ],
+ },
+ }],
+ }],
+ });
+ assert.throws(() => assertCompositionIdentity(sealComposition({
+ contract: "svml.composition@1",
+ id: "animated-invasive",
+ programSpace,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [invasive],
+ })), /cross-Track style backdrop-filter/);
+});
diff --git a/packages/core/README.md b/packages/core/README.md
index c092b43c..1fc1e06a 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -2,16 +2,33 @@
Experimental v2 bootstrap microkernel.
-The package accepts an already resolved module closure, typed authored modules and an explicit
-finite build plan. It validates identities, schemas, immutable records, Needs, Receipts and
-Derivations, then advances a serializable `BuildState` with pure `reduce(state, event)` calls.
+The package accepts an already resolved module closure, typed authored modules, a complete
+`svml.graph@1` and a `svml.build-request@1`. It verifies Candidate selection and compiles the finite
+BuildPlan by traversing backwards from every Target, resolving Logical Outputs and memoizing shared
+atomic Operations by stable OperationId. It then validates immutable Records, Needs, Receipts and
+Derivations and advances a serializable `BuildState` with pure `reduce(state, event)` calls.
Derivations bind Producer and implementation identity, input/output Record digests, Need request
digests and the accepted event digest. Needs carry the conformance floor inherited from their
inputs, so an exact external response cannot wash a substitute upstream back to exact. An exact
Need above a substitute floor fails before an external Handler can run.
+Cross-package Types are nominal: exact module name, version and type name must match. Core checks
+their package-owned structural Schema. If the Type owner locked a semantic validator in its
+Manifest, every authored, provided, Producer or Provider Record must also carry a validation
+receipt bound to the exact Type, value digest and locked validator digest. Core verifies this
+receipt uniformly but never executes the validator; trusted Host admission lives in
+`@svml/validation`.
+
It generically verifies Surface declarations in the same immutable module closure, but never
parses or dispatches one. It does not parse source, resolve package locations, execute
-implementations, access artifact bytes, select providers or search for a workflow. Those
-responsibilities remain outside Core.
+implementations, access artifact bytes, select Provider endpoints or discover undeclared graph
+structure. Those responsibilities remain outside Core. The normative laws are in
+[`../../spec/core-kernel-v1.md`](../../spec/core-kernel-v1.md).
+
+For a non-video domain, the irreducible reusable base is only `@svml/protocol` plus `@svml/core`.
+Most source languages will also use `@svml/elaborator` to turn modular component declarations into a
+Graph, and a Driver/Runtime package to execute Commands. `@svml/text`, `@svml/realization` and every
+domain contract package are optional layers; none receives Kernel privilege by being official.
+Domains that declare semantic Type validators additionally need a Host admission implementation;
+the reference one is `@svml/validation`.
diff --git a/packages/core/src/graph.ts b/packages/core/src/graph.ts
index 3797c466..efe56c2b 100644
--- a/packages/core/src/graph.ts
+++ b/packages/core/src/graph.ts
@@ -48,10 +48,10 @@ function normalizeRoot(root: CandidateRoot): CandidateRoot {
const value = {
id: root.value.id,
value: normalizedStoredValue(root.value.value),
+ ...(root.value.validation === undefined ? {} : { validation: root.value.validation }),
+ ...(root.value.provenance === undefined ? {} : { provenance: canonicalize(root.value.provenance) }),
};
- return root.value.provenance === undefined
- ? { kind: "value", value }
- : { kind: "value", value: { ...value, provenance: canonicalize(root.value.provenance) } };
+ return { kind: "value", value };
}
function normalizeOutput(output: LogicalOutput): LogicalOutput {
@@ -337,6 +337,9 @@ function candidateType(program: LinkedProgram, graph: CompiledGraph, candidate:
? {}
: { provenance: candidate.root.value.provenance }),
},
+ ...(candidate.root.value.validation === undefined
+ ? {}
+ : { validation: candidate.root.value.validation }),
});
verifyRecord(program.closure, provisional);
return provisional.type;
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index e345193f..1dcb9389 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -15,9 +15,12 @@ export {
resolveProducer,
resolveType,
sealRecord,
+ sealTypeValidationReceipt,
sealTypedModule,
verifyClosure,
verifyRecord,
+ verifyRecordStructure,
+ verifyTypeValidationReceipt,
} from "./link.js";
export {
EMPTY_REALIZATION_DIGEST,
diff --git a/packages/core/src/link.ts b/packages/core/src/link.ts
index 4151c714..f5c580b1 100644
--- a/packages/core/src/link.ts
+++ b/packages/core/src/link.ts
@@ -13,15 +13,18 @@ import type {
TypeRef,
TypedModule,
TypedRecord,
+ TypeValidationReceipt,
} from "@svml/protocol";
import { digestOf, isDigest, recordDigest, semanticRecordsDigest } from "./canonical.js";
import { CoreError, invariant } from "./error.js";
-import { capabilityKey, moduleKey, producerKey, sameModule, typeKey } from "./reference.js";
+import { capabilityKey, moduleKey, producerKey, sameModule, sameType, typeKey } from "./reference.js";
import { validateStoredValue } from "./schema.js";
export type TypedRecordDraft = Omit<TypedRecord, "digest">;
+type TypeValidationReceiptDraft = Omit<TypeValidationReceipt, "format" | "id">;
+
function manifestRef(manifest: ModuleManifest): ModuleRef {
return { name: manifest.name, version: manifest.version };
}
@@ -116,6 +119,25 @@ export function verifyClosure(closure: ResolvedModuleClosure): void {
"dependency",
key,
);
+ for (const type of module.manifest.types) {
+ if (type.validator === undefined) continue;
+ invariant(
+ type.validator.abi === "svml.type-validator@1",
+ "UNSUPPORTED_TYPE_VALIDATOR",
+ `${key}#${type.name} validator ABI is unsupported`,
+ );
+ invariant(
+ type.validator.implementation.kind.length > 0
+ && type.validator.implementation.locator.length > 0,
+ "INVALID_TYPE_VALIDATOR",
+ `${key}#${type.name} validator implementation is incomplete`,
+ );
+ invariant(
+ isDigest(type.validator.implementation.digest),
+ "INVALID_DIGEST",
+ `${key}#${type.name} validator digest is invalid`,
+ );
+ }
for (const producer of module.manifest.producers) {
ensureUniqueNames(producer.inputs.map((item) => item.name), "input port", `${key}#${producer.name}`);
ensureUniqueNames(producer.outputs.map((item) => item.name), "output port", `${key}#${producer.name}`);
@@ -336,7 +358,38 @@ export function sealRecord(record: TypedRecordDraft): TypedRecord {
return { ...record, digest: recordDigest(record.type, record.value) };
}
-export function verifyRecord(
+export function sealTypeValidationReceipt(
+ receipt: TypeValidationReceiptDraft,
+): TypeValidationReceipt {
+ const content = {
+ format: "svml.type-validation@1" as const,
+ type: receipt.type,
+ recordDigest: receipt.recordDigest,
+ validatorDigest: receipt.validatorDigest,
+ };
+ return { ...content, id: digestOf(content) };
+}
+
+export function verifyTypeValidationReceipt(
+ receipt: TypeValidationReceipt,
+ type: TypeRef,
+ record: Digest,
+ validator: Digest,
+): void {
+ invariant(receipt.format === "svml.type-validation@1", "UNSUPPORTED_TYPE_VALIDATION", "unsupported validation receipt");
+ invariant(isDigest(receipt.id), "INVALID_DIGEST", "validation receipt id is invalid");
+ invariant(sameType(receipt.type, type), "TYPE_VALIDATION_TYPE_MISMATCH", "validation receipt belongs to another type");
+ invariant(receipt.recordDigest === record, "TYPE_VALIDATION_RECORD_MISMATCH", "validation receipt belongs to another value");
+ invariant(
+ receipt.validatorDigest === validator,
+ "TYPE_VALIDATOR_DIGEST_MISMATCH",
+ "validation receipt was issued by another validator",
+ );
+ const { id: _id, ...content } = receipt;
+ invariant(receipt.id === digestOf(content), "TYPE_VALIDATION_DIGEST_MISMATCH", "validation receipt content differs");
+}
+
+export function verifyRecordStructure(
closure: ResolvedModuleClosure,
record: TypedRecord,
): void {
@@ -350,6 +403,20 @@ export function verifyRecord(
);
const declaration = resolveType(closure, record.type);
validateStoredValue(record.value, declaration.schema, `$record.${record.id}`);
+ if (record.validation !== undefined) {
+ invariant(
+ declaration.validator !== undefined,
+ "UNEXPECTED_TYPE_VALIDATION",
+ `${record.id} carries validation for a type with no validator`,
+ record.id,
+ );
+ verifyTypeValidationReceipt(
+ record.validation,
+ record.type,
+ record.digest,
+ declaration.validator.implementation.digest,
+ );
+ }
if (record.origin.kind === "authored") {
invariant(isDigest(record.origin.sourceDigest), "INVALID_DIGEST", `${record.id} source digest is invalid`);
invariant(
@@ -368,6 +435,20 @@ export function verifyRecord(
}
}
+export function verifyRecord(
+ closure: ResolvedModuleClosure,
+ record: TypedRecord,
+): void {
+ verifyRecordStructure(closure, record);
+ const declaration = resolveType(closure, record.type);
+ invariant(
+ declaration.validator === undefined || record.validation !== undefined,
+ "TYPE_VALIDATION_REQUIRED",
+ `${record.id} requires ${declaration.validator?.implementation.locator ?? "type validation"}`,
+ record.id,
+ );
+}
+
export function sealTypedModule(input: {
readonly id: string;
readonly closureDigest: Digest;
diff --git a/packages/core/src/plan.ts b/packages/core/src/plan.ts
index 3323a66a..6adef214 100644
--- a/packages/core/src/plan.ts
+++ b/packages/core/src/plan.ts
@@ -164,6 +164,9 @@ export function compileBuild(
? {}
: { provenance: candidate.root.value.provenance }),
},
+ ...(candidate.root.value.validation === undefined
+ ? {}
+ : { validation: candidate.root.value.validation }),
});
verifyRecord(program.closure, record);
invariant(!authored.has(record.id), "PROVIDED_RECORD_CONFLICT", `${record.id} conflicts with authored input`);
diff --git a/packages/core/src/reducer.ts b/packages/core/src/reducer.ts
index e89931a5..323e8fdd 100644
--- a/packages/core/src/reducer.ts
+++ b/packages/core/src/reducer.ts
@@ -27,7 +27,7 @@ import {
} from "./affinity.js";
import { canonicalize, digestOf, recordDigest } from "./canonical.js";
import { CoreError, invariant } from "./error.js";
-import { resolveProducer, resolveType, sealRecord } from "./link.js";
+import { resolveProducer, resolveType, sealRecord, verifyRecord } from "./link.js";
import { compileBuild, producerStep } from "./plan.js";
import {
commandId,
@@ -98,6 +98,13 @@ function acceptProducerEvent(
const producer = resolveProducer(state.program.closure, step.producer);
exactPortKeys(event.outputs, producer.outputs.map((port) => port.name), `${step.id}.outputs`);
exactPortKeys(event.needs, producer.needs.map((port) => port.name), `${step.id}.needs`);
+ exactPortKeys(
+ event.validations ?? {},
+ producer.outputs
+ .filter((port) => resolveType(state.program.closure, port.type).validator !== undefined)
+ .map((port) => port.name),
+ `${step.id}.validations`,
+ );
const inputs = inputRecords(state, command);
const conformance = effectiveConformance(inheritedConformance(inputs), step.fidelity);
@@ -110,7 +117,15 @@ function acceptProducerEvent(
invariant(rawValue !== undefined, "MISSING_OUTPUT_VALUE", `${step.id}.${port.name} returned no value`);
const value = normalizeStoredValue(rawValue);
validateStoredValue(value, resolveType(state.program.closure, port.type).schema, `$output.${step.id}.${port.name}`);
- return { id, type: port.type, value, digest: recordDigest(port.type, value) };
+ return {
+ id,
+ type: port.type,
+ value,
+ digest: recordDigest(port.type, value),
+ ...(event.validations?.[port.name] === undefined
+ ? {}
+ : { validation: event.validations[port.name] }),
+ };
});
const needDrafts = producer.needs
@@ -153,7 +168,9 @@ function acceptProducerEvent(
value: output.value,
conformance,
origin: { kind: "derived", derivation: id },
+ ...(output.validation === undefined ? {} : { validation: output.validation }),
}));
+ outputs.forEach((record) => verifyRecord(state.program.closure, record));
const outputLookup = new Map([...state.records, ...outputs].map((record) => [record.id, record]));
outputs.forEach((record) => {
verifyProducerRecordAffinity(state.program, state.plan, record, (recordId) => outputLookup.get(recordId));
@@ -226,7 +243,9 @@ function acceptNeedEvent(
digest: outputDigest,
conformance,
origin: { kind: "observed", receipt: receipt.id },
+ ...(event.validation === undefined ? {} : { validation: event.validation }),
};
+ verifyRecord(state.program.closure, record);
const recordLookup = new Map([...state.records, record].map((item) => [item.id, item]));
verifyProducerRecordAffinity(state.program, state.plan, record, (recordId) => recordLookup.get(recordId));
verifyGraphRecordAffinity(state.graph, state.plan, record, (recordId) => recordLookup.get(recordId));
diff --git a/packages/driver-node/README.md b/packages/driver-node/README.md
index 1ad050ef..3eab152c 100644
--- a/packages/driver-node/README.md
+++ b/packages/driver-node/README.md
@@ -2,19 +2,50 @@
Node runtime for executing Core commands without adding workflow semantics to Core.
+Its Manifest helpers only read Node filesystem paths and construct a verified Closure. Pure static
+Manifest JSON parsing belongs to `@svml/protocol` and is re-exported here temporarily for callers of
+the prototype API.
+
- `HostRegistry` registers deterministic Producer implementations locked by implementation digest.
- `ProviderRegistry` binds an already explicit external capability to endpoints that may use APIs, credentials, queues or local runtimes.
+- Registrations may declare a scheduling lane and default concurrency. The environment-neutral
+ `@svml/runtime` Scheduler shares that lane across Builds; a Runtime Profile may override its limit.
- A Producer emits a typed `Need`; it never reads provider configuration directly.
- Providers match the locked `CapabilityRef` and return `TypeRef`. Multiple exact endpoints require
`bind()`. The Registry never routes by return type alone.
+- Production-style assembly uses `applyRuntimeClosure()`: Endpoint instance, exact capability and
+ return Type, implementation facet digest and Profile-owned scheduling must all match atomically.
+ Legacy direct `bind()` remains only as the low-level trusted test/embedding API.
+- Long-lived external work uses `registerProviderEndpoint()`, not an immediate Handler. The Driver
+ creates a content-addressed Operation before `start()`, persists pending checkpoints, calls
+ `resume()` for an existing Operation, and replays a journaled completion without another external
+ call. A recoverable Endpoint is blocked unless both its locked Runtime Closure and an
+ `OperationStore` are present.
- Preview, fallback and reuse are graph-level Candidates selected by BuildRequest, not Provider
modes. 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.
- Provider 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 Driver
+ structurally checks every result, executes the Type owner's digest-locked validator when declared,
+ and attaches the resulting receipt. Producer and Provider handlers cannot self-assert validation.
Build state is serializable. Missing providers, generation latency and transient provider errors pause a
build without replaying completed Producers.
+`start()` and `resume()` receive the same stable submission key. `resume(undefined)` is intentional:
+it covers a stop after submission intent was journaled but before a remote job checkpoint was saved.
+The Endpoint must use that key to find-or-submit idempotently; the Driver cannot manufacture remote
+exactly-once semantics for an API that does not provide them.
+
+`prepare()` regenerates and classifies the exact current Core commands. `executeCommand()` accepts
+only one regenerated command id, so a Scheduler cannot smuggle modified serialized command content
+into a paid Handler. `NodeDriver.run()` remains the simple serial convenience path; multi-Build and
+within-Build parallelism belong to `LocalBuildScheduler`, not to a Provider-specific queue.
+Callers using a recoverable Endpoint through the serial path must pass a stable Build identity as
+`run(state, { build })`; the Driver deliberately does not derive one from BuildRequest content,
+because two identical requests may still be distinct Builds. The Scheduler always supplies its
+declared Build id.
+
Outstanding Commands are not trusted persistence. Serialization drops them and Core regenerates
the exact commands from verified facts on resume, before any Handler can run. The Registry never
turns a generic speaker request into a model choice: Seedance, WhisperX or another external method
diff --git a/packages/driver-node/package.json b/packages/driver-node/package.json
index 134226cc..316c01e6 100644
--- a/packages/driver-node/package.json
+++ b/packages/driver-node/package.json
@@ -8,7 +8,9 @@
},
"dependencies": {
"@svml/core": "workspace:*",
- "@svml/protocol": "workspace:*"
+ "@svml/protocol": "workspace:*",
+ "@svml/runtime": "workspace:*",
+ "@svml/validation": "workspace:*"
},
"devDependencies": {
"@svml/caption": "workspace:*",
diff --git a/packages/driver-node/src/driver.ts b/packages/driver-node/src/driver.ts
index 1a74002f..30be080d 100644
--- a/packages/driver-node/src/driver.ts
+++ b/packages/driver-node/src/driver.ts
@@ -7,6 +7,22 @@ import type {
InvokeProducerCommand,
TypedRecord,
} from "@svml/protocol";
+import {
+ TypeValidatorRegistry,
+ validateValue,
+} from "@svml/validation";
+import type { TypeValidatorRegistryLike } from "@svml/validation";
+import {
+ sealOperationIdentity,
+ verifyOperationSnapshot,
+} from "@svml/runtime";
+import type {
+ OperationSnapshot,
+ OperationStore,
+ RuntimeExecutionContext,
+ RuntimeExecutionResult,
+ RuntimePreparation,
+} from "@svml/runtime";
import { MemoryArtifactStore } from "./artifacts.js";
import {
@@ -22,6 +38,7 @@ import type {
DriverJournalEntry,
DriverRunResult,
ProducerHandlerResult,
+ ProviderRegistration,
ProviderHandlerResult,
} from "./types.js";
@@ -29,31 +46,41 @@ export type NodeDriverOptions = {
readonly registry?: HostRegistry;
readonly providers?: ProviderRegistry;
readonly artifacts?: ArtifactStore;
+ readonly operations?: OperationStore;
readonly maxEvents?: number;
+ readonly validators?: TypeValidatorRegistryLike;
};
type Executable =
| {
readonly command: InvokeProducerCommand;
+ readonly lane: string;
+ readonly maxConcurrency: number;
readonly run: () => Promise<ProducerHandlerResult>;
}
| {
readonly command: FulfillNeedCommand;
readonly providerId: string;
- readonly run: () => Promise<ProviderHandlerResult>;
+ readonly lane: string;
+ readonly maxConcurrency: number;
+ readonly registration: ProviderRegistration;
};
export class NodeDriver {
readonly registry: HostRegistry;
readonly providers: ProviderRegistry;
readonly artifacts: ArtifactStore;
+ readonly operations: OperationStore | undefined;
readonly maxEvents: number;
+ readonly validators: TypeValidatorRegistryLike;
constructor(options: NodeDriverOptions = {}) {
this.registry = options.registry ?? new HostRegistry();
this.providers = options.providers ?? new ProviderRegistry();
this.artifacts = options.artifacts ?? new MemoryArtifactStore();
+ this.operations = options.operations;
this.maxEvents = options.maxEvents ?? 1_000;
+ this.validators = options.validators ?? new TypeValidatorRegistry();
}
#producerInputs(state: BuildState, command: InvokeProducerCommand): Record<string, TypedRecord> {
@@ -100,6 +127,8 @@ export class NodeDriver {
return {
executable: {
command,
+ lane: registration.scheduling?.lane ?? `producer:${producerRegistryKey(command.producer)}`,
+ maxConcurrency: registration.scheduling?.maxConcurrency ?? Number.MAX_SAFE_INTEGER,
run: async () =>
registration.handler({
command: structuredClone(command),
@@ -133,55 +162,238 @@ export class NodeDriver {
};
}
const registration = resolution.registration;
+ if (registration.kind === "endpoint" && this.operations === undefined) {
+ return {
+ blocked: {
+ command: command.id,
+ reason: "missing-operation-store",
+ subject: registration.id,
+ },
+ };
+ }
+ if (registration.kind === "endpoint" && this.providers.runtimeClosureDigest() === undefined) {
+ return {
+ blocked: {
+ command: command.id,
+ reason: "missing-runtime-closure",
+ subject: registration.id,
+ },
+ };
+ }
return {
executable: {
command,
providerId: registration.id,
- run: async () =>
- registration.handler({
- command: structuredClone(command),
- need: structuredClone(command.need),
- artifacts: this.artifacts,
- }),
+ lane: registration.scheduling?.lane ?? `provider:${registration.id}`,
+ maxConcurrency: registration.scheduling?.maxConcurrency ?? 1,
+ registration,
+ },
+ };
+ }
+
+ async #providerEvent(
+ state: BuildState,
+ executable: Extract<Executable, { readonly providerId: string }>,
+ result: ProviderHandlerResult,
+ ): Promise<BuildEvent> {
+ const validation = await validateValue(
+ state.program.closure,
+ executable.command.need.returns,
+ result.value,
+ this.validators,
+ );
+ const content = {
+ kind: "need-fulfilled",
+ command: executable.command.id,
+ value: result.value,
+ requestDigest: executable.command.need.requestDigest,
+ fulfiller: executable.providerId,
+ conformance: result.conformance,
+ delivery: result.delivery,
+ metadata: result.metadata,
+ ...(validation === undefined ? {} : { validation }),
+ } as const;
+ return { ...content, id: `event:${digestOf(content)}` };
+ }
+
+ async #completedOperation(
+ state: BuildState,
+ executable: Extract<Executable, { readonly providerId: string }>,
+ snapshot: OperationSnapshot,
+ expectedOperation: string,
+ ): Promise<RuntimeExecutionResult> {
+ verifyOperationSnapshot(snapshot);
+ if (snapshot.id !== expectedOperation) {
+ throw new Error(`OperationStore returned ${snapshot.id} for ${expectedOperation}`);
+ }
+ if (snapshot.status === "completed" && snapshot.completion !== undefined) {
+ return {
+ status: "completed",
+ event: await this.#providerEvent(state, executable, snapshot.completion),
+ };
+ }
+ if (snapshot.status === "failed") {
+ throw new Error(`Operation ${snapshot.id} failed: ${snapshot.failure?.code ?? "UNKNOWN"}`);
+ }
+ return { status: "pending", operation: snapshot.id };
+ }
+
+ async #executeEndpoint(
+ state: BuildState,
+ executable: Extract<Executable, { readonly providerId: string }>,
+ context: RuntimeExecutionContext,
+ ): Promise<RuntimeExecutionResult> {
+ if (executable.registration.kind !== "endpoint") throw new Error("Provider is not a recoverable Endpoint");
+ const operations = this.operations;
+ if (operations === undefined) throw new Error("recoverable Provider Endpoint requires OperationStore");
+ const runtimeClosure = this.providers.runtimeClosureDigest();
+ if (runtimeClosure === undefined) throw new Error("recoverable Provider Endpoint requires Runtime Closure");
+ const implementation = executable.registration.runtimeImplementation;
+ if (implementation === undefined) throw new Error("recoverable Provider Endpoint has no implementation identity");
+ const identity = sealOperationIdentity({
+ build: context.build,
+ command: executable.command.id,
+ endpoint: executable.providerId,
+ implementationDigest: implementation.digest,
+ runtimeClosure,
+ requestDigest: executable.command.need.requestDigest,
+ attempt: 1,
+ });
+ const created = await operations.create(identity);
+ const current = created.snapshot;
+ verifyOperationSnapshot(current);
+ if (current.id !== identity.id) {
+ throw new Error(`OperationStore returned ${current.id} for ${identity.id}`);
+ }
+ if (current.status === "completed" || current.status === "failed") {
+ return await this.#completedOperation(state, executable, current, identity.id);
+ }
+ const endpointContext = {
+ command: structuredClone(executable.command),
+ need: structuredClone(executable.command.need),
+ artifacts: this.artifacts,
+ operation: structuredClone(identity),
+ };
+ const outcome = created.status === "created"
+ ? await executable.registration.endpoint.start(endpointContext)
+ : await executable.registration.endpoint.resume({
+ ...endpointContext,
+ checkpoint: current.status === "pending" ? structuredClone(current.checkpoint) : undefined,
+ });
+ if (outcome.status === "pending") {
+ const written = await operations.compareAndSwap(identity.id, current.revision, {
+ status: "pending",
+ checkpoint: outcome.checkpoint,
+ });
+ return await this.#completedOperation(
+ state,
+ executable,
+ written.status === "stored" ? written.snapshot : written.current,
+ identity.id,
+ );
+ }
+ const result: ProviderHandlerResult = {
+ ...outcome.result,
+ metadata: {
+ endpoint: structuredClone(outcome.result.metadata),
+ runtime: {
+ operation: identity.id,
+ submissionKey: identity.submissionKey,
+ closure: runtimeClosure,
+ implementation: implementation.digest,
+ },
},
};
+ const written = await operations.compareAndSwap(identity.id, current.revision, {
+ status: "completed",
+ completion: result,
+ });
+ return await this.#completedOperation(
+ state,
+ executable,
+ written.status === "stored" ? written.snapshot : written.current,
+ identity.id,
+ );
}
- async #execute(executable: Executable): Promise<BuildEvent> {
+ async #execute(
+ state: BuildState,
+ executable: Executable,
+ context?: RuntimeExecutionContext,
+ ): Promise<RuntimeExecutionResult> {
if (!("providerId" in executable)) {
const result = (await executable.run()) as ProducerHandlerResult;
- return {
+ const producer = resolveProducer(state.program.closure, executable.command.producer);
+ const validations: Record<string, NonNullable<Awaited<ReturnType<typeof validateValue>>>> = {};
+ for (const port of producer.outputs) {
+ const value = result.outputs[port.name];
+ if (value === undefined) continue;
+ const validation = await validateValue(state.program.closure, port.type, value, this.validators);
+ if (validation !== undefined) validations[port.name] = validation;
+ }
+ const content = {
kind: "producer-completed",
- id: `event:${digestOf({
- kind: "producer-completed",
- command: executable.command.id,
- result,
- })}`,
command: executable.command.id,
outputs: result.outputs,
needs: result.needs,
+ validations,
+ } as const;
+ return {
+ status: "completed",
+ event: { ...content, id: `event:${digestOf(content)}` },
};
}
+ if (executable.registration.kind === "endpoint") {
+ if (context === undefined) throw new Error("recoverable Endpoint execution requires a stable Build id");
+ return await this.#executeEndpoint(state, executable, context);
+ }
+ const result = await executable.registration.handler({
+ command: structuredClone(executable.command),
+ need: structuredClone(executable.command.need),
+ artifacts: this.artifacts,
+ });
+ return { status: "completed", event: await this.#providerEvent(state, executable, result) };
+ }
- const result = (await executable.run()) as ProviderHandlerResult;
+ /** Regenerate Core commands, then classify only what this Host can execute. */
+ prepare(initial: BuildState): RuntimePreparation {
+ const transition = reduce(initial);
+ const state = transition.state;
+ if (state.status === "complete" || state.status === "failed") {
+ return { state, runnable: [], blocked: [] };
+ }
+ const classifications = transition.commands.map((command) => ({
+ command,
+ ...this.#classify(state, command),
+ }));
return {
- kind: "need-fulfilled",
- id: `event:${digestOf({
- kind: "need-fulfilled",
- command: executable.command.id,
- result,
- })}`,
- command: executable.command.id,
- value: result.value,
- requestDigest: executable.command.need.requestDigest,
- fulfiller: executable.providerId,
- conformance: result.conformance,
- delivery: result.delivery,
- metadata: result.metadata,
+ state,
+ runnable: classifications.flatMap(({ executable }) => executable === undefined ? [] : [{
+ command: executable.command,
+ lane: executable.lane,
+ maxConcurrency: executable.maxConcurrency,
+ }]),
+ blocked: classifications
+ .map((item) => item.blocked)
+ .filter((item): item is BlockedCommand => item !== undefined),
};
}
- async run(initial: BuildState): Promise<DriverRunResult> {
+ /** Execute one command regenerated from trusted state; callers never supply serialized command content. */
+ async executeCommand(
+ initial: BuildState,
+ commandId: string,
+ context: RuntimeExecutionContext,
+ ): Promise<RuntimeExecutionResult> {
+ const prepared = this.prepare(initial);
+ const descriptor = prepared.runnable.find((item) => item.command.id === commandId);
+ if (descriptor === undefined) throw new Error(`command ${commandId} is not currently executable`);
+ const classified = this.#classify(prepared.state, descriptor.command);
+ if (classified.executable === undefined) throw new Error(`command ${commandId} is no longer executable`);
+ return await this.#execute(prepared.state, classified.executable, context);
+ }
+
+ async run(initial: BuildState, context?: RuntimeExecutionContext): Promise<DriverRunResult> {
let state = initial;
const journal: DriverJournalEntry[] = [];
@@ -216,7 +428,17 @@ export class NodeDriver {
}
try {
- const event = await this.#execute(selected);
+ const execution = await this.#execute(state, selected, context);
+ if (execution.status === "pending") {
+ journal.push({
+ command: selected.command.id,
+ kind: selected.command.kind,
+ status: "pending",
+ operation: execution.operation,
+ });
+ return { status: "paused", state, journal, blocked: [] };
+ }
+ const event = execution.event;
const accepted = reduce(state, event);
state = accepted.state;
journal.push({
diff --git a/packages/driver-node/src/manifest.ts b/packages/driver-node/src/manifest.ts
index 12d5fa45..2cb1e2c0 100644
--- a/packages/driver-node/src/manifest.ts
+++ b/packages/driver-node/src/manifest.ts
@@ -1,289 +1,13 @@
import { readFile } from "node:fs/promises";
-import { canonicalize, createResolvedClosure, isDigest } from "@svml/core";
-import type {
- CapabilityDeclaration,
- CapabilityRef,
- Digest,
- ImplementationRef,
- ModuleDependency,
- ModuleManifest,
- ModuleRef,
- NeedPortDeclaration,
- ObjectFieldSchema,
- PortDeclaration,
- ProducerDeclaration,
- ResolvedModuleClosure,
- SurfaceDeclaration,
- TypeDeclaration,
- TypeRef,
- ValueSchema,
+import { createResolvedClosure } from "@svml/core";
+import {
+ parseModuleManifest,
+ parseModuleManifestText,
} from "@svml/protocol";
+import type { ModuleManifest, ResolvedModuleClosure } from "@svml/protocol";
-function object(value: unknown, path: string): Record<string, unknown> {
- if (value === null || Array.isArray(value) || typeof value !== "object") {
- throw new Error(`${path} must be an object`);
- }
- return value as Record<string, unknown>;
-}
-
-function array(value: unknown, path: string): unknown[] {
- if (!Array.isArray(value)) throw new Error(`${path} must be an array`);
- return value;
-}
-
-function string(value: unknown, path: string): string {
- if (typeof value !== "string" || value.length === 0) throw new Error(`${path} must be a string`);
- return value;
-}
-
-function boolean(value: unknown, path: string): boolean {
- if (typeof value !== "boolean") throw new Error(`${path} must be a boolean`);
- return value;
-}
-
-function number(value: unknown, path: string): number {
- if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${path} must be a number`);
- return value;
-}
-
-function digest(value: unknown, path: string): Digest {
- const parsed = string(value, path);
- if (!isDigest(parsed)) throw new Error(`${path} must be a sha256 digest`);
- return parsed;
-}
-
-function moduleRef(value: unknown, path: string): ModuleRef {
- const parsed = object(value, path);
- return {
- name: string(parsed.name, `${path}.name`),
- version: string(parsed.version, `${path}.version`),
- };
-}
-
-function typeRef(value: unknown, path: string): TypeRef {
- const parsed = object(value, path);
- return {
- module: moduleRef(parsed.module, `${path}.module`),
- name: string(parsed.name, `${path}.name`),
- };
-}
-
-function capabilityRef(value: unknown, path: string): CapabilityRef {
- const parsed = object(value, path);
- return {
- module: moduleRef(parsed.module, `${path}.module`),
- name: string(parsed.name, `${path}.name`),
- };
-}
-
-function optionalNumber(
- parsed: Record<string, unknown>,
- name: string,
- path: string,
-): { readonly [key: string]: number } {
- return parsed[name] === undefined ? {} : { [name]: number(parsed[name], `${path}.${name}`) };
-}
-
-function valueSchema(value: unknown, path: string): ValueSchema {
- const parsed = object(value, path);
- const kind = string(parsed.kind, `${path}.kind`);
- switch (kind) {
- case "null":
- case "boolean":
- return { kind };
- case "number":
- return {
- kind,
- ...(parsed.integer === undefined ? {} : { integer: boolean(parsed.integer, `${path}.integer`) }),
- ...optionalNumber(parsed, "minimum", path),
- ...optionalNumber(parsed, "maximum", path),
- } as ValueSchema;
- case "string":
- return {
- kind,
- ...(parsed.enum === undefined
- ? {}
- : { enum: array(parsed.enum, `${path}.enum`).map((item, index) => string(item, `${path}.enum[${index}]`)) }),
- ...optionalNumber(parsed, "minLength", path),
- ...optionalNumber(parsed, "maxLength", path),
- } as ValueSchema;
- case "literal":
- return { kind, value: canonicalize(parsed.value) };
- case "array":
- return {
- kind,
- items: valueSchema(parsed.items, `${path}.items`),
- ...optionalNumber(parsed, "minItems", path),
- ...optionalNumber(parsed, "maxItems", path),
- } as ValueSchema;
- case "object": {
- const rawFields = object(parsed.fields, `${path}.fields`);
- const fields: Record<string, ObjectFieldSchema> = {};
- for (const [name, rawField] of Object.entries(rawFields)) {
- const field = object(rawField, `${path}.fields.${name}`);
- Object.defineProperty(fields, name, {
- value: {
- schema: valueSchema(field.schema, `${path}.fields.${name}.schema`),
- ...(field.optional === undefined
- ? {}
- : { optional: boolean(field.optional, `${path}.fields.${name}.optional`) }),
- },
- enumerable: true,
- configurable: true,
- writable: true,
- });
- }
- return {
- kind,
- fields,
- ...(parsed.allowUnknown === undefined
- ? {}
- : { allowUnknown: boolean(parsed.allowUnknown, `${path}.allowUnknown`) }),
- };
- }
- case "oneOf":
- return {
- kind,
- variants: array(parsed.variants, `${path}.variants`).map((item, index) =>
- valueSchema(item, `${path}.variants[${index}]`),
- ),
- };
- case "blob":
- return {
- kind,
- ...(parsed.mediaTypes === undefined
- ? {}
- : {
- mediaTypes: array(parsed.mediaTypes, `${path}.mediaTypes`).map((item, index) =>
- string(item, `${path}.mediaTypes[${index}]`),
- ),
- }),
- ...optionalNumber(parsed, "maxBytes", path),
- } as ValueSchema;
- default:
- throw new Error(`${path}.kind ${kind} is unsupported`);
- }
-}
-
-function dependency(value: unknown, path: string): ModuleDependency {
- const parsed = object(value, path);
- return {
- module: moduleRef(parsed.module, `${path}.module`),
- digest: digest(parsed.digest, `${path}.digest`),
- };
-}
-
-function typeDeclaration(value: unknown, path: string): TypeDeclaration {
- const parsed = object(value, path);
- return {
- name: string(parsed.name, `${path}.name`),
- schema: valueSchema(parsed.schema, `${path}.schema`),
- ...(parsed.description === undefined
- ? {}
- : { description: string(parsed.description, `${path}.description`) }),
- };
-}
-
-function capabilityDeclaration(value: unknown, path: string): CapabilityDeclaration {
- const parsed = object(value, path);
- return {
- name: string(parsed.name, `${path}.name`),
- returns: typeRef(parsed.returns, `${path}.returns`),
- ...(parsed.description === undefined
- ? {}
- : { description: string(parsed.description, `${path}.description`) }),
- };
-}
-
-function port(value: unknown, path: string): PortDeclaration {
- const parsed = object(value, path);
- return {
- name: string(parsed.name, `${path}.name`),
- type: typeRef(parsed.type, `${path}.type`),
- };
-}
-
-function needPort(value: unknown, path: string): NeedPortDeclaration {
- const parsed = object(value, path);
- return {
- name: string(parsed.name, `${path}.name`),
- capability: capabilityRef(parsed.capability, `${path}.capability`),
- returns: typeRef(parsed.returns, `${path}.returns`),
- };
-}
-
-function implementation(value: unknown, path: string): ImplementationRef {
- const parsed = object(value, path);
- return {
- kind: string(parsed.kind, `${path}.kind`),
- locator: string(parsed.locator, `${path}.locator`),
- digest: digest(parsed.digest, `${path}.digest`),
- };
-}
-
-function producer(value: unknown, path: string): ProducerDeclaration {
- const parsed = object(value, path);
- return {
- name: string(parsed.name, `${path}.name`),
- inputs: array(parsed.inputs, `${path}.inputs`).map((item, index) =>
- port(item, `${path}.inputs[${index}]`),
- ),
- outputs: array(parsed.outputs, `${path}.outputs`).map((item, index) =>
- port(item, `${path}.outputs[${index}]`),
- ),
- needs: array(parsed.needs, `${path}.needs`).map((item, index) =>
- needPort(item, `${path}.needs[${index}]`),
- ),
- implementation: implementation(parsed.implementation, `${path}.implementation`),
- };
-}
-
-function surface(value: unknown, path: string): SurfaceDeclaration {
- const parsed = object(value, path);
- const mode = string(parsed.mode, `${path}.mode`);
- if (mode !== "raw" && mode !== "structured") {
- throw new Error(`${path}.mode must be raw or structured`);
- }
- return {
- name: string(parsed.name, `${path}.name`),
- tag: string(parsed.tag, `${path}.tag`),
- mode,
- outputs: array(parsed.outputs, `${path}.outputs`).map((item, index) =>
- typeRef(item, `${path}.outputs[${index}]`),
- ),
- implementation: implementation(parsed.implementation, `${path}.implementation`),
- };
-}
-
-export function parseModuleManifest(value: unknown): ModuleManifest {
- const parsed = object(canonicalize(value), "$manifest");
- if (parsed.format !== "svml.module@0") throw new Error("$manifest.format must be svml.module@0");
- return {
- format: "svml.module@0",
- name: string(parsed.name, "$manifest.name"),
- version: string(parsed.version, "$manifest.version"),
- dependencies: array(parsed.dependencies, "$manifest.dependencies").map((item, index) =>
- dependency(item, `$manifest.dependencies[${index}]`),
- ),
- types: array(parsed.types, "$manifest.types").map((item, index) =>
- typeDeclaration(item, `$manifest.types[${index}]`),
- ),
- capabilities: array(parsed.capabilities, "$manifest.capabilities").map((item, index) =>
- capabilityDeclaration(item, `$manifest.capabilities[${index}]`),
- ),
- surfaces: array(parsed.surfaces, "$manifest.surfaces").map((item, index) =>
- surface(item, `$manifest.surfaces[${index}]`),
- ),
- producers: array(parsed.producers, "$manifest.producers").map((item, index) =>
- producer(item, `$manifest.producers[${index}]`),
- ),
- };
-}
-
-export function parseModuleManifestText(text: string): ModuleManifest {
- return parseModuleManifest(JSON.parse(text) as unknown);
-}
+export { parseModuleManifest, parseModuleManifestText } from "@svml/protocol";
export async function loadModuleManifest(path: string): Promise<ModuleManifest> {
return parseModuleManifestText(await readFile(path, "utf8"));
diff --git a/packages/driver-node/src/registry.ts b/packages/driver-node/src/registry.ts
index 47cfee6c..6832d3fa 100644
--- a/packages/driver-node/src/registry.ts
+++ b/packages/driver-node/src/registry.ts
@@ -5,13 +5,23 @@ import type {
ProducerRef,
TypeRef,
} from "@svml/protocol";
+import { isDigest } from "@svml/protocol";
+import {
+ RuntimeModuleRegistry,
+ runtimeProvider,
+ verifyRuntimeClosure,
+} from "@svml/runtime";
+import type { ResolveRuntimeProfileOptions, RuntimeClosure } from "@svml/runtime";
import type {
ProducerHandler,
ProducerRegistration,
+ ProviderEndpoint,
ProviderHandler,
ProviderRegistration,
ProviderResolution,
+ RuntimeProviderImplementation,
+ SchedulingHint,
} from "./types.js";
function moduleKey(ref: { readonly name: string; readonly version: string }): string {
@@ -27,6 +37,17 @@ function sameRef(
&& left.name === right.name;
}
+function verifyScheduling(scheduling: SchedulingHint | undefined): void {
+ if (scheduling === undefined) return;
+ if (scheduling.lane !== undefined && scheduling.lane.trim().length === 0) {
+ throw new Error("scheduling lane must not be empty");
+ }
+ if (scheduling.maxConcurrency !== undefined
+ && (!Number.isSafeInteger(scheduling.maxConcurrency) || scheduling.maxConcurrency < 1)) {
+ throw new Error("scheduling maxConcurrency must be a positive safe integer");
+ }
+}
+
export function producerRegistryKey(ref: ProducerRef): string {
return `${moduleKey(ref.module)}#${ref.name}`;
}
@@ -46,10 +67,12 @@ export class HostRegistry {
producer: ProducerRef,
implementationDigest: Digest,
handler: ProducerHandler,
+ options: { readonly scheduling?: SchedulingHint } = {},
): void {
const key = producerRegistryKey(producer);
if (this.#producers.has(key)) throw new Error(`producer ${key} is already registered`);
- this.#producers.set(key, { producer, implementationDigest, handler });
+ verifyScheduling(options.scheduling);
+ this.#producers.set(key, { producer, implementationDigest, handler, ...options });
}
producer(ref: ProducerRef): ProducerRegistration | undefined {
@@ -57,11 +80,17 @@ export class HostRegistry {
}
}
-type ProviderOptions = { readonly supports?: (need: Need) => boolean };
+type ProviderOptions = {
+ readonly supports?: (need: Need) => boolean;
+ readonly scheduling?: SchedulingHint;
+ readonly runtimeImplementation?: RuntimeProviderImplementation;
+};
export class ProviderRegistry {
readonly #registrations: ProviderRegistration[] = [];
readonly #bindings = new Map<string, string>();
+ readonly #runtimeScheduling = new Map<string, SchedulingHint>();
+ #runtimeClosure: Digest | undefined;
registerProvider(
id: string,
@@ -71,10 +100,46 @@ export class ProviderRegistry {
options: ProviderOptions = {},
): void {
if (!id.trim()) throw new Error("provider id must not be empty");
+ verifyScheduling(options.scheduling);
+ if (options.runtimeImplementation !== undefined) {
+ if (!isDigest(options.runtimeImplementation.digest)) {
+ throw new Error("Provider runtime implementation digest is invalid");
+ }
+ const facet = options.runtimeImplementation.facet;
+ if (!facet.name.trim() || !facet.module.name.trim() || !facet.module.version.trim()) {
+ throw new Error("Provider runtime implementation facet is invalid");
+ }
+ }
+ const duplicate = this.#registrations.some((candidate) =>
+ candidate.id === id && sameRef(candidate.capability, capability));
+ if (duplicate) throw new Error(`provider ${id} already registers ${providerCapabilityKey(capability)}`);
+ this.#registrations.push({ kind: "handler", id, capability, returns, handler, ...options });
+ }
+
+ registerProviderEndpoint(
+ id: string,
+ capability: CapabilityRef,
+ returns: TypeRef,
+ endpoint: ProviderEndpoint,
+ options: ProviderOptions = {},
+ ): void {
+ if (!id.trim()) throw new Error("provider id must not be empty");
+ verifyScheduling(options.scheduling);
+ if (options.runtimeImplementation === undefined || !isDigest(options.runtimeImplementation.digest)) {
+ throw new Error("recoverable Provider Endpoint requires a valid Runtime implementation identity");
+ }
+ const facet = options.runtimeImplementation.facet;
+ if (!facet.name.trim() || !facet.module.name.trim() || !facet.module.version.trim()) {
+ throw new Error("Provider runtime implementation facet is invalid");
+ }
const duplicate = this.#registrations.some((candidate) =>
candidate.id === id && sameRef(candidate.capability, capability));
if (duplicate) throw new Error(`provider ${id} already registers ${providerCapabilityKey(capability)}`);
- this.#registrations.push({ id, capability, returns, handler, ...options });
+ this.#registrations.push({ kind: "endpoint", id, capability, returns, endpoint, ...options });
+ }
+
+ runtimeClosureDigest(): Digest | undefined {
+ return this.#runtimeClosure;
}
bind(capability: CapabilityRef, providerId: string): void {
@@ -86,6 +151,47 @@ export class ProviderRegistry {
this.#bindings.set(key, providerId);
}
+ /** Bind only implementation-verified Endpoint instances from one locked Runtime Closure. */
+ applyRuntimeClosure(
+ closure: RuntimeClosure,
+ modules: RuntimeModuleRegistry,
+ options: ResolveRuntimeProfileOptions = {},
+ ): void {
+ verifyRuntimeClosure(closure);
+ modules.verifyClosure(closure, options);
+ if (this.#runtimeClosure !== undefined && this.#runtimeClosure !== closure.digest) {
+ throw new Error("Provider Registry is already bound to another Runtime Closure");
+ }
+ const pending: { readonly key: string; readonly endpoint: string; readonly scheduling: SchedulingHint }[] = [];
+ for (const binding of closure.providers) {
+ const endpoint = runtimeProvider(closure, binding.endpoint);
+ if (endpoint === undefined) throw new Error(`Runtime Endpoint ${binding.endpoint} is unavailable`);
+ const registration = this.#registrations.find((candidate) =>
+ candidate.id === endpoint.id
+ && sameRef(candidate.capability, binding.capability)
+ && sameRef(candidate.returns, binding.returns));
+ if (registration === undefined) {
+ throw new Error(`Provider ${endpoint.id} is not registered for ${providerCapabilityKey(binding.capability)}`);
+ }
+ const implementation = registration.runtimeImplementation;
+ if (implementation === undefined
+ || implementation.digest !== endpoint.implementation.digest
+ || !sameRef(implementation.facet, endpoint.facet)) {
+ throw new Error(`Provider ${endpoint.id} implementation does not match the Runtime Closure`);
+ }
+ pending.push({
+ key: providerCapabilityKey(binding.capability),
+ endpoint: endpoint.id,
+ scheduling: { lane: endpoint.lane, maxConcurrency: endpoint.maxConcurrency },
+ });
+ }
+ for (const item of pending) {
+ this.#bindings.set(item.key, item.endpoint);
+ this.#runtimeScheduling.set(item.endpoint, item.scheduling);
+ }
+ this.#runtimeClosure = closure.digest;
+ }
+
resolve(need: Need): ProviderResolution {
const key = providerCapabilityKey(need.capability);
const bound = this.#bindings.get(key);
@@ -95,9 +201,15 @@ export class ProviderRegistry {
&& (registration.supports?.(need) ?? true));
if (bound !== undefined) {
const registration = registrations.find((candidate) => candidate.id === bound);
+ const scheduling = registration === undefined
+ ? undefined
+ : this.#runtimeScheduling.get(registration.id) ?? registration.scheduling;
return registration === undefined
? { status: "missing", providerId: bound }
- : { status: "resolved", registration };
+ : {
+ status: "resolved",
+ registration: scheduling === undefined ? registration : { ...registration, scheduling },
+ };
}
if (registrations.length === 0) return { status: "missing" };
if (registrations.length > 1) {
@@ -106,7 +218,12 @@ export class ProviderRegistry {
providerIds: registrations.map((registration) => registration.id).sort(),
};
}
- return { status: "resolved", registration: registrations[0]! };
+ const registration = registrations[0]!;
+ const scheduling = this.#runtimeScheduling.get(registration.id) ?? registration.scheduling;
+ return {
+ status: "resolved",
+ registration: scheduling === undefined ? registration : { ...registration, scheduling },
+ };
}
providers(capability: CapabilityRef): readonly ProviderRegistration[] {
diff --git a/packages/driver-node/src/types.ts b/packages/driver-node/src/types.ts
index 0b64f117..9f34691a 100644
--- a/packages/driver-node/src/types.ts
+++ b/packages/driver-node/src/types.ts
@@ -15,6 +15,10 @@ import type {
CapabilityRef,
TypedRecord,
} from "@svml/protocol";
+import type {
+ OperationIdentity,
+ RuntimeFacetRef,
+} from "@svml/runtime";
export type ProducerHandlerResult = {
readonly outputs: Readonly<Record<string, StoredValue>>;
@@ -49,6 +53,25 @@ export type ProviderHandler = (
context: ProviderHandlerContext,
) => ProviderHandlerResult | Promise<ProviderHandlerResult>;
+export type ProviderEndpointResult =
+ | { readonly status: "pending"; readonly checkpoint: CanonicalValue }
+ | { readonly status: "completed"; readonly result: ProviderHandlerResult };
+
+export type ProviderEndpointStartContext = ProviderHandlerContext & {
+ readonly operation: OperationIdentity;
+};
+
+export type ProviderEndpointResumeContext = ProviderEndpointStartContext & {
+ /** Undefined means the process stopped after intent was journaled but before a checkpoint existed. */
+ readonly checkpoint: CanonicalValue | undefined;
+};
+
+export type ProviderEndpoint = {
+ start(context: ProviderEndpointStartContext): ProviderEndpointResult | Promise<ProviderEndpointResult>;
+ resume(context: ProviderEndpointResumeContext): ProviderEndpointResult | Promise<ProviderEndpointResult>;
+ cancel?(context: ProviderEndpointResumeContext): void | Promise<void>;
+};
+
export type ArtifactStore = {
put(bytes: Uint8Array, mediaType: string): Promise<BlobRef>;
get(digest: Digest): Promise<Uint8Array | undefined>;
@@ -58,8 +81,9 @@ export type ArtifactStore = {
export type DriverJournalEntry = {
readonly command: string;
readonly kind: CoreCommand["kind"];
- readonly status: "completed" | "blocked" | "error";
+ readonly status: "completed" | "pending" | "blocked" | "error";
readonly event?: string;
+ readonly operation?: Digest;
readonly message?: string;
};
@@ -69,7 +93,9 @@ export type BlockedCommand = {
| "missing-producer"
| "implementation-mismatch"
| "missing-provider"
- | "ambiguous-provider";
+ | "ambiguous-provider"
+ | "missing-operation-store"
+ | "missing-runtime-closure";
readonly subject: string;
};
@@ -80,20 +106,38 @@ export type DriverRunResult = {
readonly blocked: readonly BlockedCommand[];
};
+/** Endpoint/implementation scheduling metadata; it never changes Core demand or command identity. */
+export type SchedulingHint = {
+ readonly lane?: string;
+ readonly maxConcurrency?: number;
+};
+
+export type RuntimeProviderImplementation = {
+ readonly facet: RuntimeFacetRef;
+ readonly digest: Digest;
+};
+
export type ProducerRegistration = {
readonly producer: ProducerRef;
readonly implementationDigest: Digest;
readonly handler: ProducerHandler;
+ readonly scheduling?: SchedulingHint;
};
-export type ProviderRegistration = {
+type ProviderRegistrationBase = {
readonly id: string;
readonly capability: CapabilityRef;
readonly returns: TypeRef;
- readonly handler: ProviderHandler;
readonly supports?: (need: Need) => boolean;
+ readonly scheduling?: SchedulingHint;
+ readonly runtimeImplementation?: RuntimeProviderImplementation;
};
+export type ProviderRegistration = ProviderRegistrationBase & (
+ | { readonly kind: "handler"; readonly handler: ProviderHandler }
+ | { readonly kind: "endpoint"; readonly endpoint: ProviderEndpoint }
+);
+
export type ProviderResolution =
| { readonly status: "resolved"; readonly registration: ProviderRegistration }
| { readonly status: "missing"; readonly providerId?: string }
diff --git a/packages/driver-node/test/scheduler.test.ts b/packages/driver-node/test/scheduler.test.ts
new file mode 100644
index 00000000..aed11831
--- /dev/null
+++ b/packages/driver-node/test/scheduler.test.ts
@@ -0,0 +1,619 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ HostRegistry,
+ NodeDriver,
+ parseBuildState,
+ ProviderRegistry,
+ serializeBuildState,
+} from "@svml/driver-node";
+import type {
+ ProviderEndpoint,
+ RuntimeProviderImplementation,
+} from "@svml/driver-node";
+import {
+ LocalBuildScheduler,
+ MemoryBuildStore,
+ MemoryOperationStore,
+ RuntimeModuleRegistry,
+ localSchedulerOptionsFromClosure,
+ resolveRuntimeProfile,
+ sealRuntimeProfile,
+} from "@svml/runtime";
+import type {
+ OperationStore,
+ RuntimeModuleManifest,
+} from "@svml/runtime";
+import type { Digest } from "@svml/protocol";
+import {
+ createResolvedClosure,
+ digestOf,
+ link,
+ sealBuildRequest,
+ sealCompiledGraph,
+ sealRecord,
+ sealTypedModule,
+ start,
+} from "@svml/core";
+
+import {
+ capabilities,
+ createGreetingBuild,
+ implementationDigests,
+ manifest,
+ producers,
+ types,
+} from "../../core/test/greeting-fixture.js";
+
+function createParallelGreetingBuild() {
+ const closure = createResolvedClosure([manifest]);
+ const authored = sealRecord({
+ id: "intent:root",
+ type: types.intent,
+ value: { kind: "inline", value: { name: "Ada" } },
+ conformance: "exact",
+ origin: {
+ kind: "authored" as const,
+ sourceDigest: digestOf("source:parallel-greeting"),
+ frontendClosureDigest: digestOf("frontend:parallel-greeting"),
+ },
+ });
+ const program = link(closure, [sealTypedModule({
+ id: "author:parallel-greeting",
+ closureDigest: closure.digest,
+ records: [authored],
+ })]);
+ const graph = sealCompiledGraph({
+ program: program.semanticDigest,
+ outputs: [
+ {
+ id: "prompt",
+ type: types.prompt,
+ primary: "make-prompt",
+ candidates: ["make-prompt"],
+ semanticInputs: [{ kind: "record", id: "intent:root" }],
+ },
+ {
+ id: "generated-a",
+ type: types.generated,
+ primary: "generate-a",
+ candidates: ["generate-a"],
+ semanticInputs: [{ kind: "logical-output", id: "prompt" }],
+ },
+ {
+ id: "generated-b",
+ type: types.generated,
+ primary: "generate-b",
+ candidates: ["generate-b"],
+ semanticInputs: [{ kind: "logical-output", id: "prompt" }],
+ },
+ ],
+ candidates: [
+ {
+ id: "make-prompt",
+ output: "prompt",
+ root: { kind: "operation", result: { kind: "operation-result", operation: "make-prompt" } },
+ fidelity: "exact",
+ },
+ {
+ id: "generate-a",
+ output: "generated-a",
+ root: { kind: "operation", result: { kind: "operation-result", operation: "generate-a" } },
+ fidelity: "exact",
+ },
+ {
+ id: "generate-b",
+ output: "generated-b",
+ root: { kind: "operation", result: { kind: "operation-result", operation: "generate-b" } },
+ fidelity: "exact",
+ },
+ ],
+ operations: [
+ {
+ id: "make-prompt",
+ producer: producers.makePrompt,
+ inputs: { intent: { kind: "record", id: "intent:root" } },
+ result: { kind: "output", name: "prompt", record: "prompt:root" },
+ },
+ {
+ id: "generate-a",
+ producer: producers.requestText,
+ inputs: { prompt: { kind: "logical-output", id: "prompt" } },
+ result: {
+ kind: "need",
+ name: "generation",
+ id: "need:generation-a",
+ record: "generated:a",
+ accepts: "exact",
+ },
+ },
+ {
+ id: "generate-b",
+ producer: producers.requestText,
+ inputs: { prompt: { kind: "logical-output", id: "prompt" } },
+ result: {
+ kind: "need",
+ name: "generation",
+ id: "need:generation-b",
+ record: "generated:b",
+ accepts: "exact",
+ },
+ },
+ ],
+ });
+ return start(program, graph, sealBuildRequest({
+ graph: graph.id,
+ targets: [
+ { output: "generated-a", accepts: "exact" },
+ { output: "generated-b", accepts: "exact" },
+ ],
+ bindings: [],
+ }));
+}
+
+function configuredExecutor(options: {
+ readonly lane: string;
+ readonly defaultConcurrency: number;
+ readonly observe: (active: number) => void;
+ readonly runtimeImplementation?: RuntimeProviderImplementation;
+ readonly providerId?: string;
+}) {
+ const registry = new HostRegistry();
+ const providers = new ProviderRegistry();
+ registerGreetingProducers(registry);
+ let active = 0;
+ let calls = 0;
+ providers.registerProvider(
+ options.providerId ?? "fixture.seedance",
+ capabilities.generation,
+ types.generated,
+ async () => {
+ calls += 1;
+ active += 1;
+ options.observe(active);
+ await new Promise<void>((resolve) => setTimeout(resolve, 10));
+ active -= 1;
+ return {
+ value: { kind: "inline", value: `Generated ${calls}` },
+ conformance: "exact",
+ delivery: "executed",
+ metadata: {},
+ };
+ },
+ {
+ scheduling: {
+ lane: options.lane,
+ maxConcurrency: options.defaultConcurrency,
+ },
+ ...(options.runtimeImplementation === undefined
+ ? {}
+ : { runtimeImplementation: options.runtimeImplementation }),
+ },
+ );
+ return { executor: new NodeDriver({ registry, providers }), providers, getCalls: () => calls };
+}
+
+function registerGreetingProducers(registry: HostRegistry): void {
+ registry.registerProducer(producers.makePrompt, implementationDigests.makePrompt, ({ inputs }) => {
+ const intent = inputs.intent;
+ assert.equal(intent?.value.kind, "inline");
+ const name = (intent.value.value as { readonly name: string }).name;
+ return { outputs: { prompt: { kind: "inline", value: `Greet ${name}` } }, needs: {} };
+ });
+ registry.registerProducer(producers.requestText, implementationDigests.requestText, ({ inputs }) => {
+ const prompt = inputs.prompt;
+ assert.equal(prompt?.value.kind, "inline");
+ return { outputs: {}, needs: { generation: { prompt: prompt.value.value } } };
+ });
+ registry.registerProducer(producers.assemble, implementationDigests.assemble, ({ inputs }) => {
+ const generated = inputs.generated;
+ assert.equal(generated?.value.kind, "inline");
+ return {
+ outputs: { document: { kind: "inline", value: { text: generated.value.value } } },
+ needs: {},
+ };
+ });
+}
+
+const runtimeModule = { name: "example.scheduler-runtime", version: "1" } as const;
+const providerFacet = { module: runtimeModule, name: "generation-endpoint" } as const;
+const providerImplementationDigest = digestOf("example.scheduler-runtime/generation-endpoint@1");
+
+function resolvedRuntime(laneLimit: number) {
+ const manifest: RuntimeModuleManifest = {
+ format: "svml.runtime-module@1",
+ name: runtimeModule.name,
+ version: runtimeModule.version,
+ facets: [
+ {
+ name: "scheduler",
+ role: "scheduler",
+ implementation: {
+ locator: "example.scheduler-runtime/scheduler",
+ digest: digestOf("example.scheduler-runtime/scheduler@1"),
+ },
+ permissions: [],
+ },
+ {
+ name: "operations",
+ role: "operation-store",
+ implementation: {
+ locator: "example.scheduler-runtime/operations",
+ digest: digestOf("example.scheduler-runtime/operations@1"),
+ },
+ permissions: [],
+ },
+ {
+ name: providerFacet.name,
+ role: "provider-endpoint",
+ implementation: {
+ locator: "example.scheduler-runtime/generation-endpoint",
+ digest: providerImplementationDigest,
+ },
+ permissions: [],
+ fulfills: [{ capability: capabilities.generation, returns: types.generated }],
+ lifecycle: "recoverable",
+ defaultConcurrency: 1,
+ },
+ ],
+ };
+ const modules = new RuntimeModuleRegistry();
+ modules.register(manifest);
+ const closure = resolveRuntimeProfile(modules, sealRuntimeProfile({
+ name: "scheduler-test",
+ instances: [
+ { id: "scheduler.local", facet: { module: runtimeModule, name: "scheduler" } },
+ { id: "operations.memory", facet: { module: runtimeModule, name: "operations" } },
+ { id: "generation.local", facet: providerFacet, lane: "provider:generation.local" },
+ ],
+ scheduler: "scheduler.local",
+ stores: { operations: "operations.memory" },
+ providers: [{
+ capability: capabilities.generation,
+ returns: types.generated,
+ endpoint: "generation.local",
+ }],
+ scheduling: {
+ maxConcurrency: 8,
+ lanes: [{ name: "provider:generation.local", maxConcurrency: laneLimit }],
+ },
+ }));
+ return { closure, modules };
+}
+
+function recoverableExecutor(
+ endpoint: ProviderEndpoint,
+ operations: OperationStore,
+ runtime = resolvedRuntime(1),
+) {
+ const registry = new HostRegistry();
+ registerGreetingProducers(registry);
+ const providers = new ProviderRegistry();
+ providers.registerProviderEndpoint(
+ "generation.local",
+ capabilities.generation,
+ types.generated,
+ endpoint,
+ {
+ runtimeImplementation: {
+ facet: providerFacet,
+ digest: providerImplementationDigest,
+ },
+ },
+ );
+ providers.applyRuntimeClosure(runtime.closure, runtime.modules);
+ return {
+ executor: new NodeDriver({ registry, providers, operations }),
+ runtime,
+ };
+}
+
+test("one local Scheduler shares a Provider lane across multiple Builds", async () => {
+ let maximumActive = 0;
+ const { executor, getCalls } = configuredExecutor({
+ lane: "seedance:fixture.account",
+ defaultConcurrency: 1,
+ observe(active) {
+ maximumActive = Math.max(maximumActive, active);
+ },
+ });
+ const scheduler = new LocalBuildScheduler(executor, { maxConcurrency: 8 });
+ const results = await scheduler.run([
+ { id: "video-a", state: createGreetingBuild() },
+ { id: "video-b", state: createGreetingBuild() },
+ ]);
+
+ assert.deepEqual(results.map((result) => result.status), ["complete", "complete"]);
+ assert.equal(getCalls(), 2);
+ assert.equal(maximumActive, 1);
+ assert.equal(results.every((result) =>
+ result.journal.some((entry) => entry.lane === "seedance:fixture.account")), true);
+});
+
+test("a Runtime Profile lane override changes parallelism without changing either Build", async () => {
+ let maximumActive = 0;
+ const lane = "seedance:fixture.account";
+ const { executor } = configuredExecutor({
+ lane,
+ defaultConcurrency: 1,
+ observe(active) {
+ maximumActive = Math.max(maximumActive, active);
+ },
+ });
+ const initial = createGreetingBuild();
+ const scheduler = new LocalBuildScheduler(executor, {
+ maxConcurrency: 8,
+ laneLimits: { [lane]: 2 },
+ });
+ const results = await scheduler.run([
+ { id: "video-a", state: initial },
+ { id: "video-b", state: initial },
+ ]);
+
+ assert.deepEqual(results.map((result) => result.status), ["complete", "complete"]);
+ assert.equal(maximumActive, 2);
+ assert.equal(results[0]?.state.request.digest, results[1]?.state.request.digest);
+});
+
+test("independent paid commands inside one Build may fill the same lane without duplicating their shared upstream", async () => {
+ let maximumActive = 0;
+ const { executor, getCalls } = configuredExecutor({
+ lane: "seedance:fixture.account",
+ defaultConcurrency: 2,
+ observe(active) {
+ maximumActive = Math.max(maximumActive, active);
+ },
+ });
+ const [result] = await new LocalBuildScheduler(executor, { maxConcurrency: 8 }).run([{
+ id: "two-shots",
+ state: createParallelGreetingBuild(),
+ }]);
+
+ assert.equal(result?.status, "complete");
+ assert.equal(getCalls(), 2);
+ assert.equal(maximumActive, 2);
+ assert.equal(result?.state.derivations.filter((item) => item.producer.name === producers.makePrompt.name).length, 1);
+ assert.equal(result?.state.receipts.length, 2);
+});
+
+test("a locked Runtime Closure assembles exact Provider code and Scheduler policy without manual bind", async () => {
+ let maximumActive = 0;
+ const { closure, modules } = resolvedRuntime(2);
+ const { executor, providers } = configuredExecutor({
+ lane: "ignored-registration-lane",
+ defaultConcurrency: 1,
+ runtimeImplementation: {
+ facet: providerFacet,
+ digest: providerImplementationDigest,
+ },
+ providerId: "generation.local",
+ observe(active) {
+ maximumActive = Math.max(maximumActive, active);
+ },
+ });
+ providers.applyRuntimeClosure(closure, modules);
+ const results = await new LocalBuildScheduler(
+ executor,
+ localSchedulerOptionsFromClosure(closure),
+ ).run([
+ { id: "video-a", state: createGreetingBuild() },
+ { id: "video-b", state: createGreetingBuild() },
+ ]);
+
+ assert.deepEqual(results.map((result) => result.status), ["complete", "complete"]);
+ assert.equal(maximumActive, 2, "the locked Profile override, not registration order, owns the lane");
+ assert.equal(results.every((result) => result.state.receipts[0]?.fulfiller === "generation.local"), true);
+});
+
+test("a same-name Provider with different implementation bytes is rejected before execution", () => {
+ const { closure, modules } = resolvedRuntime(1);
+ const { providers, getCalls } = configuredExecutor({
+ lane: "provider:generation.local",
+ defaultConcurrency: 1,
+ runtimeImplementation: {
+ facet: providerFacet,
+ digest: digestOf("tampered-provider-implementation"),
+ },
+ providerId: "generation.local",
+ observe() {},
+ });
+ assert.throws(() => providers.applyRuntimeClosure(closure, modules), /implementation does not match/u);
+ assert.equal(getCalls(), 0);
+});
+
+test("BuildStore CAS prevents two Scheduler revisions from silently overwriting each other", async () => {
+ const store = new MemoryBuildStore();
+ const initial = createGreetingBuild();
+ const created = await store.create("video", initial);
+ assert.equal(created.revision, 0);
+ const first = await store.compareAndSwap("video", 0, initial);
+ assert.equal(first.status, "stored");
+ const stale = await store.compareAndSwap("video", 0, initial);
+ assert.equal(stale.status, "conflict");
+ if (stale.status === "conflict") assert.equal(stale.current.revision, 1);
+ const read = await store.read("video");
+ assert.equal(read?.revision, 1);
+});
+
+test("a recoverable Endpoint resumes its journaled Operation after restart without submitting twice", async () => {
+ const operations = new MemoryOperationStore();
+ const runtime = resolvedRuntime(1);
+ let starts = 0;
+ let resumes = 0;
+ let submissionKey: string | undefined;
+ const endpoint: ProviderEndpoint = {
+ start({ operation }) {
+ starts += 1;
+ submissionKey = operation.submissionKey;
+ return { status: "pending", checkpoint: { remoteJob: "job-1" } };
+ },
+ resume({ operation, checkpoint }) {
+ resumes += 1;
+ assert.equal(operation.submissionKey, submissionKey);
+ assert.deepEqual(checkpoint, { remoteJob: "job-1" });
+ return {
+ status: "completed",
+ result: {
+ value: { kind: "inline", value: "Hello after restart" },
+ conformance: "exact",
+ delivery: "executed",
+ metadata: { remoteJob: "job-1" },
+ },
+ };
+ },
+ };
+
+ const firstExecutor = recoverableExecutor(endpoint, operations, runtime).executor;
+ const [first] = await new LocalBuildScheduler(
+ firstExecutor,
+ localSchedulerOptionsFromClosure(runtime.closure),
+ ).run([{ id: "video", state: createGreetingBuild() }]);
+ assert.equal(first?.status, "paused");
+ assert.equal(starts, 1);
+ assert.equal(resumes, 0);
+ assert.equal(first?.state.receipts.length, 0, "pending external work is not a Core event");
+ const pending = first?.journal.find((entry) => entry.status === "pending");
+ assert.ok(pending?.operation);
+ assert.equal((await operations.read(pending.operation))?.status, "pending");
+
+ const restored = parseBuildState(serializeBuildState(first.state));
+ const secondExecutor = recoverableExecutor(endpoint, operations, runtime).executor;
+ const [second] = await new LocalBuildScheduler(
+ secondExecutor,
+ localSchedulerOptionsFromClosure(runtime.closure),
+ ).run([{ id: "video", state: restored }]);
+
+ assert.equal(second?.status, "complete");
+ assert.equal(starts, 1, "the already journaled Operation must not call start again");
+ assert.equal(resumes, 1);
+ assert.equal((await operations.read(pending.operation))?.status, "completed");
+ const metadata = second?.state.receipts[0]?.metadata as {
+ readonly endpoint: { readonly remoteJob: string };
+ readonly runtime: {
+ readonly operation: string;
+ readonly submissionKey: string;
+ readonly closure: string;
+ readonly implementation: string;
+ };
+ };
+ assert.equal(metadata.endpoint.remoteJob, "job-1");
+ assert.equal(metadata.runtime.operation, pending.operation);
+ assert.equal(metadata.runtime.submissionKey, submissionKey);
+ assert.equal(metadata.runtime.closure, runtime.closure.digest);
+ assert.equal(metadata.runtime.implementation, providerImplementationDigest);
+});
+
+test("a crash after Operation intent but before checkpoint resumes with the same submission key", async () => {
+ const operations = new MemoryOperationStore();
+ const runtime = resolvedRuntime(1);
+ let starts = 0;
+ let resumes = 0;
+ let submissionKey: string | undefined;
+ let operationId: Digest | undefined;
+ const endpoint: ProviderEndpoint = {
+ start({ operation }) {
+ starts += 1;
+ submissionKey = operation.submissionKey;
+ operationId = operation.id;
+ throw new Error("process stopped after the remote submit");
+ },
+ resume({ operation, checkpoint }) {
+ resumes += 1;
+ assert.equal(checkpoint, undefined);
+ assert.equal(operation.submissionKey, submissionKey);
+ return {
+ status: "completed",
+ result: {
+ value: { kind: "inline", value: "Recovered by idempotency key" },
+ conformance: "exact",
+ delivery: "executed",
+ metadata: { recovered: true },
+ },
+ };
+ },
+ };
+
+ const firstExecutor = recoverableExecutor(endpoint, operations, runtime).executor;
+ const [first] = await new LocalBuildScheduler(
+ firstExecutor,
+ localSchedulerOptionsFromClosure(runtime.closure),
+ ).run([{ id: "video", state: createGreetingBuild() }]);
+ assert.equal(first?.status, "paused");
+ assert.match(first?.journal.at(-1)?.message ?? "", /process stopped/u);
+ assert.equal(starts, 1);
+ // An exception happens before the Scheduler sees the Operation id, but OperationStore already has it.
+ assert.ok(operationId);
+ assert.equal((await operations.read(operationId))?.status, "created");
+
+ const secondExecutor = recoverableExecutor(endpoint, operations, runtime).executor;
+ const [second] = await new LocalBuildScheduler(
+ secondExecutor,
+ localSchedulerOptionsFromClosure(runtime.closure),
+ ).run([{
+ id: "video",
+ state: parseBuildState(serializeBuildState(first!.state)),
+ }]);
+ assert.equal(second?.status, "complete");
+ assert.equal(starts, 1);
+ assert.equal(resumes, 1);
+});
+
+test("a completion journaled before a crash is replayed into Core without calling the Endpoint again", async () => {
+ const operations = new MemoryOperationStore();
+ const runtime = resolvedRuntime(1);
+ let starts = 0;
+ let resumes = 0;
+ let crashOnce = true;
+ const crashingStore: OperationStore = {
+ create: (identity) => operations.create(identity),
+ read: (id) => operations.read(id),
+ async compareAndSwap(id, revision, update) {
+ const result = await operations.compareAndSwap(id, revision, update);
+ if (update.status === "completed" && crashOnce) {
+ crashOnce = false;
+ throw new Error("process stopped after completion was journaled");
+ }
+ return result;
+ },
+ };
+ const endpoint: ProviderEndpoint = {
+ start() {
+ starts += 1;
+ return {
+ status: "completed",
+ result: {
+ value: { kind: "inline", value: "Journaled completion" },
+ conformance: "exact",
+ delivery: "executed",
+ metadata: { remoteJob: "job-complete" },
+ },
+ };
+ },
+ resume() {
+ resumes += 1;
+ throw new Error("a completed Operation must never resume");
+ },
+ };
+
+ const [first] = await new LocalBuildScheduler(
+ recoverableExecutor(endpoint, crashingStore, runtime).executor,
+ localSchedulerOptionsFromClosure(runtime.closure),
+ ).run([{ id: "video", state: createGreetingBuild() }]);
+ assert.equal(first?.status, "paused");
+ assert.equal(first?.state.receipts.length, 0);
+ assert.match(first?.journal.at(-1)?.message ?? "", /completion was journaled/u);
+ assert.equal(starts, 1);
+
+ const [second] = await new LocalBuildScheduler(
+ recoverableExecutor(endpoint, operations, runtime).executor,
+ localSchedulerOptionsFromClosure(runtime.closure),
+ ).run([{
+ id: "video",
+ state: parseBuildState(serializeBuildState(first!.state)),
+ }]);
+ assert.equal(second?.status, "complete");
+ assert.equal(second?.state.receipts[0]?.metadata !== undefined, true);
+ assert.equal(starts, 1);
+ assert.equal(resumes, 0);
+});
diff --git a/packages/driver-node/test/validation.test.ts b/packages/driver-node/test/validation.test.ts
new file mode 100644
index 00000000..db8b675e
--- /dev/null
+++ b/packages/driver-node/test/validation.test.ts
@@ -0,0 +1,503 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ computeModuleDigest,
+ createResolvedClosure,
+ digestOf,
+ link,
+ sealBuildRequest,
+ sealCompiledGraph,
+ sealRecord,
+ sealTypedModule,
+ start,
+ verifyRecord,
+} from "@svml/core";
+import {
+ HostRegistry,
+ NodeDriver,
+ ProviderRegistry,
+ parseBuildState,
+ parseModuleManifestText,
+ serializeBuildState,
+} from "@svml/driver-node";
+import type {
+ CapabilityRef,
+ CompiledGraph,
+ LinkedProgram,
+ ModuleManifest,
+ ProducerRef,
+ TypeRef,
+} from "@svml/protocol";
+import {
+ TypeValidationError,
+ TypeValidatorRegistry,
+ admitRecord,
+ validateValue,
+} from "@svml/validation";
+
+const contractModule = { name: "example.measurement-contract", version: "1.0.0" } as const;
+const sensorModule = { name: "example.sensor", version: "1.0.0" } as const;
+const reportModule = { name: "example.report", version: "1.0.0" } as const;
+
+const measurementType = { module: contractModule, name: "Measurement" } satisfies TypeRef;
+const reportType = { module: reportModule, name: "Report" } satisfies TypeRef;
+const measurementCapability = {
+ module: sensorModule,
+ name: "obtain-measurement",
+} satisfies CapabilityRef;
+const measureProducer = { module: sensorModule, name: "measure" } satisfies ProducerRef;
+const requestProducer = { module: sensorModule, name: "request-measurement" } satisfies ProducerRef;
+const reportProducer = { module: reportModule, name: "write-report" } satisfies ProducerRef;
+
+const validatorDigest = digestOf("example.measurement-contract/even-integer-validator@1");
+const producerDigests = {
+ measure: digestOf("example.sensor/measure@1"),
+ request: digestOf("example.sensor/request-measurement@1"),
+ report: digestOf("example.report/write-report@1"),
+};
+
+const contractManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: contractModule.name,
+ version: contractModule.version,
+ dependencies: [],
+ types: [{
+ name: measurementType.name,
+ schema: {
+ kind: "object",
+ fields: {
+ value: { schema: { kind: "number", integer: true } },
+ unit: { schema: { kind: "literal", value: "ticks" } },
+ },
+ },
+ validator: {
+ abi: "svml.type-validator@1",
+ implementation: {
+ kind: "registered",
+ locator: "example.measurement-contract/even-integer-validator",
+ digest: validatorDigest,
+ },
+ },
+ }],
+ capabilities: [],
+ surfaces: [],
+ producers: [],
+};
+
+const contractDependency = {
+ module: contractModule,
+ digest: computeModuleDigest(contractManifest),
+};
+
+const sensorManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: sensorModule.name,
+ version: sensorModule.version,
+ dependencies: [contractDependency],
+ types: [],
+ capabilities: [{ name: measurementCapability.name, returns: measurementType }],
+ surfaces: [],
+ producers: [
+ {
+ name: measureProducer.name,
+ inputs: [],
+ outputs: [{ name: "measurement", type: measurementType }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.sensor/measure",
+ digest: producerDigests.measure,
+ },
+ },
+ {
+ name: requestProducer.name,
+ inputs: [],
+ outputs: [],
+ needs: [{
+ name: "measurement",
+ capability: measurementCapability,
+ returns: measurementType,
+ }],
+ implementation: {
+ kind: "registered",
+ locator: "example.sensor/request-measurement",
+ digest: producerDigests.request,
+ },
+ },
+ ],
+};
+
+const reportManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: reportModule.name,
+ version: reportModule.version,
+ dependencies: [contractDependency],
+ types: [{ name: reportType.name, schema: { kind: "string", minLength: 1 } }],
+ capabilities: [],
+ surfaces: [],
+ producers: [{
+ name: reportProducer.name,
+ inputs: [{ name: "measurement", type: measurementType }],
+ outputs: [{ name: "report", type: reportType }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.report/write-report",
+ digest: producerDigests.report,
+ },
+ }],
+};
+
+function registry(digest = validatorDigest): TypeValidatorRegistry {
+ const validators = new TypeValidatorRegistry();
+ validators.register(measurementType, digest, ({ value }) => {
+ if (value.kind !== "inline" || value.value === null || Array.isArray(value.value)
+ || typeof value.value !== "object") {
+ throw new Error("measurement must be inline");
+ }
+ const measured = (value.value as Readonly<Record<string, unknown>>).value;
+ if (typeof measured !== "number" || measured % 2 !== 0) {
+ throw new Error("measurement must be even");
+ }
+ });
+ return validators;
+}
+
+function program(): LinkedProgram {
+ const closure = createResolvedClosure([contractManifest, sensorManifest, reportManifest]);
+ return link(closure, [sealTypedModule({
+ id: "author:empty",
+ closureDigest: closure.digest,
+ records: [],
+ })]);
+}
+
+function outputGraph(linked: LinkedProgram): CompiledGraph {
+ return sealCompiledGraph({
+ program: linked.semanticDigest,
+ outputs: [
+ {
+ id: "measurement",
+ type: measurementType,
+ primary: "measure",
+ candidates: ["measure"],
+ semanticInputs: [],
+ },
+ {
+ id: "report",
+ type: reportType,
+ primary: "report",
+ candidates: ["report"],
+ semanticInputs: [{ kind: "logical-output", id: "measurement" }],
+ },
+ ],
+ candidates: [
+ {
+ id: "measure",
+ output: "measurement",
+ root: { kind: "operation", result: { kind: "operation-result", operation: "measure" } },
+ fidelity: "exact",
+ },
+ {
+ id: "report",
+ output: "report",
+ root: { kind: "operation", result: { kind: "operation-result", operation: "report" } },
+ fidelity: "exact",
+ },
+ ],
+ operations: [
+ {
+ id: "measure",
+ producer: measureProducer,
+ inputs: {},
+ result: { kind: "output", name: "measurement", record: "measurement:root" },
+ },
+ {
+ id: "report",
+ producer: reportProducer,
+ inputs: { measurement: { kind: "logical-output", id: "measurement" } },
+ result: { kind: "output", name: "report", record: "report:root" },
+ },
+ ],
+ });
+}
+
+function outputBuild(linked: LinkedProgram, graph = outputGraph(linked)) {
+ return start(linked, graph, sealBuildRequest({
+ graph: graph.id,
+ targets: [{ output: "report", accepts: "exact" }],
+ bindings: [],
+ }));
+}
+
+function hosts(measured: number): HostRegistry {
+ const hosts = new HostRegistry();
+ hosts.registerProducer(measureProducer, producerDigests.measure, () => ({
+ outputs: { measurement: { kind: "inline", value: { value: measured, unit: "ticks" } } },
+ needs: {},
+ }));
+ hosts.registerProducer(reportProducer, producerDigests.report, ({ inputs }) => ({
+ outputs: {
+ report: {
+ kind: "inline",
+ value: `accepted:${JSON.stringify(inputs.measurement?.value)}`,
+ },
+ },
+ needs: {},
+ }));
+ return hosts;
+}
+
+test("three independent packages communicate through an owner-validated nominal Type", async () => {
+ const linked = program();
+ const result = await new NodeDriver({
+ registry: hosts(4),
+ validators: registry(),
+ }).run(outputBuild(linked));
+
+ assert.equal(result.status, "complete");
+ const measurement = result.state.records.find((record) => record.id === "measurement:root");
+ assert.equal(measurement?.validation?.validatorDigest, validatorDigest);
+ assert.equal(measurement?.validation?.recordDigest, measurement?.digest);
+ assert.equal(result.state.records.find((record) => record.id === "report:root")?.type.name, "Report");
+
+ const restored = parseBuildState(serializeBuildState(result.state));
+ assert.equal(
+ restored.records.find((record) => record.id === "measurement:root")?.validation?.id,
+ measurement?.validation?.id,
+ );
+});
+
+test("a structurally valid but semantically invalid Producer value never enters BuildState", async () => {
+ const linked = program();
+ const result = await new NodeDriver({
+ registry: hosts(3),
+ validators: registry(),
+ }).run(outputBuild(linked));
+
+ assert.equal(result.status, "paused");
+ assert.match(result.journal[0]?.message ?? "", /measurement must be even/u);
+ assert.equal(result.state.records.some((record) => record.id === "measurement:root"), false);
+ assert.equal(result.state.acceptedEvents.length, 0);
+});
+
+test("missing or digest-mismatched validator implementations fail before record admission", async () => {
+ const linked = program();
+ const missing = await new NodeDriver({
+ registry: hosts(4),
+ validators: new TypeValidatorRegistry(),
+ }).run(outputBuild(linked));
+ assert.equal(missing.status, "paused");
+ assert.match(missing.journal[0]?.message ?? "", /validator is not registered/u);
+
+ const mismatched = await new NodeDriver({
+ registry: hosts(4),
+ validators: registry(digestOf("wrong-validator")),
+ }).run(outputBuild(linked));
+ assert.equal(mismatched.status, "paused");
+ assert.match(mismatched.journal[0]?.message ?? "", /does not match the locked Manifest/u);
+});
+
+function providerGraph(linked: LinkedProgram): CompiledGraph {
+ return sealCompiledGraph({
+ program: linked.semanticDigest,
+ outputs: [{
+ id: "measurement",
+ type: measurementType,
+ primary: "request",
+ candidates: ["request"],
+ semanticInputs: [],
+ }],
+ candidates: [{
+ id: "request",
+ output: "measurement",
+ root: { kind: "operation", result: { kind: "operation-result", operation: "request" } },
+ fidelity: "exact",
+ }],
+ operations: [{
+ id: "request",
+ producer: requestProducer,
+ inputs: {},
+ result: {
+ kind: "need",
+ name: "measurement",
+ id: "need:measurement",
+ record: "measurement:provider",
+ accepts: "exact",
+ },
+ }],
+ });
+}
+
+async function providerBuild(measured: number) {
+ const linked = program();
+ const graph = providerGraph(linked);
+ const hosts = new HostRegistry();
+ hosts.registerProducer(requestProducer, producerDigests.request, () => ({
+ outputs: {},
+ needs: { measurement: { sample: "latest" } },
+ }));
+ const providers = new ProviderRegistry();
+ providers.registerProvider(
+ "example:measurement-provider",
+ measurementCapability,
+ measurementType,
+ () => ({
+ value: { kind: "inline", value: { value: measured, unit: "ticks" } },
+ conformance: "exact",
+ delivery: "executed",
+ metadata: {},
+ }),
+ );
+ return await new NodeDriver({ registry: hosts, providers, validators: registry() }).run(start(
+ linked,
+ graph,
+ sealBuildRequest({
+ graph: graph.id,
+ targets: [{ output: "measurement", accepts: "exact" }],
+ bindings: [],
+ }),
+ ));
+}
+
+test("Provider results pass the same Type-owner validation gate as Producer results", async () => {
+ const valid = await providerBuild(8);
+ assert.equal(valid.status, "complete");
+ assert.equal(valid.state.records[0]?.validation?.validatorDigest, validatorDigest);
+
+ const invalid = await providerBuild(7);
+ assert.equal(invalid.status, "paused");
+ assert.match(invalid.journal.at(-1)?.message ?? "", /measurement must be even/u);
+ assert.equal(invalid.state.records.some((record) => record.id === "measurement:provider"), false);
+});
+
+test("authored values require a receipt bound to their exact Type and content", async () => {
+ const linked = program();
+ const raw = sealRecord({
+ id: "measurement:authored",
+ type: measurementType,
+ value: { kind: "inline", value: { value: 10, unit: "ticks" } },
+ conformance: "exact",
+ origin: {
+ kind: "authored",
+ sourceDigest: digestOf("measurement-source"),
+ frontendClosureDigest: digestOf("measurement-frontend"),
+ },
+ });
+ assert.throws(() => verifyRecord(linked.closure, raw), /requires .*validator/u);
+ const admitted = await admitRecord(linked.closure, raw, registry());
+ verifyRecord(linked.closure, admitted);
+ assert.equal(admitted.validation?.recordDigest, admitted.digest);
+});
+
+test("the static Manifest reader discovers validator declarations without executing them", () => {
+ const parsed = parseModuleManifestText(JSON.stringify(contractManifest));
+ assert.deepEqual(parsed.types[0]?.validator, contractManifest.types[0]?.validator);
+ assert.throws(
+ () => parseModuleManifestText(JSON.stringify({
+ ...contractManifest,
+ types: [{
+ ...contractManifest.types[0],
+ validator: {
+ ...contractManifest.types[0]?.validator,
+ abi: "arbitrary-javascript@1",
+ },
+ }],
+ })),
+ /validator.*abi must be svml\.type-validator@1/u,
+ );
+});
+
+test("the static Manifest reader preserves Producer and Need result affinity", () => {
+ const outputAffinity = [{
+ resultPointer: "/value",
+ input: "basis",
+ inputPointer: "/value",
+ }];
+ const needAffinity = [{
+ resultPointer: "",
+ input: "basis",
+ inputPointer: "",
+ }];
+ const manifest: ModuleManifest = {
+ ...sensorManifest,
+ producers: [
+ {
+ ...sensorManifest.producers[0]!,
+ inputs: [{ name: "basis", type: measurementType }],
+ outputs: [{ name: "measurement", type: measurementType, affinity: outputAffinity }],
+ },
+ {
+ ...sensorManifest.producers[1]!,
+ inputs: [{ name: "basis", type: measurementType }],
+ needs: [{
+ name: "measurement",
+ capability: measurementCapability,
+ returns: measurementType,
+ affinity: needAffinity,
+ }],
+ },
+ ],
+ };
+
+ const parsed = parseModuleManifestText(JSON.stringify(manifest));
+ assert.deepEqual(parsed, manifest);
+ assert.deepEqual(parsed.producers[0]?.outputs[0]?.affinity, outputAffinity);
+ assert.deepEqual(parsed.producers[1]?.needs[0]?.affinity, needAffinity);
+ assert.doesNotThrow(() => createResolvedClosure([contractManifest, parsed]));
+});
+
+test("the static Manifest reader rejects incomplete result affinity", () => {
+ assert.throws(
+ () => parseModuleManifestText(JSON.stringify({
+ ...sensorManifest,
+ producers: [{
+ ...sensorManifest.producers[0],
+ inputs: [{ name: "basis", type: measurementType }],
+ outputs: [{
+ name: "measurement",
+ type: measurementType,
+ affinity: [{ resultPointer: "/value", inputPointer: "/value" }],
+ }],
+ }],
+ })),
+ /affinity\[0\]\.input must be a string/u,
+ );
+});
+
+test("Core sees affinity restored by the static Manifest reader", () => {
+ const parsed = parseModuleManifestText(JSON.stringify({
+ ...sensorManifest,
+ producers: [{
+ ...sensorManifest.producers[0],
+ inputs: [{ name: "basis", type: measurementType }],
+ outputs: [{
+ name: "measurement",
+ type: measurementType,
+ affinity: [{
+ resultPointer: "/value",
+ input: "missing-after-json-roundtrip",
+ inputPointer: "/value",
+ }],
+ }],
+ }],
+ }));
+
+ assert.throws(
+ () => createResolvedClosure([contractManifest, parsed]),
+ /references unknown input missing-after-json-roundtrip/u,
+ );
+});
+
+test("Type validation errors remain machine distinguishable", async () => {
+ await assert.rejects(
+ () => validateValue(
+ program().closure,
+ measurementType,
+ { kind: "inline", value: { value: 9, unit: "ticks" } },
+ registry(),
+ ),
+ (error: unknown) => error instanceof TypeValidationError && error.code === "TYPE_REFINEMENT_REJECTED",
+ );
+});
diff --git a/packages/elaborator/README.md b/packages/elaborator/README.md
index 95a5ede8..44952b30 100644
--- a/packages/elaborator/README.md
+++ b/packages/elaborator/README.md
@@ -1,6 +1,43 @@
# `@svml/elaborator`
-Static Graph Fragment elaboration outside SVML Core.
+Parser-independent author linking and static Graph Fragment elaboration outside SVML Core.
+
+The package is the optional compilation layer between authored declarations and the domain-free
+Kernel. A frontend, API or visual editor first emits one sealed `svml.author-module@1` containing
+component calls with symbolic Record/Component-output references. The Elaborator then works in two
+phases:
+
+1. lock every referenced Fragment and predeclare every component export;
+2. resolve references, reject missing values, type mismatches and cycles, hygienically instantiate
+ Fragments, then emit one ordinary `svml.graph@1` for Core.
+
+Because all exports are collected before any input is resolved, declaration order has no meaning
+and a component may reference a later component. The linker itself does not parse `.svml`, execute
+package code or know any domain vocabulary. The non-video laboratory test demonstrates that the
+same layer works without `@svml/text` or audiovisual contracts.
+
+The official Text adapter now emits this exact Author Module format. Its separate non-video
+integration fixture proves the complete `source → Surface → AuthorModule → Graph → BuildPlan` path;
+Text still does not become a prerequisite for direct API or visual-editor callers.
+
+The package also provides the domain-neutral recursive Source Closure reference implementation.
+The Host supplies an entry SourceUnit, exact Frontend registry, immutable module closure and a
+Source resolver. Source compilation discovers dependencies before decoding, rejects cycles and
+duplicate aliases, decodes dependencies first, hygienically qualifies private Record/component
+identities and binds only declared public exports into importer namespaces. Host filesystem paths
+are excluded from Source Closure identity; source contents, Frontend digests and written import
+edges remain covered.
+
+The orchestration ABI is asynchronous even when a local Text/SVS implementation is synchronous.
+This lets a browser, sandbox or remote repository provide SourceUnits without changing the
+compilation contract. The Host resolver is the authority for path canonicalization, workspace
+containment, symlink policy and I/O; Elaborator receives bytes and identities but never opens files
+or grants filesystem access itself.
+
+Frontend output passes a Host-owned Record admission hook before linking. The hook is permitted to
+attach validation evidence but is forbidden to rewrite Record identity, Type, value, digest,
+conformance or origin. `@svml/compiler-node` wires this to `@svml/validation` by default, so authored
+values use the same Type-owner gate as Producer, Provider and provided Candidate values.
A `svml.fragment@1` value may reference only declared Fragment inputs and local Operations. It
contains no JavaScript callback, ambient file lookup, credential access or Runtime endpoint. Before
@@ -11,3 +48,7 @@ Expansion assigns hygienic identities from `fragment digest + author instance id
Multiple exports of one instance therefore share internal Operations, while two explicit instances
are never content-deduplicated. The result is ordinary `LogicalOutput`, `Candidate` and
`OperationNode` data that Core validates again.
+
+`@svml/elaborator` is not a public `@svml/author` subsystem. It is a reusable graph-construction
+library. A domain normally adds its own contract and component packages; Text remains only one
+optional frontend capable of producing the same Author Module data.
diff --git a/packages/elaborator/src/author.ts b/packages/elaborator/src/author.ts
new file mode 100644
index 00000000..0f141301
--- /dev/null
+++ b/packages/elaborator/src/author.ts
@@ -0,0 +1,362 @@
+import {
+ digestOf,
+ isDigest,
+ sealCompiledGraph,
+ verifyCompiledGraph,
+} from "@svml/core";
+import type {
+ CompiledGraph,
+ Digest,
+ GraphValueRef,
+ LinkedProgram,
+ TypeRef,
+} from "@svml/protocol";
+
+import {
+ bindAuthorFragment,
+ elaborateGraphFragment,
+ mergeFragmentContributions,
+ verifyGraphFragment,
+} from "./fragment.js";
+import type {
+ FragmentContribution,
+ GraphFragment,
+} from "./fragment.js";
+
+/** A reference to an authored fact that already exists in the Linked Program. */
+export type AuthorRecordRef = {
+ readonly kind: "record";
+ readonly id: string;
+};
+
+/** A symbolic reference to one public export of another component instance. */
+export type AuthorComponentOutputRef = {
+ readonly kind: "component-output";
+ readonly component: string;
+ readonly output: string;
+};
+
+export type AuthorValueRef = AuthorRecordRef | AuthorComponentOutputRef;
+
+/**
+ * One author-visible component call. The Fragment is locked by digest; its implementation remains
+ * declarative data. `outputs` binds every public Fragment export to a Logical Output identity.
+ */
+export type AuthorComponent = {
+ readonly id: string;
+ readonly fragment: Digest;
+ readonly inputs: Readonly<Record<string, AuthorValueRef>>;
+ readonly outputs: Readonly<Record<string, string>>;
+};
+
+/**
+ * Parser-independent author intent collected before references are resolved.
+ * Component declaration order has no semantic meaning, so forward references are valid.
+ */
+export type AuthorModule = {
+ readonly format: "svml.author-module@1";
+ readonly id: Digest;
+ readonly name: string;
+ readonly components: readonly AuthorComponent[];
+};
+
+export type AuthorOutputBinding = {
+ readonly component: string;
+ readonly output: string;
+ readonly id: string;
+ readonly type: TypeRef;
+};
+
+export type AuthorElaboration = {
+ readonly format: "svml.author-elaboration@1";
+ readonly author: Digest;
+ readonly graph: CompiledGraph;
+ readonly outputs: readonly AuthorOutputBinding[];
+};
+
+/** Resolve a locked Graph Fragment without executing package code. */
+export type GraphFragmentResolver = (id: Digest) => GraphFragment | undefined;
+
+export class AuthorModuleError extends Error {
+ readonly code: string;
+ readonly subject: string | undefined;
+
+ constructor(code: string, message: string, subject?: string) {
+ super(message);
+ this.name = "AuthorModuleError";
+ this.code = code;
+ this.subject = subject;
+ }
+}
+
+function assert(
+ condition: unknown,
+ code: string,
+ message: string,
+ subject?: string,
+): asserts condition {
+ if (!condition) throw new AuthorModuleError(code, message, subject);
+}
+
+function sameType(left: TypeRef, right: TypeRef): boolean {
+ return left.module.name === right.module.name
+ && left.module.version === right.module.version
+ && left.name === right.name;
+}
+
+function typeName(type: TypeRef): string {
+ return `${type.module.name}@${type.module.version}#${type.name}`;
+}
+
+function exactKeys(
+ actual: Readonly<Record<string, unknown>>,
+ expected: readonly string[],
+ subject: string,
+): void {
+ const left = Object.keys(actual).sort();
+ const right = [...expected].sort();
+ assert(
+ JSON.stringify(left) === JSON.stringify(right),
+ "AUTHOR_PORT_BINDING_MISMATCH",
+ `${subject} binds [${left.join(", ")}] but declares [${right.join(", ")}]`,
+ subject,
+ );
+}
+
+function normalizeRef(ref: AuthorValueRef): AuthorValueRef {
+ if (ref.kind === "record") return { kind: "record", id: ref.id };
+ assert(
+ ref.kind === "component-output",
+ "INVALID_AUTHOR_REFERENCE",
+ "Author inputs must reference a record or a component output",
+ );
+ return {
+ kind: "component-output",
+ component: ref.component,
+ output: ref.output,
+ };
+}
+
+function normalizeComponent(component: AuthorComponent): AuthorComponent {
+ return {
+ id: component.id,
+ fragment: component.fragment,
+ inputs: Object.fromEntries(
+ Object.entries(component.inputs)
+ .sort(([left], [right]) => left.localeCompare(right))
+ .map(([name, ref]) => [name, normalizeRef(ref)]),
+ ),
+ outputs: Object.fromEntries(
+ Object.entries(component.outputs).sort(([left], [right]) => left.localeCompare(right)),
+ ),
+ };
+}
+
+function authorModuleContent(module: AuthorModule): Omit<AuthorModule, "id"> {
+ return {
+ format: "svml.author-module@1",
+ name: module.name,
+ components: [...module.components]
+ .map(normalizeComponent)
+ .sort((left, right) => left.id.localeCompare(right.id)),
+ };
+}
+
+export function sealAuthorModule(
+ module: Omit<AuthorModule, "format" | "id">,
+): AuthorModule {
+ const draft = {
+ format: "svml.author-module@1" as const,
+ id: digestOf("unsealed-author-module"),
+ ...module,
+ };
+ const content = authorModuleContent(draft);
+ return { ...content, id: digestOf(content) };
+}
+
+type CollectedComponent = {
+ readonly declaration: AuthorComponent;
+ readonly fragment: GraphFragment;
+};
+
+type CollectedAuthorModule = {
+ readonly components: ReadonlyMap<string, CollectedComponent>;
+ readonly outputs: ReadonlyMap<string, AuthorOutputBinding>;
+ readonly ordered: readonly CollectedComponent[];
+};
+
+function outputKey(component: string, output: string): string {
+ return `${component}\u0000${output}`;
+}
+
+/** Phase one: lock every component and predeclare every public output before resolving any input. */
+function collectAuthorModule(
+ program: LinkedProgram,
+ module: AuthorModule,
+ resolveFragment: GraphFragmentResolver,
+): CollectedAuthorModule {
+ assert(module.format === "svml.author-module@1", "UNSUPPORTED_AUTHOR_MODULE", "unsupported Author Module format");
+ assert(isDigest(module.id), "INVALID_AUTHOR_MODULE_DIGEST", "Author Module id is not a digest");
+ assert(
+ module.id === digestOf(authorModuleContent(module)),
+ "AUTHOR_MODULE_DIGEST_MISMATCH",
+ "Author Module digest differs",
+ );
+ assert(module.name.length > 0, "EMPTY_AUTHOR_MODULE_NAME", "Author Module name is empty");
+
+ const components = new Map<string, CollectedComponent>();
+ const outputs = new Map<string, AuthorOutputBinding>();
+ const outputIds = new Set<string>();
+
+ for (const declaration of module.components) {
+ assert(declaration.id.length > 0, "EMPTY_AUTHOR_COMPONENT_ID", "Author component id is empty");
+ assert(
+ !components.has(declaration.id),
+ "DUPLICATE_AUTHOR_COMPONENT",
+ `${module.name} repeats component ${declaration.id}`,
+ declaration.id,
+ );
+ assert(isDigest(declaration.fragment), "INVALID_FRAGMENT_DIGEST", `${declaration.id} Fragment digest is invalid`);
+ const fragment = resolveFragment(declaration.fragment);
+ assert(
+ fragment !== undefined,
+ "UNKNOWN_GRAPH_FRAGMENT",
+ `${declaration.id} references unavailable Fragment ${declaration.fragment}`,
+ declaration.id,
+ );
+ assert(
+ fragment.id === declaration.fragment,
+ "FRAGMENT_RESOLUTION_MISMATCH",
+ `${declaration.id} resolved a different Fragment`,
+ declaration.id,
+ );
+ verifyGraphFragment(program, fragment);
+ exactKeys(declaration.inputs, fragment.inputs.map((input) => input.name), declaration.id);
+ exactKeys(declaration.outputs, fragment.exports.map((item) => item.name), declaration.id);
+ const collected = { declaration, fragment };
+ components.set(declaration.id, collected);
+
+ for (const item of fragment.exports) {
+ const id = declaration.outputs[item.name] as string;
+ assert(id.length > 0, "EMPTY_LOGICAL_OUTPUT_ID", `${declaration.id}.${item.name} output is empty`);
+ assert(
+ !outputIds.has(id),
+ "DUPLICATE_LOGICAL_OUTPUT_ID",
+ `${module.name} binds Logical Output ${id} more than once`,
+ id,
+ );
+ outputIds.add(id);
+ outputs.set(outputKey(declaration.id, item.name), {
+ component: declaration.id,
+ output: item.name,
+ id,
+ type: item.type,
+ });
+ }
+ }
+ return {
+ components,
+ outputs,
+ ordered: [...components.values()].sort((left, right) =>
+ left.declaration.id.localeCompare(right.declaration.id)),
+ };
+}
+
+/** Phase two: resolve symbolic references, reject cycles/types errors, then elaborate ordinary Core data. */
+export function elaborateAuthorModule(
+ program: LinkedProgram,
+ module: AuthorModule,
+ resolveFragment: GraphFragmentResolver,
+): AuthorElaboration {
+ const collected = collectAuthorModule(program, module, resolveFragment);
+ const records = new Map(program.records.map((record) => [record.id, record]));
+ const visiting: string[] = [];
+ const visited = new Set<string>();
+ const ordered: CollectedComponent[] = [];
+
+ const visit = (component: CollectedComponent): void => {
+ const id = component.declaration.id;
+ if (visited.has(id)) return;
+ const cycleStart = visiting.indexOf(id);
+ assert(
+ cycleStart === -1,
+ "AUTHOR_COMPONENT_CYCLE",
+ `Author components cycle through ${[...visiting.slice(cycleStart), id].join(" -> ")}`,
+ id,
+ );
+ visiting.push(id);
+ for (const ref of Object.values(component.declaration.inputs)) {
+ if (ref.kind !== "component-output") continue;
+ const dependency = collected.components.get(ref.component);
+ assert(
+ dependency !== undefined,
+ "UNKNOWN_AUTHOR_COMPONENT",
+ `${id} references unknown component ${ref.component}`,
+ id,
+ );
+ visit(dependency);
+ }
+ visiting.pop();
+ visited.add(id);
+ ordered.push(component);
+ };
+ collected.ordered.forEach(visit);
+
+ const contributions: FragmentContribution[] = [];
+ for (const component of ordered) {
+ const inputs: Record<string, GraphValueRef> = {};
+ for (const input of component.fragment.inputs) {
+ const ref = component.declaration.inputs[input.name] as AuthorValueRef;
+ if (ref.kind === "record") {
+ const record = records.get(ref.id);
+ assert(
+ record !== undefined,
+ "UNKNOWN_AUTHOR_RECORD",
+ `${component.declaration.id}.${input.name} references unknown record ${ref.id}`,
+ component.declaration.id,
+ );
+ assert(
+ sameType(record.type, input.type),
+ "AUTHOR_INPUT_TYPE_MISMATCH",
+ `${component.declaration.id}.${input.name} wants ${typeName(input.type)} but receives ${typeName(record.type)}`,
+ component.declaration.id,
+ );
+ inputs[input.name] = { kind: "record", id: record.id };
+ continue;
+ }
+ const binding = collected.outputs.get(outputKey(ref.component, ref.output));
+ assert(
+ binding !== undefined,
+ "UNKNOWN_AUTHOR_OUTPUT",
+ `${component.declaration.id}.${input.name} references unknown output ${ref.component}.${ref.output}`,
+ component.declaration.id,
+ );
+ assert(
+ sameType(binding.type, input.type),
+ "AUTHOR_INPUT_TYPE_MISMATCH",
+ `${component.declaration.id}.${input.name} wants ${typeName(input.type)} but receives ${typeName(binding.type)}`,
+ component.declaration.id,
+ );
+ inputs[input.name] = { kind: "logical-output", id: binding.id };
+ }
+ const instance = elaborateGraphFragment(program, component.fragment, {
+ id: component.declaration.id,
+ fragment: component.fragment.id,
+ inputs,
+ });
+ contributions.push(bindAuthorFragment(instance, component.declaration.outputs));
+ }
+
+ const merged = mergeFragmentContributions(
+ { outputs: [], candidates: [], operations: [] },
+ ...contributions,
+ );
+ const graph = sealCompiledGraph({ program: program.semanticDigest, ...merged });
+ verifyCompiledGraph(program, graph);
+ return {
+ format: "svml.author-elaboration@1",
+ author: module.id,
+ graph,
+ outputs: [...collected.outputs.values()].sort((left, right) => left.id.localeCompare(right.id)),
+ };
+}
diff --git a/packages/elaborator/src/index.ts b/packages/elaborator/src/index.ts
index 7c26e888..ca01c13c 100644
--- a/packages/elaborator/src/index.ts
+++ b/packages/elaborator/src/index.ts
@@ -1,3 +1,44 @@
+export {
+ AuthorModuleError,
+ elaborateAuthorModule,
+ sealAuthorModule,
+} from "./author.js";
+export type {
+ AuthorComponent,
+ AuthorComponentOutputRef,
+ AuthorElaboration,
+ AuthorModule,
+ AuthorOutputBinding,
+ AuthorRecordRef,
+ AuthorValueRef,
+ GraphFragmentResolver,
+} from "./author.js";
+export {
+ AuthorFrontendRegistry,
+ SourceClosureError,
+ compileSourceClosure,
+ resolveCompiledSourceExport,
+ verifySourceClosure,
+} from "./source.js";
+export type {
+ AuthorFrontend,
+ AuthorFrontendRegistryLike,
+ AuthorSourceDecodeContext,
+ AuthorSourceDiscovery,
+ AuthorSourceExport,
+ AuthorSourceImport,
+ AuthorSourceResolver,
+ AuthorSourceUnit,
+ AuthorRecordAdmitter,
+ Awaitable,
+ CompileSourceClosureRequest,
+ CompiledSourceClosure,
+ CompiledSourceExport,
+ DecodedAuthorSource,
+ ResolvedAuthorSourceImport,
+ SourceClosure,
+ SourceClosureUnit,
+} from "./source.js";
export {
bindAuthorFragment,
bindCandidateFragment,
diff --git a/packages/elaborator/src/source.ts b/packages/elaborator/src/source.ts
new file mode 100644
index 00000000..18ba9dad
--- /dev/null
+++ b/packages/elaborator/src/source.ts
@@ -0,0 +1,583 @@
+import {
+ canonicalize,
+ canonicalStringify,
+ digestOf,
+ isDigest,
+ link,
+ sealTypedModule,
+ verifyRecord,
+} from "@svml/core";
+import type {
+ Digest,
+ GraphValueRef,
+ LinkedProgram,
+ ResolvedModuleClosure,
+ SourceRange,
+ TypeRef,
+ TypedModule,
+ TypedRecord,
+} from "@svml/protocol";
+
+import {
+ elaborateAuthorModule,
+ sealAuthorModule,
+} from "./author.js";
+import type {
+ AuthorComponent,
+ AuthorElaboration,
+ AuthorModule,
+ AuthorValueRef,
+} from "./author.js";
+import type { GraphFragment } from "./fragment.js";
+
+export type AuthorSourceUnit = {
+ /** Host-canonical identity used only for recursion/cache diagnostics, never semantic identity. */
+ readonly id: string;
+ readonly name: string;
+ readonly text: string;
+};
+
+export type AuthorSourceImport = {
+ readonly from: string;
+ readonly alias: string;
+ readonly frontend: string;
+ readonly range?: SourceRange;
+};
+
+export type AuthorSourceDiscovery = {
+ readonly modules: readonly string[];
+ readonly sources: readonly AuthorSourceImport[];
+};
+
+export type AuthorSourceExport = {
+ /** Relative public name. The importing source contributes its own alias. */
+ readonly name: string;
+ readonly ref: AuthorValueRef;
+ readonly type: TypeRef;
+};
+
+export type ResolvedAuthorSourceImport = {
+ readonly request: AuthorSourceImport;
+ readonly source: Digest;
+ readonly exports: readonly AuthorSourceExport[];
+ /** Public record exports available to a package-owned Surface during author compilation. */
+ readonly records: readonly TypedRecord[];
+};
+
+export type AuthorSourceDecodeContext = {
+ readonly closure: ResolvedModuleClosure;
+ readonly imports: readonly ResolvedAuthorSourceImport[];
+};
+
+export type DecodedAuthorSource = {
+ readonly module: TypedModule;
+ readonly author: AuthorModule;
+ readonly fragments: readonly GraphFragment[];
+ readonly exports: readonly AuthorSourceExport[];
+};
+
+export type Awaitable<T> = T | Promise<T>;
+
+export type AuthorFrontend = {
+ readonly id: string;
+ readonly implementationDigest: Digest;
+ discover(source: AuthorSourceUnit): Awaitable<AuthorSourceDiscovery>;
+ decode(source: AuthorSourceUnit, context: AuthorSourceDecodeContext): Awaitable<DecodedAuthorSource>;
+};
+
+export interface AuthorFrontendRegistryLike {
+ resolve(id: string): AuthorFrontend | undefined;
+}
+
+export class AuthorFrontendRegistry implements AuthorFrontendRegistryLike {
+ readonly #frontends = new Map<string, AuthorFrontend>();
+
+ register(frontend: AuthorFrontend): void {
+ if (frontend.id.length === 0) throw new SourceClosureError("EMPTY_FRONTEND_ID", "Frontend id is empty");
+ if (!isDigest(frontend.implementationDigest)) {
+ throw new SourceClosureError("INVALID_FRONTEND_DIGEST", `${frontend.id} implementation digest is invalid`);
+ }
+ if (this.#frontends.has(frontend.id)) {
+ throw new SourceClosureError("DUPLICATE_FRONTEND", `Frontend ${frontend.id} is already registered`, frontend.id);
+ }
+ this.#frontends.set(frontend.id, frontend);
+ }
+
+ resolve(id: string): AuthorFrontend | undefined {
+ return this.#frontends.get(id);
+ }
+}
+
+export type AuthorSourceResolver = (
+ importer: AuthorSourceUnit,
+ request: AuthorSourceImport,
+) => Awaitable<AuthorSourceUnit>;
+
+/** Host-owned admission hook; it may attach validation evidence but cannot rewrite author meaning. */
+export type AuthorRecordAdmitter = (
+ closure: ResolvedModuleClosure,
+ record: TypedRecord,
+) => Awaitable<TypedRecord>;
+
+export type SourceClosureUnit = {
+ readonly format: "svml.source-unit@1";
+ readonly id: Digest;
+ readonly frontend: string;
+ readonly frontendDigest: Digest;
+ readonly sourceDigest: Digest;
+ readonly semanticDigest: Digest;
+ readonly modules: readonly string[];
+ readonly imports: readonly {
+ readonly alias: string;
+ readonly from: string;
+ readonly source: Digest;
+ readonly frontend: string;
+ }[];
+};
+
+export type SourceClosure = {
+ readonly format: "svml.source-closure@1";
+ readonly id: Digest;
+ readonly entry: Digest;
+ readonly units: readonly SourceClosureUnit[];
+};
+
+export type CompiledSourceExport = {
+ readonly name: string;
+ readonly type: TypeRef;
+ readonly ref: GraphValueRef;
+};
+
+export type CompiledSourceClosure = {
+ readonly closure: SourceClosure;
+ readonly module: TypedModule;
+ readonly author: AuthorModule;
+ readonly fragments: readonly GraphFragment[];
+ readonly program: LinkedProgram;
+ readonly elaboration: AuthorElaboration;
+ readonly exports: readonly CompiledSourceExport[];
+};
+
+export type CompileSourceClosureRequest = {
+ readonly entry: AuthorSourceUnit;
+ readonly frontend: string;
+ readonly closure: ResolvedModuleClosure;
+ readonly frontends: AuthorFrontendRegistryLike;
+ readonly resolveSource: AuthorSourceResolver;
+ readonly admitRecord?: AuthorRecordAdmitter;
+};
+
+export class SourceClosureError extends Error {
+ readonly code: string;
+ readonly subject: string | undefined;
+
+ constructor(code: string, message: string, subject?: string) {
+ super(message);
+ this.name = "SourceClosureError";
+ this.code = code;
+ this.subject = subject;
+ }
+}
+
+function sourceUnitContent(unit: SourceClosureUnit): Omit<SourceClosureUnit, "id"> {
+ return {
+ format: "svml.source-unit@1",
+ frontend: unit.frontend,
+ frontendDigest: unit.frontendDigest,
+ sourceDigest: unit.sourceDigest,
+ semanticDigest: unit.semanticDigest,
+ modules: [...unit.modules].sort(),
+ imports: [...unit.imports]
+ .map((item) => ({
+ alias: item.alias,
+ from: item.from,
+ source: item.source,
+ frontend: item.frontend,
+ }))
+ .sort((left, right) => left.alias.localeCompare(right.alias)),
+ };
+}
+
+function sourceClosureContent(closure: SourceClosure): Omit<SourceClosure, "id"> {
+ return {
+ format: "svml.source-closure@1",
+ entry: closure.entry,
+ units: [...closure.units].sort((left, right) => left.id.localeCompare(right.id)),
+ };
+}
+
+function assert(
+ condition: unknown,
+ code: string,
+ message: string,
+ subject?: string,
+): asserts condition {
+ if (!condition) throw new SourceClosureError(code, message, subject);
+}
+
+function typeName(type: TypeRef): string {
+ return `${type.module.name}@${type.module.version}#${type.name}`;
+}
+
+function sameType(left: TypeRef, right: TypeRef): boolean {
+ return left.module.name === right.module.name
+ && left.module.version === right.module.version
+ && left.name === right.name;
+}
+
+function sourceKey(source: AuthorSourceUnit, frontend: string): string {
+ return `${source.id}\u0000${frontend}`;
+}
+
+type HygienicSource = {
+ readonly unit: SourceClosureUnit;
+ readonly records: readonly TypedRecord[];
+ readonly components: readonly AuthorComponent[];
+ readonly fragments: readonly GraphFragment[];
+ readonly exports: readonly AuthorSourceExport[];
+};
+
+function hygienicId(kind: string, unit: Digest, local: string): string {
+ return `${kind}:${digestOf({ unit, local }).slice("sha256:".length)}`;
+}
+
+function hygienizeSource(
+ source: AuthorSourceUnit,
+ frontend: AuthorFrontend,
+ discovery: AuthorSourceDiscovery,
+ decoded: DecodedAuthorSource,
+ imports: readonly ResolvedAuthorSourceImport[],
+): HygienicSource {
+ assert(decoded.module.closureDigest.length > 0, "INVALID_SOURCE_MODULE", `${source.name} returned no closure identity`);
+ const fragmentIds = new Set<string>();
+ for (const fragment of decoded.fragments) {
+ assert(!fragmentIds.has(fragment.id), "DUPLICATE_SOURCE_FRAGMENT", `${source.name} repeats Fragment ${fragment.id}`);
+ fragmentIds.add(fragment.id);
+ }
+ const exportNames = new Set<string>();
+ for (const item of decoded.exports) {
+ assert(item.name.length > 0, "EMPTY_SOURCE_EXPORT", `${source.name} returned an empty export`);
+ assert(!exportNames.has(item.name), "DUPLICATE_SOURCE_EXPORT", `${source.name} repeats export ${item.name}`, item.name);
+ exportNames.add(item.name);
+ const ref = item.ref;
+ if (ref.kind === "record") {
+ const record = decoded.module.records.find((candidate) => candidate.id === ref.id);
+ assert(record !== undefined, "UNKNOWN_SOURCE_EXPORT", `${source.name}.${item.name} references unknown Record ${ref.id}`);
+ assert(
+ sameType(record.type, item.type),
+ "SOURCE_EXPORT_TYPE_MISMATCH",
+ `${source.name}.${item.name} declares ${typeName(item.type)} but exports ${typeName(record.type)}`,
+ );
+ } else {
+ const component = decoded.author.components.find((candidate) => candidate.id === ref.component);
+ assert(component !== undefined, "UNKNOWN_SOURCE_EXPORT", `${source.name}.${item.name} references unknown component ${ref.component}`);
+ const fragment = decoded.fragments.find((candidate) => candidate.id === component.fragment);
+ assert(fragment !== undefined, "UNKNOWN_SOURCE_EXPORT", `${source.name}.${item.name} references unavailable Fragment ${component.fragment}`);
+ const declaration = fragment.exports.find((candidate) => candidate.name === ref.output);
+ assert(declaration !== undefined, "UNKNOWN_SOURCE_EXPORT", `${source.name}.${item.name} references unknown output ${ref.output}`);
+ assert(
+ sameType(declaration.type, item.type),
+ "SOURCE_EXPORT_TYPE_MISMATCH",
+ `${source.name}.${item.name} declares ${typeName(item.type)} but exports ${typeName(declaration.type)}`,
+ );
+ }
+ }
+
+ const semanticDigest = digestOf({
+ frontend: frontend.id,
+ implementationDigest: frontend.implementationDigest,
+ records: [...decoded.module.records]
+ .sort((left, right) => left.id.localeCompare(right.id))
+ .map((record) => ({
+ id: record.id,
+ type: record.type,
+ value: record.value,
+ conformance: record.conformance,
+ })),
+ components: decoded.author.components,
+ fragments: [...decoded.fragments].map((fragment) => fragment.id).sort(),
+ exports: [...decoded.exports].sort((left, right) => left.name.localeCompare(right.name)),
+ });
+ const recordIds = new Map(decoded.module.records.map((record) => [
+ record.id,
+ hygienicId("source-record", semanticDigest, record.id),
+ ]));
+ const componentIds = new Map(decoded.author.components.map((component) => [
+ component.id,
+ hygienicId("source-component", semanticDigest, component.id),
+ ]));
+ const outputIds = new Map<string, string>();
+ for (const component of decoded.author.components) {
+ for (const output of Object.values(component.outputs)) {
+ outputIds.set(output, hygienicId("source-output", semanticDigest, output));
+ }
+ }
+ const mapRef = (ref: AuthorValueRef): AuthorValueRef => {
+ if (ref.kind === "record") {
+ return { kind: "record", id: recordIds.get(ref.id) ?? ref.id };
+ }
+ return {
+ kind: "component-output",
+ component: componentIds.get(ref.component) ?? ref.component,
+ output: ref.output,
+ };
+ };
+ const records = decoded.module.records.map((record) => ({
+ ...record,
+ id: recordIds.get(record.id) as string,
+ }));
+ const components = decoded.author.components.map((component) => ({
+ id: componentIds.get(component.id) as string,
+ fragment: component.fragment,
+ inputs: Object.fromEntries(Object.entries(component.inputs).map(([name, ref]) => [name, mapRef(ref)])),
+ outputs: Object.fromEntries(Object.entries(component.outputs).map(([name, id]) => [
+ name,
+ outputIds.get(id) as string,
+ ])),
+ }));
+ const exports = decoded.exports.map((item) => ({ ...item, ref: mapRef(item.ref) }));
+ const unitContent = {
+ format: "svml.source-unit@1" as const,
+ frontend: frontend.id,
+ frontendDigest: frontend.implementationDigest,
+ sourceDigest: digestOf(source.text),
+ semanticDigest,
+ modules: [...discovery.modules].sort(),
+ imports: discovery.sources
+ .map((request) => {
+ const resolved = imports.find((item) => item.request === request);
+ assert(resolved !== undefined, "UNRESOLVED_SOURCE_IMPORT", `${source.name} did not resolve ${request.from}`);
+ return {
+ alias: request.alias,
+ from: request.from,
+ source: resolved.source,
+ frontend: request.frontend,
+ };
+ })
+ .sort((left, right) => left.alias.localeCompare(right.alias)),
+ };
+ return {
+ unit: {
+ id: digestOf(unitContent),
+ format: "svml.source-unit@1",
+ frontend: frontend.id,
+ frontendDigest: frontend.implementationDigest,
+ sourceDigest: unitContent.sourceDigest,
+ semanticDigest,
+ modules: unitContent.modules,
+ imports: unitContent.imports,
+ },
+ records,
+ components,
+ fragments: decoded.fragments,
+ exports,
+ };
+}
+
+function graphRefForExport(
+ item: AuthorSourceExport,
+ components: ReadonlyMap<string, AuthorComponent>,
+): GraphValueRef {
+ if (item.ref.kind === "record") return item.ref;
+ const component = components.get(item.ref.component);
+ assert(component !== undefined, "UNKNOWN_SOURCE_EXPORT", `export ${item.name} references ${item.ref.component}`);
+ const output = component.outputs[item.ref.output];
+ assert(output !== undefined, "UNKNOWN_SOURCE_EXPORT", `export ${item.name} references ${item.ref.component}.${item.ref.output}`);
+ return { kind: "logical-output", id: output };
+}
+
+export async function compileSourceClosure(
+ request: CompileSourceClosureRequest,
+): Promise<CompiledSourceClosure> {
+ const cache = new Map<string, HygienicSource>();
+ const visiting: string[] = [];
+ const ordered: HygienicSource[] = [];
+
+ const compile = async (source: AuthorSourceUnit, frontendId: string): Promise<HygienicSource> => {
+ assert(source.id.length > 0, "EMPTY_SOURCE_ID", "SourceUnit id is empty");
+ const key = sourceKey(source, frontendId);
+ const cached = cache.get(key);
+ if (cached !== undefined) return cached;
+ const cycle = visiting.indexOf(key);
+ assert(
+ cycle === -1,
+ "SOURCE_IMPORT_CYCLE",
+ `Source imports cycle through ${[...visiting.slice(cycle), key].join(" -> ")}`,
+ source.id,
+ );
+ const frontend = request.frontends.resolve(frontendId);
+ assert(frontend !== undefined, "UNKNOWN_FRONTEND", `Frontend ${frontendId} is not registered`, frontendId);
+ assert(isDigest(frontend.implementationDigest), "INVALID_FRONTEND_DIGEST", `${frontendId} digest is invalid`);
+ visiting.push(key);
+ const discovery = await frontend.discover(source);
+ const aliases = new Set<string>();
+ const imports: ResolvedAuthorSourceImport[] = [];
+ for (const dependency of discovery.sources) {
+ assert(dependency.alias.length > 0, "EMPTY_SOURCE_ALIAS", `${source.name} has an empty source alias`);
+ assert(!aliases.has(dependency.alias), "DUPLICATE_SOURCE_ALIAS", `${source.name} repeats alias ${dependency.alias}`);
+ aliases.add(dependency.alias);
+ const child = await request.resolveSource(source, dependency);
+ const compiled = await compile(child, dependency.frontend);
+ const publicRecordIds = new Set(compiled.exports
+ .filter((item) => item.ref.kind === "record")
+ .map((item) => item.ref.kind === "record" ? item.ref.id : ""));
+ imports.push({
+ request: dependency,
+ source: compiled.unit.id,
+ exports: compiled.exports,
+ records: compiled.records.filter((record) => publicRecordIds.has(record.id)),
+ });
+ }
+ const rawDecoded = await frontend.decode(source, {
+ closure: request.closure,
+ imports: canonicalize(imports) as unknown as readonly ResolvedAuthorSourceImport[],
+ });
+ assert(
+ rawDecoded.module.closureDigest === request.closure.digest,
+ "SOURCE_MODULE_CLOSURE_MISMATCH",
+ `${source.name} decoded against another module closure`,
+ );
+ const admittedRecords: TypedRecord[] = [];
+ for (const record of rawDecoded.module.records) {
+ const admitted = request.admitRecord === undefined
+ ? record
+ : await request.admitRecord(request.closure, record);
+ assert(
+ canonicalStringify({
+ id: admitted.id,
+ type: admitted.type,
+ value: admitted.value,
+ digest: admitted.digest,
+ conformance: admitted.conformance,
+ origin: admitted.origin,
+ }) === canonicalStringify({
+ id: record.id,
+ type: record.type,
+ value: record.value,
+ digest: record.digest,
+ conformance: record.conformance,
+ origin: record.origin,
+ }),
+ "RECORD_ADMISSION_REWRITE",
+ `Record admission rewrote ${source.name}:${record.id}`,
+ record.id,
+ );
+ verifyRecord(request.closure, admitted);
+ admittedRecords.push(admitted);
+ }
+ const decoded: DecodedAuthorSource = {
+ ...rawDecoded,
+ module: sealTypedModule({
+ id: rawDecoded.module.id,
+ closureDigest: rawDecoded.module.closureDigest,
+ records: admittedRecords,
+ }),
+ };
+ link(request.closure, [decoded.module]);
+ const result = hygienizeSource(source, frontend, discovery, decoded, imports);
+ visiting.pop();
+ cache.set(key, result);
+ ordered.push(result);
+ return result;
+ };
+
+ const entry = await compile(request.entry, request.frontend);
+ const records = ordered.flatMap((unit) => unit.records);
+ const recordIds = new Set<string>();
+ for (const record of records) {
+ assert(!recordIds.has(record.id), "SOURCE_RECORD_COLLISION", `Source closure repeats Record ${record.id}`, record.id);
+ recordIds.add(record.id);
+ }
+ const fragments = new Map<string, GraphFragment>();
+ for (const fragment of ordered.flatMap((unit) => unit.fragments)) {
+ const existing = fragments.get(fragment.id);
+ assert(
+ existing === undefined || canonicalStringify(existing) === canonicalStringify(fragment),
+ "SOURCE_FRAGMENT_CONFLICT",
+ `Source closure has conflicting Fragment ${fragment.id}`,
+ fragment.id,
+ );
+ fragments.set(fragment.id, fragment);
+ }
+ const author = sealAuthorModule({
+ name: "source-closure",
+ components: ordered.flatMap((unit) => unit.components),
+ });
+ const module = sealTypedModule({
+ id: `source-closure:${digestOf(ordered.map((unit) => unit.unit.semanticDigest)).slice("sha256:".length)}`,
+ closureDigest: request.closure.digest,
+ records,
+ });
+ const program = link(request.closure, [module]);
+ const catalog = [...fragments.values()].sort((left, right) => left.id.localeCompare(right.id));
+ const elaboration = elaborateAuthorModule(program, author, (id) => fragments.get(id));
+ const units = ordered.map((unit) => unit.unit).sort((left, right) => left.id.localeCompare(right.id));
+ const closureContent = {
+ format: "svml.source-closure@1" as const,
+ entry: entry.unit.id,
+ units,
+ };
+ const components = new Map(author.components.map((component) => [component.id, component]));
+ const sourceClosure: SourceClosure = { ...closureContent, id: digestOf(closureContent) };
+ verifySourceClosure(sourceClosure);
+ return {
+ closure: sourceClosure,
+ module,
+ author,
+ fragments: catalog,
+ program,
+ elaboration,
+ exports: entry.exports
+ .map((item) => ({
+ name: item.name,
+ type: item.type,
+ ref: graphRefForExport(item, components),
+ }))
+ .sort((left, right) => left.name.localeCompare(right.name)),
+ };
+}
+
+export function verifySourceClosure(closure: SourceClosure): void {
+ assert(closure.format === "svml.source-closure@1", "UNSUPPORTED_SOURCE_CLOSURE", "unsupported Source Closure format");
+ assert(isDigest(closure.id), "INVALID_SOURCE_CLOSURE_DIGEST", "Source Closure digest is invalid");
+ const units = new Map<string, SourceClosureUnit>();
+ for (const unit of closure.units) {
+ assert(unit.format === "svml.source-unit@1", "UNSUPPORTED_SOURCE_UNIT", "unsupported SourceUnit format");
+ assert(isDigest(unit.id), "INVALID_SOURCE_UNIT_DIGEST", "SourceUnit digest is invalid");
+ assert(unit.id === digestOf(sourceUnitContent(unit)), "SOURCE_UNIT_DIGEST_MISMATCH", `SourceUnit ${unit.id} digest differs`);
+ assert(!units.has(unit.id), "DUPLICATE_SOURCE_UNIT", `Source Closure repeats ${unit.id}`, unit.id);
+ assert(isDigest(unit.frontendDigest), "INVALID_FRONTEND_DIGEST", `${unit.id} Frontend digest is invalid`);
+ assert(isDigest(unit.sourceDigest), "INVALID_SOURCE_DIGEST", `${unit.id} source digest is invalid`);
+ assert(isDigest(unit.semanticDigest), "INVALID_SOURCE_SEMANTIC_DIGEST", `${unit.id} semantic digest is invalid`);
+ units.set(unit.id, unit);
+ }
+ assert(units.has(closure.entry), "UNKNOWN_SOURCE_ENTRY", `Source Closure entry ${closure.entry} is absent`);
+ for (const unit of closure.units) {
+ for (const item of unit.imports) {
+ assert(units.has(item.source), "UNKNOWN_SOURCE_IMPORT", `${unit.id} imports absent SourceUnit ${item.source}`);
+ }
+ }
+ assert(
+ closure.id === digestOf(sourceClosureContent(closure)),
+ "SOURCE_CLOSURE_DIGEST_MISMATCH",
+ "Source Closure digest differs",
+ );
+}
+
+export function resolveCompiledSourceExport(
+ compiled: CompiledSourceClosure,
+ name: string,
+ expected?: TypeRef,
+): CompiledSourceExport {
+ const item = compiled.exports.find((candidate) => candidate.name === name);
+ assert(item !== undefined, "UNKNOWN_SOURCE_EXPORT", `unknown source export ${name}`, name);
+ if (expected !== undefined) {
+ assert(
+ sameType(item.type, expected),
+ "SOURCE_EXPORT_TYPE_MISMATCH",
+ `${name} is ${typeName(item.type)}, expected ${typeName(expected)}`,
+ name,
+ );
+ }
+ return item;
+}
diff --git a/packages/elaborator/test/author.test.ts b/packages/elaborator/test/author.test.ts
new file mode 100644
index 00000000..0d8530be
--- /dev/null
+++ b/packages/elaborator/test/author.test.ts
@@ -0,0 +1,258 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ createResolvedClosure,
+ digestOf,
+ link,
+ sealBuildRequest,
+ sealRecord,
+ sealTypedModule,
+ start,
+} from "@svml/core";
+import {
+ AuthorModuleError,
+ elaborateAuthorModule,
+ sealAuthorModule,
+ sealGraphFragment,
+} from "@svml/elaborator";
+import type { GraphFragment } from "@svml/elaborator";
+import type {
+ LinkedProgram,
+ ModuleManifest,
+ ProducerRef,
+ TypeRef,
+} from "@svml/protocol";
+
+const laboratory = { name: "example.laboratory", version: "1" } as const;
+const sampleType = { module: laboratory, name: "Sample" } satisfies TypeRef;
+const measurementType = { module: laboratory, name: "Measurement" } satisfies TypeRef;
+const reportType = { module: laboratory, name: "Report" } satisfies TypeRef;
+const measureProducer = { module: laboratory, name: "measure" } satisfies ProducerRef;
+const reportProducer = { module: laboratory, name: "write-report" } satisfies ProducerRef;
+const echoProducer = { module: laboratory, name: "echo-sample" } satisfies ProducerRef;
+
+const manifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: laboratory.name,
+ version: laboratory.version,
+ dependencies: [],
+ types: [
+ { name: sampleType.name, schema: { kind: "string", minLength: 1 } },
+ { name: measurementType.name, schema: { kind: "number" } },
+ { name: reportType.name, schema: { kind: "string", minLength: 1 } },
+ ],
+ capabilities: [],
+ surfaces: [],
+ producers: [
+ {
+ name: measureProducer.name,
+ inputs: [{ name: "sample", type: sampleType }],
+ outputs: [{ name: "measurement", type: measurementType }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.laboratory/measure",
+ digest: digestOf("example.laboratory/measure@1"),
+ },
+ },
+ {
+ name: reportProducer.name,
+ inputs: [{ name: "measurement", type: measurementType }],
+ outputs: [{ name: "report", type: reportType }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.laboratory/write-report",
+ digest: digestOf("example.laboratory/write-report@1"),
+ },
+ },
+ {
+ name: echoProducer.name,
+ inputs: [{ name: "sample", type: sampleType }],
+ outputs: [{ name: "sample", type: sampleType }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.laboratory/echo-sample",
+ digest: digestOf("example.laboratory/echo-sample@1"),
+ },
+ },
+ ],
+};
+
+const closure = createResolvedClosure([manifest]);
+
+function program(): LinkedProgram {
+ const origin = {
+ kind: "authored" as const,
+ sourceDigest: digestOf("source:laboratory"),
+ frontendClosureDigest: digestOf("frontend:none"),
+ };
+ return link(closure, [sealTypedModule({
+ id: "laboratory-inputs",
+ closureDigest: closure.digest,
+ records: [sealRecord({
+ id: "sample:soil",
+ type: sampleType,
+ value: { kind: "inline", value: "soil" },
+ conformance: "exact",
+ origin,
+ })],
+ })]);
+}
+
+function singleOperationFragment(
+ name: string,
+ inputName: string,
+ inputType: TypeRef,
+ producer: ProducerRef,
+ resultName: string,
+ resultType: TypeRef,
+): GraphFragment {
+ return sealGraphFragment({
+ name,
+ inputs: [{ name: inputName, type: inputType }],
+ operations: [{
+ id: "produce",
+ producer,
+ inputs: { [inputName]: { kind: "fragment-input", name: inputName } },
+ result: { kind: "output", name: resultName },
+ }],
+ exports: [{
+ name: "result",
+ type: resultType,
+ root: { kind: "fragment-operation", operation: "produce" },
+ semanticInputs: [inputName],
+ fidelity: "exact",
+ }],
+ });
+}
+
+const measureFragment = singleOperationFragment(
+ "measure-sample",
+ "sample",
+ sampleType,
+ measureProducer,
+ "measurement",
+ measurementType,
+);
+const reportFragment = singleOperationFragment(
+ "write-report",
+ "measurement",
+ measurementType,
+ reportProducer,
+ "report",
+ reportType,
+);
+const echoFragment = singleOperationFragment(
+ "echo-sample",
+ "sample",
+ sampleType,
+ echoProducer,
+ "sample",
+ sampleType,
+);
+const fragments = new Map([
+ [measureFragment.id, measureFragment],
+ [reportFragment.id, reportFragment],
+ [echoFragment.id, echoFragment],
+]);
+
+test("Author linking resolves forward component references without Text or video contracts", () => {
+ const linked = program();
+ const author = sealAuthorModule({
+ name: "soil-analysis",
+ components: [
+ {
+ id: "final-report",
+ fragment: reportFragment.id,
+ inputs: {
+ measurement: {
+ kind: "component-output",
+ component: "measurement",
+ output: "result",
+ },
+ },
+ outputs: { result: "report:final" },
+ },
+ {
+ id: "measurement",
+ fragment: measureFragment.id,
+ inputs: { sample: { kind: "record", id: "sample:soil" } },
+ outputs: { result: "measurement:soil" },
+ },
+ ],
+ });
+
+ const elaborated = elaborateAuthorModule(linked, author, (id) => fragments.get(id));
+ assert.equal(elaborated.graph.outputs.length, 2);
+ assert.deepEqual(
+ elaborated.graph.outputs.map((output) => output.id),
+ ["measurement:soil", "report:final"],
+ );
+ const reportOperation = elaborated.graph.operations.find((operation) =>
+ operation.producer.name === reportProducer.name);
+ assert.deepEqual(reportOperation?.inputs.measurement, {
+ kind: "logical-output",
+ id: "measurement:soil",
+ });
+
+ const request = sealBuildRequest({
+ graph: elaborated.graph.id,
+ targets: [{ output: "report:final", accepts: "exact" }],
+ bindings: [],
+ });
+ const state = start(linked, elaborated.graph, request);
+ assert.deepEqual(
+ state.plan.steps.map((step) => step.producer.name).sort(),
+ [measureProducer.name, reportProducer.name].sort(),
+ );
+ const measurementStep = state.plan.steps.find((step) => step.producer.name === measureProducer.name);
+ const reportStep = state.plan.steps.find((step) => step.producer.name === reportProducer.name);
+ assert.equal(reportStep?.inputs.measurement, measurementStep?.outputs.measurement);
+});
+
+test("Author linking rejects cycles before producing a Core graph", () => {
+ const author = sealAuthorModule({
+ name: "cyclic-laboratory",
+ components: [
+ {
+ id: "left",
+ fragment: echoFragment.id,
+ inputs: {
+ sample: { kind: "component-output", component: "right", output: "result" },
+ },
+ outputs: { result: "sample:left" },
+ },
+ {
+ id: "right",
+ fragment: echoFragment.id,
+ inputs: {
+ sample: { kind: "component-output", component: "left", output: "result" },
+ },
+ outputs: { result: "sample:right" },
+ },
+ ],
+ });
+ assert.throws(
+ () => elaborateAuthorModule(program(), author, (id) => fragments.get(id)),
+ (error: unknown) => error instanceof AuthorModuleError && error.code === "AUTHOR_COMPONENT_CYCLE",
+ );
+});
+
+test("Author linking checks symbolic input types before Graph verification", () => {
+ const author = sealAuthorModule({
+ name: "invalid-laboratory",
+ components: [{
+ id: "final-report",
+ fragment: reportFragment.id,
+ inputs: { measurement: { kind: "record", id: "sample:soil" } },
+ outputs: { result: "report:invalid" },
+ }],
+ });
+ assert.throws(
+ () => elaborateAuthorModule(program(), author, (id) => fragments.get(id)),
+ (error: unknown) => error instanceof AuthorModuleError && error.code === "AUTHOR_INPUT_TYPE_MISMATCH",
+ );
+});
diff --git a/packages/elaborator/test/fragment.test.ts b/packages/elaborator/test/fragment.test.ts
index 0d1166c2..1f557a0e 100644
--- a/packages/elaborator/test/fragment.test.ts
+++ b/packages/elaborator/test/fragment.test.ts
@@ -3,9 +3,8 @@ import test from "node:test";
import {
contractTypes,
- contractsManifest,
- contractsManifestDigest,
- contractsModuleRef,
+ videoContractDependencies,
+ videoContractManifests,
} from "@svml/contracts";
import {
createResolvedClosure,
@@ -49,7 +48,7 @@ const manifest: ModuleManifest = {
format: "svml.module@0",
name: testModule.name,
version: testModule.version,
- dependencies: [{ module: contractsModuleRef, digest: contractsManifestDigest }],
+ dependencies: [videoContractDependencies.speech],
types: [{ name: requestType.name, schema: { kind: "string", minLength: 1 } }],
capabilities: [],
surfaces: [],
@@ -69,7 +68,7 @@ const manifest: ModuleManifest = {
}],
};
-const closure = createResolvedClosure([contractsManifest, speechTakeManifest, manifest]);
+const closure = createResolvedClosure([...videoContractManifests, speechTakeManifest, manifest]);
function program(): LinkedProgram {
const origin = {
@@ -150,11 +149,11 @@ function speechFragment(): GraphFragment {
},
{
name: "visual",
- type: contractTypes.speechVisualTrack,
+ type: contractTypes.visualTrack,
root: operation("visual"),
semanticInputs: ["request", "style"],
affinity: [{
- resultPointer: "/basisDigest",
+ resultPointer: "/sources/0/digest",
source: operation("generate"),
sourcePointer: "/basisDigest",
}],
diff --git a/packages/film/README.md b/packages/film/README.md
new file mode 100644
index 00000000..020b586d
--- /dev/null
+++ b/packages/film/README.md
@@ -0,0 +1,20 @@
+# `@svml/film`
+
+Official package-owned assembly layer between peer Tracks and the generic Composition waist.
+Film is an ordinary author component and an optional Target, not a Core root or a privileged video
+type.
+
+The package lowers one concrete Film declaration into a finite `FilmTrackSet` fold, then compiles
+that set into `Composition`. This supports any number and mix
+of VisualTrack and AudioTrack inputs while every Core Operation retains a fixed manifest-declared
+port list and one atomic result.
+
+`FilmTrackSet` is an immutable lowering value, not an author-facing workflow collection. Each append
+result binds the previous set digest and the newly added Track digest. The final Composition remains
+order-independent because the public contract canonicalizes Tracks and visual ordering belongs to
+each Present's absolute stacking key.
+
+The official Structured Surface validates an imported generic SVS Recipe into a nominal
+`FilmProgram`, type-checks each `<film:Track source={...}/>` reference and generates the finite fold.
+Child order is organizational: Track and Present identity, timing and absolute stacking remain in
+their own typed values. Final rendering is a separate author package and capability.
diff --git a/packages/film/package.json b/packages/film/package.json
new file mode 100644
index 00000000..ce216260
--- /dev/null
+++ b/packages/film/package.json
@@ -0,0 +1,22 @@
+{
+ "name": "@svml/film",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "dependencies": {
+ "@svml/contracts": "workspace:*",
+ "@svml/elaborator": "workspace:*",
+ "@svml/protocol": "workspace:*",
+ "@svml/svs": "workspace:*",
+ "@svml/text": "workspace:*"
+ },
+ "devDependencies": {
+ "@svml/core": "workspace:*",
+ "@svml/driver-node": "workspace:*",
+ "@svml/hyperframes": "workspace:*",
+ "@svml/text-track": "workspace:*"
+ }
+}
diff --git a/packages/film/src/fragment.ts b/packages/film/src/fragment.ts
new file mode 100644
index 00000000..3a0b7dd1
--- /dev/null
+++ b/packages/film/src/fragment.ts
@@ -0,0 +1,83 @@
+import { contractTypes } from "@svml/contracts";
+import { sealGraphFragment } from "@svml/elaborator";
+import type { FragmentOperation } from "@svml/elaborator";
+
+import { filmProducers, filmTypes } from "./manifest.js";
+import type { FilmAssemblyFragmentOptions, FilmTrackInput } from "./types.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+function assertTrackInputs(tracks: readonly FilmTrackInput[]): FilmTrackInput[] {
+ const names = new Set(["program", "space"]);
+ return [...tracks]
+ .map((track) => ({ name: track.name.trim(), kind: track.kind }))
+ .sort((left, right) => left.name.localeCompare(right.name))
+ .map((track) => {
+ if (!track.name) throw new Error("Film Track input name must not be empty.");
+ if (names.has(track.name)) throw new Error(`Film Track input name ${track.name} is reserved or duplicated.`);
+ names.add(track.name);
+ return track;
+ });
+}
+
+/**
+ * Create one hygienic, finite Fragment for a concrete Film declaration. The
+ * author module decides how many Track references it has; Core still receives
+ * ordinary fixed-port Operations after this lowering.
+ */
+export function createFilmAssemblyFragment(options: FilmAssemblyFragmentOptions) {
+ const tracks = assertTrackInputs(options.tracks);
+ const operations: FragmentOperation[] = [{
+ id: "track-set:empty",
+ producer: filmProducers.createTrackSet,
+ inputs: { space: input("space") },
+ result: { kind: "output" as const, name: "set" },
+ }];
+ let current = "track-set:empty";
+ tracks.forEach((track, index) => {
+ const id = `track-set:append:${String(index).padStart(4, "0")}`;
+ operations.push({
+ id,
+ producer: track.kind === "visual" ? filmProducers.appendVisualTrack : filmProducers.appendAudioTrack,
+ inputs: { set: operation(current), track: input(track.name) },
+ result: { kind: "output" as const, name: "set" },
+ });
+ current = id;
+ });
+ operations.push({
+ id: "film:composition",
+ producer: filmProducers.compileComposition,
+ inputs: { program: input("program"), set: operation(current) },
+ result: { kind: "output" as const, name: "composition" },
+ });
+ const semanticInputs = ["program", "space", ...tracks.map((track) => track.name)];
+ return sealGraphFragment({
+ name: options.name?.trim() || "@svml/film/assembly@1",
+ inputs: [
+ { name: "program", type: filmTypes.program },
+ { name: "space", type: contractTypes.programSpace },
+ ...tracks.map((track) => ({
+ name: track.name,
+ type: track.kind === "visual" ? contractTypes.visualTrack : contractTypes.audioTrack,
+ })),
+ ],
+ operations,
+ exports: [
+ {
+ name: "composition",
+ type: contractTypes.composition,
+ root: operation("film:composition"),
+ semanticInputs,
+ affinity: [
+ { resultPointer: "/id", source: input("program"), sourcePointer: "/id" },
+ { resultPointer: "/programSpace/digest", source: input("space"), sourcePointer: "/digest" },
+ { resultPointer: "/canvas/width", source: input("program"), sourcePointer: "/canvas/width" },
+ { resultPointer: "/canvas/height", source: input("program"), sourcePointer: "/canvas/height" },
+ { resultPointer: "/canvas/clearColor", source: input("program"), sourcePointer: "/canvas/clearColor" },
+ ],
+ fidelity: "exact",
+ },
+ ],
+ });
+}
diff --git a/packages/film/src/index.ts b/packages/film/src/index.ts
new file mode 100644
index 00000000..cba24996
--- /dev/null
+++ b/packages/film/src/index.ts
@@ -0,0 +1,28 @@
+export { createFilmAssemblyFragment } from "./fragment.js";
+export {
+ filmManifest,
+ filmManifestDigest,
+ filmModuleRef,
+ filmProgramSchema,
+ filmProducers,
+ filmSurfaceImplementationDigest,
+ filmTrackSetSchema,
+ filmTypes,
+} from "./manifest.js";
+export {
+ appendFilmAudioTrack,
+ appendFilmAudioTrackImplementationDigest,
+ appendFilmVisualTrack,
+ appendFilmVisualTrackImplementationDigest,
+ assertFilmProgramIdentity,
+ assertFilmTrackSetIdentity,
+ compileFilmComposition,
+ compileFilmCompositionImplementationDigest,
+ computeFilmProgramDigest,
+ computeFilmTrackSetDigest,
+ createFilmTrackSet,
+ createFilmTrackSetImplementationDigest,
+ sealFilmProgram,
+} from "./program.js";
+export { decodeFilmSurface } from "./surface.js";
+export type * from "./types.js";
diff --git a/packages/film/src/manifest.ts b/packages/film/src/manifest.ts
new file mode 100644
index 00000000..85ed728e
--- /dev/null
+++ b/packages/film/src/manifest.ts
@@ -0,0 +1,191 @@
+import {
+ audioTrackSchema,
+ compositionSchema,
+ contractTypes,
+ programSpaceSchema,
+ videoContractDependencies,
+ visualTrackSchema,
+} from "@svml/contracts";
+import { digestOf } from "@svml/protocol";
+import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@svml/protocol";
+import { svsManifest, svsModuleRef } from "@svml/svs";
+
+import {
+ appendFilmAudioTrackImplementationDigest,
+ appendFilmVisualTrackImplementationDigest,
+ compileFilmCompositionImplementationDigest,
+ createFilmTrackSetImplementationDigest,
+} from "./program.js";
+
+export const filmModuleRef = { name: "@svml/film", version: "0.0.0-dev" } as const;
+export const filmSurfaceImplementationDigest = digestOf("@svml/film/surface@1");
+export const filmTypes = {
+ program: { module: filmModuleRef, name: "FilmProgram" },
+ trackSet: { module: filmModuleRef, name: "FilmTrackSet" },
+} satisfies Record<string, TypeRef>;
+export const filmProducers = {
+ createTrackSet: { module: filmModuleRef, name: "create-track-set" },
+ appendVisualTrack: { module: filmModuleRef, name: "append-visual-track" },
+ appendAudioTrack: { module: filmModuleRef, name: "append-audio-track" },
+ compileComposition: { module: filmModuleRef, name: "compile-composition" },
+} satisfies Record<string, ProducerRef>;
+
+const string = { kind: "string", minLength: 1 } as const;
+const integer = { kind: "number", integer: true, minimum: 1 } as const;
+const digest = { kind: "string", minLength: 71, maxLength: 71 } as const;
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({
+ kind: "object",
+ fields,
+});
+
+const canvasSchema = object({
+ width: { schema: integer },
+ height: { schema: integer },
+ clearColor: { schema: string },
+});
+const frameRateSchema = object({
+ numerator: { schema: integer },
+ denominator: { schema: integer },
+});
+
+export const filmProgramSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.film-program@1" } },
+ digest: { schema: digest },
+ id: { schema: string },
+ frameRate: { schema: frameRateSchema },
+ canvas: { schema: canvasSchema },
+});
+
+export const filmTrackSetSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.film-track-set@1" } },
+ digest: { schema: digest },
+ programSpace: { schema: programSpaceSchema },
+ tracks: {
+ schema: {
+ kind: "array",
+ items: { kind: "oneOf", variants: [visualTrackSchema, audioTrackSchema] },
+ },
+ },
+ lastAddition: {
+ schema: object({
+ previousSetDigest: { schema: digest },
+ trackDigest: { schema: digest },
+ }),
+ optional: true,
+ },
+});
+
+export const filmManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: filmModuleRef.name,
+ version: filmModuleRef.version,
+ dependencies: [
+ videoContractDependencies.programSpace,
+ videoContractDependencies.composition,
+ { module: svsModuleRef, digest: digestOf(svsManifest) },
+ ],
+ types: [
+ { name: filmTypes.program.name, schema: filmProgramSchema },
+ { name: filmTypes.trackSet.name, schema: filmTrackSetSchema },
+ ],
+ capabilities: [],
+ surfaces: [{
+ name: "film",
+ tag: "Film",
+ mode: "structured",
+ outputs: [filmTypes.program],
+ implementation: {
+ kind: "trusted-frontend-surface",
+ locator: "@svml/film/surface",
+ digest: filmSurfaceImplementationDigest,
+ },
+ }],
+ producers: [
+ {
+ name: filmProducers.createTrackSet.name,
+ inputs: [{ name: "space", type: contractTypes.programSpace }],
+ outputs: [{
+ name: "set",
+ type: filmTypes.trackSet,
+ affinity: [{ resultPointer: "/programSpace/digest", input: "space", inputPointer: "/digest" }],
+ }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "@svml/film/create-track-set",
+ digest: createFilmTrackSetImplementationDigest,
+ },
+ },
+ {
+ name: filmProducers.appendVisualTrack.name,
+ inputs: [
+ { name: "set", type: filmTypes.trackSet },
+ { name: "track", type: contractTypes.visualTrack },
+ ],
+ outputs: [{
+ name: "set",
+ type: filmTypes.trackSet,
+ affinity: [
+ { resultPointer: "/programSpace/digest", input: "set", inputPointer: "/programSpace/digest" },
+ { resultPointer: "/lastAddition/previousSetDigest", input: "set", inputPointer: "/digest" },
+ { resultPointer: "/lastAddition/trackDigest", input: "track", inputPointer: "/digest" },
+ ],
+ }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "@svml/film/append-visual-track",
+ digest: appendFilmVisualTrackImplementationDigest,
+ },
+ },
+ {
+ name: filmProducers.appendAudioTrack.name,
+ inputs: [
+ { name: "set", type: filmTypes.trackSet },
+ { name: "track", type: contractTypes.audioTrack },
+ ],
+ outputs: [{
+ name: "set",
+ type: filmTypes.trackSet,
+ affinity: [
+ { resultPointer: "/programSpace/digest", input: "set", inputPointer: "/programSpace/digest" },
+ { resultPointer: "/lastAddition/previousSetDigest", input: "set", inputPointer: "/digest" },
+ { resultPointer: "/lastAddition/trackDigest", input: "track", inputPointer: "/digest" },
+ ],
+ }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "@svml/film/append-audio-track",
+ digest: appendFilmAudioTrackImplementationDigest,
+ },
+ },
+ {
+ name: filmProducers.compileComposition.name,
+ inputs: [
+ { name: "program", type: filmTypes.program },
+ { name: "set", type: filmTypes.trackSet },
+ ],
+ outputs: [{
+ name: "composition",
+ type: contractTypes.composition,
+ affinity: [
+ { resultPointer: "/id", input: "program", inputPointer: "/id" },
+ { resultPointer: "/programSpace/digest", input: "set", inputPointer: "/programSpace/digest" },
+ { resultPointer: "/canvas/width", input: "program", inputPointer: "/canvas/width" },
+ { resultPointer: "/canvas/height", input: "program", inputPointer: "/canvas/height" },
+ { resultPointer: "/canvas/clearColor", input: "program", inputPointer: "/canvas/clearColor" },
+ { resultPointer: "/programSpace/frameRate", input: "program", inputPointer: "/frameRate" },
+ ],
+ }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "@svml/film/compile-composition",
+ digest: compileFilmCompositionImplementationDigest,
+ },
+ },
+ ],
+};
+
+export const filmManifestDigest = digestOf(filmManifest);
diff --git a/packages/film/src/program.ts b/packages/film/src/program.ts
new file mode 100644
index 00000000..d52d6bc7
--- /dev/null
+++ b/packages/film/src/program.ts
@@ -0,0 +1,183 @@
+import {
+ assertAudioTrackIdentity,
+ assertCompositionIdentity,
+ assertProgramSpaceIdentity,
+ assertVisualTrackIdentity,
+ sealComposition,
+} from "@svml/contracts";
+import type {
+ AudioTrack,
+ Composition,
+ ProgramSpace,
+ Track,
+ VisualTrack,
+} from "@svml/contracts";
+import { digestOf, isDigest } from "@svml/protocol";
+import type { Digest } from "@svml/protocol";
+
+import type { FilmProgram, FilmTrackSet } from "./types.js";
+
+export const createFilmTrackSetImplementationDigest = digestOf("@svml/film/create-track-set@1");
+export const appendFilmVisualTrackImplementationDigest = digestOf("@svml/film/append-visual-track@1");
+export const appendFilmAudioTrackImplementationDigest = digestOf("@svml/film/append-audio-track@1");
+export const compileFilmCompositionImplementationDigest = digestOf("@svml/film/compile-composition@1");
+
+function assertNonEmpty(value: string, label: string): void {
+ if (!value.trim()) throw new Error(`${label} must not be empty.`);
+}
+
+function trackKey(track: Track): string {
+ return `${track.contract}\u0000${track.id}`;
+}
+
+function filmProgramContent(value: Omit<FilmProgram, "digest">): Omit<FilmProgram, "digest"> {
+ return {
+ contract: "svml.film-program@1",
+ id: value.id,
+ frameRate: { ...value.frameRate },
+ canvas: { ...value.canvas },
+ };
+}
+
+function filmTrackSetContent(value: Omit<FilmTrackSet, "digest">): Omit<FilmTrackSet, "digest"> {
+ return {
+ contract: "svml.film-track-set@1",
+ programSpace: {
+ ...value.programSpace,
+ frameRate: { ...value.programSpace.frameRate },
+ },
+ tracks: [...value.tracks]
+ .map((track) => structuredClone(track))
+ .sort((left, right) => trackKey(left).localeCompare(trackKey(right))),
+ ...(value.lastAddition === undefined ? {} : { lastAddition: { ...value.lastAddition } }),
+ };
+}
+
+export function computeFilmProgramDigest(value: Omit<FilmProgram, "digest">): Digest {
+ return digestOf(filmProgramContent(value));
+}
+
+export function sealFilmProgram(value: Omit<FilmProgram, "digest">): FilmProgram {
+ const content = filmProgramContent(value);
+ return { ...content, digest: digestOf(content) };
+}
+
+export function assertFilmProgramIdentity(program: FilmProgram): void {
+ if (program.contract !== "svml.film-program@1") throw new Error("Unsupported FilmProgram contract.");
+ assertNonEmpty(program.id, "FilmProgram id");
+ if (
+ !Number.isSafeInteger(program.frameRate.numerator)
+ || program.frameRate.numerator <= 0
+ || !Number.isSafeInteger(program.frameRate.denominator)
+ || program.frameRate.denominator <= 0
+ ) {
+ throw new Error("FilmProgram frame rate is invalid.");
+ }
+ if (
+ !Number.isSafeInteger(program.canvas.width)
+ || program.canvas.width <= 0
+ || !Number.isSafeInteger(program.canvas.height)
+ || program.canvas.height <= 0
+ || !/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(program.canvas.clearColor)
+ ) {
+ throw new Error("FilmProgram canvas is invalid.");
+ }
+ const { digest: _digest, ...content } = program;
+ if (!isDigest(program.digest) || program.digest !== computeFilmProgramDigest(content)) {
+ throw new Error("FilmProgram digest does not match its contents.");
+ }
+}
+
+export function computeFilmTrackSetDigest(value: Omit<FilmTrackSet, "digest">): Digest {
+ return digestOf(filmTrackSetContent(value));
+}
+
+function sealFilmTrackSet(value: Omit<FilmTrackSet, "digest">): FilmTrackSet {
+ const content = filmTrackSetContent(value);
+ return { ...content, digest: digestOf(content) };
+}
+
+export function assertFilmTrackSetIdentity(set: FilmTrackSet): void {
+ if (set.contract !== "svml.film-track-set@1") throw new Error("Unsupported FilmTrackSet contract.");
+ assertProgramSpaceIdentity(set.programSpace);
+ const { digest: _digest, ...content } = set;
+ if (!isDigest(set.digest) || set.digest !== computeFilmTrackSetDigest(content)) {
+ throw new Error("FilmTrackSet digest does not match its contents.");
+ }
+ const ids = new Set<string>();
+ for (const track of set.tracks) {
+ if (ids.has(track.id)) throw new Error(`FilmTrackSet contains duplicate Track id ${track.id}.`);
+ ids.add(track.id);
+ if (track.contract === "svml.visual-track@1") assertVisualTrackIdentity(track, set.programSpace);
+ else assertAudioTrackIdentity(track, set.programSpace);
+ }
+ if (set.tracks.length === 0 && set.lastAddition !== undefined) {
+ throw new Error("An empty FilmTrackSet cannot declare a last addition.");
+ }
+ if (set.tracks.length > 0 && set.lastAddition === undefined) {
+ throw new Error("A non-empty FilmTrackSet must declare its last addition.");
+ }
+ if (set.lastAddition !== undefined) {
+ if (!isDigest(set.lastAddition.previousSetDigest) || !isDigest(set.lastAddition.trackDigest)) {
+ throw new Error("FilmTrackSet last addition contains an invalid digest.");
+ }
+ if (!set.tracks.some((track) => track.digest === set.lastAddition?.trackDigest)) {
+ throw new Error("FilmTrackSet last addition does not identify one of its Tracks.");
+ }
+ }
+}
+
+export function createFilmTrackSet(programSpace: ProgramSpace): FilmTrackSet {
+ assertProgramSpaceIdentity(programSpace);
+ return sealFilmTrackSet({
+ contract: "svml.film-track-set@1",
+ programSpace,
+ tracks: [],
+ });
+}
+
+function appendTrack(set: FilmTrackSet, track: Track): FilmTrackSet {
+ assertFilmTrackSetIdentity(set);
+ if (track.contract === "svml.visual-track@1") assertVisualTrackIdentity(track, set.programSpace);
+ else assertAudioTrackIdentity(track, set.programSpace);
+ if (set.tracks.some((existing) => existing.id === track.id)) {
+ throw new Error(`FilmTrackSet already contains Track id ${track.id}.`);
+ }
+ return sealFilmTrackSet({
+ contract: "svml.film-track-set@1",
+ programSpace: set.programSpace,
+ tracks: [...set.tracks, track],
+ lastAddition: {
+ previousSetDigest: set.digest,
+ trackDigest: track.digest,
+ },
+ });
+}
+
+export function appendFilmVisualTrack(set: FilmTrackSet, track: VisualTrack): FilmTrackSet {
+ return appendTrack(set, track);
+}
+
+export function appendFilmAudioTrack(set: FilmTrackSet, track: AudioTrack): FilmTrackSet {
+ return appendTrack(set, track);
+}
+
+export function compileFilmComposition(program: FilmProgram, set: FilmTrackSet): Composition {
+ assertFilmProgramIdentity(program);
+ assertFilmTrackSetIdentity(set);
+ if (
+ program.frameRate.numerator !== set.programSpace.frameRate.numerator
+ || program.frameRate.denominator !== set.programSpace.frameRate.denominator
+ ) {
+ throw new Error("FilmProgram and FilmTrackSet use different frame rates.");
+ }
+ const composition = sealComposition({
+ contract: "svml.composition@1",
+ id: program.id,
+ programSpace: set.programSpace,
+ canvas: program.canvas,
+ tracks: set.tracks,
+ });
+ assertCompositionIdentity(composition);
+ return composition;
+}
diff --git a/packages/film/src/surface.ts b/packages/film/src/surface.ts
new file mode 100644
index 00000000..72dc5c41
--- /dev/null
+++ b/packages/film/src/surface.ts
@@ -0,0 +1,165 @@
+import { contractTypes } from "@svml/contracts";
+import { digestOf } from "@svml/protocol";
+import { svsRecipeType } from "@svml/svs";
+import type { SvsRecipe } from "@svml/svs";
+import type {
+ StructuredElement,
+ StructuredSurfaceHandler,
+ SurfaceResolvedReference,
+ TextAttributeValue,
+} from "@svml/text";
+
+import { createFilmAssemblyFragment } from "./fragment.js";
+import { filmTypes } from "./manifest.js";
+import { sealFilmProgram } from "./program.js";
+
+function localName(value: string): string {
+ return value.includes(":") ? value.slice(value.lastIndexOf(":") + 1) : value;
+}
+
+function exactAttributes(element: StructuredElement, names: readonly string[]): void {
+ const actual = Object.keys(element.attributes).sort();
+ const expected = [...names].sort();
+ if (actual.join("\u0000") !== expected.join("\u0000")) {
+ throw new Error(`${element.name} requires exactly ${expected.join(", ")}`);
+ }
+}
+
+function stringAttribute(element: StructuredElement, name: string): string {
+ const value = element.attributes[name];
+ if (typeof value !== "string" || value.length === 0) {
+ throw new Error(`${element.name}.${name} must be a non-empty string`);
+ }
+ return value;
+}
+
+function referenceAttribute(element: StructuredElement, name: string): string {
+ const value: TextAttributeValue | undefined = element.attributes[name];
+ if (typeof value !== "object" || value.kind !== "reference" || value.path.length === 0) {
+ throw new Error(`${element.name}.${name} must be a whole-value reference`);
+ }
+ return value.path;
+}
+
+function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {
+ return left.module.name === right.module.name
+ && left.module.version === right.module.version
+ && left.name === right.name;
+}
+
+function requiredReference(
+ element: StructuredElement,
+ name: string,
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+ const path = referenceAttribute(element, name);
+ const resolved = resolve(path);
+ if (resolved === undefined) throw new Error(`${element.name}.${name} cannot resolve ${path}`);
+ return resolved;
+}
+
+function recipe(reference: SurfaceResolvedReference, label: string): SvsRecipe {
+ if (!sameType(reference.type, svsRecipeType)) throw new Error(`${label} must reference an SVS Recipe`);
+ const value = reference.record?.value;
+ if (value?.kind !== "inline" || value.value === null || Array.isArray(value.value)
+ || typeof value.value !== "object") {
+ throw new Error(`${label} must reference an authored Recipe value`);
+ }
+ return value.value as SvsRecipe;
+}
+
+function numberProperty(value: SvsRecipe, name: string): number {
+ const property = value.properties[name];
+ if (typeof property !== "number" || !Number.isSafeInteger(property) || property <= 0) {
+ throw new Error(`Film Recipe ${name} must be a positive integer`);
+ }
+ return property;
+}
+
+function colorProperty(value: SvsRecipe, name: string): string {
+ const property = value.properties[name];
+ if (typeof property !== "string" || !/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(property)) {
+ throw new Error(`Film Recipe ${name} must be a six- or eight-digit hex color`);
+ }
+ return property;
+}
+
+function trackChildren(element: StructuredElement): StructuredElement[] {
+ const tracks: StructuredElement[] = [];
+ for (const child of element.children) {
+ if (child.kind === "text") {
+ if (child.value.trim().length > 0) throw new Error(`${element.name} accepts only Track children`);
+ continue;
+ }
+ if (localName(child.name) !== "Track") throw new Error(`${element.name} accepts only Track children`);
+ exactAttributes(child, ["source"]);
+ tracks.push(child);
+ }
+ if (tracks.length === 0) throw new Error(`${element.name} requires at least one Track`);
+ return tracks;
+}
+
+function trackKind(reference: SurfaceResolvedReference): "visual" | "audio" {
+ if (sameType(reference.type, contractTypes.visualTrack)) return "visual";
+ if (sameType(reference.type, contractTypes.audioTrack)) return "audio";
+ throw new Error(`Film Track ${reference.path} must be a VisualTrack or AudioTrack`);
+}
+
+export const decodeFilmSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ exactAttributes(element, ["id", "space", "appearance"]);
+ const id = stringAttribute(element, "id");
+ const space = requiredReference(element, "space", resolveReference);
+ if (!sameType(space.type, contractTypes.programSpace)) {
+ throw new Error(`${element.name}.space must reference ProgramSpace`);
+ }
+ const appearanceReference = requiredReference(element, "appearance", resolveReference);
+ const appearance = recipe(appearanceReference, `${element.name}.appearance`);
+ const expectedProperties = ["background", "frame-rate", "height", "width"];
+ const actualProperties = Object.keys(appearance.properties).sort();
+ if (actualProperties.join("\u0000") !== expectedProperties.join("\u0000")) {
+ throw new Error(`Film Recipe requires exactly ${expectedProperties.join(", ")}`);
+ }
+
+ const programId = `${id}.program`;
+ const program = sealFilmProgram({
+ contract: "svml.film-program@1",
+ id,
+ frameRate: { numerator: numberProperty(appearance, "frame-rate"), denominator: 1 },
+ canvas: {
+ width: numberProperty(appearance, "width"),
+ height: numberProperty(appearance, "height"),
+ clearColor: colorProperty(appearance, "background"),
+ },
+ });
+
+ const tracks = trackChildren(element).map((child) => {
+ const source = requiredReference(child, "source", resolveReference);
+ const name = `track-${digestOf({ ref: source.ref, type: source.type }).slice("sha256:".length, 28)}`;
+ return { name, kind: trackKind(source), source };
+ });
+ if (new Set(tracks.map((track) => track.name)).size !== tracks.length) {
+ throw new Error(`${element.name} cannot include the same Track more than once`);
+ }
+ const fragment = createFilmAssemblyFragment({ name: "@svml/film/surface-assembly@1", tracks });
+
+ return {
+ records: [{
+ id: programId,
+ type: filmTypes.program,
+ value: { kind: "inline", value: program },
+ range: element.range,
+ }],
+ components: [{
+ id,
+ fragment: fragment.id,
+ inputs: {
+ program: { kind: "record", id: programId },
+ space: space.ref,
+ ...Object.fromEntries(tracks.map((track) => [track.name, track.source.ref])),
+ },
+ outputs: { composition: `${id}.composition` },
+ range: element.range,
+ }],
+ fragments: [fragment],
+ };
+};
diff --git a/packages/film/src/types.ts b/packages/film/src/types.ts
new file mode 100644
index 00000000..da29f9de
--- /dev/null
+++ b/packages/film/src/types.ts
@@ -0,0 +1,44 @@
+import type { ProgramSpace, Track } from "@svml/contracts";
+import type { Digest } from "@svml/protocol";
+
+/** Package-owned authoring value. A future Film Surface may produce this record. */
+export type FilmProgram = {
+ readonly contract: "svml.film-program@1";
+ readonly digest: Digest;
+ readonly id: string;
+ readonly frameRate: {
+ readonly numerator: number;
+ readonly denominator: number;
+ };
+ readonly canvas: {
+ readonly width: number;
+ readonly height: number;
+ readonly clearColor: string;
+ };
+};
+
+/**
+ * Immutable package-private fold value used to collect an arbitrary number of
+ * peer Tracks without adding variadic Operation ports to Core.
+ */
+export type FilmTrackSet = {
+ readonly contract: "svml.film-track-set@1";
+ readonly digest: Digest;
+ readonly programSpace: ProgramSpace;
+ readonly tracks: readonly Track[];
+ readonly lastAddition?: {
+ readonly previousSetDigest: Digest;
+ readonly trackDigest: Digest;
+ };
+};
+
+export type FilmTrackInput = {
+ /** Fragment input name used by the author module lowering this Film instance. */
+ readonly name: string;
+ readonly kind: "visual" | "audio";
+};
+
+export type FilmAssemblyFragmentOptions = {
+ readonly name?: string;
+ readonly tracks: readonly FilmTrackInput[];
+};
diff --git a/packages/film/test/film.test.ts b/packages/film/test/film.test.ts
new file mode 100644
index 00000000..320f49c6
--- /dev/null
+++ b/packages/film/test/film.test.ts
@@ -0,0 +1,259 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ contractTypes,
+ sealAudioTrack,
+ sealProgramSpace,
+ sealVisualTrack,
+ videoContractManifests,
+} from "@svml/contracts";
+import {
+ createResolvedClosure,
+ digestOf,
+ link,
+ sealBuildRequest,
+ sealCompiledGraph,
+ sealRecord,
+ sealTypedModule,
+ start,
+} from "@svml/core";
+import { HostRegistry, NodeDriver } from "@svml/driver-node";
+import {
+ bindAuthorFragment,
+ elaborateGraphFragment,
+ mergeFragmentContributions,
+} from "@svml/elaborator";
+import {
+ appendFilmAudioTrack,
+ appendFilmAudioTrackImplementationDigest,
+ appendFilmVisualTrack,
+ appendFilmVisualTrackImplementationDigest,
+ compileFilmComposition,
+ compileFilmCompositionImplementationDigest,
+ createFilmAssemblyFragment,
+ createFilmTrackSet,
+ createFilmTrackSetImplementationDigest,
+ filmManifest,
+ filmProducers,
+ filmTypes,
+ sealFilmProgram,
+} from "@svml/film";
+import {
+ compileHyperframesDocument,
+ compileHyperframesImplementationDigest,
+ hyperframesDocumentFragment,
+ hyperframesManifest,
+ hyperframesProducers,
+ hyperframesTypes,
+} from "@svml/hyperframes";
+import type { CanonicalValue, CompiledGraph, StoredValue, TypedRecord } from "@svml/protocol";
+import { svsManifest } from "@svml/svs";
+import {
+ renderTextTrack,
+ renderTextTrackImplementationDigest,
+ sealTextTrackProgram,
+ textTrackFragment,
+ textTrackManifest,
+ textTrackProducers,
+ textTrackTypes,
+} from "@svml/text-track";
+
+const space = sealProgramSpace({
+ contract: "svml.program-space@0",
+ durationSec: 4,
+ frameRate: { numerator: 30, denominator: 1 },
+});
+const filmProgram = sealFilmProgram({
+ contract: "svml.film-program@1",
+ id: "main-film",
+ frameRate: space.frameRate,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+});
+const textProgram = sealTextTrackProgram({
+ contract: "svml.text-track-program@1",
+ id: "title-track",
+ programSpaceDigest: space.digest,
+ items: [{
+ id: "title",
+ text: "Semantic Video Markup Language",
+ span: { startFrame: 10, endFrameExclusive: 100 },
+ z: 60,
+ tieBreak: "title",
+ box: { xPercent: 8, yPercent: 10, widthPercent: 84, heightPercent: 20 },
+ appearance: { color: "#ffffff", fontSizePx: 56, fontWeight: 800 },
+ }],
+});
+const background = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "background-track",
+ programSpaceDigest: space.digest,
+ sources: [{ name: "fixture", digest: digestOf("background") }],
+ presents: [{
+ id: "background",
+ span: { startFrame: 0, endFrameExclusive: 120 },
+ stacking: { order: 0, tieBreak: "background" },
+ elements: [{ id: "root", kind: "box", order: 0, style: [{ name: "background-color", value: "#223344" }] }],
+ }],
+});
+const audio = sealAudioTrack({
+ contract: "svml.audio-track@1",
+ id: "empty-audio-track",
+ programSpaceDigest: space.digest,
+ sources: [{ name: "fixture", digest: digestOf("audio") }],
+ clips: [],
+});
+
+function inline(record: TypedRecord | undefined): CanonicalValue {
+ assert(record, "missing Producer input");
+ assert.equal(record.value.kind, "inline");
+ return record.value.value;
+}
+
+function stored(value: CanonicalValue): StoredValue {
+ return { kind: "inline", value };
+}
+
+const closure = createResolvedClosure([
+ ...videoContractManifests,
+ svsManifest,
+ hyperframesManifest,
+ filmManifest,
+ textTrackManifest,
+]);
+const origin = {
+ kind: "authored" as const,
+ sourceDigest: digestOf("source:film-test"),
+ frontendClosureDigest: digestOf("frontend:film-test"),
+};
+const records = [
+ sealRecord({ id: "space", type: contractTypes.programSpace, value: stored(space), conformance: "exact", origin }),
+ sealRecord({ id: "film-program", type: filmTypes.program, value: stored(filmProgram), conformance: "exact", origin }),
+ sealRecord({ id: "text-program", type: textTrackTypes.program, value: stored(textProgram), conformance: "exact", origin }),
+ sealRecord({ id: "background", type: contractTypes.visualTrack, value: stored(background), conformance: "exact", origin }),
+ sealRecord({ id: "audio", type: contractTypes.audioTrack, value: stored(audio), conformance: "exact", origin }),
+];
+const linked = link(closure, [sealTypedModule({ id: "author:film-test", closureDigest: closure.digest, records })]);
+
+const textInstance = elaborateGraphFragment(linked, textTrackFragment, {
+ id: "title",
+ fragment: textTrackFragment.id,
+ inputs: {
+ space: { kind: "record", id: "space" },
+ program: { kind: "record", id: "text-program" },
+ },
+});
+const textContribution = bindAuthorFragment(textInstance, { track: "title.track" });
+
+const filmFragment = createFilmAssemblyFragment({
+ name: "example/main-film",
+ tracks: [
+ { name: "title", kind: "visual" },
+ { name: "background", kind: "visual" },
+ { name: "audio", kind: "audio" },
+ ],
+});
+const filmInstance = elaborateGraphFragment(linked, filmFragment, {
+ id: "main-film",
+ fragment: filmFragment.id,
+ inputs: {
+ program: { kind: "record", id: "film-program" },
+ space: { kind: "record", id: "space" },
+ title: { kind: "logical-output", id: "title.track" },
+ background: { kind: "record", id: "background" },
+ audio: { kind: "record", id: "audio" },
+ },
+});
+const filmContribution = bindAuthorFragment(filmInstance, {
+ composition: "main.composition",
+});
+const hyperframesInstance = elaborateGraphFragment(linked, hyperframesDocumentFragment, {
+ id: "main-render",
+ fragment: hyperframesDocumentFragment.id,
+ inputs: {
+ composition: { kind: "logical-output", id: "main.composition" },
+ },
+});
+const hyperframesContribution = bindAuthorFragment(hyperframesInstance, {
+ document: "main.document",
+});
+const merged = mergeFragmentContributions(
+ { outputs: [], candidates: [], operations: [] },
+ textContribution,
+ filmContribution,
+ hyperframesContribution,
+);
+const graph: CompiledGraph = sealCompiledGraph({ program: linked.semanticDigest, ...merged });
+
+function build(target: string) {
+ return start(linked, graph, sealBuildRequest({
+ graph: graph.id,
+ targets: [{ output: target, accepts: "exact" }],
+ bindings: [],
+ }));
+}
+
+function producerNames(target: string): string[] {
+ return build(target).plan.steps.map((step) => step.producer.name);
+}
+
+function producerModules(target: string): string[] {
+ return build(target).plan.steps.map((step) => step.producer.module.name);
+}
+
+test("Film stops at Composition and Hyperframes remains an ordinary downstream Fragment", () => {
+ assert.deepEqual(producerNames("title.track"), [textTrackProducers.render.name]);
+ assert.equal(producerModules("main.composition").includes(hyperframesProducers.compile.module.name), false);
+ assert.deepEqual(producerNames("main.composition").filter((name) => name.startsWith("append-")).sort(), [
+ filmProducers.appendAudioTrack.name,
+ filmProducers.appendVisualTrack.name,
+ filmProducers.appendVisualTrack.name,
+ ].sort());
+ assert.equal(
+ producerModules("main.document").filter((name) => name === hyperframesProducers.compile.module.name).length,
+ 1,
+ );
+});
+
+test("the Driver folds peer Tracks, then independently compiles the Composition", async () => {
+ const registry = new HostRegistry();
+ registry.registerProducer(textTrackProducers.render, renderTextTrackImplementationDigest, ({ inputs }) => ({
+ outputs: { track: stored(renderTextTrack(inline(inputs.space) as typeof space, inline(inputs.program) as typeof textProgram)) },
+ needs: {},
+ }));
+ registry.registerProducer(filmProducers.createTrackSet, createFilmTrackSetImplementationDigest, ({ inputs }) => ({
+ outputs: { set: stored(createFilmTrackSet(inline(inputs.space) as typeof space)) },
+ needs: {},
+ }));
+ registry.registerProducer(filmProducers.appendVisualTrack, appendFilmVisualTrackImplementationDigest, ({ inputs }) => ({
+ outputs: { set: stored(appendFilmVisualTrack(inline(inputs.set) as never, inline(inputs.track) as never)) },
+ needs: {},
+ }));
+ registry.registerProducer(filmProducers.appendAudioTrack, appendFilmAudioTrackImplementationDigest, ({ inputs }) => ({
+ outputs: { set: stored(appendFilmAudioTrack(inline(inputs.set) as never, inline(inputs.track) as never)) },
+ needs: {},
+ }));
+ registry.registerProducer(filmProducers.compileComposition, compileFilmCompositionImplementationDigest, ({ inputs }) => ({
+ outputs: { composition: stored(compileFilmComposition(inline(inputs.program) as never, inline(inputs.set) as never)) },
+ needs: {},
+ }));
+ registry.registerProducer(hyperframesProducers.compile, compileHyperframesImplementationDigest, ({ inputs }) => ({
+ outputs: { document: stored(compileHyperframesDocument(inline(inputs.composition) as never)) },
+ needs: {},
+ }));
+
+ const result = await new NodeDriver({ registry }).run(build("main.document"));
+ assert.equal(result.status, "complete");
+ const documentRecord = result.state.records.find((record) => record.type.module.name === hyperframesTypes.document.module.name);
+ assert(documentRecord);
+ const document = inline(documentRecord) as { readonly html: string };
+ assert.match(document.html, /Semantic Video Markup Language/u);
+ assert.match(document.html, /background-track/u);
+ assert.equal(result.state.records.filter((record) => record.type.name === filmTypes.trackSet.name).length, 4);
+});
+
+test("Film rejects duplicate Track ids before Composition", () => {
+ const set = appendFilmVisualTrack(createFilmTrackSet(space), background);
+ const duplicate = sealVisualTrack({ ...background, sources: [{ name: "other", digest: digestOf("other") }] });
+ assert.throws(() => appendFilmVisualTrack(set, duplicate), /already contains Track id/u);
+});
diff --git a/packages/film/test/surface.test.ts b/packages/film/test/surface.test.ts
new file mode 100644
index 00000000..ba486fbe
--- /dev/null
+++ b/packages/film/test/surface.test.ts
@@ -0,0 +1,185 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ contractTypes,
+ sealAudioTrack,
+ sealProgramSpace,
+ sealVisualTrack,
+ videoContractDependencies,
+ videoContractManifests,
+} from "@svml/contracts";
+import { createResolvedClosure, digestOf, sealBuildRequest, start } from "@svml/core";
+import {
+ AuthorFrontendRegistry,
+ compileSourceClosure,
+ resolveCompiledSourceExport,
+} from "@svml/elaborator";
+import type { AuthorSourceUnit } from "@svml/elaborator";
+import {
+ decodeFilmSurface,
+ filmManifest,
+ filmModuleRef,
+ filmProducers,
+ filmSurfaceImplementationDigest,
+ filmTypes,
+} from "@svml/film";
+import type { ModuleManifest } from "@svml/protocol";
+import { svsFrontend, svsFrontendId, svsManifest } from "@svml/svs";
+import {
+ TextSurfaceRegistry,
+ createTextAuthorFrontend,
+ textAuthorFrontendId,
+} from "@svml/text";
+
+const fixtureModule = { name: "example.film-fixture", version: "1" } as const;
+const fixtureSurfaceDigest = digestOf("example.film-fixture/inputs-surface@1");
+const fixtureManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: fixtureModule.name,
+ version: fixtureModule.version,
+ dependencies: [
+ videoContractDependencies.programSpace,
+ videoContractDependencies.composition,
+ ],
+ types: [],
+ capabilities: [],
+ surfaces: [{
+ name: "inputs",
+ tag: "Inputs",
+ mode: "structured",
+ outputs: [contractTypes.programSpace, contractTypes.visualTrack, contractTypes.audioTrack],
+ implementation: {
+ kind: "trusted-frontend-surface",
+ locator: "example.film-fixture/inputs-surface",
+ digest: fixtureSurfaceDigest,
+ },
+ }],
+ producers: [],
+};
+
+const space = sealProgramSpace({
+ contract: "svml.program-space@0",
+ durationSec: 2,
+ frameRate: { numerator: 30, denominator: 1 },
+});
+const visual = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "visual",
+ programSpaceDigest: space.digest,
+ sources: [{ name: "fixture", digest: digestOf("film-surface-visual") }],
+ presents: [],
+});
+const audio = sealAudioTrack({
+ contract: "svml.audio-track@1",
+ id: "audio",
+ programSpaceDigest: space.digest,
+ sources: [{ name: "fixture", digest: digestOf("film-surface-audio") }],
+ clips: [],
+});
+
+const closure = createResolvedClosure([
+ ...videoContractManifests,
+ svsManifest,
+ fixtureManifest,
+ filmManifest,
+]);
+
+function source(id: string, text: string): AuthorSourceUnit {
+ return { id, name: id.split("/").at(-1) ?? id, text };
+}
+
+const validStyles = `<sheet version="1">
+ film.vertical {
+ width: 1080;
+ height: 1920;
+ frame-rate: 30;
+ background: #09090B;
+ }
+</sheet>`;
+
+async function compileFilm(options: { readonly reverse?: boolean; readonly styles?: string } = {}) {
+ const surfaces = new TextSurfaceRegistry();
+ surfaces.registerStructured(fixtureModule, "inputs", fixtureSurfaceDigest, ({ element }) => ({
+ records: [
+ { id: "space", type: contractTypes.programSpace, value: { kind: "inline", value: space }, range: element.range },
+ { id: "visual", type: contractTypes.visualTrack, value: { kind: "inline", value: visual }, range: element.range },
+ { id: "audio", type: contractTypes.audioTrack, value: { kind: "inline", value: audio }, range: element.range },
+ ],
+ components: [],
+ fragments: [],
+ }));
+ surfaces.registerStructured(
+ filmModuleRef,
+ "film",
+ filmSurfaceImplementationDigest,
+ decodeFilmSurface,
+ );
+ const frontends = new AuthorFrontendRegistry();
+ frontends.register(createTextAuthorFrontend({
+ registry: surfaces,
+ resolveModule(request) {
+ return request.from.startsWith("@svml/film") ? filmModuleRef : fixtureModule;
+ },
+ }));
+ frontends.register(svsFrontend);
+
+ const tracks = options.reverse === true
+ ? `<film:Track source={audio}/><film:Track source={visual}/>`
+ : `<film:Track source={visual}/><film:Track source={audio}/>`;
+ return await compileSourceClosure({
+ entry: source("/project/main.svml", `<svml>
+ <import as="fixture" from="example.film-fixture@1"/>
+ <import as="film" from="@svml/film@1"/>
+ <import as="studio" from="./studio.svs" using="${svsFrontendId}"/>
+ <fixture:Inputs/>
+ <film:Film id="main" space={space} appearance={studio.film.vertical}>${tracks}</film:Film>
+ </svml>`),
+ frontend: textAuthorFrontendId,
+ closure,
+ frontends,
+ resolveSource() {
+ return source("/project/studio.svs", options.styles ?? validStyles);
+ },
+ });
+}
+
+test("the official Film Surface validates SVS and lowers dynamic peer Tracks", async () => {
+ const compiled = await compileFilm();
+ const program = compiled.module.records.find((record) => record.type.name === filmTypes.program.name);
+ assert.deepEqual(program?.value.kind === "inline" ? program.value.value : undefined, {
+ contract: "svml.film-program@1",
+ digest: program?.value.kind === "inline"
+ ? (program.value.value as { readonly digest: string }).digest
+ : undefined,
+ id: "main",
+ frameRate: { numerator: 30, denominator: 1 },
+ canvas: { width: 1080, height: 1920, clearColor: "#09090B" },
+ });
+ const target = resolveCompiledSourceExport(compiled, "main.composition", contractTypes.composition);
+ assert.equal(target.ref.kind, "logical-output");
+ const build = start(compiled.program, compiled.elaboration.graph, sealBuildRequest({
+ graph: compiled.elaboration.graph.id,
+ targets: [{ output: target.ref.kind === "logical-output" ? target.ref.id : "", accepts: "exact" }],
+ bindings: [],
+ }));
+ assert.deepEqual(build.plan.steps.map((step) => step.producer.name).sort(), [
+ filmProducers.createTrackSet.name,
+ filmProducers.appendAudioTrack.name,
+ filmProducers.appendVisualTrack.name,
+ filmProducers.compileComposition.name,
+ ].sort());
+});
+
+test("Film child order remains organizational, not graph meaning", async () => {
+ const normal = await compileFilm();
+ const reversed = await compileFilm({ reverse: true });
+ assert.equal(normal.elaboration.graph.id, reversed.elaboration.graph.id);
+});
+
+test("Film rejects an invalid package-owned Recipe during check", async () => {
+ await assert.rejects(
+ compileFilm({ styles: `<sheet version="1">film.vertical { width: 1080; }</sheet>` }),
+ /Film Recipe requires exactly/u,
+ );
+});
diff --git a/packages/hyperframes-render/README.md b/packages/hyperframes-render/README.md
new file mode 100644
index 00000000..ac16d8cc
--- /dev/null
+++ b/packages/hyperframes-render/README.md
@@ -0,0 +1,25 @@
+# `@svml/hyperframes-render`
+
+Explicit author and capability boundary for final HyperFrames video rendering.
+
+The package owns `<render:Video composition={...}/>` and lowers it to three ordinary Operations:
+
+1. compile the referenced `Composition` into a content-addressed `HyperframesDocument`;
+2. request the exact `@svml/hyperframes-render#render-video` capability;
+3. project the fulfilled render Product into the shared `MediaArtifactRef` contract.
+
+The package is not a renderer and contains no queue, credentials or deployment choice. A local
+HyperFrames process, a hosted Hypit endpoint or another conforming execution package may register a
+Provider for the exact capability. That Provider receives an already compiled document and returns
+a Product bound to its digest, ProgramSpace, rational frame rate, frame count and canvas. It does not
+parse SVML or decide which Composition to render. A Product that claims another frame domain is
+rejected by Producer affinity before it can become a final video Record.
+
+Core sees one render Need. Frame workers, contiguous or interleaved chunks, retries, image-sequence
+assembly and the final one-time audio mux remain inside the selected Endpoint. This preserves one
+author-visible result while allowing a local HyperFrames process or a distributed Lambda adapter to
+render every frame in parallel according to deployment policy.
+
+Film is not a dependency of this author meaning. Any package that produces the common Composition
+contract can feed the render Surface. Conversely, targeting Composition never demands this package;
+rendering exists only when the author declares and the Build targets the video output.
diff --git a/packages/hyperframes-render/package.json b/packages/hyperframes-render/package.json
new file mode 100644
index 00000000..38af2666
--- /dev/null
+++ b/packages/hyperframes-render/package.json
@@ -0,0 +1,20 @@
+{
+ "name": "@svml/hyperframes-render",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "dependencies": {
+ "@svml/contracts": "workspace:*",
+ "@svml/elaborator": "workspace:*",
+ "@svml/hyperframes": "workspace:*",
+ "@svml/protocol": "workspace:*",
+ "@svml/text": "workspace:*"
+ },
+ "devDependencies": {
+ "@svml/core": "workspace:*",
+ "@svml/driver-node": "workspace:*"
+ }
+}
diff --git a/packages/hyperframes-render/src/fragment.ts b/packages/hyperframes-render/src/fragment.ts
new file mode 100644
index 00000000..8cd303af
--- /dev/null
+++ b/packages/hyperframes-render/src/fragment.ts
@@ -0,0 +1,48 @@
+import { contractTypes } from "@svml/contracts";
+import { sealGraphFragment } from "@svml/elaborator";
+import { hyperframesProducers } from "@svml/hyperframes";
+
+import {
+ hyperframesRenderProducers,
+ hyperframesRenderTypes,
+} from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+export const hyperframesRenderFragment = sealGraphFragment({
+ name: "@svml/hyperframes-render/video@1",
+ inputs: [{ name: "composition", type: contractTypes.composition }],
+ operations: [
+ {
+ id: "compile-document",
+ producer: hyperframesProducers.compile,
+ inputs: { composition: input("composition") },
+ result: { kind: "output", name: "document" },
+ },
+ {
+ id: "request-render",
+ producer: hyperframesRenderProducers.request,
+ inputs: { document: operation("compile-document") },
+ result: { kind: "need", name: "product", accepts: "exact" },
+ },
+ {
+ id: "project-video",
+ producer: hyperframesRenderProducers.projectVideo,
+ inputs: { product: operation("request-render") },
+ result: { kind: "output", name: "video" },
+ },
+ ],
+ exports: [{
+ name: "video",
+ type: contractTypes.mediaArtifact,
+ root: operation("project-video"),
+ semanticInputs: ["composition"],
+ affinity: [{
+ resultPointer: "/digest",
+ source: operation("request-render"),
+ sourcePointer: "/artifact/digest",
+ }],
+ fidelity: "exact",
+ }],
+});
diff --git a/packages/hyperframes-render/src/index.ts b/packages/hyperframes-render/src/index.ts
new file mode 100644
index 00000000..e2232bb6
--- /dev/null
+++ b/packages/hyperframes-render/src/index.ts
@@ -0,0 +1,22 @@
+export { hyperframesRenderFragment } from "./fragment.js";
+export {
+ hyperframesRenderCapabilities,
+ hyperframesRenderManifest,
+ hyperframesRenderManifestDigest,
+ hyperframesRenderModuleRef,
+ hyperframesRenderProducers,
+ hyperframesRenderSurfaceImplementationDigest,
+ hyperframesRenderTypes,
+ hyperframesRenderedVideoSchema,
+} from "./manifest.js";
+export {
+ assertHyperframesRenderedVideo,
+ computeHyperframesRenderedVideoDigest,
+ hyperframesRenderRequest,
+ projectHyperframesVideo,
+ projectHyperframesVideoImplementationDigest,
+ requestHyperframesRenderImplementationDigest,
+ sealHyperframesRenderedVideo,
+} from "./product.js";
+export { decodeHyperframesRenderSurface } from "./surface.js";
+export type * from "./types.js";
diff --git a/packages/hyperframes-render/src/manifest.ts b/packages/hyperframes-render/src/manifest.ts
new file mode 100644
index 00000000..dbcf4e38
--- /dev/null
+++ b/packages/hyperframes-render/src/manifest.ts
@@ -0,0 +1,135 @@
+import {
+ contractTypes,
+ mediaArtifactSchema,
+ videoContractDependencies,
+} from "@svml/contracts";
+import {
+ hyperframesManifest,
+ hyperframesManifestDigest,
+ hyperframesModuleRef,
+ hyperframesTypes,
+} from "@svml/hyperframes";
+import { digestOf } from "@svml/protocol";
+import type {
+ CapabilityRef,
+ ModuleManifest,
+ ProducerRef,
+ TypeRef,
+ ValueSchema,
+} from "@svml/protocol";
+
+import {
+ projectHyperframesVideoImplementationDigest,
+ requestHyperframesRenderImplementationDigest,
+} from "./product.js";
+
+export const hyperframesRenderModuleRef = { name: "@svml/hyperframes-render", version: "0.0.0-dev" } as const;
+export const hyperframesRenderSurfaceImplementationDigest = digestOf("@svml/hyperframes-render/surface@1");
+export const hyperframesRenderTypes = {
+ product: { module: hyperframesRenderModuleRef, name: "HyperframesRenderedVideo" },
+} satisfies Record<string, TypeRef>;
+export const hyperframesRenderCapabilities = {
+ render: { module: hyperframesRenderModuleRef, name: "render-video" },
+} satisfies Record<string, CapabilityRef>;
+export const hyperframesRenderProducers = {
+ request: { module: hyperframesRenderModuleRef, name: "request-render" },
+ projectVideo: { module: hyperframesRenderModuleRef, name: "project-video" },
+} satisfies Record<string, ProducerRef>;
+
+const digest = { kind: "string", minLength: 71, maxLength: 71 } as const;
+const positiveInteger = { kind: "number", integer: true, minimum: 1 } as const;
+export const hyperframesRenderedVideoSchema: ValueSchema = {
+ kind: "object",
+ fields: {
+ contract: { schema: { kind: "literal", value: "svml.hyperframes-rendered-video@2" } },
+ digest: { schema: digest },
+ documentDigest: { schema: digest },
+ programSpaceDigest: { schema: digest },
+ frameRate: { schema: {
+ kind: "object",
+ fields: {
+ numerator: { schema: positiveInteger },
+ denominator: { schema: positiveInteger },
+ },
+ } },
+ frameCount: { schema: positiveInteger },
+ canvas: { schema: {
+ kind: "object",
+ fields: {
+ width: { schema: positiveInteger },
+ height: { schema: positiveInteger },
+ },
+ } },
+ artifact: { schema: mediaArtifactSchema },
+ },
+};
+
+export const hyperframesRenderManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: hyperframesRenderModuleRef.name,
+ version: hyperframesRenderModuleRef.version,
+ dependencies: [
+ videoContractDependencies.media,
+ videoContractDependencies.composition,
+ { module: hyperframesModuleRef, digest: hyperframesManifestDigest },
+ ],
+ types: [{ name: hyperframesRenderTypes.product.name, schema: hyperframesRenderedVideoSchema }],
+ capabilities: [{
+ name: hyperframesRenderCapabilities.render.name,
+ returns: hyperframesRenderTypes.product,
+ }],
+ surfaces: [{
+ name: "video",
+ tag: "Video",
+ mode: "structured",
+ outputs: [],
+ implementation: {
+ kind: "trusted-frontend-surface",
+ locator: "@svml/hyperframes-render/surface",
+ digest: hyperframesRenderSurfaceImplementationDigest,
+ },
+ }],
+ producers: [
+ {
+ name: hyperframesRenderProducers.request.name,
+ inputs: [{ name: "document", type: hyperframesTypes.document }],
+ outputs: [],
+ needs: [{
+ name: "product",
+ capability: hyperframesRenderCapabilities.render,
+ returns: hyperframesRenderTypes.product,
+ affinity: [
+ { resultPointer: "/documentDigest", input: "document", inputPointer: "/digest" },
+ { resultPointer: "/programSpaceDigest", input: "document", inputPointer: "/programSpaceDigest" },
+ { resultPointer: "/frameRate/numerator", input: "document", inputPointer: "/frameRate/numerator" },
+ { resultPointer: "/frameRate/denominator", input: "document", inputPointer: "/frameRate/denominator" },
+ { resultPointer: "/frameCount", input: "document", inputPointer: "/frameCount" },
+ { resultPointer: "/canvas/width", input: "document", inputPointer: "/canvas/width" },
+ { resultPointer: "/canvas/height", input: "document", inputPointer: "/canvas/height" },
+ ],
+ }],
+ implementation: {
+ kind: "registered",
+ locator: "@svml/hyperframes-render/request",
+ digest: requestHyperframesRenderImplementationDigest,
+ },
+ },
+ {
+ name: hyperframesRenderProducers.projectVideo.name,
+ inputs: [{ name: "product", type: hyperframesRenderTypes.product }],
+ outputs: [{
+ name: "video",
+ type: contractTypes.mediaArtifact,
+ affinity: [{ resultPointer: "/digest", input: "product", inputPointer: "/artifact/digest" }],
+ }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "@svml/hyperframes-render/project-video",
+ digest: projectHyperframesVideoImplementationDigest,
+ },
+ },
+ ],
+};
+
+export const hyperframesRenderManifestDigest = digestOf(hyperframesRenderManifest);
diff --git a/packages/hyperframes-render/src/product.ts b/packages/hyperframes-render/src/product.ts
new file mode 100644
index 00000000..5b44770b
--- /dev/null
+++ b/packages/hyperframes-render/src/product.ts
@@ -0,0 +1,91 @@
+import { isDigest } from "@svml/protocol";
+import { digestOf } from "@svml/protocol";
+import type { CanonicalValue, Digest } from "@svml/protocol";
+import { assertHyperframesDocument } from "@svml/hyperframes";
+import type { HyperframesDocument } from "@svml/hyperframes";
+
+import type { HyperframesRenderedVideo } from "./types.js";
+
+export const requestHyperframesRenderImplementationDigest = digestOf("@svml/hyperframes-render/request@2");
+export const projectHyperframesVideoImplementationDigest = digestOf("@svml/hyperframes-render/project-video@2");
+
+function content(
+ value: Omit<HyperframesRenderedVideo, "digest">,
+): Omit<HyperframesRenderedVideo, "digest"> {
+ return {
+ contract: "svml.hyperframes-rendered-video@2",
+ documentDigest: value.documentDigest,
+ programSpaceDigest: value.programSpaceDigest,
+ frameRate: { ...value.frameRate },
+ frameCount: value.frameCount,
+ canvas: { ...value.canvas },
+ artifact: { ...value.artifact },
+ };
+}
+
+export function computeHyperframesRenderedVideoDigest(
+ value: Omit<HyperframesRenderedVideo, "digest">,
+): Digest {
+ return digestOf(content(value));
+}
+
+export function sealHyperframesRenderedVideo(
+ value: Omit<HyperframesRenderedVideo, "digest">,
+): HyperframesRenderedVideo {
+ const normalized = content(value);
+ return { ...normalized, digest: digestOf(normalized) };
+}
+
+export function assertHyperframesRenderedVideo(value: HyperframesRenderedVideo): void {
+ if (value.contract !== "svml.hyperframes-rendered-video@2") {
+ throw new Error("Unsupported HyperframesRenderedVideo contract.");
+ }
+ if (
+ !isDigest(value.documentDigest)
+ || !isDigest(value.programSpaceDigest)
+ || !isDigest(value.artifact.digest)
+ ) {
+ throw new Error("HyperframesRenderedVideo contains an invalid digest.");
+ }
+ if (
+ !Number.isSafeInteger(value.frameRate.numerator)
+ || value.frameRate.numerator <= 0
+ || !Number.isSafeInteger(value.frameRate.denominator)
+ || value.frameRate.denominator <= 0
+ || !Number.isSafeInteger(value.frameCount)
+ || value.frameCount <= 0
+ || !Number.isSafeInteger(value.canvas.width)
+ || value.canvas.width <= 0
+ || !Number.isSafeInteger(value.canvas.height)
+ || value.canvas.height <= 0
+ ) {
+ throw new Error("HyperframesRenderedVideo frame domain or canvas is invalid.");
+ }
+ const durationSec = value.frameCount * value.frameRate.denominator / value.frameRate.numerator;
+ const durationTolerance = Math.max(1e-7, durationSec * Number.EPSILON * 8);
+ if (
+ value.artifact.size < 0
+ || !Number.isFinite(value.artifact.durationSec)
+ || Math.abs(value.artifact.durationSec - durationSec) > durationTolerance
+ || !value.artifact.mediaType.startsWith("video/")
+ ) {
+ throw new Error("HyperframesRenderedVideo artifact is invalid.");
+ }
+ const { digest: _digest, ...draft } = value;
+ if (!isDigest(value.digest) || value.digest !== computeHyperframesRenderedVideoDigest(draft)) {
+ throw new Error("HyperframesRenderedVideo digest does not match its contents.");
+ }
+}
+
+export function hyperframesRenderRequest(document: HyperframesDocument): CanonicalValue {
+ assertHyperframesDocument(document);
+ return {
+ contract: "svml.hyperframes-render-request@2",
+ document,
+ };
+}
+
+export function projectHyperframesVideo(value: HyperframesRenderedVideo) {
+ assertHyperframesRenderedVideo(value);
+ return { ...value.artifact };
+}
diff --git a/packages/hyperframes-render/src/surface.ts b/packages/hyperframes-render/src/surface.ts
new file mode 100644
index 00000000..e72125dc
--- /dev/null
+++ b/packages/hyperframes-render/src/surface.ts
@@ -0,0 +1,50 @@
+import { contractTypes } from "@svml/contracts";
+import type {
+ StructuredElement,
+ StructuredSurfaceHandler,
+ TextAttributeValue,
+} from "@svml/text";
+
+import { hyperframesRenderFragment } from "./fragment.js";
+
+function stringAttribute(element: StructuredElement, name: string): string {
+ const value = element.attributes[name];
+ if (typeof value !== "string" || value.length === 0) throw new Error(`${element.name}.${name} must be a string`);
+ return value;
+}
+
+function referenceAttribute(element: StructuredElement, name: string): string {
+ const value: TextAttributeValue | undefined = element.attributes[name];
+ if (typeof value !== "object" || value.kind !== "reference") {
+ throw new Error(`${element.name}.${name} must be a reference`);
+ }
+ return value.path;
+}
+
+export const decodeHyperframesRenderSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ const names = Object.keys(element.attributes).sort();
+ if (names.join(",") !== "composition,id") throw new Error(`${element.name} requires exactly composition and id`);
+ if (element.children.some((child) => child.kind === "element" || child.value.trim().length > 0)) {
+ throw new Error(`${element.name} does not accept children`);
+ }
+ const id = stringAttribute(element, "id");
+ const path = referenceAttribute(element, "composition");
+ const composition = resolveReference(path);
+ if (composition === undefined
+ || composition.type.module.name !== contractTypes.composition.module.name
+ || composition.type.module.version !== contractTypes.composition.module.version
+ || composition.type.name !== contractTypes.composition.name) {
+ throw new Error(`${element.name}.composition must reference Composition`);
+ }
+ return {
+ records: [],
+ components: [{
+ id,
+ fragment: hyperframesRenderFragment.id,
+ inputs: { composition: composition.ref },
+ outputs: { video: `${id}.video` },
+ range: element.range,
+ }],
+ fragments: [hyperframesRenderFragment],
+ };
+};
diff --git a/packages/hyperframes-render/src/types.ts b/packages/hyperframes-render/src/types.ts
new file mode 100644
index 00000000..cc219e3e
--- /dev/null
+++ b/packages/hyperframes-render/src/types.ts
@@ -0,0 +1,14 @@
+import type { MediaArtifactRef } from "@svml/contracts";
+import type {
+ HyperframesCanvas,
+ HyperframesFrameDomain,
+} from "@svml/hyperframes";
+import type { Digest } from "@svml/protocol";
+
+export type HyperframesRenderedVideo = HyperframesFrameDomain & {
+ readonly contract: "svml.hyperframes-rendered-video@2";
+ readonly digest: Digest;
+ readonly documentDigest: Digest;
+ readonly canvas: HyperframesCanvas;
+ readonly artifact: MediaArtifactRef;
+};
diff --git a/packages/hyperframes-render/test/render.test.ts b/packages/hyperframes-render/test/render.test.ts
new file mode 100644
index 00000000..521ed844
--- /dev/null
+++ b/packages/hyperframes-render/test/render.test.ts
@@ -0,0 +1,333 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ contractTypes,
+ sealComposition,
+ sealProgramSpace,
+ videoContractDependencies,
+ videoContractManifests,
+} from "@svml/contracts";
+import {
+ createResolvedClosure,
+ digestOf,
+ link,
+ sealBuildRequest,
+ sealCompiledGraph,
+ sealRecord,
+ sealTypedModule,
+ start,
+} from "@svml/core";
+import {
+ HostRegistry,
+ NodeDriver,
+ ProviderRegistry,
+} from "@svml/driver-node";
+import {
+ AuthorFrontendRegistry,
+ bindAuthorFragment,
+ compileSourceClosure,
+ elaborateGraphFragment,
+ resolveCompiledSourceExport,
+} from "@svml/elaborator";
+import type { AuthorSourceUnit } from "@svml/elaborator";
+import {
+ compileHyperframesDocument,
+ compileHyperframesImplementationDigest,
+ hyperframesManifest,
+ hyperframesProducers,
+} from "@svml/hyperframes";
+import {
+ decodeHyperframesRenderSurface,
+ hyperframesRenderCapabilities,
+ hyperframesRenderFragment,
+ hyperframesRenderManifest,
+ hyperframesRenderModuleRef,
+ hyperframesRenderProducers,
+ hyperframesRenderRequest,
+ hyperframesRenderSurfaceImplementationDigest,
+ hyperframesRenderTypes,
+ projectHyperframesVideo,
+ projectHyperframesVideoImplementationDigest,
+ requestHyperframesRenderImplementationDigest,
+ sealHyperframesRenderedVideo,
+} from "@svml/hyperframes-render";
+import type {
+ CanonicalValue,
+ ModuleManifest,
+ StoredValue,
+ TypedRecord,
+} from "@svml/protocol";
+import {
+ createTextAuthorFrontend,
+ TextSurfaceRegistry,
+ textAuthorFrontendId,
+} from "@svml/text";
+
+const space = sealProgramSpace({
+ contract: "svml.program-space@0",
+ durationSec: 2,
+ frameRate: { numerator: 30, denominator: 1 },
+});
+const composition = sealComposition({
+ contract: "svml.composition@1",
+ id: "render-test",
+ programSpace: space,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [],
+});
+
+const stored = (value: CanonicalValue): StoredValue => ({ kind: "inline", value });
+function inline(record: TypedRecord | undefined): CanonicalValue {
+ assert(record, "missing Producer input");
+ assert.equal(record.value.kind, "inline");
+ return record.value.value;
+}
+
+const closure = createResolvedClosure([
+ ...videoContractManifests,
+ hyperframesManifest,
+ hyperframesRenderManifest,
+]);
+const origin = {
+ kind: "authored" as const,
+ sourceDigest: digestOf("source:hyperframes-render-test"),
+ frontendClosureDigest: digestOf("frontend:hyperframes-render-test"),
+};
+const compositionRecord = sealRecord({
+ id: "composition",
+ type: contractTypes.composition,
+ value: stored(composition),
+ conformance: "exact",
+ origin,
+});
+const linked = link(closure, [sealTypedModule({
+ id: "author:hyperframes-render-test",
+ closureDigest: closure.digest,
+ records: [compositionRecord],
+})]);
+const instance = elaborateGraphFragment(linked, hyperframesRenderFragment, {
+ id: "final",
+ fragment: hyperframesRenderFragment.id,
+ inputs: { composition: { kind: "record", id: compositionRecord.id } },
+});
+const contribution = bindAuthorFragment(instance, { video: "final.video" });
+const graph = sealCompiledGraph({ program: linked.semanticDigest, ...contribution });
+
+function build() {
+ return start(linked, graph, sealBuildRequest({
+ graph: graph.id,
+ targets: [{ output: "final.video", accepts: "exact" }],
+ bindings: [],
+ }));
+}
+
+function producerRegistry(): HostRegistry {
+ const registry = new HostRegistry();
+ registry.registerProducer(hyperframesProducers.compile, compileHyperframesImplementationDigest, ({ inputs }) => ({
+ outputs: { document: stored(compileHyperframesDocument(inline(inputs.composition) as typeof composition)) },
+ needs: {},
+ }));
+ registry.registerProducer(
+ hyperframesRenderProducers.request,
+ requestHyperframesRenderImplementationDigest,
+ ({ inputs }) => ({
+ outputs: {},
+ needs: { product: hyperframesRenderRequest(inline(inputs.document) as never) },
+ }),
+ );
+ registry.registerProducer(
+ hyperframesRenderProducers.projectVideo,
+ projectHyperframesVideoImplementationDigest,
+ ({ inputs }) => ({
+ outputs: { video: stored(projectHyperframesVideo(inline(inputs.product) as never)) },
+ needs: {},
+ }),
+ );
+ return registry;
+}
+
+test("HyperFrames rendering is an explicit exact Need after ordinary document compilation", async () => {
+ assert.deepEqual(build().plan.steps.map((step) => step.producer.name).sort(), [
+ hyperframesProducers.compile.name,
+ hyperframesRenderProducers.request.name,
+ hyperframesRenderProducers.projectVideo.name,
+ ].sort());
+
+ const result = await new NodeDriver({ registry: producerRegistry() }).run(build());
+ assert.equal(result.status, "paused");
+ assert.equal(result.state.needs.length, 1);
+ const need = result.state.needs[0]!;
+ assert.equal(need.capability.name, hyperframesRenderCapabilities.render.name);
+ assert.equal(need.returns.name, hyperframesRenderTypes.product.name);
+ assert.equal(need.accepts, "exact");
+ assert.deepEqual(need.constraints, hyperframesRenderRequest(compileHyperframesDocument(composition)));
+ assert.equal(result.blocked[0]?.reason, "missing-provider");
+});
+
+test("a bound Provider fulfills the render Need without entering Film or HyperFrames compilation", async () => {
+ const artifact = {
+ digest: digestOf("hyperframes-render:final-video"),
+ size: 12_345,
+ mediaType: "video/mp4",
+ durationSec: space.durationSec,
+ };
+ const providers = new ProviderRegistry();
+ providers.registerProvider(
+ "example.hyperframes.local",
+ hyperframesRenderCapabilities.render,
+ hyperframesRenderTypes.product,
+ ({ need }) => {
+ const request = need.constraints as {
+ readonly contract: string;
+ readonly document: ReturnType<typeof compileHyperframesDocument>;
+ };
+ assert.equal(request.contract, "svml.hyperframes-render-request@2");
+ return {
+ value: stored(sealHyperframesRenderedVideo({
+ contract: "svml.hyperframes-rendered-video@2",
+ documentDigest: request.document.digest,
+ programSpaceDigest: request.document.programSpaceDigest,
+ frameRate: request.document.frameRate,
+ frameCount: request.document.frameCount,
+ canvas: request.document.canvas,
+ artifact,
+ })),
+ conformance: "exact",
+ delivery: "executed",
+ metadata: { runtime: "fixture-local" },
+ };
+ },
+ );
+ providers.bind(hyperframesRenderCapabilities.render, "example.hyperframes.local");
+
+ const result = await new NodeDriver({ registry: producerRegistry(), providers }).run(build());
+ assert.equal(result.status, "complete");
+ const video = result.state.records.find((record) =>
+ record.type.module.name === contractTypes.mediaArtifact.module.name
+ && record.type.name === contractTypes.mediaArtifact.name);
+ assert.deepEqual(inline(video), artifact);
+});
+
+test("a render Product cannot claim another frame domain while keeping the requested document", async () => {
+ const document = compileHyperframesDocument(composition);
+ const providers = new ProviderRegistry();
+ providers.registerProvider(
+ "example.hyperframes.wrong-domain",
+ hyperframesRenderCapabilities.render,
+ hyperframesRenderTypes.product,
+ () => ({
+ value: stored(sealHyperframesRenderedVideo({
+ contract: "svml.hyperframes-rendered-video@2",
+ documentDigest: document.digest,
+ programSpaceDigest: document.programSpaceDigest,
+ frameRate: document.frameRate,
+ frameCount: document.frameCount + 1,
+ canvas: document.canvas,
+ artifact: {
+ digest: digestOf("hyperframes-render:wrong-domain"),
+ size: 1,
+ mediaType: "video/mp4",
+ durationSec: space.durationSec,
+ },
+ })),
+ conformance: "exact",
+ delivery: "executed",
+ metadata: {},
+ }),
+ );
+ providers.bind(hyperframesRenderCapabilities.render, "example.hyperframes.wrong-domain");
+
+ const result = await new NodeDriver({ registry: producerRegistry(), providers }).run(build());
+ assert.equal(result.status, "paused");
+ assert.match(result.journal.at(-1)?.message ?? "", /frameCount|does not match/u);
+ assert.equal(result.state.receipts.length, 0);
+});
+
+const fixtureModule = { name: "example.composition-fixture", version: "1" } as const;
+const fixtureSurfaceDigest = digestOf("example.composition-fixture/surface@1");
+const fixtureManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: fixtureModule.name,
+ version: fixtureModule.version,
+ dependencies: [videoContractDependencies.composition],
+ types: [],
+ capabilities: [],
+ surfaces: [{
+ name: "composition",
+ tag: "Composition",
+ mode: "structured",
+ outputs: [contractTypes.composition],
+ implementation: {
+ kind: "trusted-frontend-surface",
+ locator: "example.composition-fixture/surface",
+ digest: fixtureSurfaceDigest,
+ },
+ }],
+ producers: [],
+};
+
+function source(text: string): AuthorSourceUnit {
+ return { id: "/project/main.svml", name: "main.svml", text };
+}
+
+test("the official render Surface lowers real author source to the same BuildPlan", async () => {
+ const sourceClosure = createResolvedClosure([
+ ...videoContractManifests,
+ hyperframesManifest,
+ hyperframesRenderManifest,
+ fixtureManifest,
+ ]);
+ const surfaces = new TextSurfaceRegistry();
+ surfaces.registerStructured(fixtureModule, "composition", fixtureSurfaceDigest, ({ element }) => ({
+ records: [{
+ id: "composition",
+ type: contractTypes.composition,
+ value: stored(composition),
+ range: element.range,
+ }],
+ components: [],
+ fragments: [],
+ }));
+ surfaces.registerStructured(
+ hyperframesRenderModuleRef,
+ "video",
+ hyperframesRenderSurfaceImplementationDigest,
+ decodeHyperframesRenderSurface,
+ );
+ const frontends = new AuthorFrontendRegistry();
+ frontends.register(createTextAuthorFrontend({
+ registry: surfaces,
+ resolveModule(request) {
+ return request.from.startsWith("@svml/hyperframes-render")
+ ? hyperframesRenderModuleRef
+ : fixtureModule;
+ },
+ }));
+ const compiled = await compileSourceClosure({
+ entry: source(`<svml>
+ <import as="fixture" from="example.composition-fixture@1"/>
+ <import as="render" from="@svml/hyperframes-render@1"/>
+ <fixture:Composition/>
+ <render:Video id="final" composition={composition}/>
+ </svml>`),
+ frontend: textAuthorFrontendId,
+ closure: sourceClosure,
+ frontends,
+ resolveSource() {
+ throw new Error("the fixture has no source imports");
+ },
+ });
+ const target = resolveCompiledSourceExport(compiled, "final.video", contractTypes.mediaArtifact);
+ assert.equal(target.ref.kind, "logical-output");
+ const state = start(compiled.program, compiled.elaboration.graph, sealBuildRequest({
+ graph: compiled.elaboration.graph.id,
+ targets: [{ output: target.ref.kind === "logical-output" ? target.ref.id : "", accepts: "exact" }],
+ bindings: [],
+ }));
+ assert.deepEqual(state.plan.steps.map((step) => step.producer.name).sort(), [
+ hyperframesProducers.compile.name,
+ hyperframesRenderProducers.request.name,
+ hyperframesRenderProducers.projectVideo.name,
+ ].sort());
+});
diff --git a/packages/hyperframes/README.md b/packages/hyperframes/README.md
new file mode 100644
index 00000000..9b3f2af6
--- /dev/null
+++ b/packages/hyperframes/README.md
@@ -0,0 +1,31 @@
+# @svml/hyperframes
+
+Deterministic reference lowering from the generic `Composition` contract to a portable
+`HyperframesDocument`.
+
+This package understands only `VisualTrack`, `AudioTrack`, `ProgramSpace` and canvas geometry. It
+does not know Caption, Speech, B-roll, Seedance or any other author-domain component. It flattens
+every Track's Presents, orders them by their own absolute stacking keys and emits frame-bound local
+keyframes. An authoring Track never becomes an isolated render stacking surface.
+
+Media remains content addressed in the compiled HTML as `svml-artifact://` placeholders. A local or
+hosted render Runtime calls `materializeHyperframesHtml()` with its own Artifact URL resolver before
+handing the HTML to HyperFrames. That environment-specific materialization is not a new compiled
+Record and does not change the document digest.
+
+The document exposes its render domain directly rather than asking an Endpoint to scrape HTML:
+`programSpaceDigest`, exact rational `frameRate`, integer `frameCount`, and canvas dimensions are
+all content-addressed. Legal frame addresses are exactly `[0, frameCount)`. A local worker pool or a
+hosted renderer may independently evaluate any legal frame or half-open chunk; partition size and
+worker count are Runtime policy, not author intent and not Core graph nodes. The emitted root also
+uses the rational HyperFrames `data-fps` form, so NTSC rates do not drift through a decimal guess.
+
+Exact `FontArtifactRef` dependencies lower to generated `@font-face` declarations with font
+synthesis disabled. `CompositableSurfaceRef` values lower as typed image/video surfaces carrying
+their declared alpha, color-space and frame-domain metadata. The package never guesses either fact
+from a user font name or filename extension.
+
+The ordinary test suite validates deterministic HTML and Artifact collection. Set
+`SVML_BROWSER_TESTS=1` to run the host integration witness that invokes the installed Hyperframes
+CLI, paints a real font and checks straight-alpha composition at the rendered pixel level. That
+test needs a local font, Chrome and FFmpeg; it is a renderer conformance witness, not Core logic.
diff --git a/packages/hyperframes/package.json b/packages/hyperframes/package.json
new file mode 100644
index 00000000..b3813711
--- /dev/null
+++ b/packages/hyperframes/package.json
@@ -0,0 +1,14 @@
+{
+ "name": "@svml/hyperframes",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "dependencies": {
+ "@svml/contracts": "workspace:*",
+ "@svml/elaborator": "workspace:*",
+ "@svml/protocol": "workspace:*"
+ }
+}
diff --git a/packages/hyperframes/src/document.ts b/packages/hyperframes/src/document.ts
new file mode 100644
index 00000000..ffb700cf
--- /dev/null
+++ b/packages/hyperframes/src/document.ts
@@ -0,0 +1,435 @@
+import {
+ assertCompositionIdentity,
+ programSpaceFrameCount,
+} from "@svml/contracts";
+import type {
+ AudioTrack,
+ Composition,
+ FontArtifactRef,
+ Track,
+ VisualAttribute,
+ VisualElement,
+ VisualPresent,
+ VisualStyleDeclaration,
+ VisualTrack,
+} from "@svml/contracts";
+import { digestOf, isDigest } from "@svml/protocol";
+import type { Digest } from "@svml/protocol";
+
+import type {
+ ArtifactUrlResolver,
+ HyperframesDocument,
+ HyperframesFrameSpan,
+} from "./types.js";
+
+export const compileHyperframesImplementationDigest = digestOf("@svml/hyperframes/compile@3");
+
+const NANOSECONDS = 1_000_000_000n;
+const ARTIFACT_URI = /svml-artifact:\/\/sha256\/([0-9a-f]{64})/gu;
+
+function escapeHtml(value: string): string {
+ return value
+ .replaceAll("&", "&amp;")
+ .replaceAll("<", "&lt;")
+ .replaceAll(">", "&gt;")
+ .replaceAll('"', "&quot;")
+ .replaceAll("'", "&#39;");
+}
+
+function frameSeconds(frame: number, numerator: number, denominator: number): string {
+ const nanos = BigInt(frame) * BigInt(denominator) * NANOSECONDS / BigInt(numerator);
+ const whole = nanos / NANOSECONDS;
+ const remainder = nanos % NANOSECONDS;
+ if (remainder === 0n) return String(whole);
+ return `${whole}.${String(remainder).padStart(9, "0").replace(/0+$/u, "")}`;
+}
+
+function fpsDecimal(numerator: number, denominator: number): string {
+ const scale = 1_000_000_000_000n;
+ const scaled = BigInt(numerator) * scale / BigInt(denominator);
+ const whole = scaled / scale;
+ const remainder = scaled % scale;
+ if (remainder === 0n) return String(whole);
+ return `${whole}.${String(remainder).padStart(12, "0").replace(/0+$/u, "")}`;
+}
+
+function fpsRational(numerator: number, denominator: number): string {
+ return denominator === 1 ? String(numerator) : `${numerator}/${denominator}`;
+}
+
+function percentage(frame: number, totalFrames: number): string {
+ const scale = 1_000_000_000n;
+ const scaled = BigInt(frame) * 100n * scale / BigInt(totalFrames);
+ const whole = scaled / scale;
+ const remainder = scaled % scale;
+ if (remainder === 0n) return `${whole}%`;
+ return `${whole}.${String(remainder).padStart(9, "0").replace(/0+$/u, "")}%`;
+}
+
+export function hyperframesArtifactUri(digest: Digest): string {
+ if (!isDigest(digest)) throw new Error("HyperFrames Artifact digest is invalid.");
+ return `svml-artifact://sha256/${digest.slice("sha256:".length)}`;
+}
+
+function css(style: readonly VisualStyleDeclaration[]): string {
+ return style.map(({ name, value }) => `${name}:${String(value)}`).join(";");
+}
+
+function attributes(values: readonly VisualAttribute[] | undefined): string {
+ return (values ?? []).map(({ name, value }) => ` ${name}="${escapeHtml(value)}"`).join("");
+}
+
+function stableDomId(parts: readonly string[]): string {
+ return `svml-${digestOf(parts).slice("sha256:".length, "sha256:".length + 20)}`;
+}
+
+function exactFontFamily(font: FontArtifactRef): string {
+ return stableDomId(["font", digestOf(font)]);
+}
+
+function exactFontStyle(element: VisualElement): string[] {
+ if (element.kind !== "text" || element.fonts === undefined) return [];
+ const first = element.fonts[0]!;
+ return [
+ `font-family:${element.fonts.map(exactFontFamily).join(",")}`,
+ `font-weight:${first.weight}`,
+ `font-style:${first.style}`,
+ "font-synthesis:none",
+ ];
+}
+
+function renderElement(
+ element: VisualElement,
+ children: ReadonlyMap<string, readonly VisualElement[]>,
+ context: {
+ readonly trackId: string;
+ readonly presentId: string;
+ readonly presentStart: string;
+ readonly presentDuration: string;
+ readonly stackIndex: number;
+ },
+): string {
+ const id = stableDomId([context.trackId, context.presentId, element.id]);
+ const animationName = element.animation === undefined
+ ? undefined
+ : stableDomId(["animation", context.trackId, context.presentId, element.id]);
+ const inlineStyle = [
+ css(element.style),
+ ...exactFontStyle(element),
+ ...(animationName === undefined ? [] : [
+ `animation-name:${animationName}`,
+ `animation-duration:${context.presentDuration}s`,
+ "animation-fill-mode:both",
+ "animation-timing-function:linear",
+ ]),
+ ].filter(Boolean).join(";");
+ const common = `id="${id}" data-svml-element-id="${escapeHtml(element.id)}" style="${escapeHtml(inlineStyle)}"${attributes(element.attributes)}`;
+ const descendants = (children.get(element.id) ?? [])
+ .map((child) => renderElement(child, children, context))
+ .join("");
+ if (element.kind === "box") return `<div ${common}>${descendants}</div>`;
+ if (element.kind === "text") return `<div ${common}>${escapeHtml(element.text)}${descendants}</div>`;
+ if (element.kind === "surface") {
+ const source = escapeHtml(hyperframesArtifactUri(element.surface.artifact.digest));
+ const surface = [
+ `data-start="${context.presentStart}"`,
+ `data-duration="${context.presentDuration}"`,
+ `data-track-index="${context.stackIndex}"`,
+ `data-svml-alpha-mode="${element.surface.alphaMode}"`,
+ `data-svml-color-space="${element.surface.colorSpace}"`,
+ `width="${element.surface.width}"`,
+ `height="${element.surface.height}"`,
+ ].join(" ");
+ if (element.surface.timing.kind === "still") return `<img ${common} ${surface} src="${source}"/>`;
+ return `<video ${common} ${surface} muted playsinline src="${source}"></video>`;
+ }
+
+ const media = [
+ `data-start="${context.presentStart}"`,
+ `data-duration="${context.presentDuration}"`,
+ `data-track-index="${context.stackIndex}"`,
+ element.mediaStartSec === undefined ? "" : `data-media-start="${element.mediaStartSec}"`,
+ element.playbackRate === undefined ? "" : `data-playback-rate="${element.playbackRate}"`,
+ element.kind === "video" && element.muted !== false ? "muted" : "",
+ element.kind === "video" ? "playsinline" : "",
+ element.loop ? "loop" : "",
+ ].filter(Boolean).join(" ");
+ const source = escapeHtml(hyperframesArtifactUri(element.artifact.digest));
+ if (element.kind === "image") return `<img ${common} ${media} src="${source}"/>`;
+ return `<video ${common} ${media} src="${source}">${descendants}</video>`;
+}
+
+function renderVisualPresent(
+ track: VisualTrack,
+ present: VisualPresent,
+ stackIndex: number,
+ numerator: number,
+ denominator: number,
+): string {
+ const start = frameSeconds(present.span.startFrame, numerator, denominator);
+ const duration = frameSeconds(present.span.endFrameExclusive - present.span.startFrame, numerator, denominator);
+ const children = new Map<string, VisualElement[]>();
+ for (const element of present.elements) {
+ if (element.parent === undefined) continue;
+ const siblings = children.get(element.parent) ?? [];
+ siblings.push(element);
+ children.set(element.parent, siblings);
+ }
+ for (const siblings of children.values()) siblings.sort((left, right) => left.order - right.order || left.id.localeCompare(right.id));
+ const root = present.elements.find((element) => element.parent === undefined)!;
+ const contents = renderElement(root, children, {
+ trackId: track.id,
+ presentId: present.id,
+ presentStart: start,
+ presentDuration: duration,
+ stackIndex,
+ });
+ return `<div class="clip svml-visual-present" data-svml-track-id="${escapeHtml(track.id)}" data-svml-present-id="${escapeHtml(present.id)}" data-svml-stack-order="${present.stacking.order}" data-svml-stack-tie="${escapeHtml(present.stacking.tieBreak)}" data-track-index="${stackIndex}" data-start="${start}" data-duration="${duration}" style="position:absolute;inset:0;z-index:${stackIndex};overflow:hidden;pointer-events:none">${contents}</div>`;
+}
+
+function renderAnimationRules(track: VisualTrack, present: VisualPresent): string[] {
+ const durationFrames = present.span.endFrameExclusive - present.span.startFrame;
+ return present.elements.flatMap((element) => {
+ if (element.animation === undefined) return [];
+ const name = stableDomId(["animation", track.id, present.id, element.id]);
+ const frames = element.animation.keyframes.map((keyframe) => {
+ const easing = keyframe.easing === undefined ? "" : `;animation-timing-function:${keyframe.easing}`;
+ return `${percentage(keyframe.atFrame, durationFrames)}{${css(keyframe.style)}${easing}}`;
+ }).join("");
+ return [`@keyframes ${name}{${frames}}`];
+ });
+}
+
+function renderAudioTrack(
+ track: AudioTrack,
+ trackIndex: number,
+ numerator: number,
+ denominator: number,
+): string {
+ return track.clips.map((clip) => {
+ const start = frameSeconds(clip.span.startFrame, numerator, denominator);
+ const duration = frameSeconds(clip.span.endFrameExclusive - clip.span.startFrame, numerator, denominator);
+ return [
+ `<audio id="${stableDomId([track.id, clip.id])}"`,
+ `data-svml-track-id="${escapeHtml(track.id)}"`,
+ `data-svml-clip-id="${escapeHtml(clip.id)}"`,
+ `data-track-index="${trackIndex}"`,
+ `data-start="${start}"`,
+ `data-duration="${duration}"`,
+ clip.mediaStartSec === undefined ? "" : `data-media-start="${clip.mediaStartSec}"`,
+ clip.playbackRate === undefined ? "" : `data-playback-rate="${clip.playbackRate}"`,
+ clip.gain === undefined ? "" : `data-volume="${clip.gain}"`,
+ clip.fadeInSec === undefined ? "" : `data-fade-in="${clip.fadeInSec}"`,
+ clip.fadeOutSec === undefined ? "" : `data-fade-out="${clip.fadeOutSec}"`,
+ clip.bus === undefined ? "" : `data-bus="${clip.bus}"`,
+ `src="${escapeHtml(hyperframesArtifactUri(clip.artifact.digest))}"></audio>`,
+ ].filter(Boolean).join(" ");
+ }).join("");
+}
+
+function orderedVisualPresents(tracks: readonly Track[]): Array<{ readonly track: VisualTrack; readonly present: VisualPresent }> {
+ return tracks
+ .filter((track): track is VisualTrack => track.contract === "svml.visual-track@1")
+ .flatMap((track) => track.presents.map((present) => ({ track, present })))
+ .sort((left, right) => left.present.stacking.order - right.present.stacking.order
+ || left.present.stacking.tieBreak.localeCompare(right.present.stacking.tieBreak)
+ || left.present.span.startFrame - right.present.span.startFrame
+ || left.track.id.localeCompare(right.track.id)
+ || left.present.id.localeCompare(right.present.id));
+}
+
+function collectArtifactDigests(composition: Composition): Digest[] {
+ const digests = new Set<Digest>();
+ for (const track of composition.tracks) {
+ if (track.contract === "svml.audio-track@1") {
+ for (const clip of track.clips) digests.add(clip.artifact.digest);
+ continue;
+ }
+ for (const present of track.presents) {
+ for (const element of present.elements) {
+ if (element.kind === "image" || element.kind === "video") digests.add(element.artifact.digest);
+ if (element.kind === "surface") digests.add(element.surface.artifact.digest);
+ if (element.kind === "text") {
+ for (const font of element.fonts ?? []) digests.add(font.artifact.digest);
+ }
+ }
+ }
+ }
+ return [...digests].sort();
+}
+
+function collectFonts(composition: Composition): FontArtifactRef[] {
+ const fonts = new Map<string, FontArtifactRef>();
+ for (const track of composition.tracks) {
+ if (track.contract !== "svml.visual-track@1") continue;
+ for (const present of track.presents) {
+ for (const element of present.elements) {
+ if (element.kind !== "text") continue;
+ for (const font of element.fonts ?? []) fonts.set(digestOf(font), font);
+ }
+ }
+ }
+ return [...fonts.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([, font]) => font);
+}
+
+function fontFormat(mediaType: string): string {
+ if (mediaType === "font/woff2") return "woff2";
+ if (mediaType === "font/woff") return "woff";
+ if (mediaType === "font/otf") return "opentype";
+ return "truetype";
+}
+
+function renderFontFaces(composition: Composition): string {
+ return collectFonts(composition).map((font) => [
+ "@font-face{",
+ `font-family:${exactFontFamily(font)};`,
+ `src:url(\"${hyperframesArtifactUri(font.artifact.digest)}\") format(\"${fontFormat(font.artifact.mediaType)}\");`,
+ `font-weight:${font.weight};`,
+ `font-style:${font.style};`,
+ "font-display:block;",
+ "}",
+ ].join("")).join("\n ");
+}
+
+function emitHtml(composition: Composition): string {
+ const { numerator, denominator } = composition.programSpace.frameRate;
+ const visuals = orderedVisualPresents(composition.tracks);
+ const audios = composition.tracks.filter((track): track is AudioTrack => track.contract === "svml.audio-track@1");
+ const visualHtml = visuals.map(({ track, present }, index) => renderVisualPresent(track, present, index, numerator, denominator)).join("\n ");
+ const animationCss = visuals.flatMap(({ track, present }) => renderAnimationRules(track, present)).join("\n ");
+ const fontCss = renderFontFaces(composition);
+ const audioHtml = audios.map((track, index) => renderAudioTrack(track, visuals.length + index, numerator, denominator)).join("\n ");
+ const duration = frameSeconds(programSpaceFrameCount(composition.programSpace), numerator, denominator);
+ const fps = fpsRational(numerator, denominator);
+ const frameCount = programSpaceFrameCount(composition.programSpace);
+ return `<!doctype html>
+<html>
+<head>
+ <meta charset="utf-8"/>
+ <meta name="viewport" content="width=device-width,initial-scale=1"/>
+ <style>
+ html,body{margin:0;width:100%;height:100%;overflow:hidden;background:${composition.canvas.clearColor}}
+ [data-composition-id]{position:relative;overflow:hidden;background:${composition.canvas.clearColor}}
+ *,*::before,*::after{box-sizing:border-box}
+ ${fontCss}
+ ${animationCss}
+ </style>
+</head>
+<body>
+ <div data-composition-id="${escapeHtml(composition.id)}" data-start="0" data-no-timeline data-width="${composition.canvas.width}" data-height="${composition.canvas.height}" data-duration="${duration}" data-fps="${fps}" data-svml-frame-count="${frameCount}" data-svml-program-space="${composition.programSpace.digest}">
+ ${visualHtml}
+ ${audioHtml}
+ </div>
+</body>
+</html>
+`;
+}
+
+function normalizedDocument(value: Omit<HyperframesDocument, "digest">): Omit<HyperframesDocument, "digest"> {
+ return {
+ contract: "svml.hyperframes-document@2",
+ compositionDigest: value.compositionDigest,
+ programSpaceDigest: value.programSpaceDigest,
+ frameRate: { ...value.frameRate },
+ frameCount: value.frameCount,
+ canvas: { ...value.canvas },
+ artifactDigests: [...value.artifactDigests].sort(),
+ html: value.html,
+ };
+}
+
+export function compileHyperframesDocument(composition: Composition): HyperframesDocument {
+ assertCompositionIdentity(composition);
+ const content = normalizedDocument({
+ contract: "svml.hyperframes-document@2",
+ compositionDigest: composition.digest,
+ programSpaceDigest: composition.programSpace.digest,
+ frameRate: { ...composition.programSpace.frameRate },
+ frameCount: programSpaceFrameCount(composition.programSpace),
+ canvas: {
+ width: composition.canvas.width,
+ height: composition.canvas.height,
+ },
+ artifactDigests: collectArtifactDigests(composition),
+ html: emitHtml(composition),
+ });
+ return { ...content, digest: digestOf(content) };
+}
+
+export function assertHyperframesDocument(document: HyperframesDocument): void {
+ if (document.contract !== "svml.hyperframes-document@2") throw new Error("Unsupported HyperframesDocument contract.");
+ if (
+ !isDigest(document.compositionDigest)
+ || !isDigest(document.programSpaceDigest)
+ || !isDigest(document.digest)
+ ) {
+ throw new Error("HyperframesDocument digest is invalid.");
+ }
+ if (
+ !Number.isSafeInteger(document.frameRate.numerator)
+ || document.frameRate.numerator <= 0
+ || !Number.isSafeInteger(document.frameRate.denominator)
+ || document.frameRate.denominator <= 0
+ || !Number.isSafeInteger(document.frameCount)
+ || document.frameCount <= 0
+ || !Number.isSafeInteger(document.canvas.width)
+ || document.canvas.width <= 0
+ || !Number.isSafeInteger(document.canvas.height)
+ || document.canvas.height <= 0
+ ) {
+ throw new Error("HyperframesDocument frame domain or canvas is invalid.");
+ }
+ const { digest, ...content } = document;
+ if (digest !== digestOf(normalizedDocument(content))) throw new Error("HyperframesDocument digest does not match its contents.");
+ if (!document.html.startsWith("<!doctype html>")) throw new Error("HyperframesDocument HTML is invalid.");
+ const declared = [...document.artifactDigests];
+ if (declared.some((item) => !isDigest(item)) || new Set(declared).size !== declared.length) {
+ throw new Error("HyperframesDocument Artifact set is invalid.");
+ }
+ const referenced = [...document.html.matchAll(ARTIFACT_URI)].map((match) => `sha256:${match[1]}` as Digest);
+ const actual = [...new Set(referenced)].sort();
+ if (JSON.stringify(actual) !== JSON.stringify([...declared].sort())) {
+ throw new Error("HyperframesDocument Artifact placeholders do not match its declared dependencies.");
+ }
+}
+
+/** Validate one independently renderable frame index without parsing generated HTML. */
+export function assertHyperframesFrameIndex(document: HyperframesDocument, frame: number): void {
+ assertHyperframesDocument(document);
+ if (!Number.isSafeInteger(frame) || frame < 0 || frame >= document.frameCount) {
+ throw new Error(`HyperFrames frame ${frame} is outside [0, ${document.frameCount}).`);
+ }
+}
+
+/** Validate a Provider-owned half-open chunk of the document's exact frame domain. */
+export function assertHyperframesFrameSpan(
+ document: HyperframesDocument,
+ span: HyperframesFrameSpan,
+): void {
+ assertHyperframesDocument(document);
+ if (
+ !Number.isSafeInteger(span.startFrame)
+ || !Number.isSafeInteger(span.endFrameExclusive)
+ || span.startFrame < 0
+ || span.endFrameExclusive <= span.startFrame
+ || span.endFrameExclusive > document.frameCount
+ ) {
+ throw new Error(
+ `HyperFrames frame span [${span.startFrame}, ${span.endFrameExclusive}) is outside [0, ${document.frameCount}).`,
+ );
+ }
+}
+
+/** Runtime-only URL materialization. The returned HTML is intentionally not a new compiled Record. */
+export function materializeHyperframesHtml(
+ document: HyperframesDocument,
+ resolve: ArtifactUrlResolver,
+): string {
+ assertHyperframesDocument(document);
+ return document.html.replace(ARTIFACT_URI, (_uri, hash: string) => {
+ const digest = `sha256:${hash}` as Digest;
+ return escapeHtml(resolve(digest));
+ });
+}
+
+export const hyperframesTime = { frameSeconds, fpsDecimal, fpsRational } as const;
diff --git a/packages/hyperframes/src/fragment.ts b/packages/hyperframes/src/fragment.ts
new file mode 100644
index 00000000..14f5d98e
--- /dev/null
+++ b/packages/hyperframes/src/fragment.ts
@@ -0,0 +1,35 @@
+import { contractTypes } from "@svml/contracts";
+import { sealGraphFragment } from "@svml/elaborator";
+
+import { hyperframesProducers, hyperframesTypes } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+/**
+ * Compile one already assembled Composition into a Hyperframes document.
+ * Film is intentionally absent: any package capable of producing Composition
+ * can use this ordinary downstream Fragment.
+ */
+export const hyperframesDocumentFragment = sealGraphFragment({
+ name: "@svml/hyperframes/document@1",
+ inputs: [{ name: "composition", type: contractTypes.composition }],
+ operations: [{
+ id: "compile-document",
+ producer: hyperframesProducers.compile,
+ inputs: { composition: input("composition") },
+ result: { kind: "output", name: "document" },
+ }],
+ exports: [{
+ name: "document",
+ type: hyperframesTypes.document,
+ root: operation("compile-document"),
+ semanticInputs: ["composition"],
+ affinity: [{
+ resultPointer: "/compositionDigest",
+ source: input("composition"),
+ sourcePointer: "/digest",
+ }],
+ fidelity: "exact",
+ }],
+});
diff --git a/packages/hyperframes/src/index.ts b/packages/hyperframes/src/index.ts
new file mode 100644
index 00000000..50625495
--- /dev/null
+++ b/packages/hyperframes/src/index.ts
@@ -0,0 +1,20 @@
+export { hyperframesDocumentFragment } from "./fragment.js";
+export {
+ assertHyperframesDocument,
+ assertHyperframesFrameIndex,
+ assertHyperframesFrameSpan,
+ compileHyperframesDocument,
+ compileHyperframesImplementationDigest,
+ hyperframesArtifactUri,
+ hyperframesTime,
+ materializeHyperframesHtml,
+} from "./document.js";
+export {
+ hyperframesDocumentSchema,
+ hyperframesManifest,
+ hyperframesManifestDigest,
+ hyperframesModuleRef,
+ hyperframesProducers,
+ hyperframesTypes,
+} from "./manifest.js";
+export type * from "./types.js";
diff --git a/packages/hyperframes/src/manifest.ts b/packages/hyperframes/src/manifest.ts
new file mode 100644
index 00000000..1c2f2295
--- /dev/null
+++ b/packages/hyperframes/src/manifest.ts
@@ -0,0 +1,79 @@
+import {
+ contractTypes,
+ videoContractDependencies,
+} from "@svml/contracts";
+import { digestOf } from "@svml/protocol";
+import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@svml/protocol";
+
+import { compileHyperframesImplementationDigest } from "./document.js";
+
+export const hyperframesModuleRef = { name: "@svml/hyperframes", version: "0.0.0-dev" } as const;
+export const hyperframesTypes = {
+ document: { module: hyperframesModuleRef, name: "HyperframesDocument" },
+} satisfies Record<string, TypeRef>;
+export const hyperframesProducers = {
+ compile: { module: hyperframesModuleRef, name: "compile-composition" },
+} satisfies Record<string, ProducerRef>;
+
+const digest = { kind: "string", minLength: 71, maxLength: 71 } as const;
+const positiveInteger = { kind: "number", integer: true, minimum: 1 } as const;
+export const hyperframesDocumentSchema: ValueSchema = {
+ kind: "object",
+ fields: {
+ contract: { schema: { kind: "literal", value: "svml.hyperframes-document@2" } },
+ digest: { schema: digest },
+ compositionDigest: { schema: digest },
+ programSpaceDigest: { schema: digest },
+ frameRate: { schema: {
+ kind: "object",
+ fields: {
+ numerator: { schema: positiveInteger },
+ denominator: { schema: positiveInteger },
+ },
+ } },
+ frameCount: { schema: positiveInteger },
+ canvas: { schema: {
+ kind: "object",
+ fields: {
+ width: { schema: positiveInteger },
+ height: { schema: positiveInteger },
+ },
+ } },
+ artifactDigests: { schema: { kind: "array", items: digest } },
+ html: { schema: { kind: "string", minLength: 1 } },
+ },
+};
+
+export const hyperframesManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: hyperframesModuleRef.name,
+ version: hyperframesModuleRef.version,
+ dependencies: [videoContractDependencies.composition],
+ types: [{ name: hyperframesTypes.document.name, schema: hyperframesDocumentSchema }],
+ capabilities: [],
+ surfaces: [],
+ producers: [{
+ name: hyperframesProducers.compile.name,
+ inputs: [{ name: "composition", type: contractTypes.composition }],
+ outputs: [{
+ name: "document",
+ type: hyperframesTypes.document,
+ affinity: [
+ { resultPointer: "/compositionDigest", input: "composition", inputPointer: "/digest" },
+ { resultPointer: "/programSpaceDigest", input: "composition", inputPointer: "/programSpace/digest" },
+ { resultPointer: "/frameRate/numerator", input: "composition", inputPointer: "/programSpace/frameRate/numerator" },
+ { resultPointer: "/frameRate/denominator", input: "composition", inputPointer: "/programSpace/frameRate/denominator" },
+ { resultPointer: "/canvas/width", input: "composition", inputPointer: "/canvas/width" },
+ { resultPointer: "/canvas/height", input: "composition", inputPointer: "/canvas/height" },
+ ],
+ }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "@svml/hyperframes/compile",
+ digest: compileHyperframesImplementationDigest,
+ },
+ }],
+};
+
+export const hyperframesManifestDigest = digestOf(hyperframesManifest);
diff --git a/packages/hyperframes/src/types.ts b/packages/hyperframes/src/types.ts
new file mode 100644
index 00000000..ff4ad056
--- /dev/null
+++ b/packages/hyperframes/src/types.ts
@@ -0,0 +1,37 @@
+import type { Digest } from "@svml/protocol";
+
+export type HyperframesFrameDomain = {
+ /** Exact ProgramSpace whose integer frame domain this document renders. */
+ readonly programSpaceDigest: Digest;
+ readonly frameRate: {
+ readonly numerator: number;
+ readonly denominator: number;
+ };
+ /** Legal frame indices are exactly [0, frameCount). */
+ readonly frameCount: number;
+};
+
+export type HyperframesCanvas = {
+ readonly width: number;
+ readonly height: number;
+};
+
+/** Deterministic, portable input to a local or remote HyperFrames renderer. */
+export type HyperframesDocument = HyperframesFrameDomain & {
+ readonly contract: "svml.hyperframes-document@2";
+ readonly digest: Digest;
+ readonly compositionDigest: Digest;
+ readonly canvas: HyperframesCanvas;
+ /** Every content-addressed media dependency referenced by the HTML template. */
+ readonly artifactDigests: readonly Digest[];
+ /** Media URLs remain svml-artifact:// placeholders until a Runtime materializes them. */
+ readonly html: string;
+};
+
+/** Runtime-local work unit; chunk selection is never author intent or a Core object. */
+export type HyperframesFrameSpan = {
+ readonly startFrame: number;
+ readonly endFrameExclusive: number;
+};
+
+export type ArtifactUrlResolver = (digest: Digest) => string;
diff --git a/packages/hyperframes/test/browser-visual.test.ts b/packages/hyperframes/test/browser-visual.test.ts
new file mode 100644
index 00000000..6ec38f7e
--- /dev/null
+++ b/packages/hyperframes/test/browser-visual.test.ts
@@ -0,0 +1,242 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFile, mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { deflateSync } from "node:zlib";
+
+import {
+ sealComposition,
+ sealProgramSpace,
+ sealVisualTrack,
+} from "@svml/contracts";
+import type { FontArtifactRef } from "@svml/contracts";
+import {
+ compileHyperframesDocument,
+ materializeHyperframesHtml,
+} from "@svml/hyperframes";
+import type { Digest } from "@svml/protocol";
+
+const enabled = process.env.SVML_BROWSER_TESTS === "1";
+const localFont = process.env.SVML_TEST_FONT_PATH
+ ?? (process.platform === "darwin" ? "/System/Library/Fonts/SFNSMono.ttf" : undefined);
+
+function digest(bytes: Uint8Array): Digest {
+ return `sha256:${createHash("sha256").update(bytes).digest("hex")}` as Digest;
+}
+
+function crc32(bytes: Uint8Array): number {
+ let crc = 0xffff_ffff;
+ for (const byte of bytes) {
+ crc ^= byte;
+ for (let bit = 0; bit < 8; bit += 1) crc = (crc >>> 1) ^ (0xedb8_8320 & -(crc & 1));
+ }
+ return (crc ^ 0xffff_ffff) >>> 0;
+}
+
+function pngChunk(name: string, data: Uint8Array): Buffer {
+ const type = Buffer.from(name, "ascii");
+ const length = Buffer.alloc(4);
+ length.writeUInt32BE(data.byteLength);
+ const body = Buffer.concat([type, data]);
+ const checksum = Buffer.alloc(4);
+ checksum.writeUInt32BE(crc32(body));
+ return Buffer.concat([length, body, checksum]);
+}
+
+function rgbaPng(width: number, height: number, rgba: readonly [number, number, number, number]): Buffer {
+ const header = Buffer.alloc(13);
+ header.writeUInt32BE(width, 0);
+ header.writeUInt32BE(height, 4);
+ header[8] = 8;
+ header[9] = 6;
+ const rows = Buffer.alloc((width * 4 + 1) * height);
+ for (let y = 0; y < height; y += 1) {
+ const row = y * (width * 4 + 1);
+ rows[row] = 0;
+ for (let x = 0; x < width; x += 1) {
+ const pixel = row + 1 + x * 4;
+ rows[pixel] = rgba[0];
+ rows[pixel + 1] = rgba[1];
+ rows[pixel + 2] = rgba[2];
+ rows[pixel + 3] = rgba[3];
+ }
+ }
+ return Buffer.concat([
+ Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
+ pngChunk("IHDR", header),
+ pngChunk("IDAT", deflateSync(rows)),
+ pngChunk("IEND", Buffer.alloc(0)),
+ ]);
+}
+
+async function findPng(directory: string): Promise<string | undefined> {
+ for (const entry of await readdir(directory, { withFileTypes: true })) {
+ const absolute = path.join(directory, entry.name);
+ if (entry.isDirectory()) {
+ const nested = await findPng(absolute);
+ if (nested !== undefined) return nested;
+ } else if (entry.name.endsWith(".png")) {
+ return absolute;
+ }
+ }
+ return undefined;
+}
+
+test("locked font and straight-alpha Surface survive one real Hyperframes browser frame", {
+ skip: !enabled || localFont === undefined,
+ timeout: 120_000,
+}, async () => {
+ assert(localFont !== undefined);
+ const temp = await mkdtemp(path.join(os.tmpdir(), "svml-hyperframes-visual-"));
+ try {
+ const fontBytes = await import("node:fs/promises").then(({ readFile }) => readFile(localFont));
+ const surfaceBytes = rgbaPng(64, 64, [255, 0, 0, 128]);
+ const fontDigest = digest(fontBytes);
+ const surfaceDigest = digest(surfaceBytes);
+ const font: FontArtifactRef = {
+ contract: "svml.font-artifact@1",
+ artifact: { kind: "blob", digest: fontDigest, size: fontBytes.byteLength, mediaType: "font/ttf" },
+ weight: 400,
+ style: "normal",
+ };
+ const space = sealProgramSpace({
+ contract: "svml.program-space@0",
+ durationSec: 1 / 30,
+ frameRate: { numerator: 30, denominator: 1 },
+ });
+ const lower = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "blue",
+ programSpaceDigest: space.digest,
+ sources: [{ name: "fixture", digest: digest(Buffer.from("blue")) }],
+ presents: [{
+ id: "blue",
+ span: { startFrame: 0, endFrameExclusive: 1 },
+ stacking: { order: 10, tieBreak: "blue" },
+ elements: [{
+ id: "blue",
+ order: 0,
+ kind: "box",
+ style: [
+ { name: "position", value: "absolute" },
+ { name: "inset", value: 0 },
+ { name: "background-color", value: "#0000ff" },
+ ],
+ }],
+ }],
+ });
+ const surface = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "surface",
+ programSpaceDigest: space.digest,
+ sources: [{ name: "receipt", digest: digest(Buffer.from("surface")) }],
+ presents: [{
+ id: "surface",
+ span: { startFrame: 0, endFrameExclusive: 1 },
+ stacking: { order: 20, tieBreak: "surface" },
+ elements: [{
+ id: "surface",
+ order: 0,
+ kind: "surface",
+ surface: {
+ contract: "svml.compositable-surface@1",
+ artifact: { kind: "blob", digest: surfaceDigest, size: surfaceBytes.byteLength, mediaType: "image/png" },
+ width: 64,
+ height: 64,
+ colorSpace: "srgb",
+ alphaMode: "straight",
+ timing: { kind: "still" },
+ },
+ style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }, { name: "width", value: "100%" }, { name: "height", value: "100%" }],
+ }],
+ }],
+ });
+ const text = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "text",
+ programSpaceDigest: space.digest,
+ sources: [{ name: "fixture", digest: digest(Buffer.from("text")) }],
+ presents: [{
+ id: "text",
+ span: { startFrame: 0, endFrameExclusive: 1 },
+ stacking: { order: 30, tieBreak: "text" },
+ elements: [{
+ id: "text",
+ order: 0,
+ kind: "text",
+ text: "I",
+ fonts: [font],
+ style: [
+ { name: "position", value: "absolute" },
+ { name: "left", value: "4px" },
+ { name: "top", value: "0px" },
+ { name: "font-size", value: "28px" },
+ { name: "line-height", value: 1 },
+ { name: "color", value: "#ffffff" },
+ ],
+ }],
+ }],
+ });
+ const document = compileHyperframesDocument(sealComposition({
+ contract: "svml.composition@1",
+ id: "visual-proof",
+ programSpace: space,
+ canvas: { width: 64, height: 64, clearColor: "#000000" },
+ tracks: [text, lower, surface],
+ }));
+
+ await copyFile(localFont, path.join(temp, "font.ttf"));
+ await writeFile(path.join(temp, "surface.png"), surfaceBytes);
+ const html = materializeHyperframesHtml(document, (artifactDigest) => {
+ if (artifactDigest === fontDigest) return "./font.ttf";
+ if (artifactDigest === surfaceDigest) return "./surface.png";
+ throw new Error(`Unexpected visual-test Artifact ${artifactDigest}`);
+ });
+ await writeFile(path.join(temp, "index.html"), html);
+ const output = path.join(temp, "frames");
+ await mkdir(output);
+ const render = spawnSync(process.execPath, [
+ path.join(process.cwd(), "node_modules/hyperframes/bin/hyperframes.mjs"),
+ "render",
+ temp,
+ "--format", "png-sequence",
+ "--output", output,
+ "--fps", "30",
+ "--workers", "1",
+ "--no-browser-gpu",
+ "--no-best-effort",
+ "--quiet",
+ ], { encoding: "utf8", timeout: 110_000 });
+ assert.equal(render.status, 0, `${render.stdout}\n${render.stderr}`);
+ const renderedFrame = await findPng(output);
+ assert(renderedFrame !== undefined, "Hyperframes did not emit a PNG frame.");
+ const decoded = spawnSync("ffmpeg", [
+ "-v", "error",
+ "-i", renderedFrame,
+ "-f", "rawvideo",
+ "-pix_fmt", "rgba",
+ "pipe:1",
+ ], { encoding: "buffer", timeout: 30_000 });
+ assert.equal(decoded.status, 0, decoded.stderr.toString());
+ assert.equal(decoded.stdout.byteLength, 64 * 64 * 4);
+ const center = (32 * 64 + 32) * 4;
+ const red = decoded.stdout[center]!;
+ const green = decoded.stdout[center + 1]!;
+ const blue = decoded.stdout[center + 2]!;
+ const alpha = decoded.stdout[center + 3]!;
+ assert.ok(red >= 120 && red <= 136, `unexpected composited red ${red}`);
+ assert.ok(green <= 5, `unexpected composited green ${green}`);
+ assert.ok(blue >= 119 && blue <= 135, `unexpected composited blue ${blue}`);
+ assert.equal(alpha, 255);
+ let whitePixels = 0;
+ for (let index = 0; index < decoded.stdout.byteLength; index += 4) {
+ if (decoded.stdout[index]! > 235 && decoded.stdout[index + 1]! > 235 && decoded.stdout[index + 2]! > 235) whitePixels += 1;
+ }
+ assert.ok(whitePixels > 0, "the exact-font text did not paint any white pixels");
+ } finally {
+ await rm(temp, { recursive: true, force: true });
+ }
+});
diff --git a/packages/hyperframes/test/document.test.ts b/packages/hyperframes/test/document.test.ts
new file mode 100644
index 00000000..55f312e5
--- /dev/null
+++ b/packages/hyperframes/test/document.test.ts
@@ -0,0 +1,266 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ sealAudioTrack,
+ sealComposition,
+ sealProgramSpace,
+ sealVisualTrack,
+} from "@svml/contracts";
+import {
+ assertHyperframesDocument,
+ assertHyperframesFrameIndex,
+ assertHyperframesFrameSpan,
+ compileHyperframesDocument,
+ hyperframesTime,
+ materializeHyperframesHtml,
+} from "@svml/hyperframes";
+import { digestOf } from "@svml/protocol";
+import type { FontArtifactRef } from "@svml/contracts";
+
+function fixture() {
+ const programSpace = sealProgramSpace({
+ contract: "svml.program-space@0",
+ durationSec: 1001 / 1000,
+ frameRate: { numerator: 30_000, denominator: 1_001 },
+ });
+ const picture = {
+ digest: digestOf("hyperframes:picture"),
+ size: 10,
+ mediaType: "image/png",
+ durationSec: 0,
+ };
+ const sound = {
+ digest: digestOf("hyperframes:sound"),
+ size: 20,
+ mediaType: "audio/wav",
+ durationSec: programSpace.durationSec,
+ };
+ const lower = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "lower",
+ programSpaceDigest: programSpace.digest,
+ sources: [{ name: "request", digest: digestOf("lower:request") }],
+ presents: [{
+ id: "picture",
+ span: { startFrame: 0, endFrameExclusive: 30 },
+ stacking: { order: 10, tieBreak: "lower" },
+ elements: [{
+ id: "media",
+ order: 0,
+ kind: "image",
+ artifact: picture,
+ style: [{ name: "width", value: "100%" }],
+ }],
+ }],
+ });
+ const upper = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "upper",
+ programSpaceDigest: programSpace.digest,
+ sources: [{ name: "projection", digest: digestOf("upper:projection") }],
+ presents: [{
+ id: "words",
+ span: { startFrame: 3, endFrameExclusive: 20 },
+ stacking: { order: 20, tieBreak: "upper" },
+ elements: [
+ { id: "root", order: 0, kind: "box", style: [{ name: "position", value: "absolute" }] },
+ { id: "text", parent: "root", order: 1, kind: "text", text: "Hello <world>", style: [] },
+ ],
+ }],
+ });
+ const audio = sealAudioTrack({
+ contract: "svml.audio-track@1",
+ id: "sound",
+ programSpaceDigest: programSpace.digest,
+ sources: [{ name: "basis", digest: digestOf("sound:basis") }],
+ clips: [{ id: "main", span: { startFrame: 0, endFrameExclusive: 30 }, artifact: sound, bus: "speech" }],
+ });
+ const composition = sealComposition({
+ contract: "svml.composition@1",
+ id: "main",
+ programSpace,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [upper, audio, lower],
+ });
+ return { composition, picture, sound };
+}
+
+test("HyperFrames flattens generic peer Track Presents in deterministic absolute stack order", () => {
+ const { composition, picture, sound } = fixture();
+ const document = compileHyperframesDocument(composition);
+ assert.doesNotThrow(() => assertHyperframesDocument(document));
+ assert.equal(document.compositionDigest, composition.digest);
+ assert.deepEqual(document.artifactDigests, [picture.digest, sound.digest].sort());
+ assert.ok(document.html.indexOf('data-svml-track-id="lower"') < document.html.indexOf('data-svml-track-id="upper"'));
+ assert.equal((document.html.match(/class="clip svml-visual-present"/gu) ?? []).length, 2);
+ assert.doesNotMatch(document.html, /isolation:isolate|svml-visual-track/u);
+ assert.match(document.html, /Hello &lt;world&gt;/u);
+ assert.doesNotMatch(document.html, /speech-visual-track|caption-track/u);
+});
+
+test("compiled Artifact placeholders are materialized only by the Runtime boundary", () => {
+ const { composition, picture, sound } = fixture();
+ const document = compileHyperframesDocument(composition);
+ assert.match(document.html, /svml-artifact:\/\/sha256\//u);
+ const resolved = materializeHyperframesHtml(document, (digest) => `https://assets.example/${digest}?x=1&y=2`);
+ assert.doesNotMatch(resolved, /svml-artifact:\/\//u);
+ assert.match(resolved, new RegExp(`https://assets\\.example/${picture.digest}\\?x=1&amp;y=2`, "u"));
+ assert.match(resolved, new RegExp(`https://assets\\.example/${sound.digest}\\?x=1&amp;y=2`, "u"));
+ assert.equal(document.html.includes("assets.example"), false, "materialization must not mutate the compiled document");
+});
+
+test("HyperframesDocument binds its HTML and exact frame-to-time projection", () => {
+ const { composition } = fixture();
+ const document = compileHyperframesDocument(composition);
+ const tampered = { ...document, html: document.html.replace("Hello", "Tampered") };
+ assert.throws(() => assertHyperframesDocument(tampered), /digest does not match/);
+ const changedDomain = { ...document, frameCount: document.frameCount - 1 };
+ assert.throws(() => assertHyperframesDocument(changedDomain), /digest does not match/);
+ assert.equal(document.programSpaceDigest, composition.programSpace.digest);
+ assert.deepEqual(document.frameRate, { numerator: 30_000, denominator: 1_001 });
+ assert.equal(document.frameCount, 30);
+ assert.deepEqual(document.canvas, { width: 1080, height: 1920 });
+ assert.match(document.html, /data-fps="30000\/1001"/u);
+ assert.match(document.html, /data-svml-frame-count="30"/u);
+ assert.equal(hyperframesTime.frameSeconds(30, 30_000, 1_001), "1.001");
+ assert.equal(hyperframesTime.fpsDecimal(30_000, 1_001), "29.970029970029");
+});
+
+test("any legal frame and Provider-owned chunk can be addressed without traversing earlier frames", () => {
+ const document = compileHyperframesDocument(fixture().composition);
+ assert.doesNotThrow(() => assertHyperframesFrameIndex(document, 0));
+ assert.doesNotThrow(() => assertHyperframesFrameIndex(document, 17));
+ assert.doesNotThrow(() => assertHyperframesFrameIndex(document, 29));
+ assert.throws(() => assertHyperframesFrameIndex(document, -1), /outside/u);
+ assert.throws(() => assertHyperframesFrameIndex(document, 30), /outside/u);
+
+ const chunks = [
+ { startFrame: 0, endFrameExclusive: 7 },
+ { startFrame: 7, endFrameExclusive: 14 },
+ { startFrame: 14, endFrameExclusive: 21 },
+ { startFrame: 21, endFrameExclusive: 28 },
+ { startFrame: 28, endFrameExclusive: 30 },
+ ];
+ for (const chunk of chunks) assert.doesNotThrow(() => assertHyperframesFrameSpan(document, chunk));
+ assert.equal(chunks[0]?.startFrame, 0);
+ assert.equal(chunks.at(-1)?.endFrameExclusive, document.frameCount);
+ assert.equal(chunks.reduce((frames, chunk) => frames + chunk.endFrameExclusive - chunk.startFrame, 0), document.frameCount);
+ assert.throws(
+ () => assertHyperframesFrameSpan(document, { startFrame: 29, endFrameExclusive: 31 }),
+ /outside/u,
+ );
+});
+
+test("HyperFrames emits frame-bound local animation without creating a Track stacking context", () => {
+ const { composition } = fixture();
+ const lower = composition.tracks.find((track) => track.id === "lower");
+ assert(lower?.contract === "svml.visual-track@1");
+ const present = lower.presents[0]!;
+ const media = present.elements[0]!;
+ const animated = sealVisualTrack({
+ ...lower,
+ presents: [{
+ ...present,
+ elements: [{
+ ...media,
+ animation: {
+ keyframes: [
+ { atFrame: 0, style: [{ name: "opacity", value: 0 }, { name: "transform", value: "translateY(100%)" }] },
+ { atFrame: 10, easing: "ease-out", style: [{ name: "opacity", value: 1 }, { name: "transform", value: "translateY(0%)" }] },
+ { atFrame: 30, style: [{ name: "opacity", value: 1 }, { name: "transform", value: "translateY(0%)" }] },
+ ],
+ },
+ }],
+ }],
+ });
+ const document = compileHyperframesDocument(sealComposition({
+ ...composition,
+ tracks: composition.tracks.map((track) => track.id === "lower" ? animated : track),
+ }));
+ assert.match(document.html, /@keyframes svml-/u);
+ assert.match(document.html, /33\.333333333%\{opacity:1;transform:translateY\(0%\)/u);
+ assert.match(document.html, /animation-duration:1\.001s/u);
+ assert.doesNotMatch(document.html, /isolation:isolate/u);
+});
+
+test("content-bound fonts and typed compositable Surfaces cross the same Artifact boundary", () => {
+ const space = sealProgramSpace({
+ contract: "svml.program-space@0",
+ durationSec: 1,
+ frameRate: { numerator: 30, denominator: 1 },
+ });
+ const font: FontArtifactRef = {
+ contract: "svml.font-artifact@1",
+ artifact: {
+ kind: "blob",
+ digest: digestOf("hyperframes:font"),
+ size: 1_024,
+ mediaType: "font/woff2",
+ },
+ weight: 700,
+ style: "normal",
+ };
+ const surfaceDigest = digestOf("hyperframes:alpha-surface");
+ const track = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "bound-render-dependencies",
+ programSpaceDigest: space.digest,
+ sources: [{ name: "fixture", digest: digestOf("bound-render-dependencies") }],
+ presents: [{
+ id: "bound",
+ span: { startFrame: 0, endFrameExclusive: 30 },
+ stacking: { order: 1, tieBreak: "bound" },
+ elements: [
+ { id: "root", order: 0, kind: "box", style: [] },
+ {
+ id: "text",
+ parent: "root",
+ order: 1,
+ kind: "text",
+ text: "SVML",
+ fonts: [font],
+ style: [{ name: "font-size", value: "72px" }],
+ },
+ {
+ id: "surface",
+ parent: "root",
+ order: 2,
+ kind: "surface",
+ surface: {
+ contract: "svml.compositable-surface@1",
+ artifact: { kind: "blob", digest: surfaceDigest, size: 2_048, mediaType: "video/webm" },
+ width: 1080,
+ height: 1920,
+ colorSpace: "srgb",
+ alphaMode: "straight",
+ timing: {
+ kind: "frames",
+ frameRate: { numerator: 30, denominator: 1 },
+ frameCount: 30,
+ },
+ },
+ style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }],
+ },
+ ],
+ }],
+ });
+ const document = compileHyperframesDocument(sealComposition({
+ contract: "svml.composition@1",
+ id: "render-dependencies",
+ programSpace: space,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [track],
+ }));
+ assert.doesNotThrow(() => assertHyperframesDocument(document));
+ assert.deepEqual(document.artifactDigests, [font.artifact.digest, surfaceDigest].sort());
+ assert.match(document.html, /@font-face\{/u);
+ assert.match(document.html, /format\("woff2"\)/u);
+ assert.match(document.html, /font-synthesis:none/u);
+ assert.match(document.html, /data-svml-alpha-mode="straight"/u);
+ assert.match(document.html, /data-svml-color-space="srgb"/u);
+ const materialized = materializeHyperframesHtml(document, (digest) => `https://assets.example/${digest}?token=1&part=2`);
+ assert.doesNotMatch(materialized, /svml-artifact:\/\//u);
+ assert.match(materialized, new RegExp(font.artifact.digest, "u"));
+ assert.match(materialized, new RegExp(surfaceDigest, "u"));
+});
diff --git a/packages/hyperframes/test/track-expressiveness.test.ts b/packages/hyperframes/test/track-expressiveness.test.ts
new file mode 100644
index 00000000..022fd5e5
--- /dev/null
+++ b/packages/hyperframes/test/track-expressiveness.test.ts
@@ -0,0 +1,432 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ sealComposition,
+ sealProgramSpace,
+ sealVisualTrack,
+} from "@svml/contracts";
+import type {
+ CompositableSurfaceRef,
+ MediaArtifactRef,
+ VisualElement,
+ VisualPresent,
+ VisualTrack,
+} from "@svml/contracts";
+import {
+ assertHyperframesDocument,
+ compileHyperframesDocument,
+} from "@svml/hyperframes";
+import { digestOf } from "@svml/protocol";
+
+const programSpace = sealProgramSpace({
+ contract: "svml.program-space@0",
+ durationSec: 10,
+ frameRate: { numerator: 30, denominator: 1 },
+});
+
+function composition(id: string, tracks: readonly VisualTrack[]) {
+ return sealComposition({
+ contract: "svml.composition@1",
+ id,
+ programSpace,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks,
+ });
+}
+
+function textPresent(
+ id: string,
+ order: number,
+ paintTarget: "frame" | "content" | "line" | "word",
+): VisualPresent {
+ const painted = [{ name: "background-color", value: "#f8ff66" }] as const;
+ const elements: VisualElement[] = [
+ {
+ id: "placement",
+ order: 0,
+ kind: "box",
+ style: [
+ { name: "position", value: "absolute" },
+ { name: "left", value: "10%" },
+ { name: "top", value: `${10 + order * 8}%` },
+ { name: "width", value: "80%" },
+ { name: "height", value: "16%" },
+ { name: "display", value: "flex" },
+ ...(paintTarget === "frame" ? painted : []),
+ ],
+ },
+ {
+ id: "layout",
+ parent: "placement",
+ order: 1,
+ kind: "box",
+ style: [
+ { name: "max-width", value: "100%" },
+ { name: "display", value: "flex" },
+ { name: "flex-wrap", value: "wrap" },
+ { name: "align-content", value: "center" },
+ { name: "direction", value: "ltr" },
+ { name: "writing-mode", value: "horizontal-tb" },
+ { name: "overflow", value: "visible" },
+ ],
+ },
+ {
+ id: "content",
+ parent: "layout",
+ order: 2,
+ kind: "box",
+ style: [
+ { name: "display", value: "inline-flex" },
+ { name: "flex-direction", value: "column" },
+ { name: "width", value: "fit-content" },
+ ...(paintTarget === "content" ? painted : []),
+ ],
+ },
+ {
+ id: "line-1",
+ parent: "content",
+ order: 3,
+ kind: "box",
+ style: [
+ { name: "display", value: "flex" },
+ ...(paintTarget === "line" ? painted : []),
+ ],
+ },
+ {
+ id: "word-intent",
+ parent: "line-1",
+ order: 4,
+ kind: "text",
+ text: "Intent",
+ style: [
+ { name: "font-family", value: "Inter, sans-serif" },
+ { name: "font-size", value: "64px" },
+ { name: "box-shadow", value: "0 12px 32px rgba(0,0,0,0.4)" },
+ ...(paintTarget === "word" ? painted : []),
+ ],
+ },
+ {
+ id: "word-first",
+ parent: "line-1",
+ order: 5,
+ kind: "text",
+ text: " first",
+ style: [
+ { name: "font-family", value: "Noto Sans SC, sans-serif" },
+ { name: "font-size", value: "64px" },
+ ],
+ },
+ ];
+ return {
+ id,
+ span: { startFrame: 0, endFrameExclusive: 90 },
+ stacking: { order: 60 + order, tieBreak: id },
+ elements,
+ };
+}
+
+test("Text three-box and frame/content/line/word paint semantics lower without public Text fields", () => {
+ const track = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "text-three-box-witness",
+ programSpaceDigest: programSpace.digest,
+ sources: [{ name: "text-program", digest: digestOf("text-layout-v2-program") }],
+ presents: [
+ textPresent("frame-paint", 0, "frame"),
+ textPresent("content-paint", 1, "content"),
+ textPresent("line-paint", 2, "line"),
+ textPresent("word-paint", 3, "word"),
+ ],
+ });
+ const document = compileHyperframesDocument(composition("text-three-box", [track]));
+ assert.doesNotThrow(() => assertHyperframesDocument(document));
+ assert.deepEqual(track.presents[0]!.elements.map((element) => element.id), [
+ "placement",
+ "layout",
+ "content",
+ "line-1",
+ "word-intent",
+ "word-first",
+ ]);
+ assert.equal("textLayout" in track, false);
+ assert.equal("backgroundTarget" in track, false);
+ assert.deepEqual(
+ track.presents.map((present) => present.elements.find((element) =>
+ element.style.some((declaration) => declaration.name === "background-color"),
+ )?.id),
+ ["placement", "content", "line-1", "word-intent"],
+ );
+ assert.match(document.html, /data-svml-element-id="placement"/u);
+ assert.match(document.html, /data-svml-element-id="layout"/u);
+ assert.match(document.html, /data-svml-element-id="content"/u);
+ assert.match(document.html, /writing-mode:horizontal-tb/u);
+ assert.match(document.html, /box-shadow:0 12px 32px rgba\(0,0,0,0\.4\)/u);
+ assert.equal((document.html.match(/background-color:#f8ff66/gu) ?? []).length, 4);
+});
+
+test("Caption range/cue/content boxes and word-local timing remain an ordinary VisualTrack", () => {
+ const durationFrames = 60;
+ const wordAnimation = (start: number, end: number) => ({
+ keyframes: [
+ { atFrame: 0, style: [{ name: "opacity", value: 0 }] },
+ { atFrame: start, style: [{ name: "opacity", value: 0 }] },
+ { atFrame: start + 1, easing: "ease-out" as const, style: [{ name: "opacity", value: 1 }] },
+ { atFrame: end, style: [{ name: "opacity", value: 1 }] },
+ { atFrame: Math.min(end + 1, durationFrames - 1), style: [{ name: "opacity", value: 0.65 }] },
+ { atFrame: durationFrames, style: [{ name: "opacity", value: 0.65 }] },
+ ],
+ });
+ const track = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "caption-three-box-witness",
+ programSpaceDigest: programSpace.digest,
+ sources: [
+ { name: "caption-program", digest: digestOf("dual-font-caption-program") },
+ { name: "timed-projection", digest: digestOf("caption-projection") },
+ ],
+ presents: [{
+ id: "cue-1",
+ span: { startFrame: 30, endFrameExclusive: 90 },
+ stacking: { order: 100, tieBreak: "cue-1" },
+ elements: [
+ {
+ id: "range",
+ order: 0,
+ kind: "box",
+ style: [
+ { name: "position", value: "absolute" },
+ { name: "left", value: "8%" },
+ { name: "width", value: "84%" },
+ { name: "overflow", value: "visible" },
+ ],
+ },
+ {
+ id: "cue",
+ parent: "range",
+ order: 1,
+ kind: "box",
+ style: [{ name: "display", value: "flex" }, { name: "justify-content", value: "center" }],
+ animation: {
+ keyframes: [
+ { atFrame: 0, style: [{ name: "opacity", value: 0 }, { name: "transform", value: "translateY(20px)" }] },
+ { atFrame: 8, easing: "ease-out", style: [{ name: "opacity", value: 1 }, { name: "transform", value: "translateY(0px)" }] },
+ { atFrame: durationFrames, style: [{ name: "opacity", value: 1 }, { name: "transform", value: "translateY(0px)" }] },
+ ],
+ },
+ },
+ {
+ id: "content",
+ parent: "cue",
+ order: 2,
+ kind: "box",
+ style: [
+ { name: "display", value: "inline-flex" },
+ { name: "filter", value: "drop-shadow(0 0 18px #00ffff)" },
+ ],
+ },
+ {
+ id: "soft-word",
+ parent: "content",
+ order: 3,
+ kind: "text",
+ text: "semantic ",
+ style: [{ name: "font-family", value: "Playfair Display, serif" }],
+ animation: wordAnimation(1, 20),
+ },
+ {
+ id: "punch-word",
+ parent: "content",
+ order: 4,
+ kind: "text",
+ text: "video",
+ style: [{ name: "font-family", value: "Inter, sans-serif" }, { name: "background-color", value: "#00ff66" }],
+ animation: wordAnimation(21, 50),
+ },
+ ],
+ }],
+ });
+ const document = compileHyperframesDocument(composition("caption-three-box", [track]));
+ assert.doesNotThrow(() => assertHyperframesDocument(document));
+ assert.equal("captionMode" in track, false);
+ assert.match(document.html, /data-svml-element-id="range"/u);
+ assert.match(document.html, /data-svml-element-id="cue"/u);
+ assert.match(document.html, /data-svml-element-id="content"/u);
+ assert.match(document.html, /Playfair Display, serif/u);
+ assert.match(document.html, /Inter, sans-serif/u);
+ assert.match(document.html, /drop-shadow\(0 0 18px #00ffff\)/u);
+});
+
+test("one content box lowers independent backdrop and foreground samples of one media Artifact", () => {
+ const media: MediaArtifactRef = {
+ digest: digestOf("two-box-source"),
+ size: 1_024,
+ mediaType: "video/mp4",
+ durationSec: 4,
+ };
+ const track = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "media-two-box-witness",
+ programSpaceDigest: programSpace.digest,
+ sources: [{ name: "media-program", digest: digestOf("media-box-style-v1") }],
+ presents: [{
+ id: "media-card",
+ span: { startFrame: 60, endFrameExclusive: 180 },
+ stacking: { order: 40, tieBreak: "media-card" },
+ elements: [
+ {
+ id: "content-box",
+ order: 0,
+ kind: "box",
+ style: [
+ { name: "position", value: "absolute" },
+ { name: "left", value: "8%" },
+ { name: "top", value: "24%" },
+ { name: "width", value: "84%" },
+ { name: "height", value: "42%" },
+ { name: "overflow", value: "hidden" },
+ { name: "border-radius", value: "28px" },
+ ],
+ },
+ {
+ id: "backdrop-sample",
+ parent: "content-box",
+ order: 1,
+ kind: "video",
+ artifact: media,
+ mediaStartSec: 0.5,
+ muted: true,
+ style: [
+ { name: "position", value: "absolute" },
+ { name: "width", value: "100%" },
+ { name: "height", value: "100%" },
+ { name: "object-fit", value: "cover" },
+ { name: "object-position", value: "80% 50%" },
+ { name: "filter", value: "blur(24px) brightness(0.7) saturate(1.2)" },
+ { name: "transform", value: "scale(1.12)" },
+ ],
+ },
+ {
+ id: "foreground-sample",
+ parent: "content-box",
+ order: 2,
+ kind: "video",
+ artifact: media,
+ mediaStartSec: 0.5,
+ muted: true,
+ style: [
+ { name: "position", value: "absolute" },
+ { name: "width", value: "100%" },
+ { name: "height", value: "100%" },
+ { name: "object-fit", value: "contain" },
+ { name: "object-position", value: "80% 50%" },
+ ],
+ },
+ ],
+ }],
+ });
+ const document = compileHyperframesDocument(composition("media-two-box", [track]));
+ assert.doesNotThrow(() => assertHyperframesDocument(document));
+ assert.deepEqual(document.artifactDigests, [media.digest], "two samples must retain one content dependency");
+ assert.equal((document.html.match(new RegExp(media.digest.slice("sha256:".length), "gu")) ?? []).length, 2);
+ assert.match(document.html, /object-fit:cover/u);
+ assert.match(document.html, /object-fit:contain/u);
+ assert.match(document.html, /object-position:80% 50%/u);
+ assert.equal("fit" in track, false);
+ assert.equal("focalPoint" in track, false);
+});
+
+test("Presents from one authoring Track interleave with a peer Track by absolute stacking", () => {
+ const ranking = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "ranking-witness",
+ programSpaceDigest: programSpace.digest,
+ sources: [{ name: "ranking-program", digest: digestOf("ranking-program") }],
+ presents: [
+ {
+ id: "board",
+ span: { startFrame: 0, endFrameExclusive: 300 },
+ stacking: { order: 30, tieBreak: "board" },
+ elements: [{ id: "board", order: 0, kind: "box", style: [{ name: "background-color", value: "#ffffff" }] }],
+ },
+ {
+ id: "icon-1",
+ span: { startFrame: 30, endFrameExclusive: 300 },
+ stacking: { order: 80, tieBreak: "icon-1" },
+ elements: [{ id: "icon", order: 0, kind: "text", text: "★", style: [{ name: "font-size", value: "72px" }] }],
+ },
+ {
+ id: "icon-2",
+ span: { startFrame: 60, endFrameExclusive: 300 },
+ stacking: { order: 90, tieBreak: "icon-2" },
+ elements: [{ id: "icon", order: 0, kind: "text", text: "◆", style: [{ name: "font-size", value: "72px" }] }],
+ },
+ ],
+ });
+ const peer = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "peer-text",
+ programSpaceDigest: programSpace.digest,
+ sources: [{ name: "text-program", digest: digestOf("peer-text") }],
+ presents: [{
+ id: "peer",
+ span: { startFrame: 0, endFrameExclusive: 300 },
+ stacking: { order: 50, tieBreak: "peer" },
+ elements: [{ id: "peer", order: 0, kind: "text", text: "between", style: [] }],
+ }],
+ });
+ const document = compileHyperframesDocument(composition("interleaved-ranking", [ranking, peer]));
+ const boardAt = document.html.indexOf('data-svml-present-id="board"');
+ const peerAt = document.html.indexOf('data-svml-present-id="peer"');
+ const icon1At = document.html.indexOf('data-svml-present-id="icon-1"');
+ const icon2At = document.html.indexOf('data-svml-present-id="icon-2"');
+ assert.ok(boardAt < peerAt && peerAt < icon1At && icon1At < icon2At);
+ assert.doesNotMatch(document.html, /svml-visual-track|isolation:isolate/u);
+});
+
+test("a complex owned visual may materialize as a typed compositable Surface without a component discriminator", () => {
+ const materialized: CompositableSurfaceRef = {
+ contract: "svml.compositable-surface@1",
+ artifact: {
+ kind: "blob",
+ digest: digestOf("materialized-complex-visual"),
+ size: 2_048,
+ mediaType: "video/webm",
+ },
+ width: 1080,
+ height: 1920,
+ colorSpace: "srgb",
+ alphaMode: "straight",
+ timing: {
+ kind: "frames",
+ frameRate: { numerator: 30, denominator: 1 },
+ frameCount: 60,
+ },
+ };
+ const track = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "materialized-visual-witness",
+ programSpaceDigest: programSpace.digest,
+ sources: [{ name: "materialization-receipt", digest: digestOf("particle-render-receipt") }],
+ presents: [{
+ id: "surface",
+ span: { startFrame: 120, endFrameExclusive: 180 },
+ stacking: { order: 70, tieBreak: "surface" },
+ elements: [{
+ id: "surface-media",
+ order: 0,
+ kind: "surface",
+ surface: materialized,
+ style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }],
+ }],
+ }],
+ });
+ const document = compileHyperframesDocument(composition("materialized-visual", [track]));
+ assert.doesNotThrow(() => assertHyperframesDocument(document));
+ assert.deepEqual(document.artifactDigests, [materialized.artifact.digest]);
+ assert.match(document.html, /<video/u);
+ assert.match(document.html, /data-svml-alpha-mode="straight"/u);
+ assert.equal("renderer" in track, false);
+ assert.equal("component" in track, false);
+ // The Surface contract, not the WebM extension, now carries the compositing promise.
+});
diff --git a/packages/protocol/README.md b/packages/protocol/README.md
index 3d873991..cc34abee 100644
--- a/packages/protocol/README.md
+++ b/packages/protocol/README.md
@@ -1,8 +1,14 @@
# `@svml/protocol`
-Data-only v2 bootstrap contracts shared by Core, Drivers and future modules. The package defines
+Execution-free v2 bootstrap contracts shared by Core, Drivers and future modules. The package defines
canonical values, module/type references, static raw/structured Surface declarations, records and
-origins, explicit plans, Needs, Receipts, Derivations, events and commands. It contains no parser,
-runtime or video vocabulary. A Surface declaration identifies and locks a parser capability; the
-protocol never executes it. Every Surface also declares the exact set of record types it may
+origins, explicit plans, Needs, Receipts, Derivations, events and commands. It also parses the static
+JSON representation of a Module Manifest without reading files or executing package code. It
+contains no author-source parser, runtime or video vocabulary. A Surface declaration identifies and
+locks a parser capability; the protocol never executes it. Every Surface also declares the exact set of record types it may
author, so a parser cannot use its early execution position to impersonate another module.
+
+A Type declaration may lock an optional `svml.type-validator@1` implementation. This is still
+data-only: Protocol describes the validator and its content-bound receipt but never loads or runs
+code. Structural Schema, semantic refinement execution and receipt verification remain separate
+responsibilities.
diff --git a/packages/protocol/src/build.ts b/packages/protocol/src/build.ts
index 20ef2186..342e76d5 100644
--- a/packages/protocol/src/build.ts
+++ b/packages/protocol/src/build.ts
@@ -52,6 +52,15 @@ export type ProvidedOrigin = {
export type RecordOrigin = AuthoredOrigin | DerivedOrigin | ObservedOrigin | ProvidedOrigin;
+/** Content-bound Host assertion that the Type owner's locked validator accepted this exact value. */
+export type TypeValidationReceipt = {
+ readonly format: "svml.type-validation@1";
+ readonly id: Digest;
+ readonly type: TypeRef;
+ readonly recordDigest: Digest;
+ readonly validatorDigest: Digest;
+};
+
export type TypedRecord = {
readonly id: RecordId;
readonly type: TypeRef;
@@ -59,6 +68,7 @@ export type TypedRecord = {
readonly digest: Digest;
readonly conformance: Conformance;
readonly origin: RecordOrigin;
+ readonly validation?: TypeValidationReceipt;
};
export type TypedModule = {
@@ -192,6 +202,7 @@ export type ProvidedValue = {
readonly id: RecordId;
readonly value: StoredValue;
readonly provenance?: CanonicalValue;
+ readonly validation?: TypeValidationReceipt;
};
export type CandidateRoot =
@@ -310,6 +321,7 @@ export type ProducerCompletedEvent = {
readonly command: CommandId;
readonly outputs: Readonly<Record<string, StoredValue>>;
readonly needs: Readonly<Record<string, CanonicalValue>>;
+ readonly validations?: Readonly<Record<string, TypeValidationReceipt>>;
};
export type NeedFulfilledEvent = {
@@ -322,6 +334,7 @@ export type NeedFulfilledEvent = {
readonly conformance: Conformance;
readonly delivery: Delivery;
readonly metadata: CanonicalValue;
+ readonly validation?: TypeValidationReceipt;
};
export type CommandFailedEvent = {
diff --git a/packages/protocol/src/index.ts b/packages/protocol/src/index.ts
index aef16ada..fdb0fcfc 100644
--- a/packages/protocol/src/index.ts
+++ b/packages/protocol/src/index.ts
@@ -1,5 +1,6 @@
export * from "./canonical.js";
export * from "./error.js";
+export { parseModuleManifest, parseModuleManifestText } from "./manifest.js";
export type * from "./build.js";
export type * from "./identity.js";
export type * from "./module.js";
diff --git a/packages/protocol/src/manifest.ts b/packages/protocol/src/manifest.ts
new file mode 100644
index 00000000..1f415301
--- /dev/null
+++ b/packages/protocol/src/manifest.ts
@@ -0,0 +1,319 @@
+import { canonicalize, isDigest } from "./canonical.js";
+import type {
+ CapabilityDeclaration,
+ ImplementationRef,
+ ModuleDependency,
+ ModuleManifest,
+ NeedPortDeclaration,
+ PortDeclaration,
+ ProducerDeclaration,
+ SurfaceDeclaration,
+ TypeDeclaration,
+} from "./module.js";
+import type { CapabilityRef, Digest, ModuleRef, TypeRef } from "./identity.js";
+import type { ObjectFieldSchema, ValueSchema } from "./value.js";
+
+function object(value: unknown, path: string): Record<string, unknown> {
+ if (value === null || Array.isArray(value) || typeof value !== "object") {
+ throw new Error(`${path} must be an object`);
+ }
+ return value as Record<string, unknown>;
+}
+
+function array(value: unknown, path: string): unknown[] {
+ if (!Array.isArray(value)) throw new Error(`${path} must be an array`);
+ return value;
+}
+
+function string(value: unknown, path: string): string {
+ if (typeof value !== "string" || value.length === 0) throw new Error(`${path} must be a string`);
+ return value;
+}
+
+function possiblyEmptyString(value: unknown, path: string): string {
+ if (typeof value !== "string") throw new Error(`${path} must be a string`);
+ return value;
+}
+
+function boolean(value: unknown, path: string): boolean {
+ if (typeof value !== "boolean") throw new Error(`${path} must be a boolean`);
+ return value;
+}
+
+function number(value: unknown, path: string): number {
+ if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${path} must be a number`);
+ return value;
+}
+
+function digest(value: unknown, path: string): Digest {
+ const parsed = string(value, path);
+ if (!isDigest(parsed)) throw new Error(`${path} must be a sha256 digest`);
+ return parsed;
+}
+
+function moduleRef(value: unknown, path: string): ModuleRef {
+ const parsed = object(value, path);
+ return {
+ name: string(parsed.name, `${path}.name`),
+ version: string(parsed.version, `${path}.version`),
+ };
+}
+
+function typeRef(value: unknown, path: string): TypeRef {
+ const parsed = object(value, path);
+ return {
+ module: moduleRef(parsed.module, `${path}.module`),
+ name: string(parsed.name, `${path}.name`),
+ };
+}
+
+function capabilityRef(value: unknown, path: string): CapabilityRef {
+ const parsed = object(value, path);
+ return {
+ module: moduleRef(parsed.module, `${path}.module`),
+ name: string(parsed.name, `${path}.name`),
+ };
+}
+
+function optionalNumber(
+ parsed: Record<string, unknown>,
+ name: string,
+ path: string,
+): { readonly [key: string]: number } {
+ return parsed[name] === undefined ? {} : { [name]: number(parsed[name], `${path}.${name}`) };
+}
+
+function valueSchema(value: unknown, path: string): ValueSchema {
+ const parsed = object(value, path);
+ const kind = string(parsed.kind, `${path}.kind`);
+ switch (kind) {
+ case "null":
+ case "boolean":
+ return { kind };
+ case "number":
+ return {
+ kind,
+ ...(parsed.integer === undefined ? {} : { integer: boolean(parsed.integer, `${path}.integer`) }),
+ ...optionalNumber(parsed, "minimum", path),
+ ...optionalNumber(parsed, "maximum", path),
+ } as ValueSchema;
+ case "string":
+ return {
+ kind,
+ ...(parsed.enum === undefined
+ ? {}
+ : { enum: array(parsed.enum, `${path}.enum`).map((item, index) => string(item, `${path}.enum[${index}]`)) }),
+ ...optionalNumber(parsed, "minLength", path),
+ ...optionalNumber(parsed, "maxLength", path),
+ } as ValueSchema;
+ case "literal":
+ return { kind, value: canonicalize(parsed.value) };
+ case "array":
+ return {
+ kind,
+ items: valueSchema(parsed.items, `${path}.items`),
+ ...optionalNumber(parsed, "minItems", path),
+ ...optionalNumber(parsed, "maxItems", path),
+ } as ValueSchema;
+ case "object": {
+ const rawFields = object(parsed.fields, `${path}.fields`);
+ const fields: Record<string, ObjectFieldSchema> = {};
+ for (const [name, rawField] of Object.entries(rawFields)) {
+ const field = object(rawField, `${path}.fields.${name}`);
+ Object.defineProperty(fields, name, {
+ value: {
+ schema: valueSchema(field.schema, `${path}.fields.${name}.schema`),
+ ...(field.optional === undefined
+ ? {}
+ : { optional: boolean(field.optional, `${path}.fields.${name}.optional`) }),
+ },
+ enumerable: true,
+ configurable: true,
+ writable: true,
+ });
+ }
+ return {
+ kind,
+ fields,
+ ...(parsed.allowUnknown === undefined
+ ? {}
+ : { allowUnknown: boolean(parsed.allowUnknown, `${path}.allowUnknown`) }),
+ };
+ }
+ case "oneOf":
+ return {
+ kind,
+ variants: array(parsed.variants, `${path}.variants`).map((item, index) =>
+ valueSchema(item, `${path}.variants[${index}]`),
+ ),
+ };
+ case "blob":
+ return {
+ kind,
+ ...(parsed.mediaTypes === undefined
+ ? {}
+ : {
+ mediaTypes: array(parsed.mediaTypes, `${path}.mediaTypes`).map((item, index) =>
+ string(item, `${path}.mediaTypes[${index}]`),
+ ),
+ }),
+ ...optionalNumber(parsed, "maxBytes", path),
+ } as ValueSchema;
+ default:
+ throw new Error(`${path}.kind ${kind} is unsupported`);
+ }
+}
+
+function dependency(value: unknown, path: string): ModuleDependency {
+ const parsed = object(value, path);
+ return {
+ module: moduleRef(parsed.module, `${path}.module`),
+ digest: digest(parsed.digest, `${path}.digest`),
+ };
+}
+
+function typeDeclaration(value: unknown, path: string): TypeDeclaration {
+ const parsed = object(value, path);
+ return {
+ name: string(parsed.name, `${path}.name`),
+ schema: valueSchema(parsed.schema, `${path}.schema`),
+ ...(parsed.description === undefined
+ ? {}
+ : { description: string(parsed.description, `${path}.description`) }),
+ ...(parsed.validator === undefined
+ ? {}
+ : { validator: typeValidator(parsed.validator, `${path}.validator`) }),
+ };
+}
+
+function typeValidator(value: unknown, path: string): NonNullable<TypeDeclaration["validator"]> {
+ const parsed = object(value, path);
+ if (parsed.abi !== "svml.type-validator@1") {
+ throw new Error(`${path}.abi must be svml.type-validator@1`);
+ }
+ return {
+ abi: "svml.type-validator@1",
+ implementation: implementation(parsed.implementation, `${path}.implementation`),
+ };
+}
+
+function capabilityDeclaration(value: unknown, path: string): CapabilityDeclaration {
+ const parsed = object(value, path);
+ return {
+ name: string(parsed.name, `${path}.name`),
+ returns: typeRef(parsed.returns, `${path}.returns`),
+ ...(parsed.description === undefined
+ ? {}
+ : { description: string(parsed.description, `${path}.description`) }),
+ };
+}
+
+function port(value: unknown, path: string): PortDeclaration {
+ const parsed = object(value, path);
+ return {
+ name: string(parsed.name, `${path}.name`),
+ type: typeRef(parsed.type, `${path}.type`),
+ ...(parsed.affinity === undefined
+ ? {}
+ : { affinity: resultAffinityList(parsed.affinity, `${path}.affinity`) }),
+ };
+}
+
+function resultAffinityList(
+ value: unknown,
+ path: string,
+): NonNullable<PortDeclaration["affinity"]> {
+ return array(value, path).map((item, index) => {
+ const itemPath = `${path}[${index}]`;
+ const parsed = object(item, itemPath);
+ return {
+ resultPointer: possiblyEmptyString(parsed.resultPointer, `${itemPath}.resultPointer`),
+ input: string(parsed.input, `${itemPath}.input`),
+ inputPointer: possiblyEmptyString(parsed.inputPointer, `${itemPath}.inputPointer`),
+ };
+ });
+}
+
+function needPort(value: unknown, path: string): NeedPortDeclaration {
+ const parsed = object(value, path);
+ return {
+ name: string(parsed.name, `${path}.name`),
+ capability: capabilityRef(parsed.capability, `${path}.capability`),
+ returns: typeRef(parsed.returns, `${path}.returns`),
+ ...(parsed.affinity === undefined
+ ? {}
+ : { affinity: resultAffinityList(parsed.affinity, `${path}.affinity`) }),
+ };
+}
+
+function implementation(value: unknown, path: string): ImplementationRef {
+ const parsed = object(value, path);
+ return {
+ kind: string(parsed.kind, `${path}.kind`),
+ locator: string(parsed.locator, `${path}.locator`),
+ digest: digest(parsed.digest, `${path}.digest`),
+ };
+}
+
+function producer(value: unknown, path: string): ProducerDeclaration {
+ const parsed = object(value, path);
+ return {
+ name: string(parsed.name, `${path}.name`),
+ inputs: array(parsed.inputs, `${path}.inputs`).map((item, index) =>
+ port(item, `${path}.inputs[${index}]`),
+ ),
+ outputs: array(parsed.outputs, `${path}.outputs`).map((item, index) =>
+ port(item, `${path}.outputs[${index}]`),
+ ),
+ needs: array(parsed.needs, `${path}.needs`).map((item, index) =>
+ needPort(item, `${path}.needs[${index}]`),
+ ),
+ implementation: implementation(parsed.implementation, `${path}.implementation`),
+ };
+}
+
+function surface(value: unknown, path: string): SurfaceDeclaration {
+ const parsed = object(value, path);
+ const mode = string(parsed.mode, `${path}.mode`);
+ if (mode !== "raw" && mode !== "structured") {
+ throw new Error(`${path}.mode must be raw or structured`);
+ }
+ return {
+ name: string(parsed.name, `${path}.name`),
+ tag: string(parsed.tag, `${path}.tag`),
+ mode,
+ outputs: array(parsed.outputs, `${path}.outputs`).map((item, index) =>
+ typeRef(item, `${path}.outputs[${index}]`),
+ ),
+ implementation: implementation(parsed.implementation, `${path}.implementation`),
+ };
+}
+
+export function parseModuleManifest(value: unknown): ModuleManifest {
+ const parsed = object(canonicalize(value), "$manifest");
+ if (parsed.format !== "svml.module@0") throw new Error("$manifest.format must be svml.module@0");
+ return {
+ format: "svml.module@0",
+ name: string(parsed.name, "$manifest.name"),
+ version: string(parsed.version, "$manifest.version"),
+ dependencies: array(parsed.dependencies, "$manifest.dependencies").map((item, index) =>
+ dependency(item, `$manifest.dependencies[${index}]`),
+ ),
+ types: array(parsed.types, "$manifest.types").map((item, index) =>
+ typeDeclaration(item, `$manifest.types[${index}]`),
+ ),
+ capabilities: array(parsed.capabilities, "$manifest.capabilities").map((item, index) =>
+ capabilityDeclaration(item, `$manifest.capabilities[${index}]`),
+ ),
+ surfaces: array(parsed.surfaces, "$manifest.surfaces").map((item, index) =>
+ surface(item, `$manifest.surfaces[${index}]`),
+ ),
+ producers: array(parsed.producers, "$manifest.producers").map((item, index) =>
+ producer(item, `$manifest.producers[${index}]`),
+ ),
+ };
+}
+
+export function parseModuleManifestText(text: string): ModuleManifest {
+ return parseModuleManifest(JSON.parse(text) as unknown);
+}
diff --git a/packages/protocol/src/module.ts b/packages/protocol/src/module.ts
index 82c541cd..9da53fc3 100644
--- a/packages/protocol/src/module.ts
+++ b/packages/protocol/src/module.ts
@@ -10,6 +10,13 @@ export type TypeDeclaration = {
readonly name: string;
readonly schema: ValueSchema;
readonly description?: string;
+ /** Optional package-owned semantic refinement beyond the structural Schema. */
+ readonly validator?: TypeValidatorDeclaration;
+};
+
+export type TypeValidatorDeclaration = {
+ readonly abi: "svml.type-validator@1";
+ readonly implementation: ImplementationRef;
};
/** A domain-neutral equality promise from one result field to one Producer input field. */
diff --git a/packages/realization/package.json b/packages/realization/package.json
index 7185c327..88d9ef6a 100644
--- a/packages/realization/package.json
+++ b/packages/realization/package.json
@@ -11,6 +11,7 @@
"@svml/protocol": "workspace:*"
},
"devDependencies": {
- "@svml/elaborator": "workspace:*"
+ "@svml/elaborator": "workspace:*",
+ "@svml/validation": "workspace:*"
}
}
diff --git a/packages/realization/src/overlay.ts b/packages/realization/src/overlay.ts
index 90402137..9c6867a8 100644
--- a/packages/realization/src/overlay.ts
+++ b/packages/realization/src/overlay.ts
@@ -16,6 +16,7 @@ import type {
LinkedProgram,
OperationNode,
StoredValue,
+ TypeValidationReceipt,
} from "@svml/protocol";
export type RealizationOverlay = {
@@ -45,6 +46,7 @@ export type ProvidedCandidateInput = {
readonly fidelity: Conformance;
readonly record?: string;
readonly provenance?: CanonicalValue;
+ readonly validation?: TypeValidationReceipt;
};
export class RealizationError extends Error {
@@ -101,6 +103,7 @@ export function createProvidedCandidate(input: ProvidedCandidateInput): Candidat
value,
fidelity: input.fidelity,
...(input.provenance === undefined ? {} : { provenance: canonicalize(input.provenance) }),
+ ...(input.validation === undefined ? {} : { validation: input.validation }),
};
const suffix = digestOf(identity).slice("sha256:".length);
return {
@@ -112,6 +115,7 @@ export function createProvidedCandidate(input: ProvidedCandidateInput): Candidat
id: input.record ?? `provided:${suffix}`,
value,
...(input.provenance === undefined ? {} : { provenance: canonicalize(input.provenance) }),
+ ...(input.validation === undefined ? {} : { validation: input.validation }),
},
},
fidelity: input.fidelity,
diff --git a/packages/realization/test/validation.test.ts b/packages/realization/test/validation.test.ts
new file mode 100644
index 00000000..08287bfc
--- /dev/null
+++ b/packages/realization/test/validation.test.ts
@@ -0,0 +1,140 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ createResolvedClosure,
+ digestOf,
+ link,
+ sealCompiledGraph,
+ sealTypedModule,
+} from "@svml/core";
+import type { ModuleManifest, TypeRef } from "@svml/protocol";
+import {
+ createProvidedCandidate,
+ resolveRealization,
+ sealRealizationOverlay,
+} from "@svml/realization";
+import {
+ TypeValidatorRegistry,
+ validateValue,
+} from "@svml/validation";
+
+const moduleRef = { name: "example.validated-existing", version: "1" } as const;
+const mediaType = { module: moduleRef, name: "Media" } satisfies TypeRef;
+const validatorDigest = digestOf("example.validated-existing/validator@1");
+const manifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: moduleRef.name,
+ version: moduleRef.version,
+ dependencies: [],
+ types: [{
+ name: mediaType.name,
+ schema: { kind: "string", minLength: 1 },
+ validator: {
+ abi: "svml.type-validator@1",
+ implementation: {
+ kind: "registered",
+ locator: "example.validated-existing/validator",
+ digest: validatorDigest,
+ },
+ },
+ }],
+ capabilities: [],
+ surfaces: [],
+ producers: [{
+ name: "generate",
+ inputs: [],
+ outputs: [{ name: "media", type: mediaType }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.validated-existing/generate",
+ digest: digestOf("example.validated-existing/generate@1"),
+ },
+ }],
+};
+
+function fixture() {
+ const closure = createResolvedClosure([manifest]);
+ const program = link(closure, [sealTypedModule({
+ id: "author:empty",
+ closureDigest: closure.digest,
+ records: [],
+ })]);
+ const source = sealCompiledGraph({
+ program: program.semanticDigest,
+ outputs: [{
+ id: "media",
+ type: mediaType,
+ primary: "generated",
+ candidates: ["generated"],
+ semanticInputs: [],
+ }],
+ candidates: [{
+ id: "generated",
+ output: "media",
+ root: { kind: "operation", result: { kind: "operation-result", operation: "generate" } },
+ fidelity: "exact",
+ }],
+ operations: [{
+ id: "generate",
+ producer: { module: moduleRef, name: "generate" },
+ inputs: {},
+ result: { kind: "output", name: "media", record: "media:generated" },
+ }],
+ });
+ return { program, source };
+}
+
+function validators(): TypeValidatorRegistry {
+ const registry = new TypeValidatorRegistry();
+ registry.register(mediaType, validatorDigest, ({ value }) => {
+ if (value.kind !== "inline" || typeof value.value !== "string" || !value.value.startsWith("approved:")) {
+ throw new Error("media is not approved");
+ }
+ });
+ return registry;
+}
+
+test("provided Candidates pass the same Type-owner admission gate", async () => {
+ const { program, source } = fixture();
+ const value = { kind: "inline" as const, value: "approved:clip" };
+ const validation = await validateValue(program.closure, mediaType, value, validators());
+ assert.ok(validation);
+ const accepted = createProvidedCandidate({
+ output: "media",
+ value,
+ fidelity: "exact",
+ validation,
+ });
+ assert.doesNotThrow(() => resolveRealization(program, source, [sealRealizationOverlay({
+ sourceGraph: source.id,
+ candidates: [accepted],
+ operations: [],
+ })]));
+
+ const missing = createProvidedCandidate({ output: "media", value, fidelity: "exact" });
+ assert.throws(
+ () => resolveRealization(program, source, [sealRealizationOverlay({
+ sourceGraph: source.id,
+ candidates: [missing],
+ operations: [],
+ })]),
+ /requires .*validator/u,
+ );
+
+ const tampered = createProvidedCandidate({
+ output: "media",
+ value,
+ fidelity: "exact",
+ validation: { ...validation, recordDigest: digestOf("another-value") },
+ });
+ assert.throws(
+ () => resolveRealization(program, source, [sealRealizationOverlay({
+ sourceGraph: source.id,
+ candidates: [tampered],
+ operations: [],
+ })]),
+ /validation receipt belongs to another value/u,
+ );
+});
diff --git a/packages/runtime/README.md b/packages/runtime/README.md
new file mode 100644
index 00000000..225c8142
--- /dev/null
+++ b/packages/runtime/README.md
@@ -0,0 +1,33 @@
+# `@svml/runtime`
+
+Environment-neutral execution and persistence ports around the domain-free Core state machine.
+
+The first implementation contains:
+
+- `RuntimeCommandExecutor`: regenerate Core-authorized commands and execute one by identity;
+- `LocalBuildScheduler`: one authoritative, queue-free scheduler shared by multiple Builds;
+- named concurrency lanes with Runtime Profile overrides;
+- static Runtime Module facets, sealed Profile resolution and a content-addressed Runtime Closure;
+- exact Provider capability/return bindings, implementation digests and permission allowlists;
+- `BuildStore` and `OperationStore` ports with compare-and-swap in-memory references;
+- a recoverable Provider Endpoint lifecycle that journals before `start`, checkpoints `pending`,
+ and calls `resume` after a restart.
+
+The Scheduler does not traverse Graphs, choose Candidates, rewrite Needs or accept arbitrary
+serialized commands. Core remains the sole source of readiness and the sole Event acceptance law.
+Lanes only limit how many already-authorized commands execute concurrently. A Provider's remote job
+queue is still internal to that Endpoint and cannot advance another Build step.
+
+`MemoryBuildStore` stores verified BuildState only. `MemoryOperationStore` separately records a
+content-addressed attempt identity, stable submission key, pending checkpoint and terminal result.
+Changing the Build, Command, Endpoint implementation or Runtime Closure changes that identity.
+Nothing in the Operation journal becomes an accepted domain fact until an Endpoint completion is
+validated and reduced by Core. If a process stops after completion is journaled but before Core
+accepts its Event, the next run reconstructs the same Event from the stored completion and does not
+call the Endpoint again.
+
+This is an in-process reference, not a durable queue. File/SQLite stores, attempt leases, wake-up
+polling, credentials and production Provider adapters remain separate Runtime packages. An Endpoint
+whose upstream API cannot look up or deduplicate the supplied `submissionKey` cannot promise
+exactly-once remote work across the crash window; its `resume(undefined)` must explicitly reconcile
+that uncertainty.
diff --git a/packages/runtime/package.json b/packages/runtime/package.json
new file mode 100644
index 00000000..4201e82e
--- /dev/null
+++ b/packages/runtime/package.json
@@ -0,0 +1,13 @@
+{
+ "name": "@svml/runtime",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "dependencies": {
+ "@svml/core": "workspace:*",
+ "@svml/protocol": "workspace:*"
+ }
+}
diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.ts
new file mode 100644
index 00000000..e002ff62
--- /dev/null
+++ b/packages/runtime/src/index.ts
@@ -0,0 +1,22 @@
+export { MemoryBuildStore } from "./memory.js";
+export {
+ MemoryOperationStore,
+ sealOperationCompletion,
+ sealOperationIdentity,
+ verifyOperationIdentity,
+ verifyOperationSnapshot,
+} from "./operations.js";
+export type * from "./operations.js";
+export {
+ RuntimeModuleRegistry,
+ localSchedulerOptionsFromClosure,
+ resolveRuntimeProfile,
+ runtimeProvider,
+ sealRuntimeProfile,
+ verifyRuntimeClosure,
+ verifyRuntimeCoverage,
+ verifyRuntimeProfile,
+} from "./profile.js";
+export type * from "./profile.js";
+export { LocalBuildScheduler } from "./scheduler.js";
+export type * from "./types.js";
diff --git a/packages/runtime/src/memory.ts b/packages/runtime/src/memory.ts
new file mode 100644
index 00000000..c538a9c7
--- /dev/null
+++ b/packages/runtime/src/memory.ts
@@ -0,0 +1,59 @@
+import { verifyBuildState } from "@svml/core";
+import type { BuildState } from "@svml/protocol";
+
+import type {
+ BuildSnapshot,
+ BuildStore,
+ BuildStoreWrite,
+} from "./types.js";
+
+function copy(snapshot: BuildSnapshot): BuildSnapshot {
+ return structuredClone(snapshot);
+}
+
+function durableState(state: BuildState): BuildState {
+ verifyBuildState(state);
+ const normalized = { ...structuredClone(state), outstanding: [] };
+ verifyBuildState(normalized);
+ return normalized;
+}
+
+/** Reference CAS store for tests and one-process local Builds. It is not an Operation journal. */
+export class MemoryBuildStore implements BuildStore {
+ readonly #builds = new Map<string, BuildSnapshot>();
+
+ async create(build: string, state: BuildState): Promise<BuildSnapshot> {
+ if (build.trim().length === 0) throw new Error("build id must not be empty");
+ if (this.#builds.has(build)) throw new Error(`build ${build} already exists`);
+ const snapshot = { build, revision: 0, state: durableState(state) };
+ this.#builds.set(build, snapshot);
+ return copy(snapshot);
+ }
+
+ async read(build: string): Promise<BuildSnapshot | undefined> {
+ const snapshot = this.#builds.get(build);
+ return snapshot === undefined ? undefined : copy(snapshot);
+ }
+
+ async compareAndSwap(
+ build: string,
+ expectedRevision: number,
+ state: BuildState,
+ ): Promise<BuildStoreWrite> {
+ if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) {
+ throw new Error("expected revision must be a non-negative safe integer");
+ }
+ const current = this.#builds.get(build);
+ if (current === undefined) throw new Error(`build ${build} does not exist`);
+ if (current.revision !== expectedRevision) {
+ return { status: "conflict", current: copy(current) };
+ }
+ const snapshot = {
+ build,
+ revision: current.revision + 1,
+ state: durableState(state),
+ };
+ this.#builds.set(build, snapshot);
+ return { status: "stored", snapshot: copy(snapshot) };
+ }
+}
diff --git a/packages/runtime/src/operations.ts b/packages/runtime/src/operations.ts
new file mode 100644
index 00000000..35f4cdee
--- /dev/null
+++ b/packages/runtime/src/operations.ts
@@ -0,0 +1,231 @@
+import { digestOf, isDigest } from "@svml/protocol";
+import type {
+ CanonicalValue,
+ Conformance,
+ Delivery,
+ Digest,
+ StoredValue,
+} from "@svml/protocol";
+
+export type OperationIdentity = {
+ readonly format: "svml.operation-identity@1";
+ readonly id: Digest;
+ readonly build: string;
+ readonly command: string;
+ readonly endpoint: string;
+ readonly implementationDigest: Digest;
+ readonly runtimeClosure: Digest;
+ readonly requestDigest: Digest;
+ readonly attempt: number;
+ readonly submissionKey: Digest;
+};
+
+export type OperationCompletion = {
+ readonly value: StoredValue;
+ readonly conformance: Conformance;
+ readonly delivery: Delivery;
+ readonly metadata: CanonicalValue;
+ readonly digest: Digest;
+};
+
+export type OperationFailure = {
+ readonly code: string;
+ readonly message: string;
+ readonly retryable: boolean;
+};
+
+export type OperationSnapshot = OperationIdentity & {
+ readonly revision: number;
+ readonly status: "created" | "pending" | "completed" | "failed";
+ readonly checkpoint?: CanonicalValue;
+ readonly completion?: OperationCompletion;
+ readonly failure?: OperationFailure;
+};
+
+export type OperationUpdate =
+ | { readonly status: "pending"; readonly checkpoint: CanonicalValue }
+ | {
+ readonly status: "completed";
+ readonly completion: Omit<OperationCompletion, "digest">;
+ }
+ | { readonly status: "failed"; readonly failure: OperationFailure };
+
+export type OperationCreate =
+ | { readonly status: "created"; readonly snapshot: OperationSnapshot }
+ | { readonly status: "existing"; readonly snapshot: OperationSnapshot };
+
+export type OperationStoreWrite =
+ | { readonly status: "stored"; readonly snapshot: OperationSnapshot }
+ | { readonly status: "conflict"; readonly current: OperationSnapshot };
+
+export type OperationStore = {
+ create(identity: OperationIdentity): Promise<OperationCreate>;
+ read(id: Digest): Promise<OperationSnapshot | undefined>;
+ compareAndSwap(id: Digest, expectedRevision: number, update: OperationUpdate): Promise<OperationStoreWrite>;
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+function positiveInteger(value: number, subject: string): number {
+ assert(Number.isSafeInteger(value) && value > 0, `${subject} must be a positive safe integer`);
+ return value;
+}
+
+function submissionContent(value: {
+ readonly build: string;
+ readonly command: string;
+ readonly endpoint: string;
+ readonly implementationDigest: Digest;
+ readonly runtimeClosure: Digest;
+ readonly requestDigest: Digest;
+ readonly attempt: number;
+}) {
+ return {
+ format: "svml.operation-submission@1",
+ build: value.build,
+ command: value.command,
+ endpoint: value.endpoint,
+ implementationDigest: value.implementationDigest,
+ runtimeClosure: value.runtimeClosure,
+ requestDigest: value.requestDigest,
+ attempt: value.attempt,
+ } as const;
+}
+
+function identityContent(value: Omit<OperationIdentity, "id">): Omit<OperationIdentity, "id"> {
+ return {
+ format: "svml.operation-identity@1",
+ build: value.build,
+ command: value.command,
+ endpoint: value.endpoint,
+ implementationDigest: value.implementationDigest,
+ runtimeClosure: value.runtimeClosure,
+ requestDigest: value.requestDigest,
+ attempt: value.attempt,
+ submissionKey: value.submissionKey,
+ };
+}
+
+export function sealOperationIdentity(
+ value: Omit<OperationIdentity, "format" | "id" | "submissionKey">,
+): OperationIdentity {
+ assert(value.build.trim().length > 0, "Operation build id is empty");
+ assert(value.command.trim().length > 0, "Operation command id is empty");
+ assert(value.endpoint.trim().length > 0, "Operation Endpoint id is empty");
+ assert(isDigest(value.implementationDigest), "Operation implementation digest is invalid");
+ assert(isDigest(value.runtimeClosure), "Operation Runtime Closure digest is invalid");
+ assert(isDigest(value.requestDigest), "Operation request digest is invalid");
+ positiveInteger(value.attempt, "Operation attempt");
+ const submissionKey = digestOf(submissionContent(value));
+ const content = identityContent({
+ format: "svml.operation-identity@1",
+ ...value,
+ submissionKey,
+ });
+ return { ...content, id: digestOf(content) };
+}
+
+export function verifyOperationIdentity(identity: OperationIdentity): void {
+ const expected = sealOperationIdentity(identity);
+ assert(identity.format === expected.format
+ && identity.id === expected.id
+ && identity.submissionKey === expected.submissionKey, "Operation identity differs");
+}
+
+function completionContent(value: Omit<OperationCompletion, "digest">) {
+ return {
+ value: structuredClone(value.value),
+ conformance: value.conformance,
+ delivery: value.delivery,
+ metadata: structuredClone(value.metadata),
+ };
+}
+
+export function sealOperationCompletion(
+ value: Omit<OperationCompletion, "digest">,
+): OperationCompletion {
+ const content = completionContent(value);
+ return { ...content, digest: digestOf(content) };
+}
+
+export function verifyOperationSnapshot(snapshot: OperationSnapshot): void {
+ verifyOperationIdentity(snapshot);
+ assert(Number.isSafeInteger(snapshot.revision) && snapshot.revision >= 0, "Operation revision is invalid");
+ const presence = [snapshot.checkpoint !== undefined, snapshot.completion !== undefined, snapshot.failure !== undefined]
+ .filter(Boolean).length;
+ if (snapshot.status === "created") assert(presence === 0, "created Operation carries mutable result state");
+ if (snapshot.status === "pending") assert(snapshot.checkpoint !== undefined && presence === 1, "pending Operation requires only a checkpoint");
+ if (snapshot.status === "completed") {
+ assert(snapshot.completion !== undefined && presence === 1, "completed Operation requires only completion");
+ const expected = sealOperationCompletion(snapshot.completion);
+ assert(snapshot.completion.digest === expected.digest, "Operation completion digest differs");
+ }
+ if (snapshot.status === "failed") {
+ assert(snapshot.failure !== undefined && presence === 1, "failed Operation requires only failure");
+ assert(snapshot.failure.code.trim().length > 0 && snapshot.failure.message.trim().length > 0, "Operation failure is invalid");
+ }
+}
+
+function copy(snapshot: OperationSnapshot): OperationSnapshot {
+ return structuredClone(snapshot);
+}
+
+/** In-process reference journal. Durable/distributed adapters must add leases around the same CAS law. */
+export class MemoryOperationStore implements OperationStore {
+ readonly #operations = new Map<Digest, OperationSnapshot>();
+
+ async create(identity: OperationIdentity): Promise<OperationCreate> {
+ verifyOperationIdentity(identity);
+ const existing = this.#operations.get(identity.id);
+ if (existing !== undefined) return { status: "existing", snapshot: copy(existing) };
+ const snapshot: OperationSnapshot = {
+ ...structuredClone(identity),
+ revision: 0,
+ status: "created",
+ };
+ verifyOperationSnapshot(snapshot);
+ this.#operations.set(snapshot.id, snapshot);
+ return { status: "created", snapshot: copy(snapshot) };
+ }
+
+ async read(id: Digest): Promise<OperationSnapshot | undefined> {
+ const snapshot = this.#operations.get(id);
+ return snapshot === undefined ? undefined : copy(snapshot);
+ }
+
+ async compareAndSwap(
+ id: Digest,
+ expectedRevision: number,
+ update: OperationUpdate,
+ ): Promise<OperationStoreWrite> {
+ assert(Number.isSafeInteger(expectedRevision) && expectedRevision >= 0, "expected Operation revision is invalid");
+ const current = this.#operations.get(id);
+ assert(current !== undefined, `Operation ${id} does not exist`);
+ if (current.revision !== expectedRevision) return { status: "conflict", current: copy(current) };
+ assert(current.status !== "completed" && current.status !== "failed", `Operation ${id} is already terminal`);
+ const mutable = update.status === "pending"
+ ? { status: "pending" as const, checkpoint: structuredClone(update.checkpoint) }
+ : update.status === "completed"
+ ? { status: "completed" as const, completion: sealOperationCompletion(update.completion) }
+ : { status: "failed" as const, failure: structuredClone(update.failure) };
+ const snapshot: OperationSnapshot = {
+ format: current.format,
+ id: current.id,
+ build: current.build,
+ command: current.command,
+ endpoint: current.endpoint,
+ implementationDigest: current.implementationDigest,
+ runtimeClosure: current.runtimeClosure,
+ requestDigest: current.requestDigest,
+ attempt: current.attempt,
+ submissionKey: current.submissionKey,
+ revision: current.revision + 1,
+ ...mutable,
+ };
+ verifyOperationSnapshot(snapshot);
+ this.#operations.set(id, snapshot);
+ return { status: "stored", snapshot: copy(snapshot) };
+ }
+}
diff --git a/packages/runtime/src/profile.ts b/packages/runtime/src/profile.ts
new file mode 100644
index 00000000..6075a910
--- /dev/null
+++ b/packages/runtime/src/profile.ts
@@ -0,0 +1,542 @@
+import { resolveProducer } from "@svml/core";
+import { digestOf, isDigest } from "@svml/protocol";
+import type {
+ BuildState,
+ CapabilityRef,
+ Digest,
+ ModuleRef,
+ TypeRef,
+} from "@svml/protocol";
+
+export type RuntimeFacetRole =
+ | "scheduler"
+ | "build-store"
+ | "operation-store"
+ | "artifact-store"
+ | "provider-endpoint";
+
+export type RuntimeFacetRef = {
+ readonly module: ModuleRef;
+ readonly name: string;
+};
+
+export type RuntimeImplementation = {
+ readonly locator: string;
+ readonly digest: Digest;
+};
+
+export type RuntimeCapability = {
+ readonly capability: CapabilityRef;
+ readonly returns: TypeRef;
+};
+
+type RuntimeServiceFacet = {
+ readonly name: string;
+ readonly role: Exclude<RuntimeFacetRole, "provider-endpoint">;
+ readonly implementation: RuntimeImplementation;
+ readonly permissions: readonly string[];
+};
+
+export type RuntimeProviderFacet = {
+ readonly name: string;
+ readonly role: "provider-endpoint";
+ readonly implementation: RuntimeImplementation;
+ readonly permissions: readonly string[];
+ readonly fulfills: readonly RuntimeCapability[];
+ readonly lifecycle: "immediate" | "recoverable";
+ readonly defaultConcurrency: number;
+};
+
+export type RuntimeFacet = RuntimeServiceFacet | RuntimeProviderFacet;
+
+/** Static package metadata. Reading it must never execute the implementation it describes. */
+export type RuntimeModuleManifest = {
+ readonly format: "svml.runtime-module@1";
+ readonly name: string;
+ readonly version: string;
+ readonly facets: readonly RuntimeFacet[];
+};
+
+export type RuntimeProfileInstance = {
+ readonly id: string;
+ readonly facet: RuntimeFacetRef;
+ /** Optional authority-wide lane name. The default is provider:<instance id>. */
+ readonly lane?: string;
+};
+
+export type RuntimeProviderBinding = RuntimeCapability & {
+ readonly endpoint: string;
+};
+
+export type RuntimeProfile = {
+ readonly format: "svml.runtime-profile@1";
+ readonly digest: Digest;
+ readonly name: string;
+ readonly instances: readonly RuntimeProfileInstance[];
+ readonly scheduler: string;
+ readonly stores: {
+ readonly build?: string;
+ readonly operations?: string;
+ readonly artifacts?: string;
+ };
+ readonly providers: readonly RuntimeProviderBinding[];
+ readonly scheduling: {
+ readonly maxConcurrency: number;
+ readonly lanes: readonly { readonly name: string; readonly maxConcurrency: number }[];
+ };
+};
+
+export type ResolvedRuntimeService = {
+ readonly id: string;
+ readonly role: Exclude<RuntimeFacetRole, "provider-endpoint">;
+ readonly facet: RuntimeFacetRef;
+ readonly implementation: RuntimeImplementation;
+ readonly permissions: readonly string[];
+};
+
+export type ResolvedRuntimeProvider = {
+ readonly id: string;
+ readonly role: "provider-endpoint";
+ readonly facet: RuntimeFacetRef;
+ readonly implementation: RuntimeImplementation;
+ readonly permissions: readonly string[];
+ readonly fulfills: readonly RuntimeCapability[];
+ readonly lifecycle: "immediate" | "recoverable";
+ readonly lane: string;
+ readonly maxConcurrency: number;
+};
+
+export type ResolvedRuntimeInstance = ResolvedRuntimeService | ResolvedRuntimeProvider;
+
+export type RuntimeClosure = {
+ readonly format: "svml.runtime-closure@1";
+ readonly digest: Digest;
+ readonly profile: Digest;
+ readonly modules: readonly { readonly module: ModuleRef; readonly digest: Digest }[];
+ readonly instances: readonly ResolvedRuntimeInstance[];
+ readonly scheduler: string;
+ readonly stores: RuntimeProfile["stores"];
+ readonly providers: readonly RuntimeProviderBinding[];
+ readonly scheduling: RuntimeProfile["scheduling"];
+};
+
+type RegisteredRuntimeModule = {
+ readonly manifest: RuntimeModuleManifest;
+ readonly digest: Digest;
+};
+
+export type ResolveRuntimeProfileOptions = {
+ readonly allowedPermissions?: readonly string[];
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+function positiveInteger(value: number, subject: string): number {
+ assert(Number.isSafeInteger(value) && value > 0, `${subject} must be a positive safe integer`);
+ return value;
+}
+
+function moduleKey(module: ModuleRef): string {
+ return `${module.name}@${module.version}`;
+}
+
+function facetKey(ref: RuntimeFacetRef): string {
+ return `${moduleKey(ref.module)}#${ref.name}`;
+}
+
+function capabilityKey(capability: CapabilityRef): string {
+ return `${moduleKey(capability.module)}#${capability.name}`;
+}
+
+function typeKey(type: TypeRef): string {
+ return `${moduleKey(type.module)}#${type.name}`;
+}
+
+function bindingKey(binding: RuntimeCapability): string {
+ return `${capabilityKey(binding.capability)} -> ${typeKey(binding.returns)}`;
+}
+
+function sameModule(left: ModuleRef, right: ModuleRef): boolean {
+ return left.name === right.name && left.version === right.version;
+}
+
+function sameCapability(left: RuntimeCapability, right: RuntimeCapability): boolean {
+ return capabilityKey(left.capability) === capabilityKey(right.capability)
+ && typeKey(left.returns) === typeKey(right.returns);
+}
+
+function sortedUniqueStrings(values: readonly string[], subject: string): readonly string[] {
+ const sorted = [...values].map((value) => {
+ assert(value.trim().length > 0, `${subject} contains an empty value`);
+ return value;
+ }).sort();
+ assert(new Set(sorted).size === sorted.length, `${subject} contains a duplicate value`);
+ return sorted;
+}
+
+function normalizeImplementation(value: RuntimeImplementation, subject: string): RuntimeImplementation {
+ assert(value.locator.trim().length > 0, `${subject} implementation locator is empty`);
+ assert(isDigest(value.digest), `${subject} implementation digest is invalid`);
+ return { locator: value.locator, digest: value.digest };
+}
+
+function normalizeCapability(value: RuntimeCapability): RuntimeCapability {
+ assert(value.capability.module.name.length > 0 && value.capability.module.version.length > 0, "runtime capability module is invalid");
+ assert(value.capability.name.length > 0, "runtime capability name is empty");
+ assert(value.returns.module.name.length > 0 && value.returns.module.version.length > 0, "runtime return type module is invalid");
+ assert(value.returns.name.length > 0, "runtime return type name is empty");
+ return {
+ capability: {
+ module: { ...value.capability.module },
+ name: value.capability.name,
+ },
+ returns: {
+ module: { ...value.returns.module },
+ name: value.returns.name,
+ },
+ };
+}
+
+function normalizeFacet(facet: RuntimeFacet): RuntimeFacet {
+ assert(facet.name.trim().length > 0, "runtime facet name is empty");
+ const common = {
+ name: facet.name,
+ implementation: normalizeImplementation(facet.implementation, facet.name),
+ permissions: sortedUniqueStrings(facet.permissions, `${facet.name} permissions`),
+ };
+ if (facet.role !== "provider-endpoint") return { ...common, role: facet.role };
+ const fulfills = facet.fulfills.map(normalizeCapability)
+ .sort((left, right) => bindingKey(left).localeCompare(bindingKey(right)));
+ assert(fulfills.length > 0, `${facet.name} must fulfill at least one exact capability`);
+ assert(new Set(fulfills.map(bindingKey)).size === fulfills.length, `${facet.name} repeats a capability binding`);
+ assert(facet.lifecycle === "immediate" || facet.lifecycle === "recoverable", `${facet.name} lifecycle is invalid`);
+ return {
+ ...common,
+ role: "provider-endpoint",
+ fulfills,
+ lifecycle: facet.lifecycle,
+ defaultConcurrency: positiveInteger(facet.defaultConcurrency, `${facet.name} defaultConcurrency`),
+ };
+}
+
+function normalizeManifest(manifest: RuntimeModuleManifest): RuntimeModuleManifest {
+ assert(manifest.format === "svml.runtime-module@1", "unsupported Runtime Module Manifest format");
+ assert(manifest.name.trim().length > 0 && manifest.version.trim().length > 0, "runtime module identity is invalid");
+ const facets = manifest.facets.map(normalizeFacet).sort((left, right) => left.name.localeCompare(right.name));
+ assert(new Set(facets.map((facet) => facet.name)).size === facets.length, `${manifest.name} repeats a Runtime facet`);
+ return {
+ format: "svml.runtime-module@1",
+ name: manifest.name,
+ version: manifest.version,
+ facets,
+ };
+}
+
+export class RuntimeModuleRegistry {
+ readonly #modules = new Map<string, RegisteredRuntimeModule>();
+
+ register(manifest: RuntimeModuleManifest): Digest {
+ const normalized = normalizeManifest(manifest);
+ const key = moduleKey(normalized);
+ assert(!this.#modules.has(key), `runtime module ${key} is already registered`);
+ const registered = { manifest: normalized, digest: digestOf(normalized) };
+ this.#modules.set(key, registered);
+ return registered.digest;
+ }
+
+ resolve(ref: RuntimeFacetRef): { readonly module: RegisteredRuntimeModule; readonly facet: RuntimeFacet } | undefined {
+ const registered = this.#modules.get(moduleKey(ref.module));
+ const facet = registered?.manifest.facets.find((candidate) => candidate.name === ref.name);
+ return registered === undefined || facet === undefined ? undefined : { module: registered, facet };
+ }
+
+ verifyClosure(closure: RuntimeClosure, options: ResolveRuntimeProfileOptions = {}): void {
+ verifyRuntimeClosure(closure);
+ const allowed = new Set(options.allowedPermissions ?? []);
+ const modules = new Map(closure.modules.map((item) => [moduleKey(item.module), item]));
+ for (const instance of closure.instances) {
+ const resolved = this.resolve(instance.facet);
+ assert(resolved !== undefined, `Runtime facet ${facetKey(instance.facet)} is not registered`);
+ assert(modules.get(moduleKey(instance.facet.module))?.digest === resolved.module.digest,
+ `${moduleKey(instance.facet.module)} Manifest digest does not match the Runtime Closure`);
+ assert(instance.role === resolved.facet.role, `${instance.id} Runtime facet role differs`);
+ assert(instance.implementation.locator === resolved.facet.implementation.locator
+ && instance.implementation.digest === resolved.facet.implementation.digest,
+ `${instance.id} Runtime implementation differs`);
+ assert(JSON.stringify(instance.permissions) === JSON.stringify(resolved.facet.permissions),
+ `${instance.id} Runtime permissions differ`);
+ for (const permission of instance.permissions) {
+ assert(allowed.has(permission), `${instance.id} requires disallowed Runtime permission ${permission}`);
+ }
+ if (instance.role === "provider-endpoint" && resolved.facet.role === "provider-endpoint") {
+ assert(instance.lifecycle === resolved.facet.lifecycle, `${instance.id} Provider lifecycle differs`);
+ assert(JSON.stringify(instance.fulfills.map(bindingKey))
+ === JSON.stringify(resolved.facet.fulfills.map(bindingKey)), `${instance.id} Provider capabilities differ`);
+ const override = closure.scheduling.lanes.find((lane) => lane.name === instance.lane)?.maxConcurrency;
+ assert(instance.maxConcurrency === (override ?? resolved.facet.defaultConcurrency),
+ `${instance.id} Provider concurrency differs`);
+ }
+ }
+ }
+}
+
+function profileContent(profile: RuntimeProfile): Omit<RuntimeProfile, "digest"> {
+ return {
+ format: "svml.runtime-profile@1",
+ name: profile.name,
+ instances: [...profile.instances]
+ .map((instance) => ({
+ id: instance.id,
+ facet: { module: { ...instance.facet.module }, name: instance.facet.name },
+ ...(instance.lane === undefined ? {} : { lane: instance.lane }),
+ }))
+ .sort((left, right) => left.id.localeCompare(right.id)),
+ scheduler: profile.scheduler,
+ stores: {
+ ...(profile.stores.build === undefined ? {} : { build: profile.stores.build }),
+ ...(profile.stores.operations === undefined ? {} : { operations: profile.stores.operations }),
+ ...(profile.stores.artifacts === undefined ? {} : { artifacts: profile.stores.artifacts }),
+ },
+ providers: [...profile.providers]
+ .map((binding) => ({ ...normalizeCapability(binding), endpoint: binding.endpoint }))
+ .sort((left, right) => bindingKey(left).localeCompare(bindingKey(right))),
+ scheduling: {
+ maxConcurrency: profile.scheduling.maxConcurrency,
+ lanes: [...profile.scheduling.lanes]
+ .map((lane) => ({ name: lane.name, maxConcurrency: lane.maxConcurrency }))
+ .sort((left, right) => left.name.localeCompare(right.name)),
+ },
+ };
+}
+
+function verifyProfileShape(profile: RuntimeProfile): void {
+ assert(profile.format === "svml.runtime-profile@1", "unsupported Runtime Profile format");
+ assert(profile.name.trim().length > 0, "Runtime Profile name is empty");
+ assert(profile.scheduler.trim().length > 0, "Runtime Profile scheduler is empty");
+ positiveInteger(profile.scheduling.maxConcurrency, "Runtime Profile maxConcurrency");
+ const ids = profile.instances.map((instance) => {
+ assert(instance.id.trim().length > 0, "Runtime Profile instance id is empty");
+ assert(instance.facet.name.trim().length > 0, `${instance.id} facet name is empty`);
+ assert(instance.facet.module.name.length > 0 && instance.facet.module.version.length > 0, `${instance.id} facet module is invalid`);
+ if (instance.lane !== undefined) assert(instance.lane.trim().length > 0, `${instance.id} lane is empty`);
+ return instance.id;
+ });
+ assert(new Set(ids).size === ids.length, "Runtime Profile repeats an instance id");
+ const bindings = profile.providers.map((binding) => {
+ assert(binding.endpoint.trim().length > 0, "Runtime Provider binding endpoint is empty");
+ return bindingKey(normalizeCapability(binding));
+ });
+ assert(new Set(bindings).size === bindings.length, "Runtime Profile repeats a Provider binding");
+ const laneNames = profile.scheduling.lanes.map((lane) => {
+ assert(lane.name.trim().length > 0, "Runtime Profile lane name is empty");
+ positiveInteger(lane.maxConcurrency, `Runtime lane ${lane.name}`);
+ return lane.name;
+ });
+ assert(new Set(laneNames).size === laneNames.length, "Runtime Profile repeats a lane override");
+}
+
+export function sealRuntimeProfile(
+ value: Omit<RuntimeProfile, "format" | "digest">,
+): RuntimeProfile {
+ const draft: RuntimeProfile = {
+ format: "svml.runtime-profile@1",
+ digest: digestOf("unsealed-runtime-profile"),
+ ...value,
+ };
+ verifyProfileShape(draft);
+ const content = profileContent(draft);
+ return { ...content, digest: digestOf(content) };
+}
+
+export function verifyRuntimeProfile(profile: RuntimeProfile): void {
+ verifyProfileShape(profile);
+ assert(isDigest(profile.digest) && profile.digest === digestOf(profileContent(profile)), "Runtime Profile digest differs");
+}
+
+function closureContent(closure: RuntimeClosure): Omit<RuntimeClosure, "digest"> {
+ return {
+ format: "svml.runtime-closure@1",
+ profile: closure.profile,
+ modules: [...closure.modules].map((item) => ({ module: { ...item.module }, digest: item.digest }))
+ .sort((left, right) => moduleKey(left.module).localeCompare(moduleKey(right.module))),
+ instances: [...closure.instances].map((instance) => structuredClone(instance))
+ .sort((left, right) => left.id.localeCompare(right.id)),
+ scheduler: closure.scheduler,
+ stores: { ...closure.stores },
+ providers: [...closure.providers].map((binding) => structuredClone(binding))
+ .sort((left, right) => bindingKey(left).localeCompare(bindingKey(right))),
+ scheduling: {
+ maxConcurrency: closure.scheduling.maxConcurrency,
+ lanes: [...closure.scheduling.lanes].map((lane) => ({ ...lane })).sort((left, right) => left.name.localeCompare(right.name)),
+ },
+ };
+}
+
+export function verifyRuntimeClosure(closure: RuntimeClosure): void {
+ assert(closure.format === "svml.runtime-closure@1", "unsupported Runtime Closure format");
+ assert(isDigest(closure.profile), "Runtime Closure profile digest is invalid");
+ assert(isDigest(closure.digest) && closure.digest === digestOf(closureContent(closure)), "Runtime Closure digest differs");
+ positiveInteger(closure.scheduling.maxConcurrency, "Runtime Closure maxConcurrency");
+ const moduleKeys = closure.modules.map((item) => {
+ assert(item.module.name.length > 0 && item.module.version.length > 0, "Runtime Closure module identity is invalid");
+ assert(isDigest(item.digest), `${moduleKey(item.module)} Runtime Manifest digest is invalid`);
+ return moduleKey(item.module);
+ });
+ assert(new Set(moduleKeys).size === moduleKeys.length, "Runtime Closure repeats a module");
+ const laneNames = closure.scheduling.lanes.map((lane) => {
+ assert(lane.name.trim().length > 0, "Runtime Closure lane is empty");
+ positiveInteger(lane.maxConcurrency, `Runtime Closure lane ${lane.name}`);
+ return lane.name;
+ });
+ assert(new Set(laneNames).size === laneNames.length, "Runtime Closure repeats a lane override");
+ const instances = new Map<string, ResolvedRuntimeInstance>();
+ for (const instance of closure.instances) {
+ assert(!instances.has(instance.id), `Runtime Closure repeats instance ${instance.id}`);
+ assert(isDigest(instance.implementation.digest), `${instance.id} implementation digest is invalid`);
+ assert(moduleKeys.includes(moduleKey(instance.facet.module)), `${instance.id} refers to an unlocked Runtime module`);
+ sortedUniqueStrings(instance.permissions, `${instance.id} permissions`);
+ if (instance.role === "provider-endpoint") {
+ assert(instance.lane.trim().length > 0, `${instance.id} Provider lane is empty`);
+ positiveInteger(instance.maxConcurrency, `${instance.id} Provider maxConcurrency`);
+ assert(instance.fulfills.length > 0, `${instance.id} Provider fulfills nothing`);
+ assert(new Set(instance.fulfills.map(bindingKey)).size === instance.fulfills.length,
+ `${instance.id} Provider repeats a capability`);
+ }
+ instances.set(instance.id, instance);
+ }
+ const schedulers = closure.instances.filter((instance) => instance.role === "scheduler");
+ assert(schedulers.length === 1 && schedulers[0]?.id === closure.scheduler, "Runtime Closure must select exactly one scheduler");
+ const roles = {
+ build: "build-store",
+ operations: "operation-store",
+ artifacts: "artifact-store",
+ } as const;
+ for (const [name, role] of Object.entries(roles) as [keyof typeof roles, typeof roles[keyof typeof roles]][]) {
+ const id = closure.stores[name];
+ if (id !== undefined) assert(instances.get(id)?.role === role, `Runtime Closure ${name} store has the wrong role`);
+ }
+ for (const binding of closure.providers) {
+ const endpoint = instances.get(binding.endpoint);
+ assert(endpoint?.role === "provider-endpoint", `${binding.endpoint} is not a Provider Endpoint`);
+ assert(endpoint.fulfills.some((item) => sameCapability(item, binding)), `${binding.endpoint} does not fulfill ${bindingKey(binding)}`);
+ }
+ assert(new Set(closure.providers.map(bindingKey)).size === closure.providers.length,
+ "Runtime Closure repeats a Provider binding");
+ if (closure.instances.some((instance) => instance.role === "provider-endpoint" && instance.lifecycle === "recoverable")) {
+ assert(closure.stores.operations !== undefined, "recoverable Provider Endpoints require an OperationStore");
+ }
+}
+
+export function resolveRuntimeProfile(
+ registry: RuntimeModuleRegistry,
+ profile: RuntimeProfile,
+ options: ResolveRuntimeProfileOptions = {},
+): RuntimeClosure {
+ verifyRuntimeProfile(profile);
+ const allowed = new Set(options.allowedPermissions ?? []);
+ const modules = new Map<string, { readonly module: ModuleRef; readonly digest: Digest }>();
+ const instances = profile.instances.map((instance): ResolvedRuntimeInstance => {
+ const resolved = registry.resolve(instance.facet);
+ assert(resolved !== undefined, `Runtime facet ${facetKey(instance.facet)} is not registered`);
+ for (const permission of resolved.facet.permissions) {
+ assert(allowed.has(permission), `${instance.id} requires disallowed Runtime permission ${permission}`);
+ }
+ modules.set(moduleKey(instance.facet.module), { module: { ...instance.facet.module }, digest: resolved.module.digest });
+ const common = {
+ id: instance.id,
+ facet: { module: { ...instance.facet.module }, name: instance.facet.name },
+ implementation: { ...resolved.facet.implementation },
+ permissions: [...resolved.facet.permissions],
+ };
+ if (resolved.facet.role !== "provider-endpoint") return { ...common, role: resolved.facet.role };
+ const lane = instance.lane ?? `provider:${instance.id}`;
+ const override = profile.scheduling.lanes.find((candidate) => candidate.name === lane)?.maxConcurrency;
+ return {
+ ...common,
+ role: "provider-endpoint",
+ fulfills: resolved.facet.fulfills.map((item) => structuredClone(item)),
+ lifecycle: resolved.facet.lifecycle,
+ lane,
+ maxConcurrency: override ?? resolved.facet.defaultConcurrency,
+ };
+ });
+ const byId = new Map(instances.map((instance) => [instance.id, instance]));
+ const schedulers = instances.filter((instance) => instance.role === "scheduler");
+ assert(schedulers.length === 1, "Runtime Profile must activate exactly one scheduler instance");
+ assert(schedulers[0]?.id === profile.scheduler, `Runtime Profile selects unknown scheduler ${profile.scheduler}`);
+ const storeRoles = {
+ build: "build-store",
+ operations: "operation-store",
+ artifacts: "artifact-store",
+ } as const;
+ for (const [name, role] of Object.entries(storeRoles) as [keyof typeof storeRoles, typeof storeRoles[keyof typeof storeRoles]][]) {
+ const id = profile.stores[name];
+ if (id !== undefined) assert(byId.get(id)?.role === role, `Runtime Profile ${name} store ${id} has the wrong role`);
+ }
+ for (const binding of profile.providers) {
+ const endpoint = byId.get(binding.endpoint);
+ assert(endpoint?.role === "provider-endpoint", `${binding.endpoint} is not an active Provider Endpoint`);
+ assert(endpoint.fulfills.some((item) => sameCapability(item, binding)), `${binding.endpoint} does not fulfill ${bindingKey(binding)}`);
+ }
+ if (instances.some((instance) => instance.role === "provider-endpoint" && instance.lifecycle === "recoverable")) {
+ assert(profile.stores.operations !== undefined, "recoverable Provider Endpoints require an OperationStore");
+ }
+ const draft: RuntimeClosure = {
+ format: "svml.runtime-closure@1",
+ digest: digestOf("unsealed-runtime-closure"),
+ profile: profile.digest,
+ modules: [...modules.values()],
+ instances,
+ scheduler: profile.scheduler,
+ stores: { ...profile.stores },
+ providers: profile.providers.map((binding) => structuredClone(binding)),
+ scheduling: structuredClone(profile.scheduling),
+ };
+ const content = closureContent(draft);
+ const closure = { ...content, digest: digestOf(content) };
+ verifyRuntimeClosure(closure);
+ return closure;
+}
+
+export function runtimeProvider(
+ closure: RuntimeClosure,
+ id: string,
+): ResolvedRuntimeProvider | undefined {
+ verifyRuntimeClosure(closure);
+ const instance = closure.instances.find((candidate) => candidate.id === id);
+ return instance?.role === "provider-endpoint" ? instance : undefined;
+}
+
+/** Fail before execution if the selected finite BuildPlan has an unbound external requirement. */
+export function verifyRuntimeCoverage(closure: RuntimeClosure, state: BuildState): void {
+ verifyRuntimeClosure(closure);
+ const required = new Map<string, RuntimeCapability>();
+ for (const step of state.plan.steps) {
+ const producer = resolveProducer(state.program.closure, step.producer);
+ for (const need of producer.needs) {
+ const requirement = { capability: need.capability, returns: need.returns };
+ required.set(bindingKey(requirement), requirement);
+ }
+ }
+ for (const requirement of required.values()) {
+ assert(
+ closure.providers.some((binding) => sameCapability(binding, requirement)),
+ `Runtime Closure does not bind demanded capability ${bindingKey(requirement)}`,
+ );
+ }
+}
+
+export function localSchedulerOptionsFromClosure(closure: RuntimeClosure): {
+ readonly maxConcurrency: number;
+ readonly laneLimits: Readonly<Record<string, number>>;
+ readonly runtimeClosure: RuntimeClosure;
+} {
+ verifyRuntimeClosure(closure);
+ return {
+ maxConcurrency: closure.scheduling.maxConcurrency,
+ laneLimits: Object.fromEntries(closure.scheduling.lanes.map((lane) => [lane.name, lane.maxConcurrency])),
+ runtimeClosure: structuredClone(closure),
+ };
+}
diff --git a/packages/runtime/src/scheduler.ts b/packages/runtime/src/scheduler.ts
new file mode 100644
index 00000000..9fe963fb
--- /dev/null
+++ b/packages/runtime/src/scheduler.ts
@@ -0,0 +1,234 @@
+import { reduce } from "@svml/core";
+import type { BuildState } from "@svml/protocol";
+import { verifyRuntimeClosure, verifyRuntimeCoverage } from "./profile.js";
+import type { RuntimeClosure } from "./profile.js";
+
+import type {
+ LocalBuildSchedulerOptions,
+ RuntimeCommandExecutor,
+ RuntimeExecutionResult,
+ RuntimeRunnableCommand,
+ ScheduledBuild,
+ ScheduledBuildResult,
+ SchedulerJournalEntry,
+} from "./types.js";
+
+type MutableBuild = {
+ readonly id: string;
+ state: BuildState;
+ readonly journal: SchedulerJournalEntry[];
+ blocked: ScheduledBuildResult["blocked"];
+ stopped: boolean;
+ completedEvents: number;
+};
+
+type ActiveResult = {
+ readonly key: string;
+ readonly build: MutableBuild;
+ readonly command: RuntimeRunnableCommand;
+ readonly execution?: RuntimeExecutionResult;
+ readonly error?: unknown;
+};
+
+type ActiveCommand = {
+ readonly build: MutableBuild;
+ readonly command: RuntimeRunnableCommand;
+ readonly promise: Promise<ActiveResult>;
+};
+
+function positiveInteger(value: number, name: string): number {
+ if (!Number.isSafeInteger(value) || value < 1) throw new Error(`${name} must be a positive safe integer`);
+ return value;
+}
+
+function buildCommandKey(build: string, command: string): string {
+ return `${build}\u0000${command}`;
+}
+
+/**
+ * Queue-free, one-process reference Scheduler. It shares lane limits across all submitted Builds,
+ * but never searches a Graph: every runnable command is regenerated by Core through the Executor.
+ */
+export class LocalBuildScheduler {
+ readonly #executor: RuntimeCommandExecutor;
+ readonly #maxConcurrency: number;
+ readonly #laneLimits: Readonly<Record<string, number>>;
+ readonly #maxEventsPerBuild: number;
+ readonly #runtimeClosure: RuntimeClosure | undefined;
+
+ constructor(executor: RuntimeCommandExecutor, options: LocalBuildSchedulerOptions = {}) {
+ this.#executor = executor;
+ this.#maxConcurrency = positiveInteger(options.maxConcurrency ?? 4, "maxConcurrency");
+ this.#maxEventsPerBuild = positiveInteger(options.maxEventsPerBuild ?? 1_000, "maxEventsPerBuild");
+ this.#runtimeClosure = options.runtimeClosure === undefined
+ ? undefined
+ : structuredClone(options.runtimeClosure);
+ if (this.#runtimeClosure !== undefined) verifyRuntimeClosure(this.#runtimeClosure);
+ for (const [lane, limit] of Object.entries(options.laneLimits ?? {})) {
+ if (lane.trim().length === 0) throw new Error("lane override name must not be empty");
+ positiveInteger(limit, `lane ${lane}`);
+ }
+ this.#laneLimits = { ...(options.laneLimits ?? {}) };
+ }
+
+ async run(requests: readonly ScheduledBuild[]): Promise<readonly ScheduledBuildResult[]> {
+ const ids = new Set<string>();
+ const builds: MutableBuild[] = requests.map((request) => {
+ if (request.id.trim().length === 0) throw new Error("scheduled build id must not be empty");
+ if (ids.has(request.id)) throw new Error(`scheduled build ${request.id} is duplicated`);
+ ids.add(request.id);
+ if (this.#runtimeClosure !== undefined) verifyRuntimeCoverage(this.#runtimeClosure, request.state);
+ return {
+ id: request.id,
+ state: structuredClone(request.state),
+ journal: [],
+ blocked: [],
+ stopped: false,
+ completedEvents: 0,
+ };
+ });
+ const active = new Map<string, ActiveCommand>();
+ const laneDefaults = new Map<string, number>();
+ let cursor = 0;
+
+ const laneLimit = (command: RuntimeRunnableCommand): number => {
+ const override = this.#laneLimits[command.lane];
+ if (override !== undefined) return override;
+ const proposed = positiveInteger(command.maxConcurrency, `lane ${command.lane} default`);
+ const previous = laneDefaults.get(command.lane);
+ if (previous !== undefined && previous !== proposed) {
+ throw new Error(`lane ${command.lane} has conflicting default concurrency ${previous} and ${proposed}`);
+ }
+ laneDefaults.set(command.lane, proposed);
+ return proposed;
+ };
+
+ const preparations = (): Map<string, readonly RuntimeRunnableCommand[]> => {
+ const ready = new Map<string, readonly RuntimeRunnableCommand[]>();
+ for (const build of builds) {
+ if (build.stopped || build.state.status === "complete" || build.state.status === "failed") {
+ ready.set(build.id, []);
+ continue;
+ }
+ const prepared = this.#executor.prepare(build.state);
+ build.state = prepared.state;
+ build.blocked = prepared.blocked;
+ ready.set(build.id, prepared.runnable.filter((item) =>
+ !active.has(buildCommandKey(build.id, item.command.id))));
+ }
+ return ready;
+ };
+
+ const laneCounts = (): Map<string, number> => {
+ const counts = new Map<string, number>();
+ for (const item of active.values()) counts.set(item.command.lane, (counts.get(item.command.lane) ?? 0) + 1);
+ return counts;
+ };
+
+ const launch = (build: MutableBuild, command: RuntimeRunnableCommand): void => {
+ const key = buildCommandKey(build.id, command.command.id);
+ const startedFrom = build.state;
+ const promise = this.#executor.executeCommand(startedFrom, command.command.id, { build: build.id }).then(
+ (execution) => ({ key, build, command, execution }),
+ (error: unknown) => ({ key, build, command, error }),
+ );
+ active.set(key, { build, command, promise });
+ };
+
+ while (true) {
+ const ready = preparations();
+ const counts = laneCounts();
+ let slots = this.#maxConcurrency - active.size;
+
+ while (slots > 0 && builds.length > 0) {
+ let selected = false;
+ for (let offset = 0; offset < builds.length; offset += 1) {
+ const index = (cursor + offset) % builds.length;
+ const build = builds[index]!;
+ const command = (ready.get(build.id) ?? []).find((candidate) =>
+ (counts.get(candidate.lane) ?? 0) < laneLimit(candidate));
+ if (command === undefined) continue;
+ ready.set(build.id, (ready.get(build.id) ?? []).filter((item) =>
+ item.command.id !== command.command.id));
+ launch(build, command);
+ counts.set(command.lane, (counts.get(command.lane) ?? 0) + 1);
+ cursor = (index + 1) % builds.length;
+ slots -= 1;
+ selected = true;
+ break;
+ }
+ if (!selected) break;
+ }
+
+ if (active.size === 0) break;
+ const settled = await Promise.race([...active.values()].map((item) => item.promise));
+ active.delete(settled.key);
+ const build = settled.build;
+ if (settled.execution === undefined) {
+ build.stopped = true;
+ build.journal.push({
+ command: settled.command.command.id,
+ kind: settled.command.command.kind,
+ lane: settled.command.lane,
+ status: "error",
+ message: settled.error instanceof Error ? settled.error.message : String(settled.error),
+ });
+ continue;
+ }
+ if (settled.execution.status === "pending") {
+ build.stopped = true;
+ build.journal.push({
+ command: settled.command.command.id,
+ kind: settled.command.command.kind,
+ lane: settled.command.lane,
+ status: "pending",
+ operation: settled.execution.operation,
+ });
+ continue;
+ }
+ const event = settled.execution.event;
+ try {
+ build.state = reduce(build.state, event).state;
+ build.completedEvents += 1;
+ build.journal.push({
+ command: settled.command.command.id,
+ kind: settled.command.command.kind,
+ lane: settled.command.lane,
+ status: "completed",
+ event: event.id,
+ });
+ if (build.completedEvents >= this.#maxEventsPerBuild
+ && build.state.status !== "complete"
+ && build.state.status !== "failed") {
+ build.stopped = true;
+ build.journal.push({
+ command: settled.command.command.id,
+ kind: settled.command.command.kind,
+ lane: settled.command.lane,
+ status: "error",
+ message: `Build exceeded ${this.#maxEventsPerBuild} accepted events`,
+ });
+ }
+ } catch (error) {
+ build.stopped = true;
+ build.journal.push({
+ command: settled.command.command.id,
+ kind: settled.command.command.kind,
+ lane: settled.command.lane,
+ status: "error",
+ message: error instanceof Error ? error.message : String(error),
+ });
+ }
+ }
+
+ return builds.map((build) => ({
+ id: build.id,
+ status: build.state.status === "complete"
+ ? "complete"
+ : build.state.status === "failed" ? "failed" : "paused",
+ state: build.state,
+ journal: [...build.journal],
+ blocked: [...build.blocked],
+ }));
+ }
+}
diff --git a/packages/runtime/src/types.ts b/packages/runtime/src/types.ts
new file mode 100644
index 00000000..462c9173
--- /dev/null
+++ b/packages/runtime/src/types.ts
@@ -0,0 +1,96 @@
+import type {
+ BuildEvent,
+ BuildState,
+ CoreCommand,
+ Digest,
+} from "@svml/protocol";
+import type { RuntimeClosure } from "./profile.js";
+
+export type RuntimeBlockedCommand = {
+ readonly command: string;
+ readonly reason: string;
+ readonly subject: string;
+};
+
+export type RuntimeRunnableCommand = {
+ readonly command: CoreCommand;
+ /** One authority-wide concurrency bucket, normally an Endpoint instance or local implementation. */
+ readonly lane: string;
+ /** Registration default; a Runtime Profile may explicitly override it for this Scheduler. */
+ readonly maxConcurrency: number;
+};
+
+export type RuntimePreparation = {
+ readonly state: BuildState;
+ readonly runnable: readonly RuntimeRunnableCommand[];
+ readonly blocked: readonly RuntimeBlockedCommand[];
+};
+
+export type RuntimeExecutionContext = {
+ /** Stable Run-local identity; two identical BuildRequests may still be distinct Builds. */
+ readonly build: string;
+};
+
+export type RuntimeExecutionResult =
+ | { readonly status: "completed"; readonly event: BuildEvent }
+ | { readonly status: "pending"; readonly operation: Digest };
+
+/**
+ * Minimal execution port used by a Scheduler. Implementations must regenerate the command from
+ * trusted BuildState before causing side effects; the caller supplies only its identity.
+ */
+export type RuntimeCommandExecutor = {
+ prepare(state: BuildState): RuntimePreparation;
+ executeCommand(
+ state: BuildState,
+ commandId: string,
+ context: RuntimeExecutionContext,
+ ): Promise<RuntimeExecutionResult>;
+};
+
+export type BuildSnapshot = {
+ readonly build: string;
+ readonly revision: number;
+ readonly state: BuildState;
+};
+
+export type BuildStoreWrite =
+ | { readonly status: "stored"; readonly snapshot: BuildSnapshot }
+ | { readonly status: "conflict"; readonly current: BuildSnapshot };
+
+/** Stores only verified Core state; execution attempts and checkpoints belong to OperationStore. */
+export type BuildStore = {
+ create(build: string, state: BuildState): Promise<BuildSnapshot>;
+ read(build: string): Promise<BuildSnapshot | undefined>;
+ compareAndSwap(build: string, expectedRevision: number, state: BuildState): Promise<BuildStoreWrite>;
+};
+
+export type ScheduledBuild = {
+ readonly id: string;
+ readonly state: BuildState;
+};
+
+export type SchedulerJournalEntry = {
+ readonly command: string;
+ readonly kind: CoreCommand["kind"];
+ readonly lane: string;
+ readonly status: "completed" | "pending" | "error";
+ readonly event?: string;
+ readonly operation?: Digest;
+ readonly message?: string;
+};
+
+export type ScheduledBuildResult = {
+ readonly id: string;
+ readonly status: "complete" | "paused" | "failed";
+ readonly state: BuildState;
+ readonly journal: readonly SchedulerJournalEntry[];
+ readonly blocked: readonly RuntimeBlockedCommand[];
+};
+
+export type LocalBuildSchedulerOptions = {
+ readonly maxConcurrency?: number;
+ readonly laneLimits?: Readonly<Record<string, number>>;
+ readonly maxEventsPerBuild?: number;
+ readonly runtimeClosure?: RuntimeClosure;
+};
diff --git a/packages/runtime/test/operations.test.ts b/packages/runtime/test/operations.test.ts
new file mode 100644
index 00000000..a71ff35a
--- /dev/null
+++ b/packages/runtime/test/operations.test.ts
@@ -0,0 +1,92 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { digestOf } from "@svml/core";
+import {
+ MemoryOperationStore,
+ sealOperationIdentity,
+ verifyOperationSnapshot,
+} from "@svml/runtime";
+
+function identity(overrides: { readonly endpoint?: string; readonly runtimeClosure?: string } = {}) {
+ return sealOperationIdentity({
+ build: "video-42",
+ command: "command:render",
+ endpoint: overrides.endpoint ?? "hyperframes.local",
+ implementationDigest: digestOf("hyperframes.local/implementation@1"),
+ runtimeClosure: (overrides.runtimeClosure ?? digestOf("runtime-closure:local")) as never,
+ requestDigest: digestOf("render-request"),
+ attempt: 1,
+ });
+}
+
+test("Operation identity locks Build, Command, Endpoint, implementation and Runtime Closure", () => {
+ const first = identity();
+ assert.equal(first.id, identity().id);
+ assert.equal(first.submissionKey, identity().submissionKey);
+ assert.notEqual(first.id, identity({ endpoint: "hyperframes.hypit" }).id);
+ assert.notEqual(first.id, identity({ runtimeClosure: digestOf("runtime-closure:hosted") }).id);
+});
+
+test("OperationStore idempotently discovers an existing submission after restart", async () => {
+ const store = new MemoryOperationStore();
+ const operation = identity();
+ const created = await store.create(operation);
+ const restored = await store.create(operation);
+ assert.equal(created.status, "created");
+ assert.equal(restored.status, "existing");
+ assert.equal(restored.snapshot.submissionKey, created.snapshot.submissionKey);
+ assert.equal(restored.snapshot.revision, 0);
+});
+
+test("pending checkpoints and completion advance by CAS without entering BuildState", async () => {
+ const store = new MemoryOperationStore();
+ const operation = identity();
+ await store.create(operation);
+ const pending = await store.compareAndSwap(operation.id, 0, {
+ status: "pending",
+ checkpoint: { remoteJob: "job-123", pollAfterMs: 5_000 },
+ });
+ assert.equal(pending.status, "stored");
+ if (pending.status !== "stored") return;
+ assert.equal(pending.snapshot.status, "pending");
+ assert.deepEqual(pending.snapshot.checkpoint, { remoteJob: "job-123", pollAfterMs: 5_000 });
+
+ const stale = await store.compareAndSwap(operation.id, 0, {
+ status: "failed",
+ failure: { code: "STALE", message: "must not win", retryable: true },
+ });
+ assert.equal(stale.status, "conflict");
+ if (stale.status === "conflict") assert.equal(stale.current.revision, 1);
+
+ const completed = await store.compareAndSwap(operation.id, 1, {
+ status: "completed",
+ completion: {
+ value: { kind: "inline", value: { artifact: "video.mp4" } },
+ conformance: "exact",
+ delivery: "executed",
+ metadata: { remoteJob: "job-123" },
+ },
+ });
+ assert.equal(completed.status, "stored");
+ if (completed.status === "stored") {
+ assert.equal(completed.snapshot.status, "completed");
+ assert.doesNotThrow(() => verifyOperationSnapshot(completed.snapshot));
+ }
+ assert.equal((await store.read(operation.id))?.status, "completed");
+ await assert.rejects(
+ store.compareAndSwap(operation.id, 2, {
+ status: "pending",
+ checkpoint: { remoteJob: "job-456" },
+ }),
+ /already terminal/u,
+ );
+});
+
+test("OperationStore returns defensive snapshots", async () => {
+ const store = new MemoryOperationStore();
+ const operation = identity();
+ const created = await store.create(operation);
+ (created.snapshot as { endpoint: string }).endpoint = "tampered";
+ assert.equal((await store.read(operation.id))?.endpoint, "hyperframes.local");
+});
diff --git a/packages/runtime/test/profile.test.ts b/packages/runtime/test/profile.test.ts
new file mode 100644
index 00000000..20b3ec47
--- /dev/null
+++ b/packages/runtime/test/profile.test.ts
@@ -0,0 +1,182 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { digestOf } from "@svml/core";
+import {
+ RuntimeModuleRegistry,
+ localSchedulerOptionsFromClosure,
+ resolveRuntimeProfile,
+ sealRuntimeProfile,
+ verifyRuntimeClosure,
+ verifyRuntimeCoverage,
+} from "@svml/runtime";
+import type { RuntimeModuleManifest } from "@svml/runtime";
+
+import {
+ capabilities,
+ createGreetingBuild,
+ types,
+} from "../../core/test/greeting-fixture.js";
+
+const runtimeModule = { name: "example.runtime-fixture", version: "1" } as const;
+const endpointFacet = { module: runtimeModule, name: "greeting-endpoint" } as const;
+const endpointImplementationDigest = digestOf("example.runtime-fixture/greeting-endpoint@1");
+
+function manifest(permissions: readonly string[] = []): RuntimeModuleManifest {
+ return {
+ format: "svml.runtime-module@1",
+ name: runtimeModule.name,
+ version: runtimeModule.version,
+ facets: [
+ {
+ name: "local-scheduler",
+ role: "scheduler",
+ implementation: {
+ locator: "example.runtime-fixture/local-scheduler",
+ digest: digestOf("example.runtime-fixture/local-scheduler@1"),
+ },
+ permissions: [],
+ },
+ {
+ name: "memory-build-store",
+ role: "build-store",
+ implementation: {
+ locator: "example.runtime-fixture/memory-build-store",
+ digest: digestOf("example.runtime-fixture/memory-build-store@1"),
+ },
+ permissions: [],
+ },
+ {
+ name: "memory-operation-store",
+ role: "operation-store",
+ implementation: {
+ locator: "example.runtime-fixture/memory-operation-store",
+ digest: digestOf("example.runtime-fixture/memory-operation-store@1"),
+ },
+ permissions: [],
+ },
+ {
+ name: endpointFacet.name,
+ role: "provider-endpoint",
+ implementation: {
+ locator: "example.runtime-fixture/greeting-endpoint",
+ digest: endpointImplementationDigest,
+ },
+ permissions,
+ fulfills: [{ capability: capabilities.generation, returns: types.generated }],
+ lifecycle: "recoverable",
+ defaultConcurrency: 1,
+ },
+ ],
+ };
+}
+
+function profile(options: { readonly operations?: boolean; readonly lane?: number } = {}) {
+ return sealRuntimeProfile({
+ name: "fixture.local",
+ instances: [
+ { id: "scheduler.local", facet: { module: runtimeModule, name: "local-scheduler" } },
+ { id: "build.memory", facet: { module: runtimeModule, name: "memory-build-store" } },
+ ...(options.operations === false ? [] : [{
+ id: "operations.memory",
+ facet: { module: runtimeModule, name: "memory-operation-store" },
+ }]),
+ {
+ id: "greeting.local",
+ facet: endpointFacet,
+ lane: "provider:greeting.local",
+ },
+ ],
+ scheduler: "scheduler.local",
+ stores: {
+ build: "build.memory",
+ ...(options.operations === false ? {} : { operations: "operations.memory" }),
+ },
+ providers: [{
+ capability: capabilities.generation,
+ returns: types.generated,
+ endpoint: "greeting.local",
+ }],
+ scheduling: {
+ maxConcurrency: 8,
+ lanes: [{ name: "provider:greeting.local", maxConcurrency: options.lane ?? 2 }],
+ },
+ });
+}
+
+test("Runtime Profile resolves installed static facets into one deterministic locked Closure", () => {
+ const registry = new RuntimeModuleRegistry();
+ const manifestDigest = registry.register(manifest());
+ const first = resolveRuntimeProfile(registry, profile());
+ const second = resolveRuntimeProfile(registry, profile());
+ assert.equal(first.digest, second.digest);
+ assert.equal(first.modules[0]?.digest, manifestDigest);
+ assert.equal(first.instances.filter((instance) => instance.role === "scheduler").length, 1);
+ const endpoint = first.instances.find((instance) => instance.id === "greeting.local");
+ assert.equal(endpoint?.role, "provider-endpoint");
+ if (endpoint?.role === "provider-endpoint") {
+ assert.equal(endpoint.implementation.digest, endpointImplementationDigest);
+ assert.equal(endpoint.lane, "provider:greeting.local");
+ assert.equal(endpoint.maxConcurrency, 2);
+ }
+ assert.deepEqual(localSchedulerOptionsFromClosure(first).laneLimits, {
+ "provider:greeting.local": 2,
+ });
+ assert.doesNotThrow(() => verifyRuntimeCoverage(first, createGreetingBuild()));
+});
+
+test("Profile order is not identity but an execution-policy change is", () => {
+ const registry = new RuntimeModuleRegistry();
+ registry.register(manifest());
+ const normal = profile();
+ const reordered = sealRuntimeProfile({
+ ...normal,
+ instances: [...normal.instances].reverse(),
+ providers: [...normal.providers].reverse(),
+ scheduling: { ...normal.scheduling, lanes: [...normal.scheduling.lanes].reverse() },
+ });
+ assert.equal(normal.digest, reordered.digest);
+ assert.notEqual(
+ resolveRuntimeProfile(registry, normal).digest,
+ resolveRuntimeProfile(registry, profile({ lane: 1 })).digest,
+ );
+});
+
+test("recoverable Endpoints require an OperationStore before any paid execution", () => {
+ const registry = new RuntimeModuleRegistry();
+ registry.register(manifest());
+ assert.throws(
+ () => resolveRuntimeProfile(registry, profile({ operations: false })),
+ /require an OperationStore/u,
+ );
+});
+
+test("Runtime permissions require an explicit Host allowlist", () => {
+ const registry = new RuntimeModuleRegistry();
+ registry.register(manifest(["network", "credentials:greeting"]));
+ assert.throws(() => resolveRuntimeProfile(registry, profile()), /disallowed Runtime permission/u);
+ assert.doesNotThrow(() => resolveRuntimeProfile(registry, profile(), {
+ allowedPermissions: ["credentials:greeting", "network"],
+ }));
+});
+
+test("Coverage rejects an unbound demanded Need before the Scheduler starts", () => {
+ const registry = new RuntimeModuleRegistry();
+ registry.register(manifest());
+ const configured = profile();
+ const unbound = sealRuntimeProfile({ ...configured, providers: [] });
+ const closure = resolveRuntimeProfile(registry, unbound);
+ assert.throws(
+ () => verifyRuntimeCoverage(closure, createGreetingBuild()),
+ /does not bind demanded capability/u,
+ );
+});
+
+test("Runtime Closure content cannot be changed without invalidating its digest", () => {
+ const registry = new RuntimeModuleRegistry();
+ registry.register(manifest());
+ const closure = resolveRuntimeProfile(registry, profile());
+ const tampered = structuredClone(closure);
+ (tampered.scheduling as { maxConcurrency: number }).maxConcurrency = 999;
+ assert.throws(() => verifyRuntimeClosure(tampered), /digest differs/u);
+});
diff --git a/packages/script/src/manifest.ts b/packages/script/src/manifest.ts
index b0f2d7b5..fc729099 100644
--- a/packages/script/src/manifest.ts
+++ b/packages/script/src/manifest.ts
@@ -1,8 +1,7 @@
import {
contractTypes,
- contractsManifestDigest,
- contractsModuleRef,
narrativeSchema,
+ videoContractDependencies,
} from "@svml/contracts";
import { digestOf } from "@svml/core";
import type { ModuleManifest, TypeRef } from "@svml/protocol";
@@ -17,7 +16,7 @@ export const scriptManifest: ModuleManifest = {
format: "svml.module@0",
name: scriptModuleRef.name,
version: scriptModuleRef.version,
- dependencies: [{ module: contractsModuleRef, digest: contractsManifestDigest }],
+ dependencies: [videoContractDependencies.narrative],
types: [],
capabilities: [],
surfaces: [
diff --git a/packages/script/src/surface.ts b/packages/script/src/surface.ts
index d8af31e2..b4a4e4c2 100644
--- a/packages/script/src/surface.ts
+++ b/packages/script/src/surface.ts
@@ -70,6 +70,8 @@ export function decodeScriptSurface(input: ScriptSurfaceInput): ScriptSurfaceOut
range: { start: input.openingStart, end: close.end },
},
],
+ components: [],
+ fragments: [],
sourceMaps: [canonicalize(narrativeSourceMap(rawId, parsed))],
};
}
diff --git a/packages/script/src/types.ts b/packages/script/src/types.ts
index 0e5cbae6..fad17bfa 100644
--- a/packages/script/src/types.ts
+++ b/packages/script/src/types.ts
@@ -100,5 +100,8 @@ export type ScriptSurfaceInput = {
export type ScriptSurfaceOutput = {
readonly nextOffset: number;
readonly records: readonly ScriptSurfaceRecordDraft[];
+ /** Script is a record-only Surface; it cannot smuggle executable graph declarations. */
+ readonly components: readonly never[];
+ readonly fragments: readonly never[];
readonly sourceMaps: readonly CanonicalValue[];
};
diff --git a/packages/script/test/script.test.ts b/packages/script/test/script.test.ts
index 82d354aa..ad6ad82b 100644
--- a/packages/script/test/script.test.ts
+++ b/packages/script/test/script.test.ts
@@ -1,4 +1,5 @@
import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
import test from "node:test";
import { digestOf } from "@svml/core";
@@ -117,6 +118,27 @@ test("zero-width temporal markers may touch a token edge but cannot split a toke
);
});
+test("the v2 authoring golden fixture reuses the implemented Script Surface unchanged", () => {
+ const source = readFileSync("examples/talking-film-golden/main.svml", "utf8");
+ const body = source.match(/<script>([\s\S]*?)<\/script>/u)?.[1];
+ if (body === undefined) throw new Error("The authoring golden fixture has no Script body.");
+ const parsed = parseScript("examples/talking-film-golden/main.svml", body);
+
+ assert.deepEqual(parsed.segments.map((segment) => segment.id), ["opening", "answer"]);
+ assert.deepEqual(parsed.selections.map((selection) => selection.id), [
+ "alice-shot",
+ "bob-shot",
+ "product-demo",
+ ]);
+ assert.equal(
+ serializeDialogue(parsed),
+ "ALICE: What if a video could be edited by meaning instead of a timeline?\n"
+ + "BOB: Then the script becomes the source. semantic video markup language lets every visual know why it is there.",
+ );
+ assert.match(serializeSpeech(parsed), /semantic video markup language/u);
+ assert.match(serializeCaption(parsed), /SVML/u);
+});
+
test("the formatter is semantic-preserving and idempotent", () => {
const input = "<opening><ALICE>Hello there.<BOB>Good morning.</opening><pause/>";
const once = formatScript("format.svml", input);
diff --git a/packages/speech-align/src/locate.ts b/packages/speech-align/src/locate.ts
index 025387f9..d023263e 100644
--- a/packages/speech-align/src/locate.ts
+++ b/packages/speech-align/src/locate.ts
@@ -504,6 +504,7 @@ export function locateSpeechTiming(
basisDigest: basis.basisDigest,
audioArtifactDigest: basis.audio.digest,
programSpaceDigest: basis.programSpace.digest,
+ programSpace: basis.programSpace,
evidenceDigest: evidence.evidenceDigest,
locatorDigest: speechLocatorDigest,
quantizationPolicy: "nearest-frame" as const,
diff --git a/packages/speech-align/src/manifest.ts b/packages/speech-align/src/manifest.ts
index 5c2cef06..d1006d67 100644
--- a/packages/speech-align/src/manifest.ts
+++ b/packages/speech-align/src/manifest.ts
@@ -1,7 +1,6 @@
import {
contractTypes,
- contractsManifestDigest,
- contractsModuleRef,
+ videoContractDependencies,
} from "@svml/contracts";
import type { ModuleManifest, ProducerRef } from "@svml/protocol";
@@ -16,7 +15,11 @@ export const speechAlignManifest: ModuleManifest = {
format: "svml.module@0",
name: speechAlignModuleRef.name,
version: speechAlignModuleRef.version,
- dependencies: [{ module: contractsModuleRef, digest: contractsManifestDigest }],
+ dependencies: [
+ videoContractDependencies.narrative,
+ videoContractDependencies.speech,
+ videoContractDependencies.semanticTime,
+ ],
types: [],
capabilities: [],
surfaces: [],
diff --git a/packages/video-fragments/README.md b/packages/speech-program/README.md
similarity index 93%
rename from packages/video-fragments/README.md
rename to packages/speech-program/README.md
index 1f955970..c8a802d7 100644
--- a/packages/video-fragments/README.md
+++ b/packages/speech-program/README.md
@@ -1,6 +1,6 @@
-# @svml/video-fragments
+# @svml/speech-program
-Trusted, static Graph Fragments for the first official speech-video path.
+Trusted, static Graph Fragments for the first official speech-video Program.
This package contains no Core behavior, Provider credentials, queues, or API
clients. It only composes ordinary Producers from the leaf packages into
diff --git a/packages/video-fragments/package.json b/packages/speech-program/package.json
similarity index 94%
rename from packages/video-fragments/package.json
rename to packages/speech-program/package.json
index 19533fd5..4f6ef9c8 100644
--- a/packages/video-fragments/package.json
+++ b/packages/speech-program/package.json
@@ -1,5 +1,5 @@
{
- "name": "@svml/video-fragments",
+ "name": "@svml/speech-program",
"version": "0.0.0-dev",
"private": true,
"type": "module",
diff --git a/packages/video-fragments/src/index.ts b/packages/speech-program/src/index.ts
similarity index 54%
rename from packages/video-fragments/src/index.ts
rename to packages/speech-program/src/index.ts
index a9e5cef6..75fb3e00 100644
--- a/packages/video-fragments/src/index.ts
+++ b/packages/speech-program/src/index.ts
@@ -1,4 +1,6 @@
+/** Official reusable speech composition; not a generic Fragment registry. */
export {
+ captionTrackFragment,
captionTimingFragment,
speechTakeProjectionFragment,
whisperXSpeechAlignmentFragment,
diff --git a/packages/video-fragments/src/speech.ts b/packages/speech-program/src/speech.ts
similarity index 64%
rename from packages/video-fragments/src/speech.ts
rename to packages/speech-program/src/speech.ts
index 67a167e2..5ccad068 100644
--- a/packages/video-fragments/src/speech.ts
+++ b/packages/speech-program/src/speech.ts
@@ -1,4 +1,4 @@
-import { captionProducers } from "@svml/caption";
+import { captionProducers, captionTypes } from "@svml/caption";
import { contractTypes } from "@svml/contracts";
import { sealGraphFragment } from "@svml/elaborator";
import { speechAlignProducers } from "@svml/speech-align";
@@ -10,9 +10,15 @@ const operation = (id: string) => ({ kind: "fragment-operation" as const, operat
/** Project one atomic SpeechTake Product without turning its fields into mutable node ports. */
export const speechTakeProjectionFragment = sealGraphFragment({
- name: "@svml/video-fragments/speech-take-projections@1",
+ name: "@svml/speech-program/speech-take-projections@1",
inputs: [{ name: "take", type: contractTypes.speechBasis }],
operations: [
+ {
+ id: "project-program-space",
+ producer: speechTakeProducers.projectProgramSpace,
+ inputs: { basis: input("take") },
+ result: { kind: "output", name: "programSpace" },
+ },
{
id: "project-audio",
producer: speechTakeProducers.projectAudio,
@@ -25,8 +31,22 @@ export const speechTakeProjectionFragment = sealGraphFragment({
inputs: { basis: input("take") },
result: { kind: "output", name: "visual" },
},
+ {
+ id: "project-audio-track",
+ producer: speechTakeProducers.projectAudioTrack,
+ inputs: { basis: input("take") },
+ result: { kind: "output", name: "track" },
+ },
],
exports: [
+ {
+ name: "programSpace",
+ type: contractTypes.programSpace,
+ root: operation("project-program-space"),
+ semanticInputs: ["take"],
+ affinity: [{ resultPointer: "/digest", source: input("take"), sourcePointer: "/programSpace/digest" }],
+ fidelity: "exact",
+ },
{
name: "audio",
type: contractTypes.speechAudioBasis,
@@ -42,13 +62,25 @@ export const speechTakeProjectionFragment = sealGraphFragment({
},
{
name: "visual",
- type: contractTypes.speechVisualTrack,
+ type: contractTypes.visualTrack,
root: operation("project-visual"),
semanticInputs: ["take"],
affinity: [
- { resultPointer: "/basisDigest", source: input("take"), sourcePointer: "/basisDigest" },
- { resultPointer: "/narrativeDigest", source: input("take"), sourcePointer: "/narrativeDigest" },
- { resultPointer: "/programSpace/digest", source: input("take"), sourcePointer: "/programSpace/digest" },
+ { resultPointer: "/sources/0/digest", source: input("take"), sourcePointer: "/basisDigest" },
+ { resultPointer: "/sources/1/digest", source: input("take"), sourcePointer: "/narrativeDigest" },
+ { resultPointer: "/programSpaceDigest", source: input("take"), sourcePointer: "/programSpace/digest" },
+ ],
+ fidelity: "exact",
+ },
+ {
+ name: "audioTrack",
+ type: contractTypes.audioTrack,
+ root: operation("project-audio-track"),
+ semanticInputs: ["take"],
+ affinity: [
+ { resultPointer: "/sources/0/digest", source: input("take"), sourcePointer: "/basisDigest" },
+ { resultPointer: "/sources/1/digest", source: input("take"), sourcePointer: "/narrativeDigest" },
+ { resultPointer: "/programSpaceDigest", source: input("take"), sourcePointer: "/programSpace/digest" },
],
fidelity: "exact",
},
@@ -57,7 +89,7 @@ export const speechTakeProjectionFragment = sealGraphFragment({
/** One WhisperX pass can expose both normalized Evidence and the final SemanticMap. */
export const whisperXSpeechAlignmentFragment = sealGraphFragment({
- name: "@svml/video-fragments/whisperx-speech-alignment@1",
+ name: "@svml/speech-program/whisperx-speech-alignment@1",
inputs: [
{ name: "narrative", type: contractTypes.narrative },
{ name: "audio", type: contractTypes.speechAudioBasis },
@@ -121,6 +153,7 @@ export const whisperXSpeechAlignmentFragment = sealGraphFragment({
{ resultPointer: "/basisDigest", source: input("audio"), sourcePointer: "/basisDigest" },
{ resultPointer: "/audioArtifactDigest", source: input("audio"), sourcePointer: "/audio/digest" },
{ resultPointer: "/programSpaceDigest", source: input("audio"), sourcePointer: "/programSpace/digest" },
+ { resultPointer: "/programSpace/digest", source: input("audio"), sourcePointer: "/programSpace/digest" },
{ resultPointer: "/evidenceDigest", source: operation("normalize-evidence"), sourcePointer: "/evidenceDigest" },
],
fidelity: "exact",
@@ -129,7 +162,7 @@ export const whisperXSpeechAlignmentFragment = sealGraphFragment({
});
export const captionTimingFragment = sealGraphFragment({
- name: "@svml/video-fragments/caption-timing@1",
+ name: "@svml/speech-program/caption-timing@1",
inputs: [
{ name: "narrative", type: contractTypes.narrative },
{ name: "map", type: contractTypes.completeSemanticMap },
@@ -142,12 +175,40 @@ export const captionTimingFragment = sealGraphFragment({
}],
exports: [{
name: "caption",
- type: contractTypes.timedCaptionProjection,
+ type: captionTypes.timedProjection,
root: operation("temporalize-caption"),
semanticInputs: ["narrative", "map"],
affinity: [
{ resultPointer: "/semanticIndexDigest", source: input("narrative"), sourcePointer: "/semanticIndex/digest" },
{ resultPointer: "/speechTimeMapDigest", source: input("map"), sourcePointer: "/mapDigest" },
+ { resultPointer: "/programSpace/digest", source: input("map"), sourcePointer: "/programSpace/digest" },
+ ],
+ fidelity: "exact",
+ }],
+});
+
+/** Official caption lowering; the exported result is an ordinary peer VisualTrack. */
+export const captionTrackFragment = sealGraphFragment({
+ name: "@svml/speech-program/caption-track@1",
+ inputs: [
+ { name: "caption", type: captionTypes.timedProjection },
+ { name: "program", type: captionTypes.trackProgram },
+ ],
+ operations: [{
+ id: "render-caption-track",
+ producer: captionProducers.renderTrack,
+ inputs: { caption: input("caption"), program: input("program") },
+ result: { kind: "output", name: "track" },
+ }],
+ exports: [{
+ name: "track",
+ type: contractTypes.visualTrack,
+ root: operation("render-caption-track"),
+ semanticInputs: ["caption", "program"],
+ affinity: [
+ { resultPointer: "/programSpaceDigest", source: input("caption"), sourcePointer: "/programSpace/digest" },
+ { resultPointer: "/sources/0/digest", source: input("program"), sourcePointer: "/digest" },
+ { resultPointer: "/sources/1/digest", source: input("caption"), sourcePointer: "/projectionDigest" },
],
fidelity: "exact",
}],
diff --git a/packages/video-fragments/test/video-pipeline-fixture.ts b/packages/speech-program/test/video-pipeline-fixture.ts
similarity index 97%
rename from packages/video-fragments/test/video-pipeline-fixture.ts
rename to packages/speech-program/test/video-pipeline-fixture.ts
index f9bd2fda..3af14931 100644
--- a/packages/video-fragments/test/video-pipeline-fixture.ts
+++ b/packages/speech-program/test/video-pipeline-fixture.ts
@@ -1,9 +1,8 @@
import { captionManifest } from "@svml/caption";
import {
contractTypes,
- contractsManifest,
- contractsManifestDigest,
- contractsModuleRef,
+ videoContractDependencies,
+ videoContractManifests,
} from "@svml/contracts";
import {
createResolvedClosure,
@@ -40,7 +39,7 @@ import {
captionTimingFragment,
speechTakeProjectionFragment,
whisperXSpeechAlignmentFragment,
-} from "@svml/video-fragments";
+} from "@svml/speech-program";
import { whisperXManifest, whisperXTypes } from "@svml/whisperx";
export const videoModule = { name: "example.video-pipeline", version: "0.0.0" } as const;
@@ -77,7 +76,10 @@ export const videoManifest: ModuleManifest = {
format: "svml.module@0",
name: videoModule.name,
version: videoModule.version,
- dependencies: [{ module: contractsModuleRef, digest: contractsManifestDigest }],
+ dependencies: [
+ videoContractDependencies.narrative,
+ videoContractDependencies.speech,
+ ],
types: [
{ name: videoTypes.estimate.name, schema: object({ durationSec: { schema: number } }) },
{
@@ -241,7 +243,9 @@ const placeholderEstimateFragment = sealGraphFragment({
export const videoOutputs = {
estimate: "speech.estimate",
take: "speech.take",
+ programSpace: "speech.program-space",
audio: "speech.audio",
+ audioTrack: "speech.audio-track",
visual: "speech.visual",
rawEvidence: "speech.whisperx-evidence",
evidence: "speech.evidence",
@@ -252,7 +256,7 @@ export const videoOutputs = {
export type VideoOutputName = keyof typeof videoOutputs;
export const videoClosure = createResolvedClosure([
- contractsManifest,
+ ...videoContractManifests,
videoManifest,
speechTakeManifest,
whisperXManifest,
@@ -322,7 +326,9 @@ export function createVideoGraph(program: LinkedProgram): CompiledGraph {
bindAuthorFragment(estimate, { estimate: videoOutputs.estimate }),
bindAuthorFragment(take, { take: videoOutputs.take }),
bindAuthorFragment(projections, {
+ programSpace: videoOutputs.programSpace,
audio: videoOutputs.audio,
+ audioTrack: videoOutputs.audioTrack,
visual: videoOutputs.visual,
}),
bindAuthorFragment(alignment, {
diff --git a/packages/video-fragments/test/video-pipeline.test.ts b/packages/speech-program/test/video-pipeline.test.ts
similarity index 97%
rename from packages/video-fragments/test/video-pipeline.test.ts
rename to packages/speech-program/test/video-pipeline.test.ts
index e16b513d..f548185f 100644
--- a/packages/video-fragments/test/video-pipeline.test.ts
+++ b/packages/speech-program/test/video-pipeline.test.ts
@@ -1,10 +1,16 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { captionImplementationDigest, captionProducers, temporalizeCaption } from "@svml/caption";
+import {
+ captionImplementationDigest,
+ captionProducers,
+ temporalizeCaption,
+} from "@svml/caption";
+import type { TimedCaptionProjection } from "@svml/caption";
import {
sealProgramSpace,
sealSpeechBasis,
+ sealVisualTrack,
} from "@svml/contracts";
import type {
AlignedTranscriptEvidence,
@@ -12,8 +18,7 @@ import type {
Narrative,
SpeechAudioBasis,
SpeechBasis,
- SpeechVisualTrack,
- TimedCaptionProjection,
+ VisualTrack,
} from "@svml/contracts";
import { digestOf, sealBuildRequest, start } from "@svml/core";
import {
@@ -86,7 +91,7 @@ function producerCount(state: BuildState, producer: ProducerRef): number {
&& step.producer.module.version === producer.module.version).length;
}
-test("the Fragment-built speech pipeline resumes without repeating paid calls", async () => {
+test("the Speech Program pipeline resumes without repeating paid calls", async () => {
const host = new HostRegistry();
const providers = new ProviderRegistry();
const calls = {
@@ -480,19 +485,16 @@ test("an Existing SpeechTake cuts generation while a visual substitute cuts the
durationSec: 1,
frameRate: { numerator: 30, denominator: 1 },
});
- const black: SpeechVisualTrack = {
- contract: "svml.speech-visual-track@1",
- basisDigest: digestOf("preview:black-basis"),
- narrativeDigest: narrative.semanticIndex.digest,
- programSpace: blackProgram,
- visualTrack: { clips: [] },
- segments: [{
- segmentId: "line",
- startSec: 0,
- endSec: 1,
- sourceArtifactDigest: digestOf("preview:black-artifact"),
- }],
- };
+ const black: VisualTrack = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "preview:black",
+ programSpaceDigest: blackProgram.digest,
+ sources: [
+ { name: "basis", digest: digestOf("preview:black-basis") },
+ { name: "narrative", digest: narrative.semanticIndex.digest },
+ ],
+ presents: [],
+ });
const blackCandidate = createProvidedCandidate({
output: videoOutputs.visual,
value: { kind: "inline", value: black },
diff --git a/packages/speech-take/src/index.ts b/packages/speech-take/src/index.ts
index 4fbd376d..36c0cc60 100644
--- a/packages/speech-take/src/index.ts
+++ b/packages/speech-take/src/index.ts
@@ -7,6 +7,10 @@ export {
export {
projectSpeechAudio,
projectSpeechAudioImplementationDigest,
+ projectSpeechAudioTrack,
+ projectSpeechAudioTrackImplementationDigest,
+ projectSpeechProgramSpace,
+ projectSpeechProgramSpaceImplementationDigest,
projectSpeechVisual,
projectSpeechVisualImplementationDigest,
} from "./projection.js";
diff --git a/packages/speech-take/src/manifest.ts b/packages/speech-take/src/manifest.ts
index 5daa2f74..be3e3712 100644
--- a/packages/speech-take/src/manifest.ts
+++ b/packages/speech-take/src/manifest.ts
@@ -1,13 +1,14 @@
import {
contractTypes,
- contractsManifestDigest,
- contractsModuleRef,
+ videoContractDependencies,
} from "@svml/contracts";
import { digestOf } from "@svml/protocol";
import type { ModuleManifest, ProducerRef } from "@svml/protocol";
import {
projectSpeechAudioImplementationDigest,
+ projectSpeechAudioTrackImplementationDigest,
+ projectSpeechProgramSpaceImplementationDigest,
projectSpeechVisualImplementationDigest,
} from "./projection.js";
@@ -15,18 +16,39 @@ export const speechTakeModuleRef = { name: "@svml/speech-take", version: "0.0.0-
export const speechTakeProducers = {
projectAudio: { module: speechTakeModuleRef, name: "project-audio" },
+ projectAudioTrack: { module: speechTakeModuleRef, name: "project-audio-track" },
projectVisual: { module: speechTakeModuleRef, name: "project-visual" },
+ projectProgramSpace: { module: speechTakeModuleRef, name: "project-program-space" },
} satisfies Record<string, ProducerRef>;
export const speechTakeManifest: ModuleManifest = {
format: "svml.module@0",
name: speechTakeModuleRef.name,
version: speechTakeModuleRef.version,
- dependencies: [{ module: contractsModuleRef, digest: contractsManifestDigest }],
+ dependencies: [
+ videoContractDependencies.speech,
+ videoContractDependencies.programSpace,
+ videoContractDependencies.composition,
+ ],
types: [],
capabilities: [],
surfaces: [],
producers: [
+ {
+ name: speechTakeProducers.projectProgramSpace.name,
+ inputs: [{ name: "basis", type: contractTypes.speechBasis }],
+ outputs: [{
+ name: "programSpace",
+ type: contractTypes.programSpace,
+ affinity: [{ resultPointer: "/digest", input: "basis", inputPointer: "/programSpace/digest" }],
+ }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "@svml/speech-take/project-program-space",
+ digest: projectSpeechProgramSpaceImplementationDigest,
+ },
+ },
{
name: speechTakeProducers.projectAudio.name,
inputs: [{ name: "basis", type: contractTypes.speechBasis }],
@@ -52,11 +74,11 @@ export const speechTakeManifest: ModuleManifest = {
inputs: [{ name: "basis", type: contractTypes.speechBasis }],
outputs: [{
name: "visual",
- type: contractTypes.speechVisualTrack,
+ type: contractTypes.visualTrack,
affinity: [
- { resultPointer: "/basisDigest", input: "basis", inputPointer: "/basisDigest" },
- { resultPointer: "/narrativeDigest", input: "basis", inputPointer: "/narrativeDigest" },
- { resultPointer: "/programSpace/digest", input: "basis", inputPointer: "/programSpace/digest" },
+ { resultPointer: "/sources/0/digest", input: "basis", inputPointer: "/basisDigest" },
+ { resultPointer: "/sources/1/digest", input: "basis", inputPointer: "/narrativeDigest" },
+ { resultPointer: "/programSpaceDigest", input: "basis", inputPointer: "/programSpace/digest" },
],
}],
needs: [],
@@ -66,6 +88,25 @@ export const speechTakeManifest: ModuleManifest = {
digest: projectSpeechVisualImplementationDigest,
},
},
+ {
+ name: speechTakeProducers.projectAudioTrack.name,
+ inputs: [{ name: "basis", type: contractTypes.speechBasis }],
+ outputs: [{
+ name: "track",
+ type: contractTypes.audioTrack,
+ affinity: [
+ { resultPointer: "/sources/0/digest", input: "basis", inputPointer: "/basisDigest" },
+ { resultPointer: "/sources/1/digest", input: "basis", inputPointer: "/narrativeDigest" },
+ { resultPointer: "/programSpaceDigest", input: "basis", inputPointer: "/programSpace/digest" },
+ ],
+ }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "@svml/speech-take/project-audio-track",
+ digest: projectSpeechAudioTrackImplementationDigest,
+ },
+ },
],
};
diff --git a/packages/speech-take/src/projection.ts b/packages/speech-take/src/projection.ts
index 1d438ae2..a1677dc0 100644
--- a/packages/speech-take/src/projection.ts
+++ b/packages/speech-take/src/projection.ts
@@ -1,8 +1,16 @@
-import { assertSpeechBasisIdentity } from "@svml/contracts";
+import {
+ assertSpeechBasisIdentity,
+ programSpaceFrameCount,
+ sealAudioTrack,
+ sealVisualTrack,
+} from "@svml/contracts";
import type {
+ AudioTrack,
+ ProgramSpace,
SpeechAudioBasis,
SpeechBasis,
- SpeechVisualTrack,
+ VisualElement,
+ VisualTrack,
} from "@svml/contracts";
import { digestOf } from "@svml/protocol";
@@ -11,9 +19,22 @@ export const projectSpeechAudioImplementationDigest = digestOf(
);
export const projectSpeechVisualImplementationDigest = digestOf(
- "@svml/speech-take/project-visual@1",
+ "@svml/speech-take/project-visual@2",
+);
+
+export const projectSpeechAudioTrackImplementationDigest = digestOf(
+ "@svml/speech-take/project-audio-track@1",
+);
+
+export const projectSpeechProgramSpaceImplementationDigest = digestOf(
+ "@svml/speech-take/project-program-space@1",
);
+export function projectSpeechProgramSpace(basis: SpeechBasis): ProgramSpace {
+ assertSpeechBasisIdentity(basis);
+ return basis.programSpace;
+}
+
export function projectSpeechAudio(basis: SpeechBasis): SpeechAudioBasis {
assertSpeechBasisIdentity(basis);
return {
@@ -26,14 +47,66 @@ export function projectSpeechAudio(basis: SpeechBasis): SpeechAudioBasis {
};
}
-export function projectSpeechVisual(basis: SpeechBasis): SpeechVisualTrack {
+function frameAt(basis: SpeechBasis, seconds: number): number {
+ return Math.round(seconds * basis.programSpace.frameRate.numerator / basis.programSpace.frameRate.denominator);
+}
+
+export function projectSpeechVisual(basis: SpeechBasis): VisualTrack {
assertSpeechBasisIdentity(basis);
- return {
- contract: "svml.speech-visual-track@1",
- basisDigest: basis.basisDigest,
- narrativeDigest: basis.narrativeDigest,
- programSpace: basis.programSpace,
- visualTrack: basis.visualTrack,
- segments: basis.segments,
- };
+ const totalFrames = programSpaceFrameCount(basis.programSpace);
+ return sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: `speech-visual:${basis.basisDigest}`,
+ programSpaceDigest: basis.programSpace.digest,
+ sources: [
+ { name: "basis", digest: basis.basisDigest },
+ { name: "narrative", digest: basis.narrativeDigest },
+ ],
+ presents: basis.visualTrack.clips.map((clip, index) => {
+ const startFrame = frameAt(basis, clip.startSec);
+ const endFrameExclusive = Math.min(totalFrames, frameAt(basis, clip.endSec));
+ const kind: VisualElement["kind"] = clip.artifact.mediaType.startsWith("image/") ? "image" : "video";
+ if (kind !== "image" && !clip.artifact.mediaType.startsWith("video/")) {
+ throw new Error(`Speech visual ${clip.segmentId} is not an image or video Artifact.`);
+ }
+ if (endFrameExclusive <= startFrame) throw new Error(`Speech visual ${clip.segmentId} has an empty frame span.`);
+ return {
+ id: `${clip.segmentId}:${index + 1}`,
+ span: { startFrame, endFrameExclusive },
+ stacking: { order: 0, tieBreak: `speech-visual:${basis.basisDigest}:${clip.segmentId}:${index + 1}` },
+ elements: [{
+ id: "media",
+ order: 0,
+ kind,
+ artifact: clip.artifact,
+ style: [
+ { name: "height", value: "100%" },
+ { name: "object-fit", value: "cover" },
+ { name: "position", value: "absolute" },
+ { name: "width", value: "100%" },
+ ],
+ ...(kind === "video" ? { muted: true } : {}),
+ }],
+ };
+ }),
+ });
+}
+
+export function projectSpeechAudioTrack(basis: SpeechBasis): AudioTrack {
+ assertSpeechBasisIdentity(basis);
+ return sealAudioTrack({
+ contract: "svml.audio-track@1",
+ id: `speech-audio:${basis.basisDigest}`,
+ programSpaceDigest: basis.programSpace.digest,
+ sources: [
+ { name: "basis", digest: basis.basisDigest },
+ { name: "narrative", digest: basis.narrativeDigest },
+ ],
+ clips: [{
+ id: "speech",
+ span: { startFrame: 0, endFrameExclusive: programSpaceFrameCount(basis.programSpace) },
+ artifact: basis.audio,
+ bus: "speech",
+ }],
+ });
}
diff --git a/packages/speech-take/test/product.test.ts b/packages/speech-take/test/product.test.ts
index 73b6f9a3..de5f0fc6 100644
--- a/packages/speech-take/test/product.test.ts
+++ b/packages/speech-take/test/product.test.ts
@@ -3,11 +3,10 @@ import test from "node:test";
import {
contractTypes,
- contractsManifest,
- contractsManifestDigest,
- contractsModuleRef,
sealProgramSpace,
sealSpeechBasis,
+ videoContractDependencies,
+ videoContractManifests,
} from "@svml/contracts";
import type { SpeechBasis } from "@svml/contracts";
import {
@@ -32,6 +31,8 @@ import type {
import {
projectSpeechAudioImplementationDigest,
projectSpeechAudio,
+ projectSpeechAudioTrack,
+ projectSpeechProgramSpace,
projectSpeechVisualImplementationDigest,
projectSpeechVisual,
speechTakeManifest,
@@ -47,7 +48,7 @@ const testManifest: ModuleManifest = {
format: "svml.module@0",
name: testModule.name,
version: testModule.version,
- dependencies: [{ module: contractsModuleRef, digest: contractsManifestDigest }],
+ dependencies: [videoContractDependencies.speech],
types: [{ name: requestType.name, schema: { kind: "string", minLength: 1 } }],
capabilities: [],
surfaces: [],
@@ -64,7 +65,7 @@ const testManifest: ModuleManifest = {
}],
};
-const closure = createResolvedClosure([contractsManifest, speechTakeManifest, testManifest]);
+const closure = createResolvedClosure([...videoContractManifests, speechTakeManifest, testManifest]);
function sampleTake(label = "generated"): SpeechBasis {
const durationSec = 2;
@@ -151,12 +152,12 @@ function createGraph(program: LinkedProgram): CompiledGraph {
},
{
id: "opening.visual",
- type: contractTypes.speechVisualTrack,
+ type: contractTypes.visualTrack,
primary: "opening.visual.project",
candidates: ["opening.visual.project", "opening.visual.existing"],
semanticInputs: [output("opening.take")],
affinity: [{
- resultPointer: "/basisDigest",
+ resultPointer: "/sources/0/digest",
source: output("opening.take"),
sourcePointer: "/basisDigest",
}],
@@ -267,6 +268,19 @@ test("SpeechBasis is one Product and audio/visual are ordinary shared projection
);
});
+test("SpeechBasis projects to peer generic visual and audio Tracks", () => {
+ const take = sampleTake();
+ const visual = projectSpeechVisual(take);
+ const audio = projectSpeechAudioTrack(take);
+ const programSpace = projectSpeechProgramSpace(take);
+ assert.equal(visual.contract, "svml.visual-track@1");
+ assert.equal(audio.contract, "svml.audio-track@1");
+ assert.equal(visual.programSpaceDigest, take.programSpace.digest);
+ assert.equal(audio.programSpaceDigest, take.programSpace.digest);
+ assert.equal(programSpace.digest, take.programSpace.digest);
+ assert.deepEqual(visual.sources, audio.sources);
+});
+
test("a substitute visual Candidate does not contaminate an independent exact audio path", () => {
const state = build(
{ "opening.audio": "exact", "opening.visual": "substitute" },
diff --git a/packages/svs/README.md b/packages/svs/README.md
new file mode 100644
index 00000000..316853e3
--- /dev/null
+++ b/packages/svs/README.md
@@ -0,0 +1,12 @@
+# `@svml/svs`
+
+Minimal official parameter-recipe Frontend for `.svs` SourceUnits.
+
+SVS v1 reads a `<sheet version="1">` containing named rule blocks and emits one immutable generic
+`Recipe` Record per rule. It does not know Caption, Film, Track or Provider parameters and it does
+not implement CSS selectors, cascade or inheritance. A consuming package validates a Recipe's
+properties and lowers it into its own typed Program Record.
+
+Source import aliases are owned by Source Closure compilation. A rule `caption.alice` remains that
+relative public export; importing it as `studio` exposes `studio.caption.alice` without changing the
+Recipe Record identity.
diff --git a/packages/svs/package.json b/packages/svs/package.json
new file mode 100644
index 00000000..bc81fe21
--- /dev/null
+++ b/packages/svs/package.json
@@ -0,0 +1,17 @@
+{
+ "name": "@svml/svs",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "dependencies": {
+ "@svml/core": "workspace:*",
+ "@svml/elaborator": "workspace:*",
+ "@svml/protocol": "workspace:*"
+ },
+ "devDependencies": {
+ "@svml/text": "workspace:*"
+ }
+}
diff --git a/packages/svs/src/frontend.ts b/packages/svs/src/frontend.ts
new file mode 100644
index 00000000..c466d1eb
--- /dev/null
+++ b/packages/svs/src/frontend.ts
@@ -0,0 +1,59 @@
+import {
+ digestOf,
+ sealRecord,
+ sealTypedModule,
+ verifyClosure,
+ verifyRecordStructure,
+} from "@svml/core";
+import { sealAuthorModule } from "@svml/elaborator";
+import type { AuthorFrontend, AuthorSourceExport } from "@svml/elaborator";
+
+import {
+ svsFrontendId,
+ svsFrontendImplementationDigest,
+ svsModuleRef,
+ svsRecipeType,
+} from "./manifest.js";
+import { parseSvs } from "./parser.js";
+
+export const svsFrontend: AuthorFrontend = {
+ id: svsFrontendId,
+ implementationDigest: svsFrontendImplementationDigest,
+ discover() {
+ return { modules: [`${svsModuleRef.name}@${svsModuleRef.version}`], sources: [] };
+ },
+ decode(source, context) {
+ verifyClosure(context.closure);
+ const parsed = parseSvs(source.name, source.text);
+ const sourceDigest = digestOf(source.text);
+ const records = parsed.recipes.map((recipe) => sealRecord({
+ id: recipe.value.path,
+ type: svsRecipeType,
+ value: { kind: "inline", value: recipe.value },
+ conformance: "exact",
+ origin: {
+ kind: "authored",
+ sourceDigest,
+ frontendClosureDigest: svsFrontendImplementationDigest,
+ sourceName: source.name,
+ range: recipe.range,
+ },
+ }));
+ records.forEach((record) => verifyRecordStructure(context.closure, record));
+ const exports: AuthorSourceExport[] = records.map((record) => ({
+ name: record.id,
+ ref: { kind: "record", id: record.id },
+ type: record.type,
+ }));
+ return {
+ module: sealTypedModule({
+ id: `source:${source.name}`,
+ closureDigest: context.closure.digest,
+ records,
+ }),
+ author: sealAuthorModule({ name: `source:${source.name}`, components: [] }),
+ fragments: [],
+ exports,
+ };
+ },
+};
diff --git a/packages/svs/src/index.ts b/packages/svs/src/index.ts
new file mode 100644
index 00000000..0aba0021
--- /dev/null
+++ b/packages/svs/src/index.ts
@@ -0,0 +1,10 @@
+export {
+ svsFrontendId,
+ svsFrontendImplementationDigest,
+ svsManifest,
+ svsModuleRef,
+ svsRecipeType,
+} from "./manifest.js";
+export { SvsSyntaxError, parseSvs } from "./parser.js";
+export { svsFrontend } from "./frontend.js";
+export type * from "./types.js";
diff --git a/packages/svs/src/manifest.ts b/packages/svs/src/manifest.ts
new file mode 100644
index 00000000..82dd28a9
--- /dev/null
+++ b/packages/svs/src/manifest.ts
@@ -0,0 +1,34 @@
+import { digestOf } from "@svml/core";
+import type { ModuleManifest, TypeRef } from "@svml/protocol";
+
+export const svsModuleRef = { name: "@svml/svs", version: "1" } as const;
+export const svsRecipeType = { module: svsModuleRef, name: "Recipe" } satisfies TypeRef;
+export const svsFrontendId = "@svml/svs@1";
+export const svsFrontendImplementationDigest = digestOf("@svml/svs/frontend@1");
+
+export const svsManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: svsModuleRef.name,
+ version: svsModuleRef.version,
+ dependencies: [],
+ types: [{
+ name: svsRecipeType.name,
+ schema: {
+ kind: "object",
+ fields: {
+ contract: { schema: { kind: "literal", value: "svml.svs-recipe@1" } },
+ path: { schema: { kind: "string", minLength: 3 } },
+ properties: {
+ schema: {
+ kind: "object",
+ fields: {},
+ allowUnknown: true,
+ },
+ },
+ },
+ },
+ }],
+ capabilities: [],
+ surfaces: [],
+ producers: [],
+};
diff --git a/packages/svs/src/parser.ts b/packages/svs/src/parser.ts
new file mode 100644
index 00000000..27246fd4
--- /dev/null
+++ b/packages/svs/src/parser.ts
@@ -0,0 +1,168 @@
+import type { CanonicalValue } from "@svml/protocol";
+
+import type { ParsedSvsRecipe, ParsedSvsSheet, SvsRecipe } from "./types.js";
+
+const RULE = /^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)+/u;
+const PROPERTY = /^[a-z][a-z0-9-]*/u;
+const SHEET_ID = /^[a-z][a-z0-9_-]{0,63}$/u;
+
+export class SvsSyntaxError extends Error {
+ readonly code: string;
+ readonly sourceName: string;
+ readonly offset: number;
+
+ constructor(code: string, message: string, sourceName: string, offset: number) {
+ super(`${sourceName}:${offset}: ${message}`);
+ this.name = "SvsSyntaxError";
+ this.code = code;
+ this.sourceName = sourceName;
+ this.offset = offset;
+ }
+}
+
+function fail(sourceName: string, code: string, message: string, offset: number): never {
+ throw new SvsSyntaxError(code, message, sourceName, offset);
+}
+
+function withoutComments(sourceName: string, text: string): string {
+ const output = [...text];
+ let cursor = 0;
+ while (cursor < text.length) {
+ if (!text.startsWith("/*", cursor)) {
+ cursor += 1;
+ continue;
+ }
+ const end = text.indexOf("*/", cursor + 2);
+ if (end < 0) fail(sourceName, "SVS_COMMENT_UNCLOSED", "Unclosed comment.", cursor);
+ for (let index = cursor; index < end + 2; index += 1) {
+ if (output[index] !== "\n" && output[index] !== "\r") output[index] = " ";
+ }
+ cursor = end + 2;
+ }
+ return output.join("");
+}
+
+function skipSpace(text: string, start: number): number {
+ let cursor = start;
+ while (/\s/u.test(text[cursor] ?? "")) cursor += 1;
+ return cursor;
+}
+
+function parseAttributes(
+ sourceName: string,
+ raw: string,
+ offset: number,
+): Readonly<Record<string, string>> {
+ const attributes: Record<string, string> = {};
+ const attribute = /([a-z][a-z0-9-]*)\s*=\s*(["'])(.*?)\2/gu;
+ let cursor = 0;
+ for (const match of raw.matchAll(attribute)) {
+ const start = match.index ?? 0;
+ if (raw.slice(cursor, start).trim().length > 0) {
+ fail(sourceName, "SVS_SHEET_ATTRIBUTE", "Malformed <sheet> attribute.", offset + cursor);
+ }
+ const name = match[1] as string;
+ if (Object.hasOwn(attributes, name)) {
+ fail(sourceName, "SVS_SHEET_ATTRIBUTE_DUPLICATE", `Duplicate sheet attribute ${name}.`, offset + start);
+ }
+ attributes[name] = match[3] as string;
+ cursor = start + match[0].length;
+ }
+ if (raw.slice(cursor).trim().length > 0) {
+ fail(sourceName, "SVS_SHEET_ATTRIBUTE", "Malformed <sheet> attribute.", offset + cursor);
+ }
+ const unknown = Object.keys(attributes).filter((name) => name !== "version" && name !== "id");
+ if (unknown.length > 0) fail(sourceName, "SVS_SHEET_ATTRIBUTE", `Unknown sheet attribute ${unknown[0]}.`, offset);
+ if (attributes.version !== "1") fail(sourceName, "SVS_VERSION", '<sheet> requires version="1".', offset);
+ if (attributes.id !== undefined && !SHEET_ID.test(attributes.id)) {
+ fail(sourceName, "SVS_SHEET_ID", "Sheet id must be a canonical lower-case identifier.", offset);
+ }
+ return attributes;
+}
+
+function parseValue(sourceName: string, text: string, offset: number): CanonicalValue {
+ const value = text.trim();
+ if (value.length === 0) fail(sourceName, "SVS_VALUE_EMPTY", "Recipe property value is empty.", offset);
+ if (value === "true") return true;
+ if (value === "false") return false;
+ if (/^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/u.test(value)) return Number(value);
+ if (
+ (value.startsWith('"') && value.endsWith('"'))
+ || (value.startsWith("'") && value.endsWith("'"))
+ ) {
+ return value.slice(1, -1);
+ }
+ return value;
+}
+
+function parseProperties(
+ sourceName: string,
+ text: string,
+ offset: number,
+): Readonly<Record<string, CanonicalValue>> {
+ const properties: Record<string, CanonicalValue> = {};
+ let cursor = 0;
+ while (cursor < text.length) {
+ cursor = skipSpace(text, cursor);
+ if (cursor >= text.length) break;
+ const match = PROPERTY.exec(text.slice(cursor));
+ if (!match) fail(sourceName, "SVS_PROPERTY", "Expected a recipe property.", offset + cursor);
+ const name = match[0];
+ if (Object.hasOwn(properties, name)) {
+ fail(sourceName, "SVS_PROPERTY_DUPLICATE", `Duplicate property ${name}.`, offset + cursor);
+ }
+ cursor += name.length;
+ cursor = skipSpace(text, cursor);
+ if (text[cursor] !== ":") fail(sourceName, "SVS_PROPERTY_COLON", `Property ${name} requires ':'.`, offset + cursor);
+ const valueStart = cursor + 1;
+ const semicolon = text.indexOf(";", valueStart);
+ if (semicolon < 0) fail(sourceName, "SVS_PROPERTY_SEMICOLON", `Property ${name} requires ';'.`, offset + valueStart);
+ properties[name] = parseValue(sourceName, text.slice(valueStart, semicolon), offset + valueStart);
+ cursor = semicolon + 1;
+ }
+ return properties;
+}
+
+export function parseSvs(sourceName: string, source: string): ParsedSvsSheet {
+ const text = withoutComments(sourceName, source);
+ let cursor = skipSpace(text, 0);
+ if (!text.startsWith("<sheet", cursor)) fail(sourceName, "SVS_ROOT", "Source must open with <sheet>.", cursor);
+ const openEnd = text.indexOf(">", cursor + 6);
+ if (openEnd < 0) fail(sourceName, "SVS_ROOT", "Opening <sheet> is not closed.", cursor);
+ const attributes = parseAttributes(sourceName, text.slice(cursor + 6, openEnd), cursor + 6);
+ cursor = openEnd + 1;
+ const close = text.indexOf("</sheet>", cursor);
+ if (close < 0) fail(sourceName, "SVS_ROOT_UNCLOSED", "Source is missing </sheet>.", source.length);
+ if (text.slice(close + "</sheet>".length).trim().length > 0) {
+ fail(sourceName, "SVS_TRAILING", "Only trivia may follow </sheet>.", close + "</sheet>".length);
+ }
+ const recipes: ParsedSvsRecipe[] = [];
+ const paths = new Set<string>();
+ while (cursor < close) {
+ cursor = skipSpace(text, cursor);
+ if (cursor >= close) break;
+ const match = RULE.exec(text.slice(cursor));
+ if (!match) fail(sourceName, "SVS_RULE", "Expected a dotted recipe path.", cursor);
+ const path = match[0];
+ if (paths.has(path)) fail(sourceName, "SVS_RULE_DUPLICATE", `Duplicate recipe ${path}.`, cursor);
+ paths.add(path);
+ const start = cursor;
+ cursor += path.length;
+ cursor = skipSpace(text, cursor);
+ if (text[cursor] !== "{") fail(sourceName, "SVS_RULE_OPEN", `Recipe ${path} requires '{'.`, cursor);
+ const blockStart = cursor + 1;
+ const blockEnd = text.indexOf("}", blockStart);
+ if (blockEnd < 0 || blockEnd > close) fail(sourceName, "SVS_RULE_UNCLOSED", `Recipe ${path} is not closed.`, start);
+ const value: SvsRecipe = {
+ contract: "svml.svs-recipe@1",
+ path,
+ properties: parseProperties(sourceName, text.slice(blockStart, blockEnd), blockStart),
+ };
+ recipes.push({ value, range: { start, end: blockEnd + 1 } });
+ cursor = blockEnd + 1;
+ }
+ return {
+ ...(attributes.id === undefined ? {} : { id: attributes.id }),
+ recipes,
+ };
+}
diff --git a/packages/svs/src/types.ts b/packages/svs/src/types.ts
new file mode 100644
index 00000000..4c723856
--- /dev/null
+++ b/packages/svs/src/types.ts
@@ -0,0 +1,17 @@
+import type { CanonicalValue, SourceRange } from "@svml/protocol";
+
+export type SvsRecipe = {
+ readonly contract: "svml.svs-recipe@1";
+ readonly path: string;
+ readonly properties: Readonly<Record<string, CanonicalValue>>;
+};
+
+export type ParsedSvsRecipe = {
+ readonly value: SvsRecipe;
+ readonly range: SourceRange;
+};
+
+export type ParsedSvsSheet = {
+ readonly id?: string;
+ readonly recipes: readonly ParsedSvsRecipe[];
+};
diff --git a/packages/svs/test/source-closure.test.ts b/packages/svs/test/source-closure.test.ts
new file mode 100644
index 00000000..9016b9f2
--- /dev/null
+++ b/packages/svs/test/source-closure.test.ts
@@ -0,0 +1,383 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+
+import {
+ computeModuleDigest,
+ createResolvedClosure,
+ digestOf,
+ sealBuildRequest,
+ start,
+} from "@svml/core";
+import {
+ AuthorFrontendRegistry,
+ SourceClosureError,
+ compileSourceClosure,
+ resolveCompiledSourceExport,
+ sealGraphFragment,
+ verifySourceClosure,
+} from "@svml/elaborator";
+import type { AuthorSourceUnit } from "@svml/elaborator";
+import type {
+ ModuleManifest,
+ ProducerRef,
+ TypeRef,
+ TypedRecord,
+} from "@svml/protocol";
+import {
+ SvsSyntaxError,
+ parseSvs,
+ svsFrontend,
+ svsFrontendId,
+ svsManifest,
+ svsRecipeType,
+} from "@svml/svs";
+import type { SvsRecipe } from "@svml/svs";
+import {
+ TextSurfaceRegistry,
+ createTextAuthorFrontend,
+ textAuthorFrontendId,
+} from "@svml/text";
+import type { StructuredElement } from "@svml/text";
+
+const laboratory = { name: "example.recipe-card", version: "1" } as const;
+const cardType = { module: laboratory, name: "Card" } satisfies TypeRef;
+const cardAppearanceType = { module: laboratory, name: "CardAppearance" } satisfies TypeRef;
+const renderProducer = { module: laboratory, name: "render-card" } satisfies ProducerRef;
+const cardSurfaceDigest = digestOf("example.recipe-card/card-surface@1");
+
+const manifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: laboratory.name,
+ version: laboratory.version,
+ dependencies: [{ module: { name: svsManifest.name, version: svsManifest.version }, digest: computeModuleDigest(svsManifest) }],
+ types: [
+ { name: cardType.name, schema: { kind: "string", minLength: 1 } },
+ {
+ name: cardAppearanceType.name,
+ schema: {
+ kind: "object",
+ fields: {
+ contract: { schema: { kind: "literal", value: "example.card-appearance@1" } },
+ sourceRecipeDigest: { schema: { kind: "string", minLength: 71, maxLength: 71 } },
+ fill: { schema: { kind: "string", minLength: 1 } },
+ padding: { schema: { kind: "string", minLength: 1 } },
+ },
+ },
+ },
+ ],
+ capabilities: [],
+ surfaces: [{
+ name: "card",
+ tag: "Card",
+ mode: "structured",
+ outputs: [cardAppearanceType],
+ implementation: {
+ kind: "trusted-frontend-surface",
+ locator: "example.recipe-card/card-surface",
+ digest: cardSurfaceDigest,
+ },
+ }],
+ producers: [{
+ name: renderProducer.name,
+ inputs: [{ name: "appearance", type: cardAppearanceType }],
+ outputs: [{ name: "card", type: cardType }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.recipe-card/render-card",
+ digest: digestOf("example.recipe-card/render-card@1"),
+ },
+ }],
+};
+
+const cardFragment = sealGraphFragment({
+ name: "example.recipe-card/card@1",
+ inputs: [{ name: "appearance", type: cardAppearanceType }],
+ operations: [{
+ id: "render",
+ producer: renderProducer,
+ inputs: { appearance: { kind: "fragment-input", name: "appearance" } },
+ result: { kind: "output", name: "card" },
+ }],
+ exports: [{
+ name: "result",
+ type: cardType,
+ root: { kind: "fragment-operation", operation: "render" },
+ semanticInputs: ["appearance"],
+ fidelity: "exact",
+ }],
+});
+
+function stringAttribute(element: StructuredElement, name: string): string {
+ const value = element.attributes[name];
+ if (typeof value !== "string" || value.length === 0) throw new Error(`${element.name}.${name} must be a string`);
+ return value;
+}
+
+function referenceAttribute(element: StructuredElement, name: string): string {
+ const value = element.attributes[name];
+ if (typeof value !== "object" || value.kind !== "reference") {
+ throw new Error(`${element.name}.${name} must be a reference`);
+ }
+ return value.path;
+}
+
+function recipeValue(record: TypedRecord | undefined): SvsRecipe {
+ if (record?.type.module.name !== svsRecipeType.module.name || record.type.name !== svsRecipeType.name) {
+ throw new Error("Card.appearance must reference an SVS Recipe");
+ }
+ if (record.value.kind !== "inline" || record.value.value === null
+ || Array.isArray(record.value.value) || typeof record.value.value !== "object") {
+ throw new Error("Card.appearance Recipe must be inline");
+ }
+ return record.value.value as SvsRecipe;
+}
+
+function sourceRegistry(): TextSurfaceRegistry {
+ const registry = new TextSurfaceRegistry();
+ registry.registerStructured(laboratory, "card", cardSurfaceDigest, ({ element, resolveReference }) => {
+ const id = stringAttribute(element, "id");
+ const appearancePath = referenceAttribute(element, "appearance");
+ const resolved = resolveReference(appearancePath);
+ if (resolved === undefined) throw new Error(`Card.appearance cannot resolve ${appearancePath}`);
+ const recipe = recipeValue(resolved.record);
+ const keys = Object.keys(recipe.properties).sort();
+ if (keys.join(",") !== "fill,padding") throw new Error("Card Recipe must contain exactly fill and padding");
+ const fill = recipe.properties.fill;
+ const padding = recipe.properties.padding;
+ if (typeof fill !== "string" || !/^#[0-9A-F]{6}$/iu.test(fill)) {
+ throw new Error("Card Recipe fill must be a six-digit hex color");
+ }
+ if (typeof padding !== "string" || padding.length === 0) {
+ throw new Error("Card Recipe padding must be non-empty");
+ }
+ const appearanceId = `${id}.appearance`;
+ return {
+ records: [{
+ id: appearanceId,
+ type: cardAppearanceType,
+ value: {
+ kind: "inline",
+ value: {
+ contract: "example.card-appearance@1",
+ sourceRecipeDigest: resolved.record?.digest ?? "",
+ fill,
+ padding,
+ },
+ },
+ range: element.range,
+ }],
+ components: [{
+ id,
+ fragment: cardFragment.id,
+ inputs: {
+ appearance: { kind: "record", id: appearanceId },
+ },
+ outputs: { result: `${id}.result` },
+ range: element.range,
+ }],
+ fragments: [cardFragment],
+ };
+ });
+ return registry;
+}
+
+const closure = createResolvedClosure([svsManifest, manifest]);
+
+function unit(id: string, text: string): AuthorSourceUnit {
+ return { id, name: id.split("/").at(-1) ?? id, text };
+}
+
+const styleText = `<sheet version="1" id="studio">
+ card.answer {
+ fill: #73FBD3;
+ padding: 16 24;
+ }
+</sheet>`;
+
+async function compileMain(alias: string, root = "/project", styles = styleText) {
+ const frontends = new AuthorFrontendRegistry();
+ frontends.register(createTextAuthorFrontend({
+ registry: sourceRegistry(),
+ resolveModule: () => laboratory,
+ }));
+ frontends.register(svsFrontend);
+ const entry = unit(`${root}/main.svml`, `<svml>
+ <import as="lab" from="example.recipe-card@1"/>
+ <import as="${alias}" from="./studio.svs" using="${svsFrontendId}"/>
+ <lab:Card id="answer" appearance={${alias}.card.answer}/>
+ </svml>`);
+ return await compileSourceClosure({
+ entry,
+ frontend: textAuthorFrontendId,
+ closure,
+ frontends,
+ async resolveSource(_importer, request) {
+ if (request.from !== "./studio.svs") throw new Error(`unknown source ${request.from}`);
+ return await Promise.resolve(unit(`${root}/studio.svs`, styles));
+ },
+ });
+}
+
+test("Text and SVS recursively compile one aliased Recipe into a Core BuildPlan", async () => {
+ const compiled = await compileMain("studio");
+ assert.equal(compiled.closure.units.length, 2);
+ assert.equal(compiled.module.records.length, 2);
+ const recipe = compiled.module.records.find((record) => record.type.name === svsRecipeType.name);
+ const appearance = compiled.module.records.find((record) => record.type.name === cardAppearanceType.name);
+ assert.deepEqual(recipe?.value, {
+ kind: "inline",
+ value: {
+ contract: "svml.svs-recipe@1",
+ path: "card.answer",
+ properties: { fill: "#73FBD3", padding: "16 24" },
+ },
+ });
+ assert.deepEqual(appearance?.value, {
+ kind: "inline",
+ value: {
+ contract: "example.card-appearance@1",
+ sourceRecipeDigest: recipe?.digest,
+ fill: "#73FBD3",
+ padding: "16 24",
+ },
+ });
+ const target = resolveCompiledSourceExport(compiled, "answer.result", cardType);
+ assert.equal(target.ref.kind, "logical-output");
+ const state = start(compiled.program, compiled.elaboration.graph, sealBuildRequest({
+ graph: compiled.elaboration.graph.id,
+ targets: [{ output: target.ref.kind === "logical-output" ? target.ref.id : "", accepts: "exact" }],
+ bindings: [],
+ }));
+ assert.equal(state.plan.steps.length, 1);
+ assert.equal(state.plan.steps[0]?.producer.name, renderProducer.name);
+ assert.equal(state.plan.steps[0]?.inputs.appearance, appearance?.id);
+});
+
+test("the consuming package rejects an invalid generic Recipe during author compilation", async () => {
+ await assert.rejects(
+ compileMain("studio", "/project", `<sheet version="1">
+ card.answer {
+ fill: definitely-not-a-color;
+ padding: 16 24;
+ }
+ </sheet>`),
+ /Card Recipe fill must be a six-digit hex color/u,
+ );
+});
+
+test("source import alias changes source identity but not Recipe or Graph semantics", async () => {
+ const studio = await compileMain("studio");
+ const brand = await compileMain("brand");
+ assert.notEqual(studio.closure.id, brand.closure.id);
+ const studioAppearance = studio.module.records.find((record) => record.type.name === cardAppearanceType.name);
+ const brandAppearance = brand.module.records.find((record) => record.type.name === cardAppearanceType.name);
+ assert.equal(studioAppearance?.id, brandAppearance?.id);
+ assert.equal(studioAppearance?.digest, brandAppearance?.digest);
+ assert.equal(studio.elaboration.graph.id, brand.elaboration.graph.id);
+});
+
+test("relocating the same source tree preserves Source Closure and Graph identity", async () => {
+ const original = await compileMain("studio", "/project");
+ const relocated = await compileMain("studio", "/copy/project");
+ assert.equal(original.closure.id, relocated.closure.id);
+ assert.equal(original.module.semanticDigest, relocated.module.semanticDigest);
+ assert.equal(original.elaboration.graph.id, relocated.elaboration.graph.id);
+});
+
+test("Source Closure binds every recursive SourceUnit digest", async () => {
+ const compiled = await compileMain("studio");
+ const first = compiled.closure.units[0]!;
+ const tampered = {
+ ...compiled.closure,
+ units: [{ ...first, sourceDigest: digestOf("tampered source") }, ...compiled.closure.units.slice(1)],
+ };
+ assert.throws(
+ () => verifySourceClosure(tampered),
+ (error: unknown) => error instanceof SourceClosureError
+ && error.code === "SOURCE_UNIT_DIGEST_MISMATCH",
+ );
+});
+
+test("Source Closure rejects recursive source import cycles", async () => {
+ const frontends = new AuthorFrontendRegistry();
+ frontends.register(createTextAuthorFrontend({
+ registry: new TextSurfaceRegistry(),
+ resolveModule: () => laboratory,
+ }));
+ const a = unit("/project/a.svml", `<svml><import as="b" from="./b.svml" using="${textAuthorFrontendId}"/></svml>`);
+ const b = unit("/project/b.svml", `<svml><import as="a" from="./a.svml" using="${textAuthorFrontendId}"/></svml>`);
+ await assert.rejects(
+ compileSourceClosure({
+ entry: a,
+ frontend: textAuthorFrontendId,
+ closure,
+ frontends,
+ resolveSource(_importer, request) {
+ return request.from === "./a.svml" ? a : b;
+ },
+ }),
+ (error: unknown) => error instanceof SourceClosureError && error.code === "SOURCE_IMPORT_CYCLE",
+ );
+});
+
+test("Source Closure rejects duplicate aliases and unknown Frontends before decode", async () => {
+ const frontends = new AuthorFrontendRegistry();
+ frontends.register(createTextAuthorFrontend({
+ registry: new TextSurfaceRegistry(),
+ resolveModule: () => laboratory,
+ }));
+ const duplicate = unit("/project/duplicate.svml", `<svml>
+ <import as="styles" from="./one.svs" using="${svsFrontendId}"/>
+ <import as="styles" from="./two.svs" using="${svsFrontendId}"/>
+ </svml>`);
+ frontends.register(svsFrontend);
+ await assert.rejects(
+ compileSourceClosure({
+ entry: duplicate,
+ frontend: textAuthorFrontendId,
+ closure,
+ frontends,
+ resolveSource(_importer, request) {
+ return unit(`/project/${request.from.slice(2)}`, styleText);
+ },
+ }),
+ (error: unknown) => error instanceof SourceClosureError && error.code === "DUPLICATE_SOURCE_ALIAS",
+ );
+
+ const unknown = unit("/project/unknown.svml", `<svml>
+ <import as="styles" from="./studio.svs" using="example.unknown@1"/>
+ </svml>`);
+ await assert.rejects(
+ compileSourceClosure({
+ entry: unknown,
+ frontend: textAuthorFrontendId,
+ closure,
+ frontends,
+ resolveSource() {
+ return unit("/project/studio.svs", styleText);
+ },
+ }),
+ (error: unknown) => error instanceof SourceClosureError && error.code === "UNKNOWN_FRONTEND",
+ );
+});
+
+test("the golden studio.svs parses as generic Recipes without video knowledge", () => {
+ const source = readFileSync(new URL("../../../examples/talking-film-golden/studio.svs", import.meta.url), "utf8");
+ const parsed = parseSvs("studio.svs", source);
+ assert.equal(parsed.recipes.length, 10);
+ assert.equal(parsed.recipes.find((recipe) => recipe.value.path === "caption.short-cues")?.value.properties.model, "gemini-2.5-flash");
+ assert.equal(parsed.recipes.find((recipe) => recipe.value.path === "film.vertical")?.value.properties.width, 1080);
+});
+
+test("SVS rejects duplicate public recipes", () => {
+ assert.throws(
+ () => parseSvs("duplicate.svs", `<sheet version="1"><x.y>{}</x.y></sheet>`),
+ (error: unknown) => error instanceof SvsSyntaxError,
+ );
+ assert.throws(
+ () => parseSvs("duplicate.svs", `<sheet version="1">x.y {} x.y {}</sheet>`),
+ (error: unknown) => error instanceof SvsSyntaxError && error.code === "SVS_RULE_DUPLICATE",
+ );
+});
diff --git a/packages/text-track/README.md b/packages/text-track/README.md
new file mode 100644
index 00000000..113bc0e7
--- /dev/null
+++ b/packages/text-track/README.md
@@ -0,0 +1,11 @@
+# `@svml/text-track`
+
+Official provider-free Text overlay package. It owns a typed `TextTrackProgram` and lowers every
+item into an independently timed and stacked Present in the public VisualTrack contract.
+
+An item spanning the complete ProgramSpace is a persistent overlay; a shorter item is timed. They
+are not different Track kinds. The package exposes semantic typography and box parameters rather
+than a rendering callback, arbitrary CSS or cross-Track access.
+
+No author-facing Surface is frozen yet. A future Text Surface and `.svs` recipes can produce the
+same TextTrackProgram without changing Core, Film, Composition or HyperFrames.
diff --git a/packages/text-track/package.json b/packages/text-track/package.json
new file mode 100644
index 00000000..085ef7f4
--- /dev/null
+++ b/packages/text-track/package.json
@@ -0,0 +1,17 @@
+{
+ "name": "@svml/text-track",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "dependencies": {
+ "@svml/contracts": "workspace:*",
+ "@svml/elaborator": "workspace:*",
+ "@svml/protocol": "workspace:*"
+ },
+ "devDependencies": {
+ "@svml/hyperframes": "workspace:*"
+ }
+}
diff --git a/packages/text-track/src/fragment.ts b/packages/text-track/src/fragment.ts
new file mode 100644
index 00000000..7cac8ef4
--- /dev/null
+++ b/packages/text-track/src/fragment.ts
@@ -0,0 +1,33 @@
+import { contractTypes } from "@svml/contracts";
+import { sealGraphFragment } from "@svml/elaborator";
+
+import { textTrackProducers, textTrackTypes } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+/** Provider-free official lowering from TextTrackProgram to one peer VisualTrack. */
+export const textTrackFragment = sealGraphFragment({
+ name: "@svml/text-track/render@1",
+ inputs: [
+ { name: "space", type: contractTypes.programSpace },
+ { name: "program", type: textTrackTypes.program },
+ ],
+ operations: [{
+ id: "render",
+ producer: textTrackProducers.render,
+ inputs: { space: input("space"), program: input("program") },
+ result: { kind: "output", name: "track" },
+ }],
+ exports: [{
+ name: "track",
+ type: contractTypes.visualTrack,
+ root: operation("render"),
+ semanticInputs: ["space", "program"],
+ affinity: [
+ { resultPointer: "/programSpaceDigest", source: input("space"), sourcePointer: "/digest" },
+ { resultPointer: "/sources/0/digest", source: input("program"), sourcePointer: "/digest" },
+ ],
+ fidelity: "exact",
+ }],
+});
diff --git a/packages/text-track/src/index.ts b/packages/text-track/src/index.ts
new file mode 100644
index 00000000..9bec2c0a
--- /dev/null
+++ b/packages/text-track/src/index.ts
@@ -0,0 +1,17 @@
+export { textTrackFragment } from "./fragment.js";
+export {
+ textTrackManifest,
+ textTrackManifestDigest,
+ textTrackModuleRef,
+ textTrackProducers,
+ textTrackProgramSchema,
+ textTrackTypes,
+} from "./manifest.js";
+export {
+ assertTextTrackProgramIdentity,
+ computeTextTrackProgramDigest,
+ renderTextTrack,
+ renderTextTrackImplementationDigest,
+ sealTextTrackProgram,
+} from "./program.js";
+export type * from "./types.js";
diff --git a/packages/text-track/src/manifest.ts b/packages/text-track/src/manifest.ts
new file mode 100644
index 00000000..fbd40816
--- /dev/null
+++ b/packages/text-track/src/manifest.ts
@@ -0,0 +1,101 @@
+import {
+ contractTypes,
+ videoContractDependencies,
+ visualTrackSchema,
+} from "@svml/contracts";
+import { digestOf } from "@svml/protocol";
+import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@svml/protocol";
+
+import { renderTextTrackImplementationDigest } from "./program.js";
+
+export const textTrackModuleRef = { name: "@svml/text-track", version: "0.0.0-dev" } as const;
+export const textTrackTypes = {
+ program: { module: textTrackModuleRef, name: "TextTrackProgram" },
+} satisfies Record<string, TypeRef>;
+export const textTrackProducers = {
+ render: { module: textTrackModuleRef, name: "render-text-track" },
+} satisfies Record<string, ProducerRef>;
+
+const string = { kind: "string", minLength: 1 } as const;
+const number = { kind: "number" } as const;
+const positiveNumber = { kind: "number", minimum: 0.000001 } as const;
+const unsignedInteger = { kind: "number", integer: true, minimum: 0 } as const;
+const signedInteger = { kind: "number", integer: true } as const;
+const digest = { kind: "string", minLength: 71, maxLength: 71 } as const;
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({
+ kind: "object",
+ fields,
+});
+
+const textItemSchema = object({
+ id: { schema: string },
+ text: { schema: string },
+ span: { schema: object({
+ startFrame: { schema: unsignedInteger },
+ endFrameExclusive: { schema: unsignedInteger },
+ }) },
+ z: { schema: signedInteger },
+ tieBreak: { schema: string },
+ box: { schema: object({
+ xPercent: { schema: number },
+ yPercent: { schema: number },
+ widthPercent: { schema: positiveNumber },
+ heightPercent: { schema: positiveNumber },
+ }) },
+ appearance: { schema: object({
+ color: { schema: string },
+ fontSizePx: { schema: positiveNumber },
+ fontFamily: { schema: string, optional: true },
+ fontWeight: { schema: { kind: "number", integer: true, minimum: 1, maximum: 1000 }, optional: true },
+ lineHeight: { schema: positiveNumber, optional: true },
+ align: { schema: { kind: "string", enum: ["left", "center", "right"] }, optional: true },
+ verticalAlign: { schema: { kind: "string", enum: ["top", "center", "bottom"] }, optional: true },
+ backgroundColor: { schema: string, optional: true },
+ borderRadiusPx: { schema: { kind: "number", minimum: 0 }, optional: true },
+ paddingPx: { schema: { kind: "number", minimum: 0 }, optional: true },
+ }) },
+});
+
+export const textTrackProgramSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.text-track-program@1" } },
+ digest: { schema: digest },
+ id: { schema: string },
+ programSpaceDigest: { schema: digest },
+ items: { schema: { kind: "array", minItems: 1, items: textItemSchema } },
+});
+
+export const textTrackManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: textTrackModuleRef.name,
+ version: textTrackModuleRef.version,
+ dependencies: [
+ videoContractDependencies.programSpace,
+ videoContractDependencies.composition,
+ ],
+ types: [{ name: textTrackTypes.program.name, schema: textTrackProgramSchema }],
+ capabilities: [],
+ surfaces: [],
+ producers: [{
+ name: textTrackProducers.render.name,
+ inputs: [
+ { name: "space", type: contractTypes.programSpace },
+ { name: "program", type: textTrackTypes.program },
+ ],
+ outputs: [{
+ name: "track",
+ type: contractTypes.visualTrack,
+ affinity: [
+ { resultPointer: "/programSpaceDigest", input: "space", inputPointer: "/digest" },
+ { resultPointer: "/sources/0/digest", input: "program", inputPointer: "/digest" },
+ ],
+ }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "@svml/text-track/render",
+ digest: renderTextTrackImplementationDigest,
+ },
+ }],
+};
+
+export const textTrackManifestDigest = digestOf(textTrackManifest);
diff --git a/packages/text-track/src/program.ts b/packages/text-track/src/program.ts
new file mode 100644
index 00000000..edc10568
--- /dev/null
+++ b/packages/text-track/src/program.ts
@@ -0,0 +1,179 @@
+import {
+ assertProgramSpaceIdentity,
+ assertVisualTrackIdentity,
+ programSpaceFrameCount,
+ sealVisualTrack,
+} from "@svml/contracts";
+import type { ProgramSpace, VisualStyleDeclaration, VisualTrack } from "@svml/contracts";
+import { digestOf, isDigest } from "@svml/protocol";
+import type { Digest } from "@svml/protocol";
+
+import type { TextAppearance, TextItem, TextTrackProgram } from "./types.js";
+
+export const renderTextTrackImplementationDigest = digestOf("@svml/text-track/render@1");
+
+function assertNonEmpty(value: string, label: string): void {
+ if (!value.trim()) throw new Error(`${label} must not be empty.`);
+}
+
+function assertFinite(value: number, label: string): void {
+ if (!Number.isFinite(value)) throw new Error(`${label} must be finite.`);
+}
+
+function normalizeItem(item: TextItem): TextItem {
+ return {
+ id: item.id,
+ text: item.text,
+ span: { ...item.span },
+ z: item.z,
+ tieBreak: item.tieBreak,
+ box: { ...item.box },
+ appearance: { ...item.appearance },
+ };
+}
+
+function textTrackProgramContent(value: Omit<TextTrackProgram, "digest">): Omit<TextTrackProgram, "digest"> {
+ return {
+ contract: "svml.text-track-program@1",
+ id: value.id,
+ programSpaceDigest: value.programSpaceDigest,
+ items: [...value.items]
+ .map(normalizeItem)
+ .sort((left, right) => left.span.startFrame - right.span.startFrame
+ || left.z - right.z
+ || left.tieBreak.localeCompare(right.tieBreak)
+ || left.id.localeCompare(right.id)),
+ };
+}
+
+export function computeTextTrackProgramDigest(value: Omit<TextTrackProgram, "digest">): Digest {
+ return digestOf(textTrackProgramContent(value));
+}
+
+export function sealTextTrackProgram(value: Omit<TextTrackProgram, "digest">): TextTrackProgram {
+ const content = textTrackProgramContent(value);
+ return { ...content, digest: digestOf(content) };
+}
+
+function assertAppearance(appearance: TextAppearance, label: string): void {
+ assertNonEmpty(appearance.color, `${label} color`);
+ assertFinite(appearance.fontSizePx, `${label} fontSizePx`);
+ if (appearance.fontSizePx <= 0) throw new Error(`${label} fontSizePx must be positive.`);
+ if (appearance.fontFamily !== undefined) assertNonEmpty(appearance.fontFamily, `${label} fontFamily`);
+ if (
+ appearance.fontWeight !== undefined
+ && (!Number.isSafeInteger(appearance.fontWeight) || appearance.fontWeight < 1 || appearance.fontWeight > 1000)
+ ) {
+ throw new Error(`${label} fontWeight must be an integer from 1 to 1000.`);
+ }
+ if (appearance.lineHeight !== undefined) {
+ assertFinite(appearance.lineHeight, `${label} lineHeight`);
+ if (appearance.lineHeight <= 0) throw new Error(`${label} lineHeight must be positive.`);
+ }
+ for (const [name, value] of Object.entries({
+ borderRadiusPx: appearance.borderRadiusPx,
+ paddingPx: appearance.paddingPx,
+ })) {
+ if (value !== undefined) {
+ assertFinite(value, `${label} ${name}`);
+ if (value < 0) throw new Error(`${label} ${name} must not be negative.`);
+ }
+ }
+ if (appearance.backgroundColor !== undefined) assertNonEmpty(appearance.backgroundColor, `${label} backgroundColor`);
+}
+
+export function assertTextTrackProgramIdentity(program: TextTrackProgram, programSpace: ProgramSpace): void {
+ assertProgramSpaceIdentity(programSpace);
+ if (program.contract !== "svml.text-track-program@1") throw new Error("Unsupported TextTrackProgram contract.");
+ assertNonEmpty(program.id, "TextTrackProgram id");
+ if (program.programSpaceDigest !== programSpace.digest) {
+ throw new Error("TextTrackProgram belongs to another ProgramSpace.");
+ }
+ const { digest: _digest, ...content } = program;
+ if (!isDigest(program.digest) || program.digest !== computeTextTrackProgramDigest(content)) {
+ throw new Error("TextTrackProgram digest does not match its contents.");
+ }
+ if (program.items.length === 0) throw new Error("TextTrackProgram must contain at least one item.");
+ const totalFrames = programSpaceFrameCount(programSpace);
+ const ids = new Set<string>();
+ for (const item of program.items) {
+ assertNonEmpty(item.id, "Text item id");
+ if (ids.has(item.id)) throw new Error(`TextTrackProgram contains duplicate item ${item.id}.`);
+ ids.add(item.id);
+ if (!item.text) throw new Error(`${item.id} text must not be empty.`);
+ if (
+ !Number.isSafeInteger(item.span.startFrame)
+ || !Number.isSafeInteger(item.span.endFrameExclusive)
+ || item.span.startFrame < 0
+ || item.span.endFrameExclusive <= item.span.startFrame
+ || item.span.endFrameExclusive > totalFrames
+ ) {
+ throw new Error(`${item.id} span is outside ProgramSpace.`);
+ }
+ if (!Number.isSafeInteger(item.z)) throw new Error(`${item.id} z must be a safe integer.`);
+ assertNonEmpty(item.tieBreak, `${item.id} tieBreak`);
+ for (const [name, value] of Object.entries(item.box)) assertFinite(value, `${item.id} box.${name}`);
+ if (item.box.widthPercent <= 0 || item.box.heightPercent <= 0) {
+ throw new Error(`${item.id} box width and height must be positive.`);
+ }
+ assertAppearance(item.appearance, `${item.id} appearance`);
+ }
+}
+
+function rootStyle(item: TextItem): VisualStyleDeclaration[] {
+ const vertical = item.appearance.verticalAlign ?? "center";
+ return [
+ { name: "position", value: "absolute" },
+ { name: "left", value: `${item.box.xPercent}%` },
+ { name: "top", value: `${item.box.yPercent}%` },
+ { name: "width", value: `${item.box.widthPercent}%` },
+ { name: "height", value: `${item.box.heightPercent}%` },
+ { name: "box-sizing", value: "border-box" },
+ { name: "display", value: "flex" },
+ { name: "align-items", value: vertical === "top" ? "flex-start" : vertical === "bottom" ? "flex-end" : "center" },
+ { name: "justify-content", value: "center" },
+ ...(item.appearance.backgroundColor === undefined
+ ? []
+ : [{ name: "background-color", value: item.appearance.backgroundColor }]),
+ ...(item.appearance.borderRadiusPx === undefined
+ ? []
+ : [{ name: "border-radius", value: `${item.appearance.borderRadiusPx}px` }]),
+ ...(item.appearance.paddingPx === undefined
+ ? []
+ : [{ name: "padding", value: `${item.appearance.paddingPx}px` }]),
+ ];
+}
+
+function textStyle(appearance: TextAppearance): VisualStyleDeclaration[] {
+ return [
+ { name: "width", value: "100%" },
+ { name: "white-space", value: "pre-wrap" },
+ { name: "color", value: appearance.color },
+ { name: "font-size", value: `${appearance.fontSizePx}px` },
+ { name: "font-weight", value: appearance.fontWeight ?? 400 },
+ { name: "line-height", value: appearance.lineHeight ?? 1.2 },
+ { name: "text-align", value: appearance.align ?? "center" },
+ ...(appearance.fontFamily === undefined ? [] : [{ name: "font-family", value: appearance.fontFamily }]),
+ ];
+}
+
+export function renderTextTrack(programSpace: ProgramSpace, program: TextTrackProgram): VisualTrack {
+ assertTextTrackProgramIdentity(program, programSpace);
+ const track = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: program.id,
+ programSpaceDigest: programSpace.digest,
+ sources: [{ name: "program", digest: program.digest }],
+ presents: program.items.map((item) => ({
+ id: item.id,
+ span: { ...item.span },
+ stacking: { order: item.z, tieBreak: item.tieBreak },
+ elements: [
+ { id: "root", kind: "box", order: 0, style: rootStyle(item) },
+ { id: "text", parent: "root", kind: "text", order: 1, text: item.text, style: textStyle(item.appearance) },
+ ],
+ })),
+ });
+ assertVisualTrackIdentity(track, programSpace);
+ return track;
+}
diff --git a/packages/text-track/src/types.ts b/packages/text-track/src/types.ts
new file mode 100644
index 00000000..b90e9fe0
--- /dev/null
+++ b/packages/text-track/src/types.ts
@@ -0,0 +1,41 @@
+import type { FrameSpan } from "@svml/contracts";
+import type { Digest } from "@svml/protocol";
+
+export type TextBox = {
+ readonly xPercent: number;
+ readonly yPercent: number;
+ readonly widthPercent: number;
+ readonly heightPercent: number;
+};
+
+export type TextAppearance = {
+ readonly color: string;
+ readonly fontSizePx: number;
+ readonly fontFamily?: string;
+ readonly fontWeight?: number;
+ readonly lineHeight?: number;
+ readonly align?: "left" | "center" | "right";
+ readonly verticalAlign?: "top" | "center" | "bottom";
+ readonly backgroundColor?: string;
+ readonly borderRadiusPx?: number;
+ readonly paddingPx?: number;
+};
+
+export type TextItem = {
+ readonly id: string;
+ readonly text: string;
+ readonly span: FrameSpan;
+ readonly z: number;
+ readonly tieBreak: string;
+ readonly box: TextBox;
+ readonly appearance: TextAppearance;
+};
+
+/** Package-owned authoring value. A future Text Surface or SVS recipe may produce it. */
+export type TextTrackProgram = {
+ readonly contract: "svml.text-track-program@1";
+ readonly digest: Digest;
+ readonly id: string;
+ readonly programSpaceDigest: Digest;
+ readonly items: readonly TextItem[];
+};
diff --git a/packages/text-track/test/text-track.test.ts b/packages/text-track/test/text-track.test.ts
new file mode 100644
index 00000000..84f9a611
--- /dev/null
+++ b/packages/text-track/test/text-track.test.ts
@@ -0,0 +1,104 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ sealComposition,
+ sealProgramSpace,
+ sealVisualTrack,
+} from "@svml/contracts";
+import { compileHyperframesDocument } from "@svml/hyperframes";
+import { digestOf } from "@svml/protocol";
+import {
+ assertTextTrackProgramIdentity,
+ renderTextTrack,
+ sealTextTrackProgram,
+} from "@svml/text-track";
+
+const space = sealProgramSpace({
+ contract: "svml.program-space@0",
+ durationSec: 5,
+ frameRate: { numerator: 30, denominator: 1 },
+});
+
+test("persistent and timed text are ordinary Presents in one VisualTrack", () => {
+ const program = sealTextTrackProgram({
+ contract: "svml.text-track-program@1",
+ id: "editorial-text",
+ programSpaceDigest: space.digest,
+ items: [
+ {
+ id: "watermark",
+ text: "SVML",
+ span: { startFrame: 0, endFrameExclusive: 150 },
+ z: 90,
+ tieBreak: "watermark",
+ box: { xPercent: 70, yPercent: 4, widthPercent: 25, heightPercent: 8 },
+ appearance: { color: "#ffffff", fontSizePx: 32, fontWeight: 700, align: "right" },
+ },
+ {
+ id: "callout",
+ text: "Intent, not timeline",
+ span: { startFrame: 30, endFrameExclusive: 90 },
+ z: 55,
+ tieBreak: "callout",
+ box: { xPercent: 10, yPercent: 65, widthPercent: 80, heightPercent: 12 },
+ appearance: {
+ color: "#111111",
+ fontSizePx: 48,
+ fontFamily: "Inter, sans-serif",
+ fontWeight: 800,
+ backgroundColor: "#f8ff66",
+ borderRadiusPx: 18,
+ paddingPx: 16,
+ },
+ },
+ ],
+ });
+ assert.doesNotThrow(() => assertTextTrackProgramIdentity(program, space));
+ const track = renderTextTrack(space, program);
+ assert.deepEqual(track.presents.map((present) => present.id), ["watermark", "callout"]);
+ assert.equal(track.sources[0]?.digest, program.digest);
+ assert.equal(track.presents[0]?.span.endFrameExclusive, 150);
+ assert.equal(track.presents[1]?.span.endFrameExclusive, 90);
+
+ const lower = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ id: "lower",
+ programSpaceDigest: space.digest,
+ sources: [{ name: "fixture", digest: digestOf("lower") }],
+ presents: [{
+ id: "lower",
+ span: { startFrame: 0, endFrameExclusive: 150 },
+ stacking: { order: 40, tieBreak: "lower" },
+ elements: [{ id: "root", kind: "box", order: 0, style: [] }],
+ }],
+ });
+ const document = compileHyperframesDocument(sealComposition({
+ contract: "svml.composition@1",
+ id: "text-film",
+ programSpace: space,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [track, lower],
+ }));
+ assert.match(document.html, /Intent, not timeline/u);
+ assert.match(document.html, /font-family:Inter, sans-serif/u);
+ assert.ok(document.html.indexOf('data-svml-present-id="lower"') < document.html.indexOf('data-svml-present-id="callout"'));
+});
+
+test("TextTrackProgram rejects a frame span outside its ProgramSpace", () => {
+ const program = sealTextTrackProgram({
+ contract: "svml.text-track-program@1",
+ id: "invalid-text",
+ programSpaceDigest: space.digest,
+ items: [{
+ id: "late",
+ text: "Too late",
+ span: { startFrame: 149, endFrameExclusive: 151 },
+ z: 1,
+ tieBreak: "late",
+ box: { xPercent: 0, yPercent: 0, widthPercent: 100, heightPercent: 10 },
+ appearance: { color: "#ffffff", fontSizePx: 24 },
+ }],
+ });
+ assert.throws(() => renderTextTrack(space, program), /outside ProgramSpace/u);
+});
diff --git a/packages/text/README.md b/packages/text/README.md
index c8a452c8..68aab481 100644
--- a/packages/text/README.md
+++ b/packages/text/README.md
@@ -23,8 +23,21 @@ Decoding has two passes. `discoverText` reads only the root and complete leading
After Driver supplies one immutable resolved closure, `decodeText` freezes the visible Surface
scope and parses the body. A raw Surface receives the source cursor immediately after its opening
tag and must return the cursor after its own close; a structured Surface receives Text's generic
-element tree. Text seals each returned draft as an authored typed Record with separate source,
-frontend-closure and semantic identities.
+element tree.
-Source imports using another codec are discovered by the syntax but intentionally rejected by the
-current decoder until Driver owns recursive SourceUnit resolution.
+A Surface may contribute three kinds of inert data:
+
+- authored typed Record drafts;
+- parser-independent Author Component drafts;
+- content-addressed Graph Fragments used by those components.
+
+Text validates source ranges, duplicate identities, Manifest-declared Record types and complete
+Fragment references. It strips diagnostic ranges before sealing one `svml.author-module@1`, so
+source reflow does not change author semantics. It never expands a Fragment or resolves a component
+input while reading the body. After every declaration has been collected, `@svml/elaborator`
+resolves forward references and emits the Core Graph.
+
+Direct `decodeText()` calls require every source import to be supplied as an already resolved
+namespace. The reference `compileSourceClosure()` orchestration in `@svml/elaborator` recursively
+discovers those SourceUnits, selects the exact `using` Frontend, decodes dependencies first and then
+calls Text with their locked public exports. Text itself never reads a file or guesses a Frontend.
diff --git a/packages/text/package.json b/packages/text/package.json
index 09d5ae4c..fa2f7a02 100644
--- a/packages/text/package.json
+++ b/packages/text/package.json
@@ -8,6 +8,7 @@
},
"dependencies": {
"@svml/core": "workspace:*",
+ "@svml/elaborator": "workspace:*",
"@svml/protocol": "workspace:*"
},
"devDependencies": {
diff --git a/packages/text/src/frontend.ts b/packages/text/src/frontend.ts
index fdf6723c..939eee57 100644
--- a/packages/text/src/frontend.ts
+++ b/packages/text/src/frontend.ts
@@ -1,11 +1,28 @@
import {
+ canonicalize,
+ canonicalStringify,
digestOf,
+ isDigest,
sealRecord,
sealTypedModule,
verifyClosure,
- verifyRecord,
+ verifyRecordStructure,
} from "@svml/core";
-import type { CanonicalValue, ModuleRef, ResolvedModule, SurfaceDeclaration } from "@svml/protocol";
+import type {
+ CanonicalValue,
+ ModuleRef,
+ ResolvedModule,
+ SurfaceDeclaration,
+ TypedRecord,
+} from "@svml/protocol";
+import { sealAuthorModule } from "@svml/elaborator";
+import type {
+ AuthorComponent,
+ AuthorSourceExport,
+ AuthorValueRef,
+ GraphFragment,
+ ResolvedAuthorSourceImport,
+} from "@svml/elaborator";
import { TextFrontendError } from "./error.js";
import {
@@ -19,14 +36,20 @@ import type {
RawSurfaceHandler,
SourceUnit,
StructuredSurfaceHandler,
+ SurfaceComponentDraft,
+ SurfaceDecodeOutput,
SurfaceRecordDraft,
+ SurfaceResolvedReference,
TextDecodeContext,
TextDecodeResult,
+ TextAuthorFrontend,
+ TextAuthorFrontendOptions,
TextImportRequest,
} from "./types.js";
export const textFrontendRef = { module: "@svml/text", version: "0.0.0-dev", name: "text" } as const;
export const textFrontendImplementationDigest = digestOf("@svml/text/frontend@0");
+export const textAuthorFrontendId = "@svml/text@1";
type BoundSurface = {
readonly tag: string;
@@ -85,14 +108,39 @@ function surfaceScope(
export function decodeText(source: SourceUnit, context: TextDecodeContext): TextDecodeResult {
verifyClosure(context.closure);
const discovery = discoverText(source);
- if (discovery.imports.some((request) => request.using !== undefined)) {
- const request = discovery.imports.find((item) => item.using !== undefined)!;
- fail(
- source,
- "TEXT_SOURCE_IMPORT_UNRESOLVED",
- `Source import "${request.from}" must be decoded by Driver before this SourceUnit.`,
- request.range.start,
- );
+ const sourceImports = context.sourceImports ?? [];
+ const importedBindings = new Map<string, AuthorSourceExport>();
+ const importedReferences = new Map<string, SurfaceResolvedReference>();
+ for (const request of discovery.imports.filter((item) => item.using !== undefined)) {
+ const resolved = sourceImports.find((item) =>
+ item.request.from === request.from
+ && item.request.alias === request.alias
+ && item.request.frontend === request.using);
+ if (resolved === undefined) {
+ fail(
+ source,
+ "TEXT_SOURCE_IMPORT_UNRESOLVED",
+ `Source import "${request.from}" must be decoded before this SourceUnit.`,
+ request.range.start,
+ );
+ }
+ for (const item of resolved.exports) {
+ const name = `${request.alias}.${item.name}`;
+ if (importedBindings.has(name)) {
+ fail(source, "TEXT_SOURCE_EXPORT_COLLISION", `Imported binding ${name} is duplicated.`, request.range.start);
+ }
+ importedBindings.set(name, item);
+ const recordId = item.ref.kind === "record" ? item.ref.id : undefined;
+ const record = recordId === undefined
+ ? undefined
+ : resolved.records.find((candidate) => candidate.id === recordId);
+ importedReferences.set(name, {
+ path: name,
+ ref: item.ref,
+ type: item.type,
+ ...(record === undefined ? {} : { record }),
+ });
+ }
}
const scope = surfaceScope(source, discovery.imports, context);
const sourceDigest = digestOf(source.text);
@@ -107,10 +155,23 @@ export function decodeText(source: SourceUnit, context: TextDecodeContext): Text
name: surface.declaration.name,
implementationDigest: surface.declaration.implementation.digest,
})),
+ sourceImports: sourceImports
+ .map((item) => ({
+ from: item.request.from,
+ alias: item.request.alias,
+ frontend: item.request.frontend,
+ source: item.source,
+ exports: item.exports,
+ }))
+ .sort((left, right) => left.alias.localeCompare(right.alias)),
});
- const records = [];
+ const records: TypedRecord[] = [];
+ const components: AuthorComponent[] = [];
+ const componentRanges = new Map<string, SurfaceComponentDraft["range"]>();
+ const fragments = new Map<string, GraphFragment>();
const sourceMaps: CanonicalValue[] = [];
const recordIds = new Set<string>();
+ const componentIds = new Set<string>();
let cursor = discovery.bodyStart;
let closed = false;
while (cursor < source.text.length) {
@@ -139,11 +200,10 @@ export function decodeText(source: SourceUnit, context: TextDecodeContext): Text
) {
fail(source, "TEXT_SURFACE_MISMATCH", `Registered Surface ${bound.declaration.name} does not match the locked Manifest.`, cursor);
}
- let drafts: readonly SurfaceRecordDraft[];
- let maps: readonly CanonicalValue[] | undefined;
+ let output: SurfaceDecodeOutput;
if (bound.declaration.mode === "raw") {
if (opening.selfClosing) fail(source, "TEXT_RAW_SELF_CLOSING", `Raw Surface <${opening.name}> cannot be self-closing.`, cursor);
- const output = (registered.handler as RawSurfaceHandler)({
+ const rawOutput = (registered.handler as RawSurfaceHandler)({
sourceName: source.name,
source: source.text,
tag: opening.name,
@@ -151,23 +211,50 @@ export function decodeText(source: SourceUnit, context: TextDecodeContext): Text
contentStart: opening.end,
attributes: opening.attributes,
});
- if (!Number.isInteger(output.nextOffset) || output.nextOffset <= opening.end || output.nextOffset > source.text.length) {
+ if (!Number.isInteger(rawOutput.nextOffset) || rawOutput.nextOffset <= opening.end || rawOutput.nextOffset > source.text.length) {
fail(source, "TEXT_SURFACE_CURSOR", `Raw Surface <${opening.name}> returned an invalid cursor.`, cursor);
}
- cursor = output.nextOffset;
- drafts = output.records;
- maps = output.sourceMaps;
+ cursor = rawOutput.nextOffset;
+ output = rawOutput;
} else {
const parsed = parseStructuredElement(source, cursor);
- const output = (registered.handler as StructuredSurfaceHandler)({
+ output = (registered.handler as StructuredSurfaceHandler)({
sourceName: source.name,
element: parsed.element,
+ resolveReference(path) {
+ const imported = importedReferences.get(path);
+ if (imported !== undefined) {
+ return imported.record === undefined
+ ? imported
+ : { ...imported, record: canonicalize(imported.record) as unknown as TypedRecord };
+ }
+ const record = records.find((candidate) => candidate.id === path);
+ if (record !== undefined) {
+ return {
+ path,
+ ref: { kind: "record", id: record.id },
+ type: record.type,
+ record: canonicalize(record) as unknown as TypedRecord,
+ };
+ }
+ for (const component of components) {
+ const output = Object.entries(component.outputs).find(([, publicName]) => publicName === path);
+ if (output === undefined) continue;
+ const fragment = fragments.get(component.fragment);
+ const declaration = fragment?.exports.find((candidate) => candidate.name === output[0]);
+ if (declaration === undefined) continue;
+ return {
+ path,
+ ref: { kind: "component-output", component: component.id, output: output[0] },
+ type: declaration.type,
+ };
+ }
+ return undefined;
+ },
});
cursor = parsed.nextOffset;
- drafts = output.records;
- maps = output.sourceMaps;
}
- for (const draft of drafts) {
+ for (const draft of output.records) {
if (
!Number.isInteger(draft.range.start)
|| !Number.isInteger(draft.range.end)
@@ -205,20 +292,117 @@ export function decodeText(source: SourceUnit, context: TextDecodeContext): Text
range: draft.range,
},
});
- verifyRecord(context.closure, record);
+ verifyRecordStructure(context.closure, record);
records.push(record);
}
- sourceMaps.push(...(maps ?? []));
+ for (const draft of output.components) {
+ if (
+ !Number.isInteger(draft.range.start)
+ || !Number.isInteger(draft.range.end)
+ || draft.range.start < opening.start
+ || draft.range.end < draft.range.start
+ || draft.range.end > cursor
+ ) {
+ fail(
+ source,
+ "TEXT_COMPONENT_RANGE",
+ `Surface ${moduleKey(bound.module.ref)}#${bound.declaration.name} returned an invalid component source range.`,
+ opening.start,
+ );
+ }
+ if (draft.id.length === 0) {
+ fail(source, "TEXT_COMPONENT_ID", "Surface returned a component with an empty id.", draft.range.start);
+ }
+ if (componentIds.has(draft.id)) {
+ fail(source, "TEXT_COMPONENT_DUPLICATE", `Duplicate author component "${draft.id}".`, draft.range.start);
+ }
+ if (!isDigest(draft.fragment)) {
+ fail(source, "TEXT_COMPONENT_FRAGMENT", `${draft.id} returned an invalid Fragment digest.`, draft.range.start);
+ }
+ componentIds.add(draft.id);
+ componentRanges.set(draft.id, draft.range);
+ components.push({
+ id: draft.id,
+ fragment: draft.fragment,
+ inputs: draft.inputs,
+ outputs: draft.outputs,
+ });
+ }
+ for (const fragment of output.fragments) {
+ if (fragment.format !== "svml.fragment@1" || !isDigest(fragment.id)) {
+ fail(
+ source,
+ "TEXT_FRAGMENT_IDENTITY",
+ `Surface ${moduleKey(bound.module.ref)}#${bound.declaration.name} returned an invalid Graph Fragment identity.`,
+ opening.start,
+ );
+ }
+ const existing = fragments.get(fragment.id);
+ if (existing !== undefined && canonicalStringify(existing) !== canonicalStringify(fragment)) {
+ fail(source, "TEXT_FRAGMENT_CONFLICT", `Graph Fragment ${fragment.id} has conflicting definitions.`, opening.start);
+ }
+ fragments.set(fragment.id, fragment);
+ }
+ sourceMaps.push(...(output.sourceMaps ?? []));
}
if (!closed) {
fail(source, "TEXT_ROOT_UNCLOSED", "Document is missing </svml>.", source.text.length);
}
+ for (const component of components) {
+ if (!fragments.has(component.fragment)) {
+ fail(
+ source,
+ "TEXT_COMPONENT_FRAGMENT_MISSING",
+ `${component.id} references Fragment ${component.fragment} that no Surface contributed.`,
+ componentRanges.get(component.id)?.start,
+ );
+ }
+ }
+ const resolveImportedRef = (ref: AuthorValueRef): AuthorValueRef => {
+ const path = ref.kind === "record" ? ref.id : `${ref.component}.${ref.output}`;
+ return importedBindings.get(path)?.ref ?? ref;
+ };
+ const resolvedComponents = components.map((component) => ({
+ ...component,
+ inputs: Object.fromEntries(Object.entries(component.inputs).map(([name, ref]) => [
+ name,
+ resolveImportedRef(ref),
+ ])),
+ }));
+ const exports: AuthorSourceExport[] = records.map((record) => ({
+ name: record.id,
+ ref: { kind: "record", id: record.id },
+ type: record.type,
+ }));
+ const exportNames = new Set(exports.map((item) => item.name));
+ for (const component of resolvedComponents) {
+ const fragment = fragments.get(component.fragment) as GraphFragment;
+ for (const [output, name] of Object.entries(component.outputs)) {
+ if (exportNames.has(name)) fail(source, "TEXT_EXPORT_DUPLICATE", `Duplicate public export ${name}.`);
+ const declaration = fragment.exports.find((item) => item.name === output);
+ if (declaration === undefined) {
+ fail(source, "TEXT_COMPONENT_EXPORT", `${component.id} binds unknown Fragment export ${output}.`);
+ }
+ exportNames.add(name);
+ exports.push({
+ name,
+ ref: { kind: "component-output", component: component.id, output },
+ type: declaration.type,
+ });
+ }
+ }
return {
module: sealTypedModule({
id: `source:${source.name}`,
closureDigest: context.closure.digest,
records,
}),
+ author: sealAuthorModule({
+ name: `source:${source.name}`,
+ components: resolvedComponents,
+ }),
+ fragments: [...fragments.values()].sort((left, right) => left.id.localeCompare(right.id)),
+ exports: exports.sort((left, right) => left.name.localeCompare(right.name)),
imports: discovery.imports,
frontendClosureDigest,
sourceMaps,
@@ -230,3 +414,43 @@ export const textFrontend = {
discover: discoverText,
decode: decodeText,
} as const;
+
+/** Adapt the official Text decoder to the domain-neutral recursive Source Closure ABI. */
+export function createTextAuthorFrontend(options: TextAuthorFrontendOptions): TextAuthorFrontend {
+ return {
+ id: textAuthorFrontendId,
+ implementationDigest: textFrontendImplementationDigest,
+ discover(source) {
+ const discovery = discoverText(source);
+ return {
+ modules: discovery.imports.filter((item) => item.using === undefined).map((item) => item.from),
+ sources: discovery.imports
+ .filter((item): item is TextImportRequest & { alias: string; using: string } =>
+ item.using !== undefined && item.alias !== undefined)
+ .map((item) => ({
+ from: item.from,
+ alias: item.alias,
+ frontend: item.using,
+ range: item.range,
+ })),
+ };
+ },
+ decode(source, context) {
+ const result = decodeText(
+ { name: source.name, text: source.text },
+ {
+ closure: context.closure,
+ registry: options.registry,
+ resolveModule: options.resolveModule,
+ sourceImports: context.imports,
+ },
+ );
+ return {
+ module: result.module,
+ author: result.author,
+ fragments: result.fragments,
+ exports: result.exports,
+ };
+ },
+ };
+}
diff --git a/packages/text/src/index.ts b/packages/text/src/index.ts
index 5ddabc9c..a7a4e2d5 100644
--- a/packages/text/src/index.ts
+++ b/packages/text/src/index.ts
@@ -1,6 +1,8 @@
export { TextFrontendError } from "./error.js";
export {
decodeText,
+ createTextAuthorFrontend,
+ textAuthorFrontendId,
textFrontend,
textFrontendImplementationDigest,
textFrontendRef,
diff --git a/packages/text/src/types.ts b/packages/text/src/types.ts
index 5d4c1b71..e9979611 100644
--- a/packages/text/src/types.ts
+++ b/packages/text/src/types.ts
@@ -8,7 +8,17 @@ import type {
SurfaceDeclaration,
TypeRef,
TypedModule,
+ TypedRecord,
} from "@svml/protocol";
+import type {
+ AuthorComponent,
+ AuthorFrontend,
+ AuthorModule,
+ AuthorSourceExport,
+ AuthorValueRef,
+ GraphFragment,
+ ResolvedAuthorSourceImport,
+} from "@svml/elaborator";
export type SourceUnit = {
readonly name: string;
@@ -57,8 +67,15 @@ export type SurfaceRecordDraft = {
readonly range: SourceRange;
};
+/** Source-local diagnostics are removed before the component enters the semantic AuthorModule. */
+export type SurfaceComponentDraft = AuthorComponent & {
+ readonly range: SourceRange;
+};
+
export type SurfaceDecodeOutput = {
readonly records: readonly SurfaceRecordDraft[];
+ readonly components: readonly SurfaceComponentDraft[];
+ readonly fragments: readonly GraphFragment[];
readonly sourceMaps?: readonly CanonicalValue[];
};
@@ -78,6 +95,19 @@ export type RawSurfaceOutput = SurfaceDecodeOutput & {
export type StructuredSurfaceInput = {
readonly sourceName: string;
readonly element: StructuredElement;
+ /**
+ * Resolve an explicitly written author reference. Imported record values are
+ * available because their SourceUnit has already been compiled and admitted.
+ * A component output has a ref and Type but no compile-time Record value.
+ */
+ readonly resolveReference: (path: string) => SurfaceResolvedReference | undefined;
+};
+
+export type SurfaceResolvedReference = {
+ readonly path: string;
+ readonly ref: AuthorValueRef;
+ readonly type: TypeRef;
+ readonly record?: TypedRecord;
};
export type RawSurfaceHandler = (input: RawSurfaceInput) => RawSurfaceOutput;
@@ -95,15 +125,26 @@ export type TextDecodeContext = {
readonly closure: ResolvedModuleClosure;
readonly registry: TextSurfaceRegistryLike;
readonly resolveModule: (request: TextImportRequest) => ModuleRef;
+ readonly sourceImports?: readonly ResolvedAuthorSourceImport[];
};
export type TextDecodeResult = {
readonly module: TypedModule;
+ readonly author: AuthorModule;
+ readonly fragments: readonly GraphFragment[];
+ readonly exports: readonly AuthorSourceExport[];
readonly imports: readonly TextImportRequest[];
readonly frontendClosureDigest: Digest;
readonly sourceMaps: readonly CanonicalValue[];
};
+export type TextAuthorFrontendOptions = {
+ readonly registry: TextSurfaceRegistryLike;
+ readonly resolveModule: (request: TextImportRequest) => ModuleRef;
+};
+
+export type TextAuthorFrontend = AuthorFrontend;
+
export interface TextSurfaceRegistryLike {
resolve(module: ModuleRef, surface: string): RegisteredSurface | undefined;
}
diff --git a/packages/text/test/author-integration.test.ts b/packages/text/test/author-integration.test.ts
new file mode 100644
index 00000000..35038367
--- /dev/null
+++ b/packages/text/test/author-integration.test.ts
@@ -0,0 +1,326 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ createResolvedClosure,
+ digestOf,
+ link,
+ sealBuildRequest,
+ start,
+} from "@svml/core";
+import {
+ AuthorModuleError,
+ elaborateAuthorModule,
+ sealGraphFragment,
+} from "@svml/elaborator";
+import type { GraphFragment } from "@svml/elaborator";
+import type {
+ ModuleManifest,
+ ProducerRef,
+ TypeRef,
+} from "@svml/protocol";
+import {
+ TextFrontendError,
+ TextSurfaceRegistry,
+ decodeText,
+} from "@svml/text";
+import type {
+ StructuredElement,
+ TextAttributeValue,
+} from "@svml/text";
+
+const laboratory = { name: "example.text-laboratory", version: "1" } as const;
+const sampleType = { module: laboratory, name: "Sample" } satisfies TypeRef;
+const measurementType = { module: laboratory, name: "Measurement" } satisfies TypeRef;
+const reportType = { module: laboratory, name: "Report" } satisfies TypeRef;
+const measureProducer = { module: laboratory, name: "measure" } satisfies ProducerRef;
+const reportProducer = { module: laboratory, name: "write-report" } satisfies ProducerRef;
+const sampleSurfaceDigest = digestOf("example.text-laboratory/sample-surface@1");
+const measureSurfaceDigest = digestOf("example.text-laboratory/measure-surface@1");
+const reportSurfaceDigest = digestOf("example.text-laboratory/report-surface@1");
+
+const manifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: laboratory.name,
+ version: laboratory.version,
+ dependencies: [],
+ types: [
+ { name: sampleType.name, schema: { kind: "string", minLength: 1 } },
+ { name: measurementType.name, schema: { kind: "number" } },
+ { name: reportType.name, schema: { kind: "string", minLength: 1 } },
+ ],
+ capabilities: [],
+ surfaces: [
+ {
+ name: "sample",
+ tag: "Sample",
+ mode: "structured",
+ outputs: [sampleType],
+ implementation: {
+ kind: "trusted-frontend-surface",
+ locator: "example.text-laboratory/sample-surface",
+ digest: sampleSurfaceDigest,
+ },
+ },
+ {
+ name: "measure",
+ tag: "Measure",
+ mode: "structured",
+ outputs: [],
+ implementation: {
+ kind: "trusted-frontend-surface",
+ locator: "example.text-laboratory/measure-surface",
+ digest: measureSurfaceDigest,
+ },
+ },
+ {
+ name: "report",
+ tag: "Report",
+ mode: "structured",
+ outputs: [],
+ implementation: {
+ kind: "trusted-frontend-surface",
+ locator: "example.text-laboratory/report-surface",
+ digest: reportSurfaceDigest,
+ },
+ },
+ ],
+ producers: [
+ {
+ name: measureProducer.name,
+ inputs: [{ name: "sample", type: sampleType }],
+ outputs: [{ name: "measurement", type: measurementType }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.text-laboratory/measure",
+ digest: digestOf("example.text-laboratory/measure@1"),
+ },
+ },
+ {
+ name: reportProducer.name,
+ inputs: [{ name: "measurement", type: measurementType }],
+ outputs: [{ name: "report", type: reportType }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.text-laboratory/write-report",
+ digest: digestOf("example.text-laboratory/write-report@1"),
+ },
+ },
+ ],
+};
+
+function singleOperationFragment(
+ name: string,
+ inputName: string,
+ inputType: TypeRef,
+ producer: ProducerRef,
+ resultName: string,
+ resultType: TypeRef,
+): GraphFragment {
+ return sealGraphFragment({
+ name,
+ inputs: [{ name: inputName, type: inputType }],
+ operations: [{
+ id: "produce",
+ producer,
+ inputs: { [inputName]: { kind: "fragment-input", name: inputName } },
+ result: { kind: "output", name: resultName },
+ }],
+ exports: [{
+ name: "result",
+ type: resultType,
+ root: { kind: "fragment-operation", operation: "produce" },
+ semanticInputs: [inputName],
+ fidelity: "exact",
+ }],
+ });
+}
+
+const measureFragment = singleOperationFragment(
+ "measure-sample",
+ "sample",
+ sampleType,
+ measureProducer,
+ "measurement",
+ measurementType,
+);
+const reportFragment = singleOperationFragment(
+ "write-report",
+ "measurement",
+ measurementType,
+ reportProducer,
+ "report",
+ reportType,
+);
+
+function stringAttribute(element: StructuredElement, name: string): string {
+ const value = element.attributes[name];
+ if (typeof value !== "string" || value.length === 0) throw new Error(`${element.name}.${name} must be a string`);
+ return value;
+}
+
+function referenceAttribute(element: StructuredElement, name: string): string {
+ const value: TextAttributeValue | undefined = element.attributes[name];
+ if (typeof value !== "object" || value.kind !== "reference" || value.path.length === 0) {
+ throw new Error(`${element.name}.${name} must be a reference`);
+ }
+ return value.path;
+}
+
+function componentOutput(path: string): { readonly component: string; readonly output: string } {
+ const separator = path.lastIndexOf(".");
+ if (separator <= 0 || separator === path.length - 1) throw new Error(`${path} must name component.output`);
+ return { component: path.slice(0, separator), output: path.slice(separator + 1) };
+}
+
+function registry(options: { readonly omitMeasureFragment?: boolean } = {}): TextSurfaceRegistry {
+ const values = new TextSurfaceRegistry();
+ values.registerStructured(laboratory, "sample", sampleSurfaceDigest, ({ element }) => ({
+ records: [{
+ id: stringAttribute(element, "id"),
+ type: sampleType,
+ value: { kind: "inline", value: stringAttribute(element, "value") },
+ range: element.range,
+ }],
+ components: [],
+ fragments: [],
+ }));
+ values.registerStructured(laboratory, "measure", measureSurfaceDigest, ({ element }) => {
+ const id = stringAttribute(element, "id");
+ return {
+ records: [],
+ components: [{
+ id,
+ fragment: measureFragment.id,
+ inputs: { sample: { kind: "record", id: referenceAttribute(element, "sample") } },
+ outputs: { result: `${id}.result` },
+ range: element.range,
+ }],
+ fragments: options.omitMeasureFragment === true ? [] : [measureFragment],
+ };
+ });
+ values.registerStructured(laboratory, "report", reportSurfaceDigest, ({ element }) => {
+ const id = stringAttribute(element, "id");
+ const measurement = componentOutput(referenceAttribute(element, "measurement"));
+ return {
+ records: [],
+ components: [{
+ id,
+ fragment: reportFragment.id,
+ inputs: {
+ measurement: {
+ kind: "component-output",
+ component: measurement.component,
+ output: measurement.output,
+ },
+ },
+ outputs: { result: `${id}.result` },
+ range: element.range,
+ }],
+ fragments: [reportFragment],
+ };
+ });
+ return values;
+}
+
+const closure = createResolvedClosure([manifest]);
+
+function decode(text: string, surfaceRegistry = registry()) {
+ return decodeText(
+ { name: "laboratory.svml", text },
+ {
+ closure,
+ registry: surfaceRegistry,
+ resolveModule: () => laboratory,
+ },
+ );
+}
+
+test("Text Surfaces compile forward author references into a Core BuildPlan", () => {
+ const decoded = decode(`<svml>
+ <import as="lab" from="example.text-laboratory@1"/>
+ <lab:Sample id="soil" value="soil"/>
+ <lab:Report id="final" measurement={measurement.result}/>
+ <lab:Measure id="measurement" sample={soil}/>
+ </svml>`);
+
+ assert.deepEqual(decoded.author.components.map((component) => component.id), ["final", "measurement"]);
+ assert.deepEqual(decoded.fragments.map((fragment) => fragment.id).sort(), [
+ measureFragment.id,
+ reportFragment.id,
+ ].sort());
+
+ const program = link(closure, [decoded.module]);
+ const catalog = new Map(decoded.fragments.map((fragment) => [fragment.id, fragment]));
+ const elaborated = elaborateAuthorModule(program, decoded.author, (id) => catalog.get(id));
+ const state = start(program, elaborated.graph, sealBuildRequest({
+ graph: elaborated.graph.id,
+ targets: [{ output: "final.result", accepts: "exact" }],
+ bindings: [],
+ }));
+
+ assert.deepEqual(
+ state.plan.steps.map((step) => step.producer.name).sort(),
+ [measureProducer.name, reportProducer.name].sort(),
+ );
+ const measurementStep = state.plan.steps.find((step) => step.producer.name === measureProducer.name);
+ const reportStep = state.plan.steps.find((step) => step.producer.name === reportProducer.name);
+ assert.equal(reportStep?.inputs.measurement, measurementStep?.outputs.measurement);
+});
+
+test("component source reflow does not change AuthorModule semantic identity", () => {
+ const compact = decode(`<svml><import as="lab" from="example.text-laboratory@1"/><lab:Sample id="soil" value="soil"/><lab:Measure id="measurement" sample={soil}/></svml>`);
+ const multiline = decode(`<svml>
+ <import as="lab" from="example.text-laboratory@1"/>
+ <lab:Sample
+ id="soil"
+ value="soil"
+ />
+ <lab:Measure
+ id="measurement"
+ sample={soil}
+ />
+ </svml>`);
+ assert.equal(compact.author.id, multiline.author.id);
+});
+
+test("Text rejects a component whose Surface omits its Fragment definition", () => {
+ assert.throws(
+ () => decode(`<svml>
+ <import as="lab" from="example.text-laboratory@1"/>
+ <lab:Sample id="soil" value="soil"/>
+ <lab:Measure id="measurement" sample={soil}/>
+ </svml>`, registry({ omitMeasureFragment: true })),
+ (error: unknown) => error instanceof TextFrontendError
+ && error.code === "TEXT_COMPONENT_FRAGMENT_MISSING",
+ );
+});
+
+test("unknown component references remain inert until whole-document Author linking", () => {
+ const decoded = decode(`<svml>
+ <import as="lab" from="example.text-laboratory@1"/>
+ <lab:Report id="final" measurement={missing.result}/>
+ </svml>`);
+ const program = link(closure, [decoded.module]);
+ const catalog = new Map(decoded.fragments.map((fragment) => [fragment.id, fragment]));
+ assert.throws(
+ () => elaborateAuthorModule(program, decoded.author, (id) => catalog.get(id)),
+ (error: unknown) => error instanceof AuthorModuleError
+ && error.code === "UNKNOWN_AUTHOR_COMPONENT",
+ );
+});
+
+test("Text rejects duplicate component identities before Author linking", () => {
+ assert.throws(
+ () => decode(`<svml>
+ <import as="lab" from="example.text-laboratory@1"/>
+ <lab:Sample id="soil" value="soil"/>
+ <lab:Measure id="measurement" sample={soil}/>
+ <lab:Measure id="measurement" sample={soil}/>
+ </svml>`),
+ (error: unknown) => error instanceof TextFrontendError
+ && error.code === "TEXT_COMPONENT_DUPLICATE",
+ );
+});
diff --git a/packages/text/test/text.test.ts b/packages/text/test/text.test.ts
index 0aad37f9..54d4173a 100644
--- a/packages/text/test/text.test.ts
+++ b/packages/text/test/text.test.ts
@@ -1,7 +1,7 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { contractsManifest } from "@svml/contracts";
+import { narrativeManifest } from "@svml/contracts";
import { createResolvedClosure, digestOf, isDigest, link } from "@svml/core";
import type { ModuleManifest } from "@svml/protocol";
import {
@@ -18,7 +18,7 @@ import {
} from "@svml/text";
function scriptContext() {
- const closure = createResolvedClosure([contractsManifest, scriptManifest]);
+ const closure = createResolvedClosure([narrativeManifest, scriptManifest]);
const registry = new TextSurfaceRegistry();
registry.registerRaw(
scriptModuleRef,
@@ -100,13 +100,18 @@ test("without the import, Text has no hard-coded knowledge of Script", () => {
});
test("a raw Surface cannot consume the Text document close", () => {
- const closure = createResolvedClosure([contractsManifest, scriptManifest]);
+ const closure = createResolvedClosure([narrativeManifest, scriptManifest]);
const registry = new TextSurfaceRegistry();
registry.registerRaw(
scriptModuleRef,
"script",
scriptSurfaceImplementationDigest,
- (input) => ({ nextOffset: input.source.length, records: [] }),
+ (input) => ({
+ nextOffset: input.source.length,
+ records: [],
+ components: [],
+ fragments: [],
+ }),
);
assert.throws(
() => decodeText(
@@ -204,6 +209,8 @@ test("a module can use Text's generic structured parser without adding another p
range: element.range,
},
],
+ components: [],
+ fragments: [],
}));
const result = decodeText(
{
@@ -226,6 +233,8 @@ test("a module can use Text's generic structured parser without adding another p
range: element.range,
},
],
+ components: [],
+ fragments: [],
}));
assert.throws(
() => decodeText(
diff --git a/packages/validation/README.md b/packages/validation/README.md
new file mode 100644
index 00000000..0643c540
--- /dev/null
+++ b/packages/validation/README.md
@@ -0,0 +1,31 @@
+# `@svml/validation`
+
+Host-side admission for package-owned semantic Types.
+
+A module owns the meaning of every `TypeRef` it declares. Core always checks the Type's structural
+Schema. When structure is insufficient, the owner may also lock a pure validator implementation in
+its static Manifest using `svml.type-validator@1`. The reference Host registers that exact Type and
+implementation digest here.
+
+`validateValue()` runs the owner validator and returns a content-bound validation receipt.
+`admitRecord()` applies the same gate to authored or externally provided Records. `NodeDriver`
+applies it to Producer and Provider results before creating an Event. Core neither executes the
+validator nor learns the domain meaning: it verifies that a required receipt names the exact
+nominal Type, Record digest and validator digest locked by the resolved Module Closure.
+
+Validators are refinements, not converters. They may accept or reject a value; they may not rewrite
+it, create graph edges, select a Provider, read credentials or add author intent. Cross-package
+communication therefore remains decentralized:
+
+```text
+Type owner Manifest -> nominal Type + Schema + optional validator digest
+Producer package -> emits that exact TypeRef
+Consumer package -> accepts that exact TypeRef
+Host admission -> executes the locked validator
+Core -> verifies graph typing, Schema and receipt bindings
+```
+
+The current reference registry executes trusted in-process handlers. A validation receipt is a
+content-bound Host assertion, not a cryptographic attestation from arbitrary third-party code.
+Community validator execution still requires the planned code-byte verification, resource limits
+and sandbox/worker boundary. Until then only trusted installed implementations may be registered.
diff --git a/packages/validation/package.json b/packages/validation/package.json
new file mode 100644
index 00000000..8062280f
--- /dev/null
+++ b/packages/validation/package.json
@@ -0,0 +1,13 @@
+{
+ "name": "@svml/validation",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "dependencies": {
+ "@svml/core": "workspace:*",
+ "@svml/protocol": "workspace:*"
+ }
+}
diff --git a/packages/validation/src/index.ts b/packages/validation/src/index.ts
new file mode 100644
index 00000000..42a3450e
--- /dev/null
+++ b/packages/validation/src/index.ts
@@ -0,0 +1,152 @@
+import {
+ isDigest,
+ recordDigest,
+ resolveType,
+ sealRecord,
+ sealTypeValidationReceipt,
+ validateStoredValue,
+ verifyRecord,
+ verifyRecordStructure,
+} from "@svml/core";
+import type {
+ Digest,
+ ResolvedModuleClosure,
+ StoredValue,
+ TypeRef,
+ TypeValidationReceipt,
+ TypedRecord,
+} from "@svml/protocol";
+
+function typeKey(type: TypeRef): string {
+ return `${type.module.name}@${type.module.version}#${type.name}`;
+}
+
+function sameType(left: TypeRef, right: TypeRef): boolean {
+ return left.module.name === right.module.name
+ && left.module.version === right.module.version
+ && left.name === right.name;
+}
+
+export type TypeValidatorContext = {
+ readonly type: TypeRef;
+ readonly value: StoredValue;
+};
+
+export type TypeValidatorHandler = (
+ context: TypeValidatorContext,
+) => void | Promise<void>;
+
+export type TypeValidatorRegistration = {
+ readonly type: TypeRef;
+ readonly implementationDigest: Digest;
+ readonly handler: TypeValidatorHandler;
+};
+
+export interface TypeValidatorRegistryLike {
+ resolve(type: TypeRef): TypeValidatorRegistration | undefined;
+}
+
+export class TypeValidationError extends Error {
+ readonly code: string;
+ readonly subject: string | undefined;
+
+ constructor(code: string, message: string, subject?: string) {
+ super(message);
+ this.name = "TypeValidationError";
+ this.code = code;
+ this.subject = subject;
+ }
+}
+
+export class TypeValidatorRegistry implements TypeValidatorRegistryLike {
+ readonly #validators = new Map<string, TypeValidatorRegistration>();
+
+ register(
+ type: TypeRef,
+ implementationDigest: Digest,
+ handler: TypeValidatorHandler,
+ ): void {
+ const key = typeKey(type);
+ if (!isDigest(implementationDigest)) {
+ throw new TypeValidationError("INVALID_TYPE_VALIDATOR_DIGEST", `${key} validator digest is invalid`, key);
+ }
+ if (this.#validators.has(key)) {
+ throw new TypeValidationError("DUPLICATE_TYPE_VALIDATOR", `${key} validator is already registered`, key);
+ }
+ this.#validators.set(key, { type, implementationDigest, handler });
+ }
+
+ resolve(type: TypeRef): TypeValidatorRegistration | undefined {
+ return this.#validators.get(typeKey(type));
+ }
+}
+
+export async function validateValue(
+ closure: ResolvedModuleClosure,
+ type: TypeRef,
+ value: StoredValue,
+ registry: TypeValidatorRegistryLike,
+): Promise<TypeValidationReceipt | undefined> {
+ const declaration = resolveType(closure, type);
+ validateStoredValue(value, declaration.schema, `$validation.${typeKey(type)}`);
+ if (declaration.validator === undefined) return undefined;
+ const registration = registry.resolve(type);
+ if (registration === undefined) {
+ throw new TypeValidationError("MISSING_TYPE_VALIDATOR", `${typeKey(type)} validator is not registered`, typeKey(type));
+ }
+ if (!sameType(registration.type, type)) {
+ throw new TypeValidationError(
+ "TYPE_VALIDATOR_REGISTRATION_MISMATCH",
+ `${typeKey(type)} registry returned another nominal Type`,
+ typeKey(type),
+ );
+ }
+ if (registration.implementationDigest !== declaration.validator.implementation.digest) {
+ throw new TypeValidationError(
+ "TYPE_VALIDATOR_IMPLEMENTATION_MISMATCH",
+ `${typeKey(type)} validator does not match the locked Manifest`,
+ typeKey(type),
+ );
+ }
+ try {
+ await registration.handler({ type: structuredClone(type), value: structuredClone(value) });
+ } catch (error) {
+ throw new TypeValidationError(
+ "TYPE_REFINEMENT_REJECTED",
+ `${typeKey(type)} rejected the value: ${error instanceof Error ? error.message : String(error)}`,
+ typeKey(type),
+ );
+ }
+ return sealTypeValidationReceipt({
+ type,
+ recordDigest: recordDigest(type, value),
+ validatorDigest: registration.implementationDigest,
+ });
+}
+
+export async function admitRecord(
+ closure: ResolvedModuleClosure,
+ record: TypedRecord,
+ registry: TypeValidatorRegistryLike,
+): Promise<TypedRecord> {
+ const {
+ digest: _digest,
+ validation: _validation,
+ ...draft
+ } = record;
+ const unvalidated = sealRecord(draft);
+ verifyRecordStructure(closure, unvalidated);
+ const validation = await validateValue(closure, record.type, record.value, registry);
+ const admitted = sealRecord({
+ ...draft,
+ ...(validation === undefined ? {} : { validation }),
+ });
+ verifyRecord(closure, admitted);
+ return admitted;
+}
+
+export function createRecordAdmitter(
+ registry: TypeValidatorRegistryLike,
+): (closure: ResolvedModuleClosure, record: TypedRecord) => Promise<TypedRecord> {
+ return async (closure, record) => await admitRecord(closure, record, registry);
+}
diff --git a/packages/whisperx/src/manifest.ts b/packages/whisperx/src/manifest.ts
index bb428f9d..0ca415cc 100644
--- a/packages/whisperx/src/manifest.ts
+++ b/packages/whisperx/src/manifest.ts
@@ -1,8 +1,7 @@
import {
alignedTranscriptEvidenceFields,
contractTypes,
- contractsManifestDigest,
- contractsModuleRef,
+ videoContractDependencies,
} from "@svml/contracts";
import { digestOf } from "@svml/core";
import type { CapabilityRef, ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@svml/protocol";
@@ -39,7 +38,10 @@ export const whisperXManifest: ModuleManifest = {
format: "svml.module@0",
name: whisperXModuleRef.name,
version: whisperXModuleRef.version,
- dependencies: [{ module: contractsModuleRef, digest: contractsManifestDigest }],
+ dependencies: [
+ videoContractDependencies.speech,
+ videoContractDependencies.semanticTime,
+ ],
types: [{ name: whisperXTypes.alignmentEvidence.name, schema: whisperXAlignmentEvidenceSchema }],
capabilities: [{
name: whisperXCapabilities.alignment.name,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 329ffb12..7f568566 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -22,14 +22,24 @@ importers:
specifier: 5.9.3
version: 5.9.3
- packages/caption:
+ packages/broll:
dependencies:
'@svml/contracts':
specifier: workspace:*
version: link:../contracts
- '@svml/core':
+ '@svml/protocol':
specifier: workspace:*
- version: link:../core
+ version: link:../protocol
+ devDependencies:
+ '@svml/hyperframes':
+ specifier: workspace:*
+ version: link:../hyperframes
+
+ packages/caption:
+ dependencies:
+ '@svml/contracts':
+ specifier: workspace:*
+ version: link:../contracts
'@svml/protocol':
specifier: workspace:*
version: link:../protocol
@@ -41,6 +51,55 @@ importers:
specifier: workspace:*
version: link:../speech-align
+ packages/cli:
+ dependencies:
+ '@svml/compiler-node':
+ specifier: workspace:*
+ version: link:../compiler-node
+ '@svml/contracts':
+ specifier: workspace:*
+ version: link:../contracts
+ '@svml/elaborator':
+ specifier: workspace:*
+ version: link:../elaborator
+ '@svml/film':
+ specifier: workspace:*
+ version: link:../film
+ '@svml/hyperframes':
+ specifier: workspace:*
+ version: link:../hyperframes
+ '@svml/hyperframes-render':
+ specifier: workspace:*
+ version: link:../hyperframes-render
+ '@svml/script':
+ specifier: workspace:*
+ version: link:../script
+ '@svml/svs':
+ specifier: workspace:*
+ version: link:../svs
+ '@svml/text':
+ specifier: workspace:*
+ version: link:../text
+
+ packages/compiler-node:
+ dependencies:
+ '@svml/core':
+ specifier: workspace:*
+ version: link:../core
+ '@svml/elaborator':
+ specifier: workspace:*
+ version: link:../elaborator
+ '@svml/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@svml/validation':
+ specifier: workspace:*
+ version: link:../validation
+ devDependencies:
+ '@svml/text':
+ specifier: workspace:*
+ version: link:../text
+
packages/contracts:
dependencies:
'@svml/protocol':
@@ -61,6 +120,12 @@ importers:
'@svml/protocol':
specifier: workspace:*
version: link:../protocol
+ '@svml/runtime':
+ specifier: workspace:*
+ version: link:../runtime
+ '@svml/validation':
+ specifier: workspace:*
+ version: link:../validation
devDependencies:
'@svml/caption':
specifier: workspace:*
@@ -94,6 +159,74 @@ importers:
specifier: workspace:*
version: link:../speech-take
+ packages/film:
+ dependencies:
+ '@svml/contracts':
+ specifier: workspace:*
+ version: link:../contracts
+ '@svml/elaborator':
+ specifier: workspace:*
+ version: link:../elaborator
+ '@svml/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@svml/svs':
+ specifier: workspace:*
+ version: link:../svs
+ '@svml/text':
+ specifier: workspace:*
+ version: link:../text
+ devDependencies:
+ '@svml/core':
+ specifier: workspace:*
+ version: link:../core
+ '@svml/driver-node':
+ specifier: workspace:*
+ version: link:../driver-node
+ '@svml/hyperframes':
+ specifier: workspace:*
+ version: link:../hyperframes
+ '@svml/text-track':
+ specifier: workspace:*
+ version: link:../text-track
+
+ packages/hyperframes:
+ dependencies:
+ '@svml/contracts':
+ specifier: workspace:*
+ version: link:../contracts
+ '@svml/elaborator':
+ specifier: workspace:*
+ version: link:../elaborator
+ '@svml/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+
+ packages/hyperframes-render:
+ dependencies:
+ '@svml/contracts':
+ specifier: workspace:*
+ version: link:../contracts
+ '@svml/elaborator':
+ specifier: workspace:*
+ version: link:../elaborator
+ '@svml/hyperframes':
+ specifier: workspace:*
+ version: link:../hyperframes
+ '@svml/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@svml/text':
+ specifier: workspace:*
+ version: link:../text
+ devDependencies:
+ '@svml/core':
+ specifier: workspace:*
+ version: link:../core
+ '@svml/driver-node':
+ specifier: workspace:*
+ version: link:../driver-node
+
packages/protocol: {}
packages/realization:
@@ -108,6 +241,18 @@ importers:
'@svml/elaborator':
specifier: workspace:*
version: link:../elaborator
+ '@svml/validation':
+ specifier: workspace:*
+ version: link:../validation
+
+ packages/runtime:
+ dependencies:
+ '@svml/core':
+ specifier: workspace:*
+ version: link:../core
+ '@svml/protocol':
+ specifier: workspace:*
+ version: link:../protocol
packages/script:
dependencies:
@@ -137,6 +282,43 @@ importers:
specifier: workspace:*
version: link:../script
+ packages/speech-program:
+ dependencies:
+ '@svml/caption':
+ specifier: workspace:*
+ version: link:../caption
+ '@svml/contracts':
+ specifier: workspace:*
+ version: link:../contracts
+ '@svml/elaborator':
+ specifier: workspace:*
+ version: link:../elaborator
+ '@svml/speech-align':
+ specifier: workspace:*
+ version: link:../speech-align
+ '@svml/speech-take':
+ specifier: workspace:*
+ version: link:../speech-take
+ '@svml/whisperx':
+ specifier: workspace:*
+ version: link:../whisperx
+ devDependencies:
+ '@svml/core':
+ specifier: workspace:*
+ version: link:../core
+ '@svml/driver-node':
+ specifier: workspace:*
+ version: link:../driver-node
+ '@svml/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@svml/realization':
+ specifier: workspace:*
+ version: link:../realization
+ '@svml/script':
+ specifier: workspace:*
+ version: link:../script
+
packages/speech-take:
dependencies:
'@svml/contracts':
@@ -153,11 +335,30 @@ importers:
specifier: workspace:*
version: link:../driver-node
+ packages/svs:
+ dependencies:
+ '@svml/core':
+ specifier: workspace:*
+ version: link:../core
+ '@svml/elaborator':
+ specifier: workspace:*
+ version: link:../elaborator
+ '@svml/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ devDependencies:
+ '@svml/text':
+ specifier: workspace:*
+ version: link:../text
+
packages/text:
dependencies:
'@svml/core':
specifier: workspace:*
version: link:../core
+ '@svml/elaborator':
+ specifier: workspace:*
+ version: link:../elaborator
'@svml/protocol':
specifier: workspace:*
version: link:../protocol
@@ -169,42 +370,30 @@ importers:
specifier: workspace:*
version: link:../script
- packages/video-fragments:
+ packages/text-track:
dependencies:
- '@svml/caption':
- specifier: workspace:*
- version: link:../caption
'@svml/contracts':
specifier: workspace:*
version: link:../contracts
'@svml/elaborator':
specifier: workspace:*
version: link:../elaborator
- '@svml/speech-align':
- specifier: workspace:*
- version: link:../speech-align
- '@svml/speech-take':
- specifier: workspace:*
- version: link:../speech-take
- '@svml/whisperx':
+ '@svml/protocol':
specifier: workspace:*
- version: link:../whisperx
+ version: link:../protocol
devDependencies:
+ '@svml/hyperframes':
+ specifier: workspace:*
+ version: link:../hyperframes
+
+ packages/validation:
+ dependencies:
'@svml/core':
specifier: workspace:*
version: link:../core
- '@svml/driver-node':
- specifier: workspace:*
- version: link:../driver-node
'@svml/protocol':
specifier: workspace:*
version: link:../protocol
- '@svml/realization':
- specifier: workspace:*
- version: link:../realization
- '@svml/script':
- specifier: workspace:*
- version: link:../script
packages/whisperx:
dependencies:
diff --git a/spec/author-surface-binding-v1.md b/spec/author-surface-binding-v1.md
new file mode 100644
index 00000000..d950f220
--- /dev/null
+++ b/spec/author-surface-binding-v1.md
@@ -0,0 +1,149 @@
+# Author Surface Binding v1
+
+Status: implemented compiler contract for trusted package-owned Surfaces; third-party isolation is
+not yet implemented.
+
+## 1. Purpose
+
+The generic Markup Frontend owns element syntax. A package-owned Surface owns what one imported tag
+means. SVS owns only its stylesheet syntax and produces generic immutable Recipe records. Neither
+Markup, SVS nor Core owns Caption, B-roll, Film or another package's property vocabulary.
+
+The missing bridge is compile-time reference inspection: a Surface such as Caption must be able to
+read an explicitly referenced public Recipe and lower it into a nominal `CaptionProgram` before the
+Core graph is built.
+
+This document defines that bridge without adding a global Recipe registry or a Runtime step.
+
+## 2. Ordered compilation boundary
+
+One Source Closure compiles in this order:
+
+```text
+recursive imported SourceUnits
+ -> admitted public Records and symbolic component exports
+ -> current document generic syntax
+ -> package-owned Surface compilation
+ -> typed authored Records + AuthorComponents + locked GraphFragments
+ -> parser-independent Author linking
+ -> Core CompiledGraph
+```
+
+An imported `.svs` SourceUnit therefore finishes before a consuming `.svml` SourceUnit. The
+consuming Surface receives the structured element and a resolver for references explicitly written
+in that element.
+
+## 3. Reference result
+
+A resolved Surface reference contains:
+
+```text
+path source spelling used by the element
+ref hygienic AuthorValueRef
+type exact nominal TypeRef
+record? defensively copied TypedRecord when the public export is already an authored Record
+```
+
+A component output has no compile-time Record and therefore omits `record`. A Surface that needs to
+inspect a value, such as a Recipe decoder, must require an authored Record and fail during `check`
+when the reference is unresolved, has the wrong Type, or has no value yet.
+
+Only public record exports of an imported SourceUnit are exposed. Private child records are not
+part of the resolver. Every returned Record is a defensive canonical copy so Surface code cannot
+rewrite an already compiled child SourceUnit or a previous declaration.
+
+## 4. Package ownership
+
+For this source:
+
+```svml
+<caption:Track appearance={studio.caption.dialogue}/>
+```
+
+the responsibilities are:
+
+```text
+@svml/svs
+ parses studio.svs
+ produces generic @svml/svs#Recipe
+
+@svml/markup
+ parses the element and the whole-value reference
+ resolves only the public imported binding
+
+@svml/caption Surface
+ requires @svml/svs#Recipe
+ validates Caption-owned properties
+ emits nominal @svml/caption#CaptionTrackProgram
+ emits the AuthorComponent and locked GraphFragment
+
+Author compiler
+ resolves symbolic component dependencies and types
+
+Core
+ sees only typed Records, LogicalOutputs, Candidates and Operations
+```
+
+There is no universal property table. Another package may interpret the same generic Recipe through
+another explicitly imported Surface and produce a different nominal Program. The Surface is never
+selected by the Recipe shape; the author selected it by writing the namespaced component.
+
+## 5. Surface output law
+
+A Surface may emit only:
+
+1. authored Records whose exact Type appears in its locked Manifest `outputs` allowlist;
+2. AuthorComponents whose Fragment digest is contributed by that decode result;
+3. immutable GraphFragments;
+4. non-semantic source-map facts.
+
+The Frontend seals authored Record provenance with source and Frontend Closure identity, verifies
+its structural Type, and passes it through the Host admission gate before linking. A Surface cannot
+inject a Record of another undeclared Type.
+
+A typed Program derived from a Recipe should contain any source digest required by its package's
+semantic validation. Its authored provenance already binds the Surface implementation digest and
+the recursively compiled Source Closure. Alias spelling and filesystem location may change source
+identity without changing the typed Program value or resulting Graph meaning.
+
+## 6. Forward-reference law
+
+Two cases are intentionally different:
+
+- Graph dependencies may remain symbolic `component.output` references and are resolved after the
+ complete document is collected, so ordinary component forward references remain valid.
+- Compile-time value inspection requires an already compiled authored Record. Imported sources are
+ always available; same-document value definitions must appear before a Surface that inspects
+ them.
+
+This is not a parser mode or Runtime mode. It follows from whether compilation needs the value now
+or only needs a typed graph edge later.
+
+## 7. What this is not
+
+Surface Binding is not:
+
+- a Core Type registry;
+- an implicit conversion search;
+- a Runtime Producer or paid Operation;
+- a Provider capability;
+- a global SVS decoder;
+- permission to read credentials, files, network or stores.
+
+The current Host executes only explicitly registered trusted Surface implementations. Locked code
+bytes, permission enforcement and isolation are required before arbitrary community Surface code
+can execute.
+
+## 8. Executable proof
+
+The non-video `example.recipe-card` fixture proves the boundary:
+
+1. SVS emits a generic Recipe;
+2. the Card Surface reads only its explicit public reference;
+3. Card validates `fill` and `padding` during author compilation;
+4. Card emits a nominal `CardAppearance` Record;
+5. the runtime Producer consumes `CardAppearance`, not `SVS Recipe`;
+6. an invalid color fails before a BuildPlan or external operation exists;
+7. changing only the source-import alias preserves the Program Record and Graph identities.
+
+Video packages must use this same mechanism rather than adding a video-specific compiler path.
diff --git a/spec/core-kernel-v0.md b/spec/core-kernel-v0.md
index 9769ff90..bb7fb6a9 100644
--- a/spec/core-kernel-v0.md
+++ b/spec/core-kernel-v0.md
@@ -1,6 +1,7 @@
# SVML Core Kernel v0
-Status: executable bootstrap contract; deliberately incomplete.
+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,
diff --git a/spec/core-kernel-v1.md b/spec/core-kernel-v1.md
new file mode 100644
index 00000000..9bfa8da0
--- /dev/null
+++ b/spec/core-kernel-v1.md
@@ -0,0 +1,73 @@
+# SVML Core Kernel v1
+
+Status: current executable v2 contract.
+
+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.
+
+## 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.
+
+## Boundary
+
+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.
+
+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.
+
+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.
diff --git a/spec/track-composition-v1.md b/spec/track-composition-v1.md
new file mode 100644
index 00000000..ee2aa9da
--- /dev/null
+++ b/spec/track-composition-v1.md
@@ -0,0 +1,121 @@
+# SVML Track and Composition v1
+
+Status: first executable v2 contract candidate; public freeze is gated by
+[`track-expressiveness-v1.md`](./track-expressiveness-v1.md).
+
+## Law
+
+Except for the shared ProgramSpace and canvas geometry, every audiovisual contribution entering a
+Composition is a peer Track. Composition validates, orders and combines Tracks. It does not know
+Caption, Speech, B-roll, Text, Seedance or any author-package family.
+
+```text
+Speech visual ───────────────> VisualTrack ─┐
+B-roll ──────────────────────> VisualTrack ─┤
+TimedCaption + style/cues ───> VisualTrack ─┤
+Text + style ────────────────> VisualTrack ─┼─> Composition
+Vignette / overlay ──────────> VisualTrack ─┤
+Speech audio / BGM / SFX ────> AudioTrack ──┘
+```
+
+## ProgramSpace
+
+ProgramSpace owns duration and exact rational frame rate. Its duration must end on an integer frame
+boundary. Every Track carries the digest of exactly one ProgramSpace; Composition rejects a Track
+from another space even when duration and type happen to look compatible.
+
+Canvas width, height and clear color are structural Composition facts. No video Track defines
+duration or becomes a privileged Base.
+
+## VisualTrack
+
+A VisualTrack is an author-package ownership and provenance boundary. It owns zero or more
+frame-exact `VisualPresent` values; every Present owns its own absolute `(order, tieBreak)` stacking
+key and one self-contained, code-free element tree made from box, text, ordinary media and typed
+compositable-Surface primitives. Parent references are Present-local. Media and exact font faces
+enter through content-addressed Artifact references rather than CSS URLs or environment font names.
+Every Track also carries named semantic source digests. Producer affinity declarations bind those
+generic commitments to upstream facts without adding Caption, Speech or B-roll fields to the Track
+contract.
+
+Composition flattens Presents across every Track before ordering them. One B-roll package may
+therefore own a board at z=30 and an icon at z=80 while a Text Present from another Track sits at
+z=50. A z change over time is represented by two non-overlapping Presents with different stacking
+keys. Track ownership never creates a render stacking context.
+
+Every element may optionally carry frame-exact local keyframes over opacity, transform, filter or
+clip-path. Those keyframes operate only on that Present's element tree. A B-roll package may lower a
+pair transition into complementary animations on two of its own Presents without teaching
+Composition the name or semantics of that transition.
+
+VisualTrack deliberately has no:
+
+- family or source-kind field;
+- sibling Track or Present reference;
+- arbitrary script or global CSS selector;
+- backdrop filtering or blend mode that samples lower Tracks;
+- cross-Track mask, intersection or transition input.
+
+A local filter, crop, transform, animation or transition is valid when it operates only on materials
+explicitly owned by the authoring package and lowers to self-contained Presents. An effect that needs
+two raw materials must receive both explicitly before final Track lowering. No Present may sample
+the accumulated lower composite.
+
+## AudioTrack
+
+An AudioTrack owns frame-exact clips, typed Artifacts, playback mapping, gain, fades and an optional
+mix bus. It has no visual stacking key and no special relationship to a Speech Track. Speech audio,
+music, source audio and sound effects use the same contract.
+
+## Composition
+
+Composition contains one ProgramSpace, one canvas and a set of VisualTrack/AudioTrack values. It:
+
+1. validates every Track digest and ProgramSpace affinity;
+2. rejects duplicate Track identities and duplicate visual stacking keys;
+3. flattens every VisualPresent and mounts it by absolute `(order, tieBreak)`;
+4. mixes AudioTrack clips in ProgramSpace;
+5. produces the input to the HyperFrames compilation package.
+
+Composition must not switch on an author-domain family or grant a Track special access to accumulated
+lower pixels. A global shatter, adjustment layer, Base FX lane or B-roll underlay transition is
+therefore not part of this version. No dedicated Base FX placeholder is reserved.
+
+TimedCaptionProjection remains an intermediate semantic value. Caption grouping, style and cue
+lowering must finish before the caption enters Composition as an ordinary VisualTrack.
+
+## HyperFrames boundary
+
+`@svml/hyperframes` consumes only the generic Composition contract. It never switches on Speech,
+Caption, B-roll or author-package identity. It deterministically emits a content-addressed
+`HyperframesDocument` whose HTML interleaves VisualPresents by absolute stacking key and carries
+AudioTrack clips on the same ProgramSpace. It must not mount an authoring Track as one isolated
+visual wrapper.
+
+The document MUST bind `programSpaceDigest`, exact rational frame rate, positive integer frame
+count, canvas dimensions, Artifact set and generated HTML. Its complete visual frame domain is the
+half-open interval `[0, frameCount)`. Rendering frame `n` must depend only on this immutable document,
+its exact Artifacts, the locked renderer implementation and `n`; it must not require sequentially
+evaluating frames `0..n-1`. Stateful author effects must therefore be materialized into a typed
+Surface before entering this boundary.
+
+Frame partitioning is Runtime policy. A conforming Endpoint may split the domain into any set of
+non-overlapping half-open spans whose ordered union is `[0, frameCount)`, evaluate them locally or
+remotely, retry individual spans, then assemble visual chunks and mux audio once. Those spans are
+not author declarations, Core Operations or Track identities. The fulfilled render Product must
+repeat the exact document/frame-domain/canvas bindings; affinity rejects a result assembled for a
+different domain.
+
+The compiled document contains `svml-artifact://` placeholders, not local paths, API URLs or signed
+URLs. Resolving those placeholders is a Runtime/Provider action immediately before rendering. Thus
+one compiled document can be rendered locally or remotely without changing author intent or its
+compiled identity. Exact text becomes generated `@font-face` rules with font synthesis disabled.
+Typed Surfaces preserve declared dimensions, color space, alpha mode and still/frame timing across
+the same Artifact boundary; they are not inferred from filename extensions.
+
+`@svml/film` now implements package-level arbitrary-arity assembly as a finite immutable TrackSet
+fold followed by ordinary Composition and HyperFrames Operations. Core receives only fixed-port,
+single-result Operations, and Targeting an intermediate Track or Composition does not demand the
+rest of the Film chain. This specification still does not define the author-facing Film Surface;
+that Surface must lower into the implemented Fragment without adding Track families to Core or
+making one Track depend on accumulated sibling pixels.
diff --git a/spec/track-expressiveness-v1.md b/spec/track-expressiveness-v1.md
new file mode 100644
index 00000000..b5d1ed86
--- /dev/null
+++ b/spec/track-expressiveness-v1.md
@@ -0,0 +1,147 @@
+# SVML Track Expressiveness Gate v1
+
+Status: executable validation gate; not yet a frozen public Track ABI.
+
+## Purpose
+
+One public Track contract must solve final audiovisual composition without pretending that every
+author package shares one authoring model. Text, Caption, B-roll, Ranking and future packages own
+their Programs and may revise those Programs independently. They may enter Composition only after
+lowering their package-specific meanings into self-contained, frame-exact contributions.
+
+This gate answers one question:
+
+> Can production-used text, media-box, caption, stacking and local-effect behavior lower into the
+> same Track waist without adding package-family fields to Track, Composition or Core?
+
+Passing this gate does not make one universal `TrackProgram`. The six Track Program axes—content,
+temporal source, window projection, spatial source, occupancy and presentation—remain a separation
+discipline for package authors, not six mandatory public fields.
+
+## Three levels that must not collapse
+
+```text
+Package Program Resolved package facts Public Track
+─────────────────────── ──────────────────────────── ─────────────────────
+TextLayout / CaptionMode boxes, glyph runs, windows Presents
+Media sampling policy -> source-time and crop mapping -> exact frame spans
+effect recipe local animations absolute stacking
+semantic/spatial locator final placement self-contained elements
+```
+
+The Package Program is editable author truth. Resolved package facts are compiler evidence. The
+public Track is a terminal audiovisual contribution. Composition must never reconstruct the first
+two levels from the third.
+
+"Flat Track" means there is no Track nesting or implicit Track stacking context. A Present may
+still own an internal element tree. One authoring Track may emit several Presents at unrelated
+absolute stack positions so that peer Tracks can interleave between them.
+
+## Required witnesses
+
+### E1 — Text three-box lowering
+
+The official browser-oriented reference lowering must represent independently:
+
+1. an outer placement frame;
+2. an inner layout box controlling wrapping, alignment, direction and overflow;
+3. paint targets for the complete frame, shrink-wrapped content, each line or each word.
+
+Paint overflow such as glow or shadow must not become a line-measurement input merely because it is
+visible outside the content box. A package may lower a paint target by attaching paint to a
+different owned element; the public Track must not acquire a `textBackgroundTarget` field.
+
+### E2 — Caption range/cue/content lowering
+
+A Caption package must be able to lower a hard range boundary, a cue-level alignment/animation
+container, shrink-wrapped rows and independently styled or animated words. Dual-font and per-word
+paint are package facts. Composition sees only ordinary elements and Presents.
+
+### E3 — Media two-box lowering
+
+A media package must be able to lower one resolved content box containing two independent samples
+of the same Artifact:
+
+- a backdrop sample with its own cover/zoom/blur/tone treatment;
+- a foreground sample with its own contain/cover/fit-height and focal alignment.
+
+The public Track must not acquire B-roll, focal-preset or blurred-background fields. Artifact
+dependency collection must deduplicate the shared content digest.
+
+### E4 — Independent absolute stacking
+
+One package may emit a board at one absolute stack position and icons or labels at other positions.
+A Present from another Track must be able to appear between them. Track identity is ownership and
+provenance, never a render stacking context.
+
+### E5 — Local motion and handoff
+
+Frame-exact opacity, transform, filter and clip animation may operate on elements owned by one
+Present. A package that owns both materials in a handoff may lower complementary Presents. No
+ordinary Track may sample the accumulated pixels below it or mutate a sibling Track.
+
+### E6 — Materialized visual fallback
+
+A component whose deterministic visual result cannot be represented by the reference element tree
+must be able to materialize its owned result and contribute it as a typed Surface. For transparent
+interleaving, the final public contract must bind enough surface information to distinguish a
+compositable alpha-bearing visual from an opaque video. Merely naming a `.webm` Artifact does not
+prove this property.
+
+## Old-system attack matrix
+
+| Historical behavior | Package-owned truth | Required terminal witness |
+|---|---|---|
+| Text placement/layout/paint boxes | Text Program | nested owned elements |
+| frame/content/line/word background | Text Program | paint attached to the selected owned level |
+| caption range/cue/content boxes | Caption Program | nested owned elements and word-local animation |
+| dual fonts, CJK, emoji and writing direction | Text/Caption Program | text elements plus locked font/layout dependencies |
+| media content box plus foreground/backdrop sampling | media package | sibling media elements referencing one Artifact |
+| focal crop and fit-height | media package | deterministic sampling/placement result |
+| Ranking board and icons at unrelated z | Ranking Program | several absolute-stack Presents |
+| B-roll enter/exit and pair transition | B-roll Program | local frame-exact keyframes over owned Presents |
+| arbitrary self-contained visual | component/provider | materialized compositable Surface Artifact |
+
+## Current executable evidence
+
+`packages/hyperframes/test/track-expressiveness.test.ts` constructs package-private lowering
+witnesses rather than adding Text, Caption, B-roll or Ranking fields to public contracts. Existing
+package tests separately prove ordinary Text, Caption and B-roll Programs lower through the same
+Track and Composition path.
+
+The current `VisualTrack / VisualPresent / VisualElement` candidate can encode the structural
+three-box, two-box, word-local and absolute-stack cases. Two generic terminal facts are now
+executable rather than package-family patches:
+
+1. `FontArtifactRef` binds each exact fallback face, weight and style to Blob bytes. Exact text
+ lowering emits content-addressed `@font-face` rules and disables font synthesis;
+2. `CompositableSurfaceRef` binds dimensions, sRGB color space, opaque/straight alpha semantics and
+ still/frame timing to Blob bytes. Animated Surfaces must exactly share the containing Present's
+ frame count and ProgramSpace rate.
+
+`packages/hyperframes/test/browser-visual.test.ts` additionally drives one real Hyperframes browser
+frame: a real content-addressed font paints glyphs and a 50% straight-alpha PNG composites over a
+blue Track at the expected pixel values. This opt-in host test is run with
+`SVML_BROWSER_TESTS=1`; it proves the current local renderer path, not every future hosted Runtime.
+
+The candidate is intentionally still not frozen. Unbound text remains temporarily legal for
+candidate-era package migration, and a production Runtime still needs to bind its exact renderer
+implementation and validate that Surface bytes satisfy the declared metadata. Those remaining
+facts must stay generic; they must not be patched with Caption-, Text- or B-roll-specific fields.
+
+## Freeze criteria
+
+Track v1 may be called a stable public waist only when all of the following hold:
+
+1. E1–E5 have executable structural and HTML-lowering witnesses;
+2. official Text/Caption lowerers either bind exact font Artifacts or explicitly materialize their
+ glyph result, and the renderer implementation used for layout is receipt-bound;
+3. E6 has a typed compositable-Surface path whose Runtime validates the declared media facts and
+ records the renderer implementation;
+4. installing a new Track package requires no Core, Film, Composition or family registry change;
+5. public Track data contains no Caption, Text, B-roll, Ranking or provider discriminator;
+6. a package can revise its Program schema while preserving or versioning only its own lowerer;
+7. unsupported cross-Track sampling fails closed.
+
+Until then, `svml.visual-track@1` is an executable candidate used to discover the correct waist,
+not an open-source compatibility promise.
diff --git a/tsconfig.v2.json b/tsconfig.v2.json
index 27a74af2..4f12ad9b 100644
--- a/tsconfig.v2.json
+++ b/tsconfig.v2.json
@@ -17,7 +17,17 @@
"@svml/speech-take": ["packages/speech-take/src/index.ts"],
"@svml/elaborator": ["packages/elaborator/src/index.ts"],
"@svml/realization": ["packages/realization/src/index.ts"],
- "@svml/video-fragments": ["packages/video-fragments/src/index.ts"]
+ "@svml/runtime": ["packages/runtime/src/index.ts"],
+ "@svml/speech-program": ["packages/speech-program/src/index.ts"],
+ "@svml/hyperframes": ["packages/hyperframes/src/index.ts"],
+ "@svml/hyperframes-render": ["packages/hyperframes-render/src/index.ts"],
+ "@svml/broll": ["packages/broll/src/index.ts"],
+ "@svml/film": ["packages/film/src/index.ts"],
+ "@svml/text-track": ["packages/text-track/src/index.ts"],
+ "@svml/svs": ["packages/svs/src/index.ts"],
+ "@svml/compiler-node": ["packages/compiler-node/src/index.ts"],
+ "@svml/cli": ["packages/cli/src/index.ts"],
+ "@svml/validation": ["packages/validation/src/index.ts"]
}
},
"include": ["packages/**/*.ts"],