Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
feat: assemble modular v2 compiler and runtime
kashorin1320b2c77fff
diff --git a/README.md b/README.mdindex 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-flowvideo. Script creates stable semantic addresses. A Composition selects onecontent-addressed `ProgramBasis` and one exact `SemanticMap`; flat Track@@ -96,6 +129,9 @@ pnpm checkpnpm testpnpm 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.svmlpnpm svml script examples/regen-ranking/regen-ranking.svml --out narrative.jsonpnpm 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; nogeneration 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-selectedcompilation modules, typed external requirements and provenance-preservingdiff --git a/docs/README.md b/docs/README.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.svmlnew file mode 100644index 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.svsnew file mode 100644index 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.mdnew file mode 100644index 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.svmlnew file mode 100644index 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.svsnew file mode 100644index 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.mdnew file mode 100644index 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.jsonindex 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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/[email protected]",+ "@svml/[email protected]",+ "@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(), [+ "@svml/[email protected]",+ "@svml/[email protected]",+ "@svml/[email protected]",+ "@svml/[email protected]",+ "@svml/[email protected]",+ ]);+ assert.deepEqual(result.exports, []);+});diff --git a/packages/compiler-node/README.md b/packages/compiler-node/README.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mdindex 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.tsdeleted file mode 100644index 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.tsindex 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">): ProgramSpreturn { ...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 <= 0diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mdindex 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 requestdigests and the accepted event digest. Needs carry the conformance floor inherited from theirinputs, so an exact external response cannot wash a substitute upstream back to exact. An exactNeed 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 neverparses 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mdindex 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 Providermodes. A reused value is an Existing-Value Candidate; “Pin” is only the host UI action that selectsit. 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 abuild 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 regeneratesthe exact commands from verified facts on resume, before any Handler can run. The Registry neverturns a generic speaker request into a model choice: Seedance, WhisperX or another external methoddiff --git a/packages/driver-node/package.json b/packages/driver-node/package.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mdindex 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. Itcontains 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 idMultiple exports of one instance therefore share internal Operations, while two explicit instancesare 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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("&", "&")+ .replaceAll("<", "<")+ .replaceAll(">", ">")+ .replaceAll('"', """)+ .replaceAll("'", "'");+}++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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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 <world>/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&y=2`, "u"));+ assert.match(resolved, new RegExp(`https://assets\\.example/${sound.digest}\\?x=1&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.tsnew file mode 100644index 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.mdindex 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 definescanonical 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 mayauthor, 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.jsonindex 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.tsindex 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): Candidatvalue,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): Candidatid: 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.tsnew file mode 100644index 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex d8af31e2..b4a4e4c2 100644--- a/packages/script/src/surface.ts+++ b/packages/script/src/surface.ts@@ -70,6 +70,8 @@ export function decodeScriptSurface(input: ScriptSurfaceInput): ScriptSurfaceOutrange: { 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mdsimilarity index 93%rename from packages/video-fragments/README.mdrename to packages/speech-program/README.mdindex 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 APIclients. It only composes ordinary Producers from the leaf packages intodiff --git a/packages/video-fragments/package.json b/packages/speech-program/package.jsonsimilarity index 94%rename from packages/video-fragments/package.jsonrename to packages/speech-program/package.jsonindex 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.tssimilarity index 54%rename from packages/video-fragments/src/index.tsrename to packages/speech-program/src/index.tsindex 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.tssimilarity index 64%rename from packages/video-fragments/src/speech.tsrename to packages/speech-program/src/speech.tsindex 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.tssimilarity index 97%rename from packages/video-fragments/test/video-pipeline-fixture.tsrename to packages/speech-program/test/video-pipeline-fixture.tsindex 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.tssimilarity index 97%rename from packages/video-fragments/test/video-pipeline.test.tsrename to packages/speech-program/test/video-pipeline.test.tsindex 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 thedurationSec: 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mdindex 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 leadingAfter Driver supplies one immutable resolved closure, `decodeText` freezes the visible Surfacescope and parses the body. A raw Surface receives the source cursor immediately after its openingtag 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.jsonindex 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.tsindex 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): Textname: 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): TextcontentStart: 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): Textrange: 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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 prange: element.range,},],+ components: [],+ fragments: [],}));const result = decodeText({@@ -226,6 +233,8 @@ test("a module can use Text's generic structured parser without adding another prange: element.range,},],+ components: [],+ fragments: [],}));assert.throws(() => decodeText(diff --git a/packages/validation/README.md b/packages/validation/README.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.yamlindex 329ffb12..7f568566 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -22,14 +22,24 @@ importers:specifier: 5.9.3version: 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:../validationdevDependencies:'@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:../protocolpackages/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:../protocoldevDependencies:+ '@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:../scriptpackages/whisperx:dependencies:diff --git a/spec/author-surface-binding-v1.md b/spec/author-surface-binding-v1.mdnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.jsonindex 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"],