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(runtime): make local execution revision-aware

kashorin4a66600116e2
diff --git a/.agents/skills/narratage/SKILL.md b/.agents/skills/narratage/SKILL.md
index a330dc6a..41deb321 100644
--- a/.agents/skills/narratage/SKILL.md
+++ b/.agents/skills/narratage/SKILL.md
@@ -25,8 +25,8 @@ Source, and `svml.runtime.json`/`.ts` Runtime Profile separate.
## Required loop
```bash
-pnpm narratage check path/to/main.svml --package-lock path/to/svml.packages.lock --root .
-pnpm narratage plan path/to/build.svrun --package-lock path/to/svml.packages.lock --root .
+node --run narratage -- check path/to/main.svml --package-lock path/to/svml.packages.lock --root .
+node --run narratage -- plan path/to/build.svrun --package-lock path/to/svml.packages.lock --root .
```
Preserve unrelated changes. Keep credentials, generated media, runtime state, and logs out of commits.
diff --git a/.agents/skills/narratage/references/environment.md b/.agents/skills/narratage/references/environment.md
index 987d6cbf..20035646 100644
--- a/.agents/skills/narratage/references/environment.md
+++ b/.agents/skills/narratage/references/environment.md
@@ -20,8 +20,8 @@ uv python install 3.13
uv sync --project services/whisperx --frozen
uv sync --project services/image-opencv --frozen
uv run --project services/whisperx --frozen svml-whisperx-prepare
-pnpm narratage services up svml.runtime.json
-pnpm narratage doctor svml.runtime.json
+node --run narratage -- services up svml.runtime.json
+node --run narratage -- doctor svml.runtime.json
```
The repository owns skill discovery: `.agents/skills` is canonical, with repository-root
diff --git a/docs/guide/services.md b/docs/guide/services.md
index 053839db..a6332a02 100644
--- a/docs/guide/services.md
+++ b/docs/guide/services.md
@@ -30,10 +30,15 @@ clean final document.
- durable queue phase counts and shared capacity reservations;
- declared external-program health.
+A stopped idle Runtime is a valid observation, not a failed command. `runtime status` exits
+successfully after a successful query and reports `ready: false`; it becomes an attention warning
+when unfinished dispatch exists but the Worker or a required declared program is unavailable.
+
The Worker record binds an effective Profile revision covering the Profile bytes plus both package
locks it names. Editing the same Profile path or regenerating either lock makes the old process
-`stale`; the next `runtime up` or `build` replaces it before admitting work under the new
-configuration.
+`stale`. The next `runtime up` or `build` first checks the DispatchStore: unfinished work from the
+old revision rejects the new revision without stopping the old Worker or starting external
+programs. Once old work is terminal, replacement is allowed.
`runtime down` asks the Worker to stop and then stops programs that the Profile owns. It does not
cancel Builds or remote Provider jobs. Queued Builds remain durable and continue after the Runtime
@@ -57,6 +62,10 @@ Build queue. It operates only on adapter-declared programs such as:
Remote-only Endpoints such as KIE have no local service.
+`services status` names every unavailable declared program and also treats a successful query as a
+successful command. Readiness remains explicit in its structured `ready` field. `services up` and
+`services down` are lifecycle requests and still fail when the requested state is not reached.
+
## Build relationship
```bash
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index 1e6172cd..b1ffb402 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -686,6 +686,14 @@ function queueRouteLines(groups: readonly QueueRouteSummary[]): readonly string[
return lines;
}
+function externalServiceLine(service: ExternalServiceReport): string {
+ const stateDetail = "detail" in service.state ? ` — ${service.state.detail}` : "";
+ const action = service.action === undefined ? "" : ` · ${service.action}`;
+ const detail = service.detail === undefined ? "" : ` · ${service.detail}`;
+ const instances = service.instances.length === 0 ? "" : ` · ${service.instances.join(", ")}`;
+ return `${service.id}: ${service.state.state}${stateDetail}${action}${detail}${instances}`;
+}
+
function inlineValuePreview(value: unknown, limit = 240): string {
const encoded = JSON.stringify(value);
if (encoded.length <= limit) return encoded;
@@ -821,7 +829,8 @@ export async function runCli(
distribution: CliDistribution,
): Promise<void> {
if (argv.length === 0 || argv[0] === "help" || argv.includes("--help")) {
- writeCliHelp(io);
+ const topic = argv[0] === "help" ? argv[1] : argv.includes("--help") ? argv[0] : undefined;
+ writeCliHelp(io, topic);
return;
}
const args = parseArgs(argv);
@@ -1067,17 +1076,26 @@ export async function runCli(
: args.action === "down"
? await distribution.externalServices.down(profile)
: await distribution.externalServices.report(profile);
+ const ready = result.services.every((item) => item.state.state === "ready");
+ const desiredState = args.action === "down" ? !result.services.some((item) => item.state.state === "ready") : ready;
const machine = {
- ok: result.services.every((item) => (args.action === "down" ? item.state.state !== "ready" : item.state.state === "ready")),
+ format: "narratage.cli-services-status@1" as const,
+ // A successful status query is not a failed lifecycle action. `ready` carries readiness.
+ ok: args.action === "status" ? true : desiredState,
+ ready,
root: result.root,
services: result.services,
};
- writeOperational(machine, `External services ${args.action}`, machine.ok ? "success" : "warning", [
+ const shownServices = args.verbose || args.action !== "status"
+ ? result.services
+ : result.services.filter((item) => item.state.state !== "ready");
+ writeOperational(machine, `External services ${args.action}`,
+ args.action === "status" ? ready ? "success" : "info" : machine.ok ? "success" : "warning", [
["Root", result.root],
["Services", String(result.services.length)],
["Ready", String(result.services.filter((item) => item.state.state === "ready").length)],
- ]);
- if (!machine.ok) io.setExitCode?.(1);
+ ], shownServices.map(externalServiceLine));
+ if (args.action !== "status" && !machine.ok) io.setExitCode?.(1);
return;
}
if (args.command === "runtime") {
@@ -1086,6 +1104,10 @@ export async function runCli(
}
const profile = resolve(args.file!);
if (args.action === "up") {
+ // Validate the exact Runtime Revision against unfinished work before replacing a stale Worker
+ // or starting external programs. A refusal must leave the old execution environment intact.
+ const validated = await loadLocalRuntime(profile, distribution);
+ await validated.close();
const external = await distribution.externalServices.up(profile, {
...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),
...(reportServiceProgress === undefined ? {} : { onProgress: reportServiceProgress }),
@@ -1128,30 +1150,51 @@ export async function runCli(
]);
return;
}
- const worker = await runtimeProcessStatus(profile);
- const external = await distribution.externalServices.report(profile);
- const runtime = await loadRuntimeControl(profile, distribution);
+ // These are independent views over one Profile. Load them concurrently without inventing a
+ // second registry; each selected package remains the authority for its own report.
+ const runtimeLoading = loadRuntimeControl(profile, distribution);
+ let runtime: LocalRuntimeControl | undefined;
try {
+ const loaded = await Promise.all([
+ runtimeProcessStatus(profile),
+ distribution.externalServices.report(profile),
+ runtimeLoading,
+ ]);
+ const [worker, external, selectedRuntime] = loaded;
+ runtime = selectedRuntime;
const queue = await runtime.queue();
const counts = Object.fromEntries(["queued", "leased", "waiting", "blocked", "settling", "terminal"]
.map((phase) => [phase, queue.dispatches.filter((item) => item.phase === phase).length]));
const routes = summarizeQueueRoutes(queue.capacity);
+ const ready = worker.state === "running"
+ && external.services.every((item) => item.state.state === "ready");
+ const active = ["queued", "leased", "waiting", "blocked", "settling"]
+ .reduce((total, phase) => total + (counts[phase] ?? 0), 0);
+ const attention = active > 0 && !ready;
+ const unavailable = external.services.filter((item) => item.state.state !== "ready");
const machine = {
- ok: worker.state === "running" && external.services.every((item) => item.state.state === "ready"),
+ format: "narratage.cli-runtime-status@1" as const,
+ ok: true,
+ ready,
+ attention,
worker,
queue: { counts, routes, capacity: queue.capacity },
services: external.services,
};
- writeOperational(machine, "Runtime status", machine.ok ? "success" : "warning", [
+ writeOperational(machine, "Runtime status", attention ? "warning" : ready ? "success" : "info", [
["Worker", worker.state],
["Queued", String(counts.queued ?? 0)],
["Running", String(counts.leased ?? 0)],
["Waiting", String(counts.waiting ?? 0)],
+ ["Services", `${external.services.length - unavailable.length}/${external.services.length} ready`],
["Capacity reservations", String(queue.capacity.length)],
- ], queueRouteLines(routes));
- if (!machine.ok) io.setExitCode?.(1);
+ ], [
+ ...unavailable.map(externalServiceLine),
+ ...queueRouteLines(routes),
+ ]);
} finally {
- await runtime.close();
+ if (runtime !== undefined) await runtime.close();
+ else await runtimeLoading.then(async (loaded) => await loaded.close(), () => undefined);
}
return;
}
@@ -1352,7 +1395,8 @@ export async function runCli(
if (operation === undefined) io.setExitCode?.(1);
} else if (args.command === "builds") {
const entries = await runtime.builds();
- const builds = await Promise.all(entries.map(async (entry) => {
+ const inspected = args.json || args.verbose ? entries : entries.slice(0, 20);
+ const builds = await Promise.all(inspected.map(async (entry) => {
const status = await runtime.status(entry.build);
return {
build: entry.build,
@@ -1363,12 +1407,13 @@ export async function runCli(
...summarizeBuildCatalog(entry, status.build?.state),
};
}));
- writeOperational({ builds }, "Build archive", "info", [["Builds", String(builds.length)]],
- builds.slice(0, args.verbose ? undefined : 20).map((item) => `${item.build}: ${item.status ?? "unknown"}`));
+ writeOperational({ builds }, "Build archive", "info", [["Builds", String(entries.length)]],
+ builds.map((item) => `${item.build}: ${item.status ?? "unknown"}`));
} else if (args.command === "history") {
const catalogs = await runtime.builds();
const entries = (await Promise.all(catalogs.map(async (catalog) => {
if (args.source !== undefined && catalog.source.path !== args.source) return [];
+ if (args.file !== undefined && !catalog.aliases.some((alias) => alias.name === args.file)) return [];
const status = await runtime.status(catalog.build);
if (status.build === undefined) return [];
return acceptedArchivedOutputs(status.build.state, catalog)
@@ -1828,6 +1873,11 @@ export async function runCli(
machine: result.plan,
run: loaded.path,
targetSet: loaded.run.graph.selectedTargets,
+ outputNames: Object.fromEntries(result.compilation.author.exports.flatMap((item) =>
+ item.ref.kind === "logical-output" ? [[item.ref.id, item.name]] : [])),
+ candidateNames: Object.fromEntries(Object.entries(loaded.run.candidates)
+ .sort(([left], [right]) => left.localeCompare(right))
+ .map(([name, id]) => [id, name])),
});
} finally {
await runtime?.close();
diff --git a/packages/cli/src/output.ts b/packages/cli/src/output.ts
index e46b437c..511ba915 100644
--- a/packages/cli/src/output.ts
+++ b/packages/cli/src/output.ts
@@ -100,6 +100,9 @@ export type CliPresentation =
readonly machine: BuildPlan;
readonly run: string;
readonly targetSet: string;
+ /** Presentation names declared by this Author Source and Run Source. Never used to plan. */
+ readonly outputNames?: Readonly<Record<string, string>>;
+ readonly candidateNames?: Readonly<Record<string, string>>;
}
| {
readonly kind: "operational";
@@ -286,18 +289,26 @@ function renderPlan(
const exact = view.machine.steps.filter((item) => item.fidelity === "exact").length;
const substitute = view.machine.steps.length - exact;
const grouped = new Map<string, number>();
+ const requested = new Map<string, number>();
for (const step of view.machine.steps) {
const name = `${step.producer.module.name}@${step.producer.module.version}`;
grouped.set(name, (grouped.get(name) ?? 0) + 1);
+ const needs = Object.keys(step.needs).length;
+ if (needs > 0) {
+ const producer = `${name}#${step.producer.name}`;
+ requested.set(producer, (requested.get(producer) ?? 0) + needs);
+ }
}
const lines = [heading("success", "Build plan is valid", io, colors), ""];
+ const requestCount = [...requested.values()].reduce((total, count) => total + count, 0);
lines.push(...facts([
["Run", shortPath(view.run)],
["Target set", view.targetSet],
["Goals", String(view.machine.goals.length)],
["Steps", String(view.machine.steps.length)],
- ["Exact", String(exact)],
- ["Substitute", String(substitute)],
+ ["Exact steps", String(exact)],
+ ["Substitute steps", String(substitute)],
+ ["External requests", String(requestCount)],
], colors));
if (grouped.size > 0) {
lines.push("", colors.strong("Operations"));
@@ -307,6 +318,17 @@ function renderPlan(
lines.push(` ${colors.accent(String(count).padStart(countWidth))} ${name}`);
}
}
+ if (requested.size > 0) {
+ lines.push("", colors.strong("External requests"));
+ const entries = [...requested.entries()].sort(([left], [right]) => left.localeCompare(right));
+ const countWidth = Math.max(...entries.map(([, count]) => String(count).length));
+ for (const [producer, count] of entries) {
+ lines.push(` ${colors.warning(String(count).padStart(countWidth))} ${producer}`);
+ }
+ lines.push(` ${colors.dim("These Needs may reach the Endpoints selected by the Runtime Profile during build.")}`);
+ } else {
+ lines.push("", heading("success", "No external requests", io, colors));
+ }
const visibleSelections = verbose
? view.machine.selections
: view.machine.selections.filter((selection) => selection.fidelity === "substitute");
@@ -316,7 +338,14 @@ function renderPlan(
const status = selection.fidelity === "exact"
? colors.success(glyph(io, "✓", "+"))
: colors.warning("!");
- lines.push(` ${status} ${shortOpaque(selection.output)} ${colors.dim(selection.fidelity)}`);
+ const output = view.outputNames?.[selection.output] ?? shortOpaque(selection.output);
+ const candidate = view.candidateNames?.[selection.candidate];
+ lines.push(` ${status} ${colors.accent(output)}`
+ + `${candidate === undefined ? "" : ` ← ${candidate}`}`
+ + ` ${colors.dim(selection.fidelity)}`);
+ if (verbose && (output !== selection.output || candidate !== undefined)) {
+ lines.push(` ${colors.dim(`${shortOpaque(selection.output)} ← ${shortOpaque(selection.candidate)}`)}`);
+ }
}
}
if (verbose) {
@@ -364,8 +393,85 @@ export function writeCliOutput(
io.write(output);
}
-export function writeCliHelp(io: CliIo): void {
+function commandHelp(topic: string, colors: Palette): readonly string[] | undefined {
+ const common = [
+ "",
+ colors.strong("Output"),
+ " --json complete machine-readable result",
+ " --verbose reveal identities and complete lists",
+ " --color auto|always|never control ANSI color",
+ " --debug include internal trace frames on failure",
+ "",
+ ];
+ const topics: Readonly<Record<string, readonly string[]>> = {
+ check: [
+ colors.accent(colors.strong("narratage check")),
+ colors.dim("Validate one self-described Author Source or Run Source without executing it."),
+ "",
+ " narratage check <source> [--runtime <profile>] [--package-lock <lock>] [--root <workspace>]",
+ ],
+ plan: [
+ colors.accent(colors.strong("narratage plan")),
+ colors.dim("Freeze the demanded subgraph and expose every selected Candidate and external Need."),
+ "",
+ " narratage plan <run-source> [--runtime <profile>] [--package-lock <lock>] [--root <workspace>]",
+ "",
+ "Planning never starts external work.",
+ ],
+ build: [
+ colors.accent(colors.strong("narratage build")),
+ colors.dim("Submit one durable Build and ensure its selected Runtime Worker is available."),
+ "",
+ " narratage build <run-source> --runtime <profile> [--build-id <id>] [--follow] [--no-services]",
+ "",
+ " --follow observe the Build; the Worker still owns execution",
+ " --no-services do not start declared external programs",
+ " --max-wait-ms <ms> bound startup or follow waiting",
+ ],
+ runtime: [
+ colors.accent(colors.strong("narratage runtime")),
+ colors.dim("Operate the Worker selected by one Runtime Profile."),
+ "",
+ " narratage runtime up <profile> validate the Runtime Revision, start services and Worker",
+ " narratage runtime status <profile> inspect Worker, queue capacity and declared services",
+ " narratage runtime logs <profile> read Worker logs",
+ " narratage runtime down <profile> stop the owned Worker and external programs",
+ ],
+ services: [
+ colors.accent(colors.strong("narratage services")),
+ colors.dim("Operate only the external programs declared by Endpoints in one Runtime Profile."),
+ "",
+ " narratage services up <profile> [--max-wait-ms <ms>]",
+ " narratage services status <profile>",
+ " narratage services down <profile>",
+ ],
+ queue: [
+ colors.accent(colors.strong("narratage queue")),
+ colors.dim("Inspect durable Build dispatch and Provider-authority capacity."),
+ "",
+ " narratage queue --runtime <profile> [--watch]",
+ " narratage queue --runtime <profile> --watch --jsonl",
+ ],
+ history: [
+ colors.accent(colors.strong("narratage history")),
+ colors.dim("Find accepted historical Logical Outputs without selecting them for a new Run."),
+ "",
+ " narratage history <output-name> --runtime <profile> [--source <author-source>]",
+ ],
+ };
+ const selected = topics[topic];
+ return selected === undefined ? undefined : [...selected, ...common];
+}
+
+export function writeCliHelp(io: CliIo, topic?: string): void {
const colors = palette(io.terminal?.isTTY === true && io.terminal.color);
+ if (topic !== undefined) {
+ const selected = commandHelp(topic, colors);
+ if (selected !== undefined) {
+ io.write(selected.join("\n"));
+ return;
+ }
+ }
io.write([
colors.accent(colors.strong("Narratage")),
colors.dim("Write the story. Compile the result."),
diff --git a/packages/cli/test/output.test.ts b/packages/cli/test/output.test.ts
index 9a47bb4c..580df3c9 100644
--- a/packages/cli/test/output.test.ts
+++ b/packages/cli/test/output.test.ts
@@ -132,7 +132,7 @@ test("plan groups operations by their declaring module", () => {
fidelity: "exact",
inputs: {},
outputs: {},
- needs: {},
+ needs: { generated: { id: "need-1", result: "record-1", accepts: "exact" } },
}, {
id: "step-2",
producer: { module: { name: "@narratage/media", version: "1" }, name: "normalize" },
@@ -142,15 +142,45 @@ test("plan groups operations by their declaring module", () => {
needs: {},
}],
goals: [],
- selections: [],
+ selections: [{
+ output: "logical:take",
+ candidate: "candidate:preview",
+ fidelity: "substitute",
+ record: "record:take",
+ }],
};
- const output = capture(human, { kind: "plan", machine: plan, run: "/project/build.svrun", targetSet: "film" });
+ const output = capture(human, {
+ kind: "plan",
+ machine: plan,
+ run: "/project/build.svrun",
+ targetSet: "film",
+ outputNames: { "logical:take": "take.video" },
+ candidateNames: { "candidate:preview": "preview" },
+ });
assert.match(output, /2\s+@narratage\/media@1/u);
- assert.match(output, /Exact\s+1/u);
- assert.match(output, /Substitute\s+1/u);
+ assert.match(output, /Exact steps\s+1/u);
+ assert.match(output, /Substitute steps\s+1/u);
+ assert.match(output, /External requests/u);
+ assert.match(output, /1\s+@narratage\/media@1#inspect/u);
+ assert.match(output, /take\.video ← preview/u);
assert.match(output, /No external work was started\./u);
});
+test("a plan with no Needs says so without knowing any Provider names", () => {
+ const plan: BuildPlan = {
+ format: "svml.plan@1",
+ id: digest,
+ graph: digest,
+ request: digest,
+ initialValues: [],
+ steps: [],
+ goals: [],
+ selections: [],
+ };
+ const output = capture(human, { kind: "plan", machine: plan, run: "/project/free.svrun", targetSet: "facts" });
+ assert.match(output, /No external requests/u);
+});
+
test("human errors expose stable codes while JSON errors remain parseable", () => {
const error = Object.assign(new Error("credential is absent"), { code: "RUNTIME_CREDENTIAL_MISSING" });
const humanError = renderCliError(error, { json: false, color: false, unicode: true, debug: false });
@@ -174,3 +204,11 @@ test("help is a successful product surface rather than a usage error", () => {
assert.match(output, /--json/u);
assert.doesNotMatch(output, /CLI_ERROR/u);
});
+
+test("command help explains only the selected shell grammar", () => {
+ let output = "";
+ writeCliHelp({ write(text) { output += text; } }, "build");
+ assert.match(output, /^narratage build\n/u);
+ assert.match(output, /--follow/u);
+ assert.doesNotMatch(output, /Authoring/u);
+});
diff --git a/packages/cli/test/services-command.test.ts b/packages/cli/test/services-command.test.ts
index 1c7c35c9..87e9dad0 100644
--- a/packages/cli/test/services-command.test.ts
+++ b/packages/cli/test/services-command.test.ts
@@ -60,3 +60,64 @@ test("services reads deployment selection from the Profile, never from flags", a
/services reads all deployment selection from the Runtime Profile itself/u,
);
});
+
+test("runtime up validates its Revision before starting any external program", async () => {
+ const calls: string[] = [];
+ const selected = distribution(calls);
+ const failing = {
+ ...selected,
+ createRuntimeFromConfig: async () => {
+ calls.push("runtime.validate");
+ throw new Error("Runtime Revision conflict");
+ },
+ } as CliDistribution;
+ await assert.rejects(
+ async () => await runCli(["runtime", "up", "/p/svml.runtime.json"], io, failing),
+ /Runtime Revision conflict/u,
+ );
+ assert.deepEqual(calls, ["runtime.validate"]);
+});
+
+test("services status reports readiness without turning an observation into a failed command", async () => {
+ let output = "";
+ let exitCode: number | undefined;
+ const selected = distribution([]);
+ selected.externalServices.report = async () => ({
+ root: "/project",
+ services: [{
+ id: "speech-evidence.local",
+ instances: ["speech.primary"],
+ state: { state: "down", detail: "not running" },
+ }],
+ });
+ await runCli(["services", "status", "/project/svml.runtime.json"], {
+ write(text) { output += text; },
+ setExitCode(code) { exitCode = code; },
+ }, selected);
+ assert.equal(exitCode, undefined);
+ assert.match(output, /speech-evidence\.local: down — not running/u);
+ assert.doesNotMatch(output, /Command failed/u);
+});
+
+test("an idle stopped Runtime is status data, not a command failure", async () => {
+ let output = "";
+ let exitCode: number | undefined;
+ const selected = {
+ ...distribution([]),
+ createRuntimeControlFromConfig: async () => ({
+ async queue() { return { dispatches: [], capacity: [], operations: [] }; },
+ async close() {},
+ }),
+ externalServices: {
+ ...distribution([]).externalServices,
+ report: async () => ({ root: "/project", services: [] }),
+ },
+ } as unknown as CliDistribution;
+ await runCli(["runtime", "status", "/project/svml.runtime.json"], {
+ write(text) { output += text; },
+ setExitCode(code) { exitCode = code; },
+ }, selected);
+ assert.equal(exitCode, undefined);
+ assert.match(output, /Runtime status/u);
+ assert.match(output, /Worker\s+stopped/u);
+});
diff --git a/packages/local/src/config.ts b/packages/local/src/config.ts
index 2e2ef6de..e80d8a6e 100644
--- a/packages/local/src/config.ts
+++ b/packages/local/src/config.ts
@@ -237,8 +237,8 @@ async function installLockedRuntimeAdapters(
path: string | undefined,
lockRoot: string,
packageRoot: string,
-): Promise<void> {
- if (path === undefined) return;
+): Promise<import("@narratage/protocol").Digest | undefined> {
+ if (path === undefined) return undefined;
const loaded = await loadNodePackageSet(resolve(lockRoot, path), packageRoot);
const lockedPackages = new Map(loaded.lock.packages.map((item) => [item.package.name, item]));
const artifacts = new Map(loaded.lock.artifacts.map((item) => [`${item.name}@${item.version}`, item]));
@@ -256,6 +256,7 @@ async function installLockedRuntimeAdapters(
});
}
}
+ return loaded.lock.digest;
}
/** One Endpoint's declaration of an external program its Provider drives. */
@@ -503,16 +504,15 @@ export async function createRuntimeFromConfig(
}
}
const registry = options.registry ?? new RuntimeAdapterRegistry();
- const implementationPackages = options.implementationPackages
- ?? (document.packageLock === undefined
- ? undefined
- : await Promise.all([
- installLockedRuntimeAdapters(registry, document.runtimePackageLock, root, packageRoot),
- loadNodePackageSet(resolve(root, document.packageLock), packageRoot),
- ]).then(([, loaded]) => loaded));
- if (options.implementationPackages !== undefined || document.packageLock === undefined) {
- await installLockedRuntimeAdapters(registry, document.runtimePackageLock, root, packageRoot);
- }
+ const implementationPackagesPromise = options.implementationPackages !== undefined
+ ? Promise.resolve(options.implementationPackages)
+ : document.packageLock === undefined
+ ? Promise.resolve(undefined)
+ : loadNodePackageSet(resolve(root, document.packageLock), packageRoot);
+ const [runtimePackageClosure, implementationPackages] = await Promise.all([
+ installLockedRuntimeAdapters(registry, document.runtimePackageLock, root, packageRoot),
+ implementationPackagesPromise,
+ ]);
const runtimeServices = await Promise.all(document.runtimeServices.map(async (item) => {
return await registry.createService(item.use, {
root,
@@ -534,6 +534,7 @@ export async function createRuntimeFromConfig(
...(implementationPackages === undefined
? {}
: { implementationClosure: implementationPackages.lock.digest }),
+ ...(runtimePackageClosure === undefined ? {} : { runtimePackageClosure }),
runtimeServices,
runtimeSelection: document.services,
components: [
diff --git a/packages/local/src/runtime.ts b/packages/local/src/runtime.ts
index 8610c705..96edc0cc 100644
--- a/packages/local/src/runtime.ts
+++ b/packages/local/src/runtime.ts
@@ -14,9 +14,12 @@ import {
collectNodePackageComponents,
} from "@narratage/package-loader-node";
import {
+ assertRuntimeRevisionAdmission,
RuntimeModuleRegistry,
createBuildDispatchIdentity,
+ createRuntimeRevision,
isStreamingArtifactStore,
+ nonTerminalDispatchPhases,
resolveRuntimeProfile,
sealRuntimeProfile,
} from "@narratage/runtime";
@@ -124,6 +127,17 @@ export async function createLocalRuntime(
if (options.scheduling?.maxConcurrency !== undefined || options.scheduling?.resourceLimits !== undefined) {
throw new Error("a locked Runtime Closure owns maxConcurrency and resource limits");
}
+ const runtimeRevision = createRuntimeRevision({
+ runtimeClosure: options.closure.value.digest,
+ ...(options.implementationClosure === undefined
+ ? {} : { implementationClosure: options.implementationClosure }),
+ ...(options.runtimePackageClosure === undefined
+ ? {} : { runtimePackageClosure: options.runtimePackageClosure }),
+ });
+ assertRuntimeRevisionAdmission(
+ runtimeRevision,
+ await options.dispatchStore.list({ phases: nonTerminalDispatchPhases }),
+ );
const producers = new ProducerRegistry();
const endpoints = new EndpointRegistry();
const validators = options.validators ?? new TypeValidatorRegistry();
@@ -168,6 +182,7 @@ export async function createLocalRuntime(
artifacts: options.artifactStore,
},
scheduling,
+ runtimeRevision,
runtimeClosure: options.closure.value,
});
const credentialControl = createLocalCredentialControl({
@@ -240,7 +255,7 @@ export async function createLocalRuntime(
const created = await options.dispatchStore.create(createBuildDispatchIdentity({
build: request.id,
core: request.state.id,
- runtimeClosure: options.closure.value.digest,
+ runtimeRevision,
}));
if (created.status === "created") {
await options.journal.append({
@@ -376,6 +391,8 @@ export async function createProjectLocalRuntime(
...(lockedPackageSet === undefined && options.implementationClosure === undefined
? {}
: { implementationClosure: lockedPackageSet?.lock.digest ?? options.implementationClosure }),
+ ...(options.runtimePackageClosure === undefined
+ ? {} : { runtimePackageClosure: options.runtimePackageClosure }),
});
return {
build: runtime.build,
diff --git a/packages/local/src/types.ts b/packages/local/src/types.ts
index 5c7b35e3..738023f8 100644
--- a/packages/local/src/types.ts
+++ b/packages/local/src/types.ts
@@ -56,6 +56,8 @@ export type CreateLocalRuntimeOptions = {
readonly validators?: LocalTypeValidatorRegistry;
/** Expected implementation package closure already bound into BuildRequest. */
readonly implementationClosure?: import("@narratage/protocol").Digest;
+ /** Verified physical Runtime-adapter package lock; absent only for trusted direct embedding. */
+ readonly runtimePackageClosure?: import("@narratage/protocol").Digest;
};
export type CreateLocalRuntimeControlOptions = {
@@ -85,6 +87,8 @@ export type ProjectLocalRuntimeOptions = {
readonly packageLock?: string;
/** Already verified implementation identity when components are supplied by this Host process. */
readonly implementationClosure?: import("@narratage/protocol").Digest;
+ /** Verified physical Runtime-adapter package lock; absent only for trusted direct embedding. */
+ readonly runtimePackageClosure?: import("@narratage/protocol").Digest;
/**
* Replaceable parts of the Runtime itself. One package may fill several roles;
* every selected role is explicit, and two packages exposing the same instance
diff --git a/packages/local/src/worker.ts b/packages/local/src/worker.ts
index 0fa7c71d..993c9139 100644
--- a/packages/local/src/worker.ts
+++ b/packages/local/src/worker.ts
@@ -301,10 +301,10 @@ class DurableLocalWorker implements RuntimeWorker {
assert(options.owner.trim().length > 0, "Worker owner is empty");
const leaseMs = positive(options.leaseMs, "Worker leaseMs");
const runtimeClosure = this.#options.runtimeClosure;
- assert(runtimeClosure !== undefined, "durable Worker requires one exact Runtime Revision");
+ assert(runtimeClosure !== undefined, "durable Worker requires one exact Runtime Closure");
const token = randomUUID();
const dispatch = await this.#options.stores.dispatch.claim({
- runtimeClosure: runtimeClosure.digest,
+ runtimeRevision: this.#options.runtimeRevision,
owner: options.owner,
token,
now: Date.now(),
@@ -318,8 +318,8 @@ class DurableLocalWorker implements RuntimeWorker {
const stored = await this.#options.stores.builds.read(dispatch.build);
assert(stored !== undefined, `Dispatch ${dispatch.build} has no BuildState`);
assert(stored.state.id === dispatch.core, `Dispatch ${dispatch.build} Core identity differs`);
- assert(runtimeClosure.digest === dispatch.runtimeClosure,
- `Dispatch ${dispatch.build} Runtime Closure differs`);
+ assert(this.#options.runtimeRevision === dispatch.runtimeRevision,
+ `Dispatch ${dispatch.build} Runtime Revision differs`);
const suppressedCommands = new Set<string>();
const controlled = new CapacityExecutor(
this.#executor,
diff --git a/packages/local/test/local.test.ts b/packages/local/test/local.test.ts
index 71a7e1ce..7cf44f2d 100644
--- a/packages/local/test/local.test.ts
+++ b/packages/local/test/local.test.ts
@@ -91,6 +91,48 @@ function projectRuntimeFixture(directory: string) {
} as const;
}
+test("one local execution domain refuses a new Runtime Revision while an old Build is unfinished", async () => {
+ const directory = await mkdtemp(join(tmpdir(), "svml-local-revision-gate-"));
+ try {
+ const firstImplementation = digestOf("implementation:first");
+ const firstRuntimePackages = digestOf("runtime-packages:first");
+ const first = await createProjectLocalRuntime({
+ root: directory,
+ ...projectRuntimeFixture(directory),
+ implementationClosure: firstImplementation,
+ runtimePackageClosure: firstRuntimePackages,
+ });
+ await first.build({
+ id: "unfinished-build",
+ state: createGreetingBuild({ implementationClosure: firstImplementation }),
+ });
+ await first.close();
+
+ const changed = projectRuntimeFixture(directory);
+ await assert.rejects(
+ createProjectLocalRuntime({
+ root: directory,
+ ...changed,
+ implementationClosure: digestOf("implementation:second"),
+ runtimePackageClosure: firstRuntimePackages,
+ }),
+ /cannot enter this execution domain[\s\S]*unfinished-build[\s\S]*original Runtime Profile/u,
+ );
+ const changedRuntimePackages = projectRuntimeFixture(directory);
+ await assert.rejects(
+ createProjectLocalRuntime({
+ root: directory,
+ ...changedRuntimePackages,
+ implementationClosure: firstImplementation,
+ runtimePackageClosure: digestOf("runtime-packages:second"),
+ }),
+ /cannot enter this execution domain[\s\S]*unfinished-build[\s\S]*original Runtime Profile/u,
+ );
+ } finally {
+ await rm(directory, { recursive: true, force: true });
+ }
+});
+
test("Artifact GC is explicit, dry-run by default, and only removes unreachable managed bytes", async () => {
const directory = await mkdtemp(join(tmpdir(), "svml-local-artifact-gc-"));
try {
diff --git a/packages/runtime/src/dispatch.ts b/packages/runtime/src/dispatch.ts
index fbd6ee56..15db990c 100644
--- a/packages/runtime/src/dispatch.ts
+++ b/packages/runtime/src/dispatch.ts
@@ -18,7 +18,8 @@ export type BuildDispatchIdentity = {
readonly id: Digest;
readonly build: string;
readonly core: Digest;
- readonly runtimeClosure: Digest;
+ /** Exact execution revision: Runtime Closure plus author/runtime implementation package locks. */
+ readonly runtimeRevision: Digest;
};
export type BuildDispatchSnapshot = BuildDispatchIdentity & {
@@ -44,7 +45,7 @@ export type BuildDispatchCreate =
export type BuildDispatchClaim = {
/** Exact Runtime Revision this Worker can execute. Claims are filtered before leasing. */
- readonly runtimeClosure: Digest;
+ readonly runtimeRevision: Digest;
readonly owner: string;
readonly token: string;
readonly now: number;
@@ -62,6 +63,14 @@ export type DispatchQuery = {
readonly admission?: DispatchAdmission;
};
+export const nonTerminalDispatchPhases = [
+ "queued",
+ "leased",
+ "waiting",
+ "blocked",
+ "settling",
+] as const satisfies readonly DispatchPhase[];
+
export type CapacityMode = "active" | "recoverable";
export type CapacityLimits = {
@@ -194,20 +203,38 @@ function positive(value: number, subject: string): number {
export function createBuildDispatchIdentity(input: {
readonly build: string;
readonly core: Digest;
- readonly runtimeClosure: Digest;
+ readonly runtimeRevision: Digest;
}): BuildDispatchIdentity {
assert(input.build.trim().length > 0, "Build Dispatch build id is empty");
assert(isDigest(input.core), "Build Dispatch Core digest is invalid");
- assert(isDigest(input.runtimeClosure), "Build Dispatch Runtime Closure digest is invalid");
+ assert(isDigest(input.runtimeRevision), "Build Dispatch Runtime Revision digest is invalid");
const content = {
format: "svml.build-dispatch-identity@1" as const,
build: input.build,
core: input.core,
- runtimeClosure: input.runtimeClosure,
+ runtimeRevision: input.runtimeRevision,
};
return { ...content, id: digestOf(content) };
}
+export function createRuntimeRevision(input: {
+ readonly runtimeClosure: Digest;
+ readonly implementationClosure?: Digest;
+ readonly runtimePackageClosure?: Digest;
+}): Digest {
+ assert(isDigest(input.runtimeClosure), "Runtime Revision Runtime Closure digest is invalid");
+ assert(input.implementationClosure === undefined || isDigest(input.implementationClosure),
+ "Runtime Revision implementation closure digest is invalid");
+ assert(input.runtimePackageClosure === undefined || isDigest(input.runtimePackageClosure),
+ "Runtime Revision Runtime package closure digest is invalid");
+ return digestOf({
+ format: "svml.runtime-revision@1",
+ runtimeClosure: input.runtimeClosure,
+ implementationClosure: input.implementationClosure ?? null,
+ runtimePackageClosure: input.runtimePackageClosure ?? null,
+ });
+}
+
export function verifyBuildDispatchIdentity(value: BuildDispatchIdentity): void {
const expected = createBuildDispatchIdentity(value);
assert(value.format === expected.format && value.id === expected.id, "Build Dispatch identity differs");
@@ -236,6 +263,28 @@ export function verifyBuildDispatchSnapshot(value: BuildDispatchSnapshot): void
if (value.cancellation !== undefined) safeNonNegative(value.cancellation.requestedAt, "cancellation requestedAt");
}
+/**
+ * One DispatchStore is one execution domain. It may admit only one Runtime Revision while work is
+ * unfinished. This keeps execution honest without retaining old code or inventing a multi-version
+ * Worker supervisor. A caller that intentionally wants another execution domain selects another
+ * DispatchStore.
+ */
+export function assertRuntimeRevisionAdmission(
+ runtimeRevision: Digest,
+ dispatches: readonly BuildDispatchSnapshot[],
+): void {
+ assert(isDigest(runtimeRevision), "Runtime Revision digest is invalid");
+ const conflicts = dispatches
+ .filter((item) => item.phase !== "terminal" && item.runtimeRevision !== runtimeRevision)
+ .sort((left, right) => left.build.localeCompare(right.build));
+ if (conflicts.length === 0) return;
+ throw new Error([
+ `Runtime Revision ${runtimeRevision} cannot enter this execution domain while unfinished Builds belong to another revision:`,
+ ...conflicts.map((item) => ` ${item.build} · ${item.phase} · ${item.runtimeRevision}`),
+ "Finish or cancel those Builds with their original Runtime Profile, restore that Profile and its package locks, or select another DispatchStore.",
+ ].join("\n"));
+}
+
export function capacityReservationId(build: string, command: string): Digest {
assert(build.trim().length > 0 && command.trim().length > 0, "Capacity reservation identity is empty");
return digestOf({ format: "svml.capacity-reservation-identity@1", build, command });
diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.ts
index 555dd886..a55ce155 100644
--- a/packages/runtime/src/index.ts
+++ b/packages/runtime/src/index.ts
@@ -14,8 +14,11 @@ export {
} from "./credentials.js";
export type * from "./credentials.js";
export {
+ assertRuntimeRevisionAdmission,
capacityReservationId,
createBuildDispatchIdentity,
+ createRuntimeRevision,
+ nonTerminalDispatchPhases,
verifyBuildDispatchIdentity,
verifyBuildDispatchSnapshot,
verifyCapacityLimits,
diff --git a/packages/runtime/src/types.ts b/packages/runtime/src/types.ts
index 597ec04f..ddd0fbe1 100644
--- a/packages/runtime/src/types.ts
+++ b/packages/runtime/src/types.ts
@@ -61,6 +61,7 @@ export type RuntimeWorkerFactoryOptions = {
readonly scheduler: BuildSchedulerFactory;
readonly stores: RuntimeExecutionStores;
readonly scheduling: BuildSchedulerOptions;
+ readonly runtimeRevision: Digest;
readonly runtimeClosure?: RuntimeClosure;
};
diff --git a/packages/store-sqlite/README.md b/packages/store-sqlite/README.md
index 5cc9e0f0..8e27345f 100644
--- a/packages/store-sqlite/README.md
+++ b/packages/store-sqlite/README.md
@@ -1,20 +1,22 @@
# `@narratage/store-sqlite`
-Durable local adapters for the environment-neutral `BuildStore` and `OperationStore` ports.
+Durable local adapters for the environment-neutral Build, Operation, Dispatch and Journal ports.
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;
+- BuildDispatchStore persists current Build admission, leases and generic capacity reservations;
+- RuntimeJournal persists operational observations for queue and cancellation inspection;
- 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 pre-release
-schema `1`; Core and Endpoint packages do not import SQLite. Incompatible development databases are
+schema `6`; Core and Endpoint packages do not import SQLite. Incompatible development databases are
rejected and recreated explicitly instead of carrying migration code before the first release.
-`createSqliteRuntimeServicePackage()` returns one physical package with two separately selectable
+`createSqliteRuntimeServicePackage()` returns one physical package with four separately selectable
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; changing the Host-only catalog table therefore cannot change the identity under which an
diff --git a/packages/store-sqlite/src/store.ts b/packages/store-sqlite/src/store.ts
index 01c77420..06ef122f 100644
--- a/packages/store-sqlite/src/store.ts
+++ b/packages/store-sqlite/src/store.ts
@@ -12,6 +12,7 @@ import type {
Digest,
} from "@narratage/protocol";
import {
+ assertRuntimeRevisionAdmission,
verifyBuildCatalogDescriptor,
verifyBuildCatalogEntry,
defineRuntimeServicePackage,
@@ -57,7 +58,7 @@ import type {
RuntimeServicePackage,
} from "@narratage/runtime";
-const databaseSchemaVersion = 5;
+const databaseSchemaVersion = 6;
export const sqliteStoreModuleRef = {
name: "@narratage/store-sqlite",
@@ -168,14 +169,16 @@ function parseOperationSnapshot(row: Row): OperationSnapshot {
readonly progress?: OperationSnapshot["progress"];
}
: undefined;
+ if (row.status === "pending") {
+ assert(pending?.format === "svml.operation-pending@1" && pending.checkpoint !== undefined,
+ "SQLite pending Operation has an unsupported checkpoint envelope");
+ }
const mutable = row.status === "pending"
- ? pending?.format === "svml.operation-pending@1" && pending.checkpoint !== undefined
- ? {
- checkpoint: pending.checkpoint,
- ...(pending.wakeAt === undefined ? {} : { wakeAt: pending.wakeAt }),
- ...(pending.progress === undefined ? {} : { progress: pending.progress }),
- }
- : { checkpoint: pending }
+ ? {
+ checkpoint: pending!.checkpoint,
+ ...(pending!.wakeAt === undefined ? {} : { wakeAt: pending!.wakeAt }),
+ ...(pending!.progress === undefined ? {} : { progress: pending!.progress }),
+ }
: row.status === "completed"
? { completion: JSON.parse(String(row.completion_json)) }
: row.status === "failed"
@@ -510,18 +513,45 @@ class SqliteBuildDispatchStore implements BuildDispatchStore {
const priority = options.priority ?? 0;
assert(Number.isSafeInteger(priority), "Dispatch priority must be a safe integer");
const availableAt = nonNegativeInteger(options.availableAt ?? now, "Dispatch availableAt");
- const result = this.#database.prepare(`
- INSERT OR IGNORE INTO svml_dispatches (
- build_id, identity_json, revision, created_at, updated_at, priority, available_at,
- admission, phase, lease_owner, lease_token, lease_fence, lease_expires_at,
- reason, cancel_requested_at, cancel_reason, terminal
- ) VALUES (?, ?, 0, ?, ?, ?, ?, 'open', 'queued', NULL, NULL, 0, NULL, NULL, NULL, NULL, NULL)
- `).run(identity.build, canonicalStringify(identity), now, now, priority, availableAt);
- const snapshot = await this.read(identity.build);
- if (snapshot === undefined) throw new Error(`Dispatch ${identity.build} disappeared after create`);
- assert(canonicalStringify({ format: snapshot.format, id: snapshot.id, build: snapshot.build, core: snapshot.core, runtimeClosure: snapshot.runtimeClosure })
- === canonicalStringify(identity), `Dispatch ${identity.build} already names another Build or Runtime Closure`);
- return { status: result.changes === 1 ? "created" : "existing", snapshot };
+ return transaction(this.#database, () => {
+ const existingRow = this.#database.prepare(
+ "SELECT * FROM svml_dispatches WHERE build_id = ?",
+ ).get(identity.build) as Row | undefined;
+ if (existingRow !== undefined) {
+ const existing = parseDispatchSnapshot(existingRow);
+ assert(canonicalStringify({
+ format: existing.format,
+ id: existing.id,
+ build: existing.build,
+ core: existing.core,
+ runtimeRevision: existing.runtimeRevision,
+ }) === canonicalStringify(identity),
+ `Dispatch ${identity.build} already names another Build or Runtime Closure`);
+ return { status: "existing", snapshot: existing };
+ }
+
+ const conflictingRows = this.#database.prepare(`
+ SELECT * FROM svml_dispatches
+ WHERE phase != 'terminal'
+ AND json_extract(identity_json, '$.runtimeRevision') != ?
+ ORDER BY created_at ASC, build_id ASC
+ `).all(identity.runtimeRevision) as Row[];
+ assertRuntimeRevisionAdmission(identity.runtimeRevision, conflictingRows.map(parseDispatchSnapshot));
+
+ const result = this.#database.prepare(`
+ INSERT INTO svml_dispatches (
+ build_id, identity_json, revision, created_at, updated_at, priority, available_at,
+ admission, phase, lease_owner, lease_token, lease_fence, lease_expires_at,
+ reason, cancel_requested_at, cancel_reason, terminal
+ ) VALUES (?, ?, 0, ?, ?, ?, ?, 'open', 'queued', NULL, NULL, 0, NULL, NULL, NULL, NULL, NULL)
+ `).run(identity.build, canonicalStringify(identity), now, now, priority, availableAt);
+ assert(result.changes === 1, `Dispatch ${identity.build} was not created`);
+ const createdRow = this.#database.prepare(
+ "SELECT * FROM svml_dispatches WHERE build_id = ?",
+ ).get(identity.build) as Row | undefined;
+ if (createdRow === undefined) throw new Error(`Dispatch ${identity.build} disappeared after create`);
+ return { status: "created", snapshot: parseDispatchSnapshot(createdRow) };
+ });
}
async read(build: string): Promise<BuildDispatchSnapshot | undefined> {
@@ -551,19 +581,19 @@ class SqliteBuildDispatchStore implements BuildDispatchStore {
async claim(request: BuildDispatchClaim): Promise<BuildDispatchSnapshot | undefined> {
assert(request.owner.trim().length > 0 && request.token.trim().length > 0, "Dispatch claim identity is empty");
- assert(/^sha256:[0-9a-f]{64}$/u.test(request.runtimeClosure), "Dispatch claim Runtime Closure is invalid");
+ assert(/^sha256:[0-9a-f]{64}$/u.test(request.runtimeRevision), "Dispatch claim Runtime Revision is invalid");
const now = nonNegativeInteger(request.now, "Dispatch claim time");
const leaseMs = positiveInteger(request.leaseMs, "Dispatch leaseMs");
return transaction(this.#database, () => {
const row = this.#database.prepare(`
SELECT * FROM svml_dispatches
WHERE phase != 'terminal'
- AND json_extract(identity_json, '$.runtimeClosure') = ?
+ AND json_extract(identity_json, '$.runtimeRevision') = ?
AND available_at <= ?
AND (lease_owner IS NULL OR lease_expires_at <= ?)
ORDER BY priority DESC, available_at ASC, created_at ASC, build_id ASC
LIMIT 1
- `).get(request.runtimeClosure, now, now) as Row | undefined;
+ `).get(request.runtimeRevision, now, now) as Row | undefined;
if (row === undefined) return undefined;
assert(typeof row.build_id === "string" && typeof row.revision === "number" && typeof row.lease_fence === "number",
"SQLite Dispatch claim row is invalid");
diff --git a/packages/store-sqlite/test/store.test.ts b/packages/store-sqlite/test/store.test.ts
index 83811710..602d9a57 100644
--- a/packages/store-sqlite/test/store.test.ts
+++ b/packages/store-sqlite/test/store.test.ts
@@ -167,7 +167,7 @@ test("Host Catalog schema changes do not change the execution Runtime Closure",
assert.deepEqual(
services.services.map((item) => item.instance.configurationDigest),
[
- ...Array(4).fill(digestOf({ path: join(directory, "runtime.sqlite"), schemaVersion: 5, busyTimeoutMs: 5_000 })),
+ ...Array(4).fill(digestOf({ path: join(directory, "runtime.sqlite"), schemaVersion: 6, busyTimeoutMs: 5_000 })),
],
);
await services.close?.();
@@ -182,18 +182,14 @@ test("SQLite fences expired Workers and shares capacity across Build dispatches"
const state = new SqliteRuntimeState(join(directory, "runtime.sqlite"));
const closure = digestOf("runtime:dispatch-test");
await state.dispatch.create(createBuildDispatchIdentity({
- build: "build-a", core: digestOf("core:a"), runtimeClosure: closure,
+ build: "build-a", core: digestOf("core:a"), runtimeRevision: closure,
}), { now: 100 });
- const foreignClosure = digestOf("runtime:another-revision");
- await state.dispatch.create(createBuildDispatchIdentity({
- build: "foreign-build", core: digestOf("core:foreign"), runtimeClosure: foreignClosure,
- }), { now: 99, priority: 1_000 });
- const first = await state.dispatch.claim({ runtimeClosure: closure, owner: "worker-a", token: "lease-a", now: 100, leaseMs: 10 });
+ const first = await state.dispatch.claim({ runtimeRevision: closure, owner: "worker-a", token: "lease-a", now: 100, leaseMs: 10 });
assert.ok(first?.lease);
- assert.equal(first.build, "build-a", "a Worker must not lease a higher-priority foreign Runtime Revision");
+ assert.equal(first.build, "build-a");
assert.equal(first.lease.fence, 1);
- assert.equal(await state.dispatch.claim({ runtimeClosure: closure, owner: "worker-b", token: "early", now: 105, leaseMs: 10 }), undefined);
- const second = await state.dispatch.claim({ runtimeClosure: closure, owner: "worker-b", token: "lease-b", now: 111, leaseMs: 10 });
+ assert.equal(await state.dispatch.claim({ runtimeRevision: closure, owner: "worker-b", token: "early", now: 105, leaseMs: 10 }), undefined);
+ const second = await state.dispatch.claim({ runtimeRevision: closure, owner: "worker-b", token: "lease-b", now: 111, leaseMs: 10 });
assert.ok(second?.lease);
assert.equal(second.lease.fence, 2);
const paidResources = [{ id: "authority:paid", maxActive: 1, maxInFlight: 1 }];
@@ -229,9 +225,9 @@ test("SQLite fences expired Workers and shares capacity across Build dispatches"
assert.equal(woken.phase, "waiting");
await state.dispatch.create(createBuildDispatchIdentity({
- build: "build-b", core: digestOf("core:b"), runtimeClosure: closure,
+ build: "build-b", core: digestOf("core:b"), runtimeRevision: closure,
}), { now: 112 });
- const third = await state.dispatch.claim({ runtimeClosure: closure, owner: "worker-c", token: "lease-c", now: 112, leaseMs: 10 });
+ const third = await state.dispatch.claim({ runtimeRevision: closure, owner: "worker-c", token: "lease-c", now: 112, leaseMs: 10 });
assert.ok(third?.lease);
const blocked = await state.dispatch.acquireCapacity({
build: "build-b", command: "command:b", resources: paidResources, mode: "recoverable",
@@ -241,9 +237,9 @@ test("SQLite fences expired Workers and shares capacity across Build dispatches"
assert.equal(blocked.status, "blocked");
await state.dispatch.create(createBuildDispatchIdentity({
- build: "build-c", core: digestOf("core:c"), runtimeClosure: closure,
+ build: "build-c", core: digestOf("core:c"), runtimeRevision: closure,
}), { now: 200, priority: 100 });
- const fourth = await state.dispatch.claim({ runtimeClosure: closure, owner: "worker-d", token: "lease-d", now: 200, leaseMs: 10 });
+ const fourth = await state.dispatch.claim({ runtimeRevision: closure, owner: "worker-d", token: "lease-d", now: 200, leaseMs: 10 });
assert.ok(fourth?.lease);
await state.dispatch.requestCancellation("build-c", "stop", 201);
const cancelledWake = await state.dispatch.release(
@@ -255,14 +251,48 @@ test("SQLite fences expired Workers and shares capacity across Build dispatches"
assert.equal(cancelledWake.admission, "closing");
assert.equal(cancelledWake.availableAt, 201,
"a cancellation racing with release cannot be delayed by the Worker's stale schedule");
- const foreign = await state.dispatch.claim({
- runtimeClosure: foreignClosure,
- owner: "foreign-worker",
- token: "foreign-lease",
- now: 203,
- leaseMs: 10,
+ state.close();
+ } finally {
+ await rm(directory, { recursive: true, force: true });
+ }
+});
+
+test("one SQLite execution domain rejects a second Runtime Revision until prior work is terminal", async () => {
+ const directory = await mkdtemp(join(tmpdir(), "svml-sqlite-revision-gate-"));
+ try {
+ const state = new SqliteRuntimeState(join(directory, "runtime.sqlite"));
+ const firstRevision = digestOf("runtime:first");
+ const secondRevision = digestOf("runtime:second");
+ const firstIdentity = createBuildDispatchIdentity({
+ build: "first-build",
+ core: digestOf("core:first"),
+ runtimeRevision: firstRevision,
+ });
+ assert.equal((await state.dispatch.create(firstIdentity, { now: 100 })).status, "created");
+ assert.equal((await state.dispatch.create(firstIdentity, { now: 101 })).status, "existing");
+ await assert.rejects(
+ state.dispatch.create(createBuildDispatchIdentity({
+ build: "second-build",
+ core: digestOf("core:second"),
+ runtimeRevision: secondRevision,
+ }), { now: 102 }),
+ /cannot enter this execution domain[\s\S]*first-build[\s\S]*original Runtime Profile/u,
+ );
+
+ const claimed = await state.dispatch.claim({
+ runtimeRevision: firstRevision,
+ owner: "worker:first",
+ token: "lease:first",
+ now: 103,
+ leaseMs: 1_000,
});
- assert.equal(foreign?.build, "foreign-build");
+ assert.ok(claimed?.lease);
+ await state.dispatch.finish("first-build", claimed.lease, "complete", undefined, 104);
+ assert.equal((await state.dispatch.create(createBuildDispatchIdentity({
+ build: "second-build",
+ core: digestOf("core:second"),
+ runtimeRevision: secondRevision,
+ }), { now: 105 })).status, "created");
state.close();
} finally {
await rm(directory, { recursive: true, force: true });
@@ -282,10 +312,10 @@ test("Authority and Route resources are acquired atomically across models", asyn
await state.dispatch.create(createBuildDispatchIdentity({
build,
core: digestOf(`core:${build}`),
- runtimeClosure: closure,
+ runtimeRevision: closure,
}), { now });
const claimed = await state.dispatch.claim({
- runtimeClosure: closure,
+ runtimeRevision: closure,
owner: `worker:${build}`,
token: `lease:${build}`,
now,
diff --git a/packages/video-cli/src/cli.ts b/packages/video-cli/src/cli.ts
index 4f77787b..cb254bb3 100644
--- a/packages/video-cli/src/cli.ts
+++ b/packages/video-cli/src/cli.ts
@@ -58,7 +58,8 @@ const io: CliIo = {
async function main(): Promise<void> {
if (argv.length === 0 || argv[0] === "help" || argv.includes("--help")) {
- writeCliHelp(io);
+ const topic = argv[0] === "help" ? argv[1] : argv.includes("--help") ? argv[0] : undefined;
+ writeCliHelp(io, topic);
return;
}
const { runVideoCli } = await import("./index.js");