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): add host build catalog

kashorincceef745cc7a
diff --git a/README.md b/README.md
index bf1c60a8..54f6d16d 100644
--- a/README.md
+++ b/README.md
@@ -113,12 +113,14 @@ pnpm svml:v2 build examples/talking-film-live/build.svrun \
--follow
pnpm 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. Paid
credentials, presenter assets, local databases and generated outputs are not committed.
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 5466096e..24d4f22e 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -27,8 +27,9 @@ 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
-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.mp4
pnpm 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, demanded
Logical 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 Host
verifies the prior Build only to extract a typed Record, attaches it as an ordinary zero-input
diff --git a/packages/cli/src/archive.ts b/packages/cli/src/archive.ts
index 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.ts
index 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.ts
index 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 build
derivations: [],
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.md
index 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` with
Record and content identities, not private filesystem layout, so filesystem and S3 stores remain
interchangeable. 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 selected
ArtifactStore. Each attachment carries claimed `BlobRef` metadata plus bytes; Local Runtime copies
the bytes, stores them content-addressably and requires the Store's returned digest, size and media
diff --git a/packages/local/src/config.ts b/packages/local/src/config.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 pa
components: [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 pa
components: [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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.md
index 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.ts
index 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.ts
index 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 reopen
const 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 reopen
const 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 });
+ }
+});