Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
feat(v2): make sources self-described and require run graphs
kashorin6b4137deca40
diff --git a/README.md b/README.mdindex 8373a5af..07a95ced 100644--- a/README.md+++ b/README.md@@ -61,7 +61,8 @@ See [the architecture](docs/architecture.md) andThe repository implements:- domain-neutral Protocol, Core, graph elaboration and Node compiler Host;-- official `.svml` markup, Script Surface and `.svs` Recipes;+- mandatory self-described Author/Run sources with no suffix-selected or default parser;+- official `.svml` markup, Script Surface, `.svs` Recipes and `.svrun` execution intent;- locked trusted package activation without package-specific Core registration;- recoverable Runtime scheduling with concurrency lanes, retries and cancellation;- SQLite Build/Operation stores and filesystem/S3 Artifact stores;@@ -99,9 +100,8 @@ pnpm test# Compile a complete provider-free v2 author graph.pnpm svml:v2 check examples/talking-film-graph-check/main.svml-# Inspect a named target without executing external capabilities.-pnpm svml:v2 plan examples/talking-film-graph-check/main.svml \- --target final.video+# Compile the self-described Run Graph and inspect its finite plan.+pnpm svml:v2 plan examples/talking-film-graph-check/build.svrun```The live example uses an explicit Run Graph, declarative local Runtime Profile and external@@ -164,13 +164,15 @@ community Parser/Producer/Validator execution still needs a real isolation and ppackages/protocol immutable wire contractspackages/artifact domain-neutral content-addressed byte Typepackages/core domain-neutral Demand compiler and Build state machine+packages/source mandatory Source Header; no syntax defaultpackages/elaborator author declarations and hygienic Fragment expansionpackages/compiler-node reference Node compiler Hostpackages/compiler-text-node optional official Text compiler assemblypackages/package-loader-node syntax-neutral trusted physical-package loadingpackages/cli generic commands requiring an explicit Distributionpackages/video-cli official Text/video command Distribution-packages/run official human-readable Run Graph frontend+packages/run syntax-neutral Run Source closure and complete Run Graph compiler+packages/run-text optional official human-readable Run Frontendpackages/runtime environment-neutral scheduling and Store portspackages/driver-node trusted Node command executionpackages/local zero-service SQLite/filesystem developer assemblydiff --git a/docs/README.md b/docs/README.mdindex c7b9e9c3..11c8d43d 100644--- a/docs/README.md+++ b/docs/README.md@@ -26,6 +26,8 @@ the working tree contains only documents that should inform current implementatiRuntime, recovery and environment replacement.- [`build-archive-and-egress-v1.md`](./build-archive-and-egress-v1.md) — Targets, durable Records,Artifact retention and optional Host materialization as four separate concerns.+- [`source-and-run-compilation-v1.md`](./source-and-run-compilation-v1.md) — mandatory Source Header,+ peer Author/Run graphs, deterministic composition and compilation data gates.- package READMEs under [`../packages`](../packages) — executable APIs and ownership.## Video-domain specificationsdiff --git a/examples/talking-film-golden/README.md b/examples/talking-film-golden/README.mdindex fa0d201d..caa74991 100644--- a/examples/talking-film-golden/README.md+++ b/examples/talking-film-golden/README.md@@ -104,10 +104,10 @@ A Hypit profile changes endpoint bindings, not `main.svml`. Existing Values, blapreview realizations remain explicitly selected Candidates in a BuildRequest; they do not alterthe author source or teach Runtime to guess a creative method.-The intended final command is:+The intended final command uses the checked-in self-described Run Source:```bash-svml build main.svml --target final.video+svml build build.svrun --runtime ./svml.runtime.json```Until real assets, credentials and a Runtime profile are supplied, tools must report this file as adiff --git a/examples/talking-film-golden/build.svrun b/examples/talking-film-golden/build.svrunnew file mode 100644index 00000000..078d28de--- /dev/null+++ b/examples/talking-film-golden/build.svrun@@ -0,0 +1,8 @@+<?svml using="@svml/run-text@1"?>++<svrun version="1" targets="delivery">+ <author source="./main.svml"/>+ <target-set id="delivery">+ <target output="final.video" accepts="exact"/>+ </target-set>+</svrun>diff --git a/examples/talking-film-golden/main.svml b/examples/talking-film-golden/main.svmlindex 8bc84dae..9e32568d 100644--- a/examples/talking-film-golden/main.svml+++ b/examples/talking-film-golden/main.svml@@ -1,3 +1,5 @@+<?svml using="@svml/text@1"?>+<!--SVML authoring golden fixture.All provider-free author Surfaces are implemented. This golden intentionally@@ -16,7 +18,7 @@<import as="text" from="@svml/text-track@1"/><import as="film" from="@svml/film@1"/><import as="render" from="@svml/hyperframes-render@1"/>- <import as="studio" from="./studio.svs" using="@svml/svs@1"/>+ <import as="studio" source="./studio.svs"/><script>@alice-shotdiff --git a/examples/talking-film-golden/studio.svs b/examples/talking-film-golden/studio.svsindex d18ce33e..c7c0283c 100644--- a/examples/talking-film-golden/studio.svs+++ b/examples/talking-film-golden/studio.svs@@ -1,3 +1,5 @@+<?svml using="@svml/svs@1"?>+<sheet version="1" id="studio">/* Exact font bytes become FontArtifactRef values during author lowering. */diff --git a/examples/talking-film-graph-check/README.md b/examples/talking-film-graph-check/README.mdindex d00f0df5..a0538bc5 100644--- a/examples/talking-film-graph-check/README.md+++ b/examples/talking-film-graph-check/README.md@@ -7,7 +7,8 @@ HyperFrames.```bashpnpm svml:v2 check examples/talking-film-graph-check/main.svml-pnpm svml:v2 plan examples/talking-film-graph-check/main.svml --target final.video+pnpm svml:v2 check examples/talking-film-graph-check/build.svrun+pnpm svml:v2 plan examples/talking-film-graph-check/build.svrun```The Gemini planner receives immutable left-side display atoms and resolved style runs only. Its genericdiff --git a/examples/talking-film-graph-check/build.svrun b/examples/talking-film-graph-check/build.svrunnew file mode 100644index 00000000..078d28de--- /dev/null+++ b/examples/talking-film-graph-check/build.svrun@@ -0,0 +1,8 @@+<?svml using="@svml/run-text@1"?>++<svrun version="1" targets="delivery">+ <author source="./main.svml"/>+ <target-set id="delivery">+ <target output="final.video" accepts="exact"/>+ </target-set>+</svrun>diff --git a/examples/talking-film-graph-check/main.svml b/examples/talking-film-graph-check/main.svmlindex 034c43ed..92c52e9f 100644--- a/examples/talking-film-graph-check/main.svml+++ b/examples/talking-film-graph-check/main.svml@@ -1,3 +1,5 @@+<?svml using="@svml/text@1"?>+<svml><import from="@svml/script@1"/><import as="seedance" from="@svml/seedance@1"/>@@ -9,7 +11,7 @@<import as="text" from="@svml/text-track@1"/><import as="film" from="@svml/film@1"/><import as="render" from="@svml/hyperframes-render@1"/>- <import as="studio" from="./studio.svs" using="@svml/svs@1"/>+ <import as="studio" source="./studio.svs"/><script id="story"><opening><HOST>Meaning @demo becomes the source @/demo.</opening>diff --git a/examples/talking-film-graph-check/studio.svs b/examples/talking-film-graph-check/studio.svsindex a97bea8c..2d8ab52f 100644--- a/examples/talking-film-graph-check/studio.svs+++ b/examples/talking-film-graph-check/studio.svs@@ -1,3 +1,5 @@+<?svml using="@svml/svs@1"?>+<sheet version="1">film.vertical { width: 1080; height: 1920; frame-rate: 30; background: #09090B; }broll.card {diff --git a/examples/talking-film-live/README.md b/examples/talking-film-live/README.mdindex 2fc03de9..698f7618 100644--- a/examples/talking-film-live/README.md+++ b/examples/talking-film-live/README.md@@ -53,7 +53,9 @@ To reuse the paid shot outputs from a verified earlier Build, add two zero-inputCandidates and their explicit Satisfaction edges to another `.svrun`:```xml-<svrun version="1" source="./main.svml" targets="delivery">+<?svml using="@svml/run-text@1"?>+<svrun version="1" targets="delivery">+ <author source="./main.svml"/><target-set id="delivery"><target output="final.video" accepts="substitute"/></target-set>diff --git a/examples/talking-film-live/build.svrun b/examples/talking-film-live/build.svrunindex 17b0c2c1..078d28de 100644--- a/examples/talking-film-live/build.svrun+++ b/examples/talking-film-live/build.svrun@@ -1,4 +1,7 @@-<svrun version="1" source="./main.svml" targets="delivery">+<?svml using="@svml/run-text@1"?>++<svrun version="1" targets="delivery">+ <author source="./main.svml"/><target-set id="delivery"><target output="final.video" accepts="exact"/></target-set>diff --git a/examples/talking-film-live/main.svml b/examples/talking-film-live/main.svmlindex c02e8e20..b78245e2 100644--- a/examples/talking-film-live/main.svml+++ b/examples/talking-film-live/main.svml@@ -1,3 +1,5 @@+<?svml using="@svml/text@1"?>+<svml><import from="@svml/script@1"/><import as="media" from="@svml/media@1"/>@@ -10,7 +12,7 @@<import as="text" from="@svml/text-track@1"/><import as="film" from="@svml/film@1"/><import as="render" from="@svml/hyperframes-render@1"/>- <import as="studio" from="./studio.svs" using="@svml/svs@1"/>+ <import as="studio" source="./studio.svs"/><script id="story"><opening>diff --git a/examples/talking-film-live/studio.svs b/examples/talking-film-live/studio.svsindex 31471faa..0d952870 100644--- a/examples/talking-film-live/studio.svs+++ b/examples/talking-film-live/studio.svs@@ -1,3 +1,5 @@+<?svml using="@svml/svs@1"?>+<sheet version="1">film.vertical {width: 480;diff --git a/examples/v2-bootstrap/main.svml b/examples/v2-bootstrap/main.svmlindex 0ae4fd98..bc30a625 100644--- a/examples/v2-bootstrap/main.svml+++ b/examples/v2-bootstrap/main.svml@@ -1,6 +1,8 @@+<?svml using="@svml/text@1"?>+<svml><import from="@svml/script@1"/>- <import as="studio" from="./studio.svs" using="@svml/svs@1"/>+ <import as="studio" source="./studio.svs"/><script id="story"><opening>diff --git a/examples/v2-bootstrap/studio.svs b/examples/v2-bootstrap/studio.svsindex cbd83a5e..3c92e699 100644--- a/examples/v2-bootstrap/studio.svs+++ b/examples/v2-bootstrap/studio.svs@@ -1,3 +1,5 @@+<?svml using="@svml/svs@1"?>+<sheet version="1" id="studio">caption.host {fill: #FFFFFF;diff --git a/package.json b/package.jsonindex e952f773..7d12dbd5 100644--- a/package.json+++ b/package.json@@ -40,6 +40,7 @@"@svml/provider-kie": "workspace:*","@svml/provider-media-local": "workspace:*","@svml/provider-whisperx-local": "workspace:*",+ "@svml/run-text": "workspace:*","@types/node": "24.10.1","tsx": "4.21.0","typescript": "5.9.3"diff --git a/packages/cli/README.md b/packages/cli/README.mdindex 084e0a3d..c99058b1 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -3,13 +3,14 @@Domain-neutral command engine for Build compilation, execution, inspection and egress.The engine implements `lock-packages`, `check`, `plan`, `build`, `status`, `builds`, `inspect`, `get`-and `cancel`, but owns no default author vocabulary, entry Frontend or Provider adapter. Its caller+and `cancel`, but owns no default author vocabulary, Frontend or Provider adapter. Its callermust pass one explicit `CliDistribution`:```tstype CliDistribution = {name: string;builtInPackageContributions: readonly NodePackageContribution[];+ runFrontends: readonly RunFrontend[];createCompiler(options): NodeCompiler;createRuntimeFromConfig(path): Promise<LocalRuntime>;};@@ -19,3 +20,7 @@ A Distribution is trusted application assembly, not Core data or source-import aofficial `@svml/video-cli` selects `@svml/compiler-text-node`, `@svml/prelude-video` and the currentvideo Runtime adapters. Another domain can reuse this command engine without installing thosepackages.++`check` accepts any self-described Author or Run Source whose Header names a trusted Frontend.+`plan` and `build` require a Run Source. Targets, Candidate selections and substitute fidelity may+not be synthesized by CLI flags; they are visible Run Graph meaning.diff --git a/packages/cli/package.json b/packages/cli/package.jsonindex af536a43..37431789 100644--- a/packages/cli/package.json+++ b/packages/cli/package.json@@ -13,6 +13,7 @@"@svml/protocol": "workspace:*","@svml/realization": "workspace:*","@svml/run": "workspace:*",+ "@svml/source": "workspace:*","@svml/runtime": "workspace:*"}}diff --git a/packages/cli/src/distribution.ts b/packages/cli/src/distribution.tsindex 9e5ad0ca..f854b7f8 100644--- a/packages/cli/src/distribution.ts+++ b/packages/cli/src/distribution.ts@@ -1,6 +1,7 @@import type { NodeCompiler } from "@svml/compiler-node";import type { LocalRuntime } from "@svml/local";import type { NodePackageContribution } from "@svml/package-loader-node";+import type { RunFrontend } from "@svml/run";export type CliCompilerOptions = {readonly root?: string;@@ -16,6 +17,8 @@ export type CliCompilerOptions = {export type CliDistribution = {readonly name: string;readonly builtInPackageContributions: readonly NodePackageContribution[];+ /** Explicitly trusted Run Frontends; source Headers select among them without suffix defaults. */+ readonly runFrontends: readonly RunFrontend[];createCompiler(options: CliCompilerOptions): NodeCompiler;createRuntimeFromConfig(path: string): Promise<LocalRuntime>;};diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.tsindex 5ea08da7..2dc45de5 100644--- a/packages/cli/src/main.ts+++ b/packages/cli/src/main.ts@@ -4,10 +4,7 @@ import { pathToFileURL } from "node:url";import type { LocalRuntime } from "@svml/local";import type { NodeCompiledSourceClosure } from "@svml/compiler-node";import type { BuildCatalogDescriptor } from "@svml/runtime";-import {- createBuildRecordCandidate,- sealRealizationOverlay,-} from "@svml/realization";+import { parseSourceHeader } from "@svml/source";import {createNodePackageLock,loadNodePackageSet,@@ -23,7 +20,7 @@ import {selectArchivedRecord,summarizeBuildCatalog,} from "./archive.js";-import { loadRunFile } from "./run-file.js";+import { collectRunFrontends, loadRunFile } from "./run-file.js";import type { CliDistribution } from "./distribution.js";type CliIo = {@@ -205,11 +202,9 @@ function usage(): string {return ["usage:"," svml-v2 lock-packages <svml.packages.lock> --package installed-name [--package installed-name] [--root directory]",- " svml-v2 check <file.svml|file.svrun> [--runtime profile.json] [--package-lock file] [--root directory]",- " svml-v2 plan <file.svml> --target export [--target export] [--accept-substitute] [--package-lock file]",- " svml-v2 plan <file.svrun> [--runtime profile.json] [--package-lock file]",- " svml-v2 build <file.svml> --target export --runtime ./svml.runtime.ts [--pin output=prior-build --accept-substitute] [--follow]",- " svml-v2 build <file.svrun> --runtime profile.json [--follow]",+ " svml-v2 check <self-described-source> [--runtime profile.json] [--package-lock file] [--root directory]",+ " svml-v2 plan <run-source> [--runtime profile.json] [--package-lock file]",+ " svml-v2 build <run-source> --runtime profile.json|./svml.runtime.ts [--follow]"," svml-v2 status <build-id> --runtime profile.json|./svml.runtime.ts"," svml-v2 builds --runtime profile.json|./svml.runtime.ts"," svml-v2 inspect <build-id> --runtime profile.json|./svml.runtime.ts",@@ -301,9 +296,8 @@ export async function runCli(&& args.command !== "get") {throw new Error("--name, --record, --output, --artifact and --to are only valid for get");}- if (args.pins.length > 0 && args.command !== "build") throw new Error("--pin is only valid for build");- if (args.pins.length > 0 && !args.substitute) {- throw new Error("--pin attaches substitute Candidates; add --accept-substitute");+ if (args.targets.length > 0 || args.substitute || args.pins.length > 0) {+ throw new Error("Targets, Candidate selections and fidelity belong in a self-described Run Source; CLI --target, --pin and --accept-substitute are not supported");}if (args.command === "status" || args.command === "builds" || args.command === "inspect"|| args.command === "get" || args.command === "cancel") {@@ -424,50 +418,64 @@ export async function runCli(return;}if (args.packages.length > 0) throw new Error("--package is only valid for lock-packages");- const runMode = extname(args.file!) === ".svrun";- if (runMode && (args.targets.length > 0 || args.substitute || args.pins.length > 0)) {- throw new Error(".svrun owns Targets, Candidate selections and fidelity; do not combine it with --target, --pin or --accept-substitute");- }const loadedPackageSet = args.packageLock === undefined? undefined: await loadNodePackageSet(args.packageLock, args.root ?? dirname(args.packageLock));const packageContributions = loadedPackageSet?.contributions ?? distribution.builtInPackageContributions;+ const runFrontends = collectRunFrontends(distribution.runFrontends, packageContributions);const compiler = distribution.createCompiler({...(args.root === undefined ? {} : { root: args.root }),packageContributions,});+ const workspace = await compiler.openFile(args.file!);+ const sourceHeader = parseSourceHeader(workspace.entry.name, workspace.entry.text);+ const runMode = runFrontends.some((frontend) => frontend.id === sourceHeader.using);+ const authorMode = compiler.supportsFrontend(sourceHeader.using);+ if (runMode === authorMode) {+ throw new Error(runMode+ ? `Frontend ${sourceHeader.using} is ambiguously registered as Author and Run`+ : `No trusted Author or Run compiler accepts Frontend ${sourceHeader.using}`);+ }+ if ((args.command === "plan" || args.command === "build") && !runMode) {+ throw new Error(`${args.command} requires a self-described Run Source; check Author Sources independently`);+ }if (args.command === "check") {let runtime: LocalRuntime | undefined;try {runtime = args.runtime === undefined ? undefined : await loadLocalRuntime(args.runtime, distribution);if (runMode) {const loaded = await loadRunFile({- path: args.file!,- compiler,+ workspace,+ authorCompiler: compiler,+ frontends: runFrontends,packageContributions,...(runtime === undefined ? {} : { runtime }),});- const planned = compiler.planCompilation(loaded.compilation, {- targets: loaded.run.targets,- satisfactions: loaded.run.satisfactions,- realizations: loaded.run.graphs,- ...(loadedPackageSet === undefined ? {} : { implementationClosure: loadedPackageSet.lock.digest }),- });+ const planned = loaded.compiler.planCompilation(+ loaded,+ loadedPackageSet?.lock.digest,+ );+ const selected = loaded.run.graph.targetSets.find((item) => item.id === loaded.run.graph.selectedTargets)!;io.write(`${JSON.stringify({ok: true,run: loaded.path,- source: loaded.source,- sourceClosure: loaded.compilation.closure.id,+ source: loaded.authorSource,+ authorSourceClosure: loaded.author.closure.id,+ runSourceClosure: loaded.run.closure.id,+ authorModuleClosure: loaded.author.program.closure.digest,+ executionModuleClosure: loaded.program.closure.digest,+ authorGraph: loaded.author.elaboration.graph.id,+ runGraph: loaded.run.graph.id,graph: planned.request.graph,- targetSet: loaded.document.selectedTargets,- targets: loaded.run.targets,+ targetSet: loaded.run.graph.selectedTargets,+ targets: selected.targets,candidates: loaded.run.candidates,- satisfactions: loaded.run.satisfactions,+ satisfactions: loaded.run.graph.satisfactions,steps: planned.plan.steps.length,}, null, 2)}\n`);return;}- const result = await compiler.compileFile(args.file!);+ const result = await compiler.compileSource(workspace.entry, workspace);io.write(`${JSON.stringify({ok: true,sourceClosure: result.closure.id,@@ -487,71 +495,25 @@ export async function runCli(if (args.runtime === undefined) throw new Error("build requires --runtime with a Runtime Profile or trusted local config module");const runtime = await loadLocalRuntime(args.runtime, distribution);try {- const planOptions = {- targets: args.targets,- accepts: args.substitute ? "substitute" as const : "exact" as const,- ...(loadedPackageSet === undefined ? {} : { implementationClosure: loadedPackageSet.lock.digest }),- };- let pinSummary: readonly { readonly output: string; readonly build: string; readonly candidate: string }[] = [];- const loadedRun = runMode- ? await loadRunFile({ path: args.file!, compiler, packageContributions, runtime })- : undefined;- const result = loadedRun !== undefined- ? compiler.planCompilation(loadedRun.compilation, {- targets: loadedRun.run.targets,- satisfactions: loadedRun.run.satisfactions,- realizations: loadedRun.run.graphs,- ...(loadedPackageSet === undefined ? {} : { implementationClosure: loadedPackageSet.lock.digest }),- })- : args.pins.length === 0- ? await compiler.planFile(args.file!, planOptions)- : await (async () => {- const compilation = await compiler.compileFile(args.file!);- const seen = new Set<string>();- const candidates = [];- const satisfactions = [];- const summary = [];- for (const pin of args.pins) {- if (seen.has(pin.output)) throw new Error(`--pin repeats output ${pin.output}`);- seen.add(pin.output);- const exported = compilation.exports.find((item) => item.name === pin.output);- if (exported === undefined) throw new Error(`--pin refers to unknown public output ${pin.output}`);- if (exported.ref.kind !== "logical-output") {- throw new Error(`--pin ${pin.output} is an authored Record, not a realizable output`);- }- const historical = await runtime.status(pin.build);- if (historical.build === undefined) throw new Error(`--pin source Build ${pin.build} does not exist`);- const candidate = createBuildRecordCandidate({- build: historical.build.state,- sourceOutput: exported.ref.id,- });- candidates.push(candidate);- satisfactions.push({ output: exported.ref.id, candidate: candidate.id, fidelity: "substitute" as const });- summary.push({ output: pin.output, build: pin.build, candidate: candidate.id });- }- const overlay = sealRealizationOverlay({- sourceGraph: compilation.elaboration.graph.id,- candidates,- operations: [],- });- pinSummary = summary;- return compiler.planCompilation(compilation, {- ...planOptions,- satisfactions,- realizations: [overlay],- });- })();+ const loadedRun = await loadRunFile({+ workspace,+ authorCompiler: compiler,+ frontends: runFrontends,+ packageContributions,+ runtime,+ });+ const result = loadedRun.compiler.planCompilation(loadedRun, loadedPackageSet?.lock.digest);const built = await runtime.build({id: args.buildId ?? result.state.id,state: result.state,catalog: createCatalogDescriptor({core: result.state.id,- source: loadedRun?.source ?? args.file!,- compilation: result.compilation,- ...(loadedRun === undefined ? {} : { run: {+ source: loadedRun.authorSource,+ compilation: result.compilation.author,+ run: {path: loadedRun.path,- targetSet: loadedRun.document.selectedTargets,- } }),+ targetSet: loadedRun.run.graph.selectedTargets,+ },}),attachments: result.compilation.attachments,}, {@@ -573,7 +535,6 @@ export async function runCli(}),blocked: built.blocked,journal: built.journal,- ...(pinSummary.length === 0 ? {} : { pins: pinSummary }),}, null, 2)}\n`);} finally {await runtime.close();@@ -583,26 +544,14 @@ export async function runCli(let runtime: LocalRuntime | undefined;try {runtime = args.runtime === undefined ? undefined : await loadLocalRuntime(args.runtime, distribution);- const result = runMode- ? await (async () => {- const loaded = await loadRunFile({- path: args.file!,- compiler,- packageContributions,- ...(runtime === undefined ? {} : { runtime }),- });- return compiler.planCompilation(loaded.compilation, {- targets: loaded.run.targets,- satisfactions: loaded.run.satisfactions,- realizations: loaded.run.graphs,- ...(loadedPackageSet === undefined ? {} : { implementationClosure: loadedPackageSet.lock.digest }),- });- })()- : await compiler.planFile(args.file!, {- targets: args.targets,- accepts: args.substitute ? "substitute" : "exact",- ...(loadedPackageSet === undefined ? {} : { implementationClosure: loadedPackageSet.lock.digest }),- });+ const loaded = await loadRunFile({+ workspace,+ authorCompiler: compiler,+ frontends: runFrontends,+ packageContributions,+ ...(runtime === undefined ? {} : { runtime }),+ });+ const result = loaded.compiler.planCompilation(loaded, loadedPackageSet?.lock.digest);io.write(`${JSON.stringify(result.plan, null, 2)}\n`);} finally {await runtime?.close();diff --git a/packages/cli/src/run-file.ts b/packages/cli/src/run-file.tsindex 60aeee5d..bc26674b 100644--- a/packages/cli/src/run-file.ts+++ b/packages/cli/src/run-file.ts@@ -1,52 +1,58 @@-import { readFile } from "node:fs/promises";-import { dirname, resolve } from "node:path";--import type { NodeCompiler, NodeCompiledSourceClosure } from "@svml/compiler-node";+import {+ NodeRunCompiler,+} from "@svml/compiler-node";+import type {+ NodeCompiledRun,+ NodeCompiler,+} from "@svml/compiler-node";import type { LocalRuntime } from "@svml/local";import type { NodePackageContribution } from "@svml/package-loader-node";+import type { WorkspaceSession } from "@svml/host";import {- parseRunDocument,- resolveRunDocument,+ installRunFragmentHostFacets,RunFragmentRegistry,+ RunFrontendRegistry,} from "@svml/run";-import type { ResolvedRunDocument, RunDocument } from "@svml/run";+import type { RunFrontend } from "@svml/run";-export type LoadedRunFile = {+export type LoadedRunFile = NodeCompiledRun & {readonly path: string;- readonly source: string;- readonly document: RunDocument;- readonly compilation: NodeCompiledSourceClosure;- readonly run: ResolvedRunDocument;+ readonly compiler: NodeRunCompiler;};+export function collectRunFrontends(+ builtIns: readonly RunFrontend[],+ packages: readonly NodePackageContribution[],+): readonly RunFrontend[] {+ return [+ ...builtIns,+ ...packages.flatMap((item) => item.runFrontends ?? []),+ ];+}+export async function loadRunFile(options: {- readonly path: string;- readonly compiler: NodeCompiler;+ readonly workspace: WorkspaceSession;+ readonly authorCompiler: NodeCompiler;+ readonly frontends: readonly RunFrontend[];readonly packageContributions: readonly NodePackageContribution[];readonly runtime?: Pick<LocalRuntime, "status">;}): Promise<LoadedRunFile> {- const path = resolve(options.path);- const directory = dirname(path);- const document = parseRunDocument(path, await readFile(path, "utf8"));- const source = resolve(directory, document.source);- const compilation = await options.compiler.compileFile(source);const fragments = new RunFragmentRegistry();for (const item of options.packageContributions) {- if (item.runFragments === undefined || Object.keys(item.runFragments).length === 0) continue;- fragments.register({ name: item.name, fragments: item.runFragments });+ installRunFragmentHostFacets(item.hostFacets ?? [], fragments);}- const run = await resolveRunDocument(document, {- compilation,+ const frontends = new RunFrontendRegistry();+ for (const frontend of options.frontends) frontends.register(frontend);+ const compiler = new NodeRunCompiler({+ authorCompiler: options.authorCompiler,+ frontends,fragments,- async readStoredValue(from) {- return JSON.parse(await readFile(resolve(directory, from), "utf8"));- },- async readBuild(id) {- if (options.runtime === undefined) {- throw new Error(`Run Candidate uses Build ${id}; select a Runtime Profile so it can be resolved`);- }- return (await options.runtime.status(id)).build?.state;- },+ ...(options.runtime === undefined ? {} : {+ async readBuild(id: string) {+ return (await options.runtime!.status(id)).build?.state;+ },+ }),});- return { path, source, document, compilation, run };+ const compiled = await compiler.compileSource(options.workspace.entry, options.workspace);+ return { path: options.workspace.entry.id, compiler, ...compiled };}diff --git a/packages/compiler-node/README.md b/packages/compiler-node/README.mdindex 3666dd0a..fd06e4a5 100644--- a/packages/compiler-node/README.md+++ b/packages/compiler-node/README.md@@ -6,13 +6,16 @@ This package is outside Core. It connects a replaceable definition-time `Workspaimplemented compiler IR:```text-file + registered Frontends + registered manifests+Source Header + registered Frontends + registered manifests-> discovered Source/Module closure-> typed Source Closure-> Author Module + Graph- -> optional BuildPlan for named exports```+Every Author Source selects its own exact Frontend through the mandatory `@svml/source` Header.+The compiler has no suffix table and no entry-Frontend default. A recursively imported source may+select another Frontend without the importer choosing on its behalf.+`ModulePackageRegistry` maps author import spellings to exact, already trusted manifests and closestheir digest-bound dependencies. It does not install npm packages or execute module code. Anembedding application must register the manifests and matching Frontend/Surface implementations it@@ -35,10 +38,16 @@ SourceUnit recursion and Source Asset resolution are intentionally different capasset cannot import syntax, and a source import does not silently make arbitrary neighboring bytesavailable to package code.-`NodeCompiler` runs a discovery pass first because Frontends must be known before source decoding,+`NodeCompiler` runs a discovery pass first because Headers and imports must be known before source decoding,while the exact Module Closure must be known before typed Records can be verified. It then invokes-the ordinary Elaborator Source Closure implementation. `planFile()` resolves author-facing export-names to Logical Outputs and asks Core to derive the finite reverse-demand plan.+the ordinary Elaborator Source Closure implementation.++`NodeRunCompiler` is the separate dual-graph assembly. It compiles one self-described Run Source,+opens its explicitly named Author Source in the same Workspace session, resolves the complete Run+Graph, extends the execution Program Closure with Modules referenced only by selected Run+Fragments, binds Author and Run graph identities into the final immutable graph, and only then asks+Core for a finite BuildPlan. The Author Graph remains unchanged. There is no Author-only planning+shortcut.The package contains no Script, video, Provider, queue, credentials or rendering knowledge. Anon-video application can use it with only its own manifests, Frontends, Surfaces and chosendiff --git a/packages/compiler-node/package.json b/packages/compiler-node/package.jsonindex a78cc615..3fd5bc10 100644--- a/packages/compiler-node/package.json+++ b/packages/compiler-node/package.json@@ -12,6 +12,8 @@"@svml/host": "workspace:*","@svml/protocol": "workspace:*","@svml/realization": "workspace:*",+ "@svml/run": "workspace:*",+ "@svml/source": "workspace:*","@svml/validation": "workspace:*","@svml/workspace-fs-node": "workspace:*"},diff --git a/packages/compiler-node/src/compiler.ts b/packages/compiler-node/src/compiler.tsindex 92d1dff2..89a704b7 100644--- a/packages/compiler-node/src/compiler.ts+++ b/packages/compiler-node/src/compiler.ts@@ -1,13 +1,13 @@import { resolve } from "node:path";-import {- sealBuildRequest,- start,-} from "@svml/core";import {compileSourceClosure,- resolveCompiledSourceExport,+ prepareAuthorSource,} from "@svml/elaborator";+import {+ link,+ sealTypedModule,+} from "@svml/core";import type {AuthorFrontendRegistryLike,AuthorSourceDiscovery,@@ -16,15 +16,7 @@ import type {AuthorRecordAdmitter,} from "@svml/elaborator";import type { ArtifactAttachment, Workspace, WorkspaceSession } from "@svml/host";-import type {- BuildPlan,- BuildRequest,- BuildState,- Satisfaction,- NeedAcceptance,-} from "@svml/protocol";-import { resolveRealization } from "@svml/realization";-import type { RealizationOverlay } from "@svml/realization";+import type { LinkedProgram } from "@svml/protocol";import {TypeValidatorRegistry,createRecordAdmitter,@@ -43,13 +35,14 @@ type DiscoveredUnit = {async function discoverClosure(entry: AuthorSourceUnit,- frontendId: string,frontends: AuthorFrontendRegistryLike,workspace: WorkspaceSession,): Promise<readonly DiscoveredUnit[]> {const units = new Map<string, DiscoveredUnit>();const visiting = new Set<string>();- const visit = async (source: AuthorSourceUnit, selectedFrontend: string): Promise<void> => {+ const visit = async (source: AuthorSourceUnit): Promise<void> => {+ const prepared = prepareAuthorSource(source);+ const selectedFrontend = prepared.header.using;const key = `${source.id}\u0000${selectedFrontend}`;if (units.has(key)) return;if (visiting.has(key)) {@@ -60,21 +53,20 @@ async function discoverClosure(throw new NodeCompilerError("UNKNOWN_FRONTEND", `Frontend ${selectedFrontend} is not registered`, selectedFrontend);}visiting.add(key);- const discovery = await frontend.discover(source);+ const discovery = await frontend.discover(prepared);for (const request of discovery.sources) {- await visit(await workspace.resolveSource(source, request), request.frontend);+ await visit(await workspace.resolveSource(source, request));}visiting.delete(key);units.set(key, { source, frontend: selectedFrontend, discovery });};- await visit(entry, frontendId);+ await visit(entry);return [...units.values()];}export type NodeCompilerOptions = {readonly modules: ModulePackageRegistryLike;readonly frontends: AuthorFrontendRegistryLike;- readonly entryFrontend: string;/** Files reachable through source imports must resolve inside this root. Defaults to entry dirname. */readonly root?: string;/** Replaces the default Node filesystem definition environment. */@@ -85,31 +77,12 @@ export type NodeCompilerOptions = {readonly admitRecord?: AuthorRecordAdmitter;};-export type PlanFileOptions = {- readonly targets: readonly (string | {- readonly name: string;- readonly accepts: NeedAcceptance;- })[];- readonly accepts?: NeedAcceptance;- readonly satisfactions?: readonly Satisfaction[];- readonly implementationClosure?: import("@svml/protocol").Digest;- /** External Candidate attachments; never discovered from the author source. */- readonly realizations?: readonly RealizationOverlay[];-};--export type PlannedSource = {- readonly compilation: NodeCompiledSourceClosure;- readonly request: BuildRequest;- readonly plan: BuildPlan;- readonly state: BuildState;-};-export type NodeCompiledSourceClosure = CompiledSourceClosure & {/** Host-side transfer bundle; bytes are not serialized into Core BuildState. */readonly attachments: readonly ArtifactAttachment[];};-/** Domain-neutral Node facade from a real source file to a verified Source Closure or BuildPlan. */+/** Domain-neutral Node facade from a real Author Source to a verified Source Closure and Graph. */export class NodeCompiler {readonly #options: NodeCompilerOptions;readonly #admitRecord: AuthorRecordAdmitter;@@ -132,16 +105,28 @@ export class NodeCompiler {?? createRecordAdmitter(options.validators ?? new TypeValidatorRegistry());}- async compileFile(file: string): Promise<NodeCompiledSourceClosure> {- const workspace = this.#options.workspace === undefined+ supportsFrontend(id: string): boolean {+ return this.#options.frontends.resolve(id) !== undefined;+ }++ /** Open one read-once Workspace session so a Host can inspect the Source Header and compile it once. */+ async openFile(file: string): Promise<WorkspaceSession> {+ return this.#options.workspace === undefined? await new NodeFilesystemWorkspace({...(this.#options.root === undefined ? {} : { root: this.#options.root }),}).open(resolve(file)): await this.#options.workspace.open(file);- const entry = workspace.entry;+ }++ async compileFile(file: string): Promise<NodeCompiledSourceClosure> {+ const workspace = await this.openFile(file);+ return await this.compileSource(workspace.entry, workspace);+ }++ /** Compile an explicitly resolved self-describing SourceUnit inside one already isolated Workspace. */+ async compileSource(entry: AuthorSourceUnit, workspace: WorkspaceSession): Promise<NodeCompiledSourceClosure> {const discovered = await discoverClosure(entry,- this.#options.entryFrontend,this.#options.frontends,workspace,);@@ -150,7 +135,6 @@ export class NodeCompiler {);const compilation = await compileSourceClosure({entry,- frontend: this.#options.entryFrontend,closure,frontends: this.#options.frontends,resolveSource: workspace.resolveSource,@@ -160,53 +144,27 @@ export class NodeCompiler {return { ...compilation, attachments: await workspace.attachments() };}- async planFile(file: string, options: PlanFileOptions): Promise<PlannedSource> {- if (options.targets.length === 0) {- throw new NodeCompilerError("EMPTY_BUILD_TARGETS", "plan requires at least one public source export");+ /**+ * Add modules used only by Run implementations without changing Author records or Author Graph+ * identity. Typed Modules are rebound to the larger verified closure before Core sees Run code.+ */+ extendExecutionProgram(program: LinkedProgram, requests: readonly string[]): LinkedProgram {+ const existing = program.closure.modules.map((item) => `${item.ref.name}@${item.ref.version}`);+ const closure = this.#options.modules.createClosure([...existing, ...requests]);+ if (closure.digest === program.closure.digest) return program;+ const rebound = program.modules.map((module) => sealTypedModule({+ id: module.id,+ closureDigest: closure.digest,+ records: module.records,+ }));+ const extended = link(closure, rebound);+ if (extended.semanticDigest !== program.semanticDigest) {+ throw new NodeCompilerError(+ "EXECUTION_PROGRAM_SEMANTIC_DRIFT",+ "Run-only Module closure extension changed Author program semantics",+ );}- const compilation = await this.compileFile(file);- return this.planCompilation(compilation, options);+ return extended;}- planCompilation(compilation: NodeCompiledSourceClosure, options: PlanFileOptions): PlannedSource {- if (options.targets.length === 0) {- throw new NodeCompilerError("EMPTY_BUILD_TARGETS", "plan requires at least one public source export");- }- const graph = options.realizations === undefined || options.realizations.length === 0- ? compilation.elaboration.graph- : resolveRealization(- compilation.program,- compilation.elaboration.graph,- options.realizations,- ).graph;- const targets = options.targets.map((target) => {- const name = typeof target === "string" ? target : target.name;- const exported = resolveCompiledSourceExport(compilation, name);- if (exported.ref.kind !== "logical-output") {- throw new NodeCompilerError(- "TARGET_IS_AUTHORED_RECORD",- `${name} is an authored Record, not a realizable component output`,- name,- );- }- return {- output: exported.ref.id,- accepts: typeof target === "string" ? options.accepts ?? "exact" : target.accepts,- } as const;- });- const request = sealBuildRequest({- graph: graph.id,- ...(options.implementationClosure === undefined- ? {}- : { implementationClosure: options.implementationClosure }),- targets,- satisfactions: options.satisfactions ?? [],- });- const state = start(- compilation.program,- graph,- request,- );- return { compilation, request, plan: state.plan, state };- }}diff --git a/packages/compiler-node/src/index.ts b/packages/compiler-node/src/index.tsindex 08c5c82a..7f3797a7 100644--- a/packages/compiler-node/src/index.ts+++ b/packages/compiler-node/src/index.ts@@ -7,9 +7,13 @@ export type {RegisteredModulePackage,} from "./modules.js";export { NodeCompiler } from "./compiler.js";+export { NodeRunCompiler } from "./run.js";export type {NodeCompilerOptions,NodeCompiledSourceClosure,- PlannedSource,- PlanFileOptions,} from "./compiler.js";+export type {+ NodeCompiledRun,+ NodeRunCompilerOptions,+ PlannedBuild,+} from "./run.js";diff --git a/packages/compiler-node/src/run.ts b/packages/compiler-node/src/run.tsnew file mode 100644index 00000000..2314f010--- /dev/null+++ b/packages/compiler-node/src/run.ts@@ -0,0 +1,179 @@+import type { Workspace, WorkspaceSession } from "@svml/host";+import {+ sealBuildRequest,+ sealCompiledGraph,+ start,+} from "@svml/core";+import type {+ ArtifactAttachment,+} from "@svml/host";+import type {+ BuildPlan,+ BuildRequest,+ BuildState,+ BuildState as ArchivedBuildState,+ Digest,+ StoredValue,+} from "@svml/protocol";+import { resolveRealization } from "@svml/realization";+import {+ collectRunModuleRequests,+ compileRunSource,+ resolveRunDocument,+} from "@svml/run";+import type {+ RunCompilation,+ RunFragmentRegistryLike,+ RunFrontendRegistryLike,+ RunSourceUnit,+} from "@svml/run";+import type { LinkedProgram } from "@svml/protocol";+import { NodeFilesystemWorkspace } from "@svml/workspace-fs-node";+import { resolve } from "node:path";++import type { NodeCompiledSourceClosure } from "./compiler.js";+import { NodeCompiler } from "./compiler.js";++export type NodeRunCompilerOptions = {+ readonly authorCompiler: NodeCompiler;+ readonly frontends: RunFrontendRegistryLike;+ readonly fragments: RunFragmentRegistryLike;+ readonly root?: string;+ readonly workspace?: Workspace;+ readonly readBuild?: (id: string) => Promise<ArchivedBuildState | undefined> | ArchivedBuildState | undefined;+};++export type NodeCompiledRun = {+ readonly source: string;+ readonly authorSource: string;+ readonly author: NodeCompiledSourceClosure;+ /** Author program rebound to the union closure required by Author and selected Run code. */+ readonly program: LinkedProgram;+ readonly run: RunCompilation;+ readonly attachments: readonly ArtifactAttachment[];+};++export type PlannedBuild = {+ readonly compilation: NodeCompiledRun;+ readonly request: BuildRequest;+ readonly plan: BuildPlan;+ readonly state: BuildState;+};++function decodeStoredValue(bytes: Uint8Array, from: string): StoredValue {+ let parsed: unknown;+ try {+ parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));+ } catch (error) {+ throw new Error(`${from} is not valid UTF-8 StoredValue JSON: ${error instanceof Error ? error.message : String(error)}`);+ }+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {+ throw new Error(`${from} must contain one StoredValue object`);+ }+ return parsed as StoredValue;+}++async function storedValueFromWorkspace(+ workspace: WorkspaceSession,+ source: RunSourceUnit,+ from: string,+): Promise<StoredValue> {+ const resolved = await workspace.resolveAsset(source, { from, mediaType: "application/json" });+ const attachment = (await workspace.attachments()).find((item) => item.artifact.digest === resolved.artifact.digest);+ if (attachment === undefined) throw new Error(`Workspace did not retain bytes for ${from}`);+ return decodeStoredValue(attachment.bytes, from);+}++/** Node Host for the second, mandatory source graph. It never guesses a Frontend from a suffix. */+export class NodeRunCompiler {+ readonly #options: NodeRunCompilerOptions;++ constructor(options: NodeRunCompilerOptions) {+ if (options.workspace !== undefined && options.root !== undefined) {+ throw new Error("NodeRunCompiler accepts a Workspace or root, not both");+ }+ this.#options = options;+ }++ supportsFrontend(id: string): boolean {+ return this.#options.frontends.resolve(id) !== undefined;+ }++ async compileFile(file: string): Promise<NodeCompiledRun> {+ const workspace = this.#options.workspace === undefined+ ? await new NodeFilesystemWorkspace({+ ...(this.#options.root === undefined ? {} : { root: this.#options.root }),+ }).open(resolve(file))+ : await this.#options.workspace.open(file);+ return await this.compileSource(workspace.entry, workspace);+ }++ /** Compile both source graphs in one read-once Workspace session selected by the Host. */+ async compileSource(source: RunSourceUnit, workspace: WorkspaceSession): Promise<NodeCompiledRun> {+ const decoded = await compileRunSource(source, this.#options.frontends);+ const authorSource = await workspace.resolveSource(source, {+ from: decoded.document.author.source,+ alias: "author",+ });+ const author = await this.#options.authorCompiler.compileSource(authorSource, workspace);+ const program = this.#options.authorCompiler.extendExecutionProgram(+ author.program,+ collectRunModuleRequests(decoded.document, this.#options.fragments),+ );+ const executionCompilation = program === author.program ? author : { ...author, program };+ const readBuild = this.#options.readBuild;+ const run = await resolveRunDocument(decoded.document, {+ compilation: executionCompilation,+ sourceClosure: decoded.closure,+ fragments: this.#options.fragments,+ readStoredValue: async (from) => await storedValueFromWorkspace(workspace, source, from),+ async readBuild(id) {+ if (readBuild === undefined) throw new Error(`Run refers to Build ${id}, but the Host has no BuildArchive`);+ return await readBuild(id);+ },+ });+ return {+ source: source.id,+ authorSource: authorSource.id,+ author,+ program,+ run,+ attachments: await workspace.attachments(),+ };+ }++ planCompilation(compilation: NodeCompiledRun, implementationClosure?: Digest): PlannedBuild {+ const authorGraph = compilation.author.elaboration.graph;+ const realized = compilation.run.overlay === undefined+ ? authorGraph+ : resolveRealization(+ compilation.program,+ authorGraph,+ [compilation.run.overlay],+ ).graph;+ const graph = sealCompiledGraph({+ program: realized.program,+ source: authorGraph.id,+ realization: compilation.run.graph.id,+ outputs: realized.outputs,+ candidates: realized.candidates,+ operations: realized.operations,+ });+ const selected = compilation.run.graph.targetSets.find(+ (item) => item.id === compilation.run.graph.selectedTargets,+ );+ if (selected === undefined) throw new Error(`Run Graph selects absent Target Set ${compilation.run.graph.selectedTargets}`);+ const request = sealBuildRequest({+ graph: graph.id,+ ...(implementationClosure === undefined ? {} : { implementationClosure }),+ targets: selected.targets,+ satisfactions: compilation.run.graph.satisfactions,+ });+ const state = start(compilation.program, graph, request);+ return { compilation, request, plan: state.plan, state };+ }++ async planFile(file: string, implementationClosure?: Digest): Promise<PlannedBuild> {+ return this.planCompilation(await this.compileFile(file), implementationClosure);+ }+}diff --git a/packages/compiler-node/test/compiler.test.ts b/packages/compiler-node/test/compiler.test.tsindex 526b38e3..ea997971 100644--- a/packages/compiler-node/test/compiler.test.ts+++ b/packages/compiler-node/test/compiler.test.ts@@ -15,6 +15,7 @@ import {ModulePackageRegistry,NodeCompiler,NodeCompilerError,+ NodeRunCompiler,} from "@svml/compiler-node";import {computeModuleDigest,@@ -37,12 +38,17 @@ import type {ProducerRef,TypeRef,} from "@svml/protocol";+import { SourceHeaderError } from "@svml/source";+import {+ RunFragmentRegistry,+ RunFrontendRegistry,+} from "@svml/run";+import { runTextFrontend } from "@svml/run-text";import type { Workspace } from "@svml/host";import { WorkspaceError } from "@svml/host";import {createTextAuthorFrontend,TextSurfaceRegistry,- textAuthorFrontendId,} from "@svml/text";import { NodeFilesystemWorkspace } from "@svml/workspace-fs-node";@@ -176,9 +182,10 @@ const assetManifest: ModuleManifest = {}],};-function compiler(root: string): NodeCompiler {+function compiler(root: string, additional: readonly ModuleManifest[] = []): NodeCompiler {const modules = new ModulePackageRegistry();modules.register({ manifest: laboratoryManifest });+ for (const manifest of additional) modules.register({ manifest });const surfaces = new TextSurfaceRegistry();surfaces.registerStructured(laboratory, "result", surfaceDigest, ({ element }) => {const id = element.attributes.id;@@ -204,9 +211,47 @@ function compiler(root: string): NodeCompiler {return resolved;},}));- return new NodeCompiler({ modules, frontends, entryFrontend: textAuthorFrontendId, root });+ return new NodeCompiler({ modules, frontends, root });}+const previewModule = { name: "example.compiler-preview", version: "1" } as const;+const previewProducer = { module: previewModule, name: "preview" } satisfies ProducerRef;+const previewManifest: ModuleManifest = {+ ...emptyManifest(previewModule.name),+ dependencies: [{+ module: laboratory,+ digest: computeModuleDigest(laboratoryManifest),+ }],+ producers: [{+ name: previewProducer.name,+ inputs: [],+ outputs: [{ name: "result", type: resultType }],+ needs: [],+ implementation: {+ kind: "registered",+ locator: "example.compiler-preview/preview",+ digest: digestOf("example.compiler-preview/preview@1"),+ },+ }],+};+const previewFragment = sealGraphFragment({+ name: "example.compiler-preview/preview@1",+ inputs: [],+ operations: [{+ id: "preview",+ producer: previewProducer,+ inputs: {},+ result: { kind: "output", name: "result" },+ }],+ exports: [{+ name: "result",+ type: resultType,+ root: { kind: "fragment-operation", operation: "preview" },+ semanticInputs: [],+ fidelity: "substitute",+ }],+});+function assetCompiler(environment: { readonly root: string } | { readonly workspace: Workspace }): NodeCompiler {const modules = new ModulePackageRegistry();modules.register({ manifest: assetManifest });@@ -231,7 +276,7 @@ function assetCompiler(environment: { readonly root: string } | { readonly worksreturn resolved;},}));- return new NodeCompiler({ modules, frontends, entryFrontend: textAuthorFrontendId, ...environment });+ return new NodeCompiler({ modules, frontends, ...environment });}function memoryWorkspace(sourceText: string, assetBytes: Uint8Array): Workspace {@@ -268,10 +313,11 @@ function memoryWorkspace(sourceText: string, assetBytes: Uint8Array): Workspace};}-test("Node Compiler discovers real imports and plans a named public export", async () => {+test("Node Compiler discovers real imports and emits a named public Author Graph export", async () => {const root = await mkdtemp(join(tmpdir(), "svml-compiler-node-"));const file = join(root, "main.svml");- await writeFile(file, `<svml>+ await writeFile(file, `<?svml using="@svml/text@1"?>+ <svml><import as="lab" from="example.compiler-lab@1"/><lab:Result id="hello"/></svml>`, "utf8");@@ -280,17 +326,78 @@ test("Node Compiler discovers real imports and plans a named public export", asyassert.equal(compiled.exports[0]?.name, "hello.result");assert.equal(compiled.elaboration.graph.outputs.length, 1);- const planned = await compiler(root).planFile(file, { targets: ["hello.result"] });+});++test("Author Frontend identity comes only from the mandatory Source Header, never the suffix", async () => {+ const root = await mkdtemp(join(tmpdir(), "svml-self-described-source-"));+ const text = `<?svml using="@svml/text@1"?>+ <svml>+ <import as="lab" from="example.compiler-lab@1"/>+ <lab:Result id="hello"/>+ </svml>`;+ const svml = join(root, "main.svml");+ const arbitrary = join(root, "main.anything");+ await writeFile(svml, text, "utf8");+ await writeFile(arbitrary, text, "utf8");+ const first = await compiler(root).compileFile(svml);+ const second = await compiler(root).compileFile(arbitrary);+ assert.equal(first.closure.id, second.closure.id);+ assert.equal(first.elaboration.graph.id, second.elaboration.graph.id);++ const missing = join(root, "missing.svml");+ await writeFile(missing, "<svml/>", "utf8");+ await assert.rejects(+ compiler(root).compileFile(missing),+ (error: unknown) => error instanceof SourceHeaderError && error.code === "SOURCE_HEADER_MISSING",+ );+});++test("Run-only Fragment modules extend the execution closure without polluting the Author Graph", async () => {+ const root = await mkdtemp(join(tmpdir(), "svml-dual-graph-closure-"));+ const authorFile = join(root, "main.svml");+ const runFile = join(root, "build.svrun");+ await writeFile(authorFile, `<?svml using="@svml/text@1"?>+ <svml>+ <import as="lab" from="example.compiler-lab@1"/>+ <lab:Result id="hello"/>+ </svml>`, "utf8");+ await writeFile(runFile, `<?svml using="@svml/run-text@1"?>+ <svrun version="1" targets="preview">+ <author source="./main.svml"/>+ <import from="@example/preview" as="preview"/>+ <target-set id="preview"><target output="hello.result" accepts="substitute"/></target-set>+ <fragment id="one" using="preview:result"/>+ <satisfy output="hello.result" candidate="one.result" fidelity="substitute"/>+ </svrun>`, "utf8");++ const authorCompiler = compiler(root, [previewManifest]);+ const frontends = new RunFrontendRegistry();+ frontends.register(runTextFrontend);+ const fragments = new RunFragmentRegistry();+ fragments.register({ name: "@example/preview", fragments: { result: previewFragment } });+ const runCompiler = new NodeRunCompiler({ authorCompiler, frontends, fragments, root });+ const compiled = await runCompiler.compileFile(runFile);+ const planned = runCompiler.planCompilation(compiled);++ assert.deepEqual(+ compiled.author.program.closure.modules.map((item) => item.ref.name),+ [laboratory.name],+ );+ assert.deepEqual(+ compiled.program.closure.modules.map((item) => item.ref.name).sort(),+ [laboratory.name, previewModule.name].sort(),+ );+ assert.equal(compiled.run.graph.authorGraph, compiled.author.elaboration.graph.id);assert.equal(planned.plan.steps.length, 1);- assert.equal(planned.plan.steps[0]?.producer.name, "produce");- assert.equal(planned.plan.goals.length, 1);+ assert.equal(planned.plan.steps[0]?.producer.name, previewProducer.name);});test("source assets are content addressed, closure-bound and returned as a Host transfer bundle", async () => {const root = await mkdtemp(join(tmpdir(), "svml-source-assets-"));const file = join(root, "main.svml");const asset = join(root, "reference.bin");- await writeFile(file, `<svml>+ await writeFile(file, `<?svml using="@svml/text@1"?>+ <svml><import as="asset" from="example.asset-lab@1"/><asset:Asset id="reference" src="./reference.bin"/></svml>`, "utf8");@@ -343,7 +450,7 @@ test("filesystem Workspace contains symlinks and reads each canonical source onlassert.equal((await new NodeFilesystemWorkspace({ root }).open(entryPath)).entry.text, "second");assert.equal(entry.text, "first");assert.equal(await readFile(entryPath, "utf8"), "second");- const sourceRequest = { from: "./included.svs", alias: "included", frontend: "example.frontend@1" };+ const sourceRequest = { from: "./included.svs", alias: "included" };const firstIncluded = await workspace.resolveSource(entry, sourceRequest);await writeFile(includedPath, "included-second", "utf8");assert.deepEqual(await workspace.resolveSource(entry, sourceRequest), firstIncluded);@@ -359,7 +466,6 @@ test("filesystem Workspace contains symlinks and reads each canonical source onlasync () => await workspace.resolveSource(entry, {from: "./escaped.svs",alias: "escaped",- frontend: "example.frontend@1",}),(error: unknown) => error instanceof WorkspaceError && error.code === "SOURCE_OUTSIDE_ROOT",);@@ -375,7 +481,8 @@ test("filesystem Workspace contains symlinks and reads each canonical source onltest("filesystem and in-memory Workspaces compile identical source and bytes to one semantic result", async () => {const root = await mkdtemp(join(tmpdir(), "svml-workspace-equivalence-"));const file = join(root, "main.svml");- const source = `<svml>+ const source = `<?svml using="@svml/text@1"?>+ <svml><import as="asset" from="example.asset-lab@1"/><asset:Asset id="reference" src="./reference.bin"/></svml>`;diff --git a/packages/compiler-text-node/README.md b/packages/compiler-text-node/README.mdindex 416f3cda..3625d22c 100644--- a/packages/compiler-text-node/README.md+++ b/packages/compiler-text-node/README.md@@ -6,6 +6,7 @@ The package selects the Text Frontend ABI, installs Text Surface Host facets fropackage contributions, and combines them with the syntax-neutral `@svml/compiler-node`. It does notdiscover packages, grant Runtime authority or know any video component by name.-Use `@svml/compiler-node` directly for another entry Frontend. Use+Every compiled source selects Text—or another registered Frontend—through its mandatory Source+Header. Use `@svml/compiler-node` directly for another Frontend assembly. Use`@svml/package-loader-node` independently when a Runtime only needs locked deterministic computefacets and no author syntax.diff --git a/packages/compiler-text-node/src/index.ts b/packages/compiler-text-node/src/index.tsindex b92767fa..fef738f1 100644--- a/packages/compiler-text-node/src/index.ts+++ b/packages/compiler-text-node/src/index.ts@@ -40,7 +40,7 @@ export function createTextNodeCompiler(names.add(item.name);for (const module of item.modules ?? []) modules.register(module);installTextSurfaceHostFacets(item.hostFacets ?? [], surfaces);- for (const frontend of item.frontends ?? []) frontends.register(frontend);+ for (const frontend of item.authorFrontends ?? []) frontends.register(frontend);}for (const component of collectNodePackageComponents(packages)) {@@ -60,7 +60,6 @@ export function createTextNodeCompiler(modules,frontends,validators,- entryFrontend: textAuthorFrontendId,...(options.root === undefined ? {} : { root: options.root }),...(options.workspace === undefined ? {} : { workspace: options.workspace }),});diff --git a/packages/compiler-text-node/test/compiler.test.ts b/packages/compiler-text-node/test/compiler.test.tsindex ad3dd8b8..f9b11efe 100644--- a/packages/compiler-text-node/test/compiler.test.ts+++ b/packages/compiler-text-node/test/compiler.test.ts@@ -76,7 +76,8 @@ test("Text compiler alone selects Text Surface Host facets from a generic packagconst root = await mkdtemp(join(tmpdir(), "svml-text-compiler-"));try {const source = join(root, "main.svml");- await writeFile(source, `<svml>+ await writeFile(source, `<?svml using="@svml/text@1"?>+ <svml><import as="example" from="example.card@1"/><example:Card/></svml>`, "utf8");diff --git a/packages/elaborator/package.json b/packages/elaborator/package.jsonindex 4efab3be..966a9ef6 100644--- a/packages/elaborator/package.json+++ b/packages/elaborator/package.json@@ -8,7 +8,8 @@},"dependencies": {"@svml/core": "workspace:*",- "@svml/protocol": "workspace:*"+ "@svml/protocol": "workspace:*",+ "@svml/source": "workspace:*"},"devDependencies": {"@svml/contracts": "workspace:*",diff --git a/packages/elaborator/src/index.ts b/packages/elaborator/src/index.tsindex f1dae68e..eef54e19 100644--- a/packages/elaborator/src/index.ts+++ b/packages/elaborator/src/index.ts@@ -17,11 +17,13 @@ export {AuthorFrontendRegistry,SourceClosureError,compileSourceClosure,+ prepareAuthorSource,resolveCompiledSourceExport,verifySourceClosure,} from "./source.js";export type {AuthorFrontend,+ AuthorFrontendSourceUnit,AuthorFrontendRegistryLike,AuthorSourceDecodeContext,AuthorSourceDiscovery,diff --git a/packages/elaborator/src/source.ts b/packages/elaborator/src/source.tsindex 792f48ad..a14375a8 100644--- a/packages/elaborator/src/source.ts+++ b/packages/elaborator/src/source.ts@@ -18,6 +18,11 @@ import type {TypedModule,TypedRecord,} from "@svml/protocol";+import {+ maskSourceHeader,+ parseSourceHeader,+} from "@svml/source";+import type { SourceHeader } from "@svml/source";import {elaborateAuthorModule,@@ -38,10 +43,15 @@ export type AuthorSourceUnit = {readonly text: string;};+/** Source presented to a Frontend after the mandatory Header has been admitted and masked. */+export type AuthorFrontendSourceUnit = AuthorSourceUnit & {+ readonly header: SourceHeader;+ readonly sourceDigest: Digest;+};+export type AuthorSourceImport = {readonly from: string;readonly alias: string;- readonly frontend: string;readonly range?: SourceRange;};@@ -73,6 +83,9 @@ export type AuthorSourceExport = {export type ResolvedAuthorSourceImport = {readonly request: AuthorSourceImport;readonly source: Digest;+ readonly frontendRequest: string;+ readonly frontend: string;+ readonly frontendDigest: Digest;readonly exports: readonly AuthorSourceExport[];/** Public record exports available to a package-owned Surface during author compilation. */readonly records: readonly TypedRecord[];@@ -97,8 +110,8 @@ export type Awaitable<T> = T | Promise<T>;export type AuthorFrontend = {readonly id: string;readonly implementationDigest: Digest;- discover(source: AuthorSourceUnit): Awaitable<AuthorSourceDiscovery>;- decode(source: AuthorSourceUnit, context: AuthorSourceDecodeContext): Awaitable<DecodedAuthorSource>;+ discover(source: AuthorFrontendSourceUnit): Awaitable<AuthorSourceDiscovery>;+ decode(source: AuthorFrontendSourceUnit, context: AuthorSourceDecodeContext): Awaitable<DecodedAuthorSource>;};export interface AuthorFrontendRegistryLike {@@ -146,8 +159,9 @@ export type AuthorRecordAdmitter = () => Awaitable<TypedRecord>;export type SourceClosureUnit = {- readonly format: "svml.source-unit@1";+ readonly format: "svml.source-unit@2";readonly id: Digest;+ readonly frontendRequest: string;readonly frontend: string;readonly frontendDigest: Digest;readonly sourceDigest: Digest;@@ -158,12 +172,14 @@ export type SourceClosureUnit = {readonly alias: string;readonly from: string;readonly source: Digest;+ readonly frontendRequest: string;readonly frontend: string;+ readonly frontendDigest: Digest;}[];};export type SourceClosure = {- readonly format: "svml.source-closure@1";+ readonly format: "svml.source-closure@2";readonly id: Digest;readonly entry: Digest;readonly units: readonly SourceClosureUnit[];@@ -187,7 +203,6 @@ export type CompiledSourceClosure = {export type CompileSourceClosureRequest = {readonly entry: AuthorSourceUnit;- readonly frontend: string;readonly closure: ResolvedModuleClosure;readonly frontends: AuthorFrontendRegistryLike;readonly resolveSource: AuthorSourceResolver;@@ -209,7 +224,8 @@ export class SourceClosureError extends Error {function sourceUnitContent(unit: SourceClosureUnit): Omit<SourceClosureUnit, "id"> {return {- format: "svml.source-unit@1",+ format: "svml.source-unit@2",+ frontendRequest: unit.frontendRequest,frontend: unit.frontend,frontendDigest: unit.frontendDigest,sourceDigest: unit.sourceDigest,@@ -223,7 +239,9 @@ function sourceUnitContent(unit: SourceClosureUnit): Omit<SourceClosureUnit, "idalias: item.alias,from: item.from,source: item.source,+ frontendRequest: item.frontendRequest,frontend: item.frontend,+ frontendDigest: item.frontendDigest,})).sort((left, right) => left.alias.localeCompare(right.alias)),};@@ -231,7 +249,7 @@ function sourceUnitContent(unit: SourceClosureUnit): Omit<SourceClosureUnit, "idfunction sourceClosureContent(closure: SourceClosure): Omit<SourceClosure, "id"> {return {- format: "svml.source-closure@1",+ format: "svml.source-closure@2",entry: closure.entry,units: [...closure.units].sort((left, right) => left.id.localeCompare(right.id)),};@@ -260,6 +278,16 @@ function sourceKey(source: AuthorSourceUnit, frontend: string): string {return `${source.id}\u0000${frontend}`;}+export function prepareAuthorSource(source: AuthorSourceUnit): AuthorFrontendSourceUnit {+ const header = parseSourceHeader(source.name, source.text);+ return {+ ...source,+ text: maskSourceHeader(source.text, header),+ header,+ sourceDigest: digestOf(source.text),+ };+}+type HygienicSource = {readonly unit: SourceClosureUnit;readonly records: readonly TypedRecord[];@@ -273,7 +301,7 @@ function hygienicId(kind: string, unit: Digest, local: string): string {}function hygienizeSource(- source: AuthorSourceUnit,+ source: AuthorFrontendSourceUnit,frontend: AuthorFrontend,discovery: AuthorSourceDiscovery,decoded: DecodedAuthorSource,@@ -316,8 +344,6 @@ function hygienizeSource(}const semanticDigest = digestOf({- frontend: frontend.id,- implementationDigest: frontend.implementationDigest,records: [...decoded.module.records].sort((left, right) => left.id.localeCompare(right.id)).map((record) => ({@@ -370,10 +396,11 @@ function hygienizeSource(}));const exports = decoded.exports.map((item) => ({ ...item, ref: mapRef(item.ref) }));const unitContent = {- format: "svml.source-unit@1" as const,+ format: "svml.source-unit@2" as const,+ frontendRequest: source.header.using,frontend: frontend.id,frontendDigest: frontend.implementationDigest,- sourceDigest: digestOf(source.text),+ sourceDigest: source.sourceDigest,semanticDigest,modules: [...discovery.modules].sort(),assets: [...assets].sort((left, right) => left.from.localeCompare(right.from)),@@ -385,7 +412,9 @@ function hygienizeSource(alias: request.alias,from: request.from,source: resolved.source,- frontend: request.frontend,+ frontendRequest: resolved.frontendRequest,+ frontend: resolved.frontend,+ frontendDigest: resolved.frontendDigest,};}).sort((left, right) => left.alias.localeCompare(right.alias)),@@ -393,7 +422,8 @@ function hygienizeSource(return {unit: {id: digestOf(unitContent),- format: "svml.source-unit@1",+ format: "svml.source-unit@2",+ frontendRequest: unitContent.frontendRequest,frontend: frontend.id,frontendDigest: frontend.implementationDigest,sourceDigest: unitContent.sourceDigest,@@ -428,9 +458,11 @@ export async function compileSourceClosure(const visiting: string[] = [];const ordered: HygienicSource[] = [];- const compile = async (source: AuthorSourceUnit, frontendId: string): Promise<HygienicSource> => {- assert(source.id.length > 0, "EMPTY_SOURCE_ID", "SourceUnit id is empty");- const key = sourceKey(source, frontendId);+ const compile = async (rawSource: AuthorSourceUnit): Promise<HygienicSource> => {+ assert(rawSource.id.length > 0, "EMPTY_SOURCE_ID", "SourceUnit id is empty");+ const source = prepareAuthorSource(rawSource);+ const frontendId = source.header.using;+ const key = sourceKey(rawSource, frontendId);const cached = cache.get(key);if (cached !== undefined) return cached;const cycle = visiting.indexOf(key);@@ -438,7 +470,7 @@ export async function compileSourceClosure(cycle === -1,"SOURCE_IMPORT_CYCLE",`Source imports cycle through ${[...visiting.slice(cycle), key].join(" -> ")}`,- source.id,+ rawSource.id,);const frontend = request.frontends.resolve(frontendId);assert(frontend !== undefined, "UNKNOWN_FRONTEND", `Frontend ${frontendId} is not registered`, frontendId);@@ -451,14 +483,17 @@ export async function compileSourceClosure(assert(dependency.alias.length > 0, "EMPTY_SOURCE_ALIAS", `${source.name} has an empty source alias`);assert(!aliases.has(dependency.alias), "DUPLICATE_SOURCE_ALIAS", `${source.name} repeats alias ${dependency.alias}`);aliases.add(dependency.alias);- const child = await request.resolveSource(source, dependency);- const compiled = await compile(child, dependency.frontend);+ const child = await request.resolveSource(rawSource, dependency);+ const compiled = await compile(child);const publicRecordIds = new Set(compiled.exports.filter((item) => item.ref.kind === "record").map((item) => item.ref.kind === "record" ? item.ref.id : ""));imports.push({request: dependency,source: compiled.unit.id,+ frontendRequest: compiled.unit.frontendRequest,+ frontend: compiled.unit.frontend,+ frontendDigest: compiled.unit.frontendDigest,exports: compiled.exports,records: compiled.records.filter((record) => publicRecordIds.has(record.id)),});@@ -486,7 +521,7 @@ export async function compileSourceClosure(`${source.name} requires source asset ${assetRequest.from}, but the Host has no asset resolver`,assetRequest.from,);- const resolved = await request.resolveAsset(source, assetRequest);+ const resolved = await request.resolveAsset(rawSource, assetRequest);const artifact = resolved.artifact;assert(artifact.kind === "blob", "INVALID_SOURCE_ASSET", `${assetRequest.from} did not resolve to a BlobRef`);assert(isDigest(artifact.digest), "INVALID_SOURCE_ASSET_DIGEST", `${assetRequest.from} has an invalid digest`);@@ -551,7 +586,7 @@ export async function compileSourceClosure(return result;};- const entry = await compile(request.entry, request.frontend);+ const entry = await compile(request.entry);const records = ordered.flatMap((unit) => unit.records);const recordIds = new Set<string>();for (const record of records) {@@ -583,7 +618,7 @@ export async function compileSourceClosure(const elaboration = elaborateAuthorModule(program, author, (id) => fragments.get(id));const units = ordered.map((unit) => unit.unit).sort((left, right) => left.id.localeCompare(right.id));const closureContent = {- format: "svml.source-closure@1" as const,+ format: "svml.source-closure@2" as const,entry: entry.unit.id,units,};@@ -608,11 +643,11 @@ export async function compileSourceClosure(}export function verifySourceClosure(closure: SourceClosure): void {- assert(closure.format === "svml.source-closure@1", "UNSUPPORTED_SOURCE_CLOSURE", "unsupported Source Closure format");+ assert(closure.format === "svml.source-closure@2", "UNSUPPORTED_SOURCE_CLOSURE", "unsupported Source Closure format");assert(isDigest(closure.id), "INVALID_SOURCE_CLOSURE_DIGEST", "Source Closure digest is invalid");const units = new Map<string, SourceClosureUnit>();for (const unit of closure.units) {- assert(unit.format === "svml.source-unit@1", "UNSUPPORTED_SOURCE_UNIT", "unsupported SourceUnit format");+ assert(unit.format === "svml.source-unit@2", "UNSUPPORTED_SOURCE_UNIT", "unsupported SourceUnit format");assert(isDigest(unit.id), "INVALID_SOURCE_UNIT_DIGEST", "SourceUnit digest is invalid");assert(unit.id === digestOf(sourceUnitContent(unit)), "SOURCE_UNIT_DIGEST_MISMATCH", `SourceUnit ${unit.id} digest differs`);assert(!units.has(unit.id), "DUPLICATE_SOURCE_UNIT", `Source Closure repeats ${unit.id}`, unit.id);diff --git a/packages/film/test/surface.test.ts b/packages/film/test/surface.test.tsindex ef808ef6..33fa0e6d 100644--- a/packages/film/test/surface.test.ts+++ b/packages/film/test/surface.test.ts@@ -27,11 +27,10 @@ import {filmTypes,} from "@svml/film";import type { ModuleManifest } from "@svml/protocol";-import { svsFrontend, svsFrontendId, svsManifest } from "@svml/svs";+import { svsFrontend, svsManifest } from "@svml/svs";import {TextSurfaceRegistry,createTextAuthorFrontend,- textAuthorFrontendId,} from "@svml/text";import { createRecordAdmitter, TypeValidatorRegistry } from "@svml/validation";@@ -88,7 +87,12 @@ const closure = createResolvedClosure([]);function source(id: string, text: string): AuthorSourceUnit {- return { id, name: id.split("/").at(-1) ?? id, text };+ const frontend = id.endsWith(".svs") ? "@svml/svs@1" : "@svml/text@1";+ return {+ id,+ name: id.split("/").at(-1) ?? id,+ text: `<?svml using="${frontend}"?>\n${text}`,+ };}function validatorRegistry(): TypeValidatorRegistry {@@ -139,11 +143,10 @@ async function compileFilm(options: { readonly reverse?: boolean; readonly styleentry: source("/project/main.svml", `<svml><import as="fixture" from="example.film-fixture@1"/><import as="film" from="@svml/film@1"/>- <import as="studio" from="./studio.svs" using="${svsFrontendId}"/>+ <import as="studio" source="./studio.svs"/><fixture:Inputs/><film:Film id="main" space={space} appearance={studio.film.vertical}>${tracks}</film:Film></svml>`),- frontend: textAuthorFrontendId,closure,frontends,resolveSource() {diff --git a/packages/hyperframes-render/test/render.test.ts b/packages/hyperframes-render/test/render.test.tsindex 4bb6f394..63f86704 100644--- a/packages/hyperframes-render/test/render.test.ts+++ b/packages/hyperframes-render/test/render.test.ts@@ -78,7 +78,6 @@ import type {import {createTextAuthorFrontend,TextSurfaceRegistry,- textAuthorFrontendId,} from "@svml/text";const space = sealProgramSpace({@@ -359,7 +358,11 @@ const fixtureManifest: ModuleManifest = {};function source(text: string): AuthorSourceUnit {- return { id: "/project/main.svml", name: "main.svml", text };+ return {+ id: "/project/main.svml",+ name: "main.svml",+ text: `<?svml using="@svml/text@1"?>\n${text}`,+ };}test("the official render Surface lowers real author source to the same BuildPlan", async () => {@@ -403,7 +406,6 @@ test("the official render Surface lowers real author source to the same BuildPla<fixture:Composition/><render:Video id="final" composition={composition}/></svml>`),- frontend: textAuthorFrontendId,closure: sourceClosure,frontends,resolveSource() {diff --git a/packages/package-loader-node/README.md b/packages/package-loader-node/README.mdindex 58fc967c..4a9f852a 100644--- a/packages/package-loader-node/README.md+++ b/packages/package-loader-node/README.md@@ -1,13 +1,15 @@# `@svml/package-loader-node`Trusted installed-package locking and loading for Node Hosts. One package lock binds every selected-physical package and declared dependency byte plus Module, Frontend, Host-facet, Producer and Type+physical package and declared dependency byte plus Module, Author/Run Frontend, Host-facet, Producer and TypeValidator identities. Loading verifies all artifacts and checks deterministic compute facetsagainst their static Manifests before returning verified `NodePackageContribution` values.This package does not select an author syntax. Syntax-specific executable facets remain inert untilan exact Host ABI installs them. `@svml/compiler-text-node` selects the official Text Surface ABI;`@svml/local` can load the same package's deterministic compute facets without depending on Text.+Run Fragment libraries use the ordinary `svml.run-fragment-host@1` Host facet; the Loader has no+Run-specific fragment field or interpretation branch.This package is deliberately not an npm client and does not activate Provider or privileged Runtimeservices. Source `<import>` can select only an already installed author contribution; trusteddiff --git a/packages/package-loader-node/package.json b/packages/package-loader-node/package.jsonindex caa7152d..ed98a12e 100644--- a/packages/package-loader-node/package.json+++ b/packages/package-loader-node/package.json@@ -12,6 +12,7 @@"@svml/elaborator": "workspace:*","@svml/host": "workspace:*","@svml/protocol": "workspace:*",+ "@svml/run": "workspace:*","@svml/validation": "workspace:*"}}diff --git a/packages/package-loader-node/src/lock.ts b/packages/package-loader-node/src/lock.tsindex f0a6af17..ee97b5a1 100644--- a/packages/package-loader-node/src/lock.ts+++ b/packages/package-loader-node/src/lock.ts@@ -190,7 +190,11 @@ function contributionMetadata(value: NodePackageContribution): unknown {manifestDigest: digestOf(item.manifest),specifiers: [...(item.specifiers ?? [])].sort(),})).sort((left, right) => left.manifestDigest.localeCompare(right.manifestDigest)),- frontends: [...(value.frontends ?? [])].map((item) => ({+ authorFrontends: [...(value.authorFrontends ?? [])].map((item) => ({+ id: item.id,+ implementationDigest: item.implementationDigest,+ })).sort((left, right) => left.id.localeCompare(right.id)),+ runFrontends: [...(value.runFrontends ?? [])].map((item) => ({id: item.id,implementationDigest: item.implementationDigest,})).sort((left, right) => left.id.localeCompare(right.id)),@@ -217,9 +221,6 @@ function contributionMetadata(value: NodePackageContribution): unknown {.localeCompare(`${right.type.module.name}@${right.type.module.version}#${right.type.name}`),),})).sort((left, right) => left.name.localeCompare(right.name)),- runFragments: Object.entries(value.runFragments ?? {})- .map(([name, fragment]) => ({ name, digest: fragment.id }))- .sort((left, right) => left.name.localeCompare(right.name)),};}diff --git a/packages/package-loader-node/src/types.ts b/packages/package-loader-node/src/types.tsindex ca41e854..9ea31457 100644--- a/packages/package-loader-node/src/types.ts+++ b/packages/package-loader-node/src/types.ts@@ -1,9 +1,9 @@import type { RegisteredModulePackage } from "@svml/compiler-node";import type { ComponentPackage } from "@svml/component-kit";import type { AuthorFrontend } from "@svml/elaborator";-import type { GraphFragment } from "@svml/elaborator";import type { HostFacet } from "@svml/host";import type { Digest } from "@svml/protocol";+import type { RunFrontend } from "@svml/run";/*** Trusted executable facets exported by one installed physical package. The Host independently@@ -14,12 +14,11 @@ export type NodePackageContribution = {readonly format: "svml.node-package@1";readonly name: string;readonly modules?: readonly RegisteredModulePackage[];- readonly frontends?: readonly AuthorFrontend[];+ readonly authorFrontends?: readonly AuthorFrontend[];+ readonly runFrontends?: readonly RunFrontend[];/** Syntax- or Host-specific executable facets, inert until their exact Host ABI selects them. */readonly hostFacets?: readonly HostFacet[];readonly components?: readonly ComponentPackage[];- /** Trusted Run-Graph Fragments, addressable from `.svrun` imports by package and export name. */- readonly runFragments?: Readonly<Record<string, GraphFragment>>;};export type LockedPackageArtifact = {diff --git a/packages/package-loader-node/test/loader.test.ts b/packages/package-loader-node/test/loader.test.tsindex 05c77b15..d7011cd6 100644--- a/packages/package-loader-node/test/loader.test.ts+++ b/packages/package-loader-node/test/loader.test.ts@@ -152,7 +152,8 @@ async function fixture(): Promise<{};`, "utf8");const source = join(root, "main.svml");- await writeFile(source, `<svml>+ await writeFile(source, `<?svml using="@svml/text@1"?>+<svml><import as="example" from="example.card@1"/><example:Card/></svml>`, "utf8");diff --git a/packages/prelude-video/src/index.ts b/packages/prelude-video/src/index.tsindex d9c1f5a4..367044be 100644--- a/packages/prelude-video/src/index.ts+++ b/packages/prelude-video/src/index.ts@@ -150,7 +150,7 @@ export const svmlPackage: NodePackageContribution = {specifiers: ["@svml/hyperframes-render", "@svml/hyperframes-render@1"],},],- frontends: [svsFrontend],+ authorFrontends: [svsFrontend],components: [...videoContractsComponents,generationComponent,diff --git a/packages/realization/README.md b/packages/realization/README.mdindex 4660c563..041a41b0 100644--- a/packages/realization/README.md+++ b/packages/realization/README.md@@ -1,12 +1,13 @@# `@svml/realization`-Content-addressed Run Graph assembly outside SVML Core.+Internal content-addressed realization composition outside SVML Core.-A `svml.realization-overlay@2` locks the exact Author Graph and contributes independent typed+A `svml.realization-overlay@2` is produced from a complete public `@svml/run` Run Graph when that+run contributes alternate implementations. It locks the exact Author Graph and contributes independent typedCandidates plus any already elaborated Operations. It does not attach those Candidates to, orrewrite, Author Logical Outputs. `resolveRealization()` merges one or more Run Graph overlays-deterministically, retains the author source digest, records a separate Realization Closure digest,-and produces the graph universe consumed by Build Compiler.+deterministically, retains the Author Graph digest, records the complete Run Graph digest as the+realization identity, and produces the graph universe consumed by Build Compiler.A Candidate is inert. It enters a finite BuildPlan only when a `BuildRequest` establishes anexplicit Satisfaction from a demanded Logical Output to that Candidate. The Satisfaction owns fidelity;diff --git a/packages/realization/src/index.ts b/packages/realization/src/index.tsindex 5d1dbab0..4f33b270 100644--- a/packages/realization/src/index.ts+++ b/packages/realization/src/index.ts@@ -5,7 +5,6 @@ export {RealizationError,resolveRealization,sealRealizationOverlay,- sealRunGraph,verifyRealizationOverlay,verifyResolvedRealization,} from "./overlay.js";@@ -15,6 +14,5 @@ export type {ProvidedCandidateInput,RealizationClosure,RealizationOverlay,- RunGraph,ResolvedRealization,} from "./overlay.js";diff --git a/packages/realization/src/overlay.ts b/packages/realization/src/overlay.tsindex 902c0d78..b38c5e22 100644--- a/packages/realization/src/overlay.ts+++ b/packages/realization/src/overlay.ts@@ -29,9 +29,6 @@ export type RealizationOverlay = {readonly operations: readonly OperationNode[];};-/** Canonical name for the external typed graph. */-export type RunGraph = RealizationOverlay;-export type RealizationClosure = {readonly format: "svml.realization-closure@2";readonly id: Digest;@@ -101,7 +98,6 @@ export function sealRealizationOverlay(}/** Canonical Run-Graph name; retained alongside the Overlay API name. */-export const sealRunGraph = sealRealizationOverlay;export function createProvidedCandidate(input: ProvidedCandidateInput): Candidate {const value = input.value.kind === "inline"diff --git a/packages/run-text/README.md b/packages/run-text/README.mdnew file mode 100644index 00000000..ee739f95--- /dev/null+++ b/packages/run-text/README.md@@ -0,0 +1,30 @@+# `@svml/run-text`++Official human-readable Frontend for `@svml/run`.++One Run Source is self-described and names one Author Source explicitly:++```xml+<?svml using="@svml/run-text@1"?>+<svrun version="1" targets="delivery">+ <author source="./main.svml"/>++ <target-set id="delivery">+ <target output="final.video" accepts="substitute"/>+ </target-set>++ <build-record id="opening" build="prior-build-id" output="opening-take"/>+ <satisfy output="opening-take" candidate="opening" fidelity="substitute"/>+</svrun>+```++The Author Source's own Header—not this file and not its suffix—selects its Author Frontend.++`<value>` declares a typed zero-input `StoredValue`. `<build-record>` exposes a verified prior+Build Record as a zero-input Candidate. `<fragment>` instantiates a trusted package Fragment and may+export several Candidates backed by shared Operations. Two declarations are two instances; one+declaration with several exports is one instance.++Imports form the opening prologue. They name Fragment libraries already admitted by the Host; they+do not install packages. Provider credentials, queues, Stores, Endpoint bindings and inline+callbacks are not Run language elements.diff --git a/packages/run-text/package.json b/packages/run-text/package.jsonnew file mode 100644index 00000000..0f8f7d94--- /dev/null+++ b/packages/run-text/package.json@@ -0,0 +1,14 @@+{+ "name": "@svml/run-text",+ "version": "0.0.0-dev",+ "private": true,+ "type": "module",+ "exports": {+ ".": "./src/index.ts"+ },+ "dependencies": {+ "@svml/protocol": "workspace:*",+ "@svml/run": "workspace:*",+ "@svml/text": "workspace:*"+ }+}diff --git a/packages/run-text/src/frontend.ts b/packages/run-text/src/frontend.tsnew file mode 100644index 00000000..a251ad15--- /dev/null+++ b/packages/run-text/src/frontend.ts@@ -0,0 +1,19 @@+import { digestOf } from "@svml/protocol";+import type { RunFrontend } from "@svml/run";++import { parseRunDocument } from "./syntax.js";++export const runTextFrontendId = "@svml/run-text@1";+export const runTextFrontendImplementationDigest = digestOf("@svml/run-text/frontend@1");++export const runTextFrontend: RunFrontend = {+ id: runTextFrontendId,+ implementationDigest: runTextFrontendImplementationDigest,+ discover(source) {+ const document = parseRunDocument(source.name, source.text);+ return { author: document.author, imports: document.imports };+ },+ decode(source) {+ return { document: parseRunDocument(source.name, source.text) };+ },+};diff --git a/packages/run-text/src/index.ts b/packages/run-text/src/index.tsnew file mode 100644index 00000000..74293e0f--- /dev/null+++ b/packages/run-text/src/index.ts@@ -0,0 +1,10 @@+export {+ runTextFrontend,+ runTextFrontendId,+ runTextFrontendImplementationDigest,+} from "./frontend.js";+export {+ parseRunDocument,+ parseTypeRef,+ RunSyntaxError,+} from "./syntax.js";diff --git a/packages/run/src/syntax.ts b/packages/run-text/src/syntax.tssimilarity index 89%rename from packages/run/src/syntax.tsrename to packages/run-text/src/syntax.tsindex 902ec6d9..dfdc74b4 100644--- a/packages/run/src/syntax.ts+++ b/packages/run-text/src/syntax.ts@@ -1,15 +1,4 @@-import type { CanonicalValue, TypeRef } from "@svml/protocol";-import {- parseStructuredElement,- skipTextTrivia,-} from "@svml/text";-import type {- SourceUnit,- StructuredElement,- StructuredNode,- TextAttributeValue,-} from "@svml/text";-+import type { TypeRef } from "@svml/protocol";import type {RunBuildRecord,RunCandidateDeclaration,@@ -19,7 +8,15 @@ import type {RunProvidedValue,RunSatisfaction,RunTargetSet,-} from "./types.js";+} from "@svml/run";+import {+ parseStructuredElement,+ skipTextTrivia,+} from "@svml/text";+import type {+ SourceUnit,+ StructuredElement,+} from "@svml/text";export class RunSyntaxError extends Error {readonly code: string;@@ -90,6 +87,12 @@ export function parseTypeRef(value: string): TypeRef {};}+function authorDeclaration(element: StructuredElement): { readonly source: string } {+ exactAttributes(element, ["source"]);+ empty(element);+ return { source: stringAttribute(element, "source")! };+}+function importDeclaration(element: StructuredElement): RunImport {exactAttributes(element, ["from", "as"]);empty(element);@@ -198,21 +201,31 @@ export function parseRunDocument(name: string, text: string): RunDocument {if (end !== text.length) throw new RunSyntaxError("RUN_TRAILING", "Only trivia may follow </svrun>", end);const root = parsed.element;if (root.name !== "svrun") fail(root, "RUN_ROOT", "Run document root must be <svrun>");- exactAttributes(root, ["version", "source", "targets"]);+ exactAttributes(root, ["version", "targets"]);if (stringAttribute(root, "version") !== "1") fail(root, "RUN_VERSION", "Only .svrun version 1 is supported");+ let author: { readonly source: string } | undefined;const imports: RunImport[] = [];const targetSets: RunTargetSet[] = [];const candidates: RunCandidateDeclaration[] = [];const satisfactions: RunSatisfaction[] = [];let bodyStarted = false;for (const child of elements(root)) {+ if (child.name === "author") {+ if (bodyStarted || author !== undefined || imports.length > 0) {+ fail(child, "RUN_AUTHOR_ORDER", "<author> must be the first and only Author declaration");+ }+ author = authorDeclaration(child);+ continue;+ }if (child.name === "import") {if (bodyStarted) fail(child, "RUN_IMPORT_ORDER", "Run imports must form the opening prologue");+ if (author === undefined) fail(child, "RUN_AUTHOR_ORDER", "<author> must precede Run imports");imports.push(importDeclaration(child));continue;}bodyStarted = true;+ if (author === undefined) fail(child, "RUN_AUTHOR_MISSING", "<svrun> requires an opening <author> declaration");if (child.name === "target-set") targetSets.push(targetSet(child));else if (child.name === "value") candidates.push(provided(child));else if (child.name === "build-record") candidates.push(buildRecord(child));@@ -220,6 +233,7 @@ export function parseRunDocument(name: string, text: string): RunDocument {else if (child.name === "satisfy") satisfactions.push(satisfaction(child));else fail(child, "RUN_CHILD", `<svrun> does not accept <${child.name}>`);}+ if (author === undefined) fail(root, "RUN_AUTHOR_MISSING", "<svrun> requires exactly one <author> declaration");unique(imports.map((item) => item.as), "Run import alias", root);unique(targetSets.map((item) => item.id), "Target set", root);@@ -230,8 +244,8 @@ export function parseRunDocument(name: string, text: string): RunDocument {fail(root, "RUN_TARGET_SET", `Selected target set ${selectedTargets} is not declared`);}return {- format: "svml.run-document@1",- source: stringAttribute(root, "source")!,+ format: "svml.run-document@2",+ author,selectedTargets,imports,targetSets,diff --git a/packages/run/README.md b/packages/run/README.mdindex 8ab87e17..543b192e 100644--- a/packages/run/README.md+++ b/packages/run/README.md@@ -1,48 +1,23 @@# `@svml/run`-The official human-readable frontend for one execution intention. It compiles a `.svrun` file into-three ordinary domain-neutral facts before Core starts:+Syntax-neutral Run Source and complete Run Graph compiler.-```text-Run Graph[] + Satisfaction[] + Target[]-```--It is deliberately separate from both author source and deployment configuration:--- `.svml` says what the author means;-- `.svrun` says what this run demands and which explicit Candidates satisfy which outputs;-- `svml.runtime.json` says where and under which permissions the frozen plan executes.+This package is outside Core and knows no XML, filename suffix, video type, Provider or Runtime+configuration. Given a self-described source unit, a registered `RunFrontend`, an already compiled+Author Source and trusted Run Fragment registry, it produces:-```xml-<svrun version="1" source="./main.svml" targets="delivery">- <target-set id="delivery">- <target output="final.video" accepts="substitute"/>- </target-set>-- <build-record id="opening" build="prior-build-id" output="opening-take"/>- <satisfy output="opening-take" candidate="opening" fidelity="substitute"/>-</svrun>+```text+RunSourceClosure + RunDocument -> complete RunGraph```-`<value>` attaches a typed zero-input `StoredValue` from JSON. `<build-record>` extracts one typed-Record from a verified prior Build by its prior Logical Output id; it is independent of the current-output later named by `<satisfy>`. Neither is a Core Pin primitive. `<fragment>` instantiates a-trusted package-exported Run Fragment and may expose several Candidates backed by one shared-Operation:--```xml-<import from="@acme/preview" as="preview"/>-<fragment id="one-black-frame" using="preview:black-video">- <input name="duration" from="opening.duration"/>-</fragment>-<satisfy output="opening.visual"- candidate="one-black-frame.video"- fidelity="substitute"/>-```+The Run Graph always exists and binds the exact Author Graph. It contains Run Candidates,+Operations, explicit Satisfaction edges, all named Target sets and the selected Target set. A run+that selects only primary Candidates therefore still has identity and cannot be replaced by hidden+CLI flags.-Two `<fragment>` declarations are two instances and therefore may execute twice. One declaration-with several exports is one instance and shares its internal Operations. Imports must form the-opening prologue and can resolve only Fragments exposed by explicitly activated trusted packages.+`RunSourceClosure` separately binds original source bytes, Frontend id/implementation and decoded+semantic meaning. `RunFragmentRegistry` accepts trusted Fragment packages only through the+`svml.run-fragment-host@1` Host-facet installer. Package loading does not interpret Fragment code.-`.svrun` cannot declare credentials, Providers, Store paths, queues, Endpoint bindings or inline-execution callbacks.+The optional official XML-like syntax lives in `@svml/run-text`. Another trusted Frontend can emit+the same `RunDocument` without changing this package or Core.diff --git a/packages/run/package.json b/packages/run/package.jsonindex d6db07d5..20295c2e 100644--- a/packages/run/package.json+++ b/packages/run/package.json@@ -7,12 +7,11 @@".": "./src/index.ts"},"dependencies": {+ "@svml/core": "workspace:*","@svml/elaborator": "workspace:*",+ "@svml/host": "workspace:*","@svml/protocol": "workspace:*","@svml/realization": "workspace:*",- "@svml/text": "workspace:*"- },- "devDependencies": {- "@svml/core": "workspace:*"+ "@svml/source": "workspace:*"}}diff --git a/packages/run/src/facet.ts b/packages/run/src/facet.tsnew file mode 100644index 00000000..9c44e295--- /dev/null+++ b/packages/run/src/facet.ts@@ -0,0 +1,92 @@+import type { GraphFragment } from "@svml/elaborator";+import type { HostFacet } from "@svml/host";+import { canonicalStringify, isDigest } from "@svml/protocol";++import type {+ RunFragmentPackage,+} from "./types.js";++export const runFragmentHostAbi = "svml.run-fragment-host@1";++export type RunFragmentHostFacetIdentity = {+ readonly contract: "svml.run-fragment-host-facet@1";+ readonly package: string;+ readonly exports: readonly {+ readonly name: string;+ readonly fragment: string;+ }[];+};++export type RunFragmentHostFacet = HostFacet & {+ readonly abi: typeof runFragmentHostAbi;+ readonly identity: RunFragmentHostFacetIdentity;+ readonly implementation: RunFragmentPackage;+};++function normalizedExports(fragments: Readonly<Record<string, GraphFragment>>): RunFragmentHostFacetIdentity["exports"] {+ return Object.entries(fragments)+ .map(([name, fragment]) => {+ if (name.trim().length === 0 || !isDigest(fragment.id)) {+ throw new Error("Run Fragment Host facet has an invalid export identity");+ }+ return { name, fragment: fragment.id };+ })+ .sort((left, right) => left.name.localeCompare(right.name));+}++/** Package helper: expose inert Run Fragments through the exact Run Host ABI. */+export function createRunFragmentHostFacet(item: RunFragmentPackage): RunFragmentHostFacet {+ if (item.name.trim().length === 0) throw new Error("Run Fragment Host facet package name is empty");+ return {+ abi: runFragmentHostAbi,+ identity: {+ contract: "svml.run-fragment-host-facet@1",+ package: item.name,+ exports: normalizedExports(item.fragments),+ },+ implementation: item,+ };+}++function sameIdentity(facet: RunFragmentHostFacet): boolean {+ const expected: RunFragmentHostFacetIdentity = {+ contract: "svml.run-fragment-host-facet@1",+ package: facet.implementation.name,+ exports: normalizedExports(facet.implementation.fragments),+ };+ return canonicalStringify(facet.identity) === canonicalStringify(expected);+}++/**+ * Install only facets addressed to this Host ABI. Package loading itself never interprets or+ * activates the executable Fragment objects.+ */+export function installRunFragmentHostFacets(+ facets: readonly HostFacet[],+ registry: { register(item: RunFragmentPackage): void },+): void {+ for (const opaque of facets) {+ if (opaque.abi !== runFragmentHostAbi) continue;+ if (opaque.identity === null || typeof opaque.identity !== "object" || Array.isArray(opaque.identity)+ || opaque.implementation === null || typeof opaque.implementation !== "object"+ || Array.isArray(opaque.implementation)) {+ throw new Error("Run Fragment Host facet has an invalid identity or implementation");+ }+ const facet = opaque as RunFragmentHostFacet;+ if (facet.identity.contract !== "svml.run-fragment-host-facet@1") {+ throw new Error("Run Fragment Host facet has an unsupported identity");+ }+ if (typeof facet.identity.package !== "string"+ || !Array.isArray(facet.identity.exports)+ || typeof facet.implementation.name !== "string"+ || facet.implementation.fragments === null+ || typeof facet.implementation.fragments !== "object"+ || Array.isArray(facet.implementation.fragments)) {+ throw new Error("Run Fragment Host facet has an invalid package implementation");+ }+ if (!sameIdentity(facet)) {+ throw new Error(`Run Fragment Host facet ${facet.identity.package} differs from its locked identity`);+ }+ registry.register(facet.implementation);+ }+}diff --git a/packages/run/src/frontend.ts b/packages/run/src/frontend.tsnew file mode 100644index 00000000..8ff9a139--- /dev/null+++ b/packages/run/src/frontend.ts@@ -0,0 +1,139 @@+import {+ canonicalStringify,+ digestOf,+ isDigest,+} from "@svml/protocol";+import {+ maskSourceHeader,+ parseSourceHeader,+} from "@svml/source";++import type {+ RunDocument,+ RunFrontend,+ RunFrontendRegistryLike,+ RunFrontendSourceUnit,+ RunSourceClosure,+ RunSourceUnit,+ RunSourceUnitIdentity,+} from "./types.js";++export class RunSourceError extends Error {+ readonly code: string;+ readonly subject: string | undefined;++ constructor(code: string, message: string, subject?: string) {+ super(message);+ this.name = "RunSourceError";+ this.code = code;+ this.subject = subject;+ }+}++function assert(condition: unknown, code: string, message: string, subject?: string): asserts condition {+ if (!condition) throw new RunSourceError(code, message, subject);+}++export class RunFrontendRegistry implements RunFrontendRegistryLike {+ readonly #frontends = new Map<string, RunFrontend>();++ register(frontend: RunFrontend): void {+ assert(frontend.id.trim().length > 0, "EMPTY_RUN_FRONTEND", "Run Frontend id is empty");+ assert(isDigest(frontend.implementationDigest), "INVALID_RUN_FRONTEND_DIGEST", `${frontend.id} digest is invalid`);+ assert(!this.#frontends.has(frontend.id), "DUPLICATE_RUN_FRONTEND", `${frontend.id} is already registered`, frontend.id);+ this.#frontends.set(frontend.id, frontend);+ }++ resolve(id: string): RunFrontend | undefined {+ return this.#frontends.get(id);+ }+}++export function prepareRunSource(source: RunSourceUnit): RunFrontendSourceUnit {+ const header = parseSourceHeader(source.name, source.text);+ return {+ ...source,+ text: maskSourceHeader(source.text, header),+ header,+ sourceDigest: digestOf(source.text),+ };+}++function unitContent(unit: RunSourceUnitIdentity): Omit<RunSourceUnitIdentity, "id"> {+ return {+ format: "svml.run-source-unit@1",+ frontendRequest: unit.frontendRequest,+ frontend: unit.frontend,+ frontendDigest: unit.frontendDigest,+ sourceDigest: unit.sourceDigest,+ semanticDigest: unit.semanticDigest,+ authorSource: unit.authorSource,+ imports: [...unit.imports].sort((left, right) => left.as.localeCompare(right.as)),+ };+}++function closureContent(closure: RunSourceClosure): Omit<RunSourceClosure, "id"> {+ return {+ format: "svml.run-source-closure@1",+ entry: closure.entry,+ units: [...closure.units].sort((left, right) => left.id.localeCompare(right.id)),+ };+}++export async function compileRunSource(+ source: RunSourceUnit,+ frontends: RunFrontendRegistryLike,+): Promise<{ readonly document: RunDocument; readonly closure: RunSourceClosure }> {+ const prepared = prepareRunSource(source);+ const frontend = frontends.resolve(prepared.header.using);+ assert(frontend !== undefined, "UNKNOWN_RUN_FRONTEND", `Run Frontend ${prepared.header.using} is not registered`, prepared.header.using);+ assert(isDigest(frontend.implementationDigest), "INVALID_RUN_FRONTEND_DIGEST", `${frontend.id} digest is invalid`);+ const discovery = await frontend.discover(prepared);+ const decoded = await frontend.decode(prepared);+ assert(+ canonicalStringify(discovery.author) === canonicalStringify(decoded.document.author),+ "RUN_FRONTEND_DISCOVERY_DRIFT",+ `${frontend.id} changed the Author Source between discover and decode`,+ );+ assert(+ canonicalStringify(discovery.imports) === canonicalStringify(decoded.document.imports),+ "RUN_FRONTEND_DISCOVERY_DRIFT",+ `${frontend.id} changed imports between discover and decode`,+ );+ const unitWithoutId = {+ format: "svml.run-source-unit@1" as const,+ frontendRequest: prepared.header.using,+ frontend: frontend.id,+ frontendDigest: frontend.implementationDigest,+ sourceDigest: prepared.sourceDigest,+ semanticDigest: digestOf(decoded.document),+ authorSource: discovery.author.source,+ imports: [...discovery.imports].sort((left, right) => left.as.localeCompare(right.as)),+ };+ const unit: RunSourceUnitIdentity = { ...unitWithoutId, id: digestOf(unitWithoutId) };+ const closureWithoutId = {+ format: "svml.run-source-closure@1" as const,+ entry: unit.id,+ units: [unit],+ };+ const closure: RunSourceClosure = { ...closureWithoutId, id: digestOf(closureWithoutId) };+ verifyRunSourceClosure(closure);+ return { document: decoded.document, closure };+}++export function verifyRunSourceClosure(closure: RunSourceClosure): void {+ assert(closure.format === "svml.run-source-closure@1", "UNSUPPORTED_RUN_SOURCE_CLOSURE", "unsupported Run Source Closure");+ assert(isDigest(closure.id), "INVALID_RUN_SOURCE_CLOSURE_DIGEST", "Run Source Closure digest is invalid");+ const ids = new Set<string>();+ for (const unit of closure.units) {+ assert(unit.format === "svml.run-source-unit@1", "UNSUPPORTED_RUN_SOURCE_UNIT", "unsupported Run SourceUnit");+ assert(isDigest(unit.id) && unit.id === digestOf(unitContent(unit)), "RUN_SOURCE_UNIT_DIGEST_MISMATCH", `${unit.id} digest differs`);+ assert(!ids.has(unit.id), "DUPLICATE_RUN_SOURCE_UNIT", `Run Source Closure repeats ${unit.id}`);+ assert(isDigest(unit.frontendDigest), "INVALID_RUN_FRONTEND_DIGEST", `${unit.id} Frontend digest is invalid`);+ assert(isDigest(unit.sourceDigest), "INVALID_RUN_SOURCE_DIGEST", `${unit.id} source digest is invalid`);+ assert(isDigest(unit.semanticDigest), "INVALID_RUN_SEMANTIC_DIGEST", `${unit.id} semantic digest is invalid`);+ ids.add(unit.id);+ }+ assert(ids.has(closure.entry), "UNKNOWN_RUN_SOURCE_ENTRY", `Run Source entry ${closure.entry} is absent`);+ assert(closure.id === digestOf(closureContent(closure)), "RUN_SOURCE_CLOSURE_DIGEST_MISMATCH", "Run Source Closure digest differs");+}diff --git a/packages/run/src/graph.ts b/packages/run/src/graph.tsnew file mode 100644index 00000000..efb71237--- /dev/null+++ b/packages/run/src/graph.ts@@ -0,0 +1,81 @@+import {+ digestOf,+ isDigest,+} from "@svml/protocol";++import type { RunGraph } from "./types.js";++export class RunGraphError extends Error {+ readonly code: string;++ constructor(code: string, message: string) {+ super(message);+ this.name = "RunGraphError";+ this.code = code;+ }+}++function assert(condition: unknown, code: string, message: string): asserts condition {+ if (!condition) throw new RunGraphError(code, message);+}++function content(graph: RunGraph): Omit<RunGraph, "id"> {+ return {+ format: "svml.run-graph@1",+ authorGraph: graph.authorGraph,+ sourceClosure: graph.sourceClosure,+ candidates: [...graph.candidates].sort((left, right) => left.id.localeCompare(right.id)),+ operations: [...graph.operations].sort((left, right) => left.id.localeCompare(right.id)),+ satisfactions: [...graph.satisfactions].sort((left, right) => left.output.localeCompare(right.output)),+ targetSets: [...graph.targetSets]+ .map((set) => ({+ id: set.id,+ targets: [...set.targets].sort((left, right) => left.output.localeCompare(right.output)),+ }))+ .sort((left, right) => left.id.localeCompare(right.id)),+ selectedTargets: graph.selectedTargets,+ };+}++export function sealRunGraph(input: Omit<RunGraph, "format" | "id">): RunGraph {+ const normalized = content({ format: "svml.run-graph@1", id: digestOf(null), ...input });+ const graph: RunGraph = { ...normalized, id: digestOf(normalized) };+ verifyRunGraph(graph);+ return graph;+}++export function verifyRunGraph(graph: RunGraph): void {+ assert(graph.format === "svml.run-graph@1", "UNSUPPORTED_RUN_GRAPH", "unsupported Run Graph");+ assert(isDigest(graph.id), "INVALID_RUN_GRAPH_DIGEST", "Run Graph digest is invalid");+ assert(isDigest(graph.authorGraph), "INVALID_RUN_AUTHOR_GRAPH", "Run Graph Author Graph digest is invalid");+ assert(isDigest(graph.sourceClosure), "INVALID_RUN_SOURCE_CLOSURE", "Run Graph Source Closure digest is invalid");+ const candidateIds = new Set<string>();+ for (const candidate of graph.candidates) {+ assert(!candidateIds.has(candidate.id), "DUPLICATE_RUN_CANDIDATE", `Run Graph repeats Candidate ${candidate.id}`);+ candidateIds.add(candidate.id);+ }+ const operationIds = new Set<string>();+ for (const operation of graph.operations) {+ assert(!operationIds.has(operation.id), "DUPLICATE_RUN_OPERATION", `Run Graph repeats Operation ${operation.id}`);+ operationIds.add(operation.id);+ }+ const satisfiedOutputs = new Set<string>();+ for (const satisfaction of graph.satisfactions) {+ assert(!satisfiedOutputs.has(satisfaction.output), "DUPLICATE_RUN_SATISFACTION", `Run Graph satisfies ${satisfaction.output} more than once`);+ assert(candidateIds.has(satisfaction.candidate), "UNKNOWN_RUN_CANDIDATE", `Run Graph Satisfaction names absent Candidate ${satisfaction.candidate}`);+ satisfiedOutputs.add(satisfaction.output);+ }+ const targetIds = new Set<string>();+ for (const set of graph.targetSets) {+ assert(set.id.length > 0 && !targetIds.has(set.id), "DUPLICATE_RUN_TARGET_SET", `Run Graph repeats Target Set ${set.id}`);+ assert(set.targets.length > 0, "EMPTY_RUN_TARGET_SET", `Run Target Set ${set.id} is empty`);+ const outputs = new Set<string>();+ for (const target of set.targets) {+ assert(!outputs.has(target.output), "DUPLICATE_RUN_TARGET", `Run Target Set ${set.id} repeats ${target.output}`);+ outputs.add(target.output);+ }+ targetIds.add(set.id);+ }+ assert(targetIds.has(graph.selectedTargets), "UNKNOWN_SELECTED_TARGET_SET", `Run Graph selects absent Target Set ${graph.selectedTargets}`);+ assert(graph.id === digestOf(content(graph)), "RUN_GRAPH_DIGEST_MISMATCH", "Run Graph digest differs");+}diff --git a/packages/run/src/index.ts b/packages/run/src/index.tsindex 165ca200..7020374a 100644--- a/packages/run/src/index.ts+++ b/packages/run/src/index.ts@@ -1,4 +1,24 @@export { RunFragmentRegistry } from "./registry.js";-export { resolveRunDocument } from "./resolve.js";-export { parseRunDocument, parseTypeRef, RunSyntaxError } from "./syntax.js";+export {+ createRunFragmentHostFacet,+ installRunFragmentHostFacets,+ runFragmentHostAbi,+} from "./facet.js";+export type {+ RunFragmentHostFacet,+ RunFragmentHostFacetIdentity,+} from "./facet.js";+export { collectRunModuleRequests, resolveRunDocument } from "./resolve.js";+export {+ compileRunSource,+ prepareRunSource,+ RunFrontendRegistry,+ RunSourceError,+ verifyRunSourceClosure,+} from "./frontend.js";+export {+ RunGraphError,+ sealRunGraph,+ verifyRunGraph,+} from "./graph.js";export type * from "./types.js";diff --git a/packages/run/src/resolve.ts b/packages/run/src/resolve.tsindex a9f6518c..7f489520 100644--- a/packages/run/src/resolve.ts+++ b/packages/run/src/resolve.ts@@ -3,19 +3,56 @@ import {exportRunFragment,resolveCompiledSourceExport,} from "@svml/elaborator";-import type { GraphValueRef, StoredValue } from "@svml/protocol";+import { canonicalStringify } from "@svml/protocol";+import type {+ Candidate,+ GraphValueRef,+ ModuleRef,+ OperationNode,+ StoredValue,+} from "@svml/protocol";import {createBuildRecordCandidate,createProvidedCandidate,- sealRunGraph,+ sealRealizationOverlay,} from "@svml/realization";+import { sealRunGraph } from "./graph.js";+import type {ResolveRunDocumentContext,- ResolvedRunDocument,+ RunCompilation,RunDocument,} from "./types.js";+function moduleRequest(ref: ModuleRef): string {+ return `${ref.name}@${ref.version}`;+}++/** Module closure additions required only by the selected Run implementations. */+export function collectRunModuleRequests(+ document: RunDocument,+ fragments: ResolveRunDocumentContext["fragments"],+): readonly string[] {+ const imports = new Map(document.imports.map((item) => [item.as, item.from]));+ const requests = new Set<string>();+ for (const declaration of document.candidates) {+ if (declaration.kind === "provided") {+ requests.add(moduleRequest(declaration.type.module));+ continue;+ }+ if (declaration.kind !== "fragment") continue;+ const packageName = imports.get(declaration.using.alias);+ if (packageName === undefined) throw new Error(`Run Fragment alias ${declaration.using.alias} is not imported`);+ const fragment = fragments.resolve(packageName, declaration.using.name);+ if (fragment === undefined) throw new Error(`${packageName} exports no Run Fragment ${declaration.using.name}`);+ for (const input of fragment.inputs) requests.add(moduleRequest(input.type.module));+ for (const operation of fragment.operations) requests.add(moduleRequest(operation.producer.module));+ for (const item of fragment.exports) requests.add(moduleRequest(item.type.module));+ }+ return [...requests].sort();+}+function authorRef(context: ResolveRunDocumentContext, name: string): GraphValueRef {const exported = resolveCompiledSourceExport(context.compilation, name);return exported.ref;@@ -46,10 +83,24 @@ function assertStoredValue(value: unknown, subject: string): asserts value is Stexport async function resolveRunDocument(document: RunDocument,context: ResolveRunDocumentContext,-): Promise<ResolvedRunDocument> {+): Promise<RunCompilation> {const imports = new Map(document.imports.map((item) => [item.as, item.from]));- const candidates = [];- const operations = [];+ const candidates = new Map<string, Candidate>();+ const operations = new Map<string, OperationNode>();+ const addCandidate = (candidate: Candidate): void => {+ const existing = candidates.get(candidate.id);+ if (existing !== undefined && canonicalStringify(existing) !== canonicalStringify(candidate)) {+ throw new Error(`Run Candidate identity ${candidate.id} has conflicting definitions`);+ }+ candidates.set(candidate.id, candidate);+ };+ const addOperation = (operation: OperationNode): void => {+ const existing = operations.get(operation.id);+ if (existing !== undefined && canonicalStringify(existing) !== canonicalStringify(operation)) {+ throw new Error(`Run Operation identity ${operation.id} has conflicting definitions`);+ }+ operations.set(operation.id, operation);+ };const candidateNames = new Map<string, string>();const bindCandidateName = (name: string, candidate: string): void => {if (candidateNames.has(name)) throw new Error(`Run Candidate reference ${name} is declared twice`);@@ -61,7 +112,7 @@ export async function resolveRunDocument(const value = await context.readStoredValue(declaration.from);assertStoredValue(value, declaration.from);const candidate = createProvidedCandidate({ type: declaration.type, value });- candidates.push(candidate);+ addCandidate(candidate);bindCandidateName(declaration.id, candidate.id);continue;}@@ -72,7 +123,7 @@ export async function resolveRunDocument(build,sourceOutput: declaration.output,});- candidates.push(candidate);+ addCandidate(candidate);bindCandidateName(declaration.id, candidate.id);continue;}@@ -88,8 +139,8 @@ export async function resolveRunDocument(inputs: Object.fromEntries(declaration.inputs.map((item) => [item.name, authorRef(context, item.from)])),});const contribution = exportRunFragment(instance, declaration.exports);- candidates.push(...contribution.candidates);- operations.push(...contribution.operations);+ for (const candidate of contribution.candidates) addCandidate(candidate);+ for (const operation of contribution.operations) addOperation(operation);for (const item of contribution.exports) bindCandidateName(`${declaration.id}.${item.name}`, item.candidate);}@@ -102,19 +153,36 @@ export async function resolveRunDocument(fidelity: item.fidelity,} as const;});- const selected = document.targetSets.find((item) => item.id === document.selectedTargets)!;- const graphs = candidates.length === 0- ? []- : [sealRunGraph({- sourceGraph: context.compilation.elaboration.graph.id,- candidates,- operations,- })];- return {- source: document.source,- targets: selected.targets.map((item) => ({ name: item.output, accepts: item.accepts })),- graphs,+ const targetSets = document.targetSets.map((set) => ({+ id: set.id,+ targets: set.targets.map((item) => ({+ output: logicalOutput(context, item.output),+ accepts: item.accepts,+ })),+ }));+ const resolvedCandidates = [...candidates.values()];+ const resolvedOperations = [...operations.values()];+ const overlay = resolvedCandidates.length === 0+ ? undefined+ : sealRealizationOverlay({+ sourceGraph: context.compilation.elaboration.graph.id,+ candidates: resolvedCandidates,+ operations: resolvedOperations,+ });+ const graph = sealRunGraph({+ authorGraph: context.compilation.elaboration.graph.id,+ sourceClosure: context.sourceClosure.id,+ candidates: resolvedCandidates,+ operations: resolvedOperations,satisfactions,+ targetSets,+ selectedTargets: document.selectedTargets,+ });+ return {+ closure: context.sourceClosure,+ document,+ graph,+ ...(overlay === undefined ? {} : { overlay }),candidates: Object.fromEntries([...candidateNames.entries()].sort(([left], [right]) => left.localeCompare(right))),};}diff --git a/packages/run/src/types.ts b/packages/run/src/types.tsindex 07295fd1..a5429f99 100644--- a/packages/run/src/types.ts+++ b/packages/run/src/types.ts@@ -4,13 +4,32 @@ import type {} from "@svml/elaborator";import type {BuildState,+ Candidate,CanonicalValue,+ Digest,NeedAcceptance,+ OperationNode,Satisfaction,StoredValue,TypeRef,} from "@svml/protocol";-import type { RunGraph } from "@svml/realization";+import type { RealizationOverlay } from "@svml/realization";+import type { SourceHeader } from "@svml/source";++export type RunSourceUnit = {+ readonly id: string;+ readonly name: string;+ readonly text: string;+};++export type RunFrontendSourceUnit = RunSourceUnit & {+ readonly header: SourceHeader;+ readonly sourceDigest: Digest;+};++export type RunAuthorSourceRequest = {+ readonly source: string;+};export type RunImport = {readonly from: string;@@ -72,8 +91,8 @@ export type RunSatisfaction = {};export type RunDocument = {- readonly format: "svml.run-document@1";- readonly source: string;+ readonly format: "svml.run-document@2";+ readonly author: RunAuthorSourceRequest;readonly selectedTargets: string;readonly imports: readonly RunImport[];readonly targetSets: readonly RunTargetSet[];@@ -81,6 +100,45 @@ export type RunDocument = {readonly satisfactions: readonly RunSatisfaction[];};+export type RunSourceDiscovery = {+ readonly author: RunAuthorSourceRequest;+ readonly imports: readonly RunImport[];+};++export type DecodedRunSource = {+ readonly document: RunDocument;+};++export type RunFrontend = {+ readonly id: string;+ readonly implementationDigest: Digest;+ discover(source: RunFrontendSourceUnit): RunSourceDiscovery | Promise<RunSourceDiscovery>;+ decode(source: RunFrontendSourceUnit): DecodedRunSource | Promise<DecodedRunSource>;+};++export interface RunFrontendRegistryLike {+ resolve(id: string): RunFrontend | undefined;+}++export type RunSourceUnitIdentity = {+ readonly format: "svml.run-source-unit@1";+ readonly id: Digest;+ readonly frontendRequest: string;+ readonly frontend: string;+ readonly frontendDigest: Digest;+ readonly sourceDigest: Digest;+ readonly semanticDigest: Digest;+ readonly authorSource: string;+ readonly imports: readonly RunImport[];+};++export type RunSourceClosure = {+ readonly format: "svml.run-source-closure@1";+ readonly id: Digest;+ readonly entry: Digest;+ readonly units: readonly RunSourceUnitIdentity[];+};+export type RunFragmentPackage = {readonly name: string;readonly fragments: Readonly<Record<string, GraphFragment>>;@@ -90,17 +148,39 @@ export interface RunFragmentRegistryLike {resolve(packageName: string, fragmentName: string): GraphFragment | undefined;}+export type ResolvedRunTargetSet = {+ readonly id: string;+ readonly targets: readonly {+ readonly output: string;+ readonly accepts: NeedAcceptance;+ }[];+};++/** Complete, mandatory execution-intent graph. Empty alternate Candidate sets are still a Run Graph. */+export type RunGraph = {+ readonly format: "svml.run-graph@1";+ readonly id: Digest;+ readonly authorGraph: Digest;+ readonly sourceClosure: Digest;+ readonly candidates: readonly Candidate[];+ readonly operations: readonly OperationNode[];+ readonly satisfactions: readonly Satisfaction[];+ readonly targetSets: readonly ResolvedRunTargetSet[];+ readonly selectedTargets: string;+};+export type ResolveRunDocumentContext = {readonly compilation: CompiledSourceClosure;+ readonly sourceClosure: RunSourceClosure;readonly fragments: RunFragmentRegistryLike;readonly readStoredValue: (from: string) => Promise<StoredValue> | StoredValue;readonly readBuild: (id: string) => Promise<BuildState | undefined> | BuildState | undefined;};-export type ResolvedRunDocument = {- readonly source: string;- readonly targets: readonly { readonly name: string; readonly accepts: NeedAcceptance }[];- readonly graphs: readonly RunGraph[];- readonly satisfactions: readonly Satisfaction[];+export type RunCompilation = {+ readonly closure: RunSourceClosure;+ readonly document: RunDocument;+ readonly graph: RunGraph;+ readonly overlay?: RealizationOverlay;readonly candidates: Readonly<Record<string, string>>;};diff --git a/packages/run/test/run.test.ts b/packages/run/test/run.test.tsindex cf8b066f..66199550 100644--- a/packages/run/test/run.test.ts+++ b/packages/run/test/run.test.ts@@ -18,10 +18,16 @@ import type { CompiledSourceClosure } from "@svml/elaborator";import type { ModuleManifest, ProducerRef, TypeRef } from "@svml/protocol";import { resolveRealization } from "@svml/realization";import {- parseRunDocument,+ compileRunSource,+ createRunFragmentHostFacet,+ installRunFragmentHostFacets,resolveRunDocument,RunFragmentRegistry,+ RunFrontendRegistry,+ RunSourceError,+ verifyRunSourceClosure,} from "@svml/run";+import { parseRunDocument, runTextFrontend } from "@svml/run-text";const moduleRef = { name: "example.run", version: "1" } as const;const promptType = { module: moduleRef, name: "Prompt" } satisfies TypeRef;@@ -124,8 +130,41 @@ function previewFragment() {});}+test("Run Fragments enter the Host only through the locked Run facet ABI", () => {+ const fragment = previewFragment();+ const facet = createRunFragmentHostFacet({+ name: "@example/run-preview",+ fragments: { shared: fragment },+ });+ const registry = new RunFragmentRegistry();+ installRunFragmentHostFacets([facet], registry);+ assert.equal(registry.resolve("@example/run-preview", "shared")?.id, fragment.id);+ assert.throws(+ () => installRunFragmentHostFacets([{+ ...facet,+ identity: {+ contract: "svml.run-fragment-host-facet@1",+ package: "@example/tampered",+ exports: facet.identity.exports,+ },+ }], new RunFragmentRegistry()),+ /differs from its locked identity/u,+ );+});++async function compileDocument(body: string) {+ const frontends = new RunFrontendRegistry();+ frontends.register(runTextFrontend);+ return await compileRunSource({+ id: "/project/build.svrun",+ name: "build.svrun",+ text: `<?svml using="@svml/run-text@1"?>\n${body}`,+ }, frontends);+}+test(".svrun compiles one multi-export Fragment instance before execution", async () => {- const document = parseRunDocument("preview.svrun", `<svrun version="1" source="./main.svml" targets="preview">+ const compiledRunSource = await compileDocument(`<svrun version="1" targets="preview">+ <author source="./main.svml"/><import from="@example/run-preview" as="preview"/><target-set id="preview"><target output="left" accepts="substitute"/>@@ -137,27 +176,28 @@ test(".svrun compiles one multi-export Fragment instance before execution", asyn<satisfy output="left" candidate="one-call.first" fidelity="substitute"/><satisfy output="right" candidate="one-call.second" fidelity="substitute"/></svrun>`);+ const document = compiledRunSource.document;const compilation = fixture();const fragments = new RunFragmentRegistry();fragments.register({ name: "@example/run-preview", fragments: { shared: previewFragment() } });const run = await resolveRunDocument(document, {compilation,+ sourceClosure: compiledRunSource.closure,fragments,readStoredValue() { throw new Error("not used"); },readBuild() { throw new Error("not used"); },});- assert.equal(run.graphs.length, 1);- assert.equal(run.graphs[0]!.operations.length, 1);+ assert.equal(run.graph.operations.length, 1);assert.equal(Object.keys(run.candidates).length, 2);const realized = resolveRealization(compilation.program,compilation.elaboration.graph,- run.graphs,+ [run.overlay!],);const request = sealBuildRequest({graph: realized.graph.id,- targets: run.targets.map((item) => ({ output: item.name, accepts: item.accepts })),- satisfactions: run.satisfactions,+ targets: run.graph.targetSets[0]!.targets,+ satisfactions: run.graph.satisfactions,});const state = start(compilation.program, realized.graph, request);assert.equal(state.plan.steps.length, 1);@@ -165,7 +205,8 @@ test(".svrun compiles one multi-export Fragment instance before execution", asyn});test("separate Fragment declarations remain separate executions", async () => {- const document = parseRunDocument("preview.svrun", `<svrun version="1" source="./main.svml" targets="preview">+ const compiledRunSource = await compileDocument(`<svrun version="1" targets="preview">+ <author source="./main.svml"/><import from="@example/run-preview" as="preview"/><target-set id="preview"><target output="left" accepts="substitute"/><target output="right" accepts="substitute"/></target-set><fragment id="left-call" using="preview:shared"><input name="prompt" from="prompt"/><export name="first"/></fragment>@@ -173,28 +214,33 @@ test("separate Fragment declarations remain separate executions", async () => {<satisfy output="left" candidate="left-call.first" fidelity="substitute"/><satisfy output="right" candidate="right-call.second" fidelity="substitute"/></svrun>`);+ const document = compiledRunSource.document;const compilation = fixture();const fragments = new RunFragmentRegistry();fragments.register({ name: "@example/run-preview", fragments: { shared: previewFragment() } });const run = await resolveRunDocument(document, {compilation,+ sourceClosure: compiledRunSource.closure,fragments,readStoredValue() { throw new Error("not used"); },readBuild() { throw new Error("not used"); },});- assert.equal(run.graphs[0]!.operations.length, 2);- assert.equal(new Set(run.graphs[0]!.operations.map((item) => item.id)).size, 2);+ assert.equal(run.graph.operations.length, 2);+ assert.equal(new Set(run.graph.operations.map((item) => item.id)).size, 2);});test("a Provided Value is an ordinary zero-input Candidate selected by Satisfaction", async () => {- const document = parseRunDocument("fixed.svrun", `<svrun version="1" source="./main.svml" targets="preview">+ const compiledRunSource = await compileDocument(`<svrun version="1" targets="preview">+ <author source="./main.svml"/><target-set id="preview"><target output="left" accepts="substitute"/></target-set><value id="fixed" type="example.run@1#Media" from="./fixed.json"/><satisfy output="left" candidate="fixed" fidelity="substitute"/></svrun>`);+ const document = compiledRunSource.document;const compilation = fixture();const run = await resolveRunDocument(document, {compilation,+ sourceClosure: compiledRunSource.closure,fragments: new RunFragmentRegistry(),readStoredValue(from) {assert.equal(from, "./fixed.json");@@ -202,11 +248,11 @@ test("a Provided Value is an ordinary zero-input Candidate selected by Satisfact},readBuild() { throw new Error("not used"); },});- const realized = resolveRealization(compilation.program, compilation.elaboration.graph, run.graphs);+ const realized = resolveRealization(compilation.program, compilation.elaboration.graph, [run.overlay!]);const state = start(compilation.program, realized.graph, sealBuildRequest({graph: realized.graph.id,- targets: run.targets.map((item) => ({ output: item.name, accepts: item.accepts })),- satisfactions: run.satisfactions,+ targets: run.graph.targetSets[0]!.targets,+ satisfactions: run.graph.satisfactions,}));assert.equal(state.plan.steps.length, 0);assert.equal(state.records.find((item) => item.id === state.plan.goals[0]!.record)?.value.kind, "inline");@@ -214,17 +260,79 @@ test("a Provided Value is an ordinary zero-input Candidate selected by Satisfacttest("Run imports are a prologue and Runtime settings are not language elements", () => {assert.throws(- () => parseRunDocument("bad.svrun", `<svrun version="1" source="main.svml" targets="x">+ () => parseRunDocument("bad.svrun", `<svrun version="1" targets="x">+ <author source="./main.svml"/><target-set id="x"><target output="film" accepts="exact"/></target-set><import from="@example/run" as="run"/></svrun>`),/opening prologue/u,);assert.throws(- () => parseRunDocument("bad.svrun", `<svrun version="1" source="main.svml" targets="x">+ () => parseRunDocument("bad.svrun", `<svrun version="1" targets="x">+ <author source="./main.svml"/><target-set id="x"><target output="film" accepts="exact"/></target-set><provider name="kie"/></svrun>`),/does not accept <provider>/u,);});++test("a Target-only execution still compiles one mandatory Run Graph", async () => {+ const compiledRunSource = await compileDocument(`<svrun version="1" targets="delivery">+ <author source="./main.svml"/>+ <target-set id="delivery"><target output="left" accepts="exact"/></target-set>+ </svrun>`);+ const compilation = fixture();+ const run = await resolveRunDocument(compiledRunSource.document, {+ compilation,+ sourceClosure: compiledRunSource.closure,+ fragments: new RunFragmentRegistry(),+ readStoredValue() { throw new Error("not used"); },+ readBuild() { throw new Error("not used"); },+ });+ assert.equal(run.overlay, undefined);+ assert.equal(run.graph.authorGraph, compilation.elaboration.graph.id);+ assert.equal(run.graph.sourceClosure, compiledRunSource.closure.id);+ assert.equal(run.graph.operations.length, 0);+ assert.equal(run.graph.targetSets[0]?.targets[0]?.output, "left");+});++test("Run Source Closure binds source bytes, Frontend implementation and semantic meaning separately", async () => {+ const first = await compileDocument(`<svrun version="1" targets="delivery">+ <author source="./main.svml"/>+ <target-set id="delivery"><target output="left" accepts="exact"/></target-set>+ </svrun>`);+ const second = await compileDocument(`<svrun version="1" targets="delivery">+ <author source="./main.svml"/>++ <target-set id="delivery"><target output="left" accepts="exact"/></target-set>+ </svrun>`);+ assert.notEqual(first.closure.id, second.closure.id);+ assert.equal(first.closure.units[0]?.semanticDigest, second.closure.units[0]?.semanticDigest);+ const unit = first.closure.units[0]!;+ assert.throws(+ () => verifyRunSourceClosure({+ ...first.closure,+ units: [{ ...unit, sourceDigest: digestOf("tampered") }],+ }),+ (error: unknown) => error instanceof RunSourceError && error.code === "RUN_SOURCE_UNIT_DIGEST_MISMATCH",+ );++ const alternate = {+ ...runTextFrontend,+ id: "example.run-text-compatible@1",+ implementationDigest: digestOf("example.run-text-compatible/implementation@1"),+ };+ const frontends = new RunFrontendRegistry();+ frontends.register(alternate);+ const equivalent = await compileRunSource({+ id: "/project/equivalent.svrun",+ name: "equivalent.svrun",+ text: `<?svml using="${alternate.id}"?>\n<svrun version="1" targets="delivery">+ <author source="./main.svml"/>+ <target-set id="delivery"><target output="left" accepts="exact"/></target-set>+ </svrun>`,+ }, frontends);+ assert.notEqual(first.closure.id, equivalent.closure.id);+ assert.equal(first.closure.units[0]?.semanticDigest, equivalent.closure.units[0]?.semanticDigest);+});diff --git a/packages/source/README.md b/packages/source/README.mdnew file mode 100644index 00000000..2b364318--- /dev/null+++ b/packages/source/README.md@@ -0,0 +1,13 @@+# `@svml/source`++The smallest source bootstrap shared by Author and Run compilation.++It recognizes exactly one mandatory bounded Header:++```xml+<?svml using="@svml/text@1"?>+```++The Header selects an exact trusted Frontend. There is no suffix dispatch and no default parser.+The package masks the Header while preserving character offsets, but does not recognize imports,+XML, Script, Recipes, Run syntax or domain Types. Those belong to the selected Frontend.diff --git a/packages/source/package.json b/packages/source/package.jsonnew file mode 100644index 00000000..f78c16c2--- /dev/null+++ b/packages/source/package.json@@ -0,0 +1,9 @@+{+ "name": "@svml/source",+ "version": "0.0.0-dev",+ "private": true,+ "type": "module",+ "exports": {+ ".": "./src/index.ts"+ }+}diff --git a/packages/source/src/header.ts b/packages/source/src/header.tsnew file mode 100644index 00000000..3ab3feaf--- /dev/null+++ b/packages/source/src/header.ts@@ -0,0 +1,78 @@+export type SourceHeader = {+ readonly format: "svml.source-header@1";+ /** Logical Frontend request. A trusted Host resolves it to one exact implementation. */+ readonly using: string;+ readonly start: number;+ readonly end: number;+};++export class SourceHeaderError extends Error {+ readonly code: string;+ readonly sourceName: string;+ readonly offset: number;++ constructor(code: string, message: string, sourceName: string, offset: number) {+ super(`${sourceName}:${offset}: ${message}`);+ this.name = "SourceHeaderError";+ this.code = code;+ this.sourceName = sourceName;+ this.offset = offset;+ }+}++const MAX_HEADER_BYTES = 4_096;+const FRONTEND = /^[^\s<>&'"]+$/u;++function fail(sourceName: string, code: string, message: string, offset: number): never {+ throw new SourceHeaderError(code, message, sourceName, offset);+}++/**+ * Parse the single irreducible SVML bootstrap directive.+ *+ * The grammar deliberately has no comments, aliases, interpolation or defaults:+ *+ * [UTF-8 BOM] <?svml using="logical-frontend-request"?>+ */+export function parseSourceHeader(sourceName: string, text: string): SourceHeader {+ const start = text.charCodeAt(0) === 0xfeff ? 1 : 0;+ if (!text.startsWith("<?svml", start)) {+ fail(sourceName, "SOURCE_HEADER_MISSING", 'Source must begin with <?svml using="..."?>', start);+ }+ const bounded = text.slice(start, start + MAX_HEADER_BYTES + 1);+ const relativeClose = bounded.indexOf("?>", "<?svml".length);+ if (relativeClose < 0) {+ fail(sourceName, "SOURCE_HEADER_UNCLOSED", `Source Header must close within ${MAX_HEADER_BYTES} bytes`, start);+ }+ const close = start + relativeClose;+ const raw = text.slice(start, close + 2);+ if (new TextEncoder().encode(raw).byteLength > MAX_HEADER_BYTES) {+ fail(sourceName, "SOURCE_HEADER_UNCLOSED", `Source Header must close within ${MAX_HEADER_BYTES} bytes`, start);+ }+ const match = /^<\?svml[ \t]+using=(['"])([^'"\r\n]+)\1[ \t]*\?>$/u.exec(raw);+ if (match === null) {+ fail(+ sourceName,+ "SOURCE_HEADER_INVALID",+ 'Source Header must use exactly <?svml using="logical-frontend-request"?>',+ start,+ );+ }+ const using = match[2]!;+ if (!FRONTEND.test(using)) {+ fail(sourceName, "SOURCE_HEADER_FRONTEND", "Source Header Frontend request must not be empty or padded", start);+ }+ const end = close + 2;+ const after = text.slice(end);+ const nextContent = /\S/u.exec(after);+ if (nextContent !== null && after.startsWith("<?svml", nextContent.index)) {+ fail(sourceName, "SOURCE_HEADER_DUPLICATE", "Source declares more than one Source Header", end + nextContent.index);+ }+ return { format: "svml.source-header@1", using, start, end };+}++/** Preserve every original offset while making the Header ordinary whitespace to body Frontends. */+export function maskSourceHeader(text: string, header: SourceHeader): string {+ const prefix = text.slice(0, header.end).replace(/[^\r\n]/gu, " ");+ return `${prefix}${text.slice(header.end)}`;+}diff --git a/packages/source/src/index.ts b/packages/source/src/index.tsnew file mode 100644index 00000000..e712685f--- /dev/null+++ b/packages/source/src/index.ts@@ -0,0 +1,6 @@+export {+ maskSourceHeader,+ parseSourceHeader,+ SourceHeaderError,+} from "./header.js";+export type { SourceHeader } from "./header.js";diff --git a/packages/source/test/header.test.ts b/packages/source/test/header.test.tsnew file mode 100644index 00000000..b83e0390--- /dev/null+++ b/packages/source/test/header.test.ts@@ -0,0 +1,41 @@+import assert from "node:assert/strict";+import test from "node:test";++import {+ maskSourceHeader,+ parseSourceHeader,+ SourceHeaderError,+} from "@svml/source";++test("Source Header explicitly selects one Frontend and masking preserves offsets", () => {+ const text = '<?svml using="@svml/text@1"?>\n\n<svml/>\n';+ const header = parseSourceHeader("main.svml", text);+ assert.equal(header.using, "@svml/text@1");+ const masked = maskSourceHeader(text, header);+ assert.equal(masked.length, text.length);+ assert.equal(masked.indexOf("<svml/>"), text.indexOf("<svml/>"));+ assert.equal(masked.slice(0, header.end).trim(), "");+});++test("Source Header accepts a UTF-8 BOM but no implicit or duplicate Frontend", () => {+ assert.equal(+ parseSourceHeader("bom.svs", '\ufeff<?svml using="@svml/svs@1"?>\n<sheet/>').using,+ "@svml/svs@1",+ );+ assert.throws(+ () => parseSourceHeader("missing.svml", "<svml/>"),+ (error: unknown) => error instanceof SourceHeaderError && error.code === "SOURCE_HEADER_MISSING",+ );+ assert.throws(+ () => parseSourceHeader("duplicate.svml", '<?svml using="a@1"?>\n<?svml using="b@1"?>'),+ (error: unknown) => error instanceof SourceHeaderError && error.code === "SOURCE_HEADER_DUPLICATE",+ );+ assert.throws(+ () => parseSourceHeader("padded.svml", '<?svml using=" a@1"?>\n<body/>'),+ (error: unknown) => error instanceof SourceHeaderError && error.code === "SOURCE_HEADER_FRONTEND",+ );+ assert.throws(+ () => parseSourceHeader("oversized.svml", `<?svml using="${"界".repeat(1_500)}"?>\n<body/>`),+ (error: unknown) => error instanceof SourceHeaderError && error.code === "SOURCE_HEADER_UNCLOSED",+ );+});diff --git a/packages/speech-program/test/surface.test.ts b/packages/speech-program/test/surface.test.tsindex 6d5bdacd..67071730 100644--- a/packages/speech-program/test/surface.test.ts+++ b/packages/speech-program/test/surface.test.ts@@ -38,7 +38,6 @@ import {import {TextSurfaceRegistry,createTextAuthorFrontend,- textAuthorFrontendId,} from "@svml/text";import { createRecordAdmitter, TypeValidatorRegistry } from "@svml/validation";@@ -57,7 +56,11 @@ const fixtureManifest: ModuleManifest = {};function source(text: string): AuthorSourceUnit {- return { id: "/project/main.svml", name: "main.svml", text };+ return {+ id: "/project/main.svml",+ name: "main.svml",+ text: `<?svml using="@svml/text@1"?>\n${text}`,+ };}test("Speech Spine lowers ordered Takes into media normalization, one audio plan and peer projections", async () => {@@ -106,7 +109,6 @@ test("Speech Spine lowers ordered Takes into media normalization, one audio plan<speech:Take source={take-two} segment={story.segment.answer}/></speech:Spine></svml>`),- frontend: textAuthorFrontendId,closure,frontends,admitRecord: createRecordAdmitter(validators),diff --git a/packages/svs/README.md b/packages/svs/README.mdindex 316853e3..4d89bfcc 100644--- a/packages/svs/README.md+++ b/packages/svs/README.md@@ -1,6 +1,7 @@# `@svml/svs`-Minimal official parameter-recipe Frontend for `.svs` SourceUnits.+Minimal official parameter-recipe Frontend normally used by `.svs` SourceUnits. The source must+select it explicitly with `<?svml using="@svml/svs@1"?>`; the suffix is only a human convention.SVS v1 reads a `<sheet version="1">` containing named rule blocks and emits one immutable generic`Recipe` Record per rule. It does not know Caption, Film, Track or Provider parameters and it doesdiff --git a/packages/svs/package.json b/packages/svs/package.jsonindex bc81fe21..d6c9fb8a 100644--- a/packages/svs/package.json+++ b/packages/svs/package.json@@ -12,6 +12,7 @@"@svml/protocol": "workspace:*"},"devDependencies": {+ "@svml/source": "workspace:*","@svml/text": "workspace:*"}}diff --git a/packages/svs/src/frontend.ts b/packages/svs/src/frontend.tsindex c466d1eb..805741c8 100644--- a/packages/svs/src/frontend.ts+++ b/packages/svs/src/frontend.ts@@ -1,5 +1,4 @@import {- digestOf,sealRecord,sealTypedModule,verifyClosure,@@ -25,7 +24,7 @@ export const svsFrontend: AuthorFrontend = {decode(source, context) {verifyClosure(context.closure);const parsed = parseSvs(source.name, source.text);- const sourceDigest = digestOf(source.text);+ const sourceDigest = source.sourceDigest;const records = parsed.recipes.map((recipe) => sealRecord({id: recipe.value.path,type: svsRecipeType,diff --git a/packages/svs/test/source-closure.test.ts b/packages/svs/test/source-closure.test.tsindex 32b18d9d..2b41859a 100644--- a/packages/svs/test/source-closure.test.ts+++ b/packages/svs/test/source-closure.test.ts@@ -24,11 +24,11 @@ import type {TypeRef,TypedRecord,} from "@svml/protocol";+import { maskSourceHeader, parseSourceHeader } from "@svml/source";import {SvsSyntaxError,parseSvs,svsFrontend,- svsFrontendId,svsManifest,svsRecipeType,} from "@svml/svs";@@ -36,7 +36,6 @@ import type { SvsRecipe } from "@svml/svs";import {TextSurfaceRegistry,createTextAuthorFrontend,- textAuthorFrontendId,} from "@svml/text";import type { StructuredElement } from "@svml/text";@@ -185,8 +184,13 @@ function sourceRegistry(): TextSurfaceRegistry {const closure = createResolvedClosure([svsManifest, manifest]);-function unit(id: string, text: string): AuthorSourceUnit {- return { id, name: id.split("/").at(-1) ?? id, text };+function unit(id: string, text: string, frontend?: string): AuthorSourceUnit {+ const selected = frontend ?? (id.endsWith(".svs") ? "@svml/svs@1" : "@svml/text@1");+ return {+ id,+ name: id.split("/").at(-1) ?? id,+ text: `<?svml using="${selected}"?>\n${text}`,+ };}const styleText = `<sheet version="1" id="studio">@@ -205,12 +209,11 @@ async function compileMain(alias: string, root = "/project", styles = styleText)frontends.register(svsFrontend);const entry = unit(`${root}/main.svml`, `<svml><import as="lab" from="example.recipe-card@1"/>- <import as="${alias}" from="./studio.svs" using="${svsFrontendId}"/>+ <import as="${alias}" source="./studio.svs"/><lab:Card id="answer" appearance={${alias}.card.answer}/></svml>`);return await compileSourceClosure({entry,- frontend: textAuthorFrontendId,closure,frontends,async resolveSource(_importer, request) {@@ -286,6 +289,31 @@ test("relocating the same source tree preserves Source Closure and Graph identitassert.equal(original.elaboration.graph.id, relocated.elaboration.graph.id);});+test("Frontend identity changes Source Closure identity but not equal decoded author meaning", async () => {+ const alternate = {+ ...svsFrontend,+ id: "example.svs-compatible@1",+ implementationDigest: digestOf("example.svs-compatible/implementation@1"),+ };+ const compileWith = async (frontend: typeof svsFrontend | typeof alternate) => {+ const frontends = new AuthorFrontendRegistry();+ frontends.register(frontend);+ return await compileSourceClosure({+ entry: unit("/project/studio.any", styleText, frontend.id),+ closure,+ frontends,+ resolveSource() { throw new Error("not used"); },+ });+ };+ const official = await compileWith(svsFrontend);+ const compatible = await compileWith(alternate);+ assert.notEqual(official.closure.id, compatible.closure.id);+ assert.notEqual(official.closure.units[0]?.frontendDigest, compatible.closure.units[0]?.frontendDigest);+ assert.equal(official.closure.units[0]?.semanticDigest, compatible.closure.units[0]?.semanticDigest);+ assert.equal(official.module.semanticDigest, compatible.module.semanticDigest);+ assert.equal(official.elaboration.graph.id, compatible.elaboration.graph.id);+});+test("Source Closure binds every recursive SourceUnit digest", async () => {const compiled = await compileMain("studio");const first = compiled.closure.units[0]!;@@ -306,12 +334,11 @@ test("Source Closure rejects recursive source import cycles", async () => {registry: new TextSurfaceRegistry(),resolveModule: () => laboratory,}));- const a = unit("/project/a.svml", `<svml><import as="b" from="./b.svml" using="${textAuthorFrontendId}"/></svml>`);- const b = unit("/project/b.svml", `<svml><import as="a" from="./a.svml" using="${textAuthorFrontendId}"/></svml>`);+ const a = unit("/project/a.svml", `<svml><import as="b" source="./b.svml"/></svml>`);+ const b = unit("/project/b.svml", `<svml><import as="a" source="./a.svml"/></svml>`);await assert.rejects(compileSourceClosure({entry: a,- frontend: textAuthorFrontendId,closure,frontends,resolveSource(_importer, request) {@@ -329,14 +356,13 @@ test("Source Closure rejects duplicate aliases and unknown Frontends before decoresolveModule: () => laboratory,}));const duplicate = unit("/project/duplicate.svml", `<svml>- <import as="styles" from="./one.svs" using="${svsFrontendId}"/>- <import as="styles" from="./two.svs" using="${svsFrontendId}"/>+ <import as="styles" source="./one.svs"/>+ <import as="styles" source="./two.svs"/></svml>`);frontends.register(svsFrontend);await assert.rejects(compileSourceClosure({entry: duplicate,- frontend: textAuthorFrontendId,closure,frontends,resolveSource(_importer, request) {@@ -346,13 +372,10 @@ test("Source Closure rejects duplicate aliases and unknown Frontends before deco(error: unknown) => error instanceof SourceClosureError && error.code === "DUPLICATE_SOURCE_ALIAS",);- const unknown = unit("/project/unknown.svml", `<svml>- <import as="styles" from="./studio.svs" using="example.unknown@1"/>- </svml>`);+ const unknown = unit("/project/unknown.svml", `<svml/>`, "example.unknown@1");await assert.rejects(compileSourceClosure({entry: unknown,- frontend: textAuthorFrontendId,closure,frontends,resolveSource() {@@ -365,7 +388,7 @@ test("Source Closure rejects duplicate aliases and unknown Frontends before decotest("the golden studio.svs parses as generic Recipes without video knowledge", () => {const source = readFileSync(new URL("../../../examples/talking-film-golden/studio.svs", import.meta.url), "utf8");- const parsed = parseSvs("studio.svs", source);+ const parsed = parseSvs("studio.svs", maskSourceHeader(source, parseSourceHeader("studio.svs", source)));assert.equal(parsed.recipes.length, 10);assert.equal(parsed.recipes.find((recipe) => recipe.value.path === "caption.short-cues")?.value.properties.model, "gemini-2.5-flash");assert.equal(parsed.recipes.find((recipe) => recipe.value.path === "film.vertical")?.value.properties.width, 1080);diff --git a/packages/text/README.md b/packages/text/README.mdindex db3d0557..52292d5d 100644--- a/packages/text/README.md+++ b/packages/text/README.md@@ -1,6 +1,7 @@# `@svml/text`-Official XML-like Author Frontend for `.svml` source units. It owns only the `<svml>` envelope,+Official XML-like Author Frontend normally used by `.svml` source units. The suffix has no parser+authority; a mandatory `<?svml using="@svml/text@1"?>` Header selects this Frontend. It owns only the `<svml>` envelope,the leading Import Prologue, namespace binding, generic structured elements and dispatch tostatically declared module Surfaces.@@ -10,8 +11,10 @@ implementation. The current registry is for trusted official/in-process use; itsandbox for third-party parser code.```svml+<?svml using="@svml/text@1"?><svml>- <import from="@svml/[email protected]"/>+ <import from="@svml/script@1"/>+ <import as="studio" source="./studio.svs"/><script id="story"><opening><ALICE>Hello.</opening>@@ -45,5 +48,6 @@ resolves forward references and emits the Core Graph.Direct `decodeText()` calls require every source import to be supplied as an already resolvednamespace. The reference `compileSourceClosure()` orchestration in `@svml/elaborator` recursively-discovers those SourceUnits, selects the exact `using` Frontend, decodes dependencies first and then-calls Text with their locked public exports. Text itself never reads a file or guesses a Frontend.+discovers those SourceUnits. Each dependency's own Source Header selects its exact Frontend; Text+never chooses a dependency parser. The compiler decodes dependencies first and then calls Text with+their locked public exports. Text itself never reads a file or guesses a Frontend.diff --git a/packages/text/src/frontend.ts b/packages/text/src/frontend.tsindex c1fb9338..8315f993 100644--- a/packages/text/src/frontend.ts+++ b/packages/text/src/frontend.ts@@ -94,7 +94,7 @@ function surfaceScope(if (aliases.has(request.alias)) fail(source, "TEXT_ALIAS_DUPLICATE", `Duplicate import alias "${request.alias}".`, request.range.start);aliases.add(request.alias);}- if (request.using !== undefined) continue;+ if (request.kind === "source") continue;const module = moduleForImport(source, request, context);for (const declaration of module.manifest.surfaces) {const tag = request.alias === undefined ? declaration.tag : `${request.alias}:${declaration.tag}`;@@ -111,11 +111,10 @@ export async function decodeText(source: SourceUnit, context: TextDecodeContext)const sourceImports = context.sourceImports ?? [];const importedBindings = new Map<string, AuthorSourceExport>();const importedReferences = new Map<string, SurfaceResolvedReference>();- for (const request of discovery.imports.filter((item) => item.using !== undefined)) {+ for (const request of discovery.imports.filter((item) => item.kind === "source")) {const resolved = sourceImports.find((item) =>item.request.from === request.from- && item.request.alias === request.alias- && item.request.frontend === request.using);+ && item.request.alias === request.alias);if (resolved === undefined) {fail(source,@@ -143,7 +142,7 @@ export async function decodeText(source: SourceUnit, context: TextDecodeContext)}}const scope = surfaceScope(source, discovery.imports, context);- const sourceDigest = digestOf(source.text);+ const sourceDigest = source.sourceDigest ?? digestOf(source.text);const frontendClosureDigest = digestOf({frontend: textFrontendImplementationDigest,surfaces: [...scope.values()]@@ -159,7 +158,8 @@ export async function decodeText(source: SourceUnit, context: TextDecodeContext).map((item) => ({from: item.request.from,alias: item.request.alias,- frontend: item.request.frontend,+ frontend: item.frontend,+ frontendDigest: item.frontendDigest,source: item.source,exports: item.exports,}))@@ -435,21 +435,20 @@ export function createTextAuthorFrontend(options: TextAuthorFrontendOptions): Tediscover(source) {const discovery = discoverText(source);return {- modules: discovery.imports.filter((item) => item.using === undefined).map((item) => item.from),+ modules: discovery.imports.filter((item) => item.kind === "module").map((item) => item.from),sources: discovery.imports- .filter((item): item is TextImportRequest & { alias: string; using: string } =>- item.using !== undefined && item.alias !== undefined)+ .filter((item): item is TextImportRequest & { alias: string; kind: "source" } =>+ item.kind === "source" && item.alias !== undefined).map((item) => ({from: item.from,alias: item.alias,- frontend: item.using,range: item.range,})),};},async decode(source, context) {const result = await decodeText(- { name: source.name, text: source.text },+ { name: source.name, text: source.text, sourceDigest: source.sourceDigest },{closure: context.closure,registry: options.registry,diff --git a/packages/text/src/syntax.ts b/packages/text/src/syntax.tsindex 767fb74a..ff082670 100644--- a/packages/text/src/syntax.ts+++ b/packages/text/src/syntax.ts@@ -210,18 +210,22 @@ function importRequest(source: SourceUnit, opening: OpeningTag): TextImportRequeif (opening.name !== "import" || !opening.selfClosing) {fail(source, "TEXT_IMPORT", "Imports must use <import .../>.", opening.start);}- const unknown = Object.keys(opening.attributes).filter((name) => !["from", "as", "using"].includes(name));+ const unknown = Object.keys(opening.attributes).filter((name) => !["from", "source", "as"].includes(name));if (unknown.length) fail(source, "TEXT_IMPORT", `Unknown import attribute "${unknown[0]}".`, opening.start);const alias = stringAttribute(source, opening, "as");if (alias !== undefined && !ALIAS.test(alias)) fail(source, "TEXT_IMPORT_ALIAS", `Invalid alias "${alias}".`, opening.start);- const using = stringAttribute(source, opening, "using");- if (using !== undefined && alias === undefined) {- fail(source, "TEXT_IMPORT_USING", "A source import using a codec requires an alias.", opening.start);+ const module = stringAttribute(source, opening, "from");+ const importedSource = stringAttribute(source, opening, "source");+ if ((module === undefined) === (importedSource === undefined)) {+ fail(source, "TEXT_IMPORT_KIND", "<import> requires exactly one of from or source.", opening.start);+ }+ if (importedSource !== undefined && alias === undefined) {+ fail(source, "TEXT_IMPORT_SOURCE_ALIAS", "A source import requires an alias.", opening.start);}return {- from: stringAttribute(source, opening, "from", true)!,+ kind: importedSource === undefined ? "module" : "source",+ from: importedSource ?? module!,...(alias === undefined ? {} : { alias }),- ...(using === undefined ? {} : { using }),range: { start: opening.start, end: opening.end },};}diff --git a/packages/text/src/types.ts b/packages/text/src/types.tsindex 8d9aeca4..676eb1fb 100644--- a/packages/text/src/types.ts+++ b/packages/text/src/types.ts@@ -25,12 +25,14 @@ import type {export type SourceUnit = {readonly name: string;readonly text: string;+ /** Whole unmasked source digest supplied by Source Closure compilation. */+ readonly sourceDigest?: Digest;};export type TextImportRequest = {+ readonly kind: "module" | "source";readonly from: string;readonly alias?: string;- readonly using?: string;readonly range: SourceRange;};diff --git a/packages/video-cli/README.md b/packages/video-cli/README.mdindex 3ab7fb73..d60af7d6 100644--- a/packages/video-cli/README.md+++ b/packages/video-cli/README.md@@ -2,9 +2,9 @@Official v2 video command-line Distribution.-Unlike the generic `@svml/cli` engine, this application is allowed to choose a trusted default prelude. It+Unlike the generic `@svml/cli` engine, this application is an explicit trusted video assembly. Itdepends on the one ordinary `@svml/prelude-video` aggregate rather than importing each video package-itself. The current prelude contributes:+itself, and registers the optional `@svml/run-text` Frontend. The current prelude contributes:- package-owned Text Surface Host facets consumed by `@svml/compiler-text-node`;- the Script raw Surface and its audiovisual Narrative contract dependency;@@ -21,11 +21,9 @@ From the repository:pnpm svml:v2 check path/to/main.svmlpnpm svml:v2 lock-packages ./svml.packages.lock --package @example/cards --root .pnpm svml:v2 check path/to/main.svml --package-lock ./svml.packages.lock --root .-pnpm svml:v2 plan path/to/main.svml --target component.resultpnpm svml:v2 check path/to/build.svrunpnpm svml:v2 plan path/to/build.svrunpnpm svml:v2 build path/to/build.svrun --runtime ./svml.runtime.json --build-id delivery-01 --follow-pnpm svml:v2 build path/to/main.svml --target final.video --runtime ./svml.runtime.ts --pin shot=<prior-build-id> --accept-substitute --build-id variant-01 --followpnpm svml:v2 status <build-id> --runtime ./svml.runtime.jsonpnpm svml:v2 builds --runtime ./svml.runtime.jsonpnpm svml:v2 inspect <build-id> --runtime ./svml.runtime.json@@ -33,10 +31,10 @@ pnpm svml:v2 get <build-id> --name final.video --runtime ./svml.runtime.json --tpnpm svml:v2 cancel <build-id> --runtime ./svml.runtime.json```-`check` is usable for the complete provider-free author graph in-`examples/talking-film-graph-check`. `plan` is fully implemented by the generic Node compiler. The-live example now executes the explicit Vertex Gemini Caption package and real local/remote-Endpoints; the CLI never fabricates missing facts.+`check` is usable for an Author Source or a complete Run Source. `plan` and `build` require a Run+Source because an Author Graph without execution intent is not a Build. The live example executes+the explicit Vertex Gemini Caption package and real local/remote Endpoints; the CLI never+fabricates a Target, Candidate or missing fact.`build` compiles the same locked BuildState and passes it to a trusted local Runtime Profile.The default Build identity is content-derived, so the same invocation resumes durable local state;@@ -62,20 +60,18 @@ value as JSON. It is Host egress only and never changes Build identity or retentand presentation names only. It is not Core truth or a Runtime Closure facet; `inspect` and `get`always resolve the alias back through the verified BuildState before accepting it.-`--pin output=<prior-build-id>` is temporary CLI compatibility language, not a Core primitive. The Host-verifies the prior Build only to extract a typed Record, attaches it as an ordinary zero-input-`substitute` Candidate, and adds an explicit Satisfaction to a newly compiled BuildRequest. It does not-prove that the old Graph, prompt or semantic meaning matches the current output. Consequently the-command requires `--accept-substitute`. Upstream work behind that selected Candidate is not-demanded, while every unbound reachable output follows the ordinary graph. The prior artifact must-still exist in the ArtifactStore selected by the Runtime. This is a new Build with a new identity;-it never resumes or copies the prior Build's outstanding Commands. `.svrun` is now the general Run-Graph, Target and Satisfaction language; this narrow flag remains only migration compatibility.+Historical Records, fixed files and generated previews are declared as ordinary Candidates in the+Run Source and selected by explicit Satisfaction edges. The Host verifies a referenced prior Build+only to extract the declared typed Record; it does not prove semantic affinity with the current+output. Upstream work behind the selected Candidate is pruned by reverse reachability, while every+unbound reachable output follows the ordinary graph. This is a new Build identity and never resumes+or copies the prior Build's outstanding Commands.`@svml/package-loader-node` supports explicitly trusted installed implementation packages. Itverifies the complete physical dependency closure before executing an activation entry, then checks-exact Module, Frontend, Host-facet, Producer and Validator identities. The Loader does not select a-syntax; this Distribution explicitly chooses `@svml/compiler-text-node`. `plan` and `build` bind the-lock digest into `BuildRequest.implementationClosure`. Source cannot install a package or activate-Provider/Runtime authority. Arbitrary untrusted community execution remains absent until an-isolated Worker and real permission boundary exist.+exact Module, Author/Run Frontend, Host-facet, Producer and Validator identities. The Loader does not+select a syntax; each Source Header selects among Frontends trusted by this Distribution and its+locked packages. Run Fragment libraries enter only through the `svml.run-fragment-host@1` facet.+`plan` and `build` bind the lock digest into `BuildRequest.implementationClosure`. Source cannot+install a package or activate Provider/Runtime authority. Arbitrary untrusted community execution+remains absent until an isolated Worker and real permission boundary exist.diff --git a/packages/video-cli/package.json b/packages/video-cli/package.jsonindex e3896e71..7c468bde 100644--- a/packages/video-cli/package.json+++ b/packages/video-cli/package.json@@ -17,6 +17,7 @@"@svml/provider-kie": "workspace:*","@svml/provider-media-local": "workspace:*","@svml/provider-whisperx-local": "workspace:*",+ "@svml/run-text": "workspace:*","@svml/protocol": "workspace:*","@svml/runtime": "workspace:*"}diff --git a/packages/video-cli/src/distribution.ts b/packages/video-cli/src/distribution.tsindex 07662099..11196d16 100644--- a/packages/video-cli/src/distribution.ts+++ b/packages/video-cli/src/distribution.ts@@ -1,4 +1,5 @@import type { CliDistribution } from "@svml/cli";+import { runTextFrontend } from "@svml/run-text";import {createVideoCompiler,@@ -10,6 +11,7 @@ import { createVideoRuntimeFromConfig } from "./runtime-config.js";export const videoCliDistribution: CliDistribution = {name: "@svml/video-cli",builtInPackageContributions: videoBuiltInPackageContributions,+ runFrontends: [runTextFrontend],createCompiler: createVideoCompiler,createRuntimeFromConfig: createVideoRuntimeFromConfig,};diff --git a/packages/video-cli/test/cli.test.ts b/packages/video-cli/test/cli.test.tsindex 4f2006c0..1f1a8bfe 100644--- a/packages/video-cli/test/cli.test.ts+++ b/packages/video-cli/test/cli.test.ts@@ -7,7 +7,23 @@ import test from "node:test";import { materializeRecord, runVideoCli as runCli } from "@svml/video-cli";-test("CLI Pin is explicit substitute selection rather than an exact-history privilege", async () => {+async function writeRun(+ root: string,+ name: string,+ targets: readonly { readonly output: string; readonly accepts?: "exact" | "substitute" }[],+): Promise<string> {+ const path = join(root, name);+ await writeFile(path, `<?svml using="@svml/run-text@1"?>+<svrun version="1" targets="selected">+ <author source="./main.svml"/>+ <target-set id="selected">+ ${targets.map((target) => `<target output="${target.output}" accepts="${target.accepts ?? "exact"}"/>`).join("\n ")}+ </target-set>+</svrun>`, "utf8");+ return path;+}++test("CLI refuses to synthesize hidden Run intent from Pin and Target flags", async () => {await assert.rejects(async () => await runCli(["build", "unused.svml",@@ -15,7 +31,7 @@ test("CLI Pin is explicit substitute selection rather than an exact-history priv"--runtime", "unused-runtime.ts","--pin", "shot=sha256:historical",], { write() {} }),- /--pin attaches substitute Candidates; add --accept-substitute/u,+ /belong in a self-described Run Source/u,);});@@ -31,15 +47,17 @@ test("CLI does not confuse Build persistence with the removed --out convenience"test("official v2 CLI checks a real Script source through the Node compiler host", async () => {const root = await mkdtemp(join(tmpdir(), "svml-cli-"));const file = join(root, "main.svml");- await writeFile(join(root, "studio.svs"), `<sheet version="1">+ await writeFile(join(root, "studio.svs"), `<?svml using="@svml/svs@1"?>+<sheet version="1">caption.host {color: #ffffff;font-size: 72;}</sheet>`, "utf8");- await writeFile(file, `<svml>+ await writeFile(file, `<?svml using="@svml/text@1"?>+<svml><import from="@svml/script@1"/>- <import as="studio" from="./studio.svs" using="@svml/svs@1"/>+ <import as="studio" source="./studio.svs"/><script id="story"><opening><ALICE>Meaning becomes the source.@@ -89,7 +107,8 @@ test("official media and Seedance Surfaces lower author intent into exact generaconst root = await mkdtemp(join(tmpdir(), "svml-cli-generation-"));const file = join(root, "main.svml");await writeFile(join(root, "host.png"), new Uint8Array([137, 80, 78, 71]));- await writeFile(file, `<svml>+ await writeFile(file, `<?svml using="@svml/text@1"?>+<svml><import from="@svml/script@1"/><import as="media" from="@svml/media@1"/><import as="seedance" from="@svml/seedance@1"/>@@ -129,10 +148,12 @@ test("official media and Seedance Surfaces lower author intent into exact genera]);let planOutput = "";+ const run = await writeRun(root, "generation.svrun", [+ { output: "take" },+ { output: "motion.video" },+ ]);await runCli([- "plan", file,- "--target", "take",- "--target", "motion.video",+ "plan", run,], { write: (text) => { planOutput += text; } });const plan = JSON.parse(planOutput) as {readonly goals: readonly unknown[];@@ -154,12 +175,15 @@ test(".svrun is the complete human-readable Target graph used by plan", async ()const root = await mkdtemp(join(tmpdir(), "svml-cli-run-"));const source = join(root, "main.svml");const run = join(root, "preview.svrun");- await writeFile(source, `<svml>+ await writeFile(source, `<?svml using="@svml/text@1"?>+<svml><import as="seedance" from="@svml/seedance@1"/><seedance:Prompt id="direction">A quiet locked-off studio shot.</seedance:Prompt><seedance:Video id="motion" model="mini" prompt={direction} duration="4"/></svml>`, "utf8");- await writeFile(run, `<svrun version="1" source="./main.svml" targets="preview">+ await writeFile(run, `<?svml using="@svml/run-text@1"?>+ <svrun version="1" targets="preview">+ <author source="./main.svml"/><target-set id="preview"><target output="motion.video" accepts="exact"/></target-set>@@ -178,7 +202,7 @@ test(".svrun is the complete human-readable Target graph used by plan", async ()]);await assert.rejects(async () => await runCli(["plan", run, "--target", "motion.video"], { write() {} }),- /.svrun owns Targets/u,+ /belong in a self-described Run Source/u,);});@@ -208,7 +232,8 @@ test("CLI accepts a declarative Runtime Profile without an executable config modtest("official prelude lowers Speech Spine and explicit WhisperX alignment without provider calls", async () => {const root = await mkdtemp(join(tmpdir(), "svml-cli-speech-spine-"));const file = join(root, "main.svml");- await writeFile(file, `<svml>+ await writeFile(file, `<?svml using="@svml/text@1"?>+<svml><import from="@svml/script@1"/><import as="seedance" from="@svml/seedance@1"/><import as="speech" from="@svml/speech@1"/>@@ -232,16 +257,18 @@ test("official prelude lowers Speech Spine and explicit WhisperX alignment withotest("Caption Gemini Surface lowers immutable display-atom runs into one explicit planning Need", async () => {const root = await mkdtemp(join(tmpdir(), "svml-cli-caption-gemini-"));const file = join(root, "main.svml");- await writeFile(join(root, "studio.svs"), `<sheet version="1">+ await writeFile(join(root, "studio.svs"), `<?svml using="@svml/svs@1"?>+<sheet version="1">caption.base { stack-order: 70; x: 0.08; y: 0.76; width: 0.84; font: Inter;weight: 600; size: 58; line-height: 1; align: center; fill: #FFFFFF;background: #09090BCC; padding: 16 24; radius: 18; }</sheet>`, "utf8");- await writeFile(file, `<svml>+ await writeFile(file, `<?svml using="@svml/text@1"?>+<svml><import from="@svml/script@1"/><import as="caption" from="@svml/caption@1"/><import as="gemini" from="@svml/caption-gemini@1"/>- <import as="studio" from="./studio.svs" using="@svml/svs@1"/>+ <import as="studio" source="./studio.svs"/><script id="story"><dialogue><ALICE>Meaning becomes the source.<BOB>Then the graph stays explicit.</dialogue></script><caption:Style id="plain" appearance={studio.caption.base}><caption:Cues>Prefer short complete semantic phrases. Never cross clause punctuation.</caption:Cues>@@ -263,7 +290,8 @@ test("Caption Gemini Surface lowers immutable display-atom runs into one expliciassert.equal(checked.exports.some((item) => item.name === "caption-program"), true);assert.equal(checked.exports.some((item) => item.name === "dialogue-plan.plan"), true);let planOutput = "";- await runCli(["plan", file, "--target", "dialogue-plan.plan"], { write: (text) => { planOutput += text; } });+ const run = await writeRun(root, "caption.svrun", [{ output: "dialogue-plan.plan" }]);+ await runCli(["plan", run], { write: (text) => { planOutput += text; } });const plan = JSON.parse(planOutput) as { readonly steps: readonly { readonly producer: { readonly name: string } }[] };assert.deepEqual(plan.steps.map((step) => step.producer.name).sort(), ["compile-caption-gemini-request",@@ -274,7 +302,8 @@ test("Caption Gemini Surface lowers immutable display-atom runs into one explicitest("Track Surfaces close one complete author graph before any external execution", async () => {const root = await mkdtemp(join(tmpdir(), "svml-cli-complete-author-"));const file = join(root, "main.svml");- await writeFile(join(root, "studio.svs"), `<sheet version="1">+ await writeFile(join(root, "studio.svs"), `<?svml using="@svml/svs@1"?>+<sheet version="1">film.vertical { width: 1080; height: 1920; frame-rate: 30; background: #09090B; }broll.card { stack-order: 40; x: 0.1; y: 0.2; width: 0.8; height: 0.5; fit: cover;background: #111116; radius: 20; enter: slide-up 4f; exit: fade 4f; }@@ -284,7 +313,8 @@ test("Track Surfaces close one complete author graph before any external executitext.title { stack-order: 90; x: 0.06; y: 0.06; width: 0.88; height: 0.1;font: Inter; weight: 900; size: 64; align: center; fill: #FFFFFF; tracking: -1; }</sheet>`, "utf8");- await writeFile(file, `<svml>+ await writeFile(file, `<?svml using="@svml/text@1"?>+<svml><import from="@svml/script@1"/><import as="seedance" from="@svml/seedance@1"/><import as="speech" from="@svml/speech@1"/>@@ -295,7 +325,7 @@ test("Track Surfaces close one complete author graph before any external executi<import as="text" from="@svml/text-track@1"/><import as="film" from="@svml/film@1"/><import as="render" from="@svml/hyperframes-render@1"/>- <import as="studio" from="./studio.svs" using="@svml/svs@1"/>+ <import as="studio" source="./studio.svs"/><script id="story"><opening><HOST>Meaning @demo becomes the source @/demo.</opening></script><seedance:Prompt id="direction">Locked medium close-up.</seedance:Prompt><seedance:Speech id="take" model="mini" dialogue={story.segment.opening.dialogue} prompt={direction} duration="5"/>@@ -334,7 +364,8 @@ test("Track Surfaces close one complete author graph before any external executitest("official v2 CLI closes the explicit HyperFrames render package without loading a Provider", async () => {const root = await mkdtemp(join(tmpdir(), "svml-cli-render-"));const file = join(root, "main.svml");- await writeFile(file, `<svml>+ await writeFile(file, `<?svml using="@svml/text@1"?>+<svml><import as="render" from="@svml/hyperframes-render@1"/></svml>`, "utf8");let output = "";@@ -393,7 +424,8 @@ test("CLI package lock activates an installed package without changing the offic`, "utf8");const file = join(root, "main.svml");const lockPath = join(root, "svml.packages.lock");- await writeFile(file, `<svml>+ await writeFile(file, `<?svml using="@svml/text@1"?>+<svml><import as="example" from="example.empty@1"/><example:Empty/></svml>`, "utf8");diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex a3de8adb..e5cdb2a2 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -33,6 +33,9 @@ importers:'@svml/provider-whisperx-local':specifier: workspace:*version: link:packages/provider-whisperx-local+ '@svml/run-text':+ specifier: workspace:*+ version: link:packages/run-text'@types/node':specifier: 24.10.1version: 24.10.1@@ -177,6 +180,9 @@ importers:'@svml/runtime':specifier: workspace:*version: link:../runtime+ '@svml/source':+ specifier: workspace:*+ version: link:../sourcepackages/compiler-node:dependencies:@@ -195,6 +201,12 @@ importers:'@svml/realization':specifier: workspace:*version: link:../realization+ '@svml/run':+ specifier: workspace:*+ version: link:../run+ '@svml/source':+ specifier: workspace:*+ version: link:../source'@svml/validation':specifier: workspace:*version: link:../validation@@ -319,6 +331,9 @@ importers:'@svml/protocol':specifier: workspace:*version: link:../protocol+ '@svml/source':+ specifier: workspace:*+ version: link:../sourcedevDependencies:'@svml/contracts':specifier: workspace:*@@ -637,6 +652,9 @@ importers:'@svml/protocol':specifier: workspace:*version: link:../protocol+ '@svml/run':+ specifier: workspace:*+ version: link:../run'@svml/validation':specifier: workspace:*version: link:../validation@@ -898,22 +916,36 @@ importers:packages/run:dependencies:+ '@svml/core':+ specifier: workspace:*+ version: link:../core'@svml/elaborator':specifier: workspace:*version: link:../elaborator+ '@svml/host':+ specifier: workspace:*+ version: link:../host'@svml/protocol':specifier: workspace:*version: link:../protocol'@svml/realization':specifier: workspace:*version: link:../realization+ '@svml/source':+ specifier: workspace:*+ version: link:../source++ packages/run-text:+ dependencies:+ '@svml/protocol':+ specifier: workspace:*+ version: link:../protocol+ '@svml/run':+ specifier: workspace:*+ version: link:../run'@svml/text':specifier: workspace:*version: link:../text- devDependencies:- '@svml/core':- specifier: workspace:*- version: link:../corepackages/runtime:dependencies:@@ -972,6 +1004,8 @@ importers:specifier: workspace:*version: link:../protocol+ packages/source: {}+packages/speech-align:dependencies:'@svml/component-kit':@@ -1086,6 +1120,9 @@ importers:specifier: workspace:*version: link:../protocoldevDependencies:+ '@svml/source':+ specifier: workspace:*+ version: link:../source'@svml/text':specifier: workspace:*version: link:../text@@ -1208,6 +1245,9 @@ importers:'@svml/provider-whisperx-local':specifier: workspace:*version: link:../provider-whisperx-local+ '@svml/run-text':+ specifier: workspace:*+ version: link:../run-text'@svml/runtime':specifier: workspace:*version: link:../runtimediff --git a/tools/package-boundaries.test.mjs b/tools/package-boundaries.test.mjsindex 666f1f5c..a097448a 100644--- a/tools/package-boundaries.test.mjs+++ b/tools/package-boundaries.test.mjs@@ -51,8 +51,10 @@ const domainNeutralPackages = new Set(["@svml/protocol","@svml/artifact","@svml/core",+ "@svml/source","@svml/elaborator","@svml/realization",+ "@svml/run","@svml/validation","@svml/host","@svml/compiler-node",diff --git a/tsconfig.v2.json b/tsconfig.v2.jsonindex dfe262d8..b5f5ef1d 100644--- a/tsconfig.v2.json+++ b/tsconfig.v2.json@@ -21,6 +21,7 @@"@svml/elaborator": ["packages/elaborator/src/index.ts"],"@svml/realization": ["packages/realization/src/index.ts"],"@svml/run": ["packages/run/src/index.ts"],+ "@svml/run-text": ["packages/run-text/src/index.ts"],"@svml/runtime": ["packages/runtime/src/index.ts"],"@svml/store-sqlite": ["packages/store-sqlite/src/index.ts"],"@svml/artifact-store-fs": ["packages/artifact-store-fs/src/index.ts"],@@ -59,6 +60,7 @@"@svml/cli": ["packages/cli/src/index.ts"],"@svml/validation": ["packages/validation/src/index.ts"],"@svml/host": ["packages/host/src/index.ts"],+ "@svml/source": ["packages/source/src/index.ts"],"@svml/workspace-fs-node": ["packages/workspace-fs-node/src/index.ts"]}},