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(v2): run realized talking-film builds
kashorin3ffb6211d993
diff --git a/.gitignore b/.gitignoreindex d2d63520..67b8005e 100644--- a/.gitignore+++ b/.gitignore@@ -3,6 +3,8 @@ dist/.svml-cache/examples/**/assets/examples/**/build/+examples/**/output/+examples/**/.svml/examples/**/evidence/generated/services/whisperx/.venv/services/whisperx/**/__pycache__/diff --git a/examples/talking-film-live/README.md b/examples/talking-film-live/README.mdnew file mode 100644index 00000000..8624cb5f--- /dev/null+++ b/examples/talking-film-live/README.md@@ -0,0 +1,41 @@+# Two-take live acceptance++This example deliberately exercises the real path rather than a placeholder path:++```text+Script -> deterministic Estimate -> two Seedance Mini 480p generations+ -> media normalization -> Speech Spine -> WhisperX -> SemanticMap+ -> Vertex Gemini Caption plan -> Caption Track+ -> Selection-located Text Track -> Film -> HyperFrames -> audio mix -> mux+```++Both English lines resolve to five seconds with `pace="normal"`, `padding="0.3"`, a four-second+minimum and `ceil` rounding. The generated presenter image is intentionally ignored by Git under+`assets/`; supply or regenerate `assets/presenter.png` before checking or building.++Run the complete graph with the explicitly trusted local Runtime:++```bash+pnpm svml:v2 build examples/talking-film-live/main.svml \+ --target final.video \+ --runtime examples/talking-film-live/svml.runtime.ts \+ --follow \+ --out examples/talking-film-live/output/final.mp4+```++Reuse the paid shot outputs from a verified earlier Build while rebuilding every reachable+downstream result:++```bash+pnpm svml:v2 build examples/talking-film-live/main.svml \+ --target final.video \+ --runtime examples/talking-film-live/svml.runtime.ts \+ --pin opening-take=<prior-build-id> \+ --pin answer-take=<prior-build-id> \+ --follow \+ --out examples/talking-film-live/output/final-pinned.mp4+```++The second command compiles a new Build whose two shot outputs are Existing values. It therefore+contains no Seedance Operations or KIE Needs, while Caption, media normalization, WhisperX,+SemanticMap, Tracks, Film and HyperFrames remain ordinary demanded graph work.diff --git a/examples/talking-film-live/main.svml b/examples/talking-film-live/main.svmlnew file mode 100644index 00000000..c02e8e20--- /dev/null+++ b/examples/talking-film-live/main.svml@@ -0,0 +1,128 @@+<svml>+ <import from="@svml/script@1"/>+ <import as="media" from="@svml/media@1"/>+ <import as="estimate" from="@svml/estimate@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@1"/>+ <import as="caption-ai" from="@svml/caption-gemini@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 id="story">+ <opening>+ <HOST>Video editing begins with meaning, not a pile of clips on a timeline.</opening>+ <answer>+ <HOST>Then every caption and visual can arrive at @callout exactly the right moment @/callout.</answer>+ </script>++ <media:Image id="presenter" src="./assets/presenter.png"/>++ <estimate:Speech+ id="opening-duration"+ source={story.segment.opening.speech}+ language="en"+ pace="normal"+ padding="0.3"+ min="4"+ max="15"+ rounding="ceil"+ />++ <estimate:Speech+ id="answer-duration"+ source={story.segment.answer.speech}+ language="en"+ pace="normal"+ padding="0.3"+ min="4"+ max="15"+ rounding="ceil"+ />++ <seedance:Prompt id="opening-direction">+ Vertical medium close-up of the reference presenter in a quiet daylight studio.+ She looks directly into camera and speaks in a calm, clear, conversational voice.+ Natural breathing, restrained movement, locked camera, no text in the scene.+ </seedance:Prompt>++ <seedance:Prompt id="answer-direction">+ Continue with the same reference presenter, studio and calm female voice.+ Vertical medium close-up, direct eye contact, slightly more assured delivery,+ restrained movement, locked camera, no text in the scene.+ </seedance:Prompt>++ <seedance:Speech+ id="opening-take"+ model="mini"+ dialogue={story.segment.opening.dialogue}+ prompt={opening-direction}+ duration={opening-duration.duration}+ resolution="480p"+ aspect-ratio="9:16"+ >+ <seedance:Reference image={presenter} role="character"/>+ </seedance:Speech>++ <seedance:Speech+ id="answer-take"+ model="mini"+ dialogue={story.segment.answer.dialogue}+ prompt={answer-direction}+ duration={answer-duration.duration}+ resolution="480p"+ aspect-ratio="9:16"+ >+ <seedance:Reference image={presenter} role="character"/>+ </seedance:Speech>++ <speech:Spine id="speech">+ <speech:Take source={opening-take} segment={story.segment.opening}/>+ <speech:Take source={answer-take} segment={story.segment.answer}/>+ </speech:Spine>++ <whisperx:Alignment id="timing" narrative={story} audio={speech.audio}/>++ <caption:Style id="primary-caption" appearance={studio.caption.primary}>+ <caption:Cues>Use short complete semantic phrases of two to five words. Never cross sentence boundaries.</caption:Cues>+ <caption:Field id="important" type="boolean" min-per-cue="0" max-per-cue="2">+ Select at most two words whose emphasis best communicates this Cue.+ </caption:Field>+ </caption:Style>++ <caption:Program id="caption-program" narrative={story} default={primary-caption}/>+ <caption-ai:Planner+ id="caption-plan"+ narrative={story}+ program={caption-program}+ model="gemini-2.5-flash"+ />++ <caption:Track+ id="captions"+ narrative={story}+ map={timing.map}+ program={caption-program}+ plan={caption-plan.plan}+ />++ <text:Track id="callout" space={speech.space} map={timing.map}>+ <text:Item+ text="EXACTLY THE RIGHT MOMENT"+ during={story.selection.callout}+ appearance={studio.text.callout}+ />+ </text:Track>++ <film:Film id="main" space={speech.space} appearance={studio.film.vertical}>+ <film:Track source={speech.visual}/>+ <film:Track source={speech.audioTrack}/>+ <film:Track source={captions.track}/>+ <film:Track source={callout.track}/>+ </film:Film>++ <render:Video id="final" composition={main.composition}/>+</svml>diff --git a/examples/talking-film-live/studio.svs b/examples/talking-film-live/studio.svsnew file mode 100644index 00000000..31471faa--- /dev/null+++ b/examples/talking-film-live/studio.svs@@ -0,0 +1,38 @@+<sheet version="1">+ film.vertical {+ width: 480;+ height: 854;+ frame-rate: 30;+ background: #09090B;+ }++ caption.primary {+ stack-order: 70;+ x: 0.08;+ y: 0.74;+ width: 0.84;+ font: Inter;+ weight: 700;+ size: 30;+ line-height: 1;+ align: center;+ fill: #FFFFFF;+ background: #09090BCC;+ padding: 10 14;+ radius: 12;+ }++ text.callout {+ stack-order: 85;+ x: 0.08;+ y: 0.10;+ width: 0.84;+ height: 0.10;+ font: Inter;+ weight: 900;+ size: 27;+ align: center;+ fill: #FFF16A;+ tracking: -0.5;+ }+</sheet>diff --git a/examples/talking-film-live/svml.runtime.ts b/examples/talking-film-live/svml.runtime.tsnew file mode 100644index 00000000..5576793c--- /dev/null+++ b/examples/talking-film-live/svml.runtime.ts@@ -0,0 +1,63 @@+import { fileURLToPath } from "node:url";++import { createProjectLocalRuntime } from "@svml/local";+import { svmlPackage } from "@svml/prelude-video";+import { createGoogleVertexCaptionProvider } from "@svml/provider-google-vertex";+import { createLocalHyperframesProvider } from "@svml/provider-hyperframes-local";+import { createKieProvider } from "@svml/provider-kie";+import { createLocalMediaProvider } from "@svml/provider-media-local";+import { createLocalWhisperXProvider } from "@svml/provider-whisperx-local";++export default async function createTalkingFilmRuntime() {+ const project = process.env.GOOGLE_CLOUD_PROJECT?.trim();+ if (!project) throw new Error("GOOGLE_CLOUD_PROJECT is required for the explicit Vertex Gemini Caption Provider");++ const endpoints = [+ createKieProvider({+ instance: "kie.talking-film",+ lane: "generation",+ defaultConcurrency: 2,+ }),+ createLocalMediaProvider({+ instance: "media.talking-film",+ lane: "media",+ defaultConcurrency: 2,+ }),+ createLocalWhisperXProvider({+ instance: "whisperx.talking-film",+ lane: "alignment",+ defaultConcurrency: 1,+ }),+ createGoogleVertexCaptionProvider({+ project,+ instance: "vertex.talking-film",+ lane: "planning",+ defaultConcurrency: 1,+ }),+ createLocalHyperframesProvider({+ instance: "hyperframes.talking-film",+ lane: "render",+ workers: 2,+ quality: "standard",+ defaultConcurrency: 1,+ }),+ ];++ return await createProjectLocalRuntime({+ root: fileURLToPath(new URL(".", import.meta.url)),+ components: svmlPackage.components,+ endpoints,+ allowedPermissions: [...new Set(endpoints.flatMap((endpoint) =>+ endpoint.manifest.facets.flatMap((facet) => facet.permissions)))],+ scheduling: {+ maxConcurrency: 4,+ lanes: {+ generation: 2,+ media: 2,+ alignment: 1,+ planning: 1,+ render: 1,+ },+ },+ });+}diff --git a/package.json b/package.jsonindex ba031794..252ed930 100644--- a/package.json+++ b/package.json@@ -33,6 +33,13 @@"hyperframes": "0.7.84"},"devDependencies": {+ "@svml/local": "workspace:*",+ "@svml/prelude-video": "workspace:*",+ "@svml/provider-google-vertex": "workspace:*",+ "@svml/provider-hyperframes-local": "workspace:*",+ "@svml/provider-kie": "workspace:*",+ "@svml/provider-media-local": "workspace:*",+ "@svml/provider-whisperx-local": "workspace:*","@types/node": "24.10.1","tsx": "4.21.0","typescript": "5.9.3"diff --git a/packages/broll/src/author.ts b/packages/broll/src/author.tsindex 9827ec52..12672ccf 100644--- a/packages/broll/src/author.ts+++ b/packages/broll/src/author.ts@@ -1,5 +1,7 @@import {- assertProgramSpaceIdentity,+ assertCompleteSemanticMapIdentity,+ assertNarrativeSelectionIdentity,+ selectionFrameSpans,verifySynchronizedMedia,} from "@svml/contracts";import type {@@ -26,16 +28,8 @@ function assert(condition: unknown, message: string): asserts condition {if (!condition) throw new Error(message);}-function verifyMap(map: CompleteSemanticMap): void {- assert(map.contract === "svml.complete-semantic-map@1", "B-roll requires CompleteSemanticMap");- assertProgramSpaceIdentity(map.programSpace);- const { mapDigest: _digest, ...content } = map;- assert(isDigest(map.mapDigest) && map.mapDigest === digestOf(canonicalize(content)),- "CompleteSemanticMap digest differs from its contents");-}-export function projectBrollProgramSpace(map: CompleteSemanticMap) {- verifyMap(map);+ assertCompleteSemanticMapIdentity(map);return map.programSpace;}@@ -63,14 +57,6 @@ function assertBrollTrackSpec(value: BrollTrackSpec): void {&& isDigest(value.digest) && value.digest === digestOf(canonicalize(content)), "BrollTrackSpec is invalid");}-function verifySelection(value: NarrativeSelectionRef): void {- assert(value.contract === "svml.narrative-selection@1" && value.id.length > 0 && value.occurrences.length > 0,- "B-roll selection is invalid");- const { selectionDigest: _digest, ...content } = value;- assert(isDigest(value.selectionDigest) && value.selectionDigest === digestOf(canonicalize(content)),- "B-roll selection digest differs");-}-function setContent(value: Omit<BrollSet, "digest">): Omit<BrollSet, "digest"> {return canonicalize(value) as unknown as Omit<BrollSet, "digest">;}@@ -82,7 +68,7 @@ function sealSet(value: Omit<BrollSet, "digest">): BrollSet {export function assertBrollSet(value: BrollSet): void {assert(value.contract === "svml.broll-set@1" && value.id.length > 0, "BrollSet identity is invalid");- verifyMap(value.map);+ assertCompleteSemanticMapIdentity(value.map);const { digest: _digest, ...content } = value;assert(isDigest(value.digest) && value.digest === digestOf(setContent(content)), "BrollSet digest differs");assert(value.items.length === 0 ? value.lastAddition === undefined : value.lastAddition !== undefined,@@ -90,25 +76,11 @@ export function assertBrollSet(value: BrollSet): void {}export function createBrollSet(map: CompleteSemanticMap, spec: BrollTrackSpec): BrollSet {- verifyMap(map);+ assertCompleteSemanticMapIdentity(map);assertBrollTrackSpec(spec);return sealSet({ contract: "svml.broll-set@1", id: spec.id, map, items: [] });}-function boundaryFrame(- map: CompleteSemanticMap,- edge: NarrativeSelectionRef["occurrences"][number]["open"],- side: "open" | "close",-): number {- const index = edge.boundary.tokenIndex;- if (side === "open") {- if (edge.affinity === "left" && index > 0) return map.tokens[index - 1]?.startFrame ?? 0;- return map.tokens[index]?.startFrame ?? Math.round(map.durationSec * map.programSpace.frameRate.numerator / map.programSpace.frameRate.denominator);- }- if (edge.affinity === "right" && index < map.tokens.length) return map.tokens[index]?.endFrame ?? 0;- return index > 0 ? map.tokens[index - 1]?.endFrame ?? 0 : 0;-}-export function appendBrollItem(set: BrollSet,media: SynchronizedMedia,@@ -117,17 +89,14 @@ export function appendBrollItem(): BrollSet {assertBrollSet(set);verifySynchronizedMedia(media);- verifySelection(selection);+ assertNarrativeSelectionIdentity(selection);assertBrollItemSpec(spec);assert(media.visual !== undefined, `B-roll ${spec.id} source has no visual stream`);assert(media.timeline.frameRate.numerator === set.map.programSpace.frameRate.numerator&& media.timeline.frameRate.denominator === set.map.programSpace.frameRate.denominator,`B-roll ${spec.id} media uses another frame rate`);const durationSec = media.timeline.frameCount * media.timeline.frameRate.denominator / media.timeline.frameRate.numerator;- const additions = selection.occurrences.map((occurrence, index) => {- const startFrame = boundaryFrame(set.map, occurrence.open, "open");- const endFrameExclusive = boundaryFrame(set.map, occurrence.close, "close");- assert(endFrameExclusive > startFrame, `B-roll ${spec.id} selection occurrence is empty`);+ const additions = selectionFrameSpans(set.map, selection).map((span, index) => {return {id: selection.occurrences.length === 1 ? spec.id : `${spec.id}:${index + 1}`,artifact: {@@ -136,7 +105,7 @@ export function appendBrollItem(mediaType: media.visual!.artifact.mediaType,durationSec,},- span: { startFrame, endFrameExclusive },+ span,z: spec.z,tieBreak: `${set.id}:${spec.id}:${index + 1}`,box: spec.box,diff --git a/packages/cli/README.md b/packages/cli/README.mdindex 96f28694..611266ca 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -25,6 +25,7 @@ pnpm svml:v2 plan path/to/main.svml --target component.resultpnpm svml:v2 build path/to/main.svml --target component.result --runtime ./svml.runtime.tspnpm svml:v2 build path/to/main.svml --target component.result --runtime ./svml.runtime.ts --followpnpm svml:v2 build path/to/main.svml --target final.video --runtime ./svml.runtime.ts --follow --out ./final.mp4+pnpm svml:v2 build path/to/main.svml --target final.video --runtime ./svml.runtime.ts --pin shot=<prior-build-id> --follow --out ./variant.mp4pnpm svml:v2 status <build-id> --runtime ./svml.runtime.tspnpm svml:v2 cancel <build-id> --runtime ./svml.runtime.ts```@@ -49,6 +50,13 @@ these commands creates a second ready-command queue.selected Runtime ArtifactStore and writes the requested file. It does not treat a CAS path as apublic filename or bypass Record identity verification.+`--pin output=<prior-build-id>` is intentionally CLI language, not a Core primitive. The trusted+Host verifies the prior Build and output Record, attaches it as an Existing-Value realization, and+adds an explicit binding to a newly compiled BuildRequest. Upstream work behind that output is not+demanded, while every unbound reachable output follows the ordinary graph. The prior artifact must+still exist in the ArtifactStore selected by the Runtime. This is a new Build with a new identity;+it never resumes or copies the prior Build's outstanding Commands.+`@svml/package-loader-node` supports explicitly trusted installed implementation packages. Itverifies the complete physical dependency closure before executing an activation entry, then checksexact Module, Frontend, Surface, Producer and Validator identities. `plan` and `build` bind the lockdiff --git a/packages/cli/package.json b/packages/cli/package.jsonindex 29505769..060e8198 100644--- a/packages/cli/package.json+++ b/packages/cli/package.json@@ -11,6 +11,7 @@"@svml/local": "workspace:*","@svml/package-loader-node": "workspace:*","@svml/prelude-video": "workspace:*",- "@svml/protocol": "workspace:*"+ "@svml/protocol": "workspace:*",+ "@svml/realization": "workspace:*"}}diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.tsindex 467da4f9..cc75609a 100644--- a/packages/cli/src/main.ts+++ b/packages/cli/src/main.ts@@ -4,6 +4,10 @@ import { pathToFileURL } from "node:url";import type { LocalRuntime } from "@svml/local";import { isDigest } from "@svml/protocol";+import {+ createHistoricalCandidate,+ sealRealizationOverlay,+} from "@svml/realization";import {createNodePackageLock,loadNodePackageSet,@@ -29,6 +33,7 @@ type ParsedArgs = {readonly packageLock: string | undefined;readonly packages: readonly string[];readonly out: string | undefined;+ readonly pins: readonly { readonly output: string; readonly build: string }[];};function parseArgs(argv: readonly string[]): ParsedArgs {@@ -43,6 +48,7 @@ function parseArgs(argv: readonly string[]): ParsedArgs {const packages: string[] = [];let substitute = false;let out: string | undefined;+ const pins: { output: string; build: string }[] = [];for (let index = 0; index < rest.length; index += 1) {const item = rest[index];if (item === "--target") {@@ -98,6 +104,15 @@ function parseArgs(argv: readonly string[]): ParsedArgs {index += 1;continue;}+ if (item === "--pin") {+ const value = rest[index + 1];+ if (value === undefined || value.startsWith("--")) throw new Error("--pin requires output=build-id");+ const separator = value.indexOf("=");+ if (separator <= 0 || separator === value.length - 1) throw new Error("--pin requires output=build-id");+ pins.push({ output: value.slice(0, separator), build: value.slice(separator + 1) });+ index += 1;+ continue;+ }if (item === "--follow") {follow = true;continue;@@ -127,6 +142,7 @@ function parseArgs(argv: readonly string[]): ParsedArgs {packageLock,packages,out,+ pins,};}@@ -136,7 +152,7 @@ function usage(): string {" svml-v2 lock-packages <svml.packages.lock> --package installed-name [--package installed-name] [--root directory]"," svml-v2 check <file.svml> [--package-lock file] [--root directory]"," svml-v2 plan <file.svml> --target export [--target export] [--accept-substitute] [--package-lock file]",- " svml-v2 build <file.svml> --target export --runtime ./svml.runtime.ts [--package-lock file] [--follow] [--out video.mp4]",+ " svml-v2 build <file.svml> --target export --runtime ./svml.runtime.ts [--pin output=prior-build] [--follow] [--out video.mp4]"," svml-v2 status <build-id> --runtime ./svml.runtime.ts"," svml-v2 cancel <build-id> --runtime ./svml.runtime.ts",].join("\n");@@ -213,6 +229,7 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>return;}if (args.out !== undefined && args.command !== "build") throw new Error("--out is only valid for build");+ if (args.pins.length > 0 && args.command !== "build") throw new Error("--pin is only valid for build");if (args.command === "status" || args.command === "cancel") {if (args.runtime === undefined) throw new Error(`${args.command} requires --runtime`);const runtime = await loadLocalRuntime(args.runtime);@@ -273,15 +290,55 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>}, null, 2)}\n`);return;}- const result = await compiler.planFile(args.file, {- targets: args.targets,- accepts: args.substitute ? "substitute" : "exact",- ...(activated === undefined ? {} : { implementationClosure: activated.lock.digest }),- });if (args.command === "build") {if (args.runtime === undefined) throw new Error("build requires --runtime with a trusted local config module");const runtime = await loadLocalRuntime(args.runtime);try {+ const planOptions = {+ targets: args.targets,+ accepts: args.substitute ? "substitute" as const : "exact" as const,+ ...(activated === undefined ? {} : { implementationClosure: activated.lock.digest }),+ };+ let pinSummary: readonly { readonly output: string; readonly build: string; readonly candidate: string }[] = [];+ const result = args.pins.length === 0+ ? await compiler.planFile(args.file, planOptions)+ : await (async () => {+ const compilation = await compiler.compileFile(args.file!);+ const seen = new Set<string>();+ const candidates = [];+ const bindings = [];+ const summary = [];+ for (const pin of args.pins) {+ if (seen.has(pin.output)) throw new Error(`--pin repeats output ${pin.output}`);+ seen.add(pin.output);+ const exported = compilation.exports.find((item) => item.name === pin.output);+ if (exported === undefined) throw new Error(`--pin refers to unknown public output ${pin.output}`);+ if (exported.ref.kind !== "logical-output") {+ throw new Error(`--pin ${pin.output} is an authored Record, not a realizable output`);+ }+ const historical = await runtime.status(pin.build);+ if (historical.build === undefined) throw new Error(`--pin source Build ${pin.build} does not exist`);+ const candidate = createHistoricalCandidate({+ source: compilation.elaboration.graph,+ build: historical.build.state,+ output: exported.ref.id,+ });+ candidates.push(candidate);+ bindings.push({ output: exported.ref.id, candidate: candidate.id });+ summary.push({ output: pin.output, build: pin.build, candidate: candidate.id });+ }+ const overlay = sealRealizationOverlay({+ sourceGraph: compilation.elaboration.graph.id,+ candidates,+ operations: [],+ });+ pinSummary = summary;+ return compiler.planCompilation(compilation, {+ ...planOptions,+ bindings,+ realizations: [overlay],+ });+ })();const built = await runtime.build({id: args.buildId ?? result.state.id,state: result.state,@@ -291,7 +348,7 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),});let materialized: { readonly path: string; readonly digest: string; readonly size: number } | undefined;- if (args.out !== undefined) {+ if (args.out !== undefined && built.status === "complete") {materialized = await materializeSingleGoal(runtime, built, args.out);}io.write(`${JSON.stringify({@@ -309,6 +366,8 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>}),blocked: built.blocked,journal: built.journal,+ ...(pinSummary.length === 0 ? {} : { pins: pinSummary }),+ ...(args.out !== undefined && materialized === undefined ? { pendingOutput: args.out } : {}),...(materialized === undefined ? {} : { output: materialized }),}, null, 2)}\n`);} finally {@@ -316,5 +375,10 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>}return;}+ const result = await compiler.planFile(args.file, {+ targets: args.targets,+ accepts: args.substitute ? "substitute" : "exact",+ ...(activated === undefined ? {} : { implementationClosure: activated.lock.digest }),+ });io.write(`${JSON.stringify(result.plan, null, 2)}\n`);}diff --git a/packages/compiler-node/package.json b/packages/compiler-node/package.jsonindex 147905e2..a78cc615 100644--- a/packages/compiler-node/package.json+++ b/packages/compiler-node/package.json@@ -11,6 +11,7 @@"@svml/elaborator": "workspace:*","@svml/host": "workspace:*","@svml/protocol": "workspace:*",+ "@svml/realization": "workspace:*","@svml/validation": "workspace:*","@svml/workspace-fs-node": "workspace:*"},diff --git a/packages/compiler-node/src/compiler.ts b/packages/compiler-node/src/compiler.tsindex 7ad99853..b7b48c36 100644--- a/packages/compiler-node/src/compiler.ts+++ b/packages/compiler-node/src/compiler.ts@@ -23,6 +23,8 @@ import type {CandidateBinding,NeedAcceptance,} from "@svml/protocol";+import { resolveRealization } from "@svml/realization";+import type { RealizationOverlay } from "@svml/realization";import {TypeValidatorRegistry,createRecordAdmitter,@@ -88,6 +90,8 @@ export type PlanFileOptions = {readonly accepts?: NeedAcceptance;readonly bindings?: readonly CandidateBinding[];readonly implementationClosure?: import("@svml/protocol").Digest;+ /** External Candidate attachments; never discovered from the author source. */+ readonly realizations?: readonly RealizationOverlay[];};export type PlannedSource = {@@ -158,6 +162,20 @@ export class NodeCompiler {throw new NodeCompilerError("EMPTY_BUILD_TARGETS", "plan requires at least one public source export");}const compilation = await this.compileFile(file);+ return this.planCompilation(compilation, options);+ }++ planCompilation(compilation: NodeCompiledSourceClosure, options: PlanFileOptions): PlannedSource {+ if (options.targets.length === 0) {+ throw new NodeCompilerError("EMPTY_BUILD_TARGETS", "plan requires at least one public source export");+ }+ const graph = options.realizations === undefined || options.realizations.length === 0+ ? compilation.elaboration.graph+ : resolveRealization(+ compilation.program,+ compilation.elaboration.graph,+ options.realizations,+ ).graph;const targets = options.targets.map((name) => {const exported = resolveCompiledSourceExport(compilation, name);if (exported.ref.kind !== "logical-output") {@@ -170,7 +188,7 @@ export class NodeCompiler {return { output: exported.ref.id, accepts: options.accepts ?? "exact" } as const;});const request = sealBuildRequest({- graph: compilation.elaboration.graph.id,+ graph: graph.id,...(options.implementationClosure === undefined? {}: { implementationClosure: options.implementationClosure }),@@ -179,7 +197,7 @@ export class NodeCompiler {});const state = start(compilation.program,- compilation.elaboration.graph,+ graph,request,);return { compilation, request, plan: state.plan, state };diff --git a/packages/contracts/src/identity.ts b/packages/contracts/src/identity.tsindex 5ac5bc87..32514a85 100644--- a/packages/contracts/src/identity.ts+++ b/packages/contracts/src/identity.ts@@ -6,9 +6,38 @@ import type {ProgramSpace,SpeechAudioBasis,SpeechBasis,+ SpeechDuration,SpeechEvidenceAudio,} from "./speech.js";+export function computeSpeechDurationDigest(value: Omit<SpeechDuration, "durationDigest">): Digest {+ return digestOf(value);+}++export function sealSpeechDuration(value: Omit<SpeechDuration, "durationDigest">): SpeechDuration {+ return { ...value, durationDigest: computeSpeechDurationDigest(value) };+}++export function assertSpeechDurationIdentity(value: SpeechDuration): void {+ if (value.contract !== "svml.speech-duration@1") throw new Error("Unsupported SpeechDuration contract.");+ if (+ value.segmentId.length === 0+ || !Number.isSafeInteger(value.tokenStart)+ || !Number.isSafeInteger(value.tokenEndExclusive)+ || value.tokenStart < 0+ || value.tokenEndExclusive <= value.tokenStart+ || !isDigest(value.sourceSpeechExcerptDigest)+ || !Number.isFinite(value.durationSec)+ || value.durationSec <= 0+ ) {+ throw new Error("SpeechDuration is invalid.");+ }+ const { durationDigest: _digest, ...content } = value;+ if (!isDigest(value.durationDigest) || value.durationDigest !== computeSpeechDurationDigest(content)) {+ throw new Error("SpeechDuration digest does not match its canonical contents.");+ }+}+export function computeProgramSpaceDigest(value: Omit<ProgramSpace, "digest">): Digest {return digestOf(value);}diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.tsindex 2ace3cdc..4ae6ef34 100644--- a/packages/contracts/src/index.ts+++ b/packages/contracts/src/index.ts@@ -1,16 +1,19 @@export {assertProgramSpaceIdentity,+ assertSpeechDurationIdentity,assertSpeechAudioBasisIdentity,assertSpeechBasisIdentity,assertSpeechEvidenceAudioIdentity,computeAlignedTranscriptEvidenceDigest,computeProgramSpaceDigest,+ computeSpeechDurationDigest,computeSpeechBasisDigest,computeSpeechEvidenceAudioDigest,programSpaceFrameCount,programSpaceSampleFrames,sealAlignedTranscriptEvidence,sealProgramSpace,+ sealSpeechDuration,sealSpeechBasis,sealSpeechEvidenceAudio,speechEvidenceSampleBoundary,@@ -88,6 +91,7 @@ export {speechAudioBasisSchema,speechEvidenceAudioSchema,speechBasisSchema,+ speechDurationSchema,visualTrackSchema,audioTrackSchema,compositionSchema,@@ -100,6 +104,11 @@ export {assertFontArtifactRef,} from "./render.js";export type * from "./render.js";+export {+ assertCompleteSemanticMapIdentity,+ assertNarrativeSelectionIdentity,+ selectionFrameSpans,+} from "./semantic-location.js";export type * from "./speech.js";export {assertAudioTrackIdentity,diff --git a/packages/contracts/src/manifest.ts b/packages/contracts/src/manifest.tsindex 9dbb659c..fee8c6ca 100644--- a/packages/contracts/src/manifest.ts+++ b/packages/contracts/src/manifest.ts@@ -33,6 +33,7 @@ export const contractTypes = {compositableSurface: { module: mediaModuleRef, name: "CompositableSurfaceRef" },programSpace: { module: programSpaceModuleRef, name: "ProgramSpace" },speechBasis: { module: speechModuleRef, name: "SpeechBasis" },+ speechDuration: { module: speechModuleRef, name: "SpeechDuration" },speechAudioBasis: { module: speechModuleRef, name: "SpeechAudioBasis" },speechEvidenceAudio: { module: speechModuleRef, name: "SpeechEvidenceAudio" },alignedTranscriptEvidence: { module: semanticTimeModuleRef, name: "AlignedTranscriptEvidence" },@@ -393,6 +394,16 @@ export const speechBasisSchema: ValueSchema = object({segments: { schema: { kind: "array", minItems: 1, items: basisSegment } },});+export const speechDurationSchema: ValueSchema = object({+ contract: { schema: { kind: "literal", value: "svml.speech-duration@1" } },+ segmentId: { schema: string },+ tokenStart: { schema: integer },+ tokenEndExclusive: { schema: integer },+ sourceSpeechExcerptDigest: { schema: digest },+ durationSec: { schema: { kind: "number", minimum: 0.000001 } },+ durationDigest: { schema: digest },+});+export const speechAudioBasisSchema: ValueSchema = object({contract: { schema: { kind: "literal", value: "svml.speech-audio-basis@1" } },programSpace: { schema: programSpaceSchema }, audio: { schema: mediaArtifactSchema },@@ -738,6 +749,7 @@ export const speechManifest: ModuleManifest = {{ module: programSpaceModuleRef, digest: programSpaceManifestDigest },],types: [+ { name: contractTypes.speechDuration.name, schema: speechDurationSchema },{ name: contractTypes.speechBasis.name, schema: speechBasisSchema },{ name: contractTypes.speechAudioBasis.name, schema: speechAudioBasisSchema },{ name: contractTypes.speechEvidenceAudio.name, schema: speechEvidenceAudioSchema },diff --git a/packages/contracts/src/semantic-location.ts b/packages/contracts/src/semantic-location.tsnew file mode 100644index 00000000..c24f7fdd--- /dev/null+++ b/packages/contracts/src/semantic-location.ts@@ -0,0 +1,64 @@+import { canonicalize, digestOf, isDigest } from "@svml/protocol";++import { assertProgramSpaceIdentity, programSpaceFrameCount } from "./identity.js";+import type { NarrativeSelectionRef } from "./narrative.js";+import type { CompleteSemanticMap } from "./speech.js";+import type { FrameSpan } from "./track.js";++export function assertCompleteSemanticMapIdentity(map: CompleteSemanticMap): void {+ if (map.contract !== "svml.complete-semantic-map@1") {+ throw new Error("Unsupported CompleteSemanticMap contract");+ }+ assertProgramSpaceIdentity(map.programSpace);+ const { mapDigest: _digest, ...content } = map;+ if (!isDigest(map.mapDigest) || map.mapDigest !== digestOf(canonicalize(content))) {+ throw new Error("CompleteSemanticMap digest differs from its contents");+ }+}++export function assertNarrativeSelectionIdentity(selection: NarrativeSelectionRef): void {+ if (+ selection.contract !== "svml.narrative-selection@1"+ || selection.id.length === 0+ || selection.occurrences.length === 0+ ) {+ throw new Error("NarrativeSelection is invalid");+ }+ const { selectionDigest: _digest, ...content } = selection;+ if (!isDigest(selection.selectionDigest) || selection.selectionDigest !== digestOf(canonicalize(content))) {+ throw new Error("NarrativeSelection digest differs from its contents");+ }+}++function boundaryFrame(+ map: CompleteSemanticMap,+ edge: NarrativeSelectionRef["occurrences"][number]["open"],+ side: "open" | "close",+): number {+ const index = edge.boundary.tokenIndex;+ if (side === "open") {+ if (edge.affinity === "left" && index > 0) return map.tokens[index - 1]?.startFrame ?? 0;+ return map.tokens[index]?.startFrame ?? programSpaceFrameCount(map.programSpace);+ }+ if (edge.affinity === "right" && index < map.tokens.length) {+ return map.tokens[index]?.endFrame ?? programSpaceFrameCount(map.programSpace);+ }+ return index > 0 ? map.tokens[index - 1]?.endFrame ?? 0 : 0;+}++/** Project every occurrence of one Script Selection onto one measured SemanticMap. */+export function selectionFrameSpans(+ map: CompleteSemanticMap,+ selection: NarrativeSelectionRef,+): readonly FrameSpan[] {+ assertCompleteSemanticMapIdentity(map);+ assertNarrativeSelectionIdentity(selection);+ return selection.occurrences.map((occurrence) => {+ const startFrame = boundaryFrame(map, occurrence.open, "open");+ const endFrameExclusive = boundaryFrame(map, occurrence.close, "close");+ if (endFrameExclusive <= startFrame) {+ throw new Error(`NarrativeSelection ${selection.id} contains an empty located occurrence`);+ }+ return { startFrame, endFrameExclusive };+ });+}diff --git a/packages/contracts/src/speech.ts b/packages/contracts/src/speech.tsindex 17e4a374..4c817d6f 100644--- a/packages/contracts/src/speech.ts+++ b/packages/contracts/src/speech.ts@@ -2,6 +2,23 @@ import type { BlobRef, Digest } from "@svml/protocol";export type TimingQuality = "measured" | "derived" | "estimated";+/**+ * One planned duration for one exact Narrative speech excerpt.+ *+ * The value is intentionally provider-neutral: a deterministic estimator,+ * an authored constant or another realization may produce it. Consumers such+ * as Seedance decide which numeric subset they accept.+ */+export type SpeechDuration = {+ readonly contract: "svml.speech-duration@1";+ readonly segmentId: string;+ readonly tokenStart: number;+ readonly tokenEndExclusive: number;+ readonly sourceSpeechExcerptDigest: Digest;+ readonly durationSec: number;+ readonly durationDigest: Digest;+};+export type ProgramSpace = {readonly contract: "svml.program-space@0";readonly digest: Digest;diff --git a/packages/contracts/src/track.ts b/packages/contracts/src/track.tsindex 24fe5d9d..5ef8019d 100644--- a/packages/contracts/src/track.ts+++ b/packages/contracts/src/track.ts@@ -556,7 +556,7 @@ export function assertCompositionIdentity(composition: Composition): void {|| 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)+ || !/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(composition.canvas.clearColor)) {throw new Error("Composition canvas is invalid.");}diff --git a/packages/contracts/test/track.test.ts b/packages/contracts/test/track.test.tsindex 9e3489e0..3737faa3 100644--- a/packages/contracts/test/track.test.ts+++ b/packages/contracts/test/track.test.ts@@ -77,6 +77,18 @@ test("Composition accepts self-contained peer VisualTrack and AudioTrack values"assert.deepEqual(composition.tracks.map((track) => track.id), ["speech", "caption"]);});+test("Composition accepts case-insensitive hexadecimal canvas colors", () => {+ const { programSpace, visual } = fixture();+ const composition = sealComposition({+ contract: "svml.composition@1",+ id: "uppercase-color",+ programSpace,+ canvas: { width: 480, height: 854, clearColor: "#09090B" },+ tracks: [visual],+ });+ assert.doesNotThrow(() => assertCompositionIdentity(composition));+});+test("VisualTrack rejects cross-Track pixel sampling styles", () => {const { programSpace, visual, sound } = fixture();const content = structuredClone(visual) as VisualTrack;diff --git a/packages/core/src/affinity.ts b/packages/core/src/affinity.tsindex 68a8ac5f..26cab9f7 100644--- a/packages/core/src/affinity.ts+++ b/packages/core/src/affinity.ts@@ -10,7 +10,12 @@ import type {import { canonicalStringify } from "./canonical.js";import { invariant } from "./error.js";-import { resolveLogicalOutput, resolveOperation } from "./graph.js";+import {+ resolveCandidate,+ resolveLogicalOutput,+ resolveOperation,+ verifyOutputValidationReceipt,+} from "./graph.js";import { resolveProducer } from "./link.js";function pointerTokens(pointer: string): string[] {@@ -81,6 +86,20 @@ export function verifyRecordAffinity(): void {if (record.conformance === "substitute") return;const output = resolveLogicalOutput(graph, outputId);+ const selection = plan.selections.find((item) => item.output === outputId && item.record === record.id);+ if (selection !== undefined) {+ const candidate = resolveCandidate(graph, selection.candidate);+ if (candidate.root.kind === "value" && candidate.root.value.outputValidation !== undefined) {+ verifyOutputValidationReceipt(+ candidate.root.value.outputValidation,+ graph.source,+ output.id,+ output.type,+ record.value,+ );+ return;+ }+ }for (const constraint of output.affinity ?? []) {const sourceId = sourceRecordId(graph, plan, constraint.source);const source = lookup(sourceId);diff --git a/packages/core/src/graph.ts b/packages/core/src/graph.tsindex 77013392..ab19d208 100644--- a/packages/core/src/graph.ts+++ b/packages/core/src/graph.ts@@ -4,17 +4,19 @@ import type {CandidateBinding,CandidateRoot,CompiledGraph,+ Digest,GraphValueRef,LinkedProgram,LogicalOutput,OperationNode,OperationResult,+ OutputValidationReceipt,ProducerRef,StoredValue,TypeRef,} from "@svml/protocol";-import { canonicalize, digestOf, isDigest } from "./canonical.js";+import { canonicalize, digestOf, isDigest, recordDigest } from "./canonical.js";import { invariant } from "./error.js";import { resolveProducer, sealRecord, verifyRecord } from "./link.js";import { producerKey, sameType, typeKey } from "./reference.js";@@ -49,11 +51,67 @@ function normalizeRoot(root: CandidateRoot): CandidateRoot {id: root.value.id,value: normalizedStoredValue(root.value.value),...(root.value.validation === undefined ? {} : { validation: root.value.validation }),+ ...(root.value.outputValidation === undefined+ ? {}+ : { outputValidation: normalizeOutputValidationReceipt(root.value.outputValidation) }),...(root.value.provenance === undefined ? {} : { provenance: canonicalize(root.value.provenance) }),};return { kind: "value", value };}+function outputValidationContent(+ receipt: Omit<OutputValidationReceipt, "id">,+): Omit<OutputValidationReceipt, "id"> {+ return {+ format: "svml.output-validation@1",+ graphSource: receipt.graphSource,+ output: receipt.output,+ recordDigest: receipt.recordDigest,+ sourceBuild: receipt.sourceBuild,+ sourceRequest: receipt.sourceRequest,+ sourceCandidate: receipt.sourceCandidate,+ };+}++function normalizeOutputValidationReceipt(receipt: OutputValidationReceipt): OutputValidationReceipt {+ const content = outputValidationContent(receipt);+ return { ...content, id: receipt.id };+}++export function sealOutputValidationReceipt(+ receipt: Omit<OutputValidationReceipt, "format" | "id">,+): OutputValidationReceipt {+ const content = outputValidationContent({ format: "svml.output-validation@1", ...receipt });+ return { ...content, id: digestOf(content) };+}++export function verifyOutputValidationReceipt(+ receipt: OutputValidationReceipt,+ graphSource: Digest,+ output: string,+ type: TypeRef,+ value: StoredValue,+): void {+ invariant(+ receipt.format === "svml.output-validation@1",+ "UNSUPPORTED_OUTPUT_VALIDATION",+ "unsupported Output validation receipt",+ );+ invariant(isDigest(receipt.id), "INVALID_DIGEST", "Output validation receipt id is invalid");+ invariant(receipt.graphSource === graphSource, "OUTPUT_VALIDATION_GRAPH_MISMATCH", "Output validation belongs to another author graph");+ invariant(receipt.output === output, "OUTPUT_VALIDATION_OUTPUT_MISMATCH", "Output validation belongs to another Logical Output");+ invariant(+ receipt.recordDigest === recordDigest(type, value),+ "OUTPUT_VALIDATION_RECORD_MISMATCH",+ "Output validation belongs to another value",+ );+ invariant(isDigest(receipt.sourceBuild), "INVALID_DIGEST", "Output validation source Build is invalid");+ invariant(isDigest(receipt.sourceRequest), "INVALID_DIGEST", "Output validation source request is invalid");+ invariant(receipt.sourceCandidate.length > 0, "EMPTY_CANDIDATE_ID", "Output validation source Candidate is empty");+ const { id: _id, ...content } = receipt;+ invariant(receipt.id === digestOf(outputValidationContent(content)), "OUTPUT_VALIDATION_DIGEST_MISMATCH", "Output validation receipt differs");+}+function normalizeOutput(output: LogicalOutput): LogicalOutput {const base = {id: output.id,@@ -441,6 +499,16 @@ export function verifyCompiledGraph(program: LinkedProgram, graph: CompiledGraph`${candidate.id} returns ${typeKey(supplied)}, not ${typeKey(output.type)}`,candidate.id,);+ if (candidate.root.kind === "value" && candidate.root.value.outputValidation !== undefined) {+ invariant(candidate.fidelity === "exact", "SUBSTITUTE_OUTPUT_VALIDATION", "a substitute Candidate cannot carry exact Output validation");+ verifyOutputValidationReceipt(+ candidate.root.value.outputValidation,+ graph.source,+ output.id,+ output.type,+ candidate.root.value.value,+ );+ }const allowed = new Set(output.semanticInputs.map(valueRefKey));for (const leaf of semanticLeaves(graph, candidate.root)) {invariant(diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 1dcb9389..d3c3db51 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -32,10 +32,12 @@ export {resolveOperation,sealBuildRequest,sealCompiledGraph,+ sealOutputValidationReceipt,selectedCandidate,valueRefKey,verifyBuildRequest,verifyCompiledGraph,+ verifyOutputValidationReceipt,} from "./graph.js";export { compileBuild, deriveBuildPlan, validatePlan } from "./plan.js";export { reduce, start } from "./reducer.js";diff --git a/packages/estimate/README.md b/packages/estimate/README.mdnew file mode 100644index 00000000..1024751e--- /dev/null+++ b/packages/estimate/README.md@@ -0,0 +1,23 @@+# `@svml/estimate`++Provider-free deterministic speech-duration planning.++`<estimate:Speech>` consumes the public `NarrativeSpeechExcerpt` contract and produces the public+`SpeechDuration` contract. It uses a language-aware syllable/character/mora rate, then applies an+explicit tail padding, bounds and rounding policy. It performs no network or media work.++```xml+<estimate:Speech+ id="opening-duration"+ source={story.segment.opening.speech}+ language="en"+ pace="normal"+ padding="0.3"+ min="4"+ max="15"+ rounding="ceil"+/>+```++The output is `opening-duration.duration`. Estimate is only one possible producer of this shared+value; model packages consume the contract rather than depending on this package.diff --git a/packages/estimate/package.json b/packages/estimate/package.jsonnew file mode 100644index 00000000..325da65e--- /dev/null+++ b/packages/estimate/package.json@@ -0,0 +1,16 @@+{+ "name": "@svml/estimate",+ "version": "0.0.0-dev",+ "private": true,+ "type": "module",+ "exports": {+ ".": "./src/index.ts"+ },+ "dependencies": {+ "@svml/component-kit": "workspace:*",+ "@svml/contracts": "workspace:*",+ "@svml/elaborator": "workspace:*",+ "@svml/protocol": "workspace:*",+ "@svml/text": "workspace:*"+ }+}diff --git a/packages/estimate/src/component.ts b/packages/estimate/src/component.tsnew file mode 100644index 00000000..fe12e1b2--- /dev/null+++ b/packages/estimate/src/component.ts@@ -0,0 +1,33 @@+import type { ComponentPackage } from "@svml/component-kit";+import type { NarrativeSpeechExcerpt } from "@svml/contracts";+import type { StoredValue } from "@svml/protocol";+import { canonicalize } from "@svml/protocol";++import { estimateProducers } from "./manifest.js";+import { estimateSpeechDuration, estimateSpeechImplementationDigest } from "./program.js";+import type { SpeechEstimatePolicy } from "./types.js";++function inline<T>(value: StoredValue | undefined, subject: string): T {+ if (value?.kind !== "inline") throw new Error(`${subject} must be inline`);+ return value.value as unknown as T;+}++export const estimateComponent = {+ name: "@svml/estimate",+ producers: [{+ producer: estimateProducers.speech,+ implementationDigest: estimateSpeechImplementationDigest,+ handler: ({ inputs }) => ({+ outputs: {+ duration: {+ kind: "inline",+ value: canonicalize(estimateSpeechDuration(+ inline<NarrativeSpeechExcerpt>(inputs.speech?.value, "NarrativeSpeechExcerpt"),+ inline<SpeechEstimatePolicy>(inputs.policy?.value, "SpeechEstimatePolicy"),+ )),+ },+ },+ needs: {},+ }),+ }],+} satisfies ComponentPackage;diff --git a/packages/estimate/src/fragment.ts b/packages/estimate/src/fragment.tsnew file mode 100644index 00000000..eb40a709--- /dev/null+++ b/packages/estimate/src/fragment.ts@@ -0,0 +1,34 @@+import { contractTypes } from "@svml/contracts";+import { sealGraphFragment } from "@svml/elaborator";++import { estimateProducers, estimateTypes } 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 speechEstimateFragment = sealGraphFragment({+ name: "@svml/estimate/speech@1",+ inputs: [+ { name: "speech", type: contractTypes.narrativeSpeechExcerpt },+ { name: "policy", type: estimateTypes.speechPolicy },+ ],+ operations: [{+ id: "estimate",+ producer: estimateProducers.speech,+ inputs: { speech: input("speech"), policy: input("policy") },+ result: { kind: "output", name: "duration" },+ }],+ exports: [{+ name: "duration",+ type: contractTypes.speechDuration,+ root: operation("estimate"),+ semanticInputs: ["speech", "policy"],+ affinity: [+ { resultPointer: "/sourceSpeechExcerptDigest", source: input("speech"), sourcePointer: "/excerptDigest" },+ { resultPointer: "/segmentId", source: input("speech"), sourcePointer: "/id" },+ { resultPointer: "/tokenStart", source: input("speech"), sourcePointer: "/tokenStart" },+ { resultPointer: "/tokenEndExclusive", source: input("speech"), sourcePointer: "/tokenEndExclusive" },+ ],+ fidelity: "exact",+ }],+});diff --git a/packages/estimate/src/index.ts b/packages/estimate/src/index.tsnew file mode 100644index 00000000..984ea924--- /dev/null+++ b/packages/estimate/src/index.ts@@ -0,0 +1,22 @@+export { estimateComponent } from "./component.js";+export { speechEstimateFragment } from "./fragment.js";+export {+ estimateManifest,+ estimateManifestDigest,+ estimateModuleRef,+ estimateProducers,+ estimateSurfaceImplementationDigest,+ estimateTypes,+ speechEstimatePolicySchema,+} from "./manifest.js";+export {+ assertSpeechEstimatePolicy,+ countSpeechEstimateUnits,+ detectSpeechEstimateLanguage,+ estimateSpeechDuration,+ estimateSpeechImplementationDigest,+ resolveSpeechEstimateLanguage,+ sealSpeechEstimatePolicy,+} from "./program.js";+export { decodeSpeechEstimateSurface } from "./surface.js";+export type * from "./types.js";diff --git a/packages/estimate/src/manifest.ts b/packages/estimate/src/manifest.tsnew file mode 100644index 00000000..655989fa--- /dev/null+++ b/packages/estimate/src/manifest.ts@@ -0,0 +1,82 @@+import {+ contractTypes,+ videoContractDependencies,+} from "@svml/contracts";+import { digestOf } from "@svml/protocol";+import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@svml/protocol";++import { estimateSpeechImplementationDigest } from "./program.js";++export const estimateModuleRef = { name: "@svml/estimate", version: "0.0.0-dev" } as const;+export const estimateTypes = {+ speechPolicy: { module: estimateModuleRef, name: "SpeechEstimatePolicy" },+} satisfies Record<string, TypeRef>;+export const estimateProducers = {+ speech: { module: estimateModuleRef, name: "estimate-speech-duration" },+} satisfies Record<string, ProducerRef>;+export const estimateSurfaceImplementationDigest = digestOf("@svml/estimate/speech-surface@1");++const number = { kind: "number" } as const satisfies ValueSchema;+const digest = { kind: "string", minLength: 71, maxLength: 71 } as const satisfies ValueSchema;+const speechEstimatePolicySchema: ValueSchema = {+ kind: "object",+ fields: {+ contract: { schema: { kind: "literal", value: "svml.speech-estimate-policy@1" } },+ language: { schema: { kind: "string", enum: ["auto", "en", "zh", "ja", "es"] } },+ pace: { schema: { kind: "string", enum: ["slow", "normal", "fast"] } },+ paddingSec: { schema: number },+ minimumSec: { schema: number },+ maximumSec: { schema: number },+ rounding: { schema: { kind: "string", enum: ["none", "round", "ceil"] } },+ policyDigest: { schema: digest },+ },+};++export const estimateManifest: ModuleManifest = {+ format: "svml.module@0",+ name: estimateModuleRef.name,+ version: estimateModuleRef.version,+ dependencies: [+ videoContractDependencies.narrative,+ videoContractDependencies.speech,+ ],+ types: [{ name: estimateTypes.speechPolicy.name, schema: speechEstimatePolicySchema }],+ capabilities: [],+ surfaces: [{+ name: "speech",+ tag: "Speech",+ mode: "structured",+ outputs: [estimateTypes.speechPolicy, contractTypes.speechDuration],+ implementation: {+ kind: "trusted-frontend-surface",+ locator: "@svml/estimate/speech-surface",+ digest: estimateSurfaceImplementationDigest,+ },+ }],+ producers: [{+ name: estimateProducers.speech.name,+ inputs: [+ { name: "speech", type: contractTypes.narrativeSpeechExcerpt },+ { name: "policy", type: estimateTypes.speechPolicy },+ ],+ outputs: [{+ name: "duration",+ type: contractTypes.speechDuration,+ affinity: [+ { resultPointer: "/sourceSpeechExcerptDigest", input: "speech", inputPointer: "/excerptDigest" },+ { resultPointer: "/segmentId", input: "speech", inputPointer: "/id" },+ { resultPointer: "/tokenStart", input: "speech", inputPointer: "/tokenStart" },+ { resultPointer: "/tokenEndExclusive", input: "speech", inputPointer: "/tokenEndExclusive" },+ ],+ }],+ needs: [],+ implementation: {+ kind: "registered",+ locator: "@svml/estimate/estimate-speech",+ digest: estimateSpeechImplementationDigest,+ },+ }],+};++export const estimateManifestDigest = digestOf(estimateManifest);+export { speechEstimatePolicySchema };diff --git a/packages/estimate/src/program.ts b/packages/estimate/src/program.tsnew file mode 100644index 00000000..0637d81e--- /dev/null+++ b/packages/estimate/src/program.ts@@ -0,0 +1,198 @@+import {+ assertSpeechDurationIdentity,+ sealSpeechDuration,+} from "@svml/contracts";+import type {+ NarrativeSpeechExcerpt,+ SpeechDuration,+} from "@svml/contracts";+import { canonicalize, digestOf, isDigest } from "@svml/protocol";++import type {+ ResolvedSpeechEstimateLanguage,+ SpeechEstimateLanguage,+ SpeechEstimatePolicy,+} from "./types.js";++export const estimateSpeechImplementationDigest = digestOf("@svml/estimate/estimate-speech@1");++const BASE_RATE: Readonly<Record<ResolvedSpeechEstimateLanguage, number>> = {+ en: 4.5,+ zh: 5.25,+ ja: 7.5,+ es: 5.9,+};++const PACE_MULTIPLIER = {+ slow: 0.8,+ normal: 1,+ fast: 1.25,+} as const;++function words(text: string): string[] {+ return text.match(/[\p{L}\p{N}]+(?:['-][\p{L}\p{N}]+)?/gu) ?? [];+}++function looksSpanish(text: string): boolean {+ if (/[ñáéíóúü¿¡]/iu.test(text)) return true;+ const tokens = words(text).map((word) => word.toLowerCase());+ if (tokens.length === 0) return false;+ const hits = tokens.filter((word) => /^(?:que|de|la|el|los|las|un|una|para|por|con|sin|pero|porque|como|más|muy|este|esta|eso|soy|eres|es|son|estoy|está|tengo|quiero|puedo|ahora|cuando|todo|nada|aquí|así)$/u.test(word)).length;+ return hits >= Math.max(2, Math.ceil(tokens.length * 0.18));+}++export function detectSpeechEstimateLanguage(text: string): ResolvedSpeechEstimateLanguage {+ const han = (text.match(/[\u3400-\u9fff]/gu) ?? []).length;+ const kana = (text.match(/[\u3040-\u30ff]/gu) ?? []).length;+ const ascii = (text.match(/[A-Za-z]/gu) ?? []).length;+ if (kana > Math.max(han, ascii / 4)) return "ja";+ if (han > ascii / 4) return "zh";+ if (looksSpanish(text)) return "es";+ return "en";+}++function englishSyllables(word: string): number {+ const normalized = word.toLowerCase().replace(/[^a-z]/gu, "");+ if (!normalized) return 0;+ if (normalized.length <= 3) return 1;+ const stripped = normalized+ .replace(/(?:[^laeiouy]es|ed|[^laeiouy]e)$/u, "")+ .replace(/^y/u, "");+ return Math.max(1, stripped.match(/[aeiouy]{1,2}/gu)?.length ?? 1);+}++function spanishVowelNuclei(run: string): number {+ let nuclei = 0;+ let pending = "";+ const flush = () => {+ if (!pending) return;+ nuclei += Math.max(1, pending.match(/[aeoáéó]/gu)?.length ?? 0);+ pending = "";+ };+ for (const character of run) {+ if (character === "í" || character === "ú") {+ flush();+ nuclei += 1;+ } else {+ pending += character;+ }+ }+ flush();+ return nuclei;+}++function spanishSyllables(word: string): number {+ let normalized = word.toLowerCase().normalize("NFC").replace(/[^a-záéíóúüñ]/gu, "");+ if (!normalized) return 0;+ if (normalized === "y") normalized = "i";+ else normalized = normalized.replace(/y$/u, "i");+ const runs = normalized.match(/[aeiouáéíóúü]+/gu) ?? [];+ return Math.max(1, runs.reduce((sum, run) => sum + spanishVowelNuclei(run), 0));+}++export function countSpeechEstimateUnits(+ text: string,+ language: ResolvedSpeechEstimateLanguage,+): number {+ if (language === "zh" || language === "ja") {+ const cjk = (text.match(/[\u3400-\u9fff\u3040-\u30ff]/gu) ?? []).length;+ const latin = text+ .replace(/[\u3400-\u9fff\u3040-\u30ff]/gu, " ")+ .split(/\s+/u)+ .filter((word) => /[A-Za-z]/u.test(word));+ return cjk + latin.reduce((sum, word) => sum + englishSyllables(word), 0);+ }+ if (language === "es") return words(text).reduce((sum, word) => sum + spanishSyllables(word), 0);+ return words(text).reduce((sum, word) => sum + englishSyllables(word), 0);+}++function policyContent(value: Omit<SpeechEstimatePolicy, "policyDigest">) {+ return canonicalize(value);+}++export function sealSpeechEstimatePolicy(+ value: Omit<SpeechEstimatePolicy, "policyDigest">,+): SpeechEstimatePolicy {+ const content = policyContent(value);+ const policy: SpeechEstimatePolicy = { ...value, policyDigest: digestOf(content) };+ assertSpeechEstimatePolicy(policy);+ return policy;+}++export function assertSpeechEstimatePolicy(value: SpeechEstimatePolicy): void {+ if (+ value.contract !== "svml.speech-estimate-policy@1"+ || !(["auto", "en", "zh", "ja", "es"] as const).includes(value.language)+ || !(["slow", "normal", "fast"] as const).includes(value.pace)+ || !(["none", "round", "ceil"] as const).includes(value.rounding)+ || !Number.isFinite(value.paddingSec)+ || value.paddingSec < 0+ || !Number.isFinite(value.minimumSec)+ || value.minimumSec < 0+ || !Number.isFinite(value.maximumSec)+ || value.maximumSec <= 0+ || value.minimumSec > value.maximumSec+ ) {+ throw new Error("SpeechEstimatePolicy is invalid");+ }+ const { policyDigest: _digest, ...raw } = value;+ const content = policyContent(raw);+ if (!isDigest(value.policyDigest) || value.policyDigest !== digestOf(content)) {+ throw new Error("SpeechEstimatePolicy digest differs from its contents");+ }+}++function assertSpeechExcerpt(value: NarrativeSpeechExcerpt): void {+ if (+ value.contract !== "svml.narrative-speech-excerpt@1"+ || value.kind !== "segment"+ || value.id.length === 0+ || !Number.isSafeInteger(value.tokenStart)+ || !Number.isSafeInteger(value.tokenEndExclusive)+ || value.tokenEndExclusive <= value.tokenStart+ || value.speech.trim().length === 0+ ) {+ throw new Error("NarrativeSpeechExcerpt is invalid");+ }+ const { excerptDigest: _digest, ...content } = value;+ if (!isDigest(value.excerptDigest) || value.excerptDigest !== digestOf(canonicalize(content))) {+ throw new Error("NarrativeSpeechExcerpt digest differs from its contents");+ }+}++function rounded(value: number, mode: SpeechEstimatePolicy["rounding"]): number {+ if (mode === "ceil") return Math.ceil(value);+ if (mode === "round") return Math.round(value);+ return value;+}++export function estimateSpeechDuration(+ excerpt: NarrativeSpeechExcerpt,+ policy: SpeechEstimatePolicy,+): SpeechDuration {+ assertSpeechExcerpt(excerpt);+ assertSpeechEstimatePolicy(policy);+ const language = policy.language === "auto" ? detectSpeechEstimateLanguage(excerpt.speech) : policy.language;+ const units = countSpeechEstimateUnits(excerpt.speech, language);+ if (units < 1) throw new Error("NarrativeSpeechExcerpt contains no countable speech units");+ const raw = units / (BASE_RATE[language] * PACE_MULTIPLIER[policy.pace]) + policy.paddingSec;+ const firstClamp = Math.min(policy.maximumSec, Math.max(policy.minimumSec, raw));+ const durationSec = Math.min(policy.maximumSec, Math.max(policy.minimumSec, rounded(firstClamp, policy.rounding)));+ const duration = sealSpeechDuration({+ contract: "svml.speech-duration@1",+ segmentId: excerpt.id,+ tokenStart: excerpt.tokenStart,+ tokenEndExclusive: excerpt.tokenEndExclusive,+ sourceSpeechExcerptDigest: excerpt.excerptDigest,+ durationSec,+ });+ assertSpeechDurationIdentity(duration);+ return duration;+}++export function resolveSpeechEstimateLanguage(+ text: string,+ requested: SpeechEstimateLanguage,+): ResolvedSpeechEstimateLanguage {+ return requested === "auto" ? detectSpeechEstimateLanguage(text) : requested;+}diff --git a/packages/estimate/src/surface.ts b/packages/estimate/src/surface.tsnew file mode 100644index 00000000..54732958--- /dev/null+++ b/packages/estimate/src/surface.ts@@ -0,0 +1,103 @@+import { contractTypes } from "@svml/contracts";+import type { CanonicalValue } from "@svml/protocol";+import type {+ StructuredElement,+ StructuredSurfaceHandler,+ SurfaceResolvedReference,+ TextAttributeValue,+} from "@svml/text";++import { speechEstimateFragment } from "./fragment.js";+import { estimateTypes } from "./manifest.js";+import { sealSpeechEstimatePolicy } from "./program.js";+import type {+ SpeechEstimateLanguage,+ SpeechEstimatePace,+ SpeechEstimateRounding,+} from "./types.js";++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 attributes(element: StructuredElement): void {+ const required = ["id", "source"];+ const optional = ["language", "pace", "padding", "min", "max", "rounding"];+ const allowed = new Set([...required, ...optional]);+ if (+ required.some((name) => element.attributes[name] === undefined)+ || Object.keys(element.attributes).some((name) => !allowed.has(name))+ ) {+ throw new Error(`${element.name} requires id and source; optional: ${optional.join(", ")}`);+ }+ if (element.children.some((child) => child.kind === "element" || child.value.trim().length > 0)) {+ throw new Error(`${element.name} must be empty`);+ }+}++function text(element: StructuredElement, name: string, fallback?: string): string {+ const value = element.attributes[name] ?? fallback;+ if (typeof value !== "string" || value.trim().length === 0) {+ throw new Error(`${element.name}.${name} must be a non-empty string`);+ }+ return value.trim();+}++function number(element: StructuredElement, name: string, fallback: number): number {+ const value = Number(text(element, name, String(fallback)));+ if (!Number.isFinite(value)) throw new Error(`${element.name}.${name} must be a finite number`);+ return value;+}++function reference(+ element: StructuredElement,+ resolveReference: (path: string) => SurfaceResolvedReference | undefined,+): SurfaceResolvedReference {+ const raw: TextAttributeValue | undefined = element.attributes.source;+ if (typeof raw !== "object" || raw.kind !== "reference") {+ throw new Error(`${element.name}.source must be a whole-value reference`);+ }+ const result = resolveReference(raw.path);+ if (result === undefined || !sameType(result.type, contractTypes.narrativeSpeechExcerpt)) {+ throw new Error(`${element.name}.source must reference a NarrativeSpeechExcerpt`);+ }+ return result;+}++export const decodeSpeechEstimateSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {+ attributes(element);+ const id = text(element, "id");+ const source = reference(element, resolveReference);+ const language = text(element, "language", "auto") as SpeechEstimateLanguage;+ const pace = text(element, "pace", "normal") as SpeechEstimatePace;+ const rounding = text(element, "rounding", "ceil") as SpeechEstimateRounding;+ const policy = sealSpeechEstimatePolicy({+ contract: "svml.speech-estimate-policy@1",+ language,+ pace,+ paddingSec: number(element, "padding", 0.3),+ minimumSec: number(element, "min", 4),+ maximumSec: number(element, "max", 15),+ rounding,+ });+ const policyId = `${id}.policy`;+ return {+ records: [{+ id: policyId,+ type: estimateTypes.speechPolicy,+ value: { kind: "inline", value: policy as unknown as CanonicalValue },+ range: element.range,+ }],+ components: [{+ id,+ fragment: speechEstimateFragment.id,+ inputs: {+ speech: source.ref,+ policy: { kind: "record", id: policyId },+ },+ outputs: { duration: `${id}.duration` },+ range: element.range,+ }],+ fragments: [speechEstimateFragment],+ };+};diff --git a/packages/estimate/src/types.ts b/packages/estimate/src/types.tsnew file mode 100644index 00000000..3c286f6e--- /dev/null+++ b/packages/estimate/src/types.ts@@ -0,0 +1,17 @@+import type { Digest } from "@svml/protocol";++export type SpeechEstimateLanguage = "auto" | "en" | "zh" | "ja" | "es";+export type ResolvedSpeechEstimateLanguage = Exclude<SpeechEstimateLanguage, "auto">;+export type SpeechEstimatePace = "slow" | "normal" | "fast";+export type SpeechEstimateRounding = "none" | "round" | "ceil";++export type SpeechEstimatePolicy = {+ readonly contract: "svml.speech-estimate-policy@1";+ readonly language: SpeechEstimateLanguage;+ readonly pace: SpeechEstimatePace;+ readonly paddingSec: number;+ readonly minimumSec: number;+ readonly maximumSec: number;+ readonly rounding: SpeechEstimateRounding;+ readonly policyDigest: Digest;+};diff --git a/packages/estimate/test/estimate.test.ts b/packages/estimate/test/estimate.test.tsnew file mode 100644index 00000000..1ea43d27--- /dev/null+++ b/packages/estimate/test/estimate.test.ts@@ -0,0 +1,51 @@+import assert from "node:assert/strict";+import test from "node:test";++import type { NarrativeSpeechExcerpt } from "@svml/contracts";+import {+ countSpeechEstimateUnits,+ estimateSpeechDuration,+ sealSpeechEstimatePolicy,+} from "@svml/estimate";+import { canonicalize, digestOf } from "@svml/protocol";++function excerpt(id: string, speech: string): NarrativeSpeechExcerpt {+ const content = {+ contract: "svml.narrative-speech-excerpt@1" as const,+ kind: "segment" as const,+ id,+ tokenStart: 0,+ tokenEndExclusive: speech.trim().split(/\s+/u).length,+ speech,+ };+ return { ...content, excerptDigest: digestOf(canonicalize(content)) };+}++const normal = sealSpeechEstimatePolicy({+ contract: "svml.speech-estimate-policy@1",+ language: "en",+ pace: "normal",+ paddingSec: 0.3,+ minimumSec: 4,+ maximumSec: 15,+ rounding: "ceil",+});++test("normal English speech estimate preserves the old syllable-rate policy", () => {+ const source = excerpt(+ "opening",+ "Video editing begins with meaning, not a pile of clips on a timeline.",+ );+ assert.equal(countSpeechEstimateUnits(source.speech, "en"), 21);+ const result = estimateSpeechDuration(source, normal);+ assert.equal(result.durationSec, 5);+ assert.equal(result.segmentId, source.id);+ assert.equal(result.sourceSpeechExcerptDigest, source.excerptDigest);+});++test("the minimum applies before rounding and the maximum applies after rounding", () => {+ assert.equal(estimateSpeechDuration(excerpt("short", "Hello."), normal).durationSec, 4);+ const { policyDigest: _digest, ...normalContent } = normal;+ const bounded = sealSpeechEstimatePolicy({ ...normalContent, maximumSec: 4.5 });+ assert.equal(estimateSpeechDuration(excerpt("long", "This sentence intentionally contains far more spoken syllables than the selected model duration allows."), bounded).durationSec, 4.5);+});diff --git a/packages/prelude-video/package.json b/packages/prelude-video/package.jsonindex 7bbcc007..9f8ce93a 100644--- a/packages/prelude-video/package.json+++ b/packages/prelude-video/package.json@@ -14,6 +14,7 @@"@svml/caption": "workspace:*","@svml/caption-gemini": "workspace:*","@svml/contracts": "workspace:*",+ "@svml/estimate": "workspace:*","@svml/generation": "workspace:*","@svml/film": "workspace:*","@svml/hyperframes": "workspace:*",diff --git a/packages/prelude-video/src/index.ts b/packages/prelude-video/src/index.tsindex fee77157..b162c663 100644--- a/packages/prelude-video/src/index.ts+++ b/packages/prelude-video/src/index.ts@@ -31,6 +31,13 @@ import {captionGeminiModuleRef,decodeCaptionGeminiPlannerSurface,} from "@svml/caption-gemini";+import {+ decodeSpeechEstimateSurface,+ estimateComponent,+ estimateManifest,+ estimateModuleRef,+ estimateSurfaceImplementationDigest,+} from "@svml/estimate";import {decodeFilmSurface,filmComponent,@@ -116,6 +123,7 @@ export const svmlPackage: NodePackageActivation = {: {}),})),{ manifest: generationManifest },+ { manifest: estimateManifest, specifiers: ["@svml/estimate", "@svml/estimate@1"] },{ manifest: seedanceManifest, specifiers: ["@svml/seedance", "@svml/seedance@1"] },{ manifest: scriptManifest, specifiers: ["@svml/script", "@svml/script@1"] },{ manifest: svsManifest },@@ -142,6 +150,7 @@ export const svmlPackage: NodePackageActivation = {components: [...videoContractsComponents,generationComponent,+ estimateComponent,seedanceComponent,captionComponent,captionGeminiComponent,@@ -157,6 +166,13 @@ export const svmlPackage: NodePackageActivation = {hyperframesRenderComponent,],textSurfaces: [+ {+ module: estimateModuleRef,+ surface: "speech",+ mode: "structured",+ implementationDigest: estimateSurfaceImplementationDigest,+ handler: decodeSpeechEstimateSurface,+ },{module: mediaModuleRef,surface: "image",diff --git a/packages/protocol/src/build.ts b/packages/protocol/src/build.tsindex 5234c2c0..38211fd6 100644--- a/packages/protocol/src/build.ts+++ b/packages/protocol/src/build.ts@@ -203,6 +203,24 @@ export type ProvidedValue = {readonly value: StoredValue;readonly provenance?: CanonicalValue;readonly validation?: TypeValidationReceipt;+ /** Trusted Host proof that this exact historical Record already realized this Output. */+ readonly outputValidation?: OutputValidationReceipt;+};++/**+ * A content-bound admission receipt issued after a trusted Host verifies a prior BuildState.+ * It is deliberately generic: Core learns neither "pin" nor any media/domain concept.+ */+export type OutputValidationReceipt = {+ readonly format: "svml.output-validation@1";+ readonly id: Digest;+ /** Author-graph source digest before any external Realization Overlay. */+ readonly graphSource: Digest;+ readonly output: LogicalOutputId;+ readonly recordDigest: Digest;+ readonly sourceBuild: Digest;+ readonly sourceRequest: Digest;+ readonly sourceCandidate: CandidateId;};export type CandidateRoot =diff --git a/packages/provider-kie/test/models.test.ts b/packages/provider-kie/test/models.test.tsindex c5c80c01..6d58b407 100644--- a/packages/provider-kie/test/models.test.ts+++ b/packages/provider-kie/test/models.test.ts@@ -2,7 +2,7 @@ import assert from "node:assert/strict";import test from "node:test";import { createResolvedClosure, digestOf } from "@svml/core";-import { mediaManifest, narrativeManifest } from "@svml/contracts";+import { videoContractManifests } from "@svml/contracts";import { verifyGraphFragment } from "@svml/elaborator";import {geminiOmniDefinition,@@ -40,8 +40,7 @@ test("all model manifests close over the shared generation contract and every FrseedreamDefinition,];const closure = createResolvedClosure([- mediaManifest,- narrativeManifest,+ ...videoContractManifests,generationManifest,seedanceManifest,minimaxH3Manifest,diff --git a/packages/realization/README.md b/packages/realization/README.mdindex bf5a57a0..4416be2f 100644--- a/packages/realization/README.md+++ b/packages/realization/README.md@@ -11,3 +11,9 @@ An attached Candidate is inert. It enters a finite BuildPlan only when a `BuildRselects it and a Target reaches its Logical Output. Product UI actions such as “Pin” create or locatean Existing-Value Candidate and then write that ordinary selection; they do not mutate Core state orrequire a database.++`createHistoricalCandidate()` is the trusted Host helper for this common case. It verifies the+complete prior `BuildState`, requires the same author Graph and the same semantic Logical Output,+then issues a content-addressed output-validation receipt binding the prior Record digest to that+output. The result is still an ordinary zero-input Existing-Value Candidate: no historical+Operation, Command or outstanding work is copied into the new Build.diff --git a/packages/realization/src/index.ts b/packages/realization/src/index.tsindex 547a1cab..3621e3e3 100644--- a/packages/realization/src/index.ts+++ b/packages/realization/src/index.ts@@ -1,4 +1,5 @@export {+ createHistoricalCandidate,createProvidedCandidate,RealizationError,resolveRealization,@@ -7,6 +8,7 @@ export {verifyResolvedRealization,} from "./overlay.js";export type {+ HistoricalCandidateInput,ProvidedCandidateInput,RealizationClosure,RealizationOverlay,diff --git a/packages/realization/src/overlay.ts b/packages/realization/src/overlay.tsindex 9c6867a8..89dcc79a 100644--- a/packages/realization/src/overlay.ts+++ b/packages/realization/src/overlay.ts@@ -3,11 +3,14 @@ import {digestOf,EMPTY_REALIZATION_DIGEST,isDigest,+ sealOutputValidationReceipt,resolveLogicalOutput,sealCompiledGraph,+ verifyBuildState,verifyCompiledGraph,} from "@svml/core";import type {+ BuildState,Candidate,CanonicalValue,CompiledGraph,@@ -17,6 +20,7 @@ import type {OperationNode,StoredValue,TypeValidationReceipt,+ OutputValidationReceipt,} from "@svml/protocol";export type RealizationOverlay = {@@ -47,6 +51,15 @@ export type ProvidedCandidateInput = {readonly record?: string;readonly provenance?: CanonicalValue;readonly validation?: TypeValidationReceipt;+ readonly outputValidation?: OutputValidationReceipt;+};++export type HistoricalCandidateInput = {+ /** Current author graph before any external Realization Overlay. */+ readonly source: CompiledGraph;+ /** A previously verified BuildState using this exact author graph source. */+ readonly build: BuildState;+ readonly output: string;};export class RealizationError extends Error {@@ -104,6 +117,7 @@ export function createProvidedCandidate(input: ProvidedCandidateInput): Candidatfidelity: input.fidelity,...(input.provenance === undefined ? {} : { provenance: canonicalize(input.provenance) }),...(input.validation === undefined ? {} : { validation: input.validation }),+ ...(input.outputValidation === undefined ? {} : { outputValidation: input.outputValidation }),};const suffix = digestOf(identity).slice("sha256:".length);return {@@ -116,12 +130,84 @@ export function createProvidedCandidate(input: ProvidedCandidateInput): Candidatvalue,...(input.provenance === undefined ? {} : { provenance: canonicalize(input.provenance) }),...(input.validation === undefined ? {} : { validation: input.validation }),+ ...(input.outputValidation === undefined ? {} : { outputValidation: input.outputValidation }),},},fidelity: input.fidelity,};}+/**+ * Admit one already verified historical Logical Output as an inert Existing Value Candidate.+ * The new Build is unrelated to recovery: only the exact Record value and its admission receipt+ * cross the boundary. No prior outstanding Command or execution state is reused.+ */+export function createHistoricalCandidate(input: HistoricalCandidateInput): Candidate {+ verifyCompiledGraph(input.build.program, input.source);+ verifyBuildState(input.build);+ assert(+ input.build.graph.source === input.source.source,+ "HISTORICAL_GRAPH_MISMATCH",+ "historical Build belongs to another author graph source",+ input.output,+ );+ const currentOutput = resolveLogicalOutput(input.source, input.output);+ const historicalOutput = resolveLogicalOutput(input.build.graph, input.output);+ assert(+ digestOf({+ id: currentOutput.id,+ type: currentOutput.type,+ semanticInputs: currentOutput.semanticInputs,+ affinity: currentOutput.affinity ?? [],+ }) === digestOf({+ id: historicalOutput.id,+ type: historicalOutput.type,+ semanticInputs: historicalOutput.semanticInputs,+ affinity: historicalOutput.affinity ?? [],+ }),+ "HISTORICAL_OUTPUT_MISMATCH",+ "historical Build has another Logical Output definition",+ input.output,+ );+ const selection = input.build.plan.selections.find((item) => item.output === input.output);+ assert(selection !== undefined, "HISTORICAL_OUTPUT_UNSELECTED", "historical Build did not select this Logical Output", input.output);+ const record = input.build.records.find((item) => item.id === selection.record);+ assert(record !== undefined, "HISTORICAL_RECORD_MISSING", "historical Output Record is absent", selection.record);+ assert(+ record.type.module.name === currentOutput.type.module.name+ && record.type.module.version === currentOutput.type.module.version+ && record.type.name === currentOutput.type.name,+ "HISTORICAL_TYPE_MISMATCH",+ "historical Output Record has another Type",+ record.id,+ );+ const outputValidation = record.conformance === "exact"+ ? sealOutputValidationReceipt({+ graphSource: input.source.source,+ output: input.output,+ recordDigest: record.digest,+ sourceBuild: input.build.id,+ sourceRequest: input.build.request.digest,+ sourceCandidate: selection.candidate,+ })+ : undefined;+ return createProvidedCandidate({+ output: input.output,+ value: record.value,+ fidelity: record.conformance,+ provenance: {+ format: "svml.historical-output@1",+ sourceBuild: input.build.id,+ sourceRequest: input.build.request.digest,+ sourceCandidate: selection.candidate,+ sourceRecord: record.id,+ sourceRecordDigest: record.digest,+ },+ ...(record.validation === undefined ? {} : { validation: record.validation }),+ ...(outputValidation === undefined ? {} : { outputValidation }),+ });+}+export function verifyRealizationOverlay(program: LinkedProgram,source: CompiledGraph,diff --git a/packages/realization/test/overlay.test.ts b/packages/realization/test/overlay.test.tsindex b8b5739d..59b23a8e 100644--- a/packages/realization/test/overlay.test.ts+++ b/packages/realization/test/overlay.test.ts@@ -6,6 +6,7 @@ import {digestOf,EMPTY_REALIZATION_DIGEST,link,+ reduce,sealBuildRequest,sealCompiledGraph,sealRecord,@@ -18,13 +19,16 @@ import {sealGraphFragment,} from "@svml/elaborator";import type {+ BuildState,CompiledGraph,LinkedProgram,+ InvokeProducerCommand,ModuleManifest,ProducerRef,TypeRef,} from "@svml/protocol";import {+ createHistoricalCandidate,createProvidedCandidate,resolveRealization,sealRealizationOverlay,@@ -141,6 +145,40 @@ function providedOverlay(source: CompiledGraph, value: string, label: string) {};}+function completedAffinityBuild(): { readonly program: LinkedProgram; readonly source: CompiledGraph; readonly state: BuildState } {+ const base = fixture();+ const source = sealCompiledGraph({+ program: base.source.program,+ outputs: base.source.outputs.map((output) => ({+ ...output,+ affinity: [{+ resultPointer: "",+ source: { kind: "record" as const, id: "prompt:shot" },+ sourcePointer: "",+ }],+ })),+ candidates: base.source.candidates,+ operations: base.source.operations,+ });+ const initial = start(base.program, source, sealBuildRequest({+ graph: source.id,+ targets: [{ output: "shot.visual", accepts: "exact" }],+ bindings: [],+ }));+ const ready = reduce(initial);+ const command = ready.commands.find((item): item is InvokeProducerCommand => item.kind === "invoke-producer");+ assert.ok(command);+ const completed = reduce(ready.state, {+ kind: "producer-completed",+ id: "event:historical-media",+ command: command.id,+ outputs: { media: { kind: "inline", value: "A founder speaking to camera." } },+ needs: {},+ });+ assert.equal(completed.state.status, "complete");+ return { program: base.program, source, state: completed.state };+}+test("an attached Existing Value is inert until BuildRequest explicitly selects it", () => {const { program, source } = fixture();const { overlay, candidate } = providedOverlay(source, "approved video", "v1");@@ -168,6 +206,50 @@ test("an attached Existing Value is inert until BuildRequest explicitly selectsassert.equal(selected.plan.selections[0]?.candidate, candidate.id);});+test("a verified historical Output becomes an exact zero-edge Candidate without replaying its Producer", () => {+ const { program, source, state: historical } = completedAffinityBuild();+ const candidate = createHistoricalCandidate({ source, build: historical, output: "shot.visual" });+ assert.equal(candidate.root.kind, "value");+ assert.equal(candidate.fidelity, "exact");+ const overlay = sealRealizationOverlay({ sourceGraph: source.id, candidates: [candidate], operations: [] });+ const realized = resolveRealization(program, source, [overlay]);+ const fresh = start(program, realized.graph, sealBuildRequest({+ graph: realized.graph.id,+ targets: [{ output: "shot.visual", accepts: "exact" }],+ bindings: [{ output: "shot.visual", candidate: candidate.id }],+ }));+ assert.deepEqual(fresh.plan.steps, []);+ assert.equal(fresh.plan.initialValues.length, 1);+ assert.notEqual(fresh.id, historical.id);+});++test("historical admission rejects another graph and a content-tampered value", () => {+ const { program, source, state: historical } = completedAffinityBuild();+ const other = sealCompiledGraph({+ program: source.program,+ outputs: source.outputs.map((output) => ({ ...output, affinity: [] })),+ candidates: source.candidates,+ operations: source.operations,+ });+ assert.throws(+ () => createHistoricalCandidate({ source: other, build: historical, output: "shot.visual" }),+ /another author graph source/u,+ );++ const admitted = createHistoricalCandidate({ source, build: historical, output: "shot.visual" });+ assert.equal(admitted.root.kind, "value");+ const outputValidation = admitted.root.value.outputValidation;+ assert.notEqual(outputValidation, undefined);+ const tampered = createProvidedCandidate({+ output: admitted.output,+ value: { kind: "inline", value: "tampered" },+ fidelity: "exact",+ outputValidation: outputValidation!,+ });+ const overlay = sealRealizationOverlay({ sourceGraph: source.id, candidates: [tampered], operations: [] });+ assert.throws(() => resolveRealization(program, source, [overlay]), /belongs to another value/u);+});+test("changing the attached Value changes Overlay, realized Graph and BuildRequest identity", () => {const { program, source } = fixture();const left = providedOverlay(source, "approved video A", "A");diff --git a/packages/seedance/src/fragment.ts b/packages/seedance/src/fragment.tsindex 05a0e4ea..7cf1d7ec 100644--- a/packages/seedance/src/fragment.ts+++ b/packages/seedance/src/fragment.ts@@ -2,6 +2,7 @@ import { contractTypes } from "@svml/contracts";import { sealGraphFragment } from "@svml/elaborator";import { generationProducers } from "@svml/generation";import type { ExactModelEndpoint } from "@svml/model-kit";+import type { ProducerRef } from "@svml/protocol";const input = (name: string) => ({ kind: "fragment-input" as const, name });const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });@@ -42,3 +43,48 @@ export function createSeedanceGenerationFragment(endpoint: ExactModelEndpoint) {}],});}++export function createSeedanceSpeechGenerationFragment(+ endpoint: ExactModelEndpoint,+ compileProducer: ProducerRef,+) {+ return sealGraphFragment({+ name: `@svml/seedance/${endpoint.key}-speech-primary-video@1`,+ inputs: [+ { name: "program", type: { module: endpoint.producer.module, name: "SpeechProgram" } },+ { name: "duration", type: contractTypes.speechDuration },+ ],+ operations: [+ {+ id: "compile-request",+ producer: compileProducer,+ inputs: { program: input("program"), duration: input("duration") },+ result: { kind: "output", name: "request" },+ },+ {+ id: "generate",+ producer: endpoint.producer,+ inputs: { request: operation("compile-request") },+ result: { kind: "need", name: "generation", accepts: "exact" },+ },+ {+ id: "select-primary-video",+ producer: generationProducers.primaryVideo,+ inputs: { set: operation("generate") },+ result: { kind: "output", name: "video" },+ },+ ],+ exports: [{+ name: "video",+ type: contractTypes.blobArtifact,+ root: operation("select-primary-video"),+ semanticInputs: ["program", "duration"],+ affinity: [{+ resultPointer: "/digest",+ source: operation("generate"),+ sourcePointer: "/videos/0/digest",+ }],+ fidelity: "exact",+ }],+ });+}diff --git a/packages/seedance/src/index.ts b/packages/seedance/src/index.tsindex 4f021250..059dd507 100644--- a/packages/seedance/src/index.ts+++ b/packages/seedance/src/index.ts@@ -9,10 +9,13 @@ import {} from "@svml/generation";import { defineExactModelModule } from "@svml/model-kit";import {+ assertSpeechDurationIdentity,+ contractTypes,videoContractDependencies,} from "@svml/contracts";+import type { SpeechDuration } from "@svml/contracts";import { canonicalize, digestOf } from "@svml/protocol";-import type { BlobRef, Digest, TypeRef, ValueSchema } from "@svml/protocol";+import type { BlobRef, Digest, ProducerRef, TypeRef, ValueSchema } from "@svml/protocol";export const seedanceModuleRef = { name: "@svml/seedance", version: "0.0.0-dev" } as const;export const seedanceModels = ["seedance-2", "seedance-2-fast", "seedance-2-mini"] as const;@@ -50,13 +53,43 @@ export type SeedancePrompt = {readonly promptDigest: Digest;};+export type SeedanceSpeechProgram = {+ readonly contract: "svml.seedance-speech-program@1";+ readonly model: SeedanceModel;+ readonly prompt: string;+ readonly mode: SeedanceMode;+ readonly resolution: "480p" | "720p" | "1080p";+ readonly aspectRatio: "1:1" | "4:3" | "3:4" | "16:9" | "9:16" | "21:9" | "adaptive";+ readonly generateAudio: true;+ readonly webSearch: boolean;+ readonly segment: {+ readonly id: string;+ readonly tokenStart: number;+ readonly tokenEndExclusive: number;+ readonly dialogueExcerptDigest: Digest;+ };+ readonly programDigest: Digest;+};+export const seedanceTypes = {prompt: { module: seedanceModuleRef, name: "Prompt" },+ speechProgram: { module: seedanceModuleRef, name: "SpeechProgram" },} satisfies Record<string, TypeRef>;+export const seedanceSpeechCompileProducers = Object.fromEntries(+ seedanceModels.map((model) => [model, {+ module: seedanceModuleRef,+ name: `compile-${model}-speech-request`,+ }]),+) as Record<SeedanceModel, ProducerRef>;++export const seedanceSpeechCompileImplementationDigests = Object.fromEntries(+ seedanceModels.map((model) => [model, digestOf(`@svml/seedance/compile-${model}-speech-request@1`)]),+) as Record<SeedanceModel, Digest>;+export const seedanceSurfaceImplementationDigests = {prompt: digestOf("@svml/seedance/prompt-surface@1"),- speech: digestOf("@svml/seedance/speech-surface@2"),+ speech: digestOf("@svml/seedance/speech-surface@3"),video: digestOf("@svml/seedance/video-surface@1"),} as const;@@ -78,6 +111,90 @@ export function verifySeedancePrompt(value: unknown): asserts value is SeedancePif (value.promptDigest !== digestOf(content)) throw new Error("Seedance Prompt digest differs");}+function speechProgramContent(value: Omit<SeedanceSpeechProgram, "programDigest">) {+ return canonicalize(value);+}++export function sealSeedanceSpeechProgram(+ value: Omit<SeedanceSpeechProgram, "programDigest">,+): SeedanceSpeechProgram {+ const result: SeedanceSpeechProgram = { ...value, programDigest: digestOf(speechProgramContent(value)) };+ verifySeedanceSpeechProgram(result);+ return result;+}++export function verifySeedanceSpeechProgram(value: unknown): asserts value is SeedanceSpeechProgram {+ assertObject(value);+ if (+ value.contract !== "svml.seedance-speech-program@1"+ || !seedanceModels.includes(value.model as SeedanceModel)+ || typeof value.prompt !== "string"+ || value.prompt.trim().length === 0+ || value.generateAudio !== true+ || typeof value.webSearch !== "boolean"+ || !["480p", "720p", "1080p"].includes(value.resolution as string)+ || !["1:1", "4:3", "3:4", "16:9", "9:16", "21:9", "adaptive"].includes(value.aspectRatio as string)+ ) {+ throw new Error("Seedance SpeechProgram is invalid");+ }+ assertObject(value.segment);+ if (+ typeof value.segment.id !== "string"+ || value.segment.id.length === 0+ || !Number.isSafeInteger(value.segment.tokenStart)+ || !Number.isSafeInteger(value.segment.tokenEndExclusive)+ || (value.segment.tokenEndExclusive as number) <= (value.segment.tokenStart as number)+ || typeof value.segment.dialogueExcerptDigest !== "string"+ ) {+ throw new Error("Seedance SpeechProgram Segment identity is invalid");+ }+ const { programDigest: _digest, ...content } = value as unknown as SeedanceSpeechProgram;+ if (value.programDigest !== digestOf(speechProgramContent(content))) {+ throw new Error("Seedance SpeechProgram digest differs from its contents");+ }+ const program = value as unknown as SeedanceSpeechProgram;+ sealSeedanceRequest({+ contract: "svml.seedance-request@1",+ model: program.model,+ prompt: program.prompt,+ mode: program.mode,+ resolution: program.resolution,+ aspectRatio: program.aspectRatio,+ durationSec: 4,+ generateAudio: true,+ webSearch: program.webSearch,+ });+}++export function compileSeedanceSpeechRequest(+ program: SeedanceSpeechProgram,+ duration: SpeechDuration,+): SeedanceRequest {+ verifySeedanceSpeechProgram(program);+ assertSpeechDurationIdentity(duration);+ if (+ duration.segmentId !== program.segment.id+ || duration.tokenStart !== program.segment.tokenStart+ || duration.tokenEndExclusive !== program.segment.tokenEndExclusive+ ) {+ throw new Error("Seedance Speech duration belongs to another Narrative Segment");+ }+ if (!Number.isSafeInteger(duration.durationSec) || duration.durationSec < 4 || duration.durationSec > 15) {+ throw new Error("Seedance Speech duration must be an integer between 4 and 15 seconds");+ }+ return sealSeedanceRequest({+ contract: "svml.seedance-request@1",+ model: program.model,+ prompt: program.prompt,+ mode: program.mode,+ resolution: program.resolution,+ aspectRatio: program.aspectRatio,+ durationSec: duration.durationSec,+ generateAudio: true,+ webSearch: program.webSearch,+ });+}+const referenceSchema: ValueSchema = {kind: "oneOf",variants: (["image", "video", "audio"] as const).map((kind) => generationObjectSchema({@@ -107,6 +224,24 @@ const aspectRatioSchema = {enum: ["1:1", "4:3", "3:4", "16:9", "9:16", "21:9", "adaptive"],} as const satisfies ValueSchema;+const speechProgramSchema: ValueSchema = generationObjectSchema({+ contract: { schema: { kind: "literal", value: "svml.seedance-speech-program@1" } },+ model: { schema: { kind: "string", enum: [...seedanceModels] } },+ prompt: { schema: generationPromptSchema },+ mode: { schema: modeSchema },+ resolution: { schema: { kind: "string", enum: ["480p", "720p", "1080p"] } },+ aspectRatio: { schema: aspectRatioSchema },+ generateAudio: { schema: { kind: "literal", value: true } },+ webSearch: { schema: { kind: "boolean" } },+ segment: { schema: generationObjectSchema({+ id: { schema: generationPromptSchema },+ tokenStart: { schema: { kind: "number", integer: true, minimum: 0 } },+ tokenEndExclusive: { schema: { kind: "number", integer: true, minimum: 1 } },+ dialogueExcerptDigest: { schema: generationDigestSchema },+ }) },+ programDigest: { schema: generationDigestSchema },+});+function requestSchema(model: SeedanceModel): ValueSchema {return generationObjectSchema({contract: { schema: { kind: "literal", value: "svml.seedance-request@1" } },@@ -184,15 +319,22 @@ const seedanceBaseDefinition = defineExactModelModule({});export const seedanceEndpoints = seedanceBaseDefinition.endpoints;+export const seedanceEndpointsByModel = {+ "seedance-2": seedanceEndpoints.standard!,+ "seedance-2-fast": seedanceEndpoints.fast!,+ "seedance-2-mini": seedanceEndpoints.mini!,+} as const;export const seedanceManifest = {...seedanceBaseDefinition.manifest,dependencies: [...seedanceBaseDefinition.manifest.dependencies,videoContractDependencies.narrative,+ videoContractDependencies.speech,],types: [...seedanceBaseDefinition.manifest.types,+ { name: seedanceTypes.speechProgram.name, schema: speechProgramSchema },{name: seedanceTypes.prompt.name,schema: generationObjectSchema({@@ -218,7 +360,7 @@ export const seedanceManifest = {name: "speech",tag: "Speech",mode: "structured",- outputs: Object.values(seedanceEndpoints).map((endpoint) => endpoint.requestType),+ outputs: [seedanceTypes.speechProgram, ...Object.values(seedanceEndpoints).map((endpoint) => endpoint.requestType)],implementation: {kind: "trusted-frontend-surface",locator: "@svml/seedance/speech-surface",@@ -237,16 +379,65 @@ export const seedanceManifest = {},},],+ producers: [+ ...seedanceBaseDefinition.manifest.producers,+ ...seedanceModels.map((model) => ({+ name: seedanceSpeechCompileProducers[model].name,+ inputs: [+ { name: "program", type: seedanceTypes.speechProgram },+ { name: "duration", type: contractTypes.speechDuration },+ ],+ outputs: [{+ name: "request",+ type: seedanceEndpointsByModel[model].requestType,+ affinity: [{ resultPointer: "/durationSec", input: "duration", inputPointer: "/durationSec" }],+ }],+ needs: [],+ implementation: {+ kind: "registered" as const,+ locator: `@svml/seedance/compile-${model}-speech-request`,+ digest: seedanceSpeechCompileImplementationDigests[model],+ },+ })),+ ],} as const;export const seedanceManifestDigest = digestOf(seedanceManifest);-export const seedanceComponent = seedanceBaseDefinition.component;+export const seedanceComponent = {+ ...seedanceBaseDefinition.component,+ producers: [+ ...seedanceBaseDefinition.component.producers,+ ...seedanceModels.map((model) => ({+ producer: seedanceSpeechCompileProducers[model],+ implementationDigest: seedanceSpeechCompileImplementationDigests[model],+ handler: ({ inputs }: { readonly inputs: Readonly<Record<string, { readonly value: import("@svml/protocol").StoredValue }>> }) => ({+ outputs: {+ request: {+ kind: "inline" as const,+ value: canonicalize(compileSeedanceSpeechRequest(+ inputs.program?.value.kind === "inline"+ ? inputs.program.value.value as unknown as SeedanceSpeechProgram+ : (() => { throw new Error("Seedance SpeechProgram must be inline"); })(),+ inputs.duration?.value.kind === "inline"+ ? inputs.duration.value.value as unknown as SpeechDuration+ : (() => { throw new Error("SpeechDuration must be inline"); })(),+ )),+ },+ },+ needs: {},+ }),+ })),+ ],+};export const seedanceDefinition = {...seedanceBaseDefinition,manifest: seedanceManifest,manifestDigest: seedanceManifestDigest,};-export { createSeedanceGenerationFragment } from "./fragment.js";+export {+ createSeedanceGenerationFragment,+ createSeedanceSpeechGenerationFragment,+} from "./fragment.js";export {decodeSeedancePromptSurface,decodeSeedanceSpeechSurface,diff --git a/packages/seedance/src/surface.ts b/packages/seedance/src/surface.tsindex 5807d3cf..00c15e09 100644--- a/packages/seedance/src/surface.ts+++ b/packages/seedance/src/surface.ts@@ -10,11 +10,16 @@ import type {TextAttributeValue,} from "@svml/text";-import { createSeedanceGenerationFragment } from "./fragment.js";+import {+ createSeedanceGenerationFragment,+ createSeedanceSpeechGenerationFragment,+} from "./fragment.js";import {sealSeedancePrompt,sealSeedanceRequest,+ sealSeedanceSpeechProgram,seedanceEndpoints,+ seedanceSpeechCompileProducers,seedanceTypes,verifySeedancePrompt,} from "./index.js";@@ -148,13 +153,17 @@ function booleanAttribute(element: StructuredElement, name: string, fallback: bothrow new Error(`${element.name}.${name} must be true or false`);}-function generationSettings(element: StructuredElement, model: SeedanceModel): {+function generationSettings(+ element: StructuredElement,+ model: SeedanceModel,+ suppliedDurationSec?: number,+): {readonly durationSec: number;readonly resolution: "480p" | "720p" | "1080p";readonly aspectRatio: "1:1" | "4:3" | "3:4" | "16:9" | "9:16" | "21:9" | "adaptive";readonly webSearch: boolean;} {- const durationSec = integerAttribute(element, "duration");+ const durationSec = suppliedDurationSec ?? integerAttribute(element, "duration");if (durationSec < 4 || durationSec > 15) {throw new Error(`${element.name}.duration must be between 4 and 15 seconds`);}@@ -212,7 +221,11 @@ function referencePrompt(values: readonly ReferenceInput[]): string {}function dialogueExcerpt(reference: SurfaceResolvedReference, subject: string): {+ readonly id: string;+ readonly tokenStart: number;+ readonly tokenEndExclusive: number;readonly dialogue: string;+ readonly excerptDigest: string;} {if (!sameType(reference.type, contractTypes.narrativeDialogueExcerpt)) {throw new Error(`${subject} must reference a NarrativeDialogueExcerpt such as script.segment.opening.dialogue`);@@ -223,13 +236,37 @@ function dialogueExcerpt(reference: SurfaceResolvedReference, subject: string):readonly dialogue?: string;readonly [key: string]: CanonicalValue | undefined;};- if (value.contract !== "svml.narrative-dialogue-excerpt@1" || typeof value.dialogue !== "string") {+ if (+ value.contract !== "svml.narrative-dialogue-excerpt@1"+ || typeof value.dialogue !== "string"+ || typeof value.id !== "string"+ || !Number.isSafeInteger(value.tokenStart)+ || !Number.isSafeInteger(value.tokenEndExclusive)+ ) {throw new Error(`${subject} NarrativeDialogueExcerpt is invalid`);}const { excerptDigest: _digest, ...content } = value;if (value.excerptDigest !== digestOf(content)) throw new Error(`${subject} NarrativeDialogueExcerpt digest differs`);if (value.dialogue.trim().length === 0) throw new Error(`${subject} contains no spoken text`);- return value as { readonly dialogue: string };+ return {+ id: value.id,+ tokenStart: value.tokenStart as number,+ tokenEndExclusive: value.tokenEndExclusive as number,+ dialogue: value.dialogue,+ excerptDigest: value.excerptDigest,+ };+}++function speechDurationReference(+ element: StructuredElement,+ resolveReference: (path: string) => SurfaceResolvedReference | undefined,+): SurfaceResolvedReference | undefined {+ if (typeof element.attributes.duration === "string") return undefined;+ const result = resolved(element, "duration", resolveReference);+ if (!sameType(result.type, contractTypes.speechDuration)) {+ throw new Error(`${element.name}.duration must reference a SpeechDuration`);+ }+ return result;}function generationOutput(@@ -303,13 +340,60 @@ export const decodeSeedanceSpeechSurface: StructuredSurfaceHandler = ({ element,const declaredPrompt = prompt(resolved(element, "prompt", resolveReference), `${element.name}.prompt`);const spoken = dialogueExcerpt(resolved(element, "dialogue", resolveReference), `${element.name}.dialogue`);const refs = references(element, resolveReference);+ const duration = speechDurationReference(element, resolveReference);+ const promptText = `${declaredPrompt.text}${referencePrompt(refs)}\n\nSpoken dialogue — say exactly:\n${spoken.dialogue}`;+ const mode = refs.length === 0+ ? { kind: "text" as const }+ : { kind: "reference" as const, items: refs.map(({ role: _role, ...item }) => item) };+ if (duration !== undefined) {+ const settings = generationSettings(element, selected.model, 4);+ const program = sealSeedanceSpeechProgram({+ contract: "svml.seedance-speech-program@1",+ model: selected.model,+ prompt: promptText,+ mode,+ resolution: settings.resolution,+ aspectRatio: settings.aspectRatio,+ generateAudio: true,+ webSearch: settings.webSearch,+ segment: {+ id: spoken.id,+ tokenStart: spoken.tokenStart,+ tokenEndExclusive: spoken.tokenEndExclusive,+ dialogueExcerptDigest: spoken.excerptDigest as ReturnType<typeof digestOf>,+ },+ });+ const id = stringAttribute(element, "id");+ const programId = `${id}.program`;+ const fragment = createSeedanceSpeechGenerationFragment(+ selected.endpoint,+ seedanceSpeechCompileProducers[selected.model],+ );+ return {+ records: [{+ id: programId,+ type: seedanceTypes.speechProgram,+ value: { kind: "inline", value: program as unknown as CanonicalValue },+ range: element.range,+ }],+ components: [{+ id,+ fragment: fragment.id,+ inputs: {+ program: { kind: "record", id: programId },+ duration: duration.ref,+ },+ outputs: { video: id },+ range: element.range,+ }],+ fragments: [fragment],+ };+ }const request = sealSeedanceRequest({contract: "svml.seedance-request@1",model: selected.model as SeedanceModel,- prompt: `${declaredPrompt.text}${referencePrompt(refs)}\n\nSpoken dialogue — say exactly:\n${spoken.dialogue}`,- mode: refs.length === 0- ? { kind: "text" }- : { kind: "reference", items: refs.map(({ role: _role, ...item }) => item) },+ prompt: promptText,+ mode,...generationSettings(element, selected.model),generateAudio: true,});diff --git a/packages/text-track/src/component.ts b/packages/text-track/src/component.tsindex 9601e753..a30be442 100644--- a/packages/text-track/src/component.ts+++ b/packages/text-track/src/component.ts@@ -1,16 +1,34 @@import type { ComponentPackage } from "@svml/component-kit";-import type { ProgramSpace } from "@svml/contracts";+import type {+ CompleteSemanticMap,+ NarrativeSelectionRef,+ ProgramSpace,+} from "@svml/contracts";import type { StoredValue } from "@svml/protocol";import { canonicalize } from "@svml/protocol";import { textTrackProducers } from "./manifest.js";import {+ appendFullTextItem,+ appendFullTextItemImplementationDigest,+ appendSelectedTextItem,+ appendSelectedTextItemImplementationDigest,compileTextTrackImplementationDigest,compileTextTrackProgram,+ createTextTrackSet,+ createTextTrackSetImplementationDigest,+ finalizeTextTrack,+ finalizeTextTrackImplementationDigest,renderTextTrack,renderTextTrackImplementationDigest,} from "./program.js";-import type { TextTrackProgram, TextTrackSpec } from "./types.js";+import type {+ TextItemSpec,+ TextTrackHeader,+ TextTrackProgram,+ TextTrackSet,+ TextTrackSpec,+} from "./types.js";function inline<T>(value: StoredValue | undefined, subject: string): T {if (value?.kind !== "inline") throw new Error(`${subject} must be inline`);@@ -20,6 +38,43 @@ function inline<T>(value: StoredValue | undefined, subject: string): T {export const textTrackComponent = {name: "@svml/text-track",producers: [{+ producer: textTrackProducers.createSet,+ implementationDigest: createTextTrackSetImplementationDigest,+ handler: ({ inputs }) => ({+ outputs: { set: { kind: "inline", value: canonicalize(createTextTrackSet(+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),+ inline<TextTrackHeader>(inputs.header?.value, "TextTrackHeader"),+ )) } }, needs: {},+ }),+ }, {+ producer: textTrackProducers.appendFull,+ implementationDigest: appendFullTextItemImplementationDigest,+ handler: ({ inputs }) => ({+ outputs: { set: { kind: "inline", value: canonicalize(appendFullTextItem(+ inline<TextTrackSet>(inputs.set?.value, "TextTrackSet"),+ inline<TextItemSpec>(inputs.spec?.value, "TextItemSpec"),+ )) } }, needs: {},+ }),+ }, {+ producer: textTrackProducers.appendSelected,+ implementationDigest: appendSelectedTextItemImplementationDigest,+ handler: ({ inputs }) => ({+ outputs: { set: { kind: "inline", value: canonicalize(appendSelectedTextItem(+ inline<TextTrackSet>(inputs.set?.value, "TextTrackSet"),+ inline<CompleteSemanticMap>(inputs.map?.value, "CompleteSemanticMap"),+ inline<NarrativeSelectionRef>(inputs.selection?.value, "NarrativeSelection"),+ inline<TextItemSpec>(inputs.spec?.value, "TextItemSpec"),+ )) } }, needs: {},+ }),+ }, {+ producer: textTrackProducers.finalize,+ implementationDigest: finalizeTextTrackImplementationDigest,+ handler: ({ inputs }) => ({+ outputs: { program: { kind: "inline", value: canonicalize(finalizeTextTrack(+ inline<TextTrackSet>(inputs.set?.value, "TextTrackSet"),+ )) } }, needs: {},+ }),+ }, {producer: textTrackProducers.compile,implementationDigest: compileTextTrackImplementationDigest,handler: ({ inputs }) => ({diff --git a/packages/text-track/src/index.ts b/packages/text-track/src/index.tsindex 56184210..cf459305 100644--- a/packages/text-track/src/index.ts+++ b/packages/text-track/src/index.ts@@ -11,7 +11,18 @@ export {textTrackTypes,} from "./manifest.js";export {+ appendFullTextItem,+ appendFullTextItemImplementationDigest,+ appendSelectedTextItem,+ appendSelectedTextItemImplementationDigest,+ assertTextItemSpec,+ assertTextTrackHeader,assertTextTrackProgramIdentity,+ assertTextTrackSet,+ createTextTrackSet,+ createTextTrackSetImplementationDigest,+ finalizeTextTrack,+ finalizeTextTrackImplementationDigest,assertTextTrackSpec,compileTextTrackImplementationDigest,compileTextTrackProgram,@@ -19,6 +30,8 @@ export {renderTextTrack,renderTextTrackImplementationDigest,sealTextTrackProgram,+ sealTextTrackHeader,+ sealTextItemSpec,sealTextTrackSpec,} from "./program.js";export { decodeTextTrackSurface } from "./surface.js";diff --git a/packages/text-track/src/manifest.ts b/packages/text-track/src/manifest.tsindex 6b51830d..994aa684 100644--- a/packages/text-track/src/manifest.ts+++ b/packages/text-track/src/manifest.ts@@ -1,21 +1,36 @@import {contractTypes,+ programSpaceSchema,videoContractDependencies,visualTrackSchema,} from "@svml/contracts";import { digestOf } from "@svml/protocol";import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@svml/protocol";-import { compileTextTrackImplementationDigest, renderTextTrackImplementationDigest } from "./program.js";+import {+ appendFullTextItemImplementationDigest,+ appendSelectedTextItemImplementationDigest,+ compileTextTrackImplementationDigest,+ createTextTrackSetImplementationDigest,+ finalizeTextTrackImplementationDigest,+ 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" },spec: { module: textTrackModuleRef, name: "TextTrackSpec" },+ header: { module: textTrackModuleRef, name: "TextTrackHeader" },+ itemSpec: { module: textTrackModuleRef, name: "TextItemSpec" },+ set: { module: textTrackModuleRef, name: "TextTrackSet" },} satisfies Record<string, TypeRef>;export const textTrackProducers = {compile: { module: textTrackModuleRef, name: "compile-text-track" },render: { module: textTrackModuleRef, name: "render-text-track" },+ createSet: { module: textTrackModuleRef, name: "create-text-track-set" },+ appendFull: { module: textTrackModuleRef, name: "append-full-text-item" },+ appendSelected: { module: textTrackModuleRef, name: "append-selected-text-item" },+ finalize: { module: textTrackModuleRef, name: "finalize-text-track" },} satisfies Record<string, ProducerRef>;const string = { kind: "string", minLength: 1 } as const;@@ -86,7 +101,40 @@ export const textTrackSpecSchema: ValueSchema = object({}) } },});-export const textTrackSurfaceImplementationDigest = digestOf("@svml/text-track/track-surface@1");+const textTrackHeaderSchema: ValueSchema = object({+ contract: { schema: { kind: "literal", value: "svml.text-track-header@1" } },+ id: { schema: string },+ digest: { schema: digest },+});++const textItemSpecSchema: ValueSchema = object({+ contract: { schema: { kind: "literal", value: "svml.text-item-spec@1" } },+ id: { schema: string },+ text: { schema: string },+ z: { schema: signedInteger },+ box: { schema: object({+ xPercent: { schema: number }, yPercent: { schema: number },+ widthPercent: { schema: positiveNumber }, heightPercent: { schema: positiveNumber },+ }) },+ appearance: { schema: textAppearanceSchema },+ digest: { schema: digest },+});++const textTrackSetSchema: ValueSchema = object({+ contract: { schema: { kind: "literal", value: "svml.text-track-set@1" } },+ id: { schema: string },+ programSpace: { schema: programSpaceSchema },+ items: { schema: { kind: "array", items: textItemSchema } },+ lastAddition: { schema: object({+ previousSetDigest: { schema: digest },+ itemSpecDigest: { schema: digest },+ selectionDigest: { schema: digest, optional: true },+ mapDigest: { schema: digest, optional: true },+ }), optional: true },+ digest: { schema: digest },+});++export const textTrackSurfaceImplementationDigest = digestOf("@svml/text-track/track-surface@2");export const textTrackManifest: ModuleManifest = {format: "svml.module@0",@@ -94,19 +142,63 @@ export const textTrackManifest: ModuleManifest = {version: textTrackModuleRef.version,dependencies: [videoContractDependencies.programSpace,+ videoContractDependencies.narrative,+ videoContractDependencies.semanticTime,videoContractDependencies.composition,],types: [{ name: textTrackTypes.program.name, schema: textTrackProgramSchema },{ name: textTrackTypes.spec.name, schema: textTrackSpecSchema },+ { name: textTrackTypes.header.name, schema: textTrackHeaderSchema },+ { name: textTrackTypes.itemSpec.name, schema: textItemSpecSchema },+ { name: textTrackTypes.set.name, schema: textTrackSetSchema },],capabilities: [],surfaces: [{name: "track", tag: "Track", mode: "structured",- outputs: [textTrackTypes.spec, textTrackTypes.program, contractTypes.visualTrack],+ outputs: [textTrackTypes.spec, textTrackTypes.header, textTrackTypes.itemSpec,+ textTrackTypes.set, textTrackTypes.program, contractTypes.visualTrack],implementation: { kind: "trusted-frontend-surface", locator: "@svml/text-track/track-surface", digest: textTrackSurfaceImplementationDigest },}],producers: [{+ name: textTrackProducers.createSet.name,+ inputs: [+ { name: "space", type: contractTypes.programSpace },+ { name: "header", type: textTrackTypes.header },+ ],+ outputs: [{ name: "set", type: textTrackTypes.set }],+ needs: [],+ implementation: { kind: "registered", locator: "@svml/text-track/create-set", digest: createTextTrackSetImplementationDigest },+ }, {+ name: textTrackProducers.appendFull.name,+ inputs: [+ { name: "set", type: textTrackTypes.set },+ { name: "spec", type: textTrackTypes.itemSpec },+ ],+ outputs: [{ name: "set", type: textTrackTypes.set }],+ needs: [],+ implementation: { kind: "registered", locator: "@svml/text-track/append-full", digest: appendFullTextItemImplementationDigest },+ }, {+ name: textTrackProducers.appendSelected.name,+ inputs: [+ { name: "set", type: textTrackTypes.set },+ { name: "map", type: contractTypes.completeSemanticMap },+ { name: "selection", type: contractTypes.narrativeSelection },+ { name: "spec", type: textTrackTypes.itemSpec },+ ],+ outputs: [{ name: "set", type: textTrackTypes.set }],+ needs: [],+ implementation: { kind: "registered", locator: "@svml/text-track/append-selected", digest: appendSelectedTextItemImplementationDigest },+ }, {+ name: textTrackProducers.finalize.name,+ inputs: [{ name: "set", type: textTrackTypes.set }],+ outputs: [{+ name: "program", type: textTrackTypes.program,+ affinity: [{ resultPointer: "/programSpaceDigest", input: "set", inputPointer: "/programSpace/digest" }],+ }],+ needs: [],+ implementation: { kind: "registered", locator: "@svml/text-track/finalize", digest: finalizeTextTrackImplementationDigest },+ }, {name: textTrackProducers.compile.name,inputs: [{ name: "space", type: contractTypes.programSpace },diff --git a/packages/text-track/src/program.ts b/packages/text-track/src/program.tsindex ad73f0af..31ea603a 100644--- a/packages/text-track/src/program.ts+++ b/packages/text-track/src/program.ts@@ -1,17 +1,38 @@import {+ assertCompleteSemanticMapIdentity,+ assertNarrativeSelectionIdentity,assertProgramSpaceIdentity,assertVisualTrackIdentity,programSpaceFrameCount,+ selectionFrameSpans,sealVisualTrack,} from "@svml/contracts";-import type { ProgramSpace, VisualStyleDeclaration, VisualTrack } from "@svml/contracts";-import { digestOf, isDigest } from "@svml/protocol";+import type {+ CompleteSemanticMap,+ NarrativeSelectionRef,+ ProgramSpace,+ VisualStyleDeclaration,+ VisualTrack,+} from "@svml/contracts";+import { canonicalize, digestOf, isDigest } from "@svml/protocol";import type { Digest } from "@svml/protocol";-import type { TextAppearance, TextItem, TextTrackProgram, TextTrackSpec } from "./types.js";+import type {+ TextAppearance,+ TextItem,+ TextItemSpec,+ TextTrackHeader,+ TextTrackProgram,+ TextTrackSet,+ TextTrackSpec,+} from "./types.js";export const renderTextTrackImplementationDigest = digestOf("@svml/text-track/render@1");export const compileTextTrackImplementationDigest = digestOf("@svml/text-track/compile@1");+export const createTextTrackSetImplementationDigest = digestOf("@svml/text-track/create-set@1");+export const appendFullTextItemImplementationDigest = digestOf("@svml/text-track/append-full-item@1");+export const appendSelectedTextItemImplementationDigest = digestOf("@svml/text-track/append-selected-item@1");+export const finalizeTextTrackImplementationDigest = digestOf("@svml/text-track/finalize@1");function assertNonEmpty(value: string, label: string): void {if (!value.trim()) throw new Error(`${label} must not be empty.`);@@ -238,3 +259,164 @@ export function renderTextTrack(programSpace: ProgramSpace, program: TextTrackPrassertVisualTrackIdentity(track, programSpace);return track;}++function contentDigest<T extends object>(value: T): Digest {+ return digestOf(canonicalize(value));+}++export function sealTextTrackHeader(value: Omit<TextTrackHeader, "digest">): TextTrackHeader {+ const content = canonicalize(value) as unknown as Omit<TextTrackHeader, "digest">;+ const result = { ...content, digest: digestOf(content) };+ assertTextTrackHeader(result);+ return result;+}++export function assertTextTrackHeader(value: TextTrackHeader): void {+ const { digest: _digest, ...content } = value;+ if (+ value.contract !== "svml.text-track-header@1"+ || value.id.length === 0+ || !isDigest(value.digest)+ || value.digest !== contentDigest(content)+ ) throw new Error("TextTrackHeader is invalid");+}++export function sealTextItemSpec(value: Omit<TextItemSpec, "digest">): TextItemSpec {+ const content = canonicalize(value) as unknown as Omit<TextItemSpec, "digest">;+ const result = { ...content, digest: digestOf(content) };+ assertTextItemSpec(result);+ return result;+}++export function assertTextItemSpec(value: TextItemSpec): void {+ const { digest: _digest, ...content } = value;+ if (+ value.contract !== "svml.text-item-spec@1"+ || value.id.length === 0+ || value.text.length === 0+ || !Number.isSafeInteger(value.z)+ || !isDigest(value.digest)+ || value.digest !== contentDigest(content)+ ) throw new Error("TextItemSpec is invalid");+ for (const [name, number] of Object.entries(value.box)) assertFinite(number, `${value.id} box.${name}`);+ if (value.box.widthPercent <= 0 || value.box.heightPercent <= 0) throw new Error("TextItemSpec box is invalid");+ assertAppearance(value.appearance, `${value.id} appearance`);+}++function setContent(value: Omit<TextTrackSet, "digest">): Omit<TextTrackSet, "digest"> {+ return canonicalize(value) as unknown as Omit<TextTrackSet, "digest">;+}++function sealTextTrackSet(value: Omit<TextTrackSet, "digest">): TextTrackSet {+ const content = setContent(value);+ return { ...content, digest: digestOf(content) };+}++export function assertTextTrackSet(value: TextTrackSet): void {+ if (value.contract !== "svml.text-track-set@1" || value.id.length === 0) {+ throw new Error("TextTrackSet identity is invalid");+ }+ assertProgramSpaceIdentity(value.programSpace);+ const { digest: _digest, ...content } = value;+ if (!isDigest(value.digest) || value.digest !== digestOf(setContent(content))) {+ throw new Error("TextTrackSet digest differs from its contents");+ }+ if (value.items.length === 0 ? value.lastAddition !== undefined : value.lastAddition === undefined) {+ throw new Error("TextTrackSet last addition is inconsistent");+ }+ const ids = new Set<string>();+ for (const item of value.items) {+ if (ids.has(item.id)) throw new Error(`TextTrackSet repeats Item ${item.id}`);+ ids.add(item.id);+ }+}++export function createTextTrackSet(space: ProgramSpace, header: TextTrackHeader): TextTrackSet {+ assertProgramSpaceIdentity(space);+ assertTextTrackHeader(header);+ return sealTextTrackSet({+ contract: "svml.text-track-set@1",+ id: header.id,+ programSpace: space,+ items: [],+ });+}++function appendItems(+ set: TextTrackSet,+ spec: TextItemSpec,+ additions: readonly TextItem[],+ affinity: { readonly selectionDigest?: Digest; readonly mapDigest?: Digest } = {},+): TextTrackSet {+ assertTextTrackSet(set);+ assertTextItemSpec(spec);+ const existing = new Set(set.items.map((item) => item.id));+ if (additions.some((item) => existing.has(item.id))) throw new Error(`Text Item ${spec.id} is duplicated`);+ return sealTextTrackSet({+ contract: "svml.text-track-set@1",+ id: set.id,+ programSpace: set.programSpace,+ items: [...set.items, ...additions],+ lastAddition: {+ previousSetDigest: set.digest,+ itemSpecDigest: spec.digest,+ ...affinity,+ },+ });+}++function itemFromSpec(spec: TextItemSpec, id: string, span: TextItem["span"], tieBreak: string): TextItem {+ return {+ id,+ text: spec.text,+ span,+ z: spec.z,+ tieBreak,+ box: spec.box,+ appearance: spec.appearance,+ };+}++export function appendFullTextItem(set: TextTrackSet, spec: TextItemSpec): TextTrackSet {+ assertTextTrackSet(set);+ return appendItems(set, spec, [itemFromSpec(+ spec,+ spec.id,+ { startFrame: 0, endFrameExclusive: programSpaceFrameCount(set.programSpace) },+ `${set.id}:${spec.id}:1`,+ )]);+}++export function appendSelectedTextItem(+ set: TextTrackSet,+ map: CompleteSemanticMap,+ selection: NarrativeSelectionRef,+ spec: TextItemSpec,+): TextTrackSet {+ assertTextTrackSet(set);+ assertCompleteSemanticMapIdentity(map);+ assertNarrativeSelectionIdentity(selection);+ if (map.programSpace.digest !== set.programSpace.digest) {+ throw new Error("Text Selection map belongs to another ProgramSpace");+ }+ const spans = selectionFrameSpans(map, selection);+ return appendItems(set, spec, spans.map((span, index) => itemFromSpec(+ spec,+ spans.length === 1 ? spec.id : `${spec.id}:${index + 1}`,+ span,+ `${set.id}:${spec.id}:${index + 1}`,+ )), { selectionDigest: selection.selectionDigest, mapDigest: map.mapDigest });+}++export function finalizeTextTrack(set: TextTrackSet): TextTrackProgram {+ assertTextTrackSet(set);+ if (set.items.length === 0) throw new Error("TextTrack requires at least one Item");+ const program = sealTextTrackProgram({+ contract: "svml.text-track-program@1",+ id: set.id,+ programSpaceDigest: set.programSpace.digest,+ items: set.items,+ });+ assertTextTrackProgramIdentity(program, set.programSpace);+ return program;+}diff --git a/packages/text-track/src/surface.ts b/packages/text-track/src/surface.tsindex aa5d2877..99342527 100644--- a/packages/text-track/src/surface.ts+++ b/packages/text-track/src/surface.ts@@ -1,30 +1,76 @@import { contractTypes } from "@svml/contracts";import { sealGraphFragment } from "@svml/elaborator";+import type { FragmentOperation } from "@svml/elaborator";import { svsRecipeType } from "@svml/svs";import type { SvsRecipe } from "@svml/svs";import type { StructuredElement, StructuredSurfaceHandler, SurfaceResolvedReference, TextAttributeValue } from "@svml/text";import { textTrackProducers, textTrackTypes } from "./manifest.js";-import { sealTextTrackSpec } from "./program.js";+import { sealTextItemSpec, sealTextTrackHeader } from "./program.js";+import type { TextItemSpec } from "./types.js";const input = (name: string) => ({ kind: "fragment-input" as const, name });const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });-const textTrackSurfaceFragment = sealGraphFragment({- name: "@svml/text-track/track-surface@1",- inputs: [- { name: "space", type: contractTypes.programSpace },- { name: "spec", type: textTrackTypes.spec },- ],- operations: [- { id: "text:compile", producer: textTrackProducers.compile, inputs: { space: input("space"), spec: input("spec") }, result: { kind: "output", name: "program" } },- { id: "text:render", producer: textTrackProducers.render, inputs: { space: input("space"), program: operation("text:compile") }, result: { kind: "output", name: "track" } },- ],- exports: [{- name: "track", type: contractTypes.visualTrack, root: operation("text:render"), semanticInputs: ["space", "spec"],- affinity: [{ resultPointer: "/programSpaceDigest", source: input("space"), sourcePointer: "/digest" }], fidelity: "exact",- }],-});+type SurfaceItem = {+ readonly suffix: string;+ readonly specName: string;+ readonly selectionName?: string;+};++function createTextTrackSurfaceFragment(id: string, items: readonly SurfaceItem[]) {+ const selected = items.filter((item) => item.selectionName !== undefined);+ const operations: FragmentOperation[] = [{+ id: "text:set:empty",+ producer: textTrackProducers.createSet,+ inputs: { space: input("space"), header: input("header") },+ result: { kind: "output", name: "set" },+ }];+ let current = "text:set:empty";+ items.forEach((item, index) => {+ const operationId = `text:set:append:${String(index + 1).padStart(4, "0")}`;+ operations.push(item.selectionName === undefined ? {+ id: operationId,+ producer: textTrackProducers.appendFull,+ inputs: { set: operation(current), spec: input(item.specName) },+ result: { kind: "output", name: "set" },+ } : {+ id: operationId,+ producer: textTrackProducers.appendSelected,+ inputs: {+ set: operation(current),+ map: input("map"),+ selection: input(item.selectionName),+ spec: input(item.specName),+ },+ result: { kind: "output", name: "set" },+ });+ current = operationId;+ });+ operations.push(+ { id: "text:finalize", producer: textTrackProducers.finalize, inputs: { set: operation(current) }, result: { kind: "output", name: "program" } },+ { id: "text:render", producer: textTrackProducers.render, inputs: { space: input("space"), program: operation("text:finalize") }, result: { kind: "output", name: "track" } },+ );+ const semanticInputs = ["space", "header", ...(selected.length === 0 ? [] : ["map"]),+ ...items.flatMap((item) => [item.specName, ...(item.selectionName === undefined ? [] : [item.selectionName])])];+ return sealGraphFragment({+ name: `@svml/text-track/surface/${id}@2`,+ inputs: [+ { name: "space", type: contractTypes.programSpace },+ { name: "header", type: textTrackTypes.header },+ ...(selected.length === 0 ? [] : [{ name: "map", type: contractTypes.completeSemanticMap }]),+ ...items.flatMap((item) => [+ { name: item.specName, type: textTrackTypes.itemSpec },+ ...(item.selectionName === undefined ? [] : [{ name: item.selectionName, type: contractTypes.narrativeSelection }]),+ ]),+ ],+ operations,+ exports: [{+ name: "track", type: contractTypes.visualTrack, root: operation("text:render"), semanticInputs,+ affinity: [{ resultPointer: "/programSpaceDigest", source: input("space"), sourcePointer: "/digest" }], fidelity: "exact",+ }],+ });+}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;@@ -60,9 +106,21 @@ function propString(value: SvsRecipe, name: string): string {}export const decodeTextTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {- exact(element, ["id", "space"]);+ const trackAttributes = Object.keys(element.attributes).sort().join("\0");+ if (trackAttributes !== ["id", "space"].sort().join("\0")+ && trackAttributes !== ["id", "map", "space"].sort().join("\0")) {+ throw new Error(`${element.name} requires id and space; map is required when an Item uses a Selection`);+ }const id = text(element, "id");const space = ref(element, "space", contractTypes.programSpace, resolveReference);+ const header = sealTextTrackHeader({ contract: "svml.text-track-header@1", id });+ const headerId = `${id}.header`;+ const records: Array<{+ id: string;+ type: typeof textTrackTypes.header | typeof textTrackTypes.itemSpec;+ value: { kind: "inline"; value: ReturnType<typeof sealTextTrackHeader> | TextItemSpec };+ range: typeof element.range;+ }> = [{ id: headerId, type: textTrackTypes.header, value: { kind: "inline", value: header }, range: element.range }];let itemIndex = 0;const items = element.children.flatMap((child) => {if (child.kind === "text") {@@ -72,16 +130,25 @@ export const decodeTextTrackSurface: StructuredSurfaceHandler = ({ element, resoif (!child.name.endsWith(":Item") && child.name !== "Item") throw new Error(`${element.name} accepts only Item children`);itemIndex += 1;exact(child, ["text", "during", "appearance"]);- if (text(child, "during") !== "full") throw new Error(`${child.name}.during currently accepts only full`);+ const rawDuring = child.attributes.during;+ const selection = typeof rawDuring === "string"+ ? (() => {+ if (rawDuring.trim() !== "full") throw new Error(`${child.name}.during must be full or a NarrativeSelection reference`);+ return undefined;+ })()+ : ref(child, "during", contractTypes.narrativeSelection, resolveReference);const appearance = recipe(ref(child, "appearance", svsRecipeType, resolveReference));const expected = ["align", "fill", "font", "height", "size", "stack-order", "tracking", "weight", "width", "x", "y"];if (Object.keys(appearance.properties).sort().join("\0") !== expected.sort().join("\0")) throw new Error(`Text Recipe requires exactly ${expected.join(", ")}`);const align = propString(appearance, "align");if (align !== "left" && align !== "center" && align !== "right") throw new Error("Text Recipe align is invalid");const textAlign = align as "left" | "center" | "right";- return [{- id: `item-${String(itemIndex).padStart(4, "0")}`,- text: text(child, "text"), during: "full" as const,+ const suffix = String(itemIndex).padStart(4, "0");+ const specId = `${id}.item.${suffix}.spec`;+ const spec = sealTextItemSpec({+ contract: "svml.text-item-spec@1",+ id: `item-${suffix}`,+ text: text(child, "text"),z: propNumber(appearance, "stack-order"),box: {xPercent: propNumber(appearance, "x") * 100, yPercent: propNumber(appearance, "y") * 100,@@ -92,14 +159,46 @@ export const decodeTextTrackSurface: StructuredSurfaceHandler = ({ element, resofontFamily: propString(appearance, "font"), fontWeight: propNumber(appearance, "weight"),letterSpacingPx: propNumber(appearance, "tracking"), align: textAlign,},+ });+ records.push({ id: specId, type: textTrackTypes.itemSpec, value: { kind: "inline", value: spec }, range: child.range });+ return [{+ suffix,+ specId,+ specName: `item-${suffix}-spec`,+ ...(selection === undefined ? {} : { selection, selectionName: `item-${suffix}-selection` }),}];});if (items.length === 0) throw new Error(`${element.name} requires at least one Item`);- const spec = sealTextTrackSpec({ contract: "svml.text-track-spec@1", id, items });- const specId = `${id}.spec`;+ const selected = items.filter((item) => item.selection !== undefined);+ const map = selected.length === 0+ ? undefined+ : ref(element, "map", contractTypes.completeSemanticMap, resolveReference);+ if (selected.length === 0 && element.attributes.map !== undefined) {+ throw new Error(`${element.name}.map is unused because every Item uses during="full"`);+ }+ const fragmentItems: SurfaceItem[] = items.map((item) => ({+ suffix: item.suffix,+ specName: item.specName,+ ...(item.selectionName === undefined ? {} : { selectionName: item.selectionName }),+ }));+ const fragment = createTextTrackSurfaceFragment(id, fragmentItems);return {- records: [{ id: specId, type: textTrackTypes.spec, value: { kind: "inline", value: spec }, range: element.range }],- components: [{ id, fragment: textTrackSurfaceFragment.id, inputs: { space: space.ref, spec: { kind: "record", id: specId } }, outputs: { track: `${id}.track` }, range: element.range }],- fragments: [textTrackSurfaceFragment],+ records,+ components: [{+ id,+ fragment: fragment.id,+ inputs: {+ space: space.ref,+ header: { kind: "record", id: headerId },+ ...(map === undefined ? {} : { map: map.ref }),+ ...Object.fromEntries(items.flatMap((item) => [+ [item.specName, { kind: "record" as const, id: item.specId }],+ ...(item.selection === undefined ? [] : [[item.selectionName!, item.selection.ref] as const]),+ ])),+ },+ outputs: { track: `${id}.track` },+ range: element.range,+ }],+ fragments: [fragment],};};diff --git a/packages/text-track/src/types.ts b/packages/text-track/src/types.tsindex 56f17a81..5145c36b 100644--- a/packages/text-track/src/types.ts+++ b/packages/text-track/src/types.ts@@ -1,4 +1,4 @@-import type { FrameSpan } from "@svml/contracts";+import type { FrameSpan, ProgramSpace } from "@svml/contracts";import type { Digest } from "@svml/protocol";export type TextBox = {@@ -54,3 +54,36 @@ export type TextTrackSpec = {readonly appearance: TextAppearance;}[];};++/** Stable Track identity used by the graph-first Surface fold. */+export type TextTrackHeader = {+ readonly contract: "svml.text-track-header@1";+ readonly id: string;+ readonly digest: Digest;+};++/** Appearance and content are authored here; timing remains an explicit graph input. */+export type TextItemSpec = {+ readonly contract: "svml.text-item-spec@1";+ readonly id: string;+ readonly text: string;+ readonly z: number;+ readonly box: TextBox;+ readonly appearance: TextAppearance;+ readonly digest: Digest;+};++/** Package-private immutable fold value for any number of full or selected Items. */+export type TextTrackSet = {+ readonly contract: "svml.text-track-set@1";+ readonly id: string;+ readonly programSpace: ProgramSpace;+ readonly items: readonly TextItem[];+ readonly lastAddition?: {+ readonly previousSetDigest: Digest;+ readonly itemSpecDigest: Digest;+ readonly selectionDigest?: Digest;+ readonly mapDigest?: Digest;+ };+ readonly digest: Digest;+};diff --git a/packages/text-track/test/text-track.test.ts b/packages/text-track/test/text-track.test.tsindex bc6a8de2..dfc830f2 100644--- a/packages/text-track/test/text-track.test.ts+++ b/packages/text-track/test/text-track.test.ts@@ -9,10 +9,17 @@ import {import { compileHyperframesDocument } from "@svml/hyperframes";import { digestOf } from "@svml/protocol";import {+ appendSelectedTextItem,+ createTextTrackSet,+ finalizeTextTrack,assertTextTrackProgramIdentity,renderTextTrack,sealTextTrackProgram,+ sealTextItemSpec,+ sealTextTrackHeader,} from "@svml/text-track";+import type { CompleteSemanticMap, NarrativeSelectionRef } from "@svml/contracts";+import { canonicalize } from "@svml/protocol";const space = sealProgramSpace({contract: "svml.program-space@0",@@ -101,3 +108,61 @@ test("TextTrackProgram rejects a frame span outside its ProgramSpace", () => {});assert.throws(() => renderTextTrack(space, program), /outside ProgramSpace/u);});++test("a selected Text Item is located only through explicit Selection and SemanticMap edges", () => {+ const mapContent = {+ contract: "svml.complete-semantic-map@1" as const,+ programSpace: space,+ quantizationPolicy: "nearest-frame" as const,+ durationSec: 5,+ segments: [{+ segmentId: "opening", startSec: 0, endSec: 3, startFrame: 0, endFrame: 90,+ startQuality: "measured" as const, endQuality: "measured" as const,+ }],+ tokens: [0, 1, 2].map((index) => ({+ tokenId: `token-${index}`,+ segmentId: "opening",+ startSec: index,+ endSec: index + 1,+ startFrame: index * 30,+ endFrame: (index + 1) * 30,+ startQuality: "measured" as const,+ endQuality: "measured" as const,+ })),+ anchors: [],+ groups: [],+ };+ const map: CompleteSemanticMap = {+ ...mapContent,+ mapDigest: digestOf(canonicalize(mapContent)),+ };+ const selectionContent = {+ contract: "svml.narrative-selection@1" as const,+ id: "callout",+ occurrences: [{+ occurrence: 1,+ open: { affinity: "right" as const, boundary: { tokenIndex: 1, structuralPosition: 1, segmentId: "opening" } },+ close: { affinity: "left" as const, boundary: { tokenIndex: 2, structuralPosition: 2, segmentId: "opening" } },+ }],+ };+ const selection: NarrativeSelectionRef = {+ ...selectionContent,+ selectionDigest: digestOf(canonicalize(selectionContent)),+ };+ const header = sealTextTrackHeader({ contract: "svml.text-track-header@1", id: "selected-text" });+ const spec = sealTextItemSpec({+ contract: "svml.text-item-spec@1",+ id: "meaning",+ text: "MEANING",+ z: 80,+ box: { xPercent: 10, yPercent: 10, widthPercent: 80, heightPercent: 10 },+ appearance: { color: "#ffffff", fontSizePx: 48 },+ });+ const program = finalizeTextTrack(appendSelectedTextItem(+ createTextTrackSet(space, header),+ map,+ selection,+ spec,+ ));+ assert.deepEqual(program.items.map((item) => item.span), [{ startFrame: 30, endFrameExclusive: 60 }]);+});diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex c07fda22..6dbb9afc 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -12,6 +12,27 @@ importers:specifier: 0.7.84version: 0.7.84(@types/[email protected])devDependencies:+ '@svml/local':+ specifier: workspace:*+ version: link:packages/local+ '@svml/prelude-video':+ specifier: workspace:*+ version: link:packages/prelude-video+ '@svml/provider-google-vertex':+ specifier: workspace:*+ version: link:packages/provider-google-vertex+ '@svml/provider-hyperframes-local':+ specifier: workspace:*+ version: link:packages/provider-hyperframes-local+ '@svml/provider-kie':+ specifier: workspace:*+ version: link:packages/provider-kie+ '@svml/provider-media-local':+ specifier: workspace:*+ version: link:packages/provider-media-local+ '@svml/provider-whisperx-local':+ specifier: workspace:*+ version: link:packages/provider-whisperx-local'@types/node':specifier: 24.10.1version: 24.10.1@@ -141,6 +162,9 @@ importers:'@svml/protocol':specifier: workspace:*version: link:../protocol+ '@svml/realization':+ specifier: workspace:*+ version: link:../realizationpackages/compiler-node:dependencies:@@ -156,6 +180,9 @@ importers:'@svml/protocol':specifier: workspace:*version: link:../protocol+ '@svml/realization':+ specifier: workspace:*+ version: link:../realization'@svml/validation':specifier: workspace:*version: link:../validation@@ -266,6 +293,24 @@ importers:specifier: workspace:*version: link:../runtime+ packages/estimate:+ dependencies:+ '@svml/component-kit':+ specifier: workspace:*+ version: link:../component-kit+ '@svml/contracts':+ specifier: workspace:*+ version: link:../contracts+ '@svml/elaborator':+ specifier: workspace:*+ version: link:../elaborator+ '@svml/protocol':+ specifier: workspace:*+ version: link:../protocol+ '@svml/text':+ specifier: workspace:*+ version: link:../text+packages/film:dependencies:'@svml/component-kit':@@ -564,6 +609,9 @@ importers:'@svml/contracts':specifier: workspace:*version: link:../contracts+ '@svml/estimate':+ specifier: workspace:*+ version: link:../estimate'@svml/film':specifier: workspace:*version: link:../filmdiff --git a/tsconfig.v2.json b/tsconfig.v2.jsonindex 6d2121ea..2dbbdeb4 100644--- a/tsconfig.v2.json+++ b/tsconfig.v2.json@@ -40,10 +40,12 @@"@svml/provider-media-local": ["packages/provider-media-local/src/index.ts"],"@svml/provider-hyperframes-local": ["packages/provider-hyperframes-local/src/index.ts"],"@svml/provider-whisperx-local": ["packages/provider-whisperx-local/src/index.ts"],+ "@svml/provider-google-vertex": ["packages/provider-google-vertex/src/index.ts"],"@svml/transport-aws-lambda": ["packages/transport-aws-lambda/src/index.ts"],"@svml/transport-process": ["packages/transport-process/src/index.ts"],"@svml/transport": ["packages/transport/src/index.ts"],"@svml/speech-program": ["packages/speech-program/src/index.ts"],+ "@svml/estimate": ["packages/estimate/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"],