Skip to content

armgit / hypit

Public Imported from GitHub
0

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

feat(v2): make sources self-described and require run graphs

kashorin6b4137deca40
diff --git a/README.md b/README.md
index 8373a5af..07a95ced 100644
--- a/README.md
+++ b/README.md
@@ -61,7 +61,8 @@ See [the architecture](docs/architecture.md) and
The 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 p
packages/protocol immutable wire contracts
packages/artifact domain-neutral content-addressed byte Type
packages/core domain-neutral Demand compiler and Build state machine
+packages/source mandatory Source Header; no syntax default
packages/elaborator author declarations and hygienic Fragment expansion
packages/compiler-node reference Node compiler Host
packages/compiler-text-node optional official Text compiler assembly
packages/package-loader-node syntax-neutral trusted physical-package loading
packages/cli generic commands requiring an explicit Distribution
packages/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 Frontend
packages/runtime environment-neutral scheduling and Store ports
packages/driver-node trusted Node command execution
packages/local zero-service SQLite/filesystem developer assembly
diff --git a/docs/README.md b/docs/README.md
index 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 implementati
Runtime, 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 specifications
diff --git a/examples/talking-film-golden/README.md b/examples/talking-film-golden/README.md
index 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, bla
preview realizations remain explicitly selected Candidates in a BuildRequest; they do not alter
the author source or teach Runtime to guess a creative method.
-The intended final command is:
+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 a
diff --git a/examples/talking-film-golden/build.svrun b/examples/talking-film-golden/build.svrun
new file mode 100644
index 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.svml
index 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-shot
diff --git a/examples/talking-film-golden/studio.svs b/examples/talking-film-golden/studio.svs
index 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.md
index d00f0df5..a0538bc5 100644
--- a/examples/talking-film-graph-check/README.md
+++ b/examples/talking-film-graph-check/README.md
@@ -7,7 +7,8 @@ HyperFrames.
```bash
pnpm 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 generic
diff --git a/examples/talking-film-graph-check/build.svrun b/examples/talking-film-graph-check/build.svrun
new file mode 100644
index 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.svml
index 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.svs
index 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.md
index 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-input
Candidates 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.svrun
index 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.svml
index 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.svs
index 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.svml
index 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.svs
index 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.json
index 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.md
index 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 caller
must pass one explicit `CliDistribution`:
```ts
type 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 a
official `@svml/video-cli` selects `@svml/compiler-text-node`, `@svml/prelude-video` and the current
video Runtime adapters. Another domain can reuse this command engine without installing those
packages.
+
+`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.json
index 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.ts
index 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.ts
index 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.ts
index 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.md
index 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 `Workspa
implemented 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 closes
their digest-bound dependencies. It does not install npm packages or execute module code. An
embedding application must register the manifests and matching Frontend/Surface implementations it
@@ -35,10 +38,16 @@ SourceUnit recursion and Source Asset resolution are intentionally different cap
asset cannot import syntax, and a source import does not silently make arbitrary neighboring bytes
available 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. A
non-video application can use it with only its own manifests, Frontends, Surfaces and chosen
diff --git a/packages/compiler-node/package.json b/packages/compiler-node/package.json
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 works
return 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", asy
assert.equal(compiled.exports[0]?.name, "hello.result");
assert.equal(compiled.elaboration.graph.outputs.length, 1);
- const planned = await compiler(root).planFile(file, { targets: ["hello.result"] });
+});
+
+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 onl
assert.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 onl
async () => 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 onl
test("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.md
index 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 fro
package contributions, and combines them with the syntax-neutral `@svml/compiler-node`. It does not
discover 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 compute
facets and no author syntax.
diff --git a/packages/compiler-text-node/src/index.ts b/packages/compiler-text-node/src/index.ts
index 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.ts
index 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 packag
const 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.json
index 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.ts
index 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.ts
index 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, "id
alias: 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, "id
function 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.ts
index 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 style
entry: source("/project/main.svml", `<svml>
<import as="fixture" from="example.film-fixture@1"/>
<import as="film" from="@svml/film@1"/>
- <import as="studio" from="./studio.svs" using="${svsFrontendId}"/>
+ <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.ts
index 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.md
index 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 Type
Validator identities. Loading verifies all artifacts and checks deterministic compute facets
against their static Manifests before returning verified `NodePackageContribution` values.
This package does not select an author syntax. Syntax-specific executable facets remain inert until
an 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 Runtime
services. Source `<import>` can select only an already installed author contribution; trusted
diff --git a/packages/package-loader-node/package.json b/packages/package-loader-node/package.json
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.md
index 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 typed
Candidates plus any already elaborated Operations. It does not attach those Candidates to, or
rewrite, 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 an
explicit 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.ts
index 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.ts
index 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.md
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
similarity index 89%
rename from packages/run/src/syntax.ts
rename to packages/run-text/src/syntax.ts
index 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.md
index 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.json
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 St
export 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.ts
index 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.ts
index 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 Satisfact
test("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.md
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.md
index 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 does
diff --git a/packages/svs/package.json b/packages/svs/package.json
index 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.ts
index 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.ts
index 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 identit
assert.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 deco
resolveModule: () => laboratory,
}));
const duplicate = unit("/project/duplicate.svml", `<svml>
- <import as="styles" from="./one.svs" using="${svsFrontendId}"/>
- <import as="styles" from="./two.svs" using="${svsFrontendId}"/>
+ <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 deco
test("the golden studio.svs parses as generic Recipes without video knowledge", () => {
const source = readFileSync(new URL("../../../examples/talking-film-golden/studio.svs", import.meta.url), "utf8");
- const parsed = parseSvs("studio.svs", source);
+ 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.md
index 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 to
statically declared module Surfaces.
@@ -10,8 +11,10 @@ implementation. The current registry is for trusted official/in-process use; it
sandbox 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 resolved
namespace. The reference `compileSourceClosure()` orchestration in `@svml/elaborator` recursively
-discovers those SourceUnits, selects the exact `using` Frontend, decodes dependencies first and then
-calls Text with their locked public exports. Text itself never reads a file or guesses a Frontend.
+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.ts
index 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): Te
discover(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.ts
index 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): TextImportReque
if (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.ts
index 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.md
index 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. It
depends 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.svml
pnpm 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.result
pnpm svml:v2 check path/to/build.svrun
pnpm svml:v2 plan path/to/build.svrun
pnpm 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 --follow
pnpm svml:v2 status <build-id> --runtime ./svml.runtime.json
pnpm svml:v2 builds --runtime ./svml.runtime.json
pnpm 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 --t
pnpm 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 retent
and 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. It
verifies 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.json
index 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.ts
index 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.ts
index 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 genera
const 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 mod
test("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 witho
test("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 explici
assert.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 explici
test("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 executi
text.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 executi
test("official v2 CLI closes the explicit HyperFrames render package without loading a Provider", async () => {
const root = await mkdtemp(join(tmpdir(), "svml-cli-render-"));
const file = join(root, "main.svml");
- await writeFile(file, `<svml>
+ 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.yaml
index 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.1
version: 24.10.1
@@ -177,6 +180,9 @@ importers:
'@svml/runtime':
specifier: workspace:*
version: link:../runtime
+ '@svml/source':
+ specifier: workspace:*
+ version: link:../source
packages/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:../source
devDependencies:
'@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:../core
packages/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:../protocol
devDependencies:
+ '@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:../runtime
diff --git a/tools/package-boundaries.test.mjs b/tools/package-boundaries.test.mjs
index 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.json
index 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"]
}
},