Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
feat(v2): add host build catalog
kashorincceef745cc7a
diff --git a/README.md b/README.mdindex bf1c60a8..54f6d16d 100644--- a/README.md+++ b/README.md@@ -113,12 +113,14 @@ pnpm svml:v2 build examples/talking-film-live/build.svrun \--followpnpm svml:v2 get talking-film-live \+ --name final.video \--runtime examples/talking-film-live/svml.runtime.json \--to examples/talking-film-live/output/final.mp4```The Build archives every accepted intermediate Record and Artifact before `get` makes an optional-human-readable copy of the sole target.+human-readable copy. `builds`, `inspect` and `get --name` use a Host-only catalog of source aliases;+the selected Record is still verified against the authoritative BuildState.Read its [deployment requirements](examples/talking-film-live/README.md) before running it. Paidcredentials, presenter assets, local databases and generated outputs are not committed.diff --git a/packages/cli/README.md b/packages/cli/README.mdindex 5466096e..24d4f22e 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -27,8 +27,9 @@ pnpm svml:v2 plan path/to/build.svrunpnpm svml:v2 build path/to/build.svrun --runtime ./svml.runtime.json --build-id delivery-01 --followpnpm svml:v2 build path/to/main.svml --target final.video --runtime ./svml.runtime.ts --pin shot=<prior-build-id> --accept-substitute --build-id variant-01 --followpnpm svml:v2 status <build-id> --runtime ./svml.runtime.json+pnpm svml:v2 builds --runtime ./svml.runtime.jsonpnpm svml:v2 inspect <build-id> --runtime ./svml.runtime.json-pnpm svml:v2 get <build-id> --runtime ./svml.runtime.json --to ./final.mp4+pnpm svml:v2 get <build-id> --name final.video --runtime ./svml.runtime.json --to ./final.mp4pnpm svml:v2 cancel <build-id> --runtime ./svml.runtime.json```@@ -52,10 +53,14 @@ these commands creates a second ready-command queue.`build` archives every accepted Record in the demanded closure and every referenced byte Artifact,whether or not the user wants a conventional filesystem copy. `inspect` lists Targets, demandedLogical Outputs, accepted Records and their Artifact references. `get` reads one accepted Record;-without a selector it requires one distinct target, while `--record` and `--output` select any-accepted Record or demanded Logical Output. `--artifact` selects any nested BlobRef that the Build-actually references. `--to` copies an Artifact or writes an inline structured value as JSON. It is-Host egress only and never changes Build identity or retention.+without a selector it requires one distinct target, while `--name`, `--record` and `--output` select+a source output alias, accepted Record or demanded Logical Output. `--artifact` selects any nested+BlobRef that the Build actually references. `--to` copies an Artifact or writes an inline structured+value as JSON. It is Host egress only and never changes Build identity or retention.++`builds` and source aliases come from an optional Host `BuildCatalog`. The Catalog contains paths+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 Hostverifies the prior Build only to extract a typed Record, attaches it as an ordinary zero-inputdiff --git a/packages/cli/src/archive.ts b/packages/cli/src/archive.tsindex 40c24084..ef1b64e9 100644--- a/packages/cli/src/archive.ts+++ b/packages/cli/src/archive.ts@@ -4,6 +4,7 @@ import { dirname } from "node:path";import type { LocalRuntime } from "@svml/local";import { isDigest } from "@svml/protocol";import type { BuildState, Digest, TypedRecord } from "@svml/protocol";+import type { BuildCatalogEntry } from "@svml/runtime";type ArtifactIdentity = {readonly digest: Digest;@@ -108,21 +109,36 @@ function summarizeRecord(record: TypedRecord) {export function selectArchivedRecord(state: BuildState,- options: { readonly record?: string; readonly output?: string },+ options: {+ readonly record?: string;+ readonly output?: string;+ readonly name?: string;+ readonly catalog?: BuildCatalogEntry;+ },): TypedRecord {- if (options.record !== undefined && options.output !== undefined) {- throw new Error("get accepts either --record or --output, not both");+ const selectors = [options.record, options.output, options.name].filter((item) => item !== undefined);+ if (selectors.length > 1) {+ throw new Error("get accepts one of --name, --record or --output");}let id = options.record;- if (options.output !== undefined) {- const selection = state.plan.selections.find((item) => item.output === options.output);- if (selection === undefined) throw new Error(`Build has no demanded Logical Output ${options.output}`);+ let output = options.output;+ if (options.name !== undefined) {+ if (options.catalog === undefined) throw new Error("Build has no Host Catalog aliases");+ if (options.catalog.core !== state.id) throw new Error("Build Catalog entry names another Core Build");+ const alias = options.catalog.aliases.find((item) => item.name === options.name);+ if (alias === undefined) throw new Error(`Build Catalog has no output named ${options.name}`);+ if (alias.ref.kind === "record") id = alias.ref.id;+ else output = alias.ref.id;+ }+ if (output !== undefined) {+ const selection = state.plan.selections.find((item) => item.output === output);+ if (selection === undefined) throw new Error(`Build has no demanded Logical Output ${output}`);id = selection.record;}if (id === undefined) {const goals = [...new Set(state.plan.goals.map((goal) => goal.record))];if (goals.length !== 1) {- throw new Error("get without --record or --output requires exactly one distinct target Record");+ throw new Error("get without a selector requires exactly one distinct target Record");}[id] = goals;}@@ -131,7 +147,10 @@ export function selectArchivedRecord(return record;}-export function inspectBuild(state: BuildState) {+export function inspectBuild(state: BuildState, catalog?: BuildCatalogEntry) {+ if (catalog !== undefined && catalog.core !== state.id) {+ throw new Error("Build Catalog entry names another Core Build");+ }const records = new Map(state.records.map((record) => [record.id, record]));const selections = new Map(state.plan.selections.map((selection) => [selection.output, selection]));return {@@ -164,5 +183,25 @@ export function inspectBuild(state: BuildState) {receipts: state.receipts.length,derivations: state.derivations.length,diagnostics: state.diagnostics,+ ...(catalog === undefined ? {} : {+ presentation: {+ source: catalog.source,+ ...(catalog.run === undefined ? {} : { run: catalog.run }),+ aliases: catalog.aliases.map((alias) => {+ const record = alias.ref.kind === "record"+ ? records.get(alias.ref.id)+ : (() => {+ const selection = selections.get(alias.ref.id);+ return selection === undefined ? undefined : records.get(selection.record);+ })();+ return {+ name: alias.name,+ type: alias.type,+ ref: alias.ref,+ ...(record === undefined ? { accepted: false } : { accepted: true, record: record.id }),+ };+ }),+ },+ }),};}diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.tsindex 584fecde..28ef4c94 100644--- a/packages/cli/src/main.ts+++ b/packages/cli/src/main.ts@@ -2,6 +2,8 @@ import { dirname, extname, resolve } from "node:path";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,@@ -42,13 +44,16 @@ type ParsedArgs = {readonly packages: readonly string[];readonly record: string | undefined;readonly output: string | undefined;+ readonly name: string | undefined;readonly artifact: string | undefined;readonly to: string | undefined;readonly pins: readonly { readonly output: string; readonly build: string }[];};function parseArgs(argv: readonly string[]): ParsedArgs {- const [command, file, ...rest] = argv;+ const [command, ...tail] = argv;+ const file = command === "builds" ? undefined : tail[0];+ const rest = command === "builds" ? tail : tail.slice(1);const targets: string[] = [];let root: string | undefined;let runtime: string | undefined;@@ -60,6 +65,7 @@ function parseArgs(argv: readonly string[]): ParsedArgs {let substitute = false;let record: string | undefined;let output: string | undefined;+ let name: string | undefined;let artifact: string | undefined;let to: string | undefined;const pins: { output: string; build: string }[] = [];@@ -121,6 +127,13 @@ function parseArgs(argv: readonly string[]): ParsedArgs {index += 1;continue;}+ if (item === "--name") {+ const value = rest[index + 1];+ if (value === undefined || value.startsWith("--")) throw new Error("--name requires a source output name");+ name = value;+ index += 1;+ continue;+ }if (item === "--artifact") {const value = rest[index + 1];if (value === undefined || value.startsWith("--")) throw new Error("--artifact requires a content digest");@@ -181,6 +194,7 @@ function parseArgs(argv: readonly string[]): ParsedArgs {packages,record,output,+ name,artifact,to,pins,@@ -197,8 +211,9 @@ function usage(): string {" 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 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",- " svml-v2 get <build-id> --runtime profile.json|./svml.runtime.ts [--record record-id|--output logical-output-id|--artifact digest] [--to path]",+ " svml-v2 get <build-id> --runtime profile.json|./svml.runtime.ts [--name source-name|--record record-id|--output logical-output-id|--artifact digest] [--to path]"," svml-v2 cancel <build-id> --runtime profile.json|./svml.runtime.ts",].join("\n");}@@ -208,12 +223,41 @@ function isLocalRuntime(value: unknown): value is LocalRuntime {&& value !== null&& "build" in value&& typeof value.build === "function"+ && "builds" in value+ && typeof value.builds === "function"&& "readArtifact" in value&& typeof value.readArtifact === "function"&& "close" in value&& typeof value.close === "function";}+function createCatalogDescriptor(options: {+ readonly core: BuildCatalogDescriptor["core"];+ readonly source: string;+ readonly compilation: NodeCompiledSourceClosure;+ readonly run?: { readonly path: string; readonly targetSet?: string };+}): BuildCatalogDescriptor {+ const aliases = options.compilation.exports.map((item) => {+ if (item.ref.kind === "operation-result") {+ throw new Error(`public output ${item.name} was not lowered to a stable Record or Logical Output`);+ }+ return { name: item.name, type: item.type, ref: item.ref };+ });+ return {+ format: "svml.build-catalog-descriptor@1",+ core: options.core,+ source: {+ path: resolve(options.source),+ closure: options.compilation.closure.id,+ },+ ...(options.run === undefined ? {} : { run: {+ path: resolve(options.run.path),+ ...(options.run.targetSet === undefined ? {} : { targetSet: options.run.targetSet }),+ } }),+ aliases,+ };+}+async function loadLocalRuntime(path: string): Promise<LocalRuntime> {if (extname(path) === ".json") return await createOfficialRuntimeFromConfig(path);// A Runtime config is trusted executable deployment code, never an Author Frontend or .svml import.@@ -232,35 +276,54 @@ async function loadLocalRuntime(path: string): Promise<LocalRuntime> {export async function runCli(argv: readonly string[], io: CliIo): Promise<void> {const args = parseArgs(argv);- if (args.file === undefined- || (args.command !== "lock-packages" && args.command !== "check" && args.command !== "plan" && args.command !== "build"- && args.command !== "status" && args.command !== "inspect" && args.command !== "get" && args.command !== "cancel")) {+ const known = args.command === "lock-packages" || args.command === "check" || args.command === "plan"+ || args.command === "build" || args.command === "status" || args.command === "builds"+ || args.command === "inspect" || args.command === "get" || args.command === "cancel";+ if (!known || (args.command !== "builds" && args.file === undefined)) {throw new Error(usage());}if (args.command === "lock-packages") {if (args.packages.length === 0) throw new Error("lock-packages requires at least one --package");if (args.packageLock !== undefined) throw new Error("lock-packages does not accept --package-lock");- const output = resolve(args.file);+ const output = resolve(args.file!);const root = args.root ?? dirname(output);const lock = await createNodePackageLock(args.packages, root);await writeNodePackageLock(output, lock);io.write(`${JSON.stringify({ ok: true, packageLock: output, digest: lock.digest, packages: lock.packages }, null, 2)}\n`);return;}- if ((args.record !== undefined || args.output !== undefined || args.artifact !== undefined || args.to !== undefined)+ if ((args.record !== undefined || args.output !== undefined || args.name !== undefined+ || args.artifact !== undefined || args.to !== undefined)&& args.command !== "get") {- throw new Error("--record, --output, --artifact and --to are only valid for 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.command === "status" || args.command === "inspect" || args.command === "get" || args.command === "cancel") {+ if (args.command === "status" || args.command === "builds" || args.command === "inspect"+ || args.command === "get" || args.command === "cancel") {if (args.runtime === undefined) throw new Error(`${args.command} requires --runtime`);const runtime = await loadLocalRuntime(args.runtime);try {- if (args.command === "status") {- const status = await runtime.status(args.file);+ if (args.command === "builds") {+ const entries = await runtime.builds();+ const builds = await Promise.all(entries.map(async (entry) => {+ const status = await runtime.status(entry.build);+ return {+ build: entry.build,+ core: entry.core,+ createdAt: entry.createdAt,+ updatedAt: entry.updatedAt,+ status: status.build?.state.status,+ source: entry.source,+ ...(entry.run === undefined ? {} : { run: entry.run }),+ outputs: entry.aliases.map((alias) => alias.name),+ };+ }));+ io.write(`${JSON.stringify({ builds }, null, 2)}\n`);+ } else if (args.command === "status") {+ const status = await runtime.status(args.file!);io.write(`${JSON.stringify({build: status.build === undefined ? undefined : {id: status.build.build,@@ -269,6 +332,7 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>status: status.build.state.status,diagnostics: status.build.state.diagnostics,},+ catalog: status.catalog,operations: status.operations.map((operation) => ({id: operation.id,command: operation.command,@@ -280,12 +344,12 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>})),}, null, 2)}\n`);} else if (args.command === "inspect") {- const status = await runtime.status(args.file);+ const status = await runtime.status(args.file!);if (status.build === undefined) throw new Error(`Build ${args.file} does not exist`);io.write(`${JSON.stringify({build: status.build.build,revision: status.build.revision,- archive: inspectBuild(status.build.state),+ archive: inspectBuild(status.build.state, status.catalog),operations: status.operations.map((operation) => ({id: operation.id,command: operation.command,@@ -297,10 +361,10 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>})),}, null, 2)}\n`);} else if (args.command === "get") {- const status = await runtime.status(args.file);+ const status = await runtime.status(args.file!);if (status.build === undefined) throw new Error(`Build ${args.file} does not exist`);- if (args.artifact !== undefined && (args.record !== undefined || args.output !== undefined)) {- throw new Error("get accepts one of --record, --output or --artifact");+ if (args.artifact !== undefined && (args.name !== undefined || args.record !== undefined || args.output !== undefined)) {+ throw new Error("get accepts one of --name, --record, --output or --artifact");}if (args.artifact !== undefined) {const references = findArchivedArtifact(status.build.state, args.artifact);@@ -321,8 +385,10 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>return;}const record = selectArchivedRecord(status.build.state, {+ ...(args.name === undefined ? {} : { name: args.name }),...(args.record === undefined ? {} : { record: args.record }),...(args.output === undefined ? {} : { output: args.output }),+ ...(status.catalog === undefined ? {} : { catalog: status.catalog }),});if (args.to === undefined) {io.write(`${JSON.stringify({@@ -340,7 +406,7 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>}, null, 2)}\n`);}} else {- const result = await runtime.cancel(args.file);+ const result = await runtime.cancel(args.file!);io.write(`${JSON.stringify({build: args.file,cancelled: result !== undefined,@@ -354,7 +420,7 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>return;}if (args.packages.length > 0) throw new Error("--package is only valid for lock-packages");- const runMode = extname(args.file) === ".svrun";+ 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");}@@ -372,7 +438,7 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>runtime = args.runtime === undefined ? undefined : await loadLocalRuntime(args.runtime);if (runMode) {const loaded = await loadRunFile({- path: args.file,+ path: args.file!,compiler,packages,...(runtime === undefined ? {} : { runtime }),@@ -397,7 +463,7 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>}, null, 2)}\n`);return;}- const result = await compiler.compileFile(args.file);+ const result = await compiler.compileFile(args.file!);io.write(`${JSON.stringify({ok: true,sourceClosure: result.closure.id,@@ -424,7 +490,7 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>};let pinSummary: readonly { readonly output: string; readonly build: string; readonly candidate: string }[] = [];const loadedRun = runMode- ? await loadRunFile({ path: args.file, compiler, packages, runtime })+ ? await loadRunFile({ path: args.file!, compiler, packages, runtime }): undefined;const result = loadedRun !== undefined? compiler.planCompilation(loadedRun.compilation, {@@ -434,7 +500,7 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>...(activated === undefined ? {} : { implementationClosure: activated.lock.digest }),}): args.pins.length === 0- ? await compiler.planFile(args.file, planOptions)+ ? await compiler.planFile(args.file!, planOptions): await (async () => {const compilation = await compiler.compileFile(args.file!);const seen = new Set<string>();@@ -474,6 +540,15 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>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: {+ path: loadedRun.path,+ targetSet: loadedRun.document.selectedTargets,+ } }),+ }),attachments: result.compilation.attachments,}, {follow: args.follow,@@ -519,7 +594,7 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>...(activated === undefined ? {} : { implementationClosure: activated.lock.digest }),});})()- : await compiler.planFile(args.file, {+ : await compiler.planFile(args.file!, {targets: args.targets,accepts: args.substitute ? "substitute" : "exact",...(activated === undefined ? {} : { implementationClosure: activated.lock.digest }),diff --git a/packages/cli/test/cli.test.ts b/packages/cli/test/cli.test.tsindex 68a42f93..7217026a 100644--- a/packages/cli/test/cli.test.ts+++ b/packages/cli/test/cli.test.ts@@ -500,11 +500,31 @@ test("CLI inspect and get read the durable Build archive independently of buildderivations: [],diagnostics: [],};+ const catalog = {+ format: "svml.build-catalog-descriptor@1",+ build: "archive-1",+ core: buildDigest,+ source: { path: join(root, "main.svml"), closure: `sha256:${"6".repeat(64)}` },+ run: { path: join(root, "delivery.svrun"), targetSet: "delivery" },+ aliases: [{+ name: "final.video",+ type: state.records[0]!.type,+ ref: { kind: "logical-output", id: "logical:final" },+ }, {+ name: "timing.rawEvidence",+ type: state.records[1]!.type,+ ref: { kind: "record", id: "record:whisperx" },+ }],+ createdAt: 100,+ updatedAt: 100,+ };await writeFile(runtimePath, `const bytes = Buffer.from(${JSON.stringify(bytes.toString("base64"))}, "base64");const rawBytes = Buffer.from(${JSON.stringify(rawBytes.toString("base64"))}, "base64");+const catalog = ${JSON.stringify(catalog)};export default {async build() { throw new Error("not used"); },- async status(id) { return { build: id === "archive-1" ? { build: id, revision: 7, state: ${JSON.stringify(state)} } : undefined, operations: [] }; },+ async builds() { return [catalog]; },+ async status(id) { return { build: id === "archive-1" ? { build: id, revision: 7, state: ${JSON.stringify(state)} } : undefined, catalog: id === "archive-1" ? catalog : undefined, operations: [] }; },async readArtifact(digest) {if (digest === ${JSON.stringify(artifactDigest)}) return bytes;if (digest === ${JSON.stringify(rawDigest)}) return rawBytes;@@ -522,16 +542,35 @@ export default {readonly status: string;readonly targets: readonly { readonly accepted: boolean }[];readonly records: readonly { readonly artifacts: readonly { readonly digest: string }[] }[];+ readonly presentation: { readonly aliases: readonly { readonly name: string; readonly accepted: boolean }[] };};};assert.equal(inspected.archive.status, "active");assert.equal(inspected.archive.targets[0]?.accepted, true);assert.equal(inspected.archive.records[0]?.artifacts[0]?.digest, artifactDigest);+ assert.deepEqual(inspected.archive.presentation.aliases.map((item) => [item.name, item.accepted]), [+ ["final.video", true],+ ["timing.rawEvidence", true],+ ]);++ let buildsOutput = "";+ await runCli(["builds", "--runtime", runtimePath], { write: (text) => { buildsOutput += text; } });+ const listed = JSON.parse(buildsOutput) as { readonly builds: readonly { readonly build: string; readonly outputs: readonly string[] }[] };+ assert.deepEqual(listed.builds, [{+ build: "archive-1",+ core: buildDigest,+ createdAt: 100,+ updatedAt: 100,+ status: "active",+ source: catalog.source,+ run: catalog.run,+ outputs: ["final.video", "timing.rawEvidence"],+ }]);let getOutput = "";await runCli(["get", "archive-1", "--runtime", runtimePath,- "--output", "logical:final", "--to", destination,+ "--name", "final.video", "--to", destination,], { write: (text) => { getOutput += text; } });assert.deepEqual(await readFile(destination), bytes);const got = JSON.parse(getOutput) as { readonly materialized: { readonly kind: string; readonly digest: string } };diff --git a/packages/local/README.md b/packages/local/README.mdindex 99826fc0..32f3b0f6 100644--- a/packages/local/README.md+++ b/packages/local/README.md@@ -78,6 +78,12 @@ change to `@svml/local`. Advanced hosts may still call `createLocalRuntime` withRecord and content identities, not private filesystem layout, so filesystem and S3 stores remaininterchangeable. Egress never determines whether a Build result is retained.+`LocalRuntime.builds()` reads a separate Host `BuildCatalog`. With the default local assembly the+catalog shares the SQLite file physically; deployments with replacement execution Stores default+to `.svml/catalog.sqlite` or may select `catalogPath`/inject a `BuildCatalog`. This index is kept out+of Runtime service selection and Closure identity because changing a source path or display alias+must not invalidate or resume a different execution.+`LocalBuildRequest.attachments` is the explicit ingress from a trusted Host into the selectedArtifactStore. Each attachment carries claimed `BlobRef` metadata plus bytes; Local Runtime copiesthe bytes, stores them content-addressably and requires the Store's returned digest, size and mediadiff --git a/packages/local/src/config.ts b/packages/local/src/config.tsindex c7ff21f5..6a83cd97 100644--- a/packages/local/src/config.ts+++ b/packages/local/src/config.ts@@ -22,6 +22,7 @@ export type RuntimeConfigDocument = {/** Resolved relative to the configuration file. Defaults to its directory. */readonly root?: string;readonly statePath?: string;+ readonly catalogPath?: string;readonly artifactPath?: string;readonly packageLock?: string;readonly services: readonly RuntimeConfigEntry[];@@ -172,7 +173,7 @@ function scheduling(value: unknown): RuntimeConfigDocument["scheduling"] {export function parseRuntimeConfig(value: unknown): RuntimeConfigDocument {const item = object(value, "$runtime");exactKeys(item, [- "format", "root", "statePath", "artifactPath", "packageLock", "services", "endpoints",+ "format", "root", "statePath", "catalogPath", "artifactPath", "packageLock", "services", "endpoints","selection", "permissions", "scheduling",], "$runtime");if (item.format !== "svml.runtime-config@1") throw new Error("$runtime.format must be svml.runtime-config@1");@@ -192,6 +193,7 @@ export function parseRuntimeConfig(value: unknown): RuntimeConfigDocument {format: "svml.runtime-config@1",...(optionalString(item.root, "$runtime.root") === undefined ? {} : { root: item.root as string }),...(optionalString(item.statePath, "$runtime.statePath") === undefined ? {} : { statePath: item.statePath as string }),+ ...(optionalString(item.catalogPath, "$runtime.catalogPath") === undefined ? {} : { catalogPath: item.catalogPath as string }),...(optionalString(item.artifactPath, "$runtime.artifactPath") === undefined ? {} : { artifactPath: item.artifactPath as string }),...(optionalString(item.packageLock, "$runtime.packageLock") === undefined ? {} : { packageLock: item.packageLock as string }),services,@@ -236,6 +238,7 @@ export async function createRuntimeFromConfig(return await createProjectLocalRuntime({root,...(document.statePath === undefined ? {} : { statePath: document.statePath }),+ ...(document.catalogPath === undefined ? {} : { catalogPath: document.catalogPath }),...(document.artifactPath === undefined ? {} : { artifactPath: document.artifactPath }),...(document.packageLock === undefined ? {} : { packageLock: document.packageLock }),runtimeServices: services,diff --git a/packages/local/src/project-services.ts b/packages/local/src/project-services.tsindex 67d8e8d6..c9e81bf1 100644--- a/packages/local/src/project-services.ts+++ b/packages/local/src/project-services.ts@@ -8,6 +8,7 @@ import {} from "@svml/runtime";import type {ArtifactStore,+ BuildCatalog,BuildStore,CredentialStore,OperationStore,@@ -15,7 +16,7 @@ import type {RuntimeServiceFacetRole,RuntimeServicePackage,} from "@svml/runtime";-import { createSqliteRuntimeServicePackage } from "@svml/store-sqlite";+import { createSqliteRuntimeServicePackage, SqliteRuntimeState } from "@svml/store-sqlite";import { createLocalSchedulerPackage } from "./scheduler-package.js";import type { ProjectLocalRuntimeOptions } from "./types.js";@@ -39,8 +40,10 @@ export type ProjectRuntimeServiceAssembly = RuntimeServiceAssembly & {export type AssembledProjectRuntimeServices = {readonly assembly: ProjectRuntimeServiceAssembly;+ readonly catalog: BuildCatalog;readonly selection: ProjectRuntimeServiceSelection;readonly allowedPermissions: readonly string[];+ close(): Promise<void>;};function assert(condition: unknown, message: string): asserts condition {@@ -156,6 +159,8 @@ export async function createProjectRuntimeServices(}const defaults: RuntimeServicePackage[] = [];+ let defaultCatalog: BuildCatalog | undefined;+ let standaloneCatalog: SqliteRuntimeState | undefined;try {if (!hasConfiguredService(configured, selection.scheduler)) {assert(selection.scheduler === "scheduler.local", `unknown selected scheduler ${selection.scheduler}`);@@ -167,11 +172,13 @@ export async function createProjectRuntimeServices(assert((!needsDefaultBuild || selection.stores.build === "builds.sqlite")&& (!needsDefaultOperations || selection.stores.operations === "operations.sqlite"),"unknown selected BuildStore or OperationStore");- defaults.push(createSqliteRuntimeServicePackage({+ const sqlite = createSqliteRuntimeServicePackage({path: resolve(root, options.statePath ?? ".svml/runtime.sqlite"),buildInstance: "builds.sqlite",operationInstance: "operations.sqlite",- }));+ });+ defaults.push(sqlite);+ defaultCatalog = sqlite.catalog;} else if (options.statePath !== undefined) {throw new Error("statePath configures the default SQLite services, but neither was selected");}@@ -190,6 +197,19 @@ export async function createProjectRuntimeServices(`unknown selected CredentialStore ${selection.stores.credentials}`);defaults.push(createEnvironmentCredentialStorePackage({ instance: selection.stores.credentials }));}+ if (options.buildCatalog !== undefined && options.catalogPath !== undefined) {+ throw new Error("buildCatalog and catalogPath are mutually exclusive");+ }+ let catalog = options.buildCatalog;+ if (catalog === undefined && options.catalogPath !== undefined) {+ standaloneCatalog = new SqliteRuntimeState(resolve(root, options.catalogPath));+ catalog = standaloneCatalog.catalog;+ }+ if (catalog === undefined) catalog = defaultCatalog;+ if (catalog === undefined) {+ standaloneCatalog = new SqliteRuntimeState(resolve(root, ".svml/catalog.sqlite"));+ catalog = standaloneCatalog.catalog;+ }const assembly = assembleRuntimeServices([...configured, ...defaults], selection);assert(assembly.buildStore !== undefined, "project Runtime requires a BuildStore");assert(assembly.operationStore !== undefined, "project Runtime requires an OperationStore");@@ -204,13 +224,22 @@ export async function createProjectRuntimeServices(};return {assembly: complete,+ catalog,selection,allowedPermissions: [...manifestPermissions(defaults),...(options.allowedPermissions ?? []),],+ async close() {+ try {+ await complete.close();+ } finally {+ standaloneCatalog?.close();+ }+ },};} catch (error) {+ standaloneCatalog?.close();return await closeAfterFailure([...configured, ...defaults], error);}}diff --git a/packages/local/src/runtime.ts b/packages/local/src/runtime.tsindex 54ecaafb..c23b4a44 100644--- a/packages/local/src/runtime.ts+++ b/packages/local/src/runtime.ts@@ -15,6 +15,7 @@ import {} from "@svml/package-loader-node";import {LocalBuildScheduler,+ MemoryBuildCatalog,RuntimeModuleRegistry,localSchedulerOptionsFromClosure,resolveRuntimeProfile,@@ -117,6 +118,7 @@ function verifyEndpointPackages(packages: readonly EndpointPackage[]): void {export async function createLocalRuntime(options: CreateLocalRuntimeOptions,): Promise<LocalRuntime> {+ const buildCatalog = options.buildCatalog ?? new MemoryBuildCatalog();if (options.closure !== undefined&& (options.scheduling?.maxConcurrency !== undefined|| options.scheduling?.laneLimits !== undefined)) {@@ -181,14 +183,19 @@ export async function createLocalRuntime(follow: LocalBuildOptions = {},) => {await stageAttachments(request);+ if (request.catalog !== undefined) {+ assert(request.catalog.core === request.state.id,+ `Build Catalog Core ${request.catalog.core} differs from Build ${request.state.id}`);+ }const startedAt = Date.now();const pollIntervalMs = nonNegativeInteger(follow.pollIntervalMs ?? 1_000, "pollIntervalMs");const maxWaitMs = follow.maxWaitMs === undefined? undefined: nonNegativeInteger(follow.maxWaitMs, "maxWaitMs");+ let [result] = await scheduler.run([scheduled(request)]);+ if (result === undefined) throw new Error(`Local Scheduler returned no result for ${request.id}`);+ if (request.catalog !== undefined) await buildCatalog.record(request.id, request.catalog);while (true) {- const [result] = await scheduler.run([scheduled(request)]);- if (result === undefined) throw new Error(`Local Scheduler returned no result for ${request.id}`);if (follow.follow !== true || result.status !== "paused") return result;const pending = result.journal.filter((item) => item.status === "pending");if (pending.length === 0) return result;@@ -197,20 +204,35 @@ export async function createLocalRuntime(const delay = Math.max(0, wakeAt - now);if (maxWaitMs !== undefined && now - startedAt + delay > maxWaitMs) return result;await wait(delay, follow.signal);+ [result] = await scheduler.run([scheduled(request)]);+ if (result === undefined) throw new Error(`Local Scheduler returned no result for ${request.id}`);}};return {build: runBuild,async buildMany(requests) {await Promise.all(requests.map(stageAttachments));- return await scheduler.run(requests.map(scheduled));+ for (const request of requests) {+ if (request.catalog === undefined) continue;+ assert(request.catalog.core === request.state.id,+ `Build Catalog Core ${request.catalog.core} differs from Build ${request.state.id}`);+ }+ const results = await scheduler.run(requests.map(scheduled));+ await Promise.all(requests.map(async (request) => {+ if (request.catalog !== undefined) await buildCatalog.record(request.id, request.catalog);+ }));+ return results;},async status(build) {return {build: await options.buildStore.read(build),+ catalog: await buildCatalog.read(build),operations: options.operationStore === undefined ? [] : await options.operationStore.list({ build }),};},+ async builds() {+ return await buildCatalog.list();+ },async cancel(build) {if (options.operationStore === undefined) throw new Error("Local Runtime has no OperationStore");const snapshot = await options.buildStore.read(build);@@ -283,6 +305,7 @@ export async function createProjectLocalRuntime(});const runtime = await createLocalRuntime({buildStore: services.buildStore,+ buildCatalog: projectServices.catalog,operationStore: services.operationStore,artifactStore: services.artifactStore,credentialStore: services.credentialStore,@@ -304,14 +327,15 @@ export async function createProjectLocalRuntime(build: runtime.build,buildMany: runtime.buildMany,status: runtime.status,+ builds: runtime.builds,cancel: runtime.cancel,readArtifact: runtime.readArtifact,close() {- return services.close();+ return projectServices.close();},};} catch (error) {- await services.close();+ await projectServices.close();throw error;}}diff --git a/packages/local/src/types.ts b/packages/local/src/types.tsindex a5535430..c8ab3a67 100644--- a/packages/local/src/types.ts+++ b/packages/local/src/types.ts@@ -5,6 +5,9 @@ import type { BuildState } from "@svml/protocol";import type { Digest } from "@svml/protocol";import type {ArtifactStore,+ BuildCatalog,+ BuildCatalogDescriptor,+ BuildCatalogEntry,BuildSchedulerFactory,BuildSchedulerOptions,BuildSnapshot,@@ -35,6 +38,8 @@ export type LocalRuntimeClosureOptions = {export type CreateLocalRuntimeOptions = {readonly buildStore: BuildStore;+ /** Host presentation metadata only; never part of Runtime Closure or Core state. */+ readonly buildCatalog?: BuildCatalog;readonly operationStore?: OperationStore;readonly artifactStore: ArtifactStore;readonly credentialStore?: CredentialStore;@@ -52,7 +57,10 @@ export type ProjectLocalRuntimeOptions = {/** Project directory containing the private .svml Runtime directory. Defaults to cwd. */readonly root?: string;readonly statePath?: string;+ /** Optional separate Host catalog database. Defaults to statePath when using local SQLite state. */+ readonly catalogPath?: string;readonly artifactPath?: string;+ readonly buildCatalog?: BuildCatalog;/** Exact installed implementation package lock. Source imports cannot change this selection. */readonly packageLock?: string;/** Additional configured Runtime services. A unique supplied role replaces that role's local default. */@@ -82,6 +90,8 @@ export type LocalBuildRequest = {/** Stable user/run identity. Reusing it resumes only the same Core Build identity. */readonly id: string;readonly state: BuildState;+ /** Source aliases and paths for Host inspection. Not trusted Build input. */+ readonly catalog?: BuildCatalogDescriptor;/** Host transfer bundle. It is staged before Core commands run and never enters BuildState. */readonly attachments?: readonly ArtifactAttachment[];};@@ -96,6 +106,7 @@ export type LocalBuildOptions = {export type LocalRuntimeStatus = {readonly build: BuildSnapshot | undefined;+ readonly catalog: BuildCatalogEntry | undefined;readonly operations: readonly OperationSnapshot[];};@@ -103,6 +114,7 @@ export type LocalRuntime = {build(request: LocalBuildRequest, options?: LocalBuildOptions): Promise<ScheduledBuildResult>;buildMany(requests: readonly LocalBuildRequest[]): Promise<readonly ScheduledBuildResult[]>;status(build: string): Promise<LocalRuntimeStatus>;+ builds(): Promise<readonly BuildCatalogEntry[]>;cancel(build: string): Promise<ScheduledBuildResult | undefined>;readArtifact(digest: Digest): Promise<Uint8Array | undefined>;close(): Awaitable<void>;diff --git a/packages/local/test/config.test.ts b/packages/local/test/config.test.tsindex c2e19d96..90ab35ad 100644--- a/packages/local/test/config.test.ts+++ b/packages/local/test/config.test.ts@@ -29,6 +29,13 @@ test("declarative Runtime config starts the domain-neutral local defaults", asyn});test("Runtime config is closed data and rejects unknown environment authority", () => {+ assert.equal(parseRuntimeConfig({+ format: "svml.runtime-config@1",+ catalogPath: ".svml/catalog.sqlite",+ services: [],+ endpoints: [],+ permissions: [],+ }).catalogPath, ".svml/catalog.sqlite");assert.throws(() => parseRuntimeConfig({format: "svml.runtime-config@1",services: [],diff --git a/packages/local/test/local.test.ts b/packages/local/test/local.test.tsindex 71ecd19c..f3b5193b 100644--- a/packages/local/test/local.test.ts+++ b/packages/local/test/local.test.ts@@ -54,6 +54,17 @@ const providerManifest: RuntimeModuleManifest = {test("project local runtime resumes durable work while component and endpoint packages stay replaceable", async () => {const directory = await mkdtemp(join(tmpdir(), "svml-local-"));+ const initial = createGreetingBuild();+ const catalog = {+ format: "svml.build-catalog-descriptor@1" as const,+ core: initial.id,+ source: { path: join(directory, "main.svml"), closure: digestOf("source:greeting") },+ aliases: [{+ name: "final.document",+ type: initial.plan.goals[0]!.type,+ ref: { kind: "logical-output" as const, id: initial.request.targets[0]!.output },+ }],+ };let promptCalls = 0;let requestCalls = 0;let assembleCalls = 0;@@ -151,7 +162,7 @@ test("project local runtime resumes durable work while component and endpoint pacomponents: [components],endpoints: [endpointPackage],});- const first = await firstRuntime.build({ id: "client-video", state: createGreetingBuild() });+ const first = await firstRuntime.build({ id: "client-video", state: initial, catalog });assert.equal(first.status, "paused");assert.equal(starts, 1);assert.equal(resumes, 0);@@ -162,13 +173,17 @@ test("project local runtime resumes durable work while component and endpoint pacomponents: [components],endpoints: [endpointPackage],});- const second = await secondRuntime.build({ id: "client-video", state: createGreetingBuild() });+ const second = await secondRuntime.build({ id: "client-video", state: createGreetingBuild(), catalog });assert.equal(second.status, "complete");assert.equal(starts, 1);assert.equal(resumes, 1);assert.equal(promptCalls, 1, "persisted Core facts stop deterministic upstream replay");assert.equal(requestCalls, 1, "the Need request Producer is also persisted");assert.equal(assembleCalls, 1);+ const clientStatus = await secondRuntime.status("client-video");+ assert.equal(clientStatus.catalog?.core, initial.id);+ assert.equal(clientStatus.catalog?.aliases[0]?.name, "final.document");+ assert.deepEqual((await secondRuntime.builds()).map((item) => item.build), ["client-video"]);const followed = await secondRuntime.build({ id: "follow-video", state: createGreetingBuild() },diff --git a/packages/runtime/src/catalog.ts b/packages/runtime/src/catalog.tsnew file mode 100644index 00000000..0d417835--- /dev/null+++ b/packages/runtime/src/catalog.ts@@ -0,0 +1,125 @@+import { isDigest } from "@svml/protocol";+import type {+ Digest,+ LogicalOutputRef,+ RecordRef,+ TypeRef,+} from "@svml/protocol";++export type BuildCatalogAlias = {+ readonly name: string;+ readonly type: TypeRef;+ readonly ref: RecordRef | LogicalOutputRef;+};++export type BuildCatalogDescriptor = {+ readonly format: "svml.build-catalog-descriptor@1";+ readonly core: Digest;+ readonly source: {+ readonly path: string;+ readonly closure: Digest;+ };+ readonly run?: {+ readonly path: string;+ readonly targetSet?: string;+ };+ readonly aliases: readonly BuildCatalogAlias[];+};++export type BuildCatalogEntry = BuildCatalogDescriptor & {+ readonly build: string;+ readonly createdAt: number;+ readonly updatedAt: number;+};++/** Host presentation index only. It is never Build truth or part of Runtime Closure. */+export type BuildCatalog = {+ record(build: string, descriptor: BuildCatalogDescriptor): Promise<BuildCatalogEntry>;+ read(build: string): Promise<BuildCatalogEntry | undefined>;+ list(): Promise<readonly BuildCatalogEntry[]>;+};++function assert(condition: unknown, message: string): asserts condition {+ if (!condition) throw new Error(message);+}++function verifyType(type: TypeRef, subject: string): void {+ assert(type.module.name.trim().length > 0, `${subject} module name is empty`);+ assert(type.module.version.trim().length > 0, `${subject} module version is empty`);+ assert(type.name.trim().length > 0, `${subject} type name is empty`);+}++export function verifyBuildCatalogDescriptor(descriptor: BuildCatalogDescriptor): void {+ assert(descriptor.format === "svml.build-catalog-descriptor@1", "Build Catalog descriptor format is invalid");+ assert(isDigest(descriptor.core), "Build Catalog Core identity is invalid");+ assert(descriptor.source.path.trim().length > 0, "Build Catalog source path is empty");+ assert(isDigest(descriptor.source.closure), "Build Catalog source closure is invalid");+ if (descriptor.run !== undefined) {+ assert(descriptor.run.path.trim().length > 0, "Build Catalog Run path is empty");+ if (descriptor.run.targetSet !== undefined) {+ assert(descriptor.run.targetSet.trim().length > 0, "Build Catalog target-set name is empty");+ }+ }+ const names = new Set<string>();+ for (const alias of descriptor.aliases) {+ assert(alias.name.trim().length > 0, "Build Catalog alias name is empty");+ assert(!names.has(alias.name), `Build Catalog repeats alias ${alias.name}`);+ names.add(alias.name);+ verifyType(alias.type, `Build Catalog alias ${alias.name}`);+ assert(alias.ref.kind === "record" || alias.ref.kind === "logical-output",+ `Build Catalog alias ${alias.name} has an unsupported reference`);+ assert(alias.ref.id.trim().length > 0, `Build Catalog alias ${alias.name} reference is empty`);+ }+}++export function verifyBuildCatalogEntry(entry: BuildCatalogEntry): void {+ verifyBuildCatalogDescriptor(entry);+ assert(entry.build.trim().length > 0, "Build Catalog build id is empty");+ assert(Number.isSafeInteger(entry.createdAt) && entry.createdAt >= 0, "Build Catalog createdAt is invalid");+ assert(Number.isSafeInteger(entry.updatedAt) && entry.updatedAt >= entry.createdAt,+ "Build Catalog updatedAt is invalid");+}++function copy<T>(value: T): T {+ return structuredClone(value);+}++export class MemoryBuildCatalog implements BuildCatalog {+ readonly #entries = new Map<string, BuildCatalogEntry>();+ readonly #now: () => number;++ constructor(now: () => number = Date.now) {+ this.#now = now;+ }++ async record(build: string, descriptor: BuildCatalogDescriptor): Promise<BuildCatalogEntry> {+ assert(build.trim().length > 0, "Build Catalog build id is empty");+ verifyBuildCatalogDescriptor(descriptor);+ const existing = this.#entries.get(build);+ if (existing !== undefined) {+ assert(existing.core === descriptor.core, `Build Catalog ${build} already names another Core Build`);+ }+ const now = this.#now();+ assert(Number.isSafeInteger(now) && now >= 0, "Build Catalog clock returned an invalid time");+ const entry: BuildCatalogEntry = {+ ...copy(descriptor),+ build,+ createdAt: existing?.createdAt ?? now,+ updatedAt: Math.max(now, existing?.updatedAt ?? now),+ };+ verifyBuildCatalogEntry(entry);+ this.#entries.set(build, entry);+ return copy(entry);+ }++ async read(build: string): Promise<BuildCatalogEntry | undefined> {+ const entry = this.#entries.get(build);+ return entry === undefined ? undefined : copy(entry);+ }++ async list(): Promise<readonly BuildCatalogEntry[]> {+ return [...this.#entries.values()]+ .sort((left, right) => right.createdAt - left.createdAt || left.build.localeCompare(right.build))+ .map(copy);+ }+}diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.tsindex 2ace167d..0cd0b433 100644--- a/packages/runtime/src/index.ts+++ b/packages/runtime/src/index.ts@@ -1,4 +1,10 @@export { MemoryBuildStore } from "./memory.js";+export {+ MemoryBuildCatalog,+ verifyBuildCatalogDescriptor,+ verifyBuildCatalogEntry,+} from "./catalog.js";+export type * from "./catalog.js";export {credentialRef,verifyCredentialRef,diff --git a/packages/runtime/test/catalog.test.ts b/packages/runtime/test/catalog.test.tsnew file mode 100644index 00000000..a78df8ec--- /dev/null+++ b/packages/runtime/test/catalog.test.ts@@ -0,0 +1,53 @@+import assert from "node:assert/strict";+import test from "node:test";++import { digestOf } from "@svml/core";+import { MemoryBuildCatalog } from "@svml/runtime";++function descriptor(core = digestOf("core:one")) {+ return {+ format: "svml.build-catalog-descriptor@1" as const,+ core,+ source: { path: "/project/main.svml", closure: digestOf("source:one") },+ run: { path: "/project/delivery.svrun", targetSet: "delivery" },+ aliases: [{+ name: "final.video",+ type: { module: { name: "example.media", version: "1" }, name: "Video" },+ ref: { kind: "logical-output" as const, id: "logical:final" },+ }],+ };+}++test("Build Catalog indexes Host aliases without becoming Build truth", async () => {+ let now = 100;+ const catalog = new MemoryBuildCatalog(() => now);+ const first = await catalog.record("delivery-01", descriptor());+ assert.equal(first.createdAt, 100);+ assert.equal(first.aliases[0]?.name, "final.video");++ now = 200;+ const updated = await catalog.record("delivery-01", {+ ...descriptor(),+ aliases: [...descriptor().aliases, {+ name: "timing.map",+ type: { module: { name: "example.timing", version: "1" }, name: "Map" },+ ref: { kind: "logical-output" as const, id: "logical:timing" },+ }],+ });+ assert.equal(updated.createdAt, 100);+ assert.equal(updated.updatedAt, 200);+ assert.deepEqual(updated.aliases.map((item) => item.name), ["final.video", "timing.map"]);+ assert.deepEqual((await catalog.list()).map((item) => item.build), ["delivery-01"]);++ (updated as unknown as { aliases: { name: string }[] }).aliases[0]!.name = "tampered";+ assert.equal((await catalog.read("delivery-01"))?.aliases[0]?.name, "final.video");+});++test("Build Catalog cannot retarget one Build id to another Core Build", async () => {+ const catalog = new MemoryBuildCatalog(() => 100);+ await catalog.record("delivery-01", descriptor());+ await assert.rejects(+ catalog.record("delivery-01", descriptor(digestOf("core:two"))),+ /another Core Build/u,+ );+});diff --git a/packages/store-sqlite/README.md b/packages/store-sqlite/README.mdindex 7812920a..7970aee0 100644--- a/packages/store-sqlite/README.md+++ b/packages/store-sqlite/README.md@@ -2,15 +2,19 @@Durable local adapters for the environment-neutral `BuildStore` and `OperationStore` ports.-One SQLite file may physically contain both tables, but the two interfaces remain separate:+One SQLite file may physically contain the execution tables and an optional Host index, but their+interfaces remain separate:- BuildStore persists verified Core facts with compare-and-swap revisions;- OperationStore persists external attempt identities, checkpoints and completions;+- BuildCatalog indexes source/run paths and output aliases for Host presentation only;- no ready-command queue is stored. Core regenerates readiness from BuildState after every restart.Artifacts and credentials never enter this database. The adapter owns its private, versioned schema;Core and Endpoint packages do not import SQLite or run these migrations.`createSqliteRuntimeServicePackage()` returns one physical package with two separately selectable-logical services. They share one connection and one close lifecycle without pretending that-BuildStore and OperationStore are the same interface.+execution services plus a Host-only `catalog` handle. They share one connection and one close+lifecycle. The catalog is deliberately absent from the Runtime service Manifest and Runtime+Closure; a physical catalog schema migration therefore cannot change the identity under which an+active Build resumes.diff --git a/packages/store-sqlite/src/store.ts b/packages/store-sqlite/src/store.tsindex 327c2b21..859fab4d 100644--- a/packages/store-sqlite/src/store.ts+++ b/packages/store-sqlite/src/store.ts@@ -12,12 +12,17 @@ import type {Digest,} from "@svml/protocol";import {+ verifyBuildCatalogDescriptor,+ verifyBuildCatalogEntry,defineRuntimeServicePackage,sealOperationCompletion,verifyOperationIdentity,verifyOperationSnapshot,} from "@svml/runtime";import type {+ BuildCatalog,+ BuildCatalogDescriptor,+ BuildCatalogEntry,BuildSnapshot,BuildStore,BuildStoreWrite,@@ -31,7 +36,9 @@ import type {RuntimeServicePackage,} from "@svml/runtime";-const schemaVersion = 1;+const databaseSchemaVersion = 2;+/** Build/Operation table semantics are unchanged by the Host-only Catalog migration. */+const executionStoreSchemaVersion = 1;export const sqliteStoreModuleRef = {name: "@svml/store-sqlite",@@ -189,6 +196,70 @@ class SqliteBuildStore implements BuildStore {}}+function parseCatalogEntry(row: Row): BuildCatalogEntry {+ assert(typeof row.build_id === "string", "SQLite Build Catalog row has no build id");+ assert(typeof row.created_at === "number", "SQLite Build Catalog row has no creation time");+ assert(typeof row.updated_at === "number", "SQLite Build Catalog row has no update time");+ assert(typeof row.descriptor_json === "string", "SQLite Build Catalog row has no descriptor");+ const descriptor = JSON.parse(row.descriptor_json) as BuildCatalogDescriptor;+ const entry = {+ ...descriptor,+ build: row.build_id,+ createdAt: row.created_at,+ updatedAt: row.updated_at,+ };+ verifyBuildCatalogEntry(entry);+ return entry;+}++class SqliteBuildCatalog implements BuildCatalog {+ readonly #database: DatabaseSync;++ constructor(database: DatabaseSync) {+ this.#database = database;+ }++ async record(build: string, descriptor: BuildCatalogDescriptor): Promise<BuildCatalogEntry> {+ assert(build.trim().length > 0, "Build Catalog build id must not be empty");+ verifyBuildCatalogDescriptor(descriptor);+ const now = Date.now();+ const inserted = this.#database.prepare(`+ INSERT OR IGNORE INTO svml_build_catalog (+ build_id, core_id, created_at, updated_at, descriptor_json+ ) VALUES (?, ?, ?, ?, ?)+ `).run(build, descriptor.core, now, now, canonicalStringify(descriptor));+ if (inserted.changes !== 1) {+ const updated = this.#database.prepare(`+ UPDATE svml_build_catalog+ SET updated_at = MAX(updated_at, ?), descriptor_json = ?+ WHERE build_id = ? AND core_id = ?+ `).run(now, canonicalStringify(descriptor), build, descriptor.core);+ assert(updated.changes === 1, `Build Catalog ${build} already names another Core Build`);+ }+ const stored = await this.read(build);+ if (stored === undefined) throw new Error(`Build Catalog ${build} disappeared after record`);+ return stored;+ }++ async read(build: string): Promise<BuildCatalogEntry | undefined> {+ const row = this.#database.prepare(`+ SELECT build_id, created_at, updated_at, descriptor_json+ FROM svml_build_catalog+ WHERE build_id = ?+ `).get(build) as Row | undefined;+ return row === undefined ? undefined : parseCatalogEntry(row);+ }++ async list(): Promise<readonly BuildCatalogEntry[]> {+ const rows = this.#database.prepare(`+ SELECT build_id, created_at, updated_at, descriptor_json+ FROM svml_build_catalog+ ORDER BY created_at DESC, build_id ASC+ `).all() as Row[];+ return rows.map(parseCatalogEntry);+ }+}+class SqliteOperationStore implements OperationStore {readonly #database: DatabaseSync;@@ -276,11 +347,12 @@ class SqliteOperationStore implements OperationStore {}}-/** One local database, two deliberately separate persistence ports, and no durable ready queue. */+/** One local database, two execution stores, one Host catalog, and no durable ready queue. */export class SqliteRuntimeState {readonly path: string;readonly builds: BuildStore;readonly operations: OperationStore;+ readonly catalog: BuildCatalog;readonly #database: DatabaseSync;constructor(path: string, options: SqliteRuntimeStateOptions = {}) {@@ -313,15 +385,35 @@ export class SqliteRuntimeState {failure_json TEXT) STRICT;`);+ const catalogSchema = `+ CREATE TABLE svml_build_catalog (+ build_id TEXT PRIMARY KEY,+ core_id TEXT NOT NULL,+ created_at INTEGER NOT NULL,+ updated_at INTEGER NOT NULL,+ descriptor_json TEXT NOT NULL+ ) STRICT;+ `;const version = this.#database.prepare("SELECT schema_version FROM svml_store_meta WHERE singleton = 1").get() as Row | undefined;if (version === undefined) {- this.#database.prepare("INSERT OR IGNORE INTO svml_store_meta (singleton, schema_version) VALUES (1, ?)").run(schemaVersion);+ this.#database.exec(`BEGIN IMMEDIATE; ${catalogSchema}`);+ this.#database.prepare("INSERT INTO svml_store_meta (singleton, schema_version) VALUES (1, ?)").run(databaseSchemaVersion);+ this.#database.exec("COMMIT");+ } else if (version.schema_version === 1) {+ this.#database.exec(`BEGIN IMMEDIATE; ${catalogSchema}`);+ this.#database.prepare("UPDATE svml_store_meta SET schema_version = ? WHERE singleton = 1").run(databaseSchemaVersion);+ this.#database.exec("COMMIT");} else {- assert(version.schema_version === schemaVersion,+ assert(version.schema_version === databaseSchemaVersion,`unsupported @svml/store-sqlite schema ${String(version.schema_version)}`);+ const catalog = this.#database.prepare(`+ SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'svml_build_catalog'+ `).get() as Row | undefined;+ assert(catalog?.name === "svml_build_catalog", "SQLite v2 database is missing the Build Catalog table");}this.builds = new SqliteBuildStore(database);this.operations = new SqliteOperationStore(database);+ this.catalog = new SqliteBuildCatalog(database);}close(): void {@@ -331,14 +423,14 @@ export class SqliteRuntimeState {export function createSqliteRuntimeServicePackage(options: CreateSqliteRuntimeServicePackageOptions,-): RuntimeServicePackage {+): RuntimeServicePackage & { readonly catalog: BuildCatalog } {const state = new SqliteRuntimeState(options.path, {...(options.busyTimeoutMs === undefined ? {} : { busyTimeoutMs: options.busyTimeoutMs }),});const buildInstance = options.buildInstance ?? "builds.sqlite";const operationInstance = options.operationInstance ?? "operations.sqlite";try {- return defineRuntimeServicePackage({+ return Object.assign(defineRuntimeServicePackage({name: options.name ?? "state.sqlite",module: sqliteStoreModuleRef,services: [@@ -353,7 +445,7 @@ export function createSqliteRuntimeServicePackage(permissions: ["filesystem:state"],configuration: {path: state.path,- schemaVersion,+ schemaVersion: executionStoreSchemaVersion,busyTimeoutMs: options.busyTimeoutMs ?? 5_000,},service: state.builds,@@ -369,14 +461,14 @@ export function createSqliteRuntimeServicePackage(permissions: ["filesystem:state"],configuration: {path: state.path,- schemaVersion,+ schemaVersion: executionStoreSchemaVersion,busyTimeoutMs: options.busyTimeoutMs ?? 5_000,},service: state.operations,},],close: () => state.close(),- });+ }), { catalog: state.catalog });} catch (error) {state.close();throw error;diff --git a/packages/store-sqlite/test/store.test.ts b/packages/store-sqlite/test/store.test.tsindex d26854c1..f160839f 100644--- a/packages/store-sqlite/test/store.test.ts+++ b/packages/store-sqlite/test/store.test.ts@@ -3,12 +3,16 @@ import { mkdtemp, rm } from "node:fs/promises";import { join } from "node:path";import { tmpdir } from "node:os";import test from "node:test";+import { DatabaseSync } from "node:sqlite";import { digestOf } from "@svml/core";import {sealOperationIdentity,} from "@svml/runtime";-import { SqliteRuntimeState } from "@svml/store-sqlite";+import {+ createSqliteRuntimeServicePackage,+ SqliteRuntimeState,+} from "@svml/store-sqlite";import { createGreetingBuild } from "../../core/test/greeting-fixture.js";@@ -20,6 +24,16 @@ test("SQLite stores verified Build facts and Operation checkpoints across reopenconst initial = createGreetingBuild();const created = await first.builds.create("video", initial);assert.equal(created.revision, 0);+ await first.catalog.record("video", {+ format: "svml.build-catalog-descriptor@1",+ core: initial.id,+ source: { path: "/project/main.svml", closure: digestOf("source-closure") },+ aliases: [{+ name: "final.video",+ type: initial.plan.goals[0]!.type,+ ref: { kind: "logical-output", id: initial.request.targets[0]!.output },+ }],+ });const operation = sealOperationIdentity({build: "video",command: "command:generation",@@ -41,6 +55,8 @@ test("SQLite stores verified Build facts and Operation checkpoints across reopenconst second = new SqliteRuntimeState(path);assert.equal((await second.builds.read("video"))?.state.id, initial.id);+ assert.equal((await second.catalog.read("video"))?.aliases[0]?.name, "final.video");+ assert.deepEqual((await second.catalog.list()).map((item) => item.build), ["video"]);const restoredOperation = await second.operations.read(operation.id);assert.equal(restoredOperation?.status, "pending");assert.deepEqual(restoredOperation?.checkpoint, { remoteJob: "job-1" });@@ -95,3 +111,49 @@ test("SQLite Operation CAS preserves a terminal completion", async () => {await rm(directory, { recursive: true, force: true });}});++test("SQLite upgrades the append-only v1 state database with a Host Catalog", async () => {+ const directory = await mkdtemp(join(tmpdir(), "svml-catalog-migration-"));+ const path = join(directory, "runtime.sqlite");+ try {+ const legacy = new DatabaseSync(path);+ legacy.exec(`+ CREATE TABLE svml_store_meta (+ singleton INTEGER PRIMARY KEY CHECK (singleton = 1),+ schema_version INTEGER NOT NULL+ ) STRICT;+ INSERT INTO svml_store_meta (singleton, schema_version) VALUES (1, 1);+ `);+ legacy.close();++ const migrated = new SqliteRuntimeState(path);+ assert.deepEqual(await migrated.catalog.list(), []);+ migrated.close();++ const checked = new DatabaseSync(path);+ const version = checked.prepare("SELECT schema_version FROM svml_store_meta WHERE singleton = 1").get() as {+ readonly schema_version: number;+ };+ assert.equal(version.schema_version, 2);+ checked.close();+ } finally {+ await rm(directory, { recursive: true, force: true });+ }+});++test("Host Catalog schema changes do not change the execution Runtime Closure", async () => {+ const directory = await mkdtemp(join(tmpdir(), "svml-sqlite-closure-"));+ try {+ const services = createSqliteRuntimeServicePackage({ path: join(directory, "runtime.sqlite") });+ assert.deepEqual(+ services.services.map((item) => item.instance.configurationDigest),+ [+ digestOf({ path: join(directory, "runtime.sqlite"), schemaVersion: 1, busyTimeoutMs: 5_000 }),+ digestOf({ path: join(directory, "runtime.sqlite"), schemaVersion: 1, busyTimeoutMs: 5_000 }),+ ],+ );+ await services.close?.();+ } finally {+ await rm(directory, { recursive: true, force: true });+ }+});