Skip to content

armgit / hypit

Public Imported from GitHub
0

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

feat: implement graph-native v2 compilation

kashorinc763ce44f166
diff --git a/README.md b/README.md
index bc6aa7a1..0b4da056 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,29 @@
# SVML
> **v2 bootstrap:** `packages/protocol`, `packages/core` and `packages/driver-node`
-> implement the domain-free typed state kernel and an explicitly registered Node Host.
+> implement the domain-free `LogicalOutput / Candidate / Operation / Target` kernel and an explicitly
+> registered Node Host. A single Build Compiler resolves each demanded Logical Output, selects its
+> Candidate from a `BuildRequest`, and memoizes the reverse closure by stable `OperationId` before the
+> Build Machine executes anything. Reuse and product-level “Pin” UI actions are ordinary
+> Existing-Value Candidates, not Core branches; Providers only execute already selected exact
+> CapabilityRefs. Declarative affinity prevents exact media evidence or provided values from being
+> attached to the wrong Narrative/Basis.
+> `packages/speech-take` proves atomic Product plus ordinary audio/visual Projection;
+> `packages/elaborator` expands content-addressed static Fragments with hygienic instance identities;
+> `packages/realization` attaches locked Existing-Value or Fragment Candidates without changing the
+> author graph identity. These are executable reference layers outside Core, not new Kernel magic.
+> `packages/video-fragments` now composes the first real speech vertical from static Fragments:
+> SpeechTake projections, one-pass WhisperX evidence, a provider-neutral SemanticMap and timed
+> captions. Producer-declared affinity protects internal Fragment results before they enter state;
+> Logical-Output affinity separately protects selected Candidates.
+> The next composition waist is intentionally flat: captions, text, speech video, B-roll and overlay
+> effects must become self-contained peer Tracks. Composition may layer them by time, space and z,
+> but no Track may mutate or intersect a sibling Track.
> `packages/text` and `packages/script` now implement the first official authoring vertical:
> a minimal Text Frontend that learns raw/structured Surfaces from locked module manifests, plus
> an ordinary Script Surface package using named Segments such as `<opening>...</opening>`.
-> `packages/whisperx` adds a pure, tested one-pass WhisperX timing locator; the Host adapter that
-> invokes WhisperX is intentionally still outside this slice. Third-party parser sandboxing,
+> `packages/whisperx` declares the typed one-pass WhisperX Need; concrete local/Hypit adapters remain
+> Runtime packages outside this slice. Third-party parser sandboxing,
> source imports and `.svs` are not implemented yet. The existing
> root compiler and standard library remain the executable v1 research oracle during migration.
@@ -148,9 +165,9 @@ generation provider is invoked by tests or compilation.
fulfillment or substitution. The executable v1 documents below remain implementation
records until that migration is complete.
- [Kernel graph and build intent v2](docs/kernel-graph-build-intent-v2.md)
- is the current Kernel construction authority: complete typed Graph, arbitrary
- Targets, Pins, reverse Demand, derived BuildPlans, Contract Packages and
- open-world dynamic modules.
+ is the superseded `@0` Graph/Pin construction record.
+- [Logical Output, Candidate, Build Compiler and Graph Fragment v2](docs/logical-output-realization-fragment-draft.md)
+ is the current `@1` Kernel construction authority and implementation record.
- [Script Surface v1](spec/script-surface-v1.md)
- [Source Architecture v1 draft](spec/source-architecture-draft.md)
- [Speech Program and Caption v1 target contract](docs/speech-program-caption-v1.md)
diff --git a/packages/caption/src/manifest.ts b/packages/caption/src/manifest.ts
index e81b59b3..03fb4797 100644
--- a/packages/caption/src/manifest.ts
+++ b/packages/caption/src/manifest.ts
@@ -18,6 +18,7 @@ export const captionManifest: ModuleManifest = {
version: captionModuleRef.version,
dependencies: [{ module: contractsModuleRef, digest: contractsManifestDigest }],
types: [],
+ capabilities: [],
surfaces: [],
producers: [{
name: captionProducers.temporalize.name,
@@ -25,7 +26,14 @@ export const captionManifest: ModuleManifest = {
{ name: "narrative", type: contractTypes.narrative },
{ name: "map", type: contractTypes.completeSemanticMap },
],
- outputs: [{ name: "caption", type: contractTypes.timedCaptionProjection }],
+ outputs: [{
+ name: "caption",
+ type: contractTypes.timedCaptionProjection,
+ affinity: [
+ { resultPointer: "/semanticIndexDigest", input: "narrative", inputPointer: "/semanticIndex/digest" },
+ { resultPointer: "/speechTimeMapDigest", input: "map", inputPointer: "/mapDigest" },
+ ],
+ }],
needs: [],
implementation: {
kind: "registered",
diff --git a/packages/caption/test/caption.test.ts b/packages/caption/test/caption.test.ts
index 18a41fed..abc97f9f 100644
--- a/packages/caption/test/caption.test.ts
+++ b/packages/caption/test/caption.test.ts
@@ -7,7 +7,7 @@ import {
sealProgramSpace,
sealSpeechBasis,
} from "@svml/contracts";
-import type { AlignedTranscriptSegment, Narrative } from "@svml/contracts";
+import type { AlignedTranscriptSegment, Narrative, SpeechAudioBasis } from "@svml/contracts";
import { digestOf } from "@svml/core";
import { parseScript } from "@svml/script";
import { locateSpeechTiming } from "@svml/speech-align";
@@ -27,6 +27,7 @@ function locate(narrative: Narrative, durationSec: number, segments: readonly Al
}));
const basis = sealSpeechBasis({
contract: "svml.speech-basis@1",
+ narrativeDigest: narrative.semanticIndex.digest,
programSpace,
audio: { digest: audioDigest, size: 1, mediaType: "audio/wav", durationSec },
visualTrack: { clips: basisSegments.map((segment) => ({
@@ -51,7 +52,15 @@ function locate(narrative: Narrative, durationSec: number, segments: readonly Al
durationSec,
segments,
});
- return locateSpeechTiming(narrative, basis, evidence);
+ const audioBasis: SpeechAudioBasis = {
+ contract: "svml.speech-audio-basis@1",
+ basisDigest: basis.basisDigest,
+ narrativeDigest: basis.narrativeDigest,
+ programSpace: basis.programSpace,
+ audio: basis.audio,
+ segments: basis.segments,
+ };
+ return locateSpeechTiming(narrative, audioBasis, evidence);
}
test("Caption temporalization preserves evidence envelopes and labels local estimates", () => {
diff --git a/packages/contracts/package.json b/packages/contracts/package.json
index 76624e61..b2ddf3e3 100644
--- a/packages/contracts/package.json
+++ b/packages/contracts/package.json
@@ -7,7 +7,6 @@
".": "./src/index.ts"
},
"dependencies": {
- "@svml/core": "workspace:*",
"@svml/protocol": "workspace:*"
}
}
diff --git a/packages/contracts/src/identity.ts b/packages/contracts/src/identity.ts
index 504a00bc..1c0dea44 100644
--- a/packages/contracts/src/identity.ts
+++ b/packages/contracts/src/identity.ts
@@ -1,7 +1,12 @@
-import { digestOf, isDigest } from "@svml/core";
+import { digestOf, isDigest } from "@svml/protocol";
import type { Digest } from "@svml/protocol";
-import type { AlignedTranscriptEvidence, ProgramSpace, SpeechBasis } from "./speech.js";
+import type {
+ AlignedTranscriptEvidence,
+ ProgramSpace,
+ SpeechAudioBasis,
+ SpeechBasis,
+} from "./speech.js";
export function computeProgramSpaceDigest(value: Omit<ProgramSpace, "digest">): Digest {
return digestOf(value);
@@ -62,3 +67,61 @@ export function assertSpeechBasisIdentity(basis: SpeechBasis): void {
throw new Error("SpeechBasis audio does not match its ProgramSpace.");
}
}
+
+/**
+ * Validate the self-contained identity claims of an audio projection.
+ *
+ * `basisDigest` names the complete SpeechBasis Product, so it intentionally
+ * cannot be recomputed from this projection after the visual fields have been
+ * removed. The graph-level affinity constraints prove that relationship.
+ */
+export function assertSpeechAudioBasisIdentity(basis: SpeechAudioBasis): void {
+ if (basis.contract !== "svml.speech-audio-basis@1") {
+ throw new Error("Unsupported SpeechAudioBasis contract.");
+ }
+ if (!isDigest(basis.basisDigest) || !isDigest(basis.narrativeDigest)) {
+ throw new Error("SpeechAudioBasis identity digest is invalid.");
+ }
+ const { digest: _programDigest, ...programContent } = basis.programSpace;
+ if (
+ !isDigest(basis.programSpace.digest)
+ || basis.programSpace.digest !== computeProgramSpaceDigest(programContent)
+ ) {
+ throw new Error("ProgramSpace digest does not match its canonical contents.");
+ }
+ const { numerator, denominator } = basis.programSpace.frameRate;
+ if (
+ !Number.isSafeInteger(numerator)
+ || numerator <= 0
+ || !Number.isSafeInteger(denominator)
+ || denominator <= 0
+ ) {
+ throw new Error("ProgramSpace frame rate must be a positive rational number.");
+ }
+ if (
+ !Number.isFinite(basis.programSpace.durationSec)
+ || basis.programSpace.durationSec <= 0
+ || basis.audio.durationSec !== basis.programSpace.durationSec
+ || !isDigest(basis.audio.digest)
+ ) {
+ throw new Error("SpeechAudioBasis audio does not match its ProgramSpace.");
+ }
+ if (basis.segments.length === 0) {
+ throw new Error("SpeechAudioBasis must contain at least one Segment.");
+ }
+ let previousEnd = 0;
+ for (const segment of basis.segments) {
+ if (
+ segment.segmentId.length === 0
+ || !Number.isFinite(segment.startSec)
+ || !Number.isFinite(segment.endSec)
+ || segment.startSec < previousEnd
+ || segment.endSec < segment.startSec
+ || segment.endSec > basis.programSpace.durationSec
+ || !isDigest(segment.sourceArtifactDigest)
+ ) {
+ throw new Error("SpeechAudioBasis Segment is invalid or out of order.");
+ }
+ previousEnd = segment.endSec;
+ }
+}
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
index 057e3235..783e68ef 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -1,5 +1,6 @@
export type * from "./caption.js";
export {
+ assertSpeechAudioBasisIdentity,
assertSpeechBasisIdentity,
computeAlignedTranscriptEvidenceDigest,
computeProgramSpaceDigest,
@@ -17,7 +18,9 @@ export {
contractsModuleRef,
contractTypes,
narrativeSchema,
+ speechAudioBasisSchema,
speechBasisSchema,
+ speechVisualTrackSchema,
timedCaptionProjectionSchema,
} from "./manifest.js";
export type * from "./narrative.js";
diff --git a/packages/contracts/src/manifest.ts b/packages/contracts/src/manifest.ts
index a8a28d6a..2058eeb4 100644
--- a/packages/contracts/src/manifest.ts
+++ b/packages/contracts/src/manifest.ts
@@ -1,4 +1,4 @@
-import { computeModuleDigest } from "@svml/core";
+import { digestOf } from "@svml/protocol";
import type { ModuleManifest, TypeRef, ValueSchema } from "@svml/protocol";
export const contractsModuleRef = { name: "@svml/contracts", version: "0.0.0-dev" } as const;
@@ -6,6 +6,8 @@ export const contractsModuleRef = { name: "@svml/contracts", version: "0.0.0-dev
export const contractTypes = {
narrative: { module: contractsModuleRef, name: "Narrative" },
speechBasis: { module: contractsModuleRef, name: "SpeechBasis" },
+ speechAudioBasis: { module: contractsModuleRef, name: "SpeechAudioBasis" },
+ speechVisualTrack: { module: contractsModuleRef, name: "SpeechVisualTrack" },
alignedTranscriptEvidence: { module: contractsModuleRef, name: "AlignedTranscriptEvidence" },
completeSemanticMap: { module: contractsModuleRef, name: "CompleteSemanticMap" },
timedCaptionProjection: { module: contractsModuleRef, name: "TimedCaptionProjection" },
@@ -101,13 +103,32 @@ const basisSegment = object({
export const speechBasisSchema: ValueSchema = object({
contract: { schema: { kind: "literal", value: "svml.speech-basis@1" } },
- basisDigest: { schema: digest }, programSpace: { schema: programSpace }, audio: { schema: artifact },
+ basisDigest: { schema: digest }, narrativeDigest: { schema: digest },
+ programSpace: { schema: programSpace }, audio: { schema: artifact },
visualTrack: { schema: object({ clips: { schema: { kind: "array", items: object({
segmentId: { schema: string }, artifact: { schema: artifact }, startSec: { schema: number }, endSec: { schema: number },
}) } } }) },
segments: { schema: { kind: "array", minItems: 1, items: basisSegment } },
});
+export const speechAudioBasisSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.speech-audio-basis@1" } },
+ basisDigest: { schema: digest }, narrativeDigest: { schema: digest },
+ programSpace: { schema: programSpace }, audio: { schema: artifact },
+ segments: { schema: { kind: "array", minItems: 1, items: basisSegment } },
+});
+
+export const speechVisualTrackSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.speech-visual-track@1" } },
+ basisDigest: { schema: digest }, narrativeDigest: { schema: digest },
+ programSpace: { schema: programSpace },
+ visualTrack: { schema: object({ clips: { schema: { kind: "array", items: object({
+ segmentId: { schema: string }, artifact: { schema: artifact },
+ startSec: { schema: number }, endSec: { schema: number },
+ }) } } }) },
+ segments: { schema: { kind: "array", minItems: 1, items: basisSegment } },
+});
+
const wordEvidence = object({
text: { schema: { kind: "string" } }, startSec: { schema: number, optional: true },
endSec: { schema: number, optional: true }, score: { schema: { kind: "number", minimum: 0, maximum: 1 }, optional: true },
@@ -193,12 +214,15 @@ export const contractsManifest: ModuleManifest = {
types: [
{ name: contractTypes.narrative.name, schema: narrativeSchema },
{ name: contractTypes.speechBasis.name, schema: speechBasisSchema },
+ { name: contractTypes.speechAudioBasis.name, schema: speechAudioBasisSchema },
+ { name: contractTypes.speechVisualTrack.name, schema: speechVisualTrackSchema },
{ name: contractTypes.alignedTranscriptEvidence.name, schema: alignedTranscriptEvidenceSchema },
{ name: contractTypes.completeSemanticMap.name, schema: completeSemanticMapSchema },
{ name: contractTypes.timedCaptionProjection.name, schema: timedCaptionProjectionSchema },
],
+ capabilities: [],
surfaces: [],
producers: [],
};
-export const contractsManifestDigest = computeModuleDigest(contractsManifest);
+export const contractsManifestDigest = digestOf(contractsManifest);
diff --git a/packages/contracts/src/speech.ts b/packages/contracts/src/speech.ts
index e9edee98..9b98154a 100644
--- a/packages/contracts/src/speech.ts
+++ b/packages/contracts/src/speech.ts
@@ -29,6 +29,8 @@ export type SpeechBasisSegment = {
export type SpeechBasis = {
readonly contract: "svml.speech-basis@1";
readonly basisDigest: Digest;
+ /** Semantic identity of the authored Narrative whose speech this Basis realizes. */
+ readonly narrativeDigest: Digest;
readonly programSpace: ProgramSpace;
readonly audio: MediaArtifactRef;
readonly visualTrack: {
@@ -42,6 +44,26 @@ export type SpeechBasis = {
readonly segments: readonly SpeechBasisSegment[];
};
+/** Deterministic audio projection of one atomic SpeechBasis/SpeechTake Product. */
+export type SpeechAudioBasis = {
+ readonly contract: "svml.speech-audio-basis@1";
+ readonly basisDigest: Digest;
+ readonly narrativeDigest: Digest;
+ readonly programSpace: ProgramSpace;
+ readonly audio: MediaArtifactRef;
+ readonly segments: readonly SpeechBasisSegment[];
+};
+
+/** Deterministic visual projection of one atomic SpeechBasis/SpeechTake Product. */
+export type SpeechVisualTrack = {
+ readonly contract: "svml.speech-visual-track@1";
+ readonly basisDigest: Digest;
+ readonly narrativeDigest: Digest;
+ readonly programSpace: ProgramSpace;
+ readonly visualTrack: SpeechBasis["visualTrack"];
+ readonly segments: readonly SpeechBasisSegment[];
+};
+
export type SpeechWordEvidence = {
readonly text: string;
readonly startSec?: number;
diff --git a/packages/core/src/affinity.ts b/packages/core/src/affinity.ts
new file mode 100644
index 00000000..d1013fc0
--- /dev/null
+++ b/packages/core/src/affinity.ts
@@ -0,0 +1,173 @@
+import type {
+ BuildPlan,
+ CompiledGraph,
+ GraphValueRef,
+ LinkedProgram,
+ ProducerStep,
+ StoredValue,
+ TypedRecord,
+} from "@svml/protocol";
+
+import { canonicalStringify } from "./canonical.js";
+import { invariant } from "./error.js";
+import { resolveLogicalOutput, resolveOperation } from "./graph.js";
+import { resolveProducer } from "./link.js";
+
+function pointerTokens(pointer: string): string[] {
+ invariant(
+ pointer === "" || pointer.startsWith("/"),
+ "INVALID_AFFINITY_POINTER",
+ `affinity pointer ${pointer} is not a JSON Pointer`,
+ );
+ if (pointer === "") return [];
+ return pointer.slice(1).split("/").map((token) => {
+ invariant(
+ !/~(?:[^01]|$)/u.test(token),
+ "INVALID_AFFINITY_POINTER",
+ `affinity pointer ${pointer} has an invalid escape`,
+ );
+ return token.replaceAll("~1", "/").replaceAll("~0", "~");
+ });
+}
+
+function atPointer(value: unknown, pointer: string, subject: string): unknown {
+ let current = value;
+ for (const token of pointerTokens(pointer)) {
+ invariant(
+ current !== null && typeof current === "object",
+ "AFFINITY_PATH_MISSING",
+ `${subject}${pointer} does not exist`,
+ subject,
+ );
+ if (Array.isArray(current)) {
+ invariant(/^0$|^[1-9][0-9]*$/u.test(token), "AFFINITY_PATH_MISSING", `${subject}${pointer} is invalid`);
+ current = current[Number(token)];
+ } else {
+ invariant(Object.hasOwn(current, token), "AFFINITY_PATH_MISSING", `${subject}${pointer} does not exist`);
+ current = (current as Readonly<Record<string, unknown>>)[token];
+ }
+ }
+ invariant(current !== undefined, "AFFINITY_PATH_MISSING", `${subject}${pointer} is undefined`, subject);
+ return current;
+}
+
+function inlineValue(value: StoredValue, subject: string): unknown {
+ invariant(value.kind === "inline", "AFFINITY_REQUIRES_INLINE_VALUE", `${subject} must be inline`, subject);
+ return value.value;
+}
+
+function sourceRecordId(graph: CompiledGraph, plan: BuildPlan, source: GraphValueRef): string {
+ if (source.kind === "record") return source.id;
+ if (source.kind === "operation-result") return resolveOperation(graph, source.operation).result.record;
+ const selection = plan.selections.find((item) => item.output === source.id);
+ invariant(
+ selection !== undefined,
+ "UNDEMANDED_AFFINITY_SOURCE",
+ `${source.id} is required to prove exact affinity but is not demanded`,
+ source.id,
+ );
+ return selection.record;
+}
+
+export function verifyRecordAffinity(
+ graph: CompiledGraph,
+ plan: BuildPlan,
+ outputId: string,
+ record: TypedRecord,
+ lookup: (id: string) => TypedRecord | undefined,
+): void {
+ if (record.conformance === "substitute") return;
+ const output = resolveLogicalOutput(graph, outputId);
+ for (const constraint of output.affinity ?? []) {
+ const sourceId = sourceRecordId(graph, plan, constraint.source);
+ const source = lookup(sourceId);
+ invariant(
+ source !== undefined,
+ "UNPROVEN_EXACT_AFFINITY",
+ `${outputId} cannot prove affinity to ${sourceId}; provide that source or mark this Candidate substitute`,
+ outputId,
+ );
+ const resultValue = atPointer(inlineValue(record.value, record.id), constraint.resultPointer, record.id);
+ const sourceValue = atPointer(inlineValue(source.value, source.id), constraint.sourcePointer, source.id);
+ invariant(
+ canonicalStringify(resultValue) === canonicalStringify(sourceValue),
+ "AFFINITY_MISMATCH",
+ `${record.id}${constraint.resultPointer} does not match ${source.id}${constraint.sourcePointer}`,
+ record.id,
+ );
+ }
+}
+
+export function verifyGraphRecordAffinity(
+ graph: CompiledGraph,
+ plan: BuildPlan,
+ record: TypedRecord,
+ lookup: (id: string) => TypedRecord | undefined,
+): void {
+ for (const selection of plan.selections.filter((item) => item.record === record.id)) {
+ verifyRecordAffinity(graph, plan, selection.output, record, lookup);
+ }
+}
+
+export function verifyInitialAffinities(
+ graph: CompiledGraph,
+ plan: BuildPlan,
+ authored: readonly TypedRecord[],
+): void {
+ const records = new Map([...authored, ...plan.initialValues].map((record) => [record.id, record]));
+ for (const record of plan.initialValues) {
+ verifyGraphRecordAffinity(graph, plan, record, (id) => records.get(id));
+ }
+}
+
+function resultPortForRecord(
+ program: LinkedProgram,
+ step: ProducerStep,
+ recordId: string,
+) {
+ const producer = resolveProducer(program.closure, step.producer);
+ const output = Object.entries(step.outputs).find(([, id]) => id === recordId);
+ if (output !== undefined) return producer.outputs.find((port) => port.name === output[0]);
+ const need = Object.entries(step.needs).find(([, binding]) => binding.result === recordId);
+ return need === undefined ? undefined : producer.needs.find((port) => port.name === need[0]);
+}
+
+/** Verify the result-to-input identity promises declared by the Producer itself. */
+export function verifyProducerRecordAffinity(
+ program: LinkedProgram,
+ plan: BuildPlan,
+ record: TypedRecord,
+ lookup: (id: string) => TypedRecord | undefined,
+): void {
+ if (record.conformance === "substitute") return;
+ const step = plan.steps.find((item) =>
+ Object.values(item.outputs).includes(record.id)
+ || Object.values(item.needs).some((binding) => binding.result === record.id));
+ if (step === undefined) return;
+ const port = resultPortForRecord(program, step, record.id);
+ invariant(port !== undefined, "UNKNOWN_RESULT_PORT", `${record.id} has no Producer result port`, record.id);
+ for (const affinity of port.affinity ?? []) {
+ const inputId = step.inputs[affinity.input];
+ invariant(
+ inputId !== undefined,
+ "UNKNOWN_AFFINITY_INPUT",
+ `${step.id} has no input ${affinity.input}`,
+ step.id,
+ );
+ const input = lookup(inputId);
+ invariant(
+ input !== undefined,
+ "UNPROVEN_EXACT_AFFINITY",
+ `${record.id} cannot prove affinity to ${inputId}`,
+ record.id,
+ );
+ const resultValue = atPointer(inlineValue(record.value, record.id), affinity.resultPointer, record.id);
+ const inputValue = atPointer(inlineValue(input.value, input.id), affinity.inputPointer, input.id);
+ invariant(
+ canonicalStringify(resultValue) === canonicalStringify(inputValue),
+ "AFFINITY_MISMATCH",
+ `${record.id}${affinity.resultPointer} does not match ${input.id}${affinity.inputPointer}`,
+ record.id,
+ );
+ }
+}
diff --git a/packages/core/src/canonical.ts b/packages/core/src/canonical.ts
index a3a4a91f..daf79cb4 100644
--- a/packages/core/src/canonical.ts
+++ b/packages/core/src/canonical.ts
@@ -1,98 +1,8 @@
-import { createHash } from "node:crypto";
-
-import type {
- CanonicalValue,
- Digest,
- StoredValue,
- TypeRef,
- TypedRecord,
+export {
+ canonicalStringify,
+ canonicalize,
+ digestOf,
+ isDigest,
+ recordDigest,
+ semanticRecordsDigest,
} from "@svml/protocol";
-
-import { CoreError } from "./error.js";
-
-function normalize(value: unknown, path: string, ancestors: WeakSet<object>): CanonicalValue {
- if (value === null || typeof value === "boolean" || typeof value === "string") {
- return value;
- }
-
- if (typeof value === "number") {
- if (!Number.isFinite(value)) {
- throw new CoreError("NON_CANONICAL_NUMBER", `${path} must be finite`);
- }
- return Object.is(value, -0) ? 0 : value;
- }
-
- if (Array.isArray(value)) {
- if (ancestors.has(value)) throw new CoreError("CYCLIC_VALUE", `${path} contains a cycle`);
- ancestors.add(value);
- const result = value.map((item, index) => normalize(item, `${path}[${index}]`, ancestors));
- ancestors.delete(value);
- return result;
- }
-
- if (typeof value === "object") {
- const prototype = Object.getPrototypeOf(value);
- if (prototype !== Object.prototype && prototype !== null) {
- throw new CoreError("NON_CANONICAL_OBJECT", `${path} must be a plain object`);
- }
- if (ancestors.has(value)) throw new CoreError("CYCLIC_VALUE", `${path} contains a cycle`);
- ancestors.add(value);
-
- const result: Record<string, CanonicalValue> = {};
- const source = value as Record<string, unknown>;
- for (const key of Object.keys(source).sort()) {
- const descriptor = Object.getOwnPropertyDescriptor(source, key);
- if (descriptor === undefined || descriptor.get !== undefined || descriptor.set !== undefined) {
- throw new CoreError("NON_CANONICAL_ACCESSOR", `${path}.${key} must be a data property`);
- }
- const item = descriptor.value;
- if (item === undefined) {
- throw new CoreError("NON_CANONICAL_UNDEFINED", `${path}.${key} is undefined`);
- }
- Object.defineProperty(result, key, {
- value: normalize(item, `${path}.${key}`, ancestors),
- enumerable: true,
- configurable: true,
- writable: true,
- });
- }
- ancestors.delete(value);
- return result;
- }
-
- throw new CoreError("NON_CANONICAL_VALUE", `${path} contains ${typeof value}`);
-}
-
-export function canonicalize(value: unknown): CanonicalValue {
- return normalize(value, "$input", new WeakSet<object>());
-}
-
-export function canonicalStringify(value: unknown): string {
- return JSON.stringify(canonicalize(value));
-}
-
-export function digestOf(value: unknown): Digest {
- const hex = createHash("sha256").update(canonicalStringify(value), "utf8").digest("hex");
- return `sha256:${hex}`;
-}
-
-export function isDigest(value: string): value is Digest {
- return /^sha256:[0-9a-f]{64}$/u.test(value);
-}
-
-export function recordDigest(type: TypeRef, value: StoredValue): Digest {
- return digestOf({ type, value });
-}
-
-export function semanticRecordsDigest(records: readonly TypedRecord[]): Digest {
- return digestOf(
- [...records]
- .sort((left, right) => left.id.localeCompare(right.id))
- .map((record) => ({
- id: record.id,
- type: record.type,
- value: record.value,
- conformance: record.conformance,
- })),
- );
-}
diff --git a/packages/core/src/error.ts b/packages/core/src/error.ts
index 6b8b5056..31e31df9 100644
--- a/packages/core/src/error.ts
+++ b/packages/core/src/error.ts
@@ -1,14 +1,6 @@
-export class CoreError extends Error {
- readonly code: string;
- readonly subject: string | undefined;
+import { SvmlError } from "@svml/protocol";
- constructor(code: string, message: string, subject?: string) {
- super(message);
- this.name = "CoreError";
- this.code = code;
- this.subject = subject;
- }
-}
+export { SvmlError as CoreError };
export function invariant(
condition: unknown,
@@ -17,6 +9,6 @@ export function invariant(
subject?: string,
): asserts condition {
if (!condition) {
- throw new CoreError(code, message, subject);
+ throw new SvmlError(code, message, subject);
}
}
diff --git a/packages/core/src/graph.ts b/packages/core/src/graph.ts
new file mode 100644
index 00000000..3797c466
--- /dev/null
+++ b/packages/core/src/graph.ts
@@ -0,0 +1,509 @@
+import type {
+ BuildRequest,
+ Candidate,
+ CandidateBinding,
+ CandidateRoot,
+ CompiledGraph,
+ GraphValueRef,
+ LinkedProgram,
+ LogicalOutput,
+ OperationNode,
+ OperationResult,
+ ProducerRef,
+ StoredValue,
+ TypeRef,
+} from "@svml/protocol";
+
+import { canonicalize, digestOf, isDigest } from "./canonical.js";
+import { invariant } from "./error.js";
+import { resolveProducer, sealRecord, verifyRecord } from "./link.js";
+import { producerKey, sameType, typeKey } from "./reference.js";
+
+export const EMPTY_REALIZATION_DIGEST = digestOf({
+ format: "svml.realization-closure@1",
+ overlays: [],
+});
+
+export function valueRefKey(ref: GraphValueRef): string {
+ if (ref.kind === "record") return `record\u0000${ref.id}`;
+ if (ref.kind === "logical-output") return `output\u0000${ref.id}`;
+ return `operation\u0000${ref.operation}`;
+}
+
+function normalizeRef(ref: GraphValueRef): GraphValueRef {
+ if (ref.kind === "record") return { kind: "record", id: ref.id };
+ if (ref.kind === "logical-output") return { kind: "logical-output", id: ref.id };
+ return { kind: "operation-result", operation: ref.operation };
+}
+
+function normalizedStoredValue(value: StoredValue): StoredValue {
+ if (value.kind === "inline") return { kind: "inline", value: canonicalize(value.value) };
+ return { kind: "blob", digest: value.digest, size: value.size, mediaType: value.mediaType };
+}
+
+function normalizeRoot(root: CandidateRoot): CandidateRoot {
+ if (root.kind === "operation") {
+ return { kind: "operation", result: { kind: "operation-result", operation: root.result.operation } };
+ }
+ const value = {
+ id: root.value.id,
+ value: normalizedStoredValue(root.value.value),
+ };
+ return root.value.provenance === undefined
+ ? { kind: "value", value }
+ : { kind: "value", value: { ...value, provenance: canonicalize(root.value.provenance) } };
+}
+
+function normalizeOutput(output: LogicalOutput): LogicalOutput {
+ const base = {
+ id: output.id,
+ type: output.type,
+ primary: output.primary,
+ candidates: [...output.candidates].sort(),
+ semanticInputs: [...output.semanticInputs].map(normalizeRef).sort((a, b) =>
+ valueRefKey(a).localeCompare(valueRefKey(b))),
+ };
+ return output.affinity === undefined
+ ? base
+ : {
+ ...base,
+ affinity: [...output.affinity]
+ .map((constraint) => ({
+ resultPointer: constraint.resultPointer,
+ source: normalizeRef(constraint.source),
+ sourcePointer: constraint.sourcePointer,
+ }))
+ .sort((a, b) => a.resultPointer.localeCompare(b.resultPointer)),
+ };
+}
+
+function normalizeCandidate(candidate: Candidate): Candidate {
+ return {
+ id: candidate.id,
+ output: candidate.output,
+ root: normalizeRoot(candidate.root),
+ fidelity: candidate.fidelity,
+ };
+}
+
+function normalizeResult(result: OperationResult): OperationResult {
+ if (result.kind === "output") {
+ return { kind: "output", name: result.name, record: result.record };
+ }
+ return {
+ kind: "need",
+ name: result.name,
+ id: result.id,
+ record: result.record,
+ accepts: result.accepts,
+ };
+}
+
+function normalizeOperation(operation: OperationNode): OperationNode {
+ return {
+ id: operation.id,
+ producer: operation.producer,
+ inputs: Object.fromEntries(
+ Object.entries(operation.inputs)
+ .sort(([a], [b]) => a.localeCompare(b))
+ .map(([name, ref]) => [name, normalizeRef(ref)]),
+ ),
+ result: normalizeResult(operation.result),
+ };
+}
+
+export function sealCompiledGraph(
+ graph: Omit<CompiledGraph, "format" | "id" | "source" | "realization">
+ & Partial<Pick<CompiledGraph, "source" | "realization">>,
+): CompiledGraph {
+ const normalized = {
+ program: graph.program,
+ outputs: [...graph.outputs].map(normalizeOutput).sort((a, b) => a.id.localeCompare(b.id)),
+ candidates: [...graph.candidates].map(normalizeCandidate).sort((a, b) => a.id.localeCompare(b.id)),
+ operations: [...graph.operations].map(normalizeOperation).sort((a, b) => a.id.localeCompare(b.id)),
+ };
+ const source = graph.source ?? digestOf({ format: "svml.graph-source@1", ...normalized });
+ const realization = graph.realization ?? EMPTY_REALIZATION_DIGEST;
+ const content = {
+ format: "svml.graph@1" as const,
+ ...normalized,
+ source,
+ realization,
+ };
+ return { ...content, id: digestOf(content) };
+}
+
+export function sealBuildRequest(
+ request: Omit<BuildRequest, "format" | "digest">,
+): BuildRequest {
+ const targets = [...request.targets]
+ .map((target) => ({ output: target.output, accepts: target.accepts }))
+ .sort((a, b) => a.output.localeCompare(b.output));
+ const bindings = [...request.bindings]
+ .map((binding) => ({ output: binding.output, candidate: binding.candidate }))
+ .sort((a, b) => a.output.localeCompare(b.output));
+ const content = {
+ format: "svml.build-request@1" as const,
+ graph: request.graph,
+ targets,
+ bindings,
+ };
+ return { ...content, digest: digestOf(content) };
+}
+
+export function resolveLogicalOutput(graph: CompiledGraph, id: string): LogicalOutput {
+ const output = graph.outputs.find((item) => item.id === id);
+ invariant(output !== undefined, "UNKNOWN_LOGICAL_OUTPUT", `unknown logical output ${id}`, id);
+ return output;
+}
+
+export function resolveCandidate(graph: CompiledGraph, id: string): Candidate {
+ const candidate = graph.candidates.find((item) => item.id === id);
+ invariant(candidate !== undefined, "UNKNOWN_CANDIDATE", `unknown Candidate ${id}`, id);
+ return candidate;
+}
+
+export function resolveOperation(graph: CompiledGraph, id: string): OperationNode {
+ const operation = graph.operations.find((item) => item.id === id);
+ invariant(operation !== undefined, "UNKNOWN_OPERATION", `unknown Operation ${id}`, id);
+ return operation;
+}
+
+export function bindingForOutput(
+ request: BuildRequest,
+ output: string,
+): CandidateBinding | undefined {
+ return request.bindings.find((binding) => binding.output === output);
+}
+
+export function selectedCandidate(
+ graph: CompiledGraph,
+ request: BuildRequest,
+ outputId: string,
+): Candidate {
+ const output = resolveLogicalOutput(graph, outputId);
+ const binding = bindingForOutput(request, outputId);
+ const candidate = resolveCandidate(graph, binding?.candidate ?? output.primary);
+ invariant(
+ candidate.output === output.id,
+ "CANDIDATE_OUTPUT_MISMATCH",
+ `${candidate.id} cannot realize ${output.id}`,
+ candidate.id,
+ );
+ return candidate;
+}
+
+export function operationResultRecord(operation: OperationNode): string {
+ return operation.result.record;
+}
+
+export function operationResultType(program: LinkedProgram, operation: OperationNode): TypeRef {
+ const producer = resolveProducer(program.closure, operation.producer);
+ if (operation.result.kind === "output") {
+ const output = producer.outputs.find((port) => port.name === operation.result.name);
+ invariant(
+ output !== undefined && producer.needs.length === 0,
+ "OPERATION_RESULT_MISMATCH",
+ `${operation.id} does not produce output ${operation.result.name}`,
+ operation.id,
+ );
+ return output.type;
+ }
+ const need = producer.needs.find((port) => port.name === operation.result.name);
+ invariant(
+ need !== undefined && producer.outputs.length === 0,
+ "OPERATION_RESULT_MISMATCH",
+ `${operation.id} does not request Need ${operation.result.name}`,
+ operation.id,
+ );
+ return need.returns;
+}
+
+function graphValueType(program: LinkedProgram, graph: CompiledGraph, ref: GraphValueRef): TypeRef {
+ if (ref.kind === "record") {
+ const record = program.records.find((item) => item.id === ref.id);
+ invariant(record !== undefined, "UNKNOWN_GRAPH_INPUT", `unknown authored record ${ref.id}`, ref.id);
+ return record.type;
+ }
+ if (ref.kind === "logical-output") return resolveLogicalOutput(graph, ref.id).type;
+ return operationResultType(program, resolveOperation(graph, ref.operation));
+}
+
+function verifyAffinityPointer(pointer: string, subject: string): void {
+ invariant(
+ pointer === "" || pointer.startsWith("/"),
+ "INVALID_AFFINITY_POINTER",
+ `${subject} has invalid JSON Pointer ${pointer}`,
+ subject,
+ );
+ for (const token of pointer === "" ? [] : pointer.slice(1).split("/")) {
+ invariant(
+ !/~(?:[^01]|$)/u.test(token),
+ "INVALID_AFFINITY_POINTER",
+ `${subject} has invalid JSON Pointer escape in ${pointer}`,
+ subject,
+ );
+ }
+}
+
+function exactKeys(
+ actual: Readonly<Record<string, unknown>>,
+ expected: readonly string[],
+ subject: string,
+): void {
+ const left = Object.keys(actual).sort();
+ const right = [...expected].sort();
+ invariant(
+ JSON.stringify(left) === JSON.stringify(right),
+ "GRAPH_PORT_BINDING_MISMATCH",
+ `${subject} binds [${left.join(", ")}] but declares [${right.join(", ")}]`,
+ subject,
+ );
+}
+
+function verifyOperation(program: LinkedProgram, graph: CompiledGraph, operation: OperationNode): void {
+ invariant(operation.id.length > 0, "EMPTY_OPERATION_ID", "Operation id is empty");
+ invariant(operation.result.record.length > 0, "EMPTY_RECORD_ID", `${operation.id} result record is empty`);
+ const producer = resolveProducer(program.closure, operation.producer);
+ exactKeys(operation.inputs, producer.inputs.map((port) => port.name), `${operation.id}.inputs`);
+ invariant(
+ producer.outputs.length + producer.needs.length === 1,
+ "PRODUCER_RESULT_NORMAL_FORM",
+ `${producerKey(operation.producer)} must declare exactly one public result`,
+ );
+ operationResultType(program, operation);
+ if (operation.result.kind === "need") {
+ invariant(operation.result.id.length > 0, "EMPTY_NEED_ID", `${operation.id} Need id is empty`);
+ invariant(
+ operation.result.accepts === "exact" || operation.result.accepts === "substitute",
+ "INVALID_NEED_ACCEPTANCE",
+ `${operation.id} Need acceptance is invalid`,
+ );
+ }
+ for (const declaration of producer.inputs) {
+ const supplied = graphValueType(program, graph, operation.inputs[declaration.name] as GraphValueRef);
+ invariant(
+ sameType(supplied, declaration.type),
+ "GRAPH_INPUT_TYPE_MISMATCH",
+ `${operation.id}.${declaration.name} wants ${typeKey(declaration.type)} but receives ${typeKey(supplied)}`,
+ operation.id,
+ );
+ }
+}
+
+function semanticLeaves(graph: CompiledGraph, root: CandidateRoot): Set<string> {
+ const leaves = new Set<string>();
+ const visited = new Set<string>();
+ const visiting = new Set<string>();
+
+ const visitRef = (ref: GraphValueRef): void => {
+ if (ref.kind !== "operation-result") {
+ leaves.add(valueRefKey(ref));
+ return;
+ }
+ if (visited.has(ref.operation)) return;
+ invariant(
+ !visiting.has(ref.operation),
+ "OPERATION_CYCLE",
+ `Operation cycle reaches ${ref.operation}`,
+ ref.operation,
+ );
+ visiting.add(ref.operation);
+ const operation = resolveOperation(graph, ref.operation);
+ Object.values(operation.inputs).forEach(visitRef);
+ visiting.delete(ref.operation);
+ visited.add(ref.operation);
+ };
+
+ if (root.kind === "operation") visitRef(root.result);
+ return leaves;
+}
+
+function candidateType(program: LinkedProgram, graph: CompiledGraph, candidate: Candidate): TypeRef {
+ const output = resolveLogicalOutput(graph, candidate.output);
+ if (candidate.root.kind === "operation") {
+ return operationResultType(program, resolveOperation(graph, candidate.root.result.operation));
+ }
+ const provisional = sealRecord({
+ id: candidate.root.value.id,
+ type: output.type,
+ value: candidate.root.value.value,
+ conformance: candidate.fidelity,
+ origin: {
+ kind: "provided",
+ candidate: candidate.id,
+ requestDigest: digestOf(`candidate:${candidate.id}`),
+ ...(candidate.root.value.provenance === undefined
+ ? {}
+ : { provenance: candidate.root.value.provenance }),
+ },
+ });
+ verifyRecord(program.closure, provisional);
+ return provisional.type;
+}
+
+export function verifyCompiledGraph(program: LinkedProgram, graph: CompiledGraph): void {
+ invariant(graph.format === "svml.graph@1", "UNSUPPORTED_GRAPH", "unsupported compiled graph format");
+ invariant(isDigest(graph.id), "INVALID_DIGEST", "compiled graph id is invalid");
+ invariant(isDigest(graph.source), "INVALID_DIGEST", "compiled graph source digest is invalid");
+ invariant(isDigest(graph.realization), "INVALID_DIGEST", "compiled graph realization digest is invalid");
+ invariant(
+ graph.program === program.semanticDigest,
+ "GRAPH_PROGRAM_MISMATCH",
+ "compiled graph belongs to another linked program",
+ );
+ const { id: _id, ...content } = graph;
+ invariant(graph.id === digestOf(content), "GRAPH_DIGEST_MISMATCH", "compiled graph digest differs");
+ if (graph.realization === EMPTY_REALIZATION_DIGEST) {
+ invariant(
+ graph.source === digestOf({
+ format: "svml.graph-source@1",
+ program: graph.program,
+ outputs: graph.outputs,
+ candidates: graph.candidates,
+ operations: graph.operations,
+ }),
+ "GRAPH_SOURCE_DIGEST_MISMATCH",
+ "author graph source digest differs",
+ );
+ }
+
+ const outputIds = new Set<string>();
+ const candidateIds = new Set<string>();
+ const operationIds = new Set<string>();
+ const operationRecords = new Set(program.records.map((record) => record.id));
+ const needIds = new Set<string>();
+
+ for (const output of graph.outputs) {
+ invariant(output.id.length > 0, "EMPTY_LOGICAL_OUTPUT_ID", "Logical Output id is empty");
+ invariant(!outputIds.has(output.id), "DUPLICATE_LOGICAL_OUTPUT", `duplicate ${output.id}`, output.id);
+ outputIds.add(output.id);
+ const semanticInputs = output.semanticInputs.map(valueRefKey);
+ invariant(
+ new Set(semanticInputs).size === semanticInputs.length,
+ "DUPLICATE_SEMANTIC_INPUT",
+ `${output.id} repeats a Semantic Input`,
+ output.id,
+ );
+ const pointers = new Set<string>();
+ for (const constraint of output.affinity ?? []) {
+ verifyAffinityPointer(constraint.resultPointer, output.id);
+ verifyAffinityPointer(constraint.sourcePointer, output.id);
+ invariant(!pointers.has(constraint.resultPointer), "DUPLICATE_AFFINITY", `${output.id} repeats affinity`);
+ pointers.add(constraint.resultPointer);
+ graphValueType(program, graph, constraint.source);
+ }
+ }
+
+ for (const operation of graph.operations) {
+ invariant(!operationIds.has(operation.id), "DUPLICATE_OPERATION", `duplicate ${operation.id}`, operation.id);
+ operationIds.add(operation.id);
+ invariant(
+ !operationRecords.has(operation.result.record),
+ "DUPLICATE_RECORD",
+ `record ${operation.result.record} has multiple sources`,
+ operation.result.record,
+ );
+ operationRecords.add(operation.result.record);
+ if (operation.result.kind === "need") {
+ invariant(!needIds.has(operation.result.id), "DUPLICATE_NEED", `duplicate Need ${operation.result.id}`);
+ needIds.add(operation.result.id);
+ }
+ }
+ for (const operation of graph.operations) verifyOperation(program, graph, operation);
+
+ for (const candidate of graph.candidates) {
+ invariant(candidate.id.length > 0, "EMPTY_CANDIDATE_ID", "Candidate id is empty");
+ invariant(!candidateIds.has(candidate.id), "DUPLICATE_CANDIDATE", `duplicate ${candidate.id}`, candidate.id);
+ candidateIds.add(candidate.id);
+ const output = resolveLogicalOutput(graph, candidate.output);
+ invariant(
+ output.candidates.includes(candidate.id),
+ "CANDIDATE_NOT_EXPOSED",
+ `${candidate.id} is not exposed by ${output.id}`,
+ candidate.id,
+ );
+ invariant(
+ candidate.fidelity === "exact" || candidate.fidelity === "substitute",
+ "INVALID_CONFORMANCE",
+ `${candidate.id} fidelity is invalid`,
+ );
+ const supplied = candidateType(program, graph, candidate);
+ invariant(
+ sameType(supplied, output.type),
+ "CANDIDATE_RESULT_TYPE_MISMATCH",
+ `${candidate.id} returns ${typeKey(supplied)}, not ${typeKey(output.type)}`,
+ candidate.id,
+ );
+ const allowed = new Set(output.semanticInputs.map(valueRefKey));
+ for (const leaf of semanticLeaves(graph, candidate.root)) {
+ invariant(
+ allowed.has(leaf),
+ "CANDIDATE_EXCEEDS_SEMANTIC_ENVELOPE",
+ `${candidate.id} depends on ${leaf} outside ${output.id}'s Semantic Input Envelope`,
+ candidate.id,
+ );
+ }
+ }
+
+ for (const output of graph.outputs) {
+ invariant(output.candidates.length > 0, "OUTPUT_WITHOUT_CANDIDATE", `${output.id} has no Candidates`);
+ invariant(
+ new Set(output.candidates).size === output.candidates.length,
+ "DUPLICATE_OUTPUT_CANDIDATE",
+ `${output.id} repeats a Candidate`,
+ output.id,
+ );
+ const primary = resolveCandidate(graph, output.primary);
+ invariant(primary.output === output.id, "PRIMARY_OUTPUT_MISMATCH", `${output.id} Primary belongs elsewhere`);
+ invariant(output.candidates.includes(primary.id), "PRIMARY_NOT_EXPOSED", `${output.id} omits its Primary`);
+ invariant(primary.fidelity === "exact", "PRIMARY_NOT_EXACT", `${output.id} Primary must be exact`);
+ for (const id of output.candidates) {
+ const candidate = resolveCandidate(graph, id);
+ invariant(candidate.output === output.id, "CANDIDATE_OUTPUT_MISMATCH", `${id} belongs elsewhere`);
+ }
+ }
+}
+
+export function verifyBuildRequest(
+ program: LinkedProgram,
+ graph: CompiledGraph,
+ request: BuildRequest,
+): void {
+ verifyCompiledGraph(program, graph);
+ invariant(
+ request.format === "svml.build-request@1",
+ "UNSUPPORTED_BUILD_REQUEST",
+ "unsupported BuildRequest format",
+ );
+ invariant(isDigest(request.digest), "INVALID_DIGEST", "BuildRequest digest is invalid");
+ invariant(request.graph === graph.id, "BUILD_REQUEST_GRAPH_MISMATCH", "BuildRequest belongs to another graph");
+ const { digest: _digest, ...content } = request;
+ invariant(request.digest === digestOf(content), "BUILD_REQUEST_DIGEST_MISMATCH", "BuildRequest digest differs");
+ invariant(request.targets.length > 0, "EMPTY_BUILD_TARGETS", "BuildRequest has no Targets");
+
+ const targets = new Set<string>();
+ for (const target of request.targets) {
+ resolveLogicalOutput(graph, target.output);
+ invariant(!targets.has(target.output), "DUPLICATE_BUILD_TARGET", `${target.output} is targeted twice`);
+ invariant(
+ target.accepts === "exact" || target.accepts === "substitute",
+ "INVALID_TARGET_ACCEPTANCE",
+ target.output,
+ );
+ targets.add(target.output);
+ }
+
+ const bindings = new Set<string>();
+ for (const binding of request.bindings) {
+ const output = resolveLogicalOutput(graph, binding.output);
+ invariant(!bindings.has(output.id), "DUPLICATE_CANDIDATE_BINDING", `${output.id} is bound twice`);
+ const candidate = resolveCandidate(graph, binding.candidate);
+ invariant(candidate.output === output.id, "CANDIDATE_OUTPUT_MISMATCH", `${candidate.id} cannot realize ${output.id}`);
+ bindings.add(output.id);
+ }
+}
+
+export function sameProducerRef(left: ProducerRef, right: ProducerRef): boolean {
+ return producerKey(left) === producerKey(right);
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 6e45d33c..e345193f 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -1,10 +1,17 @@
export { canonicalStringify, canonicalize, digestOf, isDigest, recordDigest } from "./canonical.js";
+export {
+ verifyGraphRecordAffinity,
+ verifyInitialAffinities,
+ verifyProducerRecordAffinity,
+ verifyRecordAffinity,
+} from "./affinity.js";
export { CoreError } from "./error.js";
export {
computeClosureDigest,
computeModuleDigest,
createResolvedClosure,
link,
+ resolveCapability,
resolveProducer,
resolveType,
sealRecord,
@@ -12,7 +19,22 @@ export {
verifyClosure,
verifyRecord,
} from "./link.js";
-export { validatePlan } from "./plan.js";
+export {
+ EMPTY_REALIZATION_DIGEST,
+ bindingForOutput,
+ operationResultRecord,
+ operationResultType,
+ resolveCandidate,
+ resolveLogicalOutput,
+ resolveOperation,
+ sealBuildRequest,
+ sealCompiledGraph,
+ selectedCandidate,
+ valueRefKey,
+ verifyBuildRequest,
+ verifyCompiledGraph,
+} from "./graph.js";
+export { compileBuild, deriveBuildPlan, validatePlan } from "./plan.js";
export { reduce, start } from "./reducer.js";
export { verifyBuildState } from "./verify.js";
export { validateStoredValue } from "./schema.js";
diff --git a/packages/core/src/link.ts b/packages/core/src/link.ts
index ad5d819c..4151c714 100644
--- a/packages/core/src/link.ts
+++ b/packages/core/src/link.ts
@@ -1,4 +1,5 @@
import type {
+ CapabilityRef,
Digest,
LinkedProgram,
ModuleManifest,
@@ -6,6 +7,7 @@ import type {
ProducerRef,
ResolvedModule,
ResolvedModuleClosure,
+ ResolvedCapabilityDeclaration,
ResolvedProducerDeclaration,
ResolvedTypeDeclaration,
TypeRef,
@@ -15,7 +17,7 @@ import type {
import { digestOf, isDigest, recordDigest, semanticRecordsDigest } from "./canonical.js";
import { CoreError, invariant } from "./error.js";
-import { moduleKey, producerKey, sameModule, typeKey } from "./reference.js";
+import { capabilityKey, moduleKey, producerKey, sameModule, typeKey } from "./reference.js";
import { validateStoredValue } from "./schema.js";
export type TypedRecordDraft = Omit<TypedRecord, "digest">;
@@ -63,6 +65,23 @@ function ensureUniqueNames(names: readonly string[], kind: string, owner: string
}
}
+function verifyPointer(pointer: string, subject: string): void {
+ invariant(
+ pointer === "" || pointer.startsWith("/"),
+ "INVALID_AFFINITY_POINTER",
+ `${subject} has invalid JSON Pointer ${pointer}`,
+ subject,
+ );
+ for (const token of pointer === "" ? [] : pointer.slice(1).split("/")) {
+ invariant(
+ !/~(?:[^01]|$)/u.test(token),
+ "INVALID_AFFINITY_POINTER",
+ `${subject} has invalid JSON Pointer escape in ${pointer}`,
+ subject,
+ );
+ }
+}
+
export function verifyClosure(closure: ResolvedModuleClosure): void {
invariant(closure.format === "svml.closure@0", "UNSUPPORTED_CLOSURE", "unsupported closure format");
invariant(isDigest(closure.digest), "INVALID_DIGEST", "closure digest is invalid");
@@ -88,6 +107,7 @@ export function verifyClosure(closure: ResolvedModuleClosure): void {
key,
);
ensureUniqueNames(module.manifest.types.map((item) => item.name), "type", key);
+ ensureUniqueNames(module.manifest.capabilities.map((item) => item.name), "capability", key);
ensureUniqueNames(module.manifest.surfaces.map((item) => item.name), "surface", key);
ensureUniqueNames(module.manifest.surfaces.map((item) => item.tag), "surface tag", key);
ensureUniqueNames(module.manifest.producers.map((item) => item.name), "producer", key);
@@ -100,6 +120,32 @@ export function verifyClosure(closure: ResolvedModuleClosure): void {
ensureUniqueNames(producer.inputs.map((item) => item.name), "input port", `${key}#${producer.name}`);
ensureUniqueNames(producer.outputs.map((item) => item.name), "output port", `${key}#${producer.name}`);
ensureUniqueNames(producer.needs.map((item) => item.name), "need port", `${key}#${producer.name}`);
+ invariant(
+ producer.outputs.length + producer.needs.length === 1,
+ "PRODUCER_RESULT_NORMAL_FORM",
+ `${key}#${producer.name} must declare exactly one public result`,
+ );
+ const inputNames = new Set(producer.inputs.map((input) => input.name));
+ for (const result of [...producer.outputs, ...producer.needs]) {
+ const resultPointers = new Set<string>();
+ for (const affinity of result.affinity ?? []) {
+ invariant(
+ inputNames.has(affinity.input),
+ "UNKNOWN_AFFINITY_INPUT",
+ `${key}#${producer.name}.${result.name} references unknown input ${affinity.input}`,
+ producer.name,
+ );
+ verifyPointer(affinity.resultPointer, `${key}#${producer.name}.${result.name}`);
+ verifyPointer(affinity.inputPointer, `${key}#${producer.name}.${affinity.input}`);
+ invariant(
+ !resultPointers.has(affinity.resultPointer),
+ "DUPLICATE_AFFINITY",
+ `${key}#${producer.name}.${result.name} repeats ${affinity.resultPointer}`,
+ producer.name,
+ );
+ resultPointers.add(affinity.resultPointer);
+ }
+ }
invariant(
isDigest(producer.implementation.digest),
"INVALID_DIGEST",
@@ -185,18 +231,51 @@ export function verifyClosure(closure: ResolvedModuleClosure): void {
}
for (const port of producer.needs) {
invariant(
- allowed.has(moduleKey(port.wants.module)),
+ allowed.has(moduleKey(port.returns.module)),
"UNDECLARED_TYPE_DEPENDENCY",
- `${moduleKey(module.ref)}#${producer.name} references ${typeKey(port.wants)} without a dependency`,
+ `${moduleKey(module.ref)}#${producer.name} references ${typeKey(port.returns)} without a dependency`,
);
- const target = modules.get(moduleKey(port.wants.module));
+ const target = modules.get(moduleKey(port.returns.module));
invariant(
- target?.manifest.types.some((type) => type.name === port.wants.name),
+ target?.manifest.types.some((type) => type.name === port.returns.name),
"UNKNOWN_TYPE",
- `${moduleKey(module.ref)}#${producer.name} references unknown type ${typeKey(port.wants)}`,
+ `${moduleKey(module.ref)}#${producer.name} references unknown type ${typeKey(port.returns)}`,
+ );
+ invariant(
+ allowed.has(moduleKey(port.capability.module)),
+ "UNDECLARED_CAPABILITY_DEPENDENCY",
+ `${moduleKey(module.ref)}#${producer.name} references ${capabilityKey(port.capability)} without a dependency`,
+ );
+ const capabilityModule = modules.get(moduleKey(port.capability.module));
+ const capability = capabilityModule?.manifest.capabilities.find(
+ (item) => item.name === port.capability.name,
+ );
+ invariant(
+ capability !== undefined,
+ "UNKNOWN_CAPABILITY",
+ `${moduleKey(module.ref)}#${producer.name} references unknown capability ${capabilityKey(port.capability)}`,
+ );
+ invariant(
+ typeKey(capability.returns) === typeKey(port.returns),
+ "CAPABILITY_RETURN_MISMATCH",
+ `${capabilityKey(port.capability)} returns ${typeKey(capability.returns)}, not ${typeKey(port.returns)}`,
);
}
}
+ for (const capability of module.manifest.capabilities) {
+ const ref = { module: module.ref, name: capability.name };
+ invariant(
+ allowed.has(moduleKey(capability.returns.module)),
+ "UNDECLARED_TYPE_DEPENDENCY",
+ `${capabilityKey(ref)} returns ${typeKey(capability.returns)} without a dependency`,
+ );
+ const target = modules.get(moduleKey(capability.returns.module));
+ invariant(
+ target?.manifest.types.some((type) => type.name === capability.returns.name),
+ "UNKNOWN_TYPE",
+ `${capabilityKey(ref)} returns unknown type ${typeKey(capability.returns)}`,
+ );
+ }
}
}
@@ -232,6 +311,27 @@ export function resolveProducer(
return { ...declaration, ref };
}
+export function resolveCapability(
+ closure: ResolvedModuleClosure,
+ ref: CapabilityRef,
+): ResolvedCapabilityDeclaration {
+ const module = closure.modules.find((item) => sameModule(item.ref, ref.module));
+ invariant(
+ module !== undefined,
+ "UNKNOWN_MODULE",
+ `unknown module ${moduleKey(ref.module)}`,
+ capabilityKey(ref),
+ );
+ const declaration = module.manifest.capabilities.find((item) => item.name === ref.name);
+ invariant(
+ declaration !== undefined,
+ "UNKNOWN_CAPABILITY",
+ `unknown capability ${capabilityKey(ref)}`,
+ capabilityKey(ref),
+ );
+ return { ...declaration, ref };
+}
+
export function sealRecord(record: TypedRecordDraft): TypedRecord {
return { ...record, digest: recordDigest(record.type, record.value) };
}
@@ -258,6 +358,13 @@ export function verifyRecord(
`${record.id} frontend closure digest is invalid`,
);
invariant(record.conformance === "exact", "AUTHORED_SUBSTITUTE", `${record.id} authored record is substitute`);
+ } else if (record.origin.kind === "provided") {
+ invariant(record.origin.candidate.length > 0, "EMPTY_CANDIDATE_ID", `${record.id} Candidate id is empty`);
+ invariant(
+ isDigest(record.origin.requestDigest),
+ "INVALID_DIGEST",
+ `${record.id} BuildRequest digest is invalid`,
+ );
}
}
diff --git a/packages/core/src/plan.ts b/packages/core/src/plan.ts
index fd14db0c..3323a66a 100644
--- a/packages/core/src/plan.ts
+++ b/packages/core/src/plan.ts
@@ -1,15 +1,33 @@
import type {
BuildPlan,
+ BuildRequest,
+ CompiledGraph,
+ Conformance,
+ GraphValueRef,
LinkedProgram,
+ OperationNode,
ProducerStep,
RecordId,
TypeRef,
+ TypedRecord,
} from "@svml/protocol";
+import { canonicalStringify, digestOf } from "./canonical.js";
import { invariant } from "./error.js";
-import { resolveProducer } from "./link.js";
+import {
+ operationResultRecord,
+ resolveLogicalOutput,
+ resolveOperation,
+ selectedCandidate,
+ verifyBuildRequest,
+} from "./graph.js";
+import { resolveProducer, sealRecord, verifyRecord } from "./link.js";
import { sameType, typeKey } from "./reference.js";
+function worst(left: Conformance, right: Conformance): Conformance {
+ return left === "substitute" || right === "substitute" ? "substitute" : "exact";
+}
+
function exactKeys(
actual: Readonly<Record<string, unknown>>,
expected: readonly string[],
@@ -25,18 +43,209 @@ function exactKeys(
);
}
+function subsetKeys(
+ actual: Readonly<Record<string, unknown>>,
+ declared: readonly string[],
+ subject: string,
+): void {
+ const allowed = new Set(declared);
+ for (const name of Object.keys(actual)) {
+ invariant(allowed.has(name), "PORT_BINDING_MISMATCH", `${subject} binds undeclared port ${name}`, subject);
+ }
+}
+
+type ResolvedSource = {
+ readonly record: RecordId;
+ readonly type: TypeRef;
+};
+
+type DemandedOperation = {
+ readonly operation: OperationNode;
+ readonly inputs: Readonly<Record<string, RecordId>>;
+ fidelity: Conformance;
+};
+
type ProducedRecord = {
readonly type: TypeRef;
readonly step?: string;
};
-export function validatePlan(program: LinkedProgram, plan: BuildPlan): void {
- invariant(plan.format === "svml.plan@0", "UNSUPPORTED_PLAN", "unsupported build plan format");
- invariant(plan.id.length > 0, "EMPTY_PLAN_ID", "build plan id is empty");
+function planContent(
+ graph: CompiledGraph,
+ request: BuildRequest,
+ initialValues: readonly TypedRecord[],
+ steps: readonly ProducerStep[],
+ goals: BuildPlan["goals"],
+ selections: BuildPlan["selections"],
+): Omit<BuildPlan, "id"> {
+ return {
+ format: "svml.plan@1",
+ graph: graph.id,
+ request: request.digest,
+ initialValues,
+ steps,
+ goals,
+ selections,
+ };
+}
+
+export function compileBuild(
+ program: LinkedProgram,
+ graph: CompiledGraph,
+ request: BuildRequest,
+): BuildPlan {
+ verifyBuildRequest(program, graph, request);
+
+ const authored = new Map(program.records.map((record) => [record.id, record]));
+ const initialValues = new Map<string, TypedRecord>();
+ const demanded = new Map<string, DemandedOperation>();
+ const resolvedOutputs = new Map<string, ResolvedSource>();
+ const resolvingOutputs = new Set<string>();
+ const resolvingOperations = new Set<string>();
+ const selections = new Map<string, BuildPlan["selections"][number]>();
+
+ const resolveRef = (ref: GraphValueRef): ResolvedSource => {
+ if (ref.kind === "record") {
+ const record = authored.get(ref.id);
+ invariant(record !== undefined, "UNKNOWN_RECORD", `unknown authored record ${ref.id}`, ref.id);
+ return { record: record.id, type: record.type };
+ }
+ if (ref.kind === "logical-output") return resolveOutput(ref.id);
+ return demandOperation(ref.operation, "exact");
+ };
+
+ const demandOperation = (id: string, fidelity: Conformance): ResolvedSource => {
+ const existing = demanded.get(id);
+ if (existing !== undefined) {
+ existing.fidelity = worst(existing.fidelity, fidelity);
+ const operation = existing.operation;
+ const producer = resolveProducer(program.closure, operation.producer);
+ const type = operation.result.kind === "output"
+ ? producer.outputs.find((port) => port.name === operation.result.name)?.type
+ : producer.needs.find((port) => port.name === operation.result.name)?.returns;
+ invariant(type !== undefined, "OPERATION_RESULT_MISMATCH", `${id} result is not declared`, id);
+ return { record: operationResultRecord(operation), type };
+ }
+ invariant(!resolvingOperations.has(id), "SELECTED_GRAPH_CYCLE", `selected graph cycles through ${id}`, id);
+ resolvingOperations.add(id);
+ const operation = resolveOperation(graph, id);
+ const inputs = Object.fromEntries(
+ Object.entries(operation.inputs).map(([name, ref]) => [name, resolveRef(ref).record]),
+ );
+ resolvingOperations.delete(id);
+ demanded.set(id, { operation, inputs, fidelity });
+ const producer = resolveProducer(program.closure, operation.producer);
+ const type = operation.result.kind === "output"
+ ? producer.outputs.find((port) => port.name === operation.result.name)?.type
+ : producer.needs.find((port) => port.name === operation.result.name)?.returns;
+ invariant(type !== undefined, "OPERATION_RESULT_MISMATCH", `${id} result is not declared`, id);
+ return { record: operationResultRecord(operation), type };
+ };
+
+ const resolveOutput = (id: string): ResolvedSource => {
+ const known = resolvedOutputs.get(id);
+ if (known !== undefined) return known;
+ invariant(!resolvingOutputs.has(id), "SELECTED_GRAPH_CYCLE", `selected graph cycles through ${id}`, id);
+ resolvingOutputs.add(id);
+ const output = resolveLogicalOutput(graph, id);
+ const candidate = selectedCandidate(graph, request, id);
+ let resolved: ResolvedSource;
+ if (candidate.root.kind === "value") {
+ const record = sealRecord({
+ id: candidate.root.value.id,
+ type: output.type,
+ value: candidate.root.value.value,
+ conformance: candidate.fidelity,
+ origin: {
+ kind: "provided",
+ candidate: candidate.id,
+ requestDigest: request.digest,
+ ...(candidate.root.value.provenance === undefined
+ ? {}
+ : { provenance: candidate.root.value.provenance }),
+ },
+ });
+ verifyRecord(program.closure, record);
+ invariant(!authored.has(record.id), "PROVIDED_RECORD_CONFLICT", `${record.id} conflicts with authored input`);
+ const previous = initialValues.get(record.id);
+ invariant(
+ previous === undefined || canonicalStringify(previous) === canonicalStringify(record),
+ "PROVIDED_RECORD_CONFLICT",
+ `${record.id} has conflicting Provided Values`,
+ record.id,
+ );
+ initialValues.set(record.id, record);
+ resolved = { record: record.id, type: record.type };
+ } else {
+ resolved = demandOperation(candidate.root.result.operation, candidate.fidelity);
+ }
+ invariant(
+ sameType(resolved.type, output.type),
+ "CANDIDATE_RESULT_TYPE_MISMATCH",
+ `${candidate.id} returns ${typeKey(resolved.type)}, not ${typeKey(output.type)}`,
+ candidate.id,
+ );
+ resolvingOutputs.delete(id);
+ resolvedOutputs.set(id, resolved);
+ selections.set(id, { output: id, candidate: candidate.id, record: resolved.record });
+ return resolved;
+ };
+
+ const targetSources = request.targets.map((target) => ({ target, source: resolveOutput(target.output) }));
+
+ const steps: ProducerStep[] = [...demanded.values()]
+ .sort((a, b) => a.operation.id.localeCompare(b.operation.id))
+ .map(({ operation, inputs, fidelity }) => ({
+ id: operation.id,
+ producer: operation.producer,
+ fidelity,
+ inputs,
+ outputs: operation.result.kind === "output"
+ ? { [operation.result.name]: operation.result.record }
+ : {},
+ needs: operation.result.kind === "need"
+ ? {
+ [operation.result.name]: {
+ id: operation.result.id,
+ result: operation.result.record,
+ accepts: operation.result.accepts,
+ },
+ }
+ : {},
+ }));
+
+ const goals = targetSources
+ .map(({ target, source }) => ({ record: source.record, type: source.type, accepts: target.accepts }))
+ .sort((a, b) => a.record.localeCompare(b.record));
+ const sortedInitial = [...initialValues.values()].sort((a, b) => a.id.localeCompare(b.id));
+ const sortedSelections = [...selections.values()].sort((a, b) => a.output.localeCompare(b.output));
+ const content = planContent(graph, request, sortedInitial, steps, goals, sortedSelections);
+ const plan: BuildPlan = { ...content, id: digestOf(content) };
+ validatePlanStructure(program, graph, request, plan);
+ verifyStaticGoalConformance(program, plan);
+ return plan;
+}
+
+function validatePlanStructure(
+ program: LinkedProgram,
+ graph: CompiledGraph,
+ request: BuildRequest,
+ plan: BuildPlan,
+): void {
+ invariant(plan.format === "svml.plan@1", "UNSUPPORTED_PLAN", "unsupported build plan format");
+ invariant(plan.graph === graph.id, "PLAN_GRAPH_MISMATCH", "build plan belongs to another graph");
+ invariant(plan.request === request.digest, "PLAN_REQUEST_MISMATCH", "build plan belongs to another request");
+ const { id: _id, ...content } = plan;
+ invariant(plan.id === digestOf(content), "PLAN_DIGEST_MISMATCH", "build plan digest differs");
invariant(plan.goals.length > 0, "EMPTY_PLAN_GOALS", "build plan has no goals");
const records = new Map<RecordId, ProducedRecord>();
for (const record of program.records) records.set(record.id, { type: record.type });
+ for (const record of plan.initialValues) {
+ verifyRecord(program.closure, record);
+ invariant(!records.has(record.id), "DUPLICATE_RECORD", `record ${record.id} has multiple sources`, record.id);
+ records.set(record.id, { type: record.type });
+ }
const stepIds = new Set<string>();
const needIds = new Set<string>();
@@ -45,29 +254,32 @@ export function validatePlan(program: LinkedProgram, plan: BuildPlan): void {
stepIds.add(step.id);
const producer = resolveProducer(program.closure, step.producer);
exactKeys(step.inputs, producer.inputs.map((port) => port.name), `${step.id}.inputs`);
- exactKeys(step.outputs, producer.outputs.map((port) => port.name), `${step.id}.outputs`);
- exactKeys(step.needs, producer.needs.map((port) => port.name), `${step.id}.needs`);
-
+ subsetKeys(step.outputs, producer.outputs.map((port) => port.name), `${step.id}.outputs`);
+ subsetKeys(step.needs, producer.needs.map((port) => port.name), `${step.id}.needs`);
+ invariant(
+ step.fidelity === "exact" || step.fidelity === "substitute",
+ "INVALID_CONFORMANCE",
+ `${step.id} fidelity is invalid`,
+ );
+ invariant(
+ Object.keys(step.outputs).length + Object.keys(step.needs).length === 1,
+ "STEP_RESULT_NORMAL_FORM",
+ `${step.id} must expose one atomic result`,
+ step.id,
+ );
for (const port of producer.outputs) {
const id = step.outputs[port.name];
- invariant(id !== undefined && id.length > 0, "EMPTY_RECORD_ID", `${step.id}.${port.name} is empty`);
+ if (id === undefined) continue;
invariant(!records.has(id), "DUPLICATE_RECORD", `record ${id} has multiple producers`, id);
records.set(id, { type: port.type, step: step.id });
}
for (const port of producer.needs) {
const binding = step.needs[port.name];
- invariant(binding !== undefined, "MISSING_NEED_BINDING", `${step.id}.${port.name} is not bound`);
- invariant(binding.id.length > 0, "EMPTY_NEED_ID", `${step.id}.${port.name} need id is empty`);
+ if (binding === undefined) continue;
invariant(!needIds.has(binding.id), "DUPLICATE_NEED", `need ${binding.id} has multiple producers`);
needIds.add(binding.id);
- invariant(binding.result.length > 0, "EMPTY_RECORD_ID", `${step.id}.${port.name} result id is empty`);
- invariant(
- !records.has(binding.result),
- "DUPLICATE_RECORD",
- `record ${binding.result} has multiple producers`,
- binding.result,
- );
- records.set(binding.result, { type: port.wants, step: step.id });
+ invariant(!records.has(binding.result), "DUPLICATE_RECORD", `${binding.result} has multiple producers`);
+ records.set(binding.result, { type: port.returns, step: step.id });
}
}
@@ -75,31 +287,71 @@ export function validatePlan(program: LinkedProgram, plan: BuildPlan): void {
const producer = resolveProducer(program.closure, step.producer);
for (const port of producer.inputs) {
const id = step.inputs[port.name];
- invariant(id !== undefined, "MISSING_INPUT_BINDING", `${step.id}.${port.name} is not bound`);
- const supplied = records.get(id);
+ const supplied = records.get(id as string);
invariant(supplied !== undefined, "UNKNOWN_RECORD", `${step.id}.${port.name} references ${id}`, id);
invariant(
sameType(supplied.type, port.type),
"INPUT_TYPE_MISMATCH",
- `${step.id}.${port.name} wants ${typeKey(port.type)} but ${id} is ${typeKey(supplied.type)}`,
+ `${step.id}.${port.name} wants ${typeKey(port.type)} but ${String(id)} is ${typeKey(supplied.type)}`,
id,
);
}
}
+ for (const selection of plan.selections) {
+ const output = resolveLogicalOutput(graph, selection.output);
+ const record = records.get(selection.record);
+ invariant(record !== undefined, "UNKNOWN_SELECTION_RECORD", `${selection.output} selects ${selection.record}`);
+ invariant(sameType(record.type, output.type), "SELECTION_TYPE_MISMATCH", selection.output);
+ }
for (const goal of plan.goals) {
const supplied = records.get(goal.record);
invariant(supplied !== undefined, "UNKNOWN_GOAL", `goal references ${goal.record}`, goal.record);
+ invariant(sameType(supplied.type, goal.type), "GOAL_TYPE_MISMATCH", goal.record);
+ }
+ assertAcyclic(plan, records);
+ assertAllStepsReachGoal(plan, records);
+}
+
+function verifyStaticGoalConformance(program: LinkedProgram, plan: BuildPlan): void {
+ const conformances = new Map(program.records.map((record) => [record.id, record.conformance]));
+ for (const record of plan.initialValues) conformances.set(record.id, record.conformance);
+ const pending = new Map(plan.steps.map((step) => [step.id, step]));
+ while (pending.size > 0) {
+ let progressed = false;
+ for (const [id, step] of pending) {
+ const inputs = Object.values(step.inputs).map((record) => conformances.get(record));
+ if (inputs.some((item) => item === undefined)) continue;
+ const conformance = inputs.reduce<Conformance>((result, item) => worst(result, item as Conformance), step.fidelity);
+ Object.values(step.outputs).forEach((record) => conformances.set(record, conformance));
+ Object.values(step.needs).forEach((need) => conformances.set(need.result, conformance));
+ pending.delete(id);
+ progressed = true;
+ }
+ invariant(progressed, "PLAN_CYCLE", "build plan contains a producer cycle");
+ }
+ for (const goal of plan.goals) {
invariant(
- sameType(supplied.type, goal.type),
- "GOAL_TYPE_MISMATCH",
- `goal wants ${typeKey(goal.type)} but ${goal.record} is ${typeKey(supplied.type)}`,
+ goal.accepts === "substitute" || conformances.get(goal.record) === "exact",
+ "TARGET_REJECTS_SUBSTITUTE",
+ `exact Target ${goal.record} selects a substitute path`,
goal.record,
);
}
+}
- assertAcyclic(plan, records);
- assertAllStepsReachGoal(plan, records);
+export function validatePlan(
+ program: LinkedProgram,
+ graph: CompiledGraph,
+ request: BuildRequest,
+ plan: BuildPlan,
+): void {
+ const expected = compileBuild(program, graph, request);
+ invariant(
+ canonicalStringify(plan) === canonicalStringify(expected),
+ "PLAN_NOT_DERIVED",
+ "build plan is not the plan compiled from its graph and BuildRequest",
+ );
}
function assertAcyclic(plan: BuildPlan, records: ReadonlyMap<RecordId, ProducedRecord>): void {
@@ -112,7 +364,6 @@ function assertAcyclic(plan: BuildPlan, records: ReadonlyMap<RecordId, ProducedR
if (producer !== undefined) own.add(producer);
}
}
-
const complete = new Set<string>();
while (complete.size < plan.steps.length) {
const ready = [...dependencies.entries()]
@@ -132,7 +383,6 @@ function assertAllStepsReachGoal(
const queue = plan.goals
.map((goal) => records.get(goal.record)?.step)
.filter((step): step is string => step !== undefined);
-
while (queue.length > 0) {
const id = queue.pop() as string;
if (required.has(id)) continue;
@@ -144,14 +394,8 @@ function assertAllStepsReachGoal(
if (dependency !== undefined) queue.push(dependency);
}
}
-
for (const step of plan.steps) {
- invariant(
- required.has(step.id),
- "UNREACHABLE_STEP",
- `${step.id} does not contribute to any build goal`,
- step.id,
- );
+ invariant(required.has(step.id), "UNREACHABLE_STEP", `${step.id} does not contribute to any goal`, step.id);
}
}
@@ -160,3 +404,6 @@ export function producerStep(plan: BuildPlan, id: string): ProducerStep {
invariant(step !== undefined, "UNKNOWN_STEP", `unknown step ${id}`, id);
return step;
}
+
+/** @deprecated Use compileBuild. */
+export const deriveBuildPlan = compileBuild;
diff --git a/packages/core/src/provenance.ts b/packages/core/src/provenance.ts
index 56ac1b6e..f3bdb699 100644
--- a/packages/core/src/provenance.ts
+++ b/packages/core/src/provenance.ts
@@ -18,10 +18,11 @@ export function eventDigest(event: unknown): Digest {
}
export function needRequestDigest(
- need: Pick<Need, "wants" | "constraints" | "result" | "accepts" | "conformanceFloor">,
+ need: Pick<Need, "capability" | "returns" | "constraints" | "result" | "accepts" | "conformanceFloor">,
): Digest {
return digestOf({
- wants: need.wants,
+ capability: need.capability,
+ returns: need.returns,
constraints: need.constraints,
result: need.result,
accepts: need.accepts,
diff --git a/packages/core/src/reducer.ts b/packages/core/src/reducer.ts
index 136309fb..e89931a5 100644
--- a/packages/core/src/reducer.ts
+++ b/packages/core/src/reducer.ts
@@ -1,11 +1,13 @@
import type {
BuildEvent,
BuildPlan,
+ BuildRequest,
BuildState,
CanonicalValue,
Conformance,
CoreCommand,
CoreTransition,
+ CompiledGraph,
Derivation,
FulfillNeedCommand,
InvokeProducerCommand,
@@ -18,10 +20,15 @@ import type {
TypedRecord,
} from "@svml/protocol";
+import {
+ verifyGraphRecordAffinity,
+ verifyInitialAffinities,
+ verifyProducerRecordAffinity,
+} from "./affinity.js";
import { canonicalize, digestOf, recordDigest } from "./canonical.js";
import { CoreError, invariant } from "./error.js";
import { resolveProducer, resolveType, sealRecord } from "./link.js";
-import { producerStep, validatePlan } from "./plan.js";
+import { compileBuild, producerStep } from "./plan.js";
import {
commandId,
derivationId,
@@ -93,8 +100,10 @@ function acceptProducerEvent(
exactPortKeys(event.needs, producer.needs.map((port) => port.name), `${step.id}.needs`);
const inputs = inputRecords(state, command);
- const conformance = inheritedConformance(inputs);
- const outputDrafts = producer.outputs.map((port) => {
+ const conformance = effectiveConformance(inheritedConformance(inputs), step.fidelity);
+ const outputDrafts = producer.outputs
+ .filter((port) => step.outputs[port.name] !== undefined)
+ .map((port) => {
const id = step.outputs[port.name];
const rawValue = event.outputs[port.name];
invariant(id !== undefined, "MISSING_OUTPUT_BINDING", `${step.id}.${port.name} is not bound`);
@@ -104,14 +113,17 @@ function acceptProducerEvent(
return { id, type: port.type, value, digest: recordDigest(port.type, value) };
});
- const needDrafts = producer.needs.map((port) => {
+ const needDrafts = producer.needs
+ .filter((port) => step.needs[port.name] !== undefined)
+ .map((port) => {
const binding = step.needs[port.name];
const constraints = event.needs[port.name];
invariant(binding !== undefined, "MISSING_NEED_BINDING", `${step.id}.${port.name} is not bound`);
invariant(constraints !== undefined, "MISSING_NEED_VALUE", `${step.id}.${port.name} returned no constraints`);
const normalized = canonicalize(constraints);
const request = {
- wants: port.wants,
+ capability: port.capability,
+ returns: port.returns,
constraints: normalized,
result: binding.result,
accepts: binding.accepts,
@@ -142,6 +154,11 @@ function acceptProducerEvent(
conformance,
origin: { kind: "derived", derivation: id },
}));
+ const outputLookup = new Map([...state.records, ...outputs].map((record) => [record.id, record]));
+ outputs.forEach((record) => {
+ verifyProducerRecordAffinity(state.program, state.plan, record, (recordId) => outputLookup.get(recordId));
+ verifyGraphRecordAffinity(state.graph, state.plan, record, (recordId) => outputLookup.get(recordId));
+ });
const needs: Need[] = needDrafts.map((need) => ({ ...need, requestedBy: id }));
return {
@@ -178,15 +195,15 @@ function acceptNeedEvent(
);
invariant(
need.accepts === "substitute"
- || effectiveConformance(need.conformanceFloor, event.conformance) === "exact",
+ || event.conformance === "exact",
"SUBSTITUTE_NOT_ACCEPTED",
- `${need.id} requires exact fulfillment`,
+ `${need.id} requires an exact fulfillment of its selected capability`,
need.id,
);
const value = normalizeStoredValue(event.value);
- validateStoredValue(value, resolveType(state.program.closure, need.wants).schema, `$need.${need.id}`);
- const outputDigest = recordDigest(need.wants, value);
+ validateStoredValue(value, resolveType(state.program.closure, need.returns).schema, `$need.${need.id}`);
+ const outputDigest = recordDigest(need.returns, value);
const metadata = canonicalize(event.metadata);
const conformance = effectiveConformance(need.conformanceFloor, event.conformance);
const receiptDraft: Omit<Receipt, "id"> = {
@@ -204,12 +221,15 @@ function acceptNeedEvent(
const receipt: Receipt = { id: receiptId(receiptDraft), ...receiptDraft };
const record: TypedRecord = {
id: need.result,
- type: need.wants,
+ type: need.returns,
value,
digest: outputDigest,
conformance,
origin: { kind: "observed", receipt: receipt.id },
};
+ const recordLookup = new Map([...state.records, record].map((item) => [item.id, item]));
+ verifyProducerRecordAffinity(state.program, state.plan, record, (recordId) => recordLookup.get(recordId));
+ verifyGraphRecordAffinity(state.graph, state.plan, record, (recordId) => recordLookup.get(recordId));
return {
...state,
@@ -273,28 +293,6 @@ function goalsComplete(state: BuildState): boolean {
function schedule(state: BuildState): CoreTransition {
if (state.status !== "active") return { state, commands: [] };
- const impossibleNeed = state.needs.find((need) =>
- need.accepts === "exact"
- && need.conformanceFloor === "substitute"
- && !state.records.some((record) => record.id === need.result));
- if (impossibleNeed !== undefined) {
- return {
- state: {
- ...state,
- status: "failed",
- outstanding: [],
- diagnostics: [
- ...state.diagnostics,
- {
- code: "CONFORMANCE_FLOOR_UNSATISFIABLE",
- message: `${impossibleNeed.id} requires exact output from substitute inputs`,
- subject: impossibleNeed.id,
- },
- ],
- },
- commands: [],
- };
- }
if (state.outstanding.length > 0) return { state, commands: state.outstanding };
if (goalsComplete(state)) {
@@ -359,19 +357,28 @@ function schedule(state: BuildState): CoreTransition {
return { state: scheduled, commands };
}
-export function start(program: LinkedProgram, plan: BuildPlan): BuildState {
- validatePlan(program, plan);
+export function start(
+ program: LinkedProgram,
+ graph: CompiledGraph,
+ request: BuildRequest,
+): BuildState {
+ const plan: BuildPlan = compileBuild(program, graph, request);
+ verifyInitialAffinities(graph, plan, program.records);
const state: BuildState = {
- format: "svml.build@0",
+ format: "svml.build@1",
id: digestOf({
closure: program.closure.digest,
semantic: program.semanticDigest,
- plan,
+ graph: graph.id,
+ request: request.digest,
+ plan: plan.id,
}),
program,
+ graph,
+ request,
plan,
status: "active",
- records: program.records,
+ records: [...program.records, ...plan.initialValues],
steps: plan.steps.map((step) => ({ id: step.id, status: "pending" })),
needs: [],
receipts: [],
diff --git a/packages/core/src/reference.ts b/packages/core/src/reference.ts
index 825edbe1..2ed538d8 100644
--- a/packages/core/src/reference.ts
+++ b/packages/core/src/reference.ts
@@ -1,4 +1,4 @@
-import type { ModuleRef, ProducerRef, TypeRef } from "@svml/protocol";
+import type { CapabilityRef, ModuleRef, ProducerRef, TypeRef } from "@svml/protocol";
export function moduleKey(ref: ModuleRef): string {
return `${ref.name}@${ref.version}`;
@@ -12,6 +12,10 @@ export function producerKey(ref: ProducerRef): string {
return `${moduleKey(ref.module)}#${ref.name}`;
}
+export function capabilityKey(ref: CapabilityRef): string {
+ return `${moduleKey(ref.module)}#${ref.name}`;
+}
+
export function sameModule(left: ModuleRef, right: ModuleRef): boolean {
return left.name === right.name && left.version === right.version;
}
@@ -19,3 +23,11 @@ export function sameModule(left: ModuleRef, right: ModuleRef): boolean {
export function sameType(left: TypeRef, right: TypeRef): boolean {
return sameModule(left.module, right.module) && left.name === right.name;
}
+
+export function sameCapability(left: CapabilityRef, right: CapabilityRef): boolean {
+ return sameModule(left.module, right.module) && left.name === right.name;
+}
+
+export function sameProducer(left: ProducerRef, right: ProducerRef): boolean {
+ return sameModule(left.module, right.module) && left.name === right.name;
+}
diff --git a/packages/core/src/verify.ts b/packages/core/src/verify.ts
index 4b7c1c05..7782a5f7 100644
--- a/packages/core/src/verify.ts
+++ b/packages/core/src/verify.ts
@@ -8,11 +8,12 @@ import type {
} from "@svml/protocol";
import { digestOf, isDigest } from "./canonical.js";
+import { verifyGraphRecordAffinity, verifyProducerRecordAffinity } from "./affinity.js";
import { invariant } from "./error.js";
import { link, resolveProducer, verifyRecord } from "./link.js";
import { producerStep, validatePlan } from "./plan.js";
import { commandId, derivationId, needRequestDigest, receiptId } from "./provenance.js";
-import { sameType } from "./reference.js";
+import { sameCapability, sameType } from "./reference.js";
function unique<T>(items: readonly T[], key: (item: T) => string, kind: string): void {
const seen = new Set<string>();
@@ -126,14 +127,14 @@ function verifyReceipt(state: BuildState, receipt: Receipt): void {
`${receipt.id} does not inherit its Need conformance floor`,
);
invariant(
- need.accepts === "substitute" || receipt.conformance === "exact",
+ need.accepts === "substitute" || receipt.fulfillmentConformance === "exact",
"SUBSTITUTE_NOT_ACCEPTED",
- `${receipt.id} is a forbidden substitute`,
+ `${receipt.id} did not exactly fulfill the selected capability`,
);
const record = findRecord(state, receipt.output);
invariant(record !== undefined, "RECEIPT_OUTPUT_MISSING", `${receipt.id} output is missing`);
invariant(receipt.output === need.result, "RECEIPT_OUTPUT_BINDING", `${receipt.id} output is not its Need result`);
- invariant(sameType(record.type, need.wants), "RECEIPT_OUTPUT_TYPE", `${receipt.id} output type differs`);
+ invariant(sameType(record.type, need.returns), "RECEIPT_OUTPUT_TYPE", `${receipt.id} output type differs`);
invariant(record.conformance === receipt.conformance, "RECEIPT_OUTPUT_CONFORMANCE", receipt.id);
invariant(record.digest === receipt.outputDigest, "RECEIPT_OUTPUT_MISMATCH", `${receipt.id} output differs`);
invariant(
@@ -184,7 +185,7 @@ function verifyOutstanding(state: BuildState, command: CoreCommand): void {
}
export function verifyBuildState(state: BuildState): void {
- invariant(state.format === "svml.build@0", "UNSUPPORTED_BUILD", "unsupported build state format");
+ invariant(state.format === "svml.build@1", "UNSUPPORTED_BUILD", "unsupported build state format");
invariant(
state.status === "active" || state.status === "complete" || state.status === "failed",
"INVALID_BUILD_STATUS",
@@ -217,12 +218,14 @@ export function verifyBuildState(state: BuildState): void {
digestOf({
closure: state.program.closure.digest,
semantic: state.program.semanticDigest,
- plan: state.plan,
+ graph: state.graph.id,
+ request: state.request.digest,
+ plan: state.plan.id,
}),
"BUILD_ID_MISMATCH",
"build id does not match its program and plan",
);
- validatePlan(state.program, state.plan);
+ validatePlan(state.program, state.graph, state.request, state.plan);
unique(state.records, (item) => item.id, "record");
unique(state.steps, (item) => item.id, "step state");
@@ -243,10 +246,24 @@ export function verifyBuildState(state: BuildState): void {
invariant(validConformance(record.conformance), "INVALID_CONFORMANCE", record.id);
verifyRecord(state.program.closure, record);
}
+ const affinityRecords = new Map(state.records.map((record) => [record.id, record]));
+ state.records.forEach((record) => {
+ verifyProducerRecordAffinity(state.program, state.plan, record, (recordId) => affinityRecords.get(recordId));
+ verifyGraphRecordAffinity(state.graph, state.plan, record, (recordId) => affinityRecords.get(recordId));
+ });
for (const authored of state.program.records) {
const record = findRecord(state, authored.id);
invariant(record?.digest === authored.digest, "AUTHORED_RECORD_CHANGED", `${authored.id} changed`);
}
+ for (const provided of state.plan.initialValues) {
+ const record = findRecord(state, provided.id);
+ invariant(
+ record !== undefined && digestOf(record) === digestOf(provided),
+ "PROVIDED_RECORD_CHANGED",
+ `${provided.id} differs from its compiled Provided Value`,
+ provided.id,
+ );
+ }
for (const record of state.records) {
if (record.origin.kind === "authored") {
@@ -270,12 +287,34 @@ export function verifyBuildState(state: BuildState): void {
);
const inputs = derivation.inputs.map((binding) => findRecord(state, binding.id));
invariant(inputs.every((item) => item !== undefined), "DERIVATION_INPUT_MISSING", derivation.id);
- const expected = inputs.some((item) => item?.conformance === "substitute") ? "substitute" : "exact";
+ const step = producerStep(state.plan, derivation.step);
+ const expected = step.fidelity === "substitute"
+ || inputs.some((item) => item?.conformance === "substitute")
+ ? "substitute"
+ : "exact";
invariant(record.conformance === expected, "CONFORMANCE_NOT_PROPAGATED", `${record.id} conformance differs`);
- } else {
+ } else if (record.origin.kind === "observed") {
const origin = record.origin;
const receipt = state.receipts.find((item) => item.id === origin.receipt);
invariant(receipt?.output === record.id, "OBSERVED_ORIGIN_MISMATCH", `${record.id} has no receipt`);
+ } else {
+ const origin = record.origin;
+ const expected = state.plan.initialValues.find((item) => item.id === record.id);
+ invariant(
+ expected !== undefined && digestOf(expected) === digestOf(record),
+ "INJECTED_PROVIDED_RECORD",
+ `${record.id} was not supplied by this BuildRequest`,
+ record.id,
+ );
+ invariant(
+ origin.kind === "provided"
+ && origin.requestDigest === state.request.digest
+ && state.plan.selections.some((selection) =>
+ selection.record === record.id && selection.candidate === origin.candidate),
+ "PROVIDED_ORIGIN_MISMATCH",
+ `${record.id} is not bound to its selected Candidate`,
+ record.id,
+ );
}
}
@@ -293,7 +332,25 @@ export function verifyBuildState(state: BuildState): void {
"NEED_ORIGIN_MISMATCH",
`${need.id} has no derivation`,
);
- const inherited = derivation?.inputs.some(
+ const step = derivation === undefined ? undefined : producerStep(state.plan, derivation.step);
+ const producer = step === undefined ? undefined : resolveProducer(state.program.closure, step.producer);
+ const plannedPort = step === undefined
+ ? undefined
+ : Object.entries(step.needs).find(([, binding]) => binding.id === need.id);
+ const declaration = plannedPort === undefined
+ ? undefined
+ : producer?.needs.find((port) => port.name === plannedPort[0]);
+ invariant(
+ declaration !== undefined
+ && sameCapability(need.capability, declaration.capability)
+ && sameType(need.returns, declaration.returns)
+ && plannedPort?.[1].result === need.result
+ && plannedPort[1].accepts === need.accepts,
+ "NEED_PLAN_BINDING_MISMATCH",
+ `${need.id} differs from its locked Producer Need port`,
+ need.id,
+ );
+ const inherited = step?.fidelity === "substitute" || derivation?.inputs.some(
(binding) => findRecord(state, binding.id)?.conformance === "substitute",
) ? "substitute" : "exact";
invariant(
diff --git a/packages/core/test/core.test.ts b/packages/core/test/core.test.ts
index 5d0015c6..afb318d4 100644
--- a/packages/core/test/core.test.ts
+++ b/packages/core/test/core.test.ts
@@ -4,8 +4,8 @@ import test from "node:test";
import {
CoreError,
canonicalize,
+ digestOf,
reduce,
- start,
validatePlan,
verifyBuildState,
} from "@svml/core";
@@ -67,7 +67,7 @@ function reachNeed(initial = createGreetingBuild()): {
return { state: transition.state, command };
}
-test("Core executes an explicit finite plan through Need, Receipt and completion", () => {
+test("Core executes its derived finite plan through Need, Receipt and completion", () => {
let current = reachNeed();
let transition = reduce(current.state, {
kind: "need-fulfilled",
@@ -136,6 +136,34 @@ test("schema-invalid producer output is rejected before it becomes a Record", ()
);
});
+test("Producer result affinity rejects an exact output that lies about its input", () => {
+ const current = reachNeed();
+ const fulfilled = reduce(current.state, {
+ kind: "need-fulfilled",
+ id: "event:affinity-fulfill",
+ command: current.command.id,
+ value: { kind: "inline", value: "Hello, Ada!" },
+ requestDigest: current.command.need.requestDigest,
+ fulfiller: "test:greeting",
+ conformance: "exact",
+ delivery: "executed",
+ metadata: {},
+ });
+ const assemble = fulfilled.commands.find(
+ (command): command is InvokeProducerCommand => command.kind === "invoke-producer",
+ );
+ assert.ok(assemble);
+ assert.throws(
+ () => reduce(
+ fulfilled.state,
+ producerEvent(assemble, "event:affinity-lie", {
+ document: { kind: "inline", value: { text: "Different text" } },
+ }),
+ ),
+ (error: unknown) => error instanceof CoreError && error.code === "AFFINITY_MISMATCH",
+ );
+});
+
test("an exact Need rejects a substitute fulfillment", () => {
const current = reachNeed();
assert.throws(
@@ -162,6 +190,42 @@ test("serialized BuildState survives a JSON round trip", () => {
assert.deepEqual(reduce(restored).commands, reduce(current.state).commands);
});
+test("a recomputed Need cannot change the capability locked by its Producer port", () => {
+ const current = reachNeed();
+ const tampered = structuredClone(current.state);
+ const need = tampered.needs[0];
+ assert.ok(need);
+ (need as { capability: unknown }).capability = {
+ module: need.capability.module,
+ name: "different-operation",
+ };
+ const requestDigest = digestOf({
+ capability: need.capability,
+ returns: need.returns,
+ constraints: need.constraints,
+ result: need.result,
+ accepts: need.accepts,
+ conformanceFloor: need.conformanceFloor,
+ });
+ (need as { requestDigest: string }).requestDigest = requestDigest;
+
+ const derivation = tampered.derivations.find((item) => item.id === need.requestedBy);
+ assert.ok(derivation);
+ (derivation as { needs: unknown }).needs = [{ id: need.id, requestDigest }];
+ const { id: _oldId, ...derivationContent } = derivation;
+ const nextId = `derivation:${digestOf(derivationContent)}`;
+ (derivation as { id: string }).id = nextId;
+ (need as { requestedBy: string }).requestedBy = nextId;
+ const step = tampered.steps.find((item) => item.derivation === _oldId);
+ assert.ok(step);
+ (step as { derivation: string }).derivation = nextId;
+
+ assert.throws(
+ () => verifyBuildState(tampered),
+ (error: unknown) => error instanceof CoreError && error.code === "NEED_PLAN_BINDING_MISMATCH",
+ );
+});
+
test("authored values cannot be changed inside a resumed BuildState", () => {
const tampered = structuredClone(createGreetingBuild()) as BuildState;
const authored = tampered.records[0];
@@ -175,7 +239,7 @@ test("authored values cannot be changed inside a resumed BuildState", () => {
);
});
-test("an explicit plan cannot hide producer steps unrelated to its goals", () => {
+test("a caller cannot replace Core's graph-derived plan", () => {
const state = createGreetingBuild();
const plan = {
...state.plan,
@@ -184,6 +248,7 @@ test("an explicit plan cannot hide producer steps unrelated to its goals", () =>
{
id: "unused",
producer: producers.makePrompt,
+ fidelity: "exact" as const,
inputs: { intent: "intent:root" },
outputs: { prompt: "prompt:unused" },
needs: {},
@@ -191,10 +256,11 @@ test("an explicit plan cannot hide producer steps unrelated to its goals", () =>
],
};
assert.throws(
- () => validatePlan(state.program, plan),
- (error: unknown) => error instanceof CoreError && error.code === "UNREACHABLE_STEP",
+ () => validatePlan(state.program, state.graph, state.request, plan),
+ (error: unknown) => error instanceof CoreError && error.code === "PLAN_NOT_DERIVED",
);
- assert.throws(() => start(state.program, plan), CoreError);
+ const tampered = { ...state, plan };
+ assert.throws(() => verifyBuildState(tampered), CoreError);
});
test("canonical values reject accessors and preserve hostile-looking keys as data", () => {
diff --git a/packages/core/test/demand.test.ts b/packages/core/test/demand.test.ts
new file mode 100644
index 00000000..da2ff34d
--- /dev/null
+++ b/packages/core/test/demand.test.ts
@@ -0,0 +1,538 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ createResolvedClosure,
+ digestOf,
+ link,
+ reduce,
+ sealBuildRequest,
+ sealCompiledGraph,
+ sealRecord,
+ sealTypedModule,
+ start,
+ verifyBuildState,
+} from "@svml/core";
+import type {
+ BuildRequest,
+ BuildState,
+ Candidate,
+ CandidateBinding,
+ CanonicalValue,
+ CompiledGraph,
+ GraphValueRef,
+ LinkedProgram,
+ LogicalOutput,
+ ModuleManifest,
+ OperationNode,
+ OperationResultRef,
+ ProducerRef,
+ TypeRef,
+} from "@svml/protocol";
+
+const moduleRef = { name: "example.kernel-demand", version: "0.0.0" } as const;
+const types = {
+ head: { module: moduleRef, name: "Head" },
+ duration: { module: moduleRef, name: "Duration" },
+ image: { module: moduleRef, name: "Image" },
+ imageSet: { module: moduleRef, name: "ImageSet" },
+ a: { module: moduleRef, name: "A" },
+ b: { module: moduleRef, name: "B" },
+ c: { module: moduleRef, name: "C" },
+ d: { module: moduleRef, name: "D" },
+ combined: { module: moduleRef, name: "Combined" },
+} satisfies Record<string, TypeRef>;
+
+const producer = (name: string): ProducerRef => ({ module: moduleRef, name });
+const producers = {
+ p1: producer("image-1"),
+ p2: producer("image-2"),
+ p3: producer("image-3"),
+ collect: producer("collect-images"),
+ seedance: producer("seedance-media"),
+ black: producer("black-by-duration"),
+ a1: producer("a1"),
+ a2: producer("a2"),
+ b1: producer("b1"),
+ b2: producer("b2"),
+ c: producer("c"),
+};
+const seedanceCapability = { module: moduleRef, name: "seedance-media" } as const;
+
+const implementation = (name: string) => ({
+ kind: "test",
+ locator: name,
+ digest: digestOf(`${name}@1`),
+});
+
+const manifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: moduleRef.name,
+ version: moduleRef.version,
+ dependencies: [],
+ types: [
+ { name: types.head.name, schema: { kind: "string", minLength: 1 } },
+ { name: types.duration.name, schema: { kind: "number", minimum: 0 } },
+ { name: types.image.name, schema: { kind: "string", minLength: 1 } },
+ { name: types.imageSet.name, schema: { kind: "array", items: { kind: "string" }, minItems: 1 } },
+ ...[types.a, types.b, types.c, types.d, types.combined].map((type) => ({
+ name: type.name,
+ schema: { kind: "string" as const, minLength: 1 },
+ })),
+ ],
+ capabilities: [{ name: seedanceCapability.name, returns: types.image }],
+ surfaces: [],
+ producers: [
+ {
+ name: producers.p1.name,
+ inputs: [{ name: "head", type: types.head }],
+ outputs: [{ name: "image", type: types.image }],
+ needs: [],
+ implementation: implementation("p1"),
+ },
+ {
+ name: producers.p2.name,
+ inputs: [{ name: "head", type: types.head }, { name: "image1", type: types.image }],
+ outputs: [{ name: "image", type: types.image }],
+ needs: [],
+ implementation: implementation("p2"),
+ },
+ {
+ name: producers.p3.name,
+ inputs: [
+ { name: "head", type: types.head },
+ { name: "image1", type: types.image },
+ { name: "image2", type: types.image },
+ ],
+ outputs: [{ name: "image", type: types.image }],
+ needs: [],
+ implementation: implementation("p3"),
+ },
+ {
+ name: producers.collect.name,
+ inputs: [
+ { name: "image1", type: types.image },
+ { name: "image2", type: types.image },
+ { name: "image3", type: types.image },
+ ],
+ outputs: [{ name: "images", type: types.imageSet }],
+ needs: [],
+ implementation: implementation("collect"),
+ },
+ {
+ name: producers.seedance.name,
+ inputs: [
+ { name: "head", type: types.head },
+ { name: "duration", type: types.duration },
+ { name: "reference1", type: types.image },
+ { name: "reference2", type: types.image },
+ ],
+ outputs: [],
+ needs: [{ name: "media", capability: seedanceCapability, returns: types.image }],
+ implementation: implementation("seedance"),
+ },
+ {
+ name: producers.black.name,
+ inputs: [{ name: "duration", type: types.duration }],
+ outputs: [{ name: "media", type: types.image }],
+ needs: [],
+ implementation: implementation("black"),
+ },
+ ...[
+ [producers.a1, "value", types.a],
+ [producers.a2, "value", types.b],
+ ].map(([ref, name, type]) => ({
+ name: (ref as ProducerRef).name,
+ inputs: [],
+ outputs: [{ name: name as string, type: type as TypeRef }],
+ needs: [],
+ implementation: implementation((ref as ProducerRef).name),
+ })),
+ {
+ name: producers.b1.name,
+ inputs: [{ name: "A", type: types.a }, { name: "B", type: types.b }],
+ outputs: [{ name: "C", type: types.c }],
+ needs: [],
+ implementation: implementation("b1"),
+ },
+ {
+ name: producers.b2.name,
+ inputs: [{ name: "A", type: types.a }, { name: "B", type: types.b }],
+ outputs: [{ name: "D", type: types.d }],
+ needs: [],
+ implementation: implementation("b2"),
+ },
+ {
+ name: producers.c.name,
+ inputs: [{ name: "C", type: types.c }, { name: "D", type: types.d }],
+ outputs: [{ name: "combined", type: types.combined }],
+ needs: [],
+ implementation: implementation("c"),
+ },
+ ],
+};
+
+const recordRef = (id: string): GraphValueRef => ({ kind: "record", id });
+const outputRef = (id: string): GraphValueRef => ({ kind: "logical-output", id });
+const operationRef = (operation: string): OperationResultRef => ({ kind: "operation-result", operation });
+
+function output(
+ id: string,
+ type: TypeRef,
+ primary: string,
+ candidates: readonly string[],
+ semanticInputs: readonly GraphValueRef[],
+): LogicalOutput {
+ return { id, type, primary, candidates, semanticInputs };
+}
+
+function candidate(
+ id: string,
+ outputId: string,
+ operation: string,
+ fidelity: "exact" | "substitute" = "exact",
+): Candidate {
+ return { id, output: outputId, root: { kind: "operation", result: operationRef(operation) }, fidelity };
+}
+
+function providedCandidate(
+ id: string,
+ outputId: string,
+ record: string,
+ value: CanonicalValue,
+ fidelity: "exact" | "substitute" = "exact",
+): Candidate {
+ return {
+ id,
+ output: outputId,
+ root: { kind: "value", value: { id: record, value: { kind: "inline", value }, provenance: { test: id } } },
+ fidelity,
+ };
+}
+
+function operation(
+ id: string,
+ producerRef: ProducerRef,
+ inputs: Readonly<Record<string, GraphValueRef>>,
+ result: OperationNode["result"],
+): OperationNode {
+ return { id, producer: producerRef, inputs, result };
+}
+
+function createProgram(): LinkedProgram {
+ const closure = createResolvedClosure([manifest]);
+ const authored = [
+ sealRecord({
+ id: "head:root",
+ type: types.head,
+ value: { kind: "inline", value: "reference" },
+ conformance: "exact",
+ origin: { kind: "authored", sourceDigest: digestOf("source:demand"), frontendClosureDigest: digestOf("frontend:demand") },
+ }),
+ sealRecord({
+ id: "duration:root",
+ type: types.duration,
+ value: { kind: "inline", value: 3 },
+ conformance: "exact",
+ origin: { kind: "authored", sourceDigest: digestOf("source:demand"), frontendClosureDigest: digestOf("frontend:demand") },
+ }),
+ sealRecord({
+ id: "duration:other",
+ type: types.duration,
+ value: { kind: "inline", value: 9 },
+ conformance: "exact",
+ origin: { kind: "authored", sourceDigest: digestOf("source:demand"), frontendClosureDigest: digestOf("frontend:demand") },
+ }),
+ ];
+ return link(closure, [sealTypedModule({ id: "author:demand", closureDigest: closure.digest, records: authored })]);
+}
+
+function createImageGraph(program: LinkedProgram): CompiledGraph {
+ return sealCompiledGraph({
+ program: program.semanticDigest,
+ outputs: [
+ output("image1", types.image, "p1", ["p1", "existing-image1"], [recordRef("head:root")]),
+ output("image2", types.image, "p2", ["p2", "existing-image2"], [recordRef("head:root"), outputRef("image1")]),
+ output("image3", types.image, "p3", ["p3", "existing-image3"], [recordRef("head:root"), outputRef("image1"), outputRef("image2")]),
+ output("images", types.imageSet, "collect", ["collect"], [outputRef("image1"), outputRef("image2"), outputRef("image3")]),
+ output("media", types.image, "seedance", ["seedance", "black", "existing-media"], [
+ recordRef("head:root"),
+ recordRef("duration:root"),
+ outputRef("image1"),
+ outputRef("image2"),
+ ]),
+ ],
+ candidates: [
+ candidate("p1", "image1", "p1"),
+ candidate("p2", "image2", "p2"),
+ candidate("p3", "image3", "p3"),
+ candidate("collect", "images", "collect"),
+ candidate("seedance", "media", "seedance"),
+ candidate("black", "media", "black", "substitute"),
+ providedCandidate("existing-image1", "image1", "provided:image1", "I1"),
+ providedCandidate("existing-image2", "image2", "provided:image2", "I2"),
+ providedCandidate("existing-image3", "image3", "provided:image3", "I3"),
+ providedCandidate("existing-media", "media", "provided:media", "EXISTING MEDIA"),
+ ],
+ operations: [
+ operation("p1", producers.p1, { head: recordRef("head:root") }, { kind: "output", name: "image", record: "image:1" }),
+ operation("p2", producers.p2, { head: recordRef("head:root"), image1: outputRef("image1") }, { kind: "output", name: "image", record: "image:2" }),
+ operation("p3", producers.p3, { head: recordRef("head:root"), image1: outputRef("image1"), image2: outputRef("image2") }, { kind: "output", name: "image", record: "image:3" }),
+ operation("collect", producers.collect, { image1: outputRef("image1"), image2: outputRef("image2"), image3: outputRef("image3") }, { kind: "output", name: "images", record: "images:all" }),
+ operation("seedance", producers.seedance, {
+ head: recordRef("head:root"),
+ duration: recordRef("duration:root"),
+ reference1: outputRef("image1"),
+ reference2: outputRef("image2"),
+ }, { kind: "need", name: "media", id: "need:seedance", record: "media:seedance", accepts: "exact" }),
+ operation("black", producers.black, { duration: recordRef("duration:root") }, { kind: "output", name: "media", record: "media:black" }),
+ ],
+ });
+}
+
+function request(
+ graph: CompiledGraph,
+ targets: readonly string[],
+ bindings: readonly CandidateBinding[] = [],
+ accepts: "exact" | "substitute" = "substitute",
+): BuildRequest {
+ return sealBuildRequest({
+ graph: graph.id,
+ targets: targets.map((outputId) => ({ output: outputId, accepts })),
+ bindings,
+ });
+}
+
+function fixture(targets: readonly string[], bindings: readonly CandidateBinding[] = []): BuildState {
+ const program = createProgram();
+ const graph = createImageGraph(program);
+ return start(program, graph, request(graph, targets, bindings));
+}
+
+function choose(outputId: string, candidateId: string): CandidateBinding {
+ return { output: outputId, candidate: candidateId };
+}
+
+function stepIds(state: BuildState): string[] {
+ return state.plan.steps.map((step) => step.id).sort();
+}
+
+test("Targets and Existing-Value Candidates derive the exact image closure", () => {
+ const cases: readonly [string, readonly CandidateBinding[], readonly string[]][] = [
+ ["image3", [], ["p1", "p2", "p3"]],
+ ["image3", [choose("image1", "existing-image1")], ["p2", "p3"]],
+ ["image3", [choose("image1", "existing-image1"), choose("image2", "existing-image2")], ["p3"]],
+ ["image3", [choose("image3", "existing-image3")], []],
+ ["image2", [], ["p1", "p2"]],
+ ["image1", [], ["p1"]],
+ ];
+ for (const [target, bindings, expected] of cases) {
+ assert.deepEqual(stepIds(fixture([target], bindings)), expected);
+ }
+});
+
+test("an ordinary aggregator intentionally demands every selected image", () => {
+ assert.deepEqual(stepIds(fixture(["images"])), ["collect", "p1", "p2", "p3"]);
+ assert.deepEqual(stepIds(fixture(["images"], [
+ choose("image1", "existing-image1"),
+ choose("image2", "existing-image2"),
+ ])), ["collect", "p3"]);
+});
+
+test("multiple Targets share Operations once and target order is not semantic", () => {
+ const first = fixture(["image3", "image2"]);
+ const second = fixture(["image2", "image3"]);
+ assert.deepEqual(stepIds(first), ["p1", "p2", "p3"]);
+ assert.equal(new Set(first.plan.steps.map((step) => step.id)).size, first.plan.steps.length);
+ assert.equal(first.request.digest, second.request.digest);
+ assert.equal(first.plan.id, second.plan.id);
+});
+
+test("the selected Candidate alone determines the demanded semantic inputs", () => {
+ assert.deepEqual(stepIds(fixture(["media"])), ["p1", "p2", "seedance"]);
+ assert.deepEqual(stepIds(fixture(["media"], [choose("media", "black")])), ["black"]);
+});
+
+test("an Existing Value is a normal Candidate root and prevents the paid Need from existing", () => {
+ const state = fixture(["media"], [choose("media", "existing-media")]);
+ const transition = reduce(state);
+ assert.deepEqual(stepIds(state), []);
+ assert.equal(state.plan.initialValues.length, 1);
+ assert.equal(state.plan.initialValues[0]?.origin.kind, "provided");
+ assert.equal(transition.state.status, "complete");
+ assert.equal(transition.state.needs.length, 0);
+ assert.equal(transition.commands[0]?.kind, "complete");
+});
+
+test("a Candidate cannot escape its Logical Output Semantic Input Envelope", () => {
+ const program = createProgram();
+ const graph = createImageGraph(program);
+ const tampered = sealCompiledGraph({
+ program: graph.program,
+ outputs: graph.outputs,
+ candidates: graph.candidates,
+ operations: graph.operations.map((item) => item.id === "black"
+ ? { ...item, inputs: { duration: recordRef("duration:other") } }
+ : item),
+ });
+ assert.throws(
+ () => start(program, tampered, request(tampered, ["media"], [choose("media", "black")])),
+ /outside media's Semantic Input Envelope/u,
+ );
+});
+
+test("Provided Values are checked against the Logical Output Contract", () => {
+ const program = createProgram();
+ const graph = createImageGraph(program);
+ const invalid = sealCompiledGraph({
+ program: graph.program,
+ outputs: graph.outputs,
+ operations: graph.operations,
+ candidates: graph.candidates.map((item) => item.id === "existing-image1"
+ ? providedCandidate("existing-image1", "image1", "provided:image1", 42)
+ : item),
+ });
+ assert.throws(() => start(program, invalid, request(invalid, ["image1"], [
+ choose("image1", "existing-image1"),
+ ], "exact")), /must be a string/u);
+});
+
+test("Provided state survives JSON round-trip and regenerates identical ready Commands", () => {
+ const state = fixture(["image3"], [
+ choose("image1", "existing-image1"),
+ choose("image2", "existing-image2"),
+ ]);
+ const scheduled = reduce(state);
+ const restored = JSON.parse(JSON.stringify({ ...scheduled.state, outstanding: [] })) as BuildState;
+ verifyBuildState(restored);
+ assert.deepEqual(reduce(restored).commands, scheduled.commands);
+});
+
+function createCaseGGraph(program: LinkedProgram, roots: "value" | "operation"): CompiledGraph {
+ const a1Id = roots === "value" ? "a1-value" : "a1-operation";
+ const a2Id = roots === "value" ? "a2-value" : "a2-operation";
+ return sealCompiledGraph({
+ program: program.semanticDigest,
+ outputs: [
+ output("a.A", types.a, a1Id, [a1Id], []),
+ output("a.B", types.b, a2Id, [a2Id], []),
+ output("b.C", types.c, "b1", ["b1"], [outputRef("a.A"), outputRef("a.B")]),
+ output("b.D", types.d, "b2", ["b2"], [outputRef("a.A"), outputRef("a.B")]),
+ output("c.result", types.combined, "c", ["c"], [outputRef("b.C"), outputRef("b.D")]),
+ ],
+ candidates: [
+ roots === "value"
+ ? providedCandidate(a1Id, "a.A", "provided:A", "A")
+ : candidate(a1Id, "a.A", "a1"),
+ roots === "value"
+ ? providedCandidate(a2Id, "a.B", "provided:B", "B")
+ : candidate(a2Id, "a.B", "a2"),
+ candidate("b1", "b.C", "b1"),
+ candidate("b2", "b.D", "b2"),
+ candidate("c", "c.result", "c"),
+ ],
+ operations: [
+ operation("a1", producers.a1, {}, { kind: "output", name: "value", record: "operation:A" }),
+ operation("a2", producers.a2, {}, { kind: "output", name: "value", record: "operation:B" }),
+ operation("b1", producers.b1, { A: outputRef("a.A"), B: outputRef("a.B") }, { kind: "output", name: "C", record: "operation:C" }),
+ operation("b2", producers.b2, { A: outputRef("a.A"), B: outputRef("a.B") }, { kind: "output", name: "D", record: "operation:D" }),
+ operation("c", producers.c, { C: outputRef("b.C"), D: outputRef("b.D") }, { kind: "output", name: "combined", record: "operation:combined" }),
+ ],
+ });
+}
+
+test("Case G: two single-output full-input Candidates share both upstream Values", () => {
+ const program = createProgram();
+ const graph = createCaseGGraph(program, "value");
+ const state = start(program, graph, request(graph, ["c.result"]));
+ assert.deepEqual(stepIds(state), ["b1", "b2", "c"]);
+ assert.deepEqual(state.plan.initialValues.map((record) => record.id), ["provided:A", "provided:B"]);
+ const b1 = state.plan.steps.find((step) => step.id === "b1");
+ const b2 = state.plan.steps.find((step) => step.id === "b2");
+ assert.deepEqual(b1?.inputs, { A: "provided:A", B: "provided:B" });
+ assert.deepEqual(b2?.inputs, { A: "provided:A", B: "provided:B" });
+ assert.equal(state.plan.selections.find((item) => item.output === "b.C")?.candidate, "b1");
+ assert.equal(state.plan.selections.find((item) => item.output === "b.D")?.candidate, "b2");
+});
+
+test("Case G: shared zero-input upstream Operations appear exactly once", () => {
+ const program = createProgram();
+ const graph = createCaseGGraph(program, "operation");
+ const state = start(program, graph, request(graph, ["c.result"]));
+ assert.deepEqual(stepIds(state), ["a1", "a2", "b1", "b2", "c"]);
+ assert.equal(state.plan.steps.filter((step) => step.id === "a1").length, 1);
+ assert.equal(state.plan.steps.filter((step) => step.id === "a2").length, 1);
+ const b1 = state.plan.steps.find((step) => step.id === "b1");
+ const b2 = state.plan.steps.find((step) => step.id === "b2");
+ assert.deepEqual(b1?.inputs, { A: "operation:A", B: "operation:B" });
+ assert.deepEqual(b2?.inputs, { A: "operation:A", B: "operation:B" });
+});
+
+function createOperationIdentityGraph(
+ program: LinkedProgram,
+ mode: "shared" | "distinct",
+): CompiledGraph {
+ return sealCompiledGraph({
+ program: program.semanticDigest,
+ outputs: [
+ output("left", types.image, "left-candidate", ["left-candidate"], [recordRef("head:root")]),
+ output("right", types.image, "right-candidate", ["right-candidate"], [recordRef("head:root")]),
+ ],
+ candidates: [
+ candidate("left-candidate", "left", "left-operation"),
+ candidate(
+ "right-candidate",
+ "right",
+ mode === "shared" ? "left-operation" : "right-operation",
+ ),
+ ],
+ operations: [
+ operation(
+ "left-operation",
+ producers.p1,
+ { head: recordRef("head:root") },
+ { kind: "output", name: "image", record: "identity:left" },
+ ),
+ ...(mode === "distinct"
+ ? [operation(
+ "right-operation",
+ producers.p1,
+ { head: recordRef("head:root") },
+ { kind: "output", name: "image", record: "identity:right" },
+ )]
+ : []),
+ ],
+ });
+}
+
+test("two Candidates that name one OperationId demand exactly one execution", () => {
+ const program = createProgram();
+ const graph = createOperationIdentityGraph(program, "shared");
+ const state = start(program, graph, request(graph, ["left", "right"]));
+ assert.deepEqual(stepIds(state), ["left-operation"]);
+ assert.deepEqual(
+ state.plan.selections.map((selection) => [selection.output, selection.record]),
+ [["left", "identity:left"], ["right", "identity:left"]],
+ );
+});
+
+test("different OperationIds are never content-deduplicated", () => {
+ const program = createProgram();
+ const graph = createOperationIdentityGraph(program, "distinct");
+ const state = start(program, graph, request(graph, ["left", "right"]));
+ assert.deepEqual(stepIds(state), ["left-operation", "right-operation"]);
+ assert.deepEqual(
+ state.plan.steps.map((step) => step.producer),
+ [producers.p1, producers.p1],
+ "same Producer and same inputs still represent two author-declared operations",
+ );
+});
+
+test("an exact Target rejects a selected substitute Candidate before execution", () => {
+ const program = createProgram();
+ const graph = createImageGraph(program);
+ assert.throws(
+ () => start(program, graph, request(graph, ["media"], [choose("media", "black")], "exact")),
+ /selects a substitute path/u,
+ );
+});
diff --git a/packages/core/test/greeting-fixture.ts b/packages/core/test/greeting-fixture.ts
index 4162ea76..31aaf257 100644
--- a/packages/core/test/greeting-fixture.ts
+++ b/packages/core/test/greeting-fixture.ts
@@ -2,13 +2,17 @@ import {
createResolvedClosure,
digestOf,
link,
+ sealBuildRequest,
+ sealCompiledGraph,
sealRecord,
sealTypedModule,
start,
} from "@svml/core";
import type {
- BuildPlan,
BuildState,
+ CapabilityRef,
+ CompiledGraph,
+ LinkedProgram,
ModuleManifest,
ProducerRef,
TypeRef,
@@ -23,15 +27,21 @@ export const types = {
document: { module: moduleRef, name: "GreetingDocument" },
} satisfies Record<string, TypeRef>;
+export const capabilities = {
+ generation: { module: moduleRef, name: "generate-greeting-text" },
+} satisfies Record<string, CapabilityRef>;
+
export const producers = {
makePrompt: { module: moduleRef, name: "make-prompt" },
requestText: { module: moduleRef, name: "request-text" },
+ placeholderText: { module: moduleRef, name: "placeholder-text" },
assemble: { module: moduleRef, name: "assemble" },
} satisfies Record<string, ProducerRef>;
export const implementationDigests = {
makePrompt: digestOf("example.greeting/make-prompt@0"),
requestText: digestOf("example.greeting/request-text@0"),
+ placeholderText: digestOf("example.greeting/placeholder-text@0"),
assemble: digestOf("example.greeting/assemble@0"),
};
@@ -62,6 +72,7 @@ export const manifest: ModuleManifest = {
},
},
],
+ capabilities: [{ name: capabilities.generation.name, returns: types.generated }],
surfaces: [],
producers: [
{
@@ -79,17 +90,36 @@ export const manifest: ModuleManifest = {
name: producers.requestText.name,
inputs: [{ name: "prompt", type: types.prompt }],
outputs: [],
- needs: [{ name: "generation", wants: types.generated }],
+ needs: [{
+ name: "generation",
+ capability: capabilities.generation,
+ returns: types.generated,
+ }],
implementation: {
kind: "registered",
locator: "example.greeting/request-text",
digest: implementationDigests.requestText,
},
},
+ {
+ name: producers.placeholderText.name,
+ inputs: [{ name: "prompt", type: types.prompt }],
+ outputs: [{ name: "generated", type: types.generated }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.greeting/placeholder-text",
+ digest: implementationDigests.placeholderText,
+ },
+ },
{
name: producers.assemble.name,
inputs: [{ name: "generated", type: types.generated }],
- outputs: [{ name: "document", type: types.document }],
+ outputs: [{
+ name: "document",
+ type: types.document,
+ affinity: [{ resultPointer: "/text", input: "generated", inputPointer: "" }],
+ }],
needs: [],
implementation: {
kind: "registered",
@@ -100,53 +130,71 @@ export const manifest: ModuleManifest = {
],
};
-export function greetingPlan(options?: {
- readonly needAccepts?: "exact" | "substitute";
- readonly goalAccepts?: "exact" | "substitute";
-}): BuildPlan {
- return {
- format: "svml.plan@0",
- id: "greeting",
- steps: [
+export function greetingGraph(program: LinkedProgram): CompiledGraph {
+ return sealCompiledGraph({
+ program: program.semanticDigest,
+ outputs: [
+ {
+ id: "prompt",
+ type: types.prompt,
+ primary: "make-prompt",
+ candidates: ["make-prompt"],
+ semanticInputs: [{ kind: "record", id: "intent:root" }],
+ },
+ {
+ id: "generated",
+ type: types.generated,
+ primary: "request-text",
+ candidates: ["request-text", "placeholder-text"],
+ semanticInputs: [{ kind: "logical-output", id: "prompt" }],
+ },
+ {
+ id: "document",
+ type: types.document,
+ primary: "assemble",
+ candidates: ["assemble"],
+ semanticInputs: [{ kind: "logical-output", id: "generated" }],
+ },
+ ],
+ candidates: [
+ { id: "make-prompt", output: "prompt", root: { kind: "operation", result: { kind: "operation-result", operation: "make-prompt" } }, fidelity: "exact" },
+ { id: "request-text", output: "generated", root: { kind: "operation", result: { kind: "operation-result", operation: "request-text" } }, fidelity: "exact" },
+ { id: "placeholder-text", output: "generated", root: { kind: "operation", result: { kind: "operation-result", operation: "placeholder-text" } }, fidelity: "substitute" },
+ { id: "assemble", output: "document", root: { kind: "operation", result: { kind: "operation-result", operation: "assemble" } }, fidelity: "exact" },
+ ],
+ operations: [
{
id: "make-prompt",
producer: producers.makePrompt,
- inputs: { intent: "intent:root" },
- outputs: { prompt: "prompt:root" },
- needs: {},
+ inputs: { intent: { kind: "record", id: "intent:root" } },
+ result: { kind: "output", name: "prompt", record: "prompt:root" },
},
{
id: "request-text",
producer: producers.requestText,
- inputs: { prompt: "prompt:root" },
- outputs: {},
- needs: {
- generation: {
- id: "need:generation",
- result: "generated:root",
- accepts: options?.needAccepts ?? "exact",
- },
- },
+ inputs: { prompt: { kind: "logical-output", id: "prompt" } },
+ result: { kind: "need", name: "generation", id: "need:generation", record: "generated:root", accepts: "exact" },
},
{
- id: "assemble",
- producer: producers.assemble,
- inputs: { generated: "generated:root" },
- outputs: { document: "document:root" },
- needs: {},
+ id: "placeholder-text",
+ producer: producers.placeholderText,
+ inputs: { prompt: { kind: "logical-output", id: "prompt" } },
+ result: { kind: "output", name: "generated", record: "generated:placeholder" },
},
- ],
- goals: [
{
- record: "document:root",
- type: types.document,
- accepts: options?.goalAccepts ?? "exact",
+ id: "assemble",
+ producer: producers.assemble,
+ inputs: { generated: { kind: "logical-output", id: "generated" } },
+ result: { kind: "output", name: "document", record: "document:root" },
},
],
- };
+ });
}
-export function createGreetingBuild(options?: Parameters<typeof greetingPlan>[0]): BuildState {
+export function createGreetingBuild(options?: {
+ readonly generationRealization?: "primary" | "placeholder";
+ readonly goalAccepts?: "exact" | "substitute";
+}): BuildState {
const closure = createResolvedClosure([manifest]);
const authored = sealRecord({
id: "intent:root",
@@ -165,5 +213,20 @@ export function createGreetingBuild(options?: Parameters<typeof greetingPlan>[0]
closureDigest: closure.digest,
records: [authored],
});
- return start(link(closure, [typedModule]), greetingPlan(options));
+ const program = link(closure, [typedModule]);
+ const graph = greetingGraph(program);
+ const request = sealBuildRequest({
+ graph: graph.id,
+ targets: [{
+ output: "document",
+ accepts: options?.goalAccepts ?? "exact",
+ }],
+ bindings: options?.generationRealization === "placeholder"
+ ? [{
+ output: "generated",
+ candidate: "placeholder-text",
+ }]
+ : [],
+ });
+ return start(program, graph, request);
}
diff --git a/packages/driver-node/README.md b/packages/driver-node/README.md
index 6c428acf..1ad050ef 100644
--- a/packages/driver-node/README.md
+++ b/packages/driver-node/README.md
@@ -5,7 +5,11 @@ Node runtime for executing Core commands without adding workflow semantics to Co
- `HostRegistry` registers deterministic Producer implementations locked by implementation digest.
- `ProviderRegistry` binds an already explicit external capability to endpoints that may use APIs, credentials, queues or local runtimes.
- A Producer emits a typed `Need`; it never reads provider configuration directly.
-- One matching Provider may fulfill a Need. Multiple matches require an explicit runtime `bind()`.
+- Providers match the locked `CapabilityRef` and return `TypeRef`. Multiple exact endpoints require
+ `bind()`. The Registry never routes by return type alone.
+- Preview, fallback and reuse are graph-level Candidates selected by BuildRequest, not Provider
+ modes. A reused value is an Existing-Value Candidate; “Pin” is only the host UI action that selects
+ it. Candidate fidelity is sealed into the Core-derived plan before execution.
- Provider identity becomes the Receipt fulfiller; handlers return only value, conformance, delivery and metadata.
Build state is serializable. Missing providers, generation latency and transient provider errors pause a
@@ -15,6 +19,7 @@ Outstanding Commands are not trusted persistence. Serialization drops them and C
the exact commands from verified facts on resume, before any Handler can run. The Registry never
turns a generic speaker request into a model choice: Seedance, WhisperX or another external method
must already be present as a specific Need in the locked BuildPlan.
+The BuildPlan itself is derived and sealed by Core from the locked CompiledGraph and BuildRequest.
The Driver still does not load implementation code from a package locator. A future sandboxed executor
must be designed and audited before third-party implementations can run. Frontend and Import Prologue
diff --git a/packages/driver-node/src/driver.ts b/packages/driver-node/src/driver.ts
index 1266a32c..1a74002f 100644
--- a/packages/driver-node/src/driver.ts
+++ b/packages/driver-node/src/driver.ts
@@ -9,7 +9,13 @@ import type {
} from "@svml/protocol";
import { MemoryArtifactStore } from "./artifacts.js";
-import { HostRegistry, ProviderRegistry, producerRegistryKey, providerCapabilityKey } from "./registry.js";
+import {
+ HostRegistry,
+ ProviderRegistry,
+ producerRegistryKey,
+ providerCapabilityKey,
+ providerReturnKey,
+} from "./registry.js";
import type {
ArtifactStore,
BlockedCommand,
@@ -112,8 +118,8 @@ export class NodeDriver {
command: command.id,
reason: "missing-provider",
subject: resolution.providerId === undefined
- ? providerCapabilityKey(command.need.wants)
- : `${providerCapabilityKey(command.need.wants)} -> ${resolution.providerId}`,
+ ? `${providerCapabilityKey(command.need.capability)} -> ${providerReturnKey(command.need.returns)}`
+ : `${providerCapabilityKey(command.need.capability)} -> ${resolution.providerId}`,
},
};
}
@@ -122,7 +128,7 @@ export class NodeDriver {
blocked: {
command: command.id,
reason: "ambiguous-provider",
- subject: `${providerCapabilityKey(command.need.wants)} -> ${resolution.providerIds.join(", ")}`,
+ subject: `${providerCapabilityKey(command.need.capability)} -> ${resolution.providerIds.join(", ")}`,
},
};
}
diff --git a/packages/driver-node/src/index.ts b/packages/driver-node/src/index.ts
index 859833ae..7b9bda96 100644
--- a/packages/driver-node/src/index.ts
+++ b/packages/driver-node/src/index.ts
@@ -12,5 +12,6 @@ export {
ProviderRegistry,
producerRegistryKey,
providerCapabilityKey,
+ providerReturnKey,
} from "./registry.js";
export type * from "./types.js";
diff --git a/packages/driver-node/src/manifest.ts b/packages/driver-node/src/manifest.ts
index 7c374e4b..12d5fa45 100644
--- a/packages/driver-node/src/manifest.ts
+++ b/packages/driver-node/src/manifest.ts
@@ -2,6 +2,8 @@ import { readFile } from "node:fs/promises";
import { canonicalize, createResolvedClosure, isDigest } from "@svml/core";
import type {
+ CapabilityDeclaration,
+ CapabilityRef,
Digest,
ImplementationRef,
ModuleDependency,
@@ -67,6 +69,14 @@ function typeRef(value: unknown, path: string): TypeRef {
};
}
+function capabilityRef(value: unknown, path: string): CapabilityRef {
+ const parsed = object(value, path);
+ return {
+ module: moduleRef(parsed.module, `${path}.module`),
+ name: string(parsed.name, `${path}.name`),
+ };
+}
+
function optionalNumber(
parsed: Record<string, unknown>,
name: string,
@@ -175,6 +185,17 @@ function typeDeclaration(value: unknown, path: string): TypeDeclaration {
};
}
+function capabilityDeclaration(value: unknown, path: string): CapabilityDeclaration {
+ const parsed = object(value, path);
+ return {
+ name: string(parsed.name, `${path}.name`),
+ returns: typeRef(parsed.returns, `${path}.returns`),
+ ...(parsed.description === undefined
+ ? {}
+ : { description: string(parsed.description, `${path}.description`) }),
+ };
+}
+
function port(value: unknown, path: string): PortDeclaration {
const parsed = object(value, path);
return {
@@ -187,7 +208,8 @@ function needPort(value: unknown, path: string): NeedPortDeclaration {
const parsed = object(value, path);
return {
name: string(parsed.name, `${path}.name`),
- wants: typeRef(parsed.wants, `${path}.wants`),
+ capability: capabilityRef(parsed.capability, `${path}.capability`),
+ returns: typeRef(parsed.returns, `${path}.returns`),
};
}
@@ -247,6 +269,9 @@ export function parseModuleManifest(value: unknown): ModuleManifest {
types: array(parsed.types, "$manifest.types").map((item, index) =>
typeDeclaration(item, `$manifest.types[${index}]`),
),
+ capabilities: array(parsed.capabilities, "$manifest.capabilities").map((item, index) =>
+ capabilityDeclaration(item, `$manifest.capabilities[${index}]`),
+ ),
surfaces: array(parsed.surfaces, "$manifest.surfaces").map((item, index) =>
surface(item, `$manifest.surfaces[${index}]`),
),
diff --git a/packages/driver-node/src/registry.ts b/packages/driver-node/src/registry.ts
index 78025211..47cfee6c 100644
--- a/packages/driver-node/src/registry.ts
+++ b/packages/driver-node/src/registry.ts
@@ -1,4 +1,10 @@
-import type { Digest, Need, ProducerRef, TypeRef } from "@svml/protocol";
+import type {
+ CapabilityRef,
+ Digest,
+ Need,
+ ProducerRef,
+ TypeRef,
+} from "@svml/protocol";
import type {
ProducerHandler,
@@ -12,11 +18,24 @@ function moduleKey(ref: { readonly name: string; readonly version: string }): st
return `${ref.name}@${ref.version}`;
}
+function sameRef(
+ left: { readonly module: { readonly name: string; readonly version: string }; readonly name: string },
+ right: { readonly module: { readonly name: string; readonly version: string }; readonly name: string },
+): boolean {
+ return left.module.name === right.module.name
+ && left.module.version === right.module.version
+ && left.name === right.name;
+}
+
export function producerRegistryKey(ref: ProducerRef): string {
return `${moduleKey(ref.module)}#${ref.name}`;
}
-export function providerCapabilityKey(ref: TypeRef): string {
+export function providerCapabilityKey(ref: CapabilityRef): string {
+ return `${moduleKey(ref.module)}#${ref.name}`;
+}
+
+export function providerReturnKey(ref: TypeRef): string {
return `${moduleKey(ref.module)}#${ref.name}`;
}
@@ -38,39 +57,42 @@ export class HostRegistry {
}
}
+type ProviderOptions = { readonly supports?: (need: Need) => boolean };
+
export class ProviderRegistry {
- readonly #capabilities = new Map<string, ProviderRegistration[]>();
+ readonly #registrations: ProviderRegistration[] = [];
readonly #bindings = new Map<string, string>();
registerProvider(
id: string,
- wants: TypeRef,
+ capability: CapabilityRef,
+ returns: TypeRef,
handler: ProviderHandler,
- options: { readonly supports?: (need: Need) => boolean } = {},
+ options: ProviderOptions = {},
): void {
if (!id.trim()) throw new Error("provider id must not be empty");
- const key = providerCapabilityKey(wants);
- const registrations = this.#capabilities.get(key) ?? [];
- if (registrations.some((registration) => registration.id === id)) {
- throw new Error(`provider ${id} already registers capability ${key}`);
- }
- registrations.push({ id, wants, handler, ...options });
- this.#capabilities.set(key, registrations);
+ const duplicate = this.#registrations.some((candidate) =>
+ candidate.id === id && sameRef(candidate.capability, capability));
+ if (duplicate) throw new Error(`provider ${id} already registers ${providerCapabilityKey(capability)}`);
+ this.#registrations.push({ id, capability, returns, handler, ...options });
}
- bind(wants: TypeRef, providerId: string): void {
- const key = providerCapabilityKey(wants);
- if (!(this.#capabilities.get(key) ?? []).some((registration) => registration.id === providerId)) {
+ bind(capability: CapabilityRef, providerId: string): void {
+ const key = providerCapabilityKey(capability);
+ if (!this.#registrations.some((registration) =>
+ registration.id === providerId && sameRef(registration.capability, capability))) {
throw new Error(`provider ${providerId} does not register capability ${key}`);
}
this.#bindings.set(key, providerId);
}
resolve(need: Need): ProviderResolution {
- const key = providerCapabilityKey(need.wants);
+ const key = providerCapabilityKey(need.capability);
const bound = this.#bindings.get(key);
- const registrations = (this.#capabilities.get(key) ?? [])
- .filter((registration) => registration.supports?.(need) ?? true);
+ const registrations = this.#registrations.filter((registration) =>
+ sameRef(registration.capability, need.capability)
+ && sameRef(registration.returns, need.returns)
+ && (registration.supports?.(need) ?? true));
if (bound !== undefined) {
const registration = registrations.find((candidate) => candidate.id === bound);
return registration === undefined
@@ -87,7 +109,7 @@ export class ProviderRegistry {
return { status: "resolved", registration: registrations[0]! };
}
- providers(wants: TypeRef): readonly ProviderRegistration[] {
- return [...(this.#capabilities.get(providerCapabilityKey(wants)) ?? [])];
+ providers(capability: CapabilityRef): readonly ProviderRegistration[] {
+ return this.#registrations.filter((registration) => sameRef(registration.capability, capability));
}
}
diff --git a/packages/driver-node/src/types.ts b/packages/driver-node/src/types.ts
index 63d89bfe..0b64f117 100644
--- a/packages/driver-node/src/types.ts
+++ b/packages/driver-node/src/types.ts
@@ -12,6 +12,7 @@ import type {
ProducerRef,
StoredValue,
TypeRef,
+ CapabilityRef,
TypedRecord,
} from "@svml/protocol";
@@ -87,7 +88,8 @@ export type ProducerRegistration = {
export type ProviderRegistration = {
readonly id: string;
- readonly wants: TypeRef;
+ readonly capability: CapabilityRef;
+ readonly returns: TypeRef;
readonly handler: ProviderHandler;
readonly supports?: (need: Need) => boolean;
};
diff --git a/packages/driver-node/test/driver.test.ts b/packages/driver-node/test/driver.test.ts
index 4b705540..c254c6a5 100644
--- a/packages/driver-node/test/driver.test.ts
+++ b/packages/driver-node/test/driver.test.ts
@@ -16,6 +16,7 @@ import {
} from "@svml/driver-node";
import {
+ capabilities,
createGreetingBuild,
implementationDigests,
manifest,
@@ -97,7 +98,7 @@ test("Driver pauses at an unbound Need, serializes, then resumes without rerunni
assert.deepEqual(calls, { prompt: 1, request: 1, assemble: 0, fulfill: 0 });
const restored = parseBuildState(serializeBuildState(paused.state));
- providers.registerProvider("example:generation", types.generated, ({ need }) => {
+ providers.registerProvider("example:generation", capabilities.generation, types.generated, ({ need }) => {
calls.fulfill += 1;
assert.deepEqual(need.constraints, { prompt: "Greet Ada" });
return {
@@ -118,13 +119,13 @@ test("Driver pauses at an unbound Need, serializes, then resumes without rerunni
test("Provider Registry rejects ambiguity until the Runtime binds one provider", async () => {
const { registry, providers } = configuredRegistry();
- providers.registerProvider("example:alpha", types.generated, () => ({
+ providers.registerProvider("example:alpha", capabilities.generation, types.generated, () => ({
value: { kind: "inline", value: "Alpha" },
conformance: "exact",
delivery: "executed",
metadata: {},
}));
- providers.registerProvider("example:beta", types.generated, () => ({
+ providers.registerProvider("example:beta", capabilities.generation, types.generated, () => ({
value: { kind: "inline", value: "Beta" },
conformance: "exact",
delivery: "executed",
@@ -137,7 +138,7 @@ test("Provider Registry rejects ambiguity until the Runtime binds one provider",
assert.equal(ambiguous.blocked[0]?.reason, "ambiguous-provider");
assert.match(ambiguous.blocked[0]?.subject ?? "", /example:alpha, example:beta/u);
- providers.bind(types.generated, "example:beta");
+ providers.bind(capabilities.generation, "example:beta");
const completed = await driver.run(ambiguous.state);
assert.equal(completed.status, "complete");
assert.equal(completed.state.receipts[0]?.fulfiller, "example:beta");
@@ -149,10 +150,10 @@ test("Provider Registry rejects ambiguity until the Runtime binds one provider",
test("Provider capabilities may narrow themselves with typed Need constraints", async () => {
const { registry, providers } = configuredRegistry();
- providers.registerProvider("example:wrong-model", types.generated, () => {
+ providers.registerProvider("example:wrong-model", capabilities.generation, types.generated, () => {
throw new Error("unsupported provider must never run");
}, { supports: () => false });
- providers.registerProvider("example:compatible", types.generated, () => ({
+ providers.registerProvider("example:compatible", capabilities.generation, types.generated, () => ({
value: { kind: "inline", value: "Compatible" },
conformance: "exact",
delivery: "executed",
@@ -169,19 +170,68 @@ test("Provider capabilities may narrow themselves with typed Need constraints",
assert.equal(completed.state.receipts[0]?.fulfiller, "example:compatible");
});
+test("the same return Type cannot impersonate another exact capability", async () => {
+ const { registry, providers } = configuredRegistry();
+ let calls = 0;
+ providers.registerProvider(
+ "example:wrong-capability",
+ { module: capabilities.generation.module, name: "different-text-operation" },
+ types.generated,
+ () => {
+ calls += 1;
+ return {
+ value: { kind: "inline", value: "must not run" },
+ conformance: "exact",
+ delivery: "executed",
+ metadata: {},
+ };
+ },
+ );
+ const result = await new NodeDriver({ registry, providers }).run(createGreetingBuild());
+ assert.equal(result.status, "paused");
+ assert.equal(result.blocked[0]?.reason, "missing-provider");
+ assert.equal(calls, 0);
+});
+
+test("a substitute Candidate is explicitly selected by BuildRequest, never by Provider return Type", async () => {
+ const { registry, providers } = configuredRegistry();
+ registry.registerProducer(
+ producers.placeholderText,
+ implementationDigests.placeholderText,
+ () => ({
+ outputs: { generated: { kind: "inline", value: "Compatible placeholder" } },
+ needs: {},
+ }),
+ );
+
+ const exact = await new NodeDriver({ registry, providers }).run(createGreetingBuild());
+ assert.equal(exact.status, "paused");
+ assert.equal(exact.blocked[0]?.reason, "missing-provider");
+ assert.throws(
+ () => createGreetingBuild({ generationRealization: "placeholder" }),
+ /selects a substitute path/u,
+ );
+
+ const accepted = await new NodeDriver({ registry, providers }).run(
+ createGreetingBuild({ generationRealization: "placeholder", goalAccepts: "substitute" }),
+ );
+ assert.equal(accepted.status, "complete");
+ assert.equal(accepted.state.receipts.length, 0, "an Alternative Producer is not disguised as a Provider receipt");
+ assert.equal(accepted.state.records.find((record) => record.id === "generated:placeholder")?.conformance, "substitute");
+});
+
test("substitute conformance propagates through later producer outputs", async () => {
const { registry, providers } = configuredRegistry();
- providers.registerProvider("example:placeholder", types.generated, () => ({
- value: { kind: "inline", value: "Placeholder" },
- conformance: "substitute",
- delivery: "provided",
- metadata: { reason: "preview" },
- }));
+ registry.registerProducer(
+ producers.placeholderText,
+ implementationDigests.placeholderText,
+ () => ({ outputs: { generated: { kind: "inline", value: "Placeholder" } }, needs: {} }),
+ );
const result = await new NodeDriver({ registry, providers }).run(
- createGreetingBuild({ needAccepts: "substitute", goalAccepts: "substitute" }),
+ createGreetingBuild({ generationRealization: "placeholder", goalAccepts: "substitute" }),
);
assert.equal(result.status, "complete");
- assert.equal(result.state.receipts[0]?.conformance, "substitute");
+ assert.equal(result.state.records.find((record) => record.id === "generated:placeholder")?.conformance, "substitute");
assert.equal(result.state.records.find((record) => record.id === "document:root")?.conformance, "substitute");
});
@@ -242,7 +292,7 @@ test("Driver reads static manifests without executing package code", async () =>
test("Core still owns scheduling when Driver has every implementation", async () => {
const { registry, providers } = configuredRegistry();
- providers.registerProvider("example:cache", types.generated, () => ({
+ providers.registerProvider("example:cache", capabilities.generation, types.generated, () => ({
value: { kind: "inline", value: "Hello, Ada!" },
conformance: "exact",
delivery: "cache",
@@ -257,7 +307,7 @@ test("Core still owns scheduling when Driver has every implementation", async ()
test("receipt metadata is covered by its identity during resume validation", async () => {
const { registry, providers } = configuredRegistry();
- providers.registerProvider("example:cache", types.generated, () => ({
+ providers.registerProvider("example:cache", capabilities.generation, types.generated, () => ({
value: { kind: "inline", value: "Hello, Ada!" },
conformance: "exact",
delivery: "cache",
@@ -274,7 +324,7 @@ test("receipt metadata is covered by its identity during resume validation", asy
test("derived output content is bound to the Derivation even if its Record digest is recomputed", async () => {
const { registry, providers } = configuredRegistry();
- providers.registerProvider("example:cache", types.generated, () => ({
+ providers.registerProvider("example:cache", capabilities.generation, types.generated, () => ({
value: { kind: "inline", value: "Hello, Ada!" },
conformance: "exact",
delivery: "cache",
@@ -289,7 +339,7 @@ test("derived output content is bound to the Derivation even if its Record diges
(document as { digest: string }).digest = recordDigest(document.type, document.value);
assert.throws(
() => parseBuildState(JSON.stringify(tampered)),
- /is not an output|digest differs/u,
+ /is not an output|digest differs|does not match/u,
);
});
@@ -308,7 +358,7 @@ test("resume discards serialized Commands and regenerates the exact request befo
const restored = parseBuildState(JSON.stringify(serialized));
assert.deepEqual(restored.outstanding, []);
- providers.registerProvider("example:generation", types.generated, ({ need }) => {
+ providers.registerProvider("example:generation", capabilities.generation, types.generated, ({ need }) => {
assert.deepEqual(need.constraints, { prompt: "Greet Ada" });
return {
value: { kind: "inline", value: "Hello, Ada!" },
@@ -324,7 +374,7 @@ test("resume discards serialized Commands and regenerates the exact request befo
test("a transient Handler failure pauses and can resume without replaying completed producers", async () => {
const { registry, providers, calls } = configuredRegistry();
let attempts = 0;
- providers.registerProvider("example:unstable", types.generated, () => {
+ providers.registerProvider("example:unstable", capabilities.generation, types.generated, () => {
calls.fulfill += 1;
attempts += 1;
if (attempts === 1) throw new Error("temporary outage");
diff --git a/packages/driver-node/test/video-pipeline-fixture.ts b/packages/driver-node/test/video-pipeline-fixture.ts
deleted file mode 100644
index f59ab935..00000000
--- a/packages/driver-node/test/video-pipeline-fixture.ts
+++ /dev/null
@@ -1,203 +0,0 @@
-import { captionManifest, captionProducers } from "@svml/caption";
-import {
- contractTypes,
- contractsManifest,
- contractsManifestDigest,
- contractsModuleRef,
-} from "@svml/contracts";
-import {
- createResolvedClosure,
- digestOf,
- link,
- sealRecord,
- sealTypedModule,
- start,
-} from "@svml/core";
-import type {
- BuildPlan,
- BuildState,
- ModuleManifest,
- ProducerRef,
- TypeRef,
- ValueSchema,
-} from "@svml/protocol";
-import { narrativeValue, parseScript } from "@svml/script";
-import { speechAlignManifest, speechAlignProducers } from "@svml/speech-align";
-import {
- whisperXManifest,
- whisperXProducers,
- whisperXTypes,
-} from "@svml/whisperx";
-
-export const videoModule = { name: "example.video-pipeline", version: "0.0.0" } as const;
-
-export const videoTypes = {
- estimate: { module: videoModule, name: "OfficialSpeechDurationEstimate" },
- seedanceMiniMedia: { module: videoModule, name: "SeedanceMiniSpeechMedia" },
-} satisfies Record<string, TypeRef>;
-
-export const videoProducers = {
- requestEstimate: { module: videoModule, name: "request-official-speech-estimate" },
- requestSeedanceMini: { module: videoModule, name: "request-seedance-mini-speech" },
- assembleBasis: { module: videoModule, name: "assemble-speech-basis" },
-} satisfies Record<string, ProducerRef>;
-
-export const videoImplementations = Object.fromEntries(
- Object.entries(videoProducers).map(([name]) => [name, digestOf(`example.video-pipeline/${name}@1`)]),
-) as Readonly<Record<keyof typeof videoProducers, ReturnType<typeof digestOf>>>;
-
-const string = { kind: "string", minLength: 1 } as const;
-const number = { kind: "number", minimum: 0 } as const;
-const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema }>>): ValueSchema => ({
- kind: "object",
- fields,
-});
-
-export const videoManifest: ModuleManifest = {
- format: "svml.module@0",
- name: videoModule.name,
- version: videoModule.version,
- dependencies: [{ module: contractsModuleRef, digest: contractsManifestDigest }],
- types: [
- { name: videoTypes.estimate.name, schema: object({ durationSec: { schema: number } }) },
- {
- name: videoTypes.seedanceMiniMedia.name,
- schema: object({
- model: { schema: { kind: "literal", value: "mini" } },
- audioDigest: { schema: string },
- visualDigest: { schema: string },
- durationSec: { schema: number },
- }),
- },
- ],
- surfaces: [],
- producers: [
- {
- name: videoProducers.requestEstimate.name,
- inputs: [{ name: "narrative", type: contractTypes.narrative }],
- outputs: [],
- needs: [{ name: "estimate", wants: videoTypes.estimate }],
- implementation: {
- kind: "registered",
- locator: "example.video-pipeline/request-estimate",
- digest: videoImplementations.requestEstimate,
- },
- },
- {
- name: videoProducers.requestSeedanceMini.name,
- inputs: [
- { name: "narrative", type: contractTypes.narrative },
- { name: "estimate", type: videoTypes.estimate },
- ],
- outputs: [],
- needs: [{ name: "media", wants: videoTypes.seedanceMiniMedia }],
- implementation: {
- kind: "registered",
- locator: "example.video-pipeline/request-seedance-mini",
- digest: videoImplementations.requestSeedanceMini,
- },
- },
- {
- name: videoProducers.assembleBasis.name,
- inputs: [{ name: "media", type: videoTypes.seedanceMiniMedia }],
- outputs: [{ name: "basis", type: contractTypes.speechBasis }],
- needs: [],
- implementation: {
- kind: "registered",
- locator: "example.video-pipeline/assemble-basis",
- digest: videoImplementations.assembleBasis,
- },
- },
- ],
-};
-
-export const videoPlan: BuildPlan = {
- format: "svml.plan@0",
- id: "explicit-whisperx-video-pipeline",
- steps: [
- {
- id: "request-estimate",
- producer: videoProducers.requestEstimate,
- inputs: { narrative: "narrative:root" },
- outputs: {},
- needs: { estimate: { id: "need:estimate", result: "estimate:root", accepts: "exact" } },
- },
- {
- id: "request-seedance-mini",
- producer: videoProducers.requestSeedanceMini,
- inputs: { narrative: "narrative:root", estimate: "estimate:root" },
- outputs: {},
- needs: { media: { id: "need:seedance-mini", result: "seedance-media:root", accepts: "exact" } },
- },
- {
- id: "assemble-basis",
- producer: videoProducers.assembleBasis,
- inputs: { media: "seedance-media:root" },
- outputs: { basis: "basis:root" },
- needs: {},
- },
- {
- id: "request-whisperx",
- producer: whisperXProducers.request,
- inputs: { basis: "basis:root" },
- outputs: {},
- needs: { alignment: { id: "need:whisperx", result: "whisperx:root", accepts: "exact" } },
- },
- {
- id: "normalize-whisperx",
- producer: whisperXProducers.normalize,
- inputs: { whisperx: "whisperx:root" },
- outputs: { evidence: "evidence:root" },
- needs: {},
- },
- {
- id: "locate-speech",
- producer: speechAlignProducers.locate,
- inputs: { narrative: "narrative:root", basis: "basis:root", evidence: "evidence:root" },
- outputs: { map: "speech-map:root" },
- needs: {},
- },
- {
- id: "temporalize-caption",
- producer: captionProducers.temporalize,
- inputs: { narrative: "narrative:root", map: "speech-map:root" },
- outputs: { caption: "caption:root" },
- needs: {},
- },
- ],
- goals: [{ record: "caption:root", type: contractTypes.timedCaptionProjection, accepts: "exact" }],
-};
-
-export const videoClosure = createResolvedClosure([
- contractsManifest,
- videoManifest,
- whisperXManifest,
- speechAlignManifest,
- captionManifest,
-]);
-
-export function createVideoBuild(): BuildState {
- const parsed = parseScript(
- "pipeline.svml",
- "<line><that was insane | what the fuck></line>",
- );
- const narrative = sealRecord({
- id: "narrative:root",
- type: contractTypes.narrative,
- value: { kind: "inline", value: narrativeValue(parsed) },
- conformance: "exact",
- origin: {
- kind: "authored",
- sourceDigest: digestOf("source:video-pipeline"),
- frontendClosureDigest: digestOf("frontend:script"),
- sourceName: "pipeline.svml",
- },
- });
- return start(link(videoClosure, [sealTypedModule({
- id: "author:video-pipeline",
- closureDigest: videoClosure.digest,
- records: [narrative],
- })]), videoPlan);
-}
-
-export { contractTypes, whisperXTypes };
diff --git a/packages/driver-node/test/video-pipeline.test.ts b/packages/driver-node/test/video-pipeline.test.ts
deleted file mode 100644
index d639f324..00000000
--- a/packages/driver-node/test/video-pipeline.test.ts
+++ /dev/null
@@ -1,350 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-
-import { temporalizeCaption } from "@svml/caption";
-import {
- sealProgramSpace,
- sealSpeechBasis,
-} from "@svml/contracts";
-import type {
- AlignedTranscriptEvidence,
- CompleteSemanticMap,
- Narrative,
- SpeechBasis,
- TimedCaptionProjection,
-} from "@svml/contracts";
-import { digestOf, start } from "@svml/core";
-import {
- HostRegistry,
- NodeDriver,
- ProviderRegistry,
- parseBuildState,
- serializeBuildState,
-} from "@svml/driver-node";
-import { locateSpeechTiming } from "@svml/speech-align";
-import {
- normalizeWhisperXAlignment,
- sealWhisperXAlignmentEvidence,
- whisperXImplementationDigests,
- whisperXProducers,
- whisperXRequestForBasis,
-} from "@svml/whisperx";
-import type { WhisperXAlignmentEvidence } from "@svml/whisperx";
-
-import {
- contractTypes,
- createVideoBuild,
- videoImplementations,
- videoProducers,
- videoTypes,
- whisperXTypes,
-} from "./video-pipeline-fixture.js";
-import { captionImplementationDigest, captionProducers } from "@svml/caption";
-import { speechAlignProducers, speechLocatorDigest } from "@svml/speech-align";
-
-function inlineObject(value: unknown): Readonly<Record<string, unknown>> {
- if (value === null || Array.isArray(value) || typeof value !== "object") throw new Error("expected object");
- return value as Readonly<Record<string, unknown>>;
-}
-
-function inlineValue<T>(value: unknown): T {
- return value as T;
-}
-
-test("external methods are fixed by the BuildPlan while Runtime binds only exact execution endpoints", async () => {
- const host = new HostRegistry();
- const providers = new ProviderRegistry();
- const calls = {
- estimate: 0,
- seedance: 0,
- assemble: 0,
- whisperRequest: 0,
- whisperNormalize: 0,
- locate: 0,
- caption: 0,
- };
-
- host.registerProducer(videoProducers.requestEstimate, videoImplementations.requestEstimate, ({ inputs }) => {
- calls.estimate += 1;
- assert.equal(inputs.narrative?.value.kind, "inline");
- const narrative = inlineValue<Narrative>(inputs.narrative.value.value);
- return {
- outputs: {},
- needs: {
- estimate: {
- contract: "example.official-speech-estimate-request@1",
- speech: narrative.serializations.speech,
- },
- },
- };
- });
- host.registerProducer(videoProducers.requestSeedanceMini, videoImplementations.requestSeedanceMini, ({ inputs }) => {
- calls.seedance += 1;
- assert.equal(inputs.narrative?.value.kind, "inline");
- assert.equal(inputs.estimate?.value.kind, "inline");
- const narrative = inlineValue<Narrative>(inputs.narrative.value.value);
- const estimate = inlineObject(inputs.estimate.value.value);
- return {
- outputs: {},
- needs: {
- media: {
- contract: "example.seedance-mini-speech-request@1",
- model: "mini",
- script: narrative.serializations.speech,
- durationSec: estimate.durationSec as number,
- },
- },
- };
- });
- host.registerProducer(videoProducers.assembleBasis, videoImplementations.assembleBasis, ({ inputs }) => {
- calls.assemble += 1;
- assert.equal(inputs.media?.value.kind, "inline");
- const media = inlineObject(inputs.media.value.value);
- const durationSec = media.durationSec as number;
- const programSpace = sealProgramSpace({
- contract: "svml.program-space@0",
- durationSec,
- frameRate: { numerator: 1_000, denominator: 1 },
- });
- const audioDigest = media.audioDigest as SpeechBasis["audio"]["digest"];
- const visualDigest = media.visualDigest as SpeechBasis["audio"]["digest"];
- const basis = sealSpeechBasis({
- contract: "svml.speech-basis@1",
- programSpace,
- audio: { digest: audioDigest, size: 1, mediaType: "audio/wav", durationSec },
- visualTrack: { clips: [{
- segmentId: "line",
- artifact: { digest: visualDigest, size: 1, mediaType: "video/mp4", durationSec },
- startSec: 0,
- endSec: durationSec,
- }] },
- segments: [{ segmentId: "line", startSec: 0, endSec: durationSec, sourceArtifactDigest: visualDigest }],
- });
- return { outputs: { basis: { kind: "inline", value: basis } }, needs: {} };
- });
- host.registerProducer(whisperXProducers.request, whisperXImplementationDigests.request, ({ inputs }) => {
- calls.whisperRequest += 1;
- assert.equal(inputs.basis?.value.kind, "inline");
- return {
- outputs: {},
- needs: { alignment: whisperXRequestForBasis(inlineValue<SpeechBasis>(inputs.basis.value.value), { language: "en" }) },
- };
- });
- host.registerProducer(whisperXProducers.normalize, whisperXImplementationDigests.normalize, ({ inputs }) => {
- calls.whisperNormalize += 1;
- assert.equal(inputs.whisperx?.value.kind, "inline");
- const evidence = normalizeWhisperXAlignment(
- inlineValue<WhisperXAlignmentEvidence>(inputs.whisperx.value.value),
- );
- return { outputs: { evidence: { kind: "inline", value: evidence } }, needs: {} };
- });
- host.registerProducer(speechAlignProducers.locate, speechLocatorDigest, ({ inputs }) => {
- calls.locate += 1;
- assert.equal(inputs.narrative?.value.kind, "inline");
- assert.equal(inputs.basis?.value.kind, "inline");
- assert.equal(inputs.evidence?.value.kind, "inline");
- const map = locateSpeechTiming(
- inlineValue<Narrative>(inputs.narrative.value.value),
- inlineValue<SpeechBasis>(inputs.basis.value.value),
- inlineValue<AlignedTranscriptEvidence>(inputs.evidence.value.value),
- );
- return { outputs: { map: { kind: "inline", value: map } }, needs: {} };
- });
- host.registerProducer(captionProducers.temporalize, captionImplementationDigest, ({ inputs }) => {
- calls.caption += 1;
- assert.equal(inputs.narrative?.value.kind, "inline");
- assert.equal(inputs.map?.value.kind, "inline");
- const caption = temporalizeCaption(
- inlineValue<Narrative>(inputs.narrative.value.value),
- inlineValue<CompleteSemanticMap>(inputs.map.value.value),
- );
- return { outputs: { caption: { kind: "inline", value: caption } }, needs: {} };
- });
-
- const driver = new NodeDriver({ registry: host, providers });
- const atEstimate = await driver.run(createVideoBuild());
- assert.equal(atEstimate.blocked[0]?.reason, "missing-provider");
- assert.match(atEstimate.blocked[0]?.subject ?? "", /OfficialSpeechDurationEstimate/u);
-
- providers.registerProvider("runtime:official-estimate", videoTypes.estimate, () => ({
- value: { kind: "inline", value: { durationSec: 1 } },
- conformance: "exact",
- delivery: "executed",
- metadata: {},
- }));
- const atSeedance = await driver.run(parseBuildState(serializeBuildState(atEstimate.state)));
- assert.equal(atSeedance.blocked[0]?.reason, "missing-provider");
- assert.match(atSeedance.blocked[0]?.subject ?? "", /SeedanceMiniSpeechMedia/u);
-
- providers.registerProvider("runtime:kie-seedance-mini", videoTypes.seedanceMiniMedia, ({ need }) => {
- assert.deepEqual(need.constraints, {
- contract: "example.seedance-mini-speech-request@1",
- durationSec: 1,
- model: "mini",
- script: "what the fuck",
- });
- return {
- value: { kind: "inline", value: {
- model: "mini",
- audioDigest: digestOf("artifact:audio"),
- visualDigest: digestOf("artifact:visual"),
- durationSec: 1,
- } },
- conformance: "exact",
- delivery: "executed",
- metadata: { provider: "kie", model: "seedance-mini" },
- };
- });
- // A generic Evidence provider cannot satisfy the explicit WhisperX Need.
- providers.registerProvider("runtime:generic-stt", contractTypes.alignedTranscriptEvidence, () => {
- throw new Error("generic STT must never run for an explicit WhisperX Need");
- });
- const atWhisperX = await driver.run(parseBuildState(serializeBuildState(atSeedance.state)));
- assert.equal(atWhisperX.blocked[0]?.reason, "missing-provider");
- assert.match(atWhisperX.blocked[0]?.subject ?? "", /WhisperXAlignmentEvidence/u);
-
- providers.registerProvider("runtime:whisperx-local", whisperXTypes.alignmentEvidence, ({ need }) => {
- const request = inlineObject(need.constraints);
- const audio = inlineObject(request.audio);
- return {
- value: {
- kind: "inline",
- value: sealWhisperXAlignmentEvidence({
- contract: "svml.whisperx-alignment-evidence@1",
- engine: "whisperx",
- basisDigest: request.basisDigest as WhisperXAlignmentEvidence["basisDigest"],
- audioArtifactDigest: audio.digest as WhisperXAlignmentEvidence["audioArtifactDigest"],
- programSpaceDigest: request.programSpaceDigest as WhisperXAlignmentEvidence["programSpaceDigest"],
- rawEvidenceArtifactDigest: digestOf("artifact:whisperx-json"),
- durationSec: 1,
- segments: [{
- sourceSegmentId: "line",
- startSec: 0,
- endSec: 1,
- words: [
- { text: "what", startSec: 0.1, endSec: 0.25, score: 0.98 },
- { text: "the", startSec: 0.3, endSec: 0.42, score: 0.98 },
- { text: "fuck", startSec: 0.48, endSec: 0.72, score: 0.97 },
- ],
- chars: [],
- }],
- }),
- },
- conformance: "exact",
- delivery: "executed",
- metadata: { adapter: "whisperx.local", model: "fixture" },
- };
- });
- const completed = await driver.run(parseBuildState(serializeBuildState(atWhisperX.state)));
-
- assert.equal(completed.status, "complete");
- assert.deepEqual(calls, {
- estimate: 1,
- seedance: 1,
- assemble: 1,
- whisperRequest: 1,
- whisperNormalize: 1,
- locate: 1,
- caption: 1,
- });
- assert.deepEqual(completed.state.receipts.map((receipt) => receipt.fulfiller), [
- "runtime:official-estimate",
- "runtime:kie-seedance-mini",
- "runtime:whisperx-local",
- ]);
- const caption = completed.state.records.find((record) => record.id === "caption:root");
- assert.equal(caption?.value.kind, "inline");
- const value = inlineValue<TimedCaptionProjection>(caption?.value.kind === "inline" ? caption.value.value : {});
- assert.deepEqual(
- [value.text, value.regions[0]?.display, value.regions[0]?.startSec, value.regions[0]?.endSec],
- ["that was insane", "that was insane", 0.1, 0.72],
- );
-});
-
-test("an exact Provider result cannot wash a substitute input back to exact", async () => {
- const initial = createVideoBuild();
- const plan = {
- ...initial.plan,
- steps: initial.plan.steps.map((step) => {
- if (step.id === "request-estimate") {
- return { ...step, needs: { estimate: { ...step.needs.estimate!, accepts: "substitute" as const } } };
- }
- if (step.id === "request-seedance-mini") {
- return { ...step, needs: { media: { ...step.needs.media!, accepts: "substitute" as const } } };
- }
- return step;
- }),
- goals: initial.plan.goals.map((goal) => ({ ...goal, accepts: "substitute" as const })),
- };
- const host = new HostRegistry();
- host.registerProducer(videoProducers.requestEstimate, videoImplementations.requestEstimate, () => ({
- outputs: {},
- needs: { estimate: { speech: "what the fuck" } },
- }));
- host.registerProducer(videoProducers.requestSeedanceMini, videoImplementations.requestSeedanceMini, () => ({
- outputs: {},
- needs: { media: { model: "mini" } },
- }));
- const providers = new ProviderRegistry();
- providers.registerProvider("runtime:estimated-duration", videoTypes.estimate, () => ({
- value: { kind: "inline", value: { durationSec: 1 } },
- conformance: "substitute",
- delivery: "provided",
- metadata: {},
- }));
- providers.registerProvider("runtime:exact-seedance", videoTypes.seedanceMiniMedia, () => ({
- value: { kind: "inline", value: {
- model: "mini",
- audioDigest: digestOf("floor:audio"),
- visualDigest: digestOf("floor:visual"),
- durationSec: 1,
- } },
- conformance: "exact",
- delivery: "executed",
- metadata: {},
- }));
-
- const result = await new NodeDriver({ registry: host, providers }).run(start(initial.program, plan));
- assert.equal(result.status, "paused", "the unregistered Basis assembler should pause the test after both Needs");
- const seedanceNeed = result.state.needs.find((need) => need.id === "need:seedance-mini");
- const seedanceReceipt = result.state.receipts.find((receipt) => receipt.need === "need:seedance-mini");
- const media = result.state.records.find((record) => record.id === "seedance-media:root");
- assert.equal(seedanceNeed?.conformanceFloor, "substitute");
- assert.equal(seedanceReceipt?.fulfillmentConformance, "exact");
- assert.equal(seedanceReceipt?.conformance, "substitute");
- assert.equal(media?.conformance, "substitute");
-});
-
-test("Core rejects an impossible exact downstream Need before an expensive Provider can run", async () => {
- const initial = createVideoBuild();
- const plan = {
- ...initial.plan,
- steps: initial.plan.steps.map((step) => step.id === "request-estimate"
- ? { ...step, needs: { estimate: { ...step.needs.estimate!, accepts: "substitute" as const } } }
- : step),
- };
- const host = new HostRegistry();
- host.registerProducer(videoProducers.requestEstimate, videoImplementations.requestEstimate, () => ({
- outputs: {}, needs: { estimate: { speech: "what the fuck" } },
- }));
- host.registerProducer(videoProducers.requestSeedanceMini, videoImplementations.requestSeedanceMini, () => ({
- outputs: {}, needs: { media: { model: "mini" } },
- }));
- const providers = new ProviderRegistry();
- providers.registerProvider("runtime:estimated-duration", videoTypes.estimate, () => ({
- value: { kind: "inline", value: { durationSec: 1 } },
- conformance: "substitute",
- delivery: "provided",
- metadata: {},
- }));
- let expensiveCalls = 0;
- providers.registerProvider("runtime:paid-seedance", videoTypes.seedanceMiniMedia, () => {
- expensiveCalls += 1;
- throw new Error("must not run");
- });
-
- const result = await new NodeDriver({ registry: host, providers }).run(start(initial.program, plan));
- assert.equal(result.status, "failed");
- assert.equal(result.state.diagnostics.at(-1)?.code, "CONFORMANCE_FLOOR_UNSATISFIABLE");
- assert.equal(expensiveCalls, 0);
-});
diff --git a/packages/elaborator/README.md b/packages/elaborator/README.md
new file mode 100644
index 00000000..95a5ede8
--- /dev/null
+++ b/packages/elaborator/README.md
@@ -0,0 +1,13 @@
+# `@svml/elaborator`
+
+Static Graph Fragment elaboration outside SVML Core.
+
+A `svml.fragment@1` value may reference only declared Fragment inputs and local Operations. It
+contains no JavaScript callback, ambient file lookup, credential access or Runtime endpoint. Before
+expansion the Elaborator verifies producer ports, types, cycles, reachable exports, Semantic Input
+Envelopes and affinity sources.
+
+Expansion assigns hygienic identities from `fragment digest + author instance id + local id`.
+Multiple exports of one instance therefore share internal Operations, while two explicit instances
+are never content-deduplicated. The result is ordinary `LogicalOutput`, `Candidate` and
+`OperationNode` data that Core validates again.
diff --git a/packages/elaborator/package.json b/packages/elaborator/package.json
new file mode 100644
index 00000000..4efab3be
--- /dev/null
+++ b/packages/elaborator/package.json
@@ -0,0 +1,17 @@
+{
+ "name": "@svml/elaborator",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "dependencies": {
+ "@svml/core": "workspace:*",
+ "@svml/protocol": "workspace:*"
+ },
+ "devDependencies": {
+ "@svml/contracts": "workspace:*",
+ "@svml/speech-take": "workspace:*"
+ }
+}
diff --git a/packages/elaborator/src/fragment.ts b/packages/elaborator/src/fragment.ts
new file mode 100644
index 00000000..dae7235b
--- /dev/null
+++ b/packages/elaborator/src/fragment.ts
@@ -0,0 +1,563 @@
+import {
+ canonicalStringify,
+ digestOf,
+ isDigest,
+ resolveProducer,
+} from "@svml/core";
+import type {
+ AffinityConstraint,
+ Candidate,
+ CandidateRoot,
+ CompiledGraph,
+ Conformance,
+ Digest,
+ GraphValueRef,
+ LinkedProgram,
+ LogicalOutput,
+ OperationNode,
+ ProducerRef,
+ TypeRef,
+} from "@svml/protocol";
+
+export type FragmentInputRef = {
+ readonly kind: "fragment-input";
+ readonly name: string;
+};
+
+export type FragmentOperationRef = {
+ readonly kind: "fragment-operation";
+ readonly operation: string;
+};
+
+export type FragmentValueRef = FragmentInputRef | FragmentOperationRef;
+
+export type FragmentOperationResult =
+ | { readonly kind: "output"; readonly name: string }
+ | {
+ readonly kind: "need";
+ readonly name: string;
+ readonly accepts: "exact" | "substitute";
+ };
+
+export type FragmentOperation = {
+ readonly id: string;
+ readonly producer: ProducerRef;
+ readonly inputs: Readonly<Record<string, FragmentValueRef>>;
+ readonly result: FragmentOperationResult;
+};
+
+export type FragmentAffinityConstraint = {
+ readonly resultPointer: string;
+ readonly source: FragmentValueRef;
+ readonly sourcePointer: string;
+};
+
+export type FragmentExport = {
+ readonly name: string;
+ readonly type: TypeRef;
+ readonly root: FragmentOperationRef;
+ readonly semanticInputs: readonly string[];
+ readonly affinity?: readonly FragmentAffinityConstraint[];
+ readonly fidelity: Conformance;
+};
+
+export type GraphFragment = {
+ readonly format: "svml.fragment@1";
+ readonly id: Digest;
+ readonly name: string;
+ readonly inputs: readonly { readonly name: string; readonly type: TypeRef }[];
+ readonly operations: readonly FragmentOperation[];
+ readonly exports: readonly FragmentExport[];
+};
+
+export type FragmentInstanceRequest = {
+ /** Stable author instance identity, not a content-deduplication key. */
+ readonly id: string;
+ readonly fragment: Digest;
+ readonly inputs: Readonly<Record<string, GraphValueRef>>;
+};
+
+export type ElaboratedFragmentExport = {
+ readonly name: string;
+ readonly type: TypeRef;
+ readonly root: CandidateRoot;
+ readonly semanticInputs: readonly GraphValueRef[];
+ readonly affinity?: readonly AffinityConstraint[];
+ readonly fidelity: Conformance;
+};
+
+export type ElaboratedFragment = {
+ readonly format: "svml.fragment-instance@1";
+ readonly id: Digest;
+ readonly fragment: Digest;
+ readonly instance: string;
+ readonly inputs: Readonly<Record<string, GraphValueRef>>;
+ readonly operations: readonly OperationNode[];
+ readonly exports: readonly ElaboratedFragmentExport[];
+};
+
+export type FragmentContribution = {
+ readonly outputs: readonly LogicalOutput[];
+ readonly candidates: readonly Candidate[];
+ readonly operations: readonly OperationNode[];
+};
+
+export class FragmentError extends Error {
+ readonly code: string;
+ readonly subject: string | undefined;
+
+ constructor(code: string, message: string, subject?: string) {
+ super(message);
+ this.name = "FragmentError";
+ this.code = code;
+ this.subject = subject;
+ }
+}
+
+function assert(condition: unknown, code: string, message: string, subject?: string): asserts condition {
+ if (!condition) throw new FragmentError(code, message, subject);
+}
+
+function sameType(left: TypeRef, right: TypeRef): boolean {
+ return left.module.name === right.module.name
+ && left.module.version === right.module.version
+ && left.name === right.name;
+}
+
+function typeName(type: TypeRef): string {
+ return `${type.module.name}@${type.module.version}#${type.name}`;
+}
+
+function exactKeys(
+ actual: Readonly<Record<string, unknown>>,
+ expected: readonly string[],
+ subject: string,
+): void {
+ const left = Object.keys(actual).sort();
+ const right = [...expected].sort();
+ assert(
+ JSON.stringify(left) === JSON.stringify(right),
+ "FRAGMENT_PORT_BINDING_MISMATCH",
+ `${subject} binds [${left.join(", ")}] but declares [${right.join(", ")}]`,
+ subject,
+ );
+}
+
+function normalizeFragmentRef(ref: FragmentValueRef): FragmentValueRef {
+ if (ref.kind === "fragment-input") return { kind: "fragment-input", name: ref.name };
+ assert(
+ ref.kind === "fragment-operation",
+ "INVALID_FRAGMENT_REFERENCE",
+ "Fragment references must name a declared input or local Operation",
+ );
+ return { kind: "fragment-operation", operation: ref.operation };
+}
+
+function fragmentRefKey(ref: FragmentValueRef): string {
+ return ref.kind === "fragment-input" ? `input\u0000${ref.name}` : `operation\u0000${ref.operation}`;
+}
+
+function normalizeOperation(operation: FragmentOperation): FragmentOperation {
+ return {
+ id: operation.id,
+ producer: operation.producer,
+ inputs: Object.fromEntries(
+ Object.entries(operation.inputs)
+ .sort(([left], [right]) => left.localeCompare(right))
+ .map(([name, ref]) => [name, normalizeFragmentRef(ref)]),
+ ),
+ result: operation.result.kind === "output"
+ ? { kind: "output", name: operation.result.name }
+ : {
+ kind: "need",
+ name: operation.result.name,
+ accepts: operation.result.accepts,
+ },
+ };
+}
+
+function normalizeExport(item: FragmentExport): FragmentExport {
+ const base = {
+ name: item.name,
+ type: item.type,
+ root: normalizeFragmentRef(item.root) as FragmentOperationRef,
+ semanticInputs: [...item.semanticInputs].sort(),
+ fidelity: item.fidelity,
+ };
+ return item.affinity === undefined
+ ? base
+ : {
+ ...base,
+ affinity: [...item.affinity]
+ .map((constraint) => ({
+ resultPointer: constraint.resultPointer,
+ source: normalizeFragmentRef(constraint.source),
+ sourcePointer: constraint.sourcePointer,
+ }))
+ .sort((left, right) => left.resultPointer.localeCompare(right.resultPointer)),
+ };
+}
+
+function fragmentContent(fragment: GraphFragment): Omit<GraphFragment, "id"> {
+ return {
+ format: "svml.fragment@1",
+ name: fragment.name,
+ inputs: [...fragment.inputs]
+ .map((input) => ({ name: input.name, type: input.type }))
+ .sort((left, right) => left.name.localeCompare(right.name)),
+ operations: [...fragment.operations].map(normalizeOperation).sort((left, right) => left.id.localeCompare(right.id)),
+ exports: [...fragment.exports].map(normalizeExport).sort((left, right) => left.name.localeCompare(right.name)),
+ };
+}
+
+export function sealGraphFragment(
+ fragment: Omit<GraphFragment, "format" | "id">,
+): GraphFragment {
+ const draft = { format: "svml.fragment@1" as const, id: digestOf("unsealed-fragment"), ...fragment };
+ const content = fragmentContent(draft);
+ return { ...content, id: digestOf(content) };
+}
+
+function resultType(program: LinkedProgram, operation: FragmentOperation): TypeRef {
+ const producer = resolveProducer(program.closure, operation.producer);
+ if (operation.result.kind === "output") {
+ const output = producer.outputs.find((port) => port.name === operation.result.name);
+ assert(
+ output !== undefined && producer.needs.length === 0,
+ "FRAGMENT_RESULT_MISMATCH",
+ `${operation.id} does not produce output ${operation.result.name}`,
+ operation.id,
+ );
+ return output.type;
+ }
+ const need = producer.needs.find((port) => port.name === operation.result.name);
+ assert(
+ need !== undefined && producer.outputs.length === 0,
+ "FRAGMENT_RESULT_MISMATCH",
+ `${operation.id} does not request Need ${operation.result.name}`,
+ operation.id,
+ );
+ return need.returns;
+}
+
+export function verifyGraphFragment(program: LinkedProgram, fragment: GraphFragment): void {
+ assert(fragment.format === "svml.fragment@1", "UNSUPPORTED_FRAGMENT", "unsupported Graph Fragment format");
+ assert(isDigest(fragment.id), "INVALID_FRAGMENT_DIGEST", "Graph Fragment id is not a digest");
+ assert(fragment.id === digestOf(fragmentContent(fragment)), "FRAGMENT_DIGEST_MISMATCH", "Graph Fragment digest differs");
+ assert(fragment.name.length > 0, "EMPTY_FRAGMENT_NAME", "Graph Fragment name is empty");
+ assert(fragment.exports.length > 0, "EMPTY_FRAGMENT_EXPORTS", `${fragment.name} has no exports`);
+
+ const inputs = new Map<string, TypeRef>();
+ for (const input of fragment.inputs) {
+ assert(input.name.length > 0, "EMPTY_FRAGMENT_INPUT", `${fragment.name} has an empty input name`);
+ assert(!inputs.has(input.name), "DUPLICATE_FRAGMENT_INPUT", `${fragment.name} repeats input ${input.name}`);
+ inputs.set(input.name, input.type);
+ }
+
+ const operations = new Map<string, FragmentOperation>();
+ for (const operation of fragment.operations) {
+ assert(operation.id.length > 0, "EMPTY_FRAGMENT_OPERATION", `${fragment.name} has an empty Operation id`);
+ assert(!operations.has(operation.id), "DUPLICATE_FRAGMENT_OPERATION", `${fragment.name} repeats ${operation.id}`);
+ operations.set(operation.id, operation);
+ const producer = resolveProducer(program.closure, operation.producer);
+ exactKeys(operation.inputs, producer.inputs.map((port) => port.name), `${fragment.name}.${operation.id}`);
+ if (operation.result.kind === "need") {
+ assert(
+ operation.result.accepts === "exact" || operation.result.accepts === "substitute",
+ "INVALID_FRAGMENT_NEED_ACCEPTANCE",
+ `${operation.id} has invalid Need acceptance`,
+ );
+ }
+ }
+
+ const visiting = new Set<string>();
+ const visited = new Set<string>();
+ const operationType = (id: string): TypeRef => {
+ const operation = operations.get(id);
+ assert(operation !== undefined, "UNKNOWN_FRAGMENT_OPERATION", `${fragment.name} references ${id}`, id);
+ if (visited.has(id)) return resultType(program, operation);
+ assert(!visiting.has(id), "FRAGMENT_CYCLE", `${fragment.name} cycles through ${id}`, id);
+ visiting.add(id);
+ const producer = resolveProducer(program.closure, operation.producer);
+ for (const port of producer.inputs) {
+ const ref = operation.inputs[port.name];
+ assert(ref !== undefined, "FRAGMENT_PORT_BINDING_MISMATCH", `${operation.id}.${port.name} is unbound`);
+ const supplied = ref.kind === "fragment-input"
+ ? inputs.get(ref.name)
+ : operationType(ref.operation);
+ assert(supplied !== undefined, "UNKNOWN_FRAGMENT_INPUT", `${fragment.name} references input ${ref.kind === "fragment-input" ? ref.name : ref.operation}`);
+ assert(
+ sameType(supplied, port.type),
+ "FRAGMENT_INPUT_TYPE_MISMATCH",
+ `${operation.id}.${port.name} wants ${typeName(port.type)} but receives ${typeName(supplied)}`,
+ operation.id,
+ );
+ }
+ visiting.delete(id);
+ visited.add(id);
+ return resultType(program, operation);
+ };
+
+ const exports = new Set<string>();
+ const reachableOperations = new Set<string>();
+ const collectDependencies = (ref: FragmentValueRef, keys: Set<string>, seen: Set<string>): void => {
+ keys.add(fragmentRefKey(ref));
+ if (ref.kind === "fragment-input" || seen.has(ref.operation)) return;
+ seen.add(ref.operation);
+ reachableOperations.add(ref.operation);
+ const operation = operations.get(ref.operation);
+ assert(operation !== undefined, "UNKNOWN_FRAGMENT_OPERATION", `${fragment.name} references ${ref.operation}`);
+ Object.values(operation.inputs).forEach((input) => collectDependencies(input, keys, seen));
+ };
+
+ for (const item of fragment.exports) {
+ assert(item.name.length > 0, "EMPTY_FRAGMENT_EXPORT", `${fragment.name} has an empty export name`);
+ assert(!exports.has(item.name), "DUPLICATE_FRAGMENT_EXPORT", `${fragment.name} repeats export ${item.name}`);
+ exports.add(item.name);
+ assert(
+ item.root.kind === "fragment-operation",
+ "INVALID_FRAGMENT_EXPORT_ROOT",
+ `${fragment.name}.${item.name} must export a local Operation result`,
+ );
+ const supplied = operationType(item.root.operation);
+ assert(
+ sameType(supplied, item.type),
+ "FRAGMENT_EXPORT_TYPE_MISMATCH",
+ `${fragment.name}.${item.name} declares ${typeName(item.type)} but returns ${typeName(supplied)}`,
+ );
+ assert(
+ item.fidelity === "exact" || item.fidelity === "substitute",
+ "INVALID_FRAGMENT_FIDELITY",
+ `${fragment.name}.${item.name} has invalid fidelity`,
+ );
+ const envelope = new Set<string>();
+ for (const input of item.semanticInputs) {
+ assert(inputs.has(input), "UNKNOWN_FRAGMENT_INPUT", `${fragment.name}.${item.name} exposes unknown input ${input}`);
+ assert(!envelope.has(input), "DUPLICATE_FRAGMENT_SEMANTIC_INPUT", `${fragment.name}.${item.name} repeats ${input}`);
+ envelope.add(input);
+ }
+ const dependencies = new Set<string>();
+ collectDependencies(item.root, dependencies, new Set());
+ for (const key of dependencies) {
+ if (!key.startsWith("input\u0000")) continue;
+ const input = key.slice("input\u0000".length);
+ assert(
+ envelope.has(input),
+ "FRAGMENT_EXCEEDS_SEMANTIC_ENVELOPE",
+ `${fragment.name}.${item.name} captures undeclared input ${input}`,
+ item.name,
+ );
+ }
+ for (const constraint of item.affinity ?? []) {
+ assert(
+ dependencies.has(fragmentRefKey(constraint.source)),
+ "FRAGMENT_AFFINITY_NOT_DEMANDED",
+ `${fragment.name}.${item.name} affinity source is outside its demanded closure`,
+ item.name,
+ );
+ }
+ }
+ for (const id of operations.keys()) {
+ assert(
+ reachableOperations.has(id),
+ "UNREACHABLE_FRAGMENT_OPERATION",
+ `${fragment.name}.${id} contributes to no export`,
+ id,
+ );
+ }
+}
+
+function normalizeGraphRef(ref: GraphValueRef): GraphValueRef {
+ if (ref.kind === "record") return { kind: "record", id: ref.id };
+ if (ref.kind === "logical-output") return { kind: "logical-output", id: ref.id };
+ assert(
+ ref.kind === "operation-result",
+ "INVALID_FRAGMENT_BINDING",
+ "Fragment inputs must bind to a Graph Value reference",
+ );
+ return { kind: "operation-result", operation: ref.operation };
+}
+
+function hygienicId(kind: string, fragment: Digest, instance: string, local: string): string {
+ return `${kind}:${digestOf({ fragment, instance, local }).slice("sha256:".length)}`;
+}
+
+export function elaborateGraphFragment(
+ program: LinkedProgram,
+ fragment: GraphFragment,
+ request: FragmentInstanceRequest,
+): ElaboratedFragment {
+ verifyGraphFragment(program, fragment);
+ assert(request.id.length > 0, "EMPTY_FRAGMENT_INSTANCE", "Fragment instance id is empty");
+ assert(request.fragment === fragment.id, "FRAGMENT_INSTANCE_MISMATCH", `${request.id} locks another Fragment`);
+ exactKeys(request.inputs, fragment.inputs.map((input) => input.name), request.id);
+ const inputs = Object.fromEntries(
+ Object.entries(request.inputs)
+ .sort(([left], [right]) => left.localeCompare(right))
+ .map(([name, ref]) => [name, normalizeGraphRef(ref)]),
+ );
+ const operationIds = new Map(fragment.operations.map((operation) => [
+ operation.id,
+ hygienicId("operation", fragment.id, request.id, operation.id),
+ ]));
+ const mapRef = (ref: FragmentValueRef): GraphValueRef => {
+ if (ref.kind === "fragment-input") {
+ const bound = inputs[ref.name];
+ assert(bound !== undefined, "UNKNOWN_FRAGMENT_INPUT", `${request.id} does not bind ${ref.name}`);
+ return bound;
+ }
+ const operation = operationIds.get(ref.operation);
+ assert(operation !== undefined, "UNKNOWN_FRAGMENT_OPERATION", `${fragment.name} references ${ref.operation}`);
+ return { kind: "operation-result", operation };
+ };
+ const operations: OperationNode[] = fragment.operations.map((operation) => {
+ const id = operationIds.get(operation.id) as string;
+ const record = hygienicId("record", fragment.id, request.id, operation.id);
+ return {
+ id,
+ producer: operation.producer,
+ inputs: Object.fromEntries(Object.entries(operation.inputs).map(([name, ref]) => [name, mapRef(ref)])),
+ result: operation.result.kind === "output"
+ ? { kind: "output", name: operation.result.name, record }
+ : {
+ kind: "need",
+ name: operation.result.name,
+ id: hygienicId("need", fragment.id, request.id, operation.id),
+ record,
+ accepts: operation.result.accepts,
+ },
+ };
+ });
+ const exports: ElaboratedFragmentExport[] = fragment.exports.map((item) => {
+ const root = mapRef(item.root);
+ assert(root.kind === "operation-result", "INVALID_FRAGMENT_EXPORT_ROOT", item.name);
+ const base = {
+ name: item.name,
+ type: item.type,
+ root: { kind: "operation" as const, result: root },
+ semanticInputs: item.semanticInputs.map((name) => inputs[name] as GraphValueRef),
+ fidelity: item.fidelity,
+ };
+ return item.affinity === undefined
+ ? base
+ : {
+ ...base,
+ affinity: item.affinity.map((constraint) => ({
+ resultPointer: constraint.resultPointer,
+ source: mapRef(constraint.source),
+ sourcePointer: constraint.sourcePointer,
+ })),
+ };
+ });
+ const content = {
+ format: "svml.fragment-instance@1" as const,
+ fragment: fragment.id,
+ instance: request.id,
+ inputs,
+ operations,
+ exports,
+ };
+ return { ...content, id: digestOf(content) };
+}
+
+function exportMap(instance: ElaboratedFragment): Map<string, ElaboratedFragmentExport> {
+ return new Map(instance.exports.map((item) => [item.name, item]));
+}
+
+function reachableOperationIds(
+ instance: ElaboratedFragment,
+ selected: readonly ElaboratedFragmentExport[],
+): Set<string> {
+ const operations = new Map(instance.operations.map((operation) => [operation.id, operation]));
+ const reachable = new Set<string>();
+ const visit = (id: string): void => {
+ if (reachable.has(id)) return;
+ reachable.add(id);
+ const operation = operations.get(id);
+ assert(operation !== undefined, "UNKNOWN_ELABORATED_OPERATION", `${instance.instance} references ${id}`);
+ for (const ref of Object.values(operation.inputs)) {
+ if (ref.kind === "operation-result") visit(ref.operation);
+ }
+ };
+ for (const item of selected) {
+ assert(item.root.kind === "operation", "INVALID_FRAGMENT_EXPORT_ROOT", item.name);
+ visit(item.root.result.operation);
+ }
+ return reachable;
+}
+
+function bindExports(
+ instance: ElaboratedFragment,
+ bindings: Readonly<Record<string, string>>,
+ requireAll: boolean,
+): FragmentContribution {
+ const available = exportMap(instance);
+ if (requireAll) exactKeys(bindings, instance.exports.map((item) => item.name), instance.instance);
+ assert(Object.keys(bindings).length > 0, "EMPTY_FRAGMENT_BINDING", `${instance.instance} binds no exports`);
+ const selected = Object.keys(bindings).map((name) => {
+ const item = available.get(name);
+ assert(item !== undefined, "UNKNOWN_FRAGMENT_EXPORT", `${instance.instance} has no export ${name}`);
+ return item;
+ });
+ const candidates: Candidate[] = selected.map((item) => {
+ const output = bindings[item.name] as string;
+ assert(output.length > 0, "EMPTY_LOGICAL_OUTPUT_ID", `${instance.instance}.${item.name} output is empty`);
+ return {
+ id: hygienicId("candidate", instance.fragment, instance.instance, `${item.name}\u0000${output}`),
+ output,
+ root: item.root,
+ fidelity: item.fidelity,
+ };
+ });
+ const outputs: LogicalOutput[] = requireAll
+ ? selected.map((item, index) => ({
+ id: bindings[item.name] as string,
+ type: item.type,
+ primary: candidates[index]!.id,
+ candidates: [candidates[index]!.id],
+ semanticInputs: item.semanticInputs,
+ ...(item.affinity === undefined ? {} : { affinity: item.affinity }),
+ }))
+ : [];
+ const reachable = reachableOperationIds(instance, selected);
+ return {
+ outputs,
+ candidates,
+ operations: instance.operations.filter((operation) => reachable.has(operation.id)),
+ };
+}
+
+/** Bind all Fragment exports as new author-visible Logical Outputs. */
+export function bindAuthorFragment(
+ instance: ElaboratedFragment,
+ outputs: Readonly<Record<string, string>>,
+): FragmentContribution {
+ return bindExports(instance, outputs, true);
+}
+
+/** Bind selected Fragment exports as Candidate attachments for existing Logical Outputs. */
+export function bindCandidateFragment(
+ instance: ElaboratedFragment,
+ outputs: Readonly<Record<string, string>>,
+): FragmentContribution {
+ return bindExports(instance, outputs, false);
+}
+
+/** Merge already elaborated contributions; final Graph validation remains Core's authority. */
+export function mergeFragmentContributions(
+ graph: Pick<CompiledGraph, "outputs" | "candidates" | "operations">,
+ ...contributions: readonly FragmentContribution[]
+): Pick<CompiledGraph, "outputs" | "candidates" | "operations"> {
+ return {
+ outputs: [...graph.outputs, ...contributions.flatMap((item) => item.outputs)],
+ candidates: [...graph.candidates, ...contributions.flatMap((item) => item.candidates)],
+ operations: [...graph.operations, ...contributions.flatMap((item) => item.operations)],
+ };
+}
+
+export function sameFragmentInstance(
+ left: ElaboratedFragment,
+ right: ElaboratedFragment,
+): boolean {
+ return canonicalStringify(left) === canonicalStringify(right);
+}
diff --git a/packages/elaborator/src/index.ts b/packages/elaborator/src/index.ts
new file mode 100644
index 00000000..7c26e888
--- /dev/null
+++ b/packages/elaborator/src/index.ts
@@ -0,0 +1,24 @@
+export {
+ bindAuthorFragment,
+ bindCandidateFragment,
+ elaborateGraphFragment,
+ FragmentError,
+ mergeFragmentContributions,
+ sameFragmentInstance,
+ sealGraphFragment,
+ verifyGraphFragment,
+} from "./fragment.js";
+export type {
+ ElaboratedFragment,
+ ElaboratedFragmentExport,
+ FragmentAffinityConstraint,
+ FragmentContribution,
+ FragmentExport,
+ FragmentInputRef,
+ FragmentInstanceRequest,
+ FragmentOperation,
+ FragmentOperationRef,
+ FragmentOperationResult,
+ FragmentValueRef,
+ GraphFragment,
+} from "./fragment.js";
diff --git a/packages/elaborator/test/fragment.test.ts b/packages/elaborator/test/fragment.test.ts
new file mode 100644
index 00000000..0d1166c2
--- /dev/null
+++ b/packages/elaborator/test/fragment.test.ts
@@ -0,0 +1,296 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ contractTypes,
+ contractsManifest,
+ contractsManifestDigest,
+ contractsModuleRef,
+} from "@svml/contracts";
+import {
+ createResolvedClosure,
+ digestOf,
+ link,
+ sealBuildRequest,
+ sealCompiledGraph,
+ sealRecord,
+ sealTypedModule,
+ start,
+} from "@svml/core";
+import {
+ bindAuthorFragment,
+ elaborateGraphFragment,
+ mergeFragmentContributions,
+ sameFragmentInstance,
+ sealGraphFragment,
+ verifyGraphFragment,
+} from "@svml/elaborator";
+import type {
+ FragmentContribution,
+ GraphFragment,
+} from "@svml/elaborator";
+import type {
+ CompiledGraph,
+ LinkedProgram,
+ ModuleManifest,
+ ProducerRef,
+ TypeRef,
+} from "@svml/protocol";
+import {
+ speechTakeManifest,
+ speechTakeProducers,
+} from "@svml/speech-take";
+
+const testModule = { name: "example.fragment-speech", version: "0.0.0" } as const;
+const requestType = { module: testModule, name: "Request" } satisfies TypeRef;
+const generateProducer = { module: testModule, name: "generate" } satisfies ProducerRef;
+
+const manifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: testModule.name,
+ version: testModule.version,
+ dependencies: [{ module: contractsModuleRef, digest: contractsManifestDigest }],
+ types: [{ name: requestType.name, schema: { kind: "string", minLength: 1 } }],
+ capabilities: [],
+ surfaces: [],
+ producers: [{
+ name: generateProducer.name,
+ inputs: [
+ { name: "request", type: requestType },
+ { name: "style", type: requestType },
+ ],
+ outputs: [{ name: "take", type: contractTypes.speechBasis }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.fragment-speech/generate",
+ digest: digestOf("example.fragment-speech/generate@1"),
+ },
+ }],
+};
+
+const closure = createResolvedClosure([contractsManifest, speechTakeManifest, manifest]);
+
+function program(): LinkedProgram {
+ const origin = {
+ kind: "authored" as const,
+ sourceDigest: digestOf("source:fragment"),
+ frontendClosureDigest: digestOf("frontend:fragment"),
+ };
+ return link(closure, [sealTypedModule({
+ id: "author:fragment",
+ closureDigest: closure.digest,
+ records: [
+ sealRecord({
+ id: "request:root",
+ type: requestType,
+ value: { kind: "inline", value: "Say hello." },
+ conformance: "exact",
+ origin,
+ }),
+ sealRecord({
+ id: "style:root",
+ type: requestType,
+ value: { kind: "inline", value: "Direct to camera." },
+ conformance: "exact",
+ origin,
+ }),
+ ],
+ })]);
+}
+
+function speechFragment(): GraphFragment {
+ const input = (name: string) => ({ kind: "fragment-input" as const, name });
+ const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+ return sealGraphFragment({
+ name: "official-speech-take",
+ inputs: [
+ { name: "request", type: requestType },
+ { name: "style", type: requestType },
+ ],
+ operations: [
+ {
+ id: "generate",
+ producer: generateProducer,
+ inputs: { request: input("request"), style: input("style") },
+ result: { kind: "output", name: "take" },
+ },
+ {
+ id: "audio",
+ producer: speechTakeProducers.projectAudio,
+ inputs: { basis: operation("generate") },
+ result: { kind: "output", name: "audio" },
+ },
+ {
+ id: "visual",
+ producer: speechTakeProducers.projectVisual,
+ inputs: { basis: operation("generate") },
+ result: { kind: "output", name: "visual" },
+ },
+ ],
+ exports: [
+ {
+ name: "take",
+ type: contractTypes.speechBasis,
+ root: operation("generate"),
+ semanticInputs: ["request", "style"],
+ fidelity: "exact",
+ },
+ {
+ name: "audio",
+ type: contractTypes.speechAudioBasis,
+ root: operation("audio"),
+ semanticInputs: ["request", "style"],
+ affinity: [{
+ resultPointer: "/basisDigest",
+ source: operation("generate"),
+ sourcePointer: "/basisDigest",
+ }],
+ fidelity: "exact",
+ },
+ {
+ name: "visual",
+ type: contractTypes.speechVisualTrack,
+ root: operation("visual"),
+ semanticInputs: ["request", "style"],
+ affinity: [{
+ resultPointer: "/basisDigest",
+ source: operation("generate"),
+ sourcePointer: "/basisDigest",
+ }],
+ fidelity: "exact",
+ },
+ ],
+ });
+}
+
+function instance(programValue: LinkedProgram, id: string) {
+ const fragment = speechFragment();
+ return elaborateGraphFragment(programValue, fragment, {
+ id,
+ fragment: fragment.id,
+ inputs: {
+ request: { kind: "record", id: "request:root" },
+ style: { kind: "record", id: "style:root" },
+ },
+ });
+}
+
+function graph(programValue: LinkedProgram, ...contributions: readonly FragmentContribution[]): CompiledGraph {
+ const merged = mergeFragmentContributions(
+ { outputs: [], candidates: [], operations: [] },
+ ...contributions,
+ );
+ return sealCompiledGraph({ program: programValue.semanticDigest, ...merged });
+}
+
+test("one FragmentInstance shares its generation Operation across all exports", () => {
+ const linked = program();
+ const elaborated = instance(linked, "opening");
+ const contribution = bindAuthorFragment(elaborated, {
+ take: "opening.take",
+ audio: "opening.audio",
+ visual: "opening.visual",
+ });
+ const compiled = graph(linked, contribution);
+ const request = sealBuildRequest({
+ graph: compiled.id,
+ targets: [
+ { output: "opening.audio", accepts: "exact" },
+ { output: "opening.visual", accepts: "exact" },
+ ],
+ bindings: [],
+ });
+ const state = start(linked, compiled, request);
+ assert.equal(
+ state.plan.steps.filter((step) => step.producer.name === generateProducer.name).length,
+ 1,
+ );
+ assert.equal(state.plan.steps.length, 3);
+ const takeRecord = contribution.operations.find((item) => item.producer.name === "generate")?.result.record;
+ assert.equal(
+ state.plan.steps.find((step) => step.producer.name === "project-audio")?.inputs.basis,
+ takeRecord,
+ );
+ assert.equal(
+ state.plan.steps.find((step) => step.producer.name === "project-visual")?.inputs.basis,
+ takeRecord,
+ );
+});
+
+test("the same Fragment instance is deterministic while distinct instances never content-dedupe", () => {
+ const linked = program();
+ const opening = instance(linked, "opening");
+ const openingAgain = instance(linked, "opening");
+ const closing = instance(linked, "closing");
+ assert.equal(sameFragmentInstance(opening, openingAgain), true);
+ assert.notEqual(opening.id, closing.id);
+ assert.equal(
+ new Set([...opening.operations, ...closing.operations].map((operation) => operation.id)).size,
+ 6,
+ );
+
+ const compiled = graph(
+ linked,
+ bindAuthorFragment(opening, {
+ take: "opening.take",
+ audio: "opening.audio",
+ visual: "opening.visual",
+ }),
+ bindAuthorFragment(closing, {
+ take: "closing.take",
+ audio: "closing.audio",
+ visual: "closing.visual",
+ }),
+ );
+ const state = start(linked, compiled, sealBuildRequest({
+ graph: compiled.id,
+ targets: [
+ { output: "opening.audio", accepts: "exact" },
+ { output: "closing.audio", accepts: "exact" },
+ ],
+ bindings: [],
+ }));
+ assert.equal(
+ state.plan.steps.filter((step) => step.producer.name === generateProducer.name).length,
+ 2,
+ );
+});
+
+test("a Fragment cannot capture an undeclared semantic input", () => {
+ const linked = program();
+ const valid = speechFragment();
+ const invalid = sealGraphFragment({
+ name: valid.name,
+ inputs: valid.inputs,
+ operations: valid.operations,
+ exports: valid.exports.map((item) => item.name === "take"
+ ? { ...item, semanticInputs: ["request"] }
+ : item),
+ });
+ assert.throws(
+ () => verifyGraphFragment(linked, invalid),
+ /captures undeclared input style/u,
+ );
+});
+
+test("Fragment references cannot escape through a raw Graph reference", () => {
+ const valid = speechFragment();
+ assert.throws(
+ () => sealGraphFragment({
+ name: valid.name,
+ inputs: valid.inputs,
+ operations: valid.operations.map((item) => item.id === "generate"
+ ? {
+ ...item,
+ inputs: {
+ ...item.inputs,
+ request: { kind: "record", id: "secret:ambient" } as never,
+ },
+ }
+ : item),
+ exports: valid.exports,
+ }),
+ /must name a declared input or local Operation/u,
+ );
+});
diff --git a/packages/protocol/src/build.ts b/packages/protocol/src/build.ts
index e715ac31..20ef2186 100644
--- a/packages/protocol/src/build.ts
+++ b/packages/protocol/src/build.ts
@@ -1,9 +1,13 @@
import type {
+ CandidateId,
CommandId,
+ CapabilityRef,
DerivationId,
Digest,
EventId,
+ LogicalOutputId,
NeedId,
+ OperationId,
ProducerRef,
ReceiptId,
RecordId,
@@ -39,7 +43,14 @@ export type ObservedOrigin = {
readonly receipt: ReceiptId;
};
-export type RecordOrigin = AuthoredOrigin | DerivedOrigin | ObservedOrigin;
+export type ProvidedOrigin = {
+ readonly kind: "provided";
+ readonly candidate: CandidateId;
+ readonly requestDigest: Digest;
+ readonly provenance?: CanonicalValue;
+};
+
+export type RecordOrigin = AuthoredOrigin | DerivedOrigin | ObservedOrigin | ProvidedOrigin;
export type TypedRecord = {
readonly id: RecordId;
@@ -62,7 +73,8 @@ export type NeedAcceptance = "exact" | "substitute";
export type Need = {
readonly id: NeedId;
- readonly wants: TypeRef;
+ readonly capability: CapabilityRef;
+ readonly returns: TypeRef;
readonly constraints: CanonicalValue;
readonly requestedBy: DerivationId;
readonly result: RecordId;
@@ -121,9 +133,120 @@ export type NeedBinding = {
readonly accepts: NeedAcceptance;
};
+export type RecordRef = {
+ readonly kind: "record";
+ readonly id: RecordId;
+};
+
+export type LogicalOutputRef = {
+ readonly kind: "logical-output";
+ readonly id: LogicalOutputId;
+};
+
+export type OperationResultRef = {
+ readonly kind: "operation-result";
+ readonly operation: OperationId;
+};
+
+export type GraphValueRef = RecordRef | LogicalOutputRef | OperationResultRef;
+
+/** A domain-neutral equality claim between a logical result and one source fact. */
+export type AffinityConstraint = {
+ readonly resultPointer: string;
+ readonly source: GraphValueRef;
+ readonly sourcePointer: string;
+};
+
+export type LogicalOutput = {
+ readonly id: LogicalOutputId;
+ readonly type: TypeRef;
+ readonly primary: CandidateId;
+ readonly candidates: readonly CandidateId[];
+ /** Author-visible facts that a Candidate may transitively depend upon. */
+ readonly semanticInputs: readonly GraphValueRef[];
+ readonly affinity?: readonly AffinityConstraint[];
+};
+
+export type OperationResult =
+ | {
+ readonly kind: "output";
+ readonly name: string;
+ readonly record: RecordId;
+ }
+ | {
+ readonly kind: "need";
+ readonly name: string;
+ readonly id: NeedId;
+ readonly record: RecordId;
+ readonly accepts: NeedAcceptance;
+ };
+
+export type OperationNode = {
+ readonly id: OperationId;
+ readonly producer: ProducerRef;
+ readonly inputs: Readonly<Record<string, GraphValueRef>>;
+ readonly result: OperationResult;
+};
+
+export type ProvidedValue = {
+ readonly id: RecordId;
+ readonly value: StoredValue;
+ readonly provenance?: CanonicalValue;
+};
+
+export type CandidateRoot =
+ | { readonly kind: "value"; readonly value: ProvidedValue }
+ | { readonly kind: "operation"; readonly result: OperationResultRef };
+
+export type Candidate = {
+ readonly id: CandidateId;
+ readonly output: LogicalOutputId;
+ readonly root: CandidateRoot;
+ /** Fidelity to the Logical Output promise, independent of Provider fulfillment. */
+ readonly fidelity: Conformance;
+};
+
+export type CompiledGraph = {
+ readonly format: "svml.graph@1";
+ readonly id: Digest;
+ readonly program: Digest;
+ /** Digest of the author graph before external Candidate attachment. */
+ readonly source: Digest;
+ /** Digest of the empty realization set or the locked Realization Closure. */
+ readonly realization: Digest;
+ readonly outputs: readonly LogicalOutput[];
+ readonly candidates: readonly Candidate[];
+ readonly operations: readonly OperationNode[];
+};
+
+export type BuildTarget = {
+ readonly output: LogicalOutputId;
+ readonly accepts: NeedAcceptance;
+};
+
+export type CandidateBinding = {
+ readonly output: LogicalOutputId;
+ readonly candidate: CandidateId;
+};
+
+export type BuildRequest = {
+ readonly format: "svml.build-request@1";
+ readonly graph: Digest;
+ readonly targets: readonly BuildTarget[];
+ readonly bindings: readonly CandidateBinding[];
+ readonly digest: Digest;
+};
+
+export type BuildSelection = {
+ readonly output: LogicalOutputId;
+ readonly candidate: CandidateId;
+ readonly record: RecordId;
+};
+
export type ProducerStep = {
readonly id: StepId;
readonly producer: ProducerRef;
+ readonly fidelity: Conformance;
readonly inputs: Readonly<Record<string, RecordId>>;
readonly outputs: Readonly<Record<string, RecordId>>;
readonly needs: Readonly<Record<string, NeedBinding>>;
@@ -136,10 +259,14 @@ export type BuildGoal = {
};
export type BuildPlan = {
- readonly format: "svml.plan@0";
- readonly id: string;
+ readonly format: "svml.plan@1";
+ readonly id: Digest;
+ readonly graph: Digest;
+ readonly request: Digest;
+ readonly initialValues: readonly TypedRecord[];
readonly steps: readonly ProducerStep[];
readonly goals: readonly BuildGoal[];
+ readonly selections: readonly BuildSelection[];
};
export type LinkedProgram = {
@@ -219,9 +346,11 @@ export type BuildDiagnostic = {
};
export type BuildState = {
- readonly format: "svml.build@0";
+ readonly format: "svml.build@1";
readonly id: Digest;
readonly program: LinkedProgram;
+ readonly graph: CompiledGraph;
+ readonly request: BuildRequest;
readonly plan: BuildPlan;
readonly status: "active" | "complete" | "failed";
readonly records: readonly TypedRecord[];
diff --git a/packages/protocol/src/canonical.ts b/packages/protocol/src/canonical.ts
new file mode 100644
index 00000000..e818aa83
--- /dev/null
+++ b/packages/protocol/src/canonical.ts
@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+
+import type { TypedRecord } from "./build.js";
+import { SvmlError } from "./error.js";
+import type { Digest, TypeRef } from "./identity.js";
+import type { CanonicalValue, StoredValue } from "./value.js";
+
+function normalize(value: unknown, path: string, ancestors: WeakSet<object>): CanonicalValue {
+ if (value === null || typeof value === "boolean" || typeof value === "string") return value;
+ if (typeof value === "number") {
+ if (!Number.isFinite(value)) throw new SvmlError("NON_CANONICAL_NUMBER", `${path} must be finite`);
+ return Object.is(value, -0) ? 0 : value;
+ }
+ if (Array.isArray(value)) {
+ if (ancestors.has(value)) throw new SvmlError("CYCLIC_VALUE", `${path} contains a cycle`);
+ ancestors.add(value);
+ const result = value.map((item, index) => normalize(item, `${path}[${index}]`, ancestors));
+ ancestors.delete(value);
+ return result;
+ }
+ if (typeof value === "object") {
+ const prototype = Object.getPrototypeOf(value);
+ if (prototype !== Object.prototype && prototype !== null) {
+ throw new SvmlError("NON_CANONICAL_OBJECT", `${path} must be a plain object`);
+ }
+ if (ancestors.has(value)) throw new SvmlError("CYCLIC_VALUE", `${path} contains a cycle`);
+ ancestors.add(value);
+ const result: Record<string, CanonicalValue> = {};
+ const source = value as Record<string, unknown>;
+ for (const key of Object.keys(source).sort()) {
+ const descriptor = Object.getOwnPropertyDescriptor(source, key);
+ if (descriptor === undefined || descriptor.get !== undefined || descriptor.set !== undefined) {
+ throw new SvmlError("NON_CANONICAL_ACCESSOR", `${path}.${key} must be a data property`);
+ }
+ if (descriptor.value === undefined) {
+ throw new SvmlError("NON_CANONICAL_UNDEFINED", `${path}.${key} is undefined`);
+ }
+ Object.defineProperty(result, key, {
+ value: normalize(descriptor.value, `${path}.${key}`, ancestors),
+ enumerable: true,
+ configurable: true,
+ writable: true,
+ });
+ }
+ ancestors.delete(value);
+ return result;
+ }
+ throw new SvmlError("NON_CANONICAL_VALUE", `${path} contains ${typeof value}`);
+}
+
+export function canonicalize(value: unknown): CanonicalValue {
+ return normalize(value, "$input", new WeakSet<object>());
+}
+
+export function canonicalStringify(value: unknown): string {
+ return JSON.stringify(canonicalize(value));
+}
+
+export function digestOf(value: unknown): Digest {
+ const hex = createHash("sha256").update(canonicalStringify(value), "utf8").digest("hex");
+ return `sha256:${hex}`;
+}
+
+export function isDigest(value: string): value is Digest {
+ return /^sha256:[0-9a-f]{64}$/u.test(value);
+}
+
+export function recordDigest(type: TypeRef, value: StoredValue): Digest {
+ return digestOf({ type, value });
+}
+
+export function semanticRecordsDigest(records: readonly TypedRecord[]): Digest {
+ return digestOf(
+ [...records]
+ .sort((left, right) => left.id.localeCompare(right.id))
+ .map((record) => ({
+ id: record.id,
+ type: record.type,
+ value: record.value,
+ conformance: record.conformance,
+ })),
+ );
+}
diff --git a/packages/protocol/src/error.ts b/packages/protocol/src/error.ts
new file mode 100644
index 00000000..6aff32fe
--- /dev/null
+++ b/packages/protocol/src/error.ts
@@ -0,0 +1,11 @@
+export class SvmlError extends Error {
+ readonly code: string;
+ readonly subject: string | undefined;
+
+ constructor(code: string, message: string, subject?: string) {
+ super(message);
+ this.name = "SvmlError";
+ this.code = code;
+ this.subject = subject;
+ }
+}
diff --git a/packages/protocol/src/identity.ts b/packages/protocol/src/identity.ts
index ebc9135c..1aab6208 100644
--- a/packages/protocol/src/identity.ts
+++ b/packages/protocol/src/identity.ts
@@ -1,6 +1,10 @@
export type Digest = `sha256:${string}`;
export type RecordId = string;
+export type NodeId = string;
+export type LogicalOutputId = string;
+export type CandidateId = string;
+export type OperationId = string;
export type NeedId = string;
export type StepId = string;
export type DerivationId = string;
@@ -22,3 +26,8 @@ export type ProducerRef = {
readonly module: ModuleRef;
readonly name: string;
};
+
+export type CapabilityRef = {
+ readonly module: ModuleRef;
+ readonly name: string;
+};
diff --git a/packages/protocol/src/index.ts b/packages/protocol/src/index.ts
index db68b9f7..aef16ada 100644
--- a/packages/protocol/src/index.ts
+++ b/packages/protocol/src/index.ts
@@ -1,3 +1,5 @@
+export * from "./canonical.js";
+export * from "./error.js";
export type * from "./build.js";
export type * from "./identity.js";
export type * from "./module.js";
diff --git a/packages/protocol/src/module.ts b/packages/protocol/src/module.ts
index 02495f6e..82c541cd 100644
--- a/packages/protocol/src/module.ts
+++ b/packages/protocol/src/module.ts
@@ -1,4 +1,4 @@
-import type { Digest, ModuleRef, ProducerRef, TypeRef } from "./identity.js";
+import type { CapabilityRef, Digest, ModuleRef, ProducerRef, TypeRef } from "./identity.js";
import type { ValueSchema } from "./value.js";
export type ModuleDependency = {
@@ -12,14 +12,30 @@ export type TypeDeclaration = {
readonly description?: string;
};
+/** A domain-neutral equality promise from one result field to one Producer input field. */
+export type ResultAffinityDeclaration = {
+ readonly resultPointer: string;
+ readonly input: string;
+ readonly inputPointer: string;
+};
+
export type PortDeclaration = {
readonly name: string;
readonly type: TypeRef;
+ readonly affinity?: readonly ResultAffinityDeclaration[];
};
export type NeedPortDeclaration = {
readonly name: string;
- readonly wants: TypeRef;
+ readonly capability: CapabilityRef;
+ readonly returns: TypeRef;
+ readonly affinity?: readonly ResultAffinityDeclaration[];
+};
+
+export type CapabilityDeclaration = {
+ readonly name: string;
+ readonly returns: TypeRef;
+ readonly description?: string;
};
export type ImplementationRef = {
@@ -57,6 +73,7 @@ export type ModuleManifest = {
readonly version: string;
readonly dependencies: readonly ModuleDependency[];
readonly types: readonly TypeDeclaration[];
+ readonly capabilities: readonly CapabilityDeclaration[];
readonly surfaces: readonly SurfaceDeclaration[];
readonly producers: readonly ProducerDeclaration[];
};
@@ -80,3 +97,7 @@ export type ResolvedTypeDeclaration = TypeDeclaration & {
export type ResolvedProducerDeclaration = ProducerDeclaration & {
readonly ref: ProducerRef;
};
+
+export type ResolvedCapabilityDeclaration = CapabilityDeclaration & {
+ readonly ref: CapabilityRef;
+};
diff --git a/packages/realization/README.md b/packages/realization/README.md
new file mode 100644
index 00000000..bf5a57a0
--- /dev/null
+++ b/packages/realization/README.md
@@ -0,0 +1,13 @@
+# `@svml/realization`
+
+Content-addressed Candidate attachment outside SVML Core.
+
+A `svml.realization-overlay@1` locks the exact author Graph and contributes Candidates plus any
+already elaborated Operations. `resolveRealization()` merges one or more Overlays deterministically,
+retains the author source digest, records a separate Realization Closure digest, and produces the
+final `CompiledGraph` consumed by Build Compiler.
+
+An attached Candidate is inert. It enters a finite BuildPlan only when a `BuildRequest` explicitly
+selects it and a Target reaches its Logical Output. Product UI actions such as “Pin” create or locate
+an Existing-Value Candidate and then write that ordinary selection; they do not mutate Core state or
+require a database.
diff --git a/packages/realization/package.json b/packages/realization/package.json
new file mode 100644
index 00000000..7185c327
--- /dev/null
+++ b/packages/realization/package.json
@@ -0,0 +1,16 @@
+{
+ "name": "@svml/realization",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "dependencies": {
+ "@svml/core": "workspace:*",
+ "@svml/protocol": "workspace:*"
+ },
+ "devDependencies": {
+ "@svml/elaborator": "workspace:*"
+ }
+}
diff --git a/packages/realization/src/index.ts b/packages/realization/src/index.ts
new file mode 100644
index 00000000..547a1cab
--- /dev/null
+++ b/packages/realization/src/index.ts
@@ -0,0 +1,14 @@
+export {
+ createProvidedCandidate,
+ RealizationError,
+ resolveRealization,
+ sealRealizationOverlay,
+ verifyRealizationOverlay,
+ verifyResolvedRealization,
+} from "./overlay.js";
+export type {
+ ProvidedCandidateInput,
+ RealizationClosure,
+ RealizationOverlay,
+ ResolvedRealization,
+} from "./overlay.js";
diff --git a/packages/realization/src/overlay.ts b/packages/realization/src/overlay.ts
new file mode 100644
index 00000000..90402137
--- /dev/null
+++ b/packages/realization/src/overlay.ts
@@ -0,0 +1,202 @@
+import {
+ canonicalize,
+ digestOf,
+ EMPTY_REALIZATION_DIGEST,
+ isDigest,
+ resolveLogicalOutput,
+ sealCompiledGraph,
+ verifyCompiledGraph,
+} from "@svml/core";
+import type {
+ Candidate,
+ CanonicalValue,
+ CompiledGraph,
+ Conformance,
+ Digest,
+ LinkedProgram,
+ OperationNode,
+ StoredValue,
+} from "@svml/protocol";
+
+export type RealizationOverlay = {
+ readonly format: "svml.realization-overlay@1";
+ readonly id: Digest;
+ /** Exact author graph to which these Candidates may be attached. */
+ readonly sourceGraph: Digest;
+ readonly candidates: readonly Candidate[];
+ readonly operations: readonly OperationNode[];
+};
+
+export type RealizationClosure = {
+ readonly format: "svml.realization-closure@1";
+ readonly id: Digest;
+ readonly sourceGraph: Digest;
+ readonly overlays: readonly Digest[];
+};
+
+export type ResolvedRealization = {
+ readonly closure: RealizationClosure;
+ readonly graph: CompiledGraph;
+};
+
+export type ProvidedCandidateInput = {
+ readonly output: string;
+ readonly value: StoredValue;
+ readonly fidelity: Conformance;
+ readonly record?: string;
+ readonly provenance?: CanonicalValue;
+};
+
+export class RealizationError extends Error {
+ readonly code: string;
+ readonly subject: string | undefined;
+
+ constructor(code: string, message: string, subject?: string) {
+ super(message);
+ this.name = "RealizationError";
+ this.code = code;
+ this.subject = subject;
+ }
+}
+
+function assert(condition: unknown, code: string, message: string, subject?: string): asserts condition {
+ if (!condition) throw new RealizationError(code, message, subject);
+}
+
+function overlayContent(overlay: RealizationOverlay): Omit<RealizationOverlay, "id"> {
+ return {
+ format: "svml.realization-overlay@1",
+ sourceGraph: overlay.sourceGraph,
+ candidates: [...overlay.candidates].sort((left, right) => left.id.localeCompare(right.id)),
+ operations: [...overlay.operations].sort((left, right) => left.id.localeCompare(right.id)),
+ };
+}
+
+export function sealRealizationOverlay(
+ overlay: Omit<RealizationOverlay, "format" | "id">,
+): RealizationOverlay {
+ const draft = {
+ format: "svml.realization-overlay@1" as const,
+ id: digestOf("unsealed-realization-overlay"),
+ ...overlay,
+ };
+ const content = overlayContent(draft);
+ assert(content.candidates.length > 0, "EMPTY_REALIZATION_OVERLAY", "Realization Overlay has no Candidates");
+ return { ...content, id: digestOf(content) };
+}
+
+export function createProvidedCandidate(input: ProvidedCandidateInput): Candidate {
+ assert(input.output.length > 0, "EMPTY_LOGICAL_OUTPUT_ID", "Provided Candidate output is empty");
+ assert(
+ input.fidelity === "exact" || input.fidelity === "substitute",
+ "INVALID_CONFORMANCE",
+ "Provided Candidate fidelity is invalid",
+ );
+ const value = input.value.kind === "inline"
+ ? { kind: "inline" as const, value: canonicalize(input.value.value) }
+ : { ...input.value };
+ const identity = {
+ kind: "provided-candidate@1",
+ output: input.output,
+ value,
+ fidelity: input.fidelity,
+ ...(input.provenance === undefined ? {} : { provenance: canonicalize(input.provenance) }),
+ };
+ const suffix = digestOf(identity).slice("sha256:".length);
+ return {
+ id: `candidate:${suffix}`,
+ output: input.output,
+ root: {
+ kind: "value",
+ value: {
+ id: input.record ?? `provided:${suffix}`,
+ value,
+ ...(input.provenance === undefined ? {} : { provenance: canonicalize(input.provenance) }),
+ },
+ },
+ fidelity: input.fidelity,
+ };
+}
+
+export function verifyRealizationOverlay(
+ program: LinkedProgram,
+ source: CompiledGraph,
+ overlay: RealizationOverlay,
+): void {
+ verifyCompiledGraph(program, source);
+ assert(
+ source.realization === EMPTY_REALIZATION_DIGEST,
+ "OVERLAY_REQUIRES_AUTHOR_GRAPH",
+ "Realization Overlays attach to an author graph, not an already realized graph",
+ );
+ assert(overlay.format === "svml.realization-overlay@1", "UNSUPPORTED_REALIZATION_OVERLAY", "unsupported Overlay format");
+ assert(isDigest(overlay.id), "INVALID_OVERLAY_DIGEST", "Realization Overlay id is not a digest");
+ assert(overlay.id === digestOf(overlayContent(overlay)), "OVERLAY_DIGEST_MISMATCH", "Realization Overlay digest differs");
+ assert(overlay.sourceGraph === source.id, "OVERLAY_SOURCE_MISMATCH", "Realization Overlay targets another author graph");
+ assert(overlay.candidates.length > 0, "EMPTY_REALIZATION_OVERLAY", "Realization Overlay has no Candidates");
+
+ const candidateIds = new Set(source.candidates.map((candidate) => candidate.id));
+ for (const candidate of overlay.candidates) {
+ resolveLogicalOutput(source, candidate.output);
+ assert(!candidateIds.has(candidate.id), "OVERLAY_CANDIDATE_CONFLICT", `Candidate ${candidate.id} already exists`);
+ assert(candidate.id.length > 0, "EMPTY_CANDIDATE_ID", "Overlay Candidate id is empty");
+ candidateIds.add(candidate.id);
+ }
+}
+
+function sealRealizationClosure(
+ sourceGraph: Digest,
+ overlays: readonly RealizationOverlay[],
+): RealizationClosure {
+ const content = {
+ format: "svml.realization-closure@1" as const,
+ sourceGraph,
+ overlays: overlays.map((overlay) => overlay.id).sort(),
+ };
+ return { ...content, id: digestOf(content) };
+}
+
+export function resolveRealization(
+ program: LinkedProgram,
+ source: CompiledGraph,
+ overlays: readonly RealizationOverlay[],
+): ResolvedRealization {
+ assert(overlays.length > 0, "EMPTY_REALIZATION_CLOSURE", "no Realization Overlay was supplied");
+ for (const overlay of overlays) verifyRealizationOverlay(program, source, overlay);
+ const closure = sealRealizationClosure(source.id, overlays);
+ const candidates = overlays.flatMap((overlay) => overlay.candidates);
+ const operations = overlays.flatMap((overlay) => overlay.operations);
+ const attachments = new Map<string, string[]>();
+ for (const candidate of candidates) {
+ const attached = attachments.get(candidate.output) ?? [];
+ attached.push(candidate.id);
+ attachments.set(candidate.output, attached);
+ }
+ const graph = sealCompiledGraph({
+ program: source.program,
+ source: source.source,
+ realization: closure.id,
+ outputs: source.outputs.map((output) => ({
+ ...output,
+ candidates: [...output.candidates, ...(attachments.get(output.id) ?? [])],
+ })),
+ candidates: [...source.candidates, ...candidates],
+ operations: [...source.operations, ...operations],
+ });
+ verifyCompiledGraph(program, graph);
+ return { closure, graph };
+}
+
+export function verifyResolvedRealization(
+ program: LinkedProgram,
+ source: CompiledGraph,
+ resolved: ResolvedRealization,
+ overlays: readonly RealizationOverlay[],
+): void {
+ const expected = resolveRealization(program, source, overlays);
+ assert(
+ digestOf(resolved) === digestOf(expected),
+ "REALIZATION_CLOSURE_MISMATCH",
+ "resolved Realization differs from its source graph and Overlays",
+ );
+}
diff --git a/packages/realization/test/overlay.test.ts b/packages/realization/test/overlay.test.ts
new file mode 100644
index 00000000..b8b5739d
--- /dev/null
+++ b/packages/realization/test/overlay.test.ts
@@ -0,0 +1,265 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ createResolvedClosure,
+ digestOf,
+ EMPTY_REALIZATION_DIGEST,
+ link,
+ sealBuildRequest,
+ sealCompiledGraph,
+ sealRecord,
+ sealTypedModule,
+ start,
+} from "@svml/core";
+import {
+ bindCandidateFragment,
+ elaborateGraphFragment,
+ sealGraphFragment,
+} from "@svml/elaborator";
+import type {
+ CompiledGraph,
+ LinkedProgram,
+ ModuleManifest,
+ ProducerRef,
+ TypeRef,
+} from "@svml/protocol";
+import {
+ createProvidedCandidate,
+ resolveRealization,
+ sealRealizationOverlay,
+ verifyResolvedRealization,
+} from "@svml/realization";
+
+const moduleRef = { name: "example.realization", version: "0.0.0" } as const;
+const types = {
+ prompt: { module: moduleRef, name: "Prompt" },
+ media: { module: moduleRef, name: "Media" },
+} satisfies Record<string, TypeRef>;
+const producers = {
+ generate: { module: moduleRef, name: "generate" },
+ preview: { module: moduleRef, name: "preview" },
+} satisfies Record<string, ProducerRef>;
+
+const manifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: moduleRef.name,
+ version: moduleRef.version,
+ dependencies: [],
+ types: [
+ { name: types.prompt.name, schema: { kind: "string", minLength: 1 } },
+ { name: types.media.name, schema: { kind: "string", minLength: 1 } },
+ ],
+ capabilities: [],
+ surfaces: [],
+ producers: [
+ {
+ name: producers.generate.name,
+ inputs: [{ name: "prompt", type: types.prompt }],
+ outputs: [{ name: "media", type: types.media }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.realization/generate",
+ digest: digestOf("example.realization/generate@1"),
+ },
+ },
+ {
+ name: producers.preview.name,
+ inputs: [{ name: "prompt", type: types.prompt }],
+ outputs: [{ name: "media", type: types.media }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.realization/preview",
+ digest: digestOf("example.realization/preview@1"),
+ },
+ },
+ ],
+};
+
+function fixture(): { readonly program: LinkedProgram; readonly source: CompiledGraph } {
+ const closure = createResolvedClosure([manifest]);
+ const authored = sealRecord({
+ id: "prompt:shot",
+ type: types.prompt,
+ value: { kind: "inline", value: "A founder speaking to camera." },
+ conformance: "exact",
+ origin: {
+ kind: "authored",
+ sourceDigest: digestOf("source:realization"),
+ frontendClosureDigest: digestOf("frontend:realization"),
+ },
+ });
+ const program = link(closure, [sealTypedModule({
+ id: "author:realization",
+ closureDigest: closure.digest,
+ records: [authored],
+ })]);
+ const source = sealCompiledGraph({
+ program: program.semanticDigest,
+ outputs: [{
+ id: "shot.visual",
+ type: types.media,
+ primary: "shot.generate",
+ candidates: ["shot.generate"],
+ semanticInputs: [{ kind: "record", id: "prompt:shot" }],
+ }],
+ candidates: [{
+ id: "shot.generate",
+ output: "shot.visual",
+ root: {
+ kind: "operation",
+ result: { kind: "operation-result", operation: "generate-shot" },
+ },
+ fidelity: "exact",
+ }],
+ operations: [{
+ id: "generate-shot",
+ producer: producers.generate,
+ inputs: { prompt: { kind: "record", id: "prompt:shot" } },
+ result: { kind: "output", name: "media", record: "media:generated" },
+ }],
+ });
+ return { program, source };
+}
+
+function providedOverlay(source: CompiledGraph, value: string, label: string) {
+ const candidate = createProvidedCandidate({
+ output: "shot.visual",
+ value: { kind: "inline", value },
+ fidelity: "exact",
+ provenance: { library: "approved-shots", label },
+ });
+ return {
+ candidate,
+ overlay: sealRealizationOverlay({
+ sourceGraph: source.id,
+ candidates: [candidate],
+ operations: [],
+ }),
+ };
+}
+
+test("an attached Existing Value is inert until BuildRequest explicitly selects it", () => {
+ const { program, source } = fixture();
+ const { overlay, candidate } = providedOverlay(source, "approved video", "v1");
+ const realized = resolveRealization(program, source, [overlay]);
+ assert.equal(source.realization, EMPTY_REALIZATION_DIGEST);
+ assert.equal(realized.graph.source, source.source);
+ assert.equal(realized.graph.realization, realized.closure.id);
+ assert.notEqual(realized.graph.id, source.id);
+
+ const primary = start(program, realized.graph, sealBuildRequest({
+ graph: realized.graph.id,
+ targets: [{ output: "shot.visual", accepts: "exact" }],
+ bindings: [],
+ }));
+ assert.deepEqual(primary.plan.steps.map((step) => step.id), ["generate-shot"]);
+ assert.deepEqual(primary.plan.initialValues, []);
+
+ const selected = start(program, realized.graph, sealBuildRequest({
+ graph: realized.graph.id,
+ targets: [{ output: "shot.visual", accepts: "exact" }],
+ bindings: [{ output: "shot.visual", candidate: candidate.id }],
+ }));
+ assert.deepEqual(selected.plan.steps, []);
+ assert.equal(selected.plan.initialValues[0]?.value.kind, "inline");
+ assert.equal(selected.plan.selections[0]?.candidate, candidate.id);
+});
+
+test("changing the attached Value changes Overlay, realized Graph and BuildRequest identity", () => {
+ const { program, source } = fixture();
+ const left = providedOverlay(source, "approved video A", "A");
+ const right = providedOverlay(source, "approved video B", "B");
+ const realizedLeft = resolveRealization(program, source, [left.overlay]);
+ const realizedRight = resolveRealization(program, source, [right.overlay]);
+ assert.notEqual(left.overlay.id, right.overlay.id);
+ assert.notEqual(realizedLeft.graph.id, realizedRight.graph.id);
+
+ const requestLeft = sealBuildRequest({
+ graph: realizedLeft.graph.id,
+ targets: [{ output: "shot.visual", accepts: "exact" }],
+ bindings: [{ output: "shot.visual", candidate: left.candidate.id }],
+ });
+ const requestRight = sealBuildRequest({
+ graph: realizedRight.graph.id,
+ targets: [{ output: "shot.visual", accepts: "exact" }],
+ bindings: [{ output: "shot.visual", candidate: right.candidate.id }],
+ });
+ assert.notEqual(requestLeft.digest, requestRight.digest);
+});
+
+test("Overlay order is not semantic and the resolved closure is verifiable", () => {
+ const { program, source } = fixture();
+ const left = providedOverlay(source, "approved video A", "A").overlay;
+ const right = providedOverlay(source, "approved video B", "B").overlay;
+ const forward = resolveRealization(program, source, [left, right]);
+ const reverse = resolveRealization(program, source, [right, left]);
+ assert.equal(forward.closure.id, reverse.closure.id);
+ assert.equal(forward.graph.id, reverse.graph.id);
+ verifyResolvedRealization(program, source, forward, [right, left]);
+});
+
+test("a static Fragment export can be attached as an external Candidate", () => {
+ const { program, source } = fixture();
+ const fragment = sealGraphFragment({
+ name: "black-preview",
+ inputs: [{ name: "prompt", type: types.prompt }],
+ operations: [{
+ id: "preview",
+ producer: producers.preview,
+ inputs: { prompt: { kind: "fragment-input", name: "prompt" } },
+ result: { kind: "output", name: "media" },
+ }],
+ exports: [{
+ name: "visual",
+ type: types.media,
+ root: { kind: "fragment-operation", operation: "preview" },
+ semanticInputs: ["prompt"],
+ fidelity: "substitute",
+ }],
+ });
+ const instance = elaborateGraphFragment(program, fragment, {
+ id: "shot-black-preview",
+ fragment: fragment.id,
+ inputs: { prompt: { kind: "record", id: "prompt:shot" } },
+ });
+ const contribution = bindCandidateFragment(instance, { visual: "shot.visual" });
+ const overlay = sealRealizationOverlay({
+ sourceGraph: source.id,
+ candidates: contribution.candidates,
+ operations: contribution.operations,
+ });
+ const realized = resolveRealization(program, source, [overlay]);
+ const candidate = contribution.candidates[0]!;
+ const state = start(program, realized.graph, sealBuildRequest({
+ graph: realized.graph.id,
+ targets: [{ output: "shot.visual", accepts: "substitute" }],
+ bindings: [{ output: "shot.visual", candidate: candidate.id }],
+ }));
+ assert.equal(state.plan.steps.length, 1);
+ assert.equal(state.plan.steps[0]?.producer.name, "preview");
+ assert.equal(state.plan.steps.some((step) => step.id === "generate-shot"), false);
+});
+
+test("tampered and cross-graph Overlays are rejected before Candidate selection", () => {
+ const { program, source } = fixture();
+ const { overlay } = providedOverlay(source, "approved video", "v1");
+ const tampered = {
+ ...overlay,
+ candidates: overlay.candidates.map((candidate) => ({ ...candidate, fidelity: "substitute" as const })),
+ };
+ assert.throws(() => resolveRealization(program, source, [tampered]), /Overlay digest differs/u);
+
+ const otherSource = sealCompiledGraph({
+ program: source.program,
+ outputs: source.outputs.map((output) => ({ ...output, id: "other.visual" })),
+ candidates: source.candidates.map((candidate) => ({ ...candidate, output: "other.visual" })),
+ operations: source.operations,
+ });
+ assert.throws(
+ () => resolveRealization(program, otherSource, [overlay]),
+ /targets another author graph/u,
+ );
+});
diff --git a/packages/script/src/manifest.ts b/packages/script/src/manifest.ts
index 5ca34556..b0f2d7b5 100644
--- a/packages/script/src/manifest.ts
+++ b/packages/script/src/manifest.ts
@@ -19,6 +19,7 @@ export const scriptManifest: ModuleManifest = {
version: scriptModuleRef.version,
dependencies: [{ module: contractsModuleRef, digest: contractsManifestDigest }],
types: [],
+ capabilities: [],
surfaces: [
{
name: "script",
diff --git a/packages/speech-align/README.md b/packages/speech-align/README.md
index 208cf9c6..c7804753 100644
--- a/packages/speech-align/README.md
+++ b/packages/speech-align/README.md
@@ -13,7 +13,7 @@ between their measured neighbors instead of invented point timestamps. The resul
into the selected ProgramSpace and contains one timing for every Script token and all `2M + 2N`
semantic anchors.
-The locator accepts Narrative, SpeechBasis and AlignedTranscriptEvidence together. It rejects
+The locator accepts Narrative, SpeechAudioBasis and AlignedTranscriptEvidence together. It rejects
Evidence unless its Basis, audio Artifact and ProgramSpace digests match exactly, even when another
audio file has the same duration and Segment ids.
diff --git a/packages/speech-align/src/locate.ts b/packages/speech-align/src/locate.ts
index 8be6c2ae..025387f9 100644
--- a/packages/speech-align/src/locate.ts
+++ b/packages/speech-align/src/locate.ts
@@ -7,7 +7,7 @@ import type {
Narrative,
NarrativeToken,
SemanticTimePoint,
- SpeechBasis,
+ SpeechAudioBasis,
SpeechCharacterEvidence,
SpeechWordEvidence,
TimedSpeechSegment,
@@ -17,7 +17,6 @@ import type {
import {
computeAlignedTranscriptEvidenceDigest,
computeProgramSpaceDigest,
- computeSpeechBasisDigest,
} from "@svml/contracts";
import { alignWordGroups } from "./align.js";
@@ -55,11 +54,15 @@ function validateWindow(start: number, end: number, limit: number, label: string
}
}
-function validateBasis(narrative: Narrative, basis: SpeechBasis): void {
- if (basis.contract !== "svml.speech-basis@1") fail("SPEECH_BASIS_CONTRACT", "Unsupported SpeechBasis contract.");
- const { basisDigest: _basisDigest, ...basisContent } = basis;
- if (!isDigest(basis.basisDigest) || basis.basisDigest !== computeSpeechBasisDigest(basisContent)) {
- fail("SPEECH_BASIS_DIGEST", "SpeechBasis digest does not match its canonical contents.");
+function validateBasis(narrative: Narrative, basis: SpeechAudioBasis): void {
+ if (basis.contract !== "svml.speech-audio-basis@1") {
+ fail("SPEECH_BASIS_CONTRACT", "Unsupported SpeechAudioBasis contract.");
+ }
+ if (!isDigest(basis.basisDigest) || !isDigest(basis.narrativeDigest)) {
+ fail("SPEECH_BASIS_DIGEST", "SpeechAudioBasis identity digest is invalid.");
+ }
+ if (basis.narrativeDigest !== narrative.semanticIndex.digest) {
+ fail("SPEECH_BASIS_NARRATIVE", "SpeechAudioBasis belongs to a different Narrative.");
}
const { digest: _programDigest, ...programContent } = basis.programSpace;
if (!isDigest(basis.programSpace.digest) || basis.programSpace.digest !== computeProgramSpaceDigest(programContent)) {
@@ -74,21 +77,21 @@ function validateBasis(narrative: Narrative, basis: SpeechBasis): void {
|| basis.programSpace.durationSec <= 0
|| Math.abs(basis.audio.durationSec - basis.programSpace.durationSec) > EPSILON
) {
- fail("SPEECH_BASIS_DURATION", "SpeechBasis audio and ProgramSpace must have the same positive duration.");
+ fail("SPEECH_BASIS_DURATION", "SpeechAudioBasis audio and ProgramSpace must have the same positive duration.");
}
if (!isDigest(basis.audio.digest)) fail("SPEECH_AUDIO_DIGEST", "SpeechBasis audio digest is invalid.");
if (basis.segments.length !== narrative.segments.length) {
- fail("SPEECH_BASIS_SEGMENTS", "SpeechBasis must cover every Narrative Segment exactly once.");
+ fail("SPEECH_BASIS_SEGMENTS", "SpeechAudioBasis must cover every Narrative Segment exactly once.");
}
let previousEnd = 0;
for (const [index, segment] of basis.segments.entries()) {
const expected = narrative.segments[index]!;
if (segment.segmentId !== expected.id) {
- fail("SPEECH_BASIS_SEGMENTS", `SpeechBasis Segment ${segment.segmentId} does not match ${expected.id}.`);
+ fail("SPEECH_BASIS_SEGMENTS", `SpeechAudioBasis Segment ${segment.segmentId} does not match ${expected.id}.`);
}
validateWindow(segment.startSec, segment.endSec, basis.programSpace.durationSec, `Basis Segment ${segment.segmentId}`);
if (segment.startSec < previousEnd - EPSILON) {
- fail("SPEECH_BASIS_SEGMENTS", `SpeechBasis Segment ${segment.segmentId} overlaps its predecessor.`);
+ fail("SPEECH_BASIS_SEGMENTS", `SpeechAudioBasis Segment ${segment.segmentId} overlaps its predecessor.`);
}
if (!isDigest(segment.sourceArtifactDigest)) {
fail("SPEECH_BASIS_ARTIFACT", `SpeechBasis Segment ${segment.segmentId} artifact digest is invalid.`);
@@ -99,7 +102,7 @@ function validateBasis(narrative: Narrative, basis: SpeechBasis): void {
function validateEvidence(
narrative: Narrative,
- basis: SpeechBasis,
+ basis: SpeechAudioBasis,
evidence: AlignedTranscriptEvidence,
): void {
if (evidence.contract !== "svml.aligned-transcript-evidence@1") {
@@ -419,19 +422,19 @@ function mapDigest(map: Omit<CompleteSemanticMap, "mapDigest">): CompleteSemanti
return digestOf(map);
}
-function frameFor(basis: SpeechBasis, timeSec: number): number {
+function frameFor(basis: SpeechAudioBasis, timeSec: number): number {
const { numerator, denominator } = basis.programSpace.frameRate;
return Math.round(timeSec * numerator / denominator);
}
-function secondsFor(basis: SpeechBasis, frame: number): number {
+function secondsFor(basis: SpeechAudioBasis, frame: number): number {
const { numerator, denominator } = basis.programSpace.frameRate;
return frame * denominator / numerator;
}
export function locateSpeechTiming(
narrative: Narrative,
- basis: SpeechBasis,
+ basis: SpeechAudioBasis,
evidence: AlignedTranscriptEvidence,
): CompleteSemanticMap {
validateBasis(narrative, basis);
diff --git a/packages/speech-align/src/manifest.ts b/packages/speech-align/src/manifest.ts
index daf99431..5c2cef06 100644
--- a/packages/speech-align/src/manifest.ts
+++ b/packages/speech-align/src/manifest.ts
@@ -18,15 +18,26 @@ export const speechAlignManifest: ModuleManifest = {
version: speechAlignModuleRef.version,
dependencies: [{ module: contractsModuleRef, digest: contractsManifestDigest }],
types: [],
+ capabilities: [],
surfaces: [],
producers: [{
name: speechAlignProducers.locate.name,
inputs: [
{ name: "narrative", type: contractTypes.narrative },
- { name: "basis", type: contractTypes.speechBasis },
+ { name: "audio", type: contractTypes.speechAudioBasis },
{ name: "evidence", type: contractTypes.alignedTranscriptEvidence },
],
- outputs: [{ name: "map", type: contractTypes.completeSemanticMap }],
+ outputs: [{
+ name: "map",
+ type: contractTypes.completeSemanticMap,
+ affinity: [
+ { resultPointer: "/semanticIndexDigest", input: "narrative", inputPointer: "/semanticIndex/digest" },
+ { resultPointer: "/basisDigest", input: "audio", inputPointer: "/basisDigest" },
+ { resultPointer: "/audioArtifactDigest", input: "audio", inputPointer: "/audio/digest" },
+ { resultPointer: "/programSpaceDigest", input: "audio", inputPointer: "/programSpace/digest" },
+ { resultPointer: "/evidenceDigest", input: "evidence", inputPointer: "/evidenceDigest" },
+ ],
+ }],
needs: [],
implementation: {
kind: "registered",
diff --git a/packages/speech-align/src/types.ts b/packages/speech-align/src/types.ts
index bcf9b5fc..a5d49381 100644
--- a/packages/speech-align/src/types.ts
+++ b/packages/speech-align/src/types.ts
@@ -6,7 +6,7 @@ export type {
CompleteSemanticMap,
SemanticTimePoint,
SpeechActivitySpan,
- SpeechBasis,
+ SpeechAudioBasis,
SpeechCharacterEvidence,
SpeechWordEvidence,
TimedSpeechSegment,
diff --git a/packages/speech-align/test/speech-align.test.ts b/packages/speech-align/test/speech-align.test.ts
index 30e29311..d9e03c92 100644
--- a/packages/speech-align/test/speech-align.test.ts
+++ b/packages/speech-align/test/speech-align.test.ts
@@ -6,7 +6,7 @@ import {
sealProgramSpace,
sealSpeechBasis,
} from "@svml/contracts";
-import type { Narrative, SpeechBasis } from "@svml/contracts";
+import type { Narrative, SpeechAudioBasis, SpeechBasis } from "@svml/contracts";
import { digestOf } from "@svml/core";
import { parseScript } from "@svml/script";
import {
@@ -20,7 +20,7 @@ import type {
} from "@svml/speech-align";
function evidence(args: {
- readonly basis: SpeechBasis;
+ readonly basis: SpeechAudioBasis;
readonly segmentId?: string;
readonly durationSec?: number;
readonly startSec?: number;
@@ -53,7 +53,7 @@ function speechBasis(
narrative: Narrative,
durationSec = 2,
windows?: readonly { readonly startSec: number; readonly endSec: number }[],
-): SpeechBasis {
+): SpeechAudioBasis {
const programSpace = sealProgramSpace({
contract: "svml.program-space@0",
durationSec,
@@ -66,8 +66,9 @@ function speechBasis(
endSec: windows?.[index]?.endSec ?? durationSec * (index + 1) / narrative.segments.length,
sourceArtifactDigest: digestOf(`fixture:clip:${segment.id}`),
}));
- return sealSpeechBasis({
+ const take = sealSpeechBasis({
contract: "svml.speech-basis@1",
+ narrativeDigest: narrative.semanticIndex.digest,
programSpace,
audio: { digest: audioDigest, size: 1, mediaType: "audio/wav", durationSec },
visualTrack: {
@@ -85,6 +86,18 @@ function speechBasis(
},
segments,
});
+ return audioProjection(take);
+}
+
+function audioProjection(basis: SpeechBasis): SpeechAudioBasis {
+ return {
+ contract: "svml.speech-audio-basis@1",
+ basisDigest: basis.basisDigest,
+ narrativeDigest: basis.narrativeDigest,
+ programSpace: basis.programSpace,
+ audio: basis.audio,
+ segments: basis.segments,
+ };
}
function locate(
@@ -304,17 +317,11 @@ test("Evidence from another same-duration audio Basis is rejected before alignme
{ text: "world", startSec: 0.5, endSec: 0.9 },
],
});
- const secondProgram = sealProgramSpace({
- contract: "svml.program-space@0",
- durationSec: 2,
- frameRate: { numerator: 1_000, denominator: 1 },
- });
- const { basisDigest: _firstDigest, ...firstContent } = firstBasis;
- const secondBasis = sealSpeechBasis({
- ...firstContent,
- programSpace: secondProgram,
+ const secondBasis: SpeechAudioBasis = {
+ ...firstBasis,
+ basisDigest: digestOf("fixture:another-take"),
audio: { ...firstBasis.audio, digest: digestOf("fixture:another-same-duration-audio") },
- });
+ };
assert.throws(
() => locateSpeechTiming(narrative, secondBasis, firstEvidence),
(error: unknown) => error instanceof SpeechAlignmentError && error.code === "SPEECH_EVIDENCE_BASIS",
@@ -329,8 +336,11 @@ test("the final map is quantized once into the selected ProgramSpace", () => {
durationSec: 1,
frameRate: { numerator: 30, denominator: 1 },
});
- const { basisDigest: _originalDigest, ...originalContent } = original;
- const basis = sealSpeechBasis({ ...originalContent, programSpace });
+ const basis: SpeechAudioBasis = {
+ ...original,
+ basisDigest: digestOf("fixture:30fps-take"),
+ programSpace,
+ };
const map = locateSpeechTiming(narrative, basis, evidence({
basis,
durationSec: 1,
diff --git a/packages/speech-take/README.md b/packages/speech-take/README.md
new file mode 100644
index 00000000..a81e2177
--- /dev/null
+++ b/packages/speech-take/README.md
@@ -0,0 +1,11 @@
+# `@svml/speech-take`
+
+Reference Product/Projection package for an atomic speech take.
+
+`SpeechBasis` is the indivisible Product that binds audio, visual clips, ProgramSpace and
+`basisDigest`. `project-audio` and `project-visual` are ordinary deterministic Producers. Core has no
+Projection primitive and never treats these outputs as ports of one mutable workflow node.
+
+This gives the author several independent Logical Outputs while preserving one shared generation
+Operation. Selecting an Existing `SpeechBasis` stops generation and leaves both Projections usable;
+selecting only an Existing visual Candidate does not contaminate the independent exact audio path.
diff --git a/packages/speech-take/package.json b/packages/speech-take/package.json
new file mode 100644
index 00000000..2c6c61b5
--- /dev/null
+++ b/packages/speech-take/package.json
@@ -0,0 +1,17 @@
+{
+ "name": "@svml/speech-take",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "dependencies": {
+ "@svml/contracts": "workspace:*",
+ "@svml/protocol": "workspace:*"
+ },
+ "devDependencies": {
+ "@svml/core": "workspace:*",
+ "@svml/driver-node": "workspace:*"
+ }
+}
diff --git a/packages/speech-take/src/index.ts b/packages/speech-take/src/index.ts
new file mode 100644
index 00000000..4fbd376d
--- /dev/null
+++ b/packages/speech-take/src/index.ts
@@ -0,0 +1,12 @@
+export {
+ speechTakeManifest,
+ speechTakeManifestDigest,
+ speechTakeModuleRef,
+ speechTakeProducers,
+} from "./manifest.js";
+export {
+ projectSpeechAudio,
+ projectSpeechAudioImplementationDigest,
+ projectSpeechVisual,
+ projectSpeechVisualImplementationDigest,
+} from "./projection.js";
diff --git a/packages/speech-take/src/manifest.ts b/packages/speech-take/src/manifest.ts
new file mode 100644
index 00000000..5daa2f74
--- /dev/null
+++ b/packages/speech-take/src/manifest.ts
@@ -0,0 +1,72 @@
+import {
+ contractTypes,
+ contractsManifestDigest,
+ contractsModuleRef,
+} from "@svml/contracts";
+import { digestOf } from "@svml/protocol";
+import type { ModuleManifest, ProducerRef } from "@svml/protocol";
+
+import {
+ projectSpeechAudioImplementationDigest,
+ projectSpeechVisualImplementationDigest,
+} from "./projection.js";
+
+export const speechTakeModuleRef = { name: "@svml/speech-take", version: "0.0.0-dev" } as const;
+
+export const speechTakeProducers = {
+ projectAudio: { module: speechTakeModuleRef, name: "project-audio" },
+ projectVisual: { module: speechTakeModuleRef, name: "project-visual" },
+} satisfies Record<string, ProducerRef>;
+
+export const speechTakeManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: speechTakeModuleRef.name,
+ version: speechTakeModuleRef.version,
+ dependencies: [{ module: contractsModuleRef, digest: contractsManifestDigest }],
+ types: [],
+ capabilities: [],
+ surfaces: [],
+ producers: [
+ {
+ name: speechTakeProducers.projectAudio.name,
+ inputs: [{ name: "basis", type: contractTypes.speechBasis }],
+ outputs: [{
+ name: "audio",
+ type: contractTypes.speechAudioBasis,
+ affinity: [
+ { resultPointer: "/basisDigest", input: "basis", inputPointer: "/basisDigest" },
+ { resultPointer: "/narrativeDigest", input: "basis", inputPointer: "/narrativeDigest" },
+ { resultPointer: "/programSpace/digest", input: "basis", inputPointer: "/programSpace/digest" },
+ { resultPointer: "/audio/digest", input: "basis", inputPointer: "/audio/digest" },
+ ],
+ }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "@svml/speech-take/project-audio",
+ digest: projectSpeechAudioImplementationDigest,
+ },
+ },
+ {
+ name: speechTakeProducers.projectVisual.name,
+ inputs: [{ name: "basis", type: contractTypes.speechBasis }],
+ outputs: [{
+ name: "visual",
+ type: contractTypes.speechVisualTrack,
+ affinity: [
+ { resultPointer: "/basisDigest", input: "basis", inputPointer: "/basisDigest" },
+ { resultPointer: "/narrativeDigest", input: "basis", inputPointer: "/narrativeDigest" },
+ { resultPointer: "/programSpace/digest", input: "basis", inputPointer: "/programSpace/digest" },
+ ],
+ }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "@svml/speech-take/project-visual",
+ digest: projectSpeechVisualImplementationDigest,
+ },
+ },
+ ],
+};
+
+export const speechTakeManifestDigest = digestOf(speechTakeManifest);
diff --git a/packages/speech-take/src/projection.ts b/packages/speech-take/src/projection.ts
new file mode 100644
index 00000000..1d438ae2
--- /dev/null
+++ b/packages/speech-take/src/projection.ts
@@ -0,0 +1,39 @@
+import { assertSpeechBasisIdentity } from "@svml/contracts";
+import type {
+ SpeechAudioBasis,
+ SpeechBasis,
+ SpeechVisualTrack,
+} from "@svml/contracts";
+import { digestOf } from "@svml/protocol";
+
+export const projectSpeechAudioImplementationDigest = digestOf(
+ "@svml/speech-take/project-audio@1",
+);
+
+export const projectSpeechVisualImplementationDigest = digestOf(
+ "@svml/speech-take/project-visual@1",
+);
+
+export function projectSpeechAudio(basis: SpeechBasis): SpeechAudioBasis {
+ assertSpeechBasisIdentity(basis);
+ return {
+ contract: "svml.speech-audio-basis@1",
+ basisDigest: basis.basisDigest,
+ narrativeDigest: basis.narrativeDigest,
+ programSpace: basis.programSpace,
+ audio: basis.audio,
+ segments: basis.segments,
+ };
+}
+
+export function projectSpeechVisual(basis: SpeechBasis): SpeechVisualTrack {
+ assertSpeechBasisIdentity(basis);
+ return {
+ contract: "svml.speech-visual-track@1",
+ basisDigest: basis.basisDigest,
+ narrativeDigest: basis.narrativeDigest,
+ programSpace: basis.programSpace,
+ visualTrack: basis.visualTrack,
+ segments: basis.segments,
+ };
+}
diff --git a/packages/speech-take/test/product.test.ts b/packages/speech-take/test/product.test.ts
new file mode 100644
index 00000000..73b6f9a3
--- /dev/null
+++ b/packages/speech-take/test/product.test.ts
@@ -0,0 +1,335 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ contractTypes,
+ contractsManifest,
+ contractsManifestDigest,
+ contractsModuleRef,
+ sealProgramSpace,
+ sealSpeechBasis,
+} from "@svml/contracts";
+import type { SpeechBasis } from "@svml/contracts";
+import {
+ createResolvedClosure,
+ digestOf,
+ link,
+ sealBuildRequest,
+ sealCompiledGraph,
+ sealRecord,
+ sealTypedModule,
+ start,
+} from "@svml/core";
+import { HostRegistry, NodeDriver } from "@svml/driver-node";
+import type {
+ BuildRequest,
+ CompiledGraph,
+ LinkedProgram,
+ ModuleManifest,
+ ProducerRef,
+ TypeRef,
+} from "@svml/protocol";
+import {
+ projectSpeechAudioImplementationDigest,
+ projectSpeechAudio,
+ projectSpeechVisualImplementationDigest,
+ projectSpeechVisual,
+ speechTakeManifest,
+ speechTakeProducers,
+} from "@svml/speech-take";
+
+const testModule = { name: "example.speech-take-product", version: "0.0.0" } as const;
+const requestType = { module: testModule, name: "SpeechRequest" } satisfies TypeRef;
+const generateProducer = { module: testModule, name: "generate-speech-take" } satisfies ProducerRef;
+const generateImplementationDigest = digestOf("example.speech-take-product/generate@1");
+
+const testManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: testModule.name,
+ version: testModule.version,
+ dependencies: [{ module: contractsModuleRef, digest: contractsManifestDigest }],
+ types: [{ name: requestType.name, schema: { kind: "string", minLength: 1 } }],
+ capabilities: [],
+ surfaces: [],
+ producers: [{
+ name: generateProducer.name,
+ inputs: [{ name: "request", type: requestType }],
+ outputs: [{ name: "take", type: contractTypes.speechBasis }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.speech-take-product/generate",
+ digest: generateImplementationDigest,
+ },
+ }],
+};
+
+const closure = createResolvedClosure([contractsManifest, speechTakeManifest, testManifest]);
+
+function sampleTake(label = "generated"): SpeechBasis {
+ const durationSec = 2;
+ const programSpace = sealProgramSpace({
+ contract: "svml.program-space@0",
+ durationSec,
+ frameRate: { numerator: 30, denominator: 1 },
+ });
+ const audio = {
+ digest: digestOf(`${label}:audio`),
+ size: 12,
+ mediaType: "audio/wav",
+ durationSec,
+ };
+ const visual = {
+ digest: digestOf(`${label}:visual`),
+ size: 24,
+ mediaType: "video/mp4",
+ durationSec,
+ };
+ return sealSpeechBasis({
+ contract: "svml.speech-basis@1",
+ narrativeDigest: digestOf("narrative:product-test"),
+ programSpace,
+ audio,
+ visualTrack: {
+ clips: [{ segmentId: "opening", artifact: visual, startSec: 0, endSec: durationSec }],
+ },
+ segments: [{
+ segmentId: "opening",
+ startSec: 0,
+ endSec: durationSec,
+ sourceArtifactDigest: audio.digest,
+ }],
+ });
+}
+
+function createProgram(): LinkedProgram {
+ const request = sealRecord({
+ id: "request:opening",
+ type: requestType,
+ value: { kind: "inline", value: "Generate the opening speech take." },
+ conformance: "exact",
+ origin: {
+ kind: "authored",
+ sourceDigest: digestOf("source:speech-take-product"),
+ frontendClosureDigest: digestOf("frontend:speech-take-product"),
+ },
+ });
+ return link(closure, [sealTypedModule({
+ id: "author:speech-take-product",
+ closureDigest: closure.digest,
+ records: [request],
+ })]);
+}
+
+function createGraph(program: LinkedProgram): CompiledGraph {
+ const record = (id: string) => ({ kind: "record" as const, id });
+ const output = (id: string) => ({ kind: "logical-output" as const, id });
+ const operation = (id: string) => ({ kind: "operation-result" as const, operation: id });
+ const existingTake = sampleTake("approved");
+ const existingVisual = projectSpeechVisual(existingTake);
+ return sealCompiledGraph({
+ program: program.semanticDigest,
+ outputs: [
+ {
+ id: "opening.take",
+ type: contractTypes.speechBasis,
+ primary: "opening.take.generate",
+ candidates: ["opening.take.generate", "opening.take.existing"],
+ semanticInputs: [record("request:opening")],
+ },
+ {
+ id: "opening.audio",
+ type: contractTypes.speechAudioBasis,
+ primary: "opening.audio.project",
+ candidates: ["opening.audio.project"],
+ semanticInputs: [output("opening.take")],
+ affinity: [{
+ resultPointer: "/basisDigest",
+ source: output("opening.take"),
+ sourcePointer: "/basisDigest",
+ }],
+ },
+ {
+ id: "opening.visual",
+ type: contractTypes.speechVisualTrack,
+ primary: "opening.visual.project",
+ candidates: ["opening.visual.project", "opening.visual.existing"],
+ semanticInputs: [output("opening.take")],
+ affinity: [{
+ resultPointer: "/basisDigest",
+ source: output("opening.take"),
+ sourcePointer: "/basisDigest",
+ }],
+ },
+ ],
+ candidates: [
+ {
+ id: "opening.take.generate",
+ output: "opening.take",
+ root: { kind: "operation", result: operation("generate-opening") },
+ fidelity: "exact",
+ },
+ {
+ id: "opening.take.existing",
+ output: "opening.take",
+ root: {
+ kind: "value",
+ value: {
+ id: "provided:opening-take",
+ value: { kind: "inline", value: existingTake },
+ provenance: { library: "approved-takes", take: "opening-v2" },
+ },
+ },
+ fidelity: "exact",
+ },
+ {
+ id: "opening.audio.project",
+ output: "opening.audio",
+ root: { kind: "operation", result: operation("project-opening-audio") },
+ fidelity: "exact",
+ },
+ {
+ id: "opening.visual.project",
+ output: "opening.visual",
+ root: { kind: "operation", result: operation("project-opening-visual") },
+ fidelity: "exact",
+ },
+ {
+ id: "opening.visual.existing",
+ output: "opening.visual",
+ root: {
+ kind: "value",
+ value: {
+ id: "provided:opening-visual",
+ value: { kind: "inline", value: existingVisual },
+ provenance: { library: "approved-clips", clip: "opening-v3" },
+ },
+ },
+ fidelity: "substitute",
+ },
+ ],
+ operations: [
+ {
+ id: "generate-opening",
+ producer: generateProducer,
+ inputs: { request: record("request:opening") },
+ result: { kind: "output", name: "take", record: "take:opening" },
+ },
+ {
+ id: "project-opening-audio",
+ producer: speechTakeProducers.projectAudio,
+ inputs: { basis: output("opening.take") },
+ result: { kind: "output", name: "audio", record: "audio:opening" },
+ },
+ {
+ id: "project-opening-visual",
+ producer: speechTakeProducers.projectVisual,
+ inputs: { basis: output("opening.take") },
+ result: { kind: "output", name: "visual", record: "visual:opening" },
+ },
+ ],
+ });
+}
+
+function build(
+ targetAccepts: Readonly<Record<string, "exact" | "substitute">>,
+ bindings: Readonly<Record<string, string>> = {},
+) {
+ const program = createProgram();
+ const graph = createGraph(program);
+ const request: BuildRequest = sealBuildRequest({
+ graph: graph.id,
+ targets: Object.entries(targetAccepts).map(([outputId, accepts]) => ({ output: outputId, accepts })),
+ bindings: Object.entries(bindings).map(([outputId, candidate]) => ({ output: outputId, candidate })),
+ });
+ return start(program, graph, request);
+}
+
+function stepIds(state: ReturnType<typeof build>): string[] {
+ return state.plan.steps.map((step) => step.id).sort();
+}
+
+test("SpeechBasis is one Product and audio/visual are ordinary shared projections", () => {
+ const state = build({ "opening.audio": "exact", "opening.visual": "exact" });
+ assert.deepEqual(stepIds(state), [
+ "generate-opening",
+ "project-opening-audio",
+ "project-opening-visual",
+ ]);
+ assert.equal(state.plan.steps.filter((step) => step.id === "generate-opening").length, 1);
+ assert.equal(
+ state.plan.steps.find((step) => step.id === "project-opening-audio")?.inputs.basis,
+ "take:opening",
+ );
+ assert.equal(
+ state.plan.steps.find((step) => step.id === "project-opening-visual")?.inputs.basis,
+ "take:opening",
+ );
+});
+
+test("a substitute visual Candidate does not contaminate an independent exact audio path", () => {
+ const state = build(
+ { "opening.audio": "exact", "opening.visual": "substitute" },
+ { "opening.visual": "opening.visual.existing" },
+ );
+ assert.deepEqual(stepIds(state), ["generate-opening", "project-opening-audio"]);
+ assert.equal(
+ state.plan.selections.find((selection) => selection.output === "opening.audio")?.record,
+ "audio:opening",
+ );
+ assert.equal(
+ state.plan.selections.find((selection) => selection.output === "opening.visual")?.record,
+ "provided:opening-visual",
+ );
+});
+
+test("selecting an Existing SpeechTake stops generation but keeps both projections", () => {
+ const state = build(
+ { "opening.audio": "exact", "opening.visual": "exact" },
+ { "opening.take": "opening.take.existing" },
+ );
+ assert.deepEqual(stepIds(state), ["project-opening-audio", "project-opening-visual"]);
+ assert.deepEqual(state.plan.initialValues.map((record) => record.id), ["provided:opening-take"]);
+ assert.equal(
+ state.plan.steps.find((step) => step.id === "project-opening-audio")?.inputs.basis,
+ "provided:opening-take",
+ );
+});
+
+test("the Build Machine executes one shared generation for both projected outputs", async () => {
+ let generations = 0;
+ const registry = new HostRegistry();
+ registry.registerProducer(generateProducer, generateImplementationDigest, () => {
+ generations += 1;
+ return { outputs: { take: { kind: "inline", value: sampleTake() } }, needs: {} };
+ });
+ registry.registerProducer(
+ speechTakeProducers.projectAudio,
+ projectSpeechAudioImplementationDigest,
+ ({ inputs }) => {
+ const value = inputs.basis?.value;
+ assert.equal(value?.kind, "inline");
+ return {
+ outputs: { audio: { kind: "inline", value: projectSpeechAudio(value.value as unknown as SpeechBasis) } },
+ needs: {},
+ };
+ },
+ );
+ registry.registerProducer(
+ speechTakeProducers.projectVisual,
+ projectSpeechVisualImplementationDigest,
+ ({ inputs }) => {
+ const value = inputs.basis?.value;
+ assert.equal(value?.kind, "inline");
+ return {
+ outputs: { visual: { kind: "inline", value: projectSpeechVisual(value.value as unknown as SpeechBasis) } },
+ needs: {},
+ };
+ },
+ );
+ const result = await new NodeDriver({ registry }).run(
+ build({ "opening.audio": "exact", "opening.visual": "exact" }),
+ );
+ assert.equal(result.status, "complete");
+ assert.equal(generations, 1);
+});
diff --git a/packages/text/test/text.test.ts b/packages/text/test/text.test.ts
index 3f1b8ef4..0aad37f9 100644
--- a/packages/text/test/text.test.ts
+++ b/packages/text/test/text.test.ts
@@ -177,6 +177,7 @@ test("a module can use Text's generic structured parser without adding another p
},
},
],
+ capabilities: [],
surfaces: [
{
name: "card",
diff --git a/packages/video-fragments/README.md b/packages/video-fragments/README.md
new file mode 100644
index 00000000..1f955970
--- /dev/null
+++ b/packages/video-fragments/README.md
@@ -0,0 +1,14 @@
+# @svml/video-fragments
+
+Trusted, static Graph Fragments for the first official speech-video path.
+
+This package contains no Core behavior, Provider credentials, queues, or API
+clients. It only composes ordinary Producers from the leaf packages into
+auditable reusable graph contributions:
+
+- atomic SpeechTake audio/visual projections;
+- WhisperX evidence plus the provider-neutral speech SemanticMap;
+- timed caption projection.
+
+The author frontend may expose these Fragments through concise surface syntax.
+The Elaborator expands them hygienically before SVML Core sees the graph.
diff --git a/packages/video-fragments/package.json b/packages/video-fragments/package.json
new file mode 100644
index 00000000..19533fd5
--- /dev/null
+++ b/packages/video-fragments/package.json
@@ -0,0 +1,24 @@
+{
+ "name": "@svml/video-fragments",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "dependencies": {
+ "@svml/caption": "workspace:*",
+ "@svml/contracts": "workspace:*",
+ "@svml/elaborator": "workspace:*",
+ "@svml/speech-align": "workspace:*",
+ "@svml/speech-take": "workspace:*",
+ "@svml/whisperx": "workspace:*"
+ },
+ "devDependencies": {
+ "@svml/core": "workspace:*",
+ "@svml/driver-node": "workspace:*",
+ "@svml/protocol": "workspace:*",
+ "@svml/realization": "workspace:*",
+ "@svml/script": "workspace:*"
+ }
+}
diff --git a/packages/video-fragments/src/index.ts b/packages/video-fragments/src/index.ts
new file mode 100644
index 00000000..a9e5cef6
--- /dev/null
+++ b/packages/video-fragments/src/index.ts
@@ -0,0 +1,5 @@
+export {
+ captionTimingFragment,
+ speechTakeProjectionFragment,
+ whisperXSpeechAlignmentFragment,
+} from "./speech.js";
diff --git a/packages/video-fragments/src/speech.ts b/packages/video-fragments/src/speech.ts
new file mode 100644
index 00000000..67a167e2
--- /dev/null
+++ b/packages/video-fragments/src/speech.ts
@@ -0,0 +1,154 @@
+import { captionProducers } from "@svml/caption";
+import { contractTypes } from "@svml/contracts";
+import { sealGraphFragment } from "@svml/elaborator";
+import { speechAlignProducers } from "@svml/speech-align";
+import { speechTakeProducers } from "@svml/speech-take";
+import { whisperXProducers, whisperXTypes } from "@svml/whisperx";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+/** Project one atomic SpeechTake Product without turning its fields into mutable node ports. */
+export const speechTakeProjectionFragment = sealGraphFragment({
+ name: "@svml/video-fragments/speech-take-projections@1",
+ inputs: [{ name: "take", type: contractTypes.speechBasis }],
+ operations: [
+ {
+ id: "project-audio",
+ producer: speechTakeProducers.projectAudio,
+ inputs: { basis: input("take") },
+ result: { kind: "output", name: "audio" },
+ },
+ {
+ id: "project-visual",
+ producer: speechTakeProducers.projectVisual,
+ inputs: { basis: input("take") },
+ result: { kind: "output", name: "visual" },
+ },
+ ],
+ exports: [
+ {
+ name: "audio",
+ type: contractTypes.speechAudioBasis,
+ root: operation("project-audio"),
+ semanticInputs: ["take"],
+ affinity: [
+ { resultPointer: "/basisDigest", source: input("take"), sourcePointer: "/basisDigest" },
+ { resultPointer: "/narrativeDigest", source: input("take"), sourcePointer: "/narrativeDigest" },
+ { resultPointer: "/programSpace/digest", source: input("take"), sourcePointer: "/programSpace/digest" },
+ { resultPointer: "/audio/digest", source: input("take"), sourcePointer: "/audio/digest" },
+ ],
+ fidelity: "exact",
+ },
+ {
+ name: "visual",
+ type: contractTypes.speechVisualTrack,
+ root: operation("project-visual"),
+ semanticInputs: ["take"],
+ affinity: [
+ { resultPointer: "/basisDigest", source: input("take"), sourcePointer: "/basisDigest" },
+ { resultPointer: "/narrativeDigest", source: input("take"), sourcePointer: "/narrativeDigest" },
+ { resultPointer: "/programSpace/digest", source: input("take"), sourcePointer: "/programSpace/digest" },
+ ],
+ fidelity: "exact",
+ },
+ ],
+});
+
+/** One WhisperX pass can expose both normalized Evidence and the final SemanticMap. */
+export const whisperXSpeechAlignmentFragment = sealGraphFragment({
+ name: "@svml/video-fragments/whisperx-speech-alignment@1",
+ inputs: [
+ { name: "narrative", type: contractTypes.narrative },
+ { name: "audio", type: contractTypes.speechAudioBasis },
+ ],
+ operations: [
+ {
+ id: "request-whisperx",
+ producer: whisperXProducers.request,
+ inputs: { audio: input("audio") },
+ result: { kind: "need", name: "alignment", accepts: "exact" },
+ },
+ {
+ id: "normalize-evidence",
+ producer: whisperXProducers.normalize,
+ inputs: { whisperx: operation("request-whisperx") },
+ result: { kind: "output", name: "evidence" },
+ },
+ {
+ id: "locate-speech",
+ producer: speechAlignProducers.locate,
+ inputs: {
+ narrative: input("narrative"),
+ audio: input("audio"),
+ evidence: operation("normalize-evidence"),
+ },
+ result: { kind: "output", name: "map" },
+ },
+ ],
+ exports: [
+ {
+ name: "rawEvidence",
+ type: whisperXTypes.alignmentEvidence,
+ root: operation("request-whisperx"),
+ semanticInputs: ["audio"],
+ affinity: [
+ { resultPointer: "/basisDigest", source: input("audio"), sourcePointer: "/basisDigest" },
+ { resultPointer: "/audioArtifactDigest", source: input("audio"), sourcePointer: "/audio/digest" },
+ { resultPointer: "/programSpaceDigest", source: input("audio"), sourcePointer: "/programSpace/digest" },
+ ],
+ fidelity: "exact",
+ },
+ {
+ name: "evidence",
+ type: contractTypes.alignedTranscriptEvidence,
+ root: operation("normalize-evidence"),
+ semanticInputs: ["audio"],
+ affinity: [
+ { resultPointer: "/basisDigest", source: input("audio"), sourcePointer: "/basisDigest" },
+ { resultPointer: "/audioArtifactDigest", source: input("audio"), sourcePointer: "/audio/digest" },
+ { resultPointer: "/programSpaceDigest", source: input("audio"), sourcePointer: "/programSpace/digest" },
+ ],
+ fidelity: "exact",
+ },
+ {
+ name: "map",
+ type: contractTypes.completeSemanticMap,
+ root: operation("locate-speech"),
+ semanticInputs: ["narrative", "audio"],
+ affinity: [
+ { resultPointer: "/semanticIndexDigest", source: input("narrative"), sourcePointer: "/semanticIndex/digest" },
+ { resultPointer: "/basisDigest", source: input("audio"), sourcePointer: "/basisDigest" },
+ { resultPointer: "/audioArtifactDigest", source: input("audio"), sourcePointer: "/audio/digest" },
+ { resultPointer: "/programSpaceDigest", source: input("audio"), sourcePointer: "/programSpace/digest" },
+ { resultPointer: "/evidenceDigest", source: operation("normalize-evidence"), sourcePointer: "/evidenceDigest" },
+ ],
+ fidelity: "exact",
+ },
+ ],
+});
+
+export const captionTimingFragment = sealGraphFragment({
+ name: "@svml/video-fragments/caption-timing@1",
+ inputs: [
+ { name: "narrative", type: contractTypes.narrative },
+ { name: "map", type: contractTypes.completeSemanticMap },
+ ],
+ operations: [{
+ id: "temporalize-caption",
+ producer: captionProducers.temporalize,
+ inputs: { narrative: input("narrative"), map: input("map") },
+ result: { kind: "output", name: "caption" },
+ }],
+ exports: [{
+ name: "caption",
+ type: contractTypes.timedCaptionProjection,
+ root: operation("temporalize-caption"),
+ semanticInputs: ["narrative", "map"],
+ affinity: [
+ { resultPointer: "/semanticIndexDigest", source: input("narrative"), sourcePointer: "/semanticIndex/digest" },
+ { resultPointer: "/speechTimeMapDigest", source: input("map"), sourcePointer: "/mapDigest" },
+ ],
+ fidelity: "exact",
+ }],
+});
diff --git a/packages/video-fragments/test/video-pipeline-fixture.ts b/packages/video-fragments/test/video-pipeline-fixture.ts
new file mode 100644
index 00000000..f9bd2fda
--- /dev/null
+++ b/packages/video-fragments/test/video-pipeline-fixture.ts
@@ -0,0 +1,389 @@
+import { captionManifest } from "@svml/caption";
+import {
+ contractTypes,
+ contractsManifest,
+ contractsManifestDigest,
+ contractsModuleRef,
+} from "@svml/contracts";
+import {
+ createResolvedClosure,
+ digestOf,
+ link,
+ sealBuildRequest,
+ sealCompiledGraph,
+ sealRecord,
+ sealTypedModule,
+ start,
+} from "@svml/core";
+import {
+ bindAuthorFragment,
+ bindCandidateFragment,
+ elaborateGraphFragment,
+ mergeFragmentContributions,
+ sealGraphFragment,
+} from "@svml/elaborator";
+import type {
+ BuildState,
+ CapabilityRef,
+ CompiledGraph,
+ LinkedProgram,
+ ModuleManifest,
+ ProducerRef,
+ TypeRef,
+ ValueSchema,
+} from "@svml/protocol";
+import { resolveRealization, sealRealizationOverlay } from "@svml/realization";
+import { narrativeValue, parseScript } from "@svml/script";
+import { speechAlignManifest } from "@svml/speech-align";
+import { speechTakeManifest } from "@svml/speech-take";
+import {
+ captionTimingFragment,
+ speechTakeProjectionFragment,
+ whisperXSpeechAlignmentFragment,
+} from "@svml/video-fragments";
+import { whisperXManifest, whisperXTypes } from "@svml/whisperx";
+
+export const videoModule = { name: "example.video-pipeline", version: "0.0.0" } as const;
+
+export const videoTypes = {
+ estimate: { module: videoModule, name: "OfficialSpeechDurationEstimate" },
+ seedanceMiniMedia: { module: videoModule, name: "SeedanceMiniSpeechMedia" },
+} satisfies Record<string, TypeRef>;
+
+export const videoCapabilities = {
+ estimate: { module: videoModule, name: "official-speech-duration-estimate" },
+ seedanceMini: { module: videoModule, name: "seedance-mini-speech-media" },
+} satisfies Record<string, CapabilityRef>;
+
+export const videoProducers = {
+ requestEstimate: { module: videoModule, name: "request-official-speech-estimate" },
+ placeholderEstimate: { module: videoModule, name: "placeholder-speech-estimate" },
+ requestSeedanceMini: { module: videoModule, name: "request-seedance-mini-speech" },
+ assembleBasis: { module: videoModule, name: "assemble-speech-basis" },
+} satisfies Record<string, ProducerRef>;
+
+export const videoImplementations = Object.fromEntries(
+ Object.entries(videoProducers).map(([name]) => [name, digestOf(`example.video-pipeline/${name}@1`)]),
+) as Readonly<Record<keyof typeof videoProducers, ReturnType<typeof digestOf>>>;
+
+const string = { kind: "string", minLength: 1 } as const;
+const number = { kind: "number", minimum: 0 } as const;
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema }>>): ValueSchema => ({
+ kind: "object",
+ fields,
+});
+
+export const videoManifest: ModuleManifest = {
+ format: "svml.module@0",
+ name: videoModule.name,
+ version: videoModule.version,
+ dependencies: [{ module: contractsModuleRef, digest: contractsManifestDigest }],
+ types: [
+ { name: videoTypes.estimate.name, schema: object({ durationSec: { schema: number } }) },
+ {
+ name: videoTypes.seedanceMiniMedia.name,
+ schema: object({
+ model: { schema: { kind: "literal", value: "mini" } },
+ audioDigest: { schema: string },
+ visualDigest: { schema: string },
+ durationSec: { schema: number },
+ }),
+ },
+ ],
+ capabilities: [
+ { name: videoCapabilities.estimate.name, returns: videoTypes.estimate },
+ { name: videoCapabilities.seedanceMini.name, returns: videoTypes.seedanceMiniMedia },
+ ],
+ surfaces: [],
+ producers: [
+ {
+ name: videoProducers.requestEstimate.name,
+ inputs: [{ name: "narrative", type: contractTypes.narrative }],
+ outputs: [],
+ needs: [{
+ name: "estimate",
+ capability: videoCapabilities.estimate,
+ returns: videoTypes.estimate,
+ }],
+ implementation: {
+ kind: "registered",
+ locator: "example.video-pipeline/request-estimate",
+ digest: videoImplementations.requestEstimate,
+ },
+ },
+ {
+ name: videoProducers.requestSeedanceMini.name,
+ inputs: [
+ { name: "narrative", type: contractTypes.narrative },
+ { name: "estimate", type: videoTypes.estimate },
+ ],
+ outputs: [],
+ needs: [{
+ name: "media",
+ capability: videoCapabilities.seedanceMini,
+ returns: videoTypes.seedanceMiniMedia,
+ }],
+ implementation: {
+ kind: "registered",
+ locator: "example.video-pipeline/request-seedance-mini",
+ digest: videoImplementations.requestSeedanceMini,
+ },
+ },
+ {
+ name: videoProducers.placeholderEstimate.name,
+ inputs: [{ name: "narrative", type: contractTypes.narrative }],
+ outputs: [{ name: "estimate", type: videoTypes.estimate }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.video-pipeline/placeholder-estimate",
+ digest: videoImplementations.placeholderEstimate,
+ },
+ },
+ {
+ name: videoProducers.assembleBasis.name,
+ inputs: [
+ { name: "narrative", type: contractTypes.narrative },
+ { name: "media", type: videoTypes.seedanceMiniMedia },
+ ],
+ outputs: [{
+ name: "basis",
+ type: contractTypes.speechBasis,
+ affinity: [{
+ resultPointer: "/narrativeDigest",
+ input: "narrative",
+ inputPointer: "/semanticIndex/digest",
+ }],
+ }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.video-pipeline/assemble-basis",
+ digest: videoImplementations.assembleBasis,
+ },
+ },
+ ],
+};
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+const durationEstimateFragment = sealGraphFragment({
+ name: "example.video-pipeline/duration-estimate@1",
+ inputs: [{ name: "narrative", type: contractTypes.narrative }],
+ operations: [{
+ id: "estimate",
+ producer: videoProducers.requestEstimate,
+ inputs: { narrative: input("narrative") },
+ result: { kind: "need", name: "estimate", accepts: "exact" },
+ }],
+ exports: [{
+ name: "estimate",
+ type: videoTypes.estimate,
+ root: operation("estimate"),
+ semanticInputs: ["narrative"],
+ fidelity: "exact",
+ }],
+});
+
+const speechTakeGenerationFragment = sealGraphFragment({
+ name: "example.video-pipeline/seedance-mini-speech-take@1",
+ inputs: [
+ { name: "narrative", type: contractTypes.narrative },
+ { name: "estimate", type: videoTypes.estimate },
+ ],
+ operations: [
+ {
+ id: "request-seedance-mini",
+ producer: videoProducers.requestSeedanceMini,
+ inputs: { narrative: input("narrative"), estimate: input("estimate") },
+ result: { kind: "need", name: "media", accepts: "exact" },
+ },
+ {
+ id: "assemble-take",
+ producer: videoProducers.assembleBasis,
+ inputs: { narrative: input("narrative"), media: operation("request-seedance-mini") },
+ result: { kind: "output", name: "basis" },
+ },
+ ],
+ exports: [{
+ name: "take",
+ type: contractTypes.speechBasis,
+ root: operation("assemble-take"),
+ semanticInputs: ["narrative", "estimate"],
+ affinity: [{
+ resultPointer: "/narrativeDigest",
+ source: input("narrative"),
+ sourcePointer: "/semanticIndex/digest",
+ }],
+ fidelity: "exact",
+ }],
+});
+
+const placeholderEstimateFragment = sealGraphFragment({
+ name: "example.video-pipeline/placeholder-estimate@1",
+ inputs: [{ name: "narrative", type: contractTypes.narrative }],
+ operations: [{
+ id: "placeholder",
+ producer: videoProducers.placeholderEstimate,
+ inputs: { narrative: input("narrative") },
+ result: { kind: "output", name: "estimate" },
+ }],
+ exports: [{
+ name: "estimate",
+ type: videoTypes.estimate,
+ root: operation("placeholder"),
+ semanticInputs: ["narrative"],
+ fidelity: "substitute",
+ }],
+});
+
+export const videoOutputs = {
+ estimate: "speech.estimate",
+ take: "speech.take",
+ audio: "speech.audio",
+ visual: "speech.visual",
+ rawEvidence: "speech.whisperx-evidence",
+ evidence: "speech.evidence",
+ map: "speech.map",
+ caption: "speech.caption",
+} as const;
+
+export type VideoOutputName = keyof typeof videoOutputs;
+
+export const videoClosure = createResolvedClosure([
+ contractsManifest,
+ videoManifest,
+ speechTakeManifest,
+ whisperXManifest,
+ speechAlignManifest,
+ captionManifest,
+]);
+
+function authorProgram(): LinkedProgram {
+ const parsed = parseScript("pipeline.svml", "<line><that was insane | what the fuck></line>");
+ const narrative = sealRecord({
+ id: "narrative:root",
+ type: contractTypes.narrative,
+ value: { kind: "inline", value: narrativeValue(parsed) },
+ conformance: "exact",
+ origin: {
+ kind: "authored",
+ sourceDigest: digestOf("source:video-pipeline"),
+ frontendClosureDigest: digestOf("frontend:script"),
+ sourceName: "pipeline.svml",
+ },
+ });
+ return link(videoClosure, [sealTypedModule({
+ id: "author:video-pipeline",
+ closureDigest: videoClosure.digest,
+ records: [narrative],
+ })]);
+}
+
+export function createVideoGraph(program: LinkedProgram): CompiledGraph {
+ const narrative = { kind: "record" as const, id: "narrative:root" };
+ const estimate = elaborateGraphFragment(program, durationEstimateFragment, {
+ id: "opening.estimate",
+ fragment: durationEstimateFragment.id,
+ inputs: { narrative },
+ });
+ const take = elaborateGraphFragment(program, speechTakeGenerationFragment, {
+ id: "opening.seedance-mini",
+ fragment: speechTakeGenerationFragment.id,
+ inputs: {
+ narrative,
+ estimate: { kind: "logical-output", id: videoOutputs.estimate },
+ },
+ });
+ const projections = elaborateGraphFragment(program, speechTakeProjectionFragment, {
+ id: "opening.take-projections",
+ fragment: speechTakeProjectionFragment.id,
+ inputs: { take: { kind: "logical-output", id: videoOutputs.take } },
+ });
+ const alignment = elaborateGraphFragment(program, whisperXSpeechAlignmentFragment, {
+ id: "opening.whisperx-alignment",
+ fragment: whisperXSpeechAlignmentFragment.id,
+ inputs: {
+ narrative,
+ audio: { kind: "logical-output", id: videoOutputs.audio },
+ },
+ });
+ const caption = elaborateGraphFragment(program, captionTimingFragment, {
+ id: "opening.caption",
+ fragment: captionTimingFragment.id,
+ inputs: {
+ narrative,
+ map: { kind: "logical-output", id: videoOutputs.map },
+ },
+ });
+ const contribution = mergeFragmentContributions(
+ { outputs: [], candidates: [], operations: [] },
+ bindAuthorFragment(estimate, { estimate: videoOutputs.estimate }),
+ bindAuthorFragment(take, { take: videoOutputs.take }),
+ bindAuthorFragment(projections, {
+ audio: videoOutputs.audio,
+ visual: videoOutputs.visual,
+ }),
+ bindAuthorFragment(alignment, {
+ rawEvidence: videoOutputs.rawEvidence,
+ evidence: videoOutputs.evidence,
+ map: videoOutputs.map,
+ }),
+ bindAuthorFragment(caption, { caption: videoOutputs.caption }),
+ );
+ return sealCompiledGraph({ program: program.semanticDigest, ...contribution });
+}
+
+export type VideoBuildOptions = {
+ readonly estimateRealization?: "primary" | "placeholder";
+ readonly goalAccepts?: "exact" | "substitute";
+ readonly targets?: readonly VideoOutputName[];
+};
+
+export type VideoFixture = {
+ readonly program: LinkedProgram;
+ readonly source: CompiledGraph;
+ readonly graph: CompiledGraph;
+ readonly bindings: readonly { readonly output: string; readonly candidate: string }[];
+};
+
+export function createVideoFixture(options: VideoBuildOptions = {}): VideoFixture {
+ const program = authorProgram();
+ const source = createVideoGraph(program);
+ if (options.estimateRealization !== "placeholder") {
+ return { program, source, graph: source, bindings: [] };
+ }
+ const placeholder = elaborateGraphFragment(program, placeholderEstimateFragment, {
+ id: "opening.placeholder-estimate",
+ fragment: placeholderEstimateFragment.id,
+ inputs: { narrative: { kind: "record", id: "narrative:root" } },
+ });
+ const contribution = bindCandidateFragment(placeholder, { estimate: videoOutputs.estimate });
+ const overlay = sealRealizationOverlay({
+ sourceGraph: source.id,
+ candidates: contribution.candidates,
+ operations: contribution.operations,
+ });
+ const realized = resolveRealization(program, source, [overlay]);
+ return {
+ program,
+ source,
+ graph: realized.graph,
+ bindings: [{ output: videoOutputs.estimate, candidate: contribution.candidates[0]!.id }],
+ };
+}
+
+export function createVideoBuild(options: VideoBuildOptions = {}): BuildState {
+ const fixture = createVideoFixture(options);
+ const accepts = options.goalAccepts ?? "exact";
+ const targets = options.targets ?? ["caption"];
+ const request = sealBuildRequest({
+ graph: fixture.graph.id,
+ targets: targets.map((name) => ({ output: videoOutputs[name], accepts })),
+ bindings: fixture.bindings,
+ });
+ return start(fixture.program, fixture.graph, request);
+}
+
+export { contractTypes, whisperXTypes };
diff --git a/packages/video-fragments/test/video-pipeline.test.ts b/packages/video-fragments/test/video-pipeline.test.ts
new file mode 100644
index 00000000..e16b513d
--- /dev/null
+++ b/packages/video-fragments/test/video-pipeline.test.ts
@@ -0,0 +1,567 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { captionImplementationDigest, captionProducers, temporalizeCaption } from "@svml/caption";
+import {
+ sealProgramSpace,
+ sealSpeechBasis,
+} from "@svml/contracts";
+import type {
+ AlignedTranscriptEvidence,
+ CompleteSemanticMap,
+ Narrative,
+ SpeechAudioBasis,
+ SpeechBasis,
+ SpeechVisualTrack,
+ TimedCaptionProjection,
+} from "@svml/contracts";
+import { digestOf, sealBuildRequest, start } from "@svml/core";
+import {
+ HostRegistry,
+ NodeDriver,
+ ProviderRegistry,
+ parseBuildState,
+ serializeBuildState,
+} from "@svml/driver-node";
+import type { BuildState, CapabilityRef, ProducerRef } from "@svml/protocol";
+import {
+ createProvidedCandidate,
+ resolveRealization,
+ sealRealizationOverlay,
+} from "@svml/realization";
+import { locateSpeechTiming, speechAlignProducers, speechLocatorDigest } from "@svml/speech-align";
+import {
+ projectSpeechAudio,
+ projectSpeechAudioImplementationDigest,
+ projectSpeechVisual,
+ projectSpeechVisualImplementationDigest,
+ speechTakeProducers,
+} from "@svml/speech-take";
+import {
+ normalizeWhisperXAlignment,
+ sealWhisperXAlignmentEvidence,
+ whisperXCapabilities,
+ whisperXImplementationDigests,
+ whisperXProducers,
+ whisperXRequestForAudioBasis,
+} from "@svml/whisperx";
+import type { WhisperXAlignmentEvidence } from "@svml/whisperx";
+
+import {
+ createVideoBuild,
+ createVideoFixture,
+ videoCapabilities,
+ videoImplementations,
+ videoOutputs,
+ videoProducers,
+ videoTypes,
+ whisperXTypes,
+} from "./video-pipeline-fixture.js";
+
+function inlineObject(value: unknown): Readonly<Record<string, unknown>> {
+ if (value === null || Array.isArray(value) || typeof value !== "object") throw new Error("expected object");
+ return value as Readonly<Record<string, unknown>>;
+}
+
+function inlineValue<T>(value: unknown): T {
+ return value as T;
+}
+
+function sameCapability(left: CapabilityRef, right: CapabilityRef): boolean {
+ return left.name === right.name
+ && left.module.name === right.module.name
+ && left.module.version === right.module.version;
+}
+
+function selectedRecord(state: BuildState, output: string): string {
+ const selection = state.plan.selections.find((item) => item.output === output);
+ assert(selection, `missing selection for ${output}`);
+ return selection.record;
+}
+
+function producerCount(state: BuildState, producer: ProducerRef): number {
+ return state.plan.steps.filter((step) =>
+ step.producer.name === producer.name
+ && step.producer.module.name === producer.module.name
+ && step.producer.module.version === producer.module.version).length;
+}
+
+test("the Fragment-built speech pipeline resumes without repeating paid calls", async () => {
+ const host = new HostRegistry();
+ const providers = new ProviderRegistry();
+ const calls = {
+ estimate: 0,
+ seedance: 0,
+ assemble: 0,
+ projectAudio: 0,
+ projectVisual: 0,
+ whisperRequest: 0,
+ whisperNormalize: 0,
+ locate: 0,
+ caption: 0,
+ };
+
+ host.registerProducer(videoProducers.requestEstimate, videoImplementations.requestEstimate, ({ inputs }) => {
+ calls.estimate += 1;
+ assert.equal(inputs.narrative?.value.kind, "inline");
+ const narrative = inlineValue<Narrative>(inputs.narrative.value.value);
+ return {
+ outputs: {},
+ needs: {
+ estimate: {
+ contract: "example.official-speech-estimate-request@1",
+ speech: narrative.serializations.speech,
+ },
+ },
+ };
+ });
+ host.registerProducer(videoProducers.requestSeedanceMini, videoImplementations.requestSeedanceMini, ({ inputs }) => {
+ calls.seedance += 1;
+ assert.equal(inputs.narrative?.value.kind, "inline");
+ assert.equal(inputs.estimate?.value.kind, "inline");
+ const narrative = inlineValue<Narrative>(inputs.narrative.value.value);
+ const estimate = inlineObject(inputs.estimate.value.value);
+ return {
+ outputs: {},
+ needs: {
+ media: {
+ contract: "example.seedance-mini-speech-request@1",
+ model: "mini",
+ script: narrative.serializations.speech,
+ durationSec: estimate.durationSec as number,
+ },
+ },
+ };
+ });
+ host.registerProducer(videoProducers.assembleBasis, videoImplementations.assembleBasis, ({ inputs }) => {
+ calls.assemble += 1;
+ assert.equal(inputs.narrative?.value.kind, "inline");
+ assert.equal(inputs.media?.value.kind, "inline");
+ const narrative = inlineValue<Narrative>(inputs.narrative.value.value);
+ const media = inlineObject(inputs.media.value.value);
+ const durationSec = media.durationSec as number;
+ const programSpace = sealProgramSpace({
+ contract: "svml.program-space@0",
+ durationSec,
+ frameRate: { numerator: 1_000, denominator: 1 },
+ });
+ const audioDigest = media.audioDigest as SpeechBasis["audio"]["digest"];
+ const visualDigest = media.visualDigest as SpeechBasis["audio"]["digest"];
+ const basis = sealSpeechBasis({
+ contract: "svml.speech-basis@1",
+ narrativeDigest: narrative.semanticIndex.digest,
+ programSpace,
+ audio: { digest: audioDigest, size: 1, mediaType: "audio/wav", durationSec },
+ visualTrack: { clips: [{
+ segmentId: "line",
+ artifact: { digest: visualDigest, size: 1, mediaType: "video/mp4", durationSec },
+ startSec: 0,
+ endSec: durationSec,
+ }] },
+ segments: [{ segmentId: "line", startSec: 0, endSec: durationSec, sourceArtifactDigest: visualDigest }],
+ });
+ return { outputs: { basis: { kind: "inline", value: basis } }, needs: {} };
+ });
+ host.registerProducer(
+ speechTakeProducers.projectAudio,
+ projectSpeechAudioImplementationDigest,
+ ({ inputs }) => {
+ calls.projectAudio += 1;
+ assert.equal(inputs.basis?.value.kind, "inline");
+ return {
+ outputs: {
+ audio: {
+ kind: "inline",
+ value: projectSpeechAudio(inlineValue<SpeechBasis>(inputs.basis.value.value)),
+ },
+ },
+ needs: {},
+ };
+ },
+ );
+ host.registerProducer(
+ speechTakeProducers.projectVisual,
+ projectSpeechVisualImplementationDigest,
+ ({ inputs }) => {
+ calls.projectVisual += 1;
+ assert.equal(inputs.basis?.value.kind, "inline");
+ return {
+ outputs: {
+ visual: {
+ kind: "inline",
+ value: projectSpeechVisual(inlineValue<SpeechBasis>(inputs.basis.value.value)),
+ },
+ },
+ needs: {},
+ };
+ },
+ );
+ host.registerProducer(whisperXProducers.request, whisperXImplementationDigests.request, ({ inputs }) => {
+ calls.whisperRequest += 1;
+ assert.equal(inputs.audio?.value.kind, "inline");
+ return {
+ outputs: {},
+ needs: {
+ alignment: whisperXRequestForAudioBasis(
+ inlineValue<SpeechAudioBasis>(inputs.audio.value.value),
+ { language: "en" },
+ ),
+ },
+ };
+ });
+ host.registerProducer(whisperXProducers.normalize, whisperXImplementationDigests.normalize, ({ inputs }) => {
+ calls.whisperNormalize += 1;
+ assert.equal(inputs.whisperx?.value.kind, "inline");
+ const evidence = normalizeWhisperXAlignment(
+ inlineValue<WhisperXAlignmentEvidence>(inputs.whisperx.value.value),
+ );
+ return { outputs: { evidence: { kind: "inline", value: evidence } }, needs: {} };
+ });
+ host.registerProducer(speechAlignProducers.locate, speechLocatorDigest, ({ inputs }) => {
+ calls.locate += 1;
+ assert.equal(inputs.narrative?.value.kind, "inline");
+ assert.equal(inputs.audio?.value.kind, "inline");
+ assert.equal(inputs.evidence?.value.kind, "inline");
+ const map = locateSpeechTiming(
+ inlineValue<Narrative>(inputs.narrative.value.value),
+ inlineValue<SpeechAudioBasis>(inputs.audio.value.value),
+ inlineValue<AlignedTranscriptEvidence>(inputs.evidence.value.value),
+ );
+ return { outputs: { map: { kind: "inline", value: map } }, needs: {} };
+ });
+ host.registerProducer(captionProducers.temporalize, captionImplementationDigest, ({ inputs }) => {
+ calls.caption += 1;
+ assert.equal(inputs.narrative?.value.kind, "inline");
+ assert.equal(inputs.map?.value.kind, "inline");
+ const caption = temporalizeCaption(
+ inlineValue<Narrative>(inputs.narrative.value.value),
+ inlineValue<CompleteSemanticMap>(inputs.map.value.value),
+ );
+ return { outputs: { caption: { kind: "inline", value: caption } }, needs: {} };
+ });
+
+ const driver = new NodeDriver({ registry: host, providers });
+ const atEstimate = await driver.run(createVideoBuild());
+ assert.equal(atEstimate.blocked[0]?.reason, "missing-provider");
+ assert.match(atEstimate.blocked[0]?.subject ?? "", /OfficialSpeechDurationEstimate/u);
+
+ providers.registerProvider("runtime:official-estimate", videoCapabilities.estimate, videoTypes.estimate, () => ({
+ value: { kind: "inline", value: { durationSec: 1 } },
+ conformance: "exact",
+ delivery: "executed",
+ metadata: {},
+ }));
+ const atSeedance = await driver.run(parseBuildState(serializeBuildState(atEstimate.state)));
+ assert.equal(atSeedance.blocked[0]?.reason, "missing-provider");
+ assert.match(atSeedance.blocked[0]?.subject ?? "", /SeedanceMiniSpeechMedia/u);
+
+ providers.registerProvider(
+ "runtime:kie-seedance-mini",
+ videoCapabilities.seedanceMini,
+ videoTypes.seedanceMiniMedia,
+ ({ need }) => {
+ assert.deepEqual(need.constraints, {
+ contract: "example.seedance-mini-speech-request@1",
+ durationSec: 1,
+ model: "mini",
+ script: "what the fuck",
+ });
+ return {
+ value: { kind: "inline", value: {
+ model: "mini",
+ audioDigest: digestOf("artifact:audio"),
+ visualDigest: digestOf("artifact:visual"),
+ durationSec: 1,
+ } },
+ conformance: "exact",
+ delivery: "executed",
+ metadata: { provider: "kie", model: "seedance-mini" },
+ };
+ },
+ );
+ const atWhisperX = await driver.run(parseBuildState(serializeBuildState(atSeedance.state)));
+ assert.equal(atWhisperX.blocked[0]?.reason, "missing-provider");
+ assert.match(atWhisperX.blocked[0]?.subject ?? "", /WhisperXAlignmentEvidence/u);
+
+ const wrongBasisProviders = new ProviderRegistry();
+ wrongBasisProviders.registerProvider(
+ "runtime:wrong-basis-whisperx",
+ whisperXCapabilities.alignment,
+ whisperXTypes.alignmentEvidence,
+ () => ({
+ value: {
+ kind: "inline",
+ value: sealWhisperXAlignmentEvidence({
+ contract: "svml.whisperx-alignment-evidence@1",
+ engine: "whisperx",
+ basisDigest: digestOf("another-project:basis"),
+ audioArtifactDigest: digestOf("another-project:audio"),
+ programSpaceDigest: digestOf("another-project:program-space"),
+ rawEvidenceArtifactDigest: digestOf("another-project:whisperx-json"),
+ durationSec: 1,
+ segments: [{ sourceSegmentId: "line", startSec: 0, endSec: 1, words: [], chars: [] }],
+ }),
+ },
+ conformance: "exact",
+ delivery: "executed",
+ metadata: {},
+ }),
+ );
+ const rejectedEvidence = await new NodeDriver({ registry: host, providers: wrongBasisProviders }).run(
+ parseBuildState(serializeBuildState(atWhisperX.state)),
+ );
+ assert.equal(rejectedEvidence.status, "paused");
+ assert.match(rejectedEvidence.journal.at(-1)?.message ?? "", /different SpeechBasis|does not match/u);
+ const rejectedWhisperNeed = rejectedEvidence.state.needs.find((need) =>
+ sameCapability(need.capability, whisperXCapabilities.alignment));
+ assert(rejectedWhisperNeed);
+ assert.equal(
+ rejectedEvidence.state.records.some((record) =>
+ record.id === rejectedWhisperNeed.result),
+ false,
+ "Evidence for another same-duration audio projection must not enter BuildState",
+ );
+
+ providers.registerProvider(
+ "runtime:whisperx-local",
+ whisperXCapabilities.alignment,
+ whisperXTypes.alignmentEvidence,
+ ({ need }) => {
+ const request = inlineObject(need.constraints);
+ const audio = inlineObject(request.audio);
+ return {
+ value: {
+ kind: "inline",
+ value: sealWhisperXAlignmentEvidence({
+ contract: "svml.whisperx-alignment-evidence@1",
+ engine: "whisperx",
+ basisDigest: request.basisDigest as WhisperXAlignmentEvidence["basisDigest"],
+ audioArtifactDigest: audio.digest as WhisperXAlignmentEvidence["audioArtifactDigest"],
+ programSpaceDigest: request.programSpaceDigest as WhisperXAlignmentEvidence["programSpaceDigest"],
+ rawEvidenceArtifactDigest: digestOf("artifact:whisperx-json"),
+ durationSec: 1,
+ segments: [{
+ sourceSegmentId: "line",
+ startSec: 0,
+ endSec: 1,
+ words: [
+ { text: "what", startSec: 0.1, endSec: 0.25, score: 0.98 },
+ { text: "the", startSec: 0.3, endSec: 0.42, score: 0.98 },
+ { text: "fuck", startSec: 0.48, endSec: 0.72, score: 0.97 },
+ ],
+ chars: [],
+ }],
+ }),
+ },
+ conformance: "exact",
+ delivery: "executed",
+ metadata: { adapter: "whisperx.local", model: "fixture" },
+ };
+ },
+ );
+ const completed = await driver.run(parseBuildState(serializeBuildState(atWhisperX.state)));
+
+ assert.equal(completed.status, "complete");
+ assert.deepEqual(calls, {
+ estimate: 1,
+ seedance: 1,
+ assemble: 1,
+ projectAudio: 1,
+ projectVisual: 0,
+ whisperRequest: 1,
+ whisperNormalize: 1,
+ locate: 1,
+ caption: 1,
+ });
+ assert.deepEqual(completed.state.receipts.map((receipt) => receipt.fulfiller), [
+ "runtime:official-estimate",
+ "runtime:kie-seedance-mini",
+ "runtime:whisperx-local",
+ ]);
+ const captionRecord = completed.state.records.find((record) =>
+ record.id === selectedRecord(completed.state, videoOutputs.caption));
+ assert.equal(captionRecord?.value.kind, "inline");
+ const value = inlineValue<TimedCaptionProjection>(
+ captionRecord?.value.kind === "inline" ? captionRecord.value.value : {},
+ );
+ assert.deepEqual(
+ [value.text, value.regions[0]?.display, value.regions[0]?.startSec, value.regions[0]?.endSec],
+ ["that was insane", "that was insane", 0.1, 0.72],
+ );
+});
+
+test("Targets prune official Fragments while shared SpeechTake generation stays singular", () => {
+ const visual = createVideoBuild({ targets: ["visual"] });
+ assert.equal(producerCount(visual, videoProducers.requestEstimate), 1);
+ assert.equal(producerCount(visual, videoProducers.requestSeedanceMini), 1);
+ assert.equal(producerCount(visual, videoProducers.assembleBasis), 1);
+ assert.equal(producerCount(visual, speechTakeProducers.projectVisual), 1);
+ assert.equal(producerCount(visual, speechTakeProducers.projectAudio), 0);
+ assert.equal(producerCount(visual, whisperXProducers.request), 0);
+ assert.equal(producerCount(visual, captionProducers.temporalize), 0);
+
+ const map = createVideoBuild({ targets: ["map"] });
+ assert.equal(producerCount(map, speechTakeProducers.projectAudio), 1);
+ assert.equal(producerCount(map, speechTakeProducers.projectVisual), 0);
+ assert.equal(producerCount(map, whisperXProducers.request), 1);
+ assert.equal(producerCount(map, whisperXProducers.normalize), 1);
+ assert.equal(producerCount(map, speechAlignProducers.locate), 1);
+ assert.equal(producerCount(map, captionProducers.temporalize), 0);
+
+ const bothTakeProjections = createVideoBuild({ targets: ["audio", "visual"] });
+ assert.equal(producerCount(bothTakeProjections, videoProducers.requestSeedanceMini), 1);
+ assert.equal(producerCount(bothTakeProjections, videoProducers.assembleBasis), 1);
+ assert.equal(producerCount(bothTakeProjections, speechTakeProducers.projectAudio), 1);
+ assert.equal(producerCount(bothTakeProjections, speechTakeProducers.projectVisual), 1);
+
+ const bothEvidenceExports = createVideoBuild({ targets: ["rawEvidence", "map"] });
+ assert.equal(producerCount(bothEvidenceExports, whisperXProducers.request), 1);
+ assert.equal(producerCount(bothEvidenceExports, whisperXProducers.normalize), 1);
+ assert.equal(producerCount(bothEvidenceExports, speechAlignProducers.locate), 1);
+});
+
+test("an Existing SpeechTake cuts generation while a visual substitute cuts the whole upstream", () => {
+ const fixture = createVideoFixture();
+ const narrativeRecord = fixture.program.records.find((record) => record.id === "narrative:root");
+ assert.equal(narrativeRecord?.value.kind, "inline");
+ const narrative = inlineValue<Narrative>(
+ narrativeRecord?.value.kind === "inline" ? narrativeRecord.value.value : {},
+ );
+ const programSpace = sealProgramSpace({
+ contract: "svml.program-space@0",
+ durationSec: 1,
+ frameRate: { numerator: 1_000, denominator: 1 },
+ });
+ const visualDigest = digestOf("existing-take:visual");
+ const existingTake = sealSpeechBasis({
+ contract: "svml.speech-basis@1",
+ narrativeDigest: narrative.semanticIndex.digest,
+ programSpace,
+ audio: {
+ digest: digestOf("existing-take:audio"),
+ size: 1,
+ mediaType: "audio/wav",
+ durationSec: 1,
+ },
+ visualTrack: { clips: [{
+ segmentId: "line",
+ artifact: { digest: visualDigest, size: 1, mediaType: "video/mp4", durationSec: 1 },
+ startSec: 0,
+ endSec: 1,
+ }] },
+ segments: [{ segmentId: "line", startSec: 0, endSec: 1, sourceArtifactDigest: visualDigest }],
+ });
+ const takeCandidate = createProvidedCandidate({
+ output: videoOutputs.take,
+ value: { kind: "inline", value: existingTake },
+ fidelity: "exact",
+ provenance: { source: "approved-library", name: "opening-v3" },
+ });
+ const takeOverlay = sealRealizationOverlay({
+ sourceGraph: fixture.source.id,
+ candidates: [takeCandidate],
+ operations: [],
+ });
+ const withExistingTake = resolveRealization(fixture.program, fixture.source, [takeOverlay]);
+ const captionFromExisting = start(fixture.program, withExistingTake.graph, sealBuildRequest({
+ graph: withExistingTake.graph.id,
+ targets: [{ output: videoOutputs.caption, accepts: "exact" }],
+ bindings: [{ output: videoOutputs.take, candidate: takeCandidate.id }],
+ }));
+ assert.equal(producerCount(captionFromExisting, videoProducers.requestEstimate), 0);
+ assert.equal(producerCount(captionFromExisting, videoProducers.requestSeedanceMini), 0);
+ assert.equal(producerCount(captionFromExisting, videoProducers.assembleBasis), 0);
+ assert.equal(producerCount(captionFromExisting, speechTakeProducers.projectAudio), 1);
+ assert.equal(producerCount(captionFromExisting, whisperXProducers.request), 1);
+ assert.equal(producerCount(captionFromExisting, captionProducers.temporalize), 1);
+
+ const blackProgram = sealProgramSpace({
+ contract: "svml.program-space@0",
+ durationSec: 1,
+ frameRate: { numerator: 30, denominator: 1 },
+ });
+ const black: SpeechVisualTrack = {
+ contract: "svml.speech-visual-track@1",
+ basisDigest: digestOf("preview:black-basis"),
+ narrativeDigest: narrative.semanticIndex.digest,
+ programSpace: blackProgram,
+ visualTrack: { clips: [] },
+ segments: [{
+ segmentId: "line",
+ startSec: 0,
+ endSec: 1,
+ sourceArtifactDigest: digestOf("preview:black-artifact"),
+ }],
+ };
+ const blackCandidate = createProvidedCandidate({
+ output: videoOutputs.visual,
+ value: { kind: "inline", value: black },
+ fidelity: "substitute",
+ provenance: { method: "black-preview" },
+ });
+ const blackOverlay = sealRealizationOverlay({
+ sourceGraph: fixture.source.id,
+ candidates: [blackCandidate],
+ operations: [],
+ });
+ const withBlack = resolveRealization(fixture.program, fixture.source, [blackOverlay]);
+ const preview = start(fixture.program, withBlack.graph, sealBuildRequest({
+ graph: withBlack.graph.id,
+ targets: [{ output: videoOutputs.visual, accepts: "substitute" }],
+ bindings: [{ output: videoOutputs.visual, candidate: blackCandidate.id }],
+ }));
+ assert.deepEqual(preview.plan.steps, []);
+ assert.equal(preview.plan.initialValues.length, 1);
+});
+
+test("an exact Provider result cannot wash a substitute input back to exact", async () => {
+ const initial = createVideoBuild({
+ estimateRealization: "placeholder",
+ goalAccepts: "substitute",
+ });
+ const host = new HostRegistry();
+ host.registerProducer(
+ videoProducers.placeholderEstimate,
+ videoImplementations.placeholderEstimate,
+ () => ({ outputs: { estimate: { kind: "inline", value: { durationSec: 1 } } }, needs: {} }),
+ );
+ host.registerProducer(videoProducers.requestSeedanceMini, videoImplementations.requestSeedanceMini, () => ({
+ outputs: {},
+ needs: { media: { model: "mini" } },
+ }));
+ const providers = new ProviderRegistry();
+ providers.registerProvider(
+ "runtime:exact-seedance",
+ videoCapabilities.seedanceMini,
+ videoTypes.seedanceMiniMedia,
+ () => ({
+ value: { kind: "inline", value: {
+ model: "mini",
+ audioDigest: digestOf("floor:audio"),
+ visualDigest: digestOf("floor:visual"),
+ durationSec: 1,
+ } },
+ conformance: "exact",
+ delivery: "executed",
+ metadata: {},
+ }),
+ );
+
+ const result = await new NodeDriver({ registry: host, providers }).run(initial);
+ assert.equal(result.status, "paused", "the unregistered Basis assembler should pause after Seedance");
+ const seedanceNeed = result.state.needs.find((need) =>
+ sameCapability(need.capability, videoCapabilities.seedanceMini));
+ const seedanceReceipt = result.state.receipts.find((receipt) => receipt.need === seedanceNeed?.id);
+ const media = result.state.records.find((record) => record.id === seedanceReceipt?.output);
+ assert.equal(seedanceNeed?.conformanceFloor, "substitute");
+ assert.equal(seedanceReceipt?.fulfillmentConformance, "exact");
+ assert.equal(seedanceReceipt?.conformance, "substitute");
+ assert.equal(media?.conformance, "substitute");
+});
+
+test("an exact Target rejects an explicitly selected substitute realization", () => {
+ assert.throws(
+ () => createVideoBuild({ estimateRealization: "placeholder" }),
+ /selects a substitute path/u,
+ );
+});
diff --git a/packages/whisperx/README.md b/packages/whisperx/README.md
index d33e2d33..fe16b77f 100644
--- a/packages/whisperx/README.md
+++ b/packages/whisperx/README.md
@@ -7,3 +7,7 @@ a concrete WhisperX execution endpoint such as a trusted local worker or Hypit.
The package contains no credentials, Python environment or queue. Providers translate the typed
request constraints and return the canonical WhisperX result contract. A deterministic Producer
then lowers that result to provider-neutral `AlignedTranscriptEvidence`.
+
+The request Producer consumes only `SpeechAudioBasis`, never the visual SpeechTake projection.
+Producer result affinity requires returned Basis, audio Artifact and ProgramSpace digests to match
+that exact input before the Evidence can enter BuildState.
diff --git a/packages/whisperx/src/evidence.ts b/packages/whisperx/src/evidence.ts
index 9f8d0bf1..2f5299c3 100644
--- a/packages/whisperx/src/evidence.ts
+++ b/packages/whisperx/src/evidence.ts
@@ -1,8 +1,8 @@
import {
- assertSpeechBasisIdentity,
+ assertSpeechAudioBasisIdentity,
sealAlignedTranscriptEvidence,
} from "@svml/contracts";
-import type { AlignedTranscriptEvidence, SpeechBasis } from "@svml/contracts";
+import type { AlignedTranscriptEvidence, SpeechAudioBasis } from "@svml/contracts";
import { digestOf } from "@svml/core";
import type {
@@ -11,11 +11,11 @@ import type {
WhisperXEvidenceContent,
} from "./types.js";
-export function whisperXRequestForBasis(
- basis: SpeechBasis,
+export function whisperXRequestForAudioBasis(
+ basis: SpeechAudioBasis,
options: { readonly language?: string } = {},
): WhisperXAlignmentRequest {
- assertSpeechBasisIdentity(basis);
+ assertSpeechAudioBasisIdentity(basis);
return {
contract: "svml.whisperx-alignment-request@1",
basisDigest: basis.basisDigest,
diff --git a/packages/whisperx/src/index.ts b/packages/whisperx/src/index.ts
index 7a516254..9366d8cb 100644
--- a/packages/whisperx/src/index.ts
+++ b/packages/whisperx/src/index.ts
@@ -1,10 +1,11 @@
export {
normalizeWhisperXAlignment,
sealWhisperXAlignmentEvidence,
- whisperXRequestForBasis,
+ whisperXRequestForAudioBasis,
} from "./evidence.js";
export {
whisperXAlignmentEvidenceSchema,
+ whisperXCapabilities,
whisperXImplementationDigests,
whisperXManifest,
whisperXModuleRef,
diff --git a/packages/whisperx/src/manifest.ts b/packages/whisperx/src/manifest.ts
index f468ffb6..bb428f9d 100644
--- a/packages/whisperx/src/manifest.ts
+++ b/packages/whisperx/src/manifest.ts
@@ -5,12 +5,15 @@ import {
contractsModuleRef,
} from "@svml/contracts";
import { digestOf } from "@svml/core";
-import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@svml/protocol";
+import type { CapabilityRef, ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@svml/protocol";
export const whisperXModuleRef = { name: "@svml/whisperx", version: "0.0.0-dev" } as const;
export const whisperXTypes = {
alignmentEvidence: { module: whisperXModuleRef, name: "WhisperXAlignmentEvidence" },
} satisfies Record<string, TypeRef>;
+export const whisperXCapabilities = {
+ alignment: { module: whisperXModuleRef, name: "whisperx-alignment" },
+} satisfies Record<string, CapabilityRef>;
export const whisperXProducers = {
request: { module: whisperXModuleRef, name: "request-whisperx-alignment" },
normalize: { module: whisperXModuleRef, name: "normalize-whisperx-alignment" },
@@ -38,13 +41,26 @@ export const whisperXManifest: ModuleManifest = {
version: whisperXModuleRef.version,
dependencies: [{ module: contractsModuleRef, digest: contractsManifestDigest }],
types: [{ name: whisperXTypes.alignmentEvidence.name, schema: whisperXAlignmentEvidenceSchema }],
+ capabilities: [{
+ name: whisperXCapabilities.alignment.name,
+ returns: whisperXTypes.alignmentEvidence,
+ }],
surfaces: [],
producers: [
{
name: whisperXProducers.request.name,
- inputs: [{ name: "basis", type: contractTypes.speechBasis }],
+ inputs: [{ name: "audio", type: contractTypes.speechAudioBasis }],
outputs: [],
- needs: [{ name: "alignment", wants: whisperXTypes.alignmentEvidence }],
+ needs: [{
+ name: "alignment",
+ capability: whisperXCapabilities.alignment,
+ returns: whisperXTypes.alignmentEvidence,
+ affinity: [
+ { resultPointer: "/basisDigest", input: "audio", inputPointer: "/basisDigest" },
+ { resultPointer: "/audioArtifactDigest", input: "audio", inputPointer: "/audio/digest" },
+ { resultPointer: "/programSpaceDigest", input: "audio", inputPointer: "/programSpace/digest" },
+ ],
+ }],
implementation: {
kind: "registered",
locator: "@svml/whisperx/request",
@@ -54,7 +70,15 @@ export const whisperXManifest: ModuleManifest = {
{
name: whisperXProducers.normalize.name,
inputs: [{ name: "whisperx", type: whisperXTypes.alignmentEvidence }],
- outputs: [{ name: "evidence", type: contractTypes.alignedTranscriptEvidence }],
+ outputs: [{
+ name: "evidence",
+ type: contractTypes.alignedTranscriptEvidence,
+ affinity: [
+ { resultPointer: "/basisDigest", input: "whisperx", inputPointer: "/basisDigest" },
+ { resultPointer: "/audioArtifactDigest", input: "whisperx", inputPointer: "/audioArtifactDigest" },
+ { resultPointer: "/programSpaceDigest", input: "whisperx", inputPointer: "/programSpaceDigest" },
+ ],
+ }],
needs: [],
implementation: {
kind: "registered",
diff --git a/packages/whisperx/test/whisperx.test.ts b/packages/whisperx/test/whisperx.test.ts
index 55ae38df..8e8aa1e8 100644
--- a/packages/whisperx/test/whisperx.test.ts
+++ b/packages/whisperx/test/whisperx.test.ts
@@ -2,11 +2,12 @@ import assert from "node:assert/strict";
import test from "node:test";
import { sealProgramSpace, sealSpeechBasis } from "@svml/contracts";
+import type { SpeechAudioBasis, SpeechBasis } from "@svml/contracts";
import { digestOf } from "@svml/core";
import {
normalizeWhisperXAlignment,
sealWhisperXAlignmentEvidence,
- whisperXRequestForBasis,
+ whisperXRequestForAudioBasis,
} from "@svml/whisperx";
function basis() {
@@ -18,6 +19,7 @@ function basis() {
const visual = digestOf("whisperx-test:visual");
return sealSpeechBasis({
contract: "svml.speech-basis@1",
+ narrativeDigest: digestOf("whisperx-test:narrative"),
programSpace,
audio: { digest: digestOf("whisperx-test:audio"), size: 1, mediaType: "audio/wav", durationSec: 1 },
visualTrack: { clips: [{
@@ -30,11 +32,22 @@ function basis() {
});
}
-test("WhisperX request construction rejects a self-inconsistent SpeechBasis before fulfillment", () => {
- const valid = basis();
- assert.equal(whisperXRequestForBasis(valid).basisDigest, valid.basisDigest);
- const tampered = { ...valid, audio: { ...valid.audio, digest: digestOf("another-audio") } };
- assert.throws(() => whisperXRequestForBasis(tampered), /SpeechBasis digest/u);
+function audioProjection(basis: SpeechBasis): SpeechAudioBasis {
+ return {
+ contract: "svml.speech-audio-basis@1",
+ basisDigest: basis.basisDigest,
+ narrativeDigest: basis.narrativeDigest,
+ programSpace: basis.programSpace,
+ audio: basis.audio,
+ segments: basis.segments,
+ };
+}
+
+test("WhisperX consumes only the validated audio projection of a SpeechBasis", () => {
+ const valid = audioProjection(basis());
+ assert.equal(whisperXRequestForAudioBasis(valid).basisDigest, valid.basisDigest);
+ const tampered = { ...valid, audio: { ...valid.audio, durationSec: 2 } };
+ assert.throws(() => whisperXRequestForAudioBasis(tampered), /SpeechAudioBasis audio/u);
});
test("WhisperX normalization verifies its model-specific result before lowering to common Evidence", () => {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 71313ab6..329ffb12 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -43,9 +43,6 @@ importers:
packages/contracts:
dependencies:
- '@svml/core':
- specifier: workspace:*
- version: link:../core
'@svml/protocol':
specifier: workspace:*
version: link:../protocol
@@ -81,8 +78,37 @@ importers:
specifier: workspace:*
version: link:../whisperx
+ packages/elaborator:
+ dependencies:
+ '@svml/core':
+ specifier: workspace:*
+ version: link:../core
+ '@svml/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ devDependencies:
+ '@svml/contracts':
+ specifier: workspace:*
+ version: link:../contracts
+ '@svml/speech-take':
+ specifier: workspace:*
+ version: link:../speech-take
+
packages/protocol: {}
+ packages/realization:
+ dependencies:
+ '@svml/core':
+ specifier: workspace:*
+ version: link:../core
+ '@svml/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ devDependencies:
+ '@svml/elaborator':
+ specifier: workspace:*
+ version: link:../elaborator
+
packages/script:
dependencies:
'@svml/contracts':
@@ -111,6 +137,22 @@ importers:
specifier: workspace:*
version: link:../script
+ packages/speech-take:
+ dependencies:
+ '@svml/contracts':
+ specifier: workspace:*
+ version: link:../contracts
+ '@svml/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ devDependencies:
+ '@svml/core':
+ specifier: workspace:*
+ version: link:../core
+ '@svml/driver-node':
+ specifier: workspace:*
+ version: link:../driver-node
+
packages/text:
dependencies:
'@svml/core':
@@ -127,6 +169,43 @@ importers:
specifier: workspace:*
version: link:../script
+ packages/video-fragments:
+ dependencies:
+ '@svml/caption':
+ specifier: workspace:*
+ version: link:../caption
+ '@svml/contracts':
+ specifier: workspace:*
+ version: link:../contracts
+ '@svml/elaborator':
+ specifier: workspace:*
+ version: link:../elaborator
+ '@svml/speech-align':
+ specifier: workspace:*
+ version: link:../speech-align
+ '@svml/speech-take':
+ specifier: workspace:*
+ version: link:../speech-take
+ '@svml/whisperx':
+ specifier: workspace:*
+ version: link:../whisperx
+ devDependencies:
+ '@svml/core':
+ specifier: workspace:*
+ version: link:../core
+ '@svml/driver-node':
+ specifier: workspace:*
+ version: link:../driver-node
+ '@svml/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@svml/realization':
+ specifier: workspace:*
+ version: link:../realization
+ '@svml/script':
+ specifier: workspace:*
+ version: link:../script
+
packages/whisperx:
dependencies:
'@svml/contracts':
diff --git a/tsconfig.v2.json b/tsconfig.v2.json
index 84967af9..27a74af2 100644
--- a/tsconfig.v2.json
+++ b/tsconfig.v2.json
@@ -13,7 +13,11 @@
"@svml/text": ["packages/text/src/index.ts"],
"@svml/speech-align": ["packages/speech-align/src/index.ts"],
"@svml/whisperx": ["packages/whisperx/src/index.ts"],
- "@svml/caption": ["packages/caption/src/index.ts"]
+ "@svml/caption": ["packages/caption/src/index.ts"],
+ "@svml/speech-take": ["packages/speech-take/src/index.ts"],
+ "@svml/elaborator": ["packages/elaborator/src/index.ts"],
+ "@svml/realization": ["packages/realization/src/index.ts"],
+ "@svml/video-fragments": ["packages/video-fragments/src/index.ts"]
}
},
"include": ["packages/**/*.ts"],